@warp-ds/elements 2.10.0-next.8 → 2.10.0

package/dist/docs/checkbox-group/checkbox-group.md

@@ -2,7 +2,18 @@
 
 ## Description
 
-Use `w-checkbox-group` when several checkboxes share one label, help text, optional indicator, or required validation.
+Checkboxes allow users to select multiple options from a list of choices.
+
+Use with `w-checkbox`.
+
+## Architecture Note
+This component uses a <div> wrapper instead of the more semantic <fieldset> element.
+Note that w-radio-group uses <fieldset>, which provides better accessibility and follows
+HTML best practices. This inconsistency exists for historical reasons and may be addressed
+in a future major version to align both on the more semantic approach.
+
+TODO: Align w-checkbox-group to use <fieldset> in a future major version after assessing
+backwards compatibility implications (CSS selectors, etc.).
 
 ## Usage
 
@@ -280,10 +291,18 @@ Avoid option labels that only make sense visually, such as "Yes" or "This one",
 
 ## Styling API
 
-This section documents the supported styling hooks for `<w-checkbox>`.
+This section documents the supported styling hooks for `<w-checkbox>` and `<w-checkbox-group>`.
 
 Use these hooks to customize appearance without relying on internal structure or selectors.
 
+Before changing the default styles, remember that doing so can result in less consistent experiences for users across the product. Prefer defaults.
+
+- Prefer **component tokens** for size, spacing, and state styling.
+- Use **parts** only for small, local tweaks.
+- Avoid relying on internal class names or selectors.
+
+## w-checkbox
+
 ### Parts
 
 The checkbox exposes a small set of parts that can be targeted for last‑mile layout or typography tweaks.
@@ -307,12 +326,12 @@ w-checkbox::part(control) {
 }
 ```
 
-Parts are intended as an **escape hatch**.  
+Parts are intended as an **escape hatch**.
 Prefer component tokens for anything state‑ or size‑related.
 
-### Component tokens (`--w-c-checkbox-*`)
+### Component tokens
 
-Component tokens act as inputs to the checkbox styling.  
+Component tokens (`--w-c-checkbox-*`) act as inputs to the checkbox styling.
 They can be set directly on the component or inherited from a parent container.
 
 ```css
@@ -377,39 +396,33 @@ Defaults are defined internally; setting a token is always optional.
 
 Transitions are automatically disabled when `prefers-reduced-motion: reduce` is active.
 
-### Examples
 
-#### Compact checkbox
+## w-checkbox-group
 
-```css
-.filters w-checkbox {
-  --w-c-checkbox-gap: 4px;
-  --w-c-checkbox-control-size: 1.6rem;
-}
-```
+The checkbox-group component uses direct CSS styling rather than component tokens. Customization is limited to ensure consistent form control patterns across the design system.
 
-#### Rounded checkbox
+### Styling
 
-```css
-w-checkbox {
-  --w-c-checkbox-radius: 9999px;
-}
-```
+The checkbox-group provides minimal styling hooks:
 
-#### Contextual color override (advanced)
+| Element | Current styling | Note |
+|---|---|---|
+| Label | `font-size: var(--w-font-size-s)`<br>`line-height: var(--w-line-height-s)`<br>`font-weight: 700`<br>`color: var(--w-s-color-text)` | Uses semantic tokens |
+| Optional indicator | `font-weight: 400`<br>`color: var(--w-s-color-text-subtle)` | Matches form control pattern |
+| Help text | `font-size: var(--w-font-size-xs)`<br>`line-height: var(--w-line-height-xs)`<br>`color: var(--w-s-color-text-subtle)` | Error state: `--w-s-color-text-negative` |
+| Checkbox spacing | `gap: 16px` | Spacing between checkboxes |
+| Wrapper spacing | `gap: 16px` | Spacing between label and group |
 
-```css
-.danger-zone w-checkbox {
-  --w-c-checkbox-border-color-checked: red;
-}
-```
 
-### Guidelines
+## Implementation notes
+
+### Architecture note
+
+This component uses a `<div>` wrapper instead of the more semantic `<fieldset>` element. Note that `w-radio-group` uses `<fieldset>`, which provides better accessibility and follows HTML best practices. This inconsistency exists for historical reasons and may be addressed in a future major version to align both on the more semantic approach.
+
+**Why this matters:** `<fieldset>` with `<legend>` provides automatic grouping semantics and better screen reader support. The current `<div>` + `role="group"` implementation works but requires manual ARIA wiring.
 
-- Prefer **component tokens** for size, spacing, and state styling
-- Use **parts** only for small, local tweaks
-- Avoid relying on internal class names or selectors
-- If multiple tokens are required to achieve a look, consider whether a new variant or design token is more appropriate
+**TODO:** Consider aligning w-checkbox-group to use `<fieldset>` in a future major version after assessing backwards compatibility implications (CSS selectors, etc.).
 
 ## `<w-checkbox-group>` API
 
@@ -419,23 +432,40 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 | Name | Type | Default | Summary |
 |-|-|-|-|
-| help-text | `string` | `-` | Help text displayed below the checkbox group. |
+| checkValidity (JS only) | `checkValidity() => boolean` | `-` | Checks whether the group passes constraint validation |
+| focus (JS only) | `focus(options?: FocusOptions) => void` | `-` | Sets focus on the checkbox group. |
+| help-text | `string \| undefined` | `-` | Help text displayed below the checkbox group. |
 | invalid | `boolean` | `false` | Whether the checkbox group is visually invalid. |
-| label | `string` | `-` | The group label displayed above the checkboxes. |
-| name | `string` | `-` | The name applied to child checkboxes when they do not provide one. |
+| label | `string \| undefined` | `-` | The group label displayed above the checkboxes. |
+| name | `string \| undefined` | `-` | The name applied to child checkboxes when they do not provide one. |
 | optional | `boolean` | `false` | Whether to show optional text next to the label. |
+| reportValidity (JS only) | `reportValidity() => boolean` | `-` | Checks validity and shows the validation message if invalid |
 | required | `boolean` | `false` | Whether at least one checkbox in the group must be selected. |
 | shadowRootOptions (JS only) | `object` | `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }` | - |
 
 ### Property Details
 
+#### checkValidity (JS only)
+
+Checks whether the group passes constraint validation
+
+- Type: `checkValidity() => boolean`
+- Default: `-`
+
+#### focus (JS only)
+
+Sets focus on the checkbox group.
+
+- Type: `focus(options?: FocusOptions) => void`
+- Default: `-`
+
 #### help-text
 
 Help text displayed below the checkbox group.
 
 Use this for supporting guidance or validation feedback. When required validation fails, the group replaces this text with the localized required message.
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`
 
 #### invalid
@@ -453,7 +483,7 @@ The group label displayed above the checkboxes.
 
 Use this to describe the shared question or topic for the checkbox options. The label is connected to the internal group for assistive technologies.
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`
 
 #### name
@@ -462,7 +492,7 @@ The name applied to child checkboxes when they do not provide one.
 
 Use this when the grouped checkboxes should submit values under the same form field name. Individual checkboxes can still override the group name with their own `name`.
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`
 
 #### optional
@@ -474,6 +504,13 @@ Use this to indicate that selecting an option from the group is not required.
 - Type: `boolean`
 - Default: `false`
 
+#### reportValidity (JS only)
+
+Checks validity and shows the validation message if invalid
+
+- Type: `reportValidity() => boolean`
+- Default: `-`
+
 #### required
 
 Whether at least one checkbox in the group must be selected.

package/dist/docs/checkbox-group/styling.md

@@ -1,9 +1,17 @@
 ## Styling API
 
-This section documents the supported styling hooks for `<w-checkbox>`.
+This section documents the supported styling hooks for `<w-checkbox>` and `<w-checkbox-group>`.
 
 Use these hooks to customize appearance without relying on internal structure or selectors.
 
+Before changing the default styles, remember that doing so can result in less consistent experiences for users across the product. Prefer defaults.
+
+- Prefer **component tokens** for size, spacing, and state styling.
+- Use **parts** only for small, local tweaks.
+- Avoid relying on internal class names or selectors.
+
+## w-checkbox
+
 ### Parts
 
 The checkbox exposes a small set of parts that can be targeted for last‑mile layout or typography tweaks.
@@ -27,12 +35,12 @@ w-checkbox::part(control) {
 }
 ```
 
-Parts are intended as an **escape hatch**.  
+Parts are intended as an **escape hatch**.
 Prefer component tokens for anything state‑ or size‑related.
 
-### Component tokens (`--w-c-checkbox-*`)
+### Component tokens
 
-Component tokens act as inputs to the checkbox styling.  
+Component tokens (`--w-c-checkbox-*`) act as inputs to the checkbox styling.
 They can be set directly on the component or inherited from a parent container.
 
 ```css
@@ -97,36 +105,30 @@ Defaults are defined internally; setting a token is always optional.
 
 Transitions are automatically disabled when `prefers-reduced-motion: reduce` is active.
 
-### Examples
 
-#### Compact checkbox
+## w-checkbox-group
 
-```css
-.filters w-checkbox {
-  --w-c-checkbox-gap: 4px;
-  --w-c-checkbox-control-size: 1.6rem;
-}
-```
+The checkbox-group component uses direct CSS styling rather than component tokens. Customization is limited to ensure consistent form control patterns across the design system.
 
-#### Rounded checkbox
+### Styling
 
-```css
-w-checkbox {
-  --w-c-checkbox-radius: 9999px;
-}
-```
+The checkbox-group provides minimal styling hooks:
 
-#### Contextual color override (advanced)
+| Element | Current styling | Note |
+|---|---|---|
+| Label | `font-size: var(--w-font-size-s)`<br>`line-height: var(--w-line-height-s)`<br>`font-weight: 700`<br>`color: var(--w-s-color-text)` | Uses semantic tokens |
+| Optional indicator | `font-weight: 400`<br>`color: var(--w-s-color-text-subtle)` | Matches form control pattern |
+| Help text | `font-size: var(--w-font-size-xs)`<br>`line-height: var(--w-line-height-xs)`<br>`color: var(--w-s-color-text-subtle)` | Error state: `--w-s-color-text-negative` |
+| Checkbox spacing | `gap: 16px` | Spacing between checkboxes |
+| Wrapper spacing | `gap: 16px` | Spacing between label and group |
 
-```css
-.danger-zone w-checkbox {
-  --w-c-checkbox-border-color-checked: red;
-}
-```
 
-### Guidelines
+## Implementation notes
+
+### Architecture note
+
+This component uses a `<div>` wrapper instead of the more semantic `<fieldset>` element. Note that `w-radio-group` uses `<fieldset>`, which provides better accessibility and follows HTML best practices. This inconsistency exists for historical reasons and may be addressed in a future major version to align both on the more semantic approach.
+
+**Why this matters:** `<fieldset>` with `<legend>` provides automatic grouping semantics and better screen reader support. The current `<div>` + `role="group"` implementation works but requires manual ARIA wiring.
 
-- Prefer **component tokens** for size, spacing, and state styling
-- Use **parts** only for small, local tweaks
-- Avoid relying on internal class names or selectors
-- If multiple tokens are required to achieve a look, consider whether a new variant or design token is more appropriate
+**TODO:** Consider aligning w-checkbox-group to use `<fieldset>` in a future major version after assessing backwards compatibility implications (CSS selectors, etc.).

package/dist/docs/combobox/api.md

@@ -6,21 +6,22 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 | Name | Type | Default | Summary |
 |-|-|-|-|
-| autocomplete | `string \| undefined` | `'off'` | The autocomplete attribute passed to the internal input. |
+| 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. |
+| 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. |
+| 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. |
+| 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. |
+| placeholder | `string \| undefined` | `""` | Placeholder text displayed when the input is empty. |
 | required | `boolean` | `false` | Whether the combobox is required before form submission. |
+| resetFormControl (JS only) | `resetFormControl() => void` | `-` | - |
 | select-on-blur | `boolean` | `true` | Whether the active option is selected when the input loses focus. |
-| value | `string` | `''` | The selected or typed value. |
+| value | `string` | `""` | The selected or typed value. |
 
 ### Property Details
 
@@ -31,7 +32,7 @@ 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'`
+- Default: `"off"`
 
 #### disable-static-filtering
 
@@ -58,7 +59,7 @@ Help text displayed below the input.
 Use this for supporting guidance or validation feedback.
 
 - Type: `string | undefined`
-- Default: `''`
+- Default: `""`
 
 #### invalid
 
@@ -76,7 +77,7 @@ The label displayed above the input.
 Use this to give the combobox a visible and accessible name.
 
 - Type: `string | undefined`
-- Default: `''`
+- Default: `""`
 
 #### match-text-segments
 
@@ -94,7 +95,7 @@ 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: `''`
+- Default: `""`
 
 #### open-on-focus
 
@@ -130,7 +131,7 @@ 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: `''`
+- Default: `""`
 
 #### required
 
@@ -141,6 +142,13 @@ Use this when the user must provide a value before submitting the form.
 - Type: `boolean`
 - Default: `false`
 
+#### resetFormControl (JS only)
+
+
+
+- Type: `resetFormControl() => void`
+- Default: `-`
+
 #### select-on-blur
 
 Whether the active option is selected when the input loses focus.
@@ -157,5 +165,5 @@ 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: `''`
+- Default: `""`
 

package/dist/docs/combobox/combobox.md

@@ -163,21 +163,22 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 | Name | Type | Default | Summary |
 |-|-|-|-|
-| autocomplete | `string \| undefined` | `'off'` | The autocomplete attribute passed to the internal input. |
+| 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. |
+| 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. |
+| 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. |
+| 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. |
+| placeholder | `string \| undefined` | `""` | Placeholder text displayed when the input is empty. |
 | required | `boolean` | `false` | Whether the combobox is required before form submission. |
+| resetFormControl (JS only) | `resetFormControl() => void` | `-` | - |
 | select-on-blur | `boolean` | `true` | Whether the active option is selected when the input loses focus. |
-| value | `string` | `''` | The selected or typed value. |
+| value | `string` | `""` | The selected or typed value. |
 
 ### Property Details
 
@@ -188,7 +189,7 @@ 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'`
+- Default: `"off"`
 
 #### disable-static-filtering
 
@@ -215,7 +216,7 @@ Help text displayed below the input.
 Use this for supporting guidance or validation feedback.
 
 - Type: `string | undefined`
-- Default: `''`
+- Default: `""`
 
 #### invalid
 
@@ -233,7 +234,7 @@ The label displayed above the input.
 Use this to give the combobox a visible and accessible name.
 
 - Type: `string | undefined`
-- Default: `''`
+- Default: `""`
 
 #### match-text-segments
 
@@ -251,7 +252,7 @@ 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: `''`
+- Default: `""`
 
 #### open-on-focus
 
@@ -287,7 +288,7 @@ 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: `''`
+- Default: `""`
 
 #### required
 
@@ -298,6 +299,13 @@ Use this when the user must provide a value before submitting the form.
 - Type: `boolean`
 - Default: `false`
 
+#### resetFormControl (JS only)
+
+
+
+- Type: `resetFormControl() => void`
+- Default: `-`
+
 #### select-on-blur
 
 Whether the active option is selected when the input loses focus.
@@ -314,5 +322,5 @@ 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: `''`
+- Default: `""`
 

package/dist/docs/datepicker/api.md

@@ -7,24 +7,25 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 | Name | Type | Default | Summary |
 |-|-|-|-|
 | calendar (JS only) | `HTMLDivElement` | `-` | - |
-| 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. |
+| 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` | `-` | Function used to disable dates in the calendar. |
-| label | `string` | `-` | The label displayed above the date input. |
+| isDayDisabled (JS only) | `((day: Date) => boolean) \| undefined` | `-` | Function used to disable dates in the calendar. |
+| label | `string \| undefined` | `-` | The label displayed above the date input. |
 | lang | `string` | `-` | The locale used for calendar labels and date formatting. |
 | month (JS only) | `unknown` | `-` | - |
-| name | `string` | `-` | The name submitted with the date value. |
+| name | `string \| undefined` | `-` | 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. |
+| resetFormControl (JS only) | `resetFormControl() => void` | `-` | - |
 | selectedCell (JS only) | `HTMLTableCellElement` | `-` | - |
 | selectedDate (JS only) | `Date \| null` | `-` | - |
 | shadowRootOptions (JS only) | `object` | `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }` | - |
 | todayCell (JS only) | `HTMLTableCellElement` | `-` | - |
 | toggleButton (JS only) | `HTMLButtonElement` | `-` | - |
-| value | `string` | `-` | The selected date value. |
-| weekday-format | `string` | `'EEEEEE'` | The weekday format shown above the calendar grid. |
+| value | `string \| undefined` | `-` | The selected date value. |
+| weekday-format | `string` | `"EEEEEE"` | The weekday format shown above the calendar grid. |
 | weeks (JS only) | `unknown` | `-` | - |
 | wrapper (JS only) | `HTMLDivElement` | `-` | - |
 
@@ -44,7 +45,7 @@ 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).
 
 - Type: `string`
-- Default: `'PPPP'`
+- Default: `"PPPP"`
 
 #### header-format
 
@@ -53,7 +54,7 @@ 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).
 
 - Type: `string`
-- Default: `'MMMM yyyy'`
+- Default: `"MMMM yyyy"`
 
 #### input (JS only)
 
@@ -75,7 +76,7 @@ Function used to disable dates in the calendar.
 
 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`
+- Type: `((day: Date) => boolean) | undefined`
 - Default: `-`
 
 #### label
@@ -84,7 +85,7 @@ The label displayed above the date input.
 
 Use this to give the datepicker a visible and accessible name.
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`
 
 #### lang
@@ -109,7 +110,7 @@ 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`
+- Type: `string | undefined`
 - Default: `-`
 
 #### navigationDate (JS only)
@@ -130,6 +131,13 @@ the query will point to an element that doesn't exist anymore.
 - Type: `HTMLButtonElement`
 - Default: `-`
 
+#### resetFormControl (JS only)
+
+
+
+- Type: `resetFormControl() => void`
+- Default: `-`
+
 #### selectedCell (JS only)
 
 
@@ -171,7 +179,7 @@ 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`
+- Type: `string | undefined`
 - Default: `-`
 
 #### weekday-format
@@ -181,7 +189,7 @@ 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).
 
 - Type: `string`
-- Default: `'EEEEEE'`
+- Default: `"EEEEEE"`
 
 #### weeks (JS only)