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

package/dist/docs/switch/switch.md

@@ -34,6 +34,8 @@ The internal control is rendered as a native `button` with `role="switch"` and `
 
 </elements-example>
 
+## Styling API
+
 ## `<w-switch>` API
 
 Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).
@@ -45,6 +47,7 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 | checked | `boolean` | `false` | Whether the switch is on (checked). |
 | disabled | `boolean` | `false` | Whether the switch is disabled. |
 | name | `string` | `-` | Name used when submitting an HTML form. |
+| resetFormControl (JS only) | `resetFormControl() => void` | `-` | - |
 | value | `string` | `-` | Value submitted when the switch is checked. |
 
 ### Property Details
@@ -70,6 +73,13 @@ Name used when submitting an HTML form.
 - Type: `string`
 - Default: `-`
 
+#### resetFormControl (JS only)
+
+
+
+- Type: `resetFormControl() => void`
+- Default: `-`
+
 #### value
 
 Value submitted when the switch is checked.

package/dist/docs/tabs/api.md

@@ -6,7 +6,7 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 | Name | Type | Default | Summary |
 |-|-|-|-|
-| active | `string` | `"" (Shows the first tab)` | The `id` of the panel that should be active. |
+| active | `string \| undefined` | `"" (Shows the first tab)` | The `id` of the panel that should be active. |
 
 ### Property Details
 
@@ -14,7 +14,7 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 The `id` of the panel that should be active.
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `"" (Shows the first tab)`
 
 ### Events

package/dist/docs/tabs/styling.md

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

package/dist/docs/tabs/tabs.md

@@ -97,6 +97,8 @@ Use the `over` attribute to position icons above the label:
 
 </elements-example>
 
+## Styling API
+
 ## `<w-tabs>` API
 
 Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).
@@ -105,7 +107,7 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 | Name | Type | Default | Summary |
 |-|-|-|-|
-| active | `string` | `"" (Shows the first tab)` | The `id` of the panel that should be active. |
+| active | `string \| undefined` | `"" (Shows the first tab)` | The `id` of the panel that should be active. |
 
 ### Property Details
 
@@ -113,7 +115,7 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 The `id` of the panel that should be active.
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `"" (Shows the first tab)`
 
 ### Events

package/dist/docs/textarea/api.md

@@ -6,24 +6,36 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 | Name | Type | Default | Summary |
 |-|-|-|-|
+| checkValidity (JS only) | `checkValidity() => boolean` | `-` | Checks whether the textarea passes constraint validation |
 | disabled | `boolean` | `false` | Makes the element not focusable and hides it from form submits |
-| help-text | `string` | `-` | Description shown below the input field |
+| handler (JS only) | `handler(e: InputEvent) => void` | `-` | - |
+| help-text | `string \| undefined` | `-` | Description shown below the input field |
 | invalid | `boolean` | `false` | Mark the form field as invalid. |
-| label | `string` | `-` | Either a `label` or an `aria-label` must be provided. |
-| maximum-rows | `number` | `-` | Sets the maximum number of text rows before the content starts scrolling. |
-| minimum-rows | `number` | `-` | Sets the minimum number of text rows the textarea should display |
-| name | `string` | `-` | The [name](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#name) of the input field when submitting the form |
+| label | `string \| undefined` | `-` | Either a `label` or an `aria-label` must be provided. |
+| maximum-rows | `number \| undefined` | `-` | Sets the maximum number of text rows before the content starts scrolling. |
+| minimum-rows | `number \| undefined` | `-` | Sets the minimum number of text rows the textarea should display |
+| name | `string \| undefined` | `-` | The [name](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#name) of the input field when submitting the form |
 | optional | `boolean` | `false` | Show an icon behind the label indicating the field is optional |
-| placeholder | `string` | `-` | Shown in the textarea when it doesn't have a value |
+| placeholder | `string \| undefined` | `-` | Shown in the textarea when it doesn't have a value |
 | read-only | `boolean` | `false` | **Deprecated**: Use the native `readonly` attribute instead |
 | readonly | `boolean` | `false` | Whether the input can be selected but not changed by the user |
+| reportValidity (JS only) | `reportValidity() => boolean` | `-` | Checks validity and shows the browser's validation message if invalid |
 | required | `boolean` | `false` | Whether user input is required on the input before form submission |
+| resetFormControl (JS only) | `resetFormControl() => void` | `-` | - |
+| setCustomValidity (JS only) | `setCustomValidity(message: string) => void` | `-` | Sets a custom validation message. Pass an empty string to clear. |
 | validationMessage (JS only) | `string` | `-` | Returns the validation message if the textarea is invalid, otherwise an empty string |
 | validity (JS only) | `ValidityState` | `-` | Returns the validity state of the textarea |
-| value | `string` | `-` | Lets you set the current value |
+| value | `string \| undefined` | `-` | Lets you set the current value |
 
 ### Property Details
 
+#### checkValidity (JS only)
+
+Checks whether the textarea passes constraint validation
+
+- Type: `checkValidity() => boolean`
+- Default: `-`
+
 #### disabled
 
 Keep in mind that using disabled in its current form is an anti-pattern.
@@ -35,12 +47,19 @@ Please consider more informative alternatives before choosing to use disabled on
 - Type: `boolean`
 - Default: `false`
 
+#### handler (JS only)
+
+
+
+- Type: `handler(e: InputEvent) => void`
+- Default: `-`
+
 #### help-text
 
 Use in combination with `invalid` to show as a validation error message,
 or on its own to show a help text.
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`
 
 #### invalid
@@ -56,28 +75,28 @@ Make sure to also set a `help-text` to help users fix the validation problem.
 
 Either a `label` or an `aria-label` must be provided.
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`
 
 #### maximum-rows
 
 Sets the maximum number of text rows before the content starts scrolling.
 
-- Type: `number`
+- Type: `number | undefined`
 - Default: `-`
 
 #### minimum-rows
 
 Sets the minimum number of text rows the textarea should display
 
-- Type: `number`
+- Type: `number | undefined`
 - Default: `-`
 
 #### name
 
 The [name](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#name) of the input field when submitting the form
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`
 
 #### optional
@@ -93,7 +112,7 @@ Set a text that is shown in the textarea when it doesn't have a value.
 
 Placeholder text should not be used as a substitute for labeling the element with a visible label.
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`
 
 #### read-only
@@ -112,6 +131,13 @@ Whether the input can be selected but not changed by the user
 - Type: `boolean`
 - Default: `false`
 
+#### reportValidity (JS only)
+
+Checks validity and shows the browser's validation message if invalid
+
+- Type: `reportValidity() => boolean`
+- Default: `-`
+
 #### required
 
 Whether user input is required on the input before form submission
@@ -119,6 +145,20 @@ Whether user input is required on the input before form submission
 - Type: `boolean`
 - Default: `false`
 
+#### resetFormControl (JS only)
+
+
+
+- Type: `resetFormControl() => void`
+- Default: `-`
+
+#### setCustomValidity (JS only)
+
+Sets a custom validation message. Pass an empty string to clear.
+
+- Type: `setCustomValidity(message: string) => void`
+- Default: `-`
+
 #### validationMessage (JS only)
 
 Returns the validation message if the textarea is invalid, otherwise an empty string
@@ -137,6 +177,6 @@ Returns the validity state of the textarea
 
 Lets you set the current value
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`
 

package/dist/docs/textarea/styling.md

@@ -0,0 +1,92 @@
+## Styling API
+
+This section documents the supported styling hooks for `<w-textarea>`.
+
+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 textarea exposes a minimal set of parts that can be targeted for last‑mile layout or typography tweaks.
+
+| Part | Targets | Typical use |
+|---|---|---|
+| `input` | native textarea element | minor typography or spacing tweaks |
+
+Example:
+
+```css
+w-textarea::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 textarea 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
+
+Textarea shares its label, optional indicator, and help text tokens with `w-textfield` and `w-select`. This ensures consistent form styling across all text input components.

package/dist/docs/textarea/textarea.md

@@ -111,6 +111,99 @@ Makes the textarea content immutable while remaining focusable. The contents can
 
 </elements-example>
 
+## Styling API
+
+This section documents the supported styling hooks for `<w-textarea>`.
+
+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 textarea exposes a minimal set of parts that can be targeted for last‑mile layout or typography tweaks.
+
+| Part | Targets | Typical use |
+|---|---|---|
+| `input` | native textarea element | minor typography or spacing tweaks |
+
+Example:
+
+```css
+w-textarea::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 textarea 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
+
+Textarea shares its label, optional indicator, and help text tokens with `w-textfield` and `w-select`. This ensures consistent form styling across all text input components.
+
 ## `<w-textarea>` API
 
 Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).
@@ -119,24 +212,36 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 | Name | Type | Default | Summary |
 |-|-|-|-|
+| checkValidity (JS only) | `checkValidity() => boolean` | `-` | Checks whether the textarea passes constraint validation |
 | disabled | `boolean` | `false` | Makes the element not focusable and hides it from form submits |
-| help-text | `string` | `-` | Description shown below the input field |
+| handler (JS only) | `handler(e: InputEvent) => void` | `-` | - |
+| help-text | `string \| undefined` | `-` | Description shown below the input field |
 | invalid | `boolean` | `false` | Mark the form field as invalid. |
-| label | `string` | `-` | Either a `label` or an `aria-label` must be provided. |
-| maximum-rows | `number` | `-` | Sets the maximum number of text rows before the content starts scrolling. |
-| minimum-rows | `number` | `-` | Sets the minimum number of text rows the textarea should display |
-| name | `string` | `-` | The [name](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#name) of the input field when submitting the form |
+| label | `string \| undefined` | `-` | Either a `label` or an `aria-label` must be provided. |
+| maximum-rows | `number \| undefined` | `-` | Sets the maximum number of text rows before the content starts scrolling. |
+| minimum-rows | `number \| undefined` | `-` | Sets the minimum number of text rows the textarea should display |
+| name | `string \| undefined` | `-` | The [name](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#name) of the input field when submitting the form |
 | optional | `boolean` | `false` | Show an icon behind the label indicating the field is optional |
-| placeholder | `string` | `-` | Shown in the textarea when it doesn't have a value |
+| placeholder | `string \| undefined` | `-` | Shown in the textarea when it doesn't have a value |
 | read-only | `boolean` | `false` | **Deprecated**: Use the native `readonly` attribute instead |
 | readonly | `boolean` | `false` | Whether the input can be selected but not changed by the user |
+| reportValidity (JS only) | `reportValidity() => boolean` | `-` | Checks validity and shows the browser's validation message if invalid |
 | required | `boolean` | `false` | Whether user input is required on the input before form submission |
+| resetFormControl (JS only) | `resetFormControl() => void` | `-` | - |
+| setCustomValidity (JS only) | `setCustomValidity(message: string) => void` | `-` | Sets a custom validation message. Pass an empty string to clear. |
 | validationMessage (JS only) | `string` | `-` | Returns the validation message if the textarea is invalid, otherwise an empty string |
 | validity (JS only) | `ValidityState` | `-` | Returns the validity state of the textarea |
-| value | `string` | `-` | Lets you set the current value |
+| value | `string \| undefined` | `-` | Lets you set the current value |
 
 ### Property Details
 
+#### checkValidity (JS only)
+
+Checks whether the textarea passes constraint validation
+
+- Type: `checkValidity() => boolean`
+- Default: `-`
+
 #### disabled
 
 Keep in mind that using disabled in its current form is an anti-pattern.
@@ -148,12 +253,19 @@ Please consider more informative alternatives before choosing to use disabled on
 - Type: `boolean`
 - Default: `false`
 
+#### handler (JS only)
+
+
+
+- Type: `handler(e: InputEvent) => void`
+- Default: `-`
+
 #### help-text
 
 Use in combination with `invalid` to show as a validation error message,
 or on its own to show a help text.
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`
 
 #### invalid
@@ -169,28 +281,28 @@ Make sure to also set a `help-text` to help users fix the validation problem.
 
 Either a `label` or an `aria-label` must be provided.
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`
 
 #### maximum-rows
 
 Sets the maximum number of text rows before the content starts scrolling.
 
-- Type: `number`
+- Type: `number | undefined`
 - Default: `-`
 
 #### minimum-rows
 
 Sets the minimum number of text rows the textarea should display
 
-- Type: `number`
+- Type: `number | undefined`
 - Default: `-`
 
 #### name
 
 The [name](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#name) of the input field when submitting the form
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`
 
 #### optional
@@ -206,7 +318,7 @@ Set a text that is shown in the textarea when it doesn't have a value.
 
 Placeholder text should not be used as a substitute for labeling the element with a visible label.
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`
 
 #### read-only
@@ -225,6 +337,13 @@ Whether the input can be selected but not changed by the user
 - Type: `boolean`
 - Default: `false`
 
+#### reportValidity (JS only)
+
+Checks validity and shows the browser's validation message if invalid
+
+- Type: `reportValidity() => boolean`
+- Default: `-`
+
 #### required
 
 Whether user input is required on the input before form submission
@@ -232,6 +351,20 @@ Whether user input is required on the input before form submission
 - Type: `boolean`
 - Default: `false`
 
+#### resetFormControl (JS only)
+
+
+
+- Type: `resetFormControl() => void`
+- Default: `-`
+
+#### setCustomValidity (JS only)
+
+Sets a custom validation message. Pass an empty string to clear.
+
+- Type: `setCustomValidity(message: string) => void`
+- Default: `-`
+
 #### validationMessage (JS only)
 
 Returns the validation message if the textarea is invalid, otherwise an empty string
@@ -250,6 +383,6 @@ Returns the validity state of the textarea
 
 Lets you set the current value
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`