@vectoriox/iox-ui 4.22.0 → 4.24.0

package/{types/vectoriox-iox-ui.d.ts → index.d.ts}

@@ -744,18 +744,33 @@ declare const SUPPRESSED_STYLE_PROPS_BY_TYPE: Readonly<Record<string, readonly s
 /** Remove the style props whose value a type's render-default always overrides. Returns the map
  *  unchanged (same reference) when the type suppresses nothing. */
 declare function stripSuppressedProps(type: string, styleProps: Record<string, any>): Record<string, any>;
+/**
+ * What a compiled rule is FOR — decides whether an initial value is a no-op.
+ *
+ * In a `Base` rule nothing is being overridden, so `width: auto` or `transform: none` changes
+ * nothing and is dropped (see NOOP_INITIAL_VALUES). In an `Override` rule — a breakpoint layer —
+ * the initial value is exactly how you UNDO a wider rule (`width: 520px` → `auto` on mobile), so
+ * dropping it would silently keep the desktop value.
+ */
+declare enum DeclarationContext {
+    Base = "base",
+    Override = "override"
+}
 /**
  * Compile a flat, camelCase style map into an array of `"prop: value"` CSS
- * declarations (kebab-cased, viewport-units rewritten, empties + no-op initials dropped,
- * optional `!important`). Callers wrap these in whatever selector they emit.
+ * declarations (kebab-cased, viewport-units rewritten, empties dropped, no-op initials dropped
+ * in a `Base` context only, optional `!important`). Callers wrap these in whatever selector
+ * they emit.
  *
  * @param props          Flat camelCase style map.
  * @param importantProps Keys that must carry `!important` (e.g. `position`, to beat
  *                       Angular's scoped-CSS specificity boost in the builder). A prop forced
  *                       `!important` is never dropped as a no-op — the `!important` exists to win
  *                       the cascade, so its value must always be emitted.
+ * @param context        `Override` for a rule that overrides a wider one (a breakpoint layer):
+ *                       initial values are kept, because there they reset rather than no-op.
  */
-declare function compileDeclarations(props: Record<string, any>, importantProps?: ReadonlySet<string>): string[];
+declare function compileDeclarations(props: Record<string, any>, importantProps?: ReadonlySet<string>, context?: DeclarationContext): string[];
 /**
  * Per-type default `width` that the builder applies from each component's config
  * (NOT persisted in styleProps — see render-parity.md "saved node is not
@@ -779,6 +794,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 +868,149 @@ 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 breakpoint a viewport (or canvas) of `width` CSS px falls in — the narrowest one whose
+ * `maxWidth` it fits under, else Base. Mirrors how the `max-width` media queries resolve, so the
+ * builder's editing scope is always the breakpoint the canvas is actually showing.
+ */
+declare function breakpointForWidth(width: number): Breakpoint;
+/** The next-wider breakpoint (what `bp` inherits from), or `null` for Base / unknown. */
+declare function parentBreakpoint(bp: Breakpoint | string): Breakpoint | null;
+/**
+ * What a breakpoint's width is measured against.
+ *
+ * `Media` — the browser viewport. The SSR engine: a visitor's window IS the page.
+ * `Container` — a named CSS size container. The builder: its canvas is a fixed-width frame inside a
+ * desktop browser (and `transform: scale`d for zoom), so a media query would read the EDITOR's width.
+ * A container query reads the frame's own layout width — which equals the simulated viewport and
+ * ignores the zoom transform — so the builder emits the same structure as the engine.
+ */
+declare enum BreakpointQueryKind {
+    Media = "media",
+    Container = "container"
+}
+/**
+ * The at-rule prelude for `bp` — `@media (max-width: 767px)`, or with `Container`
+ * `@container iox-canvas (max-width: 767px)`. `null` for Base or an unknown id.
+ * `containerName` is required for `Container` (an unnamed container query would match
+ * whichever ancestor container is nearest, which is not guaranteed to be the canvas).
+ */
+declare function breakpointQueryFor(bp: Breakpoint | string, kind?: BreakpointQueryKind, containerName?: string): string | null;
+/** Wrap already-compiled rules for `bp`. Base (and blank css) passes through unwrapped. */
+declare function wrapInBreakpointQuery(bp: Breakpoint | string, css: string, kind?: BreakpointQueryKind, containerName?: string): string;
+/** `@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` in its media query. Base (and blank css) passes through. */
+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;
+/**
+ * Every state that has a value anywhere — at base or at any breakpoint — in a stable order
+ * (base states first, then any that exist only at a breakpoint). A renderer iterates this, not
+ * `Object.keys(stateStyles)`, so a state defined ONLY at a breakpoint (a Mobile-only hover) still
+ * gets its selector scope resolved.
+ */
+declare function stateNamesIn(stateStyles: StateStyleMap | null | undefined, responsive: ResponsiveOverrides | null | undefined): string[];
+/** 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).
+ *
+ * ⚠️ Compile these maps with `compileDeclarations(map, …, DeclarationContext.Override)`. The
+ * default Base context drops CSS initial values as no-ops — but here `width: auto` or
+ * `transform: none` is how a breakpoint UNDOES the wider value, and dropping it silently keeps
+ * the desktop style.
+ */
+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 +1928,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, BreakpointQueryKind, 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, DeclarationContext, 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, breakpointForWidth, breakpointQueryFor, 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, stateNamesIn, stripSuppressedProps, styleKeyToKebab, variableAliases, variableItemsFrom, withContextSlots, wrapInBreakpointQuery, 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "4.22.0",
+  "version": "4.24.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",
@@ -10,16 +10,15 @@
     "tslib": "^2.3.0"
   },
   "module": "fesm2022/vectoriox-iox-ui.mjs",
-  "typings": "types/vectoriox-iox-ui.d.ts",
+  "typings": "index.d.ts",
   "exports": {
     "./package.json": {
       "default": "./package.json"
     },
     ".": {
-      "types": "./types/vectoriox-iox-ui.d.ts",
+      "types": "./index.d.ts",
       "default": "./fesm2022/vectoriox-iox-ui.mjs"
     }
   },
-  "sideEffects": false,
-  "type": "module"
+  "sideEffects": false
 }