@warp-ds/elements 2.9.2-next.1 → 2.10.0-next.10

package/dist/docs/combobox/combobox.md

@@ -4,14 +4,157 @@
 
 A combobox element for text input with selectable options.
 
-[See Storybook for usage examples](https://warp-ds.github.io/elements/?path=/docs/forms-combobox--docs)
-
 ## 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.
+
+## Styling API
+
 ## `<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/styling.md

@@ -0,0 +1 @@
+## Styling API

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/datepicker/accessibility.md

@@ -1 +1,26 @@
 ## Accessibility
+
+Datepicker renders a labeled date input with a button that opens a calendar dialog. The calendar uses a grid of dates and moves focus into the calendar when it opens.
+
+### Provide A Label
+
+Always provide a visible label.
+
+```html
+<w-datepicker label="Departure date" name="departure"></w-datepicker>
+```
+
+The label should describe the date being requested. Avoid generic labels such as "Date" when there are several date fields on the same page.
+
+### Calendar Dialog
+
+The calendar popup is rendered as a dialog with `aria-modal="true"`. The month heading is announced with `aria-live="polite"` when users move between months.
+
+Each date in the calendar grid has an accessible name formatted using `day-format`.
+
+```html
+<w-datepicker label="Date" name="date" day-format="PPPP"></w-datepicker>
+```
+
+Use a descriptive `day-format` so screen reader users hear the full date, not only the day number.
+See [the Date FNS docs](https://date-fns.org/v4.1.0/docs/format) for formatting options.

package/dist/docs/datepicker/api.md

@@ -7,15 +7,15 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 | Name | Type | Default | Summary |
 |-|-|-|-|
 | calendar (JS only) | `HTMLDivElement` | `-` | - |
-| day-format | `string` | `'PPPP'` | Decides the format of the day in the calendar as read to screen readers. |
-| header-format | `string` | `'MMMM yyyy'` | Decides the format of the date as shown in the calendar header. |
+| day-format | `string` | `'PPPP'` | The date format used for calendar day accessible names. |
+| header-format | `string` | `'MMMM yyyy'` | The date format used in the calendar header. |
 | input (JS only) | `HTMLInputElement` | `-` | - |
 | isCalendarOpen (JS only) | `boolean` | `false` | - |
-| isDayDisabled (JS only) | `(day: Date) => boolean` | `-` | Lets you control if a date in the calendar should be disabled. |
-| label | `string` | `-` | - |
-| lang | `string` | `-` | Takes precedence over the `<html>` lang attribute. |
+| isDayDisabled (JS only) | `(day: Date) => boolean` | `-` | Function used to disable dates in the calendar. |
+| label | `string` | `-` | The label displayed above the date input. |
+| lang | `string` | `-` | The locale used for calendar labels and date formatting. |
 | month (JS only) | `unknown` | `-` | - |
-| name | `string` | `-` | - |
+| name | `string` | `-` | The name submitted with the date value. |
 | navigationDate (JS only) | `Date` | `-` | - |
 | previousMonthButton (JS only) | `HTMLButtonElement` | `-` | This is the first focusable element, needed for the modal focus trap. |
 | selectedCell (JS only) | `HTMLTableCellElement` | `-` | - |
@@ -23,8 +23,8 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 | shadowRootOptions (JS only) | `object` | `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }` | - |
 | todayCell (JS only) | `HTMLTableCellElement` | `-` | - |
 | toggleButton (JS only) | `HTMLButtonElement` | `-` | - |
-| value | `string` | `-` | - |
-| weekday-format | `string` | `'EEEEEE'` | Decides the format of the weekday as shown above the grid of dates in the calendar. |
+| value | `string` | `-` | The selected date value. |
+| weekday-format | `string` | `'EEEEEE'` | The weekday format shown above the calendar grid. |
 | weeks (JS only) | `unknown` | `-` | - |
 | wrapper (JS only) | `HTMLDivElement` | `-` | - |
 
@@ -39,7 +39,7 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 #### day-format
 
-Decides the format of the day in the calendar as read to screen readers.
+The date format used for calendar day accessible names.
 
 The syntax is defined by [date-fns/format](https://date-fns.org/v4.1.0/docs/format).
 
@@ -48,7 +48,7 @@ The syntax is defined by [date-fns/format](https://date-fns.org/v4.1.0/docs/form
 
 #### header-format
 
-Decides the format of the date as shown in the calendar header.
+The date format used in the calendar header.
 
 The syntax is defined by [date-fns/format](https://date-fns.org/v4.1.0/docs/format).
 
@@ -71,23 +71,27 @@ The syntax is defined by [date-fns/format](https://date-fns.org/v4.1.0/docs/form
 
 #### isDayDisabled (JS only)
 
-Lets you control if a date in the calendar should be disabled.
+Function used to disable dates in the calendar.
 
-This needs to be set on the element instance in JavaScript, not as an HTML attribute.
+Set this on the element instance in JavaScript, not as an HTML attribute. Disabled dates cannot be selected from the calendar.
 
 - Type: `(day: Date) => boolean`
 - Default: `-`
 
 #### label
 
+The label displayed above the date input.
 
+Use this to give the datepicker a visible and accessible name.
 
 - Type: `string`
 - Default: `-`
 
 #### lang
 
-Takes precedence over the `<html>` lang attribute.
+The locale used for calendar labels and date formatting.
+
+This takes precedence over the `<html>` `lang` attribute. Supported built-in locales are `en`, `nb`, `sv`, `da`, and `fi`.
 
 - Type: `string`
 - Default: `-`
@@ -101,7 +105,9 @@ Takes precedence over the `<html>` lang attribute.
 
 #### name
 
+The name submitted with the date value.
 
+Use this when the datepicker belongs to a form and its value should be included in form data.
 
 - Type: `string`
 - Default: `-`
@@ -161,14 +167,16 @@ the query will point to an element that doesn't exist anymore.
 
 #### value
 
+The selected date value.
 
+Use an ISO date string in `YYYY-MM-DD` format. The value is submitted with the form and is reset to its initial value when the form resets.
 
 - Type: `string`
 - Default: `-`
 
 #### weekday-format
 
-Decides the format of the weekday as shown above the grid of dates in the calendar.
+The weekday format shown above the calendar grid.
 
 The syntax is defined by [date-fns/format](https://date-fns.org/v4.1.0/docs/format).