srcdev-nuxt-components 9.2.9 → 9.2.11

package/.claude/settings.json

@@ -106,5 +106,19 @@
       "/Users/simoncornforth/websites/nuxt-components/.claude/skills/components",
       "/Users/simoncornforth/websites/nuxt-components/.claude/skills"
     ]
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "f=$(jq -r '.tool_input.file_path // empty'); if [[ \"$f\" == */app/components/*.vue && \"$f\" != */tests/* && \"$f\" != */stories/* ]]; then name=$(basename \"$f\" .vue); skill=$(printf '%s' \"$name\" | sed -E 's/([a-z0-9])([A-Z])/\\1-\\2/g; s/([A-Z]+)([A-Z][a-z])/\\1-\\2/g' | tr '[:upper:]' '[:lower:]'); jq -n --arg msg \"Component file $f was edited/written. Per Claude.md Development Workflow step 7, check whether .claude/skills/components/$skill.md needs updating to reflect this change (props/slots/models/defaults/behaviour).\" '{hookSpecificOutput:{hookEventName:\"PostToolUse\",additionalContext:$msg}}'; fi",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
   }
 }

package/.claude/skills/components/content-docs.md

@@ -36,7 +36,7 @@ interface DocsNavItem {
 | `v-model:activeNavItem` | `string \| undefined` | `undefined` | The `to` of the currently-active `docsNav` item. Updates automatically on click; bind externally (e.g. to route matching) to control it. |
 | `v-model:activePageNavItem` | `string \| undefined` | `undefined` | Same, for `docsPageNav`. |
 
-Open/expanded state of the two panels is **not** exposed as a model — it's driven entirely by the container-width breakpoint logic (see below), not user-controllable.
+Open/expanded state of the two panels is **not** exposed as a model to `ContentDocs`' own consumers — externally it's driven entirely by the container-width breakpoint logic (see below), not user-controllable. Internally, each panel is still a controlled `ExpandingPanel` (`v-model`, not left uncontrolled) so it can be closed programmatically — see "Mobile overlay dismissal" below.
 
 ---
 
@@ -93,6 +93,21 @@ Widths are measured on the component's own root element (`useContainerBreakpoint
 | 768–1023px (tablet) | collapsible, closed by default | **forced open**, no toggle icon |
 | ≥ 1024px (desktop) | **forced open**, no toggle icon | **forced open**, no toggle icon |
 
+Below 1024px (i.e. whenever a panel isn't `forceOpened`), it's also `contentIsOnTop` — an overlay, not in-flow — since a collapsible nav panel pushing page content down/up as it opens reads as janky on mobile/tablet. See "Mobile overlay dismissal" below for how these are closed.
+
+### Mobile overlay dismissal
+
+Below 1024px, `docsNav`/`docsPageNav` are `contentIsOnTop` `ExpandingPanel`s (see the breakpoint table above), so they need an explicit way to close again beyond just toggling the summary:
+
+- **Click outside** — inherited for free from `ExpandingPanel`'s own `contentIsOnTop` behaviour (see `expanding-panel.md`), no extra wiring in `ContentDocs` itself.
+- **Clicking a nav link inside the open panel** — `ContentDocs` does not leave either `ExpandingPanel` uncontrolled: it holds its own `docsNavPanelOpen`/`docsPageNavPanelOpen` refs, bound via `v-model`, and each nav link's click handler sets its panel's ref to `false` in addition to updating `activeNavItem`/`activePageNavItem`. Without this, selecting a link would leave the overlay open on top of the page it just navigated to.
+
+Both are no-ops at desktop/tablet where a panel is `forceOpened` — `open` there is `forceOpened || isPanelOpen`, so `forceOpened` wins regardless of what these refs are set to.
+
+### DOM order vs visual order (accessibility)
+
+In the template, `docsContent` is placed **before** `docsNav`/`docsPageNav` — the reverse of their left-to-right visual position at desktop. This is deliberate: `docsNav`/`docsPageNav` each render an `<h3>` heading (`docsNavLabel`/`docsPageNavLabel`), and if they came first in the DOM, a screen-reader user navigating by heading would hit one of those h3s *before* the consuming page's own `h1` inside `docsContent` — a broken heading outline. Visual position is unaffected because layout comes from `grid-template-areas` (see the `<style>` block), not source order. The trade-off: default Tab order now reaches main content before the side nav — an accepted consequence, not a regression to "fix" back by reverting the order.
+
 ### Why the two panels share a `name` only on mobile
 
 Both panels are `ExpandingPanel`s using the native `<details name="...">` grouping feature, which makes same-named panels mutually exclusive (browser force-closes one when the other opens). That's the wanted behaviour on mobile (accordion — only one open at a time), but at tablet/desktop both panels must be open **simultaneously** — a shared name there would make the browser silently force-close one of them the moment both try to be open. So the component computes distinct names (`"docsNav"` / `"docsPageNav"`) once past mobile, and a shared name (`"docsPanelGroup"`) only while mobile.

package/.claude/skills/components/expanding-panel.md

@@ -13,7 +13,7 @@
 | `name` | `string` | `useId()` | Identifies the panel. Used in ARIA attributes (`id-{name}-trigger`, `id-{name}-content`). If omitted, a unique id is generated automatically. |
 | `animationDuration` | `number` | `400` | Expand/collapse transition duration in milliseconds. Pass `0` to disable animation. |
 | `forceOpened` | `boolean` | `false` | When `true`, the panel is always open. The toggle icon is hidden and clicks do not close the panel. |
-| `contentIsOnTop` | `boolean` | `false` | When `true`, the content region is taken out of flow and absolutely positioned directly below the summary, raised above surrounding page content via `z-index` — instead of pushing layout down when it opens. Applies a `content-is-on-top` class to the root `.expanding-panel` element (not the content div). |
+| `contentIsOnTop` | `boolean` | `false` | When `true`, the content region is taken out of flow and absolutely positioned directly below the summary, raised above surrounding page content via `z-index` — instead of pushing layout down when it opens. Applies a `content-is-on-top` class to the root `.expanding-panel` element (not the content div). Also enables click-outside-to-close (see below) — not applied when `forceOpened` is `true`. |
 | `styleClassPassthrough` | `string \| string[]` | `[]` | Extra CSS classes applied to the root `.expanding-panel` element. |
 
 ## Model
@@ -157,6 +157,14 @@ Why: `.expanding-panel-content` collapses via `grid-template-rows: 0fr → 1fr`,
 
 ---
 
+## Click-outside-to-close (contentIsOnTop only)
+
+When `contentIsOnTop` is `true` and the panel is open, clicking anywhere outside the panel's root element closes it (via `@vueuse/core`'s `onClickOutside`, sets `v-model` to `false`) — matching the dismissal behaviour of a native `<select>` or dropdown menu, since that's what an overlay panel functionally is. This does **not** apply to ordinary in-flow panels (`contentIsOnTop: false`, the default) — an inline accordion staying open when you click elsewhere on the page is expected, not a bug. It also never applies when `forceOpened` is `true`, regardless of `contentIsOnTop` — a forced-open panel isn't dismissible by any interaction.
+
+If you also want the panel to close when something *inside* it is activated (e.g. a nav link) — clicking outside doesn't cover that case — set `v-model` to `false` from that element's own click handler, same as any other controlled usage. See `ContentDocs`' `docsNav`/`docsPageNav` panels for a real example: both are `contentIsOnTop` on mobile, and each nav link closes its panel on click in addition to relying on click-outside.
+
+---
+
 ## CSS Token Customization
 
 All `--expanding-panel-*` tokens can be overridden at global, page, or instance scope. See `CONSUMER-STYLING.md` in the component directory for full token documentation and examples.

package/app/assets/styles/setup/01.config/_head.css

@@ -24,7 +24,6 @@ html {
     color: var(--colour-text-default);
     font-family: var(--font-family);
     font-size: var(--step-4);
-    /* min-height: 100dvh; */
     transition:
       background-color 0.4s ease,
       color 0.4s ease;
@@ -33,12 +32,11 @@ html {
 
     #__nuxt {
       height: 100%;
-      div {
-        .page-layout {
-          min-block-size: 100svh;
-          display: grid;
-          grid-template-rows: auto 1fr auto;
-        }
+      .page-layout {
+        min-block-size: 100svh;
+        display: grid;
+        grid-template-rows: auto 1fr auto;
+        align-items: start;
       }
     }
   }

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

@@ -1,8 +1,12 @@
 <template>
   <component :is="tag" ref="rootEl" class="content-docs" :class="[elementClasses]">
     <div class="content-docs-inner">
+      <div v-if="hasDocsContent" class="docs-content">
+        <slot name="docsContent"></slot>
+      </div>
       <div v-if="hasDocsNav" class="docs-nav">
         <ExpandingPanel
+          v-model="docsNavPanelOpen"
           :name="docsNavPanelName"
           :animation-duration="200"
           :force-opened="docsNavForceOpen"
@@ -21,7 +25,10 @@
                     class="docs-nav-link"
                     :class="{ 'is-active': item.to === activeNavItem }"
                     :aria-current="item.to === activeNavItem ? 'page' : undefined"
-                    @click="activeNavItem = item.to"
+                    @click="
+                      activeNavItem = item.to;
+                      docsNavPanelOpen = false;
+                    "
                   >
                     <Icon v-if="item.icon" :name="item.icon" class="docs-nav-link-icon" aria-hidden="true" />
                     <span class="docs-nav-link-label">{{ item.label }}</span>
@@ -32,11 +39,9 @@
           </template>
         </ExpandingPanel>
       </div>
-      <div v-if="hasDocsContent" class="docs-content">
-        <slot name="docsContent"></slot>
-      </div>
       <div v-if="hasDocsPageNav" class="docs-page-nav">
         <ExpandingPanel
+          v-model="docsPageNavPanelOpen"
           :name="docsPageNavPanelName"
           :animation-duration="200"
           :force-opened="docsPageNavForceOpen"
@@ -55,7 +60,10 @@
                     class="docs-page-nav-link"
                     :class="{ 'is-active': item.to === activePageNavItem }"
                     :aria-current="item.to === activePageNavItem ? 'page' : undefined"
-                    @click="activePageNavItem = item.to"
+                    @click="
+                      activePageNavItem = item.to;
+                      docsPageNavPanelOpen = false;
+                    "
                   >
                     <Icon v-if="item.icon" :name="item.icon" class="docs-page-nav-link-icon" aria-hidden="true" />
                     <span class="docs-page-nav-link-label">{{ item.label }}</span>
@@ -121,9 +129,9 @@ const docsNavOnTop = computed(() => !isDesktop.value);
 const docsPageNavForceOpen = computed(() => !isMobile.value);
 const docsPageNavOnTop = computed(() => isMobile.value);
 
-// Shared `name` groups the two <details> into a mutually-exclusive native accordion —
-// wanted on mobile (neither is forceOpened), wrong on tablet/desktop where both are
-// forceOpened simultaneously: a shared name would make the browser force-close one.
+const docsNavPanelOpen = ref(false);
+const docsPageNavPanelOpen = ref(false);
+
 const panelGroupId = useId();
 const docsNavPanelName = computed(() => (isMobile.value ? panelGroupId : `${panelGroupId}-docsNav`));
 const docsPageNavPanelName = computed(() => (isMobile.value ? panelGroupId : `${panelGroupId}-docsPageNav`));
@@ -132,7 +140,6 @@ const docsPageNavPanelName = computed(() => (isMobile.value ? panelGroupId : `${
 <style lang="css">
 @layer components {
   .content-docs {
-    /* Shared defaults — theme both docsNav and docsPageNav at once */
     --_heading-font-size: var(--content-docs-heading-font-size, 1.4rem);
     --_heading-font-weight: var(--content-docs-heading-font-weight, 700);
     --_heading-color: var(--content-docs-heading-color, light-dark(var(--slate-10), var(--slate-01)));
@@ -146,8 +153,6 @@ const docsPageNavPanelName = computed(() => (isMobile.value ? panelGroupId : `${
     --_panel-padding-inline: var(--content-docs-panel-padding-inline, 0.8rem);
     --_panel-border-radius: var(--content-docs-panel-border-radius, 0.5rem);
 
-    /* Fixed-width grid tracks — the docsNav/docsPageNav columns at tablet/desktop.
-       docsPageNav gets a narrower track at tablet since docsNav is full-width there. */
     --_nav-column-width: var(--content-docs-nav-column-width, 23rem);
     --_page-nav-column-width: var(--content-docs-page-nav-column-width, 22rem);
     --_page-nav-column-width-tablet: var(--content-docs-page-nav-column-width-tablet, 20rem);
@@ -164,7 +169,6 @@ const docsPageNavPanelName = computed(() => (isMobile.value ? panelGroupId : `${
     --_link-active-bg: var(--content-docs-link-active-bg, light-dark(var(--green-01), var(--green-09)));
     --_link-active-color: var(--content-docs-link-active-color, light-dark(var(--green-10), var(--green-04)));
 
-    /* Per-side overrides — each falls back to the shared token above */
     --_nav-heading-font-size: var(--content-docs-nav-heading-font-size, var(--_heading-font-size));
     --_nav-heading-font-weight: var(--content-docs-nav-heading-font-weight, var(--_heading-font-weight));
     --_nav-heading-color: var(--content-docs-nav-heading-color, var(--_heading-color));
@@ -313,15 +317,6 @@ const docsPageNavPanelName = computed(() => (isMobile.value ? panelGroupId : `${
       }
     }
 
-    /* Grid (not flex) so the label column stays aligned at a fixed offset whether or
-       not an item has an icon — an icon-less item's label still starts in column 2,
-       instead of collapsing back to column 1 like it would with flex.
-
-       Icon at the end: set --docs-nav-link-icon-order to rtl. This mirrors which
-       physical side each grid column renders on without touching column sizing —
-       swapping grid-column values directly would leave the label squeezed into the
-       icon-sized track instead. The label/icon direction resets further down undo
-       the mirroring for their own content so text and icon glyphs don't visually flip. */
     .docs-nav-link {
       display: grid;
       grid-template-columns: var(--docs-nav-link-icon-size, 1.6rem) 1fr;

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

@@ -74,6 +74,16 @@ describe("ContentDocs", () => {
     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, {
+      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"]);
+  });
+
   // ─── labels ─────────────────────────────────────────────────────────────
 
   it("defaults docsNavLabel to 'Navigation' and docsPageNavLabel to 'On this page'", async () => {
@@ -142,6 +152,28 @@ describe("ContentDocs", () => {
     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 } });
+
+    await wrapper.find(".docs-nav summary").trigger("click");
+    expect(wrapper.find(".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();
+  });
+
+  it("closes the docsPageNav panel when a link inside it is clicked", async () => {
+    const 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(".docs-page-nav").find("a").trigger("click");
+    expect(wrapper.find(".docs-page-nav details").attributes("open")).toBeUndefined();
+  });
+
   // ─── container-width-driven forceOpened ────────────────────────────────────
 
   describe("breakpoint-driven forceOpened", () => {

package/app/components/02.molecules/expandable/expanding-panel/ExpandingPanel.vue

@@ -1,5 +1,5 @@
 <template>
-  <div class="expanding-panel" :class="[elementClasses, { 'content-is-on-top': contentIsOnTop }]">
+  <div ref="rootEl" class="expanding-panel" :class="[elementClasses, { 'content-is-on-top': contentIsOnTop }]">
     <details class="expanding-panel-details" :name :open @toggle="onDetailsToggle">
       <summary
         :id="`id-${name}-trigger`"
@@ -32,6 +32,8 @@
 </template>
 
 <script setup lang="ts">
+import { onClickOutside } from "@vueuse/core";
+
 interface Props {
   name?: string;
   animationDuration?: number;
@@ -56,6 +58,17 @@ const open = computed(() => props.forceOpened || isPanelOpen.value);
 
 const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
 
+// contentIsOnTop panels behave like a dropdown/overlay (e.g. ContentDocs' mobile nav) rather
+// than an inline accordion — clicking outside is the expected way to dismiss those, matching
+// native <select>/menu behaviour. Not wanted for ordinary accordions (forceOpened is always
+// false here too — a forceOpened panel isn't meant to be dismissible by any interaction).
+const rootEl = ref<HTMLElement | null>(null);
+onClickOutside(rootEl, () => {
+  if (props.contentIsOnTop && !props.forceOpened && isPanelOpen.value) {
+    isPanelOpen.value = false;
+  }
+});
+
 if (import.meta.dev) {
   watch(
     () => props.contentIsOnTop,
@@ -97,10 +110,9 @@ const onDetailsToggle = (event: Event) => {
         cursor: pointer;
       }
       .expanding-panel-summary {
-        display: flex;
+        display: grid;
         align-items: center;
-        justify-content: space-between;
-        flex-direction: row;
+        grid-template-columns: 1fr auto;
         gap: var(--expanding-panel-summary-gap, 1rem);
         list-style: none;
         user-select: none;

package/app/components/02.molecules/expandable/expanding-panel/tests/ExpandingPanel.spec.ts

@@ -427,6 +427,53 @@ describe("ExpandingPanel", () => {
     expect(vm.isPanelOpen).toBe(true);
   });
 
+  it("closes an open contentIsOnTop panel on outside click", async () => {
+    const wrapper = await mountSuspended(ExpandingPanel, {
+      props: { name: "content-on-top-outside-click", contentIsOnTop: true },
+      attachTo: document.body,
+    });
+    const vm = wrapper.vm as unknown as ExpandingPanelInstance;
+
+    await wrapper.find("summary").trigger("click");
+    expect(vm.isPanelOpen).toBe(true);
+
+    document.body.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    await nextTick();
+
+    expect(vm.isPanelOpen).toBe(false);
+    wrapper.unmount();
+  });
+
+  it("does not close on outside click when contentIsOnTop is false (ordinary accordion)", async () => {
+    const wrapper = await mountSuspended(ExpandingPanel, {
+      props: { name: "content-on-top-outside-click-inline" },
+      attachTo: document.body,
+    });
+    const vm = wrapper.vm as unknown as ExpandingPanelInstance;
+
+    await wrapper.find("summary").trigger("click");
+    expect(vm.isPanelOpen).toBe(true);
+
+    document.body.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    await nextTick();
+
+    expect(vm.isPanelOpen).toBe(true);
+    wrapper.unmount();
+  });
+
+  it("does not close a forceOpened contentIsOnTop panel on outside click", async () => {
+    const wrapper = await mountSuspended(ExpandingPanel, {
+      props: { name: "content-on-top-outside-click-forced", contentIsOnTop: true, forceOpened: true },
+      attachTo: document.body,
+    });
+
+    document.body.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    await nextTick();
+
+    expect(wrapper.find("details").attributes("open")).toBeDefined();
+    wrapper.unmount();
+  });
+
   // ─── name prop / useId fallback ───────────────────────────────────────────
 
   it("uses the provided name in ARIA attributes", async () => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "srcdev-nuxt-components",
   "type": "module",
-  "version": "9.2.9",
+  "version": "9.2.11",
   "main": "nuxt.config.ts",
   "types": "types.d.ts",
   "license": "MIT",