ng-form-foundry 0.3.4 → 0.4.0

package/index.d.ts

@@ -79,6 +79,51 @@ type Appearance = {
     noBorder?: boolean;
     /** Start this node's section panel collapsed. Ignored when `flatten` is set. */
     collapsed?: boolean;
+    /**
+     * Fixed grid for the node's scalar fields: `cols` fields per row, filling
+     * left-to-right; `rows` alone fills top-to-bottom into that many rows,
+     * adding columns as needed. Overrides {@link minFieldWidth}.
+     */
+    grid?: {
+        rows?: number;
+        cols?: number;
+    };
+    /**
+     * Narrowest a scalar field may get (a CSS length, e.g. `'12rem'`): each row
+     * fits as many equal-width fields as stay at least this wide and wraps the
+     * rest. Ignored when {@link grid} is set. With neither option the fields
+     * share one wrapping row, shrinking down to 10% of it.
+     */
+    minFieldWidth?: string;
+    /**
+     * Where boolean (checkbox-rendered) fields go. A checkbox doesn't need a
+     * field-sized slot — in a {@link grid} it would claim a whole track —
+     * so `'beginning'`/`'end'` gathers them into a compact wrapping row of
+     * natural-width items before/after the node's other fields. `'default'`
+     * (or unset) keeps them in declaration order within the field flow.
+     */
+    booleanFields?: 'beginning' | 'end' | 'default';
+    /**
+     * Narrowest a **text (string) field** may get in the flex flow (a CSS
+     * length): the row wraps rather than shrink such a field further. Enum
+     * fields (rendered as a select) are text-like and follow it too, as do a
+     * string/enum leaf-list's entries. No effect under {@link grid} /
+     * {@link minFieldWidth}, whose tracks size every field alike.
+     */
+    minTextFieldWidth?: string;
+    /**
+     * Narrowest a **number field** may get in the flex flow (a CSS length) —
+     * the numeric counterpart of {@link minTextFieldWidth}, typically smaller.
+     * Also bounds a number leaf-list's entries.
+     */
+    minNumberFieldWidth?: string;
+    /**
+     * Widest a **number field** may grow in the flex flow (a CSS length):
+     * numbers are short, so capping them keeps a lone number from stretching
+     * across space a text field could use. Also caps a number leaf-list's
+     * entries. No effect under {@link grid} / {@link minFieldWidth}.
+     */
+    maxNumberFieldWidth?: string;
 };
 type Leaf = LeafString | LeafNumber | LeafBoolean | LeafEnum;
 type LeafList<TKind extends Leaf['type'] = Leaf['type']> = {
@@ -153,6 +198,8 @@ type NodeChoice = {
     /**
      * Display labels for cases, keyed by case name — for anonymous/auto-named
      * branches whose keys are not human-friendly. Falls back to the case name.
+     * Selectors render these through `caseDisplayLabels`, which disambiguates
+     * colliding entries by each case's distinguishing fields.
      */
     caseLabels?: Record<string, string>;
     default?: string;
@@ -212,6 +259,19 @@ type DFormGroup<T extends NodeGroup> = FormGroup<FormGroupType<T>>;
  * clobber the active-case control.
  */
 declare function caseFields(body: ChoiceCase): Record<string, NodeType>;
+/**
+ * Display labels for a choice's cases, keyed by case name, with colliding
+ * labels made unique. Schema-supplied `caseLabels` can repeat (e.g. two
+ * O-RAN A1 scope branches labeled from the same discriminating field), which
+ * makes the case selector ambiguous. Unique labels pass through untouched;
+ * each colliding case first gains the fields that set it apart from its
+ * same-labeled peers — "UE ID (Group ID)" vs "UE ID (Slice ID)" — and any
+ * cases the field suffix cannot separate (no distinguishing fields, peers
+ * with identical field sets among a larger clash group, or distinguishing
+ * fields that share one display label) fall back to their case name, which
+ * is unique by construction.
+ */
+declare function caseDisplayLabels(choice: NodeChoice): Record<string, string>;
 /**
  * The active case of a choice: an explicit `__case` in the initial value, else
  * the case {@link inferChoiceCase} ranks best against the initial data (inline
@@ -320,6 +380,14 @@ declare function serializeForm(schema: NodeGroup, form: FormGroup): Record<strin
  */
 declare function defineSchema<const S extends NodeGroup>(schema: S): S;
 
+/**
+ * Inline CSS declarations (property → value) for a node's `.fields` area,
+ * derived from its {@link Appearance} (see the form component's
+ * `fieldsLayout`) and bound via `[style]`. Also handed to a stacked
+ * leaf-list's `layout` input so its entries repeat the same grid tracks.
+ */
+type LayoutStyles = Record<string, string>;
+
 declare function asFormControl(control: any): FormControl;
 declare function asFormArray(control: any): FormArray;
 declare function asFormGroup(control: any): FormGroup;
@@ -349,8 +417,67 @@ declare class DynamicRecursiveFormComponent implements OnInit {
      * menu) hand focus to the new field, like the form's own add button does.
      */
     readonly focusLeaf: _angular_core.InputSignal<string | null>;
+    /**
+     * Field-layout appearance cascading down from the parent group. The node's
+     * own `appearance` wins per property — see {@link mergeAppearance}.
+     */
+    readonly inheritedAppearance: _angular_core.InputSignal<Appearance | null>;
     /** True when the schema is a root group (rendered flat, without a wrapping card). */
     readonly root: _angular_core.Signal<boolean>;
+    /** The node's own `appearance` with inherited layout gaps filled in. */
+    protected readonly effectiveAppearance: _angular_core.Signal<Appearance | undefined>;
+    /** The layout subset this node's children inherit. */
+    protected readonly childAppearance: _angular_core.Signal<Appearance | null>;
+    /**
+     * The per-type width bounds are flex-flow-only, and their CSS custom
+     * properties inherit into leaf-list internals that the grid-mode resets
+     * cannot reach across the encapsulation boundary — so under a grid layout
+     * the variables are simply not set at all.
+     */
+    private flexOnly;
+    /** `minTextFieldWidth` for the `.fields` CSS custom property, or null. */
+    protected readonly textFieldMin: _angular_core.Signal<string | null>;
+    /** `minNumberFieldWidth` for the `.fields` CSS custom property, or null. */
+    protected readonly numberFieldMin: _angular_core.Signal<string | null>;
+    /** `maxNumberFieldWidth` for the `.fields` CSS custom property, or null. */
+    protected readonly numberFieldMax: _angular_core.Signal<string | null>;
+    /**
+     * True when the active grid defines explicit column tracks. Only then can a
+     * stacked leaf-list meaningfully span the row (`grid-column: 1 / -1`
+     * resolves `-1` to line 1 without an explicit column template) and repeat
+     * the tracks for its entries; in a rows-only grid the list stays a normal
+     * auto-flowed item.
+     */
+    protected readonly gridHasCols: _angular_core.Signal<boolean>;
+    /**
+     * Inline grid styles for the `.fields` area, from `appearance`: `grid`
+     * becomes explicit tracks (`cols` fields per row; `rows` alone fills
+     * top-to-bottom, adding columns as needed) and `minFieldWidth` becomes
+     * as-many-as-fit equal columns of at least that width. `grid` wins over
+     * `minFieldWidth`; with neither, `null` keeps the stylesheet's wrapping
+     * flex flow. Non-positive `rows`/`cols` are ignored.
+     */
+    protected readonly fieldsLayout: _angular_core.Signal<LayoutStyles | null>;
+    /**
+     * Whether the gathered boolean row would show anything: a plain boolean, an
+     * enabled presence boolean, or (while editable) an absent one's add button.
+     * Keeps a read-only form from rendering an empty `.boolean-fields` div,
+     * which would add a stray container gap.
+     */
+    protected booleanAreaVisible(): boolean;
+    /**
+     * Whether a leaf renders in the regular `.fields` flow: always, unless it is
+     * a boolean that {@link booleanPlacement} gathers into the `.boolean-fields`
+     * row instead.
+     */
+    protected inFieldFlow(child: Leaf): boolean;
+    /**
+     * Where `appearance.booleanFields` places the checkbox fields: `'beginning'`
+     * or `'end'` renders them grouped in the `.boolean-fields` row and excludes
+     * them from the regular field flow; `'default'` (also when the group has no
+     * boolean leaf to move) leaves the flow untouched.
+     */
+    protected readonly booleanPlacement: _angular_core.Signal<"beginning" | "end" | "default">;
     ngOnInit(): void;
     protected get nodeGroupChildrenList(): Array<{
         key: string;
@@ -374,9 +501,17 @@ declare class DynamicRecursiveFormComponent implements OnInit {
     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;
-    /** A synthetic flattened NodeGroup used to render the active case's fields against the choice's FormGroup. */
+    /**
+     * A synthetic flattened NodeGroup used to render the active case's fields
+     * against the choice's FormGroup. Carries the choice's own `appearance`
+     * (grid / field-width layout) onto the case fields.
+     */
     protected caseAsGroup(choice: NodeChoice, caseName: string): NodeGroup;
-    /** The display label for a case: the schema's `caseLabels` entry, else the case name. */
+    /**
+     * The display label for a case: the schema's `caseLabels` entry (colliding
+     * labels disambiguated by their distinguishing fields — see
+     * {@link caseDisplayLabels}), else the case name.
+     */
     caseLabel(choice: NodeChoice, caseName: string): string;
     /**
      * A copy of a group flagged to render its fields inline (no inner panel). Used
@@ -390,7 +525,7 @@ declare class DynamicRecursiveFormComponent implements OnInit {
     protected readonly asFormArray: typeof asFormArray;
     protected readonly asFormControl: typeof asFormControl;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<DynamicRecursiveFormComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<DynamicRecursiveFormComponent, "nff-dynamic-recursive-form", never, { "schema": { "alias": "schema"; "required": true; "isSignal": true; }; "initialValue": { "alias": "initialValue"; "required": false; "isSignal": true; }; "formGroup": { "alias": "formGroup"; "required": false; "isSignal": true; }; "index": { "alias": "index"; "required": false; "isSignal": true; }; "removable": { "alias": "removable"; "required": false; "isSignal": true; }; "title": { "alias": "title"; "required": false; "isSignal": true; }; "editable": { "alias": "editable"; "required": false; "isSignal": true; }; "addButtonCallback": { "alias": "addButtonCallback"; "required": false; "isSignal": true; }; "focusLeaf": { "alias": "focusLeaf"; "required": false; "isSignal": true; }; }, { "remove": "remove"; "editable": "editableChange"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<DynamicRecursiveFormComponent, "nff-dynamic-recursive-form", never, { "schema": { "alias": "schema"; "required": true; "isSignal": true; }; "initialValue": { "alias": "initialValue"; "required": false; "isSignal": true; }; "formGroup": { "alias": "formGroup"; "required": false; "isSignal": true; }; "index": { "alias": "index"; "required": false; "isSignal": true; }; "removable": { "alias": "removable"; "required": false; "isSignal": true; }; "title": { "alias": "title"; "required": false; "isSignal": true; }; "editable": { "alias": "editable"; "required": false; "isSignal": true; }; "addButtonCallback": { "alias": "addButtonCallback"; "required": false; "isSignal": true; }; "focusLeaf": { "alias": "focusLeaf"; "required": false; "isSignal": true; }; "inheritedAppearance": { "alias": "inheritedAppearance"; "required": false; "isSignal": true; }; }, { "remove": "remove"; "editable": "editableChange"; }, never, never, true, never>;
 }
 
 /** Metadata on a list-container node that lets the tree add items to its FormArray. */
@@ -453,6 +588,8 @@ interface TreeNode {
     presenceRemovable?: {
         key: string;
     };
+    /** Field-layout appearance inherited from ancestor groups, for the node's detail-section form. */
+    inherited?: Appearance | null;
     /** Present on a choice node: the choice schema and its FormGroup (holding `__case` + the active case's fields). */
     choice?: {
         schema: NodeChoice;
@@ -504,6 +641,12 @@ declare class ConfigEditorComponent implements OnDestroy {
      * can flip it itself and the host observes the change.
      */
     readonly editable: _angular_core.ModelSignal<boolean>;
+    /**
+     * Title for the root tree row and breadcrumb origin, overriding the schema's
+     * own `label`/`name`. Read when the tree is (re)built, so a later change
+     * shows on the next rebind or structural rebuild, not immediately.
+     */
+    readonly rootTitle: _angular_core.InputSignal<string | undefined>;
     root: TreeNode;
     selected: TreeNode | null;
     /** The selected subtree as a flat, breadcrumb-separated section list. */
@@ -563,7 +706,11 @@ declare class ConfigEditorComponent implements OnDestroy {
     activeCase(node: TreeNode): string | null;
     /** The display label of a choice node's active case, or null when no case is selected. */
     activeCaseLabel(node: TreeNode): string | null;
-    /** The display label for a case: the schema's `caseLabels` entry, else the case name. */
+    /**
+     * The display label for a case: the schema's `caseLabels` entry (colliding
+     * labels disambiguated by their distinguishing fields — see
+     * {@link caseDisplayLabels}), else the case name.
+     */
     protected caseLabel(choice: NodeChoice, caseName: string): string;
     /**
      * Switch a choice node's active case from its detail selector; the
@@ -620,6 +767,8 @@ declare class ConfigEditorComponent implements OnDestroy {
     private shapeOf;
     /** The instance id a container contributes to the shape signature. */
     private uidOf;
+    /** Root row title: host override, else schema label, else its name — with the {@link ROOT_SENTINEL} swapped for a generic title. */
+    private rootLabelOf;
     /** Rebuild the whole tree from schema + form and refresh the shape signature. */
     private rebuild;
     /** Re-point `selected` at the rebuilt tree: same path, else the closest surviving ancestor. */
@@ -664,13 +813,19 @@ declare class ConfigEditorComponent implements OnDestroy {
     /**
      * The node's own fields as a flattened schema: leaf and leafList children
      * only. Complex children are rendered as sections of their own, so the
-     * embedded form never draws nested section chrome. Null when there are none.
+     * embedded form never draws nested section chrome. The node's `appearance`
+     * (grid / field-width layout) carries into the slice. Null when there are
+     * no own fields.
      */
     private leafOnly;
     private buildTree;
     /** Build the tree node for a single non-leaf child, dispatching on its kind. Null when its control is missing. */
     private buildChildNode;
-    /** Synthetic group over a case's normalized fields, so a case body builds like any group. */
+    /**
+     * Synthetic group over a case's normalized fields, so a case body builds
+     * like any group. Carries the choice's own `appearance` so its layout
+     * reaches the case fields.
+     */
     private caseAsGroup;
     /** A node's display label: its schema `label`, else its record key. */
     private labelOf;
@@ -683,7 +838,7 @@ declare class ConfigEditorComponent implements OnDestroy {
      */
     private escapeSeg;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<ConfigEditorComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ConfigEditorComponent, "nff-config-editor", never, { "schema": { "alias": "schema"; "required": true; "isSignal": true; }; "formGroup": { "alias": "formGroup"; "required": true; "isSignal": true; }; "editable": { "alias": "editable"; "required": false; "isSignal": true; }; }, { "editable": "editableChange"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ConfigEditorComponent, "nff-config-editor", never, { "schema": { "alias": "schema"; "required": true; "isSignal": true; }; "formGroup": { "alias": "formGroup"; "required": true; "isSignal": true; }; "editable": { "alias": "editable"; "required": false; "isSignal": true; }; "rootTitle": { "alias": "rootTitle"; "required": false; "isSignal": true; }; }, { "editable": "editableChange"; }, never, never, true, never>;
 }
 
 declare class LeafRendererComponent implements AfterViewInit {
@@ -716,6 +871,13 @@ declare class LeafListRendererComponent implements OnInit {
     formArray: any;
     editable: boolean;
     minItems: 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
+     * stay aligned with the columns above; an inline (single-entry) list sits in
+     * one track and ignores it.
+     */
+    layout: LayoutStyles | null;
     message: EventEmitter<any>;
     matDialog: MatDialog;
     /**
@@ -725,11 +887,15 @@ declare class LeafListRendererComponent implements OnInit {
      * cannot. Consumed by the `:host(.stacked)` rule.
      */
     get stacked(): boolean;
+    /** The entries' value type as a host class, so type-scoped min-widths (`--nff-min-*-field-width`) can target them. */
+    get typeClass(): string;
+    /** Applies {@link layout} to the host (the entries' container) while stacked. */
+    get hostLayout(): LayoutStyles | null;
     ngOnInit(): void;
     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; }; }, { "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; }; "layout": { "alias": "layout"; "required": false; }; }, { "message": "message"; }, never, never, true, never>;
 }
 
 declare class LeafEnumRendererComponent {
@@ -750,6 +916,8 @@ declare class NodeGroupListRendererComponent implements OnInit, AfterViewInit {
     editable: boolean;
     minItems: number;
     maxItems: number;
+    /** Field-layout appearance from the enclosing group, forwarded to every item form. */
+    inheritedAppearance: Appearance | null;
     message: EventEmitter<any>;
     items: QueryList<DynamicRecursiveFormComponent>;
     cdr: ChangeDetectorRef;
@@ -761,7 +929,7 @@ declare class NodeGroupListRendererComponent implements OnInit, AfterViewInit {
     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; }; "minItems": { "alias": "minItems"; "required": false; }; "maxItems": { "alias": "maxItems"; "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; }; "minItems": { "alias": "minItems"; "required": false; }; "maxItems": { "alias": "maxItems"; "required": false; }; "inheritedAppearance": { "alias": "inheritedAppearance"; "required": false; }; }, { "message": "message"; }, never, never, true, never>;
 }
 
 /**
@@ -775,9 +943,17 @@ declare class NodeMapRendererComponent implements OnChanges {
     nodeMap: NodeMap;
     formGroup: FormGroup<any>;
     editable: boolean;
+    /** Field-layout appearance from the enclosing group, forwarded to group-valued entry forms. */
+    inheritedAppearance: Appearance | null;
     /** Ordered view of entry keys, kept stable across renames (`addControl` appends). */
     entryKeys: string[];
     ngOnChanges(changes: SimpleChanges): void;
+    /**
+     * What entry forms inherit: the enclosing group's layout with the map's own
+     * `appearance` merged over it. Counterpart of the config editor's map-entry
+     * threading in `buildChildNode`.
+     */
+    get entryAppearance(): Appearance | null;
     /** The value schema as a leaf (used when `value.kind === 'leaf'`). */
     get valueLeaf(): Leaf;
     /** The value schema as a group (used when `value.kind === 'nodeGroup'`). */
@@ -797,8 +973,8 @@ declare class NodeMapRendererComponent implements OnChanges {
     protected readonly asFormControl: typeof asFormControl;
     protected readonly asFormGroup: typeof asFormGroup;
     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; }; }, {}, never, never, true, 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; }; "inheritedAppearance": { "alias": "inheritedAppearance"; "required": false; }; }, {}, never, never, true, never>;
 }
 
-export { CASE_KEY, ConfigEditorComponent, DynamicRecursiveFormComponent, LeafEnumRendererComponent, LeafListRendererComponent, LeafRendererComponent, NodeGroupListRendererComponent, NodeMapRendererComponent, addMapEntry, buildControl, buildFormFromSchema, caseFields, defineSchema, removeMapEntry, renameMapEntry, resolveChoiceCase, serializeForm, switchChoiceCase, toWireValue };
+export { CASE_KEY, ConfigEditorComponent, DynamicRecursiveFormComponent, LeafEnumRendererComponent, LeafListRendererComponent, LeafRendererComponent, NodeGroupListRendererComponent, NodeMapRendererComponent, addMapEntry, buildControl, buildFormFromSchema, caseDisplayLabels, caseFields, defineSchema, removeMapEntry, renameMapEntry, resolveChoiceCase, serializeForm, switchChoiceCase, toWireValue };
 export type { AnonLeaf, Appearance, ChoiceCase, DFormControl, DFormGroup, FormGroupType, Leaf, LeafBase, LeafBoolean, LeafEnum, LeafList, LeafNumber, LeafRuntimeType, LeafString, NodeChoice, NodeGroup, NodeGroupList, NodeMap, NodeType };

package/package.json

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