ng-form-foundry 0.4.0 → 0.5.0

package/index.d.ts

@@ -1,6 +1,6 @@
-import { FormControl, FormArray, FormGroup } from '@angular/forms';
+import { FormControl, FormArray, FormGroup, ControlValueAccessor, Validator, AbstractControl, ValidationErrors } from '@angular/forms';
 import * as _angular_core from '@angular/core';
-import { OnInit, OnDestroy, AfterViewInit, ElementRef, EventEmitter, QueryList, ChangeDetectorRef, OnChanges, SimpleChanges } from '@angular/core';
+import { OnInit, OnDestroy, AfterViewInit, ElementRef, EventEmitter, OnChanges, QueryList, ChangeDetectorRef, SimpleChanges } from '@angular/core';
 import { MatDialog } from '@angular/material/dialog';
 
 type LeafRuntimeType<T> = T extends 'string' ? string : T extends 'number' ? number : T extends 'boolean' ? boolean : T extends 'enum' ? string | number : never;
@@ -51,6 +51,13 @@ type LeafString = LeafBase & {
     maxLength?: number;
     /** Semantic string format (JSON Schema `format`); adds a matching validator. */
     format?: 'email' | 'uri' | 'url';
+    /**
+     * Present the value in this base — for the string leaves that carry an
+     * integer beyond ±2^53 as its exact decimal digits. The control value stays
+     * that decimal-digit string (`pattern` keeps validating it); only the
+     * rendered text is based. See {@link LeafNumber.radix}.
+     */
+    radix?: 2 | 8 | 16;
 };
 type LeafNumber = LeafBase & {
     type: 'number';
@@ -63,6 +70,14 @@ type LeafNumber = LeafBase & {
     max?: number;
     /** Require the value to be an integer multiple of this number (JSON Schema `multipleOf`). */
     multipleOf?: number;
+    /**
+     * Present the value in this base (16 hex, 8 octal, 2 binary) instead of
+     * decimal — a display hint set by transformers when the source document
+     * wrote the literal that way (`0x1A`, `0o17`, `0b101`). The control value
+     * stays a plain number, so every numeric validator applies unchanged; only
+     * the rendered text is based. See `RadixInputDirective`.
+     */
+    radix?: 2 | 8 | 16;
 };
 type LeafBoolean = LeafBase & {
     type: 'boolean';
@@ -135,6 +150,8 @@ type LeafList<TKind extends Leaf['type'] = Leaf['type']> = {
     type: TKind;
     minItems?: number;
     maxItems?: number;
+    /** Present every item in this base — see {@link LeafNumber.radix}. */
+    radix?: 2 | 8 | 16;
 };
 type NodeGroupList = {
     kind: 'nodeGroupList';
@@ -409,6 +426,17 @@ declare class DynamicRecursiveFormComponent implements OnInit {
     readonly title: _angular_core.InputSignal<string | undefined>;
     /** Whether fields accept input. Two-way: also toggled by the built-in edit control. */
     readonly editable: _angular_core.ModelSignal<boolean>;
+    /**
+     * Preview absent optional (presence) leaves as **ghost fields**: the field
+     * renders read-only and empty — its schema `default`, if any, shown as the
+     * placeholder — with a (+) button that incorporates it into the form, so the
+     * user sees the complete form surface. A ghost holds **no control in the
+     * form**: it never appears in `value`/`getRawValue()`/`serializeForm` output
+     * and never affects validity until incorporated. Replaces the default
+     * "Add <field>" button affordance; ignored while the form is not editable
+     * (read-only mode hides structural affordances, ghosts included).
+     */
+    readonly showAbsentOptionals: _angular_core.InputSignal<boolean>;
     /** Invoked with {@link index} to append a new sibling form to a parent list. */
     readonly addButtonCallback: _angular_core.InputSignal<((index: number) => void) | null>;
     /**
@@ -493,6 +521,22 @@ declare class DynamicRecursiveFormComponent implements OnInit {
      * children start absent).
      */
     toggleNodePresence(key: string, schema: NodeType, present: boolean): void;
+    /**
+     * The detached stand-in control a ghost field renders against. Never added
+     * to {@link formGroup} — that detachment is the whole guarantee: a ghost
+     * cannot reach `value`, `getRawValue()`, or validity. Always `null`-valued
+     * (the schema default shows as a placeholder instead, see
+     * {@link ghostPlaceholder}); cached per key so change detection re-reads a
+     * stable instance.
+     */
+    protected ghostControl(key: string): FormControl;
+    private readonly ghostControls;
+    /**
+     * A ghost field's placeholder: the leaf's `default`, or empty — spelled in
+     * the leaf's `radix` when it has one, matching how the incorporated field
+     * will display it.
+     */
+    protected ghostPlaceholder(schema: Leaf): string;
     /**
      * {@link toggleNodePresence} for a presence leaf, additionally focusing the
      * rendered field when the toggle just created it.
@@ -525,7 +569,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; }; "inheritedAppearance": { "alias": "inheritedAppearance"; "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; }; "showAbsentOptionals": { "alias": "showAbsentOptionals"; "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. */
@@ -849,6 +893,8 @@ declare class LeafRendererComponent implements AfterViewInit {
     editable: boolean;
     /** Focus the field once rendered — for fields the user just added (e.g. an enabled presence leaf). */
     autofocus: boolean;
+    /** Placeholder for the empty field — e.g. a ghost preview showing the schema default. */
+    placeholder: string;
     /** Emitted when the user removes this field (e.g. an optional presence leaf). */
     readonly remove: _angular_core.OutputEmitterRef<void>;
     constructor(elementRef: ElementRef<HTMLElement>);
@@ -862,7 +908,7 @@ declare class LeafRendererComponent implements AfterViewInit {
      */
     get errorText(): string;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<LeafRendererComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<LeafRendererComponent, "nff-leaf-renderer", never, { "leaf_": { "alias": "leaf_"; "required": false; }; "control": { "alias": "control"; "required": false; }; "removable": { "alias": "removable"; "required": false; }; "editable": { "alias": "editable"; "required": false; }; "autofocus": { "alias": "autofocus"; "required": false; }; }, { "remove": "remove"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<LeafRendererComponent, "nff-leaf-renderer", never, { "leaf_": { "alias": "leaf_"; "required": false; }; "control": { "alias": "control"; "required": false; }; "removable": { "alias": "removable"; "required": false; }; "editable": { "alias": "editable"; "required": false; }; "autofocus": { "alias": "autofocus"; "required": false; }; "placeholder": { "alias": "placeholder"; "required": false; }; }, { "remove": "remove"; }, never, never, true, never>;
 }
 
 declare class LeafListRendererComponent implements OnInit {
@@ -905,8 +951,71 @@ declare class LeafEnumRendererComponent {
     removable: boolean;
     remove: any;
     editable: boolean;
+    /** Placeholder for the empty select — e.g. a ghost preview showing the schema default. */
+    placeholder: string;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<LeafEnumRendererComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<LeafEnumRendererComponent, "nff-leaf-enum-renderer", never, { "leafEnum": { "alias": "leafEnum"; "required": false; }; "initialValue": { "alias": "initialValue"; "required": false; }; "control": { "alias": "control"; "required": false; }; "removable": { "alias": "removable"; "required": false; }; "remove": { "alias": "remove"; "required": false; }; "editable": { "alias": "editable"; "required": false; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<LeafEnumRendererComponent, "nff-leaf-enum-renderer", never, { "leafEnum": { "alias": "leafEnum"; "required": false; }; "initialValue": { "alias": "initialValue"; "required": false; }; "control": { "alias": "control"; "required": false; }; "removable": { "alias": "removable"; "required": false; }; "remove": { "alias": "remove"; "required": false; }; "editable": { "alias": "editable"; "required": false; }; "placeholder": { "alias": "placeholder"; "required": false; }; }, {}, never, never, true, never>;
+}
+
+type Radix = 2 | 8 | 16;
+/**
+ * An integer as a prefixed literal in the given base: `0x1A`, `0o17`, `0b101`,
+ * hex digits uppercase, a leading `-` for negatives. Accepts a number or a
+ * decimal-digit string (the beyond-safe-range carry).
+ */
+declare function formatRadix(value: number | string, radix: Radix): string;
+/**
+ * Presents an integer control in hex/octal/binary while the control value
+ * stays what the schema and validators expect: a plain `number`, or — with
+ * `nffRadixValueType="string"` — the exact decimal-digit string that carries
+ * integers beyond the safe range (±(2^53 − 1)). Only the visible text is
+ * based (`0x1A`, `0o17`, `0b101`); `min`/`max`/`integer`/`pattern` validators
+ * therefore apply unchanged.
+ *
+ * Typing accepts the base's digits with or without prefix, case-insensitive
+ * (`0q` is also accepted for octal, as in libconfig); the text normalizes to
+ * the prefixed spelling on blur. Unparseable text sets the control to `null`
+ * with a `radixFormat` error — never the raw text, so an invalid entry can
+ * reach neither the wire value nor a typed write-back; the text itself stays
+ * in the input for the user to correct. In number mode a magnitude beyond the
+ * safe range likewise yields `null` with `radixRange` instead of a silently
+ * rounded number.
+ */
+declare class RadixInputDirective implements ControlValueAccessor, Validator, OnChanges {
+    protected readonly el: ElementRef<HTMLInputElement>;
+    /** The display base. */
+    radix: Radix;
+    /**
+     * What the control carries: `'number'` (default), or `'string'` for the
+     * decimal-digit bigint carry of a string leaf.
+     */
+    valueType: 'number' | 'string';
+    private modelValue;
+    private parseError;
+    private onChange;
+    private onTouched;
+    private onValidatorChange;
+    constructor(el: ElementRef<HTMLInputElement>);
+    /** A changed base (or carry mode) re-renders the model and re-validates. */
+    ngOnChanges(): void;
+    writeValue(value: unknown): void;
+    registerOnChange(fn: (value: unknown) => void): void;
+    registerOnTouched(fn: () => void): void;
+    registerOnValidatorChange(fn: () => void): void;
+    setDisabledState(isDisabled: boolean): void;
+    validate(_control: AbstractControl): ValidationErrors | null;
+    protected onInput(text: string): void;
+    protected onBlur(): void;
+    /** Show the model in its base; unrepresentable models pass through as text. */
+    private render;
+    /**
+     * `[-+]?` + this base's optional prefix + this base's digits, or null. The
+     * prefix is base-specific so hex digit runs that merely *look* like another
+     * base's prefix (`0b11` as hex 0x0B11) parse as digits, not as a rejection.
+     */
+    private parse;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<RadixInputDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<RadixInputDirective, "input[nffRadixInput]", never, { "radix": { "alias": "nffRadixInput"; "required": true; }; "valueType": { "alias": "nffRadixValueType"; "required": false; }; }, {}, never, never, true, never>;
 }
 
 declare class NodeGroupListRendererComponent implements OnInit, AfterViewInit {
@@ -914,6 +1023,8 @@ declare class NodeGroupListRendererComponent implements OnInit, AfterViewInit {
     initialValue: number[] | string[] | boolean[];
     formArray: FormArray<any>;
     editable: boolean;
+    /** Forwarded to each entry's embedded form — see the form's input of the same name. */
+    showAbsentOptionals: boolean;
     minItems: number;
     maxItems: number;
     /** Field-layout appearance from the enclosing group, forwarded to every item form. */
@@ -929,7 +1040,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; }; "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"; }, never, never, true, never>;
 }
 
 /**
@@ -943,6 +1054,8 @@ declare class NodeMapRendererComponent implements OnChanges {
     nodeMap: NodeMap;
     formGroup: FormGroup<any>;
     editable: boolean;
+    /** Forwarded to each entry's embedded form — see the form's input of the same name. */
+    showAbsentOptionals: 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). */
@@ -973,8 +1086,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; }; "inheritedAppearance": { "alias": "inheritedAppearance"; "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; }; "showAbsentOptionals": { "alias": "showAbsentOptionals"; "required": false; }; "inheritedAppearance": { "alias": "inheritedAppearance"; "required": false; }; }, {}, never, never, true, never>;
 }
 
-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 };
+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 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.4.0",
+  "version": "0.5.0",
   "description": "Build fully-typed Angular Reactive Forms and Angular Material UI from a declarative, recursive form-description schema.",
   "keywords": [
     "angular",