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

package/dist/docs/breadcrumbs/breadcrumbs.md

@@ -98,6 +98,7 @@ Breadcrumbs should support orientation within the site hierarchy. They should no
 ### Basic
 
 <elements-example>
+
 ```html
   <w-breadcrumbs>
     <a href="#/real-estate">Real estate</a>
@@ -105,11 +106,13 @@ Breadcrumbs should support orientation within the site hierarchy. They should no
     <span aria-current="page">Oslo</span>
   </w-breadcrumbs>
 ```
+
 </elements-example>
 
 ### Custom Accessible Label
 
 <elements-example>
+
 ```html
   <w-breadcrumbs aria-label="Product category path">
     <a href="#/marketplace">Marketplace</a>
@@ -117,19 +120,24 @@ Breadcrumbs should support orientation within the site hierarchy. They should no
     <span aria-current="page">Sofas</span>
   </w-breadcrumbs>
 ```
+
 </elements-example>
 
 ### Short Path
 
 <elements-example>
+
 ```html
   <w-breadcrumbs>
     <a href="#/help">Help</a>
     <span aria-current="page">Contact us</span>
   </w-breadcrumbs>
 ```
+
 </elements-example>
 
+## Styling API
+
 ## `<w-breadcrumbs>` API
 
 Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).

package/dist/docs/breadcrumbs/examples.md

@@ -3,6 +3,7 @@
 ### Basic
 
 <elements-example>
+
 ```html
   <w-breadcrumbs>
     <a href="#/real-estate">Real estate</a>
@@ -10,11 +11,13 @@
     <span aria-current="page">Oslo</span>
   </w-breadcrumbs>
 ```
+
 </elements-example>
 
 ### Custom Accessible Label
 
 <elements-example>
+
 ```html
   <w-breadcrumbs aria-label="Product category path">
     <a href="#/marketplace">Marketplace</a>
@@ -22,15 +25,18 @@
     <span aria-current="page">Sofas</span>
   </w-breadcrumbs>
 ```
+
 </elements-example>
 
 ### Short Path
 
 <elements-example>
+
 ```html
   <w-breadcrumbs>
     <a href="#/help">Help</a>
     <span aria-current="page">Contact us</span>
   </w-breadcrumbs>
 ```
-</elements-example>
+
+</elements-example>

package/dist/docs/breadcrumbs/styling.md

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

package/dist/docs/button/button.md

@@ -270,6 +270,79 @@ For backwards compatibility, if `href` is set, `w-button` renders a link with bu
 
 </elements-example>
 
+## Styling API
+
+This component supports styling through **component tokens** (CSS custom properties with a --w-c- prefix) and **parts**.
+
+### Parts
+
+Use `::part(...)` from outside the component.
+
+- `base` — the clickable element (`<button>` or `<w-link>`)
+
+Example:
+
+```css
+w-button::part(base) {
+  text-transform: uppercase;
+}
+```
+
+### Component tokens
+
+Set these on `w-button` to override visuals.
+
+```css
+w-button {
+  --w-c-button-bg: var(--w-s-color-background-primary);
+  --w-c-button-color: var(--w-s-color-text-inverted);
+}
+```
+
+#### Layout & typography
+
+- `--w-c-button-radius`
+- `--w-c-button-font-size`
+- `--w-c-button-line-height`
+- `--w-c-button-font-weight`
+- `--w-c-button-padding-x`
+- `--w-c-button-padding-y`
+
+#### Background
+
+- `--w-c-button-bg`
+- `--w-c-button-bg-hover`
+- `--w-c-button-bg-active`
+
+#### Text color
+
+- `--w-c-button-color`
+- `--w-c-button-color-hover`
+- `--w-c-button-color-active`
+
+#### Border
+
+- `--w-c-button-border-width`
+- `--w-c-button-border-color`
+- `--w-c-button-border-color-hover`
+- `--w-c-button-border-color-active`
+
+#### Focus
+
+- `--w-c-button-outline-width`
+- `--w-c-button-outline-color`
+- `--w-c-button-outline-offset`
+
+#### Motion
+
+- `--w-c-button-transition`
+
+### Notes
+
+- Variant defaults are set internally using fallbacks, so overriding tokens works across variants.
+- The `quiet` boolean is supported for backwards compatibility. Prefer `variant="quiet"` going forward.
+- When `loading` is set, the button is treated as disabled (no pointer interaction).
+
 ## `<w-button>` API
 
 Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).

package/dist/docs/button/styling.md

@@ -0,0 +1,72 @@
+## Styling API
+
+This component supports styling through **component tokens** (CSS custom properties with a --w-c- prefix) and **parts**.
+
+### Parts
+
+Use `::part(...)` from outside the component.
+
+- `base` — the clickable element (`<button>` or `<w-link>`)
+
+Example:
+
+```css
+w-button::part(base) {
+  text-transform: uppercase;
+}
+```
+
+### Component tokens
+
+Set these on `w-button` to override visuals.
+
+```css
+w-button {
+  --w-c-button-bg: var(--w-s-color-background-primary);
+  --w-c-button-color: var(--w-s-color-text-inverted);
+}
+```
+
+#### Layout & typography
+
+- `--w-c-button-radius`
+- `--w-c-button-font-size`
+- `--w-c-button-line-height`
+- `--w-c-button-font-weight`
+- `--w-c-button-padding-x`
+- `--w-c-button-padding-y`
+
+#### Background
+
+- `--w-c-button-bg`
+- `--w-c-button-bg-hover`
+- `--w-c-button-bg-active`
+
+#### Text color
+
+- `--w-c-button-color`
+- `--w-c-button-color-hover`
+- `--w-c-button-color-active`
+
+#### Border
+
+- `--w-c-button-border-width`
+- `--w-c-button-border-color`
+- `--w-c-button-border-color-hover`
+- `--w-c-button-border-color-active`
+
+#### Focus
+
+- `--w-c-button-outline-width`
+- `--w-c-button-outline-color`
+- `--w-c-button-outline-offset`
+
+#### Motion
+
+- `--w-c-button-transition`
+
+### Notes
+
+- Variant defaults are set internally using fallbacks, so overriding tokens works across variants.
+- The `quiet` boolean is supported for backwards compatibility. Prefer `variant="quiet"` going forward.
+- When `loading` is set, the button is treated as disabled (no pointer interaction).

package/dist/docs/card/card.md

@@ -237,6 +237,8 @@ Use a button for an action on the current page:
 
 </elements-example>
 
+## Styling API
+
 ## `<w-card>` API
 
 Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).

package/dist/docs/card/styling.md

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

package/dist/docs/checkbox/api.md

@@ -0,0 +1,128 @@
+### `<w-checkbox>` API
+
+#### Properties
+
+| Name | Type | Default | Summary |
+|-|-|-|-|
+| _computedInvalid (JS only) | `boolean` | `-` | Computed invalid state: combines own invalid with group invalid |
+| checked | `boolean` | `false` | Whether the checkbox is checked. |
+| disabled | `boolean` | `false` | Whether the checkbox is disabled. |
+| indeterminate | `boolean` | `false` | Whether the checkbox is visually indeterminate. |
+| input (JS only) | `HTMLInputElement \| null` | `-` | - |
+| invalid | `boolean` | `false` | Whether the checkbox is visually invalid. |
+| name | `string \| undefined` | `-` | The name of the checkbox. |
+| required | `boolean` | `false` | Whether the checkbox must be checked before form submission. |
+| shadowRootOptions (JS only) | `object` | `{ ...LitElement.shadowRootOptions, delegatesFocus: true }` | - |
+| validationMessage (JS only) | `string` | `-` | Returns the validation message if the checkbox is invalid, otherwise an empty string |
+| validity (JS only) | `ValidityState` | `-` | Returns the validity state of the checkbox |
+| value | `string \| null` | `null` | The value submitted when the checkbox is checked. |
+
+#### Property Details
+
+##### _computedInvalid (JS only)
+
+Computed invalid state: combines own invalid with group invalid
+
+- Type: `boolean`
+- Default: `-`
+
+##### checked
+
+Whether the checkbox is checked.
+
+Checked checkboxes submit their value with form data. The property is reflected to the `checked` attribute.
+
+- Type: `boolean`
+- Default: `false`
+
+##### disabled
+
+Whether the checkbox is disabled.
+
+Disabled checkboxes cannot be focused, changed, or submitted with form data.
+
+- Type: `boolean`
+- Default: `false`
+
+##### indeterminate
+
+Whether the checkbox is visually indeterminate.
+
+Use this for parent options that represent a mixed set of child selections. Clicking the checkbox clears the indeterminate state and sets the checkbox to checked.
+
+- Type: `boolean`
+- Default: `false`
+
+##### input (JS only)
+
+
+
+- Type: `HTMLInputElement | null`
+- Default: `-`
+
+##### invalid
+
+Whether the checkbox is visually invalid.
+
+Use this to show an externally managed validation error. Required validation also sets the invalid state after the user interacts with the checkbox or tries to submit the form.
+
+- Type: `boolean`
+- Default: `false`
+
+##### name
+
+The name of the checkbox.
+
+When the checkbox is checked and belongs to a form, this name is submitted with the checkbox value. If the checkbox is inside a `w-checkbox-group` with a name, the group name is used when the checkbox does not have its own name.
+
+- Type: `string | undefined`
+- Default: `-`
+
+##### required
+
+Whether the checkbox must be checked before form submission.
+
+A required checkbox is invalid until it is checked. For requiring at least one option in a set, use `required` on `w-checkbox-group`.
+
+- Type: `boolean`
+- Default: `false`
+
+##### shadowRootOptions (JS only)
+
+
+
+- Type: `object`
+- Default: `{ ...LitElement.shadowRootOptions, delegatesFocus: true }`
+
+##### validationMessage (JS only)
+
+Returns the validation message if the checkbox is invalid, otherwise an empty string
+
+- Type: `string`
+- Default: `-`
+
+##### validity (JS only)
+
+Returns the validity state of the checkbox
+
+- Type: `ValidityState`
+- Default: `-`
+
+##### value
+
+The value submitted when the checkbox is checked.
+
+If no value attribute is set, the checkbox defaults to `on`. Unchecked and disabled checkboxes do not submit a value.
+
+- Type: `string | null`
+- Default: `null`
+
+#### Events
+
+##### change
+
+
+
+- Type: `Event`
+
+

package/dist/docs/checkbox/checkbox.md

@@ -0,0 +1,134 @@
+# Checkbox (w-checkbox)
+
+## Description
+
+
+
+### `<w-checkbox>` API
+
+#### Properties
+
+| Name | Type | Default | Summary |
+|-|-|-|-|
+| _computedInvalid (JS only) | `boolean` | `-` | Computed invalid state: combines own invalid with group invalid |
+| checked | `boolean` | `false` | Whether the checkbox is checked. |
+| disabled | `boolean` | `false` | Whether the checkbox is disabled. |
+| indeterminate | `boolean` | `false` | Whether the checkbox is visually indeterminate. |
+| input (JS only) | `HTMLInputElement \| null` | `-` | - |
+| invalid | `boolean` | `false` | Whether the checkbox is visually invalid. |
+| name | `string \| undefined` | `-` | The name of the checkbox. |
+| required | `boolean` | `false` | Whether the checkbox must be checked before form submission. |
+| shadowRootOptions (JS only) | `object` | `{ ...LitElement.shadowRootOptions, delegatesFocus: true }` | - |
+| validationMessage (JS only) | `string` | `-` | Returns the validation message if the checkbox is invalid, otherwise an empty string |
+| validity (JS only) | `ValidityState` | `-` | Returns the validity state of the checkbox |
+| value | `string \| null` | `null` | The value submitted when the checkbox is checked. |
+
+#### Property Details
+
+##### _computedInvalid (JS only)
+
+Computed invalid state: combines own invalid with group invalid
+
+- Type: `boolean`
+- Default: `-`
+
+##### checked
+
+Whether the checkbox is checked.
+
+Checked checkboxes submit their value with form data. The property is reflected to the `checked` attribute.
+
+- Type: `boolean`
+- Default: `false`
+
+##### disabled
+
+Whether the checkbox is disabled.
+
+Disabled checkboxes cannot be focused, changed, or submitted with form data.
+
+- Type: `boolean`
+- Default: `false`
+
+##### indeterminate
+
+Whether the checkbox is visually indeterminate.
+
+Use this for parent options that represent a mixed set of child selections. Clicking the checkbox clears the indeterminate state and sets the checkbox to checked.
+
+- Type: `boolean`
+- Default: `false`
+
+##### input (JS only)
+
+
+
+- Type: `HTMLInputElement | null`
+- Default: `-`
+
+##### invalid
+
+Whether the checkbox is visually invalid.
+
+Use this to show an externally managed validation error. Required validation also sets the invalid state after the user interacts with the checkbox or tries to submit the form.
+
+- Type: `boolean`
+- Default: `false`
+
+##### name
+
+The name of the checkbox.
+
+When the checkbox is checked and belongs to a form, this name is submitted with the checkbox value. If the checkbox is inside a `w-checkbox-group` with a name, the group name is used when the checkbox does not have its own name.
+
+- Type: `string | undefined`
+- Default: `-`
+
+##### required
+
+Whether the checkbox must be checked before form submission.
+
+A required checkbox is invalid until it is checked. For requiring at least one option in a set, use `required` on `w-checkbox-group`.
+
+- Type: `boolean`
+- Default: `false`
+
+##### shadowRootOptions (JS only)
+
+
+
+- Type: `object`
+- Default: `{ ...LitElement.shadowRootOptions, delegatesFocus: true }`
+
+##### validationMessage (JS only)
+
+Returns the validation message if the checkbox is invalid, otherwise an empty string
+
+- Type: `string`
+- Default: `-`
+
+##### validity (JS only)
+
+Returns the validity state of the checkbox
+
+- Type: `ValidityState`
+- Default: `-`
+
+##### value
+
+The value submitted when the checkbox is checked.
+
+If no value attribute is set, the checkbox defaults to `on`. Unchecked and disabled checkboxes do not submit a value.
+
+- Type: `string | null`
+- Default: `null`
+
+#### Events
+
+##### change
+
+
+
+- Type: `Event`
+
+

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

@@ -0,0 +1,71 @@
+## Accessibility
+
+Checkbox group renders the child checkboxes inside an element with `role="group"`. The group label is connected to the group, and help text is connected when provided.
+
+### Provide A Group Label
+
+Use `label` to describe the shared question or topic.
+
+```html
+<w-checkbox-group label="Interests" 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 label should not duplicate every option label. It should explain what the options are about.
+
+### Use Help Text For Extra Context
+
+Use `help-text` for instructions, constraints, or validation feedback.
+
+```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>
+```
+
+Keep help text short and actionable.
+
+### Required Groups
+
+Use `required` on the group when at least one option must be selected.
+
+```html
+<w-checkbox-group label="Preferences" required help-text="Choose at least one" name="preferences">
+  <w-checkbox value="email">Email</w-checkbox>
+  <w-checkbox value="sms">SMS</w-checkbox>
+</w-checkbox-group>
+```
+
+Do not put `required` on each child checkbox for a "choose at least one" requirement. That would mean every option must be selected.
+
+### Validation Feedback
+
+Do not rely on invalid styling alone. Provide clear help text that explains what the user needs to do.
+
+```html
+<w-checkbox-group label="Preferences" invalid help-text="Select at least one option" name="preferences">
+  <w-checkbox value="email">Email</w-checkbox>
+  <w-checkbox value="sms">SMS</w-checkbox>
+</w-checkbox-group>
+```
+
+When the group is invalid, the invalid state is also shared with child checkboxes for consistent styling and accessibility state.
+
+### Checkbox Labels
+
+Each child checkbox still needs its own clear label.
+
+```html
+<w-checkbox-group label="Contact preferences" name="contact">
+  <w-checkbox value="email">Email</w-checkbox>
+  <w-checkbox value="sms">SMS</w-checkbox>
+  <w-checkbox value="push">Push notifications</w-checkbox>
+</w-checkbox-group>
+```
+
+Avoid option labels that only make sense visually, such as "Yes" or "This one", unless the group label gives enough context.

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

@@ -0,0 +1,79 @@
+## `<w-checkbox-group>` API
+
+Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).
+
+### Properties
+
+| Name | Type | Default | Summary |
+|-|-|-|-|
+| help-text | `string` | `-` | 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. |
+| optional | `boolean` | `false` | Whether to show optional text next to the label. |
+| required | `boolean` | `false` | Whether at least one checkbox in the group must be selected. |
+| shadowRootOptions (JS only) | `object` | `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }` | - |
+
+### Property Details
+
+#### 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`
+- Default: `-`
+
+#### invalid
+
+Whether the checkbox group is visually invalid.
+
+Use this to show an externally managed validation error for the group. The invalid state is also shared with child checkboxes for consistent styling and accessibility state.
+
+- Type: `boolean`
+- Default: `false`
+
+#### label
+
+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`
+- Default: `-`
+
+#### name
+
+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`
+- Default: `-`
+
+#### optional
+
+Whether to show optional text next to the label.
+
+Use this to indicate that selecting an option from the group is not required.
+
+- Type: `boolean`
+- Default: `false`
+
+#### required
+
+Whether at least one checkbox in the group must be selected.
+
+Required validation is managed by the group. The individual checkboxes provide the submitted form values.
+
+- Type: `boolean`
+- Default: `false`
+
+#### shadowRootOptions (JS only)
+
+
+
+- Type: `object`
+- Default: `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }`
+