@warp-ds/elements 2.9.0-next.6 → 2.9.1-next.1

package/dist/docs/attention/attention.md

@@ -2,14 +2,250 @@
 
 ## 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
 
+`w-attention` provides built-in accessibility helpers for tooltip/popover/callout messaging:
+
+- 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.
+
+### Authoring Guidance
+
+- 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.
+
+### Reading Order and Placement
+
+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`.
+
+```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>
+```
+
+### 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>
+
+<script>
+  const attention = document.getElementById('dismissible');
+  attention.addEventListener('close', () => {
+    attention.show = false;
+  });
+</script>
+```
+
 ## 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
 
 ### Properties
@@ -18,19 +254,19 @@
 |-|-|-|-|
 | _actualDirection | `unknown` | `-` | - |
 | _initialPlacement | `unknown` | `-` | - |
-| callout | `boolean` | `false` | - |
-| canClose | `boolean` | `false` | - |
-| crossAxis | `boolean` | `false` | - |
-| distance | `number` | `8` | - |
-| fallbackPlacements | `Directions[]` | `-` | - |
-| flip | `boolean` | `false` | - |
-| highlight | `boolean` | `false` | - |
-| noArrow | `boolean` | `false` | - |
-| placement | `Directions` | `'bottom'` | - |
-| popover | `boolean` | `false` | - |
-| show | `boolean` | `false` | - |
-| skidding | `number` | `0` | - |
-| tooltip | `boolean` | `false` | - |
+| 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
 
@@ -50,91 +286,104 @@
 
 #### 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`
 
 #### 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`
 
 #### fallbackPlacements
 
-
+Ordered list of fallback placements.
+Provides explicit alternative placements to try when `flip` is enabled and the preferred placement does not fit.
 
 - Type: `Directions[]`
-- Default: `-`
+- 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`
 
 #### 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`
 
 #### 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'`
 
 #### popover
 
-
+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
 
-
+Controls whether the attention panel is visible.
+Set to `true` to show the attention content and `false` to hide it.
 
 - 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: `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`

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/badge.md

@@ -109,26 +109,17 @@ If the same information is already available in nearby accessible text and the b
 
 ### Basic
 
-<style-isolate>
-  <w-badge>New</w-badge>
-</style-isolate>
-
+<elements-example>
+  
 ```html
 <w-badge>New</w-badge>
 ```
 
+</elements-example>
+
 ### Status Variants
 
-<style-isolate>
-  <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: center;">
-    <w-badge variant="neutral">Neutral</w-badge>
-    <w-badge variant="info">Info</w-badge>
-    <w-badge variant="positive">Approved</w-badge>
-    <w-badge variant="warning">Pending</w-badge>
-    <w-badge variant="negative">Rejected</w-badge>
-    <w-badge variant="disabled">Unavailable</w-badge>
-  </div>
-</style-isolate>
+<elements-example>
 
 ```html
 <w-badge variant="neutral">Neutral</w-badge>
@@ -139,56 +130,52 @@ If the same information is already available in nearby accessible text and the b
 <w-badge variant="disabled">Unavailable</w-badge>
 ```
 
-### Price
+</elements-example>
 
-<style-isolate>
-  <w-badge variant="price">1 200 kr</w-badge>
-</style-isolate>
+### Price
 
+<elements-example>
+  
 ```html
 <w-badge variant="price">1 200 kr</w-badge>
 ```
 
-### Sponsored
+</elements-example>
 
-<style-isolate>
-  <w-badge variant="sponsored">Sponsored</w-badge>
-</style-isolate>
+### Sponsored
 
+<elements-example>
+  
 ```html
 <w-badge variant="sponsored">Sponsored</w-badge>
 ```
 
+</elements-example>
+
 ### Positioned
 
-<style-isolate>
-  <div style="position: relative; width: 220px; height: 124px; border-radius: 8px; overflow: hidden; background: #e5e7eb;">
-    <w-badge variant="price" position="top-right">1 200 kr</w-badge>
-  </div>
-</style-isolate>
+<elements-example>
 
 ```html
-<div style="position: relative;">
-  <img src="listing.jpg" alt="Living room with large windows" />
+<div style="position: relative; width: 220px; height: 124px; border-radius: 8px; overflow: hidden; background: #e5e7eb;">
   <w-badge variant="price" position="top-right">1 200 kr</w-badge>
 </div>
 ```
 
+</elements-example>
+
 ### Positioned Sponsored Badge
 
-<style-isolate>
-  <div style="position: relative; width: 220px; height: 124px; border-radius: 8px; overflow: hidden; background: #e5e7eb;">
-    <w-badge variant="sponsored" position="bottom-left">Sponsored</w-badge>
-  </div>
-</style-isolate>
+<elements-example>
 
 ```html
-<div style="position: relative;">
-  <img src="listing.jpg" alt="Living room with large windows" />
+<div style="position: relative; width: 220px; height: 124px; border-radius: 8px; overflow: hidden; background: #e5e7eb;">
   <w-badge variant="sponsored" position="bottom-left">Sponsored</w-badge>
 </div>
 ```
 
+</elements-example>
+
 ## API Documentation
 
 ### Properties