330 lines
7.2 KiB
Markdown
330 lines
7.2 KiB
Markdown
# 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.
|