# 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.