@ngx-formbar/core 0.11.0

package/lib/types/content.type.d.ts

@@ -0,0 +1,137 @@
+import { Expression } from './expression.type';
+/**
+ * The foundation for all form controls and groups. It defines a common set of options
+ * that control registration, validation, visibility, and behavior of the form elements.
+ */
+export interface NgxFbBaseContent {
+    /**
+     * Specifies the kind of form control. Determines what control is used and what
+     * additional properties are available.
+     */
+    type: string;
+    /**
+     * A string expression that determines when the control should be hidden.
+     * This condition is evaluated at runtime against the whole form object.
+     */
+    hidden?: Expression<boolean>;
+}
+/**
+ * Extends the base content with validation and control state management properties.
+ * Used as a base for both form controls and groups.
+ */
+export interface NgxFbAbstractControl extends NgxFbBaseContent {
+    /**
+     * Array of strings representing names of synchronous validators that apply to the control.
+     * These can be registered globally with a validator registration object.
+     */
+    validators?: string[];
+    /**
+     * Similar to validators, but for asynchronous validation logic that may involve
+     * API calls or other deferred operations.
+     */
+    asyncValidators?: string[];
+    /**
+     * Defines whether the control should be disabled. Can be a boolean value or a
+     * string expression that evaluates against the form object.
+     */
+    disabled?: Expression<boolean> | boolean;
+    /**
+     * Specifies how to handle the control when hidden: 'keep' (remains in form model)
+     * or 'remove' (removed from form model).
+     */
+    hideStrategy?: HideStrategy;
+    /**
+     * Determines how the control's value is handled when visibility changes:
+     * 'last' (preserves last value), 'default' (reverts to default value),
+     * or 'reset' (clears value).
+     */
+    valueStrategy?: ValueStrategy;
+    /**
+     * Indicates if the control is read-only (displayed but not modifiable).
+     * Accepts either a boolean value or a string expression for dynamic evaluation.
+     */
+    readonly?: Expression<boolean> | boolean;
+    /**
+     * Specifies when to update the control's value: 'change' (as user types, default),
+     * 'blur' (when control loses focus), or 'submit' (when form is submitted).
+     */
+    updateOn?: UpdateStrategy;
+    /**
+     * A value that is automatically derived and set for the control.
+     * It will overwrite user input if one of its dependencies changes.
+     */
+    computedValue?: Expression<unknown>;
+}
+/**
+ * Specifies when to update the control's value:
+ * - 'change': as user types (default)
+ * - 'blur': when control loses focus
+ * - 'submit': when form is submitted
+ */
+export type UpdateStrategy = 'change' | 'blur' | 'submit' | undefined;
+/**
+ * Represents a group of controls that can be nested within a form.
+ */
+export interface NgxFbFormGroup<T extends NgxFbBaseContent = NgxFbContent> extends NgxFbAbstractControl {
+    /**
+     * Specifies a title for the group
+     */
+    title?: string;
+    /**
+     * Dynamic title that can be evaluated from form data
+     */
+    dynamicTitle?: Expression<string>;
+    /**
+     * Object mapping keys to NgxFbContent that configure the controls of the group
+     */
+    controls: Record<string, T>;
+}
+/**
+ * Represents an individual form control with label and value properties.
+ */
+export interface NgxFbControl extends NgxFbAbstractControl {
+    /**
+     * Specifies the label for the control
+     */
+    label?: string;
+    /**
+     * Dynamic label that can be evaluated from form data
+     */
+    dynamicLabel?: Expression<string>;
+    /**
+     * Default value for the control. Should be overwritten with the proper value type of the control.
+     */
+    defaultValue?: unknown;
+    /**
+     * Whether this control can have a null value. Used to set the same property through the reactive forms API.
+     */
+    nonNullable?: boolean;
+}
+/**
+ * Represents a block element that doesn't behave like a form control.
+ * Used for UI elements that aren't part of the form model.
+ */
+export interface NgxFbBlock extends NgxFbBaseContent {
+    /**
+     * Required property for TypeScript to properly do type narrowing
+     */
+    isControl: false;
+    [key: string]: unknown;
+}
+/**
+ * Union type representing all possible content types that can be used in a form.
+ */
+export type NgxFbContent = NgxFbFormGroup | NgxFbControl | NgxFbBlock;
+/**
+ * Specifies how to handle the control when hidden:
+ * - 'keep': control remains in form model
+ * - 'remove': control is removed from form model
+ */
+export type HideStrategy = 'keep' | 'remove';
+/**
+ * Determines how the control's value is handled when visibility changes:
+ * - 'last': preserves last value
+ * - 'default': reverts to default value
+ * - 'reset': clears value
+ */
+export type ValueStrategy = 'last' | 'default' | 'reset';

package/lib/types/expression.type.d.ts

@@ -0,0 +1,2 @@
+export type FormContext = Record<string, unknown>;
+export type Expression<T> = string | ((formValue: FormContext) => T);

package/lib/types/form.type.d.ts

@@ -0,0 +1,4 @@
+import { NgxFbBaseContent, NgxFbContent } from './content.type';
+export interface NgxFbForm<ContentType extends NgxFbBaseContent = NgxFbContent> {
+    content: Record<string, ContentType>;
+}

package/lib/types/functions.type.d.ts

@@ -0,0 +1,4 @@
+import { NgxFbBaseContent, ValueStrategy } from './content.type';
+export type SimpleFunction = () => void;
+export type ValueHandleFunction = (valueStrategy?: ValueStrategy) => void;
+export type TestIdBuilderFn = (content: NgxFbBaseContent, name: string, parentTestId?: string) => string;

package/lib/types/global-configuration.type.d.ts

@@ -0,0 +1,4 @@
+import { TestIdBuilderFn } from './functions.type';
+export interface NgxFbGlobalConfiguration {
+    testIdBuilderFn: TestIdBuilderFn | undefined;
+}

package/lib/types/provide.type.d.ts

@@ -0,0 +1,42 @@
+import { ComponentRegistrationConfig } from './registration.type';
+import { AsyncValidatorConfig, RegistrationRecord, ValidatorConfig } from './validation.type';
+import { UpdateStrategy } from './content.type';
+import { NgxFbGlobalConfiguration } from './global-configuration.type';
+/**
+ * Configuration for registering and providing components and validators in Ngx Formbar
+ *
+ * @template S - Type extending RegistrationRecord for synchronous validators
+ * @template A - Type extending RegistrationRecord for asynchronous validators
+ *
+ * @property componentRegistrations - Optional mapping of control types to component implementations
+ * @property validatorRegistrations - Optional configuration for synchronous validators
+ * @property asyncValidatorRegistrations - Optional configuration for asynchronous validators
+ * @property updateOn - (Optional) Specifies when to update the control's value
+ * @property globalConfig - (Optional) Configuration that is used for all controls
+ *
+ * @example
+ * // Define custom form components and validators
+ * const formbarConfig: FormbarConfig<SyncValidators, AsyncValidators> = {
+ *   componentRegistrations:
+ *   {
+ *      'text-input': TextInputComponent
+ *      'address-group': AddressGroupComponent
+ *   },
+ *   validatorRegistrations: {
+ *      'min-chars': [Validators.minLength(3)],
+ *       letter: [letterValidator],
+ *       combined: ['min-chars', Validators.required, 'letter'],
+ *   }
+ *   asyncValidatorRegistrations: {
+ *     async: [asyncValidator],
+ *     'async-group': [asyncGroupValidator],
+ *   },
+ * };
+ */
+export interface FormbarConfig<S extends RegistrationRecord, A extends RegistrationRecord> {
+    componentRegistrations?: ComponentRegistrationConfig;
+    validatorRegistrations?: ValidatorConfig<S>;
+    asyncValidatorRegistrations?: AsyncValidatorConfig<A>;
+    updateOn?: UpdateStrategy;
+    globalConfig?: NgxFbGlobalConfiguration;
+}

package/lib/types/registration.type.d.ts

@@ -0,0 +1,18 @@
+import { Type } from '@angular/core';
+/**
+ * Configuration for registering component types
+ *
+ * Used to map string type identifiers to component implementations
+ * for dynamic rendering.
+ */
+export type ComponentRegistrationConfig = Record<string, Type<unknown>>;
+/**
+ * Strategy for handling component states
+ *
+ * Determines how visibility, disabled, and other component states
+ * are managed.
+ *
+ * - 'auto': Formbar automatically manages the state
+ * - 'manual': The component/host manages the state itself
+ */
+export type StateHandling = 'auto' | 'manual';

package/lib/types/validation.type.d.ts

@@ -0,0 +1,59 @@
+import { AsyncValidatorFn, ValidatorFn } from '@angular/forms';
+/**
+ * Base record type for validator registrations
+ *
+ * Represents a key-value store where keys are validator identifiers
+ * and values are the validator implementations
+ */
+export type RegistrationRecord = Record<string, unknown>;
+/**
+ * Utility type that extracts string keys from a validator registration
+ *
+ * Used to ensure type safety when referencing validators by their string identifiers
+ *
+ * @template Registration - A record type containing registered validators
+ */
+export type ValidatorKey<Registration extends RegistrationRecord> = Extract<keyof Registration, string>;
+/**
+ * Configuration for synchronous form validators
+ *
+ * Maps validator identifiers to arrays of validator definitions which can be:
+ * - Direct validator functions (ValidatorFn)
+ * - References to other validators by their string identifiers
+ *
+ * @template T - Record type containing registered validators
+ *
+ * @example
+ * // Define validator configurations
+ * const validatorConfig: ValidatorConfig<MyValidators> = {
+ *   required: [Validators.required],
+ *   email: [Validators.email],
+ *   password: [Validators.minLength(8), 'required'],
+ *   // Reference other validators or combine them
+ *   profile: ['required', 'email', customProfileValidator]
+ * };
+ */
+export type ValidatorConfig<T extends RegistrationRecord> = {
+    [K in keyof T]: (ValidatorFn | ValidatorKey<T>)[];
+};
+/**
+ * Configuration for asynchronous form validators
+ *
+ * Maps validator identifiers to arrays of async validator definitions which can be:
+ * - Direct async validator functions (AsyncValidatorFn)
+ * - References to other validators by their string identifiers
+ *
+ * @template T - Record type containing registered validators
+ *
+ * @example
+ * // Define async validator configurations
+ * const asyncValidatorConfig: AsyncValidatorConfig<MyAsyncValidators> = {
+ *   uniqueEmail: [emailUniquenessValidator],
+ *   serverCheck: [serverValidationFn],
+ *   // Reference other validators or combine them
+ *   complexCheck: ['uniqueEmail', customAsyncValidator]
+ * };
+ */
+export type AsyncValidatorConfig<T extends RegistrationRecord> = {
+    [K in keyof T]: (AsyncValidatorFn | ValidatorKey<T>)[];
+};

package/lib/types/validator-resolver.type.d.ts

@@ -0,0 +1,6 @@
+import { Signal } from '@angular/core';
+import { AsyncValidatorFn, ValidatorFn } from '@angular/forms';
+export interface ValidatorResolver {
+    registrations: Signal<ReadonlyMap<string, ValidatorFn[]>>;
+    asyncRegistrations: Signal<ReadonlyMap<string, AsyncValidatorFn[]>>;
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@ngx-formbar/core",
+  "version": "0.11.0",
+  "peerDependencies": {
+    "@angular/cdk": "^19.0.0",
+    "@angular/common": "^19.0.0",
+    "@angular/core": "^19.0.0"
+  },
+  "dependencies": {
+    "acorn": "^8.14.1",
+    "eval-estree-expression": "^3.0.0",
+    "tslib": "^2.3.0"
+  },
+  "schematics": "./schematics/collection.json",
+  "ng-add": {
+    "save": true
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "license": "MIT",
+  "keywords": [
+    "angular",
+    "typescript",
+    "reactive-forms",
+    "json-form"
+  ],
+  "author": {
+    "name": "Alexander Pahn",
+    "email": "alexander.pahn@outlook.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TheNordicOne/ngx-formbar.git"
+  },
+  "bugs": {
+    "url": "https://github.com/TheNordicOne/ngx-formbar/issues"
+  },
+  "module": "fesm2022/ngx-formbar-core.mjs",
+  "typings": "index.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./fesm2022/ngx-formbar-core.mjs"
+    }
+  }
+}

package/public-api.d.ts

@@ -0,0 +1 @@
+export * from './lib';

package/schematics/block/files/__componentName@dasherize__.component.html.template

@@ -0,0 +1 @@
+

package/schematics/block/files/__componentName@dasherize__.component.ts.template

@@ -0,0 +1,29 @@
+import { Component, Signal, inject } from '@angular/core';<% if (!hasViewProviderHelper) { %>
+import { ControlContainer } from '@angular/forms';<% } %>
+import { NgxfbBlockDirective } from '@ngx-formbar/core';
+import { <%= classify(interfaceName) %> } from './<%= dasherize(interfaceName) %>.type';<% if (hasViewProviderHelper) { %>
+import { <%= viewProviderIdentifier %> } from '<%= viewProviderHelperPath %>';<% } %><% if (hasHostDirectiveHelper) { %>
+import { <%= hostDirectiveIdentifier %> } from '<%= hostDirectiveHelperPath %>';<% } %>
+
+@Component({
+  selector: 'app-<%= dasherize(componentName) %>',
+  imports: [],
+  templateUrl: './<%= dasherize(componentName) %>.component.html',
+   viewProviders: <% if (hasViewProviderHelper) { %><%= viewProviderIdentifier %><% } else { %>[
+      {
+        provide: ControlContainer,
+        useFactory: () => inject(ControlContainer, { skipSelf: true }),
+      }
+    ]<% } %>,
+   hostDirectives: <% if (hasHostDirectiveHelper) { %>[<%= hostDirectiveIdentifier %>]<% } else { %>[
+      {
+        directive: NgxfbBlockDirective,
+        inputs: ['content', 'name'],
+      }
+    ]<% } %>,
+})
+export class <%= classify(componentClassName) %> {
+  private readonly block = inject(NgxfbBlockDirective<<%= classify(interfaceName) %>>);
+  readonly content: Signal<<%= classify(interfaceName) %>> = this.block.content;
+}
+

package/schematics/block/files/__interfaceName@dasherize__.type.ts.template

@@ -0,0 +1,6 @@
+import { NgxFbBlock } from '@ngx-formbar/core';
+
+export interface <%= classify(interfaceName) %> extends NgxFbBlock {
+  type: '<%= key %>';
+}
+

package/schematics/block/index.d.ts

@@ -0,0 +1,3 @@
+import { Rule } from '@angular-devkit/schematics';
+import { Schema } from '../shared/schema';
+export declare function block(options: Schema): Rule;

package/schematics/block/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.block = block;
+const schematics_1 = require("@angular-devkit/schematics");
+const scaffold_and_register_rule_1 = require("../shared/rules/scaffold-and-register.rule");
+function block(options) {
+    return () => {
+        return (0, schematics_1.chain)([(0, scaffold_and_register_rule_1.scaffoldAndRegister)(options, 'block')]);
+    };
+}
+//# sourceMappingURL=index.js.map

package/schematics/block/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../projects/core/automation/schematics/block/index.ts"],"names":[],"mappings":";;AAIA,sBAIC;AARD,2DAAyD;AACzD,2FAAiF;AAGjF,SAAgB,KAAK,CAAC,OAAe;IACnC,OAAO,GAAG,EAAE;QACV,OAAO,IAAA,kBAAK,EAAC,CAAC,IAAA,gDAAmB,EAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACxD,CAAC,CAAC;AACJ,CAAC"}

package/schematics/block/schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "NgxFormbarBlock",
+  "title": "Scaffold Block",
+  "type": "object",
+  "properties": {
+    "name": {
+      "description": "The name of the component that this control will use. Defaults to the key if not provided.",
+      "type": "string"
+    },
+    "key": {
+      "description": "The name of the key that this control will be associated with.",
+      "type": "string"
+    },
+    "path": {
+      "type": "string",
+      "format": "path",
+      "description": "The path to create the component.",
+      "visible": false,
+      "$default": {
+        "$source": "workingDirectory"
+      }
+    },
+    "project": {
+      "type": "string",
+      "description": "The name of the project.",
+      "$default": {
+        "$source": "projectName"
+      }
+    },
+    "interfaceSuffix": {
+      "type": "string",
+      "description": "The suffix of the interface. Defaults to 'Control'",
+      "default": "Control"
+    },
+    "componentSuffix": {
+      "type": "string",
+      "description": "The suffix of the component. Defaults to 'Control'",
+      "default": "Control"
+    },
+    "hostDirectiveHelperPath": {
+      "type": "string",
+      "description": "Path to the hostDirective helper"
+    },
+    "skipRegistration": {
+      "type": "boolean",
+      "description": "Skip automatic registration"
+    },
+    "viewProviderHelperPath": {
+      "type": "string",
+      "description": "Path to the viewProvider helper"
+    },
+    "schematicsConfig": {
+      "type": "string",
+      "description": "Path of the configuration that is to be used by this schematic"
+    }
+  },
+  "required": [
+    "key"
+  ]
+}
+

package/schematics/collection.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "../../../node_modules/@angular-devkit/schematics/collection-schema.json",
+  "schematics": {
+    "ng-add": {
+      "description": "Add ngx-formbar to the project.",
+      "factory": "./ng-add/index#ngAdd",
+      "schema": "./ng-add/schema.json",
+      "hidden": true
+    },
+    "control": {
+      "description": "Scaffolds a new control and registers it.",
+      "factory": "./control/index#control",
+      "schema": "./control/schema.json"
+    },
+    "group": {
+      "description": "Scaffolds a new group and registers it.",
+      "factory": "./group/index#group",
+      "schema": "./group/schema.json"
+    },
+    "block": {
+      "description": "Scaffolds a new block and registers it.",
+      "factory": "./block/index#block",
+      "schema": "./block/schema.json"
+    },
+    "register": {
+      "description": "Searches for all components and registers them",
+      "factory": "./register/index#register",
+      "schema": "./register/schema.json"
+    }
+  }
+}

package/schematics/control/files/__componentName@dasherize__.component.ts.template

@@ -0,0 +1,29 @@
+import { Component, Signal, inject } from '@angular/core';
+import { ReactiveFormsModule<% if (!hasViewProviderHelper) { %>, ControlContainer<% } %> } from '@angular/forms';
+import { NgxfbControlDirective } from '@ngx-formbar/core';
+import { <%= interfaceName %> } from './<%= dasherize(interfaceName) %>.type';<% if (hasViewProviderHelper) { %>
+import { <%= viewProviderIdentifier %> } from '<%= viewProviderHelperPath %>';<% } %><% if (hasHostDirectiveHelper) { %>
+import { <%= hostDirectiveIdentifier %> } from '<%= hostDirectiveHelperPath %>';<% } %>
+
+@Component({
+  selector: 'app-<%= dasherize(componentName) %>',
+  imports: [ReactiveFormsModule],
+  templateUrl: './<%= dasherize(componentName) %>.component.html',
+  viewProviders: <% if (hasViewProviderHelper) { %><%= viewProviderIdentifier %><% } else { %>[
+    {
+      provide: ControlContainer,
+      useFactory: () => inject(ControlContainer, { skipSelf: true }),
+    }
+  ]<% } %>,
+  hostDirectives: <% if (hasHostDirectiveHelper) { %>[<%= hostDirectiveIdentifier %>]<% } else { %>[
+    {
+      directive: NgxfbControlDirective,
+      inputs: ['content', 'name'],
+    }
+  ]<% } %>,
+})
+export class <%= classify(componentClassName) %> {
+  private readonly control = inject(NgxfbControlDirective<<%= interfaceName %>>);
+  readonly content: Signal<<%= interfaceName %>> = this.control.content;
+  readonly name: Signal<string> = this.control.name;
+}

package/schematics/control/files/__interfaceName@dasherize__.type.ts.template

@@ -0,0 +1,6 @@
+import { NgxFbControl } from '@ngx-formbar/core';
+
+export interface <%= classify(interfaceName) %> extends NgxFbControl {
+  type: '<%= key %>';
+}
+

package/schematics/control/index.d.ts

@@ -0,0 +1,3 @@
+import { Rule } from '@angular-devkit/schematics';
+import { Schema } from '../shared/schema';
+export declare function control(options: Schema): Rule;

package/schematics/control/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.control = control;
+const schematics_1 = require("@angular-devkit/schematics");
+const scaffold_and_register_rule_1 = require("../shared/rules/scaffold-and-register.rule");
+function control(options) {
+    return () => {
+        return (0, schematics_1.chain)([(0, scaffold_and_register_rule_1.scaffoldAndRegister)(options, 'control')]);
+    };
+}
+//# sourceMappingURL=index.js.map

package/schematics/control/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../projects/core/automation/schematics/control/index.ts"],"names":[],"mappings":";;AAIA,0BAIC;AARD,2DAAyD;AACzD,2FAAiF;AAGjF,SAAgB,OAAO,CAAC,OAAe;IACrC,OAAO,GAAG,EAAE;QACV,OAAO,IAAA,kBAAK,EAAC,CAAC,IAAA,gDAAmB,EAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IAC1D,CAAC,CAAC;AACJ,CAAC"}

package/schematics/control/schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "NgxFormbarControl",
+  "title": "Scaffold Control",
+  "type": "object",
+  "properties": {
+    "name": {
+      "description": "The name of the component that this control will use. Defaults to the key if not provided.",
+      "type": "string"
+    },
+    "key": {
+      "description": "The name of the key that this control will be associated with.",
+      "type": "string"
+    },
+    "path": {
+      "type": "string",
+      "format": "path",
+      "description": "The path to create the component.",
+      "visible": false,
+      "$default": {
+        "$source": "workingDirectory"
+      }
+    },
+    "project": {
+      "type": "string",
+      "description": "The name of the project.",
+      "$default": {
+        "$source": "projectName"
+      }
+    },
+    "interfaceSuffix": {
+      "type": "string",
+      "description": "The suffix of the interface. Defaults to 'Control'",
+      "default": "Control"
+    },
+    "componentSuffix": {
+      "type": "string",
+      "description": "The suffix of the component. Defaults to 'Control'",
+      "default": "Control"
+    },
+    "hostDirectiveHelperPath": {
+      "type": "string",
+      "description": "Path to the hostDirective helper"
+    },
+    "skipRegistration": {
+      "type": "boolean",
+      "description": "Skip automatic registration"
+    },
+    "viewProviderHelperPath": {
+      "type": "string",
+      "description": "Path to the viewProvider helper"
+    },
+    "schematicsConfig": {
+      "type": "string",
+      "description": "Path of the configuration that is to be used by this schematic"
+    }
+  },
+  "required": [
+    "key"
+  ]
+}

package/schematics/group/files/__componentName@dasherize__.component.html.template

@@ -0,0 +1,5 @@
+<ng-container [formGroupName]="name()">
+  @for (content of controls(); track content[0]) {
+    <ng-template *ngxfbAbstractControl="content" />
+  }
+</ng-container>