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

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

@@ -158,6 +158,99 @@ The `readonly` boolean attribute makes the selection immutable. Unlike disabled
 
 </elements-example>
 
+## 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).
@@ -170,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
 
@@ -220,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
@@ -229,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
@@ -245,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
@@ -282,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

@@ -0,0 +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.

package/dist/docs/slider/api.md

@@ -6,25 +6,34 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 | Name | Type | Default | Summary |
 |-|-|-|-|
+| _label (JS only) | `unknown` | `-` | - |
 | disabled | `boolean` | `false` | - |
-| error | `string` | `-` | Validation error text, if any |
-| help-text | `string` | `-` | Additional description to show below the fieldset |
+| error | `string \| undefined` | `-` | Validation error text, if any |
+| help-text | `string \| undefined` | `-` | Additional description to show below the fieldset |
 | hidden-textfield | `boolean` | `false` | Should only be used in special cases |
 | invalid | `boolean` | `false` | Sets the form fields and fieldset in an invalid state |
-| label | `string` | `-` | The slider fieldset label. Required for proper accessibility. |
-| labelFormatter (JS only) | `(slot: SliderSlot) => string` | `-` | Formatter for the min and max labels below the range. |
-| markers | `number` | `-` | Pass a value similar to step to create visual markers at that interval |
-| max | `string` | `100` | The maximum allowed value in the range inputs |
-| min | `string` | `0` | The minimum allowed value in the range inputs |
+| label | `string \| undefined` | `-` | The slider fieldset label. Required for proper accessibility. |
+| labelFormatter (JS only) | `((slot: SliderSlot) => string) \| undefined` | `-` | Formatter for the min and max labels below the range. |
+| markers | `number \| undefined` | `-` | Pass a value similar to step to create visual markers at that interval |
+| max | `string \| undefined` | `100` | The maximum allowed value in the range inputs |
+| min | `string \| undefined` | `0` | The minimum allowed value in the range inputs |
 | open-ended | `boolean` | `false` | Whether or not to allow values outside the range such as "Before 1950" and "2025+". |
+| optional | `boolean` | `false` | Whether to show the optional indicator after the label. |
 | required | `boolean` | `false` | Ensures a child slider thumb has a value before allowing the containing form to submit |
-| step | `number` | `-` | ets step on the range input to jump between values when dragging |
-| suffix | `string` | `-` | Suffix used in text input fields and for the min and max values of the slider |
-| tooltipFormatter (JS only) | `(value: string, slot: SliderSlot) => string` | `-` | Overrides valueFormatter for the tooltip. |
-| valueFormatter (JS only) | `(value: string, slot: SliderSlot) => string` | `-` | Formatter for the tooltip and input mask values |
+| step | `number \| undefined` | `-` | ets step on the range input to jump between values when dragging |
+| suffix | `string \| undefined` | `-` | Suffix used in text input fields and for the min and max values of the slider |
+| tooltipFormatter (JS only) | `((value: string, slot: SliderSlot) => string) \| undefined` | `-` | Overrides valueFormatter for the tooltip. |
+| valueFormatter (JS only) | `((value: string, slot: SliderSlot) => string) \| undefined` | `-` | Formatter for the tooltip and input mask values |
 
 ### Property Details
 
+#### _label (JS only)
+
+
+
+- Type: `unknown`
+- Default: `-`
+
 #### disabled
 
 
@@ -36,14 +45,14 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 Validation error text, if any
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`
 
 #### help-text
 
 Additional description to show below the fieldset
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`
 
 #### hidden-textfield
@@ -66,35 +75,35 @@ The slider fieldset label. Required for proper accessibility.
 
 If you need to display HTML, use the `label` slot instead (f. ex. `<legend class="sr-only" slot="label">Production year</legend>`)
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`
 
 #### labelFormatter (JS only)
 
 Formatter for the min and max labels below the range.
 
-- Type: `(slot: SliderSlot) => string`
+- Type: `((slot: SliderSlot) => string) | undefined`
 - Default: `-`
 
 #### markers
 
 Pass a value similar to step to create visual markers at that interval
 
-- Type: `number`
+- Type: `number | undefined`
 - Default: `-`
 
 #### max
 
 The maximum allowed value in the range inputs
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `100`
 
 #### min
 
 The minimum allowed value in the range inputs
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `0`
 
 #### open-ended
@@ -104,6 +113,13 @@ Whether or not to allow values outside the range such as "Before 1950" and "2025
 - Type: `boolean`
 - Default: `false`
 
+#### optional
+
+Whether to show the optional indicator after the label.
+
+- Type: `boolean`
+- Default: `false`
+
 #### required
 
 Ensures a child slider thumb has a value before allowing the containing form to submit
@@ -115,14 +131,14 @@ Ensures a child slider thumb has a value before allowing the containing form to
 
 ets step on the range input to jump between values when dragging
 
-- Type: `number`
+- Type: `number | undefined`
 - Default: `-`
 
 #### suffix
 
 Suffix used in text input fields and for the min and max values of the slider
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`
 
 #### tooltipFormatter (JS only)
@@ -131,13 +147,13 @@ Overrides valueFormatter for the tooltip.
 
 Use in open-ended sliders to show for example "300+ hk" instead of "Max" in the tooltip.
 
-- Type: `(value: string, slot: SliderSlot) => string`
+- Type: `((value: string, slot: SliderSlot) => string) | undefined`
 - Default: `-`
 
 #### valueFormatter (JS only)
 
 Formatter for the tooltip and input mask values
 
-- Type: `(value: string, slot: SliderSlot) => string`
+- Type: `((value: string, slot: SliderSlot) => string) | undefined`
 - Default: `-`
 

package/dist/docs/slider/slider.md

@@ -306,6 +306,8 @@ The text field doubles as a visualization of the exact value, which is difficult
 
 </elements-example>
 
+## Styling API
+
 ## `<w-slider>` API
 
 Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).
@@ -314,25 +316,34 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 | Name | Type | Default | Summary |
 |-|-|-|-|
+| _label (JS only) | `unknown` | `-` | - |
 | disabled | `boolean` | `false` | - |
-| error | `string` | `-` | Validation error text, if any |
-| help-text | `string` | `-` | Additional description to show below the fieldset |
+| error | `string \| undefined` | `-` | Validation error text, if any |
+| help-text | `string \| undefined` | `-` | Additional description to show below the fieldset |
 | hidden-textfield | `boolean` | `false` | Should only be used in special cases |
 | invalid | `boolean` | `false` | Sets the form fields and fieldset in an invalid state |
-| label | `string` | `-` | The slider fieldset label. Required for proper accessibility. |
-| labelFormatter (JS only) | `(slot: SliderSlot) => string` | `-` | Formatter for the min and max labels below the range. |
-| markers | `number` | `-` | Pass a value similar to step to create visual markers at that interval |
-| max | `string` | `100` | The maximum allowed value in the range inputs |
-| min | `string` | `0` | The minimum allowed value in the range inputs |
+| label | `string \| undefined` | `-` | The slider fieldset label. Required for proper accessibility. |
+| labelFormatter (JS only) | `((slot: SliderSlot) => string) \| undefined` | `-` | Formatter for the min and max labels below the range. |
+| markers | `number \| undefined` | `-` | Pass a value similar to step to create visual markers at that interval |
+| max | `string \| undefined` | `100` | The maximum allowed value in the range inputs |
+| min | `string \| undefined` | `0` | The minimum allowed value in the range inputs |
 | open-ended | `boolean` | `false` | Whether or not to allow values outside the range such as "Before 1950" and "2025+". |
+| optional | `boolean` | `false` | Whether to show the optional indicator after the label. |
 | required | `boolean` | `false` | Ensures a child slider thumb has a value before allowing the containing form to submit |
-| step | `number` | `-` | ets step on the range input to jump between values when dragging |
-| suffix | `string` | `-` | Suffix used in text input fields and for the min and max values of the slider |
-| tooltipFormatter (JS only) | `(value: string, slot: SliderSlot) => string` | `-` | Overrides valueFormatter for the tooltip. |
-| valueFormatter (JS only) | `(value: string, slot: SliderSlot) => string` | `-` | Formatter for the tooltip and input mask values |
+| step | `number \| undefined` | `-` | ets step on the range input to jump between values when dragging |
+| suffix | `string \| undefined` | `-` | Suffix used in text input fields and for the min and max values of the slider |
+| tooltipFormatter (JS only) | `((value: string, slot: SliderSlot) => string) \| undefined` | `-` | Overrides valueFormatter for the tooltip. |
+| valueFormatter (JS only) | `((value: string, slot: SliderSlot) => string) \| undefined` | `-` | Formatter for the tooltip and input mask values |
 
 ### Property Details
 
+#### _label (JS only)
+
+
+
+- Type: `unknown`
+- Default: `-`
+
 #### disabled
 
 
@@ -344,14 +355,14 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 Validation error text, if any
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`
 
 #### help-text
 
 Additional description to show below the fieldset
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`
 
 #### hidden-textfield
@@ -374,35 +385,35 @@ The slider fieldset label. Required for proper accessibility.
 
 If you need to display HTML, use the `label` slot instead (f. ex. `<legend class="sr-only" slot="label">Production year</legend>`)
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`
 
 #### labelFormatter (JS only)
 
 Formatter for the min and max labels below the range.
 
-- Type: `(slot: SliderSlot) => string`
+- Type: `((slot: SliderSlot) => string) | undefined`
 - Default: `-`
 
 #### markers
 
 Pass a value similar to step to create visual markers at that interval
 
-- Type: `number`
+- Type: `number | undefined`
 - Default: `-`
 
 #### max
 
 The maximum allowed value in the range inputs
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `100`
 
 #### min
 
 The minimum allowed value in the range inputs
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `0`
 
 #### open-ended
@@ -412,6 +423,13 @@ Whether or not to allow values outside the range such as "Before 1950" and "2025
 - Type: `boolean`
 - Default: `false`
 
+#### optional
+
+Whether to show the optional indicator after the label.
+
+- Type: `boolean`
+- Default: `false`
+
 #### required
 
 Ensures a child slider thumb has a value before allowing the containing form to submit
@@ -423,14 +441,14 @@ Ensures a child slider thumb has a value before allowing the containing form to
 
 ets step on the range input to jump between values when dragging
 
-- Type: `number`
+- Type: `number | undefined`
 - Default: `-`
 
 #### suffix
 
 Suffix used in text input fields and for the min and max values of the slider
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`
 
 #### tooltipFormatter (JS only)
@@ -439,13 +457,13 @@ Overrides valueFormatter for the tooltip.
 
 Use in open-ended sliders to show for example "300+ hk" instead of "Max" in the tooltip.
 
-- Type: `(value: string, slot: SliderSlot) => string`
+- Type: `((value: string, slot: SliderSlot) => string) | undefined`
 - Default: `-`
 
 #### valueFormatter (JS only)
 
 Formatter for the tooltip and input mask values
 
-- Type: `(value: string, slot: SliderSlot) => string`
+- Type: `((value: string, slot: SliderSlot) => string) | undefined`
 - Default: `-`
 

package/dist/docs/slider/styling.md

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