@signaltree/ng-forms 4.0.7 → 4.0.9

package/src/core/validators.ts

@@ -0,0 +1,209 @@
+/**
+ * @fileoverview Tree-shakeable validator functions for form fields
+ *
+ * These validators are exported as individual functions to enable
+ * tree-shaking. Only the validators you actually use will be included
+ * in your bundle.
+ */
+
+import type { FieldValidator } from './ng-forms';
+
+/**
+ * Creates a required field validator
+ *
+ * @param message - Custom error message (default: "Required")
+ * @returns Validator function that returns error message if value is falsy
+ *
+ * @example
+ * ```typescript
+ * createFormTree(data, {
+ *   validators: {
+ *     name: required(),
+ *     email: required('Email is required')
+ *   }
+ * });
+ * ```
+ */
+export function required(message = 'Required'): FieldValidator {
+  return (value: unknown) => (!value ? message : null);
+}
+
+/**
+ * Creates an email format validator
+ *
+ * @param message - Custom error message (default: "Invalid email")
+ * @returns Validator function that checks for @ symbol
+ *
+ * @example
+ * ```typescript
+ * createFormTree(data, {
+ *   validators: {
+ *     email: email('Please enter a valid email address')
+ *   }
+ * });
+ * ```
+ */
+export function email(message = 'Invalid email'): FieldValidator {
+  return (value: unknown) => {
+    const strValue = value as string;
+    return strValue && !strValue.includes('@') ? message : null;
+  };
+}
+
+/**
+ * Creates a minimum length validator for strings
+ *
+ * @param min - Minimum required length
+ * @param message - Optional custom error message
+ * @returns Validator function that checks string length
+ *
+ * @example
+ * ```typescript
+ * createFormTree(data, {
+ *   validators: {
+ *     password: minLength(8),
+ *     description: minLength(10, 'Description must be at least 10 characters')
+ *   }
+ * });
+ * ```
+ */
+export function minLength(min: number, message?: string): FieldValidator {
+  return (value: unknown) => {
+    const strValue = value as string;
+    const errorMsg = message ?? `Min ${min} characters`;
+    return strValue && strValue.length < min ? errorMsg : null;
+  };
+}
+
+/**
+ * Creates a maximum length validator for strings
+ *
+ * @param max - Maximum allowed length
+ * @param message - Optional custom error message
+ * @returns Validator function that checks string length
+ *
+ * @example
+ * ```typescript
+ * createFormTree(data, {
+ *   validators: {
+ *     username: maxLength(20),
+ *     bio: maxLength(500, 'Bio must be under 500 characters')
+ *   }
+ * });
+ * ```
+ */
+export function maxLength(max: number, message?: string): FieldValidator {
+  return (value: unknown) => {
+    const strValue = value as string;
+    const errorMsg = message ?? `Max ${max} characters`;
+    return strValue && strValue.length > max ? errorMsg : null;
+  };
+}
+
+/**
+ * Creates a regex pattern validator
+ *
+ * @param regex - Regular expression to test against
+ * @param message - Custom error message (default: "Invalid format")
+ * @returns Validator function that tests value against regex
+ *
+ * @example
+ * ```typescript
+ * createFormTree(data, {
+ *   validators: {
+ *     phone: pattern(/^\d{3}-\d{3}-\d{4}$/, 'Phone must be in format: 123-456-7890'),
+ *     zipCode: pattern(/^\d{5}$/, 'Zip code must be 5 digits')
+ *   }
+ * });
+ * ```
+ */
+export function pattern(
+  regex: RegExp,
+  message = 'Invalid format'
+): FieldValidator {
+  return (value: unknown) => {
+    const strValue = value as string;
+    return strValue && !regex.test(strValue) ? message : null;
+  };
+}
+
+/**
+ * Creates a minimum value validator for numbers
+ *
+ * @param min - Minimum allowed value
+ * @param message - Optional custom error message
+ * @returns Validator function that checks numeric minimum
+ *
+ * @example
+ * ```typescript
+ * createFormTree(data, {
+ *   validators: {
+ *     age: min(18, 'Must be at least 18 years old'),
+ *     quantity: min(1)
+ *   }
+ * });
+ * ```
+ */
+export function min(min: number, message?: string): FieldValidator {
+  return (value: unknown) => {
+    const numValue = value as number;
+    const errorMsg = message ?? `Must be at least ${min}`;
+    return numValue < min ? errorMsg : null;
+  };
+}
+
+/**
+ * Creates a maximum value validator for numbers
+ *
+ * @param max - Maximum allowed value
+ * @param message - Optional custom error message
+ * @returns Validator function that checks numeric maximum
+ *
+ * @example
+ * ```typescript
+ * createFormTree(data, {
+ *   validators: {
+ *     age: max(120, 'Must be under 120 years old'),
+ *     quantity: max(100)
+ *   }
+ * });
+ * ```
+ */
+export function max(max: number, message?: string): FieldValidator {
+  return (value: unknown) => {
+    const numValue = value as number;
+    const errorMsg = message ?? `Must be at most ${max}`;
+    return numValue > max ? errorMsg : null;
+  };
+}
+
+/**
+ * Combines multiple validators into a single validator function
+ *
+ * @param validators - Array of validator functions to combine
+ * @returns Combined validator that returns the first error encountered
+ *
+ * @example
+ * ```typescript
+ * createFormTree(data, {
+ *   validators: {
+ *     email: compose([
+ *       required('Email is required'),
+ *       email('Invalid email format'),
+ *       pattern(/@company\.com$/, 'Must be a company email')
+ *     ])
+ *   }
+ * });
+ * ```
+ */
+export function compose(validators: FieldValidator[]): FieldValidator {
+  return (value: unknown) => {
+    for (const validator of validators) {
+      const error = validator(value);
+      if (error) {
+        return error;
+      }
+    }
+    return null;
+  };
+}

package/src/history/history.ts

@@ -0,0 +1,169 @@
+import { Signal, signal } from '@angular/core';
+import { deepClone, snapshotsEqual } from '@signaltree/shared';
+
+// Local type definition to avoid circular imports in secondary entry points
+interface FormTree<T extends Record<string, unknown>> {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  form: any; // FormGroup
+  unwrap(): T;
+  destroy(): void;
+  setValues(values: Partial<T>): void;
+}
+
+/**
+ * Form history state structure
+ */
+export interface FormHistory<T> {
+  past: T[];
+  present: T;
+  future: T[];
+}
+
+/**
+ * Enhances a FormTree with undo/redo capabilities.
+ * Provides form-specific history management with capacity limits and change tracking.
+ *
+ * @param formTree - The form tree to enhance
+ * @param options - Configuration options
+ * @param options.capacity - Maximum number of history entries (default: 10)
+ * @returns Extended FormTree with undo, redo, and history access
+ *
+ * @example
+ * ```typescript
+ * const form = createFormTree({ name: '', email: '' });
+ * const formWithHistory = withFormHistory(form, { capacity: 20 });
+ *
+ * form.$.name.set('John');
+ * form.$.email.set('john@example.com');
+ *
+ * formWithHistory.undo(); // Reverts email change
+ * formWithHistory.undo(); // Reverts name change
+ * formWithHistory.redo(); // Reapplies name change
+ *
+ * console.log(formWithHistory.history().past.length); // 1
+ * ```
+ */
+export function withFormHistory<T extends Record<string, unknown>>(
+  formTree: FormTree<T>,
+  options: { capacity?: number } = {}
+): FormTree<T> & {
+  undo: () => void;
+  redo: () => void;
+  clearHistory: () => void;
+  history: Signal<FormHistory<T>>;
+} {
+  const capacity = Math.max(1, options.capacity ?? 10);
+  const historySignal = signal<FormHistory<T>>({
+    past: [],
+    present: deepClone(formTree.form.getRawValue() as T),
+    future: [],
+  });
+
+  let recording = true;
+  let suppressUpdates = 0;
+  let internalHistory: FormHistory<T> = {
+    past: [],
+    present: deepClone(formTree.form.getRawValue() as T),
+    future: [],
+  };
+
+  const subscription = formTree.form.valueChanges.subscribe(() => {
+    if (suppressUpdates > 0) {
+      suppressUpdates--;
+      return;
+    }
+
+    if (!recording) {
+      internalHistory = {
+        ...internalHistory,
+        present: deepClone(formTree.form.getRawValue() as T),
+      };
+      return;
+    }
+    const snapshot = deepClone(formTree.form.getRawValue() as T);
+    if (snapshotsEqual(internalHistory.present, snapshot)) {
+      internalHistory = {
+        ...internalHistory,
+        present: snapshot,
+      };
+      historySignal.set(cloneHistory(internalHistory));
+      return;
+    }
+    const updatedPast = [...internalHistory.past, internalHistory.present];
+    if (updatedPast.length > capacity) {
+      updatedPast.shift();
+    }
+    internalHistory = {
+      past: updatedPast,
+      present: snapshot,
+      future: [],
+    };
+    historySignal.set(cloneHistory(internalHistory));
+  });
+
+  const originalDestroy = formTree.destroy;
+  formTree.destroy = () => {
+    subscription.unsubscribe();
+    originalDestroy();
+  };
+
+  const undo = () => {
+    const history = historySignal();
+    if (history.past.length === 0) {
+      return;
+    }
+    const previous = deepClone(history.past[history.past.length - 1]);
+    recording = false;
+    suppressUpdates++;
+    formTree.setValues(previous);
+    recording = true;
+    internalHistory = {
+      past: history.past.slice(0, -1),
+      present: previous,
+      future: [history.present, ...history.future],
+    };
+    historySignal.set(cloneHistory(internalHistory));
+  };
+
+  const redo = () => {
+    const history = historySignal();
+    if (history.future.length === 0) {
+      return;
+    }
+    const next = deepClone(history.future[0]);
+    recording = false;
+    suppressUpdates++;
+    formTree.setValues(next);
+    recording = true;
+    internalHistory = {
+      past: [...history.past, history.present],
+      present: next,
+      future: history.future.slice(1),
+    };
+    historySignal.set(cloneHistory(internalHistory));
+  };
+
+  const clearHistory = () => {
+    internalHistory = {
+      past: [],
+      present: deepClone(formTree.form.getRawValue() as T),
+      future: [],
+    };
+    historySignal.set(cloneHistory(internalHistory));
+  };
+
+  function cloneHistory(state: FormHistory<T>): FormHistory<T> {
+    return {
+      past: state.past.map((entry) => deepClone(entry)),
+      present: deepClone(state.present),
+      future: state.future.map((entry) => deepClone(entry)),
+    };
+  }
+
+  return Object.assign(formTree, {
+    undo,
+    redo,
+    clearHistory,
+    history: historySignal.asReadonly(),
+  });
+}

package/src/history/index.ts

@@ -0,0 +1 @@
+export { withFormHistory, type FormHistory } from './history';

package/src/history/ng-package.json

@@ -0,0 +1,5 @@
+{
+  "lib": {
+    "entryFile": "index.ts"
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+/// <reference path="./types/signaltree-core.d.ts" />
+export * from './core/ng-forms';
+export * from './core/validators';
+export * from './core/async-validators';
+export * from './history';

package/src/rxjs/index.ts

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

package/src/rxjs/ng-package.json

@@ -0,0 +1,5 @@
+{
+  "lib": {
+    "entryFile": "public-api.ts"
+  }
+}

package/src/rxjs/public-api.ts

@@ -0,0 +1,5 @@
+/**
+ * Public API Surface of @signaltree/ng-forms/rxjs
+ */
+
+export * from './rxjs-bridge';

package/src/rxjs/rxjs-bridge.ts

@@ -0,0 +1,75 @@
+import { effect, Signal } from '@angular/core';
+import { Observable } from 'rxjs';
+
+/**
+ * @fileoverview RxJS bridge for converting Angular signals to observables
+ *
+ * This module provides utilities for integrating SignalTree forms with
+ * RxJS-based reactive patterns.
+ */
+
+/**
+ * Converts an Angular signal to an RxJS Observable.
+ *
+ * Creates an Observable that emits the signal's value whenever it changes.
+ * The effect is automatically destroyed when the Observable is unsubscribed.
+ *
+ * @template T - The type of value emitted by the signal
+ * @param signal - The Angular signal to convert
+ * @returns Observable that mirrors the signal's values
+ *
+ * @example
+ * ```typescript
+ * import { toObservable } from '@signaltree/ng-forms/rxjs';
+ *
+ * const form = createFormTree({ name: '' });
+ *
+ * // Convert form signals to observables
+ * const name$ = toObservable(form.$.name);
+ * const errors$ = toObservable(form.errors);
+ *
+ * // Use with RxJS operators
+ * name$.pipe(
+ *   debounceTime(300),
+ *   distinctUntilChanged()
+ * ).subscribe(value => {
+ *   console.log('Name changed:', value);
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Combine multiple form signals
+ * import { combineLatest } from 'rxjs';
+ *
+ * const form = createFormTree({
+ *   firstName: '',
+ *   lastName: ''
+ * });
+ *
+ * combineLatest([
+ *   toObservable(form.$.firstName),
+ *   toObservable(form.$.lastName)
+ * ]).pipe(
+ *   map(([first, last]) => `${first} ${last}`)
+ * ).subscribe(fullName => {
+ *   console.log('Full name:', fullName);
+ * });
+ * ```
+ */
+export function toObservable<T>(signal: Signal<T>): Observable<T> {
+  return new Observable((subscriber) => {
+    try {
+      const effectRef = effect(() => {
+        subscriber.next(signal());
+      });
+      return () => effectRef.destroy();
+    } catch {
+      // Fallback for test environment without injection context
+      subscriber.next(signal());
+      return () => {
+        // No cleanup needed for single emission
+      };
+    }
+  });
+}

package/src/test-setup.ts

@@ -0,0 +1,6 @@
+import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';
+
+setupZoneTestEnv({
+  errorOnUnknownElements: true,
+  errorOnUnknownProperties: true,
+});

package/src/types/signaltree-core.d.ts

@@ -0,0 +1,11 @@
+declare module '@signaltree/core' {
+  export { signalTree } from '../../../core/src/lib/signal-tree';
+  export type {
+    SignalTree,
+    TreeConfig,
+    TreeNode,
+    Enhancer,
+    Middleware
+  } from '../../../core/src/lib/types';
+  export * from '../../../core/src/index';
+}

package/src/wizard/index.ts

@@ -0,0 +1 @@
+export { createWizardForm, type FormStep } from './wizard';

package/src/wizard/wizard.ts

@@ -0,0 +1,145 @@
+import { computed, Signal, signal } from '@angular/core';
+
+import { createFormTree } from '..';
+
+// Local type definitions to avoid circular imports in secondary entry points
+type FormTreeOptions = Record<string, unknown>;
+
+interface FormTree<T extends Record<string, unknown>> {
+  unwrap(): T;
+}
+/**
+ * Defines a step in a wizard form
+ */
+export interface FormStep<T extends Record<string, unknown>> {
+  /** Fields visible in this step */
+  fields: Array<keyof T | string>;
+  /** Optional validation function to run before proceeding to next step */
+  validate?: (form: FormTree<T>) => Promise<boolean> | boolean;
+  /** Optional function to determine if this step can be skipped */
+  canSkip?: (values: T) => boolean;
+}
+
+/**
+ * Creates a wizard form with multi-step navigation.
+ * Manages step visibility, navigation, and per-step validation.
+ *
+ * @param steps - Array of form steps defining fields and validation
+ * @param initialValues - Initial form values
+ * @param config - Optional form tree configuration
+ * @returns Extended FormTree with wizard navigation methods
+ *
+ * @example
+ * ```typescript
+ * const wizard = createWizardForm(
+ *   [
+ *     { fields: ['email', 'password'] },
+ *     { fields: ['firstName', 'lastName'], validate: async (form) => form.valid() },
+ *     { fields: ['address', 'city', 'zip'] }
+ *   ],
+ *   { email: '', password: '', firstName: '', lastName: '', address: '', city: '', zip: '' }
+ * );
+ *
+ * await wizard.nextStep(); // Move to step 2
+ * wizard.previousStep();   // Back to step 1
+ * await wizard.goToStep(2); // Jump to step 3
+ * ```
+ */
+export function createWizardForm<T extends Record<string, unknown>>(
+  steps: FormStep<T>[],
+  initialValues: T,
+  config: FormTreeOptions = {}
+): FormTree<T> & {
+  currentStep: Signal<number>;
+  nextStep: () => Promise<boolean>;
+  previousStep: () => void;
+  goToStep: (index: number) => Promise<boolean>;
+  canGoToStep: (index: number) => boolean;
+  isFieldVisible: (field: keyof T | string) => Signal<boolean>;
+} {
+  const formTree = createFormTree(initialValues, config);
+  const currentStepSignal = signal(0);
+
+  const visibleFields = computed(() => {
+    const step = steps[currentStepSignal()];
+    if (!step) {
+      return new Set<string>();
+    }
+    return new Set(step.fields.map((field) => String(field)));
+  });
+
+  const canGoToStep = (index: number) => index >= 0 && index < steps.length;
+
+  const goToStep = async (index: number) => {
+    if (!canGoToStep(index)) {
+      return false;
+    }
+    if (index === currentStepSignal()) {
+      return true;
+    }
+    currentStepSignal.set(index);
+    return true;
+  };
+
+  const findNextStep = (startIndex: number) => {
+    let candidate = startIndex;
+    while (candidate < steps.length) {
+      const candidateStep = steps[candidate];
+      if (
+        !candidateStep?.canSkip ||
+        !candidateStep.canSkip(formTree.unwrap())
+      ) {
+        break;
+      }
+      candidate++;
+    }
+    return candidate;
+  };
+
+  const nextStep = async () => {
+    const currentIndex = currentStepSignal();
+    const currentStep = steps[currentIndex];
+    if (!currentStep) {
+      return false;
+    }
+
+    if (currentStep.validate) {
+      const result = await currentStep.validate(formTree);
+      if (!result) {
+        return false;
+      }
+    }
+
+    const nextIndex = findNextStep(currentIndex + 1);
+    if (!canGoToStep(nextIndex) || nextIndex <= currentIndex) {
+      return false;
+    }
+
+    currentStepSignal.set(nextIndex);
+    return true;
+  };
+
+  const previousStep = () => {
+    const currentIndex = currentStepSignal();
+    currentStepSignal.set(Math.max(0, currentIndex - 1));
+  };
+
+  const isFieldVisible = (field: keyof T | string) =>
+    computed(() => {
+      const fields = visibleFields();
+      if (fields.size === 0) {
+        return true;
+      }
+      return fields.has(String(field));
+    });
+
+  return {
+    ...formTree,
+    currentStep: currentStepSignal.asReadonly(),
+    nextStep,
+    previousStep,
+    goToStep,
+    canGoToStep,
+    isFieldVisible,
+  };
+}

package/tsconfig.json

@@ -0,0 +1,33 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "target": "es2022",
+    "moduleResolution": "node",
+    "strict": true,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "module": "preserve"
+  },
+  "angularCompilerOptions": {
+    "enableI18nLegacyMessageIdFormat": false,
+    "strictInjectionParameters": true,
+    "strictInputAccessModifiers": true,
+    "typeCheckHostBindings": true,
+    "strictTemplates": true
+  },
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "../core"
+    },
+    {
+      "path": "./tsconfig.lib.json"
+    },
+    {
+      "path": "./tsconfig.spec.json"
+    }
+  ]
+}