srcdev-nuxt-components 9.4.7 → 9.4.9

package/app/components/01.atoms/animations/rotating-carousel-image/RotatingCarouselImage.vue

@@ -0,0 +1,315 @@
+<template>
+  <component
+    :is="tag"
+    ref="carouselRef"
+    class="rotating-carousel"
+    :class="[elementClasses, { paused: isPaused, 'reduced-motion': prefersReducedMotion, 'hover-pauses': props.pauseOnHover }]"
+    :style="`--_rotate-x: ${rotateXProp}deg; --_perspective: ${perspectiveProp}; --_translateZ: ${translateZProp}`"
+    role="region"
+    :aria-label="ariaLabel"
+    tabindex="0"
+    @keydown="handleKeydown"
+    @focus="handleFocus"
+    @blur="handleBlur"
+  >
+    <div class="sr-only">
+      {{ ariaDescription }}
+    </div>
+
+    <button
+      v-if="showControls"
+      class="control-btn"
+      type="button"
+      :aria-label="isPaused ? playLabel : pauseLabel"
+      @click="togglePause"
+    >
+      <slot name="toggle-icon" :is-paused="isPaused">
+        <Icon :name="isPaused ? playIcon : pauseIcon" aria-hidden="true" />
+      </slot>
+    </button>
+
+    <div class="slider" :style="`--_quantity: ${data.length}`">
+      <div v-for="(item, key) in data" :key="key" class="item" :style="`--_position: ${key}`">
+        <NuxtImg :src="item.src" :alt="item.alt" />
+      </div>
+    </div>
+  </component>
+</template>
+
+<script setup lang="ts">
+import type { CarouselImageData } from "~/types/components"
+
+interface Props {
+  data?: CarouselImageData[]
+  tag?:
+    | "div"
+    | "p"
+    | "span"
+    | "section"
+    | "article"
+    | "aside"
+    | "header"
+    | "footer"
+    | "main"
+    | "nav"
+    | "ul"
+    | "ol"
+  rotateX?: number
+  perspective?: number
+  translateZ?: number
+  /** Pauses the rotation while the pointer hovers over the carousel. */
+  pauseOnHover?: boolean
+  /** Drives rotateX from scroll position instead of the static `rotateX` prop. */
+  useParallaxEffect?: boolean
+  showControls?: boolean
+  respectReducedMotion?: boolean
+  ariaLabel?: string
+  ariaDescription?: string
+  playIcon?: string
+  pauseIcon?: string
+  playLabel?: string
+  pauseLabel?: string
+  styleClassPassthrough?: string | string[]
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  data: () => [],
+  tag: "div",
+  rotateX: 0,
+  perspective: 1000,
+  translateZ: 1000,
+  pauseOnHover: false,
+  useParallaxEffect: true,
+  showControls: false,
+  respectReducedMotion: true,
+  ariaLabel: "Rotating image carousel",
+  ariaDescription: "Use spacebar to pause or play the rotation.",
+  playIcon: "mdi:play",
+  pauseIcon: "mdi:pause",
+  playLabel: "Play rotation",
+  pauseLabel: "Pause rotation",
+  styleClassPassthrough: () => [],
+})
+
+const perspectiveProp = computed(() => `${props.perspective.toString()}px`)
+const translateZProp = computed(() => `${props.translateZ.toString()}px`)
+
+const carouselRef = ref<HTMLElement | null>(null)
+const rotateXProp = ref(props.rotateX)
+const minRotateX = -32
+const maxRotateX = 32
+
+const isPaused = ref(false)
+const prefersReducedMotion = ref(false)
+
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough)
+
+watch(
+  () => props.styleClassPassthrough,
+  () => {
+    resetElementClasses(props.styleClassPassthrough)
+  }
+)
+
+watch(
+  () => props.rotateX,
+  () => {
+    if (!props.useParallaxEffect) {
+      rotateXProp.value = props.rotateX
+    }
+  }
+)
+
+watch(
+  () => props.useParallaxEffect,
+  (currentValue) => {
+    if (currentValue) {
+      handleScroll()
+      window.addEventListener("scroll", handleScroll)
+    } else {
+      window.removeEventListener("scroll", handleScroll)
+    }
+  }
+)
+
+const handleScroll = () => {
+  if (!carouselRef.value) return
+  const rect = (carouselRef.value as HTMLElement).getBoundingClientRect()
+  const viewportHeight = window.innerHeight
+
+  const elementCenter = rect.top + rect.height / 2
+  const viewportCenter = viewportHeight / 2
+  const distanceFromCenter = viewportCenter - elementCenter
+  const maxDistance = viewportHeight / 2 + rect.height / 2
+
+  const progress = (distanceFromCenter + maxDistance) / (maxDistance * 2)
+  const clampedProgress = Math.max(0, Math.min(1, progress))
+
+  rotateXProp.value = minRotateX + (maxRotateX - minRotateX) * clampedProgress
+}
+
+const togglePause = () => {
+  isPaused.value = !isPaused.value
+}
+
+const handleKeydown = (event: KeyboardEvent) => {
+  if (event.key === " " || event.key === "Spacebar") {
+    event.preventDefault()
+    togglePause()
+  }
+}
+
+const handleFocus = () => {
+  isPaused.value = true
+}
+
+const handleBlur = () => {
+  if (!prefersReducedMotion.value) {
+    isPaused.value = false
+  }
+}
+
+const checkReducedMotion = () => {
+  if (typeof window !== "undefined" && props.respectReducedMotion) {
+    const mediaQuery = window.matchMedia("(prefers-reduced-motion: reduce)")
+    prefersReducedMotion.value = mediaQuery.matches
+    if (mediaQuery.matches) {
+      isPaused.value = true
+    }
+
+    mediaQuery.addEventListener("change", (event) => {
+      prefersReducedMotion.value = event.matches
+      if (event.matches) {
+        isPaused.value = true
+      }
+    })
+  }
+}
+
+onMounted(async () => {
+  checkReducedMotion()
+
+  if (props.useParallaxEffect) {
+    handleScroll()
+    await nextTick()
+    window.addEventListener("scroll", handleScroll)
+  }
+})
+
+onUnmounted(() => {
+  window.removeEventListener("scroll", handleScroll)
+})
+</script>
+
+<style lang="css">
+@layer components {
+  @keyframes autoRun {
+    from {
+      transform: perspective(var(--_perspective)) rotateX(var(--_rotate-x)) rotateY(0deg);
+    }
+    to {
+      transform: perspective(var(--_perspective)) rotateX(var(--_rotate-x)) rotateY(360deg);
+    }
+  }
+
+  .rotating-carousel {
+    width: 100%;
+    height: var(--rotating-carousel-height, 70svh);
+    text-align: center;
+    overflow: hidden;
+    position: relative;
+
+    &:focus-visible {
+      outline: var(--rotating-carousel-focus-outline-width, 2px) solid var(--theme-ring);
+      outline-offset: var(--rotating-carousel-focus-outline-offset, 2px);
+    }
+
+    &.paused .slider {
+      animation-play-state: paused;
+    }
+
+    &.reduced-motion .slider {
+      animation: none !important;
+    }
+
+    .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-btn {
+      position: absolute;
+      inset-block-start: var(--rotating-carousel-control-offset, 8px);
+      inset-inline-end: var(--rotating-carousel-control-offset, 8px);
+      z-index: 10;
+      background: var(--rotating-carousel-control-background-colour, rgba(0, 0, 0, 0.7));
+      color: var(--rotating-carousel-control-text-colour, white);
+      border: none;
+      border-radius: var(--rotating-carousel-control-border-radius, 4px);
+      padding: var(--rotating-carousel-control-padding, 8px);
+      cursor: pointer;
+      font-size: var(--rotating-carousel-control-font-size, 14px);
+      transition: background-color var(--rotating-carousel-control-transition-duration, 0.2s);
+
+      &:hover {
+        background-color: var(--rotating-carousel-control-background-colour-hover, rgba(0, 0, 0, 0.9));
+      }
+
+      &:focus-visible {
+        outline: var(--rotating-carousel-focus-outline-width, 2px) solid var(--theme-ring);
+        outline-offset: var(--rotating-carousel-focus-outline-offset, 2px);
+      }
+    }
+
+    .slider {
+      position: absolute;
+      width: var(--rotating-carousel-item-width, 200px);
+      height: var(--rotating-carousel-item-height, 250px);
+      bottom: var(--rotating-carousel-offset-bottom, 35%);
+      left: calc(50% - (var(--rotating-carousel-item-width, 200px) / 2));
+      transform-style: preserve-3d;
+      transform: perspective(var(--_perspective));
+      animation: autoRun var(--rotating-carousel-rotation-duration, 30s) linear infinite;
+      z-index: var(--rotating-carousel-z-index, 2);
+
+      .item {
+        position: absolute;
+        inset: 0 0 0 0;
+        transform: rotateY(calc((var(--_position) - 1) * (360 / var(--_quantity)) * 1deg))
+          translateZ(var(--_translateZ));
+
+        img {
+          width: 100%;
+          height: 100%;
+          object-fit: cover;
+        }
+      }
+    }
+
+    &.hover-pauses:hover .slider {
+      animation-play-state: paused;
+    }
+  }
+
+  @media (prefers-contrast: high) {
+    .rotating-carousel .control-btn {
+      background: ButtonFace;
+      color: ButtonText;
+      border: var(--rotating-carousel-control-border-width, 1px) solid ButtonText;
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .rotating-carousel .slider {
+      animation: none !important;
+    }
+  }
+}
+</style>

package/app/components/01.atoms/animations/rotating-carousel-image/stories/RotatingCarouselImage.stories.ts

@@ -0,0 +1,156 @@
+import RotatingCarouselImage from "../RotatingCarouselImage.vue";
+import type { Meta, StoryObj } from "@nuxtjs/storybook";
+import type { CarouselImageData } from "~/types/components";
+
+type StoryArgs = {
+  data?: CarouselImageData[];
+  rotateX?: number;
+  perspective?: number;
+  translateZ?: number;
+  pauseOnHover?: boolean;
+  useParallaxEffect?: boolean;
+  showControls?: boolean;
+  respectReducedMotion?: boolean;
+  ariaLabel?: string;
+  ariaDescription?: string;
+  playIcon?: string;
+  pauseIcon?: string;
+  playLabel?: string;
+  pauseLabel?: string;
+};
+
+const carouselData: CarouselImageData[] = Array.from({ length: 8 }, (_, index) => ({
+  src: `https://picsum.photos/seed/rotating-carousel-${index}/400/500`,
+  alt: `Rotating carousel image ${index + 1}`,
+}));
+
+const meta: Meta<StoryArgs> = {
+  title: "Atoms/Animations/RotatingCarouselImage",
+  component: RotatingCarouselImage,
+  argTypes: {
+    data: {
+      control: "object",
+      description: "Array of `{ src, alt }` images rendered around the rotation",
+      table: { category: "Content" },
+    },
+    rotateX: {
+      control: { type: "range", min: -32, max: 32, step: 1 },
+      description: "Static X-axis tilt in degrees — ignored while `useParallaxEffect` is true",
+      table: { category: "Rotation" },
+    },
+    perspective: {
+      control: { type: "range", min: 200, max: 3000, step: 50 },
+      description: "CSS perspective distance in pixels",
+      table: { category: "Rotation" },
+    },
+    translateZ: {
+      control: { type: "range", min: 200, max: 3000, step: 50 },
+      description: "Radius of the rotation — distance each item sits from the centre, in pixels",
+      table: { category: "Rotation" },
+    },
+    pauseOnHover: {
+      control: "boolean",
+      description: "Pauses the rotation while the pointer hovers over the carousel",
+      table: { category: "Interaction" },
+    },
+    useParallaxEffect: {
+      control: "boolean",
+      description: "Drives the tilt from scroll position instead of the static `rotateX` prop",
+      table: { category: "Interaction" },
+    },
+    showControls: {
+      control: "boolean",
+      description: "Shows a visible pause/play button (required for WCAG 2.2.2 on any auto-rotating 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" },
+    },
+    ariaLabel: {
+      control: "text",
+      table: { category: "Accessibility" },
+    },
+    ariaDescription: {
+      control: "text",
+      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:
+          "A 3D rotating carousel of images. By default the tilt follows scroll position (`useParallaxEffect`); disable it to use a static `rotateX`. Supports keyboard pause (spacebar), an optional visible pause/play button, and respects prefers-reduced-motion.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<StoryArgs>;
+
+export const WithControls: Story = {
+  args: {
+    data: carouselData,
+    rotateX: 0,
+    perspective: 1000,
+    translateZ: 1000,
+    pauseOnHover: false,
+    useParallaxEffect: false,
+    showControls: true,
+    respectReducedMotion: true,
+    ariaLabel: "Rotating image carousel",
+  },
+  render: (args) => ({
+    components: { RotatingCarouselImage },
+    setup() {
+      return { args };
+    },
+    template: `<RotatingCarouselImage v-bind="args" />`,
+  }),
+};
+
+export const ScrollParallax: Story = {
+  args: {
+    data: carouselData,
+    perspective: 1000,
+    translateZ: 1000,
+    useParallaxEffect: true,
+    showControls: true,
+  },
+  render: (args) => ({
+    components: { RotatingCarouselImage },
+    setup() {
+      return { args };
+    },
+    template: `
+      <div>
+        <p style="text-align: center; padding: 2rem;">Scroll this preview to tilt the carousel.</p>
+        <div style="height: 60svh;"></div>
+        <RotatingCarouselImage v-bind="args" />
+        <div style="height: 60svh;"></div>
+      </div>
+    `,
+  }),
+};

package/app/components/01.atoms/animations/rotating-carousel-image/tests/RotatingCarouselImage.spec.ts

@@ -0,0 +1,230 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import RotatingCarouselImage from "../RotatingCarouselImage.vue";
+
+const stubMatchMedia = (prefersReducedMotion: boolean) => {
+  vi.stubGlobal(
+    "matchMedia",
+    vi.fn().mockReturnValue({
+      matches: prefersReducedMotion,
+      addEventListener: vi.fn(),
+    })
+  );
+};
+
+const carouselData = [
+  { src: "/a.jpg", alt: "A" },
+  { src: "/b.jpg", alt: "B" },
+];
+
+describe("RotatingCarouselImage", () => {
+  beforeEach(() => {
+    stubMatchMedia(false);
+  });
+
+  // ─── Mount ───────────────────────────────────────────────────────────────
+
+  it("mounts without error", async () => {
+    const wrapper = await mountSuspended(RotatingCarouselImage, {
+      props: { useParallaxEffect: false },
+    });
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  it("renders correct HTML structure (default props)", async () => {
+    const wrapper = await mountSuspended(RotatingCarouselImage, {
+      props: { useParallaxEffect: false },
+    });
+    expect(wrapper.html()).toMatchSnapshot();
+  });
+
+  it("renders correct HTML structure (all props set)", async () => {
+    const wrapper = await mountSuspended(RotatingCarouselImage, {
+      props: {
+        data: carouselData,
+        tag: "section",
+        rotateX: 10,
+        perspective: 1200,
+        translateZ: 1200,
+        pauseOnHover: true,
+        useParallaxEffect: false,
+        showControls: true,
+        ariaLabel: "Custom carousel",
+        ariaDescription: "Custom instructions",
+      },
+    });
+    expect(wrapper.html()).toMatchSnapshot();
+  });
+
+  // ─── data / rendering ────────────────────────────────────────────────────
+
+  it("renders one .item per data entry", async () => {
+    const wrapper = await mountSuspended(RotatingCarouselImage, {
+      props: { data: carouselData, useParallaxEffect: false },
+    });
+    expect(wrapper.findAll(".item")).toHaveLength(2);
+  });
+
+  it("renders no items when data is empty", async () => {
+    const wrapper = await mountSuspended(RotatingCarouselImage, {
+      props: { useParallaxEffect: false },
+    });
+    expect(wrapper.findAll(".item")).toHaveLength(0);
+  });
+
+  it("renders the given tag", async () => {
+    const wrapper = await mountSuspended(RotatingCarouselImage, {
+      props: { tag: "section", useParallaxEffect: false },
+    });
+    expect(wrapper.element.tagName).toBe("SECTION");
+  });
+
+  // ─── Accessibility attributes ────────────────────────────────────────────
+
+  it("defaults aria-label", async () => {
+    const wrapper = await mountSuspended(RotatingCarouselImage, {
+      props: { useParallaxEffect: false },
+    });
+    expect(wrapper.attributes("aria-label")).toBe("Rotating image carousel");
+  });
+
+  it("uses a custom ariaLabel when provided", async () => {
+    const wrapper = await mountSuspended(RotatingCarouselImage, {
+      props: { ariaLabel: "Client photos", useParallaxEffect: false },
+    });
+    expect(wrapper.attributes("aria-label")).toBe("Client photos");
+  });
+
+  it("uses default screen-reader instructions when ariaDescription is not set", async () => {
+    const wrapper = await mountSuspended(RotatingCarouselImage, {
+      props: { useParallaxEffect: false },
+    });
+    expect(wrapper.find(".sr-only").text()).toContain("Use spacebar to pause or play");
+  });
+
+  it("uses a custom ariaDescription when provided", async () => {
+    const wrapper = await mountSuspended(RotatingCarouselImage, {
+      props: { ariaDescription: "Custom instructions", useParallaxEffect: false },
+    });
+    expect(wrapper.find(".sr-only").text()).toBe("Custom instructions");
+  });
+
+  // ─── Controls ────────────────────────────────────────────────────────────
+
+  it("does not render the control button by default", async () => {
+    const wrapper = await mountSuspended(RotatingCarouselImage, {
+      props: { useParallaxEffect: false },
+    });
+    expect(wrapper.find(".control-btn").exists()).toBe(false);
+  });
+
+  it("renders the control button when showControls is true", async () => {
+    const wrapper = await mountSuspended(RotatingCarouselImage, {
+      props: { showControls: true, useParallaxEffect: false },
+    });
+    expect(wrapper.find(".control-btn").exists()).toBe(true);
+  });
+
+  it("toggles paused state when the control button is clicked", async () => {
+    const wrapper = await mountSuspended(RotatingCarouselImage, {
+      props: { showControls: true, useParallaxEffect: false },
+    });
+    await wrapper.find(".control-btn").trigger("click");
+    expect(wrapper.classes()).toContain("paused");
+    expect(wrapper.find(".control-btn").attributes("aria-label")).toBe("Play rotation");
+  });
+
+  it("renders a custom playIcon/pauseIcon", async () => {
+    const wrapper = await mountSuspended(RotatingCarouselImage, {
+      props: { showControls: true, useParallaxEffect: false, playIcon: "mdi:play-circle", pauseIcon: "mdi:pause-circle" },
+    });
+    expect(wrapper.find(".control-btn").html()).toContain("mdi:pause-circle");
+    await wrapper.find(".control-btn").trigger("click");
+    expect(wrapper.find(".control-btn").html()).toContain("mdi:play-circle");
+  });
+
+  it("uses custom playLabel/pauseLabel for the control button's aria-label", async () => {
+    const wrapper = await mountSuspended(RotatingCarouselImage, {
+      props: { showControls: true, useParallaxEffect: false, playLabel: "Reproduire", pauseLabel: "Suspendre" },
+    });
+    expect(wrapper.find(".control-btn").attributes("aria-label")).toBe("Suspendre");
+    await wrapper.find(".control-btn").trigger("click");
+    expect(wrapper.find(".control-btn").attributes("aria-label")).toBe("Reproduire");
+  });
+
+  it("replaces the toggle icon via the toggle-icon slot", async () => {
+    const wrapper = await mountSuspended(RotatingCarouselImage, {
+      props: { showControls: true, useParallaxEffect: false },
+      slots: { "toggle-icon": "<span class='custom-icon'>custom</span>" },
+    });
+    expect(wrapper.find(".custom-icon").exists()).toBe(true);
+  });
+
+  // ─── Keyboard interaction ────────────────────────────────────────────────
+
+  it("toggles pause on spacebar keydown", async () => {
+    const wrapper = await mountSuspended(RotatingCarouselImage, {
+      props: { useParallaxEffect: false },
+    });
+    await wrapper.trigger("keydown", { key: " " });
+    expect(wrapper.classes()).toContain("paused");
+    await wrapper.trigger("keydown", { key: " " });
+    expect(wrapper.classes()).not.toContain("paused");
+  });
+
+  // ─── Focus / blur ────────────────────────────────────────────────────────
+
+  it("pauses on focus", async () => {
+    const wrapper = await mountSuspended(RotatingCarouselImage, {
+      props: { useParallaxEffect: false },
+    });
+    await wrapper.trigger("focus");
+    expect(wrapper.classes()).toContain("paused");
+  });
+
+  it("resumes on blur when the user does not prefer reduced motion", async () => {
+    const wrapper = await mountSuspended(RotatingCarouselImage, {
+      props: { useParallaxEffect: false },
+    });
+    await wrapper.trigger("focus");
+    await wrapper.trigger("blur");
+    expect(wrapper.classes()).not.toContain("paused");
+  });
+
+  // ─── pauseOnHover ────────────────────────────────────────────────────────
+
+  it("does not apply the hover-pauses class by default", async () => {
+    const wrapper = await mountSuspended(RotatingCarouselImage, {
+      props: { useParallaxEffect: false },
+    });
+    expect(wrapper.classes()).not.toContain("hover-pauses");
+  });
+
+  it("applies the hover-pauses class when pauseOnHover is true", async () => {
+    const wrapper = await mountSuspended(RotatingCarouselImage, {
+      props: { pauseOnHover: true, useParallaxEffect: false },
+    });
+    expect(wrapper.classes()).toContain("hover-pauses");
+  });
+
+  // ─── Reduced motion ──────────────────────────────────────────────────────
+
+  it("auto-pauses and applies reduced-motion class when the user prefers reduced motion", async () => {
+    stubMatchMedia(true);
+    const wrapper = await mountSuspended(RotatingCarouselImage, {
+      props: { useParallaxEffect: false },
+    });
+    expect(wrapper.classes()).toContain("paused");
+    expect(wrapper.classes()).toContain("reduced-motion");
+  });
+
+  it("does not check matchMedia when respectReducedMotion is false", async () => {
+    stubMatchMedia(false);
+    const matchMediaSpy = vi.fn(() => ({ matches: false, addEventListener: vi.fn() }));
+    vi.stubGlobal("matchMedia", matchMediaSpy);
+    await mountSuspended(RotatingCarouselImage, {
+      props: { respectReducedMotion: false, useParallaxEffect: false },
+    });
+    expect(matchMediaSpy).not.toHaveBeenCalled();
+  });
+});