srcdev-nuxt-components 9.2.5 → 9.2.6

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

@@ -0,0 +1,172 @@
+import type { Meta, StoryFn } from "@nuxtjs/storybook";
+import ContentDocs from "../ContentDocs.vue";
+import type { DocsNavItem } from "~/types/components";
+
+interface ContentDocsStoryArgs {
+  tag: "div" | "section" | "article" | "main";
+  docsNavItems: DocsNavItem[];
+  docsPageNavItems: DocsNavItem[];
+  docsNavLabel: string;
+  docsPageNavLabel: string;
+  styleClassPassthrough: string[];
+  activeNavItem: string;
+  activePageNavItem: string;
+}
+
+const defaultNavItems: DocsNavItem[] = [
+  { label: "Getting started", to: "/docs", icon: "lucide:rocket" },
+  { label: "Installation", to: "/docs/install", icon: "lucide:download" },
+  { label: "Configuration", to: "/docs/config" },
+  { label: "Theming", to: "/docs/theming", icon: "lucide:palette" },
+];
+
+const defaultPageNavItems: DocsNavItem[] = [
+  { label: "Overview", to: "/docs#overview", icon: "lucide:eye" },
+  { label: "Examples", to: "/docs#examples" },
+  { label: "Props", to: "/docs#props", icon: "lucide:settings-2" },
+];
+
+export default {
+  title: "Atoms/Content Wrappers/ContentDocs",
+  component: ContentDocs,
+  argTypes: {
+    tag: {
+      control: { type: "select" },
+      options: ["div", "section", "article", "main"],
+      description: "Root element tag",
+      table: { category: "Basic" },
+    },
+    docsNavItems: {
+      control: "object",
+      description: "Items rendered in the docsNav panel. The panel is omitted entirely when empty.",
+      table: { category: "Nav items" },
+    },
+    docsPageNavItems: {
+      control: "object",
+      description: "Items rendered in the docsPageNav panel. The panel is omitted entirely when empty.",
+      table: { category: "Nav items" },
+    },
+    docsNavLabel: {
+      control: "text",
+      description: "Heading text for the docsNav panel",
+      table: { category: "Basic" },
+    },
+    docsPageNavLabel: {
+      control: "text",
+      description: "Heading text for the docsPageNav panel",
+      table: { category: "Basic" },
+    },
+    styleClassPassthrough: {
+      control: "object",
+      description: "Additional CSS classes applied to the root element",
+      table: { category: "Basic" },
+    },
+    activeNavItem: {
+      control: "text",
+      description: "The `to` of the currently-active docsNav item",
+      table: { category: "Model" },
+    },
+    activePageNavItem: {
+      control: "text",
+      description: "The `to` of the currently-active docsPageNav item",
+      table: { category: "Model" },
+    },
+  },
+  args: {
+    tag: "div",
+    docsNavItems: defaultNavItems,
+    docsPageNavItems: defaultPageNavItems,
+    docsNavLabel: "Navigation",
+    docsPageNavLabel: "On this page",
+    styleClassPassthrough: [],
+    activeNavItem: defaultNavItems[0]?.to,
+    activePageNavItem: "",
+  },
+} as Meta<typeof ContentDocs>;
+
+// ─── Stories ─────────────────────────────────────────────────────────────────
+
+const Template: StoryFn<ContentDocsStoryArgs> = (args) => ({
+  components: { ContentDocs },
+  setup() {
+    const { activeNavItem, activePageNavItem, ...rest } = args;
+    const activeNav = ref(activeNavItem);
+    const activePageNav = ref(activePageNavItem);
+    return { args: rest, activeNav, activePageNav };
+  },
+  template: `
+    <ContentDocs
+      v-bind="args"
+      v-model:active-nav-item="activeNav"
+      v-model:active-page-nav-item="activePageNav"
+    >
+      <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.
+        </p>
+      </template>
+    </ContentDocs>
+  `,
+});
+
+export const Default = Template.bind({});
+Default.args = {};
+
+export const NoIcons = Template.bind({});
+NoIcons.args = {
+  docsNavItems: defaultNavItems.map(({ icon: _icon, ...item }) => item),
+  docsPageNavItems: defaultPageNavItems.map(({ icon: _icon, ...item }) => item),
+};
+
+export const NavOnly = Template.bind({});
+NavOnly.args = {
+  docsPageNavItems: [],
+};
+
+export const PageNavOnly = Template.bind({});
+PageNavOnly.args = {
+  docsNavItems: [],
+};
+
+export const CustomLabels = Template.bind({});
+CustomLabels.args = {
+  docsNavLabel: "Sections",
+  docsPageNavLabel: "Contents",
+};
+
+export const IconAtEnd: StoryFn<ContentDocsStoryArgs> = (args) => ({
+  components: { ContentDocs },
+  setup() {
+    const { activeNavItem, activePageNavItem, ...rest } = args;
+    const activeNav = ref(activeNavItem);
+    const activePageNav = ref(activePageNavItem);
+    return { args: { ...rest, styleClassPassthrough: ["icon-at-end-demo"] }, activeNav, activePageNav };
+  },
+  template: `
+    <div>
+      <style>
+        .content-docs.icon-at-end-demo {
+          --docs-nav-link-icon-order: rtl;
+          --docs-page-nav-link-icon-order: rtl;
+        }
+      </style>
+      <ContentDocs
+        v-bind="args"
+        v-model:active-nav-item="activeNav"
+        v-model:active-page-nav-item="activePageNav"
+      >
+        <template #docsContent>
+          <h3 style="margin-top:0">Docs Content</h3>
+          <p>
+            <code>--docs-nav-link-icon-order: rtl</code> moves the icon to the end of each
+            link instead of the start (default <code>ltr</code>).
+          </p>
+        </template>
+      </ContentDocs>
+    </div>
+  `,
+});
+IconAtEnd.args = {};

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

@@ -0,0 +1,218 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { nextTick } from "vue";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import ContentDocs from "../ContentDocs.vue";
+
+let resizeCallback: ResizeObserverCallback | null = null;
+
+beforeEach(() => {
+  resizeCallback = null;
+  vi.stubGlobal(
+    "ResizeObserver",
+    vi.fn((callback: ResizeObserverCallback) => {
+      resizeCallback = callback;
+      return {
+        observe: vi.fn(),
+        unobserve: vi.fn(),
+        disconnect: vi.fn(),
+      };
+    })
+  );
+});
+
+function triggerResize(el: HTMLElement, width: number) {
+  Object.defineProperty(el, "offsetWidth", { value: width, configurable: true });
+  resizeCallback?.(
+    [{ contentRect: { width, height: 0 } } as unknown as ResizeObserverEntry],
+    {} as ResizeObserver
+  );
+}
+
+const navItems = [
+  { label: "One", to: "/one" },
+  { label: "Two", to: "/two" },
+];
+const pageNavItems = [{ label: "Overview", to: "/one#overview" }];
+
+describe("ContentDocs", () => {
+  it("mounts without error", async () => {
+    const 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("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");
+    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("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");
+    expect(links).toHaveLength(1);
+    expect(links[0]?.text()).toBe("Overview");
+  });
+
+  it("renders the docsContent slot", async () => {
+    const wrapper = await mountSuspended(ContentDocs, {
+      slots: { docsContent: '<p data-testid="body">Body</p>' },
+    });
+    expect(wrapper.find('[data-testid="body"]').text()).toBe("Body");
+  });
+
+  // ─── labels ─────────────────────────────────────────────────────────────
+
+  it("defaults docsNavLabel to 'Navigation' and docsPageNavLabel to 'On this page'", async () => {
+    const 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");
+  });
+
+  it("uses custom docsNavLabel / docsPageNavLabel when provided", async () => {
+    const wrapper = await mountSuspended(ContentDocs, {
+      props: {
+        docsNavItems: navItems,
+        docsPageNavItems: pageNavItems,
+        docsNavLabel: "Sections",
+        docsPageNavLabel: "Contents",
+      },
+    });
+    expect(wrapper.find(".docs-nav-heading").text()).toBe("Sections");
+    expect(wrapper.find(".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, {
+      props: { docsNavItems: [{ label: "One", to: "/one", icon: "lucide:home" }] },
+    });
+    expect(wrapper.find(".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);
+  });
+
+  it("renders an icon on a docsPageNav item when item.icon is set", async () => {
+    const 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);
+  });
+
+  // ─── active item ────────────────────────────────────────────────────────
+
+  it("applies is-active and aria-current to the link matching activeNavItem", async () => {
+    const 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");
+    expect(links[1]?.attributes("aria-current")).toBe("page");
+  });
+
+  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");
+    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");
+    expect(wrapper.emitted("update:activePageNavItem")?.[0]).toEqual(["/one#overview"]);
+  });
+
+  // ─── container-width-driven forceOpened ────────────────────────────────────
+
+  describe("breakpoint-driven forceOpened", () => {
+    it("neither panel is forceOpened below 768px (mobile)", async () => {
+      const 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);
+    });
+
+    it("only docsPageNav is forceOpened between 768px and 1023px (tablet)", async () => {
+      const 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");
+    });
+
+    it("both panels are forceOpened at 1024px and above (desktop)", async () => {
+      const 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");
+    });
+  });
+
+  // ─── native <details> name grouping ────────────────────────────────────────
+
+  describe("panel name grouping", () => {
+    it("shares one details name between docsNav and docsPageNav on mobile", async () => {
+      const 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");
+      expect(navName).toBe(pageNavName);
+    });
+
+    it("uses distinct details names on desktop, where both must stay open simultaneously", async () => {
+      const 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");
+      expect(navName).not.toBe(pageNavName);
+    });
+  });
+
+  // ─── styleClassPassthrough ────────────────────────────────────────────────
+
+  it("applies styleClassPassthrough classes to the root element", async () => {
+    const wrapper = await mountSuspended(ContentDocs, {
+      props: { styleClassPassthrough: ["custom-class"] },
+    });
+    expect(wrapper.find(".content-docs").classes()).toContain("custom-class");
+  });
+});

package/app/components/02.molecules/expandable/expanding-panel/CONSUMER-STYLING.md

@@ -0,0 +1,103 @@
+# ExpandingPanel — Consumer Styling Guide
+
+## Public token API
+
+All `--expanding-panel-*` tokens are the stable override surface. Set them at any scope
+(global, page, or instance) without touching the component itself.
+
+| Token | Default | Controls |
+|---|---|---|
+| `--expanding-panel-summary-gap` | `1rem` | Gap between the summary label and the toggle icon |
+| `--expanding-panel-summary-padding-block` | `0.5rem` | Vertical padding on the clickable summary row |
+| `--expanding-panel-icon-size` | `1.2rem` | Toggle icon `font-size` |
+| `--expanding-panel-content-z-index` | `10` | Stacking order of the content region when `contentIsOnTop` is `true` |
+| `--expanding-panel-content-gap` | `0px` | Space between the summary and the content region when `contentIsOnTop` is `true` |
+
+Note: `background-color`, `padding`, and shadow are **not** tokenised, and must never be applied
+to `.inner` itself — see [expanding-panel.md](../../../../.claude/skills/components/expanding-panel.md#styling-the-content-when-contentisontop)
+for why, and style a wrapper *inside* the `#content` slot instead.
+
+---
+
+## Global theming — recommended approach
+
+Create `assets/styles/setup/07.components/expanding-panel.css` in the consuming app and set
+tokens on `:root`. This applies to every `ExpandingPanel` across the site.
+
+```css
+/* assets/styles/setup/07.components/expanding-panel.css */
+:root {
+  --expanding-panel-summary-gap: 1.6rem;
+  --expanding-panel-summary-padding-block: 1.2rem;
+  --expanding-panel-icon-size: 1.4rem;
+}
+```
+
+---
+
+## Page-scoped overrides
+
+Override tokens for a specific section by scoping them under the page or layout wrapper.
+No `:deep()` is required (component styles are unscoped).
+
+```css
+/* In the consuming page's unscoped <style> block */
+.faq-section {
+  .expanding-panel {
+    --expanding-panel-summary-padding-block: 1.6rem;
+  }
+}
+```
+
+---
+
+## Per-instance overrides via styleClassPassthrough
+
+Use sparingly — prefer global or page-scoped CSS. When a single instance needs a distinct
+visual style, pass a modifier class:
+
+```vue
+<ExpandingPanel
+  name="promo"
+  :content-is-on-top="true"
+  :style-class-passthrough="['promo-panel']"
+>
+  <template #summary>...</template>
+  <template #content>
+    <!-- Wrapper INSIDE the slot carries the visual styling — never .inner itself -->
+    <div class="promo-panel-body">...</div>
+  </template>
+</ExpandingPanel>
+```
+
+```css
+.expanding-panel.promo-panel {
+  --expanding-panel-content-gap: 0.4rem;
+  --expanding-panel-content-z-index: 20;
+}
+
+.promo-panel-body {
+  background-color: white;
+  padding: 1rem;
+  box-shadow: 0 4px 12px rgb(0 0 0 / 15%);
+}
+```
+
+---
+
+## Notes
+
+- `--expanding-panel-content-gap` and `--expanding-panel-content-z-index` only take effect when
+  `contentIsOnTop` is `true` — they're no-ops for the default (in-flow) layout.
+- Never set `background-color`, `padding`, `border`, or a shadow directly on `.inner`. `.inner`
+  has no explicit height when collapsed (`grid-template-rows: 0fr`) and relies on
+  `overflow: hidden` to clip its *children* to 0px — but padding/border/background on `.inner`'s
+  own box are not "overflow content", so they'd still render as a visible gap under the summary
+  while closed. Always style a wrapper element placed *inside* the `#content` slot instead; that
+  wrapper is a child of `.inner` and gets clipped correctly.
+- Don't stack multiple `contentIsOnTop` panels as direct siblings (linked via a shared `name` or
+  not). The overlay is absolutely positioned so it doesn't push the next element down — which
+  means a sibling `ExpandingPanel` placed right after it sits exactly where the overlay renders,
+  and gets visually covered when the first panel opens. `contentIsOnTop` is for a single panel
+  overlaying unrelated trailing page content, not for grouped/stacked accordion panels — use the
+  default in-flow layout for those.