@vectoriox/iox-ui 4.16.2 → 4.17.1

package/package.json

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

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

@@ -779,6 +779,50 @@ declare const VIRTUAL_TRAIT_KEYS: Set<string>;
  */
 declare function composeVirtualTraits(raw: Record<string, any>, base?: Record<string, any>): Record<string, any>;
 
+/**
+ * tree-relations — framework-agnostic helpers for reasoning about a rendered node
+ * tree's structural relationships. Lives in @vectoriox/iox-ui because BOTH renderers
+ * depend on iox-ui (the engine does NOT depend on iox-builder), so the same logic
+ * drives the builder canvas AND the SSR site — no fork.
+ * See iox-ai-guidance `architecture/builder/targeted-hover-state-plan.md`.
+ */
+/**
+ * Minimal shape both renderers can satisfy. `styleId` (present on repeater/slider/symbol
+ * clones) points back to the template node's css id; when set it is the id used in the
+ * compiled selector, so we resolve against it in preference to `id`.
+ */
+interface StyleTreeNode {
+    id?: string;
+    styleId?: string;
+    children?: StyleTreeNode[] | null;
+}
+/** The css id a node contributes to selectors: its clone `styleId`, else its own `id`. */
+declare function nodeCssId(node: StyleTreeNode): string | undefined;
+/**
+ * The css id of the NEAREST COMMON ANCESTOR of two nodes (identified by their css ids),
+ * used to scope a `:has()` targeted-state selector so it stays repetition-safe.
+ *
+ * The result may equal `styledCssId` (the trigger sits INSIDE the styled node) or
+ * `triggerCssId` (the styled node sits inside the trigger) — both are valid scopes;
+ * `buildTargetedStateSelector` picks the right selector shape for each. Returns
+ * `undefined` only when a valid scope can't exist: an id is blank, the two ids are the
+ * same node, or they share no ancestor in `root`. Callers MUST skip emitting the rule
+ * when this is `undefined` — never emit an unscoped (page-global) `:has()`, which would
+ * break under repetition.
+ */
+declare function nearestCommonAncestorId(root: readonly StyleTreeNode[], styledCssId: string, triggerCssId: string): string | undefined;
+/**
+ * Build the selector BODY (no leading `.`, matching the builder's `compile()` convention)
+ * for a targeted state, given the resolved scope. Three topologies, one shared rule:
+ *
+ *   - trigger INSIDE styled  (scope === styled):  `iox-node-{styled}:has(.iox-node-{trigger}:{base})`
+ *   - styled INSIDE trigger  (scope === trigger): `iox-node-{trigger}:{base} .iox-node-{styled}`
+ *   - separate subtrees      (scope is above both): `iox-node-{scope}:has(.iox-node-{trigger}:{base}) .iox-node-{styled}`
+ *
+ * `scopeCssId` MUST be a value returned by `nearestCommonAncestorId` for the same pair.
+ */
+declare function buildTargetedStateSelector(scopeCssId: string, triggerCssId: string, styledCssId: string, base: string): string;
+
 /**
  * Shared data-source resolving pattern — the SINGLE source of truth for how an IoxDataSource
  * becomes a backend fetch, consumed by BOTH the page builder (iox-cms-client bindings panel) and
@@ -1416,5 +1460,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, buildTransitionTimeline, collectReferencedAliases, compileDeclarations, composeVirtualTraits, computeRelative, dataSourcePlanToRequest, effectiveTransitionId, excludeSelf, feelFor, getByPath, isReservedAlias, legacyEnterToTransition, matchRouteParams, normalizeCollectionResult, parseUrlList, planDataSource, referencedDataSources, referencedDataSourcesDeep, renderDefaultDeclarations, resolveDerivedInto, resolveGalleryEffect, resolveGalleryUrls, resolvePageTransition, resolveRelativeInto, resolveRepeaterItems, resolveSiblings, resolveSingleItemId, rewriteViewportUnits, 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, 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, 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, effectiveTransitionId, excludeSelf, feelFor, getByPath, isReservedAlias, legacyEnterToTransition, matchRouteParams, nearestCommonAncestorId, nodeCssId, normalizeCollectionResult, parseUrlList, planDataSource, referencedDataSources, referencedDataSourcesDeep, renderDefaultDeclarations, resolveDerivedInto, resolveGalleryEffect, resolveGalleryUrls, resolvePageTransition, resolveRelativeInto, resolveRepeaterItems, resolveSiblings, resolveSingleItemId, rewriteViewportUnits, 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 };