@warp-ds/elements 2.10.0-next.2 → 2.10.0-next.3

package/dist/docs/combobox/accessibility.md

@@ -1 +1,72 @@
 ## Accessibility
+
+Combobox renders an input with `role="combobox"` and a popup list with `role="listbox"`. Each suggestion is rendered with `role="option"`, and the active suggestion is connected to the input with `aria-activedescendant`.
+
+### Provide A Label
+
+Always provide a visible label.
+
+```html
+<w-combobox label="Country" placeholder="Search">
+  <option value="no">Norway</option>
+  <option value="se">Sweden</option>
+  <option value="dk">Denmark</option>
+</w-combobox>
+```
+
+Do not rely on placeholder text as the only label. Placeholder text disappears as soon as the user types and is not a reliable accessible name.
+
+### Help Text And Errors
+
+Use `help-text` for extra guidance or validation feedback.
+
+```html
+<w-combobox label="Country" help-text="Start typing to filter countries">
+  <option value="no">Norway</option>
+  <option value="se">Sweden</option>
+  <option value="dk">Denmark</option>
+</w-combobox>
+```
+
+When the combobox is invalid, pair `invalid` with help text that explains how to correct the error.
+
+```html
+<w-combobox label="Country" invalid help-text="Select a country from the list">
+  <option value="no">Norway</option>
+  <option value="se">Sweden</option>
+  <option value="dk">Denmark</option>
+</w-combobox>
+```
+
+Do not rely on invalid styling alone.
+
+### Keyboard Interaction
+
+The input follows common combobox keyboard behavior:
+
+- Arrow Down and Arrow Up open the list and move between suggestions.
+- Home and End move to the first and last suggestion.
+- Page Up and Page Down move through suggestions in larger steps.
+- Enter selects the active suggestion.
+- Escape closes the list. When the list is already closed, Escape clears the value.
+- Tab closes the list and moves focus onward.
+
+### Suggestions
+
+The component announces the number of available suggestions through a screen-reader-only status message while the list is open.
+
+Keep option labels short and unique enough to distinguish. If the submitted `value` differs from what users should read, provide a clear option label.
+
+```html
+<w-combobox label="Country" placeholder="Search">
+  <option value="us" label="United States">US</option>
+  <option value="uk" label="United Kingdom">UK</option>
+  <option value="no">Norway</option>
+</w-combobox>
+```
+
+### Disabled Comboboxes
+
+Avoid disabled comboboxes where possible. Disabled controls can be hard to discover and do not explain why the field is unavailable.
+
+Prefer leaving the combobox enabled and showing validation or explanatory feedback when the user tries to continue.

package/dist/docs/combobox/api.md

@@ -6,125 +6,155 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 | Name | Type | Default | Summary |
 |-|-|-|-|
-| autocomplete | `string \| undefined` | `'off'` | Autocomplete attribute for the input field |
-| disable-static-filtering | `boolean` | `false` | Disable client-side static filtering |
-| disabled | `boolean` | `false` | Whether the element is disabled |
-| help-text | `string \| undefined` | `''` | The content to display as the help text |
-| invalid | `boolean` | `false` | Renders the input field in an invalid state |
-| label | `string \| undefined` | `''` | Label above input |
-| match-text-segments | `boolean` | `false` | Whether the matching text segments in the options should be highlighted |
-| name | `string \| undefined` | `''` | Name attribute for form submission |
-| open-on-focus | `boolean` | `false` | Whether the popover opens when focus is on the text field |
-| optional | `boolean` | `false` | Whether to show optional text |
-| options | `ComboboxOption[]` | `[]` | The available options to select from |
-| placeholder | `string \| undefined` | `''` | Input placeholder |
-| required | `boolean` | `false` | Whether the element is required |
-| select-on-blur | `boolean` | `true` | Select active option on blur |
-| value | `string` | `''` | The input value |
+| autocomplete | `string \| undefined` | `'off'` | The autocomplete attribute passed to the internal input. |
+| disable-static-filtering | `boolean` | `false` | Whether built-in client-side filtering is disabled. |
+| disabled | `boolean` | `false` | Whether the combobox is disabled. |
+| help-text | `string \| undefined` | `''` | Help text displayed below the input. |
+| invalid | `boolean` | `false` | Whether the combobox is visually invalid. |
+| label | `string \| undefined` | `''` | The label displayed above the input. |
+| match-text-segments | `boolean` | `false` | Whether matching text segments in options are highlighted. |
+| name | `string \| undefined` | `''` | The name submitted with the combobox value. |
+| open-on-focus | `boolean` | `false` | Whether the option list opens when the input receives focus. |
+| optional | `boolean` | `false` | Whether to show optional text next to the label. |
+| options | `ComboboxOption[]` | `[]` | The available options to select from. |
+| placeholder | `string \| undefined` | `''` | Placeholder text displayed when the input is empty. |
+| required | `boolean` | `false` | Whether the combobox is required before form submission. |
+| select-on-blur | `boolean` | `true` | Whether the active option is selected when the input loses focus. |
+| value | `string` | `''` | The selected or typed value. |
 
 ### Property Details
 
 #### autocomplete
 
-Autocomplete attribute for the input field
+The autocomplete attribute passed to the internal input.
+
+Defaults to `off`. Set this when browser autocomplete should be enabled or scoped to a specific autocomplete token.
 
 - Type: `string | undefined`
 - Default: `'off'`
 
 #### disable-static-filtering
 
-Disable client-side static filtering
+Whether built-in client-side filtering is disabled.
+
+Use this for remote search or externally filtered results. When disabled, all entries in `options` are rendered as provided.
 
 - Type: `boolean`
 - Default: `false`
 
 #### disabled
 
-Whether the element is disabled
+Whether the combobox is disabled.
+
+Disabled comboboxes cannot be focused, changed, or submitted with form data.
 
 - Type: `boolean`
 - Default: `false`
 
 #### help-text
 
-The content to display as the help text
+Help text displayed below the input.
+
+Use this for supporting guidance or validation feedback.
 
 - Type: `string | undefined`
 - Default: `''`
 
 #### invalid
 
-Renders the input field in an invalid state
+Whether the combobox is visually invalid.
+
+Use this to show an externally managed validation error. Pair it with `help-text` to explain how to fix the error.
 
 - Type: `boolean`
 - Default: `false`
 
 #### label
 
-Label above input
+The label displayed above the input.
+
+Use this to give the combobox a visible and accessible name.
 
 - Type: `string | undefined`
 - Default: `''`
 
 #### match-text-segments
 
-Whether the matching text segments in the options should be highlighted
+Whether matching text segments in options are highlighted.
+
+Use this to visually emphasize the part of each option that matches the current input value.
 
 - Type: `boolean`
 - Default: `false`
 
 #### name
 
-Name attribute for form submission
+The name submitted with the combobox value.
+
+Use this when the combobox belongs to a form and its value should be included in form data.
 
 - Type: `string | undefined`
 - Default: `''`
 
 #### open-on-focus
 
-Whether the popover opens when focus is on the text field
+Whether the option list opens when the input receives focus.
+
+Use this when users should see available options before they start typing.
 
 - Type: `boolean`
 - Default: `false`
 
 #### optional
 
-Whether to show optional text
+Whether to show optional text next to the label.
+
+Use this to indicate that the combobox is not required.
 
 - Type: `boolean`
 - Default: `false`
 
 #### options
 
-The available options to select from
+The available options to select from.
+
+Use this for framework usage, application state, or remote search results. When `options` contains entries, it is used instead of child `<option>` elements.
 
 - Type: `ComboboxOption[]`
 - Default: `[]`
 
 #### placeholder
 
-Input placeholder
+Placeholder text displayed when the input is empty.
+
+Use this as a short hint for the expected input. Do not use placeholder text as a replacement for a label.
 
 - Type: `string | undefined`
 - Default: `''`
 
 #### required
 
-Whether the element is required
+Whether the combobox is required before form submission.
+
+Use this when the user must provide a value before submitting the form.
 
 - Type: `boolean`
 - Default: `false`
 
 #### select-on-blur
 
-Select active option on blur
+Whether the active option is selected when the input loses focus.
+
+When enabled, the combobox selects the keyboard-highlighted option, or an option whose value exactly matches the current input value, on blur.
 
 - Type: `boolean`
 - Default: `true`
 
 #### value
 
-The input value
+The selected or typed value.
+
+When an option is selected, this is set to the option value. The displayed text may differ when the option has a separate label.
 
 - Type: `string`
 - Default: `''`

package/dist/docs/combobox/combobox.md

@@ -8,10 +8,153 @@ A combobox element for text input with selectable options.
 
 ## Usage
 
+Use child `<option>` elements for declarative HTML usage.
+
+<elements-example>
+
+```html
+<w-combobox label="Country" placeholder="Search">
+    <option value="no">Norway</option>
+    <option value="se">Sweden</option>
+    <option value="dk">Denmark</option>
+</w-combobox>
+```
+
+</elements-example>
+
+The option text is used as the visible suggestion. The `value` attribute is used as the submitted and selected value.
+
+For framework usage or dynamic data, you may set the `options` property instead.
+
+```js
+combobox.options = [
+  { value: 'no', label: 'Norway' },
+  { value: 'se', label: 'Sweden' },
+  { value: 'dk', label: 'Denmark' },
+];
+```
+
+When `options` contains entries, it is used instead of child `<option>` elements.
+
 ## Accessibility
 
+Combobox renders an input with `role="combobox"` and a popup list with `role="listbox"`. Each suggestion is rendered with `role="option"`, and the active suggestion is connected to the input with `aria-activedescendant`.
+
+### Provide A Label
+
+Always provide a visible label.
+
+```html
+<w-combobox label="Country" placeholder="Search">
+  <option value="no">Norway</option>
+  <option value="se">Sweden</option>
+  <option value="dk">Denmark</option>
+</w-combobox>
+```
+
+Do not rely on placeholder text as the only label. Placeholder text disappears as soon as the user types and is not a reliable accessible name.
+
+### Help Text And Errors
+
+Use `help-text` for extra guidance or validation feedback.
+
+```html
+<w-combobox label="Country" help-text="Start typing to filter countries">
+  <option value="no">Norway</option>
+  <option value="se">Sweden</option>
+  <option value="dk">Denmark</option>
+</w-combobox>
+```
+
+When the combobox is invalid, pair `invalid` with help text that explains how to correct the error.
+
+```html
+<w-combobox label="Country" invalid help-text="Select a country from the list">
+  <option value="no">Norway</option>
+  <option value="se">Sweden</option>
+  <option value="dk">Denmark</option>
+</w-combobox>
+```
+
+Do not rely on invalid styling alone.
+
+### Keyboard Interaction
+
+The input follows common combobox keyboard behavior:
+
+- Arrow Down and Arrow Up open the list and move between suggestions.
+- Home and End move to the first and last suggestion.
+- Page Up and Page Down move through suggestions in larger steps.
+- Enter selects the active suggestion.
+- Escape closes the list. When the list is already closed, Escape clears the value.
+- Tab closes the list and moves focus onward.
+
+### Suggestions
+
+The component announces the number of available suggestions through a screen-reader-only status message while the list is open.
+
+Keep option labels short and unique enough to distinguish. If the submitted `value` differs from what users should read, provide a clear option label.
+
+```html
+<w-combobox label="Country" placeholder="Search">
+  <option value="us" label="United States">US</option>
+  <option value="uk" label="United Kingdom">UK</option>
+  <option value="no">Norway</option>
+</w-combobox>
+```
+
+### Disabled Comboboxes
+
+Avoid disabled comboboxes where possible. Disabled controls can be hard to discover and do not explain why the field is unavailable.
+
+Prefer leaving the combobox enabled and showing validation or explanatory feedback when the user tries to continue.
+
 ## Examples
 
+<elements-example>
+
+```html
+<w-combobox label="Fruit" placeholder="Type to search">
+    <option value="apple">Apple</option>
+    <option value="banana">Banana</option>
+    <option value="orange">Orange</option>
+</w-combobox>
+```
+
+</elements-example>
+
+### Different label and value
+
+Use the `label` attribute when the visible suggestion should differ from the selected value.
+
+<elements-example>
+
+```html
+<w-combobox label="Country" placeholder="Search">
+    <option value="us" label="United States">US</option>
+    <option value="uk" label="United Kingdom">UK</option>
+    <option value="no">Norway</option>
+</w-combobox>
+```
+
+</elements-example>
+
+### Dynamic options
+
+Use the `options` property when options come from application state or a remote search.
+
+```js
+const combobox = document.querySelector('w-combobox');
+
+combobox.options = [
+  { value: 'apple', label: 'Apple' },
+  { value: 'banana', label: 'Banana' },
+  { value: 'orange', label: 'Orange' },
+];
+```
+
+Child option content is plain text. Rich option content is not supported.
+
 ## `<w-combobox>` API
 
 Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).
@@ -20,125 +163,155 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 | Name | Type | Default | Summary |
 |-|-|-|-|
-| autocomplete | `string \| undefined` | `'off'` | Autocomplete attribute for the input field |
-| disable-static-filtering | `boolean` | `false` | Disable client-side static filtering |
-| disabled | `boolean` | `false` | Whether the element is disabled |
-| help-text | `string \| undefined` | `''` | The content to display as the help text |
-| invalid | `boolean` | `false` | Renders the input field in an invalid state |
-| label | `string \| undefined` | `''` | Label above input |
-| match-text-segments | `boolean` | `false` | Whether the matching text segments in the options should be highlighted |
-| name | `string \| undefined` | `''` | Name attribute for form submission |
-| open-on-focus | `boolean` | `false` | Whether the popover opens when focus is on the text field |
-| optional | `boolean` | `false` | Whether to show optional text |
-| options | `ComboboxOption[]` | `[]` | The available options to select from |
-| placeholder | `string \| undefined` | `''` | Input placeholder |
-| required | `boolean` | `false` | Whether the element is required |
-| select-on-blur | `boolean` | `true` | Select active option on blur |
-| value | `string` | `''` | The input value |
+| autocomplete | `string \| undefined` | `'off'` | The autocomplete attribute passed to the internal input. |
+| disable-static-filtering | `boolean` | `false` | Whether built-in client-side filtering is disabled. |
+| disabled | `boolean` | `false` | Whether the combobox is disabled. |
+| help-text | `string \| undefined` | `''` | Help text displayed below the input. |
+| invalid | `boolean` | `false` | Whether the combobox is visually invalid. |
+| label | `string \| undefined` | `''` | The label displayed above the input. |
+| match-text-segments | `boolean` | `false` | Whether matching text segments in options are highlighted. |
+| name | `string \| undefined` | `''` | The name submitted with the combobox value. |
+| open-on-focus | `boolean` | `false` | Whether the option list opens when the input receives focus. |
+| optional | `boolean` | `false` | Whether to show optional text next to the label. |
+| options | `ComboboxOption[]` | `[]` | The available options to select from. |
+| placeholder | `string \| undefined` | `''` | Placeholder text displayed when the input is empty. |
+| required | `boolean` | `false` | Whether the combobox is required before form submission. |
+| select-on-blur | `boolean` | `true` | Whether the active option is selected when the input loses focus. |
+| value | `string` | `''` | The selected or typed value. |
 
 ### Property Details
 
 #### autocomplete
 
-Autocomplete attribute for the input field
+The autocomplete attribute passed to the internal input.
+
+Defaults to `off`. Set this when browser autocomplete should be enabled or scoped to a specific autocomplete token.
 
 - Type: `string | undefined`
 - Default: `'off'`
 
 #### disable-static-filtering
 
-Disable client-side static filtering
+Whether built-in client-side filtering is disabled.
+
+Use this for remote search or externally filtered results. When disabled, all entries in `options` are rendered as provided.
 
 - Type: `boolean`
 - Default: `false`
 
 #### disabled
 
-Whether the element is disabled
+Whether the combobox is disabled.
+
+Disabled comboboxes cannot be focused, changed, or submitted with form data.
 
 - Type: `boolean`
 - Default: `false`
 
 #### help-text
 
-The content to display as the help text
+Help text displayed below the input.
+
+Use this for supporting guidance or validation feedback.
 
 - Type: `string | undefined`
 - Default: `''`
 
 #### invalid
 
-Renders the input field in an invalid state
+Whether the combobox is visually invalid.
+
+Use this to show an externally managed validation error. Pair it with `help-text` to explain how to fix the error.
 
 - Type: `boolean`
 - Default: `false`
 
 #### label
 
-Label above input
+The label displayed above the input.
+
+Use this to give the combobox a visible and accessible name.
 
 - Type: `string | undefined`
 - Default: `''`
 
 #### match-text-segments
 
-Whether the matching text segments in the options should be highlighted
+Whether matching text segments in options are highlighted.
+
+Use this to visually emphasize the part of each option that matches the current input value.
 
 - Type: `boolean`
 - Default: `false`
 
 #### name
 
-Name attribute for form submission
+The name submitted with the combobox value.
+
+Use this when the combobox belongs to a form and its value should be included in form data.
 
 - Type: `string | undefined`
 - Default: `''`
 
 #### open-on-focus
 
-Whether the popover opens when focus is on the text field
+Whether the option list opens when the input receives focus.
+
+Use this when users should see available options before they start typing.
 
 - Type: `boolean`
 - Default: `false`
 
 #### optional
 
-Whether to show optional text
+Whether to show optional text next to the label.
+
+Use this to indicate that the combobox is not required.
 
 - Type: `boolean`
 - Default: `false`
 
 #### options
 
-The available options to select from
+The available options to select from.
+
+Use this for framework usage, application state, or remote search results. When `options` contains entries, it is used instead of child `<option>` elements.
 
 - Type: `ComboboxOption[]`
 - Default: `[]`
 
 #### placeholder
 
-Input placeholder
+Placeholder text displayed when the input is empty.
+
+Use this as a short hint for the expected input. Do not use placeholder text as a replacement for a label.
 
 - Type: `string | undefined`
 - Default: `''`
 
 #### required
 
-Whether the element is required
+Whether the combobox is required before form submission.
+
+Use this when the user must provide a value before submitting the form.
 
 - Type: `boolean`
 - Default: `false`
 
 #### select-on-blur
 
-Select active option on blur
+Whether the active option is selected when the input loses focus.
+
+When enabled, the combobox selects the keyboard-highlighted option, or an option whose value exactly matches the current input value, on blur.
 
 - Type: `boolean`
 - Default: `true`
 
 #### value
 
-The input value
+The selected or typed value.
+
+When an option is selected, this is set to the option value. The displayed text may differ when the option has a separate label.
 
 - Type: `string`
 - Default: `''`

package/dist/docs/combobox/examples.md

@@ -1 +1,45 @@
 ## Examples
+
+<elements-example>
+
+```html
+<w-combobox label="Fruit" placeholder="Type to search">
+    <option value="apple">Apple</option>
+    <option value="banana">Banana</option>
+    <option value="orange">Orange</option>
+</w-combobox>
+```
+
+</elements-example>
+
+### Different label and value
+
+Use the `label` attribute when the visible suggestion should differ from the selected value.
+
+<elements-example>
+
+```html
+<w-combobox label="Country" placeholder="Search">
+    <option value="us" label="United States">US</option>
+    <option value="uk" label="United Kingdom">UK</option>
+    <option value="no">Norway</option>
+</w-combobox>
+```
+
+</elements-example>
+
+### Dynamic options
+
+Use the `options` property when options come from application state or a remote search.
+
+```js
+const combobox = document.querySelector('w-combobox');
+
+combobox.options = [
+  { value: 'apple', label: 'Apple' },
+  { value: 'banana', label: 'Banana' },
+  { value: 'orange', label: 'Orange' },
+];
+```
+
+Child option content is plain text. Rich option content is not supported.

package/dist/docs/combobox/usage.md

@@ -1 +1,29 @@
 ## Usage
+
+Use child `<option>` elements for declarative HTML usage.
+
+<elements-example>
+
+```html
+<w-combobox label="Country" placeholder="Search">
+    <option value="no">Norway</option>
+    <option value="se">Sweden</option>
+    <option value="dk">Denmark</option>
+</w-combobox>
+```
+
+</elements-example>
+
+The option text is used as the visible suggestion. The `value` attribute is used as the submitted and selected value.
+
+For framework usage or dynamic data, you may set the `options` property instead.
+
+```js
+combobox.options = [
+  { value: 'no', label: 'Norway' },
+  { value: 'se', label: 'Sweden' },
+  { value: 'dk', label: 'Denmark' },
+];
+```
+
+When `options` contains entries, it is used instead of child `<option>` elements.

package/dist/docs/icon/accessibility.md

@@ -0,0 +1,5 @@
+## Accessibility
+
+Icons ship with a localized descriptive `<title>`.
+
+Note that the description is about the icon itself, not its semantic meaning in every given context. If you for example make an icon button, make sure to include an `aria-label` on your button that describes its action.