srcdev-nuxt-components 9.4.8 → 9.4.10

package/app/components/01.atoms/animations/section-parallax/tests/SectionParallax.spec.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect } from "vitest";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import SectionParallax from "../SectionParallax.vue";
+
+const backgroundImage = "/images/eucalyptus-lavender-and-oil.jpg";
+
+describe("SectionParallax", () => {
+  // ─── Mount ───────────────────────────────────────────────────────────────
+
+  it("mounts without error", async () => {
+    const wrapper = await mountSuspended(SectionParallax, {
+      props: { backgroundImage },
+    });
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  // ─── Snapshots ───────────────────────────────────────────────────────────
+
+  it("renders correct HTML structure (default)", async () => {
+    const wrapper = await mountSuspended(SectionParallax, {
+      props: { backgroundImage },
+    });
+    expect(wrapper.html()).toMatchSnapshot();
+  });
+
+  it("renders correct HTML structure (with slot content)", async () => {
+    const wrapper = await mountSuspended(SectionParallax, {
+      props: { backgroundImage },
+      slots: { default: "<p class='overlay-text'>A quiet moment.</p>" },
+    });
+    expect(wrapper.html()).toMatchSnapshot();
+  });
+
+  // ─── Root element ─────────────────────────────────────────────────────────
+
+  it("renders as <div> by default", async () => {
+    const wrapper = await mountSuspended(SectionParallax, {
+      props: { backgroundImage },
+    });
+    expect(wrapper.element.tagName).toBe("DIV");
+  });
+
+  it.each(["div", "section", "article", "aside"] as const)("renders as <%s> when tag='%s'", async (tag) => {
+    const wrapper = await mountSuspended(SectionParallax, {
+      props: { backgroundImage, tag },
+    });
+    expect(wrapper.element.tagName).toBe(tag.toUpperCase());
+  });
+
+  // ─── Base class ───────────────────────────────────────────────────────────
+
+  it("always has the section-parallax class", async () => {
+    const wrapper = await mountSuspended(SectionParallax, {
+      props: { backgroundImage },
+    });
+    expect(wrapper.classes()).toContain("section-parallax");
+  });
+
+  // ─── Slot ─────────────────────────────────────────────────────────────────
+
+  it("renders default slot content when provided", async () => {
+    const wrapper = await mountSuspended(SectionParallax, {
+      props: { backgroundImage },
+      slots: { default: "<p class='overlay-text'>A quiet moment.</p>" },
+    });
+    expect(wrapper.find(".overlay-text").exists()).toBe(true);
+  });
+
+  it("renders no visible inner content when no slot is provided", async () => {
+    const wrapper = await mountSuspended(SectionParallax, {
+      props: { backgroundImage },
+    });
+    expect(wrapper.element.children.length).toBe(0);
+  });
+
+  // ─── styleClassPassthrough ────────────────────────────────────────────────
+
+  it("applies a single styleClassPassthrough string", async () => {
+    const wrapper = await mountSuspended(SectionParallax, {
+      props: { backgroundImage, styleClassPassthrough: "featured" },
+    });
+    expect(wrapper.classes()).toContain("featured");
+  });
+
+  it("applies multiple styleClassPassthrough classes from an array", async () => {
+    const wrapper = await mountSuspended(SectionParallax, {
+      props: { backgroundImage, styleClassPassthrough: ["featured", "highlighted"] },
+    });
+    expect(wrapper.classes()).toContain("featured");
+    expect(wrapper.classes()).toContain("highlighted");
+  });
+
+  it("updates classes when styleClassPassthrough prop changes", async () => {
+    const wrapper = await mountSuspended(SectionParallax, {
+      props: { backgroundImage, styleClassPassthrough: ["featured"] },
+    });
+    expect(wrapper.classes()).toContain("featured");
+    await wrapper.setProps({ styleClassPassthrough: ["highlighted"] });
+    expect(wrapper.classes()).not.toContain("featured");
+    expect(wrapper.classes()).toContain("highlighted");
+  });
+});

package/app/components/01.atoms/animations/section-parallax/tests/__snapshots__/SectionParallax.spec.ts.snap

@@ -0,0 +1,9 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`SectionParallax > renders correct HTML structure (default) 1`] = `"<div class="section-parallax"></div>"`;
+
+exports[`SectionParallax > renders correct HTML structure (with slot content) 1`] = `
+"<div class="section-parallax">
+  <p class="overlay-text">A quiet moment.</p>
+</div>"
+`;

package/app/components/01.atoms/animations/view-timeline/CONSUMER-STYLING.md

@@ -0,0 +1,70 @@
+# WipeAwayVertical — Consumer Styling
+
+## Public tokens
+
+| Token                                     | Default  | Applies to                                                                           |
+| ----------------------------------------- | -------- | ------------------------------------------------------------------------------------ |
+| `--wipe-away-vertical-height`             | `100vh`  | `.sticky-items-container` height — the visible height of the sticky panel stack      |
+| `--wipe-away-vertical-border-radius`      | `0.5rem` | `.sticky-item` corner radius                                                         |
+| `--wipe-away-vertical-animation-duration` | `1s`     | `wipe-out` scroll-linked animation, browsers supporting `animation-timeline: view()` |
+| `--wipe-away-vertical-trailing-buffer`    | `20vh`   | `.trailing-buffer` height — release room after the last panel                        |
+
+## Only itemCount - 1 scrollingItem slots
+
+The last panel has nothing left to reveal, so it has no wipe animation and no `.scrolling-section`
+of its own — only `scrollingItem-0` through `scrollingItem-{itemCount - 2}` are rendered.
+Providing a `scrollingItem-{itemCount - 1}` slot is harmless (it's simply never rendered) but
+unnecessary. Earlier versions of this component rendered a full extra `100vh` section for the
+last item purely to hold it in view before release — that made the last panel appear roughly 2x
+as deep on screen as the others, since it got the same reveal lead-in as every other panel _plus_
+a whole dedicated section with no wipe to cut it short. `.trailing-buffer` (see token above)
+replaces that with a much smaller, purpose-built release cushion instead.
+
+## Pure CSS, no JS measurement
+
+The whole pin/reveal effect is CSS-only (grid overlay + `animation-timeline: view()`); there's
+no scroll listener or `getBoundingClientRect()` measurement involved. The root is a single-column
+CSS grid: each `.scrolling-section` takes an explicit `grid-row` (after a `.leading-buffer` row—
+see below), and `.sticky-items-container` spans `grid-row: 1 / -1` to overlay all of them without
+adding its own row — so the root's height is simply the sum of the scrolling sections' own content
+height plus the leading buffer, nothing extra to size manually.
+
+## Leading buffer
+
+`.leading-buffer` is a fixed `100vh` spacer rendered before the first scrolling section. Without
+it, a section 0 positioned near the top of the page would already be partway through its `entry`
+timeline range at initial page load (before any scrolling happens), so the first panel would
+appear partially wiped on load. The buffer guarantees a full viewport of scroll run-up regardless
+of how much real content precedes the component.
+
+## No `animation-timeline: view()` support
+
+Browsers without support (checked via `@supports not (animation-timeline: view())`) get the
+sticky/grid-overlay/animation rules dropped entirely — `.sticky-item`s just render as normal
+stacked panels in document flow, and `.scrolling-section`s are hidden. No JS fallback, no
+opacity crossfade.
+
+## Sticky vertical centering — no transform
+
+`.sticky-items-container` centers itself with `top: calc((100vh - var(--wipe-away-vertical-height, 100vh)) / 2)` — a plain calc(), not a `transform: translateY()`. Do not
+reintroduce a transform for this: `position: sticky`'s stick/release threshold is computed from
+the element's untransformed layout position, so a transform-based visual shift makes the browser
+release the sticky panel early (by the transformed amount), leaving a gap of empty space between
+the last panel and whatever content follows the component.
+
+```css
+.wipe-away-vertical {
+  --wipe-away-vertical-border-radius: 1rem;
+  --wipe-away-vertical-animation-duration: 1.5s;
+}
+```
+
+## Reduced motion
+
+The wipe animation is disabled under `prefers-reduced-motion: reduce` (`animation: none;
+clip-path: none;`) — panels render fully visible with no clip.
+
+## Class passthrough
+
+`styleClassPassthrough` (string or string array) is applied to the root element via
+`useStyleClassPassthrough`.

package/app/components/01.atoms/animations/view-timeline/WipeAwayVertical.vue

@@ -0,0 +1,181 @@
+<template>
+  <component
+    :is="tag"
+    class="wipe-away-vertical"
+    :class="[elementClasses]"
+    :style="{ 'timeline-scope': timelineScope }"
+  >
+    <div class="leading-buffer" aria-hidden="true"></div>
+
+    <section
+      v-for="(item, key) in itemCount - 1"
+      :key="key"
+      class="scrolling-section"
+      :style="{
+        'grid-row': key + 2,
+        'view-timeline-name': `--section-${timelineId}-${key}`,
+      }"
+    >
+      <slot :name="`scrollingItem-${key}`"></slot>
+    </section>
+
+    <div class="trailing-buffer" aria-hidden="true" :style="{ 'grid-row': itemCount + 1 }"></div>
+
+    <div class="sticky-items-container">
+      <div
+        v-for="(item, key) in itemCount"
+        :key="key"
+        class="sticky-item"
+        :style="{
+          'animation-timeline': key === itemCount - 1 ? 'none' : `--section-${timelineId}-${key}`,
+          'z-index': itemCount - key,
+        }"
+      >
+        <slot :name="`stickyItem-${key}`"></slot>
+      </div>
+    </div>
+  </component>
+</template>
+
+<script setup lang="ts">
+interface Props {
+  tag?: "div" | "section" | "main" | "article" | "aside";
+  itemCount: number;
+  styleClassPassthrough?: string | string[];
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  tag: "div",
+  styleClassPassthrough: () => [],
+});
+
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+const timelineId = useId();
+
+const timelineScope = computed(() =>
+  Array.from({ length: props.itemCount }, (_, i) => `--section-${timelineId}-${i}`).join(", ")
+);
+
+watch(
+  () => props.styleClassPassthrough,
+  () => {
+    resetElementClasses(props.styleClassPassthrough);
+  }
+);
+</script>
+
+<style lang="css">
+@layer components {
+  .wipe-away-vertical {
+    display: grid;
+    grid-template-columns: 1fr;
+
+    .scrolling-section {
+      grid-column: 1;
+    }
+
+    .leading-buffer {
+      grid-column: 1;
+      grid-row: 1;
+    }
+
+    .trailing-buffer {
+      grid-column: 1;
+    }
+
+    .sticky-items-container {
+      grid-column: 1;
+      grid-row: 1 / -1;
+    }
+  }
+
+  @supports (animation-timeline: view()) {
+    .wipe-away-vertical {
+      /* gives entry timelines a full viewport of run-up so section 0 isn't already
+         mid-"entry" the moment the page loads, whatever content precedes this component */
+      .leading-buffer {
+        height: 100vh;
+      }
+
+      /* the last item has no wipe animation of its own (nothing left to reveal), so it
+         only needs a little room to release cleanly rather than a whole extra section */
+      .trailing-buffer {
+        height: var(--wipe-away-vertical-trailing-buffer, 20vh);
+      }
+
+      .scrolling-section {
+        view-timeline-axis: block;
+        /* sticky panel is vertically centred via the same calc() as its own top offset below,
+           so the entry/exit range needs to be inset by the same fixed amount above and below */
+        view-timeline-inset: calc((100vh - var(--wipe-away-vertical-height, 100vh)) / 2);
+      }
+
+      .sticky-items-container {
+        position: sticky;
+        /* a transform here (e.g. translateY(-50%)) would visually centre the panel, but
+           position: sticky's stick/release threshold is computed from the untransformed
+           layout position, so it would release the panel early by the transformed amount —
+           compute the centring offset directly instead so nothing needs transforming */
+        top: calc((100vh - var(--wipe-away-vertical-height, 100vh)) / 2);
+        height: var(--wipe-away-vertical-height, 100vh);
+      }
+
+      .sticky-item {
+        position: absolute;
+        inset: 0;
+        border-radius: var(--wipe-away-vertical-border-radius, 0.5rem);
+        width: 100%;
+      }
+    }
+
+    @keyframes wipe-out {
+      0% {
+        clip-path: inset(0 0 0% 0);
+      }
+      100% {
+        clip-path: inset(0 0 100% 0);
+      }
+    }
+
+    .sticky-item {
+      animation: wipe-out var(--wipe-away-vertical-animation-duration, 1s) linear both;
+      animation-range: entry 0% entry 100%;
+    }
+  }
+
+  @supports not (animation-timeline: view()) {
+    .wipe-away-vertical {
+      display: block;
+
+      .leading-buffer {
+        display: none;
+      }
+
+      .trailing-buffer {
+        display: none;
+      }
+
+      .scrolling-section {
+        display: none;
+      }
+
+      .sticky-items-container {
+        display: contents;
+      }
+
+      .sticky-item {
+        width: 100%;
+        border-radius: var(--wipe-away-vertical-border-radius, 0.5rem);
+      }
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .sticky-item {
+      animation: none !important;
+      clip-path: none !important;
+    }
+  }
+}
+</style>

package/app/components/01.atoms/animations/view-timeline/stories/WipeAwayVertical.stories.ts

@@ -0,0 +1,269 @@
+import WipeAwayVertical from "../WipeAwayVertical.vue";
+import type { Meta, StoryObj } from "@nuxtjs/storybook";
+
+const meta: Meta<typeof WipeAwayVertical> = {
+  title: "Atoms/Effects/WipeAwayVertical",
+  component: WipeAwayVertical,
+  argTypes: {
+    tag: {
+      control: "select",
+      options: ["div", "section", "main", "article", "aside"],
+      description: "Root element tag",
+      table: { category: "Structure" },
+    },
+    itemCount: {
+      control: { type: "number", min: 1, max: 5, step: 1 },
+      description:
+        "Number of sticky/scrolling section pairs. The demo below has a fixed set of 3 slotted panels, so changing this control past what's slotted will leave extra panels empty — see the FivePanels story for a differently-sized example.",
+      table: { category: "Structure" },
+    },
+    styleClassPassthrough: { table: { disable: true } },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Scroll-driven vertical wipe effect: each sticky panel wipes away to reveal the next as its paired scrolling section crosses the viewport. Pure CSS — a single-column grid overlays `.sticky-items-container` across all `.scrolling-section` rows via `animation-timeline: view()`, so there's no scroll listener or JS measurement involved. Consumers supply `stickyItem-{n}` slots for each of `itemCount` panels, and `scrollingItem-{n}` slots for only the first `itemCount - 1` — the last panel has nothing left to reveal, so it has no wipe animation or scrolling section of its own, just a small built-in trailing buffer to release cleanly. The sticky panel's own visible height is `--wipe-away-vertical-height` (default `100vh`) — leave the root's own `height` unset (`auto`) so it sizes itself from its children. Browsers without `animation-timeline: view()` support (via `@supports not (...)`) just get the sticky items stacked in normal document flow instead.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof WipeAwayVertical>;
+
+const scrollNote = `
+  <p style="text-align: center; font-size: 1.4rem; opacity: 0.5; padding-block: 2rem;">
+    Scroll down to see each panel wipe away
+  </p>
+`;
+
+const panel = (label: string, colour: string) => `
+  <div style="width: 100%; height: 100%; display: flex; align-items: center; justify-content: center; background: ${colour}; color: white; font-size: 2.4rem; font-weight: 600; border-radius: inherit;">
+    ${label}
+  </div>
+`;
+
+export const Default: Story = {
+  args: {
+    tag: "div",
+    itemCount: 3,
+  },
+  render: (args) => ({
+    components: { WipeAwayVertical },
+    setup() {
+      return { args };
+    },
+    template: `
+      <div>
+        ${scrollNote}
+        <WipeAwayVertical v-bind="args">
+          <template #stickyItem-0>${panel("Panel One", "#5b8def")}</template>
+          <template #stickyItem-1>${panel("Panel Two", "#e0576b")}</template>
+          <template #stickyItem-2>${panel("Panel Three", "#2fb380")}</template>
+          <template #scrollingItem-0><div style="height: 100vh;"></div></template>
+          <template #scrollingItem-1><div style="height: 100vh;"></div></template>
+        </WipeAwayVertical>
+        <p style="text-align: center; font-size: 1.4rem; opacity: 0.5; padding-block: 2rem;">End of timeline</p>
+      </div>
+    `,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Three panels wiping in sequence as the page scrolls. The root's height is left as `auto` so it sizes itself from its scrolling sections — no manual height calculation needed.",
+      },
+    },
+  },
+};
+
+export const RoundedPanels: Story = {
+  args: {
+    tag: "div",
+    itemCount: 3,
+  },
+  render: (args) => ({
+    components: { WipeAwayVertical },
+    setup() {
+      return { args };
+    },
+    template: `
+      <div>
+        ${scrollNote}
+        <WipeAwayVertical v-bind="args" style="--wipe-away-vertical-border-radius: 2.4rem;">
+          <template #stickyItem-0>${panel("Rounded One", "#5b8def")}</template>
+          <template #stickyItem-1>${panel("Rounded Two", "#e0576b")}</template>
+          <template #stickyItem-2>${panel("Rounded Three", "#2fb380")}</template>
+          <template #scrollingItem-0><div style="height: 100vh;"></div></template>
+          <template #scrollingItem-1><div style="height: 100vh;"></div></template>
+        </WipeAwayVertical>
+        <p style="text-align: center; font-size: 1.4rem; opacity: 0.5; padding-block: 2rem;">End of timeline</p>
+      </div>
+    `,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story: "`--wipe-away-vertical-border-radius` rounds the sticky panels' corners.",
+      },
+    },
+  },
+};
+
+export const SlowWipe: Story = {
+  args: {
+    tag: "div",
+    itemCount: 2,
+  },
+  render: (args) => ({
+    components: { WipeAwayVertical },
+    setup() {
+      return { args };
+    },
+    template: `
+      <div>
+        ${scrollNote}
+        <WipeAwayVertical v-bind="args" style="--wipe-away-vertical-animation-duration: 3s;">
+          <template #stickyItem-0>${panel("Slow One", "#5b8def")}</template>
+          <template #stickyItem-1>${panel("Slow Two", "#e0576b")}</template>
+          <template #scrollingItem-0><div style="height: 100vh;"></div></template>
+        </WipeAwayVertical>
+        <p style="text-align: center; font-size: 1.4rem; opacity: 0.5; padding-block: 2rem;">End of timeline</p>
+      </div>
+    `,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "`--wipe-away-vertical-animation-duration` stretches the wipe animation across a larger portion of the scroll-linked entry range, in browsers that support `animation-timeline: view()`.",
+      },
+    },
+  },
+};
+
+export const CompactHeight: Story = {
+  args: {
+    tag: "div",
+    itemCount: 2,
+  },
+  render: (args) => ({
+    components: { WipeAwayVertical },
+    setup() {
+      return { args };
+    },
+    template: `
+      <div>
+        ${scrollNote}
+        <WipeAwayVertical v-bind="args" style="--wipe-away-vertical-height: 50vh;">
+          <template #stickyItem-0>${panel("Compact One", "#5b8def")}</template>
+          <template #stickyItem-1>${panel("Compact Two", "#e0576b")}</template>
+          <template #scrollingItem-0><div style="height: 100vh;"></div></template>
+        </WipeAwayVertical>
+        <p style="text-align: center; font-size: 1.4rem; opacity: 0.5; padding-block: 2rem;">End of timeline</p>
+      </div>
+    `,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "`--wipe-away-vertical-height` sizes the visible sticky panel independently of the root's total scroll height — here it's shrunk to 50vh instead of the 100vh default. The root's height is still left as `auto`.",
+      },
+    },
+  },
+};
+
+export const FivePanels: Story = {
+  args: {
+    tag: "div",
+    itemCount: 5,
+  },
+  render: (args) => ({
+    components: { WipeAwayVertical },
+    setup() {
+      return { args };
+    },
+    template: `
+      <div>
+        ${scrollNote}
+        <WipeAwayVertical v-bind="args">
+          <template #stickyItem-0>${panel("Panel One", "#5b8def")}</template>
+          <template #stickyItem-1>${panel("Panel Two", "#e0576b")}</template>
+          <template #stickyItem-2>${panel("Panel Three", "#2fb380")}</template>
+          <template #stickyItem-3>${panel("Panel Four", "#e0a83a")}</template>
+          <template #stickyItem-4>${panel("Panel Five", "#8a5be0")}</template>
+          <template #scrollingItem-0><div style="height: 100vh;"></div></template>
+          <template #scrollingItem-1><div style="height: 100vh;"></div></template>
+          <template #scrollingItem-2><div style="height: 100vh;"></div></template>
+          <template #scrollingItem-3><div style="height: 100vh;"></div></template>
+        </WipeAwayVertical>
+        <p style="text-align: center; font-size: 1.4rem; opacity: 0.5; padding-block: 2rem;">End of timeline</p>
+      </div>
+    `,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Five panels wiping in sequence — itemCount scales cleanly: the root's height stays auto regardless of itemCount, and z-index/view-timeline naming are generated per item automatically.",
+      },
+    },
+  },
+};
+
+const loremParagraph = `
+  <p style="max-width: 60ch; margin-inline: auto; font-size: 1.6rem; line-height: 1.6; padding-block: 2rem;">
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut
+    labore et dolore magna aliqua. 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.
+  </p>
+`;
+
+const loremHeading = (text: string) => `
+  <h2 style="max-width: 60ch; margin-inline: auto; font-size: 2.4rem; padding-top: 3rem;">${text}</h2>
+`;
+
+export const InRealisticPage: Story = {
+  args: {
+    tag: "div",
+    itemCount: 3,
+  },
+  render: (args) => ({
+    components: { WipeAwayVertical },
+    setup() {
+      return { args };
+    },
+    template: `
+      <div>
+        ${loremHeading("Before the effect")}
+        ${loremParagraph}
+        ${loremParagraph}
+        ${loremHeading("Another section")}
+        ${loremParagraph}
+        <WipeAwayVertical v-bind="args">
+          <template #stickyItem-0>${panel("Panel One", "#5b8def")}</template>
+          <template #stickyItem-1>${panel("Panel Two", "#e0576b")}</template>
+          <template #stickyItem-2>${panel("Panel Three", "#2fb380")}</template>
+          <template #scrollingItem-0><div style="height: 100vh;"></div></template>
+          <template #scrollingItem-1><div style="height: 100vh;"></div></template>
+        </WipeAwayVertical>
+        ${loremHeading("After the effect")}
+        ${loremParagraph}
+        ${loremParagraph}
+        ${loremHeading("More reading")}
+        ${loremParagraph}
+      </div>
+    `,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "The component dropped into a realistic page: several rows of unrelated heading/paragraph content both before and after it, rather than the minimal scroll-note used by the other stories. Demonstrates that the wipe still starts fully un-wiped at initial page load and the sticky panel releases cleanly afterwards, regardless of how much content precedes or follows it.",
+      },
+    },
+  },
+};