srcdev-nuxt-components 9.6.12 → 9.6.14

package/app/components/01.atoms/content-wrappers/docs-pages/stories/ContentDocs.stories.ts

@@ -1,7 +1,8 @@
 import type { Meta, StoryFn } from "@nuxtjs/storybook";
-import { computed } from "vue";
+import { computed, ref } from "vue";
 import ContentDocs from "../ContentDocs.vue";
-import type { DocsNavItem } from "~/types/components";
+import CanvasSwitcher from "../../../canvas-switcher/CanvasSwitcher.vue";
+import type { DocsNavItem, MediaCanvas } from "~/types/components";
 
 interface ContentDocsStoryArgs {
   tag: "div" | "section" | "article" | "main";
@@ -9,6 +10,9 @@ interface ContentDocsStoryArgs {
   docsPageNavItems: DocsNavItem[];
   docsNavLabel: string;
   docsPageNavLabel: string;
+  docsNavAriaLabel: string;
+  docsPageNavAriaLabel: string;
+  panelVariant: "modern" | "classic";
   styleClassPassthrough: string[];
   activeNavItem: string;
   activePageNavItem: string;
@@ -50,11 +54,28 @@ export default {
     docsNavLabel: {
       control: "text",
       description: "Heading text for the docsNav panel",
-      table: { category: "Basic" },
+      table: { category: "Copy" },
     },
     docsPageNavLabel: {
       control: "text",
       description: "Heading text for the docsPageNav panel",
+      table: { category: "Copy" },
+    },
+    docsNavAriaLabel: {
+      control: "text",
+      description: "aria-label on the docsNav `<nav>` landmark. Override for localisation",
+      table: { category: "Copy" },
+    },
+    docsPageNavAriaLabel: {
+      control: "text",
+      description: "aria-label on the docsPageNav `<nav>` landmark. Override for localisation",
+      table: { category: "Copy" },
+    },
+    panelVariant: {
+      control: { type: "select" },
+      options: ["classic", "modern"],
+      description:
+        "Collapsible panel implementation. `classic` (default) works on WebKit; `modern` uses `::details-content`, which Safari drops",
       table: { category: "Basic" },
     },
     styleClassPassthrough: {
@@ -64,12 +85,12 @@ export default {
     },
     activeNavItem: {
       control: "text",
-      description: "The `to` of the currently-active docsNav item",
+      description: "The `to` of the currently-active docsNav item (`v-model:active-nav-item`)",
       table: { category: "Model" },
     },
     activePageNavItem: {
       control: "text",
-      description: "The `to` of the currently-active docsPageNav item",
+      description: "The `to` of the currently-active docsPageNav item (`v-model:active-page-nav-item`)",
       table: { category: "Model" },
     },
   },
@@ -79,10 +100,40 @@ export default {
     docsPageNavItems: defaultPageNavItems,
     docsNavLabel: "Navigation",
     docsPageNavLabel: "On this page",
+    docsNavAriaLabel: "Docs navigation",
+    docsPageNavAriaLabel: "On this page",
+    panelVariant: "classic",
     styleClassPassthrough: [],
     activeNavItem: defaultNavItems[0]?.to,
     activePageNavItem: "",
   },
+  decorators: [
+    // Breakpoints are container queries on the component's own width, so a constrained wrapper stands in for a narrower viewport.
+    (story, context) => ({
+      components: { story, CanvasSwitcher },
+      setup() {
+        const canvasName = ref<MediaCanvas>(context.parameters.initialCanvas ?? "fullWidthCanvas");
+        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; padding: 1.6rem; outline: 1px dashed currentColor;">
+          <story />
+        </div>
+      `,
+    }),
+  ],
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        component:
+          "A three-area docs layout: a site-level `docsNavItems` list, an on-this-page `docsPageNavItems` list, and the `docsContent` slot. Breakpoints follow the component's own width (container queries, mirrored in script): below 768px both navs are collapsible panels that overlay the content, from 768px the page nav is pinned open in a right-hand column, and from 1024px both are pinned open in three columns. The active link in each list is a `v-model` (`activeNavItem`, `activePageNavItem`) and gets `aria-current=\"page\"`. Headings and landmark labels are props for localisation, and `panelVariant` picks the collapsible implementation (`classic` by default, for WebKit).",
+      },
+    },
+  },
 } as Meta<typeof ContentDocs>;
 
 // ─── Stories ─────────────────────────────────────────────────────────────────
@@ -104,39 +155,45 @@ const Template: StoryFn<ContentDocsStoryArgs> = (args) => ({
       <template #docsContent>
         <h3 style="margin-top:0">Docs Content</h3>
         <p>
-          Resize this story's preview panel to see the layout switch between mobile, tablet,
-          and desktop — thresholds are based on the component's own measured width, not the
-          browser viewport, so page decoration elsewhere on a real page won't throw them off.
+          Switch canvas above to see the layout change between mobile, tablet and desktop. The
+          thresholds follow the component's own width, not the browser viewport.
         </p>
       </template>
     </ContentDocs>
   `,
 });
 
+const story = (text: string) => ({ docs: { description: { story: text } } });
+
 export const Default = Template.bind({});
 Default.args = {};
+Default.parameters = story("Both navs with icons on some items, the first docs link active.");
 
 export const NoIcons = Template.bind({});
 NoIcons.args = {
   docsNavItems: defaultNavItems.map(({ icon: _icon, ...item }) => item),
   docsPageNavItems: defaultPageNavItems.map(({ icon: _icon, ...item }) => item),
 };
+NoIcons.parameters = story("No item has an icon: the icon column stays reserved, so labels still line up.");
 
 export const NavOnly = Template.bind({});
 NavOnly.args = {
   docsPageNavItems: [],
 };
+NavOnly.parameters = story("An empty `docsPageNavItems` omits the page nav entirely.");
 
 export const PageNavOnly = Template.bind({});
 PageNavOnly.args = {
   docsNavItems: [],
 };
+PageNavOnly.parameters = story("An empty `docsNavItems` omits the docs nav entirely.");
 
 export const CustomLabels = Template.bind({});
 CustomLabels.args = {
   docsNavLabel: "Sections",
   docsPageNavLabel: "Contents",
 };
+CustomLabels.parameters = story("Custom panel headings via `docsNavLabel` and `docsPageNavLabel`.");
 
 export const IconAtEnd: StoryFn<ContentDocsStoryArgs> = (args) => ({
   components: { ContentDocs },
@@ -169,3 +226,72 @@ export const IconAtEnd: StoryFn<ContentDocsStoryArgs> = (args) => ({
   `,
 });
 IconAtEnd.args = {};
+IconAtEnd.parameters = story(
+  "`--content-docs-nav-link-icon-order: rtl` (and the page-nav equivalent) puts each icon after its label."
+);
+
+const stressNavItems: DocsNavItem[] = [
+  { label: "Bevorzugtekontaktmethodefürrückfragenundterminvereinbarungen", to: "/docs/a", icon: "lucide:rocket" },
+  { label: "https://example.com/a/very/long/path/that/never/breaks/naturally/at/all", to: "/docs/b" },
+  { label: "😀 Emoji first", to: "/docs/c", icon: "lucide:smile" },
+  { label: "<b>not bold</b>", to: "/docs/d" },
+  { label: "طريقة الاتصال المفضلة", to: "/docs/e", icon: "lucide:globe" },
+  { label: "", to: "/docs/f" },
+  { label: "x", to: "/docs/g" },
+  { label: "Duplicate destination", to: "/docs/a" },
+  { label: "Broken icon name", to: "/docs/h", icon: "lucide:does-not-exist" },
+  ...Array.from({ length: 30 }, (_, i) => ({ label: `Generated page ${i + 1}`, to: `/docs/generated-${i + 1}` })),
+];
+
+const stressPageNavItems: DocsNavItem[] = [
+  { label: "Ein sehr langer Abschnittstitel, der in einer schmalen Spalte umbrechen muss", to: "/docs#one" },
+  { label: "Abschnittohneleerzeichendernichtumbrechenkannundtrotzdempassenmuss", to: "/docs#two" },
+  { label: "طريقة الاتصال", to: "/docs#three" },
+];
+
+export const StressTest: StoryFn<ContentDocsStoryArgs> = (args) => ({
+  components: { ContentDocs },
+  setup() {
+    return { args };
+  },
+  template: `
+    <ContentDocs
+      v-bind="args"
+      v-model:active-nav-item="args.activeNavItem"
+      v-model:active-page-nav-item="args.activePageNavItem"
+    >
+      <template #docsContent>
+        <h1 style="margin-top:0">Dokumentationsseitenüberschriftohneleerzeichen</h1>
+        <p>https://example.com/an/unbroken/url/in/the/content/slot/that/would/otherwise/widen/the/middle/column</p>
+        <p>Slot content is the consumer's own markup: the wide table below scrolls in its own wrapper rather than stretching the grid.</p>
+        <div style="overflow-x: auto;">
+          <table style="min-width: 80rem; border-collapse: collapse;">
+            <tr><th style="text-align:start">Prop</th><th style="text-align:start">Type</th><th style="text-align:start">Default</th><th style="text-align:start">Description</th></tr>
+            <tr><td>docsNavItems</td><td>DocsNavItem[]</td><td>[]</td><td>Items rendered in the docs nav panel</td></tr>
+          </table>
+        </div>
+      </template>
+    </ContentDocs>
+  `,
+});
+StressTest.storyName = "Stress Test (Worst-Case Data)";
+StressTest.args = {
+  docsNavItems: stressNavItems,
+  docsPageNavItems: stressPageNavItems,
+  docsNavLabel: "Dokumentationsnavigationüberschriftohneleerzeichen 😀",
+  docsPageNavLabel: "<i>Auf dieser Seite</i>",
+  docsNavAriaLabel: "Dokumentationsnavigation",
+  docsPageNavAriaLabel: "Auf dieser Seite",
+  activeNavItem: "/docs/a",
+  activePageNavItem: "/docs#two",
+};
+StressTest.parameters = {
+  initialCanvas: "mobileCanvas",
+  docs: {
+    story: { inline: false, height: "900px" },
+    description: {
+      story:
+        "39 docs links (unbroken German, a long URL, emoji first, HTML-like and right-to-left labels, an empty label, a one-character label, a duplicate `to`, an unknown icon name) and three page links, with an unbroken heading. Check at every canvas width: unbroken text wraps inside its link and never widens a column, right-to-left labels read and align right-to-left, markup renders as text, both links sharing `/docs/a` show as active, and the unbroken heading and URL in the content slot wrap instead of widening the middle column at tablet and desktop. The empty label renders a thin link with no accessible name: the component can't invent one, so filter empty labels out of your data. Link labels have no line-clamp token on purpose: they name their destinations.",
+    },
+  },
+};

package/app/components/01.atoms/content-wrappers/docs-pages/tests/ContentDocs.spec.ts

@@ -1,5 +1,5 @@
-import { describe, it, expect, vi, beforeEach } from "vitest";
-import { nextTick } from "vue";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { defineComponent, h, nextTick, ref } from "vue";
 import { mountSuspended } from "@nuxt/test-utils/runtime";
 import ContentDocs from "../ContentDocs.vue";
 
@@ -37,67 +37,75 @@ const navItems = [
 const pageNavItems = [{ label: "Overview", to: "/one#overview" }];
 
 describe("ContentDocs", () => {
+  let wrapper: Awaited<ReturnType<typeof mountSuspended>> | undefined;
+
+  afterEach(() => {
+    wrapper?.unmount();
+    wrapper = undefined;
+    vi.restoreAllMocks();
+  });
+
   it("mounts without error", async () => {
-    const wrapper = await mountSuspended(ContentDocs);
+    wrapper = await mountSuspended(ContentDocs);
     expect(wrapper.vm).toBeTruthy();
   });
 
   // ─── docsNav / docsPageNav visibility ──────────────────────────────────────
 
-  it("does not render .docs-nav when docsNavItems is empty", async () => {
-    const wrapper = await mountSuspended(ContentDocs);
-    expect(wrapper.find(".docs-nav").exists()).toBe(false);
+  it("does not render .content-docs-nav when docsNavItems is empty", async () => {
+    wrapper = await mountSuspended(ContentDocs);
+    expect(wrapper.find(".content-docs-nav").exists()).toBe(false);
   });
 
-  it("renders .docs-nav with a link per item when docsNavItems is provided", async () => {
-    const wrapper = await mountSuspended(ContentDocs, { props: { docsNavItems: navItems } });
-    const links = wrapper.find(".docs-nav").findAll("a");
+  it("renders .content-docs-nav with a link per item when docsNavItems is provided", async () => {
+    wrapper = await mountSuspended(ContentDocs, { props: { docsNavItems: navItems } });
+    const links = wrapper.find(".content-docs-nav").findAll("a");
     expect(links).toHaveLength(2);
     expect(links[0]?.text()).toBe("One");
     expect(links[0]?.attributes("href")).toBe("/one");
   });
 
-  it("does not render .docs-page-nav when docsPageNavItems is empty", async () => {
-    const wrapper = await mountSuspended(ContentDocs);
-    expect(wrapper.find(".docs-page-nav").exists()).toBe(false);
+  it("does not render .content-docs-page-nav when docsPageNavItems is empty", async () => {
+    wrapper = await mountSuspended(ContentDocs);
+    expect(wrapper.find(".content-docs-page-nav").exists()).toBe(false);
   });
 
-  it("renders .docs-page-nav with a link per item when docsPageNavItems is provided", async () => {
-    const wrapper = await mountSuspended(ContentDocs, { props: { docsPageNavItems: pageNavItems } });
-    const links = wrapper.find(".docs-page-nav").findAll("a");
+  it("renders .content-docs-page-nav with a link per item when docsPageNavItems is provided", async () => {
+    wrapper = await mountSuspended(ContentDocs, { props: { docsPageNavItems: pageNavItems } });
+    const links = wrapper.find(".content-docs-page-nav").findAll("a");
     expect(links).toHaveLength(1);
     expect(links[0]?.text()).toBe("Overview");
   });
 
   it("renders the docsContent slot", async () => {
-    const wrapper = await mountSuspended(ContentDocs, {
+    wrapper = await mountSuspended(ContentDocs, {
       slots: { docsContent: '<p data-testid="body">Body</p>' },
     });
     expect(wrapper.find('[data-testid="body"]').text()).toBe("Body");
   });
 
   it("places docsContent before docsNav and docsPageNav in DOM order, so a consumer's h1 is reachable before either nav panel's h3 heading (visual position is unaffected — grid-template-areas places all three, not source order)", async () => {
-    const wrapper = await mountSuspended(ContentDocs, {
+    wrapper = await mountSuspended(ContentDocs, {
       props: { docsNavItems: navItems, docsPageNavItems: pageNavItems },
       slots: { docsContent: "<h1>Title</h1>" },
     });
     const inner = wrapper.find(".content-docs-inner").element;
     const children = [...inner.children].map((el) => el.className);
-    expect(children).toEqual(["docs-content", "docs-nav", "docs-page-nav"]);
+    expect(children).toEqual(["content-docs-content", "content-docs-nav", "content-docs-page-nav"]);
   });
 
   // ─── labels ─────────────────────────────────────────────────────────────
 
   it("defaults docsNavLabel to 'Navigation' and docsPageNavLabel to 'On this page'", async () => {
-    const wrapper = await mountSuspended(ContentDocs, {
+    wrapper = await mountSuspended(ContentDocs, {
       props: { docsNavItems: navItems, docsPageNavItems: pageNavItems },
     });
-    expect(wrapper.find(".docs-nav-heading").text()).toBe("Navigation");
-    expect(wrapper.find(".docs-page-nav-heading").text()).toBe("On this page");
+    expect(wrapper.find(".content-docs-nav-heading").text()).toBe("Navigation");
+    expect(wrapper.find(".content-docs-page-nav-heading").text()).toBe("On this page");
   });
 
   it("uses custom docsNavLabel / docsPageNavLabel when provided", async () => {
-    const wrapper = await mountSuspended(ContentDocs, {
+    wrapper = await mountSuspended(ContentDocs, {
       props: {
         docsNavItems: navItems,
         docsPageNavItems: pageNavItems,
@@ -105,111 +113,111 @@ describe("ContentDocs", () => {
         docsPageNavLabel: "Contents",
       },
     });
-    expect(wrapper.find(".docs-nav-heading").text()).toBe("Sections");
-    expect(wrapper.find(".docs-page-nav-heading").text()).toBe("Contents");
+    expect(wrapper.find(".content-docs-nav-heading").text()).toBe("Sections");
+    expect(wrapper.find(".content-docs-page-nav-heading").text()).toBe("Contents");
   });
 
   // ─── icons ──────────────────────────────────────────────────────────────
 
   it("renders an icon on a docsNav item when item.icon is set", async () => {
-    const wrapper = await mountSuspended(ContentDocs, {
+    wrapper = await mountSuspended(ContentDocs, {
       props: { docsNavItems: [{ label: "One", to: "/one", icon: "lucide:home" }] },
     });
-    expect(wrapper.find(".docs-nav-link-icon").exists()).toBe(true);
+    expect(wrapper.find(".content-docs-nav-link-icon").exists()).toBe(true);
   });
 
   it("does not render an icon on a docsNav item when item.icon is omitted", async () => {
-    const wrapper = await mountSuspended(ContentDocs, { props: { docsNavItems: navItems } });
-    expect(wrapper.find(".docs-nav-link-icon").exists()).toBe(false);
+    wrapper = await mountSuspended(ContentDocs, { props: { docsNavItems: navItems } });
+    expect(wrapper.find(".content-docs-nav-link-icon").exists()).toBe(false);
   });
 
   it("renders an icon on a docsPageNav item when item.icon is set", async () => {
-    const wrapper = await mountSuspended(ContentDocs, {
+    wrapper = await mountSuspended(ContentDocs, {
       props: { docsPageNavItems: [{ label: "Overview", to: "/one#overview", icon: "lucide:list" }] },
     });
-    expect(wrapper.find(".docs-page-nav-link-icon").exists()).toBe(true);
+    expect(wrapper.find(".content-docs-page-nav-link-icon").exists()).toBe(true);
   });
 
   // ─── active item ────────────────────────────────────────────────────────
 
-  it("applies is-active and aria-current to the link matching activeNavItem", async () => {
-    const wrapper = await mountSuspended(ContentDocs, {
+  it("sets aria-current='page' only on the link matching activeNavItem", async () => {
+    wrapper = await mountSuspended(ContentDocs, {
       props: { docsNavItems: navItems, activeNavItem: "/two" },
     });
-    const links = wrapper.find(".docs-nav").findAll("a");
-    expect(links[0]?.classes()).not.toContain("is-active");
-    expect(links[1]?.classes()).toContain("is-active");
+    const links = wrapper.find(".content-docs-nav").findAll("a");
+    expect(links[0]?.attributes("aria-current")).toBeUndefined();
     expect(links[1]?.attributes("aria-current")).toBe("page");
+    expect(links[1]?.classes()).not.toContain("is-active");
   });
 
   it("emits update:activeNavItem when a docsNav link is clicked", async () => {
-    const wrapper = await mountSuspended(ContentDocs, { props: { docsNavItems: navItems } });
-    await wrapper.find(".docs-nav").findAll("a")[1]?.trigger("click");
+    wrapper = await mountSuspended(ContentDocs, { props: { docsNavItems: navItems } });
+    await wrapper.find(".content-docs-nav").findAll("a")[1]?.trigger("click");
     expect(wrapper.emitted("update:activeNavItem")?.[0]).toEqual(["/two"]);
   });
 
   it("emits update:activePageNavItem when a docsPageNav link is clicked", async () => {
-    const wrapper = await mountSuspended(ContentDocs, { props: { docsPageNavItems: pageNavItems } });
-    await wrapper.find(".docs-page-nav").find("a").trigger("click");
+    wrapper = await mountSuspended(ContentDocs, { props: { docsPageNavItems: pageNavItems } });
+    await wrapper.find(".content-docs-page-nav").find("a").trigger("click");
     expect(wrapper.emitted("update:activePageNavItem")?.[0]).toEqual(["/one#overview"]);
   });
 
   // ─── closing on link click (mobile overlay behaviour) ─────────────────────
 
   it("closes the docsNav panel when a link inside it is clicked", async () => {
-    const wrapper = await mountSuspended(ContentDocs, { props: { docsNavItems: navItems } });
+    wrapper = await mountSuspended(ContentDocs, { props: { docsNavItems: navItems } });
 
-    await wrapper.find(".docs-nav summary").trigger("click");
-    expect(wrapper.find(".docs-nav details").attributes("open")).toBeDefined();
+    await wrapper.find(".content-docs-nav summary").trigger("click");
+    expect(wrapper.find(".content-docs-nav details").attributes("open")).toBeDefined();
 
-    await wrapper.find(".docs-nav").findAll("a")[0]?.trigger("click");
-    expect(wrapper.find(".docs-nav details").attributes("open")).toBeUndefined();
+    await wrapper.find(".content-docs-nav").findAll("a")[0]?.trigger("click");
+    expect(wrapper.find(".content-docs-nav details").attributes("open")).toBeUndefined();
   });
 
   it("closes the docsPageNav panel when a link inside it is clicked", async () => {
-    const wrapper = await mountSuspended(ContentDocs, { props: { docsPageNavItems: pageNavItems } });
+    wrapper = await mountSuspended(ContentDocs, { props: { docsPageNavItems: pageNavItems } });
 
-    await wrapper.find(".docs-page-nav summary").trigger("click");
-    expect(wrapper.find(".docs-page-nav details").attributes("open")).toBeDefined();
+    await wrapper.find(".content-docs-page-nav summary").trigger("click");
+    expect(wrapper.find(".content-docs-page-nav details").attributes("open")).toBeDefined();
 
-    await wrapper.find(".docs-page-nav").find("a").trigger("click");
-    expect(wrapper.find(".docs-page-nav details").attributes("open")).toBeUndefined();
+    await wrapper.find(".content-docs-page-nav").find("a").trigger("click");
+    expect(wrapper.find(".content-docs-page-nav details").attributes("open")).toBeUndefined();
   });
 
   // ─── container-width-driven forceOpened ────────────────────────────────────
 
   describe("breakpoint-driven forceOpened", () => {
     it("neither panel is forceOpened below 768px (mobile)", async () => {
-      const wrapper = await mountSuspended(ContentDocs, {
+      wrapper = await mountSuspended(ContentDocs, {
         props: { docsNavItems: navItems, docsPageNavItems: pageNavItems },
       });
       triggerResize(wrapper.find(".content-docs").element as HTMLElement, 500);
       await nextTick();
 
-      expect(wrapper.find(".docs-nav .icon-wrapper").exists()).toBe(true);
-      expect(wrapper.find(".docs-page-nav .icon-wrapper").exists()).toBe(true);
+      expect(wrapper.find(".content-docs-nav .icon-wrapper").exists()).toBe(true);
+      expect(wrapper.find(".content-docs-page-nav .icon-wrapper").exists()).toBe(true);
     });
 
     it("only docsPageNav is forceOpened between 768px and 1023px (tablet)", async () => {
-      const wrapper = await mountSuspended(ContentDocs, {
+      wrapper = await mountSuspended(ContentDocs, {
         props: { docsNavItems: navItems, docsPageNavItems: pageNavItems },
       });
       triggerResize(wrapper.find(".content-docs").element as HTMLElement, 900);
       await nextTick();
 
-      expect(wrapper.find(".docs-nav .icon-wrapper").classes()).not.toContain("icon-wrapper--hidden");
-      expect(wrapper.find(".docs-page-nav .icon-wrapper").classes()).toContain("icon-wrapper--hidden");
+      expect(wrapper.find(".content-docs-nav .icon-wrapper").classes()).not.toContain("icon-wrapper--hidden");
+      expect(wrapper.find(".content-docs-page-nav .icon-wrapper").classes()).toContain("icon-wrapper--hidden");
     });
 
     it("both panels are forceOpened at 1024px and above (desktop)", async () => {
-      const wrapper = await mountSuspended(ContentDocs, {
+      wrapper = await mountSuspended(ContentDocs, {
         props: { docsNavItems: navItems, docsPageNavItems: pageNavItems },
       });
       triggerResize(wrapper.find(".content-docs").element as HTMLElement, 1200);
       await nextTick();
 
-      expect(wrapper.find(".docs-nav .icon-wrapper").classes()).toContain("icon-wrapper--hidden");
-      expect(wrapper.find(".docs-page-nav .icon-wrapper").classes()).toContain("icon-wrapper--hidden");
+      expect(wrapper.find(".content-docs-nav .icon-wrapper").classes()).toContain("icon-wrapper--hidden");
+      expect(wrapper.find(".content-docs-page-nav .icon-wrapper").classes()).toContain("icon-wrapper--hidden");
     });
   });
 
@@ -217,34 +225,92 @@ describe("ContentDocs", () => {
 
   describe("panel name grouping", () => {
     it("shares one details name between docsNav and docsPageNav on mobile", async () => {
-      const wrapper = await mountSuspended(ContentDocs, {
+      wrapper = await mountSuspended(ContentDocs, {
         props: { docsNavItems: navItems, docsPageNavItems: pageNavItems },
       });
       triggerResize(wrapper.find(".content-docs").element as HTMLElement, 500);
       await nextTick();
 
-      const navName = wrapper.find(".docs-nav details").attributes("name");
-      const pageNavName = wrapper.find(".docs-page-nav details").attributes("name");
+      const navName = wrapper.find(".content-docs-nav details").attributes("name");
+      const pageNavName = wrapper.find(".content-docs-page-nav details").attributes("name");
       expect(navName).toBe(pageNavName);
     });
 
     it("uses distinct details names on desktop, where both must stay open simultaneously", async () => {
-      const wrapper = await mountSuspended(ContentDocs, {
+      wrapper = await mountSuspended(ContentDocs, {
         props: { docsNavItems: navItems, docsPageNavItems: pageNavItems },
       });
       triggerResize(wrapper.find(".content-docs").element as HTMLElement, 1200);
       await nextTick();
 
-      const navName = wrapper.find(".docs-nav details").attributes("name");
-      const pageNavName = wrapper.find(".docs-page-nav details").attributes("name");
+      const navName = wrapper.find(".content-docs-nav details").attributes("name");
+      const pageNavName = wrapper.find(".content-docs-page-nav details").attributes("name");
       expect(navName).not.toBe(pageNavName);
     });
   });
 
+  // ─── worst-case data and markup ─────────────────────────────────────────
+
+  it("gives both styled lists role=\"list\" so Safari/VoiceOver still announces them", async () => {
+    wrapper = await mountSuspended(ContentDocs, {
+      props: { docsNavItems: navItems, docsPageNavItems: pageNavItems },
+    });
+    const lists = wrapper.findAll("ul");
+    expect(lists).toHaveLength(2);
+    for (const list of lists) expect(list.attributes("role")).toBe("list");
+  });
+
+  it("renders and reorders items that share the same `to`", async () => {
+    wrapper = await mountSuspended(ContentDocs, {
+      props: {
+        docsNavItems: [
+          { label: "First", to: "/same" },
+          { label: "Second", to: "/same" },
+        ],
+      },
+    });
+    const mounted = wrapper;
+    const labels = () => mounted.findAll(".content-docs-nav-link-label").map((el: { text: () => string }) => el.text());
+    expect(labels()).toEqual(["First", "Second"]);
+    await mounted.setProps({
+      docsNavItems: [
+        { label: "Second", to: "/same" },
+        { label: "First", to: "/same" },
+        { label: "Third", to: "/same" },
+      ],
+    });
+    expect(labels()).toEqual(["Second", "First", "Third"]);
+  });
+
+  it("renders HTML-like labels as text", async () => {
+    wrapper = await mountSuspended(ContentDocs, {
+      props: { docsNavItems: [{ label: "<b>not bold</b>", to: "/x" }], docsNavLabel: "<i>x</i>" },
+    });
+    expect(wrapper.find(".content-docs-nav-link-label b").exists()).toBe(false);
+    expect(wrapper.find(".content-docs-nav-link-label").text()).toBe("<b>not bold</b>");
+    expect(wrapper.find(".content-docs-nav-heading i").exists()).toBe(false);
+  });
+
+  it("adds and removes the content area when the docsContent slot is toggled after mount", async () => {
+    const show = ref(false);
+    const Host = defineComponent({
+      setup: () => () =>
+        h(ContentDocs, null, show.value ? { docsContent: () => h("p", { class: "body" }, "Body") } : {}),
+    });
+    wrapper = await mountSuspended(Host);
+    expect(wrapper.find(".content-docs-content").exists()).toBe(false);
+    show.value = true;
+    await nextTick();
+    expect(wrapper.find(".content-docs-content .body").exists()).toBe(true);
+    show.value = false;
+    await nextTick();
+    expect(wrapper.find(".content-docs-content").exists()).toBe(false);
+  });
+
   // ─── styleClassPassthrough ────────────────────────────────────────────────
 
   it("applies styleClassPassthrough classes to the root element", async () => {
-    const wrapper = await mountSuspended(ContentDocs, {
+    wrapper = await mountSuspended(ContentDocs, {
       props: { styleClassPassthrough: ["custom-class"] },
     });
     expect(wrapper.find(".content-docs").classes()).toContain("custom-class");

package/app/components/01.atoms/display-dialog/CONSUMER-STYLING.md

@@ -6,6 +6,9 @@ All `--display-dialog-*` tokens are the stable override surface. Because dialogs
 elements — not inline components — the recommended approach is to set tokens once in a **global CSS
 file** rather than per-instance via `styleClassPassthrough`.
 
+Private tokens (`--_transition-duration`, `--_inner-border-radius`, `--_inner-border`,
+`--_inner-outline`) are not public API: set the public token each one reads instead.
+
 ### Overlay
 
 | Token | Default | Controls |
@@ -36,6 +39,8 @@ file** rather than per-instance via `styleClassPassthrough`.
 | Token | Default | Controls |
 |---|---|---|
 | `--display-dialog-header-padding` | `1.2rem` | Header area padding |
+| `--display-dialog-header-gap` | `1.2rem` | Space between the title and the close button |
+| `--display-dialog-header-accent-color` | `var(--theme-accent)` | Bottom border and close-icon colour when `theme` is set |
 | `--display-dialog-header-button-margin` | `0` | Close button margin |
 | `--display-dialog-header-button-padding` | `0.4rem` | Close button padding |
 | `--display-dialog-header-button-border` | `0.1rem solid transparent` | Close button border (resting) |
@@ -46,6 +51,14 @@ file** rather than per-instance via `styleClassPassthrough`.
 | `--display-dialog-header-button-icon-color` | `var(--colour-text-default)` | Close button icon colour |
 | `--display-dialog-header-button-icon-size` | `2.4rem` | Close button icon size |
 
+The close button is an icon-only `InputButton` (`variant="inline"`), so it renders as
+`.display-dialog-close.input-button`; the `--display-dialog-header-button-*` tokens style it.
+
+> Changed 2026-10-18: the close button was a raw `<button>` and is now an `InputButton`. Its class
+> (`.display-dialog-close`) and tokens are unchanged, so existing overrides still match. A set `theme` now tints the
+> close icon as documented: the tint rule used to lose to the resting icon colour and never applied.
+> `--display-dialog-header-gap` and `--display-dialog-header-accent-color` are new.
+
 ### Content & footer
 
 | Token | Default | Controls |
@@ -64,7 +77,7 @@ file** rather than per-instance via `styleClassPassthrough`.
 | `[justify-dialog="start|center|end"]` | `.display-dialog` | Horizontal placement of the panel |
 | `[align-dialog="start|center|end"]` | `.display-dialog` | Vertical placement of the panel |
 | `.dialog`, `.modal`, `.confirm`, `.alert`, `.fullscreen` | `.display-dialog-inner` | The resolved `variant` |
-| `[data-theme]` | `.display-dialog-header` | A `theme` is set: adds a `--theme-accent` bottom border and title colour |
+| `[data-theme]` | `.display-dialog-header` | A `theme` is set: adds a bottom border and close-icon tint in `--display-dialog-header-accent-color` |
 | `.allow-content-scroll` | `.display-dialog-content` | `allow-content-scroll` is on |
 
 Inner classes: `.display-dialog-inner` (panel), `.display-dialog-header`,
@@ -76,16 +89,28 @@ Inner classes: `.display-dialog-inner` (panel), `.display-dialog-header`,
 > consumer's own unlayered `.header`/`.footer` CSS silently restyled it. Update any overrides
 > written against the old names.
 
+## Sizing
+
+The panel never grows past the overlay: `max-inline-size` and `max-block-size` are `100%`, the
+rows are `auto minmax(0, 1fr) auto`, and the header, content and footer each keep their own row
+(so with no content the footer doesn't stretch into the middle). The title column and content area
+wrap long unbroken text (`overflow-wrap: anywhere`), and the footer wraps its buttons onto further
+rows. Content taller than the panel is clipped, or scrolls with `allow-content-scroll`; the header
+and footer stay visible either way.
+
+> Changed 2026-10-18: `modal` used to grow with its content past the viewport, a long title pushed
+> the close button out of the panel, and footer buttons never wrapped.
+
 ---
 
 ## Global theming
 
 Create `assets/styles/setup/07.components/display-dialog.css` in the consuming app and set tokens
-on `:root`. This applies to every `DisplayDialog` across the site.
+on `:where(html)`. This applies to every `DisplayDialog` across the site.
 
 ```css
 /* assets/styles/setup/07.components/display-dialog.css */
-:root {
+:where(html) {
   --display-dialog-backdrop-background: rgba(0, 0, 0, 0.6);
   --display-dialog-inner-border-radius: 1.2rem;
   --display-dialog-inner-background: var(--brand-surface);