feat: add responsive breakpoints, state syntax, and annotations support. issues: #49 #50 #51 # 52

[taranais]

Pull Request

Description

This PR delivers the planned syntax enhancements for wiremd, including:

• Responsive breakpoints and viewport blocks
• Component state syntax (inline + block)
• Annotation/comment syntax with optional visual rendering
• Data placeholder syntax with deterministic seed support

It includes parser/AST updates, renderer integration (HTML/JSON/React/Tailwind), CLI flags, tests, documentation, and new examples with generated outputs.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Performance improvement
• Test updates
• Build/tooling changes

Related Issues

• Support responsive breakpoint syntax Support responsive breakpoint syntax #49
• Add state syntax (hover, active, disabled) Add state syntax (hover, active, disabled) #50
• Add annotation/comment syntax Add annotation/comment syntax #51
• Support data placeholder syntax Support data placeholder syntax #52

Changes Made

• Added responsive syntax support (.md:grid-*, .sm:grid-*) and viewport blocks (::: mobile, ::: desktop).
• Added state syntax support ({:hover}, {:active}, {:focus}, {:disabled}, {:loading}, {:error}, {:success}, {:warning}) plus ::: state=... blocks.
• Added annotation/comment support:
  • HTML comments captured in AST/JSON
  • annotation attributes (.annotation, todo, version-note)
  • ::: note blocks
  • --show-annotations rendering mode
• Added data placeholders:
  • {{user.name}}, {{user.email}}, {{lorem:N}}, {{image:WxH}}, {{date}}, {{number:min-max}}
  • deterministic generation via --seed / placeholderSeed
  • opt-out via --no-placeholders / resolvePlaceholders: false
  • strict-mode validation for invalid placeholder syntax
• Updated docs/spec/changelog and added new placeholder demo + generated outputs.

Testing

Test Coverage

• Added new tests for new functionality
• Updated existing tests
• All tests pass locally (npm test)
• No decrease in code coverage

Manual Testing

1. Rendered demos for responsive/state/annotations and verified output behavior.
2. Rendered placeholder demo with fixed seed and verified reproducible output.
3. Rendered with --no-placeholders and verified placeholders remain literal.

Examples

Input

## Features {.grid-3 .md:grid-2 .sm:grid-1}

[Submit]{:disabled}

[Submit] <!-- Primary CTA -->

Name: {{user.name}}
Email: {{user.email}}
Reference: {{number:1000-9999}}
Image: {{image:400x300}}

::: state=hover
[Retry]
:::

Output

<!-- Responsive classes, state classes/attributes, and resolved placeholder values are rendered -->
<!-- Annotation callouts are hidden by default and shown only with --show-annotations -->

Checklist

• My code follows the project's coding standards
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings or errors
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published

Breaking Changes

• None.

Migration Guide

No migration required.
Changes are additive and backward compatible.

Screenshots/Recordings

N/A (new rendered example outputs are included in examples/).

Performance Impact

• No performance impact
• Performance improved
• Performance may be affected (explain below)

Documentation

• README.md updated
• CHANGELOG.md updated
• API documentation updated (JSDoc)
• Example files added/updated
• Syntax specification updated (if syntax changes)

Additional Notes

• Full validation run completed successfully:
  • npm run typecheck
  • npm run test
  • npm run build
• Placeholder strict validation is implemented in parser validation (strict: true).

Reviewer Checklist

• Code quality and style
• Tests are adequate
• Documentation is complete
• No security concerns
• Performance is acceptable
• Breaking changes are justified and documented