@reliability-design/web 1.4.8 → 1.4.10

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

@@ -1,168 +1,170 @@
-# rel-snackbar
-
-`<rel-snackbar>` is the snackbar of the Reliability Design System (Figma "Snackbar"): a dark, elevated message bar with a 4px tone accent and leading status icon for the success / warning / destructive tones, an optional action button and a close icon, in single-line and double-line (Figma Type=Longer Action) layouts. It is shown by setting `show` and hides itself after `duration` milliseconds. Unlike `<rel-toast>` it is **not** positioned — it is a `display: block` element you place yourself (in-flow, or fixed via your own CSS). Use it for brief feedback with one follow-up action ("Undo", "Retry"); use `<rel-alert>` for messages that must stay on the page.
-
-## Usage
-
-```html
-<!-- Hidden until `show` is set -->
-<rel-snackbar id="uploaded" message="File uploaded"></rel-snackbar>
-
-<!-- Initially visible; neutral tone (no accent, no icon), auto-hides after 4000 ms -->
-<rel-snackbar show message="Settings saved"></rel-snackbar>
-
-<!-- Status tones: left accent + leading icon -->
-<rel-snackbar show tone="success" message="Invitation sent"></rel-snackbar>
-<rel-snackbar show tone="warning" message="Connection is unstable"></rel-snackbar>
-<rel-snackbar show tone="destructive" message="Payment failed"></rel-snackbar>
-
-<!-- Action button -->
-<rel-snackbar id="deleted" message="Item deleted" action="Undo"></rel-snackbar>
-
-<!-- Double-line layout with a longer (2 × duration) dismiss delay -->
-<rel-snackbar
-  id="archived"
-  message="12 conversations were archived and will be deleted in 30 days"
-  action="Undo"
-  variant="longer-action"
-></rel-snackbar>
-
-<!-- Deprecated aliases — both still work and both log a one-time console notice.
-     `lines="double"` sets the stacked layout but NOT the doubled delay; `longeraction`
-     doubles the delay but does not stack. `variant="longer-action"` above does both.
-     Note the attribute is lower-case `longeraction`, not `longer-action`. -->
-<rel-snackbar message="Older markup" action="Undo" lines="double" longeraction></rel-snackbar>
-
-<!-- Persistent, without the close icon (the boolean must be cleared from script — see the js block) -->
-<rel-snackbar id="busy" message="Processing…" duration="0"></rel-snackbar>
-```
-
-```js
-const uploaded = document.getElementById("uploaded");
-uploaded.show = true;            // starts the auto-dismiss timer and announces the message
-uploaded.addEventListener("close", () => {
-  uploaded.show; // false — fired by the close icon, the action button and the timer
-});
-
-const deleted = document.getElementById("deleted");
-deleted.addEventListener("actionClick", () => {
-  // undo the deletion… the snackbar dismisses itself right after (a `close` event follows)
-});
-deleted.show = true;
-
-// A Lit boolean attribute is true whenever present, so iconclose="false" does NOT work.
-const busy = document.getElementById("busy");
-busy.iconClose = false;
-busy.show = true;
-busy.show = false;               // hides silently — no `close` event when hidden from script
-```
-
-```css
-/* The component is display: block; position it yourself */
-rel-snackbar {
-  position: fixed;
-  bottom: 24px;
-  left: 50%;
-  transform: translateX(-50%);
-}
-```
-
-### Deprecated aliases
-
-```html
-<!-- type= is the deprecated alias of tone= (tone wins when both are set). Logs once per page:
-     [rel-snackbar] "type" is deprecated and will be removed in 3.0 — use "tone" instead. Note: tone="destructive" replaces type="error"; tone="neutral" replaces type="default". -->
-<rel-snackbar type="error" message="Payment failed"></rel-snackbar>
-<rel-snackbar type="default" message="Settings saved"></rel-snackbar>
-
-<!-- tone="default" is the deprecated spelling of tone="neutral". Logs once:
-     [rel-snackbar] "tone="default"" is deprecated and will be removed in 3.0 — use "tone="neutral"" instead. -->
-<rel-snackbar tone="default" message="Settings saved"></rel-snackbar>
-
-<!-- tone="error" | "danger" | "critical" are deprecated spellings of tone="destructive". Logs once per spelling:
-     [rel-snackbar] "tone="error"" is deprecated and will be removed in 3.0 — use "tone="destructive"" instead. -->
-<rel-snackbar tone="error" message="Payment failed"></rel-snackbar>
-<rel-snackbar tone="critical" message="Payment failed"></rel-snackbar>
-```
-
-<!-- readme-gen:start -->
-
-<!-- Generated from rel-snackbar.ts — do not edit; run readme-generate.mjs -->
-
-## API
-
-### Attributes / Properties
-
-| Property | Attribute | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| `message` | `message` | `string` | `"This is a snackbar message"` | Message text. Announced to screen readers through the shared live-region announcer when the snackbar is shown and whenever it changes while shown. The default is a placeholder — always set it. |
-| `action` | `action` | `string` | `undefined` | Label of the optional action button (Figma trailing button, Static / Small); omitted when unset. Clicking it fires `actionClick` and then dismisses the snackbar. |
-| `variant` | `variant` | `"default" \| "longer-action"` | `undefined` | Layout and timing (Figma "Type"): `"default"` (message and actions on one row) \| `"longer-action"` (message stacked above the actions, which align to the end, with the auto-dismiss delay doubled so there is time to use the action). Takes precedence over the deprecated `lines` and `longerAction` props. |
-| `iconClose` | `iconclose` | `boolean` | `true` | Shows the trailing close icon button. Defaults to true; because it is a Lit boolean, `iconclose="false"` is still true — set the property to `false` from script to hide the button. |
-| `duration` | `duration` | `number` | `4000` | Auto-dismiss delay in milliseconds (doubled by `variant="longer-action"`), started when `show` becomes true and restarted when `duration` or the layout changes while shown. `0` (or a negative value) disables auto-dismiss. |
-| `tone` | `tone` | `"neutral" \| "success" \| "warning" \| "destructive" \| "default" \| "error" \| "danger" \| "critical"` | `undefined` | Semantic tone (Figma "Tone"): `"neutral"` (default: no accent, no icon) \| `"success"` \| `"warning"` \| `"destructive"` — the status tones add a 4px left accent and a leading icon (check-circle / warning / error) in the tone colour. `"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. |
-| `show` | `show` | `boolean` | `false` | Whether the snackbar is visible. Set it to true to show the snackbar and start the auto-dismiss timer; it is set back to false by the close icon, the action button and the timer. There is no open/close method — toggle this property. Reflected. |
-
-#### Deprecated (still supported — removal targeted for 3.0)
-
-| Property | Attribute | Type | Use instead |
-| --- | --- | --- | --- |
-| `longerAction` | `longeraction` | `boolean` | — use `variant="longer-action"`, which also sets the stacked layout. Doubles the auto-dismiss delay (`duration * 2`) on its own. Ignored when `variant` is set. Logs a one-time console notice. |
-| `lines` | `lines` | `"single" \| "double"` | — use `variant`; `lines="double"` maps to `variant="longer-action"`. Sets the stacked layout on its own but not the doubled delay. Ignored when `variant` is set. Logs a one-time console notice. |
-| `type` | `type` | `"neutral" \| "success" \| "warning" \| "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 |
-| --- | --- | --- |
-| `resolvedVariant` | `SnackbarVariant` | Read-only canonical layout actually rendered: explicit `variant` wins, else either deprecated prop (`lines="double"` or `longerAction`) promotes to `"longer-action"`, else `"default"`. |
-| `resolvedTone` | `SnackbarTone` | Read-only canonical tone actually rendered: explicit `tone` wins, else `type`, else `"neutral"`; deprecated aliases are resolved to `"neutral"` / `"destructive"`. |
-
-## Events
-
-| Event | Detail | Bubbles / composed | Description |
-| --- | --- | --- | --- |
-| `actionClick` | — | bubbles / composed | Fired when the action button is clicked, before the snackbar dismisses itself (a `close` event follows). No detail. |
-| `close` | — | bubbles / composed | Fired whenever the snackbar dismisses itself — via the close icon, the action button or the auto-dismiss timer. Not fired when `show` is set to false from script. No detail. |
-
-## Slots
-
-| Slot | Description |
-| --- | --- |
-| — | This element has no slots. |
-
-## CSS Parts
-
-| Part | Description |
-| --- | --- |
-| `label` | The message text container |
-| `action` | The action button; rendered only when `action` is set |
-| `close-button` | The close icon button; rendered while `iconclose` is true |
-
-<!-- readme-gen:end -->
-
-## Accessibility
-
-- The bar is always in the shadow DOM and hidden with `display: none` while `show` is false. Its role follows the tone: `role="alert"` for `destructive` (implicitly assertive), `role="status"` for every other tone (implicitly polite); no explicit `aria-live` is set. Because toggling `display` is not reliably announced, the component also pushes `message` into the shared off-screen live-region announcer (`utils/announce`) when `show` becomes true and whenever `message` changes while shown — assertively for `destructive`, politely otherwise. Focus is never moved.
-- The leading status icon and the close glyph are `<rel-icon>`s and render `aria-hidden="true"`; the close control is a native `<button>` with `aria-label="Close"`, the action button is labelled by `action`. 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 close button (if any) |
-| Enter / Space | Activate the focused button: action fires `actionClick` then `close`; the close button fires `close` |
-
-- Keyboard focus on either button is a 2px `--rel-text-static-light` outline with 2px offset (`:focus-visible` only); the close button adds `--rel-border-radius-xs` corners, the action button keeps its pill radius.
-- The 0.3s slide-up animation is disabled under `prefers-reduced-motion: reduce`.
-- A snackbar that auto-dismisses while one of its buttons has focus drops focus to `<body>`; use `duration="0"` (or `longeraction`) when the action matters.
-
-## Notes / Edge Cases
-
-- Positioning is yours: the host is `display: block` and in flow. The bar itself is `min-width: 280px; max-width: 500px`.
-- The auto-dismiss timer starts when `show` becomes true and restarts whenever `duration` or `longerAction` changes while visible; `longerAction` doubles the delay (`duration * 2`). `duration="0"` disables it.
-- Setting `show = false` from script hides the bar **without** firing `close`; `close` fires only for the close icon, the action button and the timer. Setting `show = true` on an already visible snackbar is a no-op (the value did not change).
-- Only `lines="double"` changes the layout (message stacked over end-aligned actions, 16px top padding); `longeraction` only affects timing — combine the two for the Figma Longer Action variant.
-- The status icon is fixed per tone (`check-circle`, `warning`, `error`) and neutral has none; there are no slots, so the icon cannot be replaced.
-- `message` defaults to the placeholder "This is a snackbar message" — a snackbar that shows that text has simply not been given a message.
-- `iconClose` is a Lit boolean: any attribute value (including `"false"`) counts as true. Clear it as a property from script.
-- Figma binds the success / destructive icon colours to dark-surface status text values that no light-mode semantic token resolves to; the component uses the status fill tokens (`--rel-bg-success` / `--rel-bg-danger` / `--rel-bg-warning`) for both the accent and the icon instead.
-- `resolvedTone` is the tone actually rendered after alias resolution; use it (not `tone` / `type`) if you branch on tone in script.
+# rel-snackbar
+
+`<rel-snackbar>` is the snackbar of the Reliability Design System (Figma "Snackbar"): a dark, elevated message bar with a 4px tone accent and leading status icon for the success / warning / destructive tones, an optional action button and a close icon, in single-line and double-line (Figma Type=Longer Action) layouts. It is shown by setting `show` and hides itself after `duration` milliseconds. Unlike `<rel-toast>` it is **not** positioned — it is a `display: block` element you place yourself (in-flow, or fixed via your own CSS). Use it for brief feedback with one follow-up action ("Undo", "Retry"); use `<rel-alert>` for messages that must stay on the page.
+
+## Usage
+
+```html
+<!-- Hidden until `show` is set -->
+<rel-snackbar id="uploaded" message="File uploaded"></rel-snackbar>
+
+<!-- Initially visible; neutral tone (no accent, no icon), auto-hides after 4000 ms -->
+<rel-snackbar show message="Settings saved"></rel-snackbar>
+
+<!-- Status tones: left accent + leading icon -->
+<rel-snackbar show tone="success" message="Invitation sent"></rel-snackbar>
+<rel-snackbar show tone="warning" message="Connection is unstable"></rel-snackbar>
+<rel-snackbar show tone="destructive" message="Payment failed"></rel-snackbar>
+
+<!-- Action button -->
+<rel-snackbar id="deleted" message="Item deleted" action="Undo"></rel-snackbar>
+
+<!-- Double-line layout with a longer (2 × duration) dismiss delay -->
+<rel-snackbar
+  id="archived"
+  message="12 conversations were archived and will be deleted in 30 days"
+  action="Undo"
+  variant="longer-action"
+></rel-snackbar>
+
+<!-- Persistent, without the close icon ("false" switches a default-true boolean off, since 1.5.0) -->
+<rel-snackbar id="busy" message="Processing…" duration="0" icon-close="false"></rel-snackbar>
+```
+
+```js
+const uploaded = document.getElementById("uploaded");
+uploaded.show = true;            // starts the auto-dismiss timer and announces the message
+uploaded.addEventListener("close", () => {
+  uploaded.show; // false — fired by the close icon, the action button and the timer
+});
+
+const deleted = document.getElementById("deleted");
+deleted.addEventListener("actionClick", () => {
+  // undo the deletion… the snackbar dismisses itself right after (a `close` event follows)
+});
+deleted.show = true;
+
+const busy = document.getElementById("busy");
+busy.show = true;
+busy.show = false;               // hides silently — no `close` event when hidden from script
+```
+
+```css
+/* The component is display: block; position it yourself */
+rel-snackbar {
+  position: fixed;
+  bottom: 24px;
+  left: 50%;
+  transform: translateX(-50%);
+}
+```
+
+### Deprecated aliases
+
+```html
+<!-- type= is the deprecated alias of tone= (tone wins when both are set). Logs once per page:
+     [rel-snackbar] "type" is deprecated and will be removed in 3.0 — use "tone" instead. Note: tone="destructive" replaces type="error"; tone="neutral" replaces type="default". -->
+<rel-snackbar type="error" message="Payment failed"></rel-snackbar>
+<rel-snackbar type="default" message="Settings saved"></rel-snackbar>
+
+<!-- tone="default" is the deprecated spelling of tone="neutral". Logs once:
+     [rel-snackbar] "tone="default"" is deprecated and will be removed in 3.0 — use "tone="neutral"" instead. -->
+<rel-snackbar tone="default" message="Settings saved"></rel-snackbar>
+
+<!-- tone="error" | "danger" | "critical" are deprecated spellings of tone="destructive". Logs once per spelling:
+     [rel-snackbar] "tone="error"" is deprecated and will be removed in 3.0 — use "tone="destructive"" instead. -->
+<rel-snackbar tone="error" message="Payment failed"></rel-snackbar>
+<rel-snackbar tone="critical" message="Payment failed"></rel-snackbar>
+
+<!-- lines="double" and longeraction (lower-case attribute) are deprecated spellings of
+     variant="longer-action". Either one alone renders the full longer-action variant: stacked
+     layout and the doubled auto-dismiss delay. Ignored when variant is set; each logs once. -->
+<rel-snackbar message="Older markup" action="Undo" lines="double"></rel-snackbar>
+<rel-snackbar message="Older markup" action="Undo" longeraction></rel-snackbar>
+
+<!-- iconclose → icon-close (since 1.5.0; still works, logs a one-time console notice, removed in 3.0) -->
+<rel-snackbar message="Processing…" duration="0" iconclose="false"></rel-snackbar>
+<rel-snackbar message="Processing…" duration="0" icon-close="false"></rel-snackbar>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-snackbar.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `message` | `message` | `string` | `"This is a snackbar message"` | Message text. Announced to screen readers through the shared live-region announcer when the snackbar is shown and whenever it changes while shown. The default is a placeholder — always set it. |
+| `action` | `action` | `string` | `undefined` | Label of the optional action button (Figma trailing button, Static / Small); omitted when unset. Clicking it fires `actionClick` and then dismisses the snackbar. |
+| `variant` | `variant` | `"default" \| "longer-action"` | `undefined` | Layout and timing (Figma "Type"): `"default"` (the default: message and actions on one row) \| `"longer-action"` (message stacked above the actions, which align to the end, with the auto-dismiss delay doubled so there is time to use the action). Takes precedence over the deprecated `lines` and `longerAction` props. |
+| `iconClose` | `icon-close` | `boolean` | `true` | Shows the trailing close icon button. Defaults to true; `icon-close="false"` (or the property set to `false`) hides the button. The `iconclose` attribute spelling is deprecated (still works; removal targeted for 3.0). |
+| `duration` | `duration` | `number` | `4000` | Auto-dismiss delay in milliseconds (doubled by `variant="longer-action"`), started when `show` becomes true and restarted when `duration` or the layout changes while shown. `0` (or a negative value) disables auto-dismiss. |
+| `tone` | `tone` | `"neutral" \| "success" \| "warning" \| "destructive" \| "default" \| "error" \| "danger" \| "critical"` | `undefined` | Semantic tone (Figma "Tone"): `"neutral"` (default: no accent, no icon) \| `"success"` \| `"warning"` \| `"destructive"` — the status tones add a 4px left accent and a leading icon (check-circle / warning / error) in the tone colour. `"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. |
+| `show` | `show` | `boolean` | `false` | Whether the snackbar is visible. Set it to true to show the snackbar and start the auto-dismiss timer; it is set back to false by the close icon, the action button and the timer. There is no open/close method — toggle this property. Reflected. |
+
+#### Deprecated (still supported — removal targeted for 3.0)
+
+| Property | Attribute | Type | Use instead |
+| --- | --- | --- | --- |
+| `longerAction` | `longeraction` | `boolean` | — use `variant="longer-action"`. On its own it renders the full longer-action variant (stacked layout and the doubled auto-dismiss delay, `duration * 2`). Ignored when `variant` is set. Logs a one-time console notice. |
+| `lines` | `lines` | `"single" \| "double"` | — use `variant`; `lines="double"` maps to `variant="longer-action"` (stacked layout and the doubled auto-dismiss delay). Ignored when `variant` is set. Logs a one-time console notice. |
+| `type` | `type` | `"neutral" \| "success" \| "warning" \| "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 |
+| --- | --- | --- |
+| `resolvedVariant` | `SnackbarVariant` | Read-only canonical layout actually rendered: explicit `variant` wins, else either deprecated prop (`lines="double"` or `longerAction`) promotes to `"longer-action"`, else `"default"`. |
+| `resolvedTone` | `SnackbarTone` | Read-only canonical tone actually rendered: explicit `tone` wins, else `type`, else `"neutral"`; deprecated aliases are resolved to `"neutral"` / `"destructive"`. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `actionClick` | — | bubbles / composed | Fired when the action button is clicked, before the snackbar dismisses itself (a `close` event follows). No detail. |
+| `close` | — | bubbles / composed | Fired whenever the snackbar dismisses itself — via the close icon, the action button or the auto-dismiss timer. Not fired when `show` is set to false from script. No detail. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| — | This element has no slots. |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `label` | The message text container |
+| `action` | The action button; rendered only when `action` is set |
+| `close-button` | The close icon button; rendered while `icon-close` is true |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- The bar is always in the shadow DOM and hidden with `display: none` while `show` is false. Its role follows the tone: `role="alert"` for `destructive` (implicitly assertive), `role="status"` for every other tone (implicitly polite); no explicit `aria-live` is set. Because toggling `display` is not reliably announced, the component also pushes `message` into the shared off-screen live-region announcer (`utils/announce`) when `show` becomes true and whenever `message` changes while shown — assertively for `destructive`, politely otherwise. Focus is never moved.
+- The leading status icon and the close glyph are `<rel-icon>`s and render `aria-hidden="true"`; the close control is a native `<button>` with `aria-label="Close"`, the action button is labelled by `action`. 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 close button (if any) |
+| Enter / Space | Activate the focused button: action fires `actionClick` then `close`; the close button fires `close` |
+
+- Keyboard focus on either button is a 2px `--rel-text-static-light` outline with 2px offset (`:focus-visible` only); the close button adds `--rel-border-radius-xs` corners, the action button keeps its pill radius.
+- The 0.3s slide-up animation is disabled under `prefers-reduced-motion: reduce`.
+- A snackbar that auto-dismisses while one of its buttons has focus drops focus to `<body>`; use `duration="0"` (or `variant="longer-action"`, which doubles the delay) when the action matters.
+
+## Notes / Edge Cases
+
+- Positioning is yours: the host is `display: block` and in flow. The bar itself is `min-width: 280px; max-width: 500px`.
+- The auto-dismiss timer starts when `show` becomes true and restarts whenever `duration`, `variant` or a deprecated `lines` / `longerAction` changes while visible; `variant="longer-action"` doubles the delay (`duration * 2`). `duration="0"` disables it.
+- Setting `show = false` from script hides the bar **without** firing `close`; `close` fires only for the close icon, the action button and the timer. Setting `show = true` on an already visible snackbar is a no-op (the value did not change).
+- `variant="longer-action"` (Figma Longer Action) stacks the message over end-aligned actions with 16px top padding and doubles the auto-dismiss delay. The deprecated `lines="double"` and `longeraction` each produce the same full variant on their own (see "Deprecated aliases"); before 1.5.0 this README said each did only half of it.
+- The status icon is fixed per tone (`check-circle`, `warning`, `error`) and neutral has none; there are no slots, so the icon cannot be replaced.
+- `message` defaults to the placeholder "This is a snackbar message" — a snackbar that shows that text has simply not been given a message.
+- `iconClose` is a boolean: presence or `""` means true, and since 1.5.0 `icon-close="false"` means false.
+- Figma binds the success / destructive icon colours to dark-surface status text values that no light-mode semantic token resolves to; the component uses the status fill tokens (`--rel-bg-success` / `--rel-bg-danger` / `--rel-bg-warning`) for both the accent and the icon instead.
+- `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-split-button/README.md

@@ -0,0 +1,129 @@
+# rel-split-button
+
+<!-- @unreleased-component 1.5.0 -->
+
+A button with a main action and a menu of related actions, also called a combo button. It is one pill in two segments with a 1px divider between them: the main action on the left, and a chevron on the right that opens a `rel-menu` of `items`, anchored below and end-aligned. Use it when one action is the usual choice and a few close variants should stay one click away, such as "New order" with "Duplicate" and "Save as template". Use `rel-button` for a single action, and a `rel-popover` with a `rel-menu` when no action is the default.
+
+Each segment is a native `<button>` drawn with rel-button's own styles for the chosen `variant`, `tone` and `size`. The heights (32 / 40 / 48px), padding, type, hover, pressed, focus ring and disabled look are therefore rel-button's. The outer corners keep the pill radius and the seam between the segments is square. While the menu is open, the chevron keeps its pressed look and its arrow turns up.
+
+## Usage
+
+```html
+<!-- Items are set as a property; the host's click is the main action -->
+<rel-split-button id="order" label="New order"></rel-split-button>
+<script>
+  const order = document.getElementById('order');
+  order.items = [
+    { value: 'duplicate', label: 'Duplicate', icon: 'copy' },
+    { value: 'template', label: 'Save as template' },
+    { value: 'archive', label: 'Archive', disabled: true }
+  ];
+  order.addEventListener('click', () => createOrder());
+  order.addEventListener('rel-select', (e) => {
+    console.log('chose', e.detail.value);
+  });
+</script>
+
+<!-- Filled, in the brand colour, with a leading icon -->
+<rel-split-button variant="primary" tone="brand" icon="plus" label="New order"></rel-split-button>
+
+<!-- Small, and a custom name for the chevron -->
+<rel-split-button size="small" menu-label="More export formats" label="Export CSV"></rel-split-button>
+
+<!-- The main action is busy: a spinner only, and the chevron is disabled -->
+<rel-split-button loading label="Saving"></rel-split-button>
+
+<!-- Icon-only: the main action is a square; aria-label names it -->
+<rel-split-button icon-only icon="plus" aria-label="New order"></rel-split-button>
+
+<!-- On a dark or coloured surface -->
+<rel-split-button variant="static" label="Book load"></rel-split-button>
+```
+
+`items` is an array, so set it as a property, or as a JSON array attribute in static HTML. In React 19 and Next.js, pass it as a prop on the client: server rendering drops arrays on custom elements.
+
+The divider between the segments follows the variant:
+
+- `secondary` draws the tone's outline border (`--rel-action-neutral-border-outline`, or the danger outline), which takes the outline's hover colour while the main action is hovered or pressed. The segments drop their inner borders.
+- `primary` draws the segment's label colour.
+- `static` draws the static label colour (white).
+- `ghost` draws `--rel-border-subtle`.
+
+The divider is its own 1px column, so the pill is the main action, plus 1px, plus the chevron. A disabled split button dims each segment and keeps the divider's colour.
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-split-button.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | `string` | `""` | Text of the main action. Slotted content replaces it. |
+| `variant` | `variant` | `"primary" \| "secondary" \| "ghost" \| "static"` | `"secondary"` | Style of both segments, as rel-button's `variant`: `primary` (filled), `secondary` (outlined, the default), `ghost` (no fill or border) or `static` (transparent with a white label and divider, for dark or coloured surfaces; neutral only, as on rel-button). Reflected. |
+| `tone` | `tone` | `"neutral" \| "brand" \| "destructive"` | `"neutral"` | Colour of both segments, as rel-button's `tone`: `neutral` (default), `brand` or `destructive`. As on rel-button, `brand` changes only the `primary` style. Reflected. |
+| `size` | `size` | `"small" \| "medium" \| "large"` | `"medium"` | Height of the pill and size of its text and icons, as rel-button's `size`: `small` = 32px, `medium` = 40px (default), `large` = 48px. The menu rows take the same size. Reflected. |
+| `disabled` | `disabled` | `boolean` | `false` | Dims both segments to rel-button's disabled look (the divider keeps its colour), removes them from the Tab order and keeps the menu closed. Reflected. |
+| `loading` | `loading` | `boolean` | `false` | The main action shows only rel-button's spinner, at its minimum width; its text stays its accessible name (visually hidden) and it is `aria-busy`. Its clicks are blocked and the chevron is disabled, so nothing else starts mid-request; an open menu closes. Reflected. |
+| `iconOnly` | `icon-only` | `boolean` | `false` | The main action is a square of the button's height (32 / 40 / 48), as rel-button's `icon-only`: give it a single icon (`icon`, or a slotted `rel-icon`) and set `aria-label`. Reflected. |
+| `ariaLabel` | `aria-label` | `string \| null` | `null` | Accessible name of the main action, forwarded to its native `<button>`. Required with `icon-only`, where the main action has no visible text (a console warning names split buttons without one). |
+| `menuLabel` | `menu-label` | `string` | `"More options"` | Accessible name of the chevron button (attribute `menu-label`); it has no visible text. |
+| `icon` | `icon` | `string` | `""` | `rel-icon` name drawn before the main action's text (16 / 18 / 20px by size). |
+| `items` | `items` | `SplitButtonItem[]` | `[]` | The menu entries, each `{ value, label, icon?, disabled? }`. Set as a property (or a JSON array attribute). |
+| `open` | `open` | `boolean` | `false` | Whether the menu is open. Updated by the component (and announced with `rel-open-change`); set it to open or close the menu from code. Reflected. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `rel-open-change` | `{ open }` | bubbles / composed | The menu opened or closed (chevron, keyboard, Escape, an outside click, Tab away, or a choice). Detail: `{ open: boolean }`. |
+| `rel-select` | `{ value, item }` | bubbles / composed | A menu entry was chosen with a click, Enter or Space; the menu has closed and focus is back on the chevron. Detail: `{ value: string, item: SplitButtonItem }`. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | The main action's content (text, or a `rel-icon` and text). Falls back to `label`. |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `main` | The main action's native `<button>`. |
+| `indicator` | The loading spinner on the main action, rendered only while `loading` is set. |
+| `toggle` | The chevron's native `<button>` (`aria-haspopup="menu"`, `aria-expanded`, named by `menu-label`). |
+
+## 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-split-button-menu-width` | `max-content` | Width of the menu (default `max-content`). The menu is never narrower than the split button. |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- The main action is a native `<button>` named by its content. The chevron is a native `<button>` with `aria-haspopup="menu"`, `aria-expanded` and the accessible name from `menu-label` (default "More options").
+- The menu is a `rel-menu` (`role="menu"`); its rows are `role="menuitem"`, and a disabled entry has `aria-disabled="true"`. Item icons are hidden from assistive technology.
+- `loading` shows only the spinner, sets `aria-busy="true"` on the main action and keeps its text as its accessible name (visually hidden). The chevron is disabled while it loads, so it leaves the Tab order.
+- With `icon-only`, the main action has no visible text: set `aria-label`, which is forwarded to its `<button>`. The element logs a console warning without one (a `label` is not drawn and does not name it).
+- Each segment shows rel-button's focus ring. A mouse open shows no ring in the menu, and none on the chevron when the menu closes; the first arrow key brings the row ring back.
+
+### Keyboard
+
+| Key | Action |
+| --- | --- |
+| Tab / Shift+Tab | Two Tab stops: the main action, then the chevron |
+| Enter / Space (main action) | Runs the main action (`click`) |
+| Enter / Space / Down (chevron) | Opens the menu on its first entry |
+| Up (chevron) | Opens the menu on its last entry |
+| Down / Up, Home / End (menu) | Moves through the entries |
+| Enter / Space (menu) | Chooses the entry: fires `rel-select`, closes the menu and returns focus to the chevron |
+| Escape (menu) | Closes the menu and returns focus to the chevron |
+| Tab (menu) | Closes the menu and moves focus on |