@vectoriox/iox-ui 4.22.0 → 4.23.0

package/package.json

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

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

@@ -779,6 +779,25 @@ declare const DEFAULT_WIDTH_BY_TYPE: Readonly<Record<string, string>>;
  */
 declare function renderDefaultDeclarations(type: string, styleProps: Record<string, any>, hasHoverState: boolean): string[];
 
+/**
+ * One composed output property and the virtual traits it is built from.
+ *
+ * Consumers that emit a PARTIAL override (a breakpoint layer — see `responsive.ts`) need
+ * to know which outputs an override actually touches, and what to emit when a touched
+ * group composes to nothing (e.g. translateX reset to 0px while the base had 20px: the
+ * override must say `transform: none`, or the wider rule's transform silently wins).
+ */
+interface VirtualTraitGroup {
+    /** The composed key `composeVirtualTraits` writes (camelCase, or `__markerStyles`). */
+    readonly output: string;
+    /** The virtual trait keys that feed it. */
+    readonly keys: readonly string[];
+    /** Value that cancels a wider rule's output, or `null` when there is no such value
+     *  (`::marker` styles are a nested map, not a single cancellable property). */
+    readonly reset: string | null;
+}
+declare const VIRTUAL_TRAIT_GROUPS: readonly VirtualTraitGroup[];
+/** Every virtual trait key — derived from the groups so there is one list to maintain. */
 declare const VIRTUAL_TRAIT_KEYS: Set<string>;
 /**
  * Strip virtual trait keys from `raw` and emit their composed CSS equivalents.
@@ -834,6 +853,107 @@ declare function nearestCommonAncestorId(root: readonly StyleTreeNode[], styledC
  */
 declare function buildTargetedStateSelector(scopeCssId: string, triggerCssId: string, styledCssId: string, base: string): string;
 
+/** The five fixed breakpoints (plan decision D2). Desktop-first: each narrower one
+ *  overrides the wider ones through `max-width`. */
+declare enum Breakpoint {
+    Base = "base",
+    Laptop = "laptop",
+    Tablet = "tablet",
+    Mobile = "mobile",
+    Small = "small"
+}
+/** Every breakpoint that can hold overrides. Base styles live in `styleProps`. */
+type OverrideBreakpoint = Exclude<Breakpoint, Breakpoint.Base>;
+interface BreakpointDef {
+    readonly id: Breakpoint;
+    readonly label: string;
+    /** Inclusive upper bound in CSS px (`max-width`). `null` for Base, which has no query. */
+    readonly maxWidth: number | null;
+    /** Width the builder canvas simulates while this breakpoint is being edited. Always
+     *  inside the breakpoint's own range (above the next one's `maxWidth`). */
+    readonly previewWidth: number;
+}
+/**
+ * Widest → narrowest. This order IS the cascade order and the `@media` emission order.
+ *
+ * ⚠️ Phones in portrait (360–430px) land in `Small`, NOT `Mobile` — `Mobile` is 480–767,
+ * a phone held landscape. The labels say so (as Webflow's do). The ids stay short because
+ * they are storage keys; the cascade still makes a `Mobile` override reach every phone.
+ */
+declare const BREAKPOINTS: readonly BreakpointDef[];
+/** The definition for `bp`, or `undefined` for an unknown id (e.g. hand-edited JSON). */
+declare function breakpointDef(bp: Breakpoint | string): BreakpointDef | undefined;
+/** Base → `bp`, inclusive — the layers whose values apply at `bp`. Unknown → `[Base]`. */
+declare function cascadeChain(bp: Breakpoint | string): Breakpoint[];
+/** The next-wider breakpoint (what `bp` inherits from), or `null` for Base / unknown. */
+declare function parentBreakpoint(bp: Breakpoint | string): Breakpoint | null;
+/** `@media (max-width: 767px)` for `bp`; `null` for Base or an unknown id. */
+declare function mediaQueryFor(bp: Breakpoint | string): string | null;
+/** Wrap already-compiled rules for `bp`. Base (and blank css) passes through unwrapped. */
+declare function wrapInMediaQuery(bp: Breakpoint | string, css: string): string;
+type StyleMap = Record<string, any>;
+type StateStyleMap = Record<string, StyleMap>;
+/** What one breakpoint overrides. Both maps are SPARSE — only keys that differ. */
+interface ResponsiveLayer {
+    styleProps?: StyleMap;
+    stateStyles?: StateStyleMap;
+}
+type ResponsiveOverrides = Partial<Record<OverrideBreakpoint, ResponsiveLayer>>;
+/** The full effective style map at `bp`: base, then each layer down the cascade. */
+declare function resolveStyleProps(styleProps: StyleMap | null | undefined, responsive: ResponsiveOverrides | null | undefined, bp: Breakpoint | string): StyleMap;
+/** The effective per-state maps at `bp`. States with no values anywhere are omitted. */
+declare function resolveStateStyles(stateStyles: StateStyleMap | null | undefined, responsive: ResponsiveOverrides | null | undefined, bp: Breakpoint | string): StateStyleMap;
+/** One level of the cascade that sets a value. */
+interface ValueSource {
+    breakpoint: Breakpoint;
+    value: any;
+}
+/**
+ * Every level from Base down to `bp` that sets `prop` (optionally within `state`), in
+ * cascade order. The LAST entry is the effective value; an empty array means unset.
+ * Drives the style panel's source chain ("Base 34 → Tablet 28 → Mobile 22").
+ */
+declare function resolveValueChain(prop: string, styleProps: StyleMap | null | undefined, stateStyles: StateStyleMap | null | undefined, responsive: ResponsiveOverrides | null | undefined, bp: Breakpoint | string, state?: string): ValueSource[];
+/** True when `bp` itself sets `prop` (the style panel's orange edge). Never true for Base. */
+declare function isOverriddenAt(responsive: ResponsiveOverrides | null | undefined, bp: Breakpoint | string, prop: string, state?: string): boolean;
+/** Number of overridden values — at `bp`, or across every breakpoint when omitted. */
+declare function countOverrides(responsive: ResponsiveOverrides | null | undefined, bp?: Breakpoint | string): number;
+/** Returns a new overrides object with `prop` set at `bp` (optionally within `state`). */
+declare function setOverride(responsive: ResponsiveOverrides | null | undefined, bp: Breakpoint | string, prop: string, value: any, state?: string): ResponsiveOverrides;
+/**
+ * Remove overrides at `bp` and PRUNE whatever becomes empty, so "reset" and "never
+ * overridden" are the same state on disk — no tombstones, no nulls.
+ *
+ *   clearOverride(r, bp)                 — the whole breakpoint
+ *   clearOverride(r, bp, undefined, st)  — one state at that breakpoint
+ *   clearOverride(r, bp, prop)           — one base-state value
+ *   clearOverride(r, bp, prop, st)       — one value within a state
+ *
+ * Returns `undefined` when nothing is left, so a serialiser omits the key entirely.
+ */
+declare function clearOverride(responsive: ResponsiveOverrides | null | undefined, bp: Breakpoint | string, prop?: string, state?: string): ResponsiveOverrides | undefined;
+/** Everything one breakpoint must emit, already composed. Wrap in `mediaQuery` (engine)
+ *  or apply directly (builder, flattened). */
+interface ResponsiveRuleSet {
+    breakpoint: OverrideBreakpoint;
+    mediaQuery: string;
+    /** Sparse declarations for the node itself at this width (virtual traits composed). */
+    styleProps: StyleMap;
+    /** Sparse declarations per state at this width (virtual traits composed). */
+    stateStyles: StateStyleMap;
+}
+/**
+ * The per-breakpoint rule sets a node needs, widest → narrowest (the order they must be
+ * emitted in, AFTER every base rule — equal specificity means source order decides).
+ * Breakpoints with nothing to emit are omitted.
+ *
+ * Handles the cross-axis case: a breakpoint that changes a virtual group (say
+ * `translateX`) also re-emits that group for every state the node has, because the wider
+ * state rule was composed against the wider value and would otherwise snap back to it on
+ * hover.
+ */
+declare function planResponsiveRules(styleProps: StyleMap | null | undefined, stateStyles: StateStyleMap | null | undefined, responsive: ResponsiveOverrides | null | undefined): ResponsiveRuleSet[];
+
 /**
  * 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
@@ -1751,5 +1871,5 @@ declare class GalleryLoop {
     private emit;
 }
 
-export { AOSService, AnalyticsService, BuilderButtonComponent, BuilderDividerComponent, BuilderHeadingComponent, BuilderIconComponent, BuilderImageComponent, BuilderLinkComponent, BuilderSpacerComponent, ButtonBlockComponent, CMSClientInfraModule, CONTEXT_ACTION_TYPES, 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, activeActions, applyBindingPipes, applyFeel, buildDataSourceFilter, buildRelatedFilter, buildTargetedStateSelector, buildTransitionTimeline, collectContextSlotKeys, collectReferencedAliases, compileDeclarations, composeVirtualTraits, computeRelative, contextActionEffect, contextSlotKeys, dataSourcePlanToRequest, declaredInputNames, effectiveTransitionId, excludeSelf, feelFor, getByPath, initialSlotValues, isActionEnabled, isContextAction, 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, variableAliases, variableItemsFrom, withContextSlots };
-export type { BuildRelatedFilterOptions, ContextActionEffect, ContextActionLike, 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, ToggleableAction, TransitionFeel, TransitionPhase, TransitionTimelineInput };
+export { AOSService, AnalyticsService, BREAKPOINTS, Breakpoint, BuilderButtonComponent, BuilderDividerComponent, BuilderHeadingComponent, BuilderIconComponent, BuilderImageComponent, BuilderLinkComponent, BuilderSpacerComponent, ButtonBlockComponent, CMSClientInfraModule, CONTEXT_ACTION_TYPES, 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_GROUPS, VIRTUAL_TRAIT_KEYS, ViewPositionDirective, ViewPositionModule, WebSettingsService, activeActions, applyBindingPipes, applyFeel, breakpointDef, buildDataSourceFilter, buildRelatedFilter, buildTargetedStateSelector, buildTransitionTimeline, cascadeChain, clearOverride, collectContextSlotKeys, collectReferencedAliases, compileDeclarations, composeVirtualTraits, computeRelative, contextActionEffect, contextSlotKeys, countOverrides, dataSourcePlanToRequest, declaredInputNames, effectiveTransitionId, excludeSelf, feelFor, getByPath, initialSlotValues, isActionEnabled, isContextAction, isOverriddenAt, isReservedAlias, isValidSlotKey, legacyEnterToTransition, matchRouteParams, mediaQueryFor, nearestCommonAncestorId, nodeCssId, nodeUsesContext, normalizeCollectionResult, parentBreakpoint, parseUrlList, planDataSource, planResponsiveRules, referencedDataSources, referencedDataSourcesDeep, renderDefaultDeclarations, resolveContextValue, resolveDerivedInto, resolveGalleryEffect, resolveGalleryUrls, resolvePageTransition, resolvePath, resolveRelativeInto, resolveRepeaterItems, resolveSiblings, resolveSingleItemId, resolveStateStyles, resolveStyleProps, resolveValueChain, rewriteViewportUnits, safeSetInput, setOverride, stripSuppressedProps, styleKeyToKebab, variableAliases, variableItemsFrom, withContextSlots, wrapInMediaQuery };
+export type { BreakpointDef, BuildRelatedFilterOptions, ContextActionEffect, ContextActionLike, 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, OverrideBreakpoint, PageTransitionCategory, PageTransitionCategoryMeta, PageTransitionOptions, PageTransitionPreset, PipeArgSpec, PipeContext, PipeDescriptor, RelativeInputs, RelativeSourceKind, RelativeSourceSpec, ResolveSiblingsOptions, ResolvedPageTransition, ResponsiveLayer, ResponsiveOverrides, ResponsiveRuleSet, RouteContext, SetContextParams, SiblingsResult, StateStyleMap, StyleMap, StyleTreeNode, ToggleableAction, TransitionFeel, TransitionPhase, TransitionTimelineInput, ValueSource, VirtualTraitGroup };