srcdev-nuxt-components 9.6.18 → 9.6.20

package/app/components/02.molecules/navigation/deep-expanding-menu/stories/DeepExpandingMenu.stories.ts

@@ -1,6 +1,8 @@
+import { computed, ref } from "vue";
 import DeepExpandingMenu from "../DeepExpandingMenu.vue";
+import CanvasSwitcher from "../../../../01.atoms/canvas-switcher/CanvasSwitcher.vue";
 import type { Meta, StoryObj } from "@nuxtjs/storybook";
-import type { ResponsiveHeaderNavItem } from "~/types/components";
+import type { MediaCanvas, ResponsiveHeaderNavItem } from "~/types/components";
 
 const navLinks: ResponsiveHeaderNavItem[] = [
   { name: "Home", path: "/" },
@@ -16,63 +18,181 @@ const navLinks: ResponsiveHeaderNavItem[] = [
   { name: "Contact", path: "/contact" },
 ];
 
-const meta: Meta<typeof DeepExpandingMenu> = {
+const stressNavLinks: ResponsiveHeaderNavItem[] = [
+  { name: "H", path: "/" },
+  {
+    name: "Dienstleistungsangebotsübersichtsseite",
+    childLinksTitle:
+      "Unsere vollständige Übersicht aller Dienstleistungen, Behandlungen und Pflegeangebote für Haut und Haar in Northtown",
+    childLinks: [
+      { name: "Haarschnitt", path: "/services/haircuts" },
+      { name: "https://example.com/a/very/long/unbroken/path/that/never/wraps/on/its/own", path: "/long-url" },
+      { name: "🎨 Colouring", path: "/services/colouring" },
+      { name: "Styling", path: "/services/styling-1" },
+      { name: "Styling", path: "/services/styling-2" },
+      { name: "<b>Not bold</b>", path: "/services/html" },
+      { name: "قص الشعر", path: "/services/rtl" },
+      ...Array.from({ length: 24 }, (_, i) => ({ name: `Treatment ${i + 1}`, path: `/services/treatment-${i + 1}` })),
+    ],
+  },
+  { name: "Gruppe ohne Titel", childLinks: [{ name: "Only link", path: "/only" }] },
+  { name: "Empty group", childLinksTitle: "Nothing here yet", childLinks: [] },
+  { name: "Supercalifragilisticexpialidociousandthensomemoretext", path: "/unbroken" },
+  { name: "🙂", path: "/emoji" },
+  { name: "Contact", path: "/contact" },
+  { name: "Contact", path: "/contact" },
+  {
+    name: "About us and our story",
+    childLinksTitle: "About Alex Morgan",
+    childLinks: [
+      { name: "Team", path: "/about/team" },
+      { name: "History", path: "/about/history" },
+    ],
+  },
+];
+
+type LineClamp = "none" | "1" | "2" | "3";
+
+// Story-only arg: drives a CSS token, not a DeepExpandingMenu prop. See the argTypes entry.
+type StoryArgs = InstanceType<typeof DeepExpandingMenu>["$props"] & {
+  headingLineClamp: LineClamp;
+};
+
+const meta: Meta<StoryArgs> = {
   title: "Molecules/DeepExpandingMenu",
   component: DeepExpandingMenu,
   argTypes: {
+    headingLineClamp: {
+      control: "select",
+      options: ["none", "1", "2", "3"] satisfies LineClamp[],
+      description:
+        "**Story control, not a prop.** Sets the `--deep-expanding-menu-panel-heading-line-clamp` CSS token on a wrapper so you can try it here. " +
+        "To use it in an app, set the token in your own CSS, e.g. `.site-nav { --deep-expanding-menu-panel-heading-line-clamp: 1; }`. " +
+        "`1` is single-line ellipsis, `none` (the default) shows everything.",
+      table: { category: "CSS tokens (story only, set in your CSS)", defaultValue: { summary: "none" } },
+    },
     tag: {
       control: { type: "select" },
-      options: ["div", "section", "nav", "ul", "ol"],
+      options: ["div", "section", "nav"],
       description: "Root element tag",
+      table: { category: "Basic", defaultValue: { summary: "nav" } },
+    },
+    ariaLabel: {
+      control: "text",
+      description: "Accessible name for the root. Set it when the page has more than one `<nav>`",
       table: { category: "Basic" },
     },
-    navLinks: { table: { disable: true } },
+    navLinks: {
+      control: "object",
+      description: "Top-level items: `path` renders a link, `childLinks` renders a toggle and panel",
+      table: { category: "Content" },
+    },
     styleClassPassthrough: { table: { disable: true } },
   },
   args: {
     tag: "nav",
     navLinks,
+    headingLineClamp: "none",
   },
+  decorators: [
+    (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: 2rem; outline: 1px dashed currentColor;">
+          <story />
+        </div>
+      `,
+    }),
+  ],
   parameters: {
+    layout: "fullscreen",
     docs: {
       description: {
         component:
-          "Modern implementation of a top-level nav with expanding child-link panels, using CSS anchor-positioning and the Popover API. See `DeepExpandingMenuClassic` for a `<details>`-based fallback with wider browser support.",
+          "Top-level nav row where each item is a direct link (`path`) or a toggle that opens a panel of child links (`childLinks`, with an optional `childLinksTitle` heading). " +
+          "Built on CSS anchor positioning and the Popover API, with a JS fallback for Safari 16-18. Props: `navLinks`, `tag`, `ariaLabel`. " +
+          "See `DeepExpandingMenuClassic` for the `<details>`-based alternative.",
       },
     },
   },
 };
 
 export default meta;
-type Story = StoryObj<typeof DeepExpandingMenu>;
+type Story = StoryObj<StoryArgs>;
+
+function useStorySetup(args: StoryArgs) {
+  const componentArgs = computed(() => {
+    const { headingLineClamp: _headingLineClamp, ...rest } = args;
+    return rest;
+  });
+  const tokenStyles = computed(() => ({
+    "--deep-expanding-menu-panel-heading-line-clamp": args.headingLineClamp,
+  }));
+  return { componentArgs, tokenStyles };
+}
+
+const render = (args: StoryArgs) => ({
+  components: { DeepExpandingMenu },
+  setup() {
+    return useStorySetup(args);
+  },
+  template: `<div :style="tokenStyles"><DeepExpandingMenu v-bind="componentArgs" /></div>`,
+});
 
 export const Default: Story = {
-  render: (args) => ({
-    components: { DeepExpandingMenu },
-    setup() {
-      return { args };
-    },
-    template: `<DeepExpandingMenu v-bind="args" style="padding: 4rem;" />`,
-  }),
+  render,
 };
 
 export const CustomColours: Story = {
+  name: "Custom Colours",
   render: (args) => ({
     components: { DeepExpandingMenu },
     setup() {
-      return { args };
+      return useStorySetup(args);
     },
     template: `
-      <DeepExpandingMenu
-        v-bind="args"
-        style="padding: 4rem; --deep-expanding-menu-panel-background-colour: #1a1a1a; --deep-expanding-menu-panel-border-colour: transparent; --deep-expanding-menu-group-link-colour: white; --deep-expanding-menu-panel-heading-colour: #aaaaaa;"
-      />
+      <div
+        :style="tokenStyles"
+        style="--deep-expanding-menu-panel-background-colour: #1a1a1a; --deep-expanding-menu-panel-border-colour: transparent; --deep-expanding-menu-group-link-colour: white; --deep-expanding-menu-group-link-border-colour-hover: white; --deep-expanding-menu-panel-heading-colour: #aaaaaa;"
+      >
+        <DeepExpandingMenu v-bind="componentArgs" />
+      </div>
     `,
   }),
   parameters: {
     docs: {
       description: {
-        story: "Overriding the public tokens via inline `--deep-expanding-menu-*` custom properties.",
+        story: "Overriding the public `--deep-expanding-menu-*` tokens on a wrapper element.",
+      },
+    },
+  },
+};
+
+export const StressTest: Story = {
+  name: "Stress Test (Worst-Case Data)",
+  args: {
+    navLinks: stressNavLinks,
+  },
+  render,
+  parameters: {
+    initialCanvas: "mobileCanvas",
+    docs: {
+      story: { inline: false, height: "720px" },
+      description: {
+        story:
+          "Hostile nav data at every `CanvasSwitcher` width. Check that: the top-level row wraps instead of overflowing; " +
+          "the long German label and the unbroken word break inside the canvas; the caret stays beside a wrapped toggle label; " +
+          "the first panel's long heading wraps (try the story-only `headingLineClamp` CSS token control), its unbroken URL link stays inside the panel, " +
+          "`<b>Not bold</b>` renders as text, the right-to-left link reads correctly, and its 31 links scroll inside the panel; " +
+          "duplicate `Styling` and `Contact` items both render; a group without a title shows its list only; " +
+          "an empty group opens with its heading and no list; the last group's panel flips to stay on screen near the right edge.",
       },
     },
   },

package/app/components/02.molecules/navigation/deep-expanding-menu/tests/DeepExpandingMenu.spec.ts

@@ -17,49 +17,62 @@ const defaultNavLinks: ResponsiveHeaderNavItem[] = [
   { name: "Contact", path: "/contact" },
 ];
 
+const mounted: Awaited<ReturnType<typeof mountSuspended>>[] = [];
+
+const mountMenu = async (options: { props?: Record<string, unknown>; attachTo?: HTMLElement } = {}) => {
+  const wrapper = await mountSuspended(DeepExpandingMenu, options);
+  mounted.push(wrapper);
+  return wrapper;
+};
+
+afterEach(() => {
+  mounted.splice(0).forEach((wrapper) => wrapper.unmount());
+  vi.restoreAllMocks();
+});
+
 describe("DeepExpandingMenu", () => {
   it("mounts without error", async () => {
-    const wrapper = await mountSuspended(DeepExpandingMenu, { props: { navLinks: defaultNavLinks } });
+    const wrapper = await mountMenu({ props: { navLinks: defaultNavLinks } });
     expect(wrapper.vm).toBeTruthy();
   });
 
   it("renders correct HTML structure", async () => {
-    const wrapper = await mountSuspended(DeepExpandingMenu, { props: { navLinks: defaultNavLinks } });
+    const wrapper = await mountMenu({ props: { navLinks: defaultNavLinks } });
     expect(wrapper.html()).toMatchSnapshot();
   });
 
   it("renders a <nav> by default", async () => {
-    const wrapper = await mountSuspended(DeepExpandingMenu, { props: { navLinks: defaultNavLinks } });
+    const wrapper = await mountMenu({ props: { navLinks: defaultNavLinks } });
     expect(wrapper.element.tagName.toLowerCase()).toBe("nav");
   });
 
   it("renders the given tag", async () => {
-    const wrapper = await mountSuspended(DeepExpandingMenu, {
+    const wrapper = await mountMenu({
       props: { navLinks: defaultNavLinks, tag: "div" },
     });
     expect(wrapper.element.tagName.toLowerCase()).toBe("div");
   });
 
   it("renders a direct link for items with a path", async () => {
-    const wrapper = await mountSuspended(DeepExpandingMenu, { props: { navLinks: defaultNavLinks } });
-    const links = wrapper.findAll(".navigation-link");
+    const wrapper = await mountMenu({ props: { navLinks: defaultNavLinks } });
+    const links = wrapper.findAll(".deep-expanding-menu-link");
     expect(links.map((l) => l.text())).toEqual(["Home", "Contact"]);
   });
 
   it("renders a toggle group for items with childLinks", async () => {
-    const wrapper = await mountSuspended(DeepExpandingMenu, { props: { navLinks: defaultNavLinks } });
-    expect(wrapper.find(".navigation-group-toggle").text()).toContain("Services");
+    const wrapper = await mountMenu({ props: { navLinks: defaultNavLinks } });
+    expect(wrapper.find(".deep-expanding-menu-group-toggle").text()).toContain("Services");
   });
 
   it("renders each child link inside the group panel", async () => {
-    const wrapper = await mountSuspended(DeepExpandingMenu, { props: { navLinks: defaultNavLinks } });
-    const childLinks = wrapper.findAll(".navigation-group-link");
+    const wrapper = await mountMenu({ props: { navLinks: defaultNavLinks } });
+    const childLinks = wrapper.findAll(".deep-expanding-menu-group-link");
     expect(childLinks.map((l) => l.text())).toEqual(["Haircuts", "Colouring"]);
   });
 
   it("renders the childLinksTitle heading", async () => {
-    const wrapper = await mountSuspended(DeepExpandingMenu, { props: { navLinks: defaultNavLinks } });
-    expect(wrapper.find(".navigation-group-panel h4").text()).toBe("Our services");
+    const wrapper = await mountMenu({ props: { navLinks: defaultNavLinks } });
+    expect(wrapper.find(".deep-expanding-menu-group-heading").text()).toBe("Our services");
   });
 
   it("gives each group toggle a unique popovertarget", async () => {
@@ -67,21 +80,21 @@ describe("DeepExpandingMenu", () => {
       { name: "A", childLinksTitle: "A", childLinks: [{ name: "A1", path: "/a1" }] },
       { name: "B", childLinksTitle: "B", childLinks: [{ name: "B1", path: "/b1" }] },
     ];
-    const wrapper = await mountSuspended(DeepExpandingMenu, { props: { navLinks } });
-    const toggles = wrapper.findAll(".navigation-group-toggle");
+    const wrapper = await mountMenu({ props: { navLinks } });
+    const toggles = wrapper.findAll(".deep-expanding-menu-group-toggle");
     const targets = toggles.map((t) => t.attributes("popovertarget"));
     expect(new Set(targets).size).toBe(2);
   });
 
   it("applies styleClassPassthrough classes", async () => {
-    const wrapper = await mountSuspended(DeepExpandingMenu, {
+    const wrapper = await mountMenu({
       props: { navLinks: defaultNavLinks, styleClassPassthrough: ["custom-class"] },
     });
     expect(wrapper.classes()).toContain("custom-class");
   });
 
   it("resets classes when styleClassPassthrough prop changes", async () => {
-    const wrapper = await mountSuspended(DeepExpandingMenu, {
+    const wrapper = await mountMenu({
       props: { navLinks: defaultNavLinks, styleClassPassthrough: ["initial-class"] },
     });
     expect(wrapper.classes()).toContain("initial-class");
@@ -91,9 +104,60 @@ describe("DeepExpandingMenu", () => {
     expect(wrapper.classes()).toContain("updated-class");
   });
 
+  it("labels the root when ariaLabel is set, and leaves it unlabelled otherwise", async () => {
+    const unlabelled = await mountMenu({ props: { navLinks: defaultNavLinks } });
+    expect(unlabelled.attributes("aria-label")).toBeUndefined();
+
+    const labelled = await mountMenu({
+      props: { navLinks: defaultNavLinks, ariaLabel: "Main" },
+    });
+    expect(labelled.attributes("aria-label")).toBe("Main");
+  });
+
+  it("gives the child link list a list role", async () => {
+    const wrapper = await mountMenu({ props: { navLinks: defaultNavLinks } });
+    expect(wrapper.find(".deep-expanding-menu-group-list").attributes("role")).toBe("list");
+  });
+
+  it("omits the heading when childLinksTitle is missing or empty", async () => {
+    const navLinks: ResponsiveHeaderNavItem[] = [
+      { name: "A", childLinks: [{ name: "A1", path: "/a1" }] },
+      { name: "B", childLinksTitle: "", childLinks: [{ name: "B1", path: "/b1" }] },
+    ];
+    const wrapper = await mountMenu({ props: { navLinks } });
+    expect(wrapper.find(".deep-expanding-menu-group-heading").exists()).toBe(false);
+  });
+
+  it("omits the list when a group has no child links", async () => {
+    const navLinks: ResponsiveHeaderNavItem[] = [{ name: "Empty", childLinksTitle: "Empty", childLinks: [] }];
+    const wrapper = await mountMenu({ props: { navLinks } });
+    expect(wrapper.find(".deep-expanding-menu-group-list").exists()).toBe(false);
+  });
+
+  it("keeps child links with duplicate names in step when the list is reordered", async () => {
+    const childLinks = [
+      { name: "Same", path: "/one" },
+      { name: "Same", path: "/two" },
+      { name: "Other", path: "/three" },
+    ];
+    const wrapper = await mountMenu({
+      props: { navLinks: [{ name: "Group", childLinksTitle: "Group", childLinks }] },
+    });
+    await wrapper.setProps({
+      navLinks: [{ name: "Group", childLinksTitle: "Group", childLinks: [childLinks[2]!, childLinks[0]!] }],
+    });
+    const links = wrapper.findAll(".deep-expanding-menu-group-link");
+    expect(links.map((l) => l.attributes("href"))).toEqual(["/three", "/one"]);
+  });
+
+  it("hides the caret icon from assistive technology", async () => {
+    const wrapper = await mountMenu({ props: { navLinks: defaultNavLinks } });
+    expect(wrapper.find(".deep-expanding-menu-group-icon").attributes("aria-hidden")).toBe("true");
+  });
+
   it("doesn't give the link panels a menu role", async () => {
-    const wrapper = await mountSuspended(DeepExpandingMenu, { props: { navLinks: defaultNavLinks } });
-    expect(wrapper.find(".navigation-group-panel").attributes("role")).toBeUndefined();
+    const wrapper = await mountMenu({ props: { navLinks: defaultNavLinks } });
+    expect(wrapper.find(".deep-expanding-menu-group-panel").attributes("role")).toBeUndefined();
   });
 
   describe("open state", () => {
@@ -116,9 +180,9 @@ describe("DeepExpandingMenu", () => {
       });
 
       it("tracks the open group from toggle events, whichever order they arrive in", async () => {
-        const wrapper = await mountSuspended(DeepExpandingMenu, { props: { navLinks: twoGroups } });
-        const [first, second] = wrapper.findAll(".navigation-group-panel");
-        const toggles = wrapper.findAll(".navigation-group-toggle");
+        const wrapper = await mountMenu({ props: { navLinks: twoGroups } });
+        const [first, second] = wrapper.findAll(".deep-expanding-menu-group-panel");
+        const toggles = wrapper.findAll(".deep-expanding-menu-group-toggle");
 
         first!.element.dispatchEvent(toggleEvent("open"));
         await nextTick();
@@ -142,9 +206,9 @@ describe("DeepExpandingMenu", () => {
       });
 
       it("opens, switches and closes groups from their toggles", async () => {
-        const wrapper = await mountSuspended(DeepExpandingMenu, { props: { navLinks: twoGroups } });
-        const toggles = wrapper.findAll(".navigation-group-toggle");
-        const panels = wrapper.findAll(".navigation-group-panel");
+        const wrapper = await mountMenu({ props: { navLinks: twoGroups } });
+        const toggles = wrapper.findAll(".deep-expanding-menu-group-toggle");
+        const panels = wrapper.findAll(".deep-expanding-menu-group-panel");
 
         await toggles[0]!.trigger("click");
         expect(panels[0]!.classes()).toContain("deep-expanding-menu-panel-open");
@@ -160,14 +224,13 @@ describe("DeepExpandingMenu", () => {
       });
 
       it("closes the open group on Escape", async () => {
-        const wrapper = await mountSuspended(DeepExpandingMenu, { props: { navLinks: twoGroups }, attachTo: document.body });
-        await wrapper.findAll(".navigation-group-toggle")[0]!.trigger("click");
+        const wrapper = await mountMenu({ props: { navLinks: twoGroups }, attachTo: document.body });
+        await wrapper.findAll(".deep-expanding-menu-group-toggle")[0]!.trigger("click");
         await nextTick();
 
         document.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" }));
         await nextTick();
         expect(wrapper.find(".deep-expanding-menu-panel-open").exists()).toBe(false);
-        wrapper.unmount();
       });
     });
   });

package/app/components/02.molecules/navigation/deep-expanding-menu/tests/__snapshots__/DeepExpandingMenu.spec.ts.snap

@@ -2,16 +2,16 @@
 
 exports[`DeepExpandingMenu > renders correct HTML structure 1`] = `
 "<nav class="deep-expanding-menu">
-  <div class="inner"><a href="/" class="navigation-link">Home</a>
-    <div class="navigation-group" style="--_anchor-name: --anchor-v-0-0-1;"><button type="button" popovertarget="popovertarget-v-0-0-1" class="navigation-group-toggle" aria-expanded="false"><span>Services</span><span class="iconify i-bi:caret-down-fill icon" aria-hidden="true"></span></button>
-      <div id="popovertarget-v-0-0-1" class="navigation-group-panel" popover="">
-        <h4 class="page-heading-4 mb-6">Our services</h4>
-        <ul class="navigation-group-list">
-          <li class="navigation-group-item"><a href="/services/haircuts" class="navigation-group-link">Haircuts</a></li>
-          <li class="navigation-group-item"><a href="/services/colouring" class="navigation-group-link">Colouring</a></li>
+  <div class="deep-expanding-menu-inner"><a href="/" class="deep-expanding-menu-link">Home</a>
+    <div class="deep-expanding-menu-group" style="--_anchor-name: --anchor-v-0-0-1;"><button type="button" popovertarget="popovertarget-v-0-0-1" class="deep-expanding-menu-group-toggle" aria-expanded="false"><span class="deep-expanding-menu-group-label">Services</span><span class="iconify i-bi:caret-down-fill deep-expanding-menu-group-icon" aria-hidden="true"></span></button>
+      <div id="popovertarget-v-0-0-1" class="deep-expanding-menu-group-panel" popover="">
+        <h4 class="deep-expanding-menu-group-heading page-heading-4 mb-6">Our services</h4>
+        <ul class="deep-expanding-menu-group-list" role="list">
+          <li class="deep-expanding-menu-group-item"><a href="/services/haircuts" class="deep-expanding-menu-group-link">Haircuts</a></li>
+          <li class="deep-expanding-menu-group-item"><a href="/services/colouring" class="deep-expanding-menu-group-link">Colouring</a></li>
         </ul>
       </div>
-    </div><a href="/contact" class="navigation-link">Contact</a>
+    </div><a href="/contact" class="deep-expanding-menu-link">Contact</a>
   </div>
 </nav>"
 `;

package/app/components/02.molecules/navigation/deep-expanding-menu-classic/CONSUMER-STYLING.md

@@ -2,44 +2,72 @@
 
 ## Public token API
 
+> Changed 2026-10-21: colour defaults now come from `--theme-*` tokens (were `--blue-10`, `white`,
+> `black`, `--slate-10`), `--deep-expanding-menu-classic-panel-offset-top` defaults to
+> `calc(100% + 1rem)` (was `4rem`, which overlapped a wrapped toggle label), the panel widths switch
+> on the menu's own width instead of the viewport, and `--deep-expanding-menu-classic-gap` was
+> removed (the root grid has one area, so it never did anything).
+
+### Top-level row
+
 | Token | Default | Controls |
 |---|---|---|
-| `--deep-expanding-menu-classic-gap` | `1.2rem` | Gap on the root grid |
-| `--deep-expanding-menu-classic-item-gap` | `2.4rem` | Gap between top-level items |
-| `--deep-expanding-menu-classic-link-border-width` | `0.2rem` | Bottom border width on links and group toggles |
+| `--deep-expanding-menu-classic-item-gap` | `2.4rem` | Gap between top-level items (row and column, the row wraps) |
+| `--deep-expanding-menu-classic-link-border-width` | `0.2rem` | Bottom border width on links, group toggles and child links |
 | `--deep-expanding-menu-classic-link-padding-block` | `0.8rem` | Vertical padding on links and group toggles |
-| `--deep-expanding-menu-classic-link-border-colour-hover` | `var(--blue-10)` | Bottom border colour on hover/focus |
+| `--deep-expanding-menu-classic-link-border-colour-hover` | `var(--theme-border)` | Bottom border colour on hover/focus |
+| `--deep-expanding-menu-classic-focus-outline-width` | `0.2rem` | Keyboard focus ring width on links and toggles |
+| `--deep-expanding-menu-classic-focus-outline-colour` | `var(--theme-ring, currentcolor)` | Keyboard focus ring colour |
 | `--deep-expanding-menu-classic-icon-size` | `1.2rem` | Caret icon size |
-| `--deep-expanding-menu-classic-panel-offset-top` | `4rem` | Panel offset from the toggle |
-| `--deep-expanding-menu-classic-panel-width` | `20rem` | Panel width below the `768px` breakpoint |
-| `--deep-expanding-menu-classic-panel-width-tablet` | `40rem` | Panel width from `768px` |
-| `--deep-expanding-menu-classic-panel-width-desktop` | `60rem` | Panel width from `1024px` |
-| `--deep-expanding-menu-classic-panel-background-colour` | `white` | Panel background |
+
+### Panel
+
+| Token | Default | Controls |
+|---|---|---|
+| `--deep-expanding-menu-classic-panel-offset-top` | `calc(100% + 1rem)` | Panel offset from the top of its group |
+| `--deep-expanding-menu-classic-panel-width` | `20rem` | Panel width while the menu is under `768px` wide |
+| `--deep-expanding-menu-classic-panel-width-tablet` | `40rem` | Panel width once the menu is `768px` wide |
+| `--deep-expanding-menu-classic-panel-width-desktop` | `60rem` | Panel width once the menu is `1024px` wide |
+| `--deep-expanding-menu-classic-panel-text-colour` | `var(--theme-text)` | Panel text colour |
+| `--deep-expanding-menu-classic-panel-background-colour` | `var(--theme-surface-subtle)` | Panel background |
 | `--deep-expanding-menu-classic-panel-border-width` | `0.1rem` | Panel border width |
-| `--deep-expanding-menu-classic-panel-border-colour` | `black` | Panel border colour |
+| `--deep-expanding-menu-classic-panel-border-colour` | `var(--theme-border)` | Panel border colour |
 | `--deep-expanding-menu-classic-panel-border-radius` | `1.2rem` | Panel corner radius |
 | `--deep-expanding-menu-classic-panel-shadow` | `0 0 1rem rgba(0, 0, 0, 0.1)` | Panel box-shadow |
 | `--deep-expanding-menu-classic-panel-padding` | `1.2rem` | Panel padding |
-| `--deep-expanding-menu-classic-panel-heading-colour` | `var(--slate-10)` | `childLinksTitle` heading colour inside the panel |
-| `--deep-expanding-menu-classic-panel-list-gap` | `1.2rem` | Gap between child link grid items |
-| `--deep-expanding-menu-classic-group-link-colour` | `var(--slate-10)` | Child link text colour |
-| `--deep-expanding-menu-classic-group-link-border-colour-hover` | `var(--slate-10)` | Child link bottom border colour on hover/focus |
+| `--deep-expanding-menu-classic-panel-heading-colour` | `var(--theme-text)` | `childLinksTitle` heading colour |
+| `--deep-expanding-menu-classic-panel-heading-line-clamp` | `none` | Lines of `childLinksTitle` before an ellipsis. `1` is single-line ellipsis, `none` shows everything |
+| `--deep-expanding-menu-classic-panel-list-gap` | `1.2rem` | Gap between the panel's heading and list, and between child link grid items |
+| `--deep-expanding-menu-classic-group-link-colour` | `var(--theme-text)` | Child link text colour |
+| `--deep-expanding-menu-classic-group-link-border-colour-hover` | `var(--theme-text)` | Child link bottom border colour on hover/focus |
+
+Each panel width is capped at the menu's own width (`min(<token>, 100cqi)`). Private tokens (not
+public API): `--_icon-transform` (caret flip).
+
+## State hooks
 
-```css
-.my-page {
-  --deep-expanding-menu-classic-panel-background-colour: #1a1a1a;
-  --deep-expanding-menu-classic-panel-border-colour: transparent;
-  --deep-expanding-menu-classic-group-link-colour: white;
-}
-```
+| Hook | Meaning |
+|---|---|
+| `.deep-expanding-menu-classic-group[open]` | Group open (flips the caret) |
 
-Or scope to a single instance via `styleClassPassthrough`:
+Inner elements: `.deep-expanding-menu-classic-inner` (the flex row),
+`.deep-expanding-menu-classic-link` (direct link), `.deep-expanding-menu-classic-group` (the
+`<details>`), `.deep-expanding-menu-classic-group-toggle` (the `<summary>`),
+`.deep-expanding-menu-classic-group-label`, `.deep-expanding-menu-classic-group-icon`,
+`.deep-expanding-menu-classic-group-panel`, `.deep-expanding-menu-classic-group-heading`,
+`.deep-expanding-menu-classic-group-list`, `.deep-expanding-menu-classic-group-item`,
+`.deep-expanding-menu-classic-group-link`.
 
-```vue
-<DeepExpandingMenuClassic style-class-passthrough="main-nav">...</DeepExpandingMenuClassic>
-```
+> Changed 2026-10-21: these were `.inner`, `.navigation-link`, `.navigation-group`,
+> `.navigation-group-toggle`, `.icon`, `.navigation-group-panel`, `.navigation-group-list`,
+> `.navigation-group-item` and `.navigation-group-link`. The heading had no class of its own.
 
----
+## Sizing model
+
+The root is an inline-size container named `deep-expanding-menu-classic`, so it can't size itself
+from its content: give it a width from its parent (it fills a block or grid cell by default). A
+panel opens from its toggle's left edge, so a group near the menu's right edge can still overrun it
+by up to the panel's width; `DeepExpandingMenu` flips its panel instead.
 
 ## Local overrides
 
@@ -49,3 +77,7 @@ Set the tokens above on an element you own (a page or section class, or a class
 `<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`.
 
+## Class passthrough
+
+`style-class-passthrough` adds classes to the root element (the `<nav>` by default). It's the
+usual place to scope token overrides to one instance.