srcdev-nuxt-components 9.4.6 → 9.4.8

package/app/components/01.atoms/animations/rotating-carousel-image/tests/__snapshots__/RotatingCarouselImage.spec.ts.snap

@@ -0,0 +1,19 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`RotatingCarouselImage > renders correct HTML structure (all props set) 1`] = `
+"<section class="rotating-carousel hover-pauses" style="--_rotate-x: 10deg; --_perspective: 1200px; --_translateZ: 1200px;" role="region" aria-label="Custom carousel" tabindex="0">
+  <div class="sr-only">Custom instructions</div><button class="control-btn" type="button" aria-label="Pause rotation"><span class="iconify i-mdi:pause" aria-hidden="true"></span></button>
+  <div class="slider" style="--_quantity: 2;">
+    <div class="item" style="--_position: 0;"><img data-nuxt-img="" srcset="/_ipx/_/a.jpg 1x, /_ipx/_/a.jpg 2x" alt="A" src="/_ipx/_/a.jpg"></div>
+    <div class="item" style="--_position: 1;"><img data-nuxt-img="" srcset="/_ipx/_/b.jpg 1x, /_ipx/_/b.jpg 2x" alt="B" src="/_ipx/_/b.jpg"></div>
+  </div>
+</section>"
+`;
+
+exports[`RotatingCarouselImage > renders correct HTML structure (default props) 1`] = `
+"<div class="rotating-carousel" style="--_rotate-x: 0deg; --_perspective: 1000px; --_translateZ: 1000px;" role="region" aria-label="Rotating image carousel" tabindex="0">
+  <div class="sr-only">Use spacebar to pause or play the rotation.</div>
+  <!--v-if-->
+  <div class="slider" style="--_quantity: 0;"></div>
+</div>"
+`;

package/app/components/01.atoms/canvas-switcher/stories/CanvasSwitcher.stories.ts

@@ -37,17 +37,18 @@ export default {
   },
 } as Meta<typeof CanvasSwitcher>;
 
+// `args` is Storybook's own reactive object — bind to it directly (`args.x`) rather than
+// destructuring it into local variables/refs, which would snapshot the values once at setup()
+// and stop reflecting later Controls-panel changes.
 const Template: StoryFn<CanvasSwitcherStoryArgs> = (args) => ({
   components: { CanvasSwitcher },
   setup() {
-    const { canvasName, ...otherArgs } = args;
-    const selected = ref(canvasName);
-    return { selected, args: otherArgs };
+    return { args };
   },
   template: `
     <div>
-      <CanvasSwitcher v-model:canvas-name="selected" v-bind="args" />
-      <p style="margin-top: 1.6rem;">Selected: {{ selected }}</p>
+      <CanvasSwitcher v-model:canvas-name="args.canvasName" v-bind="args" />
+      <p style="margin-top: 1.6rem;">Selected: {{ args.canvasName }}</p>
     </div>
   `,
 });
@@ -60,14 +61,12 @@ PreviewWidthDemo.args = {};
 PreviewWidthDemo.render = (args) => ({
   components: { CanvasSwitcher },
   setup() {
-    const { canvasName } = args;
-    const selected = ref(canvasName);
-    return { selected };
+    return { args };
   },
   template: `
     <div>
-      <CanvasSwitcher v-model:canvas-name="selected" />
-      <div :class="selected" style="border: 1px dashed currentColor; margin-top: 1.6rem; padding: 1.6rem;">
+      <CanvasSwitcher v-model:canvas-name="args.canvasName" />
+      <div :class="args.canvasName" style="border: 1px dashed currentColor; margin-top: 1.6rem; padding: 1.6rem;">
         This box is constrained by the selected canvas's utility class.
       </div>
     </div>

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

@@ -1,4 +1,5 @@
 import type { Meta, StoryFn } from "@nuxtjs/storybook";
+import { computed } from "vue";
 import ContentDocs from "../ContentDocs.vue";
 import type { DocsNavItem } from "~/types/components";
 
@@ -86,19 +87,19 @@ export default {
 
 // ─── Stories ─────────────────────────────────────────────────────────────────
 
+// `args` is Storybook's own reactive object — bind to it directly (`args.x`) rather than
+// destructuring it into local variables/refs, which would snapshot the values once at setup()
+// and stop reflecting later Controls-panel changes.
 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 };
+    return { args };
   },
   template: `
     <ContentDocs
       v-bind="args"
-      v-model:active-nav-item="activeNav"
-      v-model:active-page-nav-item="activePageNav"
+      v-model:active-nav-item="args.activeNavItem"
+      v-model:active-page-nav-item="args.activePageNavItem"
     >
       <template #docsContent>
         <h3 style="margin-top:0">Docs Content</h3>
@@ -140,10 +141,8 @@ CustomLabels.args = {
 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 };
+    const componentArgs = computed(() => ({ ...args, styleClassPassthrough: ["icon-at-end-demo"] }));
+    return { args, componentArgs };
   },
   template: `
     <div>
@@ -154,9 +153,9 @@ export const IconAtEnd: StoryFn<ContentDocsStoryArgs> = (args) => ({
         }
       </style>
       <ContentDocs
-        v-bind="args"
-        v-model:active-nav-item="activeNav"
-        v-model:active-page-nav-item="activePageNav"
+        v-bind="componentArgs"
+        v-model:active-nav-item="args.activeNavItem"
+        v-model:active-page-nav-item="args.activePageNavItem"
       >
         <template #docsContent>
           <h3 style="margin-top:0">Docs Content</h3>

package/app/components/01.atoms/grids/column-flow-grid/CONSUMER-STYLING.md

@@ -0,0 +1,33 @@
+# ColumnFlowGrid — Consumer Styling Guide
+
+## Public token API
+
+| Token | Falls back to | Controls |
+|---|---|---|
+| `--column-flow-grid-item-border-colour` | `var(--theme-border)` | Outline colour around each item |
+| `--column-flow-grid-item-padding` | `1.2rem` | Inner padding of each item |
+
+Column width and gap are controlled via props (`item-min-width`, `gap`, `unit`), not CSS custom
+properties — they drive the CSS column layout directly and need JS-computed values, so they aren't
+part of the public token API. See `.claude/skills/components/column-flow-grid.md`.
+
+---
+
+## Global theming — app-level CSS file
+
+```css
+:where(html) {
+  --column-flow-grid-item-border-colour: var(--rose-05);
+  --column-flow-grid-item-padding: 1.6rem;
+}
+```
+
+---
+
+## Per-instance overrides
+
+```vue
+<ColumnFlowGrid style="--column-flow-grid-item-border-colour: var(--gold-04);">
+  ...
+</ColumnFlowGrid>
+```

package/app/components/01.atoms/grids/column-flow-grid/ColumnFlowGrid.vue

@@ -0,0 +1,55 @@
+<template>
+  <component
+    :is="tag"
+    class="column-flow-grid-wrapper"
+    :class="[elementClasses]"
+    :style="`--_column-flow-grid-gap: ${gap}${unit}; --_item-min-width: ${itemMinWidth}px`"
+  >
+    <div v-for="(_, name) in $slots" :key="name" class="column-flow-grid-item">
+      <slot :name="name"></slot>
+    </div>
+  </component>
+</template>
+
+<script setup lang="ts">
+interface Props {
+  tag?: "div" | "section" | "article" | "main";
+  itemMinWidth?: number;
+  gap?: number;
+  unit?: string;
+  styleClassPassthrough?: string | string[];
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  tag: "div",
+  itemMinWidth: 300,
+  gap: 1.2,
+  unit: "rem",
+  styleClassPassthrough: () => [],
+});
+
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+watch(
+  () => props.styleClassPassthrough,
+  () => {
+    resetElementClasses(props.styleClassPassthrough);
+  }
+);
+</script>
+
+<style lang="css">
+@layer components {
+  .column-flow-grid-wrapper {
+    columns: auto var(--_item-min-width);
+    column-gap: var(--_column-flow-grid-gap);
+
+    .column-flow-grid-item {
+      break-inside: avoid;
+      outline: 0.1rem solid var(--column-flow-grid-item-border-colour, var(--theme-border));
+      padding: var(--column-flow-grid-item-padding, 1.2rem);
+      margin-block-end: var(--_column-flow-grid-gap);
+    }
+  }
+}
+</style>

package/app/components/01.atoms/grids/column-flow-grid/stories/ColumnFlowGrid.stories.ts

@@ -0,0 +1,178 @@
+import type { Meta, StoryFn } from "@nuxtjs/storybook";
+import ColumnFlowGrid from "../ColumnFlowGrid.vue";
+
+interface ColumnFlowGridArgs {
+  tag: "div" | "section" | "article" | "main";
+  itemMinWidth: number;
+  gap: number;
+  unit: string;
+  styleClassPassthrough: string[];
+}
+
+const meta: Meta<ColumnFlowGridArgs> = {
+  title: "Atoms/Grids/ColumnFlowGrid",
+  component: ColumnFlowGrid,
+  argTypes: {
+    tag: {
+      control: { type: "select" },
+      options: ["div", "section", "article", "main"],
+      description: "HTML tag to render as",
+      table: { category: "Props" },
+    },
+    itemMinWidth: {
+      control: { type: "select" },
+      options: [160, 200, 240, 300, 360, 450],
+      description: "Minimum column width in pixels — drives `columns: auto <value>px`",
+      table: { category: "Props" },
+    },
+    gap: {
+      control: { type: "select" },
+      options: [0, 0.4, 0.8, 1.2, 1.6, 2, 3],
+      description: "Gap between columns/items, in `unit`",
+      table: { category: "Props" },
+    },
+    unit: {
+      control: { type: "text" },
+      description: "CSS unit applied to `gap` (e.g. `rem`, `px`)",
+      table: { category: "Props" },
+    },
+    styleClassPassthrough: {
+      table: { disable: true },
+    },
+  },
+  args: {
+    tag: "div",
+    itemMinWidth: 300,
+    gap: 1.2,
+    unit: "rem",
+    styleClassPassthrough: [],
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "A CSS `columns` (multi-column text flow) layout. Renders whatever slots the consumer " +
+          "passes — no count/data prop needed (named dynamic slots, like `AutoGrid`/`GridStack`). " +
+          "Items flow into columns in DOM order, filling one column fully before starting the " +
+          "next — this does **not** reorder content, so DOM/reading order and visual order can " +
+          "diverge. Use `MasonryGrid` instead when reading order needs to match the visual layout.",
+      },
+    },
+  },
+};
+
+export default meta;
+
+const itemStyle =
+  "padding: 1.6rem; background: white; border-radius: 0.6rem; box-shadow: 0 2px 8px rgba(0,0,0,0.08);";
+const badgeStyle =
+  "display: inline-flex; align-items: center; justify-content: center; width: 2.4rem; height: 2.4rem; " +
+  "margin-bottom: 0.8rem; border-radius: 50%; background: #111827; color: white; font-weight: 700; " +
+  "font-size: 1.3rem; font-family: monospace;";
+
+// Each item shows its DOM order (slot index) as a numbered badge so you can see how the column-fill
+// algorithm actually orders items — it's not simple row-by-row order, so an item's position in the
+// visual grid doesn't always match its number sequentially top-to-bottom.
+const itemBadge = (n: number) => `<span style="${badgeStyle}">${n}</span><br />`;
+
+const paragraphPool = [
+  "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer nec odio praesent libero sed cursus ante.",
+  "Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.",
+  "Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.",
+  "Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.",
+  "Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium totam rem.",
+  "Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit sed quia consequuntur magni dolores.",
+];
+
+interface DemoItem {
+  slotName: string;
+  index: number;
+  bodyHtml: string;
+}
+
+// Generates a random number of paragraphs (1-4) per item so item heights vary unpredictably —
+// closer to real content than a handful of hand-written examples, and enough items (12) to
+// actually show multi-column flow. Built once per mount, not on every render, so a
+// Controls-panel change (itemMinWidth/gap) doesn't reshuffle the demo content underneath it.
+function buildDemoItems(count: number): DemoItem[] {
+  return Array.from({ length: count }, (_, i) => {
+    const paragraphCount = Math.floor(Math.random() * 4) + 1; // 1-4
+    const bodyHtml = Array.from(
+      { length: paragraphCount },
+      () => `<p style="margin: 0 0 0.8rem;">${paragraphPool[Math.floor(Math.random() * paragraphPool.length)]}</p>`
+    ).join("");
+    return { slotName: `item-${i + 1}`, index: i + 1, bodyHtml };
+  });
+}
+
+const Template: StoryFn<ColumnFlowGridArgs> = (args) => ({
+  components: { ColumnFlowGrid },
+  setup() {
+    const items = buildDemoItems(12);
+    return { args, items };
+  },
+  template: `
+    <div style="padding: 3.2rem; background: #f9fafb;">
+      <ColumnFlowGrid v-bind="args">
+        <template v-for="item in items" :key="item.slotName" #[item.slotName]>
+          <div style="${itemStyle}">
+            <span style="${badgeStyle}">{{ item.index }}</span><br />
+            <div v-html="item.bodyHtml"></div>
+          </div>
+        </template>
+      </ColumnFlowGrid>
+    </div>
+  `,
+});
+
+export const Default = Template.bind({});
+Default.parameters = {
+  docs: {
+    description: {
+      story:
+        "12 items with a random 1-4 paragraphs each, flowing into auto-sized columns at least " +
+        "300px wide. Each item is numbered with its slot/DOM order — resize the preview to change " +
+        "the column count and see how the numbering no longer reads strictly top-to-bottom per " +
+        "column once items wrap, since column-fill picks whichever column is currently shortest.",
+    },
+  },
+};
+
+export const NarrowColumns = Template.bind({});
+NarrowColumns.args = { itemMinWidth: 160, gap: 0.8 };
+NarrowColumns.parameters = {
+  docs: {
+    description: { story: "A smaller `itemMinWidth` fits more, narrower columns." },
+  },
+};
+
+export const WideColumns = Template.bind({});
+WideColumns.args = { itemMinWidth: 450, gap: 2 };
+WideColumns.parameters = {
+  docs: {
+    description: { story: "A larger `itemMinWidth` fits fewer, wider columns." },
+  },
+};
+
+export const TwoItems: StoryFn<ColumnFlowGridArgs> = (args) => ({
+  components: { ColumnFlowGrid },
+  setup() {
+    return { args };
+  },
+  template: `
+    <div style="padding: 3.2rem; background: #f9fafb;">
+      <ColumnFlowGrid v-bind="args">
+        <template #item-1>
+          <div style="${itemStyle}">${itemBadge(1)}Only two items provided</div>
+        </template>
+        <template #item-2>
+          <div style="${itemStyle}">
+            ${itemBadge(2)}No count prop to keep in sync — the grid just renders whichever
+            slots you give it.
+          </div>
+        </template>
+      </ColumnFlowGrid>
+    </div>
+  `,
+});
+TwoItems.storyName = "Two Items (no count prop needed)";

package/app/components/01.atoms/grids/column-flow-grid/tests/ColumnFlowGrid.spec.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect } from "vitest";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import ColumnFlowGrid from "../ColumnFlowGrid.vue";
+
+describe("ColumnFlowGrid", () => {
+  it("mounts without error", async () => {
+    const wrapper = await mountSuspended(ColumnFlowGrid);
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  it("renders as div by default", async () => {
+    const wrapper = await mountSuspended(ColumnFlowGrid);
+    expect(wrapper.element.tagName).toBe("DIV");
+  });
+
+  it("renders a different tag when provided", async () => {
+    const wrapper = await mountSuspended(ColumnFlowGrid, {
+      props: { tag: "section" },
+    });
+    expect(wrapper.element.tagName).toBe("SECTION");
+  });
+
+  it("renders slot content", async () => {
+    const wrapper = await mountSuspended(ColumnFlowGrid, {
+      slots: {
+        "item-1": "<div>Item 1</div>",
+      },
+    });
+    expect(wrapper.text()).toContain("Item 1");
+  });
+
+  it("renders each provided slot as its own column-flow-grid-item", async () => {
+    const wrapper = await mountSuspended(ColumnFlowGrid, {
+      slots: {
+        "item-1": "<div>Item 1</div>",
+        "item-2": "<div>Item 2</div>",
+        "item-3": "<div>Item 3</div>",
+      },
+    });
+    const items = wrapper.findAll(".column-flow-grid-item");
+    expect(items).toHaveLength(3);
+    expect(items[0]!.text()).toBe("Item 1");
+    expect(items[1]!.text()).toBe("Item 2");
+    expect(items[2]!.text()).toBe("Item 3");
+  });
+
+  it("renders no items when no slots are provided", async () => {
+    const wrapper = await mountSuspended(ColumnFlowGrid);
+    expect(wrapper.findAll(".column-flow-grid-item")).toHaveLength(0);
+  });
+
+  it("applies itemMinWidth and gap as inline CSS custom properties", async () => {
+    const wrapper = await mountSuspended(ColumnFlowGrid, {
+      props: { itemMinWidth: 250, gap: 2, unit: "em" },
+    });
+    const style = (wrapper.element as HTMLElement).style;
+    expect(style.getPropertyValue("--_item-min-width")).toBe("250px");
+    expect(style.getPropertyValue("--_column-flow-grid-gap")).toBe("2em");
+  });
+
+  it("applies styleClassPassthrough", async () => {
+    const wrapper = await mountSuspended(ColumnFlowGrid, {
+      props: { styleClassPassthrough: "custom-class" },
+    });
+    expect(wrapper.classes()).toContain("custom-class");
+  });
+
+  it("applies multiple styleClassPassthrough classes", async () => {
+    const wrapper = await mountSuspended(ColumnFlowGrid, {
+      props: { styleClassPassthrough: ["class-a", "class-b"] },
+    });
+    expect(wrapper.classes()).toContain("class-a");
+    expect(wrapper.classes()).toContain("class-b");
+  });
+});

package/app/components/01.atoms/grids/masonry-grid/CONSUMER-STYLING.md

@@ -0,0 +1,35 @@
+# MasonryGrid — Consumer Styling Guide
+
+## Public token API
+
+| Token | Falls back to | Controls |
+|---|---|---|
+| `--masonry-grid-item-border-colour` | `var(--theme-border)` | Outline colour around each item |
+| `--masonry-grid-item-padding` | `1.2rem` | Inner padding of each item |
+| `--masonry-grid-transition-duration` | `0.3s` | How long an item takes to slide into its new position on resize (respects `prefers-reduced-motion`) |
+
+Column width, gap, fixed-width mode, and alignment are controlled via props (`item-min-width`,
+`gap`, `fixed-width`, `justify`), not CSS custom properties — column count and item positions are
+computed in JS from measured pixel values. See `.claude/skills/components/masonry-grid.md`.
+
+---
+
+## Global theming — app-level CSS file
+
+```css
+:where(html) {
+  --masonry-grid-item-border-colour: var(--rose-05);
+  --masonry-grid-item-padding: 1.6rem;
+  --masonry-grid-transition-duration: 0.5s;
+}
+```
+
+---
+
+## Per-instance overrides
+
+```vue
+<MasonryGrid style="--masonry-grid-item-border-colour: var(--gold-04);">
+  ...
+</MasonryGrid>
+```

package/app/components/01.atoms/grids/masonry-grid/MasonryGrid.vue

@@ -0,0 +1,178 @@
+<template>
+  <component :is="tag" class="masonry-grid" :class="[elementClasses]">
+    <div ref="gridWrapper" class="masonry-grid-wrapper" :class="{ 'multiple-cols': !isSingleColumn }">
+      <div v-for="name in slotNames" :key="name" ref="gridItemRefs" class="masonry-grid-item">
+        <slot :name="name"></slot>
+      </div>
+    </div>
+  </component>
+</template>
+
+<script setup lang="ts">
+import { useElementSize } from "@vueuse/core";
+
+interface Props {
+  tag?: "div" | "section" | "article" | "main";
+  /** Minimum tile width in pixels — also the fixed tile width when `fixedWidth` is set. */
+  itemMinWidth?: number;
+  /** Gap between tiles in pixels. */
+  gap?: number;
+  /** Keep every tile at exactly `itemMinWidth` instead of stretching to fill each column. */
+  fixedWidth?: boolean;
+  /** How the block of tiles aligns within the wrapper — only visible when `fixedWidth` is set
+   * (tiles otherwise stretch to fill the full width, so there's nothing to align). */
+  justify?: "left" | "center" | "right";
+  styleClassPassthrough?: string | string[];
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  tag: "div",
+  itemMinWidth: 300,
+  gap: 12,
+  fixedWidth: false,
+  justify: "left",
+  styleClassPassthrough: () => [],
+});
+
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+const slots = useSlots();
+// Consumer-provided slot names, in natural authoring/DOM order — this is both the "data" this
+// component works with (no separate gridData/itemCount prop needed) and the order items are
+// measured and packed in, so reading order is always preserved: unlike a CSS `columns`-based
+// masonry, this never needs to reorder the DOM to keep visual and reading order in sync.
+const slotNames = computed(() => Object.keys(slots));
+
+const gridWrapper = ref<HTMLElement | null>(null);
+const gridItemRefs = ref<HTMLElement[]>([]);
+// Resize-reactive — useElementSize wires up its own ResizeObserver internally.
+const { width } = useElementSize(gridWrapper);
+
+const columnCount = computed(() => {
+  if (width.value === 0) return 1;
+  return Math.max(1, Math.floor(width.value / (props.itemMinWidth + props.gap)));
+});
+const isSingleColumn = computed(() => columnCount.value === 1);
+
+const gapPx = computed(() => `${props.gap}px`);
+const itemMinWidthPx = computed(() => `${props.itemMinWidth}px`);
+
+// Real masonry packing: each item, in natural DOM order, is measured and placed into whichever
+// column is currently shortest (a greedy bin-pack) — not CSS `columns`' column-fill, which packs
+// by accumulated height per column in DOM order and can't be reordered without breaking reading
+// order. Because placement follows DOM order directly, no reordering is ever needed here.
+function updateGrid() {
+  if (gridWrapper.value === null || columnCount.value <= 1) {
+    gridItemRefs.value.forEach((item) => {
+      item?.style.removeProperty("--_position");
+      item?.style.removeProperty("--_position-top");
+      item?.style.removeProperty("--_position-left");
+      item?.style.removeProperty("--_element-width");
+    });
+    gridWrapper.value?.style.removeProperty("--_wrapper-height");
+    return;
+  }
+
+  const wrapperWidth = width.value;
+  const itemWidth = props.fixedWidth
+    ? props.itemMinWidth
+    : Math.floor((wrapperWidth - (columnCount.value - 1) * props.gap) / columnCount.value);
+
+  // Columns are placed at fixed pixel steps (itemWidth + gap) rather than equal percentage slots
+  // of the container — a percentage slot only matches the item's actual width when the item
+  // stretches to fill it (the non-fixedWidth case); with fixedWidth, the item is narrower than an
+  // equal-percentage slot, and the leftover slot space would show up as a much bigger gap than
+  // `gap` actually specifies. `justify` shifts this whole fixed-width block left/center/right
+  // within the leftover space — done here in JS, not via CSS `justify-content`, since it has no
+  // effect on children once they're taken out of grid flow by `position: absolute` below.
+  const totalContentWidth = columnCount.value * itemWidth + (columnCount.value - 1) * props.gap;
+  const startX = props.fixedWidth
+    ? { left: 0, center: (wrapperWidth - totalContentWidth) / 2, right: wrapperWidth - totalContentWidth }[props.justify]
+    : 0;
+
+  const colHeights = Array(columnCount.value).fill(0);
+
+  gridItemRefs.value.forEach((item) => {
+    const minHeight = Math.min(...colHeights);
+    const minIndex = colHeights.indexOf(minHeight);
+
+    item?.style.setProperty("--_position", "absolute");
+    item?.style.setProperty("--_position-top", `${minHeight}px`);
+    item?.style.setProperty("--_position-left", `${startX + minIndex * (itemWidth + props.gap)}px`);
+    item?.style.setProperty("--_element-width", `${itemWidth}px`);
+
+    colHeights[minIndex] += Math.floor((item?.offsetHeight ?? 0) + props.gap);
+  });
+
+  const maxHeight = Math.max(...colHeights);
+  gridWrapper.value.style.setProperty("--_wrapper-height", `${maxHeight}px`);
+}
+
+// Re-pack whenever the measured width changes (useElementSize already wires up its own
+// ResizeObserver — a second explicit useResizeObserver call here would just duplicate it).
+watch(width, () => nextTick(() => updateGrid()));
+
+onMounted(() => {
+  nextTick(() => updateGrid());
+});
+
+watch(
+  () => [props.fixedWidth, props.justify, props.itemMinWidth, props.gap],
+  () => updateGrid()
+);
+
+watch(
+  () => props.styleClassPassthrough,
+  () => {
+    resetElementClasses(props.styleClassPassthrough);
+  }
+);
+</script>
+
+<style lang="css">
+@layer components {
+  .masonry-grid-wrapper {
+    container-type: inline-size;
+    position: relative;
+
+    display: grid;
+    gap: v-bind(gapPx);
+    /* Single column always stretches to fill the full width — with only one column there's no
+       "how many columns fit" question for itemMinWidth to answer, so applying its floor here
+       (minmax(itemMinWidth, 1fr)) only ever hurt: on a narrow container it fights the container
+       for space instead of just filling it. itemMinWidth starts governing column width once
+       there's an actual choice to make, from two columns up (below). */
+    grid-template-columns: 1fr;
+
+    height: var(--_wrapper-height, auto);
+
+    @container (min-width: 768px) {
+      grid-template-columns: repeat(2, minmax(v-bind(itemMinWidthPx), 1fr));
+    }
+    @container (min-width: 1024px) {
+      grid-template-columns: repeat(3, minmax(v-bind(itemMinWidthPx), 1fr));
+    }
+    @container (min-width: 1280px) {
+      grid-template-columns: repeat(4, minmax(v-bind(itemMinWidthPx), 1fr));
+    }
+
+    .masonry-grid-item {
+      outline: 0.1rem solid var(--masonry-grid-item-border-colour, var(--theme-border));
+      padding: var(--masonry-grid-item-padding, 1.2rem);
+    }
+
+    &.multiple-cols .masonry-grid-item {
+      position: var(--_position, static);
+      top: var(--_position-top, auto);
+      left: var(--_position-left, auto);
+      width: var(--_element-width, auto);
+
+      @media (prefers-reduced-motion: no-preference) {
+        transition:
+          top var(--masonry-grid-transition-duration, 0.3s) ease,
+          left var(--masonry-grid-transition-duration, 0.3s) ease;
+      }
+    }
+  }
+}
+</style>