srcdev-nuxt-components 9.6.18 → 9.6.20

package/app/components/03.organisms/image-galleries/carousel-flip/CONSUMER-STYLING.md

@@ -2,6 +2,12 @@
 
 ## Public token API
 
+> Changed 2026-10-21: colour defaults come from `--theme-*` tokens (were `white`,
+> `hsl(0, 29%, 3%)` and `--slate-10`), `--carousel-flip-button-icon-colour` is new, and the
+> `--carousel-flip-focus-outline-*` tokens now style the prev/next buttons as well as the markers.
+
+### Layout
+
 | Token | Default | Controls |
 |---|---|---|
 | `--carousel-flip-gap` | `1rem` | Gap between items inside the item track |
@@ -9,34 +15,80 @@
 | `--carousel-flip-display-max-width` | `80rem` | Max width of the item track and the controls bar |
 | `--carousel-flip-item-max-width` | `80rem` | Max width of a single item, before subtracting the edge-preview width |
 | `--carousel-flip-edge-preview-width` | `4rem` | How much of the neighbouring items peek in at each edge |
-| `--carousel-flip-marker-gap` | `1rem` | Gap between marker (dot) buttons |
-| `--carousel-flip-marker-active-colour` | `var(--slate-10)` | Active marker background colour |
-| `--carousel-flip-button-background-colour` | `white` | Prev/next button background colour |
-| `--carousel-flip-button-border-width` | `0.1rem` | Prev/next button border width |
-| `--carousel-flip-button-border-colour` | `hsl(0, 29%, 3%)` | Prev/next button border colour |
-| `--carousel-flip-button-border-radius` | `100vw` | Prev/next button corner radius |
-| `--carousel-flip-button-padding` | `0.8rem` | Prev/next button padding |
-| `--carousel-flip-button-icon-size` | `2.4rem` | Prev/next button icon glyph size |
-| `--carousel-flip-buttons-gap` | `1rem` | Gap between prev/next buttons in the `controls-grouped-right` layout |
 | `--carousel-flip-overlay-controls-offset` | `1rem` | Distance of the controls bar from the bottom edge in the `overlay` layout |
-| `--carousel-flip-focus-outline-width` | `0.2rem` | Marker button focus-visible outline width |
-| `--carousel-flip-focus-outline-colour` | `var(--theme-ring)` | Marker button focus-visible outline colour |
-| `--carousel-flip-focus-outline-offset` | `0.2rem` | Marker button focus-visible outline offset |
 
-```css
-.my-page {
-  --carousel-flip-button-background-colour: var(--theme-surface);
-  --carousel-flip-marker-active-colour: var(--brand-primary);
-}
-```
+### Markers
+
+| Token | Default | Controls |
+|---|---|---|
+| `--carousel-flip-marker-gap` | `1rem` | Gap between marker (dot) buttons, in both directions (the markers wrap) |
+| `--carousel-flip-marker-active-colour` | `var(--theme-surface)` | Active marker background colour |
+
+The markers otherwise keep the browser's button styling: size and shape them on
+`.carousel-flip-marker` (see the story's `carousel-flip-demo` styles for an example).
+
+### Prev/next buttons
+
+| Token | Default | Controls |
+|---|---|---|
+| `--carousel-flip-button-icon-colour` | `var(--theme-text)` | Icon colour |
+| `--carousel-flip-button-background-colour` | `var(--theme-surface-subtle)` | Background colour |
+| `--carousel-flip-button-border-width` | `0.1rem` | Border width |
+| `--carousel-flip-button-border-colour` | `var(--theme-border)` | Border colour |
+| `--carousel-flip-button-border-radius` | `100vw` | Corner radius |
+| `--carousel-flip-button-padding` | `0.8rem` | Padding |
+| `--carousel-flip-button-icon-size` | `2.4rem` | Icon glyph size |
+| `--carousel-flip-buttons-gap` | `1rem` | Gap between the buttons in the `controls-grouped-right` layout |
+| `--carousel-flip-button-align` | `center` | Vertical alignment of each button in its row: `start`, `center` or `end` (every layout except `controls-grouped-right`, where the buttons sit in the controls row) |
+| `--carousel-flip-button-inline-offset` | `0px` | `sides` and `controls-flanking` only: pushes each button outward from its default spot (negative pulls it inward over the track). Mirrors in right-to-left |
+| `--carousel-flip-button-edge-inset` | `calc(var(--carousel-flip-edge-preview-width, 4rem) + 0.8rem)` | `track-edges` only: distance of each button from the visible track's end, so the default clears the edge preview |
+
+The buttons are `InputButton` with `variant="inline"`, which adds no colours of its own; these
+tokens style them.
 
-Or scope to a single instance via `styleClassPassthrough`:
+**Placement.** In `sides` the buttons sit at the outer edges of the component's own box, so with
+`allowCarouselOverflow` on they can land over the neighbouring items that peek out past it. Use
+`buttonLayout="track-edges"` to keep them on the active frame, or the offset token to move them.
+To reach the viewport edges from a centred carousel of known width, set
+`--carousel-flip-button-inline-offset: calc((100vw - <that width>) / 2 - 1.6rem)`. A percentage
+doesn't work there (on `translate` it resolves against the button), `vw` includes the scrollbar,
+and an offset past the viewport can cause horizontal scrolling.
 
-```vue
-<CarouselFlip style-class-passthrough="hero-carousel">...</CarouselFlip>
-```
+> Added 2026-10-21: the three placement tokens and the `track-edges` layout.
 
----
+### Focus
+
+| Token | Default | Controls |
+|---|---|---|
+| `--carousel-flip-focus-outline-width` | `0.2rem` | `:focus-visible` outline width on markers and prev/next buttons |
+| `--carousel-flip-focus-outline-colour` | `var(--theme-ring)` | `:focus-visible` outline colour |
+| `--carousel-flip-focus-outline-offset` | `0.2rem` | `:focus-visible` outline offset |
+
+Private (not public API): `--_carousel-item-track-gap`, read from `--carousel-flip-gap`, and
+`--_carousel-flip-button-direction` (`1`, or `-1` under `:dir(rtl)`).
+
+## State hooks
+
+| Hook | Meaning |
+|---|---|
+| `.carousel-flip[data-button-layout="…"]` | The `buttonLayout` prop |
+| `.carousel-flip[data-mounted]` | Setup finished; the root fades from `opacity: 0` to `1` |
+| `.carousel-flip-track[data-allow-overflow]` | `allowCarouselOverflow` is on |
+| `.carousel-flip-item[aria-current="true"]` | The active item |
+| `.carousel-flip-item[data-loaded]` | The user has navigated at least once; items get their CSS transition |
+| `.carousel-flip-marker[data-active]` | The active marker (also `aria-current="true"`) |
+
+Inner elements: `.carousel-flip-track`, `.carousel-flip-item`, `.carousel-flip-controls`,
+`.carousel-flip-markers` (the `<ul>`), `.carousel-flip-markers-item`, `.carousel-flip-marker`,
+`.carousel-flip-buttons`, `.carousel-flip-button` (with `.carousel-flip-button-prev` /
+`.carousel-flip-button-next`), `.carousel-flip-button-icon`.
+
+> Changed 2026-10-21: these were `.item-container`, `.item`, `.controls-container`,
+> `.markers-container`/`.markers-list`, `.markers-item`, `.btn-marker`, `.buttons-container`,
+> `.btn-action`/`.btn-prev`/`.btn-next` and `.arrows-icon`, with state classes `.mounted`,
+> `.allow-overflow`, `.loaded` and `.active`. The markers lost their extra wrapper div.
+
+The controls bar and the prev/next buttons only render when there are at least two items.
 
 ## Local overrides
 
@@ -46,14 +98,15 @@ Set the tokens above on an element you own (a page or section class, or a class
 `<style scoped>`, tokens set on your element still work, but selectors that reach inside the component need
 `:deep()`. Patterns and examples: `.claude/skills/component-local-style-override.md`.
 
----
+## Class passthrough
+
+`style-class-passthrough` adds classes to the root `<section>`. Reactive: changing the prop
+replaces the previous classes (until 2026-10-21 later changes were ignored).
 
 ## Notes
 
 - `--carousel-flip-display-max-width`/`--carousel-flip-item-max-width` previously had no declared
-  value anywhere in the component (referenced via `var()` with no fallback) — this meant the
-  edge-preview offset and max-width caps silently never applied in production. Fixed 2026-09-21;
-  see the component's skill doc for detail.
+  value anywhere in the component (referenced via `var()` with no fallback), so the edge-preview
+  offset and max-width caps never applied. Fixed 2026-09-21; see the component's skill doc.
 - `useFlipAnimation`/`useSpringEffect`/`transitionSpeed` control animation behaviour via props,
-  not tokens — use the props rather than CSS overrides for those.
-
+  not tokens.

package/app/components/03.organisms/image-galleries/carousel-flip/CarouselFlip.vue

@@ -4,65 +4,79 @@
     class="carousel-flip"
     :class="[elementClasses]"
     :data-button-layout="buttonLayout"
-    role="region"
+    :data-mounted="isMounted ? '' : undefined"
     :aria-label="ariaLabel"
   >
     <div aria-live="polite" aria-atomic="true" class="sr-only">
-      {{ props.itemPositionAnnouncement(currentActiveIndex + 1, itemCount) }}
+      {{ itemCount > 0 ? props.itemPositionAnnouncement(currentActiveIndex + 1, itemCount) : "" }}
     </div>
 
     <div
       ref="carouselContainerRef"
       tabindex="0"
-      class="item-container"
-      :class="{ 'allow-overflow': allowCarouselOverflow }"
+      class="carousel-flip-track"
+      :data-allow-overflow="allowCarouselOverflow ? '' : undefined"
       role="group"
       :aria-label="itemsAriaLabel"
     >
       <div
         v-for="(item, index) in carouselDataIds"
-        :key="index"
+        :key="`${index}-${item}`"
         ref="carouselItems"
-        class="item"
-        :class="{ loaded: carouselInitComplete && userHasInteracted }"
+        class="carousel-flip-item"
+        :data-loaded="carouselInitComplete && userHasInteracted ? '' : undefined"
         :data-id="item"
-        :aria-current="currentActiveIndex === index ? 'true' : 'false'"
+        :aria-current="currentActiveIndex === index ? 'true' : undefined"
       >
         <slot :name="item"></slot>
       </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
-              type="button"
-              class="btn-marker"
-              :class="[{ active: displayActiveIndex === index - 1 }]"
-              :aria-label="`${jumpToItemLabel} ${index}`"
-              @click.prevent="jumpToFrame(index - 1)"
-            ></button>
-          </li>
-        </ul>
-      </div>
+    <div v-if="showControls && itemCount > 1" ref="controlsContainerRef" class="carousel-flip-controls">
+      <ul class="carousel-flip-markers" role="list">
+        <li v-for="index in itemCount" :key="index" class="carousel-flip-markers-item">
+          <button
+            type="button"
+            class="carousel-flip-marker"
+            :data-active="displayActiveIndex === index - 1 ? '' : undefined"
+            :aria-current="displayActiveIndex === index - 1 ? 'true' : undefined"
+            :aria-label="`${jumpToItemLabel} ${index}`"
+            @click.prevent="jumpToFrame(index - 1)"
+          ></button>
+        </li>
+      </ul>
     </div>
 
-    <div class="buttons-container">
-      <button type="button" class="btn-action btn-prev" :aria-label="previousLabel" @click.prevent="actionPrevious()">
-        <slot name="prev-icon">
-          <Icon :name="prevIcon" class="arrows-icon" />
-        </slot>
-      </button>
-      <button type="button" class="btn-action btn-next" :aria-label="nextLabel" @click.prevent="actionNext()">
-        <slot name="next-icon">
-          <Icon :name="nextIcon" class="arrows-icon" />
-        </slot>
-      </button>
+    <div v-if="itemCount > 1" class="carousel-flip-buttons">
+      <InputButton
+        variant="inline"
+        class="carousel-flip-button carousel-flip-button-prev"
+        :button-text="previousLabel"
+        @click.prevent="actionPrevious()"
+      >
+        <template #iconOnly>
+          <slot name="prev-icon">
+            <Icon :name="prevIcon" class="carousel-flip-button-icon" />
+          </slot>
+        </template>
+      </InputButton>
+      <InputButton
+        variant="inline"
+        class="carousel-flip-button carousel-flip-button-next"
+        :button-text="nextLabel"
+        @click.prevent="actionNext()"
+      >
+        <template #iconOnly>
+          <slot name="next-icon">
+            <Icon :name="nextIcon" class="carousel-flip-button-icon" />
+          </slot>
+        </template>
+      </InputButton>
     </div>
   </section>
 </template>
 
+
 <script setup lang="ts">
 import { useEventListener, useResizeObserver, useSwipe } from "@vueuse/core";
 
@@ -73,7 +87,7 @@ interface Props {
   allowCarouselOverflow?: boolean;
   useFlipAnimation?: boolean;
   useSpringEffect?: boolean;
-  buttonLayout?: "sides" | "controls-flanking" | "controls-grouped-right" | "overlay";
+  buttonLayout?: "sides" | "controls-flanking" | "controls-grouped-right" | "overlay" | "track-edges";
   showControls?: boolean;
   ariaLabel?: string;
   itemsAriaLabel?: string;
@@ -104,8 +118,12 @@ const props = withDefaults(defineProps<Props>(), {
   nextIcon: "ic:outline-keyboard-arrow-right",
 });
 
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
 
-const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+watch(
+  () => props.styleClassPassthrough,
+  () => resetElementClasses(props.styleClassPassthrough)
+);
 
 const carouselWrapperRef = ref<HTMLDivElement | null>(null);
 const carouselContainerRef = ref<HTMLDivElement | null>(null);
@@ -113,14 +131,15 @@ const carouselItemsRef = useTemplateRef<HTMLDivElement[]>("carouselItems");
 const controlsContainerRef = ref<HTMLDivElement | null>(null);
 const carouselInitComplete = ref(false);
 const userHasInteracted = ref(false);
+const isMounted = ref(false);
 
 const initialItemOffset = computed(() => {
   return props.useFlipAnimation ? 1 : 2;
 });
 
 const currentIndex = ref(0);
-const itemCount = ref(props.carouselDataIds.length);
-const transitionSpeedStr = props.transitionSpeed + "ms";
+const itemCount = computed(() => props.carouselDataIds.length);
+const transitionSpeedStr = computed(() => `${props.transitionSpeed}ms`);
 
 const itemWidth = ref(0);
 const itemWidthOffsetStr = computed(() => {
@@ -176,7 +195,7 @@ function analyzeOffsets(offsets: number[]) {
 }
 
 const reorderItems = (skipAnimation: boolean = false) => {
-  if (!carouselItemsRef?.value) return;
+  if (!carouselItemsRef?.value || itemCount.value < 1) return;
 
   // Capture positions before reordering (only if we're going to animate)
   const beforeRects = skipAnimation ? [] : carouselItemsRef.value.map((item) => item.getBoundingClientRect());
@@ -274,18 +293,18 @@ const reorderItems = (skipAnimation: boolean = false) => {
           if (shouldTransition) {
             if (props.allowCarouselOverflow) {
               if (props.useFlipAnimation) {
-                transitionProperties = `transform ${transitionSpeedStr} ${timingFunction}`;
+                transitionProperties = `transform ${transitionSpeedStr.value} ${timingFunction}`;
               } else {
                 if (leftValues.minorityIndex !== index) {
-                  transitionProperties = `transform ${transitionSpeedStr} ${timingFunction}`;
+                  transitionProperties = `transform ${transitionSpeedStr.value} ${timingFunction}`;
                 }
               }
             } else {
               if (props.useFlipAnimation) {
-                transitionProperties = `transform ${transitionSpeedStr} ${timingFunction}`;
+                transitionProperties = `transform ${transitionSpeedStr.value} ${timingFunction}`;
               } else {
                 if (leftValues.minorityIndex !== index) {
-                  transitionProperties = `transform ${transitionSpeedStr} ${timingFunction}`;
+                  transitionProperties = `transform ${transitionSpeedStr.value} ${timingFunction}`;
                 }
               }
             }
@@ -315,7 +334,7 @@ const reorderItems = (skipAnimation: boolean = false) => {
 };
 
 const actionPrevious = () => {
-  if (!carouselInitComplete.value || !carouselItemsRef?.value) return;
+  if (!carouselInitComplete.value || !carouselItemsRef?.value || itemCount.value < 2) return;
 
   userHasInteracted.value = true;
 
@@ -330,7 +349,7 @@ const actionPrevious = () => {
 };
 
 const actionNext = () => {
-  if (!carouselInitComplete.value || !carouselItemsRef?.value) return;
+  if (!carouselInitComplete.value || !carouselItemsRef?.value || itemCount.value < 2) return;
 
   userHasInteracted.value = true;
 
@@ -381,11 +400,8 @@ const initialSetup = () => {
   carouselInitComplete.value = true;
   checkAndMoveLastItem();
 
-  // Add mounted class to trigger opacity transition after setup is complete
   nextTick(() => {
-    if (carouselWrapperRef.value) {
-      carouselWrapperRef.value.classList.add("mounted");
-    }
+    isMounted.value = true;
   });
 };
 
@@ -416,6 +432,14 @@ useEventListener(controlsContainerRef, "keydown", (event: KeyboardEvent) => {
   }
 });
 
+watch(
+  () => props.carouselDataIds.join("\u0000"),
+  () => {
+    if (currentActiveIndex.value >= itemCount.value) currentActiveIndex.value = 0;
+    nextTick(initialSetup);
+  }
+);
+
 useResizeObserver(carouselWrapperRef, async () => {
   initialSetup();
 });
@@ -429,9 +453,10 @@ onMounted(() => {
 @layer components {
   .carousel-flip {
     --_carousel-item-track-gap: var(--carousel-flip-gap, 1rem);
+    --_carousel-flip-button-direction: 1;
 
     display: grid;
-    grid-template-columns: auto 1fr auto;
+    grid-template-columns: auto minmax(0, 1fr) auto;
     grid-template-rows: 1fr auto;
     grid-template-areas:
       "prev  carousel  next"
@@ -439,41 +464,36 @@ onMounted(() => {
     gap: var(--carousel-flip-layout-gap, 1rem);
     opacity: 0;
 
-    &.mounted {
+    &[data-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;
+    &:dir(rtl) {
+      --_carousel-flip-button-direction: -1;
     }
 
-    .item-container {
+    .carousel-flip-track {
       grid-area: carousel;
       display: flex;
       gap: var(--_carousel-item-track-gap);
       overflow-x: hidden;
       position: relative;
       isolation: isolate;
+      min-inline-size: 0;
 
       max-inline-size: var(--carousel-flip-display-max-width, 80rem);
       margin-inline: auto;
 
-      &.allow-overflow {
+      &[data-allow-overflow] {
         overflow-x: initial;
       }
 
-      .item {
+      .carousel-flip-item {
         display: flex;
         flex: 0 0 100%;
         position: relative;
+        min-inline-size: 0;
+        overflow-wrap: anywhere;
 
         margin-inline: auto;
 
@@ -488,7 +508,7 @@ onMounted(() => {
           )
           0;
 
-        &.loaded {
+        &[data-loaded] {
           @media (prefers-reduced-motion: no-preference) {
             transition: transform v-bind(transitionSpeedStr) ease;
           }
@@ -496,90 +516,96 @@ onMounted(() => {
       }
     }
 
-    .controls-container {
+    .carousel-flip-controls {
       grid-area: controls;
       display: flex;
       align-items: center;
       justify-content: center;
+      min-inline-size: 0;
       max-inline-size: var(--carousel-flip-display-max-width, 80rem);
       margin-inline: auto;
 
-      .markers-container {
-        .markers-list {
-          display: flex;
-          flex-direction: row;
-          gap: var(--carousel-flip-marker-gap, 1rem);
-          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: var(--carousel-flip-marker-active-colour, var(--slate-10));
-              }
+      .carousel-flip-markers {
+        display: flex;
+        flex-wrap: wrap;
+        justify-content: center;
+        gap: var(--carousel-flip-marker-gap, 1rem);
+        list-style-type: none;
+        margin: unset;
+        padding: unset;
+
+        .carousel-flip-marker {
+          border: 1px solid transparent;
+          outline: 1px solid transparent;
+          box-shadow: none;
+          cursor: pointer;
+          transition: background-color v-bind(transitionSpeedStr) linear;
+
+          &[data-active] {
+            background-color: var(--carousel-flip-marker-active-colour, var(--theme-surface));
+          }
 
-              &:focus-visible {
-                outline: var(--carousel-flip-focus-outline-width, 0.2rem) solid
-                  var(--carousel-flip-focus-outline-colour, var(--theme-ring));
-                outline-offset: var(--carousel-flip-focus-outline-offset, 0.2rem);
-              }
-            }
+          &:focus-visible {
+            outline: var(--carousel-flip-focus-outline-width, 0.2rem) solid
+              var(--carousel-flip-focus-outline-colour, var(--theme-ring));
+            outline-offset: var(--carousel-flip-focus-outline-offset, 0.2rem);
           }
         }
       }
     }
 
-    .buttons-container {
+    .carousel-flip-buttons {
       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 {
+    .carousel-flip-button {
       display: flex;
       align-items: center;
       justify-content: center;
+      align-self: var(--carousel-flip-button-align, center);
+      z-index: 1;
       cursor: pointer;
       height: fit-content;
+      min-height: 0;
 
-      background-color: var(--carousel-flip-button-background-colour, white);
+      color: var(--carousel-flip-button-icon-colour, var(--theme-text));
+      background-color: var(--carousel-flip-button-background-colour, var(--theme-surface-subtle));
       border: var(--carousel-flip-button-border-width, 0.1rem) solid
-        var(--carousel-flip-button-border-colour, hsl(0, 29%, 3%));
+        var(--carousel-flip-button-border-colour, var(--theme-border));
       border-radius: var(--carousel-flip-button-border-radius, 100vw);
       padding: var(--carousel-flip-button-padding, 0.8rem);
 
-      .arrows-icon {
+      &:focus-visible {
+        outline: var(--carousel-flip-focus-outline-width, 0.2rem) solid
+          var(--carousel-flip-focus-outline-colour, var(--theme-ring));
+        outline-offset: var(--carousel-flip-focus-outline-offset, 0.2rem);
+      }
+
+      .carousel-flip-button-icon {
         width: var(--carousel-flip-button-icon-size, 2.4rem);
         height: var(--carousel-flip-button-icon-size, 2.4rem);
       }
     }
 
+    .carousel-flip-button-prev {
+      grid-area: prev;
+      translate: calc(-1 * var(--_carousel-flip-button-direction) * var(--carousel-flip-button-inline-offset, 0px)) 0;
+    }
+
+    .carousel-flip-button-next {
+      grid-area: next;
+      translate: calc(var(--_carousel-flip-button-direction) * var(--carousel-flip-button-inline-offset, 0px)) 0;
+    }
+
     /* ── controls-flanking: buttons flank the controls row ─────── */
     &[data-button-layout="controls-flanking"] {
-      .btn-prev {
+      .carousel-flip-button-prev {
         grid-area: unset;
         grid-column: 1;
         grid-row: 2;
       }
 
-      .btn-next {
+      .carousel-flip-button-next {
         grid-area: unset;
         grid-column: 3;
         grid-row: 2;
@@ -588,23 +614,59 @@ onMounted(() => {
 
     /* ── controls-grouped-right: markers centred, buttons end ────── */
     &[data-button-layout="controls-grouped-right"] {
-      grid-template-columns: 1fr;
+      grid-template-columns: minmax(0, 1fr);
       grid-template-areas:
         "carousel"
         "controls";
 
-      .buttons-container {
+      .carousel-flip-buttons {
         display: flex;
         align-items: center;
         gap: var(--carousel-flip-buttons-gap, 1rem);
         grid-area: controls;
         justify-self: end;
       }
+
+      .carousel-flip-button-prev,
+      .carousel-flip-button-next {
+        translate: none;
+      }
+    }
+
+    /* ── track-edges: buttons overlay the ends of the visible track ── */
+    &[data-button-layout="track-edges"] {
+      grid-template-columns: minmax(0, 1fr);
+      grid-template-areas:
+        "carousel"
+        "controls";
+
+      .carousel-flip-buttons {
+        grid-area: carousel;
+        display: flex;
+        justify-content: space-between;
+        inline-size: 100%;
+        max-inline-size: var(--carousel-flip-display-max-width, 80rem);
+        margin-inline: auto;
+        padding-inline: var(
+          --carousel-flip-button-edge-inset,
+          calc(var(--carousel-flip-edge-preview-width, 4rem) + 0.8rem)
+        );
+        box-sizing: border-box;
+        z-index: 1;
+        pointer-events: none;
+      }
+
+      .carousel-flip-button-prev,
+      .carousel-flip-button-next {
+        grid-area: unset;
+        translate: none;
+        pointer-events: auto;
+      }
     }
 
     /* ── overlay: controls float at the bottom edge of the frame ── */
     &[data-button-layout="overlay"] {
-      .controls-container {
+      .carousel-flip-controls {
         grid-area: carousel;
         align-self: end;
         z-index: 1;
@@ -614,3 +676,4 @@ onMounted(() => {
   }
 }
 </style>
+