ngx-form-signal 1.18.0

package/README.md

@@ -0,0 +1,24 @@
+# NgxFormSignal
+
+This library was generated with [Angular CLI](https://github.com/angular/angular-cli) version 18.2.0.
+
+## Code scaffolding
+
+Run `ng generate component component-name --project ngx-form-signal` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module --project ngx-form-signal`.
+> Note: Don't forget to add `--project ngx-form-signal` or else it will be added to the default project in your `angular.json` file. 
+
+## Build
+
+Run `ng build ngx-form-signal` to build the project. The build artifacts will be stored in the `dist/` directory.
+
+## Publishing
+
+After building your library with `ng build ngx-form-signal`, go to the dist folder `cd dist/ngx-form-signal` and run `npm publish`.
+
+## Running unit tests
+
+Run `ng test ngx-form-signal` to execute the unit tests via [Karma](https://karma-runner.github.io).
+
+## Further help
+
+To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI Overview and Command Reference](https://angular.dev/tools/cli) page.

package/ng-package.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "../../node_modules/ng-packagr/ng-package.schema.json",
+  "dest": "../../dist/ngx-form-signal",
+  "lib": {
+    "entryFile": "src/public-api.ts"
+  }
+}

package/package.json

@@ -0,0 +1,13 @@
+{
+   "name": "ngx-form-signal",
+   "version": "1.18.0",
+   "peerDependencies": {
+      "@angular/common": "^18.2.0",
+      "@angular/core": "^18.2.0",
+      "@angular/forms": "^18.2.0"
+   },
+   "dependencies": {
+      "tslib": "^2.3.0"
+   },
+   "sideEffects": false
+}

package/src/lib/form-signal.ts

@@ -0,0 +1,75 @@
+import {
+   assertInInjectionContext,
+   isSignal,
+   Signal,
+   signal,
+} from '@angular/core';
+import { buildFormDirtySignal } from './helpers/form-dirty-signal';
+import { buildFormErrorSignal } from './helpers/form-error-signal';
+import { buildFormSnapshotSignal } from './helpers/form-snapshot-signal';
+import { buildFormStatusSignal } from './helpers/form-status-signal';
+import { buildFormTouchedSignal } from './helpers/form-touched-signal';
+import { buildFormValueSignal } from './helpers/form-value-signal';
+import {
+   buildDefaultFormSignalOptions,
+   FormSignalOptions,
+} from './types/form-signal-options';
+import { FormSignal, FormSignalState } from './types/form-signal-type';
+import { OptionalFormFromType } from './types/form-type';
+
+export function formSignal<T = any>(
+   form: Signal<OptionalFormFromType<T>> | OptionalFormFromType<T>,
+   options: FormSignalOptions = buildDefaultFormSignalOptions<T>()
+): FormSignal<T> {
+   const formAsSignal = isSignal(form) ? form : signal(form);
+   if (!options.injector) {
+      assertInInjectionContext(() => {});
+   }
+   const { value$, rawValue$, valueChangeSubscription$ } =
+      buildFormValueSignal<T>(formAsSignal, options);
+   const {
+      status$,
+      valid$,
+      invalid$,
+      pending$,
+      disabled$,
+      enabled$,
+      statusChangeSubscription$,
+   } = buildFormStatusSignal<T>(formAsSignal, options);
+   const { touched$, untouched$, touchedChangeSubscription$ } =
+      buildFormTouchedSignal(formAsSignal, options);
+   const { dirty$, pristine$, dirtyChangeSubscription$ } = buildFormDirtySignal(
+      formAsSignal,
+      options
+   );
+   const errors$ = buildFormErrorSignal(formAsSignal, value$, status$, options);
+
+   const formSignals: FormSignalState<T> = {
+      status: status$.asReadonly(),
+      value: value$.asReadonly(),
+      rawValue: rawValue$.asReadonly(),
+      touched: touched$.asReadonly(),
+      untouched: untouched$,
+      dirty: dirty$.asReadonly(),
+      pristine: pristine$,
+      valid: valid$,
+      invalid: invalid$,
+      pending: pending$,
+      disabled: disabled$,
+      enabled: enabled$,
+      errors: errors$,
+      subscriptions: {
+         valueChangeSubscription: valueChangeSubscription$.asReadonly(),
+         statusChangeSubscription: statusChangeSubscription$.asReadonly(),
+         touchedChangeSubscription: touchedChangeSubscription$.asReadonly(),
+         dirtyChangeSubscription: dirtyChangeSubscription$.asReadonly(),
+      },
+   };
+
+   const snapshot$ = buildFormSnapshotSignal(formSignals);
+   const formSignalObj = (() => snapshot$()) as FormSignal<T>;
+
+   Object.setPrototypeOf(formSignalObj, formSignals);
+
+   return formSignalObj;
+}

package/src/lib/helpers/form-dirty-signal.ts

@@ -0,0 +1,46 @@
+import { computed, effect, Signal, signal, untracked } from '@angular/core';
+import { PristineChangeEvent } from '@angular/forms';
+import { filter, Subscription } from 'rxjs';
+import { FormSignalOptions } from '../types/form-signal-options';
+import { OptionalFormFromType } from '../types/form-type';
+
+export function buildFormDirtySignal(
+   formAsSignal: Signal<OptionalFormFromType<any>>,
+   options: FormSignalOptions
+) {
+   const dirty$ = signal<boolean>(!!formAsSignal()?.dirty, {
+      equal: options.equalityFns?.dirtyEquality,
+   });
+   const dirtyChangeSubscription$ = signal<Subscription | null>(null);
+
+   const formDirtyChangeEffect = effect(
+      (onCleanup: Function) => {
+         const form = formAsSignal();
+         untracked(() => {
+            const setDirty = () => {
+               untracked(() => {
+                  dirty$.set(!!form?.dirty);
+               });
+            };
+
+            dirtyChangeSubscription$()?.unsubscribe();
+            dirtyChangeSubscription$.set(
+               form?.events
+                  .pipe(filter((e) => e instanceof PristineChangeEvent))
+                  .subscribe((e) => {
+                     setDirty();
+                  }) ?? null
+            );
+            setDirty();
+         });
+         onCleanup(
+            () => untracked(() => dirtyChangeSubscription$())?.unsubscribe()
+         );
+      },
+      { injector: options.injector }
+   );
+
+   const pristine$ = computed(() => !dirty$());
+
+   return { dirty$, pristine$, dirtyChangeSubscription$ };
+}

package/src/lib/helpers/form-error-signal.ts

@@ -0,0 +1,28 @@
+import {
+   Signal,
+   WritableSignal,
+   computed,
+   isSignal,
+   signal,
+} from '@angular/core';
+import { FormControlStatus } from '@angular/forms';
+import { FormSignalOptions } from '../types/form-signal-options';
+import { FormFromType, OptionalFormFromType } from '../types/form-type';
+
+export function buildFormErrorSignal<T = any>(
+   form: Signal<OptionalFormFromType<T>> | OptionalFormFromType<T>,
+   valueSignal: WritableSignal<FormFromType<T>['value'] | null>,
+   statusSignal: WritableSignal<FormControlStatus | null>,
+   options: FormSignalOptions<T>
+) {
+   const formAsSignal = isSignal(form) ? form : signal(form);
+
+   return computed(
+      () => {
+         const v = valueSignal();
+         const s = statusSignal();
+         return formAsSignal()?.errors ?? null;
+      },
+      { equal: options.equalityFns?.errorsEquality }
+   );
+}

package/src/lib/helpers/form-invalid-signal.ts

@@ -0,0 +1,23 @@
+import {
+   Signal,
+   WritableSignal,
+   computed,
+   isSignal,
+   signal,
+} from '@angular/core';
+import { FormControlStatus } from '@angular/forms';
+import { FormFromType, OptionalFormFromType } from '../types/form-type';
+
+export function buildFormInvalidSignal<T = any>(
+   form: Signal<OptionalFormFromType<T>> | OptionalFormFromType<T>,
+   valueSignal: WritableSignal<FormFromType<T>['value'] | null>,
+   statusSignal: WritableSignal<FormControlStatus | null>
+) {
+   const formAsSignal = isSignal(form) ? form : signal(form);
+
+   return computed(() => {
+      const v = valueSignal();
+      const s = statusSignal();
+      return !!formAsSignal()?.invalid;
+   });
+}

package/src/lib/helpers/form-snapshot-signal.ts

@@ -0,0 +1,37 @@
+import { computed } from '@angular/core';
+import {
+   FormSignalState,
+   FormSnapshotSignalState,
+} from '../types/form-signal-type';
+
+export function buildFormSnapshotSignal<T = any>(
+   formSignalState: FormSignalState<T>
+) {
+   return computed<FormSnapshotSignalState<T>>(() => {
+      return {
+         status: formSignalState.status(),
+         value: formSignalState.value(),
+         rawValue: formSignalState.rawValue(),
+         touched: formSignalState.touched(),
+         untouched: formSignalState.untouched(),
+         dirty: formSignalState.dirty(),
+         pristine: formSignalState.pristine(),
+         valid: formSignalState.valid(),
+         invalid: formSignalState.invalid(),
+         pending: formSignalState.pending(),
+         disabled: formSignalState.disabled(),
+         enabled: formSignalState.enabled(),
+         errors: formSignalState.errors(),
+         subscriptions: {
+            valueChangeSubscription:
+               formSignalState.subscriptions.valueChangeSubscription(),
+            statusChangeSubscription:
+               formSignalState.subscriptions.statusChangeSubscription(),
+            touchedChangeSubscription:
+               formSignalState.subscriptions.touchedChangeSubscription(),
+            dirtyChangeSubscription:
+               formSignalState.subscriptions.dirtyChangeSubscription(),
+         },
+      };
+   });
+}

package/src/lib/helpers/form-status-signal.ts

@@ -0,0 +1,57 @@
+import { computed, effect, Signal, signal, untracked } from '@angular/core';
+import { FormControlStatus } from '@angular/forms';
+import { Subscription } from 'rxjs';
+import { FormSignalOptions } from '../types/form-signal-options';
+import { OptionalFormFromType } from '../types/form-type';
+
+export function buildFormStatusSignal<T = any>(
+   formAsSignal: Signal<OptionalFormFromType<T>>,
+   options: FormSignalOptions<T>
+) {
+   const equal = options.equalityFns?.statusEquality ?? (() => false);
+   const status$ = signal<FormControlStatus | null>(
+      formAsSignal()?.status ?? null,
+      { equal }
+   );
+   const statusChangeSubscription$ = signal<Subscription | null>(null);
+   const formStatusChangeEffect = effect(
+      (onCleanup: Function) => {
+         const form = formAsSignal();
+         untracked(() => {
+            const setStatus = () => {
+               untracked(() => {
+                  status$.set(form?.status ?? null);
+               });
+            };
+
+            statusChangeSubscription$()?.unsubscribe();
+            statusChangeSubscription$.set(
+               form?.statusChanges.subscribe(() => {
+                  setStatus();
+               }) ?? null
+            );
+            setStatus();
+         });
+         onCleanup(
+            () => untracked(() => statusChangeSubscription$())?.unsubscribe()
+         );
+      },
+      { injector: options.injector }
+   );
+
+   const valid$ = computed(() => status$() === 'VALID');
+   const invalid$ = computed(() => status$() === 'INVALID');
+   const pending$ = computed(() => status$() == 'PENDING');
+   const disabled$ = computed(() => status$() === 'DISABLED');
+   const enabled$ = computed(() => status$() !== 'DISABLED');
+
+   return {
+      status$,
+      valid$,
+      invalid$,
+      pending$,
+      disabled$,
+      enabled$,
+      statusChangeSubscription$,
+   };
+}

package/src/lib/helpers/form-touched-signal.ts

@@ -0,0 +1,48 @@
+import { computed, effect, Signal, signal, untracked } from '@angular/core';
+import { TouchedChangeEvent } from '@angular/forms';
+import { filter, Subscription } from 'rxjs';
+import { FormSignalOptions } from '../types/form-signal-options';
+import { OptionalFormFromType } from '../types/form-type';
+
+export function buildFormTouchedSignal(
+   formAsSignal: Signal<OptionalFormFromType<any>>,
+   options: FormSignalOptions
+) {
+   const touched$ = signal<boolean>(!!formAsSignal()?.touched, {
+      equal: options.equalityFns?.touchedEquality,
+   });
+   const touchedChangeSubscription$ = signal<Subscription | null>(null);
+
+   const formTouchedChangeEffect = effect(
+      (onCleanup: Function) => {
+         const form = formAsSignal();
+         untracked(() => {
+            const setTouched = () => {
+               untracked(() => {
+                  touched$.set(!!form?.touched);
+               });
+            };
+
+            touchedChangeSubscription$()?.unsubscribe();
+            touchedChangeSubscription$.set(
+               form?.events
+                  .pipe(filter((e) => e instanceof TouchedChangeEvent))
+                  .subscribe((e) => {
+                     setTouched();
+                  }) ?? null
+            );
+            setTouched();
+         });
+         onCleanup(
+            () => untracked(() => touchedChangeSubscription$())?.unsubscribe()
+         );
+      },
+      { injector: options.injector }
+   );
+
+   const untouched$ = computed(() => !touched$(), {
+      equal: options.equalityFns?.touchedEquality,
+   });
+
+   return { touched$, untouched$, touchedChangeSubscription$ };
+}

package/src/lib/helpers/form-value-signal.ts

@@ -0,0 +1,48 @@
+import { effect, Signal, signal, untracked } from '@angular/core';
+import { AbstractControl } from '@angular/forms';
+import { Subscription } from 'rxjs';
+import { FormSignalOptions } from '../types/form-signal-options';
+import { FormFromType, OptionalFormFromType } from '../types/form-type';
+
+export function buildFormValueSignal<T = any>(
+   formAsSignal: Signal<OptionalFormFromType<T>>,
+   options: FormSignalOptions<T>
+) {
+   const value$ = signal<FormFromType<T>['value'] | null>(
+      formAsSignal()?.value ?? null,
+      { equal: options.equalityFns?.valueEquality ?? (() => false) }
+   );
+   const rawValue$ = signal<FormFromType<T>['value'] | null>(
+      formAsSignal()?.getRawValue() ?? null,
+      {
+         equal: options.equalityFns?.valueEquality ?? (() => false),
+      }
+   );
+   const valueChangeSubscription$ = signal<Subscription | null>(null);
+   const formValueChangeEffect = effect(
+      (onCleanup: Function) => {
+         const form = formAsSignal() as AbstractControl<T> | null;
+         untracked(() => {
+            const setValue = () => {
+               untracked(() => {
+                  value$.set(form?.value ?? null);
+                  rawValue$.set(form?.getRawValue() ?? null);
+               });
+            };
+
+            valueChangeSubscription$()?.unsubscribe();
+            valueChangeSubscription$.set(
+               form?.valueChanges.subscribe(() => {
+                  setValue();
+               }) ?? null
+            );
+            setValue();
+         });
+         onCleanup(
+            () => untracked(() => valueChangeSubscription$())?.unsubscribe()
+         );
+      },
+      { injector: options.injector }
+   );
+   return { value$, rawValue$, valueChangeSubscription$ };
+}

package/src/lib/types/form-signal-options.ts

@@ -0,0 +1,20 @@
+import { Injector, ValueEqualityFn } from '@angular/core';
+import { FormControlStatus, ValidationErrors } from '@angular/forms';
+import { FormFromType } from './form-type';
+
+export type FormSignalEqualityOptions<T = any> = {
+   dirtyEquality: ValueEqualityFn<boolean>;
+   touchedEquality: ValueEqualityFn<boolean>;
+   valueEquality: ValueEqualityFn<FormFromType<T>['value'] | null>;
+   statusEquality: ValueEqualityFn<FormControlStatus | null>;
+   errorsEquality: ValueEqualityFn<ValidationErrors | null>;
+};
+export type FormSignalOptions<T = any> = {
+   injector?: Injector;
+   equalityFns?: Partial<FormSignalEqualityOptions<T>>;
+};
+
+export const defaultFormSignalOptions: FormSignalOptions = {};
+export function buildDefaultFormSignalOptions<T = any>(): FormSignalOptions<T> {
+   return structuredClone(defaultFormSignalOptions);
+}

package/src/lib/types/form-signal-type.ts

@@ -0,0 +1,68 @@
+import { buildFormDirtySignal } from '../helpers/form-dirty-signal';
+import { buildFormErrorSignal } from '../helpers/form-error-signal';
+import { buildFormStatusSignal } from '../helpers/form-status-signal';
+import { buildFormTouchedSignal } from '../helpers/form-touched-signal';
+import { buildFormValueSignal } from '../helpers/form-value-signal';
+
+export type FormSignalSubscriptionsState<T = any> = {
+   valueChangeSubscription: ReturnType<
+      ReturnType<
+         typeof buildFormValueSignal<T>
+      >['valueChangeSubscription$']['asReadonly']
+   >;
+   statusChangeSubscription: ReturnType<
+      ReturnType<
+         typeof buildFormStatusSignal
+      >['statusChangeSubscription$']['asReadonly']
+   >;
+   touchedChangeSubscription: ReturnType<
+      ReturnType<
+         typeof buildFormTouchedSignal
+      >['touchedChangeSubscription$']['asReadonly']
+   >;
+   dirtyChangeSubscription: ReturnType<
+      ReturnType<
+         typeof buildFormDirtySignal
+      >['dirtyChangeSubscription$']['asReadonly']
+   >;
+};
+export type FormSignalState<T = any> = {
+   status: ReturnType<
+      ReturnType<typeof buildFormStatusSignal>['status$']['asReadonly']
+   >;
+   value: ReturnType<
+      ReturnType<typeof buildFormValueSignal<T>>['value$']['asReadonly']
+   >;
+   rawValue: ReturnType<
+      ReturnType<typeof buildFormValueSignal<T>>['rawValue$']['asReadonly']
+   >;
+   touched: ReturnType<
+      ReturnType<typeof buildFormTouchedSignal>['touched$']['asReadonly']
+   >;
+   untouched: ReturnType<typeof buildFormTouchedSignal>['untouched$'];
+   dirty: ReturnType<
+      ReturnType<typeof buildFormDirtySignal>['dirty$']['asReadonly']
+   >;
+   pristine: ReturnType<typeof buildFormDirtySignal>['pristine$'];
+   valid: ReturnType<typeof buildFormStatusSignal>['valid$'];
+   invalid: ReturnType<typeof buildFormStatusSignal>['invalid$'];
+   pending: ReturnType<typeof buildFormStatusSignal>['pending$'];
+   disabled: ReturnType<typeof buildFormStatusSignal>['disabled$'];
+   enabled: ReturnType<typeof buildFormStatusSignal>['enabled$'];
+   errors: ReturnType<typeof buildFormErrorSignal>;
+   subscriptions: FormSignalSubscriptionsState<T>;
+};
+
+export type FormSnapshotSignalSubscriptionsState<T = any> = {
+   [x in keyof FormSignalSubscriptionsState<T>]: ReturnType<
+      FormSignalSubscriptionsState<T>[x]
+   >;
+};
+export type FormSnapshotSignalState<T = any> = {
+   [x in keyof Omit<FormSignalState<T>, 'subscriptions'>]: ReturnType<
+      FormSignalState<T>[x]
+   >;
+} & { subscriptions: FormSnapshotSignalSubscriptionsState<T> };
+
+export type FormSignal<T = any> = FormSignalState<T> &
+   (() => FormSnapshotSignalState<T>);

package/src/lib/types/form-type.ts

@@ -0,0 +1,18 @@
+import {
+   AbstractControl,
+   FormArray,
+   FormControl,
+   FormGroup,
+} from '@angular/forms';
+
+export type FormFromType<T> = T extends { [K in keyof T]: AbstractControl<any> }
+   ? FormGroup<T>
+   : T extends AbstractControl<any>
+     ? FormArray<T>
+     : FormControl<T>;
+
+export type OptionalFormFromType<T = any> =
+   | (T extends { [K in keyof T]: AbstractControl<any> } ? FormGroup<T> : never)
+   | FormControl<T>
+   | (T extends AbstractControl<any> ? FormArray<T> : never)
+   | null;

package/src/public-api.ts

@@ -0,0 +1,8 @@
+/*
+ * Public API Surface of ngx-form-signal
+ */
+
+export * from './lib/form-signal';
+export * from './lib/types/form-signal-options';
+export * from './lib/types/form-signal-type';
+export * from './lib/types/form-type';

package/tsconfig.lib.json

@@ -0,0 +1,15 @@
+/* To learn more about Typescript configuration file: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html. */
+/* To learn more about Angular compiler options: https://angular.dev/reference/configs/angular-compiler-options. */
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../out-tsc/lib",
+    "declaration": true,
+    "declarationMap": true,
+    "inlineSources": true,
+    "types": []
+  },
+  "exclude": [
+    "**/*.spec.ts"
+  ]
+}

package/tsconfig.lib.prod.json

@@ -0,0 +1,11 @@
+/* To learn more about Typescript configuration file: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html. */
+/* To learn more about Angular compiler options: https://angular.dev/reference/configs/angular-compiler-options. */
+{
+  "extends": "./tsconfig.lib.json",
+  "compilerOptions": {
+    "declarationMap": false
+  },
+  "angularCompilerOptions": {
+    "compilationMode": "partial"
+  }
+}

package/tsconfig.spec.json

@@ -0,0 +1,15 @@
+/* To learn more about Typescript configuration file: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html. */
+/* To learn more about Angular compiler options: https://angular.dev/reference/configs/angular-compiler-options. */
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../out-tsc/spec",
+    "types": [
+      "jasmine"
+    ]
+  },
+  "include": [
+    "**/*.spec.ts",
+    "**/*.d.ts"
+  ]
+}