srcdev-nuxt-components 9.2.4 → 9.2.6

package/.vscode/srcdev-component-expanding-panel.code-snippets

@@ -0,0 +1,123 @@
+{
+  "SRCDEV ExpandingPanel Basic": {
+    "description": "Basic uncontrolled ExpandingPanel with summary and content slots",
+    "scope": "vue,html",
+    "body": [
+      "<ExpandingPanel name=\"$1delivery\">",
+      "  <template #summary>",
+      "    <span>$2Delivery &amp; Returns</span>",
+      "  </template>",
+      "  <template #content>",
+      "    <p>$3Free standard delivery on orders over £50.</p>",
+      "  </template>",
+      "</ExpandingPanel>"
+    ]
+  },
+  "SRCDEV ExpandingPanel Controlled": {
+    "description": "ExpandingPanel controlled via v-model with external toggle",
+    "scope": "vue,html",
+    "body": [
+      "<ExpandingPanel name=\"$1faq-1\" v-model=\"$2isOpen\">",
+      "  <template #summary>",
+      "    <span>$3What is your returns policy?</span>",
+      "  </template>",
+      "  <template #content>",
+      "    <p>$4You can return any item within 30 days.</p>",
+      "  </template>",
+      "</ExpandingPanel>"
+    ]
+  },
+  "SRCDEV ExpandingPanel Accordion Group": {
+    "description": "Multiple ExpandingPanels grouped into a native accordion (shared name, only one open at a time)",
+    "scope": "vue,html",
+    "body": [
+      "<ExpandingPanel name=\"$1faq\">",
+      "  <template #summary>",
+      "    <span>$2Question one?</span>",
+      "  </template>",
+      "  <template #content>",
+      "    <p>$3Answer one.</p>",
+      "  </template>",
+      "</ExpandingPanel>",
+      "<ExpandingPanel name=\"$1faq\">",
+      "  <template #summary>",
+      "    <span>$4Question two?</span>",
+      "  </template>",
+      "  <template #content>",
+      "    <p>$5Answer two.</p>",
+      "  </template>",
+      "</ExpandingPanel>"
+    ]
+  },
+  "SRCDEV ExpandingPanel Force Opened": {
+    "description": "ExpandingPanel locked open, no toggle icon, cannot be collapsed",
+    "scope": "vue,html",
+    "body": [
+      "<ExpandingPanel name=\"$1notice\" :force-opened=\"true\">",
+      "  <template #summary>",
+      "    <strong>$2Important notice</strong>",
+      "  </template>",
+      "  <template #content>",
+      "    <p>$3This panel cannot be collapsed.</p>",
+      "  </template>",
+      "</ExpandingPanel>"
+    ]
+  },
+  "SRCDEV ExpandingPanel Content Is On Top": {
+    "description": "ExpandingPanel with content overlaying page content instead of pushing layout down — styling must go on a wrapper INSIDE #content, never on .inner",
+    "scope": "vue,html",
+    "body": [
+      "<ExpandingPanel",
+      "  name=\"$1overlay\"",
+      "  :content-is-on-top=\"true\"",
+      "  :style-class-passthrough=\"['$2my-overlay-panel']\"",
+      ">",
+      "  <template #summary>",
+      "    <span>$3Open me — content overlays what's below</span>",
+      "  </template>",
+      "  <template #content>",
+      "    <!-- Wrapper INSIDE the slot carries background/padding/shadow — never .inner itself,",
+      "         which must stay visually unstyled or it renders while the panel is closed. -->",
+      "    <div class=\"$2my-overlay-panel-body\">",
+      "      <p>$4Positioned absolutely below the summary, doesn't push page content down.</p>",
+      "    </div>",
+      "  </template>",
+      "</ExpandingPanel>"
+    ]
+  },
+  "SRCDEV ExpandingPanel Custom Icon": {
+    "description": "ExpandingPanel with a custom toggle icon via #icon slot",
+    "scope": "vue,html",
+    "body": [
+      "<ExpandingPanel name=\"$1custom-icon\">",
+      "  <template #summary>",
+      "    <span>$2Section title</span>",
+      "  </template>",
+      "  <template #icon>",
+      "    <span style=\"font-size:1.2rem\">$3+</span>",
+      "  </template>",
+      "  <template #content>",
+      "    <p>$4Content here.</p>",
+      "  </template>",
+      "</ExpandingPanel>"
+    ]
+  },
+  "SRCDEV ExpandingPanel CSS Override": {
+    "description": "CSS override scaffold for ExpandingPanel tokens",
+    "scope": "css",
+    "body": [
+      ".$1my-panel {",
+      "  .expanding-panel {",
+      "    --expanding-panel-summary-gap: $2;",
+      "    --expanding-panel-summary-padding-block: $3;",
+      "    --expanding-panel-icon-size: $4;",
+      "",
+      "    &.content-is-on-top {",
+      "      --expanding-panel-content-gap: $5;",
+      "      --expanding-panel-content-z-index: $6;",
+      "    }",
+      "  }",
+      "}"
+    ]
+  }
+}

package/README.md

@@ -43,16 +43,22 @@ Skills are copied into `.claude/skills/srcdev-nuxt-components/` so they never co
 
 ### Automate with postinstall (recommended)
 
-To ensure skills are always up to date and `nuxt prepare` is never forgotten, combine both into a `postinstall` script. npm runs this automatically after every `npm install`:
+To ensure skills are always up to date, VSCode snippets are installed, and `nuxt prepare` is never forgotten, add a `postinstall` script. npm runs this automatically after every `npm install`:
 
 ```json
 "scripts": {
-  "setup:claude": "cp -r node_modules/srcdev-nuxt-components/.claude/skills .claude/skills/srcdev-nuxt-components",
-  "postinstall": "nuxt prepare && npm run setup:claude"
+  "setup:claude": "mkdir -p .claude/skills/srcdev-nuxt-components && cp -r node_modules/srcdev-nuxt-components/.claude/skills/. .claude/skills/srcdev-nuxt-components",
+  "postinstall": "node node_modules/srcdev-nuxt-components/scripts/copy-snippets.mjs && nuxt prepare && npm run setup:claude"
 }
 ```
 
-> If your app uses a standalone env flag for `nuxt prepare` (e.g. `NUXT_STANDALONE=true`), include it in the `postinstall` command. This is project-specific — check your own `nuxt.config.ts` to confirm whether it is needed.
+**What this does:**
+
+1. `copy-snippets.mjs` — copies VSCode snippets (`.code-snippets` files) from the layer to your `.vscode/` folder
+2. `nuxt prepare` — generates Nuxt type declarations
+3. `setup:claude` — copies skills into `.claude/skills/srcdev-nuxt-components/`
+
+> **Note**: The snippet copy must run from your consumer app's postinstall, not the layer's. npm doesn't invoke postinstall hooks for dependencies, so each consumer app is responsible for copying snippets into its own `.vscode/` folder. If your app uses a standalone env flag for `nuxt prepare` (e.g. `NUXT_STANDALONE=true`), add it before `nuxt prepare`. This is project-specific — check your own `nuxt.config.ts` to confirm whether it is needed.
 
 ---
 

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

@@ -0,0 +1,410 @@
+<template>
+  <component :is="tag" ref="rootEl" class="content-docs" :class="[elementClasses]">
+    <div class="content-docs-inner">
+      <div v-if="hasDocsNav" class="docs-nav">
+        <ExpandingPanel
+          :name="docsNavPanelName"
+          :animation-duration="200"
+          :force-opened="docsNavForceOpen"
+          :content-is-on-top="docsNavOnTop"
+        >
+          <template #summary>
+            <h3 class="docs-nav-heading">{{ docsNavLabel }}</h3>
+          </template>
+          <template #content>
+            <nav class="docs-nav-list" aria-label="Docs navigation">
+              <ul>
+                <li v-for="item in docsNavItems" :key="item.to">
+                  <component
+                    :is="NuxtLink"
+                    :to="item.to"
+                    class="docs-nav-link"
+                    :class="{ 'is-active': item.to === activeNavItem }"
+                    :aria-current="item.to === activeNavItem ? 'page' : undefined"
+                    @click="activeNavItem = item.to"
+                  >
+                    <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>
+                  </component>
+                </li>
+              </ul>
+            </nav>
+          </template>
+        </ExpandingPanel>
+      </div>
+      <div v-if="hasDocsContent" class="docs-content">
+        <slot name="docsContent"></slot>
+      </div>
+      <div v-if="hasDocsPageNav" class="docs-page-nav">
+        <ExpandingPanel
+          :name="docsPageNavPanelName"
+          :animation-duration="200"
+          :force-opened="docsPageNavForceOpen"
+          :content-is-on-top="docsPageNavOnTop"
+        >
+          <template #summary>
+            <h3 class="docs-page-nav-heading">{{ docsPageNavLabel }}</h3>
+          </template>
+          <template #content>
+            <nav class="docs-page-nav-list" aria-label="On this page">
+              <ul>
+                <li v-for="item in docsPageNavItems" :key="item.to">
+                  <component
+                    :is="NuxtLink"
+                    :to="item.to"
+                    class="docs-page-nav-link"
+                    :class="{ 'is-active': item.to === activePageNavItem }"
+                    :aria-current="item.to === activePageNavItem ? 'page' : undefined"
+                    @click="activePageNavItem = item.to"
+                  >
+                    <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>
+                  </component>
+                </li>
+              </ul>
+            </nav>
+          </template>
+        </ExpandingPanel>
+      </div>
+    </div>
+  </component>
+</template>
+
+<script setup lang="ts">
+import type { DocsNavItem } from "~/types/components";
+
+interface Props {
+  tag?: "div" | "section" | "article" | "main";
+  docsNavItems?: DocsNavItem[];
+  docsPageNavItems?: DocsNavItem[];
+  docsNavLabel?: string;
+  docsPageNavLabel?: string;
+  styleClassPassthrough?: string | string[];
+}
+const props = withDefaults(defineProps<Props>(), {
+  tag: "div",
+  docsNavItems: () => [],
+  docsPageNavItems: () => [],
+  docsNavLabel: "Navigation",
+  docsPageNavLabel: "On this page",
+  styleClassPassthrough: () => [],
+});
+
+const activeNavItem = defineModel<string | undefined>("activeNavItem");
+const activePageNavItem = defineModel<string | undefined>("activePageNavItem");
+
+const NuxtLink = resolveComponent("NuxtLink");
+
+const slots = useSlots();
+const hasDocsNav = computed(() => props.docsNavItems.length > 0);
+const hasDocsContent = computed(() => !!slots.docsContent);
+const hasDocsPageNav = computed(() => props.docsPageNavItems.length > 0);
+
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+watch(
+  () => props.styleClassPassthrough,
+  () => {
+    resetElementClasses(props.styleClassPassthrough);
+  }
+);
+
+// Breakpoints match this component's own @container queries below —
+// keep both in sync if either changes.
+const rootEl = ref<HTMLElement | null>(null);
+const { greaterOrEqual, smaller } = useContainerBreakpoints({ tablet: 768, desktop: 1024 }, rootEl);
+const isDesktop = greaterOrEqual("desktop");
+const isMobile = smaller("tablet");
+
+const docsNavForceOpen = computed(() => isDesktop.value);
+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 panelGroupId = useId();
+const docsNavPanelName = computed(() => (isMobile.value ? panelGroupId : `${panelGroupId}-docsNav`));
+const docsPageNavPanelName = computed(() => (isMobile.value ? panelGroupId : `${panelGroupId}-docsPageNav`));
+</script>
+
+<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)));
+    --_heading-bg: var(--content-docs-heading-bg, transparent);
+    --_heading-margin: var(--content-docs-heading-margin, 0);
+    --_heading-padding-block: var(--content-docs-heading-padding-block, 0.4rem 0.8rem);
+    --_heading-padding-inline: var(--content-docs-heading-padding-inline, 0);
+
+    --_panel-bg: var(--content-docs-panel-bg, light-dark(var(--slate-00), var(--slate-10)));
+    --_panel-padding-block: var(--content-docs-panel-padding-block, 0.8rem);
+    --_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);
+
+    --_link-font-size: var(--content-docs-link-font-size, 1.4rem);
+    --_link-padding-block: var(--content-docs-link-padding-block, 0.6rem);
+    --_link-padding-inline: var(--content-docs-link-padding-inline, 0.8rem);
+    --_link-margin-block: var(--content-docs-link-margin-block, 0);
+    --_link-border-radius: var(--content-docs-link-border-radius, 0.4rem);
+    --_link-color: var(--content-docs-link-color, light-dark(var(--slate-09), var(--slate-01)));
+    --_link-bg: var(--content-docs-link-bg, transparent);
+    --_link-hover-bg: var(--content-docs-link-hover-bg, light-dark(var(--slate-01), var(--slate-09)));
+    --_link-hover-color: var(--content-docs-link-hover-color, var(--_link-color));
+    --_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));
+    --_nav-heading-bg: var(--content-docs-nav-heading-bg, var(--_heading-bg));
+    --_nav-heading-margin: var(--content-docs-nav-heading-margin, var(--_heading-margin));
+    --_nav-heading-padding-block: var(--content-docs-nav-heading-padding-block, var(--_heading-padding-block));
+    --_nav-heading-padding-inline: var(--content-docs-nav-heading-padding-inline, var(--_heading-padding-inline));
+
+    --_page-nav-heading-font-size: var(--content-docs-page-nav-heading-font-size, var(--_heading-font-size));
+    --_page-nav-heading-font-weight: var(--content-docs-page-nav-heading-font-weight, var(--_heading-font-weight));
+    --_page-nav-heading-color: var(--content-docs-page-nav-heading-color, var(--_heading-color));
+    --_page-nav-heading-bg: var(--content-docs-page-nav-heading-bg, var(--_heading-bg));
+    --_page-nav-heading-margin: var(--content-docs-page-nav-heading-margin, var(--_heading-margin));
+    --_page-nav-heading-padding-block: var(
+      --content-docs-page-nav-heading-padding-block,
+      var(--_heading-padding-block)
+    );
+    --_page-nav-heading-padding-inline: var(
+      --content-docs-page-nav-heading-padding-inline,
+      var(--_heading-padding-inline)
+    );
+
+    --_nav-panel-bg: var(--content-docs-nav-panel-bg, var(--_panel-bg));
+    --_page-nav-panel-bg: var(--content-docs-page-nav-panel-bg, var(--_panel-bg));
+
+    --_nav-link-color: var(--content-docs-nav-link-color, var(--_link-color));
+    --_nav-link-hover-bg: var(--content-docs-nav-link-hover-bg, var(--_link-hover-bg));
+    --_nav-link-hover-color: var(--content-docs-nav-link-hover-color, var(--_link-hover-color));
+    --_nav-link-active-bg: var(--content-docs-nav-link-active-bg, var(--_link-active-bg));
+    --_nav-link-active-color: var(--content-docs-nav-link-active-color, var(--_link-active-color));
+
+    --_page-nav-link-color: var(--content-docs-page-nav-link-color, var(--_link-color));
+    --_page-nav-link-hover-bg: var(--content-docs-page-nav-link-hover-bg, var(--_link-hover-bg));
+    --_page-nav-link-hover-color: var(--content-docs-page-nav-link-hover-color, var(--_link-hover-color));
+    --_page-nav-link-active-bg: var(--content-docs-page-nav-link-active-bg, var(--_link-active-bg));
+    --_page-nav-link-active-color: var(--content-docs-page-nav-link-active-color, var(--_link-active-color));
+
+    container-type: inline-size;
+    container-name: contentDocs;
+
+    .content-docs-inner {
+      display: grid;
+      grid-template-areas:
+        "docsNav"
+        "docsPageNav"
+        "docsContent";
+      gap: 1.6rem;
+      align-items: start;
+
+      @container contentDocs (width >= 768px) {
+        grid-template-areas:
+          "docsNav docsPageNav"
+          "docsContent docsPageNav";
+        gap: 1.6rem;
+        grid-template-columns: 1fr var(--_page-nav-column-width-tablet);
+        grid-template-rows: auto 1fr;
+      }
+
+      @container contentDocs (width >= 1024px) {
+        grid-template-areas: "docsNav docsContent  docsPageNav";
+        gap: 1.6rem;
+        grid-template-columns: var(--_nav-column-width) 1fr var(--_page-nav-column-width);
+      }
+
+      .docs-nav {
+        grid-area: docsNav;
+        align-items: start;
+
+        @container contentDocs (width >= 1024px) {
+          .expanding-panel {
+            & .expanding-panel-details {
+              .expanding-panel-summary {
+                cursor: default;
+              }
+            }
+          }
+        }
+      }
+      .docs-content {
+        grid-area: docsContent;
+        align-items: start;
+      }
+      .docs-page-nav {
+        grid-area: docsPageNav;
+        align-items: start;
+
+        @container contentDocs (width >= 768px) {
+          .expanding-panel {
+            & .expanding-panel-details {
+              .expanding-panel-summary {
+                cursor: default;
+              }
+            }
+          }
+        }
+      }
+    }
+
+    .docs-nav-heading {
+      font-size: var(--_nav-heading-font-size);
+      font-weight: var(--_nav-heading-font-weight);
+      color: var(--_nav-heading-color);
+      background-color: var(--_nav-heading-bg);
+      margin: var(--_nav-heading-margin);
+      padding-block: var(--_nav-heading-padding-block);
+      padding-inline: var(--_nav-heading-padding-inline);
+    }
+    .docs-page-nav-heading {
+      font-size: var(--_page-nav-heading-font-size);
+      font-weight: var(--_page-nav-heading-font-weight);
+      color: var(--_page-nav-heading-color);
+      background-color: var(--_page-nav-heading-bg);
+      margin: var(--_page-nav-heading-margin);
+      padding-block: var(--_page-nav-heading-padding-block);
+      padding-inline: var(--_page-nav-heading-padding-inline);
+    }
+
+    .docs-nav-list {
+      border-radius: var(--_panel-border-radius);
+      padding-block: var(--_panel-padding-block);
+      padding-inline: var(--_panel-padding-inline);
+      background-color: var(--_nav-panel-bg);
+
+      ul {
+        list-style: none;
+        margin: 0;
+        padding: 0;
+        display: flex;
+        flex-direction: column;
+        gap: 0.4rem;
+      }
+    }
+    .docs-page-nav-list {
+      border-radius: var(--_panel-border-radius);
+      padding-block: var(--_panel-padding-block);
+      padding-inline: var(--_panel-padding-inline);
+      background-color: var(--_page-nav-panel-bg);
+
+      ul {
+        list-style: none;
+        margin: 0;
+        padding: 0;
+        display: flex;
+        flex-direction: column;
+        gap: 0.4rem;
+      }
+    }
+
+    /* 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;
+      align-items: center;
+      gap: var(--docs-nav-link-icon-gap, 0.6rem);
+      border-radius: var(--_link-border-radius);
+      font-size: var(--_link-font-size);
+      padding-block: var(--_link-padding-block);
+      padding-inline: var(--_link-padding-inline);
+      margin-block: var(--_link-margin-block);
+      background-color: var(--_link-bg);
+      text-decoration: none;
+      direction: var(--docs-nav-link-icon-order, ltr);
+      color: var(--_nav-link-color);
+      transition:
+        background-color var(--control-transition-duration, 200ms) var(--control-transition-ease, ease),
+        color var(--control-transition-duration, 200ms) var(--control-transition-ease, ease);
+
+      &:focus-visible {
+        outline: 0.2rem solid var(--theme-ring, currentcolor);
+        outline-offset: -0.2rem;
+      }
+
+      &:hover {
+        background-color: var(--_nav-link-hover-bg);
+        color: var(--_nav-link-hover-color);
+      }
+
+      &.is-active {
+        background-color: var(--_nav-link-active-bg);
+        color: var(--_nav-link-active-color);
+        font-weight: 600;
+      }
+    }
+    .docs-page-nav-link {
+      display: grid;
+      grid-template-columns: var(--docs-nav-link-icon-size, 1.6rem) 1fr;
+      align-items: center;
+      gap: var(--docs-nav-link-icon-gap, 0.6rem);
+      border-radius: var(--_link-border-radius);
+      font-size: var(--_link-font-size);
+      padding-block: var(--_link-padding-block);
+      padding-inline: var(--_link-padding-inline);
+      margin-block: var(--_link-margin-block);
+      background-color: var(--_link-bg);
+      text-decoration: none;
+      direction: var(--docs-page-nav-link-icon-order, ltr);
+      color: var(--_page-nav-link-color);
+      transition:
+        background-color var(--control-transition-duration, 200ms) var(--control-transition-ease, ease),
+        color var(--control-transition-duration, 200ms) var(--control-transition-ease, ease);
+
+      &:focus-visible {
+        outline: 0.2rem solid var(--theme-ring, currentcolor);
+        outline-offset: -0.2rem;
+      }
+
+      &:hover {
+        background-color: var(--_page-nav-link-hover-bg);
+        color: var(--_page-nav-link-hover-color);
+      }
+
+      &.is-active {
+        background-color: var(--_page-nav-link-active-bg);
+        color: var(--_page-nav-link-active-color);
+        font-weight: 600;
+      }
+    }
+
+    .docs-nav-link-icon,
+    .docs-page-nav-link-icon {
+      grid-column: 1;
+      direction: ltr;
+      flex-shrink: 0;
+      width: var(--docs-nav-link-icon-size, 1.6rem);
+      height: var(--docs-nav-link-icon-size, 1.6rem);
+    }
+
+    .docs-nav-link-label,
+    .docs-page-nav-link-label {
+      grid-column: 2;
+      direction: ltr;
+    }
+  }
+}
+</style>

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

@@ -0,0 +1,53 @@
+import { test, expect, type Page } from "@playwright/test";
+
+// --- Config ---
+const STORYBOOK_URL = "http://127.0.0.1:6006";
+const STORY_BASE = "atoms-content-wrappers-contentdocs";
+const ELEMENT_TIMEOUT = 15_000;
+
+// --- Helpers ---
+const getStoryUrl = (story: string): string => `${STORYBOOK_URL}/?path=/story/${STORY_BASE}--${story}`;
+
+const getElement = async (page: Page, story: string, viewport?: { width: number; height: number }) => {
+  if (viewport) await page.setViewportSize(viewport);
+  await page.goto(getStoryUrl(story), { waitUntil: "load" });
+  const frame = page.frameLocator("#storybook-preview-iframe");
+  await frame.locator("#storybook-root > *").waitFor({ state: "visible", timeout: ELEMENT_TIMEOUT });
+  const el = frame.locator(".content-docs");
+  await el.waitFor({ state: "visible", timeout: ELEMENT_TIMEOUT });
+  return el;
+};
+
+// -------------------------
+// Baseline (default story, default args)
+// -------------------------
+test.describe("ContentDocs — baseline", () => {
+  test("default matches snapshot", async ({ page }) => {
+    const el = await getElement(page, "default");
+    await expect(el).toHaveScreenshot("default.png");
+  });
+});
+
+// -------------------------
+// Breakpoint states — docsNav (toggleable) and docsPageNav (forceOpened) summary
+// rows must render at the same height so their content columns start aligned.
+// See ExpandingPanel's icon-wrapper--hidden fix: the icon-wrapper is always kept
+// in the DOM (not v-if'd away) so a forceOpened panel's row doesn't shrink relative
+// to a toggleable sibling's.
+// -------------------------
+test.describe("ContentDocs — breakpoint states", () => {
+  test("tablet: docsNav toggleable + docsPageNav forceOpened stay row-aligned", async ({ page }) => {
+    const el = await getElement(page, "default", { width: 1300, height: 700 });
+    await expect(el).toHaveScreenshot("state-tablet.png");
+  });
+
+  test("desktop: both panels forceOpened", async ({ page }) => {
+    const el = await getElement(page, "default", { width: 1800, height: 700 });
+    await expect(el).toHaveScreenshot("state-desktop.png");
+  });
+
+  test("mobile: both panels toggleable, collapsed by default", async ({ page }) => {
+    const el = await getElement(page, "default", { width: 500, height: 900 });
+    await expect(el).toHaveScreenshot("state-mobile.png");
+  });
+});