srcdev-nuxt-components 9.4.4 → 9.4.6

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

@@ -0,0 +1,70 @@
+import { describe, it, expect } from "vitest";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import ClipElement from "../ClipElement.vue";
+
+function setTopAndScroll(wrapper: Awaited<ReturnType<typeof mountSuspended>>, top: number) {
+  const clipElement = wrapper.find(".clipped-element").element as HTMLElement;
+  clipElement.getBoundingClientRect = () => ({ top } as DOMRect);
+  window.dispatchEvent(new Event("scroll"));
+}
+
+describe("ClipElement", () => {
+  it("mounts without error", async () => {
+    const wrapper = await mountSuspended(ClipElement);
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  it("renders correct HTML structure (default props)", async () => {
+    const wrapper = await mountSuspended(ClipElement);
+    expect(wrapper.html()).toMatchSnapshot();
+  });
+
+  it("renders the wrapper and clipped-element structure", async () => {
+    const wrapper = await mountSuspended(ClipElement);
+    expect(wrapper.find(".clip-element-wrapper").exists()).toBe(true);
+    expect(wrapper.find(".clipped-element").exists()).toBe(true);
+  });
+
+  it("renders slot content inside .clipped-element", async () => {
+    const wrapper = await mountSuspended(ClipElement, {
+      slots: { default: "<p class='slot-child'>Hello</p>" },
+    });
+    const content = wrapper.find(".clipped-element");
+    expect(content.find(".slot-child").exists()).toBe(true);
+    expect(content.find(".slot-child").text()).toBe("Hello");
+  });
+
+  it("applies styleClassPassthrough classes to the wrapper", async () => {
+    const wrapper = await mountSuspended(ClipElement, {
+      props: { styleClassPassthrough: ["custom-class"] },
+    });
+    expect(wrapper.find(".clip-element-wrapper").classes()).toContain("custom-class");
+  });
+
+  it("clips fully (0px inset) once the element has scrolled past maxClip", async () => {
+    const wrapper = await mountSuspended(ClipElement, { props: { maxClip: 100 } });
+    setTopAndScroll(wrapper, 150);
+    await wrapper.vm.$nextTick();
+
+    const clipElement = wrapper.find(".clipped-element").element as HTMLElement;
+    expect(clipElement.style.getPropertyValue("--_clip-path")).toBe("inset(0px 0 0 0)");
+  });
+
+  it("increases the clip offset as the element approaches the top of the viewport", async () => {
+    const wrapper = await mountSuspended(ClipElement, { props: { maxClip: 100 } });
+    setTopAndScroll(wrapper, 40);
+    await wrapper.vm.$nextTick();
+
+    const clipElement = wrapper.find(".clipped-element").element as HTMLElement;
+    expect(clipElement.style.getPropertyValue("--_clip-path")).toBe("inset(60px 0 0 0)");
+  });
+
+  it("keeps clipping past 0px once the element has scrolled above the viewport", async () => {
+    const wrapper = await mountSuspended(ClipElement, { props: { maxClip: 100 } });
+    setTopAndScroll(wrapper, -20);
+    await wrapper.vm.$nextTick();
+
+    const clipElement = wrapper.find(".clipped-element").element as HTMLElement;
+    expect(clipElement.style.getPropertyValue("--_clip-path")).toBe("inset(120px 0 0 0)");
+  });
+});

package/app/components/01.atoms/animations/clip-element/tests/__snapshots__/ClipElement.spec.ts.snap

@@ -0,0 +1,7 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`ClipElement > renders correct HTML structure (default props) 1`] = `
+"<div class="clip-element-wrapper">
+  <div class="clipped-element" style="--_clip-path: inset(0px 0 0 0);"></div>
+</div>"
+`;

package/app/components/01.atoms/animations/marquee-scroller/CONSUMER-STYLING.md

@@ -0,0 +1,94 @@
+# MarqueeScroller — Consumer Styling Guide
+
+## Public token API
+
+| Token | Default | Controls |
+|---|---|---|
+| `--marquee-scroller-fade-width` | `10%` | Width of the transparent fade at each edge of the track (`mask-image`) |
+| `--marquee-scroller-focus-outline-width` | `2px` | Outline width on the root region and the control button when keyboard-focused (colour is `--theme-ring`) |
+| `--marquee-scroller-focus-outline-offset` | `2px` | Outline offset on the same two focus states |
+| `--marquee-scroller-group-hover-filter` | `grayscale(1)` | Filter applied to every item when the pointer hovers anywhere over the scroller |
+| `--marquee-scroller-item-hover-filter` | `grayscale(0)` | Filter applied to a single item when it is individually hovered (overrides the group filter for that item) |
+| `--marquee-scroller-item-transition-duration` | `0.5s` | Transition duration for the item hover filter change |
+| `--marquee-scroller-item-border-width` | `1px` | Item border width |
+| `--marquee-scroller-item-border-colour` | `light-dark(var(--slate-10), var(--slate-00))` | Item border colour |
+| `--marquee-scroller-item-border-radius` | `4px` | Item border radius |
+| `--marquee-scroller-control-offset` | `8px` | Distance of the pause/play button from the top and end edges |
+| `--marquee-scroller-control-background-colour` | `rgba(0, 0, 0, 0.7)` | Pause/play button background |
+| `--marquee-scroller-control-background-colour-hover` | `rgba(0, 0, 0, 0.9)` | Pause/play button background on hover |
+| `--marquee-scroller-control-text-colour` | `white` | Pause/play button icon colour |
+| `--marquee-scroller-control-border-radius` | `4px` | Pause/play button border radius |
+| `--marquee-scroller-control-padding` | `8px` | Pause/play button padding |
+| `--marquee-scroller-control-font-size` | `14px` | Pause/play button icon font size |
+| `--marquee-scroller-control-transition-duration` | `0.2s` | Pause/play button background-colour transition duration |
+| `--marquee-scroller-control-border-width` | `1px` | Pause/play button border width in forced-colors/high-contrast mode (`prefers-contrast: high`). The border colour itself stays the system `ButtonText` keyword — see note below. |
+
+```css
+.my-page {
+  --marquee-scroller-item-border-colour: #b5651d;
+  --marquee-scroller-control-background-colour: #1a1a1a;
+  --marquee-scroller-fade-width: 20%;
+}
+```
+
+## High-contrast mode colours are not tokenised
+
+Under `prefers-contrast: high`, the control button switches to the system colour keywords
+`ButtonFace`/`ButtonText` rather than the component's own background/text tokens. These aren't
+exposed as overridable tokens on purpose — they're meant to track the user's OS-level high-contrast
+theme, which a component-level override would defeat. Only the border *width* in that mode is a
+token (`--marquee-scroller-control-border-width`), since it's a plain dimension with no such
+constraint.
+
+## Item size and spacing are prop-driven, not tokens
+
+Item `width`/`height`/`gap` and the animation duration are set via the `itemConfig` and
+`animationRuntime` props (not CSS custom properties), since they also drive the component's own
+layout math (`aspect-ratio`, track width). Override those through props:
+
+```vue
+<MarqueeScroller
+  :item-config="{ width: '80px', height: '80px', gap: '24px' }"
+  animation-runtime="60s"
+/>
+```
+
+## Item content via slots
+
+Each entry in `marqueeData` (`{ id, content }`) renders a slot named after its `id`. Provide the
+markup for each item via that dynamically-named slot:
+
+```vue
+<MarqueeScroller :marquee-data="[{ id: 1, content: 'logo-a' }, { id: 2, content: 'logo-b' }]">
+  <template #1>
+    <img src="/logos/a.svg" alt="Logo A" />
+  </template>
+  <template #2>
+    <img src="/logos/b.svg" alt="Logo B" />
+  </template>
+</MarqueeScroller>
+```
+
+## Control button icon and copy
+
+The pause/play button's icon and its `aria-label` copy are all overridable — see `playIcon`/
+`pauseIcon`/`playLabel`/`pauseLabel` props, or the `toggle-icon` slot for a fully custom icon
+(scoped with `isPaused`):
+
+```vue
+<MarqueeScroller
+  show-controls
+  play-icon="mdi:play-circle"
+  pause-icon="mdi:pause-circle"
+  play-label="Reproduire"
+  pause-label="Suspendre"
+/>
+```
+
+```vue
+<MarqueeScroller show-controls>
+  <template #toggle-icon="{ isPaused }">
+    <Icon :name="isPaused ? 'lucide:play' : 'lucide:pause'" />
+  </template>
+</MarqueeScroller>
+```

package/app/components/01.atoms/animations/marquee-scroller/MarqueeScroller.vue

@@ -0,0 +1,331 @@
+<template>
+  <div
+    v-if="displayComponent"
+    ref="rootEl"
+    class="marquee-scroller"
+    :class="{ reverse: reverse, paused: isPaused, 'reduced-motion': prefersReducedMotion }"
+    role="region"
+    :aria-label="ariaLabel"
+    :aria-live="isPaused ? 'polite' : 'off'"
+    tabindex="0"
+    @keydown="handleKeydown"
+    @focus="handleFocus"
+    @blur="handleBlur"
+  >
+    <div class="sr-only">
+      {{ ariaDescription }}
+    </div>
+
+    <button
+      v-if="showControls"
+      class="control-btn"
+      :aria-label="isPaused ? playLabel : pauseLabel"
+      type="button"
+      @click="togglePause"
+    >
+      <slot name="toggle-icon" :is-paused="isPaused">
+        <Icon :name="isPaused ? playIcon : pauseIcon" aria-hidden="true" />
+      </slot>
+    </button>
+
+    <div class="marquee-track" :aria-hidden="!isPaused">
+      <div ref="groupEl" class="marquee-group">
+        <template v-for="copy in repeatCount" :key="copy">
+          <div v-for="item in marqueeData" :key="`${copy}-${item.id}`" class="item">
+            <slot :name="item.id"></slot>
+          </div>
+        </template>
+      </div>
+      <div class="marquee-group" aria-hidden="true">
+        <template v-for="copy in repeatCount" :key="copy">
+          <div v-for="item in marqueeData" :key="`duplicate-${copy}-${item.id}`" class="item">
+            <slot :name="item.id"></slot>
+          </div>
+        </template>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import type { MarqueeItem, MarqueeItemConfig } from "~/types/components";
+
+interface Props {
+  animationRuntime?: string;
+  reverse?: boolean;
+  marqueeData?: MarqueeItem[];
+  itemConfig?: MarqueeItemConfig;
+  /** aria-label on the root region — override for localisation. */
+  ariaLabel?: string;
+  /** Screen-reader-only instructions rendered inside the region — override for localisation. */
+  ariaDescription?: string;
+  showControls?: boolean;
+  respectReducedMotion?: boolean;
+  /** Iconify icon name shown on the control button while paused. Ignored if the toggle-icon slot is used. */
+  playIcon?: string;
+  /** Iconify icon name shown on the control button while playing. Ignored if the toggle-icon slot is used. */
+  pauseIcon?: string;
+  /** Control button aria-label while paused — override for localisation. */
+  playLabel?: string;
+  /** Control button aria-label while playing — override for localisation. */
+  pauseLabel?: string;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  animationRuntime: "40s",
+  reverse: false,
+  marqueeData: () => [],
+  itemConfig: () => ({ width: "50px", height: "50px", gap: "16px" }),
+  ariaLabel: "Scrolling content",
+  ariaDescription: "Use spacebar to pause or play the animation.",
+  showControls: false,
+  respectReducedMotion: true,
+  playIcon: "mdi:play",
+  pauseIcon: "mdi:pause",
+  playLabel: "Play animation",
+  pauseLabel: "Pause animation",
+});
+
+const displayComponent = ref(false);
+const isPaused = ref(false);
+const isFocused = ref(false);
+const prefersReducedMotion = ref(false);
+const rootEl = ref<HTMLElement | null>(null);
+const groupEl = ref<HTMLElement | null>(null);
+const repeatCount = ref(1);
+let resizeObserver: ResizeObserver | null = null;
+
+const height = computed(() => props.itemConfig.height || "50px");
+const width = computed(() => props.itemConfig.width || "50px");
+const gap = computed(() => props.itemConfig.gap || "16px");
+const itemCount = computed(() => props.marqueeData.length * repeatCount.value);
+
+// A single copy of marqueeData may not be wide enough to fill a wide container — if it
+// isn't, the loop briefly shows empty space before snapping back into view. Repeat the
+// data enough times per track group to always exceed the container's width.
+const updateRepeatCount = () => {
+  if (!rootEl.value || !groupEl.value || props.marqueeData.length === 0) return;
+  const baseGroupWidth = groupEl.value.scrollWidth / repeatCount.value;
+  if (baseGroupWidth <= 0) return;
+  const needed = Math.max(1, Math.ceil(rootEl.value.offsetWidth / baseGroupWidth));
+  if (needed !== repeatCount.value) repeatCount.value = needed;
+};
+
+// Check for reduced motion preference
+const checkReducedMotion = () => {
+  if (typeof window !== "undefined" && props.respectReducedMotion) {
+    const mediaQuery = window.matchMedia("(prefers-reduced-motion: reduce)");
+    prefersReducedMotion.value = mediaQuery.matches;
+
+    // Listen for changes
+    mediaQuery.addEventListener("change", (e) => {
+      prefersReducedMotion.value = e.matches;
+      if (e.matches) {
+        isPaused.value = true;
+      }
+    });
+  }
+};
+
+const togglePause = () => {
+  isPaused.value = !isPaused.value;
+};
+
+const handleKeydown = (event: KeyboardEvent) => {
+  if (event.key === " " || event.key === "Spacebar") {
+    event.preventDefault();
+    togglePause();
+  }
+};
+
+const handleFocus = () => {
+  isFocused.value = true;
+  if (props.respectReducedMotion) {
+    isPaused.value = true;
+  }
+};
+
+const handleBlur = () => {
+  isFocused.value = false;
+  if (!prefersReducedMotion.value) {
+    isPaused.value = false;
+  }
+};
+
+watch(
+  () => [props.marqueeData, props.itemConfig],
+  () => {
+    repeatCount.value = 1;
+    nextTick(updateRepeatCount);
+  },
+  { deep: true }
+);
+
+onMounted(async () => {
+  displayComponent.value = true;
+  checkReducedMotion();
+
+  // Auto-pause if user prefers reduced motion
+  if (prefersReducedMotion.value) {
+    isPaused.value = true;
+  }
+
+  await nextTick();
+  updateRepeatCount();
+
+  if (typeof ResizeObserver !== "undefined" && rootEl.value) {
+    resizeObserver = new ResizeObserver(() => updateRepeatCount());
+    resizeObserver.observe(rootEl.value);
+  }
+});
+
+onUnmounted(() => {
+  resizeObserver?.disconnect();
+});
+</script>
+
+<style lang="css">
+@layer components {
+  .marquee-scroller {
+    --_fade-width: var(--marquee-scroller-fade-width, 10%);
+
+    width: 100%;
+    height: v-bind(height);
+    overflow: hidden;
+    mask-image: linear-gradient(
+      to right,
+      transparent,
+      #000 var(--_fade-width) calc(100% - var(--_fade-width)),
+      transparent
+    );
+    position: relative;
+
+    /* Focus styles */
+    &:focus-visible {
+      outline: var(--marquee-scroller-focus-outline-width, 2px) solid var(--theme-ring);
+      outline-offset: var(--marquee-scroller-focus-outline-offset, 2px);
+    }
+
+    /* Paused state */
+    &.paused .marquee-track {
+      animation-play-state: paused;
+    }
+
+    /* Reduced motion - disable animation completely */
+    &.reduced-motion .marquee-track {
+      animation: none !important;
+    }
+
+    &:hover .marquee-track {
+      animation-play-state: paused;
+    }
+
+    &:hover .item {
+      filter: var(--marquee-scroller-group-hover-filter, grayscale(1));
+    }
+
+    /* Screen reader only text */
+    .sr-only {
+      position: absolute;
+      width: 1px;
+      height: 1px;
+      padding: 0;
+      margin: -1px;
+      overflow: hidden;
+      clip: rect(0, 0, 0, 0);
+      white-space: nowrap;
+      border: 0;
+    }
+
+    /* Control button */
+    .control-btn {
+      position: absolute;
+      inset-block-start: var(--marquee-scroller-control-offset, 8px);
+      inset-inline-end: var(--marquee-scroller-control-offset, 8px);
+      z-index: 10;
+      background: var(--marquee-scroller-control-background-colour, rgba(0, 0, 0, 0.7));
+      color: var(--marquee-scroller-control-text-colour, white);
+      border: none;
+      border-radius: var(--marquee-scroller-control-border-radius, 4px);
+      padding: var(--marquee-scroller-control-padding, 8px);
+      cursor: pointer;
+      font-size: var(--marquee-scroller-control-font-size, 14px);
+      transition: background-color var(--marquee-scroller-control-transition-duration, 0.2s);
+
+      &:hover {
+        background-color: var(--marquee-scroller-control-background-colour-hover, rgba(0, 0, 0, 0.9));
+      }
+
+      &:focus-visible {
+        outline: var(--marquee-scroller-focus-outline-width, 2px) solid var(--theme-ring);
+        outline-offset: 2px;
+      }
+    }
+
+    .marquee-track {
+      --_track-shift: calc(v-bind(itemCount) * (v-bind(width) + v-bind(gap)));
+
+      display: flex;
+      width: fit-content;
+      gap: v-bind(gap);
+      animation: marqueeMove v-bind(animationRuntime) linear infinite;
+    }
+
+    &.reverse .marquee-track {
+      animation-direction: reverse;
+    }
+
+    .marquee-group {
+      display: flex;
+      gap: v-bind(gap);
+      flex-shrink: 0;
+    }
+
+    .item {
+      width: v-bind(width);
+      height: v-bind(height);
+      display: grid;
+      place-items: center;
+      aspect-ratio: 1 / 1;
+      transition: filter var(--marquee-scroller-item-transition-duration, 0.5s);
+      flex-shrink: 0;
+
+      border: var(--marquee-scroller-item-border-width, 1px) solid
+        var(--marquee-scroller-item-border-colour, light-dark(var(--slate-10), var(--slate-00)));
+      border-radius: var(--marquee-scroller-item-border-radius, 4px);
+
+      &:hover {
+        filter: var(--marquee-scroller-item-hover-filter, grayscale(0));
+      }
+    }
+  }
+
+  @keyframes marqueeMove {
+    from {
+      transform: translateX(0);
+    }
+    to {
+      /* Not -50%: the track's own gap between the two groups makes that overshoot the seam. */
+      transform: translateX(calc(-1 * var(--_track-shift)));
+    }
+  }
+
+  /* High contrast mode support */
+  @media (prefers-contrast: high) {
+    .marquee-scroller {
+      .control-btn {
+        background: ButtonFace;
+        color: ButtonText;
+        border: var(--marquee-scroller-control-border-width, 1px) solid ButtonText;
+      }
+    }
+  }
+
+  /* Respect user's motion preferences */
+  @media (prefers-reduced-motion: reduce) {
+    .marquee-scroller .marquee-track {
+      animation: none !important;
+    }
+  }
+}
+</style>

package/app/components/01.atoms/animations/marquee-scroller/stories/MarqueeScroller.stories.ts

@@ -0,0 +1,151 @@
+import { computed } from "vue";
+import MarqueeScroller from "../MarqueeScroller.vue";
+import type { Meta, StoryObj } from "@nuxtjs/storybook";
+import type { MarqueeItem, MarqueeItemConfig } from "~/types/components";
+
+// animationRuntime is a CSS duration string ("30s") on the component — Storybook has no native
+// range control for that, so the story exposes a plain-number `animationRuntimeSeconds` arg and
+// maps it to the real prop. See feedback_storybook_extra_args memory / StoryArgs pattern.
+type StoryArgs = {
+  animationRuntimeSeconds?: number;
+  reverse?: boolean;
+  marqueeData?: MarqueeItem[];
+  itemConfig?: MarqueeItemConfig;
+  ariaLabel?: string;
+  ariaDescription?: string;
+  showControls?: boolean;
+  respectReducedMotion?: boolean;
+  playIcon?: string;
+  pauseIcon?: string;
+  playLabel?: string;
+  pauseLabel?: string;
+};
+
+const logoData: MarqueeItem[] = [
+  { id: 1, content: "Logo A" },
+  { id: 2, content: "Logo B" },
+  { id: 3, content: "Logo C" },
+  { id: 4, content: "Logo D" },
+  { id: 5, content: "Logo E" },
+];
+
+const logoSlots = logoData
+  .map(
+    (item) => `
+    <template #${item.id}>
+      <div style="display: grid; place-items: center; width: 100%; height: 100%; background: light-dark(#eee, #333); font-weight: 600;">
+        ${item.content}
+      </div>
+    </template>`
+  )
+  .join("\n");
+
+function useStorySetup(args: StoryArgs) {
+  const componentArgs = computed(() => {
+    const { animationRuntimeSeconds, ...rest } = args;
+    return {
+      ...rest,
+      animationRuntime: `${animationRuntimeSeconds ?? 30}s`,
+    };
+  });
+  return { componentArgs };
+}
+
+const meta: Meta<StoryArgs> = {
+  title: "Atoms/Effects/MarqueeScroller",
+  component: MarqueeScroller,
+  argTypes: {
+    animationRuntimeSeconds: {
+      control: { type: "range", min: 5, max: 90, step: 1 },
+      description: "Loop duration in seconds — maps to the `animationRuntime` prop (e.g. `30s`)",
+      table: { category: "Animation" },
+    },
+    reverse: {
+      control: "boolean",
+      description: "Reverses the scroll direction",
+      table: { category: "Animation" },
+    },
+    marqueeData: {
+      control: "object",
+      description: "Array of `{ id, content }` items — each `id` names a slot to fill with that item's markup",
+      table: { category: "Content" },
+    },
+    itemConfig: {
+      control: "object",
+      description: "`{ width, height, gap }` applied to every item and the track",
+      table: { category: "Layout" },
+    },
+    ariaLabel: {
+      control: "text",
+      table: { category: "Accessibility" },
+    },
+    ariaDescription: {
+      control: "text",
+      table: { category: "Accessibility" },
+    },
+    showControls: {
+      control: "boolean",
+      description: "Shows a visible pause/play button (required for WCAG 2.2.2 on any auto-scrolling content)",
+      table: { category: "Accessibility" },
+    },
+    respectReducedMotion: {
+      control: "boolean",
+      description: "Auto-pauses and disables the animation when the user has prefers-reduced-motion set",
+      table: { category: "Accessibility" },
+    },
+    playIcon: {
+      control: "text",
+      description: "Iconify icon name shown on the control button while paused",
+      table: { category: "Control button" },
+    },
+    pauseIcon: {
+      control: "text",
+      description: "Iconify icon name shown on the control button while playing",
+      table: { category: "Control button" },
+    },
+    playLabel: {
+      control: "text",
+      description: "Control button aria-label while paused — override for localisation",
+      table: { category: "Control button" },
+    },
+    pauseLabel: {
+      control: "text",
+      description: "Control button aria-label while playing — override for localisation",
+      table: { category: "Control button" },
+    },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "An infinite horizontal scroller for logos, badges, or other small repeating items. Items are provided via `marqueeData` plus one dynamically-named slot per item id. Pauses on hover/focus, supports keyboard control (spacebar), and respects prefers-reduced-motion.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<StoryArgs>;
+
+export const WithControls: Story = {
+  args: {
+    animationRuntimeSeconds: 30,
+    reverse: false,
+    marqueeData: logoData,
+    itemConfig: { width: "120px", height: "60px", gap: "24px" },
+    showControls: true,
+    respectReducedMotion: true,
+  },
+  render: (args) => ({
+    components: { MarqueeScroller },
+    setup() {
+      const { componentArgs } = useStorySetup(args as StoryArgs);
+      return { componentArgs };
+    },
+    template: `
+      <MarqueeScroller v-bind="componentArgs">
+        ${logoSlots}
+      </MarqueeScroller>
+    `,
+  }),
+};