srcdev-nuxt-components 9.4.11 → 9.5.0

package/app/components/02.molecules/stepper-list/CONSUMER-STYLING.md

@@ -50,9 +50,34 @@ file, scoped to a page wrapper, or per-instance via `styleClassPassthrough`.
 | `--stepper-list-counter-square-border` | `transparent` | Bubble border colour |
 | `--stepper-list-counter-square-border-radius` | `0.25rem` | Bubble corner rounding |
 
+The defaults above are the component's own fallbacks. The library's default theme
+(`app/assets/styles/setup/03.theming/_default.css`) sets blue values for the colour tokens on
+`:root`, so that's what you see unless your app replaces that theme file or overrides them.
+
+> Changed 2026-09-27: the default theme set `--stepper-list-icon`, a name the component never
+> reads, so custom indicator icons fell back to `currentColor`. It now sets
+> `--stepper-list-icon-color`.
+
+Private (not public API): `--_gap`, `--_counter-size` and `--_padding-block`, plus `--_connector-top` and
+`--_connector-height`, which script measures and sets inline on each `<li>`.
+
+---
+
+## State hooks
+
+| Hook | Element | When |
+|---|---|---|
+| `.has-connectors` | root | `connected` is on (default) |
+| `.has-indicator` | `<li>` | That item has an `indicator-{n}` slot |
+| `.indicator-top`, `.indicator-center` | `<li>` | `indicator-alignment` |
+| `.indicator-disc`, `.indicator-square`, `.indicator-circle` | `<li>` | `indicator-variant` |
+
+Inner classes: `.stepper-list__indicator-counter` (auto-numbered bubble) or
+`.stepper-list__indicator-custom` (wraps a custom `indicator-{n}` slot).
+
 ---
 
-## Global theming — recommended approach
+## Global theming
 
 Create `assets/styles/setup/07.components/stepper-list.css` in the consuming app and set
 tokens on `:root`. This applies to every `StepperList` across the site.
@@ -78,7 +103,15 @@ tokens on `:root`. This applies to every `StepperList` across the site.
 
 ---
 
-## Page-scoped overrides
+## Local overrides
+
+Set the tokens above on an element you own (a page or section class, or a class added with
+`:style-class-passthrough`): they inherit down into the component. Keep the block **unlayered** (no
+`@layer` wrapper) so it beats the library's `@layer components`. If your own file uses
+`<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`.
+
+### Page or section
 
 Override tokens for a specific section by scoping them under the page or layout wrapper.
 No `:deep()` is required (component styles are unscoped).
@@ -96,9 +129,7 @@ No `:deep()` is required (component styles are unscoped).
 }
 ```
 
----
-
-## Per-instance overrides via styleClassPassthrough
+### One instance
 
 Use sparingly — prefer global or page-scoped CSS. When a single instance needs a distinct
 visual style, pass a modifier class:
@@ -125,6 +156,13 @@ visual style, pass a modifier class:
 
 ---
 
+## Class passthrough
+
+`style-class-passthrough` adds classes to the root `<ul>`/`<ol>`. Tokens set on a passthrough class
+land for the whole list. Reactive after mount.
+
+---
+
 ## Notes
 
 - `--stepper-list-counter-size` takes precedence over the `indicatorSize` prop. Use the prop
@@ -136,3 +174,4 @@ visual style, pass a modifier class:
 - All border tokens (`--stepper-list-counter-*-border`) control the **colour** only — the
   border is always `2px solid`. Override the border shorthand directly on `.stepper-list li
   .stepper-list__indicator-counter::before` if you need a different width.
+

package/app/components/02.molecules/stepper-list/StepperList.vue

@@ -46,7 +46,12 @@ const props = withDefaults(defineProps<Props>(), {
   styleClassPassthrough: () => [],
 });
 
-const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+watch(
+  () => props.styleClassPassthrough,
+  () => resetElementClasses(props.styleClassPassthrough)
+);
 
 const listEl = ref<HTMLElement | null>(null);
 let resizeObserver: ResizeObserver | null = null;
@@ -104,31 +109,6 @@ watch(
     --_padding-block: var(--stepper-list-padding-block, 1.2rem);
     --_gap: var(--stepper-list-gap, 2.2rem);
     --_counter-size: var(--stepper-list-counter-size, v-bind(indicatorSize));
-    --_counter-font-size: var(--stepper-list-counter-font-size, 1.4rem);
-    --_counter-font-weight: var(--stepper-list-counter-font-weight, 600);
-    --_connector-width: var(--stepper-list-connector-width, 0.2rem);
-
-    /* Colours */
-    --_connector-color: var(--stepper-list-connector-color, currentColor);
-    --_icon-color: var(--stepper-list-icon-color, currentColor);
-
-    /* Circle indicator */
-    --_counter-circle-background: var(--stepper-list-counter-circle-background, transparent);
-    --_counter-circle-text: var(--stepper-list-counter-circle-text, currentColor);
-    --_counter-circle-border-color: var(--stepper-list-counter-circle-border, currentColor);
-    --_counter-circle-border-radius: var(--stepper-list-counter-circle-border-radius, 100vw);
-
-    /* Disc indicator */
-    --_counter-disc-background: var(--stepper-list-counter-disc-background, transparent);
-    --_counter-disc-text: var(--stepper-list-counter-disc-text, currentColor);
-    --_counter-disc-border-color: var(--stepper-list-counter-disc-border, transparent);
-    --_counter-disc-border-radius: var(--stepper-list-counter-disc-border-radius, 100vw);
-
-    /* Square indicator */
-    --_counter-square-background: var(--stepper-list-counter-square-background, transparent);
-    --_counter-square-text: var(--stepper-list-counter-square-text, currentColor);
-    --_counter-square-border-color: var(--stepper-list-counter-square-border, transparent);
-    --_counter-square-border-radius: var(--stepper-list-counter-square-border-radius, 0.25rem);
 
     list-style: none;
     counter-reset: stepper-list;
@@ -158,29 +138,29 @@ watch(
         place-content: center;
         width: var(--_counter-size);
         height: var(--_counter-size);
-        font-size: var(--_counter-font-size);
-        font-weight: var(--_counter-font-weight);
+        font-size: var(--stepper-list-counter-font-size, 1.4rem);
+        font-weight: var(--stepper-list-counter-font-weight, 600);
       }
 
       &.indicator-circle .stepper-list__indicator-counter::before {
-        background-color: var(--_counter-circle-background);
-        color: var(--_counter-circle-text);
-        border: 2px solid var(--_counter-circle-border-color);
-        border-radius: var(--_counter-circle-border-radius);
+        background-color: var(--stepper-list-counter-circle-background, transparent);
+        color: var(--stepper-list-counter-circle-text, currentColor);
+        border: 2px solid var(--stepper-list-counter-circle-border, currentColor);
+        border-radius: var(--stepper-list-counter-circle-border-radius, 100vw);
       }
 
       &.indicator-disc .stepper-list__indicator-counter::before {
-        background-color: var(--_counter-disc-background);
-        color: var(--_counter-disc-text);
-        border: 2px solid var(--_counter-disc-border-color);
-        border-radius: var(--_counter-disc-border-radius);
+        background-color: var(--stepper-list-counter-disc-background, transparent);
+        color: var(--stepper-list-counter-disc-text, currentColor);
+        border: 2px solid var(--stepper-list-counter-disc-border, transparent);
+        border-radius: var(--stepper-list-counter-disc-border-radius, 100vw);
       }
 
       &.indicator-square .stepper-list__indicator-counter::before {
-        background-color: var(--_counter-square-background);
-        color: var(--_counter-square-text);
-        border: 2px solid var(--_counter-square-border-color);
-        border-radius: var(--_counter-square-border-radius);
+        background-color: var(--stepper-list-counter-square-background, transparent);
+        color: var(--stepper-list-counter-square-text, currentColor);
+        border: 2px solid var(--stepper-list-counter-square-border, transparent);
+        border-radius: var(--stepper-list-counter-square-border-radius, 0.25rem);
       }
 
       &.has-indicator::before {
@@ -198,7 +178,7 @@ watch(
         justify-content: center;
 
         .indicator-icon {
-          color: var(--_icon-color);
+          color: var(--stepper-list-icon-color, currentColor);
           width: var(--_counter-size) !important;
           height: var(--_counter-size) !important;
         }
@@ -216,8 +196,8 @@ watch(
     top: var(--_connector-top, calc(var(--_padding-block) + var(--_counter-size)));
     height: var(--_connector-height, auto);
     bottom: calc(-1 * var(--_padding-block));
-    width: var(--_connector-width);
-    background-color: var(--_connector-color);
+    width: var(--stepper-list-connector-width, 0.2rem);
+    background-color: var(--stepper-list-connector-color, currentColor);
   }
 }
 </style>

package/app/components/02.molecules/stepper-list/tests/StepperList.spec.ts

@@ -118,6 +118,15 @@ describe("StepperList", () => {
     expect(wrapper.classes()).toContain("class-b");
   });
 
+  it("updates classes when styleClassPassthrough changes after mount", async () => {
+    const wrapper = await mountSuspended(StepperList, {
+      props: { itemCount: 1, styleClassPassthrough: ["original"] },
+    });
+    await wrapper.setProps({ styleClassPassthrough: ["updated"] });
+    expect(wrapper.classes()).not.toContain("original");
+    expect(wrapper.classes()).toContain("updated");
+  });
+
   it("renders cleanly with no styleClassPassthrough prop", async () => {
     const wrapper = await mountSuspended(StepperList, {
       props: { itemCount: 1 },

package/app/components/{01.atoms → 02.molecules}/toast/CONSUMER-STYLING.md

@@ -25,3 +25,17 @@ with a strict priority order between them.
   --display-toast-provider-z-index: 1000000;
 }
 ```
+
+---
+
+## Local overrides
+
+The `--display-toast-z-index` and `--display-toast-provider-z-index` tokens above are only read,
+never declared on the toast, so they work from any ancestor, though a global `:root` value is usually
+what you want for a `position: fixed` overlay. Anything else is a direct property, scoped to an
+element you own (a page or section class, or a class added with `:style-class-passthrough`). Keep
+the block **unlayered** (no `@layer` wrapper) so it beats the library's `@layer components`. If your
+own file uses `<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`.
+

package/app/components/{01.atoms → 02.molecules}/toast/DisplayToast.vue

@@ -229,7 +229,6 @@ onBeforeRouteLeave(() => {
     }
 
     /* See the matching comment in DisplayToastProvider.vue — same fix, same rationale. */
-    --_z-index: var(--display-toast-z-index, 999999);
 
     display: block;
     overflow: hidden;
@@ -237,7 +236,7 @@ onBeforeRouteLeave(() => {
     margin: 0;
     opacity: 0;
 
-    z-index: var(--_z-index);
+    z-index: var(--display-toast-z-index, 999999);
 
     /* Focus styles for accessibility */
     &:focus {

package/app/components/{01.atoms → 02.molecules}/toast/DisplayToastProvider.vue

@@ -225,13 +225,12 @@ onUnmounted(() => {
        chrome, but 100 loses to any consumer's sticky header. Matches DisplayDialog's default so
        toasts also clear a modal's own overlay; the two ties on DOM/paint order if both happen to
        be visible at once, which is an acceptable edge case for a transient notification. */
-    --_z-index: var(--display-toast-provider-z-index, 999999);
 
     position: fixed;
     display: flex;
     flex-direction: column;
     gap: 8px;
-    z-index: var(--_z-index);
+    z-index: var(--display-toast-provider-z-index, 999999);
 
     inset-inline: var(--_gutter);
     margin-inline: auto;

package/app/components/{01.atoms → 02.molecules}/toast/stories/DisplayToast.stories.ts

@@ -16,7 +16,7 @@ interface ToastStoryArgs {
 }
 
 export default {
-  title: "Atoms/DisplayToast",
+  title: "Molecules/DisplayToast",
   component: StorybookComponent,
   argTypes: {
     theme: {

package/app/components/{01.atoms → 02.molecules}/toast/stories/DisplayToastProvider.stories.ts

@@ -23,7 +23,7 @@ const messages: Record<DisplayToastTheme, { title: string; description: string }
 };
 
 export default {
-  title: "Atoms/DisplayToastProvider",
+  title: "Molecules/DisplayToastProvider",
   component: DisplayToastProvider,
   argTypes: {
     position: {

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

@@ -36,6 +36,18 @@ Or scope to a single instance via `styleClassPassthrough`:
 <CarouselFlip style-class-passthrough="hero-carousel">...</CarouselFlip>
 ```
 
+---
+
+## Local overrides
+
+Set the tokens above on an element you own (a page or section class, or a class added with
+`:style-class-passthrough`): they inherit down into the component. Keep the block **unlayered** (no
+`@layer` wrapper) so it beats the library's `@layer components`. If your own file uses
+`<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`.
+
+---
+
 ## Notes
 
 - `--carousel-flip-display-max-width`/`--carousel-flip-item-max-width` previously had no declared
@@ -44,3 +56,4 @@ Or scope to a single instance via `styleClassPassthrough`:
   see the component's skill doc for detail.
 - `useFlipAnimation`/`useSpringEffect`/`transitionSpeed` control animation behaviour via props,
   not tokens — use the props rather than CSS overrides for those.
+

package/app/components/03.organisms/image-galleries/slider-gallery/CONSUMER-STYLING.md

@@ -0,0 +1,137 @@
+# SliderGallery — Consumer Styling Guide
+
+## Public token API
+
+### Frame
+
+| Token | Default | Controls |
+|---|---|---|
+| `--slider-gallery-height` | `100svh` | Gallery height (width is always `100vw`) |
+| `--slider-gallery-z-index` | `9999` | Stacking order (full-screen takeover) |
+| `--slider-gallery-accent` | `#f1683a` | Loading spinner and progress bar colour |
+| `--slider-gallery-loading-background` | `var(--page-bg)` | Loading overlay background |
+| `--slider-gallery-loading-colour` | `var(--colour-text-default)` | Loading overlay text |
+
+### Slide text
+
+| Token | Default | Controls |
+|---|---|---|
+| `--slider-gallery-text-light` | `#fff` | Text colour for `textBrightness: "light"` slides |
+| `--slider-gallery-text-dark` | `#000` | Text colour for `textBrightness: "dark"` slides |
+| `--slider-gallery-text-light-scrim` | `linear-gradient(to right, rgb(0 0 0 / 0.6), transparent 70%)` | Scrim behind `"light"` text (any `background` value) |
+| `--slider-gallery-text-dark-scrim` | `linear-gradient(to right, rgb(255 255 255 / 0.6), transparent 70%)` | Scrim behind `"dark"` text |
+| `--slider-gallery-title-font-size` | `5em` | Title and topic size |
+| `--slider-gallery-title-font-size-narrow` | `30px` | Title size below 678px container width |
+| `--slider-gallery-cta-background` | `#99999975` | See-more link background |
+| `--slider-gallery-cta-border-colour` | `#fff` | See-more link border |
+| `--slider-gallery-cta-colour` | `#fff` | See-more link text |
+
+### Thumbnails
+
+| Token | Default | Controls |
+|---|---|---|
+| `--slider-gallery-thumbnail-width` | `100px` | Thumbnail width below 1024px |
+| `--slider-gallery-thumbnail-height` | `165px` | Thumbnail height below 1024px |
+| `--slider-gallery-thumbnail-width-wide` | `150px` | Thumbnail width at 1024px+ |
+| `--slider-gallery-thumbnail-height-wide` | `220px` | Thumbnail height at 1024px+ |
+| `--slider-gallery-thumbnail-gap` | `20px` | Gap between thumbnails |
+| `--slider-gallery-thumbnail-border` | `1px solid transparent` | Thumbnail border |
+| `--slider-gallery-thumbnail-outline` | `1px solid transparent` | Thumbnail outline |
+| `--slider-gallery-thumbnail-outline-offset` | `0rem` | Gap between thumbnail and its outline |
+| `--slider-gallery-thumbnail-border-hover` | the resting border | Thumbnail border on hover |
+| `--slider-gallery-thumbnail-outline-hover` | the resting outline | Thumbnail outline on hover |
+| `--slider-gallery-thumbnail-outline-offset-hover` | the resting offset | Outline gap on hover |
+| `--slider-gallery-thumbnail-border-radius` | `20px` | Thumbnail rounding |
+| `--slider-gallery-thumbnail-overlay` | `#0004` | Tint over thumbnail images |
+
+### Arrows
+
+The row position tokens cascade upwards: `-desktop` falls back to `-tablet`, which falls back to the
+base token, so set only the sizes that differ.
+
+| Token | Default | Controls |
+|---|---|---|
+| `--slider-gallery-arrows-top` | `80%` | Row position from the top of the gallery |
+| `--slider-gallery-arrows-right` | `52%` | Row position from the right of the gallery |
+| `--slider-gallery-arrows-width` | `300px` | Row width |
+| `--slider-gallery-arrows-max-width` | `30%` | Row maximum width |
+| `--slider-gallery-arrows-{top,right,width,max-width}-tablet` | the base token | Same, at 768px+ container width |
+| `--slider-gallery-arrows-{top,right,width,max-width}-desktop` | the tablet token | Same, at 1024px+ container width |
+| `--slider-gallery-arrow-gap` | `20px` | Space between the two buttons |
+| `--slider-gallery-arrow-size` | `40px` | Button width/height |
+| `--slider-gallery-arrow-icon-size` | `24px` | Icon width/height |
+| `--slider-gallery-arrow-border-radius` | `50%` | Button rounding |
+| `--slider-gallery-arrow-background` | `#eee4` | Button background |
+| `--slider-gallery-arrow-colour` | `#fff` | Icon colour |
+| `--slider-gallery-arrow-border-width` | `0.2rem` | Button border width |
+| `--slider-gallery-arrow-border-colour` | `white` | Button border colour |
+| `--slider-gallery-arrow-outline-width` | `0.1rem` | Button outline width |
+| `--slider-gallery-arrow-outline-colour` | `transparent` | Button outline colour |
+| `--slider-gallery-arrow-transition-duration` | `0.5s` | Hover transition length |
+| `--slider-gallery-arrow-background-hover` | `#fff` | Hover background |
+| `--slider-gallery-arrow-colour-hover` | `#000` | Hover icon colour |
+| `--slider-gallery-arrow-border-width-hover` | resting border width | Hover border width |
+| `--slider-gallery-arrow-border-colour-hover` | resting border colour | Hover border colour |
+| `--slider-gallery-arrow-outline-width-hover` | resting outline width | Hover outline width |
+| `--slider-gallery-arrow-outline-colour-hover` | resting outline colour | Hover outline colour |
+| `--slider-gallery-arrow-outline-width-focus` | `2px` | Focus ring width |
+| `--slider-gallery-arrow-outline-colour-focus` | `var(--theme-ring, currentColor)` | Focus ring colour |
+| `--slider-gallery-arrow-outline-offset-focus` | `2px` | Focus ring gap |
+
+Private (not public API): `--_animation-duration` (from the `animationDuration` prop), `--_accent`,
+`--_thumbnail-width`, `--_thumbnail-height` (the resolved, breakpoint-switched sizes) and
+`--_arrow-border-*`/`--_arrow-outline-*` (resting values the hover tokens fall back to) and
+`--_arrows-top`/`-right`/`-width`/`-max-width` (the resolved, breakpoint-switched row position).
+
+> Changed 2026-09-28: the thumbnail sizing/border/radius overrides used to be private names
+> (`--_thumbnailMobileWidth`, `--_thumbnailBorderRadius`, etc.) with no public token; colours were
+> hardcoded. The arrow icon is now sized by `--slider-gallery-arrow-icon-size` (width/height), separately from the button, and the `--_translate-x` icon nudge was removed. The wide thumbnail size now also applies to the image
+> animating into the thumbnail strip, not just the strip itself.
+
+---
+
+## State hooks
+
+| Hook | When |
+|---|---|
+| `.slider-gallery.is-next` / `.is-prev` | A transition is running (controls are disabled) |
+| `.slider-gallery-item.is-prepended` | The item just moved to the front during a prev transition |
+| `.slider-gallery-loading.is-loaded`, `.slider-gallery-content.is-loaded` | First image loaded |
+| `.slider-gallery-item-content.light` / `.dark` | The slide's `textBrightness` |
+| `.slider-gallery-list .slider-gallery-item[data-text-brightness]` | Same, on the main slide (drives the scrim) |
+| `.slider-gallery-list .slider-gallery-item[data-has-text]` | The slide has overlay text (only these get the scrim) |
+| `.slider-gallery.has-text-scrim` | `textScrim` is on |
+
+Inner classes: `.slider-gallery-loading`, `.slider-gallery-spinner`, `.slider-gallery-content`,
+`.slider-gallery-list`, `.slider-gallery-item`, `.slider-gallery-item-content`,
+`.slider-gallery-author`, `.slider-gallery-title`, `.slider-gallery-topic`,
+`.slider-gallery-description`, `.slider-gallery-actions`, `.slider-gallery-cta`,
+`.slider-gallery-thumbnails`, `.slider-gallery-thumbnail-overlay`, `.slider-gallery-arrows`,
+`.slider-gallery-prev`, `.slider-gallery-next`, `.slider-gallery-arrow-icon`,
+`.slider-gallery-progress`.
+
+> Changed 2026-09-28: all renamed from bare generic names (`.list`, `.item`, `.content`, `.title`,
+> `.thumbnail`, `.arrows`, `.time`, `.loading-state`, `.galleryLoaded`, `.next`, `.prev`...).
+
+---
+
+## Motion
+
+Under `prefers-reduced-motion: reduce` auto-advance is off and every animation/transition inside
+the gallery collapses to 1ms, so manual navigation still works but jumps rather than animates.
+
+---
+
+## Local overrides
+
+Set the tokens above on an element you own (a page or section class, or a class added with
+`:style-class-passthrough`): they inherit down into the component. Keep the block **unlayered** (no
+`@layer` wrapper) so it beats the library's `@layer components`. If your own file uses
+`<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 `.slider-gallery`. Reactive after mount.