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

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

@@ -1,118 +1,233 @@
-## Styling API
+# Radio and Radio Group Styling
 
-This section documents the supported styling hooks for `<w-radio>` and `<w-radio-group>`.
+This document covers the styling API for both `<w-radio>` (individual radio buttons) and `<w-radio-group>` (the container that manages them).
 
-Use these hooks to customize appearance without relying on internal structure or selectors.
+## Quick Start
 
-Before changing the default styles, remember that doing so can result in less consistent experiences for users across the product. Prefer defaults.
+```html
+<w-radio-group label="Choose a size" name="size">
+  <w-radio value="small">Small</w-radio>
+  <w-radio value="medium">Medium</w-radio>
+  <w-radio value="large">Large</w-radio>
+</w-radio-group>
+```
 
-- Prefer **component tokens** for size, spacing, and state styling.
-- Use **parts** only for small, local tweaks.
-- Avoid relying on internal class names or selectors.
+Customize via component tokens:
 
-### Parts
+```css
+/* Style all radio groups in a section */
+.settings {
+  --w-c-radio-group-gap: 12px;
+  --w-c-radio-size: 2.4rem;
+}
+```
 
-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 |
+## Styling Philosophy
 
-Example:
+Before customizing, remember that changing defaults can create inconsistent experiences. Prefer the defaults.
 
+- **Component tokens** for size, spacing, color, and state styling
+- **Parts** only for small, one-off tweaks
+- Avoid relying on internal class names
+
+---
+
+## Radio Group (`<w-radio-group>`)
+
+### Parts
+
+| Part | Targets | Use Case |
+|------|---------|----------|
+| `form-control` | The `<fieldset>` wrapper | Outer container tweaks |
+| `form-control-label` | The group label element | Label typography overrides |
+| `form-control-input` | Container for radio buttons | Adjust layout/flow of radios |
+| `help-text` | Help text / error message | Style hint text |
+
+**Example:**
 ```css
-w-radio::part(label) {
-  font-weight: 600;
+w-radio-group::part(form-control-label) {
+  text-transform: uppercase;
 }
 
-w-radio::part(control) {
-  margin-top: 1px;
+w-radio-group::part(form-control-input) {
+  flex-direction: row; /* horizontal radios */
 }
 ```
 
-Parts are intended as an **escape hatch**.
-Prefer component tokens for anything state‑ or size‑related.
+### Component Tokens
 
+#### Label
 
-### Component tokens
+| Token | Purpose | Default |
+|-------|---------|---------|
+| `--w-c-radio-group-label-font-size` | Label font size | `var(--w-font-size-s)` |
+| `--w-c-radio-group-label-line-height` | Label line height | `var(--w-line-height-s)` |
+| `--w-c-radio-group-label-font-weight` | Label font weight | `700` |
+| `--w-c-radio-group-label-color` | Label text color | `var(--w-s-color-text)` |
+| `--w-c-radio-group-label-color-disabled` | Label color when disabled | `var(--w-s-color-text-disabled)` |
+| `--w-c-radio-group-label-padding-bottom` | Space below label | `16px` |
 
-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.
+#### Optional Indicator
 
+| Token | Purpose | Default |
+|-------|---------|---------|
+| `--w-c-radio-group-optional-font-weight` | "Optional" text weight | `400` |
+| `--w-c-radio-group-optional-color` | "Optional" text color | `var(--w-s-color-text-subtle)` |
+| `--w-c-radio-group-optional-margin-inline-start` | Space before "Optional" | `0.5rem` |
+
+#### Radio Spacing
+
+| Token | Purpose | Default |
+|-------|---------|---------|
+| `--w-c-radio-group-gap` | Gap between radio buttons | `16px` |
+
+#### Help Text
+
+| Token | Purpose | Default |
+|-------|---------|---------|
+| `--w-c-radio-group-help-text-margin-block-start` | Space above help text | `16px` |
+| `--w-c-radio-group-help-text-font-size` | Help text font size | `var(--w-font-size-xs)` |
+| `--w-c-radio-group-help-text-line-height` | Help text line height | `var(--w-line-height-xs)` |
+| `--w-c-radio-group-help-text-color` | Help text color | `var(--w-s-color-text-subtle)` |
+| `--w-c-radio-group-help-text-color-disabled` | Help text color when disabled | `var(--w-s-color-text-disabled)` |
+| `--w-c-radio-group-help-text-color-error` | Help text color when invalid | `var(--w-s-color-text-negative)` |
+
+**Example:**
 ```css
-.settings-panel {
-  --w-c-radio-gap: 12px;
+w-radio-group {
+  --w-c-radio-group-gap: 12px;
+  --w-c-radio-group-label-font-weight: 600;
+  --w-c-radio-group-help-text-color: var(--w-s-color-text);
 }
 ```
 
-Defaults are defined internally; setting a token is always optional.
+---
 
+## Individual Radio (`<w-radio>`)
 
-#### 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` |
+### Parts
 
+| Part | Targets | Use Case |
+|------|---------|----------|
+| `base` | Wrapper containing control and label | Container-level adjustments |
+| `control` | Radio control (circle) | Alignment or sizing tweaks |
+| `label` | Label content | Typography overrides |
 
-#### Colors
+**Example:**
+```css
+w-radio::part(label) {
+  font-weight: 600;
+}
 
-| 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` |
+w-radio::part(control) {
+  margin-top: 1px;
+}
+```
 
+### Component Tokens
 
-#### Invalid state
+#### Layout & Size
 
 | Token | Purpose | Default |
-|---|---|---|
-| `--w-c-radio-border-color-invalid` | border color when invalid | theme default |
+|-------|---------|---------|
+| `--w-c-radio-gap` | Space between control and label | `8px` |
+| `--w-c-radio-size` | Width/height of control | `2rem` |
+| `--w-c-radio-radius` | Border radius | `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 | `var(--w-s-color-background)` |
+| `--w-c-radio-border-color` | Control border color | `var(--w-s-color-border-strong)` |
+| `--w-c-radio-border-color-checked` | Border when checked | `var(--w-s-color-border-selected)` |
+| `--w-c-radio-border-color-invalid` | Border when invalid | `var(--w-s-color-border-negative)` |
+| `--w-c-radio-label-color` | Label text color | `currentColor` |
 
-#### Disabled state
+#### 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` |
+|-------|---------|---------|
+| `--w-c-radio-bg-disabled` | Background when disabled | `var(--w-s-color-background-disabled-subtle)` |
+| `--w-c-radio-border-color-disabled` | Border when disabled | `var(--w-s-color-border-disabled)` |
+| `--w-c-radio-label-color-disabled` | Label color when disabled | `var(--w-s-color-text-disabled)` |
+| `--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 |
-
+|-------|---------|---------|
+| `--w-c-radio-label-font-size` | Label font size | `var(--w-font-size-m)` |
+| `--w-c-radio-label-line-height` | Label line height | `var(--w-line-height-m)` |
 
 #### 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 |
+|-------|---------|---------|
+| `--w-c-radio-outline-width` | Focus outline width | `2px` |
+| `--w-c-radio-outline-color` | Focus outline color | `var(--w-s-color-border-focus)` |
+| `--w-c-radio-outline-offset` | Focus outline offset | `var(--w-outline-offset, 1px)` |
 
 #### Interaction
 
 | Token | Purpose | Default |
-|---|---|---|
-| `--w-c-radio-cursor` | cursor in enabled state | `pointer` |
+|-------|---------|---------|
+| `--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)` |
+|-------|---------|---------|
+| `--w-c-radio-transition` | Transition for control | `border-color 150ms, border-width 150ms, background-color 150ms` |
+
+**Note:** Transitions automatically disable when `prefers-reduced-motion: reduce` is active.
+
+---
+
+## Complete Examples
+
+### Horizontal Radio Group
+
+```css
+w-radio-group::part(form-control-input) {
+  flex-direction: row;
+  flex-wrap: wrap;
+}
+```
+
+### Larger Radio Buttons
+
+```css
+w-radio {
+  --w-c-radio-size: 2.4rem;
+  --w-c-radio-checked-border-width: 0.8rem;
+}
+```
+
+### Custom Colors
+
+```css
+w-radio {
+  --w-c-radio-border-color-checked: var(--w-s-color-border-success);
+}
+```
+
+### Tighter Spacing
+
+```css
+w-radio-group {
+  --w-c-radio-group-gap: 8px;
+  --w-c-radio-group-label-padding-bottom: 8px;
+}
+```
+
+---
+
+## Architecture Note
 
-Transitions are automatically disabled when `prefers-reduced-motion: reduce` is active.
+**Radio-group uses `<fieldset>`** which is the semantic HTML element for grouping form controls. Note that `<w-checkbox-group>` currently uses `<div>` instead - this inconsistency may be addressed in a future major version to align both components on the more accessible `<fieldset>` approach.
 

package/dist/docs/select/api.md

@@ -10,15 +10,15 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 | 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. |
-| hint | `string` | `-` | The content displayed as the help text. **Deprecated**: Use `help-text` instead. |
+| help-text | `string \| undefined` | `-` | The content displayed as the help text. |
+| hint | `string \| undefined` | `-` | 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. |
+| label | `string \| undefined` | `-` | The content to display as the label. |
+| name | `string \| undefined` | `-` | 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` | `-` | Lets you set the current value. |
+| value | `string \| undefined` | `-` | Lets you set the current value. |
 
 ### Property Details
 
@@ -60,7 +60,7 @@ The content displayed as the help text.
 
 Paired with `invalid` to show the text as a validation error.
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`
 
 #### hint
@@ -69,7 +69,7 @@ Paired with `invalid` to show the text as a validation error.
 
 The content displayed as the help text.
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`
 
 #### invalid
@@ -85,14 +85,14 @@ Paired with `help-text` to provide feedback about the error.
 
 The content to display as the label.
 
-- Type: `string`
+- Type: `string | undefined`
 - 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`
+- Type: `string | undefined`
 - Default: `-`
 
 #### optional
@@ -122,7 +122,7 @@ Renders the field in a readonly state.
 
 Lets you set the current value.
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`
 
 ### Events

package/dist/docs/select/select.md

@@ -160,6 +160,97 @@ The `readonly` boolean attribute makes the selection immutable. Unlike disabled
 
 ## Styling API
 
+This section documents the supported styling hooks for `<w-select>`.
+
+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 select exposes a minimal set of parts that can be targeted for last‑mile layout or typography tweaks.
+
+| Part | Targets | Typical use |
+|---|---|---|
+| `input` | native select element | minor typography or spacing tweaks |
+
+Example:
+
+```css
+w-select::part(input) {
+  letter-spacing: 0.5px;
+}
+```
+
+Parts are intended as an **escape hatch**.
+Prefer component tokens for anything state‑ or size‑related.
+
+
+### Component tokens
+
+Component tokens (`--w-c-input-*`) act as inputs to the select styling.
+They can be set directly on the component or inherited from a parent container.
+
+These tokens are **shared across textfield, textarea, and select** for consistent form styling.
+
+```css
+.form-section {
+  --w-c-input-label-font-weight: 600;
+  --w-c-input-help-text-color: var(--w-s-color-text);
+}
+```
+
+Defaults are defined internally; setting a token is always optional.
+
+
+#### Label tokens
+
+| Token | Purpose | Default |
+|---|---|---|
+| `--w-c-input-label-color` | label text color | `--w-s-color-text` |
+| `--w-c-input-label-font-size` | label font size | `--w-font-size-s` |
+| `--w-c-input-label-line-height` | label line height | `--w-line-height-s` |
+| `--w-c-input-label-font-weight` | label font weight | `700` |
+| `--w-c-input-label-padding-bottom` | space below label | `0.4rem` |
+| `--w-c-input-label-cursor` | cursor when hovering label | `pointer` |
+| `--w-c-input-label-display` | label display mode | `block` |
+
+
+#### Optional indicator tokens
+
+When `optional` attribute is set, these tokens control the "(optional)" text styling:
+
+| Token | Purpose | Default |
+|---|---|---|
+| `--w-c-input-optional-color` | optional text color | `--w-s-color-text-subtle` |
+| `--w-c-input-optional-font-size` | optional text font size | `--w-font-size-s` |
+| `--w-c-input-optional-line-height` | optional text line height | `--w-line-height-s` |
+| `--w-c-input-optional-font-weight` | optional text font weight | `400` |
+| `--w-c-input-optional-padding-left` | space before optional text | `0.8rem` |
+
+
+#### Help text tokens
+
+| Token | Purpose | Default |
+|---|---|---|
+| `--w-c-input-help-text-color` | help text color (normal state) | `--w-s-color-text-subtle` |
+| `--w-c-input-help-text-color-invalid` | help text color when invalid | `--w-s-color-text-negative` |
+| `--w-c-input-help-text-font-size` | help text font size | `--w-font-size-xs` |
+| `--w-c-input-help-text-line-height` | help text line height | `--w-line-height-xs` |
+| `--w-c-input-help-text-margin-top` | space above help text | `0.4rem` |
+| `--w-c-input-help-text-display` | help text display mode | `block` |
+
+
+## Implementation notes
+
+### Shared token system
+
+Select shares its label, optional indicator, and help text tokens with `w-textfield` and `w-textarea`. This ensures consistent form styling across all text input components.
+
 ## `<w-select>` API
 
 Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).
@@ -172,15 +263,15 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 | 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. |
-| hint | `string` | `-` | The content displayed as the help text. **Deprecated**: Use `help-text` instead. |
+| help-text | `string \| undefined` | `-` | The content displayed as the help text. |
+| hint | `string \| undefined` | `-` | 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. |
+| label | `string \| undefined` | `-` | The content to display as the label. |
+| name | `string \| undefined` | `-` | 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` | `-` | Lets you set the current value. |
+| value | `string \| undefined` | `-` | Lets you set the current value. |
 
 ### Property Details
 
@@ -222,7 +313,7 @@ The content displayed as the help text.
 
 Paired with `invalid` to show the text as a validation error.
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`
 
 #### hint
@@ -231,7 +322,7 @@ Paired with `invalid` to show the text as a validation error.
 
 The content displayed as the help text.
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`
 
 #### invalid
@@ -247,14 +338,14 @@ Paired with `help-text` to provide feedback about the error.
 
 The content to display as the label.
 
-- Type: `string`
+- Type: `string | undefined`
 - 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`
+- Type: `string | undefined`
 - Default: `-`
 
 #### optional
@@ -284,7 +375,7 @@ Renders the field in a readonly state.
 
 Lets you set the current value.
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`
 
 ### Events

package/dist/docs/select/styling.md

@@ -1 +1,92 @@
 ## Styling API
+
+This section documents the supported styling hooks for `<w-select>`.
+
+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 select exposes a minimal set of parts that can be targeted for last‑mile layout or typography tweaks.
+
+| Part | Targets | Typical use |
+|---|---|---|
+| `input` | native select element | minor typography or spacing tweaks |
+
+Example:
+
+```css
+w-select::part(input) {
+  letter-spacing: 0.5px;
+}
+```
+
+Parts are intended as an **escape hatch**.
+Prefer component tokens for anything state‑ or size‑related.
+
+
+### Component tokens
+
+Component tokens (`--w-c-input-*`) act as inputs to the select styling.
+They can be set directly on the component or inherited from a parent container.
+
+These tokens are **shared across textfield, textarea, and select** for consistent form styling.
+
+```css
+.form-section {
+  --w-c-input-label-font-weight: 600;
+  --w-c-input-help-text-color: var(--w-s-color-text);
+}
+```
+
+Defaults are defined internally; setting a token is always optional.
+
+
+#### Label tokens
+
+| Token | Purpose | Default |
+|---|---|---|
+| `--w-c-input-label-color` | label text color | `--w-s-color-text` |
+| `--w-c-input-label-font-size` | label font size | `--w-font-size-s` |
+| `--w-c-input-label-line-height` | label line height | `--w-line-height-s` |
+| `--w-c-input-label-font-weight` | label font weight | `700` |
+| `--w-c-input-label-padding-bottom` | space below label | `0.4rem` |
+| `--w-c-input-label-cursor` | cursor when hovering label | `pointer` |
+| `--w-c-input-label-display` | label display mode | `block` |
+
+
+#### Optional indicator tokens
+
+When `optional` attribute is set, these tokens control the "(optional)" text styling:
+
+| Token | Purpose | Default |
+|---|---|---|
+| `--w-c-input-optional-color` | optional text color | `--w-s-color-text-subtle` |
+| `--w-c-input-optional-font-size` | optional text font size | `--w-font-size-s` |
+| `--w-c-input-optional-line-height` | optional text line height | `--w-line-height-s` |
+| `--w-c-input-optional-font-weight` | optional text font weight | `400` |
+| `--w-c-input-optional-padding-left` | space before optional text | `0.8rem` |
+
+
+#### Help text tokens
+
+| Token | Purpose | Default |
+|---|---|---|
+| `--w-c-input-help-text-color` | help text color (normal state) | `--w-s-color-text-subtle` |
+| `--w-c-input-help-text-color-invalid` | help text color when invalid | `--w-s-color-text-negative` |
+| `--w-c-input-help-text-font-size` | help text font size | `--w-font-size-xs` |
+| `--w-c-input-help-text-line-height` | help text line height | `--w-line-height-xs` |
+| `--w-c-input-help-text-margin-top` | space above help text | `0.4rem` |
+| `--w-c-input-help-text-display` | help text display mode | `block` |
+
+
+## Implementation notes
+
+### Shared token system
+
+Select shares its label, optional indicator, and help text tokens with `w-textfield` and `w-textarea`. This ensures consistent form styling across all text input components.