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

package/dist/docs/alert/examples.md

@@ -2,74 +2,64 @@
 
 ### Basic
 
-<style-isolate>
-  <w-alert show>
-    <p>We have updated your preferences.</p>
-  </w-alert>
-</style-isolate>
-
+<elements-example>
+  
 ```html
 <w-alert show>
   <p>We have updated your preferences.</p>
 </w-alert>
 ```
 
-### Info
+</elements-example>
 
-<style-isolate>
-  <w-alert variant="info" show>
-    <p>This is an informational alert.</p>
-  </w-alert>
-</style-isolate>
+### Info
 
+<elements-example>
+  
 ```html
 <w-alert variant="info" show>
   <p>This is an informational alert.</p>
 </w-alert>
 ```
 
-### Warning
+</elements-example>
 
-<style-isolate>
-  <w-alert variant="warning" show>
-    <p>Please double-check this value before continuing.</p>
-  </w-alert>
-</style-isolate>
+### Warning
 
+<elements-example>
+  
 ```html
 <w-alert variant="warning" show>
   <p>Please double-check this value before continuing.</p>
 </w-alert>
 ```
 
-### Negative
+</elements-example>
 
-<style-isolate>
-  <w-alert variant="negative" show>
-    <p>Something went wrong. Try again.</p>
-  </w-alert>
-</style-isolate>
+### Negative
 
+<elements-example>
+  
 ```html
 <w-alert variant="negative" show>
   <p>Something went wrong. Try again.</p>
 </w-alert>
 ```
 
-### Positive
+</elements-example>
 
-<style-isolate>
-  <w-alert variant="positive" show>
-    <p>Your changes were saved successfully.</p>
-  </w-alert>
-</style-isolate>
+### Positive
 
+<elements-example>
+  
 ```html
 <w-alert variant="positive" show>
   <p>Your changes were saved successfully.</p>
 </w-alert>
 ```
 
+</elements-example>
+
 ### Programmatic Visibility
 
 ```html

package/dist/docs/attention/accessibility.md

@@ -1 +1,51 @@
 ## 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>
+```

package/dist/docs/attention/api.md

@@ -4,128 +4,141 @@
 
 | 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` | `-` | - |
+| _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
 
-#### show
-
+#### _actualDirection
 
 
-- Type: `boolean`
-- Default: `false`
 
-#### placement
+- Type: `unknown`
+- Default: `-`
 
+#### _initialPlacement
 
 
-- Type: `Directions`
-- Default: `'bottom'`
 
-#### tooltip
+- 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`
 
-#### callout
-
+#### 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`
 
-#### popover
-
+#### 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`
 
-#### highlight
+#### distance
 
+Distance offset between trigger and attention panel.
+Defines the main-axis spacing in pixels from the anchor element.
 
+- Type: `number`
+- Default: `8`
 
-- Type: `boolean`
-- Default: `false`
+#### fallbackPlacements
 
-#### canClose
+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: `[]`
 
+#### 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`
 
-#### noArrow
-
+#### highlight
 
+Renders the component with highlight styling.
+Use highlight mode to visually emphasize important contextual information.
 
 - Type: `boolean`
 - Default: `false`
 
-#### distance
-
-
-
-- Type: `number`
-- Default: `8`
+#### noArrow
 
-#### skidding
+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
 
-- Type: `number`
-- Default: `0`
+Preferred placement relative to the trigger element.
+Sets the initial direction for positioning, for example `top`, `right`, `bottom`, or `left` variants.
 
-#### flip
+- 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`
 
-#### crossAxis
-
+#### 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`
 
-#### fallbackPlacements
-
-
-
-- Type: `Directions[]`
-- Default: `-`
-
-#### _initialPlacement
-
+#### 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: `-`
-
-#### _actualDirection
+- 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: `unknown`
-- Default: `-`
+- Type: `boolean`
+- Default: `false`
 
 ### Types