@vectoriox/iox-ui 5.37.0 → 5.39.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.39.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,9 +1,11 @@
-import { AccordionRole, CompositeItemAction, DisclosureRole } from '@vectoriox/iox-ui/composite-core';
+import { AccordionRole, CompositeItemAction, DisclosureRole, SLIDE_TO_ROW, TabsRole } 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];
+/** Open also takes a TAB (CC4a): it turns it on. A Tabs always shows one, so Close and Toggle never aim at one. */
+const OPEN_TARGET_ROLES = [...ITEM_TARGET_ROLES, TabsRole.Trigger];
 
 /**
  * The ELEMENT action catalog (actions plan A1) — what a node can DO, as data. One list feeds the
@@ -45,8 +47,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',
@@ -56,7 +60,7 @@ export const ELEMENT_ACTION_DESCRIPTORS: readonly ActionDescriptor[] = Object.fr
     // 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 } },
+      target: { required: true, roles: OPEN_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',
@@ -136,6 +140,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/accordion-runtime.ts

@@ -3,7 +3,7 @@ import {
     ACCORDION_DEFAULT_ONS, closeAccordionItem, COMPOSITE_ATTRIBUTE, DEFAULT_ON_ATTRIBUTE, hasLabelledRegion, initialAccordionOpen, ITEM_KEY_ATTRIBUTE,
     MULTIPLE_ATTRIBUTE, nextAccordionState, ON_ATTRIBUTE, openAccordionItem, SCOPE_ATTRIBUTE, UNTIL_FOUND,
 } from './accordion';
-import { CompositeKind } from './composite-kinds';
+import { COMPOSITE_KIND_ROLES, CompositeKind, ToggleCompositeKind } from './composite-kinds';
 
 /**
  * The Accordion's RUNTIME (CC2) — ONE copy, DOM only, for the builder canvas and the live site (both engine
@@ -33,7 +33,7 @@ export const ITEM_ON_EVENT = 'iox-item-on';
 export const ITEM_OFF_EVENT = 'iox-item-off';
 
 const KIND_ROOT = (kind: CompositeKind) => `[${COMPOSITE_ATTRIBUTE}="${kind}"]`;
-const ROOT_SELECTOR = Object.values(CompositeKind).map(KIND_ROOT).join(', ');
+const ROOT_SELECTOR = (Object.keys(COMPOSITE_KIND_ROLES) as ToggleCompositeKind[]).map(KIND_ROOT).join(', ');
 /** An accordion's items are its `.iox-role-accordion-item` children; a disclosure is its own item. */
 const ACCORDION_ITEM_SELECTOR = '.iox-role-accordion-item';
 const ITEM_SELECTOR = `${ACCORDION_ITEM_SELECTOR}, ${KIND_ROOT(CompositeKind.Disclosure)}`;
@@ -75,7 +75,7 @@ const kindOf = (root: Element): CompositeKind =>
     root.getAttribute(COMPOSITE_ATTRIBUTE) === CompositeKind.Disclosure ? CompositeKind.Disclosure : CompositeKind.Accordion;
 
 /** The composite root whose items an item belongs to: a disclosure is its own root. */
-function rootOfItem(item: HTMLElement): HTMLElement | null {
+export function accordionRootOfItem(item: HTMLElement): HTMLElement | null {
     return kindOf(item) === CompositeKind.Disclosure && item.matches(KIND_ROOT(CompositeKind.Disclosure)) ? item : closestAccordion(item.parentElement);
 }
 
@@ -421,18 +421,6 @@ export enum CompositeItemAction {
     Toggle = 'toggle',
 }
 
-/**
- * Run an item action on the element of an ITEM (an accordion item, or a disclosure) — the `openItem` /
- * `closeItem` / `toggleItem` interaction actions, on the canvas and on the live site through this one function.
- * Returns whether the item shows open afterwards, or null when `el` is in no running composite.
- */
-export function runCompositeItemAction(el: Element | null | undefined, action: CompositeItemAction): boolean | null {
-    const item = closestAccordionItem(el);
-    const runtime = item ? accordionRuntimeOf(rootOfItem(item)) : null;
-    if (!item || !runtime) return null;
-    return runtime.run(action, runtime.keyOf(item));
-}
-
 /** How much of an opened item must already be on screen for the action NOT to scroll to it (its header row). */
 const VISIBLE_HEAD_PX = 48;
 

package/src/composite-core/accordion.ts

@@ -1,7 +1,7 @@
 import { readOwnedTrait } from '@vectoriox/iox-ui/design-core';
 
 import {
-    AccordionRole, COMPOSITE_KIND_ROLES, CompositeKind, compositeKindOfRole,
+    AccordionRole, COMPOSITE_KIND_ROLES, CompositeKind, compositeKindOfRole, isToggleKind,
 } from './composite-kinds';
 import {
     CompositeNode, CompositeNodeFactory, findByRole, makeCompositePart, readProp, removeFromComposite, walkComposite, writeProp, writeStyles,
@@ -233,7 +233,8 @@ export function setAccordionBehaviour(root: CompositeNode, patch: Partial<Accord
 
 /** The roles of the kind an item belongs to (an accordion item, or a disclosure — its own item). */
 function kindRolesOf(node: CompositeNode) {
-    return COMPOSITE_KIND_ROLES[compositeKindOfRole(node.role) ?? CompositeKind.Accordion];
+    const kind = compositeKindOfRole(node.role);
+    return COMPOSITE_KIND_ROLES[isToggleKind(kind) ? kind : CompositeKind.Accordion];
 }
 
 /** The header of an item (either kind). */
@@ -479,6 +480,7 @@ export interface AccordionDomIds {
 const DOM_ID_PREFIX: Readonly<Record<CompositeKind, string>> = {
     [CompositeKind.Accordion]: 'iox-acc',
     [CompositeKind.Disclosure]: 'iox-dis',
+    [CompositeKind.Tabs]: 'iox-tab',
 };
 
 /** The ARIA pairing ids of an item: unique per composite (its SCOPE id — `compositeScopeId`) and per item (its key). */

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

@@ -1,15 +1,23 @@
 /**
- * The open/close composites' kinds and roles (CC2 Accordion, CC2.1 Disclosure — composite plan T9 / T21). ONE
- * family: a Disclosure is a one-item accordion whose ROOT is its item, so both run the same state machine, the
- * same attribute planners and the same runtime (`accordion-runtime.ts`). Every consumer that treats "an item",
- * "a header" or "a panel" alike asks these predicates, never a role literal.
+ * The composites' kinds and roles. Two families:
+ * - OPEN/CLOSE (CC2 Accordion, CC2.1 Disclosure — composite plan T9 / T21): a Disclosure is a one-item accordion whose
+ *   ROOT is its item, so both run the same state machine, attribute planners and runtime (`accordion-runtime.ts`);
+ * - EXCLUSIVE (CC4 Tabs — composite T17; the Segmented control joins in CC4b): exactly one item is on, a trigger and
+ *   its panel paired by `itemKey` (`tabs.ts`, `exclusive-runtime.ts`).
+ * Every consumer that treats "an item", "a trigger" or "a panel" alike asks these predicates, never a role literal.
  */
 
 export enum CompositeKind {
     Accordion = 'accordion',
     Disclosure = 'disclosure',
+    Tabs = 'tabs',
 }
 
+/** The kinds the open/close runtime runs (`AccordionRuntime`). */
+export type ToggleCompositeKind = CompositeKind.Accordion | CompositeKind.Disclosure;
+/** The kinds the exclusive runtime runs (`ExclusiveRuntime`): one item on at a time, always one. */
+export type ExclusiveCompositeKind = CompositeKind.Tabs;
+
 export enum AccordionRole {
     Accordion = 'accordion',
     Item = 'accordion.item',
@@ -32,9 +40,22 @@ export enum DisclosureRole {
     Panel = 'disclosure.panel',
 }
 
+/**
+ * TABS (CC4a — composite T17). The tab LIST holds the triggers, the PANELS holder holds the panels; a tab and its panel
+ * share an `itemKey` (never their index — moving a tab keeps its own panel). From content (R3) the list and the panels
+ * holder are both Repeaters over the SAME source, one row giving its tab AND its panel (paired by the row's id).
+ */
+export enum TabsRole {
+    Tabs = 'tabs',
+    List = 'tabs.list',
+    Trigger = 'tabs.trigger',
+    Panels = 'tabs.panels',
+    Panel = 'tabs.panel',
+}
+
 interface RoleLike { role?: string | null }
 
-/** The roles each kind plays in the shared runtime. */
+/** The roles each open/close kind plays in the shared runtime. */
 export interface CompositeKindRoles {
     root: string;
     item: string;
@@ -43,17 +64,40 @@ export interface CompositeKindRoles {
     icon: string;
 }
 
-export const COMPOSITE_KIND_ROLES: Readonly<Record<CompositeKind, CompositeKindRoles>> = {
+export const COMPOSITE_KIND_ROLES: Readonly<Record<ToggleCompositeKind, CompositeKindRoles>> = {
     [CompositeKind.Accordion]: { root: AccordionRole.Accordion, item: AccordionRole.Item, trigger: AccordionRole.Trigger, panel: AccordionRole.Panel, icon: AccordionRole.Icon },
     [CompositeKind.Disclosure]: { root: DisclosureRole.Disclosure, item: DisclosureRole.Disclosure, trigger: DisclosureRole.Trigger, panel: DisclosureRole.Panel, icon: DisclosureRole.Icon },
 };
 
+/** The roles each EXCLUSIVE kind plays: its root, the holder of its triggers, its triggers, and — when its items show
+ *  a panel (Tabs; a Segmented control has none) — the holder of its panels and the panels. */
+export interface ExclusiveKindRoles {
+    root: string;
+    list: string;
+    trigger: string;
+    panels: string | null;
+    panel: string | null;
+}
+
+export const EXCLUSIVE_KIND_ROLES: Readonly<Record<ExclusiveCompositeKind, ExclusiveKindRoles>> = {
+    [CompositeKind.Tabs]: { root: TabsRole.Tabs, list: TabsRole.List, trigger: TabsRole.Trigger, panels: TabsRole.Panels, panel: TabsRole.Panel },
+};
+
 const KINDS = Object.values(CompositeKind);
-const rolesOf = (pick: keyof CompositeKindRoles): ReadonlySet<string> => new Set(KINDS.map(k => COMPOSITE_KIND_ROLES[k][pick]));
+const TOGGLE_KINDS = Object.keys(COMPOSITE_KIND_ROLES) as ToggleCompositeKind[];
+const EXCLUSIVE_KINDS = Object.keys(EXCLUSIVE_KIND_ROLES) as ExclusiveCompositeKind[];
+const rolesOf = (pick: keyof CompositeKindRoles): ReadonlySet<string> => new Set(TOGGLE_KINDS.map(k => COMPOSITE_KIND_ROLES[k][pick]));
+const exclusiveRolesOf = (pick: keyof ExclusiveKindRoles): ReadonlySet<string> =>
+    new Set(EXCLUSIVE_KINDS.map(k => EXCLUSIVE_KIND_ROLES[k][pick]).filter((r): r is string => !!r));
 const ROOT_ROLES = rolesOf('root');
 const ITEM_ROLES = rolesOf('item');
 const TRIGGER_ROLES = rolesOf('trigger');
 const PANEL_ROLES = rolesOf('panel');
+const EXCLUSIVE_ROOT_ROLES = exclusiveRolesOf('root');
+const EXCLUSIVE_LIST_ROLES = exclusiveRolesOf('list');
+const EXCLUSIVE_TRIGGER_ROLES = exclusiveRolesOf('trigger');
+const EXCLUSIVE_PANELS_ROLES = exclusiveRolesOf('panels');
+const EXCLUSIVE_PANEL_ROLES = exclusiveRolesOf('panel');
 
 /** The kind a role belongs to (`disclosure.panel` → Disclosure), or null for any other role. */
 export function compositeKindOfRole(role: string | null | undefined): CompositeKind | null {
@@ -61,6 +105,16 @@ export function compositeKindOfRole(role: string | null | undefined): CompositeK
     return (KINDS as string[]).includes(head ?? '') ? head as CompositeKind : null;
 }
 
+/** True for a kind the open/close runtime runs. */
+export function isToggleKind(kind: CompositeKind | null | undefined): kind is ToggleCompositeKind {
+    return !!kind && (TOGGLE_KINDS as string[]).includes(kind);
+}
+
+/** True for a kind the exclusive runtime runs. */
+export function isExclusiveKind(kind: CompositeKind | null | undefined): kind is ExclusiveCompositeKind {
+    return !!kind && (EXCLUSIVE_KINDS as string[]).includes(kind);
+}
+
 /** A root that runs the open/close runtime (an Accordion or a Disclosure). */
 export function isCompositeRoot(node: RoleLike | null | undefined): boolean {
     return !!node?.role && ROOT_ROLES.has(node.role);
@@ -108,3 +162,63 @@ export function compositeItemOf<T extends RoleLike>(node: T, path: ReadonlyArray
     }
     return null;
 }
+
+// ── the exclusive family (CC4a Tabs) ───────────────────────────────────────────────────────────
+
+/** A root that runs the exclusive runtime (Tabs). */
+export function isExclusiveRoot(node: RoleLike | null | undefined): boolean {
+    return !!node?.role && EXCLUSIVE_ROOT_ROLES.has(node.role);
+}
+
+/** The holder of an exclusive composite's triggers (a tab list): it takes only triggers. */
+export function isExclusiveList(node: RoleLike | null | undefined): boolean {
+    return !!node?.role && EXCLUSIVE_LIST_ROLES.has(node.role);
+}
+
+/** One of an exclusive composite's triggers (a tab): pressing it turns its item on. */
+export function isExclusiveTrigger(node: RoleLike | null | undefined): boolean {
+    return !!node?.role && EXCLUSIVE_TRIGGER_ROLES.has(node.role);
+}
+
+/** The holder of an exclusive composite's panels: it takes only panels. */
+export function isExclusivePanels(node: RoleLike | null | undefined): boolean {
+    return !!node?.role && EXCLUSIVE_PANELS_ROLES.has(node.role);
+}
+
+/** One of an exclusive composite's panels (a tab panel): shown only while its item is on. */
+export function isExclusivePanel(node: RoleLike | null | undefined): boolean {
+    return !!node?.role && EXCLUSIVE_PANEL_ROLES.has(node.role);
+}
+
+/** True for a trigger or a panel — a part that IS one item of an exclusive composite (it carries the `itemKey`). */
+export function isExclusiveItemPart(node: RoleLike | null | undefined): boolean {
+    return isExclusiveTrigger(node) || isExclusivePanel(node);
+}
+
+/** True for any part of a Tabs (its root included). */
+export function isTabsPart(node: RoleLike | null | undefined): boolean {
+    return compositeKindOfRole(node?.role) === CompositeKind.Tabs;
+}
+
+/** A root of either family — anything that runs a composite runtime. */
+export function isAnyCompositeRoot(node: RoleLike | null | undefined): boolean {
+    return isCompositeRoot(node) || isExclusiveRoot(node);
+}
+
+/** The exclusive root a node belongs to (the node itself when it is one), or null. `path` = its ancestors, root first. */
+export function exclusiveRootOf<T extends RoleLike>(node: T, path: ReadonlyArray<T>): T | null {
+    if (isExclusiveRoot(node)) return node;
+    for (let i = path.length - 1; i >= 0; i--) if (isExclusiveRoot(path[i])) return path[i];
+    return null;
+}
+
+/** The trigger or panel a node sits in (itself when it is one) inside an exclusive composite, or null. A nested
+ *  exclusive root ends the walk. */
+export function exclusiveItemPartOf<T extends RoleLike>(node: T, path: ReadonlyArray<T>): T | null {
+    if (isExclusiveItemPart(node)) return node;
+    for (let i = path.length - 1; i >= 0; i--) {
+        if (isExclusiveItemPart(path[i])) return path[i];
+        if (isExclusiveRoot(path[i])) return null;
+    }
+    return 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;