# 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