@vectoriox/iox-ui 5.83.1 → 5.85.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "5.83.1",
+  "version": "5.85.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",

package/scene-core/index.d.ts

@@ -70,8 +70,19 @@ interface SceneFrame {
 declare enum SceneAttribute {
     Root = "data-iox-scene",
     Tracks = "data-iox-tracks",
-    PhoneTracks = "data-iox-tracks-phone"
+    PhoneTracks = "data-iox-tracks-phone",
+    /** A root's stage that is not a Scene's `scene.stage` part: the slider a scroll plays (premium M4). */
+    Stage = "data-iox-scene-stage"
 }
+/**
+ * A SLIDER THE SCROLL PLAYS (premium components M4 — M1.3's held gallery). Its progress rests on each picture and changes
+ * only over the middle share of each step, so every picture arrives and stays a moment while the page holds it: `p` is
+ * the scroll's progress through the runway (0–1), `n` the slides; the answer is Swiper's progress (0–1).
+ */
+declare const SLIDER_HOLD_SHARE = 0.2;
+/** Page px of scroll per picture, as a share of the screen's height (the runway the renderers reserve). */
+declare const SLIDER_SCROLL_STEP_SCREENS = 0.55;
+declare function heldProgress(p: number, n: number): number;
 /** At or under this stage width a layer plays its phone tracks. The `mobile` breakpoint's width. */
 declare const SCENE_PHONE_MAX_WIDTH = 767;
 /**
@@ -287,6 +298,11 @@ declare function buildSceneRecipe(create: CompositeNodeFactory, words?: Partial<
  * - Reads come first in a frame and writes after, and a write only ever touches compositor properties.
  */
 declare const SCENE_DAMPING = 9;
+/**
+ * Dispatched (bubbling) by something the driver plays that arrived after the driver last looked — a Swiper booted on a
+ * slider's stage. Never a DOM `scroll`: nothing that follows the driver may dispatch one (SC2).
+ */
+declare const SCENE_WAKE_EVENT = "iox-scene-wake";
 /** One frame of the damping: frame-rate independent, so 60 Hz and 120 Hz settle in the same time. */
 declare function dampToward(current: number, target: number, seconds: number, rate?: number): number;
 /** Where a root stands: scrolled `local` page px into its `travel`. `zoom` undoes the canvas's scale. */
@@ -321,9 +337,12 @@ declare class ScrollDriver {
     private frame;
     private lastTime;
     private readonly wakeUp;
+    private readonly onWakeEvent;
     constructor(options?: ScrollDriverOptions);
-    /** Drive a Scene's root. Idempotent: adding a root again re-reads it. */
-    add(root: HTMLElement): void;
+    /** Drive a Scene's root. Idempotent: adding a root again re-reads it. False when another driver holds it. */
+    add(root: HTMLElement): boolean;
+    /** True when this driver holds `root`. */
+    holds(root: HTMLElement): boolean;
     remove(root: HTMLElement): void;
     /** Read a root's layers again now, keeping where it stands: an editor changed their tracks. */
     reread(root: HTMLElement): void;
@@ -366,6 +385,15 @@ declare class ScrollDriver {
 /** A page's Scenes, driven by one driver; null when it holds none, or when the visitor asked for less motion (the
  *  page's own CSS then lets each Scene flow). The live site's door. */
 declare function attachScenes(container: HTMLElement, options?: ScrollDriverOptions): ScrollDriver | null;
+/**
+ * The Scene roots that belong to `elements` (each, and what it holds) — what one runtime instance owns: the page's nodes,
+ * or the globals'. Never a whole container that also holds another instance's Scenes (premium M4: the globals' instance
+ * scanned the app root and drove the page's Scenes a second time).
+ */
+declare function sceneRootsIn(elements: Iterable<Element>): HTMLElement[];
+/** The live site's door for a runtime that owns some nodes: their Scenes on one driver (null when none, or under reduced
+ *  motion — the page's own CSS then lets each Scene flow). A root another driver holds stays with it. */
+declare function attachSceneRoots(roots: ReadonlyArray<HTMLElement>, options?: ScrollDriverOptions): ScrollDriver | null;
 
 /**
  * Text into pieces, in the browser only (premium sites SC3, Motion v2 §3c). A saved node keeps its plain text and the
@@ -416,5 +444,5 @@ declare function revealStagger(groups: number, by: TextRevealBy): number;
  */
 declare function playTextReveal(el: HTMLElement, by: TextRevealBy, timing: KeyframeAnimationOptions): Animation | null;
 
-export { LIGHT_UP_PIECE_CAP, REVEAL_PIECE_CAP, SCENE_BUDGET, SCENE_DAMPING, SCENE_FILM_SMOOTH, SCENE_FLOW_RULES, SCENE_LENGTH, SCENE_MAX_SCREENS, SCENE_MIN_SCREENS, SCENE_PHONE_LENGTH, SCENE_PHONE_MAX_WIDTH, SCENE_REDUCED_MOTION_CSS, SCENE_REVEAL_DEFAULT, SCENE_STAGE_HEIGHT, SCENE_TRACK_DEFS, SCENE_WORDS, SCENE_WORD_DIM, SceneAttribute, SceneProp, SceneRevealFrom, ScrollDriver, TextRevealBy, applySceneFirstFrame, attachScenes, buildSceneRecipe, colourAt, dampToward, lineIndexes, movedSceneKey, normalizeTracks, playTextReveal, revealClipPath, revealStagger, sceneBudget, sceneColourKeyAt, sceneDisplayValue, sceneFilmDensity, sceneFirstFrame, sceneFrame, sceneFrameDeclarations, sceneHasKeyAt, sceneHeightForScreens, sceneKeyPosition, sceneLayersOf, sceneNodeAttributes, scenePlayed, sceneRevealFromOf, sceneRootOnPath, sceneScreensOf, sceneScrollState, sceneTrackDef, sceneTrackSpan, sceneWordOpacity, sceneWordsLit, scenesIn, splitText, syncSceneAttributes, textPieces, valueAt, withSceneKey, withScenePlayback, withSceneRevealFrom, withoutSceneKey, withoutScenePlayback };
+export { LIGHT_UP_PIECE_CAP, REVEAL_PIECE_CAP, SCENE_BUDGET, SCENE_DAMPING, SCENE_FILM_SMOOTH, SCENE_FLOW_RULES, SCENE_LENGTH, SCENE_MAX_SCREENS, SCENE_MIN_SCREENS, SCENE_PHONE_LENGTH, SCENE_PHONE_MAX_WIDTH, SCENE_REDUCED_MOTION_CSS, SCENE_REVEAL_DEFAULT, SCENE_STAGE_HEIGHT, SCENE_TRACK_DEFS, SCENE_WAKE_EVENT, SCENE_WORDS, SCENE_WORD_DIM, SLIDER_HOLD_SHARE, SLIDER_SCROLL_STEP_SCREENS, SceneAttribute, SceneProp, SceneRevealFrom, ScrollDriver, TextRevealBy, applySceneFirstFrame, attachSceneRoots, attachScenes, buildSceneRecipe, colourAt, dampToward, heldProgress, lineIndexes, movedSceneKey, normalizeTracks, playTextReveal, revealClipPath, revealStagger, sceneBudget, sceneColourKeyAt, sceneDisplayValue, sceneFilmDensity, sceneFirstFrame, sceneFrame, sceneFrameDeclarations, sceneHasKeyAt, sceneHeightForScreens, sceneKeyPosition, sceneLayersOf, sceneNodeAttributes, scenePlayed, sceneRevealFromOf, sceneRootOnPath, sceneRootsIn, sceneScreensOf, sceneScrollState, sceneTrackDef, sceneTrackSpan, sceneWordOpacity, sceneWordsLit, scenesIn, splitText, syncSceneAttributes, textPieces, valueAt, withSceneKey, withScenePlayback, withSceneRevealFrom, withoutSceneKey, withoutScenePlayback };
 export type { SceneBudget, SceneFilmDensity, SceneFrame, SceneFrameOptions, SceneFrameState, SceneKey, SceneLayerNode, SceneNodeSource, SceneTrack, SceneTrackDef, SceneTreeNode, SceneWords, ScrollDriverOptions, SplitText, SplitTextOptions, TextPiece };

package/src/actions-core/dialog-motion.ts

@@ -103,3 +103,28 @@ export function closeDialogAnimated(el: DialogElementLike, options: ExitMotionOp
 export function dialogTogglesClosed(el: Pick<DialogElementLike, 'open' | 'hasAttribute'>): boolean {
     return el.open && !el.hasAttribute(DIALOG_CLOSING_ATTRIBUTE);
 }
+
+/** The element-style marker a styled dialog carries (design-core ELEMENT_STYLE_MARKER_CLASS — actions-core does not
+ *  import design-core). */
+const STYLED_DIALOG_CLASS = 'iox-es';
+
+export interface FocusableSheet {
+    classList: { contains(token: string): boolean };
+    querySelector(selector: string): unknown;
+    hasAttribute(name: string): boolean;
+    setAttribute(name: string, value: string): void;
+    focus(options?: FocusOptions): void;
+}
+
+/**
+ * A styled dialog a visitor just opened takes focus on its SHEET (premium components M4 — M1.1's carry-over). A bare
+ * `showModal()` focuses its first control, and a phone can ring it after a tap; the sheet never rings (iox-design.css) and
+ * the first Tab moves to that control, with its ring. A dialog with an author's `[autofocus]` keeps it; a dialog saved
+ * before element styles keeps the browser's behaviour. True when the sheet took focus.
+ */
+export function focusDialogSheet(dialog: FocusableSheet | null | undefined): boolean {
+    if (!dialog || !dialog.classList.contains(STYLED_DIALOG_CLASS) || dialog.querySelector('[autofocus]')) return false;
+    if (!dialog.hasAttribute('tabindex')) dialog.setAttribute('tabindex', '-1');
+    dialog.focus({ preventScroll: true });
+    return true;
+}

package/src/composite-core/header.ts

@@ -0,0 +1,25 @@
+import { HeaderBehaviour, HeaderEdge, headerBehaviourOf, headerEdgeOf, headerStaysAtTop, HeaderTrait } from '@vectoriox/iox-ui/design-core';
+
+import { CompositeNode, readProp, readStyle, writeProp, writeStyles } from './composite-node';
+
+/**
+ * Set how a header behaves as the page scrolls (premium components T2, M4) — ONE edit for the builder's Header section
+ * and the composer (generation-core), on either node shape. A header that stays at the top is the containing block of its
+ * edge: the live site makes it sticky (iox-design.css), and a header stored `static` becomes `relative` — what the canvas,
+ * which forces a node's own position, draws it with. Nothing else of the author's is touched.
+ */
+export function setHeaderBehaviour(node: CompositeNode, behaviour: HeaderBehaviour | `${HeaderBehaviour}`, edge: HeaderEdge | `${HeaderEdge}` | null): void {
+    const b = headerBehaviourOf(behaviour);
+    writeProp(node, HeaderTrait.Behaviour, b);
+    writeProp(node, HeaderTrait.Edge, headerEdgeOf(edge) ?? '');
+    const position = readStyle(node, 'position');
+    if (headerStaysAtTop(b) && (position === undefined || position === null || position === '' || position === 'static')) writeStyles(node, { position: 'relative' });
+}
+
+/** The header's behaviour and edge as stored (Scrolls / none for a header that never chose). */
+export function headerBehaviourOfNode(node: CompositeNode | null | undefined): { behaviour: HeaderBehaviour; edge: HeaderEdge | null } {
+    return {
+        behaviour: headerBehaviourOf(node ? readProp(node, HeaderTrait.Behaviour) : undefined),
+        edge: headerEdgeOf(node ? readProp(node, HeaderTrait.Edge) : undefined),
+    };
+}

package/src/composite-core/public-api.ts

@@ -24,3 +24,4 @@ export * from './segmented';
 export * from './exclusive';
 export * from './exclusive-runtime';
 export * from './composite-runtime';
+export * from './header';

package/src/composite-core/slider-runtime.ts

@@ -178,3 +178,85 @@ export function attachCarouselA11y(swiper: CarouselSwiper, options: CarouselA11y
     carouselOf(swiper.el)?.destroy();
     return new CarouselA11y(swiper, options);
 }
+
+// ── The bar's words (premium components M4, M1.3) ──────────────────────────────────────────────────────
+
+/** Where the Caption and the Count parts get their words: generated content (`attr()`), never the element's text — so
+ *  the canvas's Text component and the runtime never write the same node. */
+export const SLIDER_TEXT_ATTRIBUTE = 'data-iox-text';
+/** A slide's caption, written by every renderer (iox-ui `nodeA11yAttributes`, SLIDE_CAPTION_ATTRIBUTE). */
+const CAPTION_ATTRIBUTE = 'data-iox-caption';
+/** Held for a frame while the caption changes, so its new words fade in (iox-design.css). */
+export const SLIDER_SWAPPING_ATTRIBUTE = 'data-iox-swapping';
+const BAR_RUNTIME_KEY = '__ioxSliderBar';
+
+/** What the caption says for a slide: its own caption, else its picture's description, else nothing. */
+export function sliderCaptionOf(slide: Element | null | undefined): string {
+    if (!slide) return '';
+    const holder = slide.hasAttribute(CAPTION_ATTRIBUTE) ? slide : slide.querySelector(`[${CAPTION_ATTRIBUTE}]`);
+    const own = holder?.getAttribute(CAPTION_ATTRIBUTE)?.trim();
+    if (own) return own;
+    return slide.querySelector('img[alt]')?.getAttribute('alt')?.trim() ?? '';
+}
+
+/** "2 / 5" — the slide in view and how many there are; nothing for an empty slider. */
+export function sliderCountText(index: number, total: number): string {
+    if (!(total > 0)) return '';
+    const i = Math.min(total - 1, Math.max(0, Math.floor(Number.isFinite(index) ? index : 0)));
+    return `${i + 1} / ${total}`;
+}
+
+/** The parts of a running Swiper the bar's runtime reads. */
+export interface BarSwiper {
+    el: HTMLElement;
+    slides: HTMLElement[];
+    activeIndex: number;
+    realIndex?: number;
+    destroyed?: boolean;
+    on(event: string, handler: (...args: unknown[]) => void): void;
+    off(event: string, handler: (...args: unknown[]) => void): void;
+}
+
+/**
+ * Keep the bar's Caption and Count on the slide in view — the canvas, Preview and both engine paths (bootSlider). The
+ * caption changes behind a short fade (the first one does not); the count reads left to right in every language.
+ * Returns the stop; a slider with neither part gets a no-op.
+ */
+export function attachSliderBar(swiper: BarSwiper): () => void {
+    ((swiper.el as unknown as Record<string, () => void>)[BAR_RUNTIME_KEY])?.();
+    const caption = sliderPartElement(swiper.el, SliderRole.Caption);
+    const count = sliderPartElement(swiper.el, SliderRole.Count);
+    if (!caption && !count) return () => { /* nothing to keep */ };
+    const view = swiper.el.ownerDocument?.defaultView;
+    const raf = (fn: () => void) => (view?.requestAnimationFrame ? view.requestAnimationFrame(() => view.requestAnimationFrame(fn)) : setTimeout(fn, 32));
+    let first = true;
+    const sync = () => {
+        if (swiper.destroyed) return;
+        const slides = swiper.slides ?? [];
+        if (count) {
+            count.setAttribute('dir', 'ltr');
+            count.setAttribute(SLIDER_TEXT_ATTRIBUTE, sliderCountText(swiper.realIndex ?? swiper.activeIndex, slides.length));
+        }
+        if (caption) {
+            const words = sliderCaptionOf(slides[swiper.activeIndex]);
+            if (caption.getAttribute(SLIDER_TEXT_ATTRIBUTE) !== words) {
+                if (!first) {
+                    caption.setAttribute(SLIDER_SWAPPING_ATTRIBUTE, '');
+                    raf(() => caption.removeAttribute(SLIDER_SWAPPING_ATTRIBUTE));
+                }
+                caption.setAttribute(SLIDER_TEXT_ATTRIBUTE, words);
+            }
+        }
+        first = false;
+    };
+    swiper.on('slideChange', sync);
+    swiper.on('slidesLengthChange', sync);
+    sync();
+    const stop = () => {
+        swiper.off('slideChange', sync);
+        swiper.off('slidesLengthChange', sync);
+        delete (swiper.el as unknown as Record<string, unknown>)[BAR_RUNTIME_KEY];
+    };
+    (swiper.el as unknown as Record<string, () => void>)[BAR_RUNTIME_KEY] = stop;
+    return stop;
+}

package/src/composite-core/slider.ts

@@ -27,10 +27,37 @@ export enum SliderRole {
     Prev = 'slider.prev',
     Next = 'slider.next',
     Pagination = 'slider.pagination',
+    /** Premium M4 (M1.3): the bar UNDER the picture that holds the controls — caption · count · arrows. */
+    Bar = 'slider.bar',
+    /** The caption of the slide in view (its `caption`, else its picture's description) — drawn by the runtime. */
+    Caption = 'slider.caption',
+    /** "1 / 3", drawn by the runtime, left to right in every language. */
+    Count = 'slider.count',
 }
 
 /** Parts in the order they are stamped: the pause control first (APG: the first focus stop), the dots last. */
-export const SLIDER_PART_ROLES: ReadonlyArray<SliderRole> = [SliderRole.Pause, SliderRole.Prev, SliderRole.Next, SliderRole.Pagination];
+export const SLIDER_PART_ROLES: ReadonlyArray<SliderRole> = [
+    SliderRole.Pause, SliderRole.Prev, SliderRole.Next, SliderRole.Pagination, SliderRole.Bar, SliderRole.Caption, SliderRole.Count,
+];
+
+/** Where the controls sit (premium M4): over the picture (CC3, every slider saved before M4) or in the bar under it. */
+export enum SliderPlacement {
+    Over = 'over',
+    Under = 'under',
+}
+export const SLIDER_PLACEMENT_TRAIT = 'controlsPlacement';
+/** The bar's parts in reading order: the pause control, the caption at the reading start, the count, the dots, the
+ *  arrows at the end (M1.3). */
+export const SLIDER_BAR_ORDER: ReadonlyArray<SliderRole> = [
+    SliderRole.Pause, SliderRole.Caption, SliderRole.Count, SliderRole.Pagination, SliderRole.Prev, SliderRole.Next,
+];
+/** Parts that exist only in the bar. */
+const BAR_ONLY: ReadonlyArray<SliderRole> = [SliderRole.Caption, SliderRole.Count];
+
+/** Premium M4: the trait that has the SCROLL play the slider (held mid-screen, resting on each picture). */
+export const SLIDER_SCROLL_PLAYS_TRAIT = 'scrollPlays';
+/** Premium M4: a slide's caption (SliderSlide ▸ Caption) — the bar's Caption part shows the one in view. */
+export const SLIDE_CAPTION_TRAIT = 'caption';
 
 export const SLIDER_TYPE = 'SliderContainer';
 export const SLIDE_TYPE = 'SliderSlide';
@@ -40,12 +67,18 @@ export enum SliderFlag {
     Navigation = 'enableNavigation',
     Pagination = 'enablePagination',
     Autoplay = 'enableAutoplay',
+    /** Premium M4: a caption under the picture (the bar only). */
+    Caption = 'enableCaption',
+    /** Premium M4: "1 / 3" under the picture (the bar only). */
+    Count = 'enableCount',
 }
 
 const FLAG_PARTS: ReadonlyArray<readonly [SliderFlag, ReadonlyArray<SliderRole>]> = [
     [SliderFlag.Autoplay, [SliderRole.Pause]],
     [SliderFlag.Navigation, [SliderRole.Prev, SliderRole.Next]],
     [SliderFlag.Pagination, [SliderRole.Pagination]],
+    [SliderFlag.Caption, [SliderRole.Caption]],
+    [SliderFlag.Count, [SliderRole.Count]],
 ];
 
 /** The trait that names the carousel (Slider ▸ Accessibility ▸ Carousel name) — the A11y trait every named part uses. */
@@ -61,9 +94,25 @@ export function isSlider(node: RoleLike | null | undefined): boolean {
     return node?.type === SLIDER_TYPE;
 }
 
-/** The slider's own part playing `role` (a direct child), or undefined. */
-export function sliderPart<T extends RoleLike>(slider: { children?: T[] | null }, role: SliderRole): T | undefined {
-    return (slider.children ?? []).find(c => c?.role === role);
+/** The slider's own part playing `role` — a direct child, or one in its bar — or undefined. */
+export function sliderPart<T extends RoleLike & { children?: T[] | null }>(slider: { children?: T[] | null }, role: SliderRole): T | undefined {
+    const direct = (slider.children ?? []).find(c => c?.role === role);
+    if (direct) return direct;
+    const bar = (slider.children ?? []).find(c => c?.role === SliderRole.Bar);
+    return (bar?.children ?? []).find(c => c?.role === role);
+}
+
+/**
+ * Where the slider's controls sit. The STRUCTURE decides once there are controls — a bar means under the picture, a
+ * control of its own means over it (every slider saved before M4) — so a stored trait can never disagree with what is
+ * drawn. A slider with no controls yet takes its `controlsPlacement` (the builder's new Slider: under the picture).
+ */
+export function sliderPlacementOf(slider: CompositeNode | null | undefined): SliderPlacement {
+    if (!slider) return SliderPlacement.Over;
+    const children = slider.children ?? [];
+    if (children.some(c => c?.role === SliderRole.Bar)) return SliderPlacement.Under;
+    if (children.some(isSliderPart)) return SliderPlacement.Over;
+    return readProp(slider, SLIDER_PLACEMENT_TRAIT) === SliderPlacement.Under ? SliderPlacement.Under : SliderPlacement.Over;
 }
 
 /** True when the slider's controls are parts (it was created or migrated in CC3) — Swiper then draws none of its own. */
@@ -95,15 +144,18 @@ enum Type {
     ButtonBlock = 'ButtonBlock',
     Icon = 'Icon',
     Container = 'Container',
+    Text = 'Text',
 }
 
 enum Style {
     Control = 'button-secondary',
     Icon = 'icon',
+    /** The caption and the count read as small print. */
+    Words = 'small',
 }
 
 /** Each part's glyph (Phosphor) and its default accessible name. */
-export const SLIDER_PART_GLYPH: Readonly<Record<Exclude<SliderRole, SliderRole.Pagination>, string>> = {
+export const SLIDER_PART_GLYPH: Readonly<Record<SliderRole.Pause | SliderRole.Prev | SliderRole.Next, string>> = {
     [SliderRole.Pause]: 'ph ph-pause',
     [SliderRole.Prev]: 'ph ph-caret-left',
     [SliderRole.Next]: 'ph ph-caret-right',
@@ -115,9 +167,30 @@ const PART_LABEL: Readonly<Record<SliderRole, string>> = {
     [SliderRole.Prev]: 'Previous',
     [SliderRole.Next]: 'Next',
     [SliderRole.Pagination]: 'Pagination',
+    [SliderRole.Bar]: 'Controls',
+    [SliderRole.Caption]: 'Caption',
+    [SliderRole.Count]: 'Count',
 };
 
 const ZERO = '0px 0px 0px 0px';
+/** A control in the bar: in flow, its own size, no offsets (the bar spaces its parts). */
+const BAR_PART_LAYOUT: Readonly<Record<string, string>> = { position: 'static', top: 'auto', margin: ZERO };
+/**
+ * The bar (M1.3): a row under the picture. Its inline padding keeps the PAGE's margin when the slider bleeds to the
+ * screen's edge — the gutter less however far the slider is already inset from the screen (`100%` is the slider's
+ * width, the bar's containing block) — so in a padded section it is 0 and at full bleed it is the gutter.
+ */
+const BAR_INLINE_PAD = 'max(0px, calc(var(--iox-space-gutter, 24px) - (100vw - 100%) / 2))';
+const BAR_BASE: Readonly<Record<string, string>> = {
+    position: 'relative', display: 'flex', flexDirection: 'row', flexWrap: 'nowrap', alignItems: 'center', justifyContent: 'flex-start',
+    gap: '12px', width: '100%', height: 'auto', minHeight: '44px', margin: ZERO, padding: `12px ${BAR_INLINE_PAD} 0px ${BAR_INLINE_PAD}`, zIndex: '10',
+};
+/** The caption takes the room the controls leave; its words end in an ellipsis rather than push them off. */
+const CAPTION_BASE: Readonly<Record<string, string>> = {
+    flexGrow: '1', flexShrink: '1', flexBasis: '0%', minWidth: '0px', width: 'auto', minHeight: 'auto', margin: ZERO, padding: ZERO,
+    overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap',
+};
+const COUNT_BASE: Readonly<Record<string, string>> = { flexGrow: '0', flexShrink: '0', width: 'auto', minHeight: 'auto', margin: ZERO, padding: ZERO };
 /** A round 44px control (board 6 `.st-ctl`), over the slides (z above `.swiper-wrapper`). The PLACE (which edge) is the
  *  shared CSS's, in logical insets, so a carousel reads the same way in RTL. */
 const CONTROL_BASE: Readonly<Record<string, string>> = {
@@ -158,6 +231,17 @@ function legacyLookOf(slider: CompositeNode): LegacySliderLook {
 
 /** One part, from the recipe (board 6: `button-secondary` controls, token dots) or in a migrated slider's legacy look. */
 export function buildSliderPart(create: CompositeNodeFactory, role: SliderRole, legacy?: LegacySliderLook): CompositeNode {
+    if (role === SliderRole.Bar) {
+        const bar = makeCompositePart(create, { key: 'bar', type: Type.Container, props: {}, elementStyle: NO_ELEMENT_STYLE }, role, PART_LABEL[role], BAR_BASE);
+        bar.children = [];
+        return bar;
+    }
+    if (role === SliderRole.Caption || role === SliderRole.Count) {
+        // Their words are the runtime's (the slide in view), drawn as the part's generated content: the node's own
+        // content stays empty, so no renderer ever fights the runtime over the element's text.
+        return makeCompositePart(create, { key: role.split('.')[1], type: Type.Text, props: { content: '', tag: 'p' }, elementStyle: Style.Words },
+            role, PART_LABEL[role], role === SliderRole.Caption ? CAPTION_BASE : COUNT_BASE);
+    }
     if (role === SliderRole.Pagination) {
         const dots = makeCompositePart(create, { key: 'pagination', type: Type.Container, props: {}, elementStyle: NO_ELEMENT_STYLE }, role, PART_LABEL[role],
             legacy?.paginationColor ? { ...PAGINATION_BASE, color: legacy.paginationColor } : PAGINATION_BASE);
@@ -186,50 +270,131 @@ export function buildSliderPart(create: CompositeNodeFactory, role: SliderRole,
 
 const truthy = (v: unknown): boolean => v === true || v === 'true';
 
-/** The parts the slider's switches call for, in stamping order. */
-export function wantedSliderParts(slider: CompositeNode): SliderRole[] {
-    return FLAG_PARTS.filter(([flag]) => truthy(readProp(slider, flag))).flatMap(([, roles]) => roles);
+/** The parts the slider's switches call for, in stamping order — and its bar, while the controls sit under the
+ *  picture. A caption and a count live in the bar only. */
+export function wantedSliderParts(slider: CompositeNode, placement: SliderPlacement = sliderPlacementOf(slider)): SliderRole[] {
+    const under = placement === SliderPlacement.Under;
+    const roles = FLAG_PARTS.filter(([flag]) => truthy(readProp(slider, flag))).flatMap(([, r]) => r).filter(r => under || !BAR_ONLY.includes(r));
+    // The bar exists while it holds something: an empty band under the picture is never drawn.
+    return under && roles.length ? [...roles, SliderRole.Bar] : roles;
 }
 
+/** The slider's parts wherever they are: its direct children and those in its bar. */
+function allSliderParts(slider: CompositeNode): CompositeNode[] {
+    const direct = (slider.children ?? []).filter(isSliderPart);
+    const bar = direct.find(c => c.role === SliderRole.Bar);
+    return [...direct, ...(bar?.children ?? []).filter(isSliderPart)];
+}
+
+const barIndex = (role: string | undefined): number => SLIDER_BAR_ORDER.indexOf(role as SliderRole);
+
 export interface SliderPartsChange {
     added: CompositeNode[];
     removed: CompositeNode[];
 }
 
 /**
- * Make the slider's parts match its switches — ONE edit (a palette switch, the migration, the composer). Missing
- * parts are stamped from the recipe (or, `legacy`, in the migrated look) at their place: the pause control, Previous
- * and Next before the first slide, the pagination after the last; parts whose switch is off are removed. Everything
- * else (the slides, the author's edits to an existing part) is kept.
+ * Make the slider's parts match its switches — ONE edit (a palette switch, the migration, the composer, a change of
+ * placement). Missing parts are stamped from the recipe (or, `legacy`, in the migrated look) at their place: over the
+ * picture, the pause control, Previous and Next before the first slide and the pagination after the last; under it
+ * (premium M4), every control in the bar in its reading order, the bar after the slides. Parts whose switch is off are
+ * removed wherever they are. Everything else (the slides, the author's edits to an existing part) is kept.
  */
 export function syncSliderParts(slider: CompositeNode, create: CompositeNodeFactory, legacy?: LegacySliderLook): SliderPartsChange {
-    const wanted = new Set(wantedSliderParts(slider));
-    const children = [...(slider.children ?? [])];
-    const removed = children.filter(c => isSliderPart(c) && !wanted.has(c.role as SliderRole));
-    const kept = children.filter(c => !removed.includes(c));
+    // A migrated slider keeps the place Swiper drew its controls in: over the picture.
+    const wanted = new Set(wantedSliderParts(slider, legacy ? SliderPlacement.Over : sliderPlacementOf(slider)));
+    const under = wanted.has(SliderRole.Bar);
+    const removed = allSliderParts(slider).filter(c => !wanted.has(c.role as SliderRole));
     const added: CompositeNode[] = [];
+    let kept = [...(slider.children ?? [])].filter(c => !removed.includes(c));
+    let bar = kept.find(c => c.role === SliderRole.Bar) ?? null;
+    if (bar) bar.children = (bar.children ?? []).filter(c => !removed.includes(c));
+    if (under && !bar) {
+        bar = buildSliderPart(create, SliderRole.Bar);
+        added.push(bar);
+        kept.push(bar);
+    }
     for (const role of SLIDER_PART_ROLES) {
-        if (!wanted.has(role) || kept.some(c => c.role === role)) continue;
+        if (role === SliderRole.Bar || !wanted.has(role) || allSliderPartsOf(kept, bar).some(c => c.role === role)) continue;
         const part = buildSliderPart(create, role, legacy);
         added.push(part);
-        if (role === SliderRole.Pagination) {
+        if (under && bar) {
+            if (role !== SliderRole.Caption && role !== SliderRole.Count) writeStyles(part, BAR_PART_LAYOUT);
+            placeInBar(bar, part);
+        } else if (role === SliderRole.Pagination) {
             kept.push(part);
         } else {
-            // Before the first slide, after the parts that come before it in stamping order.
-            const order = SLIDER_PART_ROLES.indexOf(role);
-            const firstSlide = kept.findIndex(c => !isSliderPart(c));
-            let at = firstSlide < 0 ? kept.length : firstSlide;
-            for (let i = 0; i < kept.length; i++) {
-                const r = kept[i].role as SliderRole;
-                if (isSliderPart(kept[i]) && SLIDER_PART_ROLES.indexOf(r) > order && i < at) { at = i; break; }
-            }
-            kept.splice(at, 0, part);
+            kept = placeBeforeSlides(kept, part, role);
         }
     }
     if (added.length || removed.length) slider.children = kept;
     return { added, removed };
 }
 
+function allSliderPartsOf(children: ReadonlyArray<CompositeNode>, bar: CompositeNode | null): CompositeNode[] {
+    return [...children.filter(isSliderPart), ...(bar?.children ?? []).filter(isSliderPart)];
+}
+
+/** Into the bar at its reading-order place (after the parts that come before it). */
+function placeInBar(bar: CompositeNode, part: CompositeNode): void {
+    const children = [...(bar.children ?? [])];
+    const order = barIndex(part.role);
+    const at = children.findIndex(c => barIndex(c.role) > order);
+    children.splice(at < 0 ? children.length : at, 0, part);
+    bar.children = children;
+}
+
+/** Before the first slide, after the parts that come before it in stamping order. */
+function placeBeforeSlides(kept: CompositeNode[], part: CompositeNode, role: SliderRole): CompositeNode[] {
+    const out = [...kept];
+    const order = SLIDER_PART_ROLES.indexOf(role);
+    const firstSlide = out.findIndex(c => !isSliderPart(c));
+    let at = firstSlide < 0 ? out.length : firstSlide;
+    for (let i = 0; i < out.length; i++) {
+        const r = out[i].role as SliderRole;
+        if (isSliderPart(out[i]) && SLIDER_PART_ROLES.indexOf(r) > order && i < at) { at = i; break; }
+    }
+    out.splice(at, 0, part);
+    return out;
+}
+
+/** The layout a control has over the picture (its recipe's place: absolute, the arrows at the vertical middle). */
+function overLayoutFor(role: SliderRole): Readonly<Record<string, string>> {
+    if (role === SliderRole.Pagination) return { position: 'absolute', margin: ZERO };
+    return role === SliderRole.Pause ? { position: 'absolute', top: 'auto', margin: ZERO } : { position: 'absolute', top: ARROW_TOP, margin: ZERO };
+}
+
+/**
+ * Move the controls over the picture or into the bar under it (premium M4, M1.3 — Slider ▸ Controls) — ONE edit and
+ * one undo step. The parts keep their identity and the author's edits; only their place changes (in flow in the bar,
+ * absolute over the picture). A caption and a count exist only in the bar. True when anything changed.
+ */
+export function setSliderPlacement(slider: CompositeNode, placement: SliderPlacement, create: CompositeNodeFactory): boolean {
+    const was = sliderPlacementOf(slider);
+    writeProp(slider, SLIDER_PLACEMENT_TRAIT, placement);
+    if (was === placement) return false;
+    const children = [...(slider.children ?? [])];
+    const bar = children.find(c => c.role === SliderRole.Bar) ?? null;
+    if (placement === SliderPlacement.Under) {
+        const controls = children.filter(c => isSliderPart(c) && c.role !== SliderRole.Bar);
+        const rest = children.filter(c => !controls.includes(c));
+        const target = bar ?? buildSliderPart(create, SliderRole.Bar);
+        for (const part of controls) { writeStyles(part, BAR_PART_LAYOUT); placeInBar(target, part); }
+        slider.children = bar ? rest : [...rest, target];
+    } else {
+        const inBar = (bar?.children ?? []).filter(isSliderPart);
+        let rest = children.filter(c => c !== bar);
+        for (const part of inBar) {
+            if (BAR_ONLY.includes(part.role as SliderRole)) continue;
+            writeStyles(part, overLayoutFor(part.role as SliderRole));
+            rest = part.role === SliderRole.Pagination ? [...rest, part] : placeBeforeSlides(rest, part, part.role as SliderRole);
+        }
+        slider.children = rest;
+    }
+    syncSliderParts(slider, create);
+    return true;
+}
+
 /** True when a saved slider still relies on Swiper-drawn controls: a switch is on and no part exists yet. */
 export function needsSliderMigration(slider: CompositeNode | null | undefined): boolean {
     return !!slider && isSlider(slider) && !hasSliderParts(slider) && wantedSliderParts(slider).length > 0;
@@ -354,6 +519,8 @@ export function buildCarouselRecipe(create: CompositeNodeFactory, options: Carou
         // Rewind: Previous and Next are always there to press (board 6) — neither greys out at an end.
         slidesPerView: 1, spaceBetween: 0, loop: 'rewind', enableNavigation: true, enablePagination: true, enableAutoplay: true, autoplayDelay: 5000,
         autoplayPauseOnMouseEnter: true, autoHeight: true, [SLIDER_NAME_TRAIT]: options.name ?? 'What clients say',
+        // Board 6 draws its controls in a row above the quotes — its own place, not the M4 bar under a picture.
+        [SLIDER_PLACEMENT_TRAIT]: SliderPlacement.Over,
     })) writeProp(slider, name, value);
     slider.children = (options.quotes ?? CAROUSEL_QUOTES).map((q, i) => {
         const slide = makeCompositePart(create, { key: `slide-${i + 1}`, type: SLIDE_TYPE, props: {}, elementStyle: 'card' }, null, 'Slide', QUOTE_SLIDE_BASE);

package/src/composite-core/structure.ts

@@ -11,7 +11,8 @@ import { SLIDER_TYPE, SliderRole } from './slider';
 export interface CompositeRoleSpec {
     /** The role of the part's parent; null for a composite root. */
     readonly parent: string | null;
-    /** The TYPE of the part's parent, for a part whose parent carries no role (a Slider's controls). */
+    /** The TYPE of the part's parent, for a part whose parent carries no role (a Slider's controls). With `parent`
+     *  also set, either parent places it (a Slider's control lives in the slider or in its bar). */
     readonly parentType?: string;
     readonly locked?: boolean;
     /** May be deleted, but never moved out of its parent (a Slider's controls work only as its direct children). */
@@ -59,13 +60,17 @@ export const COMPOSITE_ROLE_SPECS: Readonly<Record<string, CompositeRoleSpec>> =
     // A Scene always keeps its stage: everything it pins and clips lives there.
     [SceneRole.Scene]: { parent: null },
     [SceneRole.Stage]: { parent: SceneRole.Scene, locked: true },
-    // CC3 — a Slider's controls are its own direct children (Swiper is handed them). The pause control stays while
-    // Autoplay is on (WCAG 2.2.2): the Autoplay switch removes it, never Delete. The arrows and the dots follow
-    // their switches and may be deleted.
-    [SliderRole.Pause]: { parent: null, parentType: SLIDER_TYPE, locked: true },
-    [SliderRole.Prev]: { parent: null, parentType: SLIDER_TYPE, pinned: true },
-    [SliderRole.Next]: { parent: null, parentType: SLIDER_TYPE, pinned: true },
-    [SliderRole.Pagination]: { parent: null, parentType: SLIDER_TYPE, pinned: true },
+    // CC3 — a Slider's controls are its own direct children (Swiper is handed them) — or, premium M4, children of its
+    // bar under the picture. The pause control stays while Autoplay is on (WCAG 2.2.2): the Autoplay switch removes it,
+    // never Delete. The arrows, the dots, the caption and the count follow their switches and may be deleted; the bar
+    // follows Slider ▸ Controls.
+    [SliderRole.Pause]: { parent: SliderRole.Bar, parentType: SLIDER_TYPE, locked: true },
+    [SliderRole.Prev]: { parent: SliderRole.Bar, parentType: SLIDER_TYPE, pinned: true },
+    [SliderRole.Next]: { parent: SliderRole.Bar, parentType: SLIDER_TYPE, pinned: true },
+    [SliderRole.Pagination]: { parent: SliderRole.Bar, parentType: SLIDER_TYPE, pinned: true },
+    [SliderRole.Bar]: { parent: null, parentType: SLIDER_TYPE, pinned: true },
+    [SliderRole.Caption]: { parent: SliderRole.Bar, pinned: true },
+    [SliderRole.Count]: { parent: SliderRole.Bar, pinned: true },
 };
 
 export enum StructureEdit {
@@ -95,7 +100,7 @@ export function structureRefusal(node: RoleLike | null | undefined, edit: Struct
     if (edit === StructureEdit.Move && acceptsRefusal(node, parent)) return StructureRefusal.NotAccepted;
     if (!spec?.locked && !spec?.pinned) return null;
     if (edit === StructureEdit.Delete) return spec.locked ? StructureRefusal.LockedPart : null;
-    const placed = spec.parentType ? parent?.type === spec.parentType : parent?.role === spec.parent;
+    const placed = (!!spec.parentType && parent?.type === spec.parentType) || (spec.parent !== null && parent?.role === spec.parent);
     return placed ? null : StructureRefusal.LockedPlacement;
 }