@vectoriox/iox-builder 4.9.0 → 4.11.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 i29 from '@vectoriox/iox-ui';
-import { ResponsiveOverrides, RelativeSourceSpec, Breakpoint, DataSourceEndpoints } from '@vectoriox/iox-ui';
+import { ResponsiveOverrides, RelativeSourceSpec, Breakpoint, FormRenderState, 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';
@@ -1707,6 +1707,12 @@ declare class BuilderComponent implements OnInit, AfterViewInit, OnChanges, OnDe
     private canvasContentHeight;
     handleToolbarModeChange(mode: BuilderMode): void;
     handleToolbarBreakpointChange(bp: Breakpoint): void;
+    /** The form the selection sits inside, or null. Drives the toolbar's contextual switcher. */
+    activeFormState: FormRenderState;
+    get formStateTarget(): string | null;
+    handleToolbarFormStateChange(state: FormRenderState): void;
+    /** The nearest Form ancestor of the selection (or the selection itself). */
+    private selectedFormNode;
     handleToolbarZoomChange(value: number | 'fit'): void;
     handleToolbarScreenWidthChange(width: number): void;
     get globalElementsBefore(): ComponentNode[];
@@ -2116,8 +2122,16 @@ declare class ToolbarComponent {
     canRedo: boolean;
     isSaving: boolean;
     pageStatus: string;
+    /**
+     * The form the selection sits inside, or null. CONTEXTUAL: the state switcher only appears when
+     * there is a form to switch, because a permanently-present control for a rarely-present element
+     * is exactly the toolbar clutter `builder-usability-plan.md` warns about.
+     */
+    formStateTarget: string | null;
+    activeFormState: FormRenderState;
     modeChange: EventEmitter<BuilderMode>;
     breakpointChange: EventEmitter<Breakpoint>;
+    formStateChange: EventEmitter<FormRenderState>;
     auditToggle: EventEmitter<void>;
     zoomChange: EventEmitter<number | "fit">;
     screenWidthChange: EventEmitter<number>;
@@ -2150,13 +2164,20 @@ declare class ToolbarComponent {
     toggleModePopover(event: Event): void;
     selectMode(mode: BuilderMode): void;
     selectBreakpoint(bp: Breakpoint): void;
+    /** The four states, in the order a submission moves through them. */
+    readonly formStates: {
+        id: FormRenderState;
+        label: string;
+        icon: string;
+    }[];
+    selectFormState(state: FormRenderState): 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; }; "activeBreakpoint": { "alias": "activeBreakpoint"; "required": false; }; "breakpointCounts": { "alias": "breakpointCounts"; "required": false; }; "auditCount": { "alias": "auditCount"; "required": false; }; "auditOpen": { "alias": "auditOpen"; "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"; "auditToggle": "auditToggle"; "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; }; "auditCount": { "alias": "auditCount"; "required": false; }; "auditOpen": { "alias": "auditOpen"; "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; }; "formStateTarget": { "alias": "formStateTarget"; "required": false; }; "activeFormState": { "alias": "activeFormState"; "required": false; }; }, { "modeChange": "modeChange"; "breakpointChange": "breakpointChange"; "formStateChange": "formStateChange"; "auditToggle": "auditToggle"; "zoomChange": "zoomChange"; "screenWidthChange": "screenWidthChange"; "undo": "undo"; "redo": "redo"; "save": "save"; "preview": "preview"; "publishToggle": "publishToggle"; }, never, never, false, never>;
 }
 
 /**
@@ -2852,6 +2873,68 @@ declare function essentialTraitsFor(type: string | null | undefined): readonly s
  */
 declare function matchesControlSearch(name: string, label: string, term: string): boolean;
 
+/**
+ * FORM PRESETS — a complete, working form as one insert.
+ *
+ * This is the piece that makes the whole feature feel simple. Dropping a preset gives a form that
+ * already validates, already stores, and already has designed Success and Error blocks — so the
+ * author's first action is editing copy, not wiring plumbing. Nothing here is a new component type:
+ * what lands on the canvas is ordinary nodes, editable and take-apart-able afterwards.
+ *
+ * Mirrors `layout-presets.ts` deliberately: same shape, same build-from-configs approach, so there
+ * is one way to express "a preset" in this codebase rather than two.
+ */
+interface FormPresetField {
+    label: string;
+    control: string;
+    required?: boolean;
+    help?: string;
+    placeholder?: string;
+    /** Choices for select/radio, `value|Label` per line — the Field's `optionsText` trait. */
+    optionsText?: string;
+    rows?: number;
+}
+interface FormPresetDef {
+    id: string;
+    name: string;
+    icon: string;
+    /** One line in the panel: what it collects and where it goes. */
+    description: string;
+    /** The form's author-facing name, which the submissions inbox groups by. */
+    formName: string;
+    fields: FormPresetField[];
+    submitLabel: string;
+    successText: string;
+    errorText: string;
+}
+declare const FORM_PRESETS: readonly FormPresetDef[];
+/** How a config is produced. The caller owns the registry, so this file stays pure. */
+type CreateConfig = (type: string) => ComponentNode | null | undefined;
+/**
+ * Build a preset's node tree.
+ *
+ * The Form config already auto-creates its children (two fields, a submit, and the two state
+ * blocks), so this REPLACES them wholesale rather than appending — otherwise every preset would
+ * carry the default Name/Email pair as well as its own fields.
+ *
+ * Returns null when a type is missing from the registry, so a half-built tree never reaches a page.
+ */
+declare function buildFormPreset(def: FormPresetDef, createConfig: CreateConfig): ComponentNode | null;
+
+/** The node type that scopes a form. Kept here so the rule has one name, not a scattered literal. */
+declare const FORM_TYPE = "Form";
+/**
+ * The form the current selection belongs to — the NEAREST Form ancestor, or the selection itself
+ * when a Form is selected.
+ *
+ * This is the selection-side expression of decision D1: a field belongs to its nearest ancestor
+ * form. Searching the path from the deepest node outward is what makes "nearest" true, and it is
+ * why a nested form (were one ever allowed) could not capture an outer form's toolbar.
+ *
+ * @param path Ancestor chain from the root down to the selected node, as `selectedPath` holds it.
+ */
+declare function nearestFormNode(path: readonly ComponentNode[] | null | undefined): ComponentNode | null;
+
 /**
  * The text on the drop indicator's chip — "into Card grid · position 2 of 3" (B2).
  *
@@ -2899,6 +2982,48 @@ declare class GalleryConfig extends ComponentConfig {
     constructor();
 }
 
+/**
+ * Form — the container that scopes its fields by ANCESTRY (decision D1).
+ *
+ * The destination config ("After submit") is an ordered action list edited in the Bindings panel as
+ * a property group, not here as flat traits — see forms-and-inputs-plan.md §4b. What lives here is
+ * the handful of settings that ARE single values.
+ *
+ * Auto-creates a working contact form: two fields, a submit button, and the two non-deletable state
+ * blocks. Dropping a Form therefore gives a form that already validates and already stores.
+ */
+declare class FormComponentConfig extends ComponentConfig {
+    constructor();
+}
+/**
+ * Field — ONE component for every control type (decision D4).
+ *
+ * `Required` is its own switch because it is the rule every form needs; the rest are added from a
+ * menu, so an unused rule is invisible rather than an empty control (the Effects-group pattern).
+ */
+declare class FieldComponentConfig extends ComponentConfig {
+    constructor();
+}
+/** A plain layout row so two fields can sit side by side. Config-only, like List/ListItem. */
+declare class FieldGroupComponentConfig extends ComponentConfig {
+    constructor();
+}
+/** The submit button. Carries no destination — that lives on the Form (decision D9). */
+declare class SubmitButtonComponentConfig extends ComponentConfig {
+    constructor();
+}
+/**
+ * The Success block. `hidden` keeps it out of the Components panel: it is auto-created by the Form
+ * and reached through the canvas state switcher, never dropped on its own.
+ */
+declare class FormSuccessComponentConfig extends ComponentConfig {
+    constructor();
+}
+/** The Error block. One design, five reasons — the renderer writes the resolved reason in. */
+declare class FormErrorComponentConfig extends ComponentConfig {
+    constructor();
+}
+
 declare class BuilderHeadingComponentConfig extends ComponentConfig {
     constructor();
 }
@@ -2952,5 +3077,5 @@ declare class TextBlockComponentConfig extends ComponentConfig {
     constructor();
 }
 
-export { ACTION_TYPE_OPTIONS, AuditCode, AuditPanelComponent, AuditSeverity, 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, LAYOUT_PRESETS, 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, auditNodes, buildFullStyleTraits, buildLayoutPreset, buildPresetStyleTraits, canFluidise, collapseColumnsProps, columnCountOf, defaultPageSettings, dropTargetLabel, essentialTraitsFor, findNodeLocation, findParentOf, flattenSchemaFields, fluidiseProps, generateNodeId, isHiddenAt, matchesControlSearch, nodeAncestorPath, nodeAncestorPathInEither, reorderProps, resolveInsertTarget, resolveTraitControllerType, resolveTraitOptions, setStyleTrait, stackChildrenProps, summarise, visibilityProps, wrapNode };
-export type { AuditFinding, AuditNode, BreakpointPresentation, BuilderClipboard, ComponentEventDef, ComponentMethodDef, ComponentNode, ComponentTrait, Crumb, DragPayload, DsFilterByQueryParam, DsFilterByRouteParam, ElementState, HistoryEntry, InsertTarget, InteractionAction, InteractionActionType, InteractionPreset, InteractionTrigger, IoxBinding, IoxDataSource, IoxDropEvent, IoxFontManager, IoxInteraction, IoxSymbol, LayoutPresetChildStyles, LayoutPresetDef, NodeRef, OverlayBoxModel, OverlayBoxSpacing, OverlayEntry, PageRouteAnimationSettings, PageScrollSettings, PageSettings, PageStyleSettings, PanelEvent, QuadSizeSegment, RouteAnimationPreset, ScreenWidthOption, SelectionBadge, StyleMap, StylePreset, StyleTrait, StyleTraitGroup, TraitOptionMap, TraitSelectOption, TraitShowCondition, TreePathNode, ViewportState, ZoomOption };
+export { ACTION_TYPE_OPTIONS, AuditCode, AuditPanelComponent, AuditSeverity, 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, FORM_PRESETS, FORM_TYPE, FieldComponentConfig, FieldGroupComponentConfig, FormComponentConfig, FormErrorComponentConfig, FormSuccessComponentConfig, GalleryConfig, GroupStyleConfig, INTERACTION_STATES, INVERSE_ACTION, IOX_DATA_SOURCE_ENDPOINTS, IOX_FONT_MANAGER, InteractionEngineService, InteractionPresetRegistryService, IoxBuilderModule, IoxDraggableDirective, IoxDropzoneDirective, LAYOUT_PRESETS, 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, SubmitButtonComponentConfig, 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, auditNodes, buildFormPreset, buildFullStyleTraits, buildLayoutPreset, buildPresetStyleTraits, canFluidise, collapseColumnsProps, columnCountOf, defaultPageSettings, dropTargetLabel, essentialTraitsFor, findNodeLocation, findParentOf, flattenSchemaFields, fluidiseProps, generateNodeId, isHiddenAt, matchesControlSearch, nearestFormNode, nodeAncestorPath, nodeAncestorPathInEither, reorderProps, resolveInsertTarget, resolveTraitControllerType, resolveTraitOptions, setStyleTrait, stackChildrenProps, summarise, visibilityProps, wrapNode };
+export type { AuditFinding, AuditNode, BreakpointPresentation, BuilderClipboard, ComponentEventDef, ComponentMethodDef, ComponentNode, ComponentTrait, CreateConfig, Crumb, DragPayload, DsFilterByQueryParam, DsFilterByRouteParam, ElementState, FormPresetDef, FormPresetField, HistoryEntry, InsertTarget, InteractionAction, InteractionActionType, InteractionPreset, InteractionTrigger, IoxBinding, IoxDataSource, IoxDropEvent, IoxFontManager, IoxInteraction, IoxSymbol, LayoutPresetChildStyles, LayoutPresetDef, 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.9.0",
+  "version": "4.11.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",