@warp-ds/elements 2.9.1 → 2.10.0-next.1

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

@@ -0,0 +1,69 @@
+## `<w-radio-group>` API
+
+Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).
+
+### Properties
+
+| Name | Type | Default | Summary |
+|-|-|-|-|
+| disabled | `boolean` | `false` | Disables the radio group and all child radios. |
+| help-text | `string` | `''` | Help text for the radio group. |
+| invalid | `boolean` | `false` | Marks the radio group as invalid. |
+| label | `string` | `''` | Label for the radio group. |
+| name | `string \| null` | `null` | The [name](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#name) of the select when submitting the form. |
+| optional | `boolean` | `false` | Whether to show optional text next to the label. |
+| required | `boolean` | `false` | Makes selecting a radio in the the group required. |
+
+### Property Details
+
+#### disabled
+
+Disables the radio group and all child radios.
+
+- Type: `boolean`
+- Default: `false`
+
+#### help-text
+
+Help text for the radio group.
+
+If you set `required` and `invalid` the group gets a default error message, but you can override it with this attribute.
+
+- Type: `string`
+- Default: `''`
+
+#### invalid
+
+Marks the radio group as invalid.
+
+- Type: `boolean`
+- Default: `false`
+
+#### label
+
+Label for the radio group.
+
+- Type: `string`
+- Default: `''`
+
+#### name
+
+The [name](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#name) of the select when submitting the form.
+
+- Type: `string | null`
+- Default: `null`
+
+#### optional
+
+Whether to show optional text next to the label.
+
+- Type: `boolean`
+- Default: `false`
+
+#### required
+
+Makes selecting a radio in the the group required.
+
+- Type: `boolean`
+- Default: `false`
+

package/dist/docs/radio-group/examples.md

@@ -0,0 +1,68 @@
+## Examples
+
+<elements-example>
+
+```html
+<w-radio-group label="Select an option" name="examples">
+    <w-radio value="one">Option 1</w-radio>
+    <w-radio value="two">Option 2</w-radio>
+    <w-radio value="three">Option 3</w-radio>
+</w-radio-group>
+```
+
+</elements-example>
+
+### Optional
+
+Add the `optional` prop to `<w-radio-group>` to indicate that the user doesn't have to pick an option.
+
+<elements-example>
+
+```html
+<w-radio-group label="Select an option" name="optional" optional>
+    <w-radio value="one">Option 1</w-radio>
+    <w-radio value="two">Option 2</w-radio>
+    <w-radio value="three">Option 3</w-radio>
+</w-radio-group>
+```
+
+</elements-example>
+
+
+### Help text
+
+Use `help-text` to give additional context when the label and options are not enough.
+
+<elements-example>
+
+```html
+<w-radio-group label="Select an option" name="help" help-text="Pick whichever you like">
+    <w-radio value="one">Option 1</w-radio>
+    <w-radio value="two">Option 2</w-radio>
+    <w-radio value="three">Option 3</w-radio>
+</w-radio-group>
+```
+
+</elements-example>
+
+### Disabled
+
+Keep in mind that using disabled is an anti-pattern.
+
+There will always be users who don't understand why an element is disabled, or users who can't even see that
+it is disabled because of poor lighting conditions or other reasons.
+
+Please consider more informative alternatives before choosing to use disabled on an element.
+
+
+<elements-example>
+
+```html
+<w-radio-group label="Select an option" name="disabled" disabled>
+    <w-radio value="one">Option 1</w-radio>
+    <w-radio value="two">Option 2</w-radio>
+    <w-radio value="three">Option 3</w-radio>
+</w-radio-group>
+```
+
+</elements-example>

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

@@ -0,0 +1,311 @@
+# RadioGroup (w-radio-group)
+
+## Description
+
+Radios allow users to select a single option from a list of choices.
+
+Use with `w-radio`.
+
+## Usage
+
+A radio input typically consists of two components:
+
+- `<w-radio-group>` - A grouping wrapper that manages labeling, help text, roving keyboard focus, and validation for child radios.
+- `<w-radio>` - A single radio with required and invalid states.
+
+In advanced cases you may use `<w-radio>` without `<w-radio-group>`. If you're unsure what's correct in your case, always wrap `<w-radio>` in a `<w-radio-group>`.
+
+The components automatically handle:
+
+- Form integration and constraint validation
+- Required state handling with validation messages
+- Accessibility attributes, keyboard interaction, and labeling
+
+<elements-example>
+
+```html
+<w-radio-group label="Select an option" name="usage">
+    <w-radio value="one">Option 1</w-radio>
+    <w-radio value="two">Option 2</w-radio>
+    <w-radio value="three">Option 3</w-radio>
+</w-radio-group>
+```
+
+</elements-example>
+
+### Validation
+
+Set the `invalid` attribute to display a radio group as invalid, for example if nothing was selected and the group was `required`.
+
+`invalid` can be paired with `help-text` to provide feedback to the user about how to correct the error. However, since the `invalid` + `required` use case is so common you can omit `help-text` to use a generic built-in one.
+
+<elements-example>
+
+```html
+<w-radio-group label="Select an option" name="usage" required invalid>
+    <w-radio value="one">Option 1</w-radio>
+    <w-radio value="two">Option 2</w-radio>
+    <w-radio value="three">Option 3</w-radio>
+</w-radio-group>
+```
+
+</elements-example>
+
+## Accessibility
+
+## Examples
+
+<elements-example>
+
+```html
+<w-radio-group label="Select an option" name="examples">
+    <w-radio value="one">Option 1</w-radio>
+    <w-radio value="two">Option 2</w-radio>
+    <w-radio value="three">Option 3</w-radio>
+</w-radio-group>
+```
+
+</elements-example>
+
+### Optional
+
+Add the `optional` prop to `<w-radio-group>` to indicate that the user doesn't have to pick an option.
+
+<elements-example>
+
+```html
+<w-radio-group label="Select an option" name="optional" optional>
+    <w-radio value="one">Option 1</w-radio>
+    <w-radio value="two">Option 2</w-radio>
+    <w-radio value="three">Option 3</w-radio>
+</w-radio-group>
+```
+
+</elements-example>
+
+
+### Help text
+
+Use `help-text` to give additional context when the label and options are not enough.
+
+<elements-example>
+
+```html
+<w-radio-group label="Select an option" name="help" help-text="Pick whichever you like">
+    <w-radio value="one">Option 1</w-radio>
+    <w-radio value="two">Option 2</w-radio>
+    <w-radio value="three">Option 3</w-radio>
+</w-radio-group>
+```
+
+</elements-example>
+
+### Disabled
+
+Keep in mind that using disabled is an anti-pattern.
+
+There will always be users who don't understand why an element is disabled, or users who can't even see that
+it is disabled because of poor lighting conditions or other reasons.
+
+Please consider more informative alternatives before choosing to use disabled on an element.
+
+
+<elements-example>
+
+```html
+<w-radio-group label="Select an option" name="disabled" disabled>
+    <w-radio value="one">Option 1</w-radio>
+    <w-radio value="two">Option 2</w-radio>
+    <w-radio value="three">Option 3</w-radio>
+</w-radio-group>
+```
+
+</elements-example>
+
+## Styling API
+
+This section documents the supported styling hooks for `<w-radio>` and `<w-radio-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.
+
+### Parts
+
+The radio exposes a small set of parts that can be targeted for last‑mile layout or typography tweaks.
+
+| Part | Targets | Typical use |
+|---|---|---|
+| `control` | radio control (circle) | minor alignment or sizing tweaks |
+| `label` | label content | typography tweaks |
+
+Example:
+
+```css
+w-radio::part(label) {
+  font-weight: 600;
+}
+
+w-radio::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-radio-*`) act as inputs to the radio styling.
+They can be set directly on the component or inherited from a parent container.
+
+```css
+.settings-panel {
+  --w-c-radio-gap: 12px;
+}
+```
+
+Defaults are defined internally; setting a token is always optional.
+
+
+#### Layout & size
+
+| Token | Purpose | Default |
+|---|---|---|
+| `--w-c-radio-gap` | space between control and label | `8px` |
+| `--w-c-radio-size` | width/height of the control | `2rem` |
+| `--w-c-radio-radius` | border radius of the control | `50%` |
+| `--w-c-radio-border-width` | border width | `1px` |
+| `--w-c-radio-checked-border-width` | border width when checked | `0.6rem` |
+
+
+#### Colors
+
+| Token | Purpose | Default |
+|---|---|---|
+| `--w-c-radio-bg` | control background | theme default |
+| `--w-c-radio-border-color` | control border color | theme default |
+| `--w-c-radio-border-color-checked` | border color when checked | theme default |
+| `--w-c-radio-label-color` | label text color | `currentColor` |
+
+
+#### Invalid state
+
+| Token | Purpose | Default |
+|---|---|---|
+| `--w-c-radio-border-color-invalid` | border color when invalid | theme default |
+
+
+#### Disabled state
+
+| Token | Purpose | Default |
+|---|---|---|
+| `--w-c-radio-bg-disabled` | background when disabled | theme default |
+| `--w-c-radio-border-color-disabled` | border when disabled | theme default |
+| `--w-c-radio-label-color-disabled` | label color when disabled | theme default |
+| `--w-c-radio-cursor-disabled` | cursor when disabled | `not-allowed` |
+
+#### Typography
+
+| Token | Purpose | Default |
+|---|---|---|
+| `--w-c-radio-label-font-size` | label font size | theme default |
+| `--w-c-radio-label-line-height` | label line height | theme default |
+
+
+#### Focus
+
+| Token | Purpose | Default |
+|---|---|---|
+| `--w-c-radio-outline-width` | focus outline width | `2px` |
+| `--w-c-radio-outline-color` | focus outline color | theme default |
+| `--w-c-radio-outline-offset` | focus outline offset | theme default |
+
+#### Interaction
+
+| Token | Purpose | Default |
+|---|---|---|
+| `--w-c-radio-cursor` | cursor in enabled state | `pointer` |
+
+#### Motion
+
+| Token | Purpose | Default |
+|---|---|---|
+| `--w-c-radio-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-radio-group>` API
+
+Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).
+
+### Properties
+
+| Name | Type | Default | Summary |
+|-|-|-|-|
+| disabled | `boolean` | `false` | Disables the radio group and all child radios. |
+| help-text | `string` | `''` | Help text for the radio group. |
+| invalid | `boolean` | `false` | Marks the radio group as invalid. |
+| label | `string` | `''` | Label for the radio group. |
+| name | `string \| null` | `null` | The [name](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#name) of the select when submitting the form. |
+| optional | `boolean` | `false` | Whether to show optional text next to the label. |
+| required | `boolean` | `false` | Makes selecting a radio in the the group required. |
+
+### Property Details
+
+#### disabled
+
+Disables the radio group and all child radios.
+
+- Type: `boolean`
+- Default: `false`
+
+#### help-text
+
+Help text for the radio group.
+
+If you set `required` and `invalid` the group gets a default error message, but you can override it with this attribute.
+
+- Type: `string`
+- Default: `''`
+
+#### invalid
+
+Marks the radio group as invalid.
+
+- Type: `boolean`
+- Default: `false`
+
+#### label
+
+Label for the radio group.
+
+- Type: `string`
+- Default: `''`
+
+#### name
+
+The [name](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#name) of the select when submitting the form.
+
+- Type: `string | null`
+- Default: `null`
+
+#### optional
+
+Whether to show optional text next to the label.
+
+- Type: `boolean`
+- Default: `false`
+
+#### required
+
+Makes selecting a radio in the the group required.
+
+- Type: `boolean`
+- Default: `false`
+

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

@@ -0,0 +1,118 @@
+## Styling API
+
+This section documents the supported styling hooks for `<w-radio>` and `<w-radio-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.
+
+### Parts
+
+The radio exposes a small set of parts that can be targeted for last‑mile layout or typography tweaks.
+
+| Part | Targets | Typical use |
+|---|---|---|
+| `control` | radio control (circle) | minor alignment or sizing tweaks |
+| `label` | label content | typography tweaks |
+
+Example:
+
+```css
+w-radio::part(label) {
+  font-weight: 600;
+}
+
+w-radio::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-radio-*`) act as inputs to the radio styling.
+They can be set directly on the component or inherited from a parent container.
+
+```css
+.settings-panel {
+  --w-c-radio-gap: 12px;
+}
+```
+
+Defaults are defined internally; setting a token is always optional.
+
+
+#### Layout & size
+
+| Token | Purpose | Default |
+|---|---|---|
+| `--w-c-radio-gap` | space between control and label | `8px` |
+| `--w-c-radio-size` | width/height of the control | `2rem` |
+| `--w-c-radio-radius` | border radius of the control | `50%` |
+| `--w-c-radio-border-width` | border width | `1px` |
+| `--w-c-radio-checked-border-width` | border width when checked | `0.6rem` |
+
+
+#### Colors
+
+| Token | Purpose | Default |
+|---|---|---|
+| `--w-c-radio-bg` | control background | theme default |
+| `--w-c-radio-border-color` | control border color | theme default |
+| `--w-c-radio-border-color-checked` | border color when checked | theme default |
+| `--w-c-radio-label-color` | label text color | `currentColor` |
+
+
+#### Invalid state
+
+| Token | Purpose | Default |
+|---|---|---|
+| `--w-c-radio-border-color-invalid` | border color when invalid | theme default |
+
+
+#### Disabled state
+
+| Token | Purpose | Default |
+|---|---|---|
+| `--w-c-radio-bg-disabled` | background when disabled | theme default |
+| `--w-c-radio-border-color-disabled` | border when disabled | theme default |
+| `--w-c-radio-label-color-disabled` | label color when disabled | theme default |
+| `--w-c-radio-cursor-disabled` | cursor when disabled | `not-allowed` |
+
+#### Typography
+
+| Token | Purpose | Default |
+|---|---|---|
+| `--w-c-radio-label-font-size` | label font size | theme default |
+| `--w-c-radio-label-line-height` | label line height | theme default |
+
+
+#### Focus
+
+| Token | Purpose | Default |
+|---|---|---|
+| `--w-c-radio-outline-width` | focus outline width | `2px` |
+| `--w-c-radio-outline-color` | focus outline color | theme default |
+| `--w-c-radio-outline-offset` | focus outline offset | theme default |
+
+#### Interaction
+
+| Token | Purpose | Default |
+|---|---|---|
+| `--w-c-radio-cursor` | cursor in enabled state | `pointer` |
+
+#### Motion
+
+| Token | Purpose | Default |
+|---|---|---|
+| `--w-c-radio-transition` | transition for control | `150ms cubic-bezier(0.4, 0, 0.2, 1)` |
+
+Transitions are automatically disabled when `prefers-reduced-motion: reduce` is active.
+

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

@@ -0,0 +1,44 @@
+## Usage
+
+A radio input typically consists of two components:
+
+- `<w-radio-group>` - A grouping wrapper that manages labeling, help text, roving keyboard focus, and validation for child radios.
+- `<w-radio>` - A single radio with required and invalid states.
+
+In advanced cases you may use `<w-radio>` without `<w-radio-group>`. If you're unsure what's correct in your case, always wrap `<w-radio>` in a `<w-radio-group>`.
+
+The components automatically handle:
+
+- Form integration and constraint validation
+- Required state handling with validation messages
+- Accessibility attributes, keyboard interaction, and labeling
+
+<elements-example>
+
+```html
+<w-radio-group label="Select an option" name="usage">
+    <w-radio value="one">Option 1</w-radio>
+    <w-radio value="two">Option 2</w-radio>
+    <w-radio value="three">Option 3</w-radio>
+</w-radio-group>
+```
+
+</elements-example>
+
+### Validation
+
+Set the `invalid` attribute to display a radio group as invalid, for example if nothing was selected and the group was `required`.
+
+`invalid` can be paired with `help-text` to provide feedback to the user about how to correct the error. However, since the `invalid` + `required` use case is so common you can omit `help-text` to use a generic built-in one.
+
+<elements-example>
+
+```html
+<w-radio-group label="Select an option" name="usage" required invalid>
+    <w-radio value="one">Option 1</w-radio>
+    <w-radio value="two">Option 2</w-radio>
+    <w-radio value="three">Option 3</w-radio>
+</w-radio-group>
+```
+
+</elements-example>

package/dist/docs/select/accessibility.md

@@ -1 +1,3 @@
 ## Accessibility
+
+If a visible label isn't specified, an `aria-label` must be provided to the text field for accessibility. If the field is labeled by a separate element, an `aria-labelledby` property must be provided using the `id` of the labeling element instead.

package/dist/docs/select/api.md

@@ -6,19 +6,19 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 | Name | Type | Default | Summary |
 |-|-|-|-|
-| always | `boolean` | `false` | Whether to always show a hint.. **Deprecated**: Use `help-text` instead and only set it if you want to display the help text. |
-| auto-focus | `boolean` | `false` | Whether the element should receive focus on render.. **Deprecated**: Use the native `autofocus` attribute instead. |
+| always | `boolean` | `false` | Whether to always show a hint. **Deprecated**: Use `help-text` instead and only set it if you want to display the help text. |
+| auto-focus | `boolean` | `false` | Whether the element should receive focus on render. **Deprecated**: Use the native `autofocus` attribute instead. |
 | autofocus | `boolean` | `false` | Whether the element should receive focus on render |
 | disabled | `boolean` | `false` | Renders the field in a disabled state. |
-| help-text | `string` | `-` | The content displayed as the help text. Paired with `invalid` to show the text as a validation error. |
-| hint | `string` | `-` | The content displayed as the help text.. **Deprecated**: Use `help-text` instead. |
-| invalid | `boolean` | `false` | Renders the field in an invalid state. Paired with `help-text` to provide feedback about the error. |
-| label | `string` | `-` | The content to disply as the label |
-| name | `string` | `-` | - |
-| optional | `boolean` | `false` | Whether to show optional text |
-| read-only | `boolean` | `false` | Renders the field in a readonly state.. **Deprecated**: Use the native readonly attribute instead. |
+| help-text | `string` | `-` | The content displayed as the help text. |
+| hint | `string` | `-` | The content displayed as the help text. **Deprecated**: Use `help-text` instead. |
+| invalid | `boolean` | `false` | Renders the field in an invalid state. |
+| label | `string` | `-` | The content to display as the label. |
+| name | `string` | `-` | The [name](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#name) of the select when submitting the form. |
+| optional | `boolean` | `false` | Whether to show the optional indicator after the label. |
+| read-only | `boolean` | `false` | Renders the field in a readonly state. **Deprecated**: Use the native readonly attribute instead. |
 | readonly | `boolean` | `false` | Renders the field in a readonly state. |
-| value | `string` | `-` | - |
+| value | `string` | `-` | Lets you set the current value. |
 
 ### Property Details
 
@@ -56,7 +56,9 @@ Renders the field in a disabled state.
 
 #### help-text
 
-The content displayed as the help text. Paired with `invalid` to show the text as a validation error.
+The content displayed as the help text.
+
+Paired with `invalid` to show the text as a validation error.
 
 - Type: `string`
 - Default: `-`
@@ -72,28 +74,30 @@ The content displayed as the help text.
 
 #### invalid
 
-Renders the field in an invalid state. Paired with `help-text` to provide feedback about the error.
+Renders the field in an invalid state.
+
+Paired with `help-text` to provide feedback about the error.
 
 - Type: `boolean`
 - Default: `false`
 
 #### label
 
-The content to disply as the label
+The content to display as the label.
 
 - Type: `string`
 - Default: `-`
 
 #### name
 
-
+The [name](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#name) of the select when submitting the form.
 
 - Type: `string`
 - Default: `-`
 
 #### optional
 
-Whether to show optional text
+Whether to show the optional indicator after the label.
 
 - Type: `boolean`
 - Default: `false`
@@ -116,7 +120,7 @@ Renders the field in a readonly state.
 
 #### value
 
-
+Lets you set the current value.
 
 - Type: `string`
 - Default: `-`