# ng-forge

> A configuration-driven dynamic forms library for Angular. Build complex, reactive forms with minimal code using JSON/TypeScript configurations.

## Overview

Dynamic Forms is a configuration-driven way to build forms in Angular applications. Instead of manually building form templates, you define form structure through configuration objects, and ng-forge renders the appropriate UI components automatically.

## Key Features

- Configuration-driven form generation
- Multiple UI library integrations (Material, PrimeNG, Ionic, Bootstrap)
- Built-in validation with expression-based validators
- Conditional logic for showing/hiding fields
- Value derivation for computed fields
- Property derivation for dynamic field properties
- Type-safe form configurations
- Built on Angular Signal Forms (signal-based reactivity, not Reactive Forms or FormGroup)
- Value exclusion for controlling submitted form data
- AI integration via MCP server

## Documentation Structure

### Getting Started
- /getting-started: How to install and set up ng-forge dynamic forms in your project

### Configuration
- /configuration: Configure your UI library integration (Material, PrimeNG, Ionic, Bootstrap)
- /api-driven-forms: Drive forms from JSON shipped by a backend API

### Building an Adapter
- /building-an-adapter: Creating custom UI library integrations

### Field Types
- /field-types/text-inputs: Text input fields (input, textarea)
- /field-types/selection: Selection fields (select, radio, checkbox, toggle, multi-checkbox)
- /field-types/buttons: Button fields (submit, button, next, previous, array buttons)
- /field-types/utility: Utility fields (text, hidden)
- /field-types/advanced-controls: Advanced control fields (slider, datepicker)

### Validation
- /validation/basics: Validation configuration basics
- /validation/advanced: Conditional validators
- /validation/custom-validators: Custom and expression validators
- /validation/reference: Complete validation reference

### Dynamic Behavior
- /dynamic-behavior/conditional-logic: Conditional logic - show/hide fields based on conditions
- /dynamic-behavior/derivation/values: Value derivation - computed field values
- /dynamic-behavior/derivation/property: Property derivation - dynamic field properties
- /dynamic-behavior/derivation/async: Async derivation - asynchronous computed values
- /dynamic-behavior/i18n: Internationalization support
- /dynamic-behavior/submission: Form submission handling

### Schema Validation
- /schema-validation/overview: Form-level validation overview
- /schema-validation/angular-schema: Angular native schema validation
- /schema-validation/zod: Standard Schema (Zod, Valibot, ArkType) validation

### Layout Components
- /prebuilt/form-pages: Page container components
- /prebuilt/form-groups: Field grouping components
- /prebuilt/form-rows: Row layout components
- /prebuilt/form-arrays/simplified: Simplified array API (recommended)
- /prebuilt/form-arrays/complete: Complete array API (advanced)
- /prebuilt/container-field: Container for stacking wrappers without nesting form values
- /prebuilt/text-components: Text and label components
- /prebuilt/hidden-fields: Hidden field components

### Wrappers
- /wrappers/overview: Decorate fields with extra UI chrome (cards, panels, indicators)
- /wrappers/writing-a-wrapper: Build a custom wrapper component
- /wrappers/registering-and-applying: Register wrappers and apply them to fields

### Addons
- /addons/overview: Icons, buttons, and text in a field's prefix and suffix slots
- /addons/presets-and-actions: Built-in presets (clear, reset, paste, copy, password toggle) and registered actions
- /addons/custom-types: Register your own addon type

### Examples
- /examples: Browse all examples
- /examples/login-form: Simple login form example
- /examples/contact-form: Contact form with validation
- /examples/user-registration: Multi-field registration form
- /examples/paginated-form: Multi-page wizard form
- /examples/value-derivation: Computed field values example
- /examples/contact-dynamic-fields: Dynamic contact fields
- /examples/business-account-form: Business account form
- /examples/shipping-billing-address: Shipping same-as-billing example
- /examples/age-conditional-form: Age-based conditional form
- /examples/enterprise-features: Complex multi-condition form
- /examples/simplified-array-form: Simplified array API example
- /examples/array-form: Complete array API example
- /examples/wrapper-array-actions: Wrapper that owns an array's add button
- /examples/addon-clear-button: Clear-button addon pattern
- /examples/addon-currency: Universal text addon (currency prefix)
- /examples/addon-password-toggle: Password-visibility toggle addon

### Recipes
- /recipes/type-safety: TypeScript type safety features
- /recipes/events: Form and field event handling
- /recipes/expression-parser: Expression syntax for validators and conditions
- /recipes/custom-fields: Adding custom field types
- /recipes/value-exclusion: Controlling which fields are included in submitted form values

### Migration
- /migrating-from-ngx-formly: Concept-by-concept migration guide from ngx-formly to ng-forge

### Feature Overview
- /feature-overview: Task-oriented navigator into the docs, plus a general FAQ and the most common pitfalls (group vs container, hidden field values, validator messages, custom-fn dependencies, select option shape, derivation depth limits)

### AI Integration
- /ai-integration: MCP server for AI-assisted form schema generation

### OpenAPI Generator
- /openapi-generator: Generate FormConfig and typed form values from an OpenAPI 3.x spec

### API Reference
- /api-reference: Complete API documentation for all packages

## Installation

```bash
npm install @ng-forge/dynamic-forms
# Plus your preferred UI library integration
npm install @ng-forge/dynamic-forms-material
```

## Quick Example

```typescript
import { DynamicForm, type FormConfig, type InferFormValue } from '@ng-forge/dynamic-forms';

@Component({
  imports: [DynamicForm],
  template: `<form [dynamic-form]="config" (submitted)="onSubmit($event)"></form>`,
})
export class LoginComponent {
  config = {
    fields: [
      { key: 'email', type: 'input', value: '', label: 'Email', required: true, email: true },
      { key: 'password', type: 'input', value: '', label: 'Password', required: true, minLength: 8, props: { type: 'password' } },
      { type: 'submit', key: 'submit', label: 'Sign In' },
    ],
  } as const satisfies FormConfig;

  onSubmit(value: InferFormValue<typeof this.config.fields>) {
    console.log('Form submitted:', value);
  }
}
```

## Repository

- GitHub: https://github.com/ng-forge/ng-forge
- Documentation: https://ng-forge.com/dynamic-forms/

## License

MIT