@warp-ds/elements 2.9.0-next.5 → 2.9.0

package/dist/docs/attention/attention.md

@@ -2,142 +2,391 @@
 
 ## Description
 
+Attention is a versatile component for displaying contextual information and messages. It can be used for a wide range of purposes, such as tooltips, callouts, popovers, and highlights.
 
+The component is designed to be anchored to a trigger element, providing contextual information related to that element. It supports various placements and styling options to accommodate different use cases and design needs.
+
+Note: attention will soon be split into multiple components (tooltip, callout, popover, highlight) at which time this component will be deprecated. For now, use the `tooltip`, `callout`, `popover`, and `highlight` boolean properties to achieve the desired style and behavior.
 
 ## Usage
 
+`w-attention` is used to show contextual messaging anchored to a target element.
+
+### Basic Structure
+
+Use the `target` slot for the trigger/anchor element and the `message` slot for the content.
+
+```html
+<w-attention placement="bottom" popover>
+  <w-button slot="target" variant="secondary">Open message</w-button>
+  <span slot="message">I'm a popover</span>
+</w-attention>
+```
+
+### Visibility (`show`)
+
+`w-attention` visibility is controlled with the `show` property. Toggle it based on user interaction.
+
+```html
+<w-attention id="my-attention" placement="bottom" popover>
+  <w-button id="my-trigger" slot="target" variant="secondary">Toggle</w-button>
+  <span slot="message">I'm a popover</span>
+</w-attention>
+
+<script>
+  const trigger = document.getElementById('my-trigger');
+  const attention = document.getElementById('my-attention');
+  trigger.addEventListener('click', () => {
+    attention.show = !attention.show;
+  });
+</script>
+```
+
+### Variants
+
+`w-attention` supports four visual variants:
+
+- `tooltip`
+- `popover`
+- `callout`
+- `highlight`
+
+Use one variant at a time.
+
+```html
+<w-attention tooltip placement="right">
+  <w-button slot="target" variant="secondary">Hover me</w-button>
+  <span slot="message">Short helper text</span>
+</w-attention>
+```
+
+### Placement and Collision Handling
+
+Use `placement` to define preferred direction. For overlays, `flip`, `cross-axis`, and `fallback-placements` can improve placement in constrained layouts.
+
+```html
+<w-attention
+  popover
+  placement="right"
+  flip
+  cross-axis
+  fallback-placements='["bottom","left","top"]'
+>
+  <w-button slot="target" variant="secondary">Open</w-button>
+  <span slot="message">Smartly positioned message</span>
+</w-attention>
+```
+
+### Dismissible Messages
+
+Use `can-close` for an internal close button, and listen for the `close` event.
+
+```html
+<w-attention id="dismissible-attention" highlight can-close placement="right">
+  <w-button id="dismissible-trigger" slot="target" variant="secondary">Show message</w-button>
+  <span slot="message">You can dismiss this message.</span>
+</w-attention>
+
+<script>
+  const trigger = document.getElementById('dismissible-trigger');
+  const attention = document.getElementById('dismissible-attention');
+
+  trigger.addEventListener('click', () => {
+    attention.show = true;
+  });
+
+  attention.addEventListener('close', () => {
+    attention.show = false;
+  });
+</script>
+```
+
 ## Accessibility
 
-## Examples
+`w-attention` provides built-in accessibility helpers for tooltip/popover/callout messaging:
 
-## API Documentation
+- It sets `role="tooltip"` for tooltip mode.
+- It sets `role="img"` for non-tooltip variants.
+- It provides a default localized `aria-label` describing the attention type and arrow direction.
 
-### Properties
+### Authoring Guidance
 
-| Name | Type | Default | Summary |
-|-|-|-|-|
-| show | `boolean` | `false` | - |
-| placement | `Directions` | `'bottom'` | - |
-| tooltip | `boolean` | `false` | - |
-| callout | `boolean` | `false` | - |
-| popover | `boolean` | `false` | - |
-| highlight | `boolean` | `false` | - |
-| canClose | `boolean` | `false` | - |
-| noArrow | `boolean` | `false` | - |
-| distance | `number` | `8` | - |
-| skidding | `number` | `0` | - |
-| flip | `boolean` | `false` | - |
-| crossAxis | `boolean` | `false` | - |
-| fallbackPlacements | `Directions[]` | `-` | - |
-| _initialPlacement | `unknown` | `-` | - |
-| _actualDirection | `unknown` | `-` | - |
+- Provide meaningful text in the `message` slot.
+- Ensure the `target` slot content is keyboard-accessible (for example `w-button` or a native button).
+- For hover-triggered tooltips, also support focus/blur so keyboard users receive the same information.
 
-### Property Details
+### Reading Order and Placement
 
-#### show
+For left/top placements, placing the attention message before the target in DOM order can improve screen reader flow.
 
+### Precise ARIA Targeting
 
+If only part of the message should be announced as details, set an explicit id on the relevant message content and reference it from the target with `aria-details`.
 
-- Type: `boolean`
-- Default: `false`
+```html
+<w-attention id="accessible-attention" placement="right" popover>
+  <div slot="message">
+    <p id="aria-content" role="tooltip">Important contextual text</p>
+    <p>Secondary text</p>
+  </div>
+  <w-button aria-details="aria-content" slot="target" variant="secondary">
+    Open
+  </w-button>
+</w-attention>
+```
 
-#### placement
+### Dismissible Attention
 
+When `can-close` is used, ensure your app listens to the `close` event and updates `show` accordingly so the UI and assistive technology state stay in sync.
 
+```html
+<w-attention id="dismissible" can-close highlight>
+  <w-button slot="target" variant="secondary">Show message</w-button>
+  <span slot="message">Dismissible message</span>
+</w-attention>
 
-- Type: `Directions`
-- Default: `'bottom'`
+<script>
+  const attention = document.getElementById('dismissible');
+  attention.addEventListener('close', () => {
+    attention.show = false;
+  });
+</script>
+```
 
-#### tooltip
+## Examples
 
+### Popover (Click To Toggle)
+
+<elements-example>
+
+```html
+<w-attention id="example-popover" placement="bottom" popover flip>
+  <w-button id="example-popover-trigger" slot="target" variant="secondary">Click to toggle a popover</w-button>
+  <span slot="message">I'm a popover</span>
+</w-attention>
+<script>
+  (() => {
+    const trigger = document.getElementById('example-popover-trigger');
+    const attention = document.getElementById('example-popover');
+    trigger.addEventListener('click', () => {
+      attention.show = !attention.show;
+    });
+  })();
+</script>
+```
+
+</elements-example>
+
+### Tooltip (Hover and Focus)
+
+<elements-example>
+
+```html
+<w-attention id="example-tooltip" placement="right" tooltip flip>
+  <w-button id="example-tooltip-trigger" slot="target" variant="secondary">Hover or focus me</w-button>
+  <span slot="message">I'm a tooltip</span>
+</w-attention>
+<script>
+  (() => {
+    const trigger = document.getElementById('example-tooltip-trigger');
+    const attention = document.getElementById('example-tooltip');
+    trigger.addEventListener('mouseenter', () => {
+      attention.show = true;
+    });
+    trigger.addEventListener('mouseleave', () => {
+      attention.show = false;
+    });
+    trigger.addEventListener('focus', () => {
+      attention.show = true;
+    });
+    trigger.addEventListener('blur', () => {
+      attention.show = false;
+    });
+  })();
+</script>
+```
+
+</elements-example>
+
+### Inline Callout
+
+<elements-example>
+  
+```html
+<w-attention callout show placement="right">
+  <w-button slot="target" variant="secondary">Inline target</w-button>
+  <span slot="message">I'm an inline callout</span>
+</w-attention>
+```
+
+</elements-example>
+
+### Dismissible Highlight
+
+<elements-example>
+
+```html
+<w-attention id="example-highlight" highlight can-close placement="right" flip>
+  <w-button id="example-highlight-trigger" slot="target" variant="secondary">Click me</w-button>
+  <span slot="message">I'm highlighted and dismissible</span>
+</w-attention>
+<script>
+  (() => {
+    const trigger = document.getElementById('example-highlight-trigger');
+    const attention = document.getElementById('example-highlight');
+    trigger.addEventListener('click', () => {
+      attention.show = true;
+    });
+    attention.addEventListener('close', () => {
+      attention.show = false;
+    });
+  })();
+</script>
+```
+
+</elements-example>
 
+## API Documentation
 
-- Type: `boolean`
-- Default: `false`
+### Properties
 
-#### callout
+| Name | Type | Default | Summary |
+|-|-|-|-|
+| _actualDirection | `unknown` | `-` | - |
+| _initialPlacement | `unknown` | `-` | - |
+| callout | `boolean` | `false` | Renders the component as an inline callout. |
+| canClose | `boolean` | `false` | Shows a close button inside the attention component. |
+| crossAxis | `boolean` | `false` | Allows overflow checks on the cross axis when flipping. |
+| distance | `number` | `8` | Distance offset between trigger and attention panel. |
+| fallbackPlacements | `Directions[]` | `[]` | Ordered list of fallback placements. |
+| flip | `boolean` | `false` | Enables automatic flipping when placement has no space. |
+| highlight | `boolean` | `false` | Renders the component with highlight styling. |
+| noArrow | `boolean` | `false` | Hides the directional arrow of the attention component. |
+| placement | `Directions` | `'bottom'` | Preferred placement relative to the trigger element. |
+| 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. |
+| tooltip | `boolean` | `false` | Renders the component with tooltip styling and behavior. |
 
+### Property Details
 
+#### _actualDirection
 
-- Type: `boolean`
-- Default: `false`
 
-#### popover
 
+- Type: `unknown`
+- Default: `-`
 
+#### _initialPlacement
 
-- Type: `boolean`
-- Default: `false`
 
-#### highlight
 
+- Type: `unknown`
+- Default: `-`
+
+#### callout
 
+Renders the component as an inline callout.
+Callout mode is used for always-in-flow informational content instead of floating overlay behavior.
 
 - Type: `boolean`
 - Default: `false`
 
 #### canClose
 
-
+Shows a close button inside the attention component.
+Adds an internal dismiss action that lets users close the attention panel.
 
 - Type: `boolean`
 - Default: `false`
 
-#### noArrow
-
+#### crossAxis
 
+Allows overflow checks on the cross axis when flipping.
+Use with `flip` to improve collision handling when space is constrained horizontally or vertically.
 
 - Type: `boolean`
 - Default: `false`
 
 #### distance
 
-
+Distance offset between trigger and attention panel.
+Defines the main-axis spacing in pixels from the anchor element.
 
 - Type: `number`
 - Default: `8`
 
-#### skidding
-
+#### fallbackPlacements
 
+Ordered list of fallback placements.
+Provides explicit alternative placements to try when `flip` is enabled and the preferred placement does not fit.
 
-- Type: `number`
-- Default: `0`
+- Type: `Directions[]`
+- Default: `[]`
 
 #### flip
 
-
+Enables automatic flipping when placement has no space.
+Allows the component to choose an alternative side if the preferred placement would overflow.
 
 - Type: `boolean`
 - Default: `false`
 
-#### crossAxis
+#### highlight
+
+Renders the component with highlight styling.
+Use highlight mode to visually emphasize important contextual information.
+
+- Type: `boolean`
+- Default: `false`
 
+#### noArrow
 
+Hides the directional arrow of the attention component.
+Disable the arrow when the visual connection to the trigger should not be shown.
 
 - Type: `boolean`
 - Default: `false`
 
-#### fallbackPlacements
+#### placement
 
+Preferred placement relative to the trigger element.
+Sets the initial direction for positioning, for example `top`, `right`, `bottom`, or `left` variants.
 
+- Type: `Directions`
+- Default: `'bottom'`
 
-- Type: `Directions[]`
-- Default: `-`
+#### popover
 
-#### _initialPlacement
+Enables native popover behavior for the attention element.
+When enabled, the component uses popover semantics and styling suitable for floating surface UI.
 
+- Type: `boolean`
+- Default: `false`
 
+#### show
 
-- Type: `unknown`
-- Default: `-`
+Controls whether the attention panel is visible.
+Set to `true` to show the attention content and `false` to hide it.
 
-#### _actualDirection
+- Type: `boolean`
+- Default: `false`
 
+#### skidding
 
+Cross-axis offset for fine-grained positioning.
+Moves the panel along the cross axis in pixels to adjust alignment with the trigger.
 
-- Type: `unknown`
-- Default: `-`
+- Type: `number`
+- Default: `0`
+
+#### tooltip
+
+Renders the component with tooltip styling and behavior.
+Use for compact, non-modal contextual hints anchored to another element.
+
+- Type: `boolean`
+- Default: `false`
 
 ### Types
 

package/dist/docs/attention/examples.md

@@ -1 +1,92 @@
 ## Examples
+
+### Popover (Click To Toggle)
+
+<elements-example>
+
+```html
+<w-attention id="example-popover" placement="bottom" popover flip>
+  <w-button id="example-popover-trigger" slot="target" variant="secondary">Click to toggle a popover</w-button>
+  <span slot="message">I'm a popover</span>
+</w-attention>
+<script>
+  (() => {
+    const trigger = document.getElementById('example-popover-trigger');
+    const attention = document.getElementById('example-popover');
+    trigger.addEventListener('click', () => {
+      attention.show = !attention.show;
+    });
+  })();
+</script>
+```
+
+</elements-example>
+
+### Tooltip (Hover and Focus)
+
+<elements-example>
+
+```html
+<w-attention id="example-tooltip" placement="right" tooltip flip>
+  <w-button id="example-tooltip-trigger" slot="target" variant="secondary">Hover or focus me</w-button>
+  <span slot="message">I'm a tooltip</span>
+</w-attention>
+<script>
+  (() => {
+    const trigger = document.getElementById('example-tooltip-trigger');
+    const attention = document.getElementById('example-tooltip');
+    trigger.addEventListener('mouseenter', () => {
+      attention.show = true;
+    });
+    trigger.addEventListener('mouseleave', () => {
+      attention.show = false;
+    });
+    trigger.addEventListener('focus', () => {
+      attention.show = true;
+    });
+    trigger.addEventListener('blur', () => {
+      attention.show = false;
+    });
+  })();
+</script>
+```
+
+</elements-example>
+
+### Inline Callout
+
+<elements-example>
+  
+```html
+<w-attention callout show placement="right">
+  <w-button slot="target" variant="secondary">Inline target</w-button>
+  <span slot="message">I'm an inline callout</span>
+</w-attention>
+```
+
+</elements-example>
+
+### Dismissible Highlight
+
+<elements-example>
+
+```html
+<w-attention id="example-highlight" highlight can-close placement="right" flip>
+  <w-button id="example-highlight-trigger" slot="target" variant="secondary">Click me</w-button>
+  <span slot="message">I'm highlighted and dismissible</span>
+</w-attention>
+<script>
+  (() => {
+    const trigger = document.getElementById('example-highlight-trigger');
+    const attention = document.getElementById('example-highlight');
+    trigger.addEventListener('click', () => {
+      attention.show = true;
+    });
+    attention.addEventListener('close', () => {
+      attention.show = false;
+    });
+  })();
+</script>
+```
+
+</elements-example>

package/dist/docs/attention/usage.md

@@ -1 +1,92 @@
 ## Usage
+
+`w-attention` is used to show contextual messaging anchored to a target element.
+
+### Basic Structure
+
+Use the `target` slot for the trigger/anchor element and the `message` slot for the content.
+
+```html
+<w-attention placement="bottom" popover>
+  <w-button slot="target" variant="secondary">Open message</w-button>
+  <span slot="message">I'm a popover</span>
+</w-attention>
+```
+
+### Visibility (`show`)
+
+`w-attention` visibility is controlled with the `show` property. Toggle it based on user interaction.
+
+```html
+<w-attention id="my-attention" placement="bottom" popover>
+  <w-button id="my-trigger" slot="target" variant="secondary">Toggle</w-button>
+  <span slot="message">I'm a popover</span>
+</w-attention>
+
+<script>
+  const trigger = document.getElementById('my-trigger');
+  const attention = document.getElementById('my-attention');
+  trigger.addEventListener('click', () => {
+    attention.show = !attention.show;
+  });
+</script>
+```
+
+### Variants
+
+`w-attention` supports four visual variants:
+
+- `tooltip`
+- `popover`
+- `callout`
+- `highlight`
+
+Use one variant at a time.
+
+```html
+<w-attention tooltip placement="right">
+  <w-button slot="target" variant="secondary">Hover me</w-button>
+  <span slot="message">Short helper text</span>
+</w-attention>
+```
+
+### Placement and Collision Handling
+
+Use `placement` to define preferred direction. For overlays, `flip`, `cross-axis`, and `fallback-placements` can improve placement in constrained layouts.
+
+```html
+<w-attention
+  popover
+  placement="right"
+  flip
+  cross-axis
+  fallback-placements='["bottom","left","top"]'
+>
+  <w-button slot="target" variant="secondary">Open</w-button>
+  <span slot="message">Smartly positioned message</span>
+</w-attention>
+```
+
+### Dismissible Messages
+
+Use `can-close` for an internal close button, and listen for the `close` event.
+
+```html
+<w-attention id="dismissible-attention" highlight can-close placement="right">
+  <w-button id="dismissible-trigger" slot="target" variant="secondary">Show message</w-button>
+  <span slot="message">You can dismiss this message.</span>
+</w-attention>
+
+<script>
+  const trigger = document.getElementById('dismissible-trigger');
+  const attention = document.getElementById('dismissible-attention');
+
+  trigger.addEventListener('click', () => {
+    attention.show = true;
+  });
+
+  attention.addEventListener('close', () => {
+    attention.show = false;
+  });
+</script>
+```

package/dist/docs/badge/accessibility.md

@@ -1 +1,45 @@
 ## Accessibility
+
+Badge renders slotted text as regular content. It does not add an ARIA role and it is not announced as a live region.
+
+### Use Meaningful Text
+
+Do not rely on color alone to communicate meaning. The badge text should describe the status or metadata by itself.
+
+```html
+<w-badge variant="positive">Approved</w-badge>
+<w-badge variant="negative">Rejected</w-badge>
+```
+
+Avoid labels that only make sense visually:
+
+```html
+<!-- Avoid -->
+<w-badge variant="positive">Green</w-badge>
+```
+
+### Keep Badges Non-Interactive
+
+Do not place interactive elements inside `w-badge`. If the user can click, dismiss, filter, or select the item, use an interactive component instead.
+
+The `disabled` variant is visual only. It does not disable related controls or remove anything from the tab order.
+
+```html
+<!-- Avoid -->
+<w-badge>
+  <button type="button">New</button>
+</w-badge>
+```
+
+### Dynamic Changes
+
+If a badge value changes after the page has loaded and users need to be notified, announce that change outside the badge with an appropriate live region or use [Alert](/docs/components/alert/overview) for important feedback.
+
+### Duplicate or Decorative Badges
+
+If the same information is already available in nearby accessible text and the badge is only a visual duplicate, hide the duplicate badge from assistive technologies.
+
+```html
+<p>Sponsored listing</p>
+<w-badge aria-hidden="true" variant="sponsored">Sponsored</w-badge>
+```