srcdev-nuxt-components 9.1.38 → 9.1.39

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/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/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";

package/app/components/carousels/CarouselFlip.vue

@@ -3,6 +3,7 @@
     ref="carouselWrapperRef"
     class="carousel-flip"
     :class="[elementClasses]"
+    :data-button-layout="buttonLayout"
     role="region"
     aria-label="Image carousel"
   >
@@ -10,84 +11,81 @@
       Item {{ currentActiveIndex + 1 }} of {{ itemCount }}
     </div>
 
-    <LayoutRow tag="div" variant="full-width" :style-class-passthrough="['mbe-20']">
+    <div
+      ref="carouselContainerRef"
+      tabindex="0"
+      class="item-container"
+      :class="{ 'allow-overflow': allowCarouselOverflow }"
+      role="group"
+      aria-label="Carousel items"
+    >
       <div
-        ref="carouselContainerRef"
-        tabindex="0"
-        class="item-container"
-        :class="{ 'allow-overflow': allowCarouselOverflow }"
-        role="group"
-        aria-label="Carousel items"
+        v-for="(item, index) in carouselDataIds"
+        :key="index"
+        ref="carouselItems"
+        class="item"
+        :class="{ loaded: carouselInitComplete && userHasInteracted }"
+        :data-id="item"
+        :aria-current="currentActiveIndex === index ? 'true' : 'false'"
       >
-        <div
-          v-for="(item, index) in carouselDataIds"
-          :key="index"
-          ref="carouselItems"
-          class="item"
-          :class="{ loaded: carouselInitComplete && userHasInteracted }"
-          :data-id="item"
-          :aria-current="currentActiveIndex === index ? 'true' : 'false'"
-        >
-          <slot :name="item"></slot>
-        </div>
+        <slot :name="item"></slot>
       </div>
-    </LayoutRow>
-
-    <LayoutRow tag="div" variant="full-width" :style-class-passthrough="['mbe-20']">
-      <div ref="controlsContainerRef" tabindex="0" class="controls-container">
-        <div class="markers-container">
-          <ul class="markers-list">
-            <li v-for="index in itemCount" :key="index" class="markers-item">
-              <button
-                class="btn-marker"
-                :class="[{ active: displayActiveIndex === index - 1 }]"
-                :aria-label="`Jump to item ${index}`"
-                @click.prevent="jumpToFrame(index - 1)"
-              ></button>
-            </li>
-          </ul>
-        </div>
-        <div class="buttons-container">
-          <button type="button" class="btn-action" aria-label="Go to previous item" @click.prevent="actionPrevious()">
-            <Icon name="ic:outline-keyboard-arrow-left" class="arrows-icon" />
-          </button>
-          <button type="button" class="btn-action" aria-label="Go to next item" @click.prevent="actionNext()">
-            <Icon name="ic:outline-keyboard-arrow-right" class="arrows-icon" />
-          </button>
-        </div>
+    </div>
+
+    <div v-if="showControls" ref="controlsContainerRef" tabindex="0" class="controls-container">
+      <div class="markers-container">
+        <ul class="markers-list">
+          <li v-for="index in itemCount" :key="index" class="markers-item">
+            <button
+              class="btn-marker"
+              :class="[{ active: displayActiveIndex === index - 1 }]"
+              :aria-label="`Jump to item ${index}`"
+              @click.prevent="jumpToFrame(index - 1)"
+            ></button>
+          </li>
+        </ul>
       </div>
-    </LayoutRow>
+    </div>
+
+    <div class="buttons-container">
+      <button
+        type="button"
+        class="btn-action btn-prev"
+        aria-label="Go to previous item"
+        @click.prevent="actionPrevious()"
+      >
+        <Icon name="ic:outline-keyboard-arrow-left" class="arrows-icon" />
+      </button>
+      <button type="button" class="btn-action btn-next" aria-label="Go to next item" @click.prevent="actionNext()">
+        <Icon name="ic:outline-keyboard-arrow-right" class="arrows-icon" />
+      </button>
+    </div>
   </section>
 </template>
 
 <script setup lang="ts">
 import { useEventListener, useResizeObserver, useSwipe } from "@vueuse/core";
 
-const props = defineProps({
-  carouselDataIds: {
-    type: Array as PropType<string[]>,
-    default: () => [],
-  },
-  styleClassPassthrough: {
-    type: [String, Array] as PropType<string | string[]>,
-    default: () => [],
-  },
-  transitionSpeed: {
-    type: Number,
-    default: 200,
-  },
-  allowCarouselOverflow: {
-    type: Boolean,
-    default: false,
-  },
-  useFlipAnimation: {
-    type: Boolean,
-    default: false,
-  },
-  useSpringEffect: {
-    type: Boolean,
-    default: false,
-  },
+interface Props {
+  carouselDataIds?: string[];
+  styleClassPassthrough?: string | string[];
+  transitionSpeed?: number;
+  allowCarouselOverflow?: boolean;
+  useFlipAnimation?: boolean;
+  useSpringEffect?: boolean;
+  buttonLayout?: "sides" | "controls-flanking" | "controls-grouped-right" | "overlay";
+  showControls?: boolean;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  carouselDataIds: () => [],
+  styleClassPassthrough: () => [],
+  transitionSpeed: 200,
+  allowCarouselOverflow: false,
+  useFlipAnimation: false,
+  useSpringEffect: false,
+  buttonLayout: "sides",
+  showControls: true,
 });
 
 const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
@@ -417,93 +415,100 @@ onMounted(() => {
 
 <style lang="css">
 @layer components {
-.carousel-flip {
-  --_carousel-item-track-gap: 10px;
-
-  display: grid;
-  grid-template-columns: 1fr;
-  gap: 10px;
-  opacity: 0;
-
-  &.mounted {
-    opacity: 1;
-  }
-
-  .sr-only {
-    position: absolute;
-    width: 1px;
-    height: 1px;
-    padding: 0;
-    margin: -1px;
-    overflow: hidden;
-    clip: rect(0, 0, 0, 0);
-    white-space: nowrap;
-    border: 0;
-  }
-
-  .item-container {
-    display: flex;
-    gap: var(--_carousel-item-track-gap);
-    overflow-x: hidden;
-    position: relative;
-    isolation: isolate;
-
-    max-inline-size: var(--_carousel-display-max-width);
-    margin-inline: auto;
+  .carousel-flip {
+    --_carousel-item-track-gap: 10px;
+
+    display: grid;
+    grid-template-columns: auto 1fr auto;
+    grid-template-rows: 1fr auto;
+    grid-template-areas:
+      "prev  carousel  next"
+      ".     controls  .   ";
+    gap: 10px;
+    opacity: 0;
+
+    &.mounted {
+      opacity: 1;
+    }
 
-    &.allow-overflow {
-      overflow-x: initial;
+    .sr-only {
+      position: absolute;
+      width: 1px;
+      height: 1px;
+      padding: 0;
+      margin: -1px;
+      overflow: hidden;
+      clip: rect(0, 0, 0, 0);
+      white-space: nowrap;
+      border: 0;
     }
 
-    .item {
+    .item-container {
+      grid-area: carousel;
       display: flex;
-      flex: 0 0 100%;
+      gap: var(--_carousel-item-track-gap);
+      overflow-x: hidden;
       position: relative;
+      isolation: isolate;
 
+      max-inline-size: var(--_carousel-display-max-width);
       margin-inline: auto;
 
-      max-inline-size: calc(
-        var(--_carousel-container-max-inline-size) + var(--_carousel-item-track-gap) -
-          (2 * var(--_carousel-item-edge-preview-width))
-      );
+      &.allow-overflow {
+        overflow-x: initial;
+      }
+
+      .item {
+        display: flex;
+        flex: 0 0 100%;
+        position: relative;
 
-      translate: calc(
-          v-bind(itemWidthOffsetStr) - var(--_carousel-item-track-gap) + var(--_carousel-item-edge-preview-width)
-        )
-        0;
+        margin-inline: auto;
 
-      &.loaded {
-        transition: transform v-bind(transitionSpeedStr) ease;
+        max-inline-size: calc(
+          var(--_carousel-container-max-inline-size) + var(--_carousel-item-track-gap) -
+            (2 * var(--_carousel-item-edge-preview-width))
+        );
+
+        translate: calc(
+            v-bind(itemWidthOffsetStr) - var(--_carousel-item-track-gap) + var(--_carousel-item-edge-preview-width)
+          )
+          0;
+
+        &.loaded {
+          transition: transform v-bind(transitionSpeedStr) ease;
+        }
       }
     }
-  }
 
-  .controls-container {
-    display: flex;
-    align-items: center;
-    justify-content: flex-end;
-    max-inline-size: var(--_carousel-display-max-width);
-    margin-inline: auto;
+    .controls-container {
+      grid-area: controls;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      max-inline-size: var(--_carousel-display-max-width);
+      margin-inline: auto;
 
-    .markers-container {
-      .markers-list {
-        display: flex;
-        flex-direction: row;
-        gap: 10px;
-        list-style-type: none;
-        margin: unset;
-        padding: unset;
-
-        .markers-item {
-          .btn-marker {
-            border: 1px solid transparent;
-            outline: 1px solid transparent;
-            box-shadow: none;
-            cursor: pointer;
-            transition: background-color v-bind(transitionSpeedStr) linear;
-
-            &.active {
-              background-color: light-dark(var(--slate-10), var(--slate-00));
+      .markers-container {
+        .markers-list {
+          display: flex;
+          flex-direction: row;
+          gap: 10px;
+          list-style-type: none;
+          margin: unset;
+          padding: unset;
+
+          .markers-item {
+            .btn-marker {
+              border: 1px solid transparent;
+              outline: 1px solid transparent;
+              box-shadow: none;
+              cursor: pointer;
+              transition: background-color v-bind(transitionSpeedStr) linear;
+
+              &.active {
+                background-color: light-dark(var(--slate-10), var(--slate-00));
+              }
             }
           }
         }
@@ -511,26 +516,79 @@ onMounted(() => {
     }
 
     .buttons-container {
+      display: contents;
+    }
+
+    .btn-prev {
+      grid-area: prev;
+      align-self: center;
+      z-index: 1;
+    }
+
+    .btn-next {
+      grid-area: next;
+      align-self: center;
+      z-index: 1;
+    }
+
+    .btn-action {
       display: flex;
       align-items: center;
-      justify-content: end;
-      gap: 20px;
+      justify-content: center;
+      cursor: pointer;
+      height: fit-content;
+
+      background-color: white;
+      border: 1px solid light-dark(hsl(0, 29%, 3%), hsl(0, 0%, 92%));
+      border-radius: 100vw;
+      padding: 8px;
+
+      .arrows-icon {
+        width: 24px;
+        height: 24px;
+      }
+    }
+
+    /* ── controls-flanking: buttons flank the controls row ─────── */
+    &[data-button-layout="controls-flanking"] {
+      .btn-prev {
+        grid-area: unset;
+        grid-column: 1;
+        grid-row: 2;
+      }
+
+      .btn-next {
+        grid-area: unset;
+        grid-column: 3;
+        grid-row: 2;
+      }
+    }
+
+    /* ── controls-grouped-right: markers centred, buttons end ────── */
+    &[data-button-layout="controls-grouped-right"] {
+      grid-template-columns: 1fr;
+      grid-template-areas:
+        "carousel"
+        "controls";
 
-      .btn-action {
+      .buttons-container {
         display: flex;
         align-items: center;
-        justify-content: center;
-
-        cursor: pointer;
-        height: fit-content;
+        gap: 10px;
+        grid-area: controls;
+        justify-self: end;
+      }
+    }
 
-        .arrows-icon {
-          width: 24px;
-          height: 24px;
-        }
+    /* ── overlay: controls float at the bottom edge of the frame ── */
+    &[data-button-layout="overlay"] {
+      .controls-container {
+        grid-area: carousel;
+        align-self: end;
+        z-index: 1;
+        padding-block-end: 1rem;
       }
     }
   }
 }
-}
 </style>

package/app/components/carousels/stories/CarouselFlip.stories.ts

@@ -16,6 +16,8 @@ interface CarouselFlipStoryArgs {
   transitionSpeed: number;
   useFlipAnimation: boolean;
   useSpringEffect: boolean;
+  buttonLayout: "sides" | "controls-flanking" | "controls-grouped-right" | "overlay";
+  showControls: boolean;
   styleClassPassthrough: string[];
   // Mock data for stories
   carouselData: CarouselItem[];
@@ -105,6 +107,21 @@ export default {
         category: "Animation",
       },
     },
+    buttonLayout: {
+      control: { type: "select" },
+      options: ["sides", "controls-flanking", "controls-grouped-right", "overlay"],
+      description: "Placement of prev/next buttons relative to the carousel and controls bar",
+      table: {
+        category: "Layout",
+      },
+    },
+    showControls: {
+      control: { type: "boolean" },
+      description: "Show or hide the markers/controls bar",
+      table: {
+        category: "Layout",
+      },
+    },
     styleClassPassthrough: {
       control: { type: "object" },
       description: "Additional CSS classes to pass through",
@@ -127,6 +144,8 @@ export default {
     transitionSpeed: 1000,
     useFlipAnimation: true,
     useSpringEffect: false,
+    buttonLayout: "sides",
+    showControls: true,
     styleClassPassthrough: ["carousel-flip-demo"],
     carouselData: sampleCarouselItems,
   },
@@ -289,6 +308,8 @@ const Template: StoryFn<CarouselFlipStoryArgs> = (args) => ({
         :transition-speed="args.transitionSpeed"
         :use-flip-animation="args.useFlipAnimation"
         :use-spring-effect="args.useSpringEffect"
+        :button-layout="args.buttonLayout"
+        :show-controls="args.showControls"
         :style-class-passthrough="args.styleClassPassthrough"
       >
         <template v-for="(item, index) in filteredCarouselData" #[item.id] :key="index">
@@ -350,6 +371,16 @@ NoOverflow.args = {
   styleClassPassthrough: ["carousel-flip-demo", "no-overflow"],
 };
 
+export const NoControls = Template.bind({});
+NoControls.args = {
+  carouselDataIds: [1, 2, 3, 4, 5],
+  transitionSpeed: 1000,
+  useFlipAnimation: true,
+  useSpringEffect: false,
+  allowCarouselOverflow: true,
+  showControls: false,
+};
+
 export const ManyItems = Template.bind({});
 ManyItems.args = {
   carouselDataIds: [1, 2, 3, 4, 5, 6, 7, 8],
@@ -452,6 +483,8 @@ const RichContentTemplate: StoryFn<CarouselFlipStoryArgs> = (args) => ({
         :transition-speed="args.transitionSpeed"
         :use-flip-animation="args.useFlipAnimation"
         :use-spring-effect="args.useSpringEffect"
+        :button-layout="args.buttonLayout"
+        :show-controls="args.showControls"
         :style-class-passthrough="args.styleClassPassthrough"
       >
         <template v-for="(item, index) in filteredCarouselData" #[item.id] :key="index">
@@ -592,6 +625,8 @@ const AnimationShowcaseTemplate: StoryFn<CarouselFlipStoryArgs> = (args) => ({
         :transition-speed="args.transitionSpeed"
         :use-flip-animation="args.useFlipAnimation"
         :use-spring-effect="args.useSpringEffect"
+        :button-layout="args.buttonLayout"
+        :show-controls="args.showControls"
         :style-class-passthrough="args.styleClassPassthrough"
       >
         <template v-for="(item, index) in filteredCarouselData" #[item.id] :key="index">

package/app/components/carousels/tests/CarouselFlip.spec.ts

@@ -232,6 +232,44 @@ describe("CarouselFlip", () => {
       expect(component).toBeDefined();
       // Spring effect is applied during transitions
     });
+
+    it("shows controls container by default", async () => {
+      await createWrapper();
+
+      expect(wrapper.find(".controls-container").exists()).toBe(true);
+      expect(wrapper.findAll(".btn-marker").length).toBe(6);
+    });
+
+    it("hides controls container when showControls is false", async () => {
+      await createWrapper({ showControls: false });
+
+      expect(wrapper.find(".controls-container").exists()).toBe(false);
+      expect(wrapper.findAll(".btn-marker").length).toBe(0);
+    });
+
+    it("still renders navigation buttons when showControls is false", async () => {
+      await createWrapper({ showControls: false });
+
+      expect(wrapper.find('[aria-label="Go to previous item"]').exists()).toBe(true);
+      expect(wrapper.find('[aria-label="Go to next item"]').exists()).toBe(true);
+    });
+
+    it("navigation still works when showControls is false", async () => {
+      await createWrapper({ showControls: false });
+      await nextTick();
+
+      const nextButton = wrapper.find('[aria-label="Go to next item"]');
+      await nextButton.trigger("click");
+      await nextTick();
+
+      expect(component.currentActiveIndex).toBe(1);
+    });
+
+    it("sets data-button-layout attribute from buttonLayout prop", async () => {
+      await createWrapper({ buttonLayout: "overlay" });
+
+      expect(wrapper.attributes("data-button-layout")).toBe("overlay");
+    });
   });
 
   describe("Initial Setup", () => {

package/app/pages/ui/carousel-flip.vue

@@ -6,24 +6,127 @@
           <h1 class="page-heading-2">Carousel</h1>
         </LayoutRow>
 
-        <LayoutRow tag="div" variant="popout" :style-class-passthrough="['mbe-20']">
-          <CarouselFlip
-            v-if="carouselStatus === 'success'"
-            :carousel-data-ids
-            :allow-carousel-overflow="true"
-            :transition-speed="1000"
-            :use-flip-animation="true"
-            :use-spring-effect="false"
-            :style-class-passthrough="['carousel-flip-demo', 'mbe-20']"
-          >
-            <template v-for="(item, index) in carouselData?.items" :key="index" #[item.id]>
-              <div class="custom-carousel-item">
-                <h3>{{ index + 1 }}</h3>
-                <p>{{ item.alt }}</p>
+        <!-- ── 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 — CarouselFlip</span>
+              <code class="qa-panel__status">
+                overflow:{{ qaAllowOverflow ? "on" : "off" }} · speed:{{ qaTransitionSpeed }}ms · flip:{{
+                  qaUseFlipAnimation ? "on" : "off"
+                }}
+                · spring:{{ qaUseSpringEffect ? "on" : "off" }} · {{ qaButtonLayout }} · controls:{{
+                  qaShowControls ? "on" : "off"
+                }}
+              </code>
+            </summary>
+            <div class="qa-panel__body">
+              <div class="qa-panel__group">
+                <span class="qa-panel__label">Allow Overflow</span>
+                <div class="qa-panel__chips">
+                  <button
+                    v-for="opt in [true, false]"
+                    :key="String(opt)"
+                    class="qa-panel__chip"
+                    :class="{ 'is-active': qaAllowOverflow === opt }"
+                    @click="qaAllowOverflow = opt"
+                  >
+                    {{ opt ? "on" : "off" }}
+                  </button>
+                </div>
               </div>
-            </template>
-          </CarouselFlip>
-        </LayoutRow>
+              <div class="qa-panel__group">
+                <span class="qa-panel__label">Transition Speed</span>
+                <div class="qa-panel__chips">
+                  <button
+                    v-for="preset in transitionSpeedPresets"
+                    :key="preset"
+                    class="qa-panel__chip"
+                    :class="{ 'is-active': qaTransitionSpeed === preset }"
+                    @click="qaTransitionSpeed = preset"
+                  >
+                    {{ preset }}ms
+                  </button>
+                </div>
+              </div>
+              <div class="qa-panel__group">
+                <span class="qa-panel__label">Flip Animation</span>
+                <div class="qa-panel__chips">
+                  <button
+                    v-for="opt in [true, false]"
+                    :key="String(opt)"
+                    class="qa-panel__chip"
+                    :class="{ 'is-active': qaUseFlipAnimation === opt }"
+                    @click="qaUseFlipAnimation = opt"
+                  >
+                    {{ opt ? "on" : "off" }}
+                  </button>
+                </div>
+              </div>
+              <div class="qa-panel__group">
+                <span class="qa-panel__label">Spring Effect</span>
+                <div class="qa-panel__chips">
+                  <button
+                    v-for="opt in [true, false]"
+                    :key="String(opt)"
+                    class="qa-panel__chip"
+                    :class="{ 'is-active': qaUseSpringEffect === opt }"
+                    @click="qaUseSpringEffect = opt"
+                  >
+                    {{ opt ? "on" : "off" }}
+                  </button>
+                </div>
+              </div>
+              <div class="qa-panel__group">
+                <span class="qa-panel__label">Button Layout</span>
+                <div class="qa-panel__chips">
+                  <button
+                    v-for="layout in buttonLayoutPresets"
+                    :key="layout"
+                    class="qa-panel__chip"
+                    :class="{ 'is-active': qaButtonLayout === layout }"
+                    @click="qaButtonLayout = layout"
+                  >
+                    {{ layout }}
+                  </button>
+                </div>
+              </div>
+              <div class="qa-panel__group">
+                <span class="qa-panel__label">Show Controls</span>
+                <div class="qa-panel__chips">
+                  <button
+                    v-for="opt in [true, false]"
+                    :key="String(opt)"
+                    class="qa-panel__chip"
+                    :class="{ 'is-active': qaShowControls === opt }"
+                    @click="qaShowControls = opt"
+                  >
+                    {{ opt ? "on" : "off" }}
+                  </button>
+                </div>
+              </div>
+            </div>
+          </details>
+        </div>
+
+        <CarouselFlip
+          v-if="carouselStatus === 'success'"
+          :carousel-data-ids
+          :allow-carousel-overflow="qaAllowOverflow"
+          :transition-speed="qaTransitionSpeed"
+          :use-flip-animation="qaUseFlipAnimation"
+          :use-spring-effect="qaUseSpringEffect"
+          :button-layout="qaButtonLayout"
+          :show-controls="qaShowControls"
+          :style-class-passthrough="['carousel-flip-demo', 'mbe-20']"
+        >
+          <template v-for="(item, index) in carouselData?.items" :key="index" #[item.id]>
+            <div class="custom-carousel-item">
+              <h3>{{ index + 1 }}</h3>
+              <p>{{ item.alt }}</p>
+            </div>
+          </template>
+        </CarouselFlip>
       </template>
     </NuxtLayout>
   </div>
@@ -32,6 +135,17 @@
 <script setup lang="ts">
 import type { ICarouselBasic } from "~/types/components";
 
+// ── QA controls (dev only) ────────────────────────────────────────
+const isDev = import.meta.dev;
+const qaAllowOverflow = ref(true);
+const qaTransitionSpeed = ref(1000);
+const qaUseFlipAnimation = ref(true);
+const qaUseSpringEffect = ref(false);
+const qaButtonLayout = ref<"sides" | "controls-flanking" | "controls-grouped-right" | "overlay">("sides");
+const qaShowControls = ref(true);
+const transitionSpeedPresets = [100, 200, 400, 600, 1000, 2000];
+const buttonLayoutPresets = ["sides", "controls-flanking", "controls-grouped-right", "overlay"] as const;
+
 definePageMeta({
   layout: false,
 });
@@ -54,6 +168,97 @@ const carouselDataIds = computed(() => {
 </script>
 
 <style lang="css">
+.carousel-flip-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);
+    }
+  }
+}
+
 @property --glow-deg {
   syntax: "<angle>";
   inherits: true;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "srcdev-nuxt-components",
   "type": "module",
-  "version": "9.1.38",
+  "version": "9.1.39",
   "main": "nuxt.config.ts",
   "types": "types.d.ts",
   "license": "MIT",