@vectoriox/iox-ui 5.37.0 → 5.39.0

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

@@ -0,0 +1,180 @@
+import { sliderLiveRegion, sliderPauseAttributes, sliderPauseGlyph, SliderRole, SliderWords, sliderWords } from './slider';
+
+/**
+ * The accessible carousel's RUNTIME (CC3, board 6; closes vectoriox/iox-ui#13) — DOM only, over a running Swiper,
+ * ONE copy for the engine (both paths) and the admin's Preview. Swiper's A11y module gives the container
+ * `aria-roledescription="carousel"`, every slide `role=group` + "slide" + "n of m"; this adds what the APG
+ * carousel needs on top:
+ * - the PAUSE control (role `slider.pause`, rendered first): it stops rotation for good and starts it again; its
+ *   name says what it will do, its glyph swaps;
+ * - rotation PAUSES while focus is anywhere inside (hover is Swiper's `pauseOnMouseEnter`) and resumes when it
+ *   leaves — unless the visitor pressed pause;
+ * - the wrapper's live region is `off` while the slides move on their own and `polite` otherwise;
+ * - slides that are not in view are `inert` (and hidden from assistive technology), so Tab never lands in one.
+ * The builder's EDIT canvas never attaches it (no autoplay there, and a slide must stay clickable).
+ */
+
+/** The parts of the Swiper instance this runtime reads — a real Swiper, or a stub in a spec. */
+export interface CarouselSwiper {
+    el: HTMLElement;
+    wrapperEl: HTMLElement;
+    slides: HTMLElement[];
+    activeIndex: number;
+    destroyed?: boolean;
+    params?: { slidesPerView?: number | 'auto'; autoplay?: { pauseOnMouseEnter?: boolean } | boolean };
+    autoplay?: { running: boolean; paused?: boolean; start(): void; stop(): void; pause(): void; resume(): void };
+    on(event: string, handler: (...args: unknown[]) => void): void;
+    off(event: string, handler: (...args: unknown[]) => void): void;
+}
+
+export interface CarouselA11yOptions {
+    words?: SliderWords;
+}
+
+const SLIDE_VISIBLE = 'swiper-slide-visible';
+const RUNTIME_KEY = '__ioxCarousel';
+const ROTATION_EVENTS = 'autoplayStart autoplayStop autoplayPause autoplayResume';
+const SLIDE_EVENTS = 'slideChange transitionEnd resize slidesLengthChange';
+
+const AUTHOR_NAME_KEY = '__ioxAuthorName';
+
+/** The name the AUTHOR gave the pause control (its rendered `aria-label` before this runtime first relabelled it). */
+function authorNameOf(el: HTMLElement | null): string | null {
+    if (!el) return null;
+    const host = el as unknown as Record<string, unknown>;
+    if (host[AUTHOR_NAME_KEY] === undefined) host[AUTHOR_NAME_KEY] = el.getAttribute('aria-label') ?? '';
+    return (host[AUTHOR_NAME_KEY] as string) || null;
+}
+
+/** The part of `role` that belongs to THIS slider (never one of a slider nested in a slide). */
+export function sliderPartElement(sliderEl: Element, role: SliderRole): HTMLElement | null {
+    const cls = `iox-role-${role.replace('.', '-')}`;
+    for (const el of Array.from(sliderEl.querySelectorAll<HTMLElement>(`.${cls}`))) {
+        if (el.closest('.swiper') === sliderEl && !el.closest('.swiper-wrapper')) return el;
+    }
+    return null;
+}
+
+export class CarouselA11y {
+    /** The visitor pressed pause: rotation stays stopped until they press it again. */
+    private stoppedByVisitor = false;
+    private focusInside = false;
+    /** The pointer is over the carousel and Swiper holds rotation for it (`pauseOnMouseEnter`). */
+    private hovering = false;
+    private readonly cleanups: Array<() => void> = [];
+    private readonly words: SliderWords;
+    private readonly pause: HTMLElement | null;
+    private readonly authorName: string | null;
+
+    constructor(private readonly swiper: CarouselSwiper, options: CarouselA11yOptions = {}) {
+        const el = swiper.el;
+        this.words = options.words ?? sliderWords(el.ownerDocument?.documentElement?.getAttribute('lang'));
+        this.pause = sliderPartElement(el, SliderRole.Pause);
+        this.authorName = authorNameOf(this.pause);
+        this.listen(el, 'focusin', () => this.onFocusIn());
+        this.listen(el, 'pointerenter', () => { this.hovering = this.hoverPauses; this.sync(); });
+        this.listen(el, 'pointerleave', () => { this.hovering = false; this.sync(); });
+        this.listen(el, 'focusout', (e) => this.onFocusOut(e as FocusEvent));
+        if (this.pause) this.listen(this.pause, 'click', (e) => { e.preventDefault(); this.togglePause(); });
+        const sync = () => this.sync();
+        swiper.on(ROTATION_EVENTS, sync);
+        swiper.on(SLIDE_EVENTS, sync);
+        this.cleanups.push(() => { swiper.off(ROTATION_EVENTS, sync); swiper.off(SLIDE_EVENTS, sync); });
+        (el as unknown as Record<string, unknown>)[RUNTIME_KEY] = this;
+        this.sync();
+    }
+
+    /** True while the slides move on their own: autoplay runs and nothing holds it — not focus inside, not the
+     *  pointer over it. (Swiper's own `paused` also flips during every transition, so it is not read here.) */
+    get rotating(): boolean {
+        return !!this.swiper.autoplay?.running && !this.focusInside && !this.hovering;
+    }
+
+    private get hoverPauses(): boolean {
+        const autoplay = this.swiper.params?.autoplay;
+        return typeof autoplay === 'object' && !!autoplay?.pauseOnMouseEnter;
+    }
+
+    /** The pause control: stop rotation for good, or start it again. */
+    togglePause(): void {
+        const a = this.swiper.autoplay;
+        if (!a) return;
+        if (a.running) {
+            this.stoppedByVisitor = true;
+            a.stop();
+        } else {
+            this.stoppedByVisitor = false;
+            a.start();
+            // Focus is on the pause control itself — inside the carousel: the rotation it just started waits until
+            // focus leaves (APG), but the control already reads "stop".
+            if (this.focusInside) a.pause();
+        }
+        this.sync();
+    }
+
+    destroy(): void {
+        this.cleanups.splice(0).forEach(fn => fn());
+        delete (this.swiper.el as unknown as Record<string, unknown>)[RUNTIME_KEY];
+    }
+
+    private listen(target: EventTarget, type: string, fn: (e: Event) => void): void {
+        target.addEventListener(type, fn);
+        this.cleanups.push(() => target.removeEventListener(type, fn));
+    }
+
+    private onFocusIn(): void {
+        this.focusInside = true;
+        if (this.swiper.autoplay?.running && !this.swiper.autoplay.paused) this.swiper.autoplay.pause();
+        this.sync();
+    }
+
+    private onFocusOut(e: FocusEvent): void {
+        const next = e.relatedTarget as Node | null;
+        if (next && this.swiper.el.contains(next)) return;
+        this.focusInside = false;
+        if (!this.stoppedByVisitor && this.swiper.autoplay?.running && this.swiper.autoplay.paused) this.swiper.autoplay.resume();
+        this.sync();
+    }
+
+    /** Re-state the carousel: the live region, the pause control, the slides out of view. */
+    sync(): void {
+        if (this.swiper.destroyed) return;
+        const rotating = this.rotating;
+        this.swiper.wrapperEl?.setAttribute('aria-live', sliderLiveRegion(rotating));
+        if (this.pause) {
+            const running = !!this.swiper.autoplay?.running;
+            const attrs = sliderPauseAttributes(running, this.words, this.authorName);
+            for (const [name, value] of Object.entries(attrs)) this.pause.setAttribute(name, value);
+            if (!('aria-pressed' in attrs)) this.pause.removeAttribute('aria-pressed');
+            const icon = this.pause.querySelector('i');
+            if (icon) icon.className = `${sliderPauseGlyph(running)} ${Array.from(icon.classList).filter(c => !c.startsWith('ph')).join(' ')}`.trim();
+        }
+        this.syncHiddenSlides();
+    }
+
+    private syncHiddenSlides(): void {
+        const slides = this.swiper.slides ?? [];
+        const anyVisibleMarked = slides.some(s => s.classList?.contains(SLIDE_VISIBLE));
+        slides.forEach((slide, i) => {
+            const visible = anyVisibleMarked ? slide.classList.contains(SLIDE_VISIBLE) : i === this.swiper.activeIndex;
+            if (visible) {
+                slide.removeAttribute('inert');
+                slide.removeAttribute('aria-hidden');
+            } else {
+                slide.setAttribute('inert', '');
+                slide.setAttribute('aria-hidden', 'true');
+            }
+        });
+    }
+}
+
+/** The carousel runtime attached to a slider element, if any. */
+export function carouselOf(el: Element | null | undefined): CarouselA11y | null {
+    return ((el as unknown as Record<string, unknown> | null)?.[RUNTIME_KEY] as CarouselA11y | undefined) ?? null;
+}
+
+/** Attach once per Swiper (a re-init gets a fresh runtime). */
+export function attachCarouselA11y(swiper: CarouselSwiper, options: CarouselA11yOptions = {}): CarouselA11y {
+    carouselOf(swiper.el)?.destroy();
+    return new CarouselA11y(swiper, options);
+}

package/src/composite-core/slider.ts

@@ -0,0 +1,378 @@
+import { CompositeNode, CompositeNodeFactory, makeCompositePart, NO_ELEMENT_STYLE, readProp, writeProp, writeStyles } from './composite-node';
+
+/**
+ * THE ACCESSIBLE CAROUSEL (CC3 — complex-components plan §7c, board 6; board 9 Q13). The Slider's controls are no
+ * longer drawn by Swiper: Previous, Next, Pause and Pagination are REAL nodes with roles — selectable on the canvas,
+ * in the layer tree and the breadcrumb, and styled on their own (R2) — handed to Swiper as its navigation and
+ * pagination elements.
+ *
+ *   SliderContainer  (.swiper)
+ *   ├─ ButtonBlock `button-secondary`   role slider.pause       FIRST focus stop; present while Autoplay is on, locked
+ *   ├─ ButtonBlock `button-secondary`   role slider.prev        › Icon caret (points the reading way in RTL)
+ *   ├─ ButtonBlock `button-secondary`   role slider.next        › Icon caret
+ *   ├─ (the slides — `.swiper-wrapper` › SliderSlide …)
+ *   └─ Container                        role slider.pagination  Swiper draws the dots (or "3 / 6") inside it
+ *
+ * The parts render INSIDE the `.swiper` element, never inside `.swiper-wrapper` (slider.md: a `.swiper-slide` must be
+ * the wrapper's direct child): the parts that come before the first slide in the tree render before the wrapper, the
+ * rest after it. By default they sit over the slides like Swiper's own controls (the shared CSS, iox-design.css, at
+ * zero specificity — a part's own styles win), so a saved slider migrated from Swiper-drawn controls keeps its look.
+ *
+ * The Bindings switches stay the source of truth: Navigation arrows ⇔ Previous + Next, Pagination ⇔ Pagination,
+ * Autoplay ⇔ Pause (WCAG 2.2.2 — "added while Autoplay is on, cannot be removed"). `syncSliderParts` is the one edit.
+ */
+
+export enum SliderRole {
+    Pause = 'slider.pause',
+    Prev = 'slider.prev',
+    Next = 'slider.next',
+    Pagination = 'slider.pagination',
+}
+
+/** 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_TYPE = 'SliderContainer';
+export const SLIDE_TYPE = 'SliderSlide';
+
+/** The Bindings switches that own the parts. */
+export enum SliderFlag {
+    Navigation = 'enableNavigation',
+    Pagination = 'enablePagination',
+    Autoplay = 'enableAutoplay',
+}
+
+const FLAG_PARTS: ReadonlyArray<readonly [SliderFlag, ReadonlyArray<SliderRole>]> = [
+    [SliderFlag.Autoplay, [SliderRole.Pause]],
+    [SliderFlag.Navigation, [SliderRole.Prev, SliderRole.Next]],
+    [SliderFlag.Pagination, [SliderRole.Pagination]],
+];
+
+/** The trait that names the carousel (Slider ▸ Accessibility ▸ Carousel name) — the A11y trait every named part uses. */
+export const SLIDER_NAME_TRAIT = 'ariaLabel';
+
+interface RoleLike { role?: string | null; type?: string }
+
+export function isSliderPart(node: RoleLike | null | undefined): boolean {
+    return !!node?.role && (SLIDER_PART_ROLES as ReadonlyArray<string>).includes(node.role);
+}
+
+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);
+}
+
+/** True when the slider's controls are parts (it was created or migrated in CC3) — Swiper then draws none of its own. */
+export function hasSliderParts(slider: { children?: ReadonlyArray<RoleLike> | null }): boolean {
+    return (slider.children ?? []).some(isSliderPart);
+}
+
+/** A slider's children split as they render: parts before the first slide, the slides (into `.swiper-wrapper`), and
+ *  the parts after it. */
+export function splitSliderChildren<T extends RoleLike>(children: ReadonlyArray<T> | null | undefined): { lead: T[]; slides: T[]; trail: T[] } {
+    const lead: T[] = [];
+    const slides: T[] = [];
+    const trail: T[] = [];
+    for (const child of children ?? []) {
+        if (!isSliderPart(child)) slides.push(child);
+        else (slides.length ? trail : lead).push(child);
+    }
+    return { lead, slides, trail };
+}
+
+/** The slides only (the template slide of a bound slider is `sliderSlides(children)[0]`). */
+export function sliderSlides<T extends RoleLike>(children: ReadonlyArray<T> | null | undefined): T[] {
+    return (children ?? []).filter(c => !isSliderPart(c));
+}
+
+// ── the parts' recipe ───────────────────────────────────────────────────────────────────────────────
+
+enum Type {
+    ButtonBlock = 'ButtonBlock',
+    Icon = 'Icon',
+    Container = 'Container',
+}
+
+enum Style {
+    Control = 'button-secondary',
+    Icon = 'icon',
+}
+
+/** Each part's glyph (Phosphor) and its default accessible name. */
+export const SLIDER_PART_GLYPH: Readonly<Record<Exclude<SliderRole, SliderRole.Pagination>, string>> = {
+    [SliderRole.Pause]: 'ph ph-pause',
+    [SliderRole.Prev]: 'ph ph-caret-left',
+    [SliderRole.Next]: 'ph ph-caret-right',
+};
+export const SLIDER_PLAY_GLYPH = 'ph-fill ph-play';
+
+const PART_LABEL: Readonly<Record<SliderRole, string>> = {
+    [SliderRole.Pause]: 'Pause',
+    [SliderRole.Prev]: 'Previous',
+    [SliderRole.Next]: 'Next',
+    [SliderRole.Pagination]: 'Pagination',
+};
+
+const ZERO = '0px 0px 0px 0px';
+/** 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>> = {
+    position: 'absolute', zIndex: '10', display: 'flex', alignItems: 'center', justifyContent: 'center',
+    width: '44px', height: '44px', minWidth: '44px', padding: ZERO, margin: ZERO, borderRadius: '999px',
+};
+const ICON_BASE: Readonly<Record<string, string>> = { fontSize: '20px', color: 'inherit' };
+/** The arrows' vertical middle over the slides: half the 44px control above the centre line. */
+const ARROW_TOP = 'calc(50% - 22px)';
+const PAGINATION_BASE: Readonly<Record<string, string>> = {
+    position: 'absolute', zIndex: '10', display: 'flex', alignItems: 'center', justifyContent: 'center', gap: '8px',
+    width: 'auto', minHeight: 'auto', height: 'auto', padding: ZERO, margin: ZERO, color: 'var(--iox-accent)',
+};
+
+/**
+ * What a saved slider drew through Swiper before CC3, carried into its parts by the migration so it looks the same:
+ * bare chevrons in the author's arrow colour and size, the dots in the author's colour. Swiper's own default colour
+ * is its theme blue — what the live site drew, because the engine never applied the colour traits.
+ */
+export interface LegacySliderLook {
+    navigationColor?: string;
+    navigationSize?: number;
+    paginationColor?: string;
+}
+
+export const SWIPER_THEME_COLOR = '#007aff';
+
+function legacyLookOf(slider: CompositeNode): LegacySliderLook {
+    const color = readProp(slider, 'navigationColor');
+    const size = Number(readProp(slider, 'navigationSize'));
+    const dots = readProp(slider, 'paginationColor');
+    return {
+        navigationColor: typeof color === 'string' && color ? color : SWIPER_THEME_COLOR,
+        navigationSize: Number.isFinite(size) && size > 0 ? size : 44,
+        paginationColor: typeof dots === 'string' && dots ? dots : SWIPER_THEME_COLOR,
+    };
+}
+
+/** 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.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);
+        dots.children = [];
+        return dots;
+    }
+    const key = role.split('.')[1];
+    // Previous / Next sit at the vertical middle (their own `top`, so a part set back in flow drops it); the inline edge
+    // is the shared CSS's, logical, so the arrows swap sides in RTL.
+    const placed = role === SliderRole.Pause ? CONTROL_BASE : { ...CONTROL_BASE, top: ARROW_TOP };
+    const base = legacy
+        ? { ...placed, backgroundColor: 'transparent', borderWidth: ZERO, color: legacy.navigationColor ?? SWIPER_THEME_COLOR, boxShadow: 'none' }
+        : placed;
+    // Previous / Next carry their accessible name (Swiper's A11y module reads it); the pause control's name is its
+    // runtime's — it says what pressing it will do.
+    const props: Record<string, unknown> = { tag: 'button', type: 'button' };
+    if (role !== SliderRole.Pause) props[SLIDER_NAME_TRAIT] = role === SliderRole.Prev ? SLIDER_WORDS.en.prev : SLIDER_WORDS.en.next;
+    const button = makeCompositePart(create, { key, type: Type.ButtonBlock, props, elementStyle: legacy ? NO_ELEMENT_STYLE : Style.Control },
+        role, PART_LABEL[role], base);
+    const iconBase = legacy ? { ...ICON_BASE, fontSize: `${Math.round((legacy.navigationSize ?? 44) * 0.6)}px` } : ICON_BASE;
+    const icon = makeCompositePart(create, { key: `${key}-icon`, type: Type.Icon, props: { iconClass: SLIDER_PART_GLYPH[role] }, elementStyle: legacy ? NO_ELEMENT_STYLE : Style.Icon },
+        null, 'Icon', iconBase);
+    button.children = [icon];
+    return button;
+}
+
+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);
+}
+
+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.
+ */
+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));
+    const added: CompositeNode[] = [];
+    for (const role of SLIDER_PART_ROLES) {
+        if (!wanted.has(role) || kept.some(c => c.role === role)) continue;
+        const part = buildSliderPart(create, role, legacy);
+        added.push(part);
+        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);
+        }
+    }
+    if (added.length || removed.length) slider.children = kept;
+    return { added, removed };
+}
+
+/** 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;
+}
+
+/**
+ * The migration of a saved slider (board 9 Q13): its Swiper-drawn arrows, dots — and, when Autoplay is on, the pause
+ * control WCAG 2.2.2 requires — become parts, in the place and the colours Swiper drew them. Idempotent: a slider
+ * that already has parts is left alone. True when it changed.
+ */
+export function migrateSliderControls(slider: CompositeNode, create: CompositeNodeFactory): boolean {
+    if (!needsSliderMigration(slider)) return false;
+    const change = syncSliderParts(slider, create, legacyLookOf(slider));
+    return change.added.length > 0;
+}
+
+/**
+ * A switch flipped in the panel: on a slider still on Swiper-drawn controls, migrate it first (so its other controls
+ * keep their look), then stamp / remove the parts the new switch calls for. ONE edit.
+ */
+export function setSliderFlag(slider: CompositeNode, flag: SliderFlag, on: boolean, create: CompositeNodeFactory): SliderPartsChange {
+    const wasLegacy = !hasSliderParts(slider);
+    const before = wantedSliderParts(slider);
+    const migrated: CompositeNode[] = [];
+    if (wasLegacy && before.length) {
+        syncSliderParts(slider, create, legacyLookOf(slider)).added.forEach(p => migrated.push(p));
+    }
+    writeProp(slider, flag, on);
+    const change = syncSliderParts(slider, create);
+    return { added: [...migrated, ...change.added], removed: change.removed };
+}
+
+// ── accessibility vocabulary (both runtimes) ───────────────────────────────────────────────────────
+
+export interface SliderWords {
+    stop: string;
+    start: string;
+    prev: string;
+    next: string;
+    carousel: string;
+    slide: string;
+    /** `{{index}}` and `{{slidesLength}}`, Swiper's placeholders. */
+    slideLabel: string;
+    goTo: string;
+}
+
+export const SLIDER_WORDS: Readonly<Record<'en' | 'he', SliderWords>> = {
+    en: {
+        stop: 'Stop automatic slide show', start: 'Start automatic slide show', prev: 'Previous slide', next: 'Next slide',
+        carousel: 'carousel', slide: 'slide', slideLabel: '{{index}} of {{slidesLength}}', goTo: 'Go to slide {{index}}',
+    },
+    he: {
+        stop: 'עצירת המצגת האוטומטית', start: 'הפעלת המצגת האוטומטית', prev: 'השקופית הקודמת', next: 'השקופית הבאה',
+        carousel: 'קרוסלה', slide: 'שקופית', slideLabel: '{{index}} מתוך {{slidesLength}}', goTo: 'מעבר לשקופית {{index}}',
+    },
+};
+
+export function sliderWords(lang?: string | null): SliderWords {
+    return (lang ?? '').toLowerCase().startsWith('he') ? SLIDER_WORDS.he : SLIDER_WORDS.en;
+}
+
+/** The wrapper's live region (APG): silent while the slides move on their own, polite otherwise. */
+export function sliderLiveRegion(rotating: boolean): 'off' | 'polite' {
+    return rotating ? 'off' : 'polite';
+}
+
+/**
+ * The pause control's state (APG carousel): its NAME says what it will do ("Stop automatic slide show" while it
+ * rotates, "Start automatic slide show" when stopped). An author who named the control keeps the name, and the
+ * state is `aria-pressed` instead (pressed = stopped).
+ */
+export function sliderPauseAttributes(rotating: boolean, words: SliderWords = SLIDER_WORDS.en, authorName?: string | null): Record<string, string> {
+    const name = (authorName ?? '').trim();
+    return name
+        ? { 'aria-label': name, 'aria-pressed': rotating ? 'false' : 'true' }
+        : { 'aria-label': rotating ? words.stop : words.start };
+}
+
+/** The pause control's glyph: pause while it rotates, play when stopped. */
+export function sliderPauseGlyph(rotating: boolean): string {
+    return rotating ? SLIDER_PART_GLYPH[SliderRole.Pause] : SLIDER_PLAY_GLYPH;
+}
+
+// ── the testimonial carousel (board 6; generation-core `proof.testimonial-carousel`) ─────────────────
+
+export interface CarouselQuote {
+    quote: string;
+    who: string;
+}
+
+/** Board 6's sample quotes — PLACEHOLDERS: testimonials are facts the studio gives, never invented. */
+export const CAROUSEL_QUOTES: ReadonlyArray<CarouselQuote> = [
+    { quote: 'A sample quote, two lines long, in the client’s own words.', who: '[Client name] · [Project, city]' },
+    { quote: 'Testimonials are facts: replace these with words a client actually said.', who: '[Client name] · [Project, city]' },
+    { quote: 'A third sample quote so the rotation has somewhere to go.', who: '[Client name] · [Project, city]' },
+];
+
+export interface CarouselOptions {
+    /** The carousel's accessible name (a `region` landmark). */
+    name?: string;
+    quotes?: ReadonlyArray<CarouselQuote>;
+}
+
+/** A quote card. The carousel's controls sit in a ROW above the slides and the dots below them (board 6), so the
+ *  card needs no room kept for an overlay. */
+const QUOTE_SLIDE_BASE: Readonly<Record<string, string>> = {
+    width: '100%', aspectRatio: 'auto', minHeight: 'auto', height: 'auto', display: 'flex', flexDirection: 'column', gap: '12px', padding: '32px 32px 32px 32px',
+};
+/** Board 6's carousel: the pause control, Previous and Next in one row above the slides (in flow — they read in the
+ *  page's direction), the dots under them. */
+const ROW_CONTROL_BASE: Readonly<Record<string, string>> = { position: 'static', display: 'inline-flex', margin: '0px 4px 12px 4px' };
+const ROW_DOTS_BASE: Readonly<Record<string, string>> = { position: 'static', margin: '12px 0px 0px 0px' };
+const QUOTE_TEXT_BASE: Readonly<Record<string, string>> = { margin: ZERO, padding: ZERO, minHeight: 'auto', width: 'auto' };
+
+/**
+ * The testimonial carousel (board 6): a named Slider, one quote per slide (each a `card`), rotating every 5s with its
+ * control parts — the pause control first, Previous · Next, the dots. ONE recipe for the composer and the builder.
+ */
+export function buildCarouselRecipe(create: CompositeNodeFactory, options: CarouselOptions = {}): CompositeNode {
+    const slider = makeCompositePart(create, { key: 'carousel', type: SLIDER_TYPE, props: {}, elementStyle: NO_ELEMENT_STYLE }, null, 'Carousel', { width: '100%' });
+    for (const [name, value] of Object.entries({
+        // 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',
+    })) 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);
+        slide.children = [
+            makeCompositePart(create, { key: `quote-${i + 1}`, type: 'Text', props: { content: q.quote, tag: 'p' }, elementStyle: 'lead' }, null, 'Quote', QUOTE_TEXT_BASE),
+            makeCompositePart(create, { key: `who-${i + 1}`, type: 'Text', props: { content: q.who, tag: 'p' }, elementStyle: 'small' }, null, 'Client', QUOTE_TEXT_BASE),
+        ];
+        return slide;
+    });
+    syncSliderParts(slider, create);
+    for (const part of slider.children ?? []) {
+        if (part.role === SliderRole.Pagination) writeStyles(part, ROW_DOTS_BASE);
+        else if (isSliderPart(part)) writeStyles(part, ROW_CONTROL_BASE);
+    }
+    return slider;
+}
+
+/** The slide a lightbox opens at for the clicked row (clamped to the slides there are). */
+export function slideIndexForRow(rowIndex: number, slideCount: number): number {
+    if (!Number.isFinite(rowIndex) || rowIndex < 0 || slideCount <= 0) return 0;
+    return Math.min(Math.floor(rowIndex), slideCount - 1);
+}

package/src/composite-core/structure.ts

@@ -1,5 +1,6 @@
-import { AccordionRole, DisclosureRole } from './composite-kinds';
+import { AccordionRole, DisclosureRole, TabsRole } from './composite-kinds';
 import { CardPart, CardRole } from './card';
+import { SLIDER_TYPE, SliderRole } from './slider';
 
 /**
  * The structure every composite declares (composite-components plan §3a `RoleSpec`): where a role may
@@ -10,8 +11,14 @@ import { CardPart, CardRole } from './card';
 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). */
+    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). */
+    readonly pinned?: boolean;
     readonly part?: CardPart;
+    /** The only roles that may be dropped INTO this part (a tab list takes tabs, a panels holder takes panels). */
+    readonly accepts?: ReadonlyArray<string>;
 }
 
 export const COMPOSITE_ROLE_SPECS: Readonly<Record<string, CompositeRoleSpec>> = {
@@ -36,6 +43,21 @@ export const COMPOSITE_ROLE_SPECS: Readonly<Record<string, CompositeRoleSpec>> =
     [DisclosureRole.More]: { parent: DisclosureRole.Trigger },
     [DisclosureRole.Less]: { parent: DisclosureRole.Trigger },
     [DisclosureRole.Icon]: { parent: DisclosureRole.Trigger },
+    // CC4a — a Tabs always keeps its tab list and its panels holder; a tab lives in the list and a panel in the
+    // holder (each may be deleted — with its pair — but never moved out); the list takes only tabs, the holder only
+    // panels, and a panel takes anything.
+    [TabsRole.Tabs]: { parent: null },
+    [TabsRole.List]: { parent: TabsRole.Tabs, locked: true, accepts: [TabsRole.Trigger] },
+    [TabsRole.Panels]: { parent: TabsRole.Tabs, locked: true, accepts: [TabsRole.Panel] },
+    [TabsRole.Trigger]: { parent: TabsRole.List, pinned: true },
+    [TabsRole.Panel]: { parent: TabsRole.Panels, pinned: 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 },
 };
 
 export enum StructureEdit {
@@ -49,9 +71,11 @@ export enum StructureRefusal {
     LockedPart = 'locked-part',
     /** A locked part can only live directly inside its own parent role. */
     LockedPlacement = 'locked-placement',
+    /** The new parent takes only certain roles (a tab list takes only tabs, CC4a). */
+    NotAccepted = 'not-accepted',
 }
 
-interface RoleLike { role?: string | null }
+interface RoleLike { role?: string | null; type?: string }
 
 /**
  * Why the structure guard refuses `edit` on `node`, or null when it is allowed. `ancestors` (Move only) =
@@ -59,10 +83,12 @@ interface RoleLike { role?: string | null }
  */
 export function structureRefusal(node: RoleLike | null | undefined, edit: StructureEdit, ancestors: ReadonlyArray<RoleLike> = []): StructureRefusal | null {
     const spec = node?.role ? COMPOSITE_ROLE_SPECS[node.role] : undefined;
-    if (!spec?.locked) return null;
-    if (edit === StructureEdit.Delete) return StructureRefusal.LockedPart;
     const parent = ancestors[ancestors.length - 1];
-    return parent?.role === spec.parent ? null : StructureRefusal.LockedPlacement;
+    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;
+    return placed ? null : StructureRefusal.LockedPlacement;
 }
 
 /** True when `node` is a locked part (shown with a lock and no delete in the layer tree). Deleting a whole
@@ -70,3 +96,10 @@ export function structureRefusal(node: RoleLike | null | undefined, edit: Struct
 export function isLockedPart(node: RoleLike | null | undefined): boolean {
     return !!(node?.role && COMPOSITE_ROLE_SPECS[node.role]?.locked);
 }
+
+/** Why `parent` refuses `node` as a child (it takes only certain roles), or null. */
+export function acceptsRefusal(node: RoleLike | null | undefined, parent: RoleLike | null | undefined): StructureRefusal | null {
+    const accepts = parent?.role ? COMPOSITE_ROLE_SPECS[parent.role]?.accepts : undefined;
+    if (!accepts) return null;
+    return node?.role && accepts.includes(node.role) ? null : StructureRefusal.NotAccepted;
+}