@reliability-design/web 1.4.6 → 1.4.8

package/dist/components/rel-toast/README.md

@@ -1,148 +1,165 @@
-# rel-toast
-
-## Overview
-A fixed-position toast notification component for brief feedback messages. Features default and error type variants, optional action buttons, auto-dismiss functionality, and slide-up animation. Positioned at the bottom-center of the viewport with `z-index: 1000`.
-
-## Usage
-```html
-<!-- Basic toast (must be shown programmatically) -->
-<rel-toast id="toast1" message="File saved successfully" type="default"></rel-toast>
-<script>
-  const toast = document.getElementById('toast1');
-  toast.show(); // Show the toast
-</script>
-
-<!-- Error toast -->
-<rel-toast id="errorToast" message="Failed to upload file" type="error"></rel-toast>
-<script>
-  document.getElementById('errorToast').show();
-</script>
-
-<!-- With action button -->
-<rel-toast
-  id="actionToast"
-  message="Connection lost"
-  actionLabel="RETRY"
-  type="default">
-</rel-toast>
-<script>
-  const actionToast = document.getElementById('actionToast');
-  actionToast.addEventListener('action', () => {
-    console.log('Retry clicked');
-    // Perform retry logic
-  });
-  actionToast.show();
-</script>
-
-<!-- Custom duration (7 seconds) -->
-<rel-toast
-  id="customDuration"
-  message="Download complete"
-  duration="7000">
-</rel-toast>
-<script>
-  document.getElementById('customDuration').show();
-</script>
-
-<!-- No auto-dismiss -->
-<rel-toast
-  id="persist"
-  message="Manual dismiss required"
-  duration="0">
-</rel-toast>
-<script>
-  const persist = document.getElementById('persist');
-  persist.show();
-  // Manually close later: persist.close();
-</script>
-
-<!-- Listen for dismiss -->
-<rel-toast id="notif" message="Update available"></rel-toast>
-<script>
-  const notif = document.getElementById('notif');
-  notif.addEventListener('dismissed', () => {
-    console.log('Toast was dismissed');
-  });
-  notif.show();
-</script>
-```
-
-## API
-
-### Attributes/Properties
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `message` | `string` | `""` | Toast message text |
-| `type` | `"default" \| "error"` | `"default"` | Visual style (default: dark gray, error: red) |
-| `actionLabel` | `string` | - | Optional action button label (e.g., "UNDO", "RETRY") |
-| `duration` | `number` | `4000` | Auto-dismiss duration in milliseconds (0 = no auto-dismiss) |
-
-### Methods
-| Method | Description |
-|--------|-------------|
-| `show()` | Display the toast and start auto-dismiss timer |
-| `close()` | Manually dismiss the toast and clear timer |
-
-## Events
-| Event | Detail | Description |
-|-------|--------|-------------|
-| `action` | None | Fired when the action button is clicked (toast auto-closes after) |
-| `dismissed` | None | Fired when toast is dismissed (via action, close button, or auto-dismiss) |
-
-## Slots
-Default slot not used.
-
-## CSS Parts
-None exposed.
-
-## Tokens / CSS Variables
-
-### Semantic Tokens
-- `--rel-fonts-font-family` - Font family
-- `--rel-body-md-regular-font-size` - Font size
-
-### Spacing Tokens
-- `--rel-spacing-sm` - Gap between elements
-- `--rel-spacing-md` - Padding
-- `--rel-spacing-2xs` - Close button padding and margin
-
-### Color Tokens
-- `--rel-bg-neutral-inverse-1` - Default background color (dark gray)
-- `--rel-text-danger` - Error background color
-- `--rel-bg-surface` - Text and focus outline color
-- `--rel-bg-brand` - Action button text color
-
-### Shadow Tokens
-- `--rel-shadows-shadow-300` - Drop shadow
-
-### Border Tokens
-- `--rel-border-radius-sm` - Border radius
-
-## Accessibility
-- Uses `role="status"` and `aria-live="polite"` for screen reader announcements
-- Focus styles on action and close buttons
-- Animation respects `prefers-reduced-motion` media query
-- Close button has `aria-label="Dismiss"`
-
-### Keyboard Interactions
-- `Tab` - Focus action button or close button
-- `Space/Enter` - Activate focused button
-
-### Focus Behavior
-- Buttons show 2px white outline with 2px offset when focused
-- Border radius applied to maintain visual consistency
-
-## Notes / Edge Cases
-- **Important:** Toasts are hidden by default; you must call `show()` to display them
-- The component uses `:host` with `position: fixed`, `bottom: 24px`, `left: 50%`, `transform: translateX(-50%)` for bottom-center positioning
-- `z-index: 1000` ensures toasts appear above most content
-- The toast container is `display: inline-flex` with `pointer-events: all` (while`:host` has `pointer-events: none`)
-- Auto-dismiss timer starts when `show()` is called
-- Calling `close()` sets `visible = false`, dispatches `dismissed`, and clears the timeout
-- Clicking the action button dispatches `action` then automatically calls `close()`
-- Setting `duration="0"` disables auto-dismiss
-- The component includes a `fadeInUp` animation (20px translateY → 0, opacity 0 → 1) on appearance
-- Animation disabled when `prefers-reduced-motion: reduce` is set
-- When `visible` is false, `hidden` class applies `display: none`
-- **Type variants**: `default` uses `--rel-bg-neutral-inverse-1`, `error` uses `--rel-text-danger` 
-- The toast appears inline-flex, so it sizes to content width
+# rel-toast
+
+`<rel-toast>` is the transient notification of the Reliability Design System: a card anchored to one of six viewport positions (bottom centre by default) that shows a short message, an optional action button ("Undo", "Retry") and a dismiss button, then hides itself after `duration` milliseconds. It has two tones — `default` and `destructive` — and is driven by the `show` property (or `open()` / `close()`). Use it for brief confirmations that need no reply; use `<rel-snackbar>` when you need the status tones, a stacked layout or your own positioning, and `<rel-alert>` for messages that must stay on the page.
+
+## Usage
+
+```html
+<!-- Hidden until `show` is set (or open() is called) -->
+<rel-toast id="saved" message="File saved"></rel-toast>
+
+<!-- Initially visible; auto-hides after the default 4000 ms -->
+<rel-toast show message="Welcome back"></rel-toast>
+
+<!-- Destructive tone: danger fill, announced assertively -->
+<rel-toast id="failed" tone="destructive" message="Upload failed"></rel-toast>
+
+<!-- Action button (attribute is lower-case: actionlabel) -->
+<rel-toast id="deleted" message="Item deleted" actionlabel="Undo"></rel-toast>
+
+<!-- Longer and persistent toasts -->
+<rel-toast id="slow" message="Download complete" duration="7000"></rel-toast>
+<rel-toast id="sticky" message="Reconnecting…" duration="0"></rel-toast>
+```
+
+```js
+const saved = document.getElementById("saved");
+saved.open();                 // same as saved.show = true — starts the auto-dismiss timer
+saved.addEventListener("dismissed", () => {
+  saved.show; // false — fired by close(), the ✕ button, the action button and the timer
+});
+
+const deleted = document.getElementById("deleted");
+deleted.addEventListener("action", () => {
+  // undo the deletion… the toast closes itself right after (a `dismissed` event follows)
+});
+deleted.open();
+
+const sticky = document.getElementById("sticky");
+sticky.open();
+sticky.close();               // the only way to hide a duration="0" toast from script
+```
+
+```css
+/* Lift the toast above an open modal / drawer layer */
+rel-toast { --rel-toast-z: 10000; }
+```
+
+### Deprecated aliases
+
+```html
+<!-- type= is the deprecated alias of tone= (tone wins when both are set). Logs once per page:
+     [rel-toast] "type" is deprecated and will be removed in 3.0 — use "tone" instead. Note: tone="destructive" replaces type="error". -->
+<rel-toast type="error" message="Upload failed"></rel-toast>
+
+<!-- tone="error" | "danger" | "critical" are deprecated spellings of tone="destructive". Logs once per spelling:
+     [rel-toast] "tone="error"" is deprecated and will be removed in 3.0 — use "tone="destructive"" instead. -->
+<rel-toast tone="error" message="Upload failed"></rel-toast>
+<rel-toast tone="danger" message="Upload failed"></rel-toast>
+```
+
+```css
+/* --rel-z-toast is the deprecated alias of --rel-toast-z; it is still read as the fallback (no console notice). */
+rel-toast { --rel-z-toast: 10000; }
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-toast.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `message` | `message` | `string` | `""` | Text of the toast. It is also announced to screen readers through the shared live-region announcer each time `show` becomes true. |
+| `tone` | `tone` | `"neutral" \| "destructive" \| "default" \| "error" \| "danger" \| "critical"` | `undefined` | Semantic tone (Figma "Tone"): `"neutral"` (default: neutral surface) \| `"destructive"` (danger fill, announced assertively). `"default"` is a deprecated alias of `"neutral"`; `"error"`, `"danger"` and `"critical"` are deprecated aliases of `"destructive"`; each logs a one-time console notice. Takes precedence over the deprecated `type` prop. |
+| `actionLabel` | `actionlabel` | `string` | `undefined` | Label of the optional action button rendered between the message and the dismiss button; the button is omitted when unset. Clicking it fires `action` and then closes the toast. |
+| `duration` | `duration` | `number` | `4000` | Auto-dismiss delay in milliseconds, started each time `show` becomes true. `0` (or a negative value) disables auto-dismiss so the toast stays until `close()` or the dismiss button. Changing it while the toast is visible does not restart the running timer. |
+| `show` | `show` | `boolean` | `false` | Whether the toast is visible. Set it to true (or call `open()`) to show the toast and start the auto-dismiss timer; it is set back to false by `close()`, the dismiss button, the action button and the timer. Reflected. |
+| `dismissible` | `dismissible` | `boolean` | `true` | Shows the trailing dismiss button (Figma "Show Close Button"). Defaults to true; because it is a Lit boolean, `dismissible="false"` is still true — set the property to `false` from script to hide the button. |
+| `position` | `position` | `"top-left" \| "top-center" \| "top-right" \| "bottom-left" \| "bottom-center" \| "bottom-right"` | `"bottom-center"` | Where the toast is anchored: `bottom-center` (default, unchanged from before this prop existed), `bottom-left`, `bottom-right`, `top-left`, `top-center` or `top-right`. Top anchors also animate in from the top edge rather than upward from the bottom. Figma's Toast has axes Content / Show Button / Show Close Button / Tone and no position, so this axis is ours. Reflected. |
+| `size` | `size` | `"small" \| "medium" \| "large" \| "sm" \| "md" \| "lg"` | `"medium"` | Toast scale: `small`, `medium` (default, unchanged) or `large`. `sm` / `md` / `lg` are alternative spellings and stay supported — normalised to the full words, not deprecated. Scales the padding, the inner gap, the message type role and the close icon. Figma has no Size axis on Toast. Reflected. |
+| `maxVisible` | `max-visible` | `number` | `3` | How many toasts may be on screen at once AT THIS POSITION. Further ones wait their turn rather than being dropped — a notification the user never saw is worse than a late one — and each toast's `duration` only starts once it actually becomes visible, so a queued message cannot expire unseen. Default 3; unbounded stacking just fills the viewport. |
+
+#### Deprecated (still supported — removal targeted for 3.0)
+
+| Property | Attribute | Type | Use instead |
+| --- | --- | --- | --- |
+| `type` | `type` | `"neutral" \| "destructive" \| "default" \| "error" \| "danger" \| "critical"` | Deprecated since 1.4.7 — alias of `tone`; use `tone`. Same values as `tone`; `type="error"` maps to `tone="destructive"` and `type="default"` to `tone="neutral"`. Ignored when `tone` is set. Logs a one-time console notice. |
+
+### Public fields / accessors
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `resolvedTone` | `ToastTone` | Read-only canonical tone actually rendered: explicit `tone` wins, else `type`, else `"neutral"`; deprecated aliases are resolved to `"neutral"` / `"destructive"`. |
+
+### Methods
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| `open` | `open()` | Shows the toast: sets `show = true`, which starts the auto-dismiss timer and announces `message`. |
+| `close` | `close()` | Hides the toast, clears the auto-dismiss timer and fires `dismissed`. It fires `dismissed` even when the toast was already hidden. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `action` | — | bubbles / composed | Fired when the action button is clicked, before the toast closes itself (a `dismissed` event follows). No detail. |
+| `dismissed` | — | bubbles / composed | Fired whenever the toast is closed — by `close()`, the dismiss button, the action button or the auto-dismiss timer. No detail. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| — | This element has no slots. |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `base` | The `role="status"` toast container that carries the tone class |
+| `label` | The message text span |
+| `action` | The action button; rendered only when `actionlabel` is set |
+| `close-button` | The dismiss button; rendered while `dismissible` is true |
+
+## Tokens / CSS Variables
+
+### Component hooks
+
+Set these on the host (or an ancestor) to customise the element without touching design tokens.
+
+| Custom property | Default | Description |
+| --- | --- | --- |
+| `--rel-toast-z` | `var(--rel-z-toast, 9000)` | `z-index` of the fixed host (default `9000`); raise it when a modal or drawer layer covers the toast |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- The toast container (part `base`) is always in the shadow DOM with `role="status"`, `aria-live="polite"` and `aria-atomic="true"`; it is hidden with `display: none` while `show` is false. Because toggling `display` is not reliably announced, the component also pushes `message` into the shared off-screen live-region announcer (`utils/announce`) every time `show` becomes true — politely for `default`, assertively for `destructive`. Focus is never moved.
+- Two native `<button>`s: the optional action button (labelled by `actionlabel`) and the dismiss button with `aria-label="Dismiss"`. Both are in the Tab order; the component registers no key handlers (there is no Escape-to-close):
+
+| Key | Action |
+| --- | --- |
+| Tab / Shift + Tab | Move between the action button (if any) and the dismiss button; the toast sits in the Tab order at its DOM position, not at the end of the page |
+| Enter / Space | Activate the focused button: action fires `action` then `dismissed`; dismiss fires `dismissed` |
+
+- Keyboard focus on either button is a 2px `--rel-text-static-light` outline with 2px offset and `--rel-border-radius-xs` corners (`:focus-visible` only).
+- The 0.25s fade-in-up animation is disabled under `prefers-reduced-motion: reduce`.
+- A toast that auto-dismisses while a button inside it has focus drops focus to `<body>`; give important actions a `duration="0"` toast or a persistent control elsewhere.
+
+## Notes / Edge Cases
+
+- `show` is a boolean **property**, not a method: `toast.show()` throws. Use `toast.show = true` or `toast.open()`; the old README's `show()` call was wrong.
+- The host is a full-width `position: fixed` bar (`left: 0; right: 0`) pinned to the edge named by `position`, with `pointer-events: none` (the pill itself restores `pointer-events: all`), so it never blocks clicks around it. The corner positions add a 24px side inset so the toast does not sit flush against the viewport edge; the centred ones keep the full width to centre in, which is why `bottom-center` is unchanged from before the axis existed.
+- Top-anchored toasts animate in from the top edge (`fadeInDown`) rather than sliding upward, which would have read as the toast escaping its own anchor.
+- **Toasts at the same `position` stack automatically.** No wrapper element and no change to your markup: each `rel-toast` registers itself, and up to `max-visible` (default 3) show at once with the newest against the anchor edge. Dismissing one closes the gap for the rest, animated. The six positions are independent stacks, and a toast whose `position` changes while it is showing leaves one and joins the other.
+- **Overflow waits; it is never dropped.** Beyond `max-visible`, further toasts queue in arrival order and appear as earlier ones dismiss. A toast's `duration` does not begin until it is actually on screen, so a queued message cannot expire before anyone has seen it. *Behaviour change*: five toasts at one position used to render on top of each other — now three show and two wait.
+- A single toast is unaffected by any of this: the stack only writes a transform from the second card onward, so a lone toast renders exactly as it did before stacking existed.
+- The auto-dismiss timer starts only when `show` changes to true; changing `duration` on a visible toast does not restart it. Re-showing a visible toast (setting `show = true` again) is a no-op because the value did not change — `close()` it first.
+- `close()` always fires `dismissed`, even when the toast was already hidden.
+- The action button's hover state swaps to `--rel-bg-neutral` / `--rel-text-default` at 75% opacity.
+- Layering: the host's `z-index` is `--rel-toast-z` (default 9000; the pre-rename `--rel-z-toast` still works as its fallback). Raise it on the element or an ancestor if an overlay with a higher `z-index` covers the toast; anything rendered in the browser top layer (native `<dialog>` / Popover API content) always paints above it regardless of `z-index`.
+- `resolvedTone` is the tone actually rendered after alias resolution; use it (not `tone` / `type`) if you branch on tone in script.

package/dist/components/rel-tooltip/README.md

@@ -1,111 +1,119 @@
-# rel-tooltip
-
-## Overview
-A simple tooltip component that displays contextual text on hover. Supports above/below positioning and optional tail (arrow pointer). Uses CSS opacity transitions for smooth fade-in/out effects. Content is provided via a `<slot>` for flexible trigger elements.
-
-## Usage
-```html
-<!-- Basic tooltip (above) -->
-<rel-tooltip text="This is a helpful tooltip">
-  <button>Hover me</button>
-</rel-tooltip>
-
-<!-- Tooltip positioned below -->
-<rel-tooltip text="Information appears below" position="below">
-  <span>Hover for info</span>
-</rel-tooltip>
-
-<!-- With tail/arrow -->
-<rel-tooltip text="Tooltip with pointer" position="above" showTail>
-  <button>Hover me</button>
-</rel-tooltip>
-
-<!-- Tooltip on icon -->
-<rel-tooltip text="Edit item" showTail>
-  <img src="edit-icon.svg" alt="Edit">
-</rel-tooltip>
-
-<!-- Multiple elements in trigger -->
-<rel-tooltip text="Profile options" position="below">
-  <div class="user-avatar">
-    <img src="avatar.jpg" alt="User">
-    <span>John Doe</span>
-  </div>
-</rel-tooltip>
-```
-
-## API
-
-### Attributes/Properties
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `text` | `string` | `""` | Tooltip text content |
-| `position` | `"above" \| "below"` | `"above"` | Vertical position relative to trigger |
-| `showTail` | `boolean` | `false` | Whether to show the arrow/pointer |
-
-## Events
-None.
-
-## Slots
-| Slot | Description |
-|------|-------------|
-| (default) | Trigger element(s) that activate the tooltip on hover |
-
-## CSS Parts
-None exposed.
-
-## Tokens / CSS Variables
-
-### Semantic Tokens
-- `--rel-fonts-font-family` - Font family
-- `--rel-body-sm-regular-font-size` - Font size
-
-### Spacing Tokens
-- `--rel-spacing-xs` - Vertical padding
-- `--rel-spacing-sm` - Horizontal padding
-
-### Color Tokens
-- `--rel-bg-neutral-inverse-2` - Background color (near-black in light theme, white in dark theme)
-- `--rel-text-inverse` - Text color (white in light theme, near-black in dark theme)
-- `--rel-colors-dark-alpha-3` - Elevation shadow color (Figma `shadow/sm`: 0 2px 4px at 10% black; applied via `drop-shadow` so the tail casts the same shadow as the bubble)
-
-### Border Tokens
-- `--rel-border-radius-sm` - Border radius
-
-### Theming
-Colors use inverse semantic tokens, so the tooltip adapts automatically when
-`data-theme="dark"` (or `.dark`) is set on an ancestor — no page refresh needed.
-Dark-theme rendering (white bubble, dark text) is unchanged by the elevation
-shadow, which is effectively invisible on dark backgrounds.
-
-## Accessibility
-- Uses `role="tooltip"` on the tooltip bubble
-- `aria-hidden="true"` on tooltip (content is supplemental, not critical)
-- Tooltip does not receive focus (purely decorative on hover)
-- For critical information, consider alternative patterns (e.g., visible labels or expandable sections)
-
-### Keyboard Interactions
-- Tooltip shows on `:focus-within` as well as hover, so keyboard users see it when the slotted trigger receives focus (ensure the trigger is focusable)
-- `Escape` dismisses the tooltip (APG); it re-arms once hover/focus leaves and returns
-- Keyboard-triggered tooltips use the same theme-aware styling as hover-triggered ones
-
-### Focus Behavior
-- Tooltip activates on hover or focus within the trigger
-- Does not interfere with focus on slotted content
-
-## Notes / Edge Cases
-- The tooltip appears on `:host(:hover)` via CSS `opacity: 1` transition
-- By default, tooltip has `opacity: 0` and `pointer-events: none`
-- **Position "above"**: tooltip is positioned at `bottom: calc(100% + 8px)` (8px gap above trigger)
-- **Position "below"**: tooltip is positioned at `top: calc(100% + 8px)` (8px gap below trigger)
-- The tooltip uses `left: 50%` and `transform: translateX(-50%)` for horizontal centering
-- `white-space: nowrap` prevents text wrapping (tooltip width adjusts to content)
-- **Tail/arrow** is a CSS triangle created with transparent borders:
-  - Above pointer: 6px border-top, positioned at `bottom: -6px`
-  - Below pointer: 6px border-bottom, positioned at `top: -6px`
-  - Tail uses `left: 50%` and `transform: translateX(-50%)` for centering
-- The tooltip has `z-index: 1000` to appear above most content
-- The tooltip is `position: absolute` relative to `:host` (which is `position: relative`)
-- `:host` is `display: inline-block` to size to slotted content
-- Transition duration is `0.2s ease` for opacity changes
-- For very long tooltip text, consider wrapping or alternative UI patterns (max-width not set by default)
+# rel-tooltip
+
+Hover/focus tooltip implementing the Figma "Tooltip" component: wraps a trigger element and fades in a short inverse-coloured text bubble above, below, left or right of it, in the Figma `single-line` or `multi-line` **Type**, optionally with a pointing tail. Use it for brief supplementary hints on icon buttons and truncated labels. Do not put critical or interactive content in it — it is not reachable on touch, cannot be focused, and disappears on hover-out.
+
+## Usage
+
+```html
+<!-- Default: above the trigger -->
+<rel-tooltip text="Save your changes">
+  <rel-button variant="primary">Save</rel-button>
+</rel-tooltip>
+
+<!-- Positions -->
+<rel-tooltip text="Appears below" position="below">
+  <rel-button variant="secondary">Below</rel-button>
+</rel-tooltip>
+<rel-tooltip text="Appears on the left" position="left">
+  <rel-button variant="secondary">Left</rel-button>
+</rel-tooltip>
+<rel-tooltip text="Appears on the right" position="right">
+  <rel-button variant="secondary">Right</rel-button>
+</rel-tooltip>
+
+<!-- With the pointing tail -->
+<rel-tooltip text="Edit" show-tail>
+  <rel-button variant="ghost" icon-only aria-label="Edit">
+    <rel-icon name="edit"></rel-icon>
+  </rel-button>
+</rel-tooltip>
+
+<!-- Multi-line: wraps inside a 220px bubble -->
+<rel-tooltip
+  type="multi-line"
+  position="below"
+  show-tail
+  text="Exports the current view as CSV. Filters and sorting are preserved."
+>
+  <rel-button variant="secondary">Export</rel-button>
+</rel-tooltip>
+
+<!-- Restyle the bubble through its part -->
+<style>
+  .wide::part(panel) {
+    max-width: 320px;
+  }
+</style>
+<rel-tooltip class="wide" type="multi-line" text="A longer explanation that needs more room than the default bubble.">
+  <rel-button variant="ghost">Details</rel-button>
+</rel-tooltip>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-tooltip.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `text` | `text` | `string` | `""` | Plain-text content of the bubble. Empty text still renders an (empty) bubble on hover, so always set it. |
+| `position` | `position` | `"above" \| "below" \| "left" \| "right"` | `"above"` | Side of the trigger the bubble appears on, centred and 6px away (13px when `show-tail` is set, so the tail clears the trigger; override with `--rel-tooltip-offset`): `above`, `below`, `left` or `right`. No collision detection — pick a side with room in the viewport. |
+| `showTail` | `show-tail` | `boolean` | `false` | Renders the triangular tail (`indicator` part) on the bubble's edge facing the trigger. |
+| `type` | `type` | `"single-line" \| "multi-line"` | `"single-line"` | Figma "Type": `single-line` keeps the text on one line and sizes to content; `multi-line` wraps inside a 200px max-width bubble. Reflected. |
+| `tone` | `tone` | `"inverse" \| "neutral"` | `"inverse"` | Bubble appearance: `inverse` (default) is the original inverse-surface bubble, unchanged; `neutral` is a light surface — `--rel-bg-neutral` with `--rel-text-default` and a 1px `--rel-border-default`, tail included. Figma has no such variant; this is a deliberate addition. Reflected. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| — | — | — | This element emits no custom events. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | The trigger element (one focusable element such as a button or icon button). It receives `aria-describedby` pointing at the bubble. |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `panel` | The tooltip bubble (`role="tooltip"`): background, padding, radius, shadow and max-width. |
+| `indicator` | The triangular tail pointing at the trigger, rendered only when `show-tail` is set. |
+
+## Tokens / CSS Variables
+
+### Component hooks
+
+Set these on the host (or an ancestor) to customise the element without touching design tokens.
+
+| Custom property | Default | Description |
+| --- | --- | --- |
+| `--rel-tooltip-offset` | `6px` | Gap between the trigger and the bubble; defaults to `6px`, or `13px` when `show-tail` is set so the tail clears the trigger. |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- The bubble is a `role="tooltip"` element with a stable generated `id`; the first slotted element is given `aria-describedby` pointing at it (re-linked on `slotchange`), so screen readers read the hint as the trigger's description.
+- The bubble is shown while the host is hovered **or** has focus within (`:focus-within`), so keyboard users see it when the slotted trigger is focused. The trigger therefore must be focusable — wrap a button or link, not plain text.
+- The bubble never takes focus and has `pointer-events: none`.
+
+| Key | Action |
+| --- | --- |
+| `Tab` | Focus the slotted trigger; the tooltip appears |
+| `Escape` | Dismiss the tooltip (APG pattern). The key is not swallowed, so an enclosing dialog may also react to it |
+
+After `Escape` the tooltip stays hidden until the pointer leaves and returns or focus leaves and returns (`mouseleave` / `focusout` clear the dismissed state).
+
+## Notes / Edge Cases
+
+- **Attribute spelling is `show-tail`** (kebab-case). `showTail="…"` as an HTML attribute does nothing; set the property in code.
+- **Positioning is static.** The bubble is `position: absolute` relative to the host (which is `display: inline-block; position: relative`), 6px from the trigger, centred on it, with `z-index: 1000`. There is no flipping or viewport collision detection, and ancestors with `overflow: hidden` or their own stacking context will clip it — for popover-style panels use `rel-popover`.
+- `single-line` bubbles use `white-space: nowrap` and grow with the text; `multi-line` wraps at a 220px `max-width` (override it via `::part(panel)`).
+- The bubble's shadow is applied with `filter: drop-shadow` so the tail (`indicator` part) casts the same shadow as the panel.
+- Colours use the inverse neutral tokens, so the tooltip flips automatically (dark bubble on light themes, light bubble under `data-theme="dark"` / `.dark`).
+- The hint is read from `text` only; slotted content is the trigger, not the tooltip body.