@vectoriox/iox-ui 5.57.0 → 5.58.0

package/harness-core/index.d.ts

@@ -110,13 +110,13 @@ declare const SPEC_STRUCTURES: {
         readonly label: "Practice";
         readonly blurb: "Services, prices and a clear way to book.";
         readonly pages: readonly ["Home", "Services", "Prices", "About", "Contact"];
-        readonly shipped: false;
+        readonly shipped: true;
     };
     readonly place: {
         readonly label: "Place";
         readonly blurb: "A menu, opening hours and how to find you.";
-        readonly pages: readonly ["Home", "Menu", "Visit (hours + map)", "About", "Contact"];
-        readonly shipped: false;
+        readonly pages: readonly ["Home", "Menu", "Visit (hours and address)", "About", "Contact"];
+        readonly shipped: true;
     };
 };
 declare const SPEC_BUSINESS_TYPES: readonly [{
@@ -2136,13 +2136,13 @@ declare const STRUCTURES: {
         readonly label: "Practice";
         readonly blurb: "Services, prices and a clear way to book.";
         readonly pages: readonly ["Home", "Services", "Prices", "About", "Contact"];
-        readonly shipped: false;
+        readonly shipped: true;
     };
     readonly place: {
         readonly label: "Place";
         readonly blurb: "A menu, opening hours and how to find you.";
-        readonly pages: readonly ["Home", "Menu", "Visit (hours + map)", "About", "Contact"];
-        readonly shipped: false;
+        readonly pages: readonly ["Home", "Menu", "Visit (hours and address)", "About", "Contact"];
+        readonly shipped: true;
     };
 };
 /** How much a kind of business needs "book a slot" — the next product bet (off this road). */

package/index.d.ts

@@ -2229,6 +2229,27 @@ declare function keyframeStyleEntries(frame: InteractionKeyframe | null | undefi
  * CSS — so the server render ships it already hidden (no visible→hidden flash). `{}` for anything else.
  */
 declare function entrancePreStateStyle(type: string, params?: Readonly<Record<string, unknown>> | null): Record<string, string>;
+/** Triggers that play an entrance by themselves — the page loading or arriving, the element scrolling into view. */
+declare const SELF_PLAYING_TRIGGERS: ReadonlySet<string>;
+/**
+ * Whether an entrance on `trigger` starts hidden (its pre-state). Always — a menu revealed by a click must stay hidden
+ * until the click — except a self-playing one under reduced motion: it would only ever reveal what is already there,
+ * so it starts shown and never moves (M1-6b: "nothing moves and nothing stays hidden"). Both runtimes ask this.
+ */
+declare function entranceStartsHidden(trigger: string, reducedMotion?: boolean): boolean;
+/** The attribute a SERVER render puts on an element it ships in its entrance's first frame (`entrancePreStateStyle`).
+ *  The live runtime takes the element over — and drops the attribute — when it attaches; until then the fallback CSS
+ *  below reads it. */
+declare const ENTRANCE_PRESTATE_ATTRIBUTE = "data-iox-enter";
+/**
+ * What keeps a server-rendered entrance from hiding content where nothing will play it (AI plan §5 "Entrances that hide
+ * content"; M1-6b): under reduced motion every pre-stated element is shown at once, before any script; and if the
+ * runtime never takes an element over (a script that failed), it is revealed after a few seconds. One stylesheet for
+ * the engine's head — `ENTRANCE_NOSCRIPT_CSS` covers a visitor with no script at all.
+ */
+declare const ENTRANCE_FALLBACK_CSS: string;
+/** The same, for a visitor with no script: every pre-stated element shown at once (served inside `<noscript>`). */
+declare const ENTRANCE_NOSCRIPT_CSS = "[data-iox-enter]{opacity:1!important;transform:none!important;visibility:visible!important;pointer-events:auto!important;animation:none!important}";
 /** The frame an animation comes to rest on (what reduced motion applies at once). */
 declare function finalKeyframe(frames: ReadonlyArray<InteractionKeyframe> | null | undefined): InteractionKeyframe | null;
 
@@ -3175,5 +3196,5 @@ declare class GalleryLoop {
     private emit;
 }
 
-export { A11yAttribute, A11yTrait, ACCESSIBLE_NAME_TYPES, AOSService, ARIA_CURRENT_PAGE, BACKDROP_TWIN_KEY, BACKDROP_WHOLE_KEY, BREAKPOINTS, Breakpoint, BreakpointQueryKind, BuilderButtonComponent, BuilderDividerComponent, BuilderHeadingComponent, BuilderIconComponent, BuilderImageComponent, BuilderLinkComponent, BuilderSpacerComponent, ButtonBlockComponent, COMPONENT_STATE_SELECTOR, CONTAINER_HTML_TAGS, CONTEXT_ACTION_TYPES, CURRENT_LINK_TYPES, CardComponent, ClientGalleryComponent, ClientListComponent, ClientListItemComponent, ClientRepeaterComponent, ClientSliderContainerComponent, ClientSliderSlideComponent, ComponentInstanceRegistryService, ComponentState, ContainerComponent, ContextStore, DECORATIVE_TYPES, DEFAULT_GALLERY_SCHEDULER, DEFAULT_PAGE_TRANSITION, DEFAULT_PAGE_TRANSITION_DURATION, DEFAULT_PAGE_TRANSITION_EASING, DEFAULT_PAGE_TRANSITION_PERSPECTIVE, DEFAULT_PHOSPHOR_WEIGHT, DEFAULT_WIDTH_BY_TYPE, DIALOG_CLOSE_ABOVE_ATTRIBUTE, DIALOG_NODE_TYPE, DeclarationContext, ENTRANCE_ACTION_TYPES, EXIT_ACTION_TYPES, FormRenderState, FormRuntimeService, GALLERY_EFFECTS, GALLERY_EFFECT_DESCRIPTORS, GalleryLoop, HOVER_DEFAULT_TRANSITION, HOVER_STATES, INTERACTION_HIDDEN_ATTRIBUTE, IOX_BUILDER_EVENTS, IOX_FORM_MESSAGES, IOX_FORM_NAVIGATOR, IOX_FORM_TRANSPORT, IS_PREVIEW, IoxAnimateContainer, IoxAosDirective, IoxAosModule, IoxBuilderComponentsModule, IoxComponentRegistryService, IoxDialogComponent, IoxFieldComponent, IoxFormComponent, IoxFormErrorComponent, IoxFormSuccessComponent, IoxPageComponent, IoxPageModule, IoxSubmitButtonComponent, IoxUiModule, IoxVideoComponent, LAST_EMITTED_STATES, LEGACY_DIRECTION_KEY, LEGACY_HOVER_TRANSITION, LEGACY_SWIPER_CONTROLS, LinkedContainerComponent, MANAGED_A11Y_ATTRIBUTES, MAX_LINES_KEY, NAMED_GROUP_ROLES, NO_PAGE_TRANSITION, ON_STATE_ROLES, PAGE_STYLE_TOKENS, PAGE_TOKEN_FALLBACKS, PAGE_TRANSITION_CATEGORIES, PAGE_TRANSITION_PRESETS, PART_CLASS_NAMES, PART_PAGINATION_MODIFIER, PHONE_TRANSITION_QUERY, PIPE_DESCRIPTORS, PIPE_REGISTRY, PageScrollProvider, PageStyleField, PageStyleSource, REDUCED_MOTION_QUERY, SCROLL_EASINGS, SLIDER_INPUTS_ATTRIBUTE, SLIDER_INPUT_NAMES, STATE_PSEUDO_CLASS, SUPPRESSED_STYLE_PROPS_BY_TYPE, SWIPER_A11Y_OPTIONS, SWIPER_RESPONSIVE_TRAITS, SWIPER_TRIGGER_EVENTS, ScrollEasing, SectionComponent, SwiperModuleName, TARGETED_STATE_SUFFIX, TEXT_ALIGN_KEY, TEXT_DIRECTION_KEY, TRANSITION_FEELS, TextAlign, TextBlockComponent, VALIDATION_STATES, VALIDATION_STATE_CLASS, VIRTUAL_TRAIT_GROUPS, VIRTUAL_TRAIT_KEYS, ViewPositionDirective, ViewPositionModule, VisibilityActionType, activeActions, applyBindingPipes, applyFeel, bootSlider, breakpointDef, breakpointForWidth, breakpointQueryFor, buildInteractionKeyframes, buildPartSelector, buildSwiperBreakpoints, buildTargetedStateSelector, buildTargetedSuffixSelector, buildTransitionTimeline, cascadeChain, clearInputOverride, clearOverride, closeAboveMediaQuery, collectContextSlotKeys, compileDeclarations, compilePageStyle, componentStatesFor, composeVirtualTraits, containerHtmlTag, contextActionEffect, contextSlotKeys, countOverrides, declaredInputNames, decomposeBackdropFilter, defaultHoverTransition, defaultMessageResolver, deriveSeoFromContent, describePageStyle, describeSeoFields, dialogCloseAboveMinWidth, domHasSliderParts, effectiveActionType, effectiveTransitionId, entrancePreStateStyle, feelFor, finalKeyframe, getSeoValue, hasHoverState, hasOwnPageTransition, hasOwnTransition, initialSlotValues, isActionEnabled, isContextAction, isCurrentLink, isExternalOrFragment, isGradientPaint, isInputOverriddenAt, isLastEmittedStateKey, isOverriddenAt, isValidSlotKey, isWholeBackdropSet, keyframePropertyName, keyframeStyleEntries, legacyEnterToTransition, mediaQueryFor, mergeSwiperBreakpoints, migrateLegacyDirection, migrateLegacyTextAlign, motionAllowed, nearestCommonAncestorId, needsAccessibleName, needsGroupName, nodeA11yAttributes, nodeCssId, nodeTraitValue, nodeUsesContext, normalizeAppPath, normalizeGalleryImage, normalizeIconClass, orderStatesForEmit, pageTransitionOf, parentBreakpoint, parseUrlList, partClassName, planResponsiveRules, planScroll, planSwiperOptions, playDualLayerTransition, prefersReducedMotion, renderDefaultDeclarations, resetPageStyleField, resetSeoField, resolveBoundValue, resolveContextValue, resolveGalleryEffect, resolveGalleryUrls, resolveInputChain, resolveInputs, resolvePageTransition, resolvePath, resolveSeo, resolveStateStyles, resolveStyleProps, resolveToggleVisibility, resolveValueChain, rewriteViewportUnits, safeSetInput, serializeA11yAttributes, setInputOverride, setOverride, setSeoAuto, setSeoBinding, setSeoOverride, setSeoValue, sliderControlElements, sliderInputsFromProps, sliderInputsOf, stateNamesIn, statePseudoClass, stateSelectorSuffix, stripSuppressedProps, swiperAutoplayAllowed, swiperLoopOptions, swiperModuleNames, syncNodeA11yAttributes, targetedStateSelector, viewportTransitionContext, withContextSlots, withDefaultHoverTransition, wrapInBreakpointQuery, wrapInMediaQuery };
+export { A11yAttribute, A11yTrait, ACCESSIBLE_NAME_TYPES, AOSService, ARIA_CURRENT_PAGE, BACKDROP_TWIN_KEY, BACKDROP_WHOLE_KEY, BREAKPOINTS, Breakpoint, BreakpointQueryKind, BuilderButtonComponent, BuilderDividerComponent, BuilderHeadingComponent, BuilderIconComponent, BuilderImageComponent, BuilderLinkComponent, BuilderSpacerComponent, ButtonBlockComponent, COMPONENT_STATE_SELECTOR, CONTAINER_HTML_TAGS, CONTEXT_ACTION_TYPES, CURRENT_LINK_TYPES, CardComponent, ClientGalleryComponent, ClientListComponent, ClientListItemComponent, ClientRepeaterComponent, ClientSliderContainerComponent, ClientSliderSlideComponent, ComponentInstanceRegistryService, ComponentState, ContainerComponent, ContextStore, DECORATIVE_TYPES, DEFAULT_GALLERY_SCHEDULER, DEFAULT_PAGE_TRANSITION, DEFAULT_PAGE_TRANSITION_DURATION, DEFAULT_PAGE_TRANSITION_EASING, DEFAULT_PAGE_TRANSITION_PERSPECTIVE, DEFAULT_PHOSPHOR_WEIGHT, DEFAULT_WIDTH_BY_TYPE, DIALOG_CLOSE_ABOVE_ATTRIBUTE, DIALOG_NODE_TYPE, DeclarationContext, ENTRANCE_ACTION_TYPES, ENTRANCE_FALLBACK_CSS, ENTRANCE_NOSCRIPT_CSS, ENTRANCE_PRESTATE_ATTRIBUTE, EXIT_ACTION_TYPES, FormRenderState, FormRuntimeService, GALLERY_EFFECTS, GALLERY_EFFECT_DESCRIPTORS, GalleryLoop, HOVER_DEFAULT_TRANSITION, HOVER_STATES, INTERACTION_HIDDEN_ATTRIBUTE, IOX_BUILDER_EVENTS, IOX_FORM_MESSAGES, IOX_FORM_NAVIGATOR, IOX_FORM_TRANSPORT, IS_PREVIEW, IoxAnimateContainer, IoxAosDirective, IoxAosModule, IoxBuilderComponentsModule, IoxComponentRegistryService, IoxDialogComponent, IoxFieldComponent, IoxFormComponent, IoxFormErrorComponent, IoxFormSuccessComponent, IoxPageComponent, IoxPageModule, IoxSubmitButtonComponent, IoxUiModule, IoxVideoComponent, LAST_EMITTED_STATES, LEGACY_DIRECTION_KEY, LEGACY_HOVER_TRANSITION, LEGACY_SWIPER_CONTROLS, LinkedContainerComponent, MANAGED_A11Y_ATTRIBUTES, MAX_LINES_KEY, NAMED_GROUP_ROLES, NO_PAGE_TRANSITION, ON_STATE_ROLES, PAGE_STYLE_TOKENS, PAGE_TOKEN_FALLBACKS, PAGE_TRANSITION_CATEGORIES, PAGE_TRANSITION_PRESETS, PART_CLASS_NAMES, PART_PAGINATION_MODIFIER, PHONE_TRANSITION_QUERY, PIPE_DESCRIPTORS, PIPE_REGISTRY, PageScrollProvider, PageStyleField, PageStyleSource, REDUCED_MOTION_QUERY, SCROLL_EASINGS, SELF_PLAYING_TRIGGERS, SLIDER_INPUTS_ATTRIBUTE, SLIDER_INPUT_NAMES, STATE_PSEUDO_CLASS, SUPPRESSED_STYLE_PROPS_BY_TYPE, SWIPER_A11Y_OPTIONS, SWIPER_RESPONSIVE_TRAITS, SWIPER_TRIGGER_EVENTS, ScrollEasing, SectionComponent, SwiperModuleName, TARGETED_STATE_SUFFIX, TEXT_ALIGN_KEY, TEXT_DIRECTION_KEY, TRANSITION_FEELS, TextAlign, TextBlockComponent, VALIDATION_STATES, VALIDATION_STATE_CLASS, VIRTUAL_TRAIT_GROUPS, VIRTUAL_TRAIT_KEYS, ViewPositionDirective, ViewPositionModule, VisibilityActionType, activeActions, applyBindingPipes, applyFeel, bootSlider, breakpointDef, breakpointForWidth, breakpointQueryFor, buildInteractionKeyframes, buildPartSelector, buildSwiperBreakpoints, buildTargetedStateSelector, buildTargetedSuffixSelector, buildTransitionTimeline, cascadeChain, clearInputOverride, clearOverride, closeAboveMediaQuery, collectContextSlotKeys, compileDeclarations, compilePageStyle, componentStatesFor, composeVirtualTraits, containerHtmlTag, contextActionEffect, contextSlotKeys, countOverrides, declaredInputNames, decomposeBackdropFilter, defaultHoverTransition, defaultMessageResolver, deriveSeoFromContent, describePageStyle, describeSeoFields, dialogCloseAboveMinWidth, domHasSliderParts, effectiveActionType, effectiveTransitionId, entrancePreStateStyle, entranceStartsHidden, feelFor, finalKeyframe, getSeoValue, hasHoverState, hasOwnPageTransition, hasOwnTransition, initialSlotValues, isActionEnabled, isContextAction, isCurrentLink, isExternalOrFragment, isGradientPaint, isInputOverriddenAt, isLastEmittedStateKey, isOverriddenAt, isValidSlotKey, isWholeBackdropSet, keyframePropertyName, keyframeStyleEntries, legacyEnterToTransition, mediaQueryFor, mergeSwiperBreakpoints, migrateLegacyDirection, migrateLegacyTextAlign, motionAllowed, nearestCommonAncestorId, needsAccessibleName, needsGroupName, nodeA11yAttributes, nodeCssId, nodeTraitValue, nodeUsesContext, normalizeAppPath, normalizeGalleryImage, normalizeIconClass, orderStatesForEmit, pageTransitionOf, parentBreakpoint, parseUrlList, partClassName, planResponsiveRules, planScroll, planSwiperOptions, playDualLayerTransition, prefersReducedMotion, renderDefaultDeclarations, resetPageStyleField, resetSeoField, resolveBoundValue, resolveContextValue, resolveGalleryEffect, resolveGalleryUrls, resolveInputChain, resolveInputs, resolvePageTransition, resolvePath, resolveSeo, resolveStateStyles, resolveStyleProps, resolveToggleVisibility, resolveValueChain, rewriteViewportUnits, safeSetInput, serializeA11yAttributes, setInputOverride, setOverride, setSeoAuto, setSeoBinding, setSeoOverride, setSeoValue, sliderControlElements, sliderInputsFromProps, sliderInputsOf, stateNamesIn, statePseudoClass, stateSelectorSuffix, stripSuppressedProps, swiperAutoplayAllowed, swiperLoopOptions, swiperModuleNames, syncNodeA11yAttributes, targetedStateSelector, viewportTransitionContext, withContextSlots, withDefaultHoverTransition, wrapInBreakpointQuery, wrapInMediaQuery };
 export type { A11yNodeSource, BoundValueSpec, BreakpointDef, ContextActionEffect, ContextActionLike, ContextItemRef, ContextSlotDefault, ContextValueSpec, ContextWriteScope, CurrentLinkOptions, FormMessageResolver, GalleryBoundSource, GalleryDurations, GalleryEffect, GalleryEffectDescriptor, GalleryImage, GalleryLoopOptions, GalleryLoopScheduler, GalleryLoopState, GallerySlideState, IBuilderEventEmitter, InputMap, InteractionKeyframe, IoxContextSlot, IoxPipe, MatchMediaHost, NodeA11yContext, OverrideBreakpoint, PageScrollStart, PageStyleFieldState, PageStyleOptions, PageStyleSettings, PageTransitionCategory, PageTransitionCategoryMeta, PageTransitionContext, PageTransitionOptions, PageTransitionPreset, PipeArgSpec, PipeContext, PipeDescriptor, PlannedPageTransition, ResolvedPageTransition, ResponsiveLayer, ResponsiveOverrides, ResponsiveRuleSet, RouteAnimationLike, ScrollPlanContext, SeoDerivedContent, SeoFieldSource, SeoFieldState, SeoResolveContext, SetContextParams, SliderBootOptions, SliderControlElements, SliderInputs, StateStyleMap, StyleMap, StyleTreeNode, SwiperBreakpointMap, SwiperModuleFlags, SwiperPlan, SwiperPlanContext, ToggleableAction, TransitionFeel, TransitionPhase, TransitionPreviewLayers, TransitionTimelineInput, TransitionViewport, ValueSource, VirtualTraitGroup };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "5.57.0",
+  "version": "5.58.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",

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

@@ -1,3 +1,5 @@
+import { ROW_INDEX_ATTRIBUTE } from '@vectoriox/iox-ui/design-core';
+
 import {
     AccordionBehaviour, AccordionClass, AccordionDefaultOn, accordionDomIds, accordionFocusIndex, accordionKeyAction,
     ACCORDION_DEFAULT_ONS, closeAccordionItem, COMPOSITE_ATTRIBUTE, DEFAULT_ON_ATTRIBUTE, hasLabelledRegion, initialAccordionOpen, ITEM_KEY_ATTRIBUTE,
@@ -394,7 +396,6 @@ export function detachAccordion(runtime: AccordionRuntime): void {
  *  destroy), so an item action finds the runtime of whatever item it targets. */
 const RUNTIMES = new WeakMap<Element, AccordionRuntime>();
 
-const ROW_INDEX_ATTRIBUTE = 'data-iox-row-idx';
 
 /** The repeated rows an element sits in, outermost first — each row's index as its row wrappers stamp it
  *  (`data-iox-row-idx`: the builder's Repeater rows, the engine's component path). The builder folds them into a

package/src/composite-core/lightbox.ts

@@ -1,4 +1,4 @@
-import { setColorScheme } from '@vectoriox/iox-ui/design-core';
+import { repeatedRowIndex, ROW_INDEX_ATTRIBUTE, 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';
@@ -20,8 +20,9 @@ import { buildSliderPart, SLIDE_TYPE, SLIDER_TYPE, SliderRole } from './slider';
  */
 
 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';
+/** The attribute a renderer writes on every repeated row (the context-state provenance, both engine paths, the canvas) —
+ *  defined once in design-core (the entrance stagger reads it too). */
+export { ROW_INDEX_ATTRIBUTE };
 export const LIGHTBOX_LABEL = 'Lightbox';
 const DIALOG = 'Dialog';
 const REPEATER = 'Repeater';
@@ -186,7 +187,5 @@ export function canOpenAtClickedItem(ownerPath: ReadonlyArray<CompositeNode>, di
 
 /** 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;
+    return repeatedRowIndex(el) ?? 0;
 }

package/src/design-core/entrance-timing.ts

@@ -0,0 +1,56 @@
+/**
+ * WHEN a look-stamped entrance plays (AI plan rev 3.1 §3p, G29) — the one piece of timing both interaction runtimes, the
+ * composer and the Design specimen share. An item entrance names `stagger` (ms per item) and `cap` (how many items wait
+ * longer than the one before): a static row of cards gets its delays written at stamp time (`staggerDelay`), a Repeater's
+ * rows share ONE template node, so its entrance carries them as params and each runtime adds them for the row it plays on
+ * (`entranceDelay`, the row read from `data-iox-row-idx`). Pure.
+ */
+
+/** The params an item entrance carries for a Repeater's rows. */
+export enum EntranceParam {
+    Distance = 'distance',
+    Stagger = 'stagger',
+    Cap = 'cap',
+}
+
+/** The row attribute both renderers write on a repeated row (its 0-based index in the source) — the ONE definition. */
+export const ROW_INDEX_ATTRIBUTE = 'data-iox-row-idx';
+
+export interface StaggerSpec {
+    readonly stagger?: number;
+    readonly cap?: number;
+}
+
+/** The delay of the `index`-th item: `stagger` ms each, the last `cap` waiting no longer than the one before. */
+export function staggerDelay(spec: StaggerSpec, index = 0): number {
+    const stagger = Number(spec.stagger ?? 0);
+    if (!(stagger > 0)) return 0;
+    const cap = Math.max(1, Math.floor(Number(spec.cap ?? 1)) || 1);
+    const i = Number.isFinite(index) ? Math.max(0, Math.floor(index)) : 0;
+    return Math.min(i, cap - 1) * stagger;
+}
+
+/** What an action carries, as both runtimes read it. */
+export interface TimedAction {
+    readonly delay?: number;
+    readonly params?: Readonly<Record<string, unknown>> | null;
+}
+
+/**
+ * The delay an action plays with on the row at `rowIndex`: its own delay, plus — when it carries a stagger — that row's
+ * share (`staggerDelay`). No row (`null`, the template outside a Repeater) adds nothing.
+ */
+export function entranceDelay(action: TimedAction, rowIndex: number | null | undefined): number {
+    const own = Number(action.delay ?? 0) || 0;
+    const params = action.params ?? {};
+    if (rowIndex === null || rowIndex === undefined || params[EntranceParam.Stagger] === undefined) return own;
+    return own + staggerDelay({ stagger: Number(params[EntranceParam.Stagger]), cap: Number(params[EntranceParam.Cap] ?? 1) }, rowIndex);
+}
+
+/** The row index an element sits in (the nearest `data-iox-row-idx` up its tree), or null outside a Repeater's rows. */
+export function repeatedRowIndex(el: { closest?: (selector: string) => { getAttribute(name: string): string | null } | null } | null | undefined): number | null {
+    const raw = el?.closest?.(`[${ROW_INDEX_ATTRIBUTE}]`)?.getAttribute(ROW_INDEX_ATTRIBUTE);
+    if (raw === null || raw === undefined || raw === '') return null;
+    const n = Number(raw);
+    return Number.isInteger(n) && n >= 0 ? n : null;
+}

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

@@ -25,6 +25,7 @@ export * from './contrast-audit';
 export * from './flavor-tokens';
 export * from './flavor-seed';
 export * from './spring';
+export * from './entrance-timing';
 export * from './fonts';
 export * from './token-names';
 export * from './design-settings';