@vectoriox/iox-ui 4.17.3 → 4.18.0

package/package.json

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

package/types/vectoriox-iox-ui.d.ts

@@ -1222,6 +1222,174 @@ declare function declaredInputNames(type: Type<unknown>): Set<string>;
  */
 declare function safeSetInput(ref: ComponentRef<unknown>, name: string, value: unknown): boolean;
 
+/**
+ * THE binding path resolver — one implementation, shared by every renderer.
+ *
+ * Resolves a dot-notation path with optional array brackets against a data object:
+ * `title`, `author.name`, `tags[0]`, `items[2].title`.
+ *
+ * This lived in three places before (iox-builder's binding-path.util, the engine's string
+ * renderer, and the engine's component renderer) and had already drifted: the component-renderer
+ * copy was missing the `$` case below, so a repeater over a primitive array rendered in the SSR
+ * HTML and then blanked on hydration. See render-parity.md.
+ */
+declare function resolvePath(obj: any, path: string): any;
+
+/**
+ * Element context state — shared types.
+ *
+ * A **context slot** is a data-source alias whose value is WRITTEN at runtime (by an interaction)
+ * instead of fetched. That is the whole trick: bindings need no new grammar, because a slot is just
+ * another key in the `resolvedData` map both renderers already resolve against.
+ *
+ * See architecture/builder/element-context-state-plan.md.
+ */
+/** How a slot behaves before anyone has interacted with the page. */
+type ContextSlotDefault = 
+/** Empty until an interaction fills it. The preview is hidden by CSS until then. */
+'none'
+/** Pre-filled with the first item of `source`, so the page is never empty. */
+ | 'first';
+/** Declared on the PAGE — always page-level, never promoted to the org library. */
+interface IoxContextSlot {
+    /**
+     * The bindable alias, e.g. `currentItem`. Shares the page's data-source alias namespace, so it
+     * must be unique among sources AND slots, and must not start with `$` (reserved for system
+     * aliases).
+     */
+    key: string;
+    /** The data-source alias whose items this slot holds. Types the slot for the bind picker. */
+    source: string;
+    /** Defaults to `'none'`. */
+    default?: ContextSlotDefault;
+}
+/**
+ * What a `setContext` action writes. Three shapes, one for each way an element can know a value.
+ */
+type ContextValueSpec = 
+/** `$item` — the row's own item, read from the enclosing loop scope. Configured once. */
+{
+    kind: 'item';
+}
+/** An explicit source + path, for a standalone element that is not inside a loop. */
+ | {
+    kind: 'source';
+    source: string;
+    path?: string;
+}
+/** A fixed value. */
+ | {
+    kind: 'literal';
+    value: unknown;
+};
+/** The parameters of a `setContext` interaction action. */
+interface SetContextParams {
+    /** Which slot to write. */
+    slot: string;
+    /** What to write into it. */
+    value: ContextValueSpec;
+    /**
+     * When true this action does NOT auto-reverse on `mouseleave`.
+     *
+     * `hover` binds both ends and runs actions reversed on leave, which is what we want on a LIST
+     * container (leave → clear) and exactly what we do NOT want on a row: a row clearing itself on
+     * its own leave makes every row-to-row move flicker. Rows set this; container clears don't.
+     */
+    noReverse?: boolean;
+}
+/** Where a slot's value came from — stored as a reference, never a snapshot copy. */
+interface ContextItemRef {
+    /** The source alias the item belongs to. */
+    source: string;
+    /** Position in the resolved array — the O(1) read path. */
+    index: number;
+    /** Optional stable id, used only to repair the index if the collection re-fetched or reordered. */
+    id?: string;
+}
+
+/**
+ * Pure context resolution — no Angular, no transport. Shared by the builder canvas and the SSR
+ * engine so a slot behaves identically in both. See element-context-state-plan.md.
+ */
+/** What an interaction knows at the moment it fires. */
+interface ContextWriteScope {
+    /** The enclosing loop's item, when the element sits inside a repeater/slider row. */
+    item?: unknown;
+    /** The page's resolved data, for `{ kind: 'source' }` specs. */
+    resolvedData?: Record<string, unknown>;
+}
+/**
+ * Turn a `setContext` value spec into the value to store.
+ *
+ * Returns `undefined` when the spec cannot be satisfied (e.g. `$item` on an element that is not in
+ * a loop), which the store treats as "don't write" rather than "write empty".
+ */
+declare function resolveContextValue(spec: ContextValueSpec | undefined, scope?: ContextWriteScope): unknown;
+/**
+ * The value each slot holds before any interaction.
+ *
+ * `'first'` pre-fills from the resolved source so the page is never empty; `'none'` (the default)
+ * leaves the key ABSENT — not set to undefined — so `resolvedData` looks exactly as it does for a
+ * source that returned nothing, and bindings simply don't resolve.
+ */
+declare function initialSlotValues(slots: readonly IoxContextSlot[] | undefined, resolvedData?: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Merge live slot values over the page's resolved data, producing the map bindings resolve against.
+ *
+ * Slot keys share the data-source namespace, so a slot deliberately shadows a source of the same
+ * name — the same way a repeater row shadows its own source alias with the single item.
+ */
+declare function withContextSlots(resolvedData: Record<string, unknown> | undefined, slotValues: Record<string, unknown> | undefined): Record<string, unknown>;
+/** The set of declared slot keys — what marks a binding as "live". */
+declare function contextSlotKeys(slots: readonly IoxContextSlot[] | undefined): Set<string>;
+/**
+ * Does this node read a context slot? Nodes that do must be REGISTERED at render time and
+ * re-applied when the store changes — they are the only ones whose props are not final after the
+ * first render.
+ */
+declare function nodeUsesContext(node: unknown, slotKeys: ReadonlySet<string>): boolean;
+/**
+ * Is a slot key a legal user alias?
+ *
+ * Slots live in the page's data-source alias namespace, so uniqueness is the existing rule. The one
+ * extra constraint is the reserved `$` prefix (system aliases — `$route`, `$current`, …).
+ */
+declare function isValidSlotKey(key: string | undefined | null): boolean;
+
+/**
+ * The runtime context channel: named slots an interaction writes and bindings read.
+ *
+ * Signal-backed because writes are HOT — a hover fires on every row crossing. A write must cost a
+ * signal set and re-apply one input on the registered nodes; it must never re-clone a repeater or
+ * re-render the loop. See element-context-state-plan.md (trap T2).
+ *
+ * Provided in root and reset by the consumer on page navigation — slots are page-level state.
+ */
+declare class ContextStore {
+    private readonly _values;
+    /** All live slot values. Merge over `resolvedData` with `withContextSlots` to resolve bindings. */
+    readonly values: i0.Signal<Readonly<Record<string, unknown>>>;
+    /** The keys currently holding a value — what the "is this slot populated?" CSS state keys off. */
+    readonly populatedKeys: i0.Signal<Set<string>>;
+    /**
+     * Write a slot. An `undefined` value is IGNORED rather than stored: a spec that could not be
+     * satisfied (e.g. `$item` outside a loop) must not silently blank a populated slot.
+     */
+    set(key: string, value: unknown): void;
+    /** Remove a slot's value entirely, so the key is ABSENT (not undefined) for binding resolution. */
+    clear(key: string): void;
+    /** Drop every slot — call on page navigation; context is page-level state. */
+    resetAll(): void;
+    /** Seed the initial values (from `initialSlotValues`) without clobbering later writes. */
+    seed(values: Record<string, unknown>): void;
+    /** Non-reactive read — for imperative code that must not create a dependency. */
+    peek(key: string): unknown;
+    /** Whether a slot currently holds a value. */
+    has(key: string): boolean;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ContextStore, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ContextStore>;
+}
+
 /**
  * Cinematic page-transition presets — the SINGLE SOURCE OF TRUTH shared by the page builder
  * (preview) and the SSR client engine (production). Pure, transport-agnostic: this module only
@@ -1485,5 +1653,5 @@ declare class GalleryLoop {
     private emit;
 }
 
-export { AOSService, AnalyticsService, BuilderButtonComponent, BuilderDividerComponent, BuilderHeadingComponent, BuilderIconComponent, BuilderImageComponent, BuilderLinkComponent, BuilderSpacerComponent, ButtonBlockComponent, CMSClientInfraModule, CardComponent, ClientGalleryComponent, ClientListComponent, ClientListItemComponent, ClientRepeaterComponent, ClientSliderContainerComponent, ClientSliderSlideComponent, ComponentInstanceRegistryService, ConsentService, ContainerComponent, ContentService, DEFAULT_GALLERY_SCHEDULER, DEFAULT_PAGE_TRANSITION, DEFAULT_PAGE_TRANSITION_DURATION, DEFAULT_PAGE_TRANSITION_EASING, DEFAULT_PAGE_TRANSITION_PERSPECTIVE, DEFAULT_WIDTH_BY_TYPE, ENVIRONMENT, GALLERY_EFFECTS, GALLERY_EFFECT_DESCRIPTORS, GalleryLoop, IOX_BUILDER_EVENTS, IS_PREVIEW, IoxAnimateContainer, IoxAosDirective, IoxAosModule, IoxBuilderComponentsModule, IoxComponentRegistryService, IoxPageComponent, IoxPageModule, IoxUiModule, LinkedContainerComponent, PAGE_TRANSITION_CATEGORIES, PAGE_TRANSITION_PRESETS, PIPE_DESCRIPTORS, PIPE_REGISTRY, PageScrollProvider, PrivacyModalComponent, PrivacyModalService, PrivacyModelEvent, RESERVED_ALIAS_PREFIX, SUPPRESSED_STYLE_PROPS_BY_TYPE, SectionComponent, TRANSITION_FEELS, TextBlockComponent, VIRTUAL_TRAIT_KEYS, ViewPositionDirective, ViewPositionModule, WebSettingsService, applyBindingPipes, applyFeel, buildDataSourceFilter, buildRelatedFilter, buildTargetedStateSelector, buildTransitionTimeline, collectReferencedAliases, compileDeclarations, composeVirtualTraits, computeRelative, dataSourcePlanToRequest, declaredInputNames, effectiveTransitionId, excludeSelf, feelFor, getByPath, isReservedAlias, legacyEnterToTransition, matchRouteParams, nearestCommonAncestorId, nodeCssId, normalizeCollectionResult, parseUrlList, planDataSource, referencedDataSources, referencedDataSourcesDeep, renderDefaultDeclarations, resolveDerivedInto, resolveGalleryEffect, resolveGalleryUrls, resolvePageTransition, resolveRelativeInto, resolveRepeaterItems, resolveSiblings, resolveSingleItemId, rewriteViewportUnits, safeSetInput, stripSuppressedProps, styleKeyToKebab };
-export type { BuildRelatedFilterOptions, DataSourceDomain, DataSourceEndpoints, DataSourceMode, DataSourcePlan, DataSourceQueryFilter, DataSourceRequest, DataSourceRequestSpec, DataSourceRouteFilter, DataSourceSpec, GalleryBoundSource, GalleryDurations, GalleryEffect, GalleryEffectDescriptor, GalleryImage, GalleryLoopOptions, GalleryLoopScheduler, GalleryLoopState, GallerySlideState, IBuilderEventEmitter, IoxPipe, PageTransitionCategory, PageTransitionCategoryMeta, PageTransitionOptions, PageTransitionPreset, PipeArgSpec, PipeContext, PipeDescriptor, RelativeInputs, RelativeSourceKind, RelativeSourceSpec, ResolveSiblingsOptions, ResolvedPageTransition, RouteContext, SiblingsResult, StyleTreeNode, TransitionFeel, TransitionPhase, TransitionTimelineInput };
+export { AOSService, AnalyticsService, BuilderButtonComponent, BuilderDividerComponent, BuilderHeadingComponent, BuilderIconComponent, BuilderImageComponent, BuilderLinkComponent, BuilderSpacerComponent, ButtonBlockComponent, CMSClientInfraModule, CardComponent, ClientGalleryComponent, ClientListComponent, ClientListItemComponent, ClientRepeaterComponent, ClientSliderContainerComponent, ClientSliderSlideComponent, ComponentInstanceRegistryService, ConsentService, ContainerComponent, ContentService, ContextStore, DEFAULT_GALLERY_SCHEDULER, DEFAULT_PAGE_TRANSITION, DEFAULT_PAGE_TRANSITION_DURATION, DEFAULT_PAGE_TRANSITION_EASING, DEFAULT_PAGE_TRANSITION_PERSPECTIVE, DEFAULT_WIDTH_BY_TYPE, ENVIRONMENT, GALLERY_EFFECTS, GALLERY_EFFECT_DESCRIPTORS, GalleryLoop, IOX_BUILDER_EVENTS, IS_PREVIEW, IoxAnimateContainer, IoxAosDirective, IoxAosModule, IoxBuilderComponentsModule, IoxComponentRegistryService, IoxPageComponent, IoxPageModule, IoxUiModule, LinkedContainerComponent, PAGE_TRANSITION_CATEGORIES, PAGE_TRANSITION_PRESETS, PIPE_DESCRIPTORS, PIPE_REGISTRY, PageScrollProvider, PrivacyModalComponent, PrivacyModalService, PrivacyModelEvent, RESERVED_ALIAS_PREFIX, SUPPRESSED_STYLE_PROPS_BY_TYPE, SectionComponent, TRANSITION_FEELS, TextBlockComponent, VIRTUAL_TRAIT_KEYS, ViewPositionDirective, ViewPositionModule, WebSettingsService, applyBindingPipes, applyFeel, buildDataSourceFilter, buildRelatedFilter, buildTargetedStateSelector, buildTransitionTimeline, collectReferencedAliases, compileDeclarations, composeVirtualTraits, computeRelative, contextSlotKeys, dataSourcePlanToRequest, declaredInputNames, effectiveTransitionId, excludeSelf, feelFor, getByPath, initialSlotValues, isReservedAlias, isValidSlotKey, legacyEnterToTransition, matchRouteParams, nearestCommonAncestorId, nodeCssId, nodeUsesContext, normalizeCollectionResult, parseUrlList, planDataSource, referencedDataSources, referencedDataSourcesDeep, renderDefaultDeclarations, resolveContextValue, resolveDerivedInto, resolveGalleryEffect, resolveGalleryUrls, resolvePageTransition, resolvePath, resolveRelativeInto, resolveRepeaterItems, resolveSiblings, resolveSingleItemId, rewriteViewportUnits, safeSetInput, stripSuppressedProps, styleKeyToKebab, withContextSlots };
+export type { BuildRelatedFilterOptions, ContextItemRef, ContextSlotDefault, ContextValueSpec, ContextWriteScope, DataSourceDomain, DataSourceEndpoints, DataSourceMode, DataSourcePlan, DataSourceQueryFilter, DataSourceRequest, DataSourceRequestSpec, DataSourceRouteFilter, DataSourceSpec, GalleryBoundSource, GalleryDurations, GalleryEffect, GalleryEffectDescriptor, GalleryImage, GalleryLoopOptions, GalleryLoopScheduler, GalleryLoopState, GallerySlideState, IBuilderEventEmitter, IoxContextSlot, IoxPipe, PageTransitionCategory, PageTransitionCategoryMeta, PageTransitionOptions, PageTransitionPreset, PipeArgSpec, PipeContext, PipeDescriptor, RelativeInputs, RelativeSourceKind, RelativeSourceSpec, ResolveSiblingsOptions, ResolvedPageTransition, RouteContext, SetContextParams, SiblingsResult, StyleTreeNode, TransitionFeel, TransitionPhase, TransitionTimelineInput };