srcdev-nuxt-components 9.1.28 → 9.1.29

package/.claude/skills/theming-partial-override.md

@@ -0,0 +1,131 @@
+# Partial Token Override in a Consuming App
+
+## Overview
+
+Use this skill when you need to override a specific category of tokens (e.g. form inputs, buttons,
+colours) without replacing the entire default theme. The full token reference is in
+`CONSUMER-STYLING.md` at the root of the layer package.
+
+## How it works
+
+All library tokens are declared inside `@layer theming`. Any CSS written outside a layer wins
+automatically — no `!important` or specificity tricks required. Override files just need to be
+imported **after** the layer styles.
+
+## Steps
+
+### 1. Create your override file
+
+Create a CSS file for the category you want to override. Place it anywhere in your app's assets —
+`app/assets/styles/` is conventional.
+
+**Example: form input overrides**
+
+```css
+/* app/assets/styles/form-overrides.css */
+:root {
+  --theme-input-surface: oklch(0.98 0.005 250);
+  --theme-input-border: oklch(0.45 0.08 270);
+  --theme-input-border-focus: oklch(0.55 0.18 280);
+  --theme-input-outline-focus: oklch(0.55 0.18 280);
+  --theme-focus-visible-shadow: 0 0 0 2px oklch(0.80 0.12 280);
+  --theme-input-placeholder: oklch(0.60 0.02 255);
+  --theme-input-text-color-normal: oklch(0.20 0.02 255);
+}
+```
+
+**Example: add a red colour scale and remap accent tokens**
+
+```css
+/* app/assets/styles/red-palette.css */
+:root {
+  /* Red scale — 00 (lightest) to 10 (darkest) */
+  --red-00: oklch(0.99 0.005 20);
+  --red-01: oklch(0.96 0.020 20);
+  --red-02: oklch(0.90 0.055 20);
+  --red-03: oklch(0.82 0.105 20);
+  --red-04: oklch(0.72 0.155 20);
+  --red-05: oklch(0.62 0.185 20);
+  --red-06: oklch(0.53 0.185 20);
+  --red-07: oklch(0.44 0.165 20);
+  --red-08: oklch(0.36 0.140 20);
+  --red-09: oklch(0.28 0.110 20);
+  --red-10: oklch(0.20 0.080 20);
+
+  /* Remap semantic accent tokens to red */
+  --colour-text-accent: var(--red-08);
+  --colour-text-eyebrow: var(--red-08);
+  --colour-link-default: var(--red-09);
+  --colour-link-hover: var(--red-08);
+}
+```
+
+**Example: button overrides only**
+
+```css
+/* app/assets/styles/button-overrides.css */
+:root {
+  --theme-button-primary-surface: oklch(0.55 0.20 280);
+  --theme-button-primary-surface-hover: oklch(0.48 0.22 280);
+  --theme-button-primary-surface-active: oklch(0.42 0.22 280);
+  --theme-button-primary-text: oklch(1 0 0);
+  --theme-button-primary-text-hover: oklch(1 0 0);
+}
+```
+
+### 2. Register it in nuxt.config.ts
+
+Import your override file **after** the layer styles:
+
+```ts
+export default defineNuxtConfig({
+  extends: "srcdev-nuxt-components",
+  css: [
+    "~/assets/styles/form-overrides.css",   // or whichever file(s) you created
+  ],
+});
+```
+
+The layer's own CSS loads via the `extends` mechanism before app CSS, so your unlayered overrides
+always win.
+
+### 3. Dark mode (optional)
+
+If you need dark mode variants of your overrides, add them in the same file using the `html.dark`
+class selector:
+
+```css
+:root {
+  --theme-input-surface: oklch(0.98 0.005 250);
+}
+
+:where(html.dark) {
+  --theme-input-surface: oklch(0.15 0.02 255);
+}
+```
+
+## Scoped overrides (section or component level)
+
+To restrict an override to a specific section of the page, scope to a wrapper class instead of
+`:root`:
+
+```css
+.pricing-section {
+  --theme-button-primary-surface: oklch(0.55 0.20 140);  /* green for pricing CTA */
+}
+```
+
+## Token reference
+
+See `CONSUMER-STYLING.md` in the layer package for the full list of available tokens, grouped
+by category (typography, colours, form inputs, buttons, checkboxes, toggle, glass panel,
+StepperList).
+
+## Notes
+
+- Only override the tokens you actually need — unset tokens fall back to layer defaults.
+- Use oklch for all colour values. Use an oklch colour picker (e.g. oklch.com) to build scales.
+- For a full palette replacement (replacing the entire default theme), use
+  `theming-override-default.md` instead.
+- `--slate-*` neutral tokens come from the layer and do not need to be redefined unless you
+  genuinely want different neutrals.

package/.claude/skills/vue-video-autoplay.md

@@ -0,0 +1,74 @@
+# Vue Video Autoplay on Client-Side Navigation
+
+## Overview
+
+In Vue/Nuxt SPAs, binding `:src` directly on a `<video>` element silently skips the browser fetch when Vue patches the element during client-side navigation. The video appears but never loads — no network request is made. Use a `<source>` child element instead, combined with `:key` and an explicit `load()` call.
+
+## The problem
+
+When Vue patches an existing `<video>` DOM element (e.g. on route change), setting `src` via `:src` doesn't always trigger the browser to re-fetch the media resource. This fails silently — no console error, no network request, poster image just sits there.
+
+## The fix
+
+```vue
+<!-- ✅ Correct — src in <source> child -->
+<video
+  :key="src"
+  autoplay
+  muted
+  loop
+  playsinline
+  preload="auto"
+  :poster="poster"
+>
+  <source :src="src" type="video/mp4" />
+</video>
+
+<!-- ❌ Wrong — :src on <video> silently skips fetch on Vue patches -->
+<video autoplay muted loop playsinline preload="auto" :src="src"></video>
+```
+
+## Three things working together
+
+1. **`<source>` child** — the browser re-reads source children when `load()` is called, reliably initiating the fetch.
+2. **`:key="src"`** — forces Vue to unmount/remount the `<video>` element when the source changes (covers same-component src swaps).
+3. **Explicit `v.load()` call** — programmatically re-initiates fetching after mount and on src change. Do not rely on `autoplay` alone for client-side navigation.
+
+## Autoplay pattern for Nuxt components
+
+```ts
+const videoEl = shallowRef<HTMLVideoElement | null>(null);
+
+const tryPlay = async () => {
+  const v = videoEl.value;
+  if (!v) return;
+  v.muted = true; // required for programmatic autoplay in all browsers
+  try {
+    await v.play();
+  } catch {
+    // autoplay blocked — poster remains visible
+  }
+};
+
+const kickOffLoad = async () => {
+  await nextTick();
+  const v = videoEl.value;
+  if (!v) return;
+  v.load();
+  void tryPlay();
+};
+
+// Covers initial mount and src prop changes
+watch(() => props.src, () => void kickOffLoad(), { immediate: true, flush: "post" });
+
+// Covers keep-alive re-activation
+onActivated(() => void kickOffLoad());
+```
+
+Attach `@loadeddata="() => void tryPlay()"` and `@canplay="() => void tryPlay()"` to the `<video>` element as additional retry points once data arrives.
+
+## Notes
+
+- `preload="auto"` tells the browser to buffer eagerly — essential for autoplay reliability.
+- `v.muted = true` set programmatically (in addition to the `muted` attribute) works around a Safari bug where the attribute alone is insufficient for programmatic play.
+- This pattern applies to any Vue/Nuxt video component, not just background/ambient video.

package/README.md

@@ -8,7 +8,7 @@
 
 Althought this repo is public and feel free to do what you wish with it, this has been developed for use with websites we develop.
 
-## Install Nuxt Forms layer
+## Install Nuxt Components layer
 
 ```bash
 npm install --save srcdev-nuxt-components
@@ -17,10 +17,7 @@ npm install --save srcdev-nuxt-components
 ```ts
 defineNuxtConfig({
   extends: "srcdev-nuxt-components",
-  css: [
-    "srcdev-nuxt-components/app/assets/styles/main.css",
-    "./app/assets/styles/main.css",
-  ],
+  css: ["srcdev-nuxt-components/app/assets/styles/main.css", "./app/assets/styles/main.css"],
 });
 ```
 
@@ -44,6 +41,19 @@ npm run setup:claude
 
 Skills are copied into `.claude/skills/srcdev-nuxt-components/` so they never conflict with or overwrite skills your own project defines. Re-running the script after a package update is safe.
 
+### Automate with postinstall (recommended)
+
+To ensure skills are always up to date and `nuxt prepare` is never forgotten, combine both into a `postinstall` script. npm runs this automatically after every `npm install`:
+
+```json
+"scripts": {
+  "setup:claude": "cp -r node_modules/srcdev-nuxt-components/.claude/skills .claude/skills/srcdev-nuxt-components",
+  "postinstall": "nuxt prepare && npm run setup:claude"
+}
+```
+
+> If your app uses a standalone env flag for `nuxt prepare` (e.g. `NUXT_STANDALONE=true`), include it in the `postinstall` command. This is project-specific — check your own `nuxt.config.ts` to confirm whether it is needed.
+
 ---
 
 ## Consumer App Configuration

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

@@ -0,0 +1,201 @@
+<template>
+  <component
+    :is="tag"
+    class="banner-video"
+    :class="elementClasses"
+    :style="{
+      '--_max-height': maxHeight,
+      '--_max-height-tablet': maxHeightTablet,
+      '--_max-height-mobile': maxHeightMobile,
+      '--_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;
+  /** Maximum height at desktop (≥64em). Defaults to `"56rem"`. */
+  maxHeight?: string;
+  /** Maximum height at tablet (48em–64em). Falls back to `maxHeight` when unset. */
+  maxHeightTablet?: string;
+  /** Maximum height on mobile (<48em). Falls back to `maxHeightTablet` then `maxHeight` when unset. */
+  maxHeightMobile?: string;
+  /**
+   * 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: "section",
+  alt: "",
+  imgWidth: 1920,
+  imgHeight: 1080,
+  maxHeight: "56rem",
+  maxHeightTablet: undefined,
+  maxHeightMobile: undefined,
+  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 {
+    display: grid;
+    grid-template-areas: "media";
+    aspect-ratio: var(--_aspect-ratio, 16/9);
+    max-height: var(--_max-height-mobile, var(--_max-height, 56rem));
+    width: 100%;
+    overflow: hidden;
+
+    @media (min-width: 48em) {
+      max-height: var(--_max-height-tablet, var(--_max-height, 56rem));
+    }
+
+    @media (min-width: 64em) {
+      max-height: var(--_max-height, 56rem);
+    }
+
+    .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,191 @@
+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" },
+    },
+    maxHeight: {
+      control: "text",
+      description: "Maximum height at desktop (≥64em). Defaults to 56rem",
+      table: { category: "Layout" },
+    },
+    maxHeightTablet: {
+      control: "text",
+      description: "Maximum height at tablet (48em–64em). Falls back to maxHeight when unset",
+      table: { category: "Layout" },
+    },
+    maxHeightMobile: {
+      control: "text",
+      description: "Maximum height on mobile (<48em). Falls back through tablet → desktop when unset",
+      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 per-breakpoint `max-height` caps — no fixed pixel heights. `objectFit` controls how media fills the frame. `verticalPosition` and `horizontalPosition` control the crop focal point — the video uses CSS grid alignment (`align-self`/`justify-self`) while the fallback image uses `object-position`.",
+      },
+    },
+  },
+};
+
+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",
+    maxHeight: "56rem",
+    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, capped at 56rem on desktop.",
+      },
+    },
+  },
+};
+
+export const Widescreen: Story = {
+  args: {
+    ...Default.args,
+    aspectRatio: "21/9",
+    maxHeight: "80rem",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: "A wider cinematic crop with a raised maxHeight, giving the banner more vertical presence on large screens.",
+      },
+    },
+  },
+};
+
+export const Standard169: Story = {
+  args: {
+    ...Default.args,
+    aspectRatio: "16/9",
+    maxHeight: "56rem",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: "Standard 16/9 aspect ratio — matches a typical video's native ratio, so objectPosition has minimal visible effect unless the frame is very narrow.",
+      },
+    },
+  },
+};
+
+export const ShortBanner: Story = {
+  args: {
+    ...Default.args,
+    maxHeight: "32rem",
+    verticalPosition: "end",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: "A shallower banner capped at 32rem. verticalPosition: 'end' shifts the crop to show the bottom of the frame.",
+      },
+    },
+  },
+};
+
+export const FullViewportHeight: Story = {
+  args: {
+    ...Default.args,
+    maxHeight: "100vh",
+    aspectRatio: "16/9",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: "maxHeight set to 100vh — the banner fills the full viewport height on large screens and aspect-ratio controls height on smaller ones.",
+      },
+    },
+  },
+};
+
+export const ResponsiveBreakpoints: Story = {
+  args: {
+    ...Default.args,
+    maxHeight: "56rem",
+    maxHeightTablet: "40rem",
+    maxHeightMobile: "24rem",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: "Per-breakpoint max-height: 56rem desktop, 40rem tablet (≥48em), 24rem mobile (<48em). Resize the viewport to see each cap take effect.",
+      },
+    },
+  },
+};