srcdev-nuxt-components 9.1.28 → 9.1.30

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.",
+      },
+    },
+  },
+};

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

@@ -0,0 +1,148 @@
+import { describe, it, expect } from "vitest";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import ScrollRevealFrame from "../ScrollRevealFrame.vue";
+
+describe("ScrollRevealFrame", () => {
+  // ─── Mount ───────────────────────────────────────────────────────────────
+
+  it("mounts without error", async () => {
+    const wrapper = await mountSuspended(ScrollRevealFrame);
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  // ─── Snapshots ───────────────────────────────────────────────────────────
+
+  it("renders correct HTML structure (default props)", async () => {
+    const wrapper = await mountSuspended(ScrollRevealFrame);
+    expect(wrapper.html()).toMatchSnapshot();
+  });
+
+  it("renders correct HTML structure (all props set)", async () => {
+    const wrapper = await mountSuspended(ScrollRevealFrame, {
+      props: {
+        frameHeight: "400px",
+        parallaxOffset: "20rem",
+        radius: "1.6rem",
+        styleClassPassthrough: ["custom-class"],
+      },
+    });
+    expect(wrapper.html()).toMatchSnapshot();
+  });
+
+  // ─── Root element ────────────────────────────────────────────────────────
+
+  it("renders a <figure> as the root element", async () => {
+    const wrapper = await mountSuspended(ScrollRevealFrame);
+    expect(wrapper.element.tagName).toBe("FIGURE");
+  });
+
+  it("always has the reveal-frame class", async () => {
+    const wrapper = await mountSuspended(ScrollRevealFrame);
+    expect(wrapper.classes()).toContain("reveal-frame");
+  });
+
+  // ─── Inner content wrapper ───────────────────────────────────────────────
+
+  it("renders a .reveal-content child element", async () => {
+    const wrapper = await mountSuspended(ScrollRevealFrame);
+    expect(wrapper.find(".reveal-content").exists()).toBe(true);
+  });
+
+  // ─── Slot ────────────────────────────────────────────────────────────────
+
+  it("renders slot content inside .reveal-content", async () => {
+    const wrapper = await mountSuspended(ScrollRevealFrame, {
+      slots: { default: "<p class='slot-child'>Hello</p>" },
+    });
+    const content = wrapper.find(".reveal-content");
+    expect(content.find(".slot-child").exists()).toBe(true);
+    expect(content.find(".slot-child").text()).toBe("Hello");
+  });
+
+  it("renders multiple slot children inside .reveal-content", async () => {
+    const wrapper = await mountSuspended(ScrollRevealFrame, {
+      slots: { default: "<div class='child-a'></div><div class='child-b'></div>" },
+    });
+    const content = wrapper.find(".reveal-content");
+    expect(content.find(".child-a").exists()).toBe(true);
+    expect(content.find(".child-b").exists()).toBe(true);
+  });
+
+  // ─── CSS custom properties ───────────────────────────────────────────────
+
+  it("sets --_frame-height to 540px by default", async () => {
+    const wrapper = await mountSuspended(ScrollRevealFrame);
+    const style = (wrapper.element as HTMLElement).style;
+    expect(style.getPropertyValue("--_frame-height")).toBe("540px");
+  });
+
+  it("sets --_parallax-offset to 36rem by default", async () => {
+    const wrapper = await mountSuspended(ScrollRevealFrame);
+    const style = (wrapper.element as HTMLElement).style;
+    expect(style.getPropertyValue("--_parallax-offset")).toBe("36rem");
+  });
+
+  it("sets --_radius to 0px by default", async () => {
+    const wrapper = await mountSuspended(ScrollRevealFrame);
+    const style = (wrapper.element as HTMLElement).style;
+    expect(style.getPropertyValue("--_radius")).toBe("0px");
+  });
+
+  it("reflects frameHeight prop in --_frame-height", async () => {
+    const wrapper = await mountSuspended(ScrollRevealFrame, {
+      props: { frameHeight: "80vh" },
+    });
+    const style = (wrapper.element as HTMLElement).style;
+    expect(style.getPropertyValue("--_frame-height")).toBe("80vh");
+  });
+
+  it("reflects parallaxOffset prop in --_parallax-offset", async () => {
+    const wrapper = await mountSuspended(ScrollRevealFrame, {
+      props: { parallaxOffset: "48rem" },
+    });
+    const style = (wrapper.element as HTMLElement).style;
+    expect(style.getPropertyValue("--_parallax-offset")).toBe("48rem");
+  });
+
+  it("reflects radius prop in --_radius", async () => {
+    const wrapper = await mountSuspended(ScrollRevealFrame, {
+      props: { radius: "2.4rem" },
+    });
+    const style = (wrapper.element as HTMLElement).style;
+    expect(style.getPropertyValue("--_radius")).toBe("2.4rem");
+  });
+
+  // ─── styleClassPassthrough ───────────────────────────────────────────────
+
+  it("applies a single styleClassPassthrough string to the root", async () => {
+    const wrapper = await mountSuspended(ScrollRevealFrame, {
+      props: { styleClassPassthrough: "hero-frame" },
+    });
+    expect(wrapper.classes()).toContain("hero-frame");
+  });
+
+  it("applies multiple styleClassPassthrough classes from an array", async () => {
+    const wrapper = await mountSuspended(ScrollRevealFrame, {
+      props: { styleClassPassthrough: ["hero-frame", "mbe-32"] },
+    });
+    expect(wrapper.classes()).toContain("hero-frame");
+    expect(wrapper.classes()).toContain("mbe-32");
+  });
+
+  it("does not apply styleClassPassthrough to .reveal-content", async () => {
+    const wrapper = await mountSuspended(ScrollRevealFrame, {
+      props: { styleClassPassthrough: "hero-frame" },
+    });
+    expect(wrapper.find(".reveal-content").classes()).not.toContain("hero-frame");
+  });
+
+  it("updates classes when styleClassPassthrough prop changes", async () => {
+    const wrapper = await mountSuspended(ScrollRevealFrame, {
+      props: { 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/scroll-reveal-frame/tests/__snapshots__/ScrollRevealFrame.spec.ts.snap

@@ -0,0 +1,13 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`ScrollRevealFrame > renders correct HTML structure (all props set) 1`] = `
+"<figure class="reveal-frame custom-class" style="--_frame-height: 400px; --_parallax-offset: 20rem; --_radius: 1.6rem;">
+  <div class="reveal-content"></div>
+</figure>"
+`;
+
+exports[`ScrollRevealFrame > renders correct HTML structure (default props) 1`] = `
+"<figure class="reveal-frame" style="--_frame-height: 540px; --_parallax-offset: 36rem; --_radius: 0px;">
+  <div class="reveal-content"></div>
+</figure>"
+`;

package/app/components/01.atoms/scroll-reveal-image/ScrollRevealImage.vue

@@ -0,0 +1,96 @@
+<template>
+  <ScrollRevealFrame
+    :frame-height="frameHeight"
+    :parallax-offset="parallaxOffset"
+    :radius="radius"
+    :style-class-passthrough="styleClassPassthrough"
+    :style="{ '--_focal-x': focalX }"
+  >
+    <NuxtImg
+      class="reveal-image"
+      :src="src"
+      :alt="alt"
+      :width="imgWidth"
+      :height="imgHeight"
+      loading="lazy"
+      decoding="async"
+    />
+  </ScrollRevealFrame>
+</template>
+
+<script setup lang="ts">
+/**
+ * ScrollRevealImage
+ *
+ * A single-image convenience wrapper around ScrollRevealFrame.
+ * Adds NuxtImg optimisation (src, alt, intrinsic dimensions) and horizontal
+ * focal-point control (focalX → CSS object-position x-axis).
+ *
+ * For a grid of images or arbitrary slot content use ScrollRevealFrame directly.
+ */
+
+interface Props {
+  src: string;
+  alt?: string;
+  /** Intrinsic width of the source image — required for NuxtImg optimisation. */
+  imgWidth?: number;
+  /** Intrinsic height of the source image — required for NuxtImg optimisation. */
+  imgHeight?: number;
+  /** Height of the visible clipping frame. */
+  frameHeight?: string;
+  /**
+   * How far the image travels vertically as the frame scrolls through the
+   * viewport. Larger = more image revealed = stronger parallax feel.
+   */
+  parallaxOffset?: string;
+  /**
+   * Horizontal focal point — CSS `object-position` x-axis value.
+   * Controls which horizontal slice of the image is kept in view.
+   * Examples: "50%", "left", "30%".
+   */
+  focalX?: string;
+  /** Optional rounded corners on the frame. */
+  radius?: string;
+  styleClassPassthrough?: string | string[];
+}
+
+withDefaults(defineProps<Props>(), {
+  alt: "",
+  imgWidth: 1920,
+  imgHeight: 1080,
+  frameHeight: "540px",
+  parallaxOffset: "36rem",
+  focalX: "50%",
+  radius: "0px",
+  styleClassPassthrough: () => [],
+});
+</script>
+
+<style lang="css">
+@layer components {
+  .reveal-image {
+    display: block;
+    width: 100%;
+    height: 100%;
+    object-fit: cover;
+    /*
+     * Y is always 0% — ScrollRevealFrame's translateY handles vertical travel.
+     * focalX (--_focal-x) lets the consumer pin the horizontal crop point.
+     */
+    object-position: var(--_focal-x, 50%) 0%;
+  }
+
+  /* ── Fallback: centre the crop vertically when there is no animation ── */
+  @supports not (animation-timeline: scroll()) {
+    .reveal-image {
+      object-position: var(--_focal-x, 50%) 50%;
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .reveal-image {
+      object-position: var(--_focal-x, 50%) 50%;
+    }
+  }
+}
+</style>