@vectoriox/iox-ui 5.37.0 → 5.38.0

package/media-core/index.d.ts

@@ -0,0 +1,277 @@
+import { ConsentCategory, ConsentDecision } from '@vectoriox/iox-ui/consent-core';
+
+/**
+ * VIDEO (CC3 — complex-components plan §7b, board 5). A LEAF type with two sources:
+ * - an uploaded FILE renders as a real `<video>` (poster, `preload="metadata"`, captions, controls);
+ * - a YouTube / Vimeo address is ALWAYS a FACADE (D5): the studio's poster and a play button named after the video,
+ *   behind the site's consent gate (Marketing). The player's `<iframe>` exists only after a click AND a grant —
+ *   never in the server's HTML, never on the builder canvas.
+ *
+ * `planVideo(node, consent)` is the ONE decision — the only code that knows the URL shapes, the embed hosts and the
+ * consent category. Both engine paths and the canvas render from it (`videoInnerHtml`), and the runtime
+ * (`video-runtime.ts`) builds the player's address from the same plan.
+ */
+declare const VIDEO_NODE_TYPE = "Video";
+declare enum VideoSource {
+    File = "file",
+    YouTube = "youtube",
+    Vimeo = "vimeo"
+}
+declare enum VideoMode {
+    /** In the page, with the player's controls. */
+    Inline = "inline",
+    /** Muted, looped, no controls, an always-visible pause button (WCAG 2.2.2) — an uploaded file only. */
+    Background = "background"
+}
+/** The node's traits (Bindings ▸ Media · Behaviour · Accessibility · Privacy). */
+declare enum VideoTrait {
+    /** Not `source`: across the builder `source` names a DATA source (a Repeater's, a Slider's). */
+    Source = "videoSource",
+    Src = "src",
+    Poster = "poster",
+    Mode = "mode",
+    Autoplay = "autoplay",
+    Title = "title",
+    Captions = "captions",
+    CaptionsLang = "captionsLang",
+    Consent = "consentCategory"
+}
+/** What a plan renders. */
+declare enum VideoKind {
+    /** An uploaded file: a real `<video>`. */
+    File = "file",
+    /** YouTube / Vimeo: poster + play, the player loaded on a click after consent. */
+    Facade = "facade",
+    /** No address yet: the poster blank (DS3) and nothing to play. */
+    Empty = "empty"
+}
+/** A recognised embed: which provider, its video id and (Vimeo, unlisted) its privacy hash. */
+interface VideoRef {
+    source: VideoSource.YouTube | VideoSource.Vimeo;
+    id: string;
+    hash?: string;
+}
+declare const VIDEO_PROVIDER_LABEL: Readonly<Record<VideoRef['source'], string>>;
+/** Who the visitor's IP address and cookies go to, named in the consent prompt. */
+declare const VIDEO_PROVIDER_COMPANY: Readonly<Record<VideoRef['source'], string>>;
+/** The two hosts a player ever loads from — youtube-nocookie and Vimeo's player (with Do Not Track). */
+declare const VIDEO_EMBED_ORIGINS: ReadonlyArray<string>;
+/** The embed a pasted address names — a YouTube or Vimeo watch, share, embed or short link — or null. */
+declare function parseVideoUrl(raw: string | null | undefined): VideoRef | null;
+/** The source a node plays: its declared source when it is one, else what its address is. */
+declare function videoSourceOf(src: unknown, declared?: unknown): VideoSource;
+/** The player's address — loaded only after a click and a grant. Autoplays (the visitor just pressed play). */
+declare function videoEmbedUrl(ref: VideoRef): string;
+/** Where the SERVER fetches an embed's thumbnail to store as the studio's own poster (never the visitor). */
+interface VideoThumbnailRequest {
+    /** `image`: the url IS the picture; `oembed`: the url answers JSON whose `thumbnail_url` is the picture. */
+    kind: 'image' | 'oembed';
+    url: string;
+    /** The only hosts the picture itself may come from (the server refuses anything else). */
+    imageHosts: ReadonlyArray<string>;
+}
+declare function videoThumbnailRequest(ref: VideoRef): VideoThumbnailRequest;
+/** A stored poster's object name — one per video, so fetching it again overwrites rather than piles up. */
+declare function videoPosterFileName(ref: VideoRef): string;
+interface VideoNodeLike {
+    type?: string;
+    props?: Record<string, unknown> | null;
+    traits?: ReadonlyArray<{
+        name?: string;
+        default?: unknown;
+    }> | null;
+}
+/** A content value of a Video node, saved (`props`) or builder (`traits[].default`) shape. */
+declare function videoProp(node: VideoNodeLike | null | undefined, name: VideoTrait | string): unknown;
+/** The consent category an embed waits for — Marketing by default (D5); an uploaded file waits for none. */
+declare function videoConsentCategory(node: VideoNodeLike | null | undefined, source?: VideoSource): ConsentCategory | null;
+interface VideoPlan {
+    kind: VideoKind;
+    source: VideoSource;
+    /** An embed's provider and id (Facade). */
+    ref: VideoRef | null;
+    /** An uploaded file's address (File). */
+    src: string;
+    /** The studio's own poster ('' = the token blank). Never a provider's thumbnail URL. */
+    poster: string;
+    /** The video's name — the play button's accessible name. */
+    title: string;
+    mode: VideoMode;
+    background: boolean;
+    /** Muted autoplay when motion is allowed (the runtime asks; the server never writes `autoplay`). */
+    autoplay: boolean;
+    muted: boolean;
+    loop: boolean;
+    controls: boolean;
+    /** A `.vtt` file ('' = none). */
+    captions: string;
+    captionsLang: string;
+    /** What the facade waits for (null for a file). */
+    consentCategory: ConsentCategory | null;
+    /** The visitor's decision grants it. */
+    granted: boolean;
+    /** The player's address — only when granted (the runtime loads it on a click). */
+    embedUrl: string | null;
+    /** "YouTube" / "Vimeo" ('' for a file). */
+    providerLabel: string;
+}
+/**
+ * The ONE decision for a Video node and a visitor's consent (null = none recorded — the server always passes null,
+ * so its HTML is always the facade). A poster that is a provider's thumbnail URL is dropped: the poster is the
+ * studio's own image (or the thumbnail the server fetched and stored for it), never a request to a third party.
+ */
+declare function planVideo(node: VideoNodeLike | null | undefined, consent: ConsentDecision | null): VideoPlan;
+/** A poster served by the video's provider — a request to a third party before consent, so it never renders. */
+declare function isThirdPartyPoster(url: string): boolean;
+/**
+ * The words the renderer draws (board 5; Q7: the consent prompt is NOT an editable part — its words are the
+ * consent vocabulary's, one source, translated). English and Hebrew; the page's `lang` picks.
+ */
+interface VideoWords {
+    /** The play button's name: the video's title and its provider. */
+    play(title: string, provider: string): string;
+    /** The play button's name with no title. */
+    playUntitled(provider: string): string;
+    pauseBackground: string;
+    playBackground: string;
+    /** The consent prompt (a group): its name, its lead and its body. */
+    promptLabel: string;
+    promptLead(provider: string): string;
+    promptBody(company: string): string;
+    /** The same prompt where the player is narrow (board 5's phone): one shorter sentence, its lead in bold. */
+    promptCompactLead(provider: string): string;
+    promptCompactBody: string;
+    allow: string;
+    settings: string;
+}
+declare const VIDEO_WORDS: Readonly<Record<'en' | 'he', VideoWords>>;
+/** The words for a page language (`he`, `he-IL` → Hebrew; anything else → English). */
+declare function videoWords(lang?: string | null): VideoWords;
+/** The play button's accessible name. */
+declare function videoPlayLabel(plan: VideoPlan, words?: VideoWords): string;
+declare enum VideoClass {
+    Root = "iox-video",
+    Poster = "iox-video__poster",
+    Play = "iox-video__play",
+    Badge = "iox-video__badge",
+    Media = "iox-video__media",
+    Frame = "iox-video__frame",
+    Toggle = "iox-video__toggle",
+    Consent = "iox-video__consent",
+    ConsentText = "iox-video__consent-text",
+    /** The prompt's text on a wide player / on a narrow one (a container query shows one). */
+    ConsentWide = "iox-video__consent-wide",
+    ConsentCompact = "iox-video__consent-compact",
+    ConsentRow = "iox-video__consent-row",
+    Allow = "iox-video__allow",
+    Settings = "iox-video__settings"
+}
+declare enum VideoAttribute {
+    /** On the node element: its kind (`file` · `facade` · `empty`) — what the runtime attaches to. */
+    Root = "data-iox-video",
+    Source = "data-iox-video-source",
+    Id = "data-iox-video-id",
+    Hash = "data-iox-video-hash",
+    Mode = "data-iox-video-mode",
+    Autoplay = "data-iox-video-autoplay",
+    Consent = "data-iox-video-consent",
+    Title = "data-iox-video-title",
+    /** The poster is the token blank (no image): the shared CSS fills it with `surface-2`. */
+    PosterEmpty = "data-iox-video-poster-empty",
+    /** The player is loaded (after the click and the grant). */
+    Playing = "data-iox-video-playing",
+    /** The consent prompt is showing. */
+    Asking = "data-iox-video-asking"
+}
+declare enum VideoIcon {
+    Play = "ph-fill ph-play",
+    Pause = "ph-fill ph-pause"
+}
+/** The attributes the node's own element carries (both engine paths, the canvas). */
+declare function videoRootAttributes(plan: VideoPlan): Record<string, string>;
+interface VideoMarkupOptions {
+    /** HTML-escape an attribute or text value. */
+    esc: (value: string) => string;
+    /** The builder canvas: the poster ONLY — no `<video>`, no player, nothing that loads or takes a click. */
+    canvas?: boolean;
+    words?: VideoWords;
+}
+/** The element's inner markup. The server's HTML for a facade holds no `<iframe>` and requests nothing from
+ *  the provider: only the studio's poster, the play button and the (hidden) consent prompt. */
+declare function videoInnerHtml(plan: VideoPlan, options: VideoMarkupOptions): string;
+/** Serialise attributes for a string renderer (a present boolean attribute is written bare). */
+declare function serializeVideoAttributes(attrs: Readonly<Record<string, string>>, esc: (value: string) => string): string;
+
+/**
+ * The Video's RUNTIME (CC3, board 5) — DOM only, ONE copy for both engine paths (the component path attaches it from
+ * its component, the string path from the page's interaction service; `attachVideoAt` is idempotent). It reads the
+ * markup `videoInnerHtml` writes. The builder canvas never attaches it (the canvas shows the poster only).
+ *
+ * - FACADE: play → the visitor's consent grants the category → the player's `<iframe>` replaces the poster, focused,
+ *   autoplaying (the visitor just pressed play). Not granted → the consent prompt: "Allow and play" grants the
+ *   category in the site's ONE consent record (the banner and its preferences read the same cookie) and plays;
+ *   "Privacy settings" opens the site's own preferences dialog.
+ * - FILE: the play button starts the `<video>`; muted autoplay only when motion is allowed.
+ * - BACKGROUND: muted and looped; it plays only when motion is allowed (never under reduced motion), and its
+ *   pause button is always there (WCAG 2.2.2).
+ */
+/** Ask the page to record a category the visitor granted (cancelable: the site's consent service handles it). */
+declare const CONSENT_GRANT_EVENT = "iox-consent-grant";
+/** Ask the page to open its consent preferences (cancelable: handled = a dialog opened). */
+declare const CONSENT_PREFERENCES_EVENT = "iox-consent-preferences";
+interface ConsentGrantDetail {
+    category: ConsentCategory;
+}
+/** How the runtime reads and writes the visitor's ONE consent record — the page's transport. */
+interface ConsentTransport {
+    read(): ConsentDecision | null;
+    /** Record the category as granted (synchronously, before the player loads). */
+    grant(category: ConsentCategory): void;
+    /** Open the site's privacy preferences; false when the page has none. */
+    openPreferences(): boolean;
+}
+/** The cookie the consent record lives in, read from a document. */
+declare function readConsentRecord(doc: Document): ConsentDecision | null;
+/**
+ * The default transport: the page's own consent service answers the events (the engine records the decision, tells
+ * Consent Mode, re-syncs the banner's switches); a page with no such service (the admin's Preview) records the cookie
+ * itself, through the same consent-core decision, so the record is the same shape either way.
+ */
+declare function documentConsentTransport(doc: Document): ConsentTransport;
+interface VideoRuntimeOptions {
+    consent?: ConsentTransport;
+    /** True to stop motion (default: the visitor's reduced-motion setting). */
+    reducedMotion?: () => boolean;
+    words?: VideoWords;
+}
+/** The embed a facade root names (its provider, id and hash attributes). */
+declare function videoRefOf(root: Element): VideoRef | null;
+declare class VideoRuntime {
+    readonly root: HTMLElement;
+    private readonly cleanups;
+    private readonly consent;
+    private readonly reduced;
+    private readonly words;
+    private readonly doc;
+    constructor(root: HTMLElement, options?: VideoRuntimeOptions);
+    destroy(): void;
+    /** The category a facade waits for (Marketing unless the node named another). */
+    private get category();
+    private on;
+    private attachFacade;
+    /** Play pressed: the player when the category is granted, else the consent prompt. */
+    requestPlay(): void;
+    /** The player — created only now, after the click and the grant. */
+    loadPlayer(): void;
+    private attachFile;
+    private attachBackground;
+}
+/** Run the video at `el` (a `[data-iox-video]` element) once; null when it is not one or already runs. */
+declare function attachVideoAt(el: HTMLElement | null | undefined, options?: VideoRuntimeOptions): VideoRuntime | null;
+/** Every video under `container` that is not running yet (the string path's globals and pages). */
+declare function attachVideos(container: ParentNode, options?: VideoRuntimeOptions): VideoRuntime[];
+/** The runtime already running at `el`, if any. */
+declare function videoRuntimeOf(el: Element | null | undefined): VideoRuntime | null;
+
+export { CONSENT_GRANT_EVENT, CONSENT_PREFERENCES_EVENT, VIDEO_EMBED_ORIGINS, VIDEO_NODE_TYPE, VIDEO_PROVIDER_COMPANY, VIDEO_PROVIDER_LABEL, VIDEO_WORDS, VideoAttribute, VideoClass, VideoIcon, VideoKind, VideoMode, VideoRuntime, VideoSource, VideoTrait, attachVideoAt, attachVideos, documentConsentTransport, isThirdPartyPoster, parseVideoUrl, planVideo, readConsentRecord, serializeVideoAttributes, videoConsentCategory, videoEmbedUrl, videoInnerHtml, videoPlayLabel, videoPosterFileName, videoProp, videoRefOf, videoRootAttributes, videoRuntimeOf, videoSourceOf, videoThumbnailRequest, videoWords };
+export type { ConsentGrantDetail, ConsentTransport, VideoMarkupOptions, VideoNodeLike, VideoPlan, VideoRef, VideoRuntimeOptions, VideoThumbnailRequest, VideoWords };

package/media-core/package.json

@@ -0,0 +1,3 @@
+{
+  "module": "../fesm2022/vectoriox-iox-ui-media-core.mjs"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "5.37.0",
+  "version": "5.38.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",
@@ -43,6 +43,10 @@
       "types": "./generation-core/index.d.ts",
       "default": "./fesm2022/vectoriox-iox-ui-generation-core.mjs"
     },
+    "./media-core": {
+      "types": "./media-core/index.d.ts",
+      "default": "./fesm2022/vectoriox-iox-ui-media-core.mjs"
+    },
     "./seo-core": {
       "types": "./seo-core/index.d.ts",
       "default": "./fesm2022/vectoriox-iox-ui-seo-core.mjs"

package/src/actions-core/element-actions.ts

@@ -1,4 +1,4 @@
-import { AccordionRole, CompositeItemAction, DisclosureRole } from '@vectoriox/iox-ui/composite-core';
+import { AccordionRole, CompositeItemAction, DisclosureRole, SLIDE_TO_ROW } from '@vectoriox/iox-ui/composite-core';
 
 import { ActionDescriptor } from './action.model';
 
@@ -45,8 +45,10 @@ export const ELEMENT_ACTION_DESCRIPTORS: readonly ActionDescriptor[] = Object.fr
       target: { required: false } },
 
     // ── Dialog (A1 — needs the Dialog component, A1b) ───────────────────────
+    // CC3 (board 6): "Open at the clicked item" — `slideTo: 'row'` opens a lightbox at the clicked thumbnail's slide.
     { type: 'openDialog',   labelKey: 'builder.actions.openDialog',   kind: 'instant', group: 'dialog', builderBehaviour: 'run',
-      target: { required: true, types: ['Dialog'] } },
+      target: { required: true, types: ['Dialog'] },
+      params: [{ name: 'slideTo', type: 'string', label: 'builder.actions.params.slideTo', options: [{ value: SLIDE_TO_ROW, labelKey: 'builder.actions.params.slideToRow' }] }] },
     { type: 'closeDialog',  labelKey: 'builder.actions.closeDialog',  kind: 'instant', group: 'dialog', builderBehaviour: 'run',
       target: { required: true, types: ['Dialog'] } },
     { type: 'toggleDialog', labelKey: 'builder.actions.toggleDialog', kind: 'instant', group: 'dialog', builderBehaviour: 'run',
@@ -136,6 +138,11 @@ export const ITEM_ACTION_TYPES: Readonly<Record<string, CompositeItemAction>> =
 });
 
 /** The item action an action type runs, or null when it is not one. */
+/** True when an `openDialog` action opens its dialog at the clicked row's slide (CC3 "Open at the clicked item"). */
+export function opensAtClickedItem(action: { type?: string; params?: Record<string, unknown> | null } | null | undefined): boolean {
+    return action?.type === 'openDialog' && action.params?.['slideTo'] === SLIDE_TO_ROW;
+}
+
 export function itemActionOf(type: string | null | undefined): CompositeItemAction | null {
     return (type && ITEM_ACTION_TYPES[type]) || null;
 }

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;

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

@@ -15,3 +15,6 @@ export * from './disclosure';
 export * from './badge';
 export * from './card';
 export * from './structure';
+export * from './slider';
+export * from './slider-runtime';
+export * from './lightbox';