srcdev-nuxt-components 9.6.12 → 9.6.14

package/app/components/01.atoms/banner-video/CONSUMER-STYLING.md

@@ -14,7 +14,10 @@ file, scoped to a page wrapper, or per-instance via `styleClassPassthrough`.
 | `--banner-video-max-height-md` | `clamp(28rem, 38vw, 56rem)` | Max height at `depth="md"` (default) |
 | `--banner-video-max-height-lg` | `clamp(40rem, 52vw, 72rem)` | Max height at `depth="lg"` |
 | `--banner-video-max-height-xl` | `clamp(52rem, 65vw, 90rem)` | Max height at `depth="xl"` |
-| `--banner-video-max-height` | `clamp(28rem, 38vw, 56rem)` | Fallback used if the active depth tier's own token isn't set |
+| `--banner-video-max-height` | `clamp(28rem, 38vw, 56rem)` | Only reached if the root has no valid `data-depth`; every typed `depth` value has its own token above |
+
+Only the active tier's token matters: `depth="lg"` reads `--banner-video-max-height-lg` and nothing
+else. The `vw` values in the defaults track the viewport, not the banner's container.
 
 ### Pause/play toggle button
 
@@ -23,14 +26,41 @@ file, scoped to a page wrapper, or per-instance via `styleClassPassthrough`.
 | `--banner-video-toggle-size` | `3.2rem` | Width and height of the toggle button |
 | `--banner-video-toggle-offset` | `1.2rem` | Margin from the bottom-right corner of the banner |
 | `--banner-video-toggle-background` | `oklch(0% 0 0 / 0.4)` | Button background |
-| `--banner-video-toggle-background-hover` | `oklch(0% 0 0 / 0.6)` | Button background on hover/focus |
-| `--banner-video-toggle-icon-color` | `white` | Icon colour (and any text colour, via `color`) |
+| `--banner-video-toggle-background-hover` | `oklch(0% 0 0 / 0.6)` | Button background on hover and keyboard focus |
+| `--banner-video-toggle-icon-color` | `white` | Icon colour (and slot text colour, via `color`) |
+| `--banner-video-toggle-focus-outline-width` | `2px` | Focus ring width |
+| `--banner-video-toggle-focus-outline-color` | `currentColor` (the icon colour) | Focus ring colour |
+| `--banner-video-toggle-focus-outline-offset` | `2px` | Focus ring offset |
+
+The toggle defaults are a dark scrim with a white icon rather than `--theme-*` colours: they sit
+over video, whose colours the theme doesn't know.
+
+Private tokens (not public API): `--_max-height` (the active depth tier's value), and
+`--_aspect-ratio`, `--_align-self`, `--_justify-self`, set inline from the `aspectRatio`,
+`verticalPosition` and `horizontalPosition` props.
+
+## State hooks
+
+| Hook | Meaning |
+|---|---|
+| `[data-depth="xs" \| "sm" \| "md" \| "lg" \| "xl"]` | The active depth tier, on the root |
+
+| Class | Element |
+|---|---|
+| `.banner-video` | Root (tag from the `tag` prop) |
+| `.banner-video-media` | The `<video>` |
+| `.banner-video-fallback` | The poster `NuxtImg`, shown only under `prefers-reduced-motion: reduce` |
+| `.banner-video-toggle` | The pause/play `InputButton` (also carries `.input-button`); hidden under reduced motion |
 
----
+> **Changed 2026-10-18**: `.video` → `.banner-video-media`, `.fallback` → `.banner-video-fallback`
+> and `.banner-video__toggle` → `.banner-video-toggle`, so they can't collide with consumer CSS.
+> The toggle is now an icon-only `InputButton`: its label is visually hidden text
+> (`.input-button-text.sr-only`, from `playLabel`/`pauseLabel`) instead of an `aria-label`. Token
+> names are unchanged.
 
-## Icon and content overrides — props and slots, not CSS
+## Icon and label overrides: props and slots, not CSS
 
-The toggle's icon is prop-driven, not hardcoded:
+The toggle's icon is prop-driven:
 
 ```vue
 <BannerVideo
@@ -41,9 +71,9 @@ The toggle's icon is prop-driven, not hardcoded:
 />
 ```
 
-For anything beyond swapping the icon name (e.g. a custom SVG, or an icon set the `Icon`
-component doesn't cover), replace it with the `toggle-icon` scoped slot, which receives
-`isPlaying`:
+For anything beyond swapping the icon name (a custom SVG, or an icon set the `Icon` component
+doesn't cover), use the `toggle-icon` scoped slot, which receives `isPlaying`. Slot content is
+clipped to the round button, so size it to `--banner-video-toggle-size`:
 
 ```vue
 <BannerVideo src="/videos/hero.mp4" poster="/images/hero-poster.jpg">
@@ -53,16 +83,13 @@ component doesn't cover), replace it with the `toggle-icon` scoped slot, which r
 </BannerVideo>
 ```
 
----
+The button's accessible name comes from `play-label`/`pause-label` (defaults "Play background
+video" / "Pause background video"); pass translated strings from your own i18n.
 
 ## Global theming
 
-Create `assets/styles/setup/07.components/banner-video.css` in the consuming app and set
-tokens on `:root`. This applies to every `BannerVideo` across the site.
-
 ```css
-/* assets/styles/setup/07.components/banner-video.css */
-:root {
+:where(html) {
   --banner-video-max-height-md: clamp(32rem, 45vw, 64rem);
   --banner-video-toggle-background: var(--brand-overlay);
   --banner-video-toggle-background-hover: var(--brand-overlay-strong);
@@ -70,8 +97,6 @@ tokens on `:root`. This applies to every `BannerVideo` across the site.
 }
 ```
 
----
-
 ## Local overrides
 
 Set the tokens above on an element you own (a page or section class, or a class added with
@@ -82,46 +107,40 @@ Set the tokens above on an element you own (a page or section class, or a class
 
 ### Page or section
 
-Override tokens for a specific banner by scoping them under the page or layout wrapper.
-No `:deep()` is required (component styles are unscoped).
-
 ```css
-/* In the consuming page's unscoped <style> block */
 .homepage-hero {
-  .banner-video {
-    --banner-video-max-height-xl: 80rem;
-    --banner-video-toggle-size: 4rem;
-    --banner-video-toggle-offset: 2rem;
-  }
+  --banner-video-max-height-xl: 80rem;
+  --banner-video-toggle-size: 4rem;
+  --banner-video-toggle-offset: 2rem;
 }
 ```
 
 ### One instance
 
-Use sparingly — prefer global or page-scoped CSS. When a single instance needs a distinct
-visual style, pass a modifier class:
-
 ```vue
 <BannerVideo :style-class-passthrough="['quiet-toggle']" src="…" poster="…" />
 ```
 
 ```css
-.banner-video.quiet-toggle {
+.quiet-toggle {
   --banner-video-toggle-background: transparent;
   --banner-video-toggle-background-hover: oklch(0% 0 0 / 0.3);
 }
 ```
 
----
+## Class passthrough
 
-## Notes
+`:style-class-passthrough` (string or string array) adds classes to the root `.banner-video`
+element only, never to the video, image or toggle. Use it for per-instance token overrides or
+layout utilities (`full-bleed`, `mbe-0`).
 
-- `--banner-video-max-height` (no suffix) only applies if the active `data-depth` tier's own
-  token isn't set — in practice this only matters if you delete a depth tier's token without
-  replacing it. Prefer setting the specific `-{depth}` token you need.
-- The toggle button's `border-radius` (`100vw`, i.e. a full circle) and `transition-duration`
-  (`0.2s`) are not tokenized — they're low-variance visual details rather than something
-  consuming apps are expected to reskin per-brand.
-- `aspectRatio`, `objectFit`, `verticalPosition`, and `horizontalPosition` are props, not
-  tokens — set them directly on the component.
+## Notes
 
+- The toggle button's `border-radius` (`100vw`, a full circle) and transition (`0.2s`) are not
+  tokenized: low-variance details rather than something consuming apps reskin per brand.
+- `aspectRatio`, `objectFit`, `verticalPosition` and `horizontalPosition` are props, not tokens.
+  An invalid `aspectRatio` (empty, zero, negative, not a number or `w/h` ratio) falls back to
+  `21/9`.
+- Once the viewport is wide enough, the depth tier's `max-height` wins over `aspect-ratio`, so
+  changing `aspectRatio` can look like a no-op on desktop. Raise the active tier's token to let the
+  ratio dominate.

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

@@ -1,5 +1,8 @@
+import { ref } from "vue";
 import BannerVideo from "../BannerVideo.vue";
+import CanvasSwitcher from "../../canvas-switcher/CanvasSwitcher.vue";
 import type { Meta, StoryObj } from "@nuxtjs/storybook";
+import type { MediaCanvas } from "~/types/components";
 
 const meta: Meta<typeof BannerVideo> = {
   title: "Atoms/Media/BannerVideo",
@@ -75,15 +78,43 @@ const meta: Meta<typeof BannerVideo> = {
       description: "Icon name for the toggle button once playback starts (any Iconify icon)",
       table: { category: "Appearance" },
     },
+    playLabel: {
+      control: "text",
+      description: "Toggle button label while paused (visually hidden, its accessible name). Override for localisation",
+      table: { category: "Content" },
+    },
+    pauseLabel: {
+      control: "text",
+      description: "Toggle button label while playing (visually hidden, its accessible name). Override for localisation",
+      table: { category: "Content" },
+    },
     styleClassPassthrough: {
       table: { disable: true },
     },
   },
+  decorators: [
+    // The banner is 100% of its container wide and takes its height from aspect-ratio, so a constrained wrapper stands in for a narrower viewport.
+    (story, context) => ({
+      components: { story, CanvasSwitcher },
+      setup() {
+        const canvasName = ref<MediaCanvas>(context.parameters.initialCanvas ?? "fullWidthCanvas");
+        return { canvasName };
+      },
+      template: `
+        <div style="padding: 1.2rem 1.6rem; border-block-end: 1px solid currentColor;">
+          <CanvasSwitcher v-model:canvas-name="canvasName" />
+        </div>
+        <div :class="canvasName" style="margin-inline: auto; outline: 1px dashed currentColor;">
+          <story />
+        </div>
+      `,
+    }),
+  ],
   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 `--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. The pause/play toggle's icon is configurable via `playIcon`/`pauseIcon` props, or fully replaceable via the `toggle-icon` scoped slot.",
+          "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 `--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. The pause/play toggle (WCAG 2.2.2) is an icon-only `InputButton`: its icon is configurable via `playIcon`/`pauseIcon`, or fully replaceable via the `toggle-icon` scoped slot, and its visually hidden label comes from `playLabel`/`pauseLabel`. An invalid `aspectRatio` (empty, zero, negative, not a number or `w/h` ratio) falls back to `21/9`.",
       },
     },
   },
@@ -229,3 +260,59 @@ export const CustomToggleIconSlot: Story = {
     },
   },
 };
+
+export const StressTest: Story = {
+  name: "Stress Test (Worst-Case Data)",
+  args: {
+    ...Default.args,
+    src: "https://example.invalid/missing-video.mp4",
+    alt: "Bevorzugtekontaktmethodefürrückfragenundterminvereinbarungen 😀 <b>not bold</b> طريقة الاتصال المفضلة",
+    playLabel: "Hintergrundvideoabspielenundweiterlaufenlassen 😀 <b>not bold</b>",
+    pauseLabel: "Hintergrundvideoanhaltenundstehenlassen",
+  },
+  render: (args) => ({
+    components: { BannerVideo },
+    setup() {
+      const lake = Default.args!;
+      return { args, lake };
+    },
+    template: `
+      <div style="display: grid; gap: 2.4rem; font-size: 1.4rem;">
+        <p style="margin: 0;">Broken video URL, long unbroken localised labels with emoji and HTML-like text, and an alt with right-to-left text. The video never loads, so its poster shows instead.</p>
+        <BannerVideo v-bind="args"></BannerVideo>
+
+        <p style="margin: 0;">Broken video and broken poster URLs: an empty frame at the banner's size, the toggle still in its corner.</p>
+        <BannerVideo
+          src="https://example.invalid/missing-video.mp4"
+          poster="https://example.invalid/missing-poster.jpg"
+          :alt="args.alt"
+          depth="sm"
+        ></BannerVideo>
+
+        <p style="margin: 0;">Invalid <code>aspectRatio</code> values (<code>"abc"</code>, <code>"0"</code>, <code>"-16/9"</code>, <code>""</code>): each falls back to <code>21/9</code> instead of collapsing to the video's intrinsic size.</p>
+        <BannerVideo v-for="ratio in ['abc', '0', '-16/9', '']" :key="ratio" v-bind="lake" :aspect-ratio="ratio" depth="xs"></BannerVideo>
+
+        <p style="margin: 0;">Extreme ratios: a <code>10/1</code> sliver and a <code>1/3</code> portrait (capped by the depth tier's max-height).</p>
+        <BannerVideo v-bind="lake" aspect-ratio="10/1"></BannerVideo>
+        <BannerVideo v-bind="lake" aspect-ratio="1/3" depth="xs"></BannerVideo>
+
+        <p style="margin: 0;">Oversized <code>toggle-icon</code> slot content: clipped to the round button, never spilling over the video.</p>
+        <BannerVideo v-bind="lake" depth="xs">
+          <template #toggle-icon="{ isPlaying }">
+            <span style="font-size: 1.4rem;">{{ isPlaying ? 'Anhaltenundstehenlassen' : 'Abspielenundweiterlaufen' }}</span>
+          </template>
+        </BannerVideo>
+      </div>
+    `,
+  }),
+  parameters: {
+    initialCanvas: "mobileCanvas",
+    docs: {
+      story: { inline: false, height: "1600px" },
+      description: {
+        story:
+          "Worst-case data across nine banners. Check at every canvas width: a broken video falls back to its poster, a broken poster leaves an empty frame of the right size (not a 300x150 default box), invalid aspect ratios fall back to 21/9, the toggle stays in the bottom-right corner at every size, oversized slot content is clipped to the button, and the long labels never show on screen (they're the button's visually hidden accessible name: inspect `.input-button-text`). Under `prefers-reduced-motion: reduce` every banner shows its poster image instead, and a broken poster then shows its alt text.",
+      },
+    },
+  },
+};