signal-template-forms
Version:
A powerful, type-safe Angular forms library built with signals, providing reactive form management with excellent developer experience and performance.
139 lines (138 loc) • 6.06 kB
TypeScript
import { type ArrayFormBuilderArgs, type ArrayFormContainer, type FormBuilderArgs, type SignalFormContainer, type SignalSteppedFormContainer, type SteppedFormBuilderArgs } from '../../models/signal-form.model';
/**
* SignalFormBuilder - Main factory class for creating Signal Forms
*
* Provides static methods to create different types of forms:
* - Single forms with standard fields
* - Stepped/wizard forms with multiple pages
* - Array forms for managing collections of items
*
* Features:
* - Type-safe form creation with TypeScript generics
* - Automatic field binding and validation setup
* - Reactive computed properties for form state
* - Built-in save/reset functionality
* - Parent-child form relationships
*
* @example
* ```typescript
* const userForm = SignalFormBuilder.createForm({
* model: { name: '', email: '' },
* fields: [
* { name: 'name', type: FormFieldType.TEXT, label: 'Name' },
* { name: 'email', type: FormFieldType.TEXT, label: 'Email' }
* ],
* onSave: (data) => console.log('Saved:', data)
* });
* ```
*/
export declare class SignalFormBuilder {
/**
* Creates a standard single-page form with specified fields
*
* Builds a complete form container with reactive state management,
* validation, and save functionality. The form automatically binds
* to the provided model and creates appropriate field components.
*
* @template TModel - The TypeScript type of the form data model
* @param args - Configuration object for the form
* @param args.model - Initial data model for the form
* @param args.fields - Array of field configurations
* @param args.title - Optional form title
* @param args.config - Layout and behavior configuration
* @param args.onSave - Callback function when form is saved
* @param args.parentForm - Parent form if this is a nested form
* @param args.parentPath - Path prefix for nested form fields
* @returns Complete form container with reactive state and methods
*
* @example
* ```typescript
* const contactForm = SignalFormBuilder.createForm({
* model: { name: '', email: '', phone: '' },
* fields: [
* { name: 'name', type: FormFieldType.TEXT, label: 'Full Name' },
* { name: 'email', type: FormFieldType.TEXT, label: 'Email' },
* { name: 'phone', type: FormFieldType.TEXT, label: 'Phone' }
* ],
* config: { layout: 'flex', view: 'stacked' },
* onSave: (data) => saveContact(data)
* });
* ```
*/
static createForm<TModel>(args: FormBuilderArgs<TModel>): SignalFormContainer<TModel>;
/**
* Creates a multi-step form (wizard) with separate pages/steps
*
* Builds a stepped form container that manages multiple form pages,
* allowing users to navigate between steps while maintaining state.
* Each step is a complete form with its own fields and validation.
*
* @template TModel - The TypeScript type of the form data model
* @param args - Configuration object for the stepped form
* @param args.model - Initial data model shared across all steps
* @param args.steps - Array of step configurations, each with fields
* @param args.onSave - Callback function when entire form is saved
* @param args.config - Global configuration for the stepped form
* @param args.config.canSkipIncompleteSteps - Allow navigation to incomplete steps
* @returns Stepped form container with navigation and validation methods
*
* @example
* ```typescript
* const wizardForm = SignalFormBuilder.createSteppedForm({
* model: { personal: {}, contact: {}, preferences: {} },
* steps: [
* {
* title: 'Personal Info',
* fields: [
* { name: 'firstName', type: FormFieldType.TEXT, label: 'First Name' }
* ]
* },
* {
* title: 'Contact Info',
* fields: [
* { name: 'email', type: FormFieldType.TEXT, label: 'Email' }
* ]
* }
* ],
* config: { canSkipIncompleteSteps: false }
* });
* ```
*/
static createSteppedForm<TModel>(args: SteppedFormBuilderArgs<TModel>): SignalSteppedFormContainer<TModel>;
/**
* Creates a form for managing an array/collection of items
*
* Builds a dynamic form container that manages multiple instances
* of the same form structure. Useful for managing lists of items
* where users can add, remove, and edit multiple entries.
*
* @template TModel - The TypeScript type of individual items in the array
* @param args - Configuration object for the array form
* @param args.model - Initial array of items
* @param args.fields - Field configuration shared by all items
* @param args.title - Optional form title
* @param args.config - Layout and behavior configuration
* @param args.onSave - Callback when entire array is saved
* @param args.onItemAdd - Callback when new item is added
* @param args.onItemRemove - Callback when item is removed
* @param args.defaultItem - Default values for new items
* @param args.parentForm - Parent form if this is nested
* @param args.parentPath - Path prefix for nested forms
* @returns Array form container with add/remove/manage functionality
*
* @example
* ```typescript
* const contactsForm = SignalFormBuilder.createFormFromArray({
* model: [{ name: '', email: '' }],
* fields: [
* { name: 'name', type: FormFieldType.TEXT, label: 'Name' },
* { name: 'email', type: FormFieldType.TEXT, label: 'Email' }
* ],
* defaultItem: { name: '', email: '' },
* onItemAdd: (item) => console.log('Added:', item),
* onItemRemove: (index) => console.log('Removed index:', index)
* });
* ```
*/
static createFormFromArray<TModel>(args: ArrayFormBuilderArgs<TModel>): ArrayFormContainer<TModel>;
}