@dvirus-js/angular-signals 0.0.16 → 0.0.18

package/types/dvirus-js-angular-signals-signal-form.d.ts

@@ -0,0 +1,1000 @@
+import { Signal, WritableSignal } from '@angular/core';
+import { SignalOrValue } from '@dvirus-js/angular-signals';
+
+/**
+ * Recursively extracts the value type from a form structure.
+ *
+ * Converts form control types to their underlying value types:
+ * - Arrays become arrays of extracted values
+ * - Objects become objects with extracted property values
+ * - Primitives become `T | undefined`
+ *
+ * @template T - The form structure type to extract values from
+ *
+ * @example
+ * ```typescript
+ * type Person = { name: string; age: number };
+ * type PersonValue = SignalFormValueFor<Person>;
+ * // Result: { name: string | undefined; age: number | undefined }
+ * ```
+ */
+type SignalFormValueFor<T> = T extends (infer U)[] ? SignalFormValueFor<U>[] : T extends object ? {
+    [Key in keyof T]: SignalFormValueFor<T[Key]>;
+} : T | undefined;
+/**
+ * Recursively defines the error structure for a form.
+ *
+ * Mirrors the form structure where:
+ * - Arrays become arrays of error structures
+ * - Objects become objects with error properties
+ * - Primitives become error maps (Record<string, string>) or undefined
+ *
+ * @template T - The form structure type to create error structure for
+ *
+ * @example
+ * ```typescript
+ * type Person = { name: string; hobbies: string[] };
+ * type PersonErrors = SignalFormErrorFor<Person>;
+ * // Result: { name: Record<string, string> | undefined; hobbies: (Record<string, string> | undefined)[] }
+ * ```
+ */
+type SignalFormErrorFor<T> = T extends (infer U)[] ? SignalFormErrorFor<U>[] : T extends object ? {
+    [Key in keyof T]: SignalFormErrorFor<T[Key]>;
+} : Record<string, string> | undefined;
+/**
+ * Represents the first error or warning found in a control.
+ *
+ * @template Type - Either 'error' or 'warning' to distinguish validation type
+ *
+ * @property name - The validator name that triggered this error/warning
+ * @property message - The human-readable error/warning message
+ * @property type - Whether this is an 'error' or 'warning'
+ *
+ * @example
+ * ```typescript
+ * const firstError: FirstError<'error'> = {
+ *   name: 'required',
+ *   message: 'This field is required',
+ *   type: 'error'
+ * };
+ * ```
+ */
+type FirstError<Type extends 'warning' | 'error'> = {
+    name: string;
+    message: string;
+    type: Type;
+} | undefined;
+/**
+ * Represents a single form control (primitive value) with validation and state management.
+ *
+ * A control wraps a primitive value (string, number, etc.) and provides:
+ * - Reactive value through Angular signals
+ * - Validation with errors and warnings
+ * - State tracking (touched, dirty, disabled)
+ * - Manual error/warning management
+ *
+ * @template TValue - The type of value this control manages
+ */
+interface SignalFormControl<TValue> {
+    /** Discriminator property set to 'control' for type checking */
+    kind: 'control';
+    /** Writable signal containing the current control value */
+    value: WritableSignal<TValue | undefined>;
+    /** Signal indicating if the control is disabled */
+    disabled: Signal<boolean>;
+    /** Signal indicating if the control has been interacted with */
+    touched: Signal<boolean>;
+    /** Signal indicating if the value has changed from initial */
+    dirty: Signal<boolean>;
+    /** Signal containing all validation errors (from validators + manual) */
+    errors: Signal<Record<string, string>>;
+    /** Signal containing all validation warnings (from warnings + manual) */
+    warnings: Signal<Record<string, string>>;
+    /** Signal containing only manually set errors */
+    selfErrors: Signal<Record<string, string>>;
+    /** Signal containing only manually set warnings */
+    selfWarnings: Signal<Record<string, string>>;
+    /** Signal true when control has errors and is not disabled */
+    invalid: Signal<boolean>;
+    /** Signal true when control has no errors */
+    valid: Signal<boolean>;
+    /** Signal with the first error, if any */
+    firstError: Signal<FirstError<'error'>>;
+    /** Signal with the first warning, if any */
+    firstWarning: Signal<FirstError<'warning'>>;
+    /** Signal with the first error or warning */
+    firstErrorOrWarning: Signal<FirstError<'error' | 'warning'>>;
+    /**
+     * Updates the control value with optional state flags.
+     * @param value - New value to set
+     * @param options - Optional flags for marking dirty/touched
+     */
+    setValue: (value: TValue | undefined, options?: SignalFormSetValueOptions) => void;
+    /**
+     * Resets control to initial value and clears all state.
+     * @param value - Optional new initial value
+     */
+    reset: (value?: TValue | undefined) => void;
+    /** Marks the control as touched */
+    markTouched: () => void;
+    /** Marks the control as not touched */
+    markUntouched: () => void;
+    /** Marks the control as dirty (modified) */
+    markDirty: () => void;
+    /** Marks the control as pristine (unmodified) */
+    markPristine: () => void;
+    /**
+     * Sets the disabled state of the control.
+     * @param disabled - True to disable, false to enable
+     */
+    setDisabled: (disabled: boolean) => void;
+    /**
+     * Adds a manual error with key and message.
+     * @param key - Error identifier key
+     * @param message - Error message
+     */
+    setError: (key: string, message: string) => void;
+    /**
+     * Removes a specific manual error by key.
+     * @param key - Error identifier key to remove
+     */
+    clearError: (key: string) => void;
+    /** Removes all manual errors */
+    clearErrors: () => void;
+    /**
+     * Adds a manual warning with key and message.
+     * @param key - Warning identifier key
+     * @param message - Warning message
+     */
+    setWarning: (key: string, message: string) => void;
+    /**
+     * Removes a specific manual warning by key.
+     * @param key - Warning identifier key to remove
+     */
+    clearWarning: (key: string) => void;
+    /** Removes all manual warnings */
+    clearWarnings: () => void;
+}
+/**
+ * Represents a form array - a collection of form controls/groups with dynamic add/remove capabilities.
+ *
+ * Manages an array of controls where each item can be a control, group, or nested array.
+ * Provides methods for array manipulation (push, insert, remove) and tracks collective state.
+ *
+ * @template TValue - The type of each item in the array
+ */
+interface SignalFormArray<TValue> {
+    /** Discriminator property set to 'array' for type checking */
+    kind: 'array';
+    /** Signal containing the array of child controls */
+    controls: Signal<SignalFormControlLike<TValue>[]>;
+    /** Signal containing array of extracted values from all controls */
+    value: Signal<SignalFormValueFor<TValue>[]>;
+    /** Signal containing array of error structures from all controls */
+    errors: Signal<SignalFormErrorFor<TValue>[]>;
+    /** Signal containing array of warning structures from all controls */
+    warnings: Signal<SignalFormErrorFor<TValue>[]>;
+    /** Signal containing manually set errors on the array itself */
+    selfErrors: Signal<Record<string, string>>;
+    /** Signal containing manually set warnings on the array itself */
+    selfWarnings: Signal<Record<string, string>>;
+    /** Signal indicating if the array is disabled */
+    disabled: Signal<boolean>;
+    /** Signal true when array or any child is touched */
+    touched: Signal<boolean>;
+    /** Signal true when array or any child is dirty */
+    dirty: Signal<boolean>;
+    /** Signal true when array or any child has errors */
+    invalid: Signal<boolean>;
+    /** Signal true when array and all children have no errors */
+    valid: Signal<boolean>;
+    /**
+     * Inserts a control at specified index (defaults to end).
+     * @param item - Item to insert (value, config, or control)
+     * @param index - Position to insert at (optional, defaults to end)
+     * @returns Index where item was inserted
+     */
+    insert: (item: SignalFormInput<TValue, any> | SignalFormValueFor<TValue>, index?: number) => number;
+    /**
+     * Appends a control to the end of the array.
+     * @param item - Item to append (value, config, or control)
+     * @returns Index where item was inserted
+     */
+    push: (item: SignalFormInput<TValue, any> | SignalFormValueFor<TValue>) => number;
+    /**
+     * Removes the control at specified index.
+     * @param index - Index of control to remove
+     */
+    removeAt: (index: number) => void;
+    /** Removes all controls from the array */
+    clear: () => void;
+    /**
+     * Retrieves the control at specified index.
+     * @param index - Index of control to retrieve
+     * @returns Control at index, or undefined if out of bounds
+     */
+    at: (index: number) => SignalFormControlLike<TValue> | undefined;
+    /**
+     * Sets values for all controls (recreates if length differs).
+     * @param value - Array of new values
+     * @param options - Optional flags for marking dirty/touched
+     */
+    setValue: (value: SignalFormValueFor<TValue>[], options?: SignalFormSetValueOptions) => void;
+    /**
+     * Resets all controls to initial state or provided values.
+     * @param value - Optional new initial values
+     */
+    reset: (value?: SignalFormValueFor<TValue>[]) => void;
+    /** Marks the array itself as touched */
+    markTouched: () => void;
+    /** Marks the array itself as untouched */
+    markUntouched: () => void;
+    /** Marks the array itself as dirty */
+    markDirty: () => void;
+    /** Marks the array itself as pristine */
+    markPristine: () => void;
+    /** Marks the array and all children as touched */
+    markAllTouched: () => void;
+    /**
+     * Sets disabled state for array and optionally children.
+     * @param disabled - True to disable, false to enable
+     * @param options - Options to control if children are affected
+     */
+    setDisabled: (disabled: boolean, options?: SignalFormDisableOptions) => void;
+    /**
+     * Adds a manual error to the array.
+     * @param key - Error identifier key
+     * @param message - Error message
+     */
+    setError: (key: string, message: string) => void;
+    /**
+     * Removes a specific manual error.
+     * @param key - Error identifier key to remove
+     */
+    clearError: (key: string) => void;
+    /** Removes all manual errors */
+    clearErrors: () => void;
+    /**
+     * Adds a manual warning to the array.
+     * @param key - Warning identifier key
+     * @param message - Warning message
+     */
+    setWarning: (key: string, message: string) => void;
+    /**
+     * Removes a specific manual warning.
+     * @param key - Warning identifier key to remove
+     */
+    clearWarning: (key: string) => void;
+    /** Removes all manual warnings */
+    clearWarnings: () => void;
+}
+/**
+ * Represents a form group - a structured collection of named form controls.
+ *
+ * Manages an object/record of controls where each property is a control, group, or array.
+ * Provides type-safe access to controls and tracks collective validation state.
+ *
+ * @template TData - The object type defining the structure and types of all controls
+ */
+interface SignalForm<TData extends object> {
+    /** Discriminator property set to 'group' for type checking */
+    kind: 'group';
+    /** Object containing all named child controls */
+    controls: {
+        [Key in keyof TData]: SignalFormControlLike<TData[Key]>;
+    };
+    /** Signal containing object with extracted values from all controls */
+    value: Signal<{
+        [Key in keyof TData]: SignalFormValueFor<TData[Key]>;
+    }>;
+    /** Signal containing object with error structures from all controls */
+    errors: Signal<{
+        [Key in keyof TData]: SignalFormErrorFor<TData[Key]>;
+    }>;
+    /** Signal containing object with warning structures from all controls */
+    warnings: Signal<{
+        [Key in keyof TData]: SignalFormErrorFor<TData[Key]>;
+    }>;
+    /** Signal containing manually set errors on the group itself */
+    selfErrors: Signal<Record<string, string>>;
+    /** Signal containing manually set warnings on the group itself */
+    selfWarnings: Signal<Record<string, string>>;
+    /** Signal indicating if the group is disabled */
+    disabled: Signal<boolean>;
+    /** Signal true when group or any child is touched */
+    touched: Signal<boolean>;
+    /** Signal true when group or any child is dirty */
+    dirty: Signal<boolean>;
+    /** Signal true when group or any child has errors */
+    invalid: Signal<boolean>;
+    /** Signal true when group and all children have no errors */
+    valid: Signal<boolean>;
+    /**
+     * Type-safe method to retrieve a specific control by key.
+     * @param key - Control property name
+     * @returns The control for the specified key
+     */
+    getControl: <Key extends keyof TData>(key: Key) => SignalFormControlLike<TData[Key]>;
+    /**
+     * Updates values for specified controls (partial updates supported).
+     * @param value - Partial object with new values
+     * @param options - Optional flags for marking dirty/touched
+     */
+    setValue: (value: Partial<{
+        [Key in keyof TData]: SignalFormValueFor<TData[Key]>;
+    }>, options?: SignalFormSetValueOptions) => void;
+    /**
+     * Resets all controls to initial state or provided values.
+     * @param value - Optional partial object with new initial values
+     */
+    reset: (value?: Partial<{
+        [Key in keyof TData]: SignalFormValueFor<TData[Key]>;
+    }>) => void;
+    /** Marks the group itself as touched */
+    markTouched: () => void;
+    /** Marks the group itself as untouched */
+    markUntouched: () => void;
+    /** Marks the group itself as dirty */
+    markDirty: () => void;
+    /** Marks the group itself as pristine */
+    markPristine: () => void;
+    /** Marks the group and all children as touched */
+    markAllTouched: () => void;
+    /**
+     * Sets disabled state for group and optionally children.
+     * @param disabled - True to disable, false to enable
+     * @param options - Options to control if children are affected
+     */
+    setDisabled: (disabled: boolean, options?: SignalFormDisableOptions) => void;
+    /**
+     * Adds a manual error to the group.
+     * @param key - Error identifier key
+     * @param message - Error message
+     */
+    setError: (key: string, message: string) => void;
+    /**
+     * Removes a specific manual error.
+     * @param key - Error identifier key to remove
+     */
+    clearError: (key: string) => void;
+    /** Removes all manual errors */
+    clearErrors: () => void;
+    /**
+     * Adds a manual warning to the group.
+     * @param key - Warning identifier key
+     * @param message - Warning message
+     */
+    setWarning: (key: string, message: string) => void;
+    /**
+     * Removes a specific manual warning.
+     * @param key - Warning identifier key to remove
+     */
+    clearWarning: (key: string) => void;
+    /** Removes all manual warnings */
+    clearWarnings: () => void;
+}
+/**
+ * Type utility that maps a value type to its appropriate control interface.
+ *
+ * Automatically determines the correct control type based on the value:
+ * - Arrays → SignalFormArray
+ * - Objects → SignalForm (group)
+ * - Primitives → SignalFormControl
+ *
+ * @template TValue - The value type to map to a control interface
+ *
+ * @example
+ * ```typescript
+ * type StringControl = SignalFormControlLike<string>; // SignalFormControl<string>
+ * type PersonControl = SignalFormControlLike<Person>; // SignalForm<Person>
+ * type HobbiesControl = SignalFormControlLike<string[]>; // SignalFormArray<string>
+ * ```
+ */
+type SignalFormControlLike<TValue> = TValue extends (infer U)[] ? SignalFormArray<U> : TValue extends object ? SignalForm<TValue> : SignalFormControl<TValue>;
+/**
+ * Context object passed to validators and disabled functions.
+ *
+ * Provides access to the current control's value and sibling controls,
+ * enabling cross-field validation and dynamic behavior based on other form values.
+ *
+ * @template TControls - Object type defining all available sibling controls
+ * @template TValue - The type of the current control's value
+ *
+ * @example
+ * ```typescript
+ * const validator: SignalFormValidatorFn<FormModel, string> = (ctx) => {
+ *   const otherControl = ctx.getControl('otherField');
+ *   return ctx.item.value === otherControl.value() ? null : { mismatch: 'Values must match' };
+ * };
+ * ```
+ */
+interface SignalFormContext<TControls extends object, TValue> {
+    /** Object containing the current control's value */
+    item: {
+        value: TValue | undefined;
+    };
+    /**
+     * Function to retrieve sibling controls by key for cross-field logic.
+     * @param controlName - Key of the sibling control to retrieve
+     * @returns The sibling control
+     */
+    getControl: <ControlKey extends keyof TControls>(controlName: ControlKey) => SignalFormControlLike<TControls[ControlKey]>;
+}
+/**
+ * Return type for validation functions.
+ *
+ * Validators return a map of error keys to messages when validation fails,
+ * or null/empty when validation passes. Empty strings and null values are ignored.
+ *
+ * @example
+ * ```typescript
+ * const result: SignalFormValidationError = { required: 'Field is required', min: 'Too small' };
+ * const success: SignalFormValidationError = null;
+ * ```
+ */
+type SignalFormValidationError = Record<string, string | undefined | null> | null;
+/**
+ * Function signature for validators and warnings.
+ *
+ * Takes a context with the current value and sibling controls,
+ * returns error/warning messages or null when validation passes.
+ *
+ * @template TControls - Object type defining available sibling controls
+ * @template TValue - The type of value being validated
+ *
+ * @param ctx - Validation context with current value and control accessor
+ * @returns Error map when validation fails, null when it passes
+ *
+ * @example
+ * ```typescript
+ * const minValidator: SignalFormValidatorFn<any, number> = ({ item }) => {
+ *   return item.value && item.value < 0 ? { min: 'Must be positive' } : null;
+ * };
+ * ```
+ */
+type SignalFormValidatorFn<TControls extends object, TValue> = (ctx: SignalFormContext<TControls, TValue>) => SignalFormValidationError;
+/**
+ * Configuration object for creating a form control with advanced options.
+ *
+ * Allows specifying initial value, validators, warnings, and dynamic disabled logic.
+ *
+ * @template TValue - The type of value the control will manage
+ * @template TControls - Object type defining available sibling controls for validators
+ *
+ * @example
+ * ```typescript
+ * const config: SignalFormControlConfig<number, FormModel> = {
+ *   value: 0,
+ *   validators: [signalFormValidators.min(0)],
+ *   warnings: [signalFormValidators.max(100)],
+ *   disabled: (ctx) => ctx.getControl('otherField').value() === 'locked'
+ * };
+ * ```
+ */
+interface SignalFormControlConfig<TValue, TControls extends object> {
+    /** Initial value (can be a signal or static value) */
+    value: SignalOrValue<TValue | undefined>;
+    /** Disabled state (boolean, signal, or function based on form context) */
+    disabled?: SignalOrValue<boolean> | SignalFormDisabledFn<TControls, TValue>;
+    /** Array of validation functions that mark control as invalid */
+    validators?: SignalFormValidatorFn<TControls, TValue>[];
+    /** Array of validation functions that don't affect validity */
+    warnings?: SignalFormValidatorFn<TControls, TValue>[];
+}
+/**
+ * Input type accepted when creating a form control.
+ *
+ * Flexible input that accepts:
+ * - A raw value (primitive, signal)
+ * - A configuration object with validators and options
+ * - An existing SignalFormControl instance
+ *
+ * @template TValue - The value type for the control
+ * @template TControls - Object type defining available sibling controls
+ */
+type SignalFormControlInput<TValue, TControls extends object> = SignalOrValue<TValue | undefined> | SignalFormControlConfig<TValue, TControls> | SignalFormControl<TValue>;
+/**
+ * Input type accepted when creating a form group.
+ *
+ * @template TData - Object type defining the structure of the group
+ */
+type SignalFormGroupInput<TData extends object> = SignalFormInputs<TData> | SignalForm<TData>;
+/**
+ * Input type accepted when creating a form array.
+ *
+ * @template TItem - The type of each item in the array
+ * @template TControls - Object type defining available sibling controls
+ */
+type SignalFormArrayInput<TItem, TControls extends object> = SignalFormArray<TItem> | SignalFormInput<TItem, TControls>[];
+/**
+ * Recursive input type that automatically maps to the correct control input type.
+ *
+ * Determines the appropriate input type based on value structure:
+ * - Arrays → SignalFormArrayInput
+ * - Objects → SignalFormGroupInput
+ * - Primitives → SignalFormControlInput
+ *
+ * @template TValue - The value type to create an input for
+ * @template TControls - Object type defining available sibling controls
+ */
+type SignalFormInput<TValue, TControls extends object> = TValue extends (infer U)[] ? SignalFormArrayInput<U, TControls> : TValue extends object ? SignalFormGroupInput<TValue> : SignalFormControlInput<TValue, TControls>;
+/**
+ * Type for defining the inputs of a form group.
+ *
+ * Maps each property of TData to its appropriate input type,
+ * all properties are optional to allow partial form definitions.
+ *
+ * @template TData - Object type defining the structure of the form
+ */
+type SignalFormInputs<TData extends object> = {
+    [Key in keyof TData]?: SignalFormInput<TData[Key], TData>;
+};
+/**
+ * Function signature for dynamic disabled logic.
+ *
+ * Determines if a control should be disabled based on form context.
+ *
+ * @template TControls - Object type defining available sibling controls
+ * @template TValue - The type of value in the control
+ *
+ * @param ctx - Context with current value and sibling controls
+ * @returns Boolean indicating if control should be disabled
+ */
+type SignalFormDisabledFn<TControls extends object, TValue> = (ctx: SignalFormContext<TControls, TValue>) => boolean;
+/**
+ * Options for setValue operations.
+ */
+interface SignalFormSetValueOptions {
+    /** Whether to mark the control as dirty (default: true) */
+    markDirty?: boolean;
+    /** Whether to mark the control as touched (default: false) */
+    markTouched?: boolean;
+}
+/**
+ * Options for setDisabled operations.
+ */
+interface SignalFormDisableOptions {
+    /** If true, only disable this control without affecting children (default: false) */
+    onlySelf?: boolean;
+}
+
+/**
+ * Internal type for accessing sibling controls in a form.
+ *
+ * @internal
+ */
+type ControlAccessor$1<TControls extends object> = <Key extends keyof TControls>(controlName: Key) => SignalFormControlLike<TControls[Key]>;
+/**
+ * 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
+ * }
+ * ```
+ */
+declare function isSignalFormArray<TValue>(obj: unknown): obj is SignalFormArray<TValue>;
+/**
+ * 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'
+ * ]);
+ * ```
+ */
+declare function createSignalFormArray<TItem, TControls extends object = object>(inputItems: SignalFormInput<TItem, TControls>[], getControl?: ControlAccessor$1<TControls>): SignalFormArray<TItem>;
+
+/**
+ * Internal type for accessing sibling controls in a form.
+ *
+ * @internal
+ */
+type ControlAccessor<TControls extends object> = <Key extends keyof TControls>(controlName: Key) => SignalFormControlLike<TControls[Key]>;
+/**
+ * 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
+ * }
+ * ```
+ */
+declare function isSignalFormControl<TValue>(obj: unknown): obj is SignalFormControl<TValue>;
+/**
+ * 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'
+ * });
+ * ```
+ */
+declare function createSignalFormControl<TControls extends object, TValue>(input: SignalFormControlInput<TValue, TControls>, getControl?: ControlAccessor<TControls>): SignalFormControl<TValue>;
+
+/**
+ * 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
+ * }
+ * ```
+ */
+declare function isSignalFormGroup<TData extends object>(obj: unknown): obj is SignalForm<TData>;
+/**
+ * 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);
+ * ```
+ */
+declare function createSignalFormGroup<TData extends object>(inputs: SignalFormInputs<TData>): SignalForm<TData>;
+/**
+ * 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)]
+ * });
+ * ```
+ */
+declare function formControl<TValue>(input: SignalFormControlInput<TValue, object>): SignalFormControl<TValue>;
+/**
+ * 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' }
+ * ]);
+ * ```
+ */
+declare function formArray<TValue>(input: SignalFormInput<TValue, object>[]): SignalFormArray<TValue>;
+/**
+ * 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]
+ *   }
+ * });
+ * ```
+ */
+declare function formGroup<TData extends object>(input: SignalFormInputs<TData>): SignalForm<TData>;
+/**
+ * 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' }
+ * ```
+ */
+declare const signalForm: typeof formGroup;
+
+type ValidatorFn = SignalFormValidatorFn<any, any>;
+/**
+ * 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' }
+ * ```
+ */
+declare function maxLength(num: number): ValidatorFn;
+/**
+ * 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' }
+ * ```
+ */
+declare function minLength(num: number): ValidatorFn;
+/**
+ * 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' }
+ * ```
+ */
+declare function min(num: number): ValidatorFn;
+/**
+ * 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' }
+ * ```
+ */
+declare function max(num: number): ValidatorFn;
+/**
+ * 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}')] }
+ * });
+ * ```
+ */
+declare function pattern(valuePattern: string | RegExp): ValidatorFn;
+/**
+ * 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_]+$/)
+ *     ]
+ *   }
+ * });
+ * ```
+ */
+declare const signalFormValidators: {
+    required: ValidatorFn;
+    maxLength: typeof maxLength;
+    minLength: typeof minLength;
+    min: typeof min;
+    max: typeof max;
+    email: ValidatorFn;
+    pattern: typeof pattern;
+};
+
+export { createSignalFormArray, createSignalFormControl, createSignalFormGroup, formArray, formControl, formGroup, isSignalFormArray, isSignalFormControl, isSignalFormGroup, signalForm, signalFormValidators };
+export type { FirstError, SignalForm, SignalFormArray, SignalFormArrayInput, SignalFormContext, SignalFormControl, SignalFormControlConfig, SignalFormControlInput, SignalFormControlLike, SignalFormDisableOptions, SignalFormDisabledFn, SignalFormErrorFor, SignalFormGroupInput, SignalFormInput, SignalFormInputs, SignalFormSetValueOptions, SignalFormValidationError, SignalFormValidatorFn, SignalFormValueFor };