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

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

@@ -0,0 +1,132 @@
+## Styling API
+
+This section documents the supported styling hooks for `<w-checkbox>`.
+
+Use these hooks to customize appearance without relying on internal structure or selectors.
+
+### Parts
+
+The checkbox exposes a small set of parts that can be targeted for last‑mile layout or typography tweaks.
+
+| Part | Targets | Typical use |
+|---|---|---|
+| `base` | wrapper element | layout adjustments (spacing, alignment) |
+| `control` | checkbox control (box) | minor alignment or sizing tweaks |
+| `input` | native `<input type="checkbox">` | focus / outline adjustments |
+| `label` | label content | typography tweaks |
+
+Example:
+
+```css
+w-checkbox::part(label) {
+  font-weight: 600;
+}
+
+w-checkbox::part(control) {
+  margin-top: 1px;
+}
+```
+
+Parts are intended as an **escape hatch**.  
+Prefer component tokens for anything state‑ or size‑related.
+
+### Component tokens (`--w-c-checkbox-*`)
+
+Component tokens act as inputs to the checkbox styling.  
+They can be set directly on the component or inherited from a parent container.
+
+```css
+.settings-panel {
+  --w-c-checkbox-gap: 12px;
+}
+```
+
+Defaults are defined internally; setting a token is always optional.
+
+
+#### Layout & size
+
+| Token | Purpose | Default |
+|---|---|---|
+| `--w-c-checkbox-gap` | space between control and label | `8px` |
+| `--w-c-checkbox-control-size` | width/height of the control | `2rem` |
+| `--w-c-checkbox-radius` | border radius of the control | `4px` |
+| `--w-c-checkbox-border-width` | border width | `1px` |
+
+
+#### Colors
+
+| Token | Purpose | Default |
+|---|---|---|
+| `--w-c-checkbox-bg` | control background | theme default |
+| `--w-c-checkbox-border-color` | control border color | theme default |
+| `--w-c-checkbox-bg-checked` | background when checked | theme default |
+| `--w-c-checkbox-border-color-checked` | border when checked | theme default |
+| `--w-c-checkbox-icon-color` | icon color | theme default |
+
+
+#### Invalid state
+
+| Token | Purpose | Default |
+|---|---|---|
+| `--w-c-checkbox-border-color-invalid` | border color when invalid | theme default |
+| `--w-c-checkbox-bg-invalid-checked` | background when invalid and checked | theme default |
+
+
+#### Disabled state
+
+| Token | Purpose | Default |
+|---|---|---|
+| `--w-c-checkbox-bg-disabled` | background when disabled | theme default |
+| `--w-c-checkbox-border-color-disabled` | border when disabled | theme default |
+| `--w-c-checkbox-bg-disabled-checked` | background when disabled and checked | theme default |
+
+#### Focus
+
+| Token | Purpose | Default |
+|---|---|---|
+| `--w-c-checkbox-outline-width` | focus outline width | `2px` |
+| `--w-c-checkbox-outline-color` | focus outline color | theme default |
+| `--w-c-checkbox-outline-offset` | focus outline offset | theme default |
+
+#### Motion
+
+| Token | Purpose | Default |
+|---|---|---|
+| `--w-c-checkbox-transition` | transition for control | `150ms cubic-bezier(0.4, 0, 0.2, 1)` |
+
+Transitions are automatically disabled when `prefers-reduced-motion: reduce` is active.
+
+### Examples
+
+#### Compact checkbox
+
+```css
+.filters w-checkbox {
+  --w-c-checkbox-gap: 4px;
+  --w-c-checkbox-control-size: 1.6rem;
+}
+```
+
+#### Rounded checkbox
+
+```css
+w-checkbox {
+  --w-c-checkbox-radius: 9999px;
+}
+```
+
+#### Contextual color override (advanced)
+
+```css
+.danger-zone w-checkbox {
+  --w-c-checkbox-border-color-checked: red;
+}
+```
+
+### Guidelines
+
+- 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

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

@@ -0,0 +1,95 @@
+## Usage
+
+Checkbox lets users select one or more options. Use it for independent yes/no choices, multi-select lists, and terms or consent confirmations.
+
+Use `w-checkbox-group` when several checkboxes share one label, help text, optional indicator, or required validation.
+
+### Basic Checkbox
+
+```html
+<w-checkbox name="newsletter" value="yes">Sign up for updates</w-checkbox>
+```
+
+The slotted text becomes the checkbox label.
+
+### Checked State
+
+Use `checked` when the checkbox should be selected by default.
+
+```html
+<w-checkbox name="alerts" value="email" checked>Email alerts</w-checkbox>
+```
+
+Listen for the `change` event when you need to react to user changes.
+
+```html
+<w-checkbox id="newsletter" name="newsletter" value="yes">Sign up for updates</w-checkbox>
+
+<script>
+  const checkbox = document.querySelector('#newsletter');
+
+  checkbox.addEventListener('change', () => {
+    console.log(checkbox.checked);
+  });
+</script>
+```
+
+### Form Submission
+
+`w-checkbox` is form-associated. When checked, it submits its `name` and `value` with the form. When unchecked or disabled, it submits nothing.
+
+```html
+<form>
+  <w-checkbox name="newsletter" value="yes">Sign up for updates</w-checkbox>
+  <w-button type="submit">Submit</w-button>
+</form>
+```
+
+If no `value` is set, the submitted value defaults to `on`.
+
+### Required
+
+Use `required` when one standalone checkbox must be checked before form submission, such as accepting terms.
+
+```html
+<form>
+  <w-checkbox name="terms" value="accepted" required>Accept the terms</w-checkbox>
+  <w-button type="submit">Continue</w-button>
+</form>
+```
+
+For a set of options where at least one option is required, put `required` on `w-checkbox-group` instead.
+
+### Checkbox Group
+
+Use `w-checkbox-group` to group related options under a shared label and help text.
+
+```html
+<w-checkbox-group label="Interests" help-text="Select all that apply" name="interests">
+  <w-checkbox value="housing">Housing</w-checkbox>
+  <w-checkbox value="jobs">Jobs</w-checkbox>
+  <w-checkbox value="travel">Travel</w-checkbox>
+</w-checkbox-group>
+```
+
+The group name is applied to child checkboxes that do not have their own `name`.
+
+### Indeterminate
+
+Use `indeterminate` when a parent checkbox represents a mixed set of child selections.
+
+```html
+<w-checkbox name="all-notifications" indeterminate>All notifications</w-checkbox>
+```
+
+Indeterminate is a visual state. When the user clicks the checkbox, the indeterminate state is cleared and the checkbox becomes checked.
+
+### Invalid
+
+Set `invalid` when validation is managed outside the component.
+
+```html
+<w-checkbox name="terms" value="accepted" invalid>Accept the terms</w-checkbox>
+```
+
+When possible, place clear error text near the checkbox or group so users know how to correct the error.

package/dist/docs/combobox/combobox.md

@@ -155,6 +155,8 @@ combobox.options = [
 
 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).

package/dist/docs/combobox/styling.md

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

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).
 

package/dist/docs/datepicker/datepicker.md

@@ -10,10 +10,196 @@ Uses the `lang` attribute on either the element or on `<html>` to determine the
 
 ## Usage
 
+Datepicker lets users type or choose a calendar date.
+
+Use `w-datepicker` when the user needs to provide one specific date, such as a travel date, appointment date, or deadline. The component is form-associated and submits an ISO date value.
+
+### Basic Datepicker
+
+```html
+<w-datepicker label="Date" name="date"></w-datepicker>
+```
+
+Always provide a visible `label`.
+
+### Value
+
+Use `value` to set the selected date. The value should use `YYYY-MM-DD` format.
+
+```html
+<w-datepicker label="Start date" name="start-date" value="2026-06-15"></w-datepicker>
+```
+
+The same value is submitted with the form.
+
+```html
+<form>
+  <w-datepicker label="Departure date" name="departure"></w-datepicker>
+  <w-button type="submit">Search</w-button>
+</form>
+```
+
+### Locale
+
+Datepicker uses the `lang` attribute on the component, or the `lang` attribute on `<html>`, to choose locale-specific calendar labels and formatting.
+
+```html
+<w-datepicker label="Dato" name="date" lang="nb"></w-datepicker>
+```
+
+The component includes built-in locale support for `en`, `nb`, `sv`, `da`, and `fi`.
+
+### Formatting
+
+Use `header-format`, `weekday-format`, and `day-format` to control calendar display and accessible day labels.
+
+```html
+<w-datepicker
+  label="Date"
+  name="date"
+  header-format="MMMM yyyy"
+  weekday-format="EEEEEE"
+  day-format="PPPP"
+></w-datepicker>
+```
+
+These formats use `date-fns/format` syntax. Keep `day-format` descriptive because it is used as the accessible name for each day in the calendar.
+
+### Disable Dates
+
+Use `isDayDisabled` to prevent users from selecting certain dates from the calendar.
+
+This property must be set on the element instance in JavaScript.
+
+```html
+<w-datepicker id="booking-date" label="Booking date" name="booking-date"></w-datepicker>
+
+<script type="module">
+  const datepicker = document.querySelector('#booking-date');
+
+  datepicker.isDayDisabled = (day) => day.getDay() === 0;
+</script>
+```
+
+Disabled dates cannot be selected from the calendar.
+
+### About change events
+
+With events the datepicker works much like the native `<input type="date">`:
+
+- When the user types in the input field the component fires [`input` events](https://developer.mozilla.org/en-US/docs/Web/API/Element/input_event).
+- When the user clicks a date in the calendar the component fires [`change` events](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event).
+
+Note that the component does not fire a `change` event when typing in the input field. This is intentional.
+
+You can listen to the [`blur` event](https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event) if you only care about getting a value, no matter if it was typed or chosen via the calendar. Note that the `blur` event might not fire if the user types and submits the form without leaving the input field. If you use the `blur` event to update JavaScript state you should read the value from the datepicker in your `submit` handler as well.
+
 ## 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.
+
 ## Examples
 
+### Basic
+
+<elements-example>
+
+```html
+<w-datepicker label="Date" name="date"></w-datepicker>
+```
+
+</elements-example>
+
+### With Value
+
+<elements-example>
+
+```html
+<w-datepicker label="Start date" name="start-date" value="2026-06-15"></w-datepicker>
+```
+
+</elements-example>
+
+### Locale
+
+<elements-example>
+
+```html
+<w-datepicker label="Dato" name="date" lang="nb"></w-datepicker>
+```
+
+</elements-example>
+
+### Custom Formats
+
+<elements-example>
+
+```html
+<w-datepicker
+  label="Date"
+  name="date"
+  header-format="MMMM yyyy"
+  weekday-format="EEEEEE"
+  day-format="PPPP"
+></w-datepicker>
+```
+
+</elements-example>
+
+### Form Associated
+
+<elements-example>
+
+```html
+<form>
+  <w-datepicker label="Departure date" name="departure"></w-datepicker>
+  <w-button type="submit">Search</w-button>
+</form>
+```
+
+</elements-example>
+
+### Disabled Calendar Dates
+
+<elements-example>
+
+```html
+<w-datepicker id="booking-date" label="Booking date" name="booking-date"></w-datepicker>
+
+<script type="module">
+  const datepicker = document.querySelector('#booking-date');
+
+  datepicker.isDayDisabled = (day) => day.getDay() === 0;
+</script>
+```
+
+</elements-example>
+
+## Styling API
+
 ## `<w-datepicker>` API
 
 Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).
@@ -23,15 +209,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` | `-` | - |
@@ -39,8 +225,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` | `-` | - |
 
@@ -55,7 +241,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).
 
@@ -64,7 +250,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).
 
@@ -87,23 +273,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: `-`
@@ -117,7 +307,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: `-`
@@ -177,14 +369,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).