srcdev-nuxt-components 9.4.6 → 9.4.7

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>

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

@@ -0,0 +1,199 @@
+import type { Meta, StoryFn } from "@nuxtjs/storybook";
+import MasonryGrid from "../MasonryGrid.vue";
+
+interface MasonryGridArgs {
+  tag: "div" | "section" | "article" | "main";
+  itemMinWidth: number;
+  gap: number;
+  fixedWidth: boolean;
+  justify: "left" | "center" | "right";
+  styleClassPassthrough: string[];
+}
+
+const meta: Meta<MasonryGridArgs> = {
+  title: "Atoms/Grids/MasonryGrid",
+  component: MasonryGrid,
+  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 tile width in pixels — also the fixed tile width when fixedWidth is set",
+      table: { category: "Props" },
+    },
+    gap: {
+      control: { type: "select" },
+      options: [0, 4, 8, 12, 16, 24, 32],
+      description: "Gap between tiles in pixels",
+      table: { category: "Props" },
+    },
+    fixedWidth: {
+      control: { type: "boolean" },
+      description: "Keep every tile at exactly itemMinWidth instead of stretching to fill each column",
+      table: { category: "Props" },
+    },
+    justify: {
+      control: { type: "select" },
+      options: ["left", "center", "right"],
+      description: "How the block of tiles aligns within the wrapper — only visible when fixedWidth is set",
+      table: { category: "Props" },
+    },
+    styleClassPassthrough: {
+      table: { disable: true },
+    },
+  },
+  args: {
+    tag: "div",
+    itemMinWidth: 300,
+    gap: 12,
+    fixedWidth: false,
+    justify: "left",
+    styleClassPassthrough: [],
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "A real masonry layout: each item is measured and placed into whichever column is " +
+          "currently shortest (a greedy bin-pack), not CSS `columns`' column-fill. Renders " +
+          "whatever slots the consumer passes, in natural DOM/reading order — no count/data prop " +
+          "needed, and no reordering trick required (unlike a `columns`-based masonry) since " +
+          "placement already follows the order items were authored in. Resize-reactive: items " +
+          "animate into their new position (respecting `prefers-reduced-motion`) as the container " +
+          "resizes. See `ColumnFlowGrid` for the lighter, non-measuring CSS `columns` alternative.",
+      },
+    },
+  },
+};
+
+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/reading order as a numbered badge. Unlike a reading-order effect based
+// on rearranging DOM order to match a visual grid, here the number is simply the authoring order —
+// tab/screen-reader order always reads 1, 2, 3... regardless of which column an item's measured
+// height ends up placing it in visually.
+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.",
+];
+
+const itemBadge = (n: number) => `<span style="${badgeStyle}">${n}</span><br />`;
+
+interface DemoItem {
+  slotName: string;
+  index: number;
+  bodyHtml: string;
+}
+
+// Built once per mount (not on every render) so a Controls-panel change doesn't reshuffle the
+// demo content underneath it. Random paragraph counts (1-4) give genuinely uneven heights —
+// necessary to actually see the shortest-column packing at work, unlike uniform-height tiles.
+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<MasonryGridArgs> = (args) => ({
+  components: { MasonryGrid },
+  setup() {
+    const items = buildDemoItems(12);
+    return { args, items };
+  },
+  template: `
+    <div style="padding: 3.2rem; background: #f9fafb;">
+      <MasonryGrid 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>
+      </MasonryGrid>
+    </div>
+  `,
+});
+
+export const Default = Template.bind({});
+Default.parameters = {
+  docs: {
+    description: {
+      story:
+        "12 numbered items with 1-4 random paragraphs each, flowing into whichever column is " +
+        "currently shortest. Resize the preview panel — items animate into their new positions, " +
+        "and DOM/tab order always stays 1, 2, 3... regardless of which column each ends up in.",
+    },
+  },
+};
+
+export const NarrowColumns = Template.bind({});
+NarrowColumns.args = { itemMinWidth: 160, gap: 8 };
+NarrowColumns.parameters = {
+  docs: {
+    description: { story: "A smaller `itemMinWidth` fits more, narrower columns." },
+  },
+};
+
+export const WideColumns = Template.bind({});
+WideColumns.args = { itemMinWidth: 450, gap: 16 };
+WideColumns.parameters = {
+  docs: {
+    description: { story: "A larger `itemMinWidth` fits fewer, wider columns." },
+  },
+};
+
+export const FixedWidthCentered = Template.bind({});
+FixedWidthCentered.storyName = "Fixed Width, Centered";
+FixedWidthCentered.args = { fixedWidth: true, justify: "center", itemMinWidth: 240 };
+FixedWidthCentered.parameters = {
+  docs: {
+    description: {
+      story:
+        "`fixedWidth` keeps every tile at exactly `itemMinWidth` instead of stretching to fill " +
+        "each column — `justify` then controls how the resulting (narrower) block of tiles " +
+        "aligns within the available width.",
+    },
+  },
+};
+
+export const TwoItems: StoryFn<MasonryGridArgs> = (args) => ({
+  components: { MasonryGrid },
+  setup() {
+    return { args };
+  },
+  template: `
+    <div style="padding: 3.2rem; background: #f9fafb;">
+      <MasonryGrid 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>
+      </MasonryGrid>
+    </div>
+  `,
+});
+TwoItems.storyName = "Two Items (no count prop needed)";