ng-form-foundry 0.5.4 → 0.6.0

package/index.d.ts

@@ -152,6 +152,14 @@ type LeafList<TKind extends Leaf['type'] = Leaf['type']> = {
     maxItems?: number;
     /** Present every item in this base — see {@link LeafNumber.radix}. */
     radix?: 2 | 8 | 16;
+    /**
+     * Optional scalar list whose *presence itself* is data — an absent key,
+     * distinct from a present-but-empty list. Off means no control and no key in
+     * the value; on means the (possibly empty) list is materialized. Mirrors
+     * {@link NodeGroup.presence}; lets a round-trip distinguish `x = ( )` (present,
+     * empty) from an absent `x`.
+     */
+    presence?: boolean;
 };
 type NodeGroupList = {
     kind: 'nodeGroupList';
@@ -161,6 +169,8 @@ type NodeGroupList = {
     type: NodeGroup;
     minItems?: number;
     maxItems?: number;
+    /** Optional list whose presence is itself data — see {@link LeafList.presence}. */
+    presence?: boolean;
 };
 type NodeGroup = {
     kind: 'nodeGroup';
@@ -327,6 +337,24 @@ declare function addMapEntry(group: FormGroup, map: NodeMap, key?: string): stri
 declare function renameMapEntry(group: FormGroup, map: NodeMap, oldKey: string, newKey: string): boolean;
 /** Remove entry `key` unless the map is at `minEntries`. Returns whether it was removed. */
 declare function removeMapEntry(group: FormGroup, map: NodeMap, key: string): boolean;
+/**
+ * Materialize or de-materialize an optional (presence) child of `group`,
+ * mirroring the presence toggle the form UI offers — but callable by any host
+ * holding the {@link FormGroup}, for a key at any depth. `present: true` builds
+ * the child fresh from `schema` (seeded with `initial` if given; nested
+ * presence descendants start absent, as {@link buildControl}); `present: false`
+ * removes it, dropping the key from the form value.
+ *
+ * The materialize direction is why the coupling exists: a materialized
+ * non-nullable presence leaf carries `Validators.required`, because an
+ * enabled-but-empty key would serialize as `null` and fail a typed schema. A
+ * host that materializes fields for editing therefore drops the ones left
+ * empty on cancel by de-materializing them — this API is that primitive.
+ *
+ * `schema` must be the presence node for `key`; a non-presence `schema` is a
+ * no-op. Returns whether the form changed.
+ */
+declare function setNodePresence(group: FormGroup, schema: NodeType, key: string, present: boolean, initial?: unknown): boolean;
 /**
  * Build the `AbstractControl` for a single schema node.
  *
@@ -525,7 +553,8 @@ declare class DynamicRecursiveFormComponent implements OnInit {
      * Add or remove a presence node's control on this form — any presence kind:
      * group, leaf, map, or choice. Removing it drops the key from `form.value`;
      * adding it builds the control fresh from its schema (nested presence
-     * children start absent).
+     * children start absent). Delegates to {@link setNodePresence}, the
+     * host-callable primitive.
      */
     toggleNodePresence(key: string, schema: NodeType, present: boolean): void;
     /**
@@ -549,6 +578,14 @@ declare class DynamicRecursiveFormComponent implements OnInit {
      * rendered field when the toggle just created it.
      */
     toggleLeafPresence(key: string, schema: Leaf, present: boolean): void;
+    /**
+     * Materialize an absent presence (optional / `advisoryRequired`) list *with
+     * its first entry* — clicking "Add <list>" makes the first entry appear at
+     * once. An optional list has no present-empty state: removing the last entry
+     * de-materializes it (→ absent). A required list is always present instead and
+     * uses the renderer's own "Add item" affordance, so it never routes here.
+     */
+    addPresenceList(key: string, schema: NodeType): void;
     protected objectKeys(obj: Record<string, unknown>): string[];
     /** The active case name of a choice control, or null if none is selected. */
     protected activeCase(key: string): string | null;
@@ -638,6 +675,7 @@ interface TreeNode {
     /** Present on a present optional child node: drives the row's remove control. */
     presenceRemovable?: {
         key: string;
+        schema: NodeType;
     };
     /** Field-layout appearance inherited from ancestor groups, for the node's detail-section form. */
     inherited?: Appearance | null;
@@ -724,6 +762,7 @@ declare class ConfigEditorComponent implements OnDestroy {
     private shape;
     private changes?;
     private readonly host;
+    private readonly cdr;
     /** Stable per-instance ids for the shape signature, so replacing a control (setControl) reads as a structural change. */
     private readonly controlIds;
     private controlIdSeq;
@@ -731,6 +770,21 @@ declare class ConfigEditorComponent implements OnDestroy {
     ngOnDestroy(): void;
     /** Bind the editor to a schema/form pair: fresh tree, root selection, and shape-sync subscription. */
     private attach;
+    /**
+     * Force the editor to re-read the bound form. A leaf field normally reflects
+     * an external `setValue` on its own — the reactive value accessor writes the
+     * value synchronously, no change detection needed — so this is only for the
+     * corners that bypass that: a structural change made with
+     * `{ emitEvent: false }` (the tree wouldn't otherwise rebuild), a non-reactive
+     * display (the case selector, a map key) that needs re-reading, or a host
+     * whose change detector was detached during the mutation.
+     *
+     * It re-syncs the tree structure and **tears down and recreates** the detail
+     * sections, so every rendered control rebinds to the live form and re-pulls
+     * its current value — even a field whose bound input somehow missed the
+     * external write.
+     */
+    refresh(): void;
     select(node: TreeNode, reveal?: boolean): void;
     /**
      * Root-to-`target` path for the detail-pane breadcrumb (inclusive of both ends),
@@ -940,6 +994,7 @@ declare class LeafListRendererComponent implements OnInit {
     formArray: any;
     editable: boolean;
     minItems: number;
+    maxItems: number;
     /**
      * The parent group's grid layout (its `fieldsLayout` styles). A stacked list
      * spans the parent's full row, so its entries repeat the same tracks and
@@ -948,6 +1003,12 @@ declare class LeafListRendererComponent implements OnInit {
      */
     layout: LayoutStyles | null;
     message: EventEmitter<any>;
+    /**
+     * Emitted from the empty-list remove button when the list is a presence list —
+     * the host removes the whole list (de-materializes it, → absent). Only wired
+     * for a `presence` `leafList`; the parent maps it to `setNodePresence`.
+     */
+    removeList: EventEmitter<void>;
     matDialog: MatDialog;
     /**
      * Take a full-width row of its own once the array holds more than one entry.
@@ -961,10 +1022,14 @@ declare class LeafListRendererComponent implements OnInit {
     /** Applies {@link layout} to the host (the entries' container) while stacked. */
     get hostLayout(): LayoutStyles | null;
     ngOnInit(): void;
+    get effectiveMin(): number;
+    get effectiveMax(): number;
+    /** Whether another item may be appended (below the effective maximum). */
+    get canAdd(): boolean;
     removeItem($index: number): void;
     addItem(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<LeafListRendererComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<LeafListRendererComponent, "nff-leaf-list-renderer", never, { "leaf_": { "alias": "leaf_"; "required": false; }; "initialValue": { "alias": "initialValue"; "required": false; }; "formArray": { "alias": "formArray"; "required": false; }; "editable": { "alias": "editable"; "required": false; }; "minItems": { "alias": "minItems"; "required": false; }; "layout": { "alias": "layout"; "required": false; }; }, { "message": "message"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<LeafListRendererComponent, "nff-leaf-list-renderer", never, { "leaf_": { "alias": "leaf_"; "required": false; }; "initialValue": { "alias": "initialValue"; "required": false; }; "formArray": { "alias": "formArray"; "required": false; }; "editable": { "alias": "editable"; "required": false; }; "minItems": { "alias": "minItems"; "required": false; }; "maxItems": { "alias": "maxItems"; "required": false; }; "layout": { "alias": "layout"; "required": false; }; }, { "message": "message"; "removeList": "removeList"; }, never, never, true, never>;
 }
 
 declare class LeafEnumRendererComponent {
@@ -1053,17 +1118,27 @@ declare class NodeGroupListRendererComponent implements OnInit, AfterViewInit {
     /** Field-layout appearance from the enclosing group, forwarded to every item form. */
     inheritedAppearance: Appearance | null;
     message: EventEmitter<any>;
+    /**
+     * Emitted when the last entry of a presence (optional / advisoryRequired) list
+     * is removed — the host de-materializes the whole list (→ absent). An optional
+     * list has no present-empty state; a required list never routes here.
+     */
+    removeList: EventEmitter<void>;
     items: QueryList<DynamicRecursiveFormComponent>;
     cdr: ChangeDetectorRef;
     ngOnInit(): void;
+    get effectiveMin(): number;
+    get effectiveMax(): number;
+    /** Whether another item may be appended (below the effective maximum). */
+    get canAdd(): boolean;
     ngAfterViewInit(): void;
     removeItem($index: number): void;
-    addItem: (index: number) => void;
+    addItem: (index?: number) => void;
     setLastEditable(): void;
     asFormGroup(group: any): FormGroup;
     getTitle($index: number): string;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<NodeGroupListRendererComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NodeGroupListRendererComponent, "nff-node-group-list-renderer", never, { "nodeGroupList": { "alias": "nodeGroupList"; "required": false; }; "initialValue": { "alias": "initialValue"; "required": false; }; "formArray": { "alias": "formArray"; "required": false; }; "editable": { "alias": "editable"; "required": false; }; "showAbsentOptionals": { "alias": "showAbsentOptionals"; "required": false; }; "minItems": { "alias": "minItems"; "required": false; }; "maxItems": { "alias": "maxItems"; "required": false; }; "inheritedAppearance": { "alias": "inheritedAppearance"; "required": false; }; }, { "message": "message"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NodeGroupListRendererComponent, "nff-node-group-list-renderer", never, { "nodeGroupList": { "alias": "nodeGroupList"; "required": false; }; "initialValue": { "alias": "initialValue"; "required": false; }; "formArray": { "alias": "formArray"; "required": false; }; "editable": { "alias": "editable"; "required": false; }; "showAbsentOptionals": { "alias": "showAbsentOptionals"; "required": false; }; "minItems": { "alias": "minItems"; "required": false; }; "maxItems": { "alias": "maxItems"; "required": false; }; "inheritedAppearance": { "alias": "inheritedAppearance"; "required": false; }; }, { "message": "message"; "removeList": "removeList"; }, never, never, true, never>;
 }
 
 /**
@@ -1094,6 +1169,10 @@ declare class NodeMapRendererComponent implements OnChanges {
     get valueLeaf(): Leaf;
     /** The value schema as a group (used when `value.kind === 'nodeGroup'`). */
     get valueGroup(): NodeGroup;
+    /** Narrowing casts for the complex value kinds the template renders. */
+    protected asLeafList(v: unknown): LeafList;
+    protected asNodeGroupList(v: unknown): NodeGroupList;
+    protected asNodeMap(v: unknown): NodeMap;
     get atMax(): boolean;
     get atMin(): boolean;
     /** Append a new entry under a unique placeholder key. Delegates to {@link addMapEntry}. */
@@ -1108,9 +1187,10 @@ declare class NodeMapRendererComponent implements OnChanges {
     renameEntry(oldKey: string, rawKey: string): void;
     protected readonly asFormControl: typeof asFormControl;
     protected readonly asFormGroup: typeof asFormGroup;
+    protected readonly asFormArray: typeof asFormArray;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<NodeMapRendererComponent, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<NodeMapRendererComponent, "nff-node-map-renderer", never, { "nodeMap": { "alias": "nodeMap"; "required": false; }; "formGroup": { "alias": "formGroup"; "required": false; }; "editable": { "alias": "editable"; "required": false; }; "showAbsentOptionals": { "alias": "showAbsentOptionals"; "required": false; }; "inheritedAppearance": { "alias": "inheritedAppearance"; "required": false; }; }, {}, never, never, true, never>;
 }
 
-export { CASE_KEY, ConfigEditorComponent, DynamicRecursiveFormComponent, LeafEnumRendererComponent, LeafListRendererComponent, LeafRendererComponent, NodeGroupListRendererComponent, NodeMapRendererComponent, RadixInputDirective, addMapEntry, buildControl, buildFormFromSchema, caseDisplayLabels, caseFields, defineSchema, formatRadix, removeMapEntry, renameMapEntry, resolveChoiceCase, serializeForm, switchChoiceCase, toWireValue };
+export { CASE_KEY, ConfigEditorComponent, DynamicRecursiveFormComponent, LeafEnumRendererComponent, LeafListRendererComponent, LeafRendererComponent, NodeGroupListRendererComponent, NodeMapRendererComponent, RadixInputDirective, addMapEntry, buildControl, buildFormFromSchema, caseDisplayLabels, caseFields, defineSchema, formatRadix, removeMapEntry, renameMapEntry, resolveChoiceCase, serializeForm, setNodePresence, switchChoiceCase, toWireValue };
 export type { AnonLeaf, Appearance, ChoiceCase, DFormControl, DFormGroup, FormGroupType, Leaf, LeafBase, LeafBoolean, LeafEnum, LeafList, LeafNumber, LeafRuntimeType, LeafString, NodeChoice, NodeGroup, NodeGroupList, NodeMap, NodeType, Radix };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ng-form-foundry",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "description": "Build fully-typed Angular Reactive Forms and Angular Material UI from a declarative, recursive form-description schema.",
   "keywords": [
     "angular",