srcdev-nuxt-components 9.5.7 → 9.6.1

package/app/components/02.molecules/select-menu/stories/SelectMenu.stories.ts

@@ -1,7 +1,9 @@
-import { ref } from "vue";
+import { computed, ref } from "vue";
 import type { Meta, StoryObj } from "@nuxtjs/storybook";
 import SelectMenu from "../SelectMenu.vue";
+import CanvasSwitcher from "../../../01.atoms/canvas-switcher/CanvasSwitcher.vue";
 import type { SelectMenuOption } from "~/types/components/select-menu";
+import type { MediaCanvas } from "~/types/components";
 
 // ─── Meta ─────────────────────────────────────────────────────────────────────
 
@@ -10,13 +12,18 @@ interface StoryArgs {
   label?: string;
   placeholder?: string;
   showIcon?: boolean;
+  triggerIcon?: string;
+  indicator?: "none" | "count" | "dot";
+  selectedCountLabel?: string;
   showLabel?: boolean;
   showChevron?: boolean;
   multiple?: boolean;
   showSelectionInTrigger?: boolean;
+  reserveLabelWidth?: boolean;
   inputVariant?: "normal" | "underlined";
   modelValue?: string | number | (string | number)[];
   styleClassPassthrough?: string | string[];
+  itemLabelLineClamp?: string;
 }
 
 const meta: Meta<StoryArgs> = {
@@ -35,9 +42,25 @@ const meta: Meta<StoryArgs> = {
     },
     showIcon: {
       control: { type: "boolean" },
-      description: "Show the selected option's icon in the trigger.",
+      description: "Show the leading icon in the trigger: the selected option's icon (single-select), otherwise `triggerIcon`.",
       table: { category: "Trigger content" },
     },
+    triggerIcon: {
+      control: { type: "text" },
+      description: "Fixed leading icon, e.g. a filter category icon. In single-select a selected option's own icon replaces it.",
+      table: { category: "Trigger content" },
+    },
+    indicator: {
+      control: { type: "select" },
+      options: ["none", "count", "dot"],
+      description: "Selection indicator after the trigger text, shown only while something is selected: a count badge or a status dot.",
+      table: { category: "Trigger content" },
+    },
+    selectedCountLabel: {
+      control: { type: "text" },
+      description: "Appended to the trigger's accessible name while the indicator shows. `{count}` is replaced with the number selected.",
+      table: { category: "Content" },
+    },
     showLabel: {
       control: { type: "boolean" },
       description: "Show the selected option's label text in the trigger. Turn off for an icon-only compact trigger.",
@@ -58,6 +81,11 @@ const meta: Meta<StoryArgs> = {
       description: "In multiple mode, update the trigger text to a comma-separated list of the currently checked options instead of leaving it fixed on placeholder/label. No effect outside multiple mode.",
       table: { category: "Content" },
     },
+    reserveLabelWidth: {
+      control: { type: "boolean" },
+      description: "Single-select only. Size the trigger text to the longest option label (or placeholder), so the trigger doesn't change width as the selection changes.",
+      table: { category: "Trigger content" },
+    },
     inputVariant: {
       control: { type: "select" },
       options: ["normal", "underlined"],
@@ -67,10 +95,18 @@ const meta: Meta<StoryArgs> = {
     styleClassPassthrough: {
       table: { disable: true },
     },
+    itemLabelLineClamp: {
+      control: { type: "select" },
+      options: ["none", "1", "2", "3"],
+      description:
+        "**Story control, not a prop.** Sets `--select-menu-item-label-line-clamp` on a wrapper (StressTest only). In your CSS: `.booking-filters { --select-menu-item-label-line-clamp: 2; }`",
+      table: { category: "CSS tokens (story only, set in your CSS)" },
+    },
   },
   args: {
     label: "Language",
     showIcon: true,
+    indicator: "none",
     showLabel: true,
     showChevron: true,
     inputVariant: "normal",
@@ -328,6 +364,75 @@ export const MultiSelectShowingSelection: Story = {
   }),
 };
 
+/**
+ * Filter with a count — a fixed category icon (`triggerIcon`) plus a count
+ * badge (`indicator="count"`) showing how many options are checked. The
+ * badge only appears once something is selected.
+ */
+export const FilterWithCount: Story = {
+  name: "Filter — Icon + Count",
+  args: {
+    label: "Category",
+    multiple: true,
+    triggerIcon: "lucide:list",
+    indicator: "count",
+  },
+  render: (args) => ({
+    components: { SelectMenu },
+    setup() {
+      const value = ref<string[]>(["trim", "layers", "restyle"]);
+      return { args, value, treatmentOptions };
+    },
+    template: `
+      <div style="padding: 4rem 8rem;">
+        <SelectMenu v-bind="args" v-model="value" :options="treatmentOptions" />
+        <p style="margin: 1.6rem 0 0; font-size: 1.3rem; opacity: 0.6;">
+          modelValue: <strong>{{ value.length ? value.join(', ') : '[]' }}</strong>
+        </p>
+      </div>
+    `,
+  }),
+};
+
+/**
+ * Filter with a status dot — single-select with `indicator="dot"`, e.g. a
+ * status filter. The dot signals the filter is active and disappears when the
+ * value is cleared. Each option's `dotColor` colours the trigger dot while
+ * it's selected and shows beside it in the list. `reserveLabelWidth` keeps
+ * the trigger at the width of the longest status, so it doesn't resize between
+ * "Active" and "Archived" (toggle it off in Controls to compare).
+ */
+export const FilterWithDot: Story = {
+  name: "Filter — Icon + Status Dot",
+  args: {
+    label: "Status",
+    triggerIcon: "lucide:circle-dot",
+    indicator: "dot",
+    reserveLabelWidth: true,
+  },
+  render: (args) => ({
+    components: { SelectMenu },
+    setup() {
+      const value = ref<string | undefined>("active");
+      const statusOptions: SelectMenuOption[] = [
+        { value: "active", label: "Active", dotColor: "var(--status-success)" },
+        { value: "pending", label: "Pending", dotColor: "var(--status-warning)" },
+        { value: "archived", label: "Archived", dotColor: "var(--status-neutral)" },
+      ];
+      return { args, value, statusOptions };
+    },
+    template: `
+      <div style="padding: 4rem 8rem;">
+        <SelectMenu v-bind="args" v-model="value" :options="statusOptions" />
+        <p style="margin: 1.6rem 0 0; font-size: 1.3rem; opacity: 0.6;">
+          modelValue: <strong>{{ value === undefined ? 'undefined' : value }}</strong>
+          <button type="button" style="margin-inline-start: 1.2rem;" @click="value = undefined">Clear</button>
+        </p>
+      </div>
+    `,
+  }),
+};
+
 /**
  * Custom tokens — a per-instance styleClassPassthrough overriding the public
  * --select-menu-* tokens to demonstrate full visual customisation.
@@ -392,3 +497,128 @@ export const Underlined: Story = {
     `,
   }),
 };
+
+// ─── Stress test ──────────────────────────────────────────────────────────────
+
+const longUnbroken = "Donaudampfschifffahrtselektrizitätenhauptbetriebswerkbauunterbeamtengesellschaft";
+
+const stressOptions: SelectMenuOption[] = [
+  {
+    value: "long",
+    label:
+      "Full head balayage with toner, Olaplex bond treatment, deep conditioning mask and a blow-dry finish (allow 4 hours)",
+    icon: "lucide:sparkles",
+  },
+  { value: "unbroken", label: longUnbroken },
+  { value: "url", label: "https://example.com/" + "a-very-long-path-segment-without-spaces".repeat(3) },
+  { value: "emoji", label: "🎉 Emoji first option", dotColor: "var(--status-success)" },
+  { value: "html", label: "<b>Not bold</b> <script>alert('x')</script>" },
+  { value: "rtl", label: "قص الشعر وتصفيفه" },
+  { value: "single", label: "A" },
+  { value: "empty", label: "" },
+  { value: "broken-icon", label: "Broken icon name", icon: "lucide:does-not-exist" },
+  { value: "bad-dot", label: "Invalid dot colour", dotColor: "not-a-colour" },
+  ...Array.from({ length: 40 }, (_, index) => ({ value: `extra-${index + 1}`, label: `Option ${index + 1}` })),
+];
+
+/**
+ * Stress test — hostile option data at every canvas width.
+ */
+export const StressTest: Story = {
+  name: "Stress Test (Worst-Case Data)",
+  args: {
+    label: "Behandlung auswählen für Ihren nächsten Termin im Salon (sehr lange Beschriftung)",
+    placeholder: "Bitte wählen Sie eine oder mehrere Behandlungen aus der Liste",
+    indicator: "count",
+    selectedCountLabel: "{count} ausgewählt",
+    itemLabelLineClamp: "none",
+  },
+  render: (args) => ({
+    components: { SelectMenu },
+    setup() {
+      const componentArgs = computed(() => {
+        const { itemLabelLineClamp: _itemLabelLineClamp, ...rest } = args;
+        return rest;
+      });
+      const wrapperStyle = computed(() => ({
+        "--select-menu-item-label-line-clamp": args.itemLabelLineClamp,
+      }));
+      const single = ref<string | undefined>("long");
+      const reserved = ref<string | undefined>("unbroken");
+      const many = ref<string[]>(stressOptions.map((option) => option.value as string));
+      const none = ref<string | undefined>(undefined);
+      return { componentArgs, wrapperStyle, single, reserved, many, none, stressOptions };
+    },
+    template: `
+      <div :style="wrapperStyle" style="display: grid; gap: 2.4rem; padding: 2.4rem 1.6rem;">
+        <section>
+          <h3 style="margin: 0 0 0.8rem;">Single-select, longest option selected</h3>
+          <SelectMenu v-bind="componentArgs" v-model="single" :options="stressOptions" :multiple="false" />
+        </section>
+        <section>
+          <h3 style="margin: 0 0 0.8rem;">Reserved label width, unbroken word selected, status dot</h3>
+          <SelectMenu
+            v-bind="componentArgs"
+            v-model="reserved"
+            :options="stressOptions"
+            :multiple="false"
+            :reserve-label-width="true"
+            indicator="dot"
+          />
+        </section>
+        <section>
+          <h3 style="margin: 0 0 0.8rem;">Multi-select, all 50 checked, selection shown in trigger</h3>
+          <SelectMenu
+            v-bind="componentArgs"
+            v-model="many"
+            :options="stressOptions"
+            :multiple="true"
+            :show-selection-in-trigger="true"
+            trigger-icon="lucide:list-filter"
+          />
+        </section>
+        <section style="display: flex; justify-content: flex-end;">
+          <div>
+            <h3 style="margin: 0 0 0.8rem;">Right-aligned trigger (menu should stay on screen)</h3>
+            <SelectMenu v-bind="componentArgs" v-model="none" :options="stressOptions" :multiple="false" :show-label="false" trigger-icon="lucide:list-filter" />
+          </div>
+        </section>
+        <section>
+          <h3 style="margin: 0 0 0.8rem;">No options</h3>
+          <SelectMenu v-bind="componentArgs" v-model="none" :options="[]" :multiple="false" />
+        </section>
+      </div>
+    `,
+  }),
+  decorators: [
+    (story, context) => ({
+      components: { story, CanvasSwitcher },
+      setup() {
+        const canvasName = ref<MediaCanvas>(context.parameters.initialCanvas ?? "mobileCanvas");
+        return { canvasName };
+      },
+      template: `
+        <div style="padding: 1.2rem 1.6rem; border-block-end: 1px solid currentColor;">
+          <CanvasSwitcher v-model:canvas-name="canvasName" />
+        </div>
+        <div :class="canvasName" style="margin-inline: auto; outline: 1px dashed currentColor;">
+          <story />
+        </div>
+      `,
+    }),
+  ],
+  parameters: {
+    initialCanvas: "mobileCanvas",
+    docs: {
+      description: {
+        story:
+          "Hostile option data: a very long label, an unbroken word, a long URL, emoji first, HTML-like text (must render as text), " +
+          "RTL, a single character, an empty label, a broken icon name, an invalid dot colour, and 50 options in total. " +
+          "Check at every canvas width that each trigger stays inside the canvas with its text truncated by an ellipsis, the count badge " +
+          "and chevron stay visible, the menu never runs off either side of the screen (the right-aligned trigger flips its menu), " +
+          "long options wrap inside the menu, and the list scrolls. `itemLabelLineClamp` is a story-only control for the " +
+          "`--select-menu-item-label-line-clamp` CSS token: try `1` for single-line ellipsis. The empty menu shows just its border.",
+      },
+    },
+  },
+};

package/app/components/02.molecules/select-menu/tests/SelectMenu.spec.ts

@@ -462,6 +462,157 @@ describe("SelectMenu", () => {
     });
   });
 
+  // -------------------------
+  // Trigger icon + indicator
+  // -------------------------
+  describe("Trigger icon and indicator", () => {
+    const plainOptions: SelectMenuOption[] = [
+      { value: "a", label: "Alpha" },
+      { value: "b", label: "Beta" },
+      { value: "c", label: "Gamma" },
+    ];
+
+    it("renders triggerIcon in multiple mode", async () => {
+      wrapper = await createWrapper({ multiple: true, modelValue: [], triggerIcon: "lucide:list" });
+      expect(wrapper.find(".select-menu-trigger-icon").exists()).toBe(true);
+    });
+
+    it("renders triggerIcon in single mode when the selected option has no icon", async () => {
+      wrapper = await createWrapper({ options: plainOptions, modelValue: "a", triggerIcon: "lucide:list" });
+      expect(wrapper.find(".select-menu-trigger-icon").exists()).toBe(true);
+    });
+
+    it("hides triggerIcon when showIcon is false", async () => {
+      wrapper = await createWrapper({ multiple: true, modelValue: [], triggerIcon: "lucide:list", showIcon: false });
+      expect(wrapper.find(".select-menu-trigger-icon").exists()).toBe(false);
+    });
+
+    it("renders no indicator by default", async () => {
+      wrapper = await createWrapper({ multiple: true, modelValue: ["en", "fr"] });
+      expect(wrapper.find(".select-menu-trigger-count").exists()).toBe(false);
+      expect(wrapper.find(".select-menu-trigger-dot").exists()).toBe(false);
+    });
+
+    it("shows the number selected in the count badge", async () => {
+      wrapper = await createWrapper({ multiple: true, modelValue: ["en", "fr"], indicator: "count" });
+      expect(wrapper.find(".select-menu-trigger-count").text()).toBe("2");
+    });
+
+    it("keeps an empty, hidden count badge in the layout when nothing is selected", async () => {
+      wrapper = await createWrapper({ multiple: true, modelValue: [], indicator: "count" });
+      const badge = wrapper.find(".select-menu-trigger-count");
+      expect(badge.exists()).toBe(true);
+      expect(badge.text()).toBe("");
+      expect(badge.classes()).toContain("select-menu-trigger-indicator-empty");
+    });
+
+    it("updates the count badge as options are toggled", async () => {
+      wrapper = await createWrapper({ multiple: true, modelValue: [], indicator: "count" });
+      await wrapper.setProps({ modelValue: ["en", "fr", "de"] });
+      const badge = wrapper.find(".select-menu-trigger-count");
+      expect(badge.text()).toBe("3");
+      expect(badge.classes()).not.toContain("select-menu-trigger-indicator-empty");
+    });
+
+    it("hides the dot, keeping its space, when nothing is selected", async () => {
+      wrapper = await createWrapper({ modelValue: "en", indicator: "dot" });
+      const dot = () => wrapper.find(".select-menu-trigger-dot");
+      expect(dot().classes()).not.toContain("select-menu-trigger-indicator-empty");
+      await wrapper.setProps({ modelValue: undefined });
+      expect(dot().exists()).toBe(true);
+      expect(dot().classes()).toContain("select-menu-trigger-indicator-empty");
+    });
+
+    it("colours the trigger dot with the selected option's dotColor", async () => {
+      const statusOptions: SelectMenuOption[] = [
+        { value: "active", label: "Active", dotColor: "green" },
+        { value: "pending", label: "Pending", dotColor: "orange" },
+      ];
+      wrapper = await createWrapper({ options: statusOptions, modelValue: "active", indicator: "dot" });
+      const dot = () => wrapper.find(".select-menu-trigger-dot").element as HTMLElement;
+      expect(dot().style.getPropertyValue("--_dot-color")).toBe("green");
+      await wrapper.setProps({ modelValue: "pending" });
+      expect(dot().style.getPropertyValue("--_dot-color")).toBe("orange");
+    });
+
+    it("leaves the trigger dot on the token colour when the option has no dotColor", async () => {
+      wrapper = await createWrapper({ options: plainOptions, modelValue: "a", indicator: "dot" });
+      const dot = wrapper.find(".select-menu-trigger-dot").element as HTMLElement;
+      expect(dot.style.getPropertyValue("--_dot-color")).toBe("");
+    });
+
+    it("renders a list dot for options with dotColor and no icon", async () => {
+      wrapper = await createWrapper({
+        options: [
+          { value: "a", label: "Alpha", dotColor: "green" },
+          { value: "b", label: "Beta" },
+          { value: "c", label: "Gamma", icon: "lucide:star", dotColor: "red" },
+        ],
+      });
+      const rows = wrapper.findAll(".select-menu-list-item");
+      const rowDot = rows[0]!.find(".select-menu-item-dot");
+      expect((rowDot.element as HTMLElement).style.getPropertyValue("--_dot-color")).toBe("green");
+      expect(rows[1]!.find(".select-menu-item-dot").exists()).toBe(false);
+      expect(rows[2]!.find(".select-menu-item-dot").exists()).toBe(false);
+    });
+
+    it("hides the indicator from assistive tech", async () => {
+      wrapper = await createWrapper({ multiple: true, modelValue: ["en"], indicator: "count" });
+      expect(wrapper.find(".select-menu-trigger-count").attributes("aria-hidden")).toBe("true");
+    });
+
+    it("appends the selected count to the trigger's accessible name while the indicator shows", async () => {
+      wrapper = await createWrapper({ multiple: true, modelValue: ["en", "fr"], indicator: "count" });
+      expect(wrapper.find(".select-menu-trigger").attributes("aria-label")).toBe("Language, 2 selected");
+    });
+
+    it("uses a custom selectedCountLabel", async () => {
+      wrapper = await createWrapper({
+        multiple: true,
+        modelValue: ["en"],
+        indicator: "count",
+        selectedCountLabel: "{count} sélectionné",
+      });
+      expect(wrapper.find(".select-menu-trigger").attributes("aria-label")).toBe("Language, 1 sélectionné");
+    });
+
+    it("keeps the plain label as the accessible name when nothing is selected", async () => {
+      wrapper = await createWrapper({ multiple: true, modelValue: [], indicator: "count" });
+      expect(wrapper.find(".select-menu-trigger").attributes("aria-label")).toBe("Language");
+    });
+  });
+
+  // -------------------------
+  // reserveLabelWidth
+  // -------------------------
+  describe("reserveLabelWidth", () => {
+    it("renders plain label text by default", async () => {
+      wrapper = await createWrapper({ modelValue: "en" });
+      expect(wrapper.find(".select-menu-trigger-label-sizer").exists()).toBe(false);
+      expect(wrapper.find(".select-menu-trigger-label").text()).toBe("English");
+    });
+
+    it("renders a hidden sizer for the placeholder and every option label", async () => {
+      wrapper = await createWrapper({ modelValue: "en", placeholder: "Pick one", reserveLabelWidth: true });
+      const sizers = wrapper.findAll(".select-menu-trigger-label-sizer");
+      expect(sizers.map((sizer) => sizer.text())).toEqual(["Pick one", "English", "Français", "Deutsch"]);
+      expect(sizers.every((sizer) => sizer.attributes("aria-hidden") === "true")).toBe(true);
+    });
+
+    it("shows the selected label in the visible text span", async () => {
+      wrapper = await createWrapper({ modelValue: "fr", reserveLabelWidth: true });
+      expect(wrapper.find(".select-menu-trigger-label-text").text()).toBe("Français");
+      await wrapper.setProps({ modelValue: "de" });
+      expect(wrapper.find(".select-menu-trigger-label-text").text()).toBe("Deutsch");
+    });
+
+    it("has no effect in multiple mode", async () => {
+      wrapper = await createWrapper({ multiple: true, modelValue: [], reserveLabelWidth: true });
+      expect(wrapper.find(".select-menu-trigger-label").classes()).not.toContain("select-menu-trigger-label-reserved");
+      expect(wrapper.find(".select-menu-trigger-label-sizer").exists()).toBe(false);
+    });
+  });
+
   // -------------------------
   // styleClassPassthrough
   // -------------------------

package/app/components/02.molecules/select-menu/tests/__snapshots__/SelectMenu.spec.ts.snap

@@ -2,7 +2,8 @@
 
 exports[`SelectMenu > Snapshots > default 1`] = `
 "<div class="select-menu normal" style="--_anchor-name: --select-menu-anchor-v-0-0;"><button popovertarget="select-menu-v-0-0" popovertargetaction="toggle" type="button" class="select-menu-trigger" aria-label="Language" aria-haspopup="listbox" aria-expanded="false">
-    <!--v-if--><span class="select-menu-trigger-label">Language</span><span class="iconify i-lucide:chevron-down select-menu-trigger-chevron" aria-hidden="true"></span>
+    <!--v-if--><span class="select-menu-trigger-label">Language</span>
+    <!--v-if--><span class="iconify i-lucide:chevron-down select-menu-trigger-chevron" aria-hidden="true"></span>
   </button>
   <div id="select-menu-v-0-0" popover="" class="select-menu-popover">
     <ul class="select-menu-list" role="listbox" aria-label="Language">
@@ -18,6 +19,7 @@ exports[`SelectMenu > Snapshots > icon-only trigger 1`] = `
 "<div class="select-menu normal" style="--_anchor-name: --select-menu-anchor-v-0-0;"><button popovertarget="select-menu-v-0-0" popovertargetaction="toggle" type="button" class="select-menu-trigger" aria-label="Language" aria-haspopup="listbox" aria-expanded="false"><span class="iconify i-flag:gb-4x3 select-menu-trigger-icon" aria-hidden="true"></span>
     <!--v-if-->
     <!--v-if-->
+    <!--v-if-->
   </button>
   <div id="select-menu-v-0-0" popover="" class="select-menu-popover">
     <ul class="select-menu-list" role="listbox" aria-label="Language">
@@ -30,7 +32,9 @@ exports[`SelectMenu > Snapshots > icon-only trigger 1`] = `
 `;
 
 exports[`SelectMenu > Snapshots > with a selected value 1`] = `
-"<div class="select-menu normal" style="--_anchor-name: --select-menu-anchor-v-0-0;"><button popovertarget="select-menu-v-0-0" popovertargetaction="toggle" type="button" class="select-menu-trigger" aria-label="Language" aria-haspopup="listbox" aria-expanded="false"><span class="iconify i-flag:fr-4x3 select-menu-trigger-icon" aria-hidden="true"></span><span class="select-menu-trigger-label">Français</span><span class="iconify i-lucide:chevron-down select-menu-trigger-chevron" aria-hidden="true"></span></button>
+"<div class="select-menu normal" style="--_anchor-name: --select-menu-anchor-v-0-0;"><button popovertarget="select-menu-v-0-0" popovertargetaction="toggle" type="button" class="select-menu-trigger" aria-label="Language" aria-haspopup="listbox" aria-expanded="false"><span class="iconify i-flag:fr-4x3 select-menu-trigger-icon" aria-hidden="true"></span><span class="select-menu-trigger-label">Français</span>
+    <!--v-if--><span class="iconify i-lucide:chevron-down select-menu-trigger-chevron" aria-hidden="true"></span>
+  </button>
   <div id="select-menu-v-0-0" popover="" class="select-menu-popover">
     <ul class="select-menu-list" role="listbox" aria-label="Language">
       <li class="select-menu-list-item" role="option" tabindex="-1" aria-selected="false" data-label="English"><span class="select-menu-item-check" aria-hidden="true"><!--v-if--></span><span class="iconify i-flag:gb-4x3 select-menu-item-icon" aria-hidden="true"></span><span class="select-menu-item-label">English</span></li>

package/app/components/02.molecules/toast/CONSUMER-STYLING.md

@@ -1,41 +1,105 @@
 # DisplayToast / DisplayToastProvider — Consumer Styling Guide
 
+Both render the toast body with `AlertContent` (or `AlertMaskedContent` when `masked`), so the
+card's colours, radius and accent bar come from `--alert-content-*` tokens: see
+`02.molecules/alert-content/CONSUMER-STYLING.md`. The tokens below cover the toast's own shell.
+
+## Public token API
+
+### DisplayToast (standalone)
+
+| Token | Default | Description |
+|---|---|---|
+| `--display-toast-z-index` | `999999` | Stacking order (see Stacking order). |
+| `--display-toast-max-width` | `min(48rem, 100% - 2 * gutter)` | Maximum toast width. Ignored when `fullWidth` is set. |
+| `--display-toast-progress-colour` | `var(--theme-accent)` | Auto-dismiss progress bar colour. |
+| `--display-toast-focus-ring-colour` | `var(--theme-ring)` | Keyboard focus outline colour. |
+
+### DisplayToastProvider (queue)
+
+| Token | Default | Description |
+|---|---|---|
+| `--display-toast-provider-z-index` | `999999` | Stacking order (see Stacking order). |
+| `--display-toast-provider-max-width` | `min(48rem, 100% - 2 * gutter)` | Maximum width of the toast stack. Ignored when `fullWidth` is set. |
+| `--display-toast-provider-progress-colour` | `var(--theme-accent)` | Auto-dismiss progress bar colour. |
+| `--display-toast-provider-focus-ring-colour` | `var(--theme-ring)` | Keyboard focus outline colour. |
+
+The gutter is `12px` below `600px` viewport width, `24px` above.
+
+> Changed 2026-10-08: the max-width tokens are new. The standalone centred toast used
+> `width: max-content` with no cap, so long text made it wider than the screen; right/left-aligned
+> toasts and the provider stack could stretch almost the full viewport on wide screens. Both now
+> cap at `48rem`. Set the max-width token to `none` (with the gutter still applying) to undo that.
+> The progress and focus-ring colour tokens are also new; they used to read `--theme-accent` and
+> `--theme-ring` directly.
+
+Private tokens, not public API: `--_toast-gutter` and `--_gutter` (the responsive gutter), and the
+provider's `--_reveal` / `--_duration` (set inline per toast from its config).
+
+## State hooks
+
+| Hook | Where | Meaning |
+|---|---|---|
+| `[data-position="top\|bottom"]` | `.display-toast`, `.display-toast-provider` | Vertical position. |
+| `[data-alignment="left\|center\|right\|full-width"]` | `.display-toast`, `.display-toast-provider` | Horizontal alignment; `full-width` when `fullWidth` is set. Below `600px` every toast is centred. |
+| `[data-state="show\|hide"]` | `.display-toast` | Entering or leaving (standalone only; the provider uses `TransitionGroup`'s `v-enter-*`/`v-leave-*` classes). |
+| `[data-paused]` | `.display-toast`, `.display-toast-provider-item` | Auto-dismiss is paused (hovered, or keyboard focus on or inside the toast). Freezes the progress bar. |
+| `[data-theme]` | `.display-toast`, `.display-toast-provider-item` | The toast's semantic theme. |
+
+Inner elements: `.display-toast-progress`, `.display-toast-provider-item`,
+`.display-toast-provider-progress`.
+
+> Changed 2026-10-08: position, alignment and state were bare classes (`.top`, `.left`, `.center`,
+> `.full-width`, `.show`, `.hide`). The toast is teleported into `<body>`, so a consumer's own
+> utility classes with those names (a `.hide { display: none }` especially) could match it. They're
+> `data-*` attributes now; update any selector that used the old classes. The keyframes were
+> renamed for the same reason (`show`, `progress`, `hideTop`, … are now `display-toast-*` and
+> `display-toast-provider-*`).
+
 ## Stacking order
 
-```css
---display-toast-z-index: 999999;          /* DisplayToast (standalone) */
---display-toast-provider-z-index: 999999; /* DisplayToastProvider (queue) */
-```
+Both z-index tokens default to `999999`, matching `DisplayDialog`'s `--display-dialog-z-index`. A
+toast is meant to float above ordinary page chrome (headers, sticky nav). If a toast appears behind
+your site header, your header's z-index is at or above `999999`: raise the toast's token, or (more
+robust) lower the header's z-index. If a `DisplayDialog` and a toast are visible at once, they tie
+on paint order, an acceptable edge case for a transient notification.
 
-Both default to `999999`, matching `DisplayDialog`'s own `--display-dialog-z-index` default — a
-toast is meant to float above ordinary page chrome (headers, sticky nav), so it needs to clear
-whatever z-index a consumer's own layout uses for that. If a toast appears behind your site
-header, your header's z-index is at or above `999999`; either raise the toast's token to match/
-exceed it, or (more robust) lower the header's z-index to something more ordinary — very few
-elements legitimately need to sit above a `dialog`/`alertdialog`.
+## Motion
 
-If a `DisplayDialog` and a toast happen to be visible at the same time, the two tie on DOM/paint
-order at equal z-index — an acceptable edge case for a transient notification, not worth resolving
-with a strict priority order between them.
+Toasts slide in and out over `behavior.revealDuration` (default `550ms`). Under
+`prefers-reduced-motion: reduce` they fade instead, with no slide; the progress bar still runs
+because it shows how long is left.
+
+Auto-dismiss pauses while the pointer is over a toast, or while keyboard focus is on it or inside
+it, and resumes with the time that was left (WCAG 2.2.2). The toast moves focus to itself when
+shown; that only pauses it when the user was using a keyboard (`:focus-visible`), so mouse users
+still get auto-dismiss.
+
+## Global theming
 
 ```css
-/* Global override, e.g. assets/styles/setup/07.components/display-toast.css */
-:root {
-  --display-toast-z-index: 1000000;
-  --display-toast-provider-z-index: 1000000;
+/* e.g. assets/styles/setup/07.components/display-toast.css */
+:where(html) {
+  --display-toast-provider-max-width: min(36rem, 100% - 48px);
+  --display-toast-provider-progress-colour: var(--brand-accent);
 }
 ```
 
----
-
 ## Local overrides
 
-The `--display-toast-z-index` and `--display-toast-provider-z-index` tokens above are only read,
-never declared on the toast, so they work from any ancestor, though a global `:root` value is usually
-what you want for a `position: fixed` overlay. Anything else is a direct property, scoped to an
-element you own (a page or section class, or a class added with `:style-class-passthrough`). Keep
-the block **unlayered** (no `@layer` wrapper) so it beats the library's `@layer components`. If your
-own file uses `<style scoped>`, tokens set on your element still work, but selectors that reach
-inside the component need `:deep()`. Patterns and examples:
-`.claude/skills/component-local-style-override.md`.
+Set the tokens above on an element you own (a page or section class, or a class added with
+`:style-class-passthrough`): they inherit down into the component. Keep the block **unlayered** (no
+`@layer` wrapper) so it beats the library's `@layer components`. If your own file uses
+`<style scoped>`, tokens set on your element still work, but selectors that reach inside the
+component need `:deep()`. Patterns and examples: `.claude/skills/component-local-style-override.md`.
+
+**Caveat:** both components teleport to `<body>`, so they aren't inside your page or section
+elements and can't inherit tokens from them. Set toast tokens globally (`:root` or `:where(html)`),
+or on `DisplayToast` itself via `:style-class-passthrough` (the class lands on the toast element).
+`DisplayToastProvider` has no passthrough, so style it globally or with a `.display-toast-provider`
+selector.
+
+## Class passthrough
 
+`DisplayToast`'s `styleClassPassthrough` adds classes to the teleported `.display-toast` element, so
+it's the way to style one toast instance. `DisplayToastProvider` has none.