69 lines
3.7 KiB
Markdown
69 lines
3.7 KiB
Markdown
# 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
|
|
|
|
1. Documentation-first, no-break improvements:
|
|
- known limitations docs
|
|
- security/a11y/js contract sections
|
|
- issue tracker links and migration guidance
|
|
|
|
2. Additive API upgrades:
|
|
- `className`
|
|
- `attributes`
|
|
- options records
|
|
- constants for allowed values
|
|
|
|
3. Strong typing and validation:
|
|
- enums
|
|
- analyzers
|
|
- debug validations
|
|
|
|
4. 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
|