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

package/dist/docs/affix/affix.md

@@ -4,7 +4,15 @@
 
 This component is usually used in other components like form elements to show a prefix or suffix. See for example `w-textfield`.
 
-[See Storybook for usage examples](https://warp-ds.github.io/elements/?path=/docs/forms-affix--docs)
+## Accessibility Note
+Due to shadow DOM encapsulation, ARIA attributes (like `aria-describedby`, `aria-labelledby`)
+cannot reference elements across shadow boundaries. This means:
+- Non-interactive affixes (text labels, icons) cannot be connected to the parent input via ARIA
+- Interactive affixes (buttons) must have their own `aria-label` (already implemented)
+- Do NOT attempt to reference affix content from parent components via ARIA ID references - it won't work
+
+For non-interactive labels (e.g., currency symbols), consider including the information in the
+main label or placeholder instead of relying on ARIA to announce affix content.
 
 ## Usage
 
@@ -144,6 +152,115 @@ Clicking the clear button will reset the textfield
 
 </elements-example>
 
+# Affix Styling
+
+The affix component provides a comprehensive styling API through CSS custom properties (tokens).
+
+## Styling API
+
+### Wrapper Tokens
+
+Customize the appearance of the affix wrapper container:
+
+```css
+--w-c-affix-wrapper-bg: transparent;
+--w-c-affix-wrapper-border-radius: 0.4rem;
+--w-c-affix-wrapper-padding-left: 1.2rem;
+--w-c-affix-wrapper-padding-right: 1.2rem;
+--w-c-affix-wrapper-width-with-label: max-content;
+--w-c-affix-wrapper-width-with-icon: 4rem;
+```
+
+### Label Tokens
+
+Customize the appearance of text labels (when `label` property is used):
+
+```css
+--w-c-affix-label-color: var(--w-s-color-text);
+--w-c-affix-label-font-size: var(--w-font-size-xs);
+--w-c-affix-label-line-height: var(--w-line-height-xs);
+--w-c-affix-label-font-weight: 700;
+--w-c-affix-label-cursor: default;
+```
+
+## Parts
+
+For advanced styling needs beyond tokens, you can target internal elements using CSS parts:
+
+- `::part(wrapper)` - The container element (either `<div>` or `<button>` depending on variant)
+- `::part(label)` - The text label element (when using `label` property)
+
+```css
+w-affix::part(wrapper) {
+  /* Custom styling for the wrapper */
+  background-color: var(--w-s-color-background-subtle);
+}
+
+w-affix::part(label) {
+  /* Custom styling for text labels */
+  text-transform: uppercase;
+}
+```
+
+## Example Usage
+
+### Customizing Label Color
+
+```css
+w-affix {
+  --w-c-affix-label-color: var(--w-s-color-text-primary);
+}
+```
+
+### Customizing Wrapper Background
+
+```css
+w-affix {
+  --w-c-affix-wrapper-bg: var(--w-s-color-background-subtle);
+  --w-c-affix-wrapper-padding-left: 1.6rem;
+  --w-c-affix-wrapper-padding-right: 1.6rem;
+}
+```
+
+### Adjusting Icon/Label Widths
+
+```css
+w-affix {
+  --w-c-affix-wrapper-width-with-icon: 5rem;
+  --w-c-affix-wrapper-width-with-label: auto;
+}
+```
+
+### Styling by Slot Position
+
+Target prefix and suffix affixes differently:
+
+```css
+/* Style only prefix affixes */
+w-affix[slot='prefix'] {
+  --w-c-affix-wrapper-padding-left: 2rem;
+}
+
+/* Style only suffix affixes */
+w-affix[slot='suffix'] {
+  --w-c-affix-wrapper-padding-right: 2rem;
+}
+```
+
+### Using Parts for Advanced Customization
+
+```css
+/* Add a border to the wrapper */
+w-affix::part(wrapper) {
+  border-left: 1px solid var(--w-s-color-border);
+}
+
+/* Make labels italic */
+w-affix::part(label) {
+  font-style: italic;
+}
+```
+
 ## `<w-affix>` API
 
 Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).
@@ -156,7 +273,7 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 | aria-label | `string \| null` | `null` | Accessible label for icon-button variants. |
 | clear | `boolean` | `false` | Renders a clear icon button. |
 | icon | `string \| null` | `null` | Icon name rendered as prefix/suffix content. |
-| label | `string` | `''` | Text label shown as prefix/suffix content. |
+| label | `string` | `""` | Text label shown as prefix/suffix content. |
 | search | `boolean` | `false` | Renders a search icon button. |
 
 ### Property Details
@@ -196,7 +313,7 @@ Set an `aria-label` that explains the action when using this.
 
 
 - Type: `string`
-- Default: `''`
+- Default: `""`
 
 #### search
 

package/dist/docs/affix/api.md

@@ -10,7 +10,7 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 | aria-label | `string \| null` | `null` | Accessible label for icon-button variants. |
 | clear | `boolean` | `false` | Renders a clear icon button. |
 | icon | `string \| null` | `null` | Icon name rendered as prefix/suffix content. |
-| label | `string` | `''` | Text label shown as prefix/suffix content. |
+| label | `string` | `""` | Text label shown as prefix/suffix content. |
 | search | `boolean` | `false` | Renders a search icon button. |
 
 ### Property Details
@@ -50,7 +50,7 @@ Set an `aria-label` that explains the action when using this.
 
 
 - Type: `string`
-- Default: `''`
+- Default: `""`
 
 #### search
 

package/dist/docs/affix/styling.md

@@ -0,0 +1,108 @@
+# Affix Styling
+
+The affix component provides a comprehensive styling API through CSS custom properties (tokens).
+
+## Styling API
+
+### Wrapper Tokens
+
+Customize the appearance of the affix wrapper container:
+
+```css
+--w-c-affix-wrapper-bg: transparent;
+--w-c-affix-wrapper-border-radius: 0.4rem;
+--w-c-affix-wrapper-padding-left: 1.2rem;
+--w-c-affix-wrapper-padding-right: 1.2rem;
+--w-c-affix-wrapper-width-with-label: max-content;
+--w-c-affix-wrapper-width-with-icon: 4rem;
+```
+
+### Label Tokens
+
+Customize the appearance of text labels (when `label` property is used):
+
+```css
+--w-c-affix-label-color: var(--w-s-color-text);
+--w-c-affix-label-font-size: var(--w-font-size-xs);
+--w-c-affix-label-line-height: var(--w-line-height-xs);
+--w-c-affix-label-font-weight: 700;
+--w-c-affix-label-cursor: default;
+```
+
+## Parts
+
+For advanced styling needs beyond tokens, you can target internal elements using CSS parts:
+
+- `::part(wrapper)` - The container element (either `<div>` or `<button>` depending on variant)
+- `::part(label)` - The text label element (when using `label` property)
+
+```css
+w-affix::part(wrapper) {
+  /* Custom styling for the wrapper */
+  background-color: var(--w-s-color-background-subtle);
+}
+
+w-affix::part(label) {
+  /* Custom styling for text labels */
+  text-transform: uppercase;
+}
+```
+
+## Example Usage
+
+### Customizing Label Color
+
+```css
+w-affix {
+  --w-c-affix-label-color: var(--w-s-color-text-primary);
+}
+```
+
+### Customizing Wrapper Background
+
+```css
+w-affix {
+  --w-c-affix-wrapper-bg: var(--w-s-color-background-subtle);
+  --w-c-affix-wrapper-padding-left: 1.6rem;
+  --w-c-affix-wrapper-padding-right: 1.6rem;
+}
+```
+
+### Adjusting Icon/Label Widths
+
+```css
+w-affix {
+  --w-c-affix-wrapper-width-with-icon: 5rem;
+  --w-c-affix-wrapper-width-with-label: auto;
+}
+```
+
+### Styling by Slot Position
+
+Target prefix and suffix affixes differently:
+
+```css
+/* Style only prefix affixes */
+w-affix[slot='prefix'] {
+  --w-c-affix-wrapper-padding-left: 2rem;
+}
+
+/* Style only suffix affixes */
+w-affix[slot='suffix'] {
+  --w-c-affix-wrapper-padding-right: 2rem;
+}
+```
+
+### Using Parts for Advanced Customization
+
+```css
+/* Add a border to the wrapper */
+w-affix::part(wrapper) {
+  border-left: 1px solid var(--w-s-color-border);
+}
+
+/* Make labels italic */
+w-affix::part(label) {
+  font-style: italic;
+}
+```

package/dist/docs/alert/alert.md

@@ -6,8 +6,6 @@ Alert is an inline component used for displaying different types of messages.
 
 For accessibility reasons, alert should appear close to the element that triggered it.
 
-[See Storybook for usage examples](https://warp-ds.github.io/elements/?path=/docs/feedback-alert--docs)
-
 ## Usage
 
 Alert is an inline component used for displaying different types of messages.
@@ -152,6 +150,8 @@ attribute on [MDN](https://developer.mozilla.org/en-US/docs/Web/Accessibility/AR
 </script>
 ```
 
+## Styling API
+
 ## `<w-alert>` API
 
 Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).
@@ -160,9 +160,9 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 | Name | Type | Default | Summary |
 |-|-|-|-|
-| role | `string` | `'alert'` | ARIA role announced to assistive technology. |
+| role | `string` | `"alert"` | ARIA role announced to assistive technology. |
 | show | `boolean` | `false` | Whether the alert is visible. |
-| variant | [`AlertVariants`](#alertvariants) | `'info'` | Visual style of the alert. |
+| variant | [`AlertVariants`](#alertvariants) | `"info"` | Visual style of the alert. |
 
 ### Property Details
 
@@ -171,7 +171,7 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 
 - Type: `string`
-- Default: `'alert'`
+- Default: `"alert"`
 
 #### show
 
@@ -185,7 +185,7 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 
 - Type: [`AlertVariants`](#alertvariants)
-- Default: `'info'`
+- Default: `"info"`
 
 ### Types
 

package/dist/docs/alert/api.md

@@ -6,9 +6,9 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 | Name | Type | Default | Summary |
 |-|-|-|-|
-| role | `string` | `'alert'` | ARIA role announced to assistive technology. |
+| role | `string` | `"alert"` | ARIA role announced to assistive technology. |
 | show | `boolean` | `false` | Whether the alert is visible. |
-| variant | [`AlertVariants`](#alertvariants) | `'info'` | Visual style of the alert. |
+| variant | [`AlertVariants`](#alertvariants) | `"info"` | Visual style of the alert. |
 
 ### Property Details
 
@@ -17,7 +17,7 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 
 - Type: `string`
-- Default: `'alert'`
+- Default: `"alert"`
 
 #### show
 
@@ -31,7 +31,7 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 
 - Type: [`AlertVariants`](#alertvariants)
-- Default: `'info'`
+- Default: `"info"`
 
 ### Types
 

package/dist/docs/alert/styling.md

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

package/dist/docs/attention/api.md

@@ -8,15 +8,21 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 |-|-|-|-|
 | _actualDirection (JS only) | `unknown` | `-` | - |
 | _initialPlacement (JS only) | `unknown` | `-` | - |
+| activeAttentionType (JS only) | `activeAttentionType() => void` | `-` | - |
 | callout | `boolean` | `false` | Renders the component as an inline callout. |
 | can-close | `boolean` | `false` | Shows a close button inside the attention component. |
+| close (JS only) | `close() => void` | `-` | - |
 | cross-axis | `boolean` | `false` | Allows overflow checks on the cross axis when flipping. |
+| defaultAriaLabel (JS only) | `defaultAriaLabel() => void` | `-` | - |
 | distance | `number` | `8` | Distance offset between trigger and attention panel. |
 | fallback-placements | `Directions[]` | `[]` | Ordered list of fallback placements. |
 | flip | `boolean` | `false` | Enables automatic flipping when placement has no space. |
+| handleDone (JS only) | `handleDone() => void` | `-` | - |
 | highlight | `boolean` | `false` | Renders the component with highlight styling. |
+| keypressed (JS only) | `keypressed(e: KeyboardEvent) => void` | `-` | - |
 | no-arrow | `boolean` | `false` | Hides the directional arrow of the attention component. |
-| placement | [`Directions`](#directions) | `'bottom'` | Preferred placement relative to the trigger element. |
+| placement | [`Directions`](#directions) | `"bottom"` | Preferred placement relative to the trigger element. |
+| pointingAtDirection (JS only) | `pointingAtDirection() => void` | `-` | - |
 | popover | `boolean` | `false` | Enables native popover behavior for the attention element. |
 | show | `boolean` | `false` | Controls whether the attention panel is visible. |
 | skidding | `number` | `0` | Cross-axis offset for fine-grained positioning. |
@@ -38,6 +44,13 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 - Type: `unknown`
 - Default: `-`
 
+#### activeAttentionType (JS only)
+
+
+
+- Type: `activeAttentionType() => void`
+- Default: `-`
+
 #### callout
 
 Renders the component as an inline callout.
@@ -54,6 +67,13 @@ Adds an internal dismiss action that lets users close the attention panel.
 - Type: `boolean`
 - Default: `false`
 
+#### close (JS only)
+
+
+
+- Type: `close() => void`
+- Default: `-`
+
 #### cross-axis
 
 Allows overflow checks on the cross axis when flipping.
@@ -62,6 +82,13 @@ Use with `flip` to improve collision handling when space is constrained horizont
 - Type: `boolean`
 - Default: `false`
 
+#### defaultAriaLabel (JS only)
+
+
+
+- Type: `defaultAriaLabel() => void`
+- Default: `-`
+
 #### distance
 
 Distance offset between trigger and attention panel.
@@ -86,6 +113,13 @@ Allows the component to choose an alternative side if the preferred placement wo
 - Type: `boolean`
 - Default: `false`
 
+#### handleDone (JS only)
+
+
+
+- Type: `handleDone() => void`
+- Default: `-`
+
 #### highlight
 
 Renders the component with highlight styling.
@@ -94,6 +128,13 @@ Use highlight mode to visually emphasize important contextual information.
 - Type: `boolean`
 - Default: `false`
 
+#### keypressed (JS only)
+
+
+
+- Type: `keypressed(e: KeyboardEvent) => void`
+- Default: `-`
+
 #### no-arrow
 
 Hides the directional arrow of the attention component.
@@ -108,7 +149,14 @@ Preferred placement relative to the trigger element.
 Sets the initial direction for positioning, for example `top`, `right`, `bottom`, or `left` variants.
 
 - Type: [`Directions`](#directions)
-- Default: `'bottom'`
+- Default: `"bottom"`
+
+#### pointingAtDirection (JS only)
+
+
+
+- Type: `pointingAtDirection() => void`
+- Default: `-`
 
 #### popover
 

package/dist/docs/attention/attention.md

@@ -246,6 +246,8 @@ When `can-close` is used, ensure your app listens to the `close` event and updat
 
 </elements-example>
 
+## Styling API
+
 ## `<w-attention>` API
 
 Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).
@@ -256,15 +258,21 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 |-|-|-|-|
 | _actualDirection (JS only) | `unknown` | `-` | - |
 | _initialPlacement (JS only) | `unknown` | `-` | - |
+| activeAttentionType (JS only) | `activeAttentionType() => void` | `-` | - |
 | callout | `boolean` | `false` | Renders the component as an inline callout. |
 | can-close | `boolean` | `false` | Shows a close button inside the attention component. |
+| close (JS only) | `close() => void` | `-` | - |
 | cross-axis | `boolean` | `false` | Allows overflow checks on the cross axis when flipping. |
+| defaultAriaLabel (JS only) | `defaultAriaLabel() => void` | `-` | - |
 | distance | `number` | `8` | Distance offset between trigger and attention panel. |
 | fallback-placements | `Directions[]` | `[]` | Ordered list of fallback placements. |
 | flip | `boolean` | `false` | Enables automatic flipping when placement has no space. |
+| handleDone (JS only) | `handleDone() => void` | `-` | - |
 | highlight | `boolean` | `false` | Renders the component with highlight styling. |
+| keypressed (JS only) | `keypressed(e: KeyboardEvent) => void` | `-` | - |
 | no-arrow | `boolean` | `false` | Hides the directional arrow of the attention component. |
-| placement | [`Directions`](#directions) | `'bottom'` | Preferred placement relative to the trigger element. |
+| placement | [`Directions`](#directions) | `"bottom"` | Preferred placement relative to the trigger element. |
+| pointingAtDirection (JS only) | `pointingAtDirection() => void` | `-` | - |
 | popover | `boolean` | `false` | Enables native popover behavior for the attention element. |
 | show | `boolean` | `false` | Controls whether the attention panel is visible. |
 | skidding | `number` | `0` | Cross-axis offset for fine-grained positioning. |
@@ -286,6 +294,13 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 - Type: `unknown`
 - Default: `-`
 
+#### activeAttentionType (JS only)
+
+
+
+- Type: `activeAttentionType() => void`
+- Default: `-`
+
 #### callout
 
 Renders the component as an inline callout.
@@ -302,6 +317,13 @@ Adds an internal dismiss action that lets users close the attention panel.
 - Type: `boolean`
 - Default: `false`
 
+#### close (JS only)
+
+
+
+- Type: `close() => void`
+- Default: `-`
+
 #### cross-axis
 
 Allows overflow checks on the cross axis when flipping.
@@ -310,6 +332,13 @@ Use with `flip` to improve collision handling when space is constrained horizont
 - Type: `boolean`
 - Default: `false`
 
+#### defaultAriaLabel (JS only)
+
+
+
+- Type: `defaultAriaLabel() => void`
+- Default: `-`
+
 #### distance
 
 Distance offset between trigger and attention panel.
@@ -334,6 +363,13 @@ Allows the component to choose an alternative side if the preferred placement wo
 - Type: `boolean`
 - Default: `false`
 
+#### handleDone (JS only)
+
+
+
+- Type: `handleDone() => void`
+- Default: `-`
+
 #### highlight
 
 Renders the component with highlight styling.
@@ -342,6 +378,13 @@ Use highlight mode to visually emphasize important contextual information.
 - Type: `boolean`
 - Default: `false`
 
+#### keypressed (JS only)
+
+
+
+- Type: `keypressed(e: KeyboardEvent) => void`
+- Default: `-`
+
 #### no-arrow
 
 Hides the directional arrow of the attention component.
@@ -356,7 +399,14 @@ Preferred placement relative to the trigger element.
 Sets the initial direction for positioning, for example `top`, `right`, `bottom`, or `left` variants.
 
 - Type: [`Directions`](#directions)
-- Default: `'bottom'`
+- Default: `"bottom"`
+
+#### pointingAtDirection (JS only)
+
+
+
+- Type: `pointingAtDirection() => void`
+- Default: `-`
 
 #### popover
 

package/dist/docs/attention/styling.md

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

package/dist/docs/badge/api.md

@@ -6,8 +6,20 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 | Name | Type | Default | Summary |
 |-|-|-|-|
-| position | `'top-left' \| 'top-right' \| 'bottom-right' \| 'bottom-left'` | `-` | Positions the badge in a corner of a parent element. |
-| variant | `'neutral' \| 'info' \| 'positive' \| 'warning' \| 'negative' \| 'disabled' \| 'price' \| 'sponsored'` | `-` | Controls the badge color treatment. |
+| position | [`\| "top-left"
+		\| "top-right"
+		\| "bottom-right"
+		\| "bottom-left"
+		\| undefined`](#top-left-top-right-bottom-right-bottom-left-undefined) | `-` | Positions the badge in a corner of a parent element. |
+| variant | [`\| "neutral"
+		\| "info"
+		\| "positive"
+		\| "warning"
+		\| "negative"
+		\| "disabled"
+		\| "price"
+		\| "sponsored"
+		\| undefined`](#neutral-info-positive-warning-negative-disabled-price-sponsored-undefined) | `-` | Controls the badge color treatment. |
 
 ### Property Details
 
@@ -17,7 +29,11 @@ Positions the badge in a corner of a parent element.
 Use this with a parent element that has `position: relative`. When set, the badge uses absolute positioning and adjusts its corner radii so it sits flush against the selected corner.
 Use this with a parent element that has `position: relative`. Accepted values are `top-left`, `top-right`, `bottom-right`, and `bottom-left`.
 
-- Type: `'top-left' | 'top-right' | 'bottom-right' | 'bottom-left'`
+- Type: [`| "top-left"
+		| "top-right"
+		| "bottom-right"
+		| "bottom-left"
+		| undefined`](#top-left-top-right-bottom-right-bottom-left-undefined)
 - Default: `-`
 
 #### variant
@@ -26,6 +42,36 @@ Controls the badge color treatment.
 If omitted, the badge uses neutral styling without reflecting a `variant` attribute.
 Accepted values are `neutral`, `info`, `positive`, `warning`, `negative`, `disabled`, `price`, and `sponsored`. If omitted, the badge uses neutral styling without reflecting a `variant` attribute.
 
-- Type: `'neutral' | 'info' | 'positive' | 'warning' | 'negative' | 'disabled' | 'price' | 'sponsored'`
+- Type: [`| "neutral"
+		| "info"
+		| "positive"
+		| "warning"
+		| "negative"
+		| "disabled"
+		| "price"
+		| "sponsored"
+		| undefined`](#neutral-info-positive-warning-negative-disabled-price-sponsored-undefined)
 - Default: `-`
 
+### Types
+
+#### | "neutral"
+		| "info"
+		| "positive"
+		| "warning"
+		| "negative"
+		| "disabled"
+		| "price"
+		| "sponsored"
+		| undefined
+
+`'neutral' | 'info' | 'positive' | 'warning' | 'negative' | 'disabled' | 'price' | 'sponsored' | undefined`
+
+#### | "top-left"
+		| "top-right"
+		| "bottom-right"
+		| "bottom-left"
+		| undefined
+
+`'top-left' | 'top-right' | 'bottom-right' | 'bottom-left' | undefined`
+