3.7 KiB
3.7 KiB
Improvement Options and Costs
This matrix helps prioritize API improvements by DX value, risk, and migration cost.
Legend:
- Effort: S (small), M (medium), L (large), XL (very large)
- Break Risk: Low, Medium, High
- Runtime Impact: Positive, Neutral, Slight Negative
| Proposal | Solves | Effort | Break Risk | Runtime Impact | Notes |
|---|---|---|---|---|---|
Add standardized className to all components |
wrapper-div workaround, styling consistency | M | Low | Neutral | Additive change if optional |
Add standardized attributes bag (attributes) |
missing aria-*, data-*, test IDs |
L | Medium | Slight Negative | Best long-term extensibility |
Keep hxAttrs as compatibility fallback |
migration safety | S | Low | Neutral | Mark as legacy in docs |
| Enums for variant/size/type | magic strings | M | Medium | Neutral | Better compile-time safety |
| Constants classes for allowed string values | magic strings (partial) | S | Low | Neutral | Good transitional step |
| Replace tuple APIs with named records | readability, future extensibility | M | Medium | Neutral | TabItem, AccordionItem, etc. |
| Add options-record constructors for complex components | constructor bloat | M | Low | Neutral | Improves call-site clarity |
| Safe-by-default text encoding APIs | XSS risk | M | High | Neutral | Breaking if current raw HTML behavior is relied on |
| Explicit trusted HTML wrapper API | intentional raw HTML path | M | Medium | Neutral | Clear security intent |
| Add standardized Security section in every component doc | security docs inconsistency | M | Low | Neutral | High ROI docs work |
| Add standardized Accessibility section in every component doc | a11y gaps | M | Low | Neutral | High ROI docs work |
| Add JS contract metadata/docs for interactive components | hidden JS dependencies | S | Low | Neutral | Immediate debugging benefit |
| Add development-time JS diagnostics in components.js | silent interactive failures | M | Low | Slight Negative | Dev-only checks recommended |
| Add analyzer: invalid variant literals | magic string typos | L | Low | Neutral | Tooling investment pays off |
| Add analyzer: unsafe unencoded user input usage | XSS prevention | L | Medium | Neutral | Requires careful heuristics |
| Add API evolution policy and deprecation plan | change management | S | Low | Neutral | Needed before major refactors |
| Introduce per-category baseline contracts | inconsistency across components | L | Medium | Neutral | Strategic but broad |
| Introduce table column/cell model | table API limitations | L | Medium | Neutral | High payoff for real apps |
| Add form control baseline contract | form component inconsistency | L | Medium | Neutral | Improves predictability |
| Introduce lazy compute in heavy components | precompute allocation concerns | M | Low | Positive | Benchmark before and after |
Recommended Sequencing
- Documentation-first, no-break improvements:
- known limitations docs
- security/a11y/js contract sections
- issue tracker links and migration guidance
- Additive API upgrades:
classNameattributes- options records
- constants for allowed values
- Strong typing and validation:
- enums
- analyzers
- debug validations
- Breaking/security-hardening updates:
- safe-by-default content model
- deprecate raw string HTML entry points
Consequence Summary
Positive consequences:
- More predictable and discoverable API
- Lower bug rate from string typos and attr mistakes
- Better security baseline
- Less wrapper-div boilerplate
Negative/neutral consequences:
- Larger API surface
- Migration overhead in existing usages
- Potentially more allocations for flexible attribute models
- Need for contributor discipline to maintain consistency