@vectoriox/iox-ui 5.36.0 → 5.38.0

package/src/composite-core/composite-node.ts

@@ -37,6 +37,10 @@ export interface CompositeNode extends ElementStyleTarget {
  *  (the builder's `createConfig`, generation-core's `createSerializedNode`), with these props and this
  *  element style. `key` is stable per recipe node — a consumer that needs deterministic ids builds them
  *  from it (generation-core: `<root id>-<key>`). */
+/** `elementStyle: NO_ELEMENT_STYLE` asks for a node that wears NO element style (undefined / null = the type's default,
+ *  as both node factories have always read it): a migrated slider's bare chevrons, a lightbox's slide (CC3). */
+export const NO_ELEMENT_STYLE = '';
+
 export interface CompositeNodeSpec {
     key: string;
     type: string;
@@ -46,6 +50,17 @@ export interface CompositeNodeSpec {
 
 export type CompositeNodeFactory = (spec: CompositeNodeSpec) => CompositeNode;
 
+/** A recipe part: a NEW node (`create`) playing `role` under `label`, with the layout `base` styles its recipe
+ *  gives it — its LOOK is its element style. Shared by every recipe (Accordion, Disclosure). */
+export function makeCompositePart(create: CompositeNodeFactory, spec: CompositeNodeSpec, role: string | null, label: string | undefined,
+    base?: Readonly<Record<string, string>>): CompositeNode {
+    const node = create(spec);
+    if (role) node.role = role;
+    if (label) node.label = label;
+    if (base) writeStyles(node, base);
+    return node;
+}
+
 const usesTraits = (node: CompositeNode): boolean => Array.isArray(node.traits);
 
 /** A content trait's value — `traits[].default` on a builder node, `props[name]` on a saved one. */

package/src/composite-core/disclosure.ts

@@ -0,0 +1,125 @@
+import { accordionBehaviour, AccordionDefaultOn, AccordionIcon, buildCompositeIcon, CompositeBehaviourTrait, ITEM_OPEN_STATE } from './accordion';
+import { DisclosureRole } from './composite-kinds';
+import { CompositeNode, CompositeNodeFactory, makeCompositePart, writeProp, writeStyles } from './composite-node';
+
+/**
+ * DISCLOSURE / "Read more" (CC2.1 — composite T21). Not a component: a recipe of ordinary nodes on the
+ * ACCORDION's machinery — a disclosure is a one-item accordion whose root is its item, so it runs the same
+ * state machine, attribute planners and runtime (`accordion-runtime.ts`), on the canvas and on the live site.
+ *
+ *   Container `box`                         role disclosure          itemKey k1 · trait defaultOn (none | first)
+ *   ├─ LinkedContainer `accordion-trigger`  role disclosure.trigger  → <button aria-expanded aria-controls>
+ *   │   ├─ Text `body` (span)               role disclosure.more     "Read more" — hidden while open
+ *   │   ├─ Text `body` (span)               role disclosure.less     "Read less" — shown only while open
+ *   │   └─ Icon `icon`                      role disclosure.icon     Item open → turns
+ *   └─ Container `accordion-panel`          role disclosure.panel    inside a hidden="until-found" track
+ *       └─ Text `body`                      the rest of the text
+ *
+ * The words swap through the ordinary Item open state (`trigger-on` → the root), so the label an author sees on
+ * the canvas is the one the visitor gets, with no script and nothing to break. The look is the accordion's own
+ * element styles (no `disclosure-*` contract: the boards draw none) — the header's ink, hover ink and focus ring;
+ * the panel's padding and muted ink — and the words are `body` text: the site's body type, with `color: inherit`, so
+ * the toggle's ink and its hover ink reach them.
+ */
+
+export interface DisclosureWords {
+    more: string;
+    less: string;
+    body: string;
+}
+
+/** The words a fresh disclosure starts with — generic, the author's to replace. */
+export const DISCLOSURE_WORDS: Readonly<DisclosureWords> = {
+    more: 'Read more',
+    less: 'Read less',
+    body: 'Write the rest of the story here. It stays out of the way until someone asks for it.',
+};
+
+export interface DisclosureOptions {
+    words?: Partial<DisclosureWords>;
+    /** Open on first render (default: closed). */
+    open?: boolean;
+    icon?: AccordionIcon;
+}
+
+/** A disclosure's one item key — its root IS its item. */
+export const DISCLOSURE_ITEM_KEY = 'k1';
+
+enum Type {
+    Container = 'Container',
+    LinkedContainer = 'LinkedContainer',
+    Text = 'Text',
+}
+
+enum Style {
+    Root = 'box',
+    Trigger = 'accordion-trigger',
+    Word = 'body',
+    Panel = 'accordion-panel',
+    Body = 'body',
+}
+
+const ZERO_BOX = '0px 0px 0px 0px';
+const HIDDEN = 'none';
+const INHERIT = 'inherit';
+/** A word is a flex item of the toggle — `block` (never `inline`: the compiler drops a value equal to the CSS initial,
+ *  and the Text's own default would come back in its place). */
+const SHOWN = 'block';
+
+/** What each part holds — layout only; its LOOK is its element style. The trigger sizes to its words (a button in
+ *  the flow, not a full-width header row — `fit-content` keeps it from stretching) and the panel spans the root. The
+ *  trigger is `flex`, not `inline-flex`: it is a flex item of the root, which blockifies it on the site anyway. */
+const PART_BASE: Readonly<Record<string, Readonly<Record<string, string>>>> = {
+    [DisclosureRole.Disclosure]: { display: 'flex', flexDirection: 'column', width: '100%', minHeight: 'auto', height: 'auto' },
+    // The toggle reads the text around it (the page's body type, through the root) — a LinkedContainer is born with
+    // its own literal font, which an accordion's heading masks and a disclosure's words would show.
+    [DisclosureRole.Trigger]: {
+        display: 'flex', alignItems: 'center', gap: '8px', width: 'fit-content', minHeight: 'auto', height: 'auto', textAlign: 'start', cursor: 'pointer',
+        fontFamily: INHERIT, fontSize: INHERIT, fontWeight: INHERIT, lineHeight: INHERIT,
+    },
+    // A word is just its words: none of a Text's own box (its type's 10px padding, its full width) — the toggle's
+    // padding is the click target.
+    [DisclosureRole.More]: { display: SHOWN, margin: ZERO_BOX, padding: ZERO_BOX, width: 'auto' },
+    [DisclosureRole.Less]: { display: HIDDEN, margin: ZERO_BOX, padding: ZERO_BOX, width: 'auto' },
+    [DisclosureRole.Panel]: { display: 'block', width: '100%', minHeight: 'auto', height: 'auto' },
+};
+const BODY_BASE: Readonly<Record<string, string>> = { margin: ZERO_BOX, padding: ZERO_BOX, minHeight: 'auto' };
+
+function make(create: CompositeNodeFactory, key: string, type: string, role: DisclosureRole | null, style: string,
+    props: Record<string, unknown>, label: string): CompositeNode {
+    return makeCompositePart(create, { key, type, props, elementStyle: style }, role, label, role ? PART_BASE[role] : undefined);
+}
+
+/** One of the trigger's two words: shown while the disclosure is closed (`more`) or open (`less`). */
+function buildWord(create: CompositeNodeFactory, role: DisclosureRole.More | DisclosureRole.Less, words: string, rootId?: string): CompositeNode {
+    const node = make(create, role === DisclosureRole.More ? 'more' : 'less', Type.Text, role, Style.Word, { content: words, tag: 'span' }, 'Text');
+    node.stateStyles = { ...(node.stateStyles ?? {}), [ITEM_OPEN_STATE]: { display: role === DisclosureRole.More ? HIDDEN : SHOWN } };
+    if (rootId) node.stateTriggers = { ...(node.stateTriggers ?? {}), [ITEM_OPEN_STATE]: rootId };
+    return node;
+}
+
+/** A fresh Disclosure: "Read more" opens the text below and reads "Read less" while it is open; closed by default. */
+export function buildDisclosureRecipe(create: CompositeNodeFactory, options: DisclosureOptions = {}): CompositeNode {
+    const words = { ...DISCLOSURE_WORDS, ...(options.words ?? {}) };
+    const root = make(create, 'disclosure', Type.Container, DisclosureRole.Disclosure, Style.Root, {}, 'Disclosure');
+    root.itemKey = DISCLOSURE_ITEM_KEY;
+    writeProp(root, CompositeBehaviourTrait.DefaultOn, options.open ? AccordionDefaultOn.First : AccordionDefaultOn.None);
+    const icon = options.icon ?? AccordionIcon.Chevron;
+    const trigger = make(create, 'trigger', Type.LinkedContainer, DisclosureRole.Trigger, Style.Trigger, {}, 'Toggle');
+    trigger.children = [
+        buildWord(create, DisclosureRole.More, words.more, root.id),
+        buildWord(create, DisclosureRole.Less, words.less, root.id),
+        ...(icon === AccordionIcon.None ? [] : [buildCompositeIcon(create, 'icon', icon, root.id, DisclosureRole.Icon)]),
+    ];
+    const panel = make(create, 'panel', Type.Container, DisclosureRole.Panel, Style.Panel, {}, 'Panel');
+    const body = make(create, 'body', Type.Text, null, Style.Body, { content: words.body, tag: 'p' }, 'Text');
+    writeStyles(body, BODY_BASE);
+    panel.children = [body];
+    root.children = [trigger, panel];
+    return root;
+}
+
+/** Behaviour ▸ Open by default (a disclosure: on or off). */
+export function disclosureOpenByDefault(root: CompositeNode): boolean {
+    return accordionBehaviour(root).defaultOn !== AccordionDefaultOn.None;
+}

package/src/composite-core/lightbox.ts

@@ -0,0 +1,192 @@
+import { setColorScheme } from '@vectoriox/iox-ui/design-core';
+
+import { CompositeNode, CompositeNodeFactory, makeCompositePart, NO_ELEMENT_STYLE, readProp, writeProp, writeStyles } from './composite-node';
+import { buildSliderPart, SLIDE_TYPE, SLIDER_TYPE, SliderRole } from './slider';
+
+/**
+ * THE LIGHTBOX (CC3 — complex-components plan §7d, board 6). Not a component: a Dialog holding a Slider bound to the
+ * SAME source as the grid of thumbnails. The one new thing is `openDialog`'s "Open at the clicked item"
+ * (`slideTo: 'row'`): a thumbnail in a repeater row opens the lightbox at ITS slide.
+ *
+ *   Dialog `dialog` · centre · full viewport · Inverse scheme      "Lightbox" (a free-standing Dialog: board A4)
+ *   ├─ ButtonBlock `button-ghost`  "Close"  › Icon ×                click → closeDialog
+ *   └─ SliderContainer  one slide in view · keyboard · the source's rows
+ *       ├─ Previous · Next (slider.prev / slider.next, button-secondary)   hidden on a phone (swipe)
+ *       ├─ SliderSlide › Image `media` (contain, keeps its alt) + Text `small` caption
+ *       └─ Pagination (slider.pagination) — the counter "3 / 6"
+ *
+ * Keyboard ← → are the Slider's Keyboard module; Esc and the focus trap are the `<dialog>`'s; focus returns to the
+ * thumbnail that opened it (the dialog opener's own rule).
+ */
+
+export const SLIDE_TO_ROW = 'row';
+/** The attribute a renderer writes on every repeated row (the context-state provenance, both engine paths, the canvas). */
+export const ROW_INDEX_ATTRIBUTE = 'data-iox-row-idx';
+export const LIGHTBOX_LABEL = 'Lightbox';
+const DIALOG = 'Dialog';
+const REPEATER = 'Repeater';
+const SOURCE = 'source';
+const SOURCE_PATH = 'sourcePath';
+
+export interface LightboxOptions {
+    /** The list the slides come from (the grid's own source). Empty = three manual slides. */
+    source?: string;
+    sourcePath?: string;
+    /** The row field each slide's image and caption read (`item` = the row itself, a bare URL). */
+    imageField?: string;
+    captionField?: string;
+    /** The image's alt binding; '' = decorative (a bare URL row has no words of its own). */
+    altField?: string;
+}
+
+const ZERO = '0px 0px 0px 0px';
+const DIALOG_BASE: Readonly<Record<string, string>> = {
+    width: '100vw', maxWidth: '100vw', height: '100dvh', maxHeight: '100dvh', borderRadius: '0px', padding: '18px 18px 18px 18px',
+    display: 'flex', flexDirection: 'column', gap: '0px',
+};
+/** The top row (board 6): the counter at its start, Close at its end — Close sits above the slider, which rises into
+ *  the row so its counter shares it. */
+const CLOSE_BASE: Readonly<Record<string, string>> = {
+    display: 'flex', alignItems: 'center', justifyContent: 'center', width: '44px', height: '44px', minWidth: '44px',
+    padding: ZERO, margin: ZERO, borderRadius: '999px', alignSelf: 'flex-end', flexShrink: '0', position: 'relative', zIndex: '20',
+};
+const SLIDER_BASE: Readonly<Record<string, string>> = { width: '100%', height: '100%', minHeight: '0px', flexGrow: '1', margin: '-44px 0px 0px 0px' };
+const SLIDE_BASE: Readonly<Record<string, string>> = {
+    width: '100%', height: '100%', aspectRatio: 'auto', display: 'flex', flexDirection: 'column', alignItems: 'center',
+    justifyContent: 'center', gap: '12px', padding: '56px 64px 16px 64px',
+};
+const IMAGE_BASE: Readonly<Record<string, string>> = { width: '100%', height: 'auto', maxHeight: '72dvh', minHeight: '0px', objectFit: 'contain', aspectRatio: '4 / 3', flexShrink: '1' };
+const CAPTION_BASE: Readonly<Record<string, string>> = { textAlign: 'center', margin: ZERO, padding: ZERO, minHeight: 'auto', width: 'auto' };
+/** The counter "3 / 6" sits at the START of the top row, Close at its end (board 6). */
+const COUNTER_BASE: Readonly<Record<string, string>> = { color: 'var(--iox-text-muted)', top: '12px', alignItems: 'flex-start', justifyContent: 'flex-start' };
+/** On a phone the arrows give way to a swipe (board 6, "the arrows hide on touch-only widths"). */
+export const LIGHTBOX_ARROWS_HIDE_AT = 'mobile';
+
+interface WithInteractions { interactions?: unknown[] }
+
+/** A click on `node` runs one instant action on `target`. */
+function onClick(node: CompositeNode, type: string, target: string, params?: Record<string, unknown>): void {
+    (node as WithInteractions).interactions = [{
+        id: `${node.id ?? 'node'}-click`, trigger: 'click',
+        actions: [{ type, target, duration: 0, delay: 0, easing: 'ease', ...(params ? { params } : {}) }],
+    }];
+}
+
+/** A binding of `prop` to the row field `field` of `source` (`item` = the row itself). */
+function bindRow(node: CompositeNode, prop: string, source: string, field: string): void {
+    const bindings = ((node as { bindings?: unknown[] }).bindings ?? []).filter((b) => (b as { prop?: string }).prop !== prop);
+    bindings.push({ prop, source, path: field === 'item' ? '' : field });
+    (node as { bindings?: unknown[] }).bindings = bindings;
+}
+
+function buildSlide(create: CompositeNodeFactory, key: string, options: LightboxOptions, rowAlias: string | null): CompositeNode {
+    const slide = makeCompositePart(create, { key, type: SLIDE_TYPE, props: {}, elementStyle: NO_ELEMENT_STYLE }, null, 'Slide', SLIDE_BASE);
+    const image = makeCompositePart(create, { key: `${key}-image`, type: 'Image', props: { src: '', alt: '' }, elementStyle: 'media' }, null, 'Image', IMAGE_BASE);
+    const caption = makeCompositePart(create, { key: `${key}-caption`, type: 'Text', props: { content: 'Caption', tag: 'p' }, elementStyle: 'small' }, null, 'Caption', CAPTION_BASE);
+    if (rowAlias) {
+        bindRow(image, 'src', rowAlias, options.imageField ?? 'item');
+        if (options.altField) bindRow(image, 'alt', rowAlias, options.altField);
+        if (options.captionField) bindRow(caption, 'content', rowAlias, options.captionField);
+    }
+    slide.children = options.captionField || !rowAlias ? [image, caption] : [image];
+    return slide;
+}
+
+/** A fresh lightbox: the Dialog, its Close part and the Slider (bound to `source`, or three manual slides). */
+export function buildLightboxRecipe(create: CompositeNodeFactory, options: LightboxOptions = {}): CompositeNode {
+    const dialog = makeCompositePart(create, { key: 'lightbox', type: DIALOG, props: {}, elementStyle: 'dialog' }, null, LIGHTBOX_LABEL, DIALOG_BASE);
+    writeProp(dialog, 'placement', 'center');
+    writeProp(dialog, 'closeOnBackdrop', true);
+    writeProp(dialog, 'showCloseButton', false);
+    writeProp(dialog, 'ariaLabel', 'Gallery');
+    setColorScheme(dialog, 'inverse');
+
+    const close = makeCompositePart(create, { key: 'close', type: 'ButtonBlock', props: { tag: 'button', type: 'button', ariaLabel: 'Close' }, elementStyle: 'button-ghost' }, null, 'Close', CLOSE_BASE);
+    close.children = [makeCompositePart(create, { key: 'close-icon', type: 'Icon', props: { iconClass: 'ph ph-x' }, elementStyle: 'icon' }, null, 'Icon', { fontSize: '22px', color: 'inherit' })];
+    onClick(close, 'closeDialog', dialog.id ?? '');
+
+    const slider = makeCompositePart(create, { key: 'slider', type: SLIDER_TYPE, props: {}, elementStyle: NO_ELEMENT_STYLE }, null, 'Slider', SLIDER_BASE);
+    for (const [name, value] of Object.entries({
+        slidesPerView: 1, spaceBetween: 0, loop: 'off', enableNavigation: true, enablePagination: true, paginationType: 'fraction',
+        enableKeyboard: true, ariaLabel: 'Gallery', limit: 50,
+    })) writeProp(slider, name, value);
+    const rowAlias = options.source ? lastSegment(options.sourcePath) || options.source : null;
+    if (options.source) {
+        writeProp(slider, SOURCE, options.source);
+        if (options.sourcePath) writeProp(slider, SOURCE_PATH, options.sourcePath);
+    }
+    const prev = buildSliderPart(create, SliderRole.Prev);
+    const next = buildSliderPart(create, SliderRole.Next);
+    for (const arrow of [prev, next]) {
+        const layers = { ...(arrow.responsive ?? {}) };
+        layers[LIGHTBOX_ARROWS_HIDE_AT] = { styleProps: { display: 'none' } };
+        arrow.responsive = layers;
+    }
+    const counter = buildSliderPart(create, SliderRole.Pagination);
+    counter.label = 'Counter';
+    writeStyles(counter, COUNTER_BASE);
+    const slides = rowAlias ? [buildSlide(create, 'slide', options, rowAlias)] : [1, 2, 3].map(n => buildSlide(create, `slide-${n}`, options, null));
+    slider.children = [prev, next, ...slides, counter];
+    dialog.children = [close, slider];
+    return dialog;
+}
+
+const lastSegment = (path: string | undefined): string => (path ? String(path).split('.').filter(Boolean).pop() ?? '' : '');
+
+// ── "Open at the clicked item" ─────────────────────────────────────────────────────────────────────
+
+export interface RepeatSource {
+    source: string;
+    path: string;
+}
+
+/** What a Repeater (its `source` binding) or a bound Slider (its `source` / `sourcePath` traits) repeats over. */
+export function repeatSourceOf(node: CompositeNode | null | undefined): RepeatSource | null {
+    if (!node || (node.type !== REPEATER && node.type !== SLIDER_TYPE)) return null;
+    const binding = ((node as { bindings?: Array<{ prop?: string; source?: string; path?: string }> }).bindings ?? []).find(b => b?.prop === SOURCE);
+    if (binding?.source) return { source: binding.source, path: binding.path ?? '' };
+    const source = readProp(node, SOURCE);
+    if (typeof source !== 'string' || !source) return null;
+    const path = readProp(node, SOURCE_PATH);
+    return { source, path: typeof path === 'string' ? path : '' };
+}
+
+export function sameRepeatSource(a: RepeatSource | null, b: RepeatSource | null): boolean {
+    return !!a && !!b && a.source === b.source && (a.path ?? '') === (b.path ?? '');
+}
+
+/** The Slider a lightbox Dialog holds (the first one, depth first), or null. */
+export function lightboxSliderOf(dialog: CompositeNode | null | undefined): CompositeNode | null {
+    for (const child of dialog?.children ?? []) {
+        if (child.type === SLIDER_TYPE) return child;
+        const below = lightboxSliderOf(child);
+        if (below) return below;
+    }
+    return null;
+}
+
+/** The repeated rows the element is in: the nearest Repeater or bound Slider among its ancestors (`path` = root → the
+ *  element, inclusive). */
+export function rowSourceOf(path: ReadonlyArray<CompositeNode>): RepeatSource | null {
+    for (let i = path.length - 2; i >= 0; i--) {
+        const source = repeatSourceOf(path[i]);
+        if (source) return source;
+    }
+    return null;
+}
+
+/**
+ * Interactions ▸ openDialog ▸ "Open at the clicked item" is offered only when it can work (board 9): the clicked
+ * element sits in a repeater row AND the target Dialog holds a Slider bound to the same source.
+ */
+export function canOpenAtClickedItem(ownerPath: ReadonlyArray<CompositeNode>, dialog: CompositeNode | null | undefined): boolean {
+    if (!dialog || dialog.type !== DIALOG) return false;
+    return sameRepeatSource(rowSourceOf(ownerPath), repeatSourceOf(lightboxSliderOf(dialog)));
+}
+
+/** The repeated row an element sits in (its row index), 0 when it is in none (the canvas' template row). */
+export function rowIndexOf(el: Element | null | undefined): number {
+    const row = el?.closest?.(`[${ROW_INDEX_ATTRIBUTE}]`);
+    const index = Number(row?.getAttribute(ROW_INDEX_ATTRIBUTE));
+    return Number.isInteger(index) && index >= 0 ? index : 0;
+}

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

@@ -3,12 +3,18 @@
  * plan §3a). FRAMEWORK-FREE: the builder, the SSR engine and iox-cms (generation-core's composer, the site
  * build) read the same recipes, roles and structure rules. Card v2 + Badge / Chip (T23 / T25) are the
  * first; the Accordion (CC2) adds the first composite RUNTIME (accordion-runtime.ts — DOM only, no
- * framework); Tabs join with their own phase.
+ * framework), which the Disclosure (CC2.1) runs too — a one-item accordion whose root is its item; Tabs join with
+ * their own phase.
  * ⚠️ Consumers wire the usual trio — ng-package raw-ts assets, jest moduleNameMapper, tsconfig paths.
  */
 export * from './composite-node';
+export * from './composite-kinds';
 export * from './accordion';
 export * from './accordion-runtime';
+export * from './disclosure';
 export * from './badge';
 export * from './card';
 export * from './structure';
+export * from './slider';
+export * from './slider-runtime';
+export * from './lightbox';

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