Htmx/docs/Issues/Improvement-Options-and-Costs.md

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