@vectoriox/iox-builder 4.1.2 → 4.3.0

package/index.d.ts

@@ -2576,6 +2576,120 @@ declare function findParentOf<T extends TreePathNode>(roots: readonly T[] | null
  */
 declare function nodeAncestorPathInEither<T extends TreePathNode>(layout: readonly T[] | null | undefined, globalElements: readonly T[] | null | undefined, target: T | null | undefined): T[] | null;
 
+/** Where a click-inserted element lands: the array it goes into and the index within it. */
+interface InsertTarget<T> {
+    /** The live children array to splice into (a container's `children`, or the page root). */
+    children: T[];
+    index: number;
+    /** The node that owns `children`, or `null` for the page root. */
+    parent: T | null;
+}
+/**
+ * Resolve where "click to insert" puts a new element, from the current selection — the rule the
+ * components panel and the canvas "+" share (builder-usability-plan.md, B2):
+ *
+ *   nothing selected        → appended to the page root
+ *   a CONTAINER selected    → appended INSIDE it (its last child)
+ *   a LEAF selected         → inserted AFTER it, as its next sibling
+ *
+ * `isContainer` decides what can hold children — the builder passes "has a registered drop zone",
+ * the same test a drag uses, so a click can never insert somewhere a drop couldn't.
+ * A selection not found in `roots` (stale) falls back to appending to the root.
+ */
+declare function resolveInsertTarget<T extends TreePathNode & {
+    children?: T[] | null;
+}>(roots: T[], selected: T | null | undefined, isContainer: (node: T) => boolean): InsertTarget<T>;
+
+/**
+ * STRUCTURE OPS (A4) — the one-click layout changes people actually make at a narrow width, as pure
+ * "what to write" functions. Each returns a flat style map the caller stores in the node's
+ * `responsive[bp]` layer (or in the base styles at Base) through the shared `setOverride`.
+ *
+ * All of it is ordinary CSS the SSR engine already renders — there is no second tree and no
+ * per-width HTML. See responsive-breakpoints-plan.md (D5).
+ */
+type StyleMap = Record<string, any>;
+/**
+ * Hide / show at a width. Hiding is `display: none` INSIDE that breakpoint's rules — the node stays
+ * in the DOM and in the SSR output (one HTML document serves every width), so hidden content still
+ * ships bytes and is still indexed. Showing again clears the override rather than guessing a value.
+ *
+ * @returns the props to write, or `null` meaning "clear the display override at this breakpoint".
+ */
+declare function visibilityProps(hidden: boolean): StyleMap | null;
+/** True when this node is hidden by the resolved styles at some width. */
+declare function isHiddenAt(resolvedStyleProps: StyleMap | null | undefined): boolean;
+/**
+ * Stack a container's children in one column — the most common mobile edit, and four separate
+ * controls today (display, direction, wrap, columns). A grid becomes a single-column grid; anything
+ * else becomes a column flex box.
+ */
+declare function stackChildrenProps(resolvedStyleProps: StyleMap | null | undefined): StyleMap;
+/**
+ * Collapse a grid to `count` columns (a flex row is stacked instead — it has no column track).
+ * `count` is clamped to at least 1.
+ */
+declare function collapseColumnsProps(resolvedStyleProps: StyleMap | null | undefined, count: number): StyleMap;
+/** How many equal columns a `repeat(N, …)` track list describes, or null when it isn't one. */
+declare function columnCountOf(resolvedStyleProps: StyleMap | null | undefined): number | null;
+/**
+ * Make fixed pixel sizes fluid: `width: 520px` → `width: 100%` with the original kept as
+ * `max-width`, so the element still never exceeds its designed size on a wide screen. `minWidth` in
+ * px is dropped to 0 — it is what actually forces horizontal scrolling on a phone.
+ *
+ * @returns the props to write; EMPTY when there is nothing fixed to fluidise.
+ */
+declare function fluidiseProps(resolvedStyleProps: StyleMap | null | undefined): StyleMap;
+/** True when `fluidiseProps` would change anything — drives the button's disabled state. */
+declare function canFluidise(resolvedStyleProps: StyleMap | null | undefined): boolean;
+/**
+ * Reorder children AT ONE WIDTH using CSS `order`, leaving the tree — and so the DOM and
+ * screen-reader order — untouched. Returns one value per child BY CHILD INDEX: the `order` it must
+ * take, or `null` for "no override needed".
+ *
+ * Either every child gets an explicit `order` or none does: CSS defaults `order` to 0, so a partial
+ * set would mix overridden children with unordered ones and read as an arbitrary interleave.
+ *
+ * @param count  How many children there are.
+ * @param from   Index of the child being moved.
+ * @param to     Index it should occupy.
+ */
+declare function reorderProps(count: number, from: number, to: number): Array<number | null>;
+
+/**
+ * ESSENTIALS (B3) — the handful of style controls that matter first for each component type.
+ *
+ * The style panel carries 94 controls across ten groups, ranked by nothing: the control you want for
+ * a heading sits at the same visual weight as `backdrop-filter`. The panel shows this short list in
+ * a band at the top; everything else stays exactly where it is, one click away, and reachable by
+ * search. Nothing is removed and nothing changes group.
+ *
+ * A data table, not per-component code: adding a type is one row. Types with no row fall back to
+ * `DEFAULT_ESSENTIAL_TRAITS`, so a new component is never worse off than today.
+ */
+declare const ESSENTIAL_TRAITS_BY_TYPE: Readonly<Record<string, readonly string[]>>;
+/** For any type without its own row — size, spacing and background suit almost anything. */
+declare const DEFAULT_ESSENTIAL_TRAITS: readonly string[];
+/** The essential trait NAMES for a component type, in the order they should be shown. */
+declare function essentialTraitsFor(type: string | null | undefined): readonly string[];
+/**
+ * Does `label` or `name` match a control search? Case-insensitive substring on either, so "shadow"
+ * finds `boxShadow` ("Box shadow") and "radius" finds `borderRadius`.
+ */
+declare function matchesControlSearch(name: string, label: string, term: string): boolean;
+
+/**
+ * The text on the drop indicator's chip — "into Card grid · position 2 of 3" (B2).
+ *
+ * The most common drag failure is landing a node one level off and not noticing; naming the PARENT
+ * and the slot makes the target unambiguous before the pointer is released.
+ *
+ * @param containerName  The target container's label or type; blank / unknown → "the page".
+ * @param index          Insert index within the container (0-based).
+ * @param childCount     How many children it has now — the node being dropped makes `childCount + 1`.
+ */
+declare function dropTargetLabel(containerName: string | null | undefined, index: number, childCount: number): string;
+
 declare class BuilderButtonComponentConfig extends ComponentConfig {
     constructor();
 }
@@ -2664,5 +2778,5 @@ declare class TextBlockComponentConfig extends ComponentConfig {
     constructor();
 }
 
-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 };
+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, DEFAULT_ESSENTIAL_TRAITS, DRAG_HANDLE_ATTR, DataSourceRegistryService, DataSourceType, DimensionsGroupStyleConfig, DragEngineService, EASING_OPTIONS, ESSENTIAL_TRAITS_BY_TYPE, 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, canFluidise, collapseColumnsProps, columnCountOf, defaultPageSettings, dropTargetLabel, essentialTraitsFor, findNodeLocation, findParentOf, flattenSchemaFields, fluidiseProps, generateNodeId, isHiddenAt, matchesControlSearch, nodeAncestorPath, nodeAncestorPathInEither, reorderProps, resolveInsertTarget, resolveTraitControllerType, resolveTraitOptions, stackChildrenProps, visibilityProps, wrapNode };
+export type { BreakpointPresentation, BuilderClipboard, ComponentEventDef, ComponentMethodDef, ComponentNode, ComponentTrait, Crumb, DragPayload, DsFilterByQueryParam, DsFilterByRouteParam, ElementState, HistoryEntry, InsertTarget, InteractionAction, InteractionActionType, InteractionPreset, InteractionTrigger, IoxBinding, IoxDataSource, IoxDropEvent, IoxFontManager, IoxInteraction, IoxSymbol, NodeRef, OverlayBoxModel, OverlayBoxSpacing, OverlayEntry, PageRouteAnimationSettings, PageScrollSettings, PageSettings, PageStyleSettings, PanelEvent, QuadSizeSegment, RouteAnimationPreset, ScreenWidthOption, SelectionBadge, StyleMap, StylePreset, StyleTrait, StyleTraitGroup, TraitOptionMap, TraitSelectOption, TraitShowCondition, TreePathNode, ViewportState, ZoomOption };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-builder",
-  "version": "4.1.2",
+  "version": "4.3.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",