srcdev-nuxt-components 9.4.11 → 9.5.0

package/app/components/01.atoms/content-wrappers/layout-grid/layout-grid-by-cols/stories/LayoutGridByCols.stories.ts

@@ -16,27 +16,29 @@ const meta: Meta<StoryArgs> = {
     },
     label: {
       control: "text",
-      description:
-        "Accessible label for the grid — required when tag is section (rendered as a visually hidden element)",
+      description: "Accessible name when tag is section (rendered as a visually hidden element)",
       table: { category: "Semantic" },
     },
     itemCount: {
       control: { type: "range", min: 0, max: 18, step: 1 },
-      description: "Number of grid cells to render — must match the number of #item-{n} slots provided",
+      description: "Story only: how many #item-{n} slots to pass",
+      table: { category: "Story" },
     },
     columnCount: {
-      control: { type: "range", min: 1, max: 8, step: 1 },
-      description:
-        "Integer → repeat(N, 1fr) equal columns. CSS string (e.g. '200px', '15rem') → repeat(auto-fill, minmax(value, 1fr)) wrapping columns.",
+      control: { type: "range", min: 2, max: 6, step: 1 },
+      description: "Equal columns above singleColBelow (2–6). Writes --layout-grid-by-cols-column-count.",
+      table: { category: "Layout" },
     },
     gap: {
       control: "text",
-      description: "Grid gap — any valid CSS length (e.g. '1rem', '2.4rem', '16px')",
+      description: "Row and column gap, a single CSS length. Writes --layout-grid-by-cols-gap.",
+      table: { category: "Layout" },
     },
     singleColBelow: {
       control: "text",
       description:
-        "Container width below which the grid collapses to a single column — any valid CSS length (e.g. '600px', '40rem'). Default '0px' means never collapse.",
+        "Grid width below which it collapses to one column. '0px' never collapses. Writes --layout-grid-by-cols-single-col-below.",
+      table: { category: "Layout" },
     },
     styleClassPassthrough: {
       table: { disable: true },
@@ -44,6 +46,7 @@ const meta: Meta<StoryArgs> = {
   },
   args: {
     tag: "div",
+    label: "",
     itemCount: 6,
     columnCount: 3,
     gap: "1rem",
@@ -54,7 +57,7 @@ const meta: Meta<StoryArgs> = {
     docs: {
       description: {
         component:
-          "A CSS grid wrapper driven by props. Content is placed via dynamic named slots (#item-0, #item-1, …). Pass an integer to columnCount for N equal columns, or a CSS width string for auto-fill behaviour. The grid collapses to a single column below singleColBelow using a CSS container query.",
+          "A CSS grid of N equal columns, filled from named dynamic slots in document order. Collapses to one column when the grid is narrower than singleColBelow. Every layout prop writes a public --layout-grid-by-cols-* token inline; leave a prop off to set its token from CSS instead.",
       },
     },
   },
@@ -63,8 +66,6 @@ const meta: Meta<StoryArgs> = {
 export default meta;
 type Story = StoryObj<StoryArgs>;
 
-// ─── Helpers ──────────────────────────────────────────────────────────────────
-
 const colours = [
   { bg: "#dbeafe", fg: "#1e40af" },
   { bg: "#dcfce7", fg: "#166534" },
@@ -72,148 +73,131 @@ const colours = [
   { bg: "#ede9fe", fg: "#5b21b6" },
   { bg: "#fce7f3", fg: "#9d174d" },
   { bg: "#ffedd5", fg: "#9a3412" },
-  { bg: "#f0fdf4", fg: "#14532d" },
-  { bg: "#fdf4ff", fg: "#7e22ce" },
 ];
 
-const cell = (label: string, index: number, body = "Placeholder content for this grid cell.") =>
-  `<div style="padding: 2.4rem; background: ${colours[index % colours.length]?.bg}; border-radius: 0.8rem; color: ${colours[index % colours.length]?.fg}; font-family: sans-serif; height: 100%;">
-    <strong style="display: block; margin-bottom: 0.8rem;">${label}</strong>
-    <p style="margin: 0; font-size: 1.4rem; line-height: 1.6; opacity: 0.8;">${body}</p>
-  </div>`;
-
-// Pre-generate max slots — the component only renders up to itemCount, extras are ignored.
-const allSlots = Array.from(
-  { length: 18 },
-  (_, i) => `<template #item-${i}>${cell(`Item ${i + 1}`, i)}</template>`
-).join("\n        ");
-
-// Normalise args: explicitly maps each prop so no raw slider number leaks through to the component.
-// colWidth: 0 → undefined (not set), N → "Nrem" CSS string.
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-const toStoryArgs = (args: any) =>
-  computed(() => ({
-    tag: args.tag as "div" | "section",
-    label: args.label as string,
-    itemCount: Number(args.itemCount),
-    columnCount: args.columnCount as number,
-    gap: args.gap as string,
-    singleColBelow: args.singleColBelow as string,
-    styleClassPassthrough: args.styleClassPassthrough as string[],
-  }));
+const cellStyle = (i: number) =>
+  `padding: 2.4rem; background: ${colours[i % colours.length]?.bg}; color: ${colours[i % colours.length]?.fg}; border-radius: 0.8rem; font-family: sans-serif; height: 100%;`;
 
-// ─── Stories ──────────────────────────────────────────────────────────────────
+const renderGrid = (args: StoryArgs) => ({
+  components: { LayoutGridByCols },
+  setup() {
+    const componentArgs = computed(() => {
+      const { itemCount: _itemCount, ...rest } = args;
+      return rest;
+    });
+    const items = computed(() => Array.from({ length: Number(args.itemCount ?? 0) }, (_, i) => i));
+    return { componentArgs, items, cellStyle };
+  },
+  template: `
+    <LayoutGridByCols v-bind="componentArgs">
+      <template v-for="i in items" :key="i" #[\`item-\${i}\`]>
+        <div :style="cellStyle(i)">
+          <strong style="display: block; margin-bottom: 0.8rem;">Item {{ i + 1 }}</strong>
+          <p style="margin: 0; font-size: 1.4rem; line-height: 1.6; opacity: 0.8;">Placeholder content for this grid cell.</p>
+        </div>
+      </template>
+    </LayoutGridByCols>
+  `,
+});
 
-/** Default — equal columns. Adjust columns, colWidth and itemCount with the sliders. */
 export const Default: Story = {
-  args: {
-    itemCount: 6,
-    columnCount: 3,
-  },
-  render: (args) => ({
-    components: { LayoutGridByCols },
-    setup() {
-      return { storyArgs: toStoryArgs(args) };
-    },
-    template: `
-      <LayoutGridByCols v-bind="storyArgs">
-        ${allSlots}
-      </LayoutGridByCols>
-    `,
-  }),
+  render: (args) => renderGrid(args),
 };
 
-/** Single column below a breakpoint — collapses to stacked layout on narrow containers. */
 export const SingleColBelow: Story = {
   name: "Single Column Below 600px",
   args: {
-    itemCount: 6,
-    columnCount: 3,
     singleColBelow: "600px",
   },
-  render: (args) => ({
-    components: { LayoutGridByCols },
-    setup() {
-      return { storyArgs: toStoryArgs(args) };
-    },
-    template: `
-      <LayoutGridByCols v-bind="storyArgs">
-        ${allSlots}
-      </LayoutGridByCols>
-    `,
-  }),
+  render: (args) => renderGrid(args),
   parameters: {
     docs: {
       description: {
-        story:
-          "Below 600px container width the grid collapses to a single column via a CSS container query. Resize the canvas to see the switch.",
+        story: "Below 600px of grid width the grid collapses to one column. Resize the canvas to see the switch.",
       },
     },
   },
 };
 
-/** Custom gap — wider spacing between cells. */
+export const NeverCollapse: Story = {
+  name: "Never Collapse",
+  args: {
+    columnCount: 4,
+    singleColBelow: "0px",
+  },
+  render: (args) => renderGrid(args),
+};
+
 export const CustomGap: Story = {
   name: "Custom Gap",
   args: {
-    itemCount: 6,
-    columnCount: 3,
     gap: "3.2rem",
   },
-  render: (args) => ({
-    components: { LayoutGridByCols },
-    setup() {
-      return { storyArgs: toStoryArgs(args) };
-    },
-    template: `
-      <LayoutGridByCols v-bind="storyArgs">
-        ${allSlots}
-      </LayoutGridByCols>
-    `,
-  }),
+  render: (args) => renderGrid(args),
 };
 
-/** Semantic section — tag='section' with a visually hidden label for accessibility. */
 export const SemanticSection: Story = {
   name: "Semantic Section",
   args: {
     tag: "section",
     label: "Feature highlights",
-    itemCount: 6,
-    columnCount: 3,
   },
-  render: (args) => ({
-    components: { LayoutGridByCols },
-    setup() {
-      return { storyArgs: toStoryArgs(args) };
+  render: (args) => renderGrid(args),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "When tag is section, the label is rendered as a visually hidden element and linked with aria-labelledby.",
+      },
     },
-    template: `
-      <LayoutGridByCols v-bind="storyArgs">
-        ${allSlots}
-      </LayoutGridByCols>
-    `,
-  }),
+  },
+};
+
+export const CssTokens: Story = {
+  name: "CSS Tokens (no layout props)",
+  args: {
+    columnCount: undefined,
+    gap: undefined,
+    singleColBelow: undefined,
+  },
+  render: (args) => {
+    const inner = renderGrid(args);
+    return {
+      ...inner,
+      template: `
+        <div class="lgbc-story-tokens">
+          <component is="style">
+            .lgbc-story-tokens {
+              --layout-grid-by-cols-column-count: 2;
+              --layout-grid-by-cols-row-gap: 0.8rem;
+              --layout-grid-by-cols-column-gap: 2.4rem;
+              --layout-grid-by-cols-single-col-below: 480px;
+            }
+            @media (width >= 1024px) {
+              .lgbc-story-tokens {
+                --layout-grid-by-cols-column-count: 4;
+              }
+            }
+          </component>
+          ${inner.template}
+        </div>
+      `,
+    };
+  },
   parameters: {
     docs: {
       description: {
         story:
-          "When tag is section, an aria-labelledby attribute is added and the label is rendered as a visually hidden element for screen readers.",
+          "No layout props are passed, so columns, gaps and the collapse threshold come from tokens on an ancestor: 2 columns, 4 from 1024px viewport, one column below 480px of grid width, separate row and column gaps.",
       },
     },
   },
 };
 
-/** Zero items — renders an empty grid with no cells. */
 export const ZeroItems: Story = {
   name: "Zero Items",
   args: {
     itemCount: 0,
   },
-  render: (args) => ({
-    components: { LayoutGridByCols },
-    setup() {
-      return { storyArgs: toStoryArgs(args) };
-    },
-    template: `<LayoutGridByCols v-bind="storyArgs" />`,
-  }),
+  render: (args) => renderGrid(args),
 };

package/app/components/01.atoms/content-wrappers/layout-grid/layout-grid-by-cols/tests/LayoutGridByCols.spec.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, vi } from "vitest";
 import { mountSuspended } from "@nuxt/test-utils/runtime";
 import LayoutGridByCols from "../LayoutGridByCols.vue";
 
@@ -52,16 +52,16 @@ describe("LayoutGridByCols", () => {
 
   // ─── Base class ──────────────────────────────────────────────────────────
 
-  it("always has the layout-grid class", async () => {
+  it("always has the layout-grid-by-cols class", async () => {
     const wrapper = await mountSuspended(LayoutGridByCols);
     expect(wrapper.classes()).toContain("layout-grid-by-cols");
   });
 
   // ─── Inner div ───────────────────────────────────────────────────────────
 
-  it("renders a .layout-grid-inner div", async () => {
+  it("renders a .layout-grid-by-cols-inner div", async () => {
     const wrapper = await mountSuspended(LayoutGridByCols);
-    expect(wrapper.find(".layout-grid-inner").exists()).toBe(true);
+    expect(wrapper.find(".layout-grid-by-cols-inner").exists()).toBe(true);
   });
 
   // ─── Accessibility ───────────────────────────────────────────────────────
@@ -94,7 +94,7 @@ describe("LayoutGridByCols", () => {
         "item-2": "<span>Gamma</span>",
       },
     });
-    const inner = wrapper.find(".layout-grid-inner");
+    const inner = wrapper.find(".layout-grid-by-cols-inner");
     expect(inner.text()).toContain("Alpha");
     expect(inner.text()).toContain("Beta");
     expect(inner.text()).toContain("Gamma");
@@ -102,7 +102,7 @@ describe("LayoutGridByCols", () => {
 
   it("renders no slot content when no slots are provided", async () => {
     const wrapper = await mountSuspended(LayoutGridByCols);
-    expect(wrapper.find(".layout-grid-inner").text().trim()).toBe("");
+    expect(wrapper.find(".layout-grid-by-cols-inner").text().trim()).toBe("");
   });
 
   // ─── styleClassPassthrough ───────────────────────────────────────────────
@@ -122,29 +122,64 @@ describe("LayoutGridByCols", () => {
     expect(wrapper.classes()).toContain("class-b");
   });
 
-  // ─── columnCount prop ─────────────────────────────────────────────────────
+  // ─── Token props ──────────────────────────────────────────────────────────
 
-  it("accepts columnCount without error", async () => {
+  const inlineToken = (wrapper: { element: Element }, name: string) =>
+    (wrapper.element as HTMLElement).style.getPropertyValue(name);
+
+  it("writes no inline style when no layout props are passed", async () => {
+    const wrapper = await mountSuspended(LayoutGridByCols);
+    expect(wrapper.attributes("style")).toBeUndefined();
+  });
+
+  it("writes columnCount to --layout-grid-by-cols-column-count", async () => {
     const wrapper = await mountSuspended(LayoutGridByCols, {
       props: { columnCount: 3 },
     });
-    expect(wrapper.vm).toBeTruthy();
+    expect(inlineToken(wrapper, "--layout-grid-by-cols-column-count")).toBe("3");
   });
 
-  // ─── Other prop acceptance ────────────────────────────────────────────────
+  it("clamps columnCount to a minimum of 2", async () => {
+    const wrapper = await mountSuspended(LayoutGridByCols, {
+      props: { columnCount: 1 as unknown as 2 },
+    });
+    expect(inlineToken(wrapper, "--layout-grid-by-cols-column-count")).toBe("2");
+  });
 
-  it("accepts gap prop without error", async () => {
+  it("writes gap to --layout-grid-by-cols-gap", async () => {
     const wrapper = await mountSuspended(LayoutGridByCols, {
       props: { gap: "2rem" },
     });
-    expect(wrapper.vm).toBeTruthy();
+    expect(inlineToken(wrapper, "--layout-grid-by-cols-gap")).toBe("2rem");
   });
 
-  it("accepts singleColBelow prop without error", async () => {
+  it("writes singleColBelow to --layout-grid-by-cols-single-col-below", async () => {
     const wrapper = await mountSuspended(LayoutGridByCols, {
       props: { singleColBelow: "600px" },
     });
-    expect(wrapper.vm).toBeTruthy();
+    expect(inlineToken(wrapper, "--layout-grid-by-cols-single-col-below")).toBe("600px");
+  });
+
+  it("updates the inline token when a prop changes", async () => {
+    const wrapper = await mountSuspended(LayoutGridByCols, {
+      props: { columnCount: 3 },
+    });
+    await wrapper.setProps({ columnCount: 4 });
+    expect(inlineToken(wrapper, "--layout-grid-by-cols-column-count")).toBe("4");
+    await wrapper.setProps({ columnCount: undefined });
+    expect(inlineToken(wrapper, "--layout-grid-by-cols-column-count")).toBe("");
+  });
+
+  it("does not render placeholder text or aria-labelledby for a section without a label", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const wrapper = await mountSuspended(LayoutGridByCols, {
+      props: { tag: "section" },
+    });
+    expect(wrapper.find(".sr-only").exists()).toBe(false);
+    expect(wrapper.attributes("aria-labelledby")).toBeUndefined();
+    expect(wrapper.text()).not.toContain("label is required");
+    expect(warn).toHaveBeenCalled();
+    warn.mockRestore();
   });
 
   // ─── Combined ────────────────────────────────────────────────────────────
@@ -167,7 +202,7 @@ describe("LayoutGridByCols", () => {
     });
     expect(wrapper.element.tagName).toBe("SECTION");
     expect(wrapper.classes()).toContain("services-grid");
-    expect(wrapper.find(".layout-grid-inner").exists()).toBe(true);
+    expect(wrapper.find(".layout-grid-by-cols-inner").exists()).toBe(true);
     expect(wrapper.text()).toContain("One");
     expect(wrapper.html()).toMatchSnapshot();
   });

package/app/components/01.atoms/content-wrappers/layout-grid/layout-grid-by-cols/tests/__snapshots__/LayoutGridByCols.spec.ts.snap

@@ -3,7 +3,7 @@
 exports[`LayoutGridByCols > renders correct HTML structure (div, 2 items) 1`] = `
 "<div class="layout-grid-by-cols">
   <!--v-if-->
-  <div class="layout-grid-inner">
+  <div class="layout-grid-by-cols-inner">
     <p>First</p>
     <p>Second</p>
   </div>
@@ -13,21 +13,21 @@ exports[`LayoutGridByCols > renders correct HTML structure (div, 2 items) 1`] =
 exports[`LayoutGridByCols > renders correct HTML structure (section with label) 1`] = `
 "<section class="layout-grid-by-cols" aria-labelledby="v-0-0">
   <p id="v-0-0" class="sr-only">Feature grid</p>
-  <div class="layout-grid-inner"></div>
+  <div class="layout-grid-by-cols-inner"></div>
 </section>"
 `;
 
 exports[`LayoutGridByCols > renders correct HTML structure with styleClassPassthrough 1`] = `
 "<div class="layout-grid-by-cols custom-class another-class">
   <!--v-if-->
-  <div class="layout-grid-inner"></div>
+  <div class="layout-grid-by-cols-inner"></div>
 </div>"
 `;
 
 exports[`LayoutGridByCols > renders correctly with all props and slots combined 1`] = `
-"<section class="layout-grid-by-cols services-grid" aria-labelledby="v-0-0">
+"<section class="layout-grid-by-cols services-grid" aria-labelledby="v-0-0" style="--layout-grid-by-cols-column-count: 3; --layout-grid-by-cols-gap: 2rem; --layout-grid-by-cols-single-col-below: 768px;">
   <p id="v-0-0" class="sr-only">Services</p>
-  <div class="layout-grid-inner">
+  <div class="layout-grid-by-cols-inner">
     <p>One</p>
     <p>Two</p>
     <p>Three</p>

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

@@ -24,6 +24,8 @@ Or scope to a single instance via `styleClassPassthrough`:
 }
 ```
 
+---
+
 ## Layout
 
 `DisplayBanner` stacks its `canvas` and `content` slots on top of each other in a single grid
@@ -33,3 +35,14 @@ overlaid text/CTAs in `content`, since `content` follows `canvas` in the templat
 
 Both slots are conditionally rendered (`v-if="$slots.canvas"` / `v-if="$slots.content"`), so an
 unused slot contributes no empty wrapper `<div>` to the DOM.
+
+---
+
+## Local overrides
+
+Set the tokens above on an element you own (a page or section class, or a class added with
+`:style-class-passthrough`): they inherit down into the component. Keep the block **unlayered** (no
+`@layer` wrapper) so it beats the library's `@layer components`. If your own file uses
+`<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`.
+