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

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

@@ -0,0 +1,134 @@
+## Styling API
+
+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.
+
+| 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
+
+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
+.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.
+
+
+## w-checkbox-group
+
+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.
+
+### Styling
+
+The checkbox-group provides minimal styling hooks:
+
+| 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 |
+
+
+## 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.
+
+**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/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/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,126 +6,164 @@ 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. |
+| 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. |
 
 ### 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'`
+- 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: `''`
+- 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: `''`
+- 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: `''`
+- 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: `''`
+- 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`
 
+#### resetFormControl (JS only)
+
+
+
+- Type: `resetFormControl() => void`
+- Default: `-`
+
 #### 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: `''`
+- Default: `""`