@vectoriox/iox-ui 4.23.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
@@ -885,11 +900,39 @@ declare const BREAKPOINTS: readonly BreakpointDef[];
 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`. Base (and blank css) passes through unwrapped. */
+/** 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>;
@@ -903,6 +946,13 @@ type ResponsiveOverrides = Partial<Record<OverrideBreakpoint, ResponsiveLayer>>;
 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;
@@ -932,8 +982,15 @@ declare function setOverride(responsive: ResponsiveOverrides | null | undefined,
  * 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). */
+/**
+ * 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;
@@ -1871,5 +1928,5 @@ declare class GalleryLoop {
     private emit;
 }
 
-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 { 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.23.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
 }