@vectoriox/iox-builder 3.5.1 → 4.0.0

package/index.d.ts

@@ -1,7 +1,7 @@
 import * as i0 from '@angular/core';
 import { ComponentRef, Type, ChangeDetectorRef, OnInit, AfterViewInit, OnChanges, OnDestroy, EventEmitter, ElementRef, ApplicationRef, SimpleChanges, ViewContainerRef, Injector, EnvironmentInjector, InjectionToken, TemplateRef, AfterContentInit, QueryList } from '@angular/core';
 import * as i28 from '@vectoriox/iox-ui';
-import { RelativeSourceSpec, DataSourceEndpoints } from '@vectoriox/iox-ui';
+import { ResponsiveOverrides, RelativeSourceSpec, Breakpoint, DataSourceEndpoints } from '@vectoriox/iox-ui';
 export { ComponentInstanceRegistryService, IoxContextSlot, SetContextParams, VIRTUAL_TRAIT_KEYS, composeVirtualTraits } from '@vectoriox/iox-ui';
 import * as rxjs from 'rxjs';
 import { Subject, Subscription, BehaviorSubject, Observable } from 'rxjs';
@@ -301,6 +301,15 @@ interface ComponentNode {
      * appear in the trigger picker.
      */
     stateTriggers?: Partial<Record<ElementState, string>>;
+    /**
+     * Per-breakpoint overrides — SPARSE, shaped like `stateStyles`:
+     * `{ mobile: { styleProps: {…}, stateStyles: { hover: {…} } } }`. Base styles stay in
+     * `styleTraits`; absent means the node looks the same at every width. Read and written only
+     * through the shared helpers in `@vectoriox/iox-ui` (`resolveStyleProps`, `setOverride`,
+     * `clearOverride`, `planResponsiveRules`) so builder and SSR engine agree.
+     * See iox-ai-guidance `architecture/builder/responsive-breakpoints-plan.md`.
+     */
+    responsive?: ResponsiveOverrides;
     /** User-defined display name for this node. Used in the layer tree and as an
      *  interaction target identifier. Only nodes with a label appear in the
      *  interaction target picker. */
@@ -587,20 +596,20 @@ declare enum BuilderMode {
     Style = "style",
     Pan = "pan"
 }
-declare enum DeviceMode {
-    Desktop = "desktop",
-    Tablet = "tablet",
-    Mobile = "mobile"
-}
-interface DeviceOption {
-    mode: DeviceMode;
-    label: string;
+/**
+ * Builder-only presentation of the shared breakpoints. The breakpoint SET — ids, max widths, labels,
+ * preview widths — lives once in `@vectoriox/iox-ui` `BREAKPOINTS`; this adds only what the toolbar
+ * and canvas need and the SSR engine never will: an icon and a simulated viewport height.
+ * (Replaces the old DeviceMode / DEVICE_OPTIONS, which only resized the canvas and stored nothing.)
+ */
+interface BreakpointPresentation {
     icon: string;
-    width: number;
-    /** Simulated browser viewport height in CSS px. */
-    height: number;
+    /** Simulated browser viewport height in CSS px — a landscape phone is short. */
+    previewHeight: number;
+    /** Show the icon rotated 90°: Phosphor has no landscape-phone glyph. */
+    landscape?: boolean;
 }
-declare const DEVICE_OPTIONS: DeviceOption[];
+declare const BREAKPOINT_PRESENTATION: Readonly<Record<Breakpoint, BreakpointPresentation>>;
 interface ZoomOption {
     label: string;
     value: number | 'fit';
@@ -896,6 +905,13 @@ declare class DragEngineService {
     static ɵprov: i0.ɵɵInjectableDeclaration<DragEngineService>;
 }
 
+/**
+ * CSS container name of the builder canvas frame (and of the global-elements overlay). Breakpoint
+ * rules are emitted as `@container iox-canvas (max-width: …)`: the frame's layout width IS the
+ * simulated viewport and is unaffected by the zoom `transform: scale`, whereas a `@media` query
+ * would read the editor window. Set on the frame in builder.component.scss.
+ */
+declare const BUILDER_CANVAS_CONTAINER = "iox-canvas";
 /**
  * StyleRegistryService — manages a single <style> tag for the builder canvas.
  *
@@ -921,6 +937,14 @@ declare class DragEngineService {
 declare class StyleRegistryService {
     readonly changes$: Subject<void>;
     private rules;
+    /** Breakpoint rules, kept apart so they flush AFTER every base rule — equal specificity, so
+     *  source order decides (plan trap 1). Keyed per breakpoint like `rules` (`id`, `id:state`). */
+    private responsiveRules;
+    private responsiveInputs;
+    /** Which breakpoint rule keys each node owns — so re-emitting one node's rules is O(its rules),
+     *  not a scan of every breakpoint rule on the page (this runs on every node render). */
+    private responsiveKeys;
+    private stateScopes;
     private styleEl;
     /**
      * Properties that must live on the OUTER wrapper (.iox-outer-{id}) because they
@@ -954,6 +978,30 @@ declare class StyleRegistryService {
      *                pseudo-class drives the state. Compiles a `:has()`-scoped selector.
      */
     upsert(nodeId: string, styles: Record<string, any>, state?: ElementState, relativeToId?: string, triggerId?: string): void;
+    /**
+     * Emit (or clear) a node's breakpoint rules. `planResponsiveRules` — shared with the SSR engine —
+     * decides what each breakpoint emits; this only turns it into selectors, through the SAME
+     * inner/outer split and state selectors as the base rules, compiled in the Override context
+     * (a CSS initial value undoes the wider rule there, so it must not be dropped).
+     *
+     * @param styleProps  The node's full BASE style map (raw — virtual traits not yet composed).
+     */
+    upsertResponsive(nodeId: string, styleProps: Record<string, any>, stateStyles: Record<string, Record<string, any>> | undefined, responsive: ResponsiveOverrides | undefined): void;
+    private emitResponsive;
+    private setResponsiveRule;
+    private clearResponsive;
+    private isOutOfFlow;
+    /**
+     * The selector BODY (no leading dot) for a state rule, or null when a relational / targeted
+     * state has no scope yet (emitting it unscoped would be wrong — a page-global `:has()`).
+     */
+    private stateSelector;
+    /**
+     * The inner + outer rule (joined) and the `::marker` rule for one composed style map.
+     * `isOutOfFlow` is passed in rather than read from `styles` because a breakpoint layer is
+     * sparse — the position in force may come from a wider layer.
+     */
+    private nodeRuleCss;
     /**
      * Write the org-level design token variables as a `:root { … }` block.
      * Token names should be CSS custom property names without the `--` prefix
@@ -1221,7 +1269,11 @@ declare class InteractionEngineService {
 }
 
 interface ViewportState {
-    device: DeviceMode;
+    /**
+     * The breakpoint being edited — ALWAYS the one the canvas width falls in (derived, never set
+     * independently), so the editing scope can't disagree with what the canvas is showing.
+     */
+    breakpoint: Breakpoint;
     /** Real canvas width in CSS pixels (e.g., 1440 for desktop). */
     width: number;
     /** Real canvas height in CSS pixels (e.g., 900 for desktop). Simulates the browser viewport. */
@@ -1235,8 +1287,10 @@ declare class ViewportService {
     state$: rxjs.Observable<ViewportState>;
     getState(): ViewportState;
     getScale(): number;
-    setDevice(device: DeviceMode): void;
+    /** Show (and edit) `bp`: the canvas takes that breakpoint's preview width and height. */
+    setBreakpoint(bp: Breakpoint): void;
     setScale(scale: number): void;
+    /** Any canvas width — the breakpoint follows from it. */
     setWidth(width: number): void;
     /**
      * Calculate the scale that makes the canvas fit inside the available editor width.
@@ -1262,11 +1316,19 @@ declare class ViewportService {
     };
     private update;
     private saveToStorage;
+    /**
+     * Restores width / height / scale. Older builds also saved a `device` ('desktop' | 'tablet' |
+     * 'mobile'); it is ignored — the saved width (1440 / 768 / 375) already resolves to the
+     * matching breakpoint (Base / Tablet / Small), so old preferences carry over unchanged.
+     */
     private loadFromStorage;
     static ɵfac: i0.ɵɵFactoryDeclaration<ViewportService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<ViewportService>;
 }
 
+/** Override counts per breakpoint — what the breakpoint bar's dots show. Base is never present. */
+type BreakpointCounts = Partial<Record<Breakpoint, number>>;
+
 interface BuilderClipboard {
     node?: ComponentNode;
     presetId?: string;
@@ -1371,7 +1433,11 @@ declare class BuilderComponent implements OnInit, AfterViewInit, OnChanges, OnDe
     panelTypes: typeof PanelTypes;
     activeMode: BuilderMode;
     builderModes: typeof BuilderMode;
-    activeDevice: DeviceMode;
+    /** The breakpoint being edited — derived from the canvas width by ViewportService. */
+    activeBreakpoint: Breakpoint;
+    /** Overrides per breakpoint for the selection (or the whole page when nothing is selected) —
+     *  the breakpoint bar's dots. A field recomputed on change, never a getter (OnPush input). */
+    breakpointCounts: BreakpointCounts;
     activeZoom: number;
     activeScreenWidth: number;
     selectedItem: ComponentNode | null;
@@ -1406,7 +1472,7 @@ declare class BuilderComponent implements OnInit, AfterViewInit, OnChanges, OnDe
     private previewFrameRo?;
     private canvasContentHeight;
     handleToolbarModeChange(mode: BuilderMode): void;
-    handleToolbarDeviceChange(device: DeviceMode): void;
+    handleToolbarBreakpointChange(bp: Breakpoint): void;
     handleToolbarZoomChange(value: number | 'fit'): void;
     handleToolbarScreenWidthChange(width: number): void;
     get globalElementsBefore(): ComponentNode[];
@@ -1468,7 +1534,7 @@ declare class BuilderComponent implements OnInit, AfterViewInit, OnChanges, OnDe
     addComponent(name: string): void;
     onDrop(event: IoxDropEvent): void;
     onModeChange(mode: BuilderMode): void;
-    onDeviceChange(device: DeviceMode): void;
+    onBreakpointChange(bp: Breakpoint): void;
     onZoomChange(value: number | 'fit'): void;
     onBoardMouseDown(event: MouseEvent): void;
     onBoardMouseMove(event: MouseEvent): void;
@@ -1526,6 +1592,7 @@ declare class BuilderComponent implements OnInit, AfterViewInit, OnChanges, OnDe
     private _refreshRepeaterFor;
     /** Emit ELEMENT_SELECT with the ancestors the panels need (symbol + repeater item scope). */
     private _emitElementSelect;
+    private refreshBreakpointCounts;
     /** Read a node's current `display` value. The style panel mutates `styleTraits` in place at edit
      *  time, so that is the live source of truth; fall back to a preset's `styleOverrides` map, then
      *  the CSS initial value. */
@@ -1789,7 +1856,9 @@ declare class OverlayComponent implements OnInit, OnDestroy {
 
 declare class ToolbarComponent {
     activeMode: BuilderMode;
-    activeDevice: DeviceMode;
+    activeBreakpoint: Breakpoint;
+    /** Overrides per breakpoint — for the selection, or the page when nothing is selected. */
+    breakpointCounts: BreakpointCounts;
     activeZoom: number;
     activeScreenWidth: number;
     canUndo: boolean;
@@ -1797,7 +1866,7 @@ declare class ToolbarComponent {
     isSaving: boolean;
     pageStatus: string;
     modeChange: EventEmitter<BuilderMode>;
-    deviceChange: EventEmitter<DeviceMode>;
+    breakpointChange: EventEmitter<Breakpoint>;
     zoomChange: EventEmitter<number | "fit">;
     screenWidthChange: EventEmitter<number>;
     undo: EventEmitter<void>;
@@ -1807,30 +1876,35 @@ declare class ToolbarComponent {
     publishToggle: EventEmitter<void>;
     get isPublished(): boolean;
     modePopover: Popover;
-    devicePopover: Popover;
     zoomPopover: Popover;
     widthPopover: Popover;
     modes: typeof BuilderMode;
-    deviceModes: typeof DeviceMode;
-    deviceOptions: DeviceOption[];
+    readonly breakpointIds: typeof Breakpoint;
+    /** Built once — the breakpoint set is fixed. Template binds fields, never method calls. */
+    readonly breakpointOptions: {
+        icon: string;
+        previewHeight: number;
+        landscape?: boolean;
+        id: Breakpoint;
+        label: string;
+        range: string;
+    }[];
     zoomOptions: _vectoriox_iox_builder.ZoomOption[];
     screenWidthOptions: ScreenWidthOption[];
     get activeModeIcon(): string;
     get activeModeLabel(): string;
-    get activeDeviceOption(): DeviceOption;
     get zoomLabel(): string;
     get sliderZoom(): number;
     toggleModePopover(event: Event): void;
     selectMode(mode: BuilderMode): void;
-    toggleDevicePopover(event: Event): void;
-    selectDevice(mode: DeviceMode): void;
+    selectBreakpoint(bp: Breakpoint): void;
     onSliderChange(event: Event): void;
     toggleWidthPopover(event: Event): void;
     selectScreenWidth(width: number): void;
     toggleZoomPopover(event: Event): void;
     selectZoom(value: number | 'fit'): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<ToolbarComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<ToolbarComponent, "app-toolbar", never, { "activeMode": { "alias": "activeMode"; "required": false; }; "activeDevice": { "alias": "activeDevice"; "required": false; }; "activeZoom": { "alias": "activeZoom"; "required": false; }; "activeScreenWidth": { "alias": "activeScreenWidth"; "required": false; }; "canUndo": { "alias": "canUndo"; "required": false; }; "canRedo": { "alias": "canRedo"; "required": false; }; "isSaving": { "alias": "isSaving"; "required": false; }; "pageStatus": { "alias": "pageStatus"; "required": false; }; }, { "modeChange": "modeChange"; "deviceChange": "deviceChange"; "zoomChange": "zoomChange"; "screenWidthChange": "screenWidthChange"; "undo": "undo"; "redo": "redo"; "save": "save"; "preview": "preview"; "publishToggle": "publishToggle"; }, never, never, false, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<ToolbarComponent, "app-toolbar", never, { "activeMode": { "alias": "activeMode"; "required": false; }; "activeBreakpoint": { "alias": "activeBreakpoint"; "required": false; }; "breakpointCounts": { "alias": "breakpointCounts"; "required": false; }; "activeZoom": { "alias": "activeZoom"; "required": false; }; "activeScreenWidth": { "alias": "activeScreenWidth"; "required": false; }; "canUndo": { "alias": "canUndo"; "required": false; }; "canRedo": { "alias": "canRedo"; "required": false; }; "isSaving": { "alias": "isSaving"; "required": false; }; "pageStatus": { "alias": "pageStatus"; "required": false; }; }, { "modeChange": "modeChange"; "breakpointChange": "breakpointChange"; "zoomChange": "zoomChange"; "screenWidthChange": "screenWidthChange"; "undo": "undo"; "redo": "redo"; "save": "save"; "preview": "preview"; "publishToggle": "publishToggle"; }, never, never, false, never>;
 }
 
 /**
@@ -2544,5 +2618,5 @@ declare class TextBlockComponentConfig extends ComponentConfig {
     constructor();
 }
 
-export { ACTION_TYPE_OPTIONS, BackgroundGroupStyleConfig, BorderGroupStyleConfig, BreadcrumbBarComponent, BuilderButtonBlockComponent, BuilderButtonComponentConfig, BuilderClipboardService, BuilderComponent, BuilderContainerComponent, BuilderContainerComponentConfig, BuilderDataSourceService, BuilderDividerComponentConfig, BuilderHeadingComponentConfig, BuilderHistoryService, BuilderIconComponentConfig, BuilderImageComponentConfig, BuilderLinkComponentConfig, BuilderLinkedContainerComponent, BuilderLinkedContainerConfig, BuilderListComponentConfig, BuilderListItemComponentConfig, BuilderMode, BuilderRepeaterComponent, BuilderSpacerComponentConfig, ButtonBlockComponentConfig, CardComponentConfig, ChildLayoutGroupStyleConfig, ComponentConfig, ComponentRegistryService, DEVICE_OPTIONS, DRAG_HANDLE_ATTR, DataSourceRegistryService, DataSourceType, DeviceMode, DimensionsGroupStyleConfig, DragEngineService, EASING_OPTIONS, EffectsGroupStyleConfig, GalleryConfig, GroupStyleConfig, INTERACTION_STATES, INVERSE_ACTION, IOX_DATA_SOURCE_ENDPOINTS, IOX_FONT_MANAGER, InteractionEngineService, InteractionPresetRegistryService, IoxBuilderModule, IoxDraggableDirective, IoxDropzoneDirective, LayerTreeComponent, LayoutGroupStyleConfig, ListGroupStyleConfig, NodeAction, OverlayComponent, OverlayService, PanelChildComponent, PanelComponent, PanelEventService, PanelEventTypes, PanelTypes, PositionGroupStyleConfig, PresetRegistryService, RELATIONAL_STATES, RELATIONAL_STATE_BASE, ROUTE_ANIMATION_OPTIONS, RenderDirective, RepeaterComponentConfig, SCREEN_WIDTH_OPTIONS, STRUCTURAL_STATES, SUPPORTED_STATES, SectionComponent, SectionComponentConfig, SizeGroupStyleConfig, SliderContainerComponent, SliderContainerConfig, SliderSlideComponent, SliderSlideConfig, SpacingGroupStyleConfig, StyleCategory, StyleRegistryService, TraitConfig as StyleTraitConfig, SymbolRegistryService, TARGETED_STATES, TARGETED_STATE_BASE, TRIGGER_OPTIONS, TextBlockComponentConfig, ToolbarAction, ToolbarComponent, TraitConfig, TraitInputType, TypographyGroupStyleConfig, UNITS_ALL, UNITS_DEG, UNITS_FIXED, UNITS_NO_VW, ViewportService, ZOOM_OPTIONS, arrayItemSchemaFields, arraySchemaFields, buildFullStyleTraits, buildPresetStyleTraits, defaultPageSettings, findNodeLocation, findParentOf, flattenSchemaFields, generateNodeId, nodeAncestorPath, nodeAncestorPathInEither, resolveTraitControllerType, resolveTraitOptions, wrapNode };
-export type { BuilderClipboard, ComponentEventDef, ComponentMethodDef, ComponentNode, ComponentTrait, Crumb, DeviceOption, DragPayload, DsFilterByQueryParam, DsFilterByRouteParam, ElementState, HistoryEntry, InteractionAction, InteractionActionType, InteractionPreset, InteractionTrigger, IoxBinding, IoxDataSource, IoxDropEvent, IoxFontManager, IoxInteraction, IoxSymbol, NodeRef, OverlayBoxModel, OverlayBoxSpacing, OverlayEntry, PageRouteAnimationSettings, PageScrollSettings, PageSettings, PageStyleSettings, PanelEvent, QuadSizeSegment, RouteAnimationPreset, ScreenWidthOption, SelectionBadge, StylePreset, StyleTrait, StyleTraitGroup, TraitOptionMap, TraitSelectOption, TraitShowCondition, TreePathNode, ViewportState, ZoomOption };
+export { ACTION_TYPE_OPTIONS, BREAKPOINT_PRESENTATION, BUILDER_CANVAS_CONTAINER, BackgroundGroupStyleConfig, BorderGroupStyleConfig, BreadcrumbBarComponent, BuilderButtonBlockComponent, BuilderButtonComponentConfig, BuilderClipboardService, BuilderComponent, BuilderContainerComponent, BuilderContainerComponentConfig, BuilderDataSourceService, BuilderDividerComponentConfig, BuilderHeadingComponentConfig, BuilderHistoryService, BuilderIconComponentConfig, BuilderImageComponentConfig, BuilderLinkComponentConfig, BuilderLinkedContainerComponent, BuilderLinkedContainerConfig, BuilderListComponentConfig, BuilderListItemComponentConfig, BuilderMode, BuilderRepeaterComponent, BuilderSpacerComponentConfig, ButtonBlockComponentConfig, CardComponentConfig, ChildLayoutGroupStyleConfig, ComponentConfig, ComponentRegistryService, DRAG_HANDLE_ATTR, DataSourceRegistryService, DataSourceType, DimensionsGroupStyleConfig, DragEngineService, EASING_OPTIONS, EffectsGroupStyleConfig, GalleryConfig, GroupStyleConfig, INTERACTION_STATES, INVERSE_ACTION, IOX_DATA_SOURCE_ENDPOINTS, IOX_FONT_MANAGER, InteractionEngineService, InteractionPresetRegistryService, IoxBuilderModule, IoxDraggableDirective, IoxDropzoneDirective, LayerTreeComponent, LayoutGroupStyleConfig, ListGroupStyleConfig, NodeAction, OverlayComponent, OverlayService, PanelChildComponent, PanelComponent, PanelEventService, PanelEventTypes, PanelTypes, PositionGroupStyleConfig, PresetRegistryService, RELATIONAL_STATES, RELATIONAL_STATE_BASE, ROUTE_ANIMATION_OPTIONS, RenderDirective, RepeaterComponentConfig, SCREEN_WIDTH_OPTIONS, STRUCTURAL_STATES, SUPPORTED_STATES, SectionComponent, SectionComponentConfig, SizeGroupStyleConfig, SliderContainerComponent, SliderContainerConfig, SliderSlideComponent, SliderSlideConfig, SpacingGroupStyleConfig, StyleCategory, StyleRegistryService, TraitConfig as StyleTraitConfig, SymbolRegistryService, TARGETED_STATES, TARGETED_STATE_BASE, TRIGGER_OPTIONS, TextBlockComponentConfig, ToolbarAction, ToolbarComponent, TraitConfig, TraitInputType, TypographyGroupStyleConfig, UNITS_ALL, UNITS_DEG, UNITS_FIXED, UNITS_NO_VW, ViewportService, ZOOM_OPTIONS, arrayItemSchemaFields, arraySchemaFields, buildFullStyleTraits, buildPresetStyleTraits, defaultPageSettings, findNodeLocation, findParentOf, flattenSchemaFields, generateNodeId, nodeAncestorPath, nodeAncestorPathInEither, resolveTraitControllerType, resolveTraitOptions, wrapNode };
+export type { BreakpointPresentation, BuilderClipboard, ComponentEventDef, ComponentMethodDef, ComponentNode, ComponentTrait, Crumb, DragPayload, DsFilterByQueryParam, DsFilterByRouteParam, ElementState, HistoryEntry, InteractionAction, InteractionActionType, InteractionPreset, InteractionTrigger, IoxBinding, IoxDataSource, IoxDropEvent, IoxFontManager, IoxInteraction, IoxSymbol, NodeRef, OverlayBoxModel, OverlayBoxSpacing, OverlayEntry, PageRouteAnimationSettings, PageScrollSettings, PageSettings, PageStyleSettings, PanelEvent, QuadSizeSegment, RouteAnimationPreset, ScreenWidthOption, SelectionBadge, StylePreset, StyleTrait, StyleTraitGroup, TraitOptionMap, TraitSelectOption, TraitShowCondition, TreePathNode, ViewportState, ZoomOption };

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@vectoriox/iox-builder",
-  "version": "3.5.1",
+  "version": "4.0.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",
     "@angular/animations": ">=20.0.0",
     "@angular/cdk": ">=20.0.0",
-    "@vectoriox/iox-ui": ">=4.2.0",
+    "@vectoriox/iox-ui": ">=4.24.0",
     "interactjs": "^1.10.27",
     "primeng": ">=20.0.0",
     "swiper": ">=12.0.0",