srcdev-nuxt-components 9.1.28 → 9.1.30

package/app/components/01.atoms/banner-video/BannerVideo.vue

@@ -0,0 +1,207 @@
+<template>
+  <component
+    :is="tag"
+    class="banner-video"
+    :class="elementClasses"
+    :data-depth="depth"
+    :style="{
+      '--_aspect-ratio': aspectRatio,
+      '--_align-self': verticalPosition,
+      '--_justify-self': horizontalPosition,
+    }"
+  >
+    <video
+      :key="src"
+      ref="videoEl"
+      class="video"
+      autoplay
+      muted
+      loop
+      playsinline
+      preload="auto"
+      :poster="poster"
+      :style="{ objectFit: props.objectFit }"
+      @loadeddata="handleLoadedData"
+      @canplay="handleCanPlay"
+    >
+      <source :src="src" type="video/mp4" />
+    </video>
+    <NuxtImg
+      class="fallback"
+      :src="poster"
+      :alt="alt"
+      :width="imgWidth"
+      :height="imgHeight"
+      loading="eager"
+      decoding="async"
+      :style="{ objectFit: props.objectFit, objectPosition: imgObjectPosition }"
+    />
+  </component>
+</template>
+
+<script setup lang="ts">
+interface Props {
+  /** HTML element to render as the root. Defaults to `section` for landmark semantics. */
+  tag?: "section" | "div" | "header" | "main" | "article";
+  /** Path to the video source file (mp4). */
+  src: string;
+  /** Path to the fallback/poster image. Used as video poster and as the visible fallback
+   *  when the video cannot play or when the user prefers reduced motion. */
+  poster: string;
+  alt?: string;
+  /** Intrinsic width of the poster image — required for NuxtImg optimisation. */
+  imgWidth?: number;
+  /** Intrinsic height of the poster image — required for NuxtImg optimisation. */
+  imgHeight?: number;
+  /**
+   * Depth tier controlling the responsive max-height via a `clamp()` scale.
+   * Each tier maps to a `--theme-banner-video-max-height-{depth}` CSS token that
+   * consuming pages can override. Defaults to `"md"`.
+   */
+  depth?: "xs" | "sm" | "md" | "lg" | "xl";
+  /**
+   * CSS aspect-ratio of the banner container (e.g. `"16/9"`, `"21/9"`, `"4/3"`).
+   * Provides the intrinsic height that `max-height` caps at larger viewport widths.
+   */
+  aspectRatio?: string;
+  /** How the video and fallback image fill the banner frame. Defaults to `"cover"`. */
+  objectFit?: "cover" | "contain" | "fill" | "none" | "scale-down";
+  /** Vertical crop position within the banner. Maps to `align-self` on the video and `object-position` on the fallback image. Defaults to `"center"`. */
+  verticalPosition?: "start" | "center" | "end";
+  /** Horizontal crop position within the banner. Maps to `object-position` on the fallback image. Defaults to `"center"`. */
+  horizontalPosition?: "start" | "center" | "end";
+  styleClassPassthrough?: string | string[];
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  tag: "div",
+  alt: "",
+  imgWidth: 1920,
+  imgHeight: 1080,
+  depth: "md",
+  aspectRatio: "21/9",
+  objectFit: "cover",
+  verticalPosition: "center",
+  horizontalPosition: "center",
+  styleClassPassthrough: () => [],
+});
+
+const positionKeywordMap = {
+  vertical: { start: "top", center: "center", end: "bottom" },
+  horizontal: { start: "left", center: "center", end: "right" },
+} as const;
+
+const imgObjectPosition = computed(
+  () =>
+    `${positionKeywordMap.horizontal[props.horizontalPosition]} ${positionKeywordMap.vertical[props.verticalPosition]}`
+);
+
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+watch(
+  () => props.styleClassPassthrough,
+  () => resetElementClasses(props.styleClassPassthrough)
+);
+
+const videoEl = shallowRef<HTMLVideoElement | null>(null);
+
+const tryPlay = async () => {
+  const v = videoEl.value;
+  if (!v) return;
+  try {
+    // Ensure muted stays true — required for programmatic autoplay in all browsers
+    v.muted = true;
+    await v.play();
+  } catch {
+    // Autoplay blocked or interrupted — fallback image will remain visible
+  }
+};
+
+const kickOffLoad = async () => {
+  await nextTick();
+  const v = videoEl.value;
+  if (!v) return;
+  // Force the media element to (re)read its source child and begin fetching
+  v.load();
+  // Attempt immediate play; loadeddata/canplay handlers will retry once data arrives
+  void tryPlay();
+};
+
+const handleLoadedData = () => {
+  void tryPlay();
+};
+const handleCanPlay = () => {
+  void tryPlay();
+};
+
+// Runs on mount AND whenever src changes (covers route-change re-use edge cases)
+watch(
+  () => props.src,
+  () => {
+    void kickOffLoad();
+  },
+  { immediate: true, flush: "post" }
+);
+
+// Extra safety: when the component becomes active again (e.g. returning via keep-alive)
+onActivated(() => {
+  void kickOffLoad();
+});
+</script>
+
+<style lang="css">
+@layer components {
+  .banner-video {
+    --_max-height: var(--theme-banner-video-max-height, clamp(28rem, 38vw, 56rem));
+
+    display: grid;
+    grid-template-areas: "media";
+    aspect-ratio: var(--_aspect-ratio, 16/9);
+    max-height: var(--_max-height);
+    width: 100%;
+    overflow: hidden;
+
+    &[data-depth="xs"] {
+      --_max-height: var(--theme-banner-video-max-height-xs, clamp(12rem, 15vw, 24rem));
+    }
+    &[data-depth="sm"] {
+      --_max-height: var(--theme-banner-video-max-height-sm, clamp(18rem, 22vw, 36rem));
+    }
+    &[data-depth="md"] {
+      --_max-height: var(--theme-banner-video-max-height-md, clamp(28rem, 38vw, 56rem));
+    }
+    &[data-depth="lg"] {
+      --_max-height: var(--theme-banner-video-max-height-lg, clamp(40rem, 52vw, 72rem));
+    }
+    &[data-depth="xl"] {
+      --_max-height: var(--theme-banner-video-max-height-xl, clamp(52rem, 65vw, 90rem));
+    }
+
+    .video {
+      grid-area: media;
+      display: block;
+      width: 100%;
+      height: auto;
+      min-height: 100%;
+      align-self: var(--_align-self, center);
+      justify-self: var(--_justify-self, center);
+    }
+
+    .fallback {
+      grid-area: media;
+      display: none;
+      width: 100%;
+      height: 100%;
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+      .video {
+        display: none;
+      }
+      .fallback {
+        display: block;
+      }
+    }
+  }
+}
+</style>

package/app/components/01.atoms/banner-video/stories/BannerVideo.stories.ts

@@ -0,0 +1,180 @@
+import BannerVideo from "../BannerVideo.vue";
+import type { Meta, StoryObj } from "@nuxtjs/storybook";
+
+const meta: Meta<typeof BannerVideo> = {
+  title: "Atoms/Media/BannerVideo",
+  component: BannerVideo,
+  argTypes: {
+    src: {
+      control: "text",
+      description: "Path to the mp4 video source file",
+      table: { category: "Media" },
+    },
+    poster: {
+      control: "text",
+      description: "Path to the fallback/poster image — shown before video loads, on error, and when prefers-reduced-motion is active",
+      table: { category: "Media" },
+    },
+    alt: {
+      control: "text",
+      description: "Alt text for the fallback image",
+      table: { category: "Media" },
+    },
+    imgWidth: {
+      control: { type: "number" },
+      description: "Intrinsic width of the poster image — required for NuxtImg optimisation",
+      table: { category: "Media" },
+    },
+    imgHeight: {
+      control: { type: "number" },
+      description: "Intrinsic height of the poster image — required for NuxtImg optimisation",
+      table: { category: "Media" },
+    },
+    tag: {
+      control: "select",
+      options: ["section", "div", "header", "main", "article"],
+      description: "HTML element rendered as the root",
+      table: { category: "Markup" },
+    },
+    depth: {
+      control: "select",
+      options: ["xs", "sm", "md", "lg", "xl"],
+      description: "Responsive max-height tier. Each maps to a clamp() scale; override via --theme-banner-video-max-height-{depth}",
+      table: { category: "Layout" },
+    },
+    aspectRatio: {
+      control: "text",
+      description: "CSS aspect-ratio of the banner container (e.g. '16/9', '21/9', '4/3')",
+      table: { category: "Layout" },
+    },
+    objectFit: {
+      control: "select",
+      options: ["cover", "contain", "fill", "none", "scale-down"],
+      description: "How the video and fallback image fill the banner frame",
+      table: { category: "Appearance" },
+    },
+    verticalPosition: {
+      control: "select",
+      options: ["start", "center", "end"],
+      description: "Vertical crop position — start (top), center, or end (bottom). Maps to align-self on the video and object-position on the fallback image",
+      table: { category: "Appearance" },
+    },
+    horizontalPosition: {
+      control: "select",
+      options: ["start", "center", "end"],
+      description: "Horizontal crop position — start (left), center, or end (right). Maps to object-position on the fallback image",
+      table: { category: "Appearance" },
+    },
+    styleClassPassthrough: {
+      table: { disable: true },
+    },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "A full-width banner that plays a muted, looping mp4 video. The poster image is shown before the video loads, when the video fails to play, and whenever the user has `prefers-reduced-motion: reduce` set. The banner is sized via `aspect-ratio` with a responsive `max-height` driven by the `depth` tier (`xs` → `xl`). Each tier uses a `clamp()` scale and exposes a `--theme-banner-video-max-height-{depth}` token for consuming pages to override. `objectFit` controls how media fills the frame. `verticalPosition` and `horizontalPosition` control the crop focal point.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof BannerVideo>;
+
+export const Default: Story = {
+  args: {
+    src: "/images/banners/video/lake-banner.mp4",
+    poster: "/images/banners/video/lake-banner.jpg",
+    alt: "A serene lake landscape",
+    imgWidth: 1920,
+    imgHeight: 1080,
+    tag: "section",
+    depth: "md",
+    aspectRatio: "21/9",
+    objectFit: "cover",
+    verticalPosition: "center",
+    horizontalPosition: "center",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: "Default props. The lake video plays muted and looped at a 21/9 aspect ratio with the md depth tier (clamp 28rem → 56rem).",
+      },
+    },
+  },
+};
+
+export const Compact: Story = {
+  args: {
+    ...Default.args,
+    depth: "xs",
+    verticalPosition: "end",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: "xs depth tier (clamp 12rem → 24rem) — a thin strip banner. verticalPosition: 'end' crops to the bottom of the frame.",
+      },
+    },
+  },
+};
+
+export const Shallow: Story = {
+  args: {
+    ...Default.args,
+    depth: "sm",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: "sm depth tier (clamp 18rem → 36rem) — a shorter banner suitable for secondary sections.",
+      },
+    },
+  },
+};
+
+export const Deep: Story = {
+  args: {
+    ...Default.args,
+    depth: "lg",
+    aspectRatio: "21/9",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: "lg depth tier (clamp 40rem → 72rem) — a tall cinematic banner with more vertical presence on large screens.",
+      },
+    },
+  },
+};
+
+export const Hero: Story = {
+  args: {
+    ...Default.args,
+    depth: "xl",
+    aspectRatio: "16/9",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: "xl depth tier (clamp 52rem → 90rem) — near full-screen hero. Pair with a 16/9 ratio to maximise coverage.",
+      },
+    },
+  },
+};
+
+export const Standard169: Story = {
+  args: {
+    ...Default.args,
+    aspectRatio: "16/9",
+    depth: "md",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: "Standard 16/9 aspect ratio with md depth — matches a typical video's native ratio.",
+      },
+    },
+  },
+};