Htmx/docs/Issues/Component-by-Component-Concerns.md

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.