# Component-by-Component Concerns

This matrix captures likely API/DX complaints per component area, including potential improvement directions.

## Display Components

### Alert

Concerns:
- Variant as magic string.
- Content/title may be used as raw HTML without explicit safety boundary.
- Custom classes/attributes may be inconsistent.

Potential improvements:
- Enum for variant.
- Safe text API + explicit trusted HTML path.
- Standard `className` and `attributes`.

### Avatar

Concerns:
- Fallback/shape/size options can become string-heavy.
- Accessibility attributes may be awkward without attr bag.

Potential improvements:
- Typed size/shape options.
- Uniform attributes model.

### Badge

Concerns:
- Variant string typing and typo risk.
- Inconsistent extension points compared with Button/Input.

Potential improvements:
- Variant enum/constants.
- Standardized extensibility surface.

### Breadcrumb

Concerns:
- Item model may be primitive/string-only.
- Accessibility hooks and custom attrs may be limited.

Potential improvements:
- Named item record model.
- Attr bag and aria convenience options.

### Card

Concerns:
- Raw HTML sections can be misused.
- Optional sections create many constructor parameters.

Potential improvements:
- Options record.
- Safe content model.

### Progress

Concerns:
- Value bounds validation may be implicit or absent.
- Class extension inconsistencies.

Potential improvements:
- Explicit min/max validation.
- Standard class and attr extension.

### Separator

Concerns:
- Orientation/type as magic string.
- Thin API extensibility for accessibility semantics.

Potential improvements:
- Enum for orientation.
- Attr bag support.

### Skeleton

Concerns:
- Shape/sizing patterns vary by caller wrappers.
- Lacks compositional guidance for complex placeholders.

Potential improvements:
- Preset variants + className override.
- Pattern docs for loading states.

### Table

Concerns:
- Primitive row/cell string model limits rich content.
- Possible heavy constructor precomputation for large data.
- Safety boundary unclear when rendering rich cell content.

Potential improvements:
- Typed column/cell models.
- Lazy render/cache strategy for large tables.
- Explicit text-vs-html cell APIs.

### Tooltip

Concerns:
- Trigger/content composition can rely on string/slot conventions.
- Accessibility and focus behavior may need clearer guidance.

Potential improvements:
- Better keyboard and aria documentation.
- Attr/class pass-through consistency.

## Form Components

### Button

Concerns:
- Variant/size/type magic strings.
- `hxAttrs` raw string ergonomics/security risk.
- Need for wrapper to add layout classes in some contexts.

Potential improvements:
- Enums/constants.
- Structured attributes.
- Standard `className`.

### Checkbox

Concerns:
- Label/id/checked model may not match other form controls.
- Limited pass-through attributes.

Potential improvements:
- Shared form-control options contract.
- Attr bag and validation state support.

### FileInput

Concerns:
- Accepted file types and attrs may be cumbersome.
- Inconsistent API vs Input/Textarea.

Potential improvements:
- Shared form-control options.
- Better file-specific typed options.

### Input

Concerns:
- Input type as string.
- Validation/aria hooks likely manual.

Potential improvements:
- Input type enum/constants.
- Baseline form options and attr bag.

### RadioGroup

Concerns:
- Tuple options reduce readability.
- Direction/layout often string-based.
- Attr pass-through likely limited.

Potential improvements:
- Named option record.
- Typed direction values.
- Standard form/attr contract.

### Select

Concerns:
- Option model and selected/default semantics may be inconsistent.
- Styling/attrs may differ from Input/Textarea.

Potential improvements:
- Named option record.
- Unified form control API.

### Slider

Concerns:
- Value/min/max/step validation and formatting ergonomics.
- Limited attr/class extensibility in some usages.

Potential improvements:
- Stronger numeric validation and docs.
- Standard extension points.

### Switch

Concerns:
- Checked/value semantics may differ from checkbox.
- JS and accessibility contracts may not be obvious.

Potential improvements:
- Form contract alignment.
- Explicit a11y + JS requirements docs.

### Textarea

Concerns:
- Similar concerns to Input: attrs, validation, and consistency.

Potential improvements:
- Shared baseline form options.

## Interactive Components

### Accordion

Concerns:
- Tuple-based item model.
- JS selector coupling via markup classes/data attributes.
- Rich content safety boundary if strings are HTML.

Potential improvements:
- Named `AccordionItem` model.
- Stable data-role contracts.
- Explicit safe/trusted content APIs.

### Calendar

Concerns:
- JS dependency and date contract coupling.
- Limited custom attributes for instrumentation/a11y.

Potential improvements:
- Explicit JS contract docs in API comments.
- Standard attrs support.

### CalendarRange

Concerns:
- Similar to Calendar plus complexity around range state.
- Validation/error state API may be weak.

Potential improvements:
- Strong state model and docs.
- Better attr/validation contract.

### Dialog

Concerns:
- Open/close semantics rely on data attributes and JS wiring.
- Content sections may use raw HTML strings.

Potential improvements:
- Named trigger/actions patterns in docs.
- Safe content APIs and structured attrs.

### DropdownMenu

Concerns:
- Item model can be tuple-heavy.
- Keyboard and accessibility behavior depends on JS contract.

Potential improvements:
- Named item/action records.
- Explicit interaction/accessibility contract docs.

### Tabs

Concerns:
- Tuple-based tab definitions.
- ID/active state handling as plain strings.
- JS contract may be implicit.

Potential improvements:
- `TabItem` record + typed active key model.
- Explicit JS and accessibility notes.

### TimePicker

Concerns:
- Value format/string handling may be error-prone.
- JS coupling and validation ergonomics.

Potential improvements:
- Typed time value helpers.
- Clear formatting and validation rules.

## Notification Components

### Toast

Concerns:
- Trigger lifecycle and JS coupling may not be obvious.
- Variant/style options likely string-based.

Potential improvements:
- Typed options and JS contract docs.
- Standard attrs/class extension points.

### ToastViewport

Concerns:
- Placement/config likely string-heavy.
- Global singleton usage constraints may be under-documented.

Potential improvements:
- Typed placement/options.
- Clear singleton/layout guidance.

## Navigation Components

### Pagination

Concerns:
- Data model may be primitive and hard to customize.
- Accessibility state semantics need consistency.

Potential improvements:
- Named model for page items and actions.
- Strong accessibility defaults and hooks.

## Cross-Component Cost Notes

Low-cost improvements:
- Better docs for limitations/security/js contracts.
- Add design guidelines and migration policy.
- Constants for common string literals.

Medium-cost improvements:
- Standard `className` and `attributes` options.
- Options records for complex constructors.
- Named item models replacing tuples.

High-cost improvements:
- Safe-by-default content model transition.
- Full enum migration for all semantic options.
- Analyzer suite for API misuse detection.