srcdev-nuxt-components 9.1.38 → 9.1.40

package/.claude/settings.json

@@ -23,7 +23,10 @@
       "Bash(npm run:*)",
       "Bash(git add:*)",
       "Bash(gh release:*)",
-      "Bash(node -e ':*)"
+      "Bash(node -e ':*)",
+      "Bash(git ls-tree *)",
+      "Bash(node -p \"require\\('./package.json'\\).version\")",
+      "Bash(git status *)"
     ],
     "additionalDirectories": []
   }

package/.claude/settings.local.json

@@ -24,7 +24,12 @@
       "Bash(git -C /Users/simoncornforth/websites/nuxt-components show 0f99d7a --stat)",
       "Bash(git -C /Users/simoncornforth/websites/nuxt-components diff app/components/parallax/SectionParallax.vue)",
       "Bash(git -C /Users/simoncornforth/websites/nuxt-components diff HEAD app/components/parallax/SectionParallax.vue)",
-      "Bash(git -C /Users/simoncornforth/websites/nuxt-components diff --cached)"
+      "Bash(git -C /Users/simoncornforth/websites/nuxt-components diff --cached)",
+      "Bash(SRCDEV_STANDALONE=true npx vitest --run app/components/02.molecules/samaritan-prompt)",
+      "Bash(SRCDEV_STANDALONE=true npx vitest --run app/composables/tests/useCancellableTimer app/components/02.molecules/samaritan-prompt/tests/SamaritanPromptMixed)",
+      "Bash(SRCDEV_STANDALONE=true npx vitest --run app/components/02.molecules/samaritan-prompt/tests/SamaritanPromptMixed)",
+      "Bash(SRCDEV_STANDALONE=true npx vitest --run app/composables/tests/useCancellableTimer)",
+      "Bash(SRCDEV_STANDALONE=true npm run test:run -- --reporter=verbose)"
     ],
     "additionalDirectories": [
       "/Users/simoncornforth/websites/nuxt-components/app/components/01.atoms/content-wrappers/content-width",

package/.claude/skills/components/carousel-flip.md

@@ -0,0 +1,188 @@
+# CarouselFlip
+
+## Overview
+
+A FLIP-animated carousel that reorders items in the DOM using CSS `order` and animates transitions with the FLIP technique (First, Last, Invert, Play). Supports swipe, keyboard navigation, and marker dots. The prev/next buttons and controls bar can be placed in several layouts via a single prop.
+
+---
+
+## Implementation guide
+
+When a dev asks to implement CarouselFlip, work through the following questions before writing any code. Each answer maps directly to a prop or CSS decision. You do not need to ask all questions at once — use context clues where the answer is obvious.
+
+### Step 1 — Data source
+
+Ask: **"Where is the carousel data coming from — a static array, an API, or a Nuxt `useFetch`?"**
+
+- **Static array**: Define `carouselDataIds` directly as a `const`.
+- **API / useFetch**: Derive `carouselDataIds` as a `computed` from the response. Gate the component with `v-if="status === 'success'"` to avoid a flash of empty slots.
+
+```vue
+<!-- API pattern -->
+const { data, status } = await useFetch<MyType>("/api/items");
+const carouselDataIds = computed(() => data.value?.items.map(i => i.id) ?? []);
+
+<CarouselFlip v-if="status === 'success'" :carousel-data-ids="carouselDataIds">
+  <template v-for="item in data.items" :key="item.id" #[item.id]>
+    <!-- slot content -->
+  </template>
+</CarouselFlip>
+```
+
+### Step 2 — Button layout
+
+Ask: **"Where should the prev/next buttons sit?"** Show these options:
+
+| Value | Visual description |
+|---|---|
+| `"sides"` | Buttons float on the left and right edges of the carousel frame, centred vertically — the classic look |
+| `"controls-flanking"` | Buttons move down into the controls row: prev · markers · next |
+| `"controls-grouped-right"` | Markers stretch left, both buttons grouped together at the far right of the controls row |
+| `"overlay"` | Buttons stay on the sides; the markers bar overlays the bottom edge of the carousel frame |
+
+Set via `:button-layout="..."`. Default is `"sides"`.
+
+### Step 3 — Show or hide the markers bar
+
+Ask: **"Do you want the dot/marker navigation bar visible?"**
+
+- **Yes** (default): omit the prop or pass `:show-controls="true"`.
+- **No**: pass `:show-controls="false"`. The element is fully removed from the DOM — no layout space, no keyboard listener.
+
+> If `showControls` is false and `buttonLayout` is `"controls-flanking"` or `"controls-grouped-right"`, the controls row collapses entirely — only the buttons remain. Recommend switching `buttonLayout` to `"sides"` or `"overlay"` in that case.
+
+### Step 4 — Edge peek (overflow)
+
+Ask: **"Should adjacent carousel items peek in from the sides?"**
+
+- **No peek** (default): `:allow-carousel-overflow="false"` — clean, contained look.
+- **Peek visible**: `:allow-carousel-overflow="true"` — items bleed slightly out of the container. Requires CSS custom properties to control how much:
+
+```css
+.my-carousel.carousel-flip {
+  --_carousel-item-track-gap: 16px;
+  --_carousel-item-edge-preview-width: 32px; /* keep at 2× track-gap */
+  --_carousel-container-max-inline-size: 900px;
+}
+```
+
+### Step 5 — Animation style
+
+Ask: **"What animation feel are you going for?"**
+
+| Prop | Effect |
+|---|---|
+| `:use-flip-animation="false"` (default) | Slides — items translate horizontally |
+| `:use-flip-animation="true"` | FLIP reorder — items swap position with a physics-aware delta animation |
+| `:use-spring-effect="true"` | Adds spring easing to FLIP transitions. Requires `var(--spring-easing)` in the theme |
+| `:transition-speed="400"` | Duration in ms. Default `200`. Recommended range: `200`–`1200` |
+
+### Step 6 — Minimal working implementation
+
+Once the above decisions are made, assemble the component:
+
+```vue
+<CarouselFlip
+  :carousel-data-ids="carouselDataIds"
+  :allow-carousel-overflow="true"
+  :transition-speed="600"
+  :use-flip-animation="true"
+  :use-spring-effect="false"
+  button-layout="sides"
+  :show-controls="true"
+  :style-class-passthrough="['my-carousel']"
+>
+  <template v-for="item in items" :key="item.id" #[item.id]>
+    <div class="my-carousel__item">
+      <!-- item content -->
+    </div>
+  </template>
+</CarouselFlip>
+```
+
+### Step 7 — Style the component
+
+Always scope overrides using `styleClassPassthrough` + a page/section wrapper class. Required tokens for a usable carousel:
+
+```css
+.my-carousel.carousel-flip {
+  --_carousel-item-track-gap: 16px;
+  --_carousel-container-max-inline-size: 900px;
+  --_carousel-item-edge-preview-width: 32px; /* 2× track-gap when overflow is on */
+
+  /* Items */
+  .item {
+    border-radius: 1.2rem;
+    overflow: hidden;
+  }
+
+  /* Markers */
+  .btn-marker {
+    width: 10px;
+    height: 10px;
+    border-radius: 100vw;
+    background: oklch(70% 0 0);
+
+    &.active { background: white; }
+  }
+
+  /* Prev/next buttons */
+  .btn-action {
+    padding: 10px;
+    background: oklch(0% 0 0 / 0.4);
+    border: none;
+    border-radius: 100vw;
+    color: white;
+  }
+}
+```
+
+---
+
+## Props reference
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `carouselDataIds` | `string[]` | `[]` | Ordered list of unique IDs — each becomes a named slot |
+| `transitionSpeed` | `number` | `200` | Animation duration in ms |
+| `allowCarouselOverflow` | `boolean` | `false` | Allows peeking items outside the container bounds |
+| `useFlipAnimation` | `boolean` | `false` | Enables FLIP reorder animation on prev/next |
+| `useSpringEffect` | `boolean` | `false` | Uses spring easing (`var(--spring-easing)`) instead of `ease` |
+| `buttonLayout` | `"sides" \| "controls-flanking" \| "controls-grouped-right" \| "overlay"` | `"sides"` | Controls placement of prev/next buttons relative to the carousel frame and controls bar |
+| `showControls` | `boolean` | `true` | Show or hide the markers/controls bar. When `false` the element is removed from the DOM; `controlsContainerRef` becomes null and its keyboard listener detaches automatically |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Classes applied to the root element |
+
+## CSS custom properties
+
+| Property | Purpose |
+|---|---|
+| `--_carousel-item-track-gap` | Gap between carousel items (default `10px`) |
+| `--_carousel-container-max-inline-size` | Max width of the visible carousel window |
+| `--_carousel-item-edge-preview-width` | How much of adjacent items to reveal (edge peek). Keep at `2× --_carousel-item-track-gap` |
+| `--_carousel-display-max-width` | Max width of the whole component inc. controls |
+
+## HTML structure
+
+```text
+section.carousel-flip               ← grid root, data-button-layout="..."
+  div.item-container                ← grid-area: carousel — flex row of items
+    div.item[data-id]               ← one per carouselDataIds entry
+  div.controls-container            ← grid-area: controls — markers bar (v-if="showControls")
+    div.markers-container
+      ul.markers-list
+        li.markers-item
+          button.btn-marker
+  div.buttons-container             ← display: contents by default (transparent to grid)
+    button.btn-action.btn-prev      ← grid-area: prev (row 1, col 1)
+    button.btn-action.btn-next      ← grid-area: next (row 1, col 3)
+```
+
+`buttons-container` uses `display: contents` so `.btn-prev`/`.btn-next` participate directly in the parent grid. In the `controls-grouped-right` variant the component sets `display: flex` on it, making it the grid child instead.
+
+## Notes
+
+- **Opacity fade-in**: The root starts at `opacity: 0` and gets `.mounted` (opacity 1) after `initialSetup()` completes. This prevents a flash of unstyled layout on mount.
+- **z-index**: `.btn-prev`/`.btn-next` have `z-index: 1` to sit above `.item-container` which uses `isolation: isolate` (carousel items are translated and can overlap the button columns).
+- **ResizeObserver**: `initialSetup()` re-runs on resize to recalculate item widths. CSS `translate` on `.item` is driven by the measured `itemWidth` via `v-bind`.
+- **Spring easing**: `useSpringEffect` switches to `var(--spring-easing)`. Make sure this custom property is defined in your theme or global CSS when enabling it.
+- **buttonLayout + showControls combo**: `"controls-flanking"` and `"controls-grouped-right"` place buttons in the controls row. If `showControls` is false that row collapses — use `"sides"` or `"overlay"` instead.

package/.claude/skills/index.md

@@ -41,6 +41,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
 ├── 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)
+├── qa-panel.md                       — collapsible dev-only panel for toggling component props live on a page (demo pages and consuming apps)
 ├── release-notes.md                  — produce release notes as a fenced markdown block from git log
 ├── composable-canonical-url.md       — useCanonicalUrl: set <link rel="canonical"> from runtimeConfig.public.canonicalHost; layout setup, node types
 ├── composable-whatsapp.md            — useWhatsApp: open pre-filled wa.me link from form payload; runtime config, security, usage
@@ -75,7 +76,8 @@ Each skill is a single markdown file named `<area>-<task>.md`.
     ├── display-qr-code.md      — DisplayQrCode: QR code SVG from a string value, colour/size/variant/radius props, currentColor default
     ├── capture-qr-code.md      — CaptureQrCode: live camera scanner, error state, visibility/route/KeepAlive lifecycle, media stream cleanup
     ├── decode-qr-code.md       — DecodeQrCode: file picker + drag-and-drop image decoder, shared results list, CSS override points
-    └── data-grid.md            — DataGrid: auto-fit responsive grid, $slots iteration, --data-grid-columns/gap tokens, semantic tag + aria
+    ├── data-grid.md            — DataGrid: auto-fit responsive grid, $slots iteration, --data-grid-columns/gap tokens, semantic tag + aria
+    └── carousel-flip.md        — CarouselFlip: FLIP-animated carousel, carouselDataIds slot API, buttonLayout variants (sides/controls-flanking/controls-grouped-right/overlay), CSS tokens
 ```
 
 ## Skill file template

package/.claude/skills/qa-panel.md

@@ -0,0 +1,231 @@
+# QA Panel
+
+## Overview
+
+A collapsible dev-only panel that lets you toggle component props live on a page — without touching the component or breaking the visual layout. Hidden in production via `import.meta.dev`. Uses a native `<details>`/`<summary>` so it takes up no space when collapsed. Useful on both demo pages in this library and on pages in consuming apps.
+
+## Structure
+
+```
+<details>            ← collapses the whole panel
+  <summary>          ← always visible: title + live status line
+  <body>             ← groups of chip buttons (and optional free-text inputs)
+```
+
+Each group controls one prop. The status `<code>` in the summary mirrors the current state so you can see it at a glance without opening the panel.
+
+## Steps
+
+### 1. Add the reactive state to `<script setup>`
+
+```ts
+// ── QA controls (dev only) ────────────────────────────────────────
+const isDev = import.meta.dev;
+
+// One ref per controllable prop
+const qaMyBoolean = ref(true);
+const qaMyNumber  = ref(400);
+const qaMyString  = ref<"a" | "b" | "c">("a");
+
+// Preset arrays for numeric/string chip groups
+const myNumberPresets = [100, 200, 400, 800, 1600];
+const myStringPresets = ["a", "b", "c"] as const;
+```
+
+### 2. Wire the refs to the component
+
+```vue
+<MyComponent
+  :my-boolean="qaMyBoolean"
+  :my-number="qaMyNumber"
+  :my-string="qaMyString"
+/>
+```
+
+### 3. Add the panel markup
+
+Place directly above (or below) the component being QA'd, outside any layout wrapper that clips content:
+
+```vue
+<!-- ── QA Panel (dev only) ───────────────────────────────── -->
+<div v-if="isDev" class="qa-panel">
+  <details class="qa-panel__details">
+    <summary class="qa-panel__summary">
+      <span class="qa-panel__title">QA — MyComponent</span>
+      <code class="qa-panel__status">
+        bool:{{ qaMyBoolean ? "on" : "off" }} · {{ qaMyNumber }}ms · {{ qaMyString }}
+      </code>
+    </summary>
+    <div class="qa-panel__body">
+
+      <!-- Boolean group -->
+      <div class="qa-panel__group">
+        <span class="qa-panel__label">My Boolean</span>
+        <div class="qa-panel__chips">
+          <button
+            v-for="opt in [true, false]"
+            :key="String(opt)"
+            class="qa-panel__chip"
+            :class="{ 'is-active': qaMyBoolean === opt }"
+            @click="qaMyBoolean = opt"
+          >{{ opt ? "on" : "off" }}</button>
+        </div>
+      </div>
+
+      <!-- Number group (preset chips) -->
+      <div class="qa-panel__group">
+        <span class="qa-panel__label">My Number</span>
+        <div class="qa-panel__chips">
+          <button
+            v-for="preset in myNumberPresets"
+            :key="preset"
+            class="qa-panel__chip"
+            :class="{ 'is-active': qaMyNumber === preset }"
+            @click="qaMyNumber = preset"
+          >{{ preset }}</button>
+        </div>
+      </div>
+
+      <!-- String union group -->
+      <div class="qa-panel__group">
+        <span class="qa-panel__label">My String</span>
+        <div class="qa-panel__chips">
+          <button
+            v-for="opt in myStringPresets"
+            :key="opt"
+            class="qa-panel__chip"
+            :class="{ 'is-active': qaMyString === opt }"
+            @click="qaMyString = opt"
+          >{{ opt }}</button>
+        </div>
+      </div>
+
+      <!-- Free-text input (for strings where presets aren't enough) -->
+      <div class="qa-panel__group">
+        <span class="qa-panel__label">Custom Value</span>
+        <input v-model="qaMyString" placeholder="e.g. 4/3" class="qa-panel__input" />
+      </div>
+
+    </div>
+  </details>
+</div>
+```
+
+### 4. Add the CSS
+
+Scope inside your page body class (e.g. `.my-page`) so styles don't bleed. The panel is always dark regardless of colour scheme — it's a dev tool, not a UI element.
+
+```css
+.my-page {
+  /* ── QA Panel ──────────────────────────────────────────────────── */
+
+  .qa-panel {
+    background: oklch(15% 0 0);
+    color: white;
+    font-size: 1.3rem;
+  }
+
+  .qa-panel__details {
+    padding: 1rem 2rem;
+  }
+
+  .qa-panel__summary {
+    cursor: pointer;
+    display: flex;
+    align-items: center;
+    gap: 1.6rem;
+    list-style: none;
+    user-select: none;
+
+    &::-webkit-details-marker { display: none; }
+  }
+
+  .qa-panel__title {
+    font-weight: 600;
+    font-size: 1.1rem;
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+  }
+
+  .qa-panel__status {
+    font-family: monospace;
+    font-size: 1.2rem;
+    background: oklch(0% 0 0 / 0.3);
+    padding: 0.2rem 0.8rem;
+    border-radius: 0.4rem;
+    user-select: text;
+    cursor: text;
+  }
+
+  .qa-panel__body {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 2.4rem;
+    padding-block: 1.2rem 0.4rem;
+  }
+
+  .qa-panel__group {
+    display: flex;
+    flex-direction: column;
+    gap: 0.6rem;
+  }
+
+  .qa-panel__label {
+    font-size: 1.1rem;
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    opacity: 0.55;
+  }
+
+  .qa-panel__chips {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.4rem;
+  }
+
+  .qa-panel__chip {
+    font-family: monospace;
+    font-size: 1.2rem;
+    color: white;
+    background: oklch(0% 0 0 / 0.25);
+    border: 1px solid oklch(100% 0 0 / 0.18);
+    padding: 0.3rem 1rem;
+    border-radius: 0.4rem;
+    cursor: pointer;
+    transition: background 0.15s;
+
+    &:hover { background: oklch(0% 0 0 / 0.4); }
+
+    &.is-active {
+      background: oklch(55% 0.18 240);
+      border-color: oklch(55% 0.18 240);
+    }
+  }
+
+  .qa-panel__input {
+    font-family: monospace;
+    font-size: 1.2rem;
+    color: white;
+    background: oklch(0% 0 0 / 0.25);
+    border: 1px solid oklch(100% 0 0 / 0.18);
+    padding: 0.3rem 1rem;
+    border-radius: 0.4rem;
+    width: 18rem;
+
+    &::placeholder { opacity: 0.45; }
+  }
+}
+```
+
+## Notes
+
+- **Production safety**: `import.meta.dev` is `false` in production builds — the entire `v-if="isDev"` block is tree-shaken. No runtime cost.
+- **Consuming apps**: The active chip color (`oklch(55% 0.18 240)`) is a neutral blue. Replace with a brand accent token if preferred: `background: var(--color-brand-accent)`.
+- **Panel placement**: Outside any `overflow: hidden` or clipping container, otherwise the panel may be clipped or push layout unexpectedly. Placing it as a direct sibling of the component row works well.
+- **Computed CSS vars**: When a prop controls a CSS custom property (e.g. max-height tiers), use a `computed` that returns a style object and bind it with `:style` on the component wrapper:
+
+  ```ts
+  const qaStyleOverrides = computed(() => ({
+    "--theme-component-max-height": qaMaxHeight.value || undefined,
+  }));
+  ```

package/.claude/skills/testing-add-unit-test.md

@@ -182,6 +182,38 @@ await nextTick();
 vi.runAllTimers();
 ```
 
+## `mountSuspended` flushes component async setup — initial state may be past the first `await`
+
+`mountSuspended` calls `flushPromises()` internally, draining all pending microtasks including `await nextTick()` calls inside the component's async functions. If a component's async lifecycle starts with `await nextTick()` (e.g. to let a CSS `v-bind` update before beginning a transition), **the component will have already executed past it by the time `mountSuspended` returns**.
+
+Assert the post-flush state, not the state before the first await:
+
+```ts
+// Component's runEffect() starts with: await nextTick(); opacity.value = 0;
+// ❌ — by the time mountSuspended returns, opacity is already 0
+const wrapper = await mountSuspended(MyComponent, { props });
+expect(wrapper.find(".content").attributes("style")).toContain("opacity: 1");
+
+// ✅ — assert the state that exists after mountSuspended's flush
+const wrapper = await mountSuspended(MyComponent, { props });
+expect(wrapper.find(".content").attributes("style")).toContain("opacity: 0");
+```
+
+## `.then().catch()` requires two microtask hops; use `.then(onFulfilled, onRejected)` for one
+
+When asserting Promise settlement with a single `await Promise.resolve()`, put both handlers in the two-argument form of `.then()`. Chaining `.then().catch()` creates an intermediate Promise that adds a second hop, so `settled` won't be `true` after only one drain:
+
+```ts
+// ❌ needs two await Promise.resolve() to settle
+promise.then(() => { settled = true; }).catch(() => { settled = true; });
+
+// ✅ settles after one await Promise.resolve()
+promise.then(
+  () => { settled = true; },
+  () => { settled = true; },
+);
+```
+
 ## Hyphenated prop attributes in tests
 
 When a component uses a hyphenated Vue prop like `:tab-index` or `:aria-label`, Vue renders it as the literal hyphenated DOM attribute. Assert with the hyphenated form — not the camelCase equivalent:

package/app/components/01.atoms/{grid-stack → grids/grid-stack}/stories/GridStack.stories.ts

@@ -1,6 +1,6 @@
 import type { Meta, StoryFn } from "@nuxtjs/storybook";
 import GridStackComponent from "../GridStack.vue";
-import BannerVideoComponent from "../../banner-video/BannerVideo.vue";
+import BannerVideoComponent from "../../../banner-video/BannerVideo.vue";
 
 interface GridStackArgs {
   tag: "div" | "section" | "article" | "main";