@vectoriox/iox-builder 4.18.3 → 4.20.0

package/index.d.ts

@@ -234,7 +234,7 @@ interface InteractionPreset {
     name: string;
     interactions: IoxInteraction[];
 }
-type ElementState = 'hover' | 'active' | 'focus' | 'first-child' | 'last-child' | 'nth-child(odd)' | 'nth-child(even)' | 'parent-hover' | 'trigger-hover';
+type ElementState = 'hover' | 'active' | 'focus' | 'first-child' | 'last-child' | 'nth-child(odd)' | 'nth-child(even)' | 'parent-hover' | 'trigger-hover' | 'wrong' | 'accepted';
 /** Interaction pseudo-classes — compiled to .iox-node-{id}:state */
 declare const INTERACTION_STATES: ElementState[];
 /** Structural pseudo-classes — compiled to .iox-outer-{id}:state */
@@ -260,6 +260,16 @@ declare const RELATIONAL_STATE_BASE: Partial<Record<ElementState, string>>;
  */
 declare const TARGETED_STATES: ElementState[];
 declare const TARGETED_STATE_BASE: Partial<Record<ElementState, string>>;
+/**
+ * Design-time validation states (forms-and-inputs-plan.md Part 2, board 7 — "the failure
+ * design"). Not real CSS pseudo-classes: `IoxFieldComponent` already carries `.iox-invalid`/
+ * `.iox-valid` host classes it sets from `forceInvalid`/`showValid` (decision D5), so authoring
+ * "Wrong"/"Accepted" styles compiles to a CLASS-compound selector, not `:state`. Currently only
+ * meaningful on Field (or any future component with the same host classes).
+ */
+declare const VALIDATION_STATES: ElementState[];
+/** The host class each validation state maps to. */
+declare const VALIDATION_STATE_CLASS: Partial<Record<ElementState, string>>;
 declare const SUPPORTED_STATES: ElementState[];
 interface ComponentNode {
     id?: string;
@@ -301,6 +311,18 @@ interface ComponentNode {
      * appear in the trigger picker.
      */
     stateTriggers?: Partial<Record<ElementState, string>>;
+    /**
+     * Per-PART style overrides for a compound component (board 7 — "the failure design"). Keyed
+     * by the part's key (e.g. Field's `label`/`control`/`help`/`error`/`required`); the whole
+     * node's own base styling is unaffected and keeps using `styleTraits`/`stateStyles` directly
+     * — there is no `'whole'` entry here. Each part's `stateStyles` reuses the SAME `ElementState`
+     * union as the node itself, so a part can vary by hover/wrong/accepted/etc. Compiled via
+     * `buildPartSelector` (`@vectoriox/iox-ui`) — no new compiler, no second code path.
+     */
+    partStyles?: Record<string, {
+        styleProps?: Record<string, any>;
+        stateStyles?: Partial<Record<ElementState, Record<string, any>>>;
+    }>;
     /**
      * Per-breakpoint overrides — SPARSE, shaped like `stateStyles`:
      * `{ mobile: { styleProps: {…}, stateStyles: { hover: {…} } } }`. Base styles stay in
@@ -400,6 +422,17 @@ interface StyleTraitGroup {
     category: string;
     traits: ComponentTrait[];
 }
+/**
+ * One styleable sub-element of a compound component (board 7 — "the failure design"). `key`
+ * identifies it in `ComponentNode.partStyles`; `className` is the stable class the component's
+ * OWN template already renders (e.g. `IoxFieldComponent`'s `iox-field__error`) — the part
+ * mechanism styles what already exists, it does not invent new markup.
+ */
+interface StylePart {
+    key: string;
+    label: string;
+    className: string;
+}
 declare function generateNodeId(): string;
 declare class ComponentConfig {
     id: string;
@@ -422,6 +455,9 @@ declare class ComponentConfig {
     /** Imperative methods this component exposes that can be used as interaction actions.
      *  The Interactions panel appends these to the action dropdown when targeting this component. */
     componentMethods?: ComponentMethodDef[];
+    /** Styleable sub-elements (board 7). Absent/empty means no piece selector shows in the Style
+     *  panel — most components have no addressable descendant, so this stays opt-in. */
+    parts?: StylePart[];
     constructor(type: string, selector: string, icon?: string, category?: string);
     /** Override specific trait defaults after styleTraits are set.
      *  Call this at the end of each subclass constructor. */
@@ -801,7 +837,14 @@ declare enum PanelEventTypes {
     /** CLICK-TO-INSERT (B2): a components-panel entry was clicked. Carries the same payload a drag
      *  would (`string` component type, or a block / symbol object). The builder resolves WHERE from
      *  the current selection — see `resolveInsertTarget`. */
-    INSERT_COMPONENT = "insertcomponent"
+    INSERT_COMPONENT = "insertcomponent",
+    /** A panel wants to select a NODE it already has a reference to (e.g. the Form's nested field
+     *  list). Carries `{ node }`. `OverlayService.setSelect()` alone only updates the overlay's own
+     *  visual state — `selectedItem`/`selectedPath` (breadcrumb) and every other panel's idea of
+     *  "what's selected" stay stale unless the SAME `_emitElementSelect` a real canvas click goes
+     *  through also runs. This event is that path for code outside `BuilderComponent` itself,
+     *  mirroring what `onTreeNodeSelect`/`onCrumbSelect` already do internally. */
+    SELECT_NODE = "selectnode"
 }
 interface PanelEvent {
     type: PanelEventTypes;
@@ -1064,6 +1107,16 @@ 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;
+    /**
+     * Write or clear the styles for one PART of a compound component (board 7 — "the failure
+     * design"), optionally further scoped to a validation state ('wrong'/'accepted'). Compiles
+     * through the exact same `compile()` every other rule uses — `buildPartSelector` (shared,
+     * `@vectoriox/iox-ui`) just builds a different selector string. Unlike interaction/relational/
+     * targeted states, a validation state compounds a CLASS onto the node (`.iox-invalid`), not a
+     * `:pseudo-class`, since `IoxFieldComponent` sets that class itself from `forceInvalid`/
+     * `showValid` — there is no real "wrong" pseudo-class to hook.
+     */
+    upsertPart(nodeId: string, partClassName: string, styles: Record<string, any>, state?: ElementState): 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
@@ -1950,6 +2003,9 @@ declare class RenderDirective implements OnInit, OnDestroy {
     private childSubs;
     /** Host element drag was registered on (collapsed path) — unregistered on destroy. */
     private hostDragEl;
+    /** type -> its declared parts (board 7), cached so partClassNameFor doesn't instantiate a
+     *  fresh ComponentConfig on every render — same precedent as the layer tree's own icon cache. */
+    private static readonly partsCache;
     constructor(vcr: ViewContainerRef, injector: Injector, envInjector: EnvironmentInjector, doc: Document, registryService: ComponentRegistryService, overlayService: OverlayService, styleRegistry: StyleRegistryService, interactionEngine: InteractionEngineService, cdr: ChangeDetectorRef, panelEventService: PanelEventService, dragEngine: DragEngineService);
     /**
      * Tag for a variable-tag directive-host (whose selector lists several tags, so
@@ -1969,6 +2025,9 @@ declare class RenderDirective implements OnInit, OnDestroy {
      * registry — at state-restore time the parent isn't registered yet, since it registers only
      * AFTER rendering its children). Used to key relational (parent-hover) rules. (issue #1)
      */
+    /** The stable class a declared part compiles against, e.g. ('Field', 'error') -> 'iox-field__error'.
+     *  Undefined when the type declares no such part (or no parts at all) — caller skips it. */
+    private partClassNameFor;
     private resolveParentNodeId;
     /** Nearest ANCESTOR of the styled element that is a registered iox-node AND contains the trigger
      *  element — i.e. the DOM equivalent of `nearestCommonAncestorId`, resolved per rendered instance.
@@ -3073,6 +3132,14 @@ declare class GalleryConfig extends ComponentConfig {
     constructor();
 }
 
+/**
+ * Field's styleable sub-elements (board 7 — "the failure design"). Class names match
+ * `IoxFieldComponent`'s own template exactly (`@vectoriox/iox-ui`) — the part mechanism styles
+ * what that component already renders, it does not invent new markup. "Whole field" (the node's
+ * own base styling) is not listed here — the Style panel always offers it as the implicit first
+ * choice, falling back to the node's ordinary `styleTraits`.
+ */
+declare const FIELD_PARTS: StylePart[];
 /**
  * Form — the container that scopes its fields by ANCESTRY (decision D1).
  *
@@ -3168,5 +3235,5 @@ declare class TextBlockComponentConfig extends ComponentConfig {
     constructor();
 }
 
-export { ACTION_TYPE_OPTIONS, AuditCode, AuditPanelComponent, AuditSeverity, BODY_CRUMB_LABEL, BREAKPOINT_PRESENTATION, BUILDER_CANVAS_CONTAINER, BUILDER_CHROME_EN, 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, FormStateService, FormSuccessComponentConfig, GalleryConfig, GroupStyleConfig, INTERACTION_STATES, INVERSE_ACTION, IOX_BUILDER_LABELS, 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, defaultBuilderLabels, 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, BuilderLabelResolver, ComponentEventDef, ComponentMethodDef, ComponentNode, ComponentTrait, CreateConfig, Crumb, DragPayload, DsFilterByQueryParam, DsFilterByRouteParam, ElementState, FormPresetDef, FormPresetField, FormStateSnapshot, HistoryEntry, InsertTarget, InteractionAction, InteractionActionType, InteractionPreset, InteractionTrigger, IoxBinding, IoxDataSource, IoxDropEvent, IoxFontManager, IoxInteraction, IoxSymbol, LayoutPresetChildStyles, LayoutPresetDef, NodeRef, OverlayBoxModel, OverlayBoxSpacing, OverlayEntry, PageRouteAnimationSettings, PageScrollSettings, PageSettings, PanelEvent, QuadSizeSegment, RouteAnimationPreset, ScreenWidthOption, SelectionBadge, StyleMap, StylePreset, StyleTrait, StyleTraitGroup, TraitOptionMap, TraitSelectOption, TraitShowCondition, TreePathNode, ViewportState, ZoomOption };
+export { ACTION_TYPE_OPTIONS, AuditCode, AuditPanelComponent, AuditSeverity, BODY_CRUMB_LABEL, BREAKPOINT_PRESENTATION, BUILDER_CANVAS_CONTAINER, BUILDER_CHROME_EN, 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, FIELD_PARTS, FORM_PRESETS, FORM_TYPE, FieldComponentConfig, FieldGroupComponentConfig, FormComponentConfig, FormErrorComponentConfig, FormStateService, FormSuccessComponentConfig, GalleryConfig, GroupStyleConfig, INTERACTION_STATES, INVERSE_ACTION, IOX_BUILDER_LABELS, 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, VALIDATION_STATES, VALIDATION_STATE_CLASS, ViewportService, ZOOM_OPTIONS, arrayItemSchemaFields, arraySchemaFields, auditNodes, buildFormPreset, buildFullStyleTraits, buildLayoutPreset, buildPresetStyleTraits, canFluidise, collapseColumnsProps, columnCountOf, defaultBuilderLabels, 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, BuilderLabelResolver, ComponentEventDef, ComponentMethodDef, ComponentNode, ComponentTrait, CreateConfig, Crumb, DragPayload, DsFilterByQueryParam, DsFilterByRouteParam, ElementState, FormPresetDef, FormPresetField, FormStateSnapshot, HistoryEntry, InsertTarget, InteractionAction, InteractionActionType, InteractionPreset, InteractionTrigger, IoxBinding, IoxDataSource, IoxDropEvent, IoxFontManager, IoxInteraction, IoxSymbol, LayoutPresetChildStyles, LayoutPresetDef, NodeRef, OverlayBoxModel, OverlayBoxSpacing, OverlayEntry, PageRouteAnimationSettings, PageScrollSettings, PageSettings, PanelEvent, QuadSizeSegment, RouteAnimationPreset, ScreenWidthOption, SelectionBadge, StyleMap, StylePart, StylePreset, StyleTrait, StyleTraitGroup, TraitOptionMap, TraitSelectOption, TraitShowCondition, TreePathNode, ViewportState, ZoomOption };

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@vectoriox/iox-builder",
-  "version": "4.18.3",
+  "version": "4.20.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.24.0",
+    "@vectoriox/iox-ui": ">=4.41.0",
     "interactjs": "^1.10.27",
     "primeng": ">=20.0.0",
     "swiper": ">=12.0.0",