srcdev-nuxt-components 9.1.28 → 9.1.29

package/app/components/01.atoms/banner-video/tests/BannerVideo.spec.ts

@@ -0,0 +1,374 @@
+import { describe, it, expect } from "vitest";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import { nextTick } from "vue";
+import BannerVideo from "../BannerVideo.vue";
+
+const defaultProps = {
+  src: "/images/banners/video/lake-banner.mp4",
+  poster: "/images/banners/video/lake-banner.jpg",
+};
+
+describe("BannerVideo", () => {
+  // ─── Mount ───────────────────────────────────────────────────────────────
+
+  it("mounts without error", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  // ─── Snapshots ───────────────────────────────────────────────────────────
+
+  it("renders correct HTML structure (default props)", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    expect(wrapper.html()).toMatchSnapshot();
+  });
+
+  it("renders correct HTML structure (all props set)", async () => {
+    const wrapper = await mountSuspended(BannerVideo, {
+      props: {
+        ...defaultProps,
+        tag: "header",
+        alt: "Lake banner",
+        imgWidth: 1280,
+        imgHeight: 720,
+        height: "40rem",
+        styleClassPassthrough: ["full-bleed"],
+      },
+    });
+    expect(wrapper.html()).toMatchSnapshot();
+  });
+
+  // ─── Root element ────────────────────────────────────────────────────────
+
+  it("renders a <section> as the root element by default", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    expect(wrapper.element.tagName).toBe("SECTION");
+  });
+
+  it("renders the specified tag as root", async () => {
+    for (const tag of ["div", "header", "main", "article"] as const) {
+      const wrapper = await mountSuspended(BannerVideo, {
+        props: { ...defaultProps, tag },
+      });
+      expect(wrapper.element.tagName).toBe(tag.toUpperCase());
+    }
+  });
+
+  it("always has the banner-video class", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    expect(wrapper.classes()).toContain("banner-video");
+  });
+
+  // ─── Video element ───────────────────────────────────────────────────────
+
+  it("renders a video element", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    expect(wrapper.find("video").exists()).toBe(true);
+  });
+
+  it("video has the video class", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    expect(wrapper.find("video").classes()).toContain("video");
+  });
+
+  it("video has autoplay attribute", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    expect(wrapper.find("video").attributes()).toHaveProperty("autoplay");
+  });
+
+  it("video has muted attribute", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    expect(wrapper.find("video").attributes()).toHaveProperty("muted");
+  });
+
+  it("video has loop attribute", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    expect(wrapper.find("video").attributes()).toHaveProperty("loop");
+  });
+
+  it("video has playsinline attribute", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    expect(wrapper.find("video").attributes()).toHaveProperty("playsinline");
+  });
+
+  it("video has the poster attribute set to the poster prop", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    expect(wrapper.find("video").attributes("poster")).toBe(defaultProps.poster);
+  });
+
+  it("video element has preload=auto", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    expect(wrapper.find("video").attributes("preload")).toBe("auto");
+  });
+
+  it("source element has the correct src", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    expect(wrapper.find("source").attributes("src")).toBe(defaultProps.src);
+  });
+
+  it("source element has type video/mp4", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    expect(wrapper.find("source").attributes("type")).toBe("video/mp4");
+  });
+
+  it("calls play() when loadeddata fires", async () => {
+    const play = vi.fn().mockResolvedValue(undefined);
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    (wrapper.find("video").element as HTMLVideoElement).play = play;
+    await wrapper.find("video").trigger("loadeddata");
+    expect(play).toHaveBeenCalled();
+  });
+
+  it("calls play() when canplay fires", async () => {
+    const play = vi.fn().mockResolvedValue(undefined);
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    (wrapper.find("video").element as HTMLVideoElement).play = play;
+    await wrapper.find("video").trigger("canplay");
+    expect(play).toHaveBeenCalled();
+  });
+
+  // ─── Fallback image ──────────────────────────────────────────────────────
+
+  it("renders a NuxtImg fallback element", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    expect(wrapper.find("img[data-nuxt-img]").exists()).toBe(true);
+  });
+
+  it("fallback image has the fallback class", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    expect(wrapper.find("img[data-nuxt-img]").classes()).toContain("fallback");
+  });
+
+  it("fallback image src contains the poster filename", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    const src = wrapper.find("img[data-nuxt-img]").attributes("src") ?? "";
+    expect(src).toContain("lake-banner.jpg");
+  });
+
+  it("fallback image alt defaults to empty string", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    expect(wrapper.find("img[data-nuxt-img]").attributes("alt")).toBe("");
+  });
+
+  it("fallback image alt reflects the alt prop", async () => {
+    const wrapper = await mountSuspended(BannerVideo, {
+      props: { ...defaultProps, alt: "A serene lake" },
+    });
+    expect(wrapper.find("img[data-nuxt-img]").attributes("alt")).toBe("A serene lake");
+  });
+
+  it("fallback image width defaults to 1920", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    expect(wrapper.find("img[data-nuxt-img]").attributes("width")).toBe("1920");
+  });
+
+  it("fallback image height defaults to 1080", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    expect(wrapper.find("img[data-nuxt-img]").attributes("height")).toBe("1080");
+  });
+
+  it("fallback image uses custom imgWidth and imgHeight when provided", async () => {
+    const wrapper = await mountSuspended(BannerVideo, {
+      props: { ...defaultProps, imgWidth: 1280, imgHeight: 720 },
+    });
+    const img = wrapper.find("img[data-nuxt-img]");
+    expect(img.attributes("width")).toBe("1280");
+    expect(img.attributes("height")).toBe("720");
+  });
+
+  it("fallback image has loading=eager", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    expect(wrapper.find("img[data-nuxt-img]").attributes("loading")).toBe("eager");
+  });
+
+  it("fallback image has decoding=async", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    expect(wrapper.find("img[data-nuxt-img]").attributes("decoding")).toBe("async");
+  });
+
+  // ─── CSS custom properties ───────────────────────────────────────────────
+
+  it("sets --_max-height to 56rem by default", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    const style = (wrapper.element as HTMLElement).style;
+    expect(style.getPropertyValue("--_max-height")).toBe("56rem");
+  });
+
+  it("reflects maxHeight prop in --_max-height", async () => {
+    const wrapper = await mountSuspended(BannerVideo, {
+      props: { ...defaultProps, maxHeight: "80rem" },
+    });
+    const style = (wrapper.element as HTMLElement).style;
+    expect(style.getPropertyValue("--_max-height")).toBe("80rem");
+  });
+
+  it("does not set --_max-height-tablet when maxHeightTablet is not provided", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    const style = (wrapper.element as HTMLElement).style;
+    expect(style.getPropertyValue("--_max-height-tablet")).toBe("");
+  });
+
+  it("reflects maxHeightTablet prop in --_max-height-tablet", async () => {
+    const wrapper = await mountSuspended(BannerVideo, {
+      props: { ...defaultProps, maxHeightTablet: "48rem" },
+    });
+    const style = (wrapper.element as HTMLElement).style;
+    expect(style.getPropertyValue("--_max-height-tablet")).toBe("48rem");
+  });
+
+  it("does not set --_max-height-mobile when maxHeightMobile is not provided", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    const style = (wrapper.element as HTMLElement).style;
+    expect(style.getPropertyValue("--_max-height-mobile")).toBe("");
+  });
+
+  it("reflects maxHeightMobile prop in --_max-height-mobile", async () => {
+    const wrapper = await mountSuspended(BannerVideo, {
+      props: { ...defaultProps, maxHeightMobile: "32rem" },
+    });
+    const style = (wrapper.element as HTMLElement).style;
+    expect(style.getPropertyValue("--_max-height-mobile")).toBe("32rem");
+  });
+
+  it("sets --_aspect-ratio to 21/9 by default", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    const style = (wrapper.element as HTMLElement).style;
+    expect(style.getPropertyValue("--_aspect-ratio")).toBe("21/9");
+  });
+
+  it("reflects aspectRatio prop in --_aspect-ratio", async () => {
+    const wrapper = await mountSuspended(BannerVideo, {
+      props: { ...defaultProps, aspectRatio: "16/9" },
+    });
+    const style = (wrapper.element as HTMLElement).style;
+    expect(style.getPropertyValue("--_aspect-ratio")).toBe("16/9");
+  });
+
+  it("sets object-fit to cover on the video element by default", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    const style = (wrapper.find("video").element as HTMLElement).style;
+    expect(style.objectFit).toBe("cover");
+  });
+
+  it("reflects objectFit prop on the video element", async () => {
+    const wrapper = await mountSuspended(BannerVideo, {
+      props: { ...defaultProps, objectFit: "contain" },
+    });
+    const style = (wrapper.find("video").element as HTMLElement).style;
+    expect(style.objectFit).toBe("contain");
+  });
+
+  it("sets object-fit to cover on the fallback image by default", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    const style = (wrapper.find("img[data-nuxt-img]").element as HTMLElement).style;
+    expect(style.objectFit).toBe("cover");
+  });
+
+  it("reflects objectFit prop on the fallback image", async () => {
+    const wrapper = await mountSuspended(BannerVideo, {
+      props: { ...defaultProps, objectFit: "contain" },
+    });
+    const style = (wrapper.find("img[data-nuxt-img]").element as HTMLElement).style;
+    expect(style.objectFit).toBe("contain");
+  });
+
+  it("video element does not have object-position style", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    const style = (wrapper.find("video").element as HTMLElement).style;
+    expect(style.objectPosition).toBe("");
+  });
+
+  it("sets --_align-self to center by default", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    const style = (wrapper.element as HTMLElement).style;
+    expect(style.getPropertyValue("--_align-self")).toBe("center");
+  });
+
+  it("reflects verticalPosition prop in --_align-self", async () => {
+    for (const [prop, expected] of [["start", "start"], ["end", "end"]] as const) {
+      const wrapper = await mountSuspended(BannerVideo, {
+        props: { ...defaultProps, verticalPosition: prop },
+      });
+      expect((wrapper.element as HTMLElement).style.getPropertyValue("--_align-self")).toBe(expected);
+    }
+  });
+
+  it("sets --_justify-self to center by default", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    const style = (wrapper.element as HTMLElement).style;
+    expect(style.getPropertyValue("--_justify-self")).toBe("center");
+  });
+
+  it("reflects horizontalPosition prop in --_justify-self", async () => {
+    for (const [prop, expected] of [["start", "start"], ["end", "end"]] as const) {
+      const wrapper = await mountSuspended(BannerVideo, {
+        props: { ...defaultProps, horizontalPosition: prop },
+      });
+      expect((wrapper.element as HTMLElement).style.getPropertyValue("--_justify-self")).toBe(expected);
+    }
+  });
+
+  it("fallback image object-position defaults to center center", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    const style = (wrapper.find("img[data-nuxt-img]").element as HTMLElement).style;
+    expect(style.objectPosition).toBe("center center");
+  });
+
+  it("fallback image object-position reflects verticalPosition", async () => {
+    const wrapper = await mountSuspended(BannerVideo, {
+      props: { ...defaultProps, verticalPosition: "start" },
+    });
+    const style = (wrapper.find("img[data-nuxt-img]").element as HTMLElement).style;
+    expect(style.objectPosition).toBe("center top");
+  });
+
+  it("fallback image object-position reflects horizontalPosition", async () => {
+    const wrapper = await mountSuspended(BannerVideo, {
+      props: { ...defaultProps, horizontalPosition: "end" },
+    });
+    const style = (wrapper.find("img[data-nuxt-img]").element as HTMLElement).style;
+    expect(style.objectPosition).toBe("right center");
+  });
+
+  it("fallback image object-position reflects both verticalPosition and horizontalPosition", async () => {
+    const wrapper = await mountSuspended(BannerVideo, {
+      props: { ...defaultProps, verticalPosition: "end", horizontalPosition: "start" },
+    });
+    const style = (wrapper.find("img[data-nuxt-img]").element as HTMLElement).style;
+    expect(style.objectPosition).toBe("left bottom");
+  });
+
+  // ─── styleClassPassthrough ───────────────────────────────────────────────
+
+  it("applies a single styleClassPassthrough string to the root", async () => {
+    const wrapper = await mountSuspended(BannerVideo, {
+      props: { ...defaultProps, styleClassPassthrough: "full-bleed" },
+    });
+    expect(wrapper.classes()).toContain("full-bleed");
+  });
+
+  it("applies multiple styleClassPassthrough classes from an array", async () => {
+    const wrapper = await mountSuspended(BannerVideo, {
+      props: { ...defaultProps, styleClassPassthrough: ["full-bleed", "mbe-0"] },
+    });
+    expect(wrapper.classes()).toContain("full-bleed");
+    expect(wrapper.classes()).toContain("mbe-0");
+  });
+
+  it("does not apply styleClassPassthrough to the video element", async () => {
+    const wrapper = await mountSuspended(BannerVideo, {
+      props: { ...defaultProps, styleClassPassthrough: "full-bleed" },
+    });
+    expect(wrapper.find("video").classes()).not.toContain("full-bleed");
+  });
+
+  it("updates classes when styleClassPassthrough prop changes", async () => {
+    const wrapper = await mountSuspended(BannerVideo, {
+      props: { ...defaultProps, styleClassPassthrough: ["original"] },
+    });
+    expect(wrapper.classes()).toContain("original");
+    await wrapper.setProps({ styleClassPassthrough: ["updated"] });
+    expect(wrapper.classes()).not.toContain("original");
+    expect(wrapper.classes()).toContain("updated");
+  });
+});

package/app/components/01.atoms/banner-video/tests/__snapshots__/BannerVideo.spec.ts.snap

@@ -0,0 +1,13 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`BannerVideo > renders correct HTML structure (all props set) 1`] = `
+"<header class="banner-video full-bleed" style="--_max-height: 56rem; --_aspect-ratio: 21/9; --_align-self: center; --_justify-self: center;" height="40rem"><video class="video" autoplay="" muted="" loop="" playsinline="" preload="auto" poster="/images/banners/video/lake-banner.jpg" style="object-fit: cover;">
+    <source src="/images/banners/video/lake-banner.mp4" type="video/mp4">
+  </video><img width="1280" height="720" data-nuxt-img="" srcset="/_ipx/s_1280x720/images/banners/video/lake-banner.jpg 1x, /_ipx/s_2560x1440/images/banners/video/lake-banner.jpg 2x" class="fallback" alt="Lake banner" loading="eager" decoding="async" style="object-fit: cover; object-position: center center;" src="/_ipx/s_1280x720/images/banners/video/lake-banner.jpg"></header>"
+`;
+
+exports[`BannerVideo > renders correct HTML structure (default props) 1`] = `
+"<section class="banner-video" style="--_max-height: 56rem; --_aspect-ratio: 21/9; --_align-self: center; --_justify-self: center;"><video class="video" autoplay="" muted="" loop="" playsinline="" preload="auto" poster="/images/banners/video/lake-banner.jpg" style="object-fit: cover;">
+    <source src="/images/banners/video/lake-banner.mp4" type="video/mp4">
+  </video><img width="1920" height="1080" data-nuxt-img="" srcset="/_ipx/s_1920x1080/images/banners/video/lake-banner.jpg 1x, /_ipx/s_3840x2160/images/banners/video/lake-banner.jpg 2x" class="fallback" alt="" loading="eager" decoding="async" style="object-fit: cover; object-position: center center;" src="/_ipx/s_1920x1080/images/banners/video/lake-banner.jpg"></section>"
+`;

package/app/components/01.atoms/scroll-reveal-frame/ScrollRevealFrame.vue

@@ -0,0 +1,125 @@
+<template>
+  <figure
+    class="reveal-frame"
+    :class="[elementClasses]"
+    :style="{
+      '--_frame-height': frameHeight,
+      '--_parallax-offset': parallaxOffset,
+      '--_radius': radius,
+    }"
+  >
+    <div class="reveal-content">
+      <slot></slot>
+    </div>
+  </figure>
+</template>
+
+<script setup lang="ts">
+/**
+ * ScrollRevealFrame
+ *
+ * Generic clipping frame that pans its slot content vertically as it scrolls
+ * through the viewport — driven entirely by CSS Scroll-driven Animations.
+ * No scroll listeners, no JS animation.
+ *
+ * How it works:
+ *   - The <figure> is a fixed-height clipping window (overflow: hidden).
+ *   - It registers a named view-timeline scoped to itself.
+ *   - The inner .reveal-content wrapper is taller than the frame by
+ *     `parallaxOffset`, and animates translateY as the frame scrolls.
+ *   - Any slot content (single image, grid, video, etc.) fills that wrapper.
+ *
+ * Browser support (as of 2026):
+ *   Chrome 115+, Edge 115+, Firefox 114+, Safari 17.2+
+ *   Falls back gracefully to a static cropped view in older browsers.
+ *
+ * For single-image use with NuxtImg optimisation and focal-point control,
+ * use ScrollRevealImage instead — it wraps this component.
+ */
+
+interface Props {
+  /** Height of the visible clipping frame. */
+  frameHeight?: string;
+  /**
+   * How far the content travels vertically as the frame scrolls through the
+   * viewport. Larger = more content revealed = stronger parallax feel.
+   */
+  parallaxOffset?: string;
+  /** Optional rounded corners on the frame. */
+  radius?: string;
+  styleClassPassthrough?: string | string[];
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  frameHeight: "540px",
+  parallaxOffset: "36rem",
+  radius: "0px",
+  styleClassPassthrough: () => [],
+});
+
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+watch(
+  () => props.styleClassPassthrough,
+  () => resetElementClasses(props.styleClassPassthrough)
+);
+</script>
+
+<style lang="css">
+@layer components {
+  .reveal-frame {
+    /* Public tokens (overridable by consumer) */
+    --_frame-height: 540px;
+    --_parallax-offset: 36rem;
+    --_radius: 0px;
+
+    position: relative;
+    height: var(--_frame-height);
+    width: 100%;
+    overflow: hidden;
+    border-radius: var(--_radius);
+
+    /*
+     * Named view-timeline lets the child content reference this element's
+     * scroll progress rather than its own (which would be distorted by the
+     * artificially inflated height).
+     */
+    view-timeline: --reveal-frame-timeline block;
+  }
+
+  .reveal-content {
+    display: block;
+    width: 100%;
+    /*
+     * Content is taller than the frame by parallaxOffset so there is always
+     * content to travel into as the animation progresses.
+     */
+    height: calc(100% + var(--_parallax-offset));
+
+    animation: reveal-pan linear both;
+    animation-timeline: --reveal-frame-timeline;
+    animation-range: entry 0% exit 100%;
+  }
+
+  @keyframes reveal-pan {
+    from { transform: translateY(0); }
+    to   { transform: translateY(calc(-1 * var(--_parallax-offset))); }
+  }
+
+  /* ── Fallback: browsers without Scroll-driven Animations ── */
+  @supports not (animation-timeline: scroll()) {
+    .reveal-content {
+      animation: none;
+      height: 100%;
+    }
+  }
+
+  /* ── Reduced-motion: static view, no travel ── */
+  @media (prefers-reduced-motion: reduce) {
+    .reveal-content {
+      animation: none;
+      height: 100%;
+    }
+  }
+}
+</style>

package/app/components/01.atoms/scroll-reveal-frame/stories/ScrollRevealFrame.stories.ts

@@ -0,0 +1,166 @@
+import ScrollRevealFrame from "../ScrollRevealFrame.vue";
+import type { Meta, StoryObj } from "@nuxtjs/storybook";
+
+const meta: Meta<typeof ScrollRevealFrame> = {
+  title: "Atoms/Effects/ScrollRevealFrame",
+  component: ScrollRevealFrame,
+  argTypes: {
+    frameHeight: {
+      control: "text",
+      description: "Height of the visible clipping frame",
+      table: { category: "Layout" },
+    },
+    parallaxOffset: {
+      control: "text",
+      description: "Distance the content travels vertically as the frame scrolls through the viewport",
+      table: { category: "Layout" },
+    },
+    radius: {
+      control: "text",
+      description: "Border-radius applied to the clipping frame",
+      table: { category: "Appearance" },
+    },
+    styleClassPassthrough: {
+      table: { disable: true },
+    },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Generic clipping frame that pans any slot content vertically as it scrolls through the viewport — driven entirely by CSS Scroll-driven Animations. No scroll listeners, no JS. Use this when you need the parallax reveal with arbitrary content (grids, video, etc.). For a single NuxtImg with optimisation and focal-point control, use ScrollRevealImage instead.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ScrollRevealFrame>;
+
+const scrollWrapper = (inner: string) => `
+  <div style="padding-block: 60vh; max-width: 860px; margin-inline: auto;">
+    <p style="text-align: center; font-size: 1.4rem; opacity: 0.5; margin-block-end: 4rem;">Scroll to see the parallax effect</p>
+    ${inner}
+  </div>
+`;
+
+export const Default: Story = {
+  args: {
+    frameHeight: "540px",
+    parallaxOffset: "36rem",
+    radius: "0px",
+  },
+  render: (args) => ({
+    components: { ScrollRevealFrame },
+    setup() {
+      return { args };
+    },
+    template: scrollWrapper(`
+      <ScrollRevealFrame v-bind="args">
+        <img
+          src="/images/page/hero/hero-blonde.jpg"
+          alt="Blonde hair portrait"
+          style="display: block; width: 100%; height: 100%; object-fit: cover;"
+        />
+      </ScrollRevealFrame>
+    `),
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story: "Default props — a single image in the slot panning from top to bottom as the frame crosses the viewport.",
+      },
+    },
+  },
+};
+
+export const ImageGrid: Story = {
+  args: {
+    frameHeight: "480px",
+    parallaxOffset: "36rem",
+    radius: "0px",
+  },
+  render: (args) => ({
+    components: { ScrollRevealFrame },
+    setup() {
+      return { args };
+    },
+    template: scrollWrapper(`
+      <ScrollRevealFrame v-bind="args">
+        <div style="display: grid; grid-template-columns: repeat(3, 1fr); grid-template-rows: repeat(2, 1fr); gap: 4px; height: 100%;">
+          <div style="overflow: hidden; min-height: 0;">
+            <img src="/images/services/service-balayage.jpg" alt="Balayage" style="width: 100%; height: 100%; object-fit: cover; display: block;" />
+          </div>
+          <div style="overflow: hidden; min-height: 0;">
+            <img src="/images/services/service-colour.jpg" alt="Colour" style="width: 100%; height: 100%; object-fit: cover; display: block;" />
+          </div>
+          <div style="overflow: hidden; min-height: 0;">
+            <img src="/images/services/service-cut.jpg" alt="Cut" style="width: 100%; height: 100%; object-fit: cover; display: block;" />
+          </div>
+          <div style="overflow: hidden; min-height: 0;">
+            <img src="/images/services/service-highlights.jpg" alt="Highlights" style="width: 100%; height: 100%; object-fit: cover; display: block;" />
+          </div>
+          <div style="overflow: hidden; min-height: 0;">
+            <img src="/images/services/service-lowlights.jpg" alt="Lowlights" style="width: 100%; height: 100%; object-fit: cover; display: block;" />
+          </div>
+          <div style="overflow: hidden; min-height: 0;">
+            <img src="/images/services/service-toner.jpg" alt="Toner" style="width: 100%; height: 100%; object-fit: cover; display: block;" />
+          </div>
+        </div>
+      </ScrollRevealFrame>
+    `),
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story: "A six-image CSS grid in the slot — all six images pan together as a single unit. This is the primary use case for ScrollRevealFrame over ScrollRevealImage.",
+      },
+    },
+  },
+};
+
+export const RoundedCorners: Story = {
+  args: {
+    frameHeight: "480px",
+    parallaxOffset: "36rem",
+    radius: "2.4rem",
+  },
+  render: Default.render,
+  parameters: {
+    docs: {
+      description: {
+        story: "The radius prop applies border-radius to the clipping frame. The reveal stays contained within the rounded shape.",
+      },
+    },
+  },
+};
+
+export const ShortFrame: Story = {
+  args: {
+    frameHeight: "320px",
+    parallaxOffset: "24rem",
+    radius: "0px",
+  },
+  render: (args) => ({
+    components: { ScrollRevealFrame },
+    setup() {
+      return { args };
+    },
+    template: scrollWrapper(`
+      <ScrollRevealFrame v-bind="args">
+        <img
+          src="/images/banners/banner-mid-brown.webp"
+          alt="Mid brown hair banner"
+          style="display: block; width: 100%; height: 100%; object-fit: cover;"
+        />
+      </ScrollRevealFrame>
+    `),
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story: "A shallow banner frame. parallaxOffset is reduced proportionally to match the shorter frame height.",
+      },
+    },
+  },
+};