@reliability-design/web 1.2.0 → 1.3.1

package/dist/components/rel-select/README.md

@@ -1,7 +1,7 @@
 # rel-select
 
 ## Overview
-A customizable dropdown select component with support for icons, multiple states, and sizes. Features built-in validation states, supporting text, and comprehensive styling options for form-based interfaces.
+A custom combobox-style select component built on the same textfield visual language (sizes, states, border styles). Renders a typeable text trigger with a custom-styled dropdown listbox (no native `<select>`/`<option>` rendering), so the dropdown is fully themeable in both light and dark mode. Supports icons, multiple states, and sizes, with built-in keyboard navigation, type-to-filter, and an inline "ghost text" autocomplete suggestion.
 
 ## Usage
 ```html
@@ -40,8 +40,9 @@ A customizable dropdown select component with support for icons, multiple states
 | `supportingText` | `string` | `""` | Helper or error text displayed below the select |
 | `size` | `"small" \| "medium" \| "large"` | `"medium"` | Size variant affecting padding and font size |
 | `border` | `"rounded" \| "sharp"` | `"rounded"` | Border radius style |
-| `leftIcon` | `string` | `""` | Icon or text displayed on the left side |
-| `rightIcon` | `string` | `""` | Icon or text displayed on the right side (before dropdown arrow) |
+| `leftIcon` | `string` | `""` | `rel-icon` name displayed on the left side |
+| `rightIcon` | `string` | `""` | `rel-icon` name to override the default right-side icon. When unset, a chevron is shown that rotates 180° on open; a custom `rightIcon` replaces the chevron entirely and does not rotate |
+| `placeholder` | `string` | `"Select option"` | Placeholder text shown when nothing is selected |
 
 ## Events
 | Event | Detail | Description |
@@ -63,45 +64,50 @@ None exposed.
 
 ### Spacing Tokens
 - `--rel-spacing-space-3xs`, `--rel-spacing-space-2xs`, `--rel-spacing-space-xs` - Internal padding
-- `--rel-spacing-space-sm`, `--rel-spacing-space-lg`, `--rel-spacing-space-xl`, `--rel-spacing-space-2xl`, `--rel-spacing-space-3xl` - Padding and icon positioning
+- `--rel-spacing-space-sm`, `--rel-spacing-space-md`, `--rel-spacing-space-xl`, `--rel-spacing-space-2xl` - Padding and icon positioning
 
 ### Color Tokens
-- `--rel-colors-gray-heading` - Label text color
-- `--rel-colors-gray-primary` - Icon and border hover color
-- `--rel-colors-gray-border` - Default border color
-- `--rel-colors-gray-placeholder` - Supporting text color
-- `--rel-colors-white` - Background color
-- `--rel-colors-primary-500` - Focus border and shadow color
-- `--rel-colors-red-secondary` - Error state border color
-- `--rel-background-error-light` - Error state focus shadow
-- `--rel-surface-surface` - Disabled background
-- `--rel-text-heading` - Select text color
-- `--rel-text-disabled` - Disabled text color
+- `--rel-color-text-heading` - Label and selected-value text color
+- `--rel-color-text-primary` - Icon color, focus border/shadow color
+- `--rel-color-text-placeholder` - Placeholder, supporting text, and ghost-suggestion text color
+- `--rel-color-text-disabled` - Disabled text/icon color
+- `--rel-color-border-default` - Default border color
+- `--rel-color-bg-primary` - Background color (trigger and dropdown panel)
+- `--rel-color-bg-tertiary` - Disabled background, hovered/highlighted option background
+- `--rel-error-surface-default` - Error state border, text, and icon color (light: `#D50000`, dark: `#FF5252`)
+- `--rel-shadows-shadow-200` - Dropdown panel shadow
 
 ### Border Tokens
-- `--rel-borders-radius-border-radius-300` - Rounded border radius
+- `--rel-borders-radius-border-radius-100` - Rounded border radius (default `border="rounded"`)
 
 ## Accessibility
-- Native `<select>` element provides built-in keyboard navigation
-- Focus visible states with clear visual indicators (border color and box shadow)
-- Label properly associated with select for screen readers
+- Trigger input uses `role="combobox"` with `aria-haspopup="listbox"`, `aria-expanded`, and `aria-controls`
+- Dropdown panel uses `role="listbox"`; each option uses `role="option"` with `aria-selected`
+- `aria-activedescendant` tracks the keyboard-highlighted option
+- Label properly associated with the trigger via `for`/`id`
 - Disabled state prevents interaction and reduces opacity
 - Error state communicated through color and supporting text
 
 ### Keyboard Interactions
-- `Space/Enter` - Open dropdown
-- `Arrow Up/Down` - Navigate options
-- `Escape` - Close dropdown
-- `Tab` - Move focus to next element
+- Typing - Filters the dropdown to matching options and shows an inline "ghost text" suggestion for the best prefix match
+- `→ (Arrow Right)` - When the cursor is at the end of the input, accepts the current ghost-text suggestion
+- `Enter` - Opens the dropdown (if closed); if open, selects the highlighted option, or commits the typed text if it exactly matches an option
+- `Arrow Up/Down` - Open dropdown (if closed) or move the highlighted option
+- `Home/End` - Jump to first/last filtered option (when open)
+- `Escape` - Revert input text to the committed value and close the dropdown
+- `Tab` - Accept any ghost suggestion, commit or revert the typed text, close the dropdown, and move focus to the next element
 
 ### Focus Behavior
-- Clear focus ring with primary color on keyboard focus
-- Focus state uses box-shadow for visibility
+- Clear focus ring with primary color via `box-shadow` on the container (`:focus-within`)
+- Trigger input is a normal editable text field with a visible caret
 
 ## Notes / Edge Cases
 - When `state="disabled"`, the select becomes non-interactive with reduced opacity and cursor indication
-- Empty `selected` value shows placeholder text "Select Option" which is hidden from the dropdown list
+- Empty `selected` value shows the `placeholder` text ("Select option" by default)
 - Icons (left/right) adjust internal padding automatically to accommodate icon space
-- The native dropdown arrow is always visible on the right side, custom rightIcon appears before it
-- In error state, supporting text is styled with error color for visual consistency
+- The chevron is always visible on the far right and rotates 180° when the dropdown is open; a custom `rightIcon` replaces it entirely (no chevron) and does not rotate
+- In error state, supporting text is styled with error color for visual consistency; the error state automatically clears once a valid option is selected
 - Options array is rendered as-is; complex objects not supported (use string values only)
+- Typed text that doesn't exactly match (case-insensitive) any option reverts to the last committed `selected` value on blur, Escape, or Tab
+- The ghost-text suggestion shows the remainder of the first option whose name starts with the typed text (case-insensitive); it has no effect on filtering, which matches substrings anywhere in an option
+- Dropdown panel is positioned via `position: fixed` and flips above the trigger if there isn't enough viewport space below