Htmx/docs/Issues/Roadmap.md

API Improvement Roadmap

This roadmap is designed to improve DX without destabilizing the current template.

Phase 0: Track and Communicate (Now)

Goals:

• Make limitations explicit.
• Prevent repeated confusion.

Actions:

• Publish issues catalog and cost matrix.
• Link issues from the main component reference.
• Add "Known Limitations" + "Security" notes in component docs.

Success criteria:

• New contributors can find limitations before implementation.

Phase 1: Low-Risk Additive API Improvements

Goals:

• Improve ergonomics with minimal break risk.

Actions:

• Add optional className to all components.
• Add optional attributes bag to all components.
• Keep hxAttrs as legacy fallback.
• Introduce constants classes for common string domains.

Success criteria:

• Most wrapper-div style workarounds disappear.
• Most custom attribute hacks disappear.

Phase 2: Standardization and Strong Typing

Goals:

• Reduce error-prone string APIs.

Actions:

• Move high-value components to enums for semantic options.
• Introduce options records where constructors are overloaded.
• Replace tuple-based list inputs with named records.

Success criteria:

• IntelliSense can guide common component usage.
• Fewer runtime surprises from typos.

Phase 3: Security and Validation Hardening

Goals:

• Safer defaults and clearer intent.

Actions:

• Introduce safe-by-default text paths.
• Keep explicit trusted HTML APIs for advanced usage.
• Add analyzers (or debug validators) for invalid options and unsafe patterns.

Success criteria:

• XSS risk materially reduced.
• Unsafe usage becomes explicit and reviewable.

Phase 4: Deep API Evolution

Goals:

• Improve advanced composition and maintainability.

Actions:

• Formalize per-category component contracts.
• Improve table/form models for richer data and validation scenarios.
• Consider generator-level support for richer parameter/props models.

Success criteria:

• New component additions follow one predictable design style.
• Complex UIs require less custom glue code.

Migration Strategy

1. Add new APIs first.
2. Mark old parameters/patterns as deprecated.
3. Provide codemod or migration examples.
4. Remove deprecated surface only in major release.