srcdev-nuxt-components 9.4.4 → 9.4.6

package/.vscode/srcdev-component-marquee-scroller.code-snippets

@@ -0,0 +1,93 @@
+{
+  "SRCDEV MarqueeScroller Basic": {
+    "description": "MarqueeScroller — infinite horizontal logo/badge scroller with per-item slots",
+    "scope": "vue,html",
+    "body": [
+      "<MarqueeScroller",
+      "  :marquee-data=\"[",
+      "    { id: 1, content: '$1logo-a' },",
+      "    { id: 2, content: '$2logo-b' },",
+      "  ]\"",
+      "  :item-config=\"{ width: '${3:120px}', height: '${4:60px}', gap: '${5:24px}' }\"",
+      ">",
+      "  <template #1>",
+      "    $6",
+      "  </template>",
+      "  <template #2>",
+      "    $7",
+      "  </template>",
+      "</MarqueeScroller>"
+    ]
+  },
+  "SRCDEV MarqueeScroller With Controls": {
+    "description": "MarqueeScroller with the visible pause/play control button (WCAG 2.2.2)",
+    "scope": "vue,html",
+    "body": [
+      "<MarqueeScroller",
+      "  :marquee-data=\"$1items\"",
+      "  show-controls",
+      "  aria-label=\"$2Scrolling client logos\"",
+      ">",
+      "  <template v-for=\"item in $1items\" #[item.id] :key=\"item.id\">",
+      "    $3",
+      "  </template>",
+      "</MarqueeScroller>"
+    ]
+  },
+  "SRCDEV MarqueeScroller Custom Control Icon/Copy": {
+    "description": "MarqueeScroller control button with custom icons and localised aria-labels",
+    "scope": "vue,html",
+    "body": [
+      "<MarqueeScroller",
+      "  :marquee-data=\"$1items\"",
+      "  show-controls",
+      "  play-icon=\"${2:mdi:play-circle}\"",
+      "  pause-icon=\"${3:mdi:pause-circle}\"",
+      "  play-label=\"${4:Play}\"",
+      "  pause-label=\"${5:Pause}\"",
+      ">",
+      "  <template v-for=\"item in $1items\" #[item.id] :key=\"item.id\">",
+      "    $6",
+      "  </template>",
+      "</MarqueeScroller>"
+    ]
+  },
+  "SRCDEV MarqueeScroller Custom Toggle Icon Slot": {
+    "description": "MarqueeScroller with the toggle-icon slot fully replacing the control button's icon",
+    "scope": "vue,html",
+    "body": [
+      "<MarqueeScroller :marquee-data=\"$1items\" show-controls>",
+      "  <template #toggle-icon=\"{ isPaused }\">",
+      "    $2",
+      "  </template>",
+      "</MarqueeScroller>"
+    ]
+  },
+  "SRCDEV MarqueeScroller CSS Override": {
+    "description": "CSS override scaffold for MarqueeScroller — scope to a page or section class",
+    "scope": "css",
+    "body": [
+      ".$1my-page {",
+      "  .marquee-scroller {",
+      "    --marquee-scroller-fade-width: ;",
+      "    --marquee-scroller-focus-outline-width: ;",
+      "    --marquee-scroller-focus-outline-offset: ;",
+      "    --marquee-scroller-item-border-colour: ;",
+      "    --marquee-scroller-item-border-width: ;",
+      "    --marquee-scroller-item-border-radius: ;",
+      "    --marquee-scroller-item-transition-duration: ;",
+      "    --marquee-scroller-group-hover-filter: ;",
+      "    --marquee-scroller-item-hover-filter: ;",
+      "    --marquee-scroller-control-offset: ;",
+      "    --marquee-scroller-control-background-colour: ;",
+      "    --marquee-scroller-control-background-colour-hover: ;",
+      "    --marquee-scroller-control-text-colour: ;",
+      "    --marquee-scroller-control-border-radius: ;",
+      "    --marquee-scroller-control-border-width: ;",
+      "    --marquee-scroller-control-padding: ;",
+      "    --marquee-scroller-control-font-size: ;",
+      "  }",
+      "}"
+    ]
+  }
+}

package/.vscode/srcdev-component-responsive-header.code-snippets

@@ -15,6 +15,18 @@
       "</ResponsiveHeader>"
     ]
   },
+  "SRCDEV ResponsiveHeader Localised Nav Labels": {
+    "description": "ResponsiveHeader with localised aria-labels on the main/secondary nav landmarks and overflow menu",
+    "scope": "vue,html",
+    "body": [
+      "<ResponsiveHeader",
+      "  :responsive-nav-links=\"$1responsiveNavLinks\"",
+      "  main-nav-aria-label=\"${2:Main navigation}\"",
+      "  secondary-nav-aria-label=\"${3:Secondary navigation}\"",
+      "  overflow-menu-aria-label=\"${4:Overflow navigation menu}\"",
+      "/>"
+    ]
+  },
   "SRCDEV ResponsiveHeader Nav Data (with dropdown)": {
     "description": "responsiveNavLinks data with a dropdown group",
     "scope": "typescript,vue",

package/.vscode/srcdev-component-site-header.code-snippets

@@ -30,6 +30,23 @@
       "</SiteHeader>"
     ]
   },
+  "SRCDEV SiteHeader Localised Nav Labels": {
+    "description": "SiteHeader with localised aria-labels on all its nav landmarks (home, main, secondary, overflow)",
+    "scope": "vue,html",
+    "body": [
+      "<SiteHeader",
+      "  :responsive-nav-links=\"$1responsiveNavLinks\"",
+      "  home-nav-aria-label=\"${2:Home Navigation}\"",
+      "  main-nav-aria-label=\"${3:Main navigation}\"",
+      "  secondary-nav-aria-label=\"${4:Secondary navigation}\"",
+      "  overflow-menu-aria-label=\"${5:Overflow navigation menu}\"",
+      ">",
+      "  <template #branding>",
+      "    <NuxtLink to=\"/\" class=\"home-link\">$6Brand</NuxtLink>",
+      "  </template>",
+      "</SiteHeader>"
+    ]
+  },
   "SRCDEV SiteHeader Nav Data (flat)": {
     "description": "Simple flat responsiveNavLinks data with no dropdowns, for a few-page site",
     "scope": "typescript,vue",

package/.vscode/srcdev-component-site-navigation.code-snippets

@@ -0,0 +1,30 @@
+{
+  "SRCDEV SiteNavigation Basic": {
+    "description": "SiteNavigation horizontal nav with sliding active/hover indicator",
+    "scope": "vue,html",
+    "body": [
+      "<SiteNavigation :nav-item-data=\"$1navData\" nav-align=\"${2:left}\" />"
+    ]
+  },
+  "SRCDEV SiteNavigation Localised": {
+    "description": "SiteNavigation with a localised aria-label",
+    "scope": "vue,html",
+    "body": [
+      "<SiteNavigation :nav-item-data=\"$1navData\" aria-label=\"${2:Site navigation}\" />"
+    ]
+  },
+  "SRCDEV SiteNavigation Nav Data Script": {
+    "description": "navItemData for SiteNavigation",
+    "scope": "typescript,vue",
+    "body": [
+      "import type { NavItemData } from \"srcdev-nuxt-components\";",
+      "",
+      "const $1navData: NavItemData = {",
+      "  main: [",
+      "    { text: \"$2Home\", href: \"$3/\" },",
+      "    { text: \"$4About\", href: \"$5/about\" },",
+      "  ],",
+      "};"
+    ]
+  }
+}

package/.vscode/srcdev-component-slider-gallery.code-snippets

@@ -0,0 +1,38 @@
+{
+  "SRCDEV SliderGallery Basic": {
+    "description": "SliderGallery full-screen image slider with thumbnails and prev/next arrows",
+    "scope": "vue,html",
+    "body": [
+      "<SliderGallery v-model:gallery-data=\"$1galleryData\" />"
+    ]
+  },
+  "SRCDEV SliderGallery Localised": {
+    "description": "SliderGallery with localised loading/CTA/arrow copy",
+    "scope": "vue,html",
+    "body": [
+      "<SliderGallery",
+      "  v-model:gallery-data=\"$1galleryData\"",
+      "  loading-text=\"${2:Loading gallery...}\"",
+      "  see-more-text=\"${3:SEE MORE}\"",
+      "  prev-aria-label=\"${4:Previous image}\"",
+      "  next-aria-label=\"${5:Next image}\"",
+      "/>"
+    ]
+  },
+  "SRCDEV SliderGallery Data Script": {
+    "description": "galleryData ref for SliderGallery",
+    "scope": "typescript,vue",
+    "body": [
+      "import type { IGalleryData } from \"srcdev-nuxt-components\";",
+      "",
+      "const $1galleryData = ref<IGalleryData[]>([",
+      "  {",
+      "    src: \"$2/images/slide-1.jpg\",",
+      "    alt: \"$3\",",
+      "    title: \"$4\",",
+      "    textBrightness: \"${5:light}\",",
+      "  },",
+      "]);"
+    ]
+  }
+}

package/.vscode/srcdev-component-tab-navigation.code-snippets

@@ -0,0 +1,30 @@
+{
+  "SRCDEV TabNavigation Basic": {
+    "description": "TabNavigation with route/hash links",
+    "scope": "vue,html",
+    "body": [
+      "<TabNavigation :nav-item-data=\"$1navData\" nav-align=\"${2:center}\" />"
+    ]
+  },
+  "SRCDEV TabNavigation Localised": {
+    "description": "TabNavigation with a localised aria-label",
+    "scope": "vue,html",
+    "body": [
+      "<TabNavigation :nav-item-data=\"$1navData\" aria-label=\"${2:Site navigation}\" />"
+    ]
+  },
+  "SRCDEV TabNavigation Nav Data Script": {
+    "description": "navItemData for TabNavigation",
+    "scope": "typescript,vue",
+    "body": [
+      "import type { NavItemData } from \"srcdev-nuxt-components\";",
+      "",
+      "const $1navData: NavItemData = {",
+      "  main: [",
+      "    { text: \"$2Home\", href: \"$3/\" },",
+      "    { text: \"$4Overview\", href: \"$5#overview\" },",
+      "  ],",
+      "};"
+    ]
+  }
+}

package/app/components/01.atoms/animations/animated-svg-text/AnimatedSvgText.vue

@@ -0,0 +1,58 @@
+<template>
+  <div class="animated-svg-text" :class="[elementClasses]">
+    <slot name="text"></slot>
+  </div>
+</template>
+
+<script setup lang="ts">
+interface Props {
+  styleClassPassthrough?: string | string[];
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  styleClassPassthrough: () => [],
+});
+
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+watch(
+  () => props.styleClassPassthrough,
+  () => {
+    resetElementClasses(props.styleClassPassthrough);
+  }
+);
+</script>
+
+<style lang="css">
+@layer components {
+
+@keyframes animatedSvgText {
+  0% {
+    fill: transparent;
+    stroke-dashoffset: var(--animated-svg-text-stroke-dasharray, 1000);
+    stroke-width: var(--animated-svg-text-stroke-width, 0.3);
+  }
+  70% {
+    fill: transparent;
+    stroke-width: var(--animated-svg-text-stroke-width, 0.3);
+  }
+  100% {
+    fill: var(--animated-svg-text-fill-colour, var(--theme-text));
+    stroke-dashoffset: 0;
+    stroke-width: 0;
+  }
+}
+
+.animated-svg-text {
+  svg path,
+  svg text {
+    stroke: var(--animated-svg-text-stroke-colour, var(--theme-text));
+    stroke-width: var(--animated-svg-text-stroke-width, 0.3);
+    stroke-dasharray: var(--animated-svg-text-stroke-dasharray, 1000);
+    stroke-dashoffset: var(--animated-svg-text-stroke-dasharray, 1000);
+    animation: animatedSvgText var(--animated-svg-text-animation-duration, 2s) linear 1 forwards;
+  }
+}
+
+}
+</style>

package/app/components/01.atoms/animations/animated-svg-text/CONSUMER-STYLING.md

@@ -0,0 +1,34 @@
+# AnimatedSvgText — Consumer Styling
+
+`AnimatedSvgText` has no props of its own beyond `styleClassPassthrough` — the SVG markup is
+provided via the `text` slot, either as `<path>` outlines of the text or a plain SVG `<text>`
+element (both support `stroke`/`fill`/`stroke-dasharray` per the SVG spec). All visual control is
+through public CSS custom properties, consumed directly on `.animated-svg-text svg path, .animated-svg-text svg text`.
+
+## Public tokens
+
+| Property | Default | Description |
+| -------- | ------- | ------------ |
+| `--animated-svg-text-stroke-colour` | `var(--theme-text)` | Stroke colour during the draw-on phase. |
+| `--animated-svg-text-fill-colour` | `var(--theme-text)` | Fill colour once the draw-on animation completes. |
+| `--animated-svg-text-stroke-width` | `0.3` | Stroke width (in the SVG's own coordinate units) during the draw-on phase. |
+| `--animated-svg-text-stroke-dasharray` | `1000` | Dash length used to drive the "draw" effect. Set this to roughly the total path length of your SVG — too small and the stroke completes before covering the full outline; too large and the animation appears to pause at the start. |
+| `--animated-svg-text-animation-duration` | `2s` | Duration of the full draw-fill animation. |
+
+```vue
+<AnimatedSvgText style="--animated-svg-text-stroke-colour: #e63946; --animated-svg-text-animation-duration: 3.5s;">
+  <template #text>
+    <svg viewBox="0 0 400 100"><path d="..." /></svg>
+  </template>
+</AnimatedSvgText>
+```
+
+## Notes
+
+- The animation runs once on mount (`forwards`, `1` iteration) — it does not loop or replay on re-entry.
+- `--animated-svg-text-stroke-dasharray` is the one token worth tuning per SVG: it depends on the
+  total length of the animated content, which varies with font, text length, and the SVG's
+  coordinate scale (`viewBox`). The defaults (`0.3` stroke-width, `1000` dasharray) suit path data
+  traced at a small/normalised coordinate scale — a larger `viewBox` (e.g. plain SVG `<text>` at a
+  large `font-size`) needs a proportionally larger `--animated-svg-text-stroke-width` and
+  `--animated-svg-text-stroke-dasharray`, or the stroke renders too thin/short to see.

package/app/components/01.atoms/animations/animated-svg-text/stories/AnimatedSvgText.stories.ts

@@ -0,0 +1,69 @@
+import AnimatedSvgText from "../AnimatedSvgText.vue";
+import type { Meta, StoryObj } from "@nuxtjs/storybook";
+
+const meta: Meta<typeof AnimatedSvgText> = {
+  title: "Atoms/Animations/AnimatedSvgText",
+  component: AnimatedSvgText,
+  argTypes: {
+    styleClassPassthrough: {
+      table: { disable: true },
+    },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Animates inline SVG text outlines with a stroke-draw-then-fill effect on mount. Provide the SVG markup via the `text` slot. Styling is entirely via CSS custom properties — see CONSUMER-STYLING.md.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof AnimatedSvgText>;
+
+const svgSlot = `
+  <svg viewBox="0 0 600 150" xmlns="http://www.w3.org/2000/svg" style="width: 100%; height: auto;">
+    <text x="0" y="110" font-size="120" font-family="sans-serif" font-weight="700" fill="none">Hello</text>
+  </svg>
+`;
+
+// The default tokens (stroke-width 0.3, dasharray 1000) are tuned for path data traced at a
+// small/normalised coordinate scale. This demo's viewBox is much larger, so both stories override
+// stroke-width/dasharray to suit — see CONSUMER-STYLING.md: dasharray should roughly match the
+// total path length of the SVG being animated.
+const demoScaleTokens = "--animated-svg-text-stroke-width: 2; --animated-svg-text-stroke-dasharray: 2200;";
+
+export const Default: Story = {
+  render: () => ({
+    components: { AnimatedSvgText },
+    template: `<AnimatedSvgText style="${demoScaleTokens}"><template #text>${svgSlot}</template></AnimatedSvgText>`,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story: "Default draw-on animation using the theme's text colour for both stroke and fill.",
+      },
+    },
+  },
+};
+
+export const CustomColourAndSpeed: Story = {
+  render: () => ({
+    components: { AnimatedSvgText },
+    template: `
+      <AnimatedSvgText
+        style="${demoScaleTokens} --animated-svg-text-stroke-colour: #e63946; --animated-svg-text-fill-colour: #e63946; --animated-svg-text-animation-duration: 3.5s;"
+      >
+        <template #text>${svgSlot}</template>
+      </AnimatedSvgText>
+    `,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story: "Overriding `--animated-svg-text-stroke-colour`, `--animated-svg-text-fill-colour`, and slowing the animation via `--animated-svg-text-animation-duration`.",
+      },
+    },
+  },
+};

package/app/components/01.atoms/animations/animated-svg-text/tests/AnimatedSvgText.spec.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect } from "vitest";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import AnimatedSvgText from "../AnimatedSvgText.vue";
+
+describe("AnimatedSvgText", () => {
+  // ─── Mount ───────────────────────────────────────────────────────────────
+
+  it("mounts without error", async () => {
+    const wrapper = await mountSuspended(AnimatedSvgText);
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  it("renders correct HTML structure", async () => {
+    const wrapper = await mountSuspended(AnimatedSvgText, {
+      slots: { text: '<svg viewBox="0 0 100 100"><path d="M0 0 L100 100" /></svg>' },
+    });
+    expect(wrapper.html()).toMatchSnapshot();
+  });
+
+  // ─── Root element ────────────────────────────────────────────────────────
+
+  it("renders a div with the animated-svg-text class", async () => {
+    const wrapper = await mountSuspended(AnimatedSvgText);
+    expect(wrapper.element.tagName).toBe("DIV");
+    expect(wrapper.classes()).toContain("animated-svg-text");
+  });
+
+  // ─── Slot ────────────────────────────────────────────────────────────────
+
+  it("renders the text slot content", async () => {
+    const wrapper = await mountSuspended(AnimatedSvgText, {
+      slots: { text: '<svg data-testid="my-svg"><path d="M0 0" /></svg>' },
+    });
+    expect(wrapper.find('[data-testid="my-svg"]').exists()).toBe(true);
+  });
+
+  // ─── styleClassPassthrough ───────────────────────────────────────────────
+
+  it("applies a single styleClassPassthrough string to the root", async () => {
+    const wrapper = await mountSuspended(AnimatedSvgText, {
+      props: { styleClassPassthrough: "hero-svg-text" },
+    });
+    expect(wrapper.classes()).toContain("hero-svg-text");
+  });
+
+  it("applies multiple styleClassPassthrough classes from an array", async () => {
+    const wrapper = await mountSuspended(AnimatedSvgText, {
+      props: { styleClassPassthrough: ["hero-svg-text", "mbe-32"] },
+    });
+    expect(wrapper.classes()).toContain("hero-svg-text");
+    expect(wrapper.classes()).toContain("mbe-32");
+  });
+
+  it("updates classes when styleClassPassthrough prop changes", async () => {
+    const wrapper = await mountSuspended(AnimatedSvgText, {
+      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/animations/animated-svg-text/tests/__snapshots__/AnimatedSvgText.spec.ts.snap

@@ -0,0 +1,7 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`AnimatedSvgText > renders correct HTML structure 1`] = `
+"<div class="animated-svg-text"><svg viewBox="0 0 100 100">
+    <path d="M0 0 L100 100"></path>
+  </svg></div>"
+`;

package/app/components/01.atoms/animations/clip-element/CONSUMER-STYLING.md

@@ -0,0 +1,27 @@
+# ClipElement — Consumer Styling Guide
+
+## No public CSS token API
+
+`ClipElement` has no `--clip-element-*` custom properties. Its only visual output is the
+`clip-path` inset applied to `.clipped-element`, and that value is entirely computed at runtime
+from the `maxClip` prop and the element's scroll position — there is no fixed appearance value a
+consumer would plausibly want to override via CSS.
+
+## Override surface
+
+Use `styleClassPassthrough` to apply your own classes to the root `.clip-element-wrapper`:
+
+```vue
+<ClipElement :max-clip="150" style-class-passthrough="my-clip-wrapper">
+  <img src="/images/hero.jpg" alt="Hero" />
+</ClipElement>
+```
+
+```css
+.my-clip-wrapper {
+  border-radius: 1.6rem;
+}
+```
+
+Style the slotted content directly for anything beyond the clip effect itself (sizing, object-fit,
+borders, etc.) — `ClipElement` does not constrain it.

package/app/components/{clip-element → 01.atoms/animations/clip-element}/ClipElement.vue

@@ -7,18 +7,23 @@
 </template>
 
 <script lang="ts" setup>
-const props = defineProps({
-  maxClip: {
-    type: Number,
-    default: 100,
-  },
-  styleClassPassthrough: {
-    type: [String, Array] as PropType<string | string[]>,
-    default: () => [],
-  },
-})
+interface Props {
+  /** Scroll distance (px) over which the element clips in/out. */
+  maxClip?: number;
+  styleClassPassthrough?: string | string[];
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  maxClip: 100,
+  styleClassPassthrough: () => [],
+});
+
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
 
-const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough)
+watch(
+  () => props.styleClassPassthrough,
+  () => resetElementClasses(props.styleClassPassthrough)
+);
 
 const container = ref(null)
 const clipElement = ref<HTMLDivElement | null>(null)

package/app/components/01.atoms/animations/clip-element/stories/ClipElement.stories.ts

@@ -0,0 +1,133 @@
+import ClipElement from "../ClipElement.vue";
+import type { Meta, StoryObj } from "@nuxtjs/storybook";
+
+const meta: Meta<typeof ClipElement> = {
+  title: "Atoms/Effects/ClipElement",
+  component: ClipElement,
+  argTypes: {
+    maxClip: {
+      control: { type: "number", min: 0, step: 10 },
+      description: "Scroll distance (px) over which the element clips in as it enters the viewport, and clips further out as it scrolls above it.",
+      table: { category: "Behaviour" },
+    },
+    styleClassPassthrough: {
+      table: { disable: true },
+    },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Clips its slot content in from the top edge as it scrolls into the viewport, using a scroll listener to drive a `clip-path: inset(...)` value. For a CSS-only, listener-free parallax reveal, prefer ScrollRevealFrame/ScrollRevealImage instead — reach for ClipElement only when you specifically need this scroll-position-driven clip behaviour.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ClipElement>;
+
+// A fixed marker at the top of the viewport, since that's exactly where the
+// clip finishes resolving (top === 0) — makes the effect's endpoint visible
+// instead of something you have to guess at while scrolling.
+const topMarker = `
+  <div style="position: fixed; top: 0; left: 0; right: 0; height: 2px; background: #ff5c5c; z-index: 10;"></div>
+  <div style="position: fixed; top: 6px; left: 12px; font-size: 1.2rem; color: #ff5c5c; z-index: 10;">clip fully resolves at this line ↑</div>
+`;
+
+// Horizontal rules baked into the image itself so the wipe boundary is
+// visible against the photo, not just a subtle crop of pixels.
+const rulerOverlayStyle = `
+  background-image: repeating-linear-gradient(
+    to bottom,
+    transparent,
+    transparent 49px,
+    rgba(255, 92, 92, 0.6) 49px,
+    rgba(255, 92, 92, 0.6) 50px
+  );
+`;
+
+const scrollWrapper = (maxClip: number, inner: string) => `
+  ${topMarker}
+  <div style="padding-block: 30vh 6px; max-width: 860px; margin-inline: auto;">
+    <p style="text-align: center; font-size: 1.4rem; opacity: 0.6; margin-block-end: 1rem;">
+      Scroll slowly — the image clips in over the ${maxClip}px just before it reaches the red line.
+    </p>
+  </div>
+  ${inner}
+  <div style="height: 100vh;"></div>
+`;
+
+export const Default: Story = {
+  args: {
+    maxClip: 100,
+  },
+  render: (args) => ({
+    components: { ClipElement },
+    setup() {
+      return { args };
+    },
+    template: scrollWrapper(
+      args.maxClip ?? 100,
+      `
+      <div style="max-width: 860px; margin-inline: auto; position: relative;">
+        <ClipElement v-bind="args">
+          <div style="position: relative;">
+            <img
+              src="/images/page/hero/hero-blonde.jpg"
+              alt="Blonde hair portrait"
+              style="display: block; width: 100%;"
+            />
+            <div style="position: absolute; inset: 0; ${rulerOverlayStyle}"></div>
+          </div>
+        </ClipElement>
+      </div>
+    `
+    ),
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Default props — the ruled overlay makes the clip boundary visible as it wipes in over the last 100px before the image reaches the top of the viewport (marked by the red line).",
+      },
+    },
+  },
+};
+
+export const LargeClipDistance: Story = {
+  args: {
+    maxClip: 500,
+  },
+  render: (args) => ({
+    components: { ClipElement },
+    setup() {
+      return { args };
+    },
+    template: scrollWrapper(
+      args.maxClip ?? 500,
+      `
+      <div style="max-width: 860px; margin-inline: auto; position: relative;">
+        <ClipElement v-bind="args">
+          <div style="position: relative;">
+            <img
+              src="/images/page/hero/hero-blonde.jpg"
+              alt="Blonde hair portrait"
+              style="display: block; width: 100%;"
+            />
+            <div style="position: absolute; inset: 0; ${rulerOverlayStyle}"></div>
+          </div>
+        </ClipElement>
+      </div>
+    `
+    ),
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "A much larger maxClip (500px) stretches the wipe over a longer, easier-to-watch scroll distance — useful for previewing the effect without scrolling pixel-by-pixel.",
+      },
+    },
+  },
+};