@vectoriox/iox-ui 5.36.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.36.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/action.model.ts

@@ -11,7 +11,7 @@ export type ActionKind = 'animated' | 'instant' | 'server';
 
 /** Picker grouping. Flat lists die at ~10 entries; the group is data, never a second list. */
 export type ActionGroup =
-    | 'motion' | 'visibility' | 'navigate' | 'dialog' | 'form' | 'data' | 'consent' | 'service';
+    | 'motion' | 'visibility' | 'navigate' | 'dialog' | 'item' | 'form' | 'data' | 'consent' | 'service';
 
 /**
  * What a step does inside the live builder canvas (the canvas RUNS interactions):
@@ -29,10 +29,12 @@ export interface ActionParamSpec {
     options?: readonly { value: string; labelKey: string }[];
 }
 
-/** Does this action point at another node — and may it be any node or only certain types? */
+/** Does this action point at another node — and may it be any node, or only certain types / composite roles? */
 export interface ActionTargetSpec {
     required: boolean;
     types?: string[];
+    /** Only nodes playing one of these composite roles (`openItem` targets an accordion item or a disclosure). */
+    roles?: string[];
 }
 
 /**

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

@@ -1,5 +1,10 @@
+import { AccordionRole, CompositeItemAction, DisclosureRole, SLIDE_TO_ROW } from '@vectoriox/iox-ui/composite-core';
+
 import { ActionDescriptor } from './action.model';
 
+/** The items an item action may target: an accordion's item, or a disclosure (its own one item). */
+const ITEM_TARGET_ROLES = [AccordionRole.Item, DisclosureRole.Disclosure];
+
 /**
  * The ELEMENT action catalog (actions plan A1) — what a node can DO, as data. One list feeds the
  * grouped picker, the two interaction engines, and the AI composer's validation (§9: the model
@@ -40,13 +45,25 @@ 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',
       target: { required: true, types: ['Dialog'] } },
 
+    // ── Item (CC2.1 — composite T14): drive an accordion item or a disclosure from anywhere ("See shipping"
+    // opens FAQ item 3). The canvas RUNS them, like the dialog actions: it is the same runtime, and an item you
+    // cannot open from the button is a button you cannot design.
+    { type: 'openItem',   labelKey: 'builder.actions.openItem',   kind: 'instant', group: 'item', builderBehaviour: 'run',
+      target: { required: true, roles: ITEM_TARGET_ROLES } },
+    { type: 'closeItem',  labelKey: 'builder.actions.closeItem',  kind: 'instant', group: 'item', builderBehaviour: 'run',
+      target: { required: true, roles: ITEM_TARGET_ROLES } },
+    { type: 'toggleItem', labelKey: 'builder.actions.toggleItem', kind: 'instant', group: 'item', builderBehaviour: 'run',
+      target: { required: true, roles: ITEM_TARGET_ROLES } },
+
     // ── Form (A1 — Tier A; the submit transport is the forms module's, I7 of its plan) ──
     // simulate in the CANVAS: the builder's Form is a container twin with no real <form>,
     // so there is nothing honest to run — the live engine requestSubmit()s the real one.
@@ -112,6 +129,24 @@ export const SERVER_ELEMENT_ACTION_TYPES: ReadonlySet<string> =
 export const BEHAVIOUR_ACTION_TYPES: ReadonlySet<string> =
     new Set(['navigate', 'scrollTo', 'submitForm', 'copyToClipboard']);
 
+/** The item actions' dispatch set (T14) and what each does to its item — the engines branch on it beside
+ *  DIALOG/BEHAVIOUR, and composite-core `runCompositeItemAction` runs it on the target item's own runtime. */
+export const ITEM_ACTION_TYPES: Readonly<Record<string, CompositeItemAction>> = Object.freeze({
+    openItem: CompositeItemAction.Open,
+    closeItem: CompositeItemAction.Close,
+    toggleItem: CompositeItemAction.Toggle,
+});
+
+/** 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;
+}
+
 /** The consent actions' dispatch set (C3) — the engines branch on it beside DIALOG/BEHAVIOUR.
  *  `openConsentPreferences` is dialog-opening by nature and included so ONE branch owns consent. */
 export const CONSENT_ACTION_TYPES: ReadonlySet<string> =
@@ -119,7 +154,7 @@ export const CONSENT_ACTION_TYPES: ReadonlySet<string> =
 
 /** Picker order — most-used groups first, services last (they are the shop window, not the shop). */
 export const ELEMENT_ACTION_GROUP_ORDER: readonly string[] =
-    Object.freeze(['motion', 'visibility', 'navigate', 'dialog', 'form', 'data', 'consent', 'service']);
+    Object.freeze(['motion', 'visibility', 'navigate', 'dialog', 'item', 'form', 'data', 'consent', 'service']);
 
 /** The catalog, grouped and ordered for the picker — one derivation, no hand-kept second list. */
 export function groupedElementActions(): ReadonlyArray<{ group: string; actions: ActionDescriptor[] }> {