@ng-modular-forms/core 0.1.0

package/README.md

@@ -0,0 +1,125 @@
+# @ng-modular-forms/core
+
+Core primitives for orchestrating complex Angular reactive forms.
+
+## What This Provides
+
+- Form orchestration
+- Reactive logic isolation
+- Data mapping layer
+
+## Installation
+
+```bash
+npm install @ng-modular-forms/core
+```
+
+## Key Concepts
+
+### FormOrchestratorBase
+
+Coordinates form structure and lifecycle.
+
+```ts
+@Component({...})
+export class ExampleComponent extends FormOrchestratorBase {
+  form = new FormGroup({});
+
+  ngOnInit() {
+   // Handlers are not required if there is no reactive logic or value change subscriptions.
+   const mainHandler = inject(ExampleFormHandler);
+   const sectionAHandler = inject(SectionAHandler);
+
+   const formOptions = {
+      mainHandler: mainHandler,
+      subHandlers: {
+         sectionA: sectionAHandler
+      }
+    };
+
+   this.initialize(this.form, formOptions);
+  }
+
+  // Only required if forms are split across multiple components
+  onSubformReady(form: FormGroup, key: string) {
+    super.onSubformReady(form, key);
+  }
+}
+```
+
+---
+
+### FormHandlerBase
+
+Encapsulates reactive logic.
+
+```ts
+const CONTROL_NAMES = ["fieldA", "dependentField"] as const;
+
+type ControlNames = (typeof CONTROL_NAMES)[number];
+
+@Injectable()
+export class SectionAHandler extends FormHandlerBase<ControlNames> {
+  override getReactiveLogic(): Subscription {
+    this.registerControls(this.form, [...CONTROL_NAMES]);
+
+    return this.valueChangesOf("fieldA").subscribe((value) => {
+      if (value) {
+        this.controls.dependentField.enable();
+      } else {
+        this.controls.dependentField.disable();
+      }
+    });
+  }
+}
+```
+
+---
+
+### FormMapperBase
+
+Handles transformations between API and form.
+
+```ts
+export class ExampleMapper extends FormMapperBase<ApiModel, RequestModel> {
+  buildRequest(form: FormGroup) {
+    return {
+      fieldA: form.value.fieldA,
+      fieldB: form.value.fieldB,
+    };
+  }
+
+  transformFromModel(model: ApiModel) {
+    return {
+      fieldA: model.fieldA,
+      fieldB: model.fieldB,
+    };
+  }
+}
+```
+
+---
+
+### Responsibility Boundaries
+
+| Layer            | Responsibility                                           |
+| :--------------- | :------------------------------------------------------- |
+| **Orchestrator** | Manages form composition and lifecycle coordination.     |
+| **Handler**      | Encapsulates all reactive logic and stream management.   |
+| **Mapper**       | Handles data transformation between API and Form states. |
+
+---
+
+### No UI Included
+
+This package does **not** provide UI components.
+
+Use:
+
+- @ng-modular-forms/control
+- @ng-modular-forms/input
+- @ng-modular-forms/material
+
+## License
+
+MIT

package/fesm2022/ng-modular-forms-core.mjs

@@ -0,0 +1,254 @@
+import * as i0 from '@angular/core';
+import { inject, ChangeDetectorRef, HostBinding, Input, Optional, Self, Directive, signal } from '@angular/core';
+import * as i1 from '@angular/forms';
+import { FormGroup } from '@angular/forms';
+import { Subscription } from 'rxjs';
+
+/**
+ * Base implementation for custom form controls that integrate with Angular Reactive Forms (ControlValueAccessor)
+ *
+ * NOTE: This class is UI-layer only and should not be used in form orchestration logic.
+ */
+class FormControlBase {
+    ngControl;
+    elementRef;
+    cdr = inject(ChangeDetectorRef);
+    name;
+    placeholder = '';
+    required = false;
+    disabled = false;
+    readonly = false;
+    formControlName;
+    static nextId = 0;
+    id = `nmf-form-control-${FormControlBase.nextId++}`;
+    _value = null;
+    get value() {
+        return this._value;
+    }
+    set value(val) {
+        this._value = val;
+    }
+    onChange = (_value) => { };
+    onTouched = () => { };
+    constructor(ngControl, elementRef) {
+        this.ngControl = ngControl;
+        this.elementRef = elementRef;
+        if (this.ngControl != null) {
+            this.ngControl.valueAccessor = this;
+        }
+    }
+    writeValue(value) {
+        this._value = value;
+        this.cdr.markForCheck();
+    }
+    registerOnChange(fn) {
+        this.onChange = fn;
+    }
+    registerOnTouched(fn) {
+        this.onTouched = fn;
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.2.20", ngImport: i0, type: FormControlBase, deps: [{ token: i1.NgControl, optional: true, self: true }, { token: i0.ElementRef }], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "19.2.20", type: FormControlBase, isStandalone: true, inputs: { name: "name", placeholder: "placeholder", required: "required", disabled: "disabled", readonly: "readonly", formControlName: "formControlName" }, host: { properties: { "id": "this.id" } }, ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.20", ngImport: i0, type: FormControlBase, decorators: [{
+            type: Directive
+        }], ctorParameters: () => [{ type: i1.NgControl, decorators: [{
+                    type: Optional
+                }, {
+                    type: Self
+                }] }, { type: i0.ElementRef }], propDecorators: { name: [{
+                type: Input
+            }], placeholder: [{
+                type: Input
+            }], required: [{
+                type: Input
+            }], disabled: [{
+                type: Input
+            }], readonly: [{
+                type: Input
+            }], formControlName: [{
+                type: Input
+            }], id: [{
+                type: HostBinding
+            }] } });
+
+function getControl(controlName, form) {
+    if (!form) {
+        throw new Error(`Missing form instance while getting the control of "${controlName}"`);
+    }
+    const control = form.get(controlName);
+    if (!control) {
+        throw new Error(`Missing control "${controlName}" in form "${form}"`);
+    }
+    return control;
+}
+function getControlValue(controlName, form) {
+    const control = getControl(controlName, form);
+    if (!control) {
+        throw new Error(`Missing control "${controlName}" in form "${form}"`);
+    }
+    const value = control.getRawValue();
+    if (value === '') {
+        return null;
+    }
+    if (typeof value === 'string') {
+        const cleaned = value.replace(/,/g, '');
+        if (!Number.isNaN(Number(cleaned))) {
+            return parseCurrency(value);
+        }
+    }
+    return value;
+}
+function parseCurrency(currencyString) {
+    if (currencyString == null) {
+        return 0;
+    }
+    if (typeof currencyString === 'number') {
+        return currencyString;
+    }
+    return Number(currencyString.replace(/[^0-9.-]/g, ''));
+}
+
+class FormHandlerBase {
+    registeredControls = {};
+    /**
+     * Registers form controls for later reactive access.
+     */
+    registerControls(form, controlNames) {
+        controlNames.forEach((cn) => {
+            const control = getControl(cn.replace(/_/g, '.'), form);
+            if (!control) {
+                throw new Error(`Failed to register control with name: "${cn}" in form group: "${form}"`);
+            }
+            const key = cn;
+            this.registeredControls[key] = control;
+        });
+    }
+    valueChangesOf(key) {
+        if (!this.registeredControls[key]) {
+            throw new Error(`Control with name: "${key}" not found. Ensure it is registered in registerControls(...)`);
+        }
+        return this.registeredControls[key].valueChanges;
+    }
+}
+
+class FormMapperBase {
+    patchForm(form, data, _context, emitEvent = false) {
+        form.patchValue({
+            ...data,
+        }, { emitEvent });
+    }
+    patchFromModel(form, model, store) {
+        const formModel = this.transformFromModel(model);
+        this.patchForm(form, formModel, store);
+    }
+}
+
+class FormOrchestratorBase {
+    _form = signal(new FormGroup({}));
+    _mainHandler = signal(null);
+    _subHandlers = signal({});
+    _status = signal('idle');
+    _errorMessage = signal(null);
+    _loadedHandlers = signal(0);
+    _allHandlersLoaded = signal(false);
+    _logicSubscription = new Subscription();
+    form = this._form.asReadonly();
+    mainHandler = this._mainHandler.asReadonly();
+    subHandlers = this._subHandlers.asReadonly();
+    status = this._status.asReadonly();
+    errorMessage = this._errorMessage.asReadonly();
+    /**
+     * Initializes orchestration state.
+     * Must be called before any subform registration or handler execution.
+     */
+    initialize(form, formOrchestratorOptions) {
+        const { mainHandler, subHandlers = {} } = formOrchestratorOptions ?? {};
+        this._form.set(form);
+        this._mainHandler.set(mainHandler ?? null);
+        this._subHandlers.set(subHandlers);
+        this._loadedHandlers.set(0);
+        const subHandlerCount = Object.keys(this.subHandlers());
+        if (subHandlerCount.length === 0) {
+            this.loadMainHandler();
+        }
+    }
+    setForm(form) {
+        this._form.set(form);
+    }
+    getHandler(key) {
+        return this.subHandlers()[key];
+    }
+    setHandler(key, handler) {
+        this._subHandlers.set({
+            ...this._subHandlers(),
+            [key]: handler,
+        });
+    }
+    addReactiveLogic(subscription) {
+        this._logicSubscription.add(subscription);
+    }
+    setStatus(status) {
+        this._status.set(status);
+    }
+    setErrorMessage(message) {
+        this._errorMessage.set(message);
+    }
+    ngOnDestroy() {
+        this._logicSubscription.unsubscribe();
+    }
+    /**
+     * Registers a subform into the main form tree and coordinates handler execution.
+     *
+     * IMPORTANT:
+     * - Handler execution is gated until all registered subhandlers are ready.
+     * - Calling order matters; this is lifecycle-sensitive orchestration logic.
+     */
+    onSubformReady(subform, groupName, nestGroups = false) {
+        if (nestGroups) {
+            this.form().setControl(groupName, subform);
+        }
+        else {
+            const keys = Object.keys(subform.controls);
+            keys.forEach((key) => {
+                this.form().setControl(key, subform.get(key));
+            });
+        }
+        // Prevent duplicate main handler execution when all subhandlers already resolved
+        if (this._allHandlersLoaded()) {
+            return;
+        }
+        const subformHandler = this.subHandlers()[groupName];
+        if (subformHandler) {
+            this._loadedHandlers.set(this._loadedHandlers() + 1);
+            this.addReactiveLogic(subformHandler.getReactiveLogic());
+        }
+        const totalSubHandlers = Object.keys(this.subHandlers()).length;
+        const allSubHandlersLoaded = this._loadedHandlers() === totalSubHandlers;
+        if (allSubHandlersLoaded && this.mainHandler()) {
+            this.loadMainHandler();
+        }
+    }
+    loadMainHandler() {
+        if (!this.mainHandler())
+            return;
+        this.addReactiveLogic(this.mainHandler().getReactiveLogic(this.form()));
+        this._allHandlersLoaded.set(true);
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.2.20", ngImport: i0, type: FormOrchestratorBase, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "19.2.20", type: FormOrchestratorBase, isStandalone: true, ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.20", ngImport: i0, type: FormOrchestratorBase, decorators: [{
+            type: Directive
+        }] });
+
+/*
+ * Public API Surface of core
+ */
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { FormControlBase, FormHandlerBase, FormMapperBase, FormOrchestratorBase };
+//# sourceMappingURL=ng-modular-forms-core.mjs.map

package/fesm2022/ng-modular-forms-core.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ng-modular-forms-core.mjs","sources":["../../../projects/core/src/lib/form-control-base.ts","../../../projects/core/src/lib/form.util.ts","../../../projects/core/src/lib/form-handler-base.ts","../../../projects/core/src/lib/form-mapper-base.ts","../../../projects/core/src/lib/form-orchestrator-base.ts","../../../projects/core/src/public-api.ts","../../../projects/core/src/ng-modular-forms-core.ts"],"sourcesContent":["import {\n  Directive,\n  ElementRef,\n  Input,\n  HostBinding,\n  Optional,\n  Self,\n  inject,\n  ChangeDetectorRef,\n} from '@angular/core';\nimport { ControlValueAccessor, NgControl } from '@angular/forms';\n\n/**\n * Base implementation for custom form controls that integrate with Angular Reactive Forms (ControlValueAccessor)\n *\n * NOTE: This class is UI-layer only and should not be used in form orchestration logic.\n */\n\n@Directive()\nexport abstract class FormControlBase<T> implements ControlValueAccessor {\n  protected readonly cdr = inject(ChangeDetectorRef);\n\n  @Input() name!: string;\n  @Input() placeholder: string = '';\n  @Input() required = false;\n  @Input() disabled = false;\n  @Input() readonly = false;\n\n  @Input() formControlName?: string;\n\n  static nextId = 0;\n\n  @HostBinding()\n  id = `nmf-form-control-${FormControlBase.nextId++}`;\n\n  _value: T | null = null;\n\n  get value(): T | null {\n    return this._value;\n  }\n\n  set value(val: T | null) {\n    this._value = val;\n  }\n\n  onChange = (_value: T) => {};\n  onTouched = () => {};\n\n  constructor(\n    @Optional() @Self() public ngControl: NgControl,\n    protected elementRef: ElementRef<HTMLElement>,\n  ) {\n    if (this.ngControl != null) {\n      this.ngControl.valueAccessor = this;\n    }\n  }\n\n  writeValue(value: T): void {\n    this._value = value;\n    this.cdr.markForCheck();\n  }\n\n  registerOnChange(fn: (value: T) => void): void {\n    this.onChange = fn;\n  }\n\n  registerOnTouched(fn: () => void): void {\n    this.onTouched = fn;\n  }\n}\n","import { FormControl, FormGroup } from '@angular/forms';\n\nexport function getControl<T = unknown>(controlName: string, form: FormGroup) {\n  if (!form) {\n    throw new Error(\n      `Missing form instance while getting the control of \"${controlName}\"`,\n    );\n  }\n\n  const control = form.get(controlName) as FormControl<T>;\n  if (!control) {\n    throw new Error(`Missing control \"${controlName}\" in form \"${form}\"`);\n  }\n\n  return control;\n}\n\nexport function getControlValue<T = unknown>(\n  controlName: string,\n  form: FormGroup,\n): T | null;\n\nexport function getControlValue(\n  controlName: string,\n  form: FormGroup,\n): number | null;\n\nexport function getControlValue<T = unknown>(\n  controlName: string,\n  form: FormGroup,\n): T | null {\n  const control = getControl<T>(controlName, form);\n  if (!control) {\n    throw new Error(`Missing control \"${controlName}\" in form \"${form}\"`);\n  }\n\n  const value = control.getRawValue();\n  if (value === '') {\n    return null;\n  }\n\n  if (typeof value === 'string') {\n    const cleaned = value.replace(/,/g, '');\n\n    if (!Number.isNaN(Number(cleaned))) {\n      return parseCurrency(value) as T;\n    }\n  }\n\n  return value;\n}\n\nexport function parseCurrency(\n  currencyString: string | number | null | undefined,\n): number {\n  if (currencyString == null) {\n    return 0;\n  }\n\n  if (typeof currencyString === 'number') {\n    return currencyString;\n  }\n\n  return Number(currencyString.replace(/[^0-9.-]/g, ''));\n}\n","import { FormControl, FormGroup } from '@angular/forms';\nimport { Observable, Subscription } from 'rxjs';\nimport { getControl } from './form.util';\n\nexport abstract class FormHandlerBase<ControlNames extends string = string> {\n  abstract getReactiveLogic(form?: FormGroup): Subscription;\n\n  protected registeredControls: Record<string, FormControl> = {};\n\n  /**\n   * Registers form controls for later reactive access.\n   */\n  registerControls(form: FormGroup, controlNames: ControlNames[]): void {\n    controlNames.forEach((cn) => {\n      const control = getControl(cn.replace(/_/g, '.'), form);\n\n      if (!control) {\n        throw new Error(\n          `Failed to register control with name: \"${cn}\" in form group: \"${form}\"`,\n        );\n      }\n\n      const key = cn as ControlNames;\n      this.registeredControls[key] = control;\n    });\n  }\n\n  valueChangesOf<T>(key: ControlNames): Observable<T> {\n    if (!this.registeredControls[key]) {\n      throw new Error(\n        `Control with name: \"${key}\" not found. Ensure it is registered in registerControls(...)`,\n      );\n    }\n\n    return this.registeredControls[key].valueChanges as Observable<T>;\n  }\n}\n","import { FormGroup } from '@angular/forms';\n\nexport abstract class FormMapperBase<\n  TModelIn = unknown,\n  TModelOut = unknown,\n  TFormModel = unknown,\n  TStore = Record<string, unknown>,\n> {\n  /**\n   * Maps form state + external store into an API request payload.\n   */\n  abstract buildRequest(form: FormGroup, store: TStore): Partial<TModelOut>;\n\n  /**\n   * Transforms a domain/API model into a form-compatible structure.\n   */\n  abstract transformFromModel(model: TModelIn): TFormModel;\n\n  patchForm(\n    form: FormGroup,\n    data: TFormModel,\n    _context: TStore,\n    emitEvent: boolean = false,\n  ): void {\n    form.patchValue(\n      {\n        ...(data as Record<string, unknown>),\n      },\n      { emitEvent },\n    );\n  }\n\n  patchFromModel(form: FormGroup, model: TModelIn, store: TStore): void {\n    const formModel = this.transformFromModel(model);\n    this.patchForm(form, formModel, store);\n  }\n}\n","import { FormGroup } from '@angular/forms';\nimport { Directive, OnDestroy, signal } from '@angular/core';\nimport { Subscription } from 'rxjs';\nimport { FormHandlerBase } from './form-handler-base';\n\nexport type FormStatus = 'idle' | 'submitting' | 'error' | 'success';\n\ntype FormHandlerRegistry = Record<string, FormHandlerBase<string>>;\n\ninterface FormOrchestratorOptions {\n  mainHandler?: FormHandlerBase<string> | null;\n  subHandlers?: FormHandlerRegistry;\n}\n\n@Directive()\nexport abstract class FormOrchestratorBase implements OnDestroy {\n  private _form = signal<FormGroup>(new FormGroup({}));\n\n  private _mainHandler = signal<FormHandlerBase<string> | null>(null);\n  private _subHandlers = signal<FormHandlerRegistry>({});\n\n  private _status = signal<FormStatus>('idle');\n  private _errorMessage = signal<string | null>(null);\n\n  private _loadedHandlers = signal<number>(0);\n  private _allHandlersLoaded = signal<boolean>(false);\n\n  private _logicSubscription = new Subscription();\n\n  public readonly form = this._form.asReadonly();\n  public readonly mainHandler = this._mainHandler.asReadonly();\n  public readonly subHandlers = this._subHandlers.asReadonly();\n  public readonly status = this._status.asReadonly();\n  public readonly errorMessage = this._errorMessage.asReadonly();\n\n  /**\n   * Initializes orchestration state.\n   * Must be called before any subform registration or handler execution.\n   */\n  public initialize(\n    form: FormGroup,\n    formOrchestratorOptions?: FormOrchestratorOptions,\n  ) {\n    const { mainHandler, subHandlers = {} } = formOrchestratorOptions ?? {};\n\n    this._form.set(form);\n    this._mainHandler.set(mainHandler ?? null);\n    this._subHandlers.set(subHandlers);\n    this._loadedHandlers.set(0);\n\n    const subHandlerCount = Object.keys(this.subHandlers());\n    if (subHandlerCount.length === 0) {\n      this.loadMainHandler();\n    }\n  }\n\n  public setForm(form: FormGroup) {\n    this._form.set(form);\n  }\n\n  public getHandler(key: string): FormHandlerBase<string> | undefined {\n    return this.subHandlers()[key];\n  }\n\n  public setHandler(key: string, handler: FormHandlerBase<string>) {\n    this._subHandlers.set({\n      ...this._subHandlers(),\n      [key]: handler,\n    });\n  }\n\n  public addReactiveLogic(subscription: Subscription) {\n    this._logicSubscription.add(subscription);\n  }\n\n  public setStatus(status: FormStatus) {\n    this._status.set(status);\n  }\n\n  public setErrorMessage(message: string | null) {\n    this._errorMessage.set(message);\n  }\n\n  ngOnDestroy(): void {\n    this._logicSubscription.unsubscribe();\n  }\n\n  /**\n   * Registers a subform into the main form tree and coordinates handler execution.\n   *\n   * IMPORTANT:\n   * - Handler execution is gated until all registered subhandlers are ready.\n   * - Calling order matters; this is lifecycle-sensitive orchestration logic.\n   */\n  onSubformReady(\n    subform: FormGroup,\n    groupName: string,\n    nestGroups: boolean = false,\n  ): void {\n    if (nestGroups) {\n      this.form().setControl(groupName, subform);\n    } else {\n      const keys = Object.keys(subform.controls);\n      keys.forEach((key) => {\n        this.form().setControl(key, subform.get(key));\n      });\n    }\n\n    // Prevent duplicate main handler execution when all subhandlers already resolved\n    if (this._allHandlersLoaded()) {\n      return;\n    }\n\n    const subformHandler = this.subHandlers()[groupName];\n\n    if (subformHandler) {\n      this._loadedHandlers.set(this._loadedHandlers() + 1);\n      this.addReactiveLogic(subformHandler.getReactiveLogic());\n    }\n\n    const totalSubHandlers = Object.keys(this.subHandlers()).length;\n    const allSubHandlersLoaded = this._loadedHandlers() === totalSubHandlers;\n\n    if (allSubHandlersLoaded && this.mainHandler()) {\n      this.loadMainHandler();\n    }\n  }\n\n  private loadMainHandler() {\n    if (!this.mainHandler()) return;\n\n    this.addReactiveLogic(this.mainHandler()!.getReactiveLogic(this.form()));\n    this._allHandlersLoaded.set(true);\n  }\n}\n","/*\n * Public API Surface of core\n */\n\nexport * from './lib/index';\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './public-api';\n"],"names":[],"mappings":"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"}

package/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Generated bundle index. Do not edit.
+ */
+/// <amd-module name="@ng-modular-forms/core" />
+export * from './public-api';

package/lib/form-control-base.d.ts

@@ -0,0 +1,32 @@
+import { ElementRef, ChangeDetectorRef } from '@angular/core';
+import { ControlValueAccessor, NgControl } from '@angular/forms';
+import * as i0 from "@angular/core";
+/**
+ * Base implementation for custom form controls that integrate with Angular Reactive Forms (ControlValueAccessor)
+ *
+ * NOTE: This class is UI-layer only and should not be used in form orchestration logic.
+ */
+export declare abstract class FormControlBase<T> implements ControlValueAccessor {
+    ngControl: NgControl;
+    protected elementRef: ElementRef<HTMLElement>;
+    protected readonly cdr: ChangeDetectorRef;
+    name: string;
+    placeholder: string;
+    required: boolean;
+    disabled: boolean;
+    readonly: boolean;
+    formControlName?: string;
+    static nextId: number;
+    id: string;
+    _value: T | null;
+    get value(): T | null;
+    set value(val: T | null);
+    onChange: (_value: T) => void;
+    onTouched: () => void;
+    constructor(ngControl: NgControl, elementRef: ElementRef<HTMLElement>);
+    writeValue(value: T): void;
+    registerOnChange(fn: (value: T) => void): void;
+    registerOnTouched(fn: () => void): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<FormControlBase<any>, [{ optional: true; self: true; }, null]>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<FormControlBase<any>, never, never, { "name": { "alias": "name"; "required": false; }; "placeholder": { "alias": "placeholder"; "required": false; }; "required": { "alias": "required"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "readonly": { "alias": "readonly"; "required": false; }; "formControlName": { "alias": "formControlName"; "required": false; }; }, {}, never, never, true, never>;
+}

package/lib/form-handler-base.d.ts

@@ -0,0 +1,11 @@
+import { FormControl, FormGroup } from '@angular/forms';
+import { Observable, Subscription } from 'rxjs';
+export declare abstract class FormHandlerBase<ControlNames extends string = string> {
+    abstract getReactiveLogic(form?: FormGroup): Subscription;
+    protected registeredControls: Record<string, FormControl>;
+    /**
+     * Registers form controls for later reactive access.
+     */
+    registerControls(form: FormGroup, controlNames: ControlNames[]): void;
+    valueChangesOf<T>(key: ControlNames): Observable<T>;
+}

package/lib/form-mapper-base.d.ts

@@ -0,0 +1,13 @@
+import { FormGroup } from '@angular/forms';
+export declare abstract class FormMapperBase<TModelIn = unknown, TModelOut = unknown, TFormModel = unknown, TStore = Record<string, unknown>> {
+    /**
+     * Maps form state + external store into an API request payload.
+     */
+    abstract buildRequest(form: FormGroup, store: TStore): Partial<TModelOut>;
+    /**
+     * Transforms a domain/API model into a form-compatible structure.
+     */
+    abstract transformFromModel(model: TModelIn): TFormModel;
+    patchForm(form: FormGroup, data: TFormModel, _context: TStore, emitEvent?: boolean): void;
+    patchFromModel(form: FormGroup, model: TModelIn, store: TStore): void;
+}

package/lib/form-orchestrator-base.d.ts

@@ -0,0 +1,50 @@
+import { FormGroup } from '@angular/forms';
+import { OnDestroy } from '@angular/core';
+import { Subscription } from 'rxjs';
+import { FormHandlerBase } from './form-handler-base';
+import * as i0 from "@angular/core";
+export type FormStatus = 'idle' | 'submitting' | 'error' | 'success';
+type FormHandlerRegistry = Record<string, FormHandlerBase<string>>;
+interface FormOrchestratorOptions {
+    mainHandler?: FormHandlerBase<string> | null;
+    subHandlers?: FormHandlerRegistry;
+}
+export declare abstract class FormOrchestratorBase implements OnDestroy {
+    private _form;
+    private _mainHandler;
+    private _subHandlers;
+    private _status;
+    private _errorMessage;
+    private _loadedHandlers;
+    private _allHandlersLoaded;
+    private _logicSubscription;
+    readonly form: import("@angular/core").Signal<FormGroup<any>>;
+    readonly mainHandler: import("@angular/core").Signal<FormHandlerBase<string> | null>;
+    readonly subHandlers: import("@angular/core").Signal<FormHandlerRegistry>;
+    readonly status: import("@angular/core").Signal<FormStatus>;
+    readonly errorMessage: import("@angular/core").Signal<string | null>;
+    /**
+     * Initializes orchestration state.
+     * Must be called before any subform registration or handler execution.
+     */
+    initialize(form: FormGroup, formOrchestratorOptions?: FormOrchestratorOptions): void;
+    setForm(form: FormGroup): void;
+    getHandler(key: string): FormHandlerBase<string> | undefined;
+    setHandler(key: string, handler: FormHandlerBase<string>): void;
+    addReactiveLogic(subscription: Subscription): void;
+    setStatus(status: FormStatus): void;
+    setErrorMessage(message: string | null): void;
+    ngOnDestroy(): void;
+    /**
+     * Registers a subform into the main form tree and coordinates handler execution.
+     *
+     * IMPORTANT:
+     * - Handler execution is gated until all registered subhandlers are ready.
+     * - Calling order matters; this is lifecycle-sensitive orchestration logic.
+     */
+    onSubformReady(subform: FormGroup, groupName: string, nestGroups?: boolean): void;
+    private loadMainHandler;
+    static ɵfac: i0.ɵɵFactoryDeclaration<FormOrchestratorBase, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<FormOrchestratorBase, never, never, {}, {}, never, never, true, never>;
+}
+export {};

package/lib/form.util.d.ts

@@ -0,0 +1,5 @@
+import { FormControl, FormGroup } from '@angular/forms';
+export declare function getControl<T = unknown>(controlName: string, form: FormGroup): FormControl<T>;
+export declare function getControlValue<T = unknown>(controlName: string, form: FormGroup): T | null;
+export declare function getControlValue(controlName: string, form: FormGroup): number | null;
+export declare function parseCurrency(currencyString: string | number | null | undefined): number;

package/lib/index.d.ts

@@ -0,0 +1,4 @@
+export * from './form-control-base';
+export * from './form-handler-base';
+export * from './form-mapper-base';
+export * from './form-orchestrator-base';

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@ng-modular-forms/core",
+  "version": "0.1.0",
+  "peerDependencies": {
+    "@angular/core": ">=17 <22",
+    "@angular/common": ">=17 <22",
+    "@angular/forms": ">=17 <22",
+    "rxjs": ">=7.8.0 <8"
+  },
+  "dependencies": {
+    "tslib": "^2.6.0"
+  },
+  "sideEffects": false,
+  "module": "fesm2022/ng-modular-forms-core.mjs",
+  "typings": "index.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./fesm2022/ng-modular-forms-core.mjs"
+    }
+  }
+}

package/public-api.d.ts

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