Added issues that are going to be tracked and will be deeply considering changes based on DX.

Co-authored-by: Copilot <copilot@github.com>
2026-05-06 00:21:13 +05:00
parent f6ae86617c
commit 0787525134
8 changed files with 1218 additions and 0 deletions
@@ -0,0 +1,81 @@
+# 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.