@vectoriox/iox-ui 5.84.0 → 5.85.0

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;
 }