82 lines
2.2 KiB
Markdown
82 lines
2.2 KiB
Markdown
# 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.
|