srcdev-nuxt-components 9.1.29 → 9.1.30

package/.claude/skills/components/banner-video.md

@@ -1,6 +1,6 @@
 ---
 name: BannerVideo
-description: BannerVideo full-width hero video banner — props, verticalPosition/horizontalPosition, responsive max-height, reduced-motion fallback, CSS tokens, consumer styling
+description: BannerVideo full-width hero video banner — props, depth tier system, verticalPosition/horizontalPosition, reduced-motion fallback, CSS tokens, consumer styling
 type: reference
 ---
 
@@ -10,7 +10,7 @@ type: reference
 
 `BannerVideo` renders a full-width banner section that plays a muted, looping mp4 video. A poster image is shown as fallback when the user has `prefers-reduced-motion: reduce` set — handled entirely in CSS, no JS.
 
-The banner is sized via `aspect-ratio` so it scales naturally, with `max-height` props capping height at each breakpoint.
+The banner is sized via `aspect-ratio` so it scales naturally. The `depth` prop selects a responsive `max-height` tier (`xs` → `xl`) implemented with `clamp()` — no breakpoint props needed. Each tier exposes a `--theme-banner-video-max-height-{depth}` CSS token that consuming pages can override.
 
 ### Autoplay mechanism
 
@@ -26,9 +26,7 @@ The video uses `autoplay muted loop playsinline preload="auto"` attributes on th
 | `imgWidth` | `number` | `1920` | Intrinsic width of the poster image — required for NuxtImg/IPX optimisation. |
 | `imgHeight` | `number` | `1080` | Intrinsic height of the poster image — required for NuxtImg/IPX optimisation. |
 | `tag` | `"section" \| "div" \| "header" \| "main" \| "article"` | `"section"` | HTML element rendered as the root. |
-| `maxHeight` | `string` | `"56rem"` | Maximum height at desktop (≥64em / 1024px). |
-| `maxHeightTablet` | `string` | `undefined` | Maximum height at tablet (48em–64em). Falls back to `maxHeight`. |
-| `maxHeightMobile` | `string` | `undefined` | Maximum height on mobile (<48em). Falls back through tablet → desktop. |
+| `depth` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Responsive max-height tier. Each maps to a `clamp()` scale; override via `--theme-banner-video-max-height-{depth}`. |
 | `aspectRatio` | `string` | `"21/9"` | CSS `aspect-ratio` of the container (e.g. `"16/9"`, `"21/9"`, `"4/3"`). |
 | `objectFit` | `"cover" \| "contain" \| "fill" \| "none" \| "scale-down"` | `"cover"` | How the video and fallback image fill the banner frame. |
 | `verticalPosition` | `"start" \| "center" \| "end"` | `"center"` | Vertical crop position. Maps to `align-self` on the video element and `object-position` Y on the fallback image. |
@@ -47,29 +45,23 @@ The video uses `autoplay muted loop playsinline preload="auto"` attributes on th
 
 ## Common variants
 
-### Responsive max-height per breakpoint
+### Depth tiers
 
 ```vue
-<BannerVideo
-  src="/videos/hero.mp4"
-  poster="/images/hero-poster.jpg"
-  alt="Studio interior"
-  max-height="56rem"
-  max-height-tablet="40rem"
-  max-height-mobile="24rem"
-/>
-```
+<!-- xs: clamp(12rem, 15vw, 24rem) — thin strip -->
+<BannerVideo src="…" poster="…" depth="xs" />
 
-### Tall viewport-filling banner
+<!-- sm: clamp(18rem, 22vw, 36rem) -->
+<BannerVideo src="…" poster="…" depth="sm" />
 
-```vue
-<BannerVideo
-  src="/videos/hero.mp4"
-  poster="/images/hero-poster.jpg"
-  alt="Studio interior"
-  max-height="100vh"
-  aspect-ratio="16/9"
-/>
+<!-- md (default): clamp(28rem, 38vw, 56rem) -->
+<BannerVideo src="…" poster="…" />
+
+<!-- lg: clamp(40rem, 52vw, 72rem) -->
+<BannerVideo src="…" poster="…" depth="lg" />
+
+<!-- xl: clamp(52rem, 65vw, 90rem) — near full-screen hero -->
+<BannerVideo src="…" poster="…" depth="xl" aspect-ratio="16/9" />
 ```
 
 ### Custom focal point
@@ -125,32 +117,35 @@ Always match the intrinsic dimensions of the poster file. NuxtImg uses them to a
 
 ## CSS custom properties
 
-All set from props via inline `:style` on the root element.
+Private tokens (set via `data-depth` + CSS selectors, not inline style):
+
+| Property | Default (md tier) | Controlled by |
+|---|---|---|
+| `--_max-height` | `clamp(28rem, 38vw, 56rem)` | `data-depth` selector |
+
+Inline style tokens (set from props):
 
 | Property | Default | Set by prop |
 |---|---|---|
-| `--_max-height` | `56rem` | `maxHeight` |
-| `--_max-height-tablet` | *(unset)* | `maxHeightTablet` |
-| `--_max-height-mobile` | *(unset)* | `maxHeightMobile` |
 | `--_aspect-ratio` | `21/9` | `aspectRatio` |
 | `--_align-self` | `center` | `verticalPosition` |
 | `--_justify-self` | `center` | `horizontalPosition` |
 
-**Responsive override example:**
+### Depth token defaults
 
-```css
-.my-page {
-  .banner-video {
-    --_max-height: 56rem;
+| depth | token | clamp value |
+|---|---|---|
+| `xs` | `--theme-banner-video-max-height-xs` | `clamp(12rem, 15vw, 24rem)` |
+| `sm` | `--theme-banner-video-max-height-sm` | `clamp(18rem, 22vw, 36rem)` |
+| `md` | `--theme-banner-video-max-height-md` | `clamp(28rem, 38vw, 56rem)` |
+| `lg` | `--theme-banner-video-max-height-lg` | `clamp(40rem, 52vw, 72rem)` |
+| `xl` | `--theme-banner-video-max-height-xl` | `clamp(52rem, 65vw, 90rem)` |
 
-    @media (width < 1024px) {
-      --_max-height: 40rem;
-    }
+**Override a tier in a consuming page:**
 
-    @media (width < 768px) {
-      --_max-height: 24rem;
-    }
-  }
+```css
+.my-page {
+  --theme-banner-video-max-height-md: clamp(32rem, 45vw, 64rem);
 }
 ```
 
@@ -169,11 +164,8 @@ Use an unscoped style block scoped by a page or section wrapper class. No `:deep
 ```vue
 <style>
 .my-page {
-  .banner-video {
-    @media (width < 900px) {
-      --_max-height: 36rem;
-    }
-  }
+  /* Override the md tier's clamp range for this page */
+  --theme-banner-video-max-height-md: clamp(32rem, 45vw, 64rem);
 }
 </style>
 ```

package/.claude/skills/components/grid-stack.md

@@ -0,0 +1,133 @@
+---
+name: GridStack
+description: GridStack CSS Grid z-axis stacking component — slot API, z-order rules, sizing behaviour, consumer patterns (video+overlay, image+text)
+type: reference
+---
+
+# GridStack
+
+## Overview
+
+`GridStack` stacks slot content in the z-axis using a single `grid-template-areas: "stack"` — no `position: absolute` needed. Every slot is wrapped in a `.grid-stack__layer` div sharing that grid area. The container sizes itself from the tallest layer; all layers stretch to fill that height.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tag` | `"div" \| "section" \| "article" \| "main"` | `"div"` | HTML element rendered as the root. |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root element. |
+
+## Slot API
+
+Any named slot is accepted — there are no declared slot names. Convention is `layer-1`, `layer-2`, `layer-3` etc., but any name works. The component iterates `$slots` and wraps each in a `.grid-stack__layer`.
+
+**Z-order rule: DOM order = z-order. The last slot is on top.**
+
+```vue
+<GridStack>
+  <template #layer-1><!-- base, behind everything --></template>
+  <template #layer-2><!-- middle --></template>
+  <template #layer-3><!-- on top --></template>
+</GridStack>
+```
+
+## Basic usage
+
+```vue
+<GridStack>
+  <template #layer-1>
+    <img src="/images/hero.jpg" alt="" />
+  </template>
+  <template #layer-2>
+    <div class="hero-overlay">
+      <h1>Heading over image</h1>
+    </div>
+  </template>
+</GridStack>
+```
+
+## Common patterns
+
+### Video background + overlay
+
+```vue
+<GridStack>
+  <template #layer-1>
+    <BannerVideo
+      src="/videos/hero.mp4"
+      poster="/images/hero-poster.jpg"
+      alt=""
+      depth="lg"
+    />
+  </template>
+  <template #layer-2>
+    <div class="video-overlay">
+      <h1>Content over video</h1>
+    </div>
+  </template>
+</GridStack>
+```
+
+### Decorative background + content
+
+```vue
+<GridStack tag="section">
+  <template #layer-1>
+    <div class="decorative-bg" aria-hidden="true"></div>
+  </template>
+  <template #layer-2>
+    <div class="section-content">
+      <p>Real content here</p>
+    </div>
+  </template>
+</GridStack>
+```
+
+## Sizing
+
+The container height is determined by the tallest child layer. All layers stretch to match. If layers have different intrinsic heights, the shorter ones will stretch — use `align-self` on the layer's inner content to control vertical position within the stretched space.
+
+To pin the stack to a fixed height, set it on the root from the consuming page:
+
+```css
+.my-page {
+  .grid-stack {
+    block-size: 60rem;
+  }
+}
+```
+
+## CSS classes
+
+| Class | Element |
+|---|---|
+| `.grid-stack` | Root element |
+| `.grid-stack__layer` | Wrapper div around each slot — all share `grid-area: stack` |
+
+## Consumer styling
+
+No `:deep()` needed — `@layer components` means page styles win automatically.
+
+```vue
+<style>
+.my-page {
+  .grid-stack {
+    border-radius: 1.2rem;
+    overflow: hidden; /* clips layers to rounded corners */
+  }
+
+  /* Style the overlay layer by targeting content inside it */
+  .my-overlay {
+    display: grid;
+    place-items: center;
+    pointer-events: none; /* let clicks through to the layer below */
+  }
+}
+</style>
+```
+
+## Notes
+
+- `pointer-events: none` on overlay layers (and `pointer-events: auto` on interactive children within them) is the standard pattern for overlays that shouldn't block interaction with layers behind them.
+- There is no built-in `z-index` — stacking is handled purely by DOM order. If a consumer applies `z-index` on a layer for other reasons, be aware it creates a new stacking context.
+- The slot name is used as the Vue `:key` on the layer wrapper, so slot names must be unique.

package/.claude/skills/index.md

@@ -40,6 +40,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
 ├── vue-video-autoplay.md             — autoplay on client-side navigation: use <source> child (not :src on <video>), :key, and explicit v.load()
 ├── icon-sets.md                      — icon set packages required by layer components, FOUC prevention, component→package map
 ├── robots-env-aware.md               — @nuxtjs/robots: allow crawling on prod domain only, block on preview/staging via env var
+├── new-app-scaffold.md               — scaffold a new Nuxt consumer app extending this layer (package.json, nuxt.config, app structure, CLAUDE.md)
 ├── release-notes.md                  — produce release notes as a fenced markdown block from git log
 ├── composable-whatsapp.md            — useWhatsApp: open pre-filled wa.me link from form payload; runtime config, security, usage
 ├── composable-zod-validation.md      — useZodValidation: schema-driven form validation, error binding, submit flow, API error push
@@ -64,7 +65,8 @@ Each skill is a single markdown file named `<area>-<task>.md`.
     ├── glass-panel.md          — GlassPanel props, slots, CSS token API (--glass-panel-bg/border-color/shadow/highlight), theming override
     ├── navigation-horizontal.md — NavigationHorizontal props, NavItemData type, CSS token API, import path gotcha
     ├── input-copy-core.md      — InputCopyCore: readonly copy-to-clipboard input; props, emits, slots, CSS classes, usage
-    ├── banner-video.md         — BannerVideo: full-width hero video banner, objectFit/objectPosition, responsive max-height, reduced-motion fallback, CSS tokens
+    ├── banner-video.md         — BannerVideo: full-width hero video banner, depth tier system, objectFit/objectPosition, reduced-motion fallback, CSS tokens
+    ├── grid-stack.md           — GridStack: CSS Grid z-axis stacking, slot API, z-order rules, sizing, video+overlay and image+text patterns
     ├── scroll-reveal-frame.md  — ScrollRevealFrame: generic parallax clipping frame, slot API, image grid pattern, CSS tokens, browser support
     ├── scroll-reveal-image.md  — ScrollRevealImage: single-image parallax reveal, focalX, imgWidth/imgHeight, responsive frame height
     ├── site-navigation.md      — SiteNavigation: responsive nav with auto-collapse, burger menu, decorator indicators, CSS token API

package/.claude/skills/new-app-scaffold.md

@@ -0,0 +1,301 @@
+# New App Scaffold
+
+## Overview
+
+Scaffold a new Nuxt app that extends `srcdev-nuxt-components` as a layer. Use this skill when
+a user asks to initialise or set up a new consumer app from scratch.
+
+## Prerequisites
+
+- An empty (or near-empty) git repo exists at the target path
+- The user provides: repo path, package name, production domain, fonts, and whether to include
+  `nuxt-security` + `@nuxtjs/robots`
+
+## Steps
+
+### 1. Gather details
+
+Ask for (or confirm from context):
+
+| Detail | Example |
+|---|---|
+| Repo path | `/Users/name/websites/my-app` |
+| Package name | `my-app` (used in `package.json` and `bodyAttrs.class`) |
+| Production domain | `myapp.co.uk` |
+| Fonts | `Fraunces, Manrope` — assume bunny CDN unless stated otherwise |
+| Include security modules? | yes / no (nuxt-security + @nuxtjs/robots) |
+
+Check for any existing files (`.claude/`, `README.md`, design docs) before writing — read them
+to inform the CLAUDE.md and CSS tokens.
+
+### 2. Create `package.json`
+
+```json
+{
+  "name": "{name}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "clean": "rm -rf .nuxt && rm -rf .output && rm -rf node_modules && rm ./package-lock.json",
+    "cleanupandprepare": "npx nuxi cleanup && npx nuxi prepare",
+    "reinstall": "npm install",
+    "cleaninstall": "npm run clean && npm run reinstall",
+    "build": "nuxt build",
+    "dev": "nuxt dev",
+    "generate": "nuxt generate",
+    "preview": "nuxt preview",
+    "setup:claude": "mkdir -p .claude/skills/srcdev-nuxt-components && cp -r node_modules/srcdev-nuxt-components/.claude/skills/. .claude/skills/srcdev-nuxt-components",
+    "postinstall": "NUXT_STANDALONE=true nuxt prepare && npm run setup:claude",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  },
+  "dependencies": {
+    "@iconify-json/gravity-ui": "1.2.12",
+    "@iconify-json/ic": "1.2.4",
+    "@iconify-json/lucide": "1.2.101",
+    "@iconify-json/material-symbols": "1.2.65",
+    "@iconify-json/mdi": "1.2.3",
+    "modern-normalize": "3.0.1",
+    "nuxt-security": "2.5.1"
+  },
+  "devDependencies": {
+    "@nuxt/eslint": "1.15.2",
+    "@nuxt/scripts": "0.13.2",
+    "@nuxtjs/robots": "6.0.6",
+    "eslint": "10.2.0",
+    "nuxt": "4.4.2",
+    "srcdev-nuxt-components": "{latest version}"
+  }
+}
+```
+
+> **`setup:claude` script**: `mkdir -p` is required — the destination folder won't exist on a
+> fresh clone. The trailing `/.` on the source path copies contents into the destination rather
+> than nesting a `skills` subfolder inside it.
+
+### 3. Create `nuxt.config.ts`
+
+```ts
+const PROD_HOST = "{domain}"
+const canonicalHost = process.env.NUXT_PUBLIC_CANONICAL_HOST ?? "{name}.vercel.app"
+const isProduction = canonicalHost === PROD_HOST
+
+export default defineNuxtConfig({
+  debug: false,
+  devServer: { https: false },
+  compatibilityDate: "2025-08-04",
+  runtimeConfig: {
+    public: {
+      canonicalHost,
+      colourScheme: { enabled: false },
+    },
+  },
+  extends: ["srcdev-nuxt-components"],
+  modules: ["@nuxt/eslint", "@nuxt/scripts", "nuxt-security", "@nuxtjs/robots"],
+  robots: {
+    enabled: isProduction,
+    groups: [{ userAgent: ["*"], allow: ["/"] }],
+    sitemap: [`https://${PROD_HOST}/sitemap.xml`],
+  },
+  components: [{ path: "./components", pathPrefix: false }],
+  imports: { dirs: ["./stores"] },
+  devtools: { enabled: true },
+  app: {
+    head: {
+      htmlAttrs: { lang: "en" },
+      titleTemplate: "%s - {App Title}",
+      meta: [{ charset: "utf-8" }, { name: "viewport", content: "width=device-width, initial-scale=1" }],
+      link: [{ rel: "icon", href: "/icons/favicon.png" }],
+      bodyAttrs: { class: "{name}-body" },
+    },
+    pageTransition: { name: "page", mode: "out-in" },
+    layoutTransition: { name: "layout", mode: "out-in" },
+  },
+  css: ["srcdev-nuxt-components/app/assets/styles/main.css", "./app/assets/styles/main.css"],
+  fonts: {
+    assets: { prefix: "/_fonts" },
+    families: [
+      // Add chosen fonts here — provider: "bunny" for Google Fonts via bunny CDN
+      { name: "{Font}", weights: [300, 400, 500, 600, 700], styles: ["normal", "italic"], provider: "bunny", display: "optional" },
+    ],
+  },
+  typescript: {
+    includeWorkspace: true,
+    strict: true,
+    shim: true,
+    typeCheck: false,
+    tsConfig: { compilerOptions: { types: ["srcdev-nuxt-components"] } },
+  },
+  eslint: { config: {} },
+  security: {
+    headers: {
+      contentSecurityPolicy: {
+        "default-src": ["'self'"],
+        "script-src": ["'self'", "'unsafe-inline'", "'unsafe-eval'", "https://vercel.live"],
+        "style-src": ["'self'", "'unsafe-inline'"],
+        "script-src-attr": ["'self'", "'unsafe-inline'"],
+        "img-src": ["'self'", "data:"],
+        "connect-src": ["'self'", "https://api.iconify.design", "https://vercel.live"],
+        "frame-src": ["'self'", "https://vercel.live"],
+      },
+    },
+  },
+  vite: {
+    optimizeDeps: {
+      include: ["@oddbird/css-anchor-positioning", "@vue/devtools-core", "@vue/devtools-kit", "zod"],
+    },
+  },
+})
+```
+
+### 4. Create supporting config files
+
+**`tsconfig.json`**
+```json
+{
+  "extends": "./.nuxt/tsconfig.json",
+  "compilerOptions": { "strict": true }
+}
+```
+
+**`eslint.config.mjs`**
+```js
+// @ts-check
+import withNuxt from "./.nuxt/eslint.config.mjs"
+
+export default withNuxt({
+  files: ["**/*.vue"],
+  rules: {
+    "@stylistic/max-len": "off",
+    "vue/max-len": "off",
+    "vue/max-attributes-per-line": "off",
+    "vue/singleline-html-element-content-newline": "off",
+    "vue/html-closing-bracket-newline": "off",
+    "vue/html-self-closing": [
+      "error",
+      { html: { void: "always", normal: "never", component: "always" } },
+    ],
+    "@stylistic/member-delimiter-style": [
+      "error",
+      {
+        multiline: { delimiter: "semi", requireLast: true },
+        singleline: { delimiter: "semi", requireLast: false },
+        multilineDetection: "brackets",
+      },
+    ],
+  },
+})
+```
+
+**`.prettierrc`**
+```json
+{
+  "printWidth": 120,
+  "singleQuote": false,
+  "trailingComma": "es5",
+  "bracketSpacing": true,
+  "semi": false,
+  "vueIndentScriptAndStyle": false,
+  "htmlWhitespaceSensitivity": "ignore"
+}
+```
+
+**`.nvmrc`**
+```
+node 20
+```
+
+**`.gitignore`** — include `.output`, `.nuxt`, `.nitro`, `.cache`, `node_modules`, `.env`, `.DS_Store`, `.vercel`, `storybook-static`.
+
+### 5. Create app directory structure
+
+```
+app/
+├── assets/styles/
+│   └── main.css          ← brand tokens + font vars (loads after layer CSS)
+├── layouts/
+│   └── default.vue       ← minimal shell with <slot>
+├── pages/
+│   └── index.vue         ← placeholder home page with useSeoMeta
+└── error.vue             ← 404 / 500 handler with clearError redirect
+```
+
+**`app/assets/styles/main.css`** — declare brand CSS custom properties and set font-family:
+
+```css
+:root {
+  /* Add brand colour tokens */
+  --font-display: "{Display Font}", serif;
+  --font-body: "{Body Font}", sans-serif;
+  font-family: var(--font-body);
+}
+```
+
+**`app/layouts/default.vue`** — minimal:
+
+```vue
+<template>
+  <div class="layout-default">
+    <main><slot></slot></main>
+  </div>
+</template>
+```
+
+**`app/pages/index.vue`** — placeholder with `useSeoMeta`.
+
+**`app/error.vue`** — handle `statusCode` 404 vs 500, call `clearError({ redirect: "/" })`.
+
+### 6. Create `.claude/skills/.gitkeep`
+
+Ensures `.claude/skills/` exists in the repo on a fresh clone so `setup:claude` never errors.
+
+```bash
+mkdir -p .claude/skills && touch .claude/skills/.gitkeep
+```
+
+### 7. Create `CLAUDE.md`
+
+Brief project context file at repo root:
+
+```md
+# {App Title} — Claude Guidelines
+
+This app extends the `srcdev-nuxt-components` Nuxt layer.
+
+## Layer Skills
+
+Skills are copied into `.claude/skills/srcdev-nuxt-components/` during `npm install`.
+Run `npm run setup:claude` to refresh after a layer upgrade.
+
+## Project Context
+
+- **Design system**: `.claude/design.md` (if it exists)
+- **Production domain**: {domain}
+- **Fonts**: {fonts}
+
+## Key Conventions
+
+- Follow all guidelines in the layer's `CLAUDE.md`
+- CSS custom properties for all design tokens — no hardcoded values in component styles
+- Layer CSS loads first; `app/assets/styles/main.css` overrides
+```
+
+### 8. Confirm next step for the user
+
+Tell the user to run:
+
+```bash
+npm install
+```
+
+`postinstall` will run `nuxt prepare` and copy the layer skills automatically.
+
+## Notes
+
+- If the repo contains a `.claude/design.md`, read it before writing `main.css` — use any
+  brand colours or font choices from it to seed the CSS tokens.
+- If security modules are not wanted, omit `nuxt-security` from `dependencies` and remove it
+  from `modules` and the `security` config block in `nuxt.config.ts`. Same for `@nuxtjs/robots`.
+- The `colourScheme.enabled: false` default is correct for most consumer apps — enable only if
+  the app needs light/dark switching.
+- Check the latest `srcdev-nuxt-components` version on npm before writing `package.json`.

package/README.md

@@ -56,6 +56,21 @@ To ensure skills are always up to date and `nuxt prepare` is never forgotten, co
 
 ---
 
+## Scaffolding a New App
+
+A Claude Code skill is included to scaffold a new Nuxt consumer app from scratch. It generates
+`package.json`, `nuxt.config.ts`, ESLint/Prettier config, the full `app/` directory structure,
+and a `CLAUDE.md` — all pre-wired to extend this layer correctly.
+
+**Trigger it by saying to Claude Code:**
+
+> "Scaffold a new layer consumer app. Repo: `/path/to/repo`, name: `my-app`, domain: `myapp.co.uk`, fonts: `Fraunces, Manrope`."
+
+The skill is available at `.claude/skills/new-app-scaffold.md` once copied into your project
+via `npm run setup:claude`.
+
+---
+
 ## Consumer App Configuration
 
 Configuration options for apps extending this layer. All options go in the consumer's `nuxt.config.ts` under `runtimeConfig.public` and can also be set via environment variable.