@dvirus-js/angular-signals 0.0.15 → 0.0.17

package/fesm2022/dvirus-js-angular-signals-signal-form.mjs

@@ -0,0 +1,1409 @@
+import { isSignal, signal, computed } from '@angular/core';
+import { signalOrValue, fromSignalObj, writableSignal } from '@dvirus-js/angular-signals';
+
+/**
+ * Normalizes a validation error object by filtering out empty/null values.
+ *
+ * Converts a raw validation result into a clean error map containing only
+ * non-empty string messages. Filters out undefined, null, and empty strings.
+ *
+ * @param error - Raw validation error object or null
+ * @returns Clean error map with only valid error messages
+ *
+ * @example
+ * ```typescript
+ * normalizeValidationError({ required: 'Error', empty: '', invalid: null });
+ * // Returns: { required: 'Error' }
+ * ```
+ */
+function normalizeValidationError(error) {
+    if (!error)
+        return {};
+    return Object.entries(error).reduce((acc, [key, val]) => {
+        if (typeof val === 'string' && val.length > 0) {
+            acc[key] = val;
+        }
+        return acc;
+    }, {});
+}
+/**
+ * Executes an array of validators and collects all error messages.
+ *
+ * Runs each validator function with the provided context and merges all
+ * error messages into a single error map. Empty/null results are filtered out.
+ *
+ * @template TControls - Object type defining available sibling controls
+ * @template TValue - The type of value being validated
+ *
+ * @param validators - Array of validator functions to execute
+ * @param ctx - Validation context with current value and control accessor
+ * @returns Combined error map from all validators
+ *
+ * @example
+ * ```typescript
+ * const errors = collectValidationErrors(
+ *   [signalFormValidators.required, signalFormValidators.minLength(3)],
+ *   { item: { value: '' }, getControl: () => {} }
+ * );
+ * // Returns: { required: 'This field is required' }
+ * ```
+ */
+function collectValidationErrors(validators, ctx) {
+    if (!validators?.length)
+        return {};
+    return validators.reduce((acc, validator) => {
+        const normalized = normalizeValidationError(validator(ctx));
+        Object.entries(normalized).forEach(([key, val]) => {
+            acc[key] = val;
+        });
+        return acc;
+    }, {});
+}
+/**
+ * Checks if an error map contains any errors.
+ *
+ * Simple utility to determine if a control has validation errors by
+ * checking if the error map object has any keys.
+ *
+ * @param errorMap - Error map to check
+ * @returns True if there are any errors, false if empty
+ *
+ * @example
+ * ```typescript
+ * hasErrors({ required: 'Error' }); // true
+ * hasErrors({}); // false
+ * ```
+ */
+function hasErrors(errorMap) {
+    return Object.keys(errorMap).length > 0;
+}
+/**
+ * Recursively checks if an error tree structure is completely empty.
+ *
+ * Traverses nested error structures (objects and arrays) to determine if
+ * there are any actual error messages anywhere in the tree. Returns true
+ * only when the entire structure contains no errors.
+ *
+ * @param value - Error tree to check (can be nested objects/arrays)
+ * @returns True if no errors exist anywhere in the tree
+ *
+ * @example
+ * ```typescript
+ * isEmptyErrorTree({ name: undefined, address: { street: undefined } }); // true
+ * isEmptyErrorTree({ name: { required: 'Error' } }); // false
+ * isEmptyErrorTree([undefined, undefined]); // true
+ * ```
+ */
+function isEmptyErrorTree(value) {
+    if (value === null || value === undefined)
+        return true;
+    if (Array.isArray(value)) {
+        return value.every(isEmptyErrorTree);
+    }
+    if (typeof value === 'object') {
+        return Object.values(value).every(isEmptyErrorTree);
+    }
+    return false;
+}
+
+/**
+ * Shared empty error map object to avoid creating new objects.
+ *
+ * @internal
+ */
+const EMPTY_ERROR_MAP = {};
+/**
+ * Checks if a value is a plain JavaScript object (not array, not null, not class instance).
+ *
+ * @internal
+ * @param value - Value to check
+ * @returns True if value is a plain object
+ */
+function isPlainObject(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * Checks if an object contains any Angular signal values.
+ *
+ * @internal
+ * @param obj - Object to check for signal values
+ * @returns True if any property value is a signal
+ */
+function hasSignalValues(obj) {
+    return Object.values(obj).some((value) => isSignal(value));
+}
+/**
+ * Resolves a SignalOrValue to its actual value, handling nested signal objects.
+ *
+ * If the resolved value is a plain object containing signals, it converts
+ * all signal properties to their values using fromSignalObj.
+ *
+ * @internal
+ * @template TValue - The type of value to resolve
+ * @param value - Signal or static value to resolve
+ * @returns The resolved value
+ */
+function resolveControlValue(value) {
+    const resolved = signalOrValue(value);
+    if (isPlainObject(resolved) && hasSignalValues(resolved)) {
+        return fromSignalObj(resolved);
+    }
+    return resolved;
+}
+/**
+ * Normalizes various control input formats to a standard SignalFormControlConfig.
+ *
+ * Handles three input types:
+ * - SignalFormControl: extracts current value
+ * - Config object with 'value' property: uses as-is
+ * - Raw value: wraps in config object
+ *
+ * @internal
+ * @template TValue - The type of control value
+ * @template TControls - Object type defining available sibling controls
+ * @param input - Input in any accepted format
+ * @returns Normalized control configuration
+ */
+function normalizeControlInput(input) {
+    if (isSignalFormControl(input)) {
+        return { value: input.value() };
+    }
+    if (typeof input === 'object' && input !== null && 'value' in input) {
+        return input;
+    }
+    return { value: input };
+}
+/**
+ * Type guard to check if an object is a SignalFormControl.
+ *
+ * @template TValue - The type of value the control manages
+ * @param obj - Object to check
+ * @returns True if obj is a SignalFormControl
+ *
+ * @example
+ * ```typescript
+ * if (isSignalFormControl(value)) {
+ *   console.log(value.value()); // TypeScript knows this is a control
+ * }
+ * ```
+ */
+function isSignalFormControl(obj) {
+    return (!!obj &&
+        typeof obj === 'object' &&
+        obj.kind === 'control');
+}
+/**
+ * Creates a reactive form control with signal-based state management.
+ *
+ * Builds a control that wraps a primitive value (string, number, boolean, etc.)
+ * with validation, state tracking, and reactive updates using Angular signals.
+ *
+ * Features:
+ * - Reactive value updates through signals
+ * - Validators for errors (mark control as invalid)
+ * - Warnings (validation messages without invalidating)
+ * - Dynamic disabled state based on form context
+ * - State tracking (touched, dirty)
+ * - Manual error/warning management
+ *
+ * @template TControls - Object type defining available sibling controls for cross-field validation
+ * @template TValue - The type of value this control manages
+ *
+ * @param input - Control input (raw value, config object, or existing control)
+ * @param getControl - Optional accessor function for sibling controls
+ * @returns Fully configured SignalFormControl instance
+ *
+ * @example
+ * ```typescript
+ * // Simple control
+ * const nameControl = createSignalFormControl('John');
+ *
+ * // With validators
+ * const ageControl = createSignalFormControl({
+ *   value: 25,
+ *   validators: [signalFormValidators.required, signalFormValidators.min(0)],
+ *   warnings: [signalFormValidators.max(120)]
+ * });
+ *
+ * // With dynamic disabled
+ * const emailControl = createSignalFormControl({
+ *   value: '',
+ *   disabled: (ctx) => ctx.getControl('accountType').value() === 'guest'
+ * });
+ * ```
+ */
+function createSignalFormControl(input, getControl) {
+    if (isSignalFormControl(input)) {
+        return input;
+    }
+    const config = normalizeControlInput(input);
+    const accessControl = getControl ??
+        (() => {
+            throw new Error('getControl is not available for this control.');
+        });
+    const initialValue = resolveControlValue(config.value);
+    const value = writableSignal(() => resolveControlValue(config.value));
+    const manualErrors = signal({}, ...(ngDevMode ? [{ debugName: "manualErrors" }] : []));
+    const manualWarnings = signal({}, ...(ngDevMode ? [{ debugName: "manualWarnings" }] : []));
+    const selfTouched = signal(false, ...(ngDevMode ? [{ debugName: "selfTouched" }] : []));
+    const selfDirty = signal(false, ...(ngDevMode ? [{ debugName: "selfDirty" }] : []));
+    const selfDisabled = signal(false, ...(ngDevMode ? [{ debugName: "selfDisabled" }] : []));
+    const disabledResolver = config.disabled;
+    const disabled = computed(() => {
+        const derived = typeof disabledResolver === 'function'
+            ? disabledResolver({
+                item: { value: value() },
+                getControl: accessControl,
+            })
+            : disabledResolver
+                ? signalOrValue(disabledResolver)
+                : false;
+        return selfDisabled() || derived;
+    }, ...(ngDevMode ? [{ debugName: "disabled" }] : []));
+    const errors = computed(() => {
+        if (disabled())
+            return EMPTY_ERROR_MAP;
+        const ctx = {
+            item: { value: value() },
+            getControl: accessControl,
+        };
+        return {
+            ...collectValidationErrors(config.validators, ctx),
+            ...manualErrors(),
+        };
+    }, ...(ngDevMode ? [{ debugName: "errors" }] : []));
+    const warnings = computed(() => {
+        if (disabled())
+            return EMPTY_ERROR_MAP;
+        const ctx = {
+            item: { value: value() },
+            getControl: accessControl,
+        };
+        return {
+            ...collectValidationErrors(config.warnings, ctx),
+            ...manualWarnings(),
+        };
+    }, ...(ngDevMode ? [{ debugName: "warnings" }] : []));
+    const invalid = computed(() => !disabled() && hasErrors(errors()), ...(ngDevMode ? [{ debugName: "invalid" }] : []));
+    const valid = computed(() => !invalid(), ...(ngDevMode ? [{ debugName: "valid" }] : []));
+    const firstError = computed(() => {
+        const entries = Object.entries(errors());
+        if (!entries.length)
+            return undefined;
+        const [name, message] = entries[0] ?? ['', ''];
+        return { name, message, type: 'error' };
+    }, ...(ngDevMode ? [{ debugName: "firstError" }] : []));
+    const firstWarning = computed(() => {
+        const entries = Object.entries(warnings());
+        if (!entries.length)
+            return undefined;
+        const [name, message] = entries[0] ?? ['', ''];
+        return { name, message, type: 'warning' };
+    }, ...(ngDevMode ? [{ debugName: "firstWarning" }] : []));
+    const firstErrorOrWarning = computed(() => {
+        return firstError() ?? firstWarning();
+    }, ...(ngDevMode ? [{ debugName: "firstErrorOrWarning" }] : []));
+    const setValue = (next, options) => {
+        value.set(next);
+        if (options?.markDirty ?? true)
+            selfDirty.set(true);
+        if (options?.markTouched)
+            selfTouched.set(true);
+    };
+    const reset = (next) => {
+        value.set(next ?? initialValue);
+        selfDirty.set(false);
+        selfTouched.set(false);
+        manualErrors.set({});
+        manualWarnings.set({});
+    };
+    return {
+        kind: 'control',
+        value,
+        disabled,
+        touched: computed(() => selfTouched()),
+        dirty: computed(() => selfDirty()),
+        errors,
+        warnings,
+        selfErrors: errors,
+        selfWarnings: warnings,
+        invalid,
+        valid,
+        firstError,
+        firstWarning,
+        firstErrorOrWarning,
+        setValue,
+        reset,
+        markTouched: () => selfTouched.set(true),
+        markUntouched: () => selfTouched.set(false),
+        markDirty: () => selfDirty.set(true),
+        markPristine: () => selfDirty.set(false),
+        setDisabled: (next) => selfDisabled.set(next),
+        setError: (key, message) => manualErrors.update((current) => ({ ...current, [key]: message })),
+        clearError: (key) => manualErrors.update((current) => {
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            const { [key]: _removed, ...rest } = current;
+            return rest;
+        }),
+        clearErrors: () => manualErrors.set({}),
+        setWarning: (key, message) => manualWarnings.update((current) => ({ ...current, [key]: message })),
+        clearWarning: (key) => manualWarnings.update((current) => {
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            const { [key]: _removed, ...rest } = current;
+            return rest;
+        }),
+        clearWarnings: () => manualWarnings.set({}),
+    };
+}
+
+/**
+ * Set of valid keys for control configuration objects.
+ * Used to distinguish config objects from plain value objects.
+ *
+ * @internal
+ */
+const CONTROL_CONFIG_KEYS$1 = new Set([
+    'value',
+    'validators',
+    'warnings',
+    'disabled',
+]);
+/**
+ * Checks if a value is a control configuration object.
+ *
+ * Determines if the value has a 'value' property and only contains
+ * valid control config keys (value, validators, warnings, disabled).
+ *
+ * @internal
+ * @param value - Value to check
+ * @returns True if value is a control config object
+ */
+function isControlConfig$1(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    if (!('value' in value))
+        return false;
+    return Object.keys(value).every(key => CONTROL_CONFIG_KEYS$1.has(key));
+}
+/**
+ * Creates the appropriate control node from various input types.
+ *
+ * Recursively determines and creates the correct control type:
+ * - Existing controls are returned as-is
+ * - Arrays become SignalFormArray
+ * - Objects (non-config) become SignalForm (group)
+ * - Primitives/configs become SignalFormControl
+ *
+ * @internal
+ * @template TValue - The type of value to create a control for
+ * @template TControls - Object type defining available sibling controls
+ * @param input - Input value in any accepted format
+ * @param getControl - Accessor for sibling controls
+ * @returns Appropriate control type for the input
+ */
+function createNodeFromInput$1(input, getControl) {
+    if (isSignalFormControl(input)) {
+        return input;
+    }
+    if (isSignalFormGroup(input)) {
+        return input;
+    }
+    if (isSignalFormArray(input)) {
+        return input;
+    }
+    if (Array.isArray(input)) {
+        return createSignalFormArray(input, getControl);
+    }
+    if (typeof input === 'object' && input !== null && !isControlConfig$1(input)) {
+        return createSignalFormGroup(input);
+    }
+    return createSignalFormControl(input, getControl);
+}
+/**
+ * Type guard to check if an object is a SignalForm (form group).
+ *
+ * @template TData - Object type defining the form structure
+ * @param obj - Object to check
+ * @returns True if obj is a SignalForm
+ *
+ * @example
+ * ```typescript
+ * if (isSignalFormGroup(value)) {
+ *   console.log(value.controls.name); // TypeScript knows this is a form group
+ * }
+ * ```
+ */
+function isSignalFormGroup(obj) {
+    return (!!obj &&
+        typeof obj === 'object' &&
+        obj.kind === 'group');
+}
+/**
+ * Creates a reactive form group for managing structured form data.
+ *
+ * Builds a typed form container that holds multiple named controls, groups, or arrays.
+ * Each property in the input object becomes a control with full signal-based reactivity.
+ * Provides type-safe access to controls and tracks collective validation state.
+ *
+ * Features:
+ * - Type-safe control access via `.controls` property
+ * - Reactive value and error tracking across all controls
+ * - Collective state management (touched, dirty, valid)
+ * - Manual error/warning management at group level
+ * - Support for nested groups and arrays
+ * - Cross-field validation via getControl accessor
+ *
+ * @template TData - Object type defining the structure and types of all controls
+ *
+ * @param inputs - Object mapping property names to their control inputs
+ * @returns Fully configured SignalForm instance
+ *
+ * @example
+ * ```typescript
+ * // Simple form
+ * const form = createSignalFormGroup({
+ *   name: 'John',
+ *   age: 25
+ * });
+ *
+ * // With validators and nested structure
+ * const form = createSignalFormGroup<User>({
+ *   email: {
+ *     value: '',
+ *     validators: [signalFormValidators.required, signalFormValidators.email]
+ *   },
+ *   age: {
+ *     value: 25,
+ *     validators: [signalFormValidators.min(0)],
+ *     warnings: [signalFormValidators.max(120)]
+ *   },
+ *   address: {
+ *     street: '123 Main St',
+ *     city: 'NYC'
+ *   },
+ *   hobbies: ['coding', 'gaming']
+ * });
+ *
+ * // Access controls
+ * form.controls.email.value(); // Type-safe access
+ * form.getControl('age').setValue(30);
+ * ```
+ */
+function createSignalFormGroup(inputs) {
+    const controls = {};
+    const getControl = key => controls[key];
+    Object.entries(inputs).forEach(([key, value]) => {
+        controls[key] = createNodeFromInput$1(value, getControl);
+    });
+    const selfDirty = signal(false, ...(ngDevMode ? [{ debugName: "selfDirty" }] : []));
+    const selfTouched = signal(false, ...(ngDevMode ? [{ debugName: "selfTouched" }] : []));
+    const selfDisabled = signal(false, ...(ngDevMode ? [{ debugName: "selfDisabled" }] : []));
+    const manualErrors = signal({}, ...(ngDevMode ? [{ debugName: "manualErrors" }] : []));
+    const manualWarnings = signal({}, ...(ngDevMode ? [{ debugName: "manualWarnings" }] : []));
+    const value = computed(() => {
+        return Object.entries(controls).reduce((acc, [key, control]) => {
+            acc[key] = control.value();
+            return acc;
+        }, {});
+    }, ...(ngDevMode ? [{ debugName: "value" }] : []));
+    const errors = computed(() => {
+        const all = {};
+        Object.entries(controls).forEach(([key, control]) => {
+            if (control.kind === 'control') {
+                const map = control.errors();
+                all[key] = (hasErrors(map) ? map : undefined);
+                return;
+            }
+            const childErrors = control.errors();
+            all[key] = (isEmptyErrorTree(childErrors) ? undefined : childErrors);
+        });
+        return all;
+    }, ...(ngDevMode ? [{ debugName: "errors" }] : []));
+    const warnings = computed(() => {
+        const all = {};
+        Object.entries(controls).forEach(([key, control]) => {
+            if (control.kind === 'control') {
+                const map = control.warnings();
+                all[key] = (hasErrors(map) ? map : undefined);
+                return;
+            }
+            const childWarnings = control.warnings();
+            all[key] = (isEmptyErrorTree(childWarnings) ? undefined : childWarnings);
+        });
+        return all;
+    }, ...(ngDevMode ? [{ debugName: "warnings" }] : []));
+    const selfErrors = computed(() => {
+        if (selfDisabled())
+            return {};
+        return { ...manualErrors() };
+    }, ...(ngDevMode ? [{ debugName: "selfErrors" }] : []));
+    const selfWarnings = computed(() => {
+        if (selfDisabled())
+            return {};
+        return { ...manualWarnings() };
+    }, ...(ngDevMode ? [{ debugName: "selfWarnings" }] : []));
+    const invalid = computed(() => {
+        if (selfDisabled())
+            return false;
+        return (hasErrors(selfErrors()) ||
+            Object.values(controls).some(control => control.invalid()));
+    }, ...(ngDevMode ? [{ debugName: "invalid" }] : []));
+    const valid = computed(() => !invalid(), ...(ngDevMode ? [{ debugName: "valid" }] : []));
+    const touched = computed(() => selfTouched() ||
+        Object.values(controls).some(control => control.touched()), ...(ngDevMode ? [{ debugName: "touched" }] : []));
+    const dirty = computed(() => selfDirty() ||
+        Object.values(controls).some(control => control.dirty()), ...(ngDevMode ? [{ debugName: "dirty" }] : []));
+    const setValue = (nextValues, options) => {
+        Object.entries(nextValues).forEach(([key, nextValue]) => {
+            const control = controls[key];
+            control?.setValue(nextValue, options);
+        });
+        if (options?.markDirty ?? true)
+            selfDirty.set(true);
+        if (options?.markTouched)
+            selfTouched.set(true);
+    };
+    const reset = (nextValues) => {
+        if (nextValues) {
+            setValue(nextValues, { markDirty: false });
+        }
+        else {
+            Object.values(controls).forEach(control => control.reset());
+        }
+        selfDirty.set(false);
+        selfTouched.set(false);
+        manualErrors.set({});
+        manualWarnings.set({});
+    };
+    const setDisabled = (disabled, options) => {
+        selfDisabled.set(disabled);
+        if (!options?.onlySelf) {
+            Object.values(controls).forEach(control => control.setDisabled(disabled));
+        }
+    };
+    return {
+        kind: 'group',
+        controls,
+        value,
+        errors,
+        warnings,
+        selfErrors,
+        selfWarnings,
+        disabled: computed(() => selfDisabled()),
+        touched,
+        dirty,
+        invalid,
+        valid,
+        getControl,
+        setValue,
+        reset,
+        markTouched: () => selfTouched.set(true),
+        markUntouched: () => selfTouched.set(false),
+        markDirty: () => selfDirty.set(true),
+        markPristine: () => selfDirty.set(false),
+        markAllTouched: () => Object.values(controls).forEach(control => control.markTouched()),
+        setDisabled,
+        setError: (key, message) => manualErrors.update(current => ({ ...current, [key]: message })),
+        clearError: (key) => manualErrors.update(current => {
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            const { [key]: _removed, ...rest } = current;
+            return rest;
+        }),
+        clearErrors: () => manualErrors.set({}),
+        setWarning: (key, message) => manualWarnings.update(current => ({ ...current, [key]: message })),
+        clearWarning: (key) => manualWarnings.update(current => {
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            const { [key]: _removed, ...rest } = current;
+            return rest;
+        }),
+        clearWarnings: () => manualWarnings.set({}),
+    };
+}
+/**
+ * Helper function to create a standalone form control.
+ *
+ * Creates a control without sibling control access. Useful for creating
+ * individual controls outside of a form group context.
+ *
+ * @template TValue - The type of value the control manages
+ * @param input - Control input (raw value, config object, or existing control)
+ * @returns SignalFormControl instance
+ *
+ * @example
+ * ```typescript
+ * const nameControl = formControl('John');
+ * const ageControl = formControl({
+ *   value: 25,
+ *   validators: [signalFormValidators.min(0)]
+ * });
+ * ```
+ */
+function formControl(input) {
+    return createSignalFormControl(input, undefined);
+}
+/**
+ * Helper function to create a standalone form array.
+ *
+ * Creates an array without sibling control access. Useful for creating
+ * array controls outside of a form group context.
+ *
+ * @template TValue - The type of each item in the array
+ * @param input - Array of initial items
+ * @returns SignalFormArray instance
+ *
+ * @example
+ * ```typescript
+ * const tagsArray = formArray(['tag1', 'tag2', 'tag3']);
+ * const addressesArray = formArray<Address>([
+ *   { street: '123 Main', city: 'NYC' }
+ * ]);
+ * ```
+ */
+function formArray(input) {
+    return createSignalFormArray(input, undefined);
+}
+/**
+ * Helper function to create a form group.
+ *
+ * Alias for createSignalFormGroup. Creates a typed form with multiple controls.
+ *
+ * @template TData - Object type defining the form structure
+ * @param input - Object mapping property names to control inputs
+ * @returns SignalForm instance
+ *
+ * @example
+ * ```typescript
+ * const form = formGroup({
+ *   name: 'John',
+ *   email: {
+ *     value: 'john@example.com',
+ *     validators: [signalFormValidators.email]
+ *   }
+ * });
+ * ```
+ */
+function formGroup(input) {
+    return createSignalFormGroup(input);
+}
+/**
+ * Primary API for creating signal-based reactive forms.
+ *
+ * Alias for `formGroup`. This is the main entry point for creating forms.
+ * Provides type-safe, signal-based form state management with built-in validation.
+ *
+ * @example
+ * ```typescript
+ * // Basic form
+ * const form = signalForm({ name: 'John', age: 25 });
+ *
+ * // Complex form with validation
+ * const form = signalForm<Person>({
+ *   name: {
+ *     value: '',
+ *     validators: [signalFormValidators.required, signalFormValidators.minLength(2)]
+ *   },
+ *   age: {
+ *     value: 30,
+ *     validators: [signalFormValidators.min(0)],
+ *     warnings: [signalFormValidators.max(120)],
+ *     disabled: (ctx) => ctx.getControl('name').value() === 'admin'
+ *   },
+ *   address: {
+ *     street: '123 Main St',
+ *     city: 'NYC'
+ *   },
+ *   hobbies: ['coding', 'gaming']
+ * });
+ *
+ * // Access form state
+ * console.log(form.value()); // { name: '', age: 30, address: {...}, hobbies: [...] }
+ * console.log(form.valid()); // boolean
+ * console.log(form.controls.name.errors()); // { required: 'This field is required' }
+ * ```
+ */
+const signalForm = formGroup;
+
+/**
+ * Set of valid keys for control configuration objects.
+ * Used to distinguish config objects from plain value objects.
+ *
+ * @internal
+ */
+const CONTROL_CONFIG_KEYS = new Set([
+    'value',
+    'validators',
+    'warnings',
+    'disabled',
+]);
+/**
+ * Checks if a value is a control configuration object.
+ *
+ * Determines if the value has a 'value' property and only contains
+ * valid control config keys (value, validators, warnings, disabled).
+ *
+ * @internal
+ * @param value - Value to check
+ * @returns True if value is a control config object
+ */
+function isControlConfig(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    if (!('value' in value))
+        return false;
+    return Object.keys(value).every(key => CONTROL_CONFIG_KEYS.has(key));
+}
+/**
+ * Creates the appropriate control node from various input types.
+ *
+ * Recursively determines and creates the correct control type:
+ * - Existing controls are returned as-is
+ * - Arrays become SignalFormArray
+ * - Objects (non-config) become SignalForm (group)
+ * - Primitives/configs become SignalFormControl
+ *
+ * @internal
+ * @template TItem - The type of item to create a control for
+ * @template TControls - Object type defining available sibling controls
+ * @param input - Input value in any accepted format
+ * @param getControl - Accessor for sibling controls
+ * @returns Appropriate control type for the input
+ */
+function createNodeFromInput(input, getControl) {
+    if (isSignalFormControl(input)) {
+        return input;
+    }
+    if (isSignalFormGroup(input)) {
+        return input;
+    }
+    if (isSignalFormArray(input)) {
+        return input;
+    }
+    if (Array.isArray(input)) {
+        return createSignalFormArray(input, getControl);
+    }
+    if (typeof input === 'object' && input !== null && !isControlConfig(input)) {
+        return createSignalFormGroup(input);
+    }
+    return createSignalFormControl(input, getControl);
+}
+/**
+ * Type guard to check if an object is a SignalFormArray.
+ *
+ * @template TValue - The type of items in the array
+ * @param obj - Object to check
+ * @returns True if obj is a SignalFormArray
+ *
+ * @example
+ * ```typescript
+ * if (isSignalFormArray(value)) {
+ *   console.log(value.controls().length); // TypeScript knows this is an array
+ * }
+ * ```
+ */
+function isSignalFormArray(obj) {
+    return (!!obj &&
+        typeof obj === 'object' &&
+        obj.kind === 'array');
+}
+/**
+ * Creates a reactive form array for managing dynamic collections of controls.
+ *
+ * Builds an array container that can hold multiple controls (primitives, groups, or nested arrays)
+ * with full signal-based reactivity. Provides methods for dynamic addition/removal of items
+ * and tracks collective validation state.
+ *
+ * Features:
+ * - Dynamic array operations (push, insert, remove, clear)
+ * - Reactive value and error tracking across all items
+ * - Collective state management (touched, dirty, valid)
+ * - Manual error/warning management at array level
+ * - Type-safe access to individual controls
+ *
+ * @template TItem - The type of each item in the array
+ * @template TControls - Object type defining available sibling controls
+ *
+ * @param inputItems - Array of initial items (values, configs, or controls)
+ * @param getControl - Optional accessor for sibling controls
+ * @returns Fully configured SignalFormArray instance
+ *
+ * @example
+ * ```typescript
+ * // Array of primitives
+ * const tagsArray = createSignalFormArray(['tag1', 'tag2']);
+ * tagsArray.push('tag3');
+ *
+ * // Array of objects
+ * const addressesArray = createSignalFormArray<Address>([
+ *   { street: '123 Main', city: 'NYC' },
+ *   { street: '456 Oak', city: 'LA' }
+ * ]);
+ *
+ * // Array with validators
+ * const hobbiesArray = createSignalFormArray([
+ *   { value: 'coding', validators: [signalFormValidators.minLength(3)] },
+ *   'gaming'
+ * ]);
+ * ```
+ */
+function createSignalFormArray(inputItems, getControl) {
+    const accessControl = getControl ??
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        ((_) => {
+            throw new Error('getControl is not available for this array.');
+        });
+    const controls = signal(inputItems.map(item => createNodeFromInput(item, accessControl)), ...(ngDevMode ? [{ debugName: "controls" }] : []));
+    const selfDirty = signal(false, ...(ngDevMode ? [{ debugName: "selfDirty" }] : []));
+    const selfTouched = signal(false, ...(ngDevMode ? [{ debugName: "selfTouched" }] : []));
+    const selfDisabled = signal(false, ...(ngDevMode ? [{ debugName: "selfDisabled" }] : []));
+    const manualErrors = signal({}, ...(ngDevMode ? [{ debugName: "manualErrors" }] : []));
+    const manualWarnings = signal({}, ...(ngDevMode ? [{ debugName: "manualWarnings" }] : []));
+    const value = computed(() => controls().map(control => control.value()), ...(ngDevMode ? [{ debugName: "value" }] : []));
+    const errors = computed(() => controls().map(control => {
+        if (control.kind === 'control') {
+            const map = control.errors();
+            return hasErrors(map) ? map : undefined;
+        }
+        const childErrors = control.errors();
+        return isEmptyErrorTree(childErrors) ? undefined : childErrors;
+    }), ...(ngDevMode ? [{ debugName: "errors" }] : []));
+    const warnings = computed(() => controls().map(control => {
+        if (control.kind === 'control') {
+            const map = control.warnings();
+            return hasErrors(map) ? map : undefined;
+        }
+        const childWarnings = control.warnings();
+        return isEmptyErrorTree(childWarnings) ? undefined : childWarnings;
+    }), ...(ngDevMode ? [{ debugName: "warnings" }] : []));
+    const selfErrors = computed(() => {
+        if (selfDisabled())
+            return {};
+        return { ...manualErrors() };
+    }, ...(ngDevMode ? [{ debugName: "selfErrors" }] : []));
+    const selfWarnings = computed(() => {
+        if (selfDisabled())
+            return {};
+        return { ...manualWarnings() };
+    }, ...(ngDevMode ? [{ debugName: "selfWarnings" }] : []));
+    const invalid = computed(() => {
+        if (selfDisabled())
+            return false;
+        return (hasErrors(selfErrors()) || controls().some(control => control.invalid()));
+    }, ...(ngDevMode ? [{ debugName: "invalid" }] : []));
+    const valid = computed(() => !invalid(), ...(ngDevMode ? [{ debugName: "valid" }] : []));
+    const touched = computed(() => selfTouched() || controls().some(control => control.touched()), ...(ngDevMode ? [{ debugName: "touched" }] : []));
+    const dirty = computed(() => selfDirty() || controls().some(control => control.dirty()), ...(ngDevMode ? [{ debugName: "dirty" }] : []));
+    const insert = (item, index) => {
+        const node = createNodeFromInput(item, accessControl);
+        const position = index ?? controls().length;
+        controls.update(old => {
+            const newArray = [...old];
+            newArray.splice(position, 0, node);
+            return newArray;
+        });
+        selfDirty.set(true);
+        return position;
+    };
+    const push = (item) => insert(item);
+    const removeAt = (index) => {
+        controls.update(old => {
+            const newArray = [...old];
+            newArray.splice(index, 1);
+            return newArray;
+        });
+        selfDirty.set(true);
+    };
+    const clear = () => {
+        controls.set([]);
+        selfDirty.set(true);
+    };
+    const at = (index) => controls()[index];
+    const setValue = (nextValues, options) => {
+        controls.update(old => {
+            if (nextValues.length !== old.length) {
+                return nextValues.map(_value => createNodeFromInput(_value, accessControl));
+            }
+            old.forEach((control, index) => {
+                control.setValue(nextValues[index], options);
+            });
+            return old;
+        });
+        if (options?.markDirty ?? true)
+            selfDirty.set(true);
+        if (options?.markTouched)
+            selfTouched.set(true);
+    };
+    const reset = (nextValues) => {
+        if (nextValues) {
+            setValue(nextValues, { markDirty: false });
+        }
+        else {
+            controls().forEach(control => control.reset());
+        }
+        selfDirty.set(false);
+        selfTouched.set(false);
+        manualErrors.set({});
+        manualWarnings.set({});
+    };
+    const setDisabled = (disabled, options) => {
+        selfDisabled.set(disabled);
+        if (!options?.onlySelf) {
+            controls().forEach(control => control.setDisabled(disabled));
+        }
+    };
+    return {
+        kind: 'array',
+        controls,
+        value,
+        errors,
+        warnings,
+        selfErrors,
+        selfWarnings,
+        disabled: computed(() => selfDisabled()),
+        touched,
+        dirty,
+        invalid,
+        valid,
+        insert,
+        push,
+        removeAt,
+        clear,
+        at,
+        setValue,
+        reset,
+        markTouched: () => selfTouched.set(true),
+        markUntouched: () => selfTouched.set(false),
+        markDirty: () => selfDirty.set(true),
+        markPristine: () => selfDirty.set(false),
+        markAllTouched: () => controls().forEach(control => control.markTouched()),
+        setDisabled,
+        setError: (key, message) => manualErrors.update(current => ({ ...current, [key]: message })),
+        clearError: (key) => manualErrors.update(current => {
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            const { [key]: _removed, ...rest } = current;
+            return rest;
+        }),
+        clearErrors: () => manualErrors.set({}),
+        setWarning: (key, message) => manualWarnings.update(current => ({ ...current, [key]: message })),
+        clearWarning: (key) => manualWarnings.update(current => {
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            const { [key]: _removed, ...rest } = current;
+            return rest;
+        }),
+        clearWarnings: () => manualWarnings.set({}),
+    };
+}
+
+/**
+ * Regular expression for email validation.
+ *
+ * Aligned with Angular's built-in email validator. Validates standard email formats
+ * with proper domain and local parts.
+ *
+ * Pattern requirements:
+ * - Total length: 1-254 characters
+ * - Local part (before @): 1-64 characters
+ * - Allows alphanumeric and special characters: !#$%&'*+/=?^_`{|}~-
+ * - Domain must have valid format with optional subdomains
+ */
+const EMAIL_REGEXP = /^(?=.{1,254}$)(?=.{1,64}@)[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+)*@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/;
+/**
+ * Determines if a value is considered empty for validation purposes.
+ *
+ * Checks various types:
+ * - null/undefined: always empty
+ * - Numbers: empty when equals 0
+ * - Strings/Arrays: empty when length is 0
+ * - Sets: empty when size is 0
+ *
+ * @param value - Value to check for emptiness
+ * @returns True if the value is considered empty
+ *
+ * @example
+ * ```typescript
+ * isEmptyInputValue(null); // true
+ * isEmptyInputValue(''); // true
+ * isEmptyInputValue(0); // true
+ * isEmptyInputValue('hello'); // false
+ * ```
+ */
+function isEmptyInputValue(value) {
+    if (value === null || value === undefined)
+        return true;
+    // TODO 1: check if number==0 is empty or number.length==0 is empty
+    if (typeof value === 'number' /* or - isNumber(value) */) {
+        return value == 0;
+    }
+    if (Array.isArray(value) || typeof value === 'string') {
+        return value.length === 0;
+    }
+    if (value instanceof Set) {
+        return value.size === 0;
+    }
+    return false;
+}
+/**
+ * Type guard that checks if a value can be coerced to a valid number.
+ *
+ * Uses JavaScript's Number coercion and checks for NaN to determine
+ * if a value represents a valid numeric value.
+ *
+ * @param value - Value to check
+ * @returns True if value is or can be coerced to a number
+ *
+ * @example
+ * ```typescript
+ * isNumber(42); // true
+ * isNumber('42'); // true
+ * isNumber('hello'); // false
+ * ```
+ */
+function isNumber(value) {
+    return !Number.isNaN(Number(value));
+}
+/**
+ * Validator that requires a non-empty value.
+ *
+ * Fails when the value is null, undefined, empty string, empty array,
+ * zero (for numbers), or empty Set.
+ *
+ * @param ctx - Validation context with the value to check
+ * @returns Error object with 'required' key if validation fails, null otherwise
+ *
+ * @example
+ * ```typescript
+ * const control = signalForm({ name: { value: '', validators: [signalFormValidators.required] } });
+ * // control.controls.name.errors() => { required: 'This field is required' }
+ * ```
+ */
+const required = ({ item: { value } }) => isEmptyInputValue(value) ? { required: 'This field is required' } : null;
+/**
+ * Validator that enforces a maximum string or number length.
+ *
+ * Converts the value to string and checks if its length exceeds the specified maximum.
+ * Works with both string and number types.
+ *
+ * @param num - Maximum allowed length (inclusive)
+ * @returns Validator function
+ *
+ * @example
+ * ```typescript
+ * const control = signalForm({
+ *   username: { value: 'verylongusername', validators: [signalFormValidators.maxLength(10)] }
+ * });
+ * // control.controls.username.errors() => { maxLength: 'To long' }
+ * ```
+ */
+function maxLength(num) {
+    return ({ item: { value } }) => (typeof value == 'string' || typeof value == 'number') &&
+        value.toString().length > num
+        ? { maxLength: 'To long' }
+        : null;
+}
+/**
+ * Validator that enforces a minimum string or number length.
+ *
+ * Converts the value to string and checks if its length is less than or equal to the specified minimum.
+ * Works with both string and number types.
+ *
+ * @param num - Minimum required length (inclusive)
+ * @returns Validator function
+ *
+ * @example
+ * ```typescript
+ * const control = signalForm({
+ *   code: { value: 'ab', validators: [signalFormValidators.minLength(3)] }
+ * });
+ * // control.controls.code.errors() => { minLength: 'To short' }
+ * ```
+ */
+function minLength(num) {
+    return ({ item: { value } }) => (typeof value == 'string' || typeof value == 'number') &&
+        value.toString().length <= num
+        ? { minLength: 'To short' }
+        : null;
+}
+/**
+ * Validator that enforces a minimum numeric value.
+ *
+ * Checks if a numeric value is less than or equal to the specified minimum.
+ * Value is coerced to a number for comparison.
+ *
+ * @param num - Minimum allowed value (exclusive - value must be greater than this)
+ * @returns Validator function
+ *
+ * @example
+ * ```typescript
+ * const control = signalForm({
+ *   age: { value: -5, validators: [signalFormValidators.min(0)] }
+ * });
+ * // control.controls.age.errors() => { minLength: 'To small' }
+ * ```
+ */
+function min(num) {
+    return ({ item: { value } }) => isNumber(value) && value <= num ? { minLength: 'To small' } : null;
+}
+/**
+ * Validator that enforces a maximum numeric value.
+ *
+ * Checks if a numeric value exceeds the specified maximum.
+ * Value is coerced to a number for comparison.
+ *
+ * @param num - Maximum allowed value (inclusive)
+ * @returns Validator function
+ *
+ * @example
+ * ```typescript
+ * const control = signalForm({
+ *   age: { value: 150, validators: [signalFormValidators.max(120)] }
+ * });
+ * // control.controls.age.errors() => { minLength: 'To big' }
+ * ```
+ */
+function max(num) {
+    return ({ item: { value } }) => isNumber(value) && value > num ? { minLength: 'To big' } : null;
+}
+/**
+ * Validator that checks if a value is a valid email address.
+ *
+ * Uses Angular-compatible email regex pattern to validate email format.
+ * Skips validation for empty values (use with `required` if needed).
+ *
+ * @param ctx - Validation context with the email value to check
+ * @returns Error object with 'email' key if validation fails, null otherwise
+ *
+ * @example
+ * ```typescript
+ * const control = signalForm({
+ *   email: { value: 'invalid-email', validators: [signalFormValidators.email] }
+ * });
+ * // control.controls.email.errors() => { email: 'Invalid email' }
+ * ```
+ */
+const email = ({ item: { value } }) => {
+    if (isEmptyInputValue(value))
+        return null;
+    return EMAIL_REGEXP.test(String(value)) ? null : { email: 'Invalid email' };
+};
+/**
+ * Validator that checks if a value matches a specified regular expression pattern.
+ *
+ * Accepts either a RegExp object or a string pattern. String patterns are automatically
+ * wrapped with ^ and $ anchors to match the entire value.
+ *
+ * Skips validation for empty values (use with `required` if needed).
+ *
+ * @param valuePattern - Regular expression or pattern string to match against
+ * @returns Validator function
+ *
+ * @example
+ * ```typescript
+ * // Using regex
+ * const control1 = signalForm({
+ *   code: { value: 'abc', validators: [signalFormValidators.pattern(/^[0-9]+$/)] }
+ * });
+ * // control1.controls.code.errors() => { pattern: 'RequiredPattern: ^[0-9]+$, ActualValue: abc' }
+ *
+ * // Using string pattern
+ * const control2 = signalForm({
+ *   zipCode: { value: 'ABC', validators: [signalFormValidators.pattern('[0-9]{5}')] }
+ * });
+ * ```
+ */
+function pattern(valuePattern) {
+    if (!valuePattern)
+        return () => null;
+    let regex;
+    let regexStr;
+    if (typeof valuePattern === 'string') {
+        regexStr = '';
+        if (valuePattern.charAt(0) !== '^')
+            regexStr += '^';
+        regexStr += valuePattern;
+        if (valuePattern.charAt(valuePattern.length - 1) !== '$')
+            regexStr += '$';
+        regex = new RegExp(regexStr);
+    }
+    else {
+        regexStr = valuePattern.toString();
+        regex = valuePattern;
+    }
+    return ({ item: { value } }) => {
+        if (isEmptyInputValue(value))
+            return null;
+        const valueStr = String(value);
+        return regex.test(valueStr)
+            ? null
+            : {
+                pattern: `RequiredPattern: ${regexStr}, ActualValue: ${valueStr}`,
+            };
+    };
+}
+/**
+ * Collection of built-in validators for signal-form controls.
+ *
+ * Provides common validation functions that can be used in the `validators` or `warnings`
+ * arrays of form controls. All validators skip empty values except `required`.
+ *
+ * @property required - Ensures the value is not empty (null, undefined, '', [], 0, empty Set)
+ * @property maxLength - Ensures string/number length doesn't exceed maximum
+ * @property minLength - Ensures string/number length meets minimum requirement
+ * @property min - Ensures numeric value is greater than minimum (exclusive)
+ * @property max - Ensures numeric value doesn't exceed maximum (inclusive)
+ * @property email - Validates email address format using Angular-compatible regex
+ * @property pattern - Validates value matches a regular expression pattern
+ *
+ * @example
+ * ```typescript
+ * const form = signalForm({
+ *   email: {
+ *     value: '',
+ *     validators: [signalFormValidators.required, signalFormValidators.email]
+ *   },
+ *   age: {
+ *     value: 25,
+ *     validators: [signalFormValidators.min(0), signalFormValidators.max(120)],
+ *     warnings: [signalFormValidators.max(100)] // Warning but doesn't invalidate
+ *   },
+ *   username: {
+ *     value: '',
+ *     validators: [
+ *       signalFormValidators.required,
+ *       signalFormValidators.minLength(3),
+ *       signalFormValidators.maxLength(20),
+ *       signalFormValidators.pattern(/^[a-zA-Z0-9_]+$/)
+ *     ]
+ *   }
+ * });
+ * ```
+ */
+const signalFormValidators = {
+    required,
+    maxLength,
+    minLength,
+    min,
+    max,
+    email,
+    pattern,
+};
+
+/**
+ * Example demonstrating the usage of signal-based reactive forms.
+ *
+ * Shows various features including:
+ * - Simple value initialization
+ * - Validators that mark controls as invalid
+ * - Warnings that don't affect validity
+ * - Dynamic disabled state based on other controls
+ * - Nested objects and arrays
+ * - Type-safe control access
+ *
+ * This function is exported as an example and reference implementation.
+ * It's not meant to be called in production code.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage pattern from the example
+ * const form = signalForm<Person>({
+ *   name: 'dvirus',
+ *   age: {
+ *     value: 130,
+ *     validators: [signalFormValidators.required, signalFormValidators.min(0)],
+ *     warnings: [signalFormValidators.max(120)],
+ *     disabled: (ctx) => ctx.getControl('name').value() === 'admin'
+ *   },
+ *   address: {
+ *     street: { value: '123 Main St', validators: [signalFormValidators.required] }
+ *   },
+ *   hobbies: [
+ *     { value: 'coding', validators: [signalFormValidators.minLength(3)] },
+ *     'programming'
+ *   ]
+ * });
+ *
+ * // Access form state
+ * form.getControl('address').value(); // { street: '123 Main St' }
+ * form.controls.hobbies.controls()[0].errors(); // {}
+ * form.controls.age.firstErrorOrWarning(); // { name: 'max', message: 'To big', type: 'warning' }
+ * ```
+ */
+// function main() {
+//   type Person = {
+//     name: string;
+//     age: number;
+//     address: {
+//       street: string;
+//       city: string;
+//     };
+//     hobbies: string[];
+//   };
+//   /**
+//    * Example 1: Simple form with direct value initialization.
+//    *
+//    * Creates a form from a plain object. Each property becomes
+//    * a control with the provided value.
+//    */
+//   const model1: Person = {
+//     name: 'dvirus',
+//     age: 30,
+//     address: {
+//       street: '123 Main St',
+//       city: 'Any-town',
+//     },
+//     hobbies: ['coding', 'gaming'],
+//   };
+//   const form1 = signalForm(model1);
+//   /**
+//    * Example 2: Advanced form with validators, warnings, and dynamic disabled state.
+//    *
+//    * Demonstrates:
+//    * - Simple value for name field
+//    * - Age control with validators (required, min) and warnings (max)
+//    * - Dynamic disabled logic based on name value
+//    * - Nested address object with validated street field
+//    * - Array of hobbies with mixed control configs and simple values
+//    */
+//   const form2 = signalForm<Person>({
+//     name: 'dvirus',
+//     age: {
+//       // initial value
+//       value: 130,
+//       // example of validators, they add error messages and mark the control as invalid if the validation fails
+//       validators: [signalFormValidators.required, signalFormValidators.min(0)],
+//       // warning are like validators but they don't make the control invalid, just add a warning message
+//       warnings: [signalFormValidators.max(120)],
+//       // example of dynamic disabling based on another control's value
+//       disabled: (ctx) => ctx.getControl('name').value() === 'admin',
+//     },
+//     address: {
+//       street: {
+//         value: '123 Main St',
+//         validators: [signalFormValidators.required],
+//         disabled: false,
+//       },
+//     },
+//     hobbies: [
+//       {
+//         value: 'coding',
+//         validators: [signalFormValidators.minLength(3)],
+//         disabled: computed(() => false),
+//       },
+//       'programming',
+//       'Typing',
+//     ],
+//   });
+//   // Example outputs demonstrating form access patterns
+//   console.log(form2.getControl('address').value()); // { street: '123 Main St' }
+//   console.log(form2.controls.hobbies.controls()[0].errors()); // {}
+//   console.log(form2.controls.age.firstErrorOrWarning()); // {name: 'minLength', message: 'To big', type: 'warning'}
+//   console.log(form2.controls.age.warnings()); // { minLength: 'To big' }
+// }
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { createSignalFormArray, createSignalFormControl, createSignalFormGroup, formArray, formControl, formGroup, isSignalFormArray, isSignalFormControl, isSignalFormGroup, signalForm, signalFormValidators };
+//# sourceMappingURL=dvirus-js-angular-signals-signal-form.mjs.map