ng-entity-forms 1.0.0

package/README.md

@@ -0,0 +1,497 @@
+# ng-entity-forms
+
+Strongly-typed reactive forms for Angular. Define your entity interface — the library maps it to a fully-typed `FormGroup` with autocompletion, validation, and error messages out of the box.
+
+---
+
+## Requirements
+
+- Angular 17+
+
+---
+
+## Installation
+
+```bash
+npm install ng-entity-forms
+```
+
+---
+
+## Quick Start
+
+```typescript
+import { entity, entityForm } from 'ng-entity-forms';
+
+export interface ProductForm {
+  name: string;
+  description: string | null;
+  price: number;
+  active: boolean;
+  thumbnail: File | null;
+}
+
+protected form = entityForm<ProductForm>({
+  name:        entity.required(''),
+  description: entity.optional<string>(null),
+  price:       entity.required(0),
+  active:      entity.required(false),
+  thumbnail:   entity.file(),
+});
+
+// TypeScript knows the exact type of every control
+// form.controls.name        → FormControl<string>
+// form.controls.description → FormControl<string | null>
+// form.controls.thumbnail   → FormControl<File | null>
+```
+
+---
+
+## API
+
+### `entity.required(initialValue, config?)`
+
+Creates a non-nullable `FormControl` with `Validators.required` applied automatically.
+
+```typescript
+entity.required('');
+entity.required(0); // 0 is a valid initial value
+entity.required(false); // false is a valid initial value
+```
+
+The second argument is flexible — pick whatever fits:
+
+```typescript
+entity.required('', Validators.minLength(3))                         // single validator
+entity.required('', [Validators.minLength(3), myValidator])          // array
+entity.required('', { validators: [...], disabled: true, updateOn: 'blur' }) // full options
+```
+
+---
+
+### `entity.optional<T>(initialValue, config?)`
+
+Creates a nullable `FormControl<T | null>`.
+
+```typescript
+entity.optional<string>(null)
+entity.optional<number>(null, Validators.max(100))
+entity.optional<string>(null, [Validators.maxLength(500), myValidator])
+entity.optional<string>(null, { validators: [...], disabled: true })
+```
+
+---
+
+### `entity.file(config?)`
+
+Creates a `FormControl<File | null>`. The value is the native `File` object — no wrappers, no library types leaking into your entity.
+
+```typescript
+entity.file();
+entity.file({ validators: [mimeTypeValidator, maxFileSizeValidator] });
+```
+
+---
+
+### `entityForm<T>(controls, options?)`
+
+Creates a fully-typed `FormGroup` from your entity. Supports single or multiple cross-field validators at the form level.
+
+```typescript
+// Basic
+const form = entityForm<ProductForm>({ ... });
+
+// With cross-field validator
+const form = entityForm<ProductForm>(
+  { ... },
+  { validators: passwordMatchValidator },
+);
+
+// Multiple cross-field validators
+const form = entityForm<ProductForm>(
+  { ... },
+  { validators: [passwordMatchValidator, priceRangeValidator] },
+);
+```
+
+---
+
+## File Handling
+
+Declare the field as `File | null` in your entity — no library types needed.
+
+```typescript
+export interface ProductForm {
+  thumbnail: File | null;
+}
+```
+
+Use `patchFileControl` and `clearFileControl` to connect the native input:
+
+```typescript
+import { patchFileControl, clearFileControl } from 'ng-entity-forms';
+
+@Component({
+  template: `
+    <input #fileInput type="file" (change)="onFileChange($event)" />
+    <button type="button" (click)="removeFile()">Remove</button>
+    @if (form.controls.thumbnail.value; as file) {
+      <span>{{ file.name }} — {{ (file.size / 1024).toFixed(1) }}KB</span>
+    }
+  `,
+})
+export class MyComponent {
+  @ViewChild('fileInput') fileInput!: ElementRef<HTMLInputElement>;
+
+  protected form = entityForm<ProductForm>({
+    thumbnail: entity.file({ validators: [mimeTypeValidator] }),
+  });
+
+  onFileChange(event: Event): void {
+    patchFileControl(event, this.form.controls.thumbnail);
+  }
+
+  removeFile(): void {
+    // Resets the native input so the browser forgets the previous selection
+    clearFileControl(this.form.controls.thumbnail, this.fileInput.nativeElement);
+  }
+
+  onSubmit(): void {
+    const { thumbnail } = this.form.getRawValue();
+    const formData = new FormData();
+    if (thumbnail) formData.append('thumbnail', thumbnail); // native File, ready to upload
+  }
+}
+```
+
+---
+
+## Global Validators
+
+Register validators once in `app.config.ts`. They are applied automatically to every control — no need to repeat them per field.
+
+```typescript
+// app.config.ts
+import { provideDefaultValidators } from 'ng-entity-forms';
+
+provideDefaultValidators({
+  all: [Validators.maxLength(255)], // every control
+  required: [trimValidator], // required controls only
+  optional: [], // optional controls only
+});
+```
+
+Per-control validators are always **additive** — they stack on top of the global ones.
+
+---
+
+## Error Messages
+
+Built-in Angular validators (`required`, `minlength`, `maxlength`, `min`, `max`, `email`, `pattern`) are resolved automatically. **English is the default locale.**
+
+### `provideErrorMessages` — custom messages
+
+Merges your custom messages on top of the English built-ins. Only define what you need.
+
+```typescript
+// app.config.ts
+import { provideErrorMessages } from 'ng-entity-forms';
+
+provideErrorMessages({
+  // Custom validator messages
+  whitespace: 'Cannot contain only whitespace',
+  passwordMismatch: 'Passwords do not match',
+  slugTaken: (err) => `The slug "${err.value}" is already taken`,
+  mimeType: (err) => `Invalid format. Allowed: ${err.allowed.join(', ')}`,
+  maxFileSize: (err) => `File too large. Max size: ${err.maxMb}MB`,
+
+  // Override a built-in if needed
+  required: 'This field cannot be empty',
+});
+```
+
+Message values can be a plain `string` or a function that receives the Angular error object:
+
+```typescript
+// Plain string
+whitespace: 'Cannot contain only whitespace';
+
+// Function with error data
+minPrice: (err) => `Min price is ${err.min}`;
+```
+
+### `provideErrorMessagesLocale` — switch locale
+
+Switches all built-in messages to a supported locale (`'en'` | `'es'`). Optionally extend with your custom messages on top.
+
+```typescript
+import { provideErrorMessagesLocale } from 'ng-entity-forms';
+
+// Spanish built-ins only
+provideErrorMessagesLocale('es');
+
+// Spanish + custom messages
+provideErrorMessagesLocale('es', {
+  whitespace: 'No puede contener solo espacios',
+  passwordMismatch: 'Las contraseñas no coinciden',
+  slugTaken: (err) => `El slug "${err.value}" ya está en uso`,
+
+  // Override a Spanish built-in
+  required: 'Campo requerido',
+});
+```
+
+> Use either `provideErrorMessages` or `provideErrorMessagesLocale` — not both. If you need a locale other than English with custom messages, always use `provideErrorMessagesLocale`.
+
+### `fieldErrors` pipe
+
+Returns `FieldError[]` — only when the control is `touched` or `dirty`. Each item has a stable `key` and a resolved `message`.
+
+```typescript
+imports: [FieldErrorsPipe];
+```
+
+```html
+<!-- Global messages -->
+@for (error of form.controls.name | fieldErrors; track error.key) {
+<small class="error">{{ error.message }}</small>
+}
+
+<!-- Local override — takes priority over global messages for this field only -->
+@for ( error of form.controls.name | fieldErrors: { required: 'Product name is required' }; track
+error.key ) {
+<small class="error">{{ error.message }}</small>
+}
+
+<!-- Cross-field errors on the FormGroup -->
+@for (error of form | fieldErrors; track error.key) {
+<p class="error">{{ error.message }}</p>
+}
+```
+
+Always use `track error.key` — the error key is stable and avoids Angular's `NG0956` warning.
+
+---
+
+## Async Validators
+
+Pass them through the options object along with `updateOn: 'blur'` to avoid hammering the server on every keystroke.
+
+```typescript
+entity.required('', {
+  validators: [Validators.minLength(3), Validators.pattern(/^[a-z0-9-]+$/)],
+  asyncValidators: [slugAvailableValidator],
+  updateOn: 'blur',
+});
+```
+
+Always check `form.pending` before submitting — async validators may still be running:
+
+```typescript
+onSubmit(): void {
+  this.form.markAllAsTouched();
+  if (this.form.pending) return;  // async validators still running
+  if (this.form.invalid) return;
+
+  const value = this.form.getRawValue();
+}
+```
+
+---
+
+## Dynamic Fields
+
+Start a field as disabled and toggle it based on business logic:
+
+```typescript
+protected form = entityForm<MyEntity>({
+  featured:     entity.optional<boolean>(null),
+  discountCode: entity.optional<string>(null, { disabled: true }), // starts disabled
+});
+
+onFeaturedChange(): void {
+  if (this.form.controls.featured.value) {
+    this.form.controls.discountCode.enable();
+  } else {
+    this.form.controls.discountCode.disable();
+    this.form.controls.discountCode.setValue(null);
+  }
+}
+```
+
+`getRawValue()` includes disabled fields. `value` does not.
+
+---
+
+## Considerations
+
+### Optional fields require `string | null` — not `name?`
+
+Angular's `FormControl` does not support `undefined`. Use explicit null unions instead of optional properties.
+
+```typescript
+// will not work
+export interface ProductForm {
+  description?: string;
+}
+
+// correct
+export interface ProductForm {
+  description: string | null;
+}
+```
+
+If your domain entity uses `?`, create a dedicated form interface:
+
+```typescript
+// Domain entity — keep as is
+export interface Product {
+  name: string;
+  description?: string;
+}
+
+// Form interface — explicit nulls
+export interface ProductForm {
+  name: string;
+  description: string | null;
+}
+
+protected form = entityForm<ProductForm>({ ... });
+```
+
+### `0` and `false` are valid initial values
+
+```typescript
+entity.required(0); // stock starting at zero
+entity.required(false); // checkbox starting unchecked
+```
+
+### Always use `getRawValue()` on submit
+
+`form.value` omits disabled fields. `getRawValue()` includes them.
+
+```typescript
+const value = this.form.getRawValue(); // includes disabled fields
+```
+
+### The `fieldErrors` pipe is `pure: false`
+
+It re-evaluates on every change detection cycle to react to control state changes (`touched`, `dirty`, `errors`). This is intentional — a pure pipe would miss mutations on the same `FormControl` reference. For large forms, pair it with `OnPush` change detection on your component.
+
+---
+
+## Full Example
+
+```typescript
+import { Component, ElementRef, ViewChild } from '@angular/core';
+import { ReactiveFormsModule, Validators, AbstractControl, ValidationErrors } from '@angular/forms';
+import {
+  entity,
+  entityForm,
+  patchFileControl,
+  clearFileControl,
+  FieldErrorsPipe,
+} from 'ng-entity-forms';
+
+export interface ProductForm {
+  name: string;
+  description: string | null;
+  price: number;
+  active: boolean;
+  thumbnail: File | null;
+}
+
+function noNegativePrice(control: AbstractControl): ValidationErrors | null {
+  return (control.value as number) < 0 ? { negativePrice: true } : null;
+}
+
+@Component({
+  standalone: true,
+  imports: [ReactiveFormsModule, FieldErrorsPipe],
+  template: `
+    <form [formGroup]="form" (ngSubmit)="onSubmit()">
+      <input formControlName="name" placeholder="Product name" />
+      @for (e of form.controls.name | fieldErrors; track e.key) {
+        <small>{{ e.message }}</small>
+      }
+
+      <input type="number" formControlName="price" />
+      @for (e of form.controls.price | fieldErrors; track e.key) {
+        <small>{{ e.message }}</small>
+      }
+
+      <input #fileInput type="file" (change)="onFileChange($event)" />
+      @if (form.controls.thumbnail.value; as file) {
+        <span>{{ file.name }}</span>
+      }
+
+      <button type="submit">Save</button>
+    </form>
+  `,
+})
+export class ProductFormComponent {
+  protected form = entityForm<ProductForm>({
+    name: entity.required('', Validators.minLength(3)),
+    description: entity.optional<string>(null),
+    price: entity.required(0, [Validators.min(0), noNegativePrice]),
+    active: entity.required(false),
+    thumbnail: entity.file(),
+  });
+
+  onFileChange(event: Event): void {
+    patchFileControl(event, this.form.controls.thumbnail);
+  }
+
+  onSubmit(): void {
+    this.form.markAllAsTouched();
+    if (this.form.pending || this.form.invalid) return;
+
+    const value = this.form.getRawValue();
+    // value.name      → string
+    // value.price     → number
+    // value.thumbnail → File | null
+  }
+}
+```
+
+---
+
+## Public API
+
+| Export                       | Description                                                                          |
+| ---------------------------- | ------------------------------------------------------------------------------------ |
+| `entity`                     | Builder object — `entity.required`, `entity.optional`, `entity.file`                 |
+| `entityForm`                 | Creates a typed `FormGroup<EntityFields<T>>`                                         |
+| `patchFileControl`           | Updates a file control from a native input `change` event                            |
+| `clearFileControl`           | Clears a file control and resets the native input element                            |
+| `FieldErrorsPipe`            | Pipe that resolves control errors to `FieldError[]`                                  |
+| `provideDefaultValidators`   | Registers global validators in `app.config`                                          |
+| `provideErrorMessages`       | Registers custom error messages in `app.config` (English base)                       |
+| `provideErrorMessagesLocale` | Switches built-in messages to a locale (`'en'` \| `'es'`) + optional custom messages |
+| `EntityForm<T>`              | Type alias for `FormGroup<EntityFields<T>>`                                          |
+| `EntityFields<T>`            | Maps entity fields to typed `FormControl`                                            |
+| `ControlConfig`              | Second argument type for `entity.required` / `entity.optional`                       |
+| `FieldError`                 | `{ key: string; message: string }` — returned by `fieldErrors` pipe                  |
+| `ErrorMessages`              | Error messages map type                                                              |
+| `SupportedLocale`            | `'en' \| 'es'`                                                                       |
+| `DefaultValidatorsConfig`    | Config type for `provideDefaultValidators`                                           |
+
+---
+
+## Philosophy
+
+Angular's reactive forms are powerful but verbose. Typed forms (introduced in Angular 14) improved the situation, but the boilerplate of creating controls, wiring validators, and displaying errors still adds up fast across a real project.
+
+`ng-entity-forms` takes the position that your form should follow your entity — not the other way around. You define the shape of your data once, and the library derives the form structure from it. TypeScript does the rest.
+
+- **Entity-first** — your interface is the source of truth, the form follows it
+- **Zero guessing** — full autocompletion on `form.controls.X` with the correct type
+- **Flat API** — one builder object, three methods, one function to create the group
+- **Additive** — global validators and error messages layer on top without touching your controls
+- **No lock-in** — built entirely on Angular's own `FormControl` and `FormGroup`, no custom abstractions underneath
+
+---
+
+## License
+
+MIT

package/fesm2022/ng-entity-forms.mjs

@@ -0,0 +1,157 @@
+import * as i0 from '@angular/core';
+import { InjectionToken, inject, Pipe } from '@angular/core';
+import { FormControl, Validators, FormGroup } from '@angular/forms';
+
+const DEFAULT_VALIDATORS_TOKEN = new InjectionToken('NG_ENTITY_FORMS_DEFAULT_VALIDATORS', {
+    providedIn: 'root',
+    factory: () => ({}),
+});
+
+function normalizeConfig(config) {
+    if (typeof config === 'function') {
+        return { validators: [config] };
+    }
+    if (Array.isArray(config)) {
+        return { validators: config };
+    }
+    return config;
+}
+function resolveGlobalValidators(type) {
+    const config = inject(DEFAULT_VALIDATORS_TOKEN);
+    return [...(config.all ?? []), ...(config[type] ?? [])];
+}
+function requiredControl(initialValue, config = []) {
+    const { validators = [], asyncValidators = [], disabled = false, updateOn, } = normalizeConfig(config);
+    const globalValidators = resolveGlobalValidators('required');
+    return new FormControl({ value: initialValue, disabled }, {
+        nonNullable: true,
+        validators: [Validators.required, ...globalValidators, ...validators],
+        asyncValidators,
+        updateOn,
+    });
+}
+function optionalControl(initialValue, config = []) {
+    const { validators = [], asyncValidators = [], disabled = false, updateOn, } = normalizeConfig(config);
+    const globalValidators = resolveGlobalValidators('optional');
+    return new FormControl({ value: initialValue, disabled }, {
+        validators: [...globalValidators, ...validators],
+        asyncValidators,
+        updateOn,
+    });
+}
+
+const entity = {
+    required(initialValue, config = []) {
+        return requiredControl(initialValue, config);
+    },
+    optional(initialValue, config = []) {
+        return optionalControl(initialValue, config);
+    },
+    file(config = []) {
+        return optionalControl(null, config);
+    },
+};
+
+function entityForm(controls, options) {
+    return new FormGroup(controls, options);
+}
+function patchFileControl(event, control) {
+    if (!(event.target instanceof HTMLInputElement)) {
+        throw new Error('patchFileControl expects an HTMLInputElement');
+    }
+    const file = event.target.files?.[0] ?? null;
+    control.setValue(file);
+    control.markAsTouched();
+}
+function clearFileControl(control, inputElement) {
+    control.setValue(null);
+    control.markAsTouched();
+    if (inputElement) {
+        inputElement.value = '';
+    }
+}
+
+function provideDefaultValidators(config) {
+    return {
+        provide: DEFAULT_VALIDATORS_TOKEN,
+        useValue: config,
+    };
+}
+
+const BUILT_IN_ERROR_MESSAGES_EN = {
+    required: 'This field is required',
+    email: 'Invalid email format',
+    pattern: 'Invalid format',
+    minlength: (err) => `Minimum ${err.requiredLength} characters`,
+    maxlength: (err) => `Maximum ${err.requiredLength} characters`,
+    min: (err) => `Minimum value is ${err.min}`,
+    max: (err) => `Maximum value is ${err.max}`,
+};
+const BUILT_IN_ERROR_MESSAGES_ES = {
+    required: 'Este campo es obligatorio',
+    email: 'El formato del email no es válido',
+    pattern: 'El formato no es válido',
+    minlength: (err) => `Mínimo ${err.requiredLength} caracteres`,
+    maxlength: (err) => `Máximo ${err.requiredLength} caracteres`,
+    min: (err) => `El valor mínimo es ${err.min}`,
+    max: (err) => `El valor máximo es ${err.max}`,
+};
+const BUILT_IN_ERROR_MESSAGES = {
+    en: BUILT_IN_ERROR_MESSAGES_EN,
+    es: BUILT_IN_ERROR_MESSAGES_ES,
+};
+const ERROR_MESSAGES_TOKEN = new InjectionToken('NG_ENTITY_FORMS_ERROR_MESSAGES', {
+    providedIn: 'root',
+    factory: () => ({ ...BUILT_IN_ERROR_MESSAGES_EN }),
+});
+
+function provideErrorMessages(messages) {
+    return {
+        provide: ERROR_MESSAGES_TOKEN,
+        useValue: { ...BUILT_IN_ERROR_MESSAGES['en'], ...messages },
+    };
+}
+function provideErrorMessagesLocale(locale, messages = {}) {
+    return {
+        provide: ERROR_MESSAGES_TOKEN,
+        useValue: { ...BUILT_IN_ERROR_MESSAGES[locale], ...messages },
+    };
+}
+
+function resolveMessage(messageValue, errorData) {
+    return typeof messageValue === 'function' ? messageValue(errorData) : messageValue;
+}
+class FieldErrorsPipe {
+    globalMessages = inject(ERROR_MESSAGES_TOKEN);
+    transform(control, overrides) {
+        if (!control || !control.errors)
+            return [];
+        if (!control.touched && !control.dirty)
+            return [];
+        const messages = overrides
+            ? { ...this.globalMessages, ...overrides }
+            : this.globalMessages;
+        return Object.entries(control.errors).map(([key, errorData]) => {
+            const messageValue = messages[key];
+            const message = messageValue ? resolveMessage(messageValue, errorData) : `[${key}]`;
+            return { key, message };
+        });
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.1.5", ngImport: i0, type: FieldErrorsPipe, deps: [], target: i0.ɵɵFactoryTarget.Pipe });
+    static ɵpipe = i0.ɵɵngDeclarePipe({ minVersion: "14.0.0", version: "21.1.5", ngImport: i0, type: FieldErrorsPipe, isStandalone: true, name: "fieldErrors", pure: false });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.5", ngImport: i0, type: FieldErrorsPipe, decorators: [{
+            type: Pipe,
+            args: [{
+                    name: 'fieldErrors',
+                    standalone: true,
+                    pure: false,
+                }]
+        }] });
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { BUILT_IN_ERROR_MESSAGES, DEFAULT_VALIDATORS_TOKEN, ERROR_MESSAGES_TOKEN, FieldErrorsPipe, clearFileControl, entity, entityForm, patchFileControl, provideDefaultValidators, provideErrorMessages, provideErrorMessagesLocale };
+//# sourceMappingURL=ng-entity-forms.mjs.map

package/fesm2022/ng-entity-forms.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ng-entity-forms.mjs","sources":["../../../projects/ng-entity-forms/src/lib/validation/validation.token.ts","../../../projects/ng-entity-forms/src/lib/core/controls.ts","../../../projects/ng-entity-forms/src/lib/core/entity.ts","../../../projects/ng-entity-forms/src/lib/core/entity-form.ts","../../../projects/ng-entity-forms/src/lib/validation/validation.provider.ts","../../../projects/ng-entity-forms/src/lib/errors/error-messages.token.ts","../../../projects/ng-entity-forms/src/lib/errors/error-messages.provider.ts","../../../projects/ng-entity-forms/src/lib/errors/field-errors.pipe.ts","../../../projects/ng-entity-forms/src/ng-entity-forms.ts"],"sourcesContent":["import { InjectionToken } from '@angular/core';\nimport { ValidatorFn } from '@angular/forms';\n\nexport interface DefaultValidatorsConfig {\n  all?: ValidatorFn[];\n  required?: ValidatorFn[];\n  optional?: ValidatorFn[];\n}\n\nexport const DEFAULT_VALIDATORS_TOKEN = new InjectionToken<DefaultValidatorsConfig>(\n  'NG_ENTITY_FORMS_DEFAULT_VALIDATORS',\n  {\n    providedIn: 'root',\n    factory: () => ({}),\n  },\n);\n","import { inject } from '@angular/core';\nimport { FormControl, ValidatorFn, Validators } from '@angular/forms';\n\nimport { ControlOptions, ControlConfig } from './types';\nimport { DEFAULT_VALIDATORS_TOKEN } from '../validation/validation.token';\n\nexport function normalizeConfig(config: ControlConfig): ControlOptions {\n  if (typeof config === 'function') {\n    return { validators: [config as ValidatorFn] };\n  }\n\n  if (Array.isArray(config)) {\n    return { validators: config as ValidatorFn[] };\n  }\n\n  return config as ControlOptions;\n}\n\nexport function resolveGlobalValidators(type: 'required' | 'optional'): ValidatorFn[] {\n  const config = inject(DEFAULT_VALIDATORS_TOKEN);\n  return [...(config.all ?? []), ...(config[type] ?? [])];\n}\n\nexport function requiredControl<T>(\n  initialValue: NonNullable<T>,\n  config: ControlConfig = [],\n): FormControl<NonNullable<T>> {\n  const {\n    validators = [],\n    asyncValidators = [],\n    disabled = false,\n    updateOn,\n  } = normalizeConfig(config);\n\n  const globalValidators = resolveGlobalValidators('required');\n\n  return new FormControl<NonNullable<T>>(\n    { value: initialValue, disabled },\n    {\n      nonNullable: true,\n      validators: [Validators.required, ...globalValidators, ...validators],\n      asyncValidators,\n      updateOn,\n    },\n  ) as FormControl<NonNullable<T>>;\n}\n\nexport function optionalControl<T>(\n  initialValue: T | null,\n  config: ControlConfig = [],\n): FormControl<T | null> {\n  const {\n    validators = [],\n    asyncValidators = [],\n    disabled = false,\n    updateOn,\n  } = normalizeConfig(config);\n\n  const globalValidators = resolveGlobalValidators('optional');\n\n  return new FormControl<T | null>(\n    { value: initialValue, disabled },\n    {\n      validators: [...globalValidators, ...validators],\n      asyncValidators,\n      updateOn,\n    },\n  );\n}\n","import { FormControl } from '@angular/forms';\n\nimport { ControlConfig } from './types';\nimport { optionalControl, requiredControl } from './controls';\n\nexport const entity = {\n  required<T>(\n    initialValue: NonNullable<T>,\n    config: ControlConfig = [],\n  ): FormControl<NonNullable<T>> {\n    return requiredControl<T>(initialValue, config);\n  },\n\n  optional<T>(initialValue: T | null, config: ControlConfig = []): FormControl<T | null> {\n    return optionalControl<T>(initialValue, config);\n  },\n\n  file(config: ControlConfig = []): FormControl<File | null> {\n    return optionalControl<File>(null, config);\n  },\n};\n","import { FormControl, FormGroup } from '@angular/forms';\n\nimport { EntityFields, EntityForm, GroupOptions } from './types';\n\nexport function entityForm<T>(controls: EntityFields<T>, options?: GroupOptions): EntityForm<T> {\n  return new FormGroup<EntityFields<T>>(controls, options);\n}\n\nexport function patchFileControl(event: Event, control: FormControl<File | null>): void {\n  if (!(event.target instanceof HTMLInputElement)) {\n    throw new Error('patchFileControl expects an HTMLInputElement');\n  }\n\n  const file = event.target.files?.[0] ?? null;\n\n  control.setValue(file);\n  control.markAsTouched();\n}\n\nexport function clearFileControl(\n  control: FormControl<File | null>,\n  inputElement?: HTMLInputElement,\n): void {\n  control.setValue(null);\n  control.markAsTouched();\n\n  if (inputElement) {\n    inputElement.value = '';\n  }\n}\n","import { Provider } from '@angular/core';\n\nimport { DEFAULT_VALIDATORS_TOKEN, DefaultValidatorsConfig } from './validation.token';\n\nexport function provideDefaultValidators(config: DefaultValidatorsConfig): Provider {\n  return {\n    provide: DEFAULT_VALIDATORS_TOKEN,\n    useValue: config,\n  };\n}\n","import { InjectionToken } from '@angular/core';\n\nexport type ErrorMessageFn = (err: unknown) => string;\nexport type ErrorMessageValue = string | ErrorMessageFn;\nexport type ErrorMessages = Record<string, ErrorMessageValue>;\n\nexport type SupportedLocale = 'en' | 'es';\n\nconst BUILT_IN_ERROR_MESSAGES_EN: ErrorMessages = {\n  required: 'This field is required',\n  email: 'Invalid email format',\n  pattern: 'Invalid format',\n  minlength: (err: unknown) =>\n    `Minimum ${(err as { requiredLength: number }).requiredLength} characters`,\n  maxlength: (err: unknown) =>\n    `Maximum ${(err as { requiredLength: number }).requiredLength} characters`,\n  min: (err: unknown) => `Minimum value is ${(err as { min: number }).min}`,\n  max: (err: unknown) => `Maximum value is ${(err as { max: number }).max}`,\n};\n\nconst BUILT_IN_ERROR_MESSAGES_ES: ErrorMessages = {\n  required: 'Este campo es obligatorio',\n  email: 'El formato del email no es válido',\n  pattern: 'El formato no es válido',\n  minlength: (err: unknown) =>\n    `Mínimo ${(err as { requiredLength: number }).requiredLength} caracteres`,\n  maxlength: (err: unknown) =>\n    `Máximo ${(err as { requiredLength: number }).requiredLength} caracteres`,\n  min: (err: unknown) => `El valor mínimo es ${(err as { min: number }).min}`,\n  max: (err: unknown) => `El valor máximo es ${(err as { max: number }).max}`,\n};\n\nexport const BUILT_IN_ERROR_MESSAGES: Record<SupportedLocale, ErrorMessages> = {\n  en: BUILT_IN_ERROR_MESSAGES_EN,\n  es: BUILT_IN_ERROR_MESSAGES_ES,\n};\n\nexport const ERROR_MESSAGES_TOKEN = new InjectionToken<ErrorMessages>(\n  'NG_ENTITY_FORMS_ERROR_MESSAGES',\n  {\n    providedIn: 'root',\n    factory: () => ({ ...BUILT_IN_ERROR_MESSAGES_EN }),\n  },\n);\n","import { Provider } from '@angular/core';\n\nimport {\n  BUILT_IN_ERROR_MESSAGES,\n  ERROR_MESSAGES_TOKEN,\n  ErrorMessages,\n  SupportedLocale,\n} from './error-messages.token';\n\nexport function provideErrorMessages(messages: ErrorMessages): Provider {\n  return {\n    provide: ERROR_MESSAGES_TOKEN,\n    useValue: { ...BUILT_IN_ERROR_MESSAGES['en'], ...messages },\n  };\n}\n\nexport function provideErrorMessagesLocale(\n  locale: SupportedLocale,\n  messages: ErrorMessages = {},\n): Provider {\n  return {\n    provide: ERROR_MESSAGES_TOKEN,\n    useValue: { ...BUILT_IN_ERROR_MESSAGES[locale], ...messages },\n  };\n}\n","import { inject, Pipe, PipeTransform } from '@angular/core';\nimport { AbstractControl } from '@angular/forms';\n\nimport { ErrorMessageValue, ERROR_MESSAGES_TOKEN, ErrorMessages } from './error-messages.token';\n\nfunction resolveMessage(messageValue: ErrorMessageValue, errorData: unknown): string {\n  return typeof messageValue === 'function' ? messageValue(errorData) : messageValue;\n}\n\nexport interface FieldError {\n  key: string;\n  message: string;\n}\n\n@Pipe({\n  name: 'fieldErrors',\n  standalone: true,\n  pure: false,\n})\nexport class FieldErrorsPipe implements PipeTransform {\n  private readonly globalMessages = inject(ERROR_MESSAGES_TOKEN);\n  transform(control: AbstractControl | null | undefined, overrides?: ErrorMessages): FieldError[] {\n    if (!control || !control.errors) return [];\n\n    if (!control.touched && !control.dirty) return [];\n\n    const messages: ErrorMessages = overrides\n      ? { ...this.globalMessages, ...overrides }\n      : this.globalMessages;\n\n    return Object.entries(control.errors).map(([key, errorData]) => {\n      const messageValue = messages[key];\n      const message = messageValue ? resolveMessage(messageValue, errorData) : `[${key}]`;\n      return { key, message };\n    });\n  }\n}\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './public-api';\n"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "ng-entity-forms",
+  "version": "1.0.0",
+  "license": "MIT",
+  "description": "Typed reactive forms for Angular. Build strongly-typed forms from your entity interfaces with minimal boilerplate.",
+  "keywords": [
+    "angular",
+    "forms",
+    "reactive-forms",
+    "typed-forms",
+    "entity-forms",
+    "form-builder",
+    "typescript",
+    "angular-library",
+    "form-validation",
+    "angular-forms"
+  ],
+  "peerDependencies": {
+    "@angular/common": ">=17.0.0",
+    "@angular/core": ">=17.0.0",
+    "@angular/forms": ">=17.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@angular/common": {
+      "optional": false
+    },
+    "@angular/core": {
+      "optional": false
+    },
+    "@angular/forms": {
+      "optional": false
+    }
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "sideEffects": false,
+  "module": "fesm2022/ng-entity-forms.mjs",
+  "typings": "types/ng-entity-forms.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./types/ng-entity-forms.d.ts",
+      "default": "./fesm2022/ng-entity-forms.mjs"
+    }
+  }
+}

package/types/ng-entity-forms.d.ts

@@ -0,0 +1,63 @@
+import { ValidatorFn, AsyncValidatorFn, FormControl, FormGroup, AbstractControl } from '@angular/forms';
+import * as i0 from '@angular/core';
+import { InjectionToken, Provider, PipeTransform } from '@angular/core';
+
+type EntityFields<T> = {
+    [K in keyof T]: FormControl<T[K]>;
+};
+type EntityForm<T> = FormGroup<EntityFields<T>>;
+interface ControlOptions {
+    validators?: ValidatorFn[];
+    asyncValidators?: AsyncValidatorFn[];
+    disabled?: boolean;
+    updateOn?: 'change' | 'blur' | 'submit';
+}
+type ControlConfig = ValidatorFn | ValidatorFn[] | ControlOptions;
+interface GroupOptions {
+    validators?: ValidatorFn | ValidatorFn[];
+    asyncValidators?: AsyncValidatorFn | AsyncValidatorFn[];
+    updateOn?: 'change' | 'blur' | 'submit';
+}
+
+declare const entity: {
+    required<T>(initialValue: NonNullable<T>, config?: ControlConfig): FormControl<NonNullable<T>>;
+    optional<T>(initialValue: T | null, config?: ControlConfig): FormControl<T | null>;
+    file(config?: ControlConfig): FormControl<File | null>;
+};
+
+declare function entityForm<T>(controls: EntityFields<T>, options?: GroupOptions): EntityForm<T>;
+declare function patchFileControl(event: Event, control: FormControl<File | null>): void;
+declare function clearFileControl(control: FormControl<File | null>, inputElement?: HTMLInputElement): void;
+
+interface DefaultValidatorsConfig {
+    all?: ValidatorFn[];
+    required?: ValidatorFn[];
+    optional?: ValidatorFn[];
+}
+declare const DEFAULT_VALIDATORS_TOKEN: InjectionToken<DefaultValidatorsConfig>;
+
+declare function provideDefaultValidators(config: DefaultValidatorsConfig): Provider;
+
+type ErrorMessageFn = (err: unknown) => string;
+type ErrorMessageValue = string | ErrorMessageFn;
+type ErrorMessages = Record<string, ErrorMessageValue>;
+type SupportedLocale = 'en' | 'es';
+declare const BUILT_IN_ERROR_MESSAGES: Record<SupportedLocale, ErrorMessages>;
+declare const ERROR_MESSAGES_TOKEN: InjectionToken<ErrorMessages>;
+
+declare function provideErrorMessages(messages: ErrorMessages): Provider;
+declare function provideErrorMessagesLocale(locale: SupportedLocale, messages?: ErrorMessages): Provider;
+
+interface FieldError {
+    key: string;
+    message: string;
+}
+declare class FieldErrorsPipe implements PipeTransform {
+    private readonly globalMessages;
+    transform(control: AbstractControl | null | undefined, overrides?: ErrorMessages): FieldError[];
+    static ɵfac: i0.ɵɵFactoryDeclaration<FieldErrorsPipe, never>;
+    static ɵpipe: i0.ɵɵPipeDeclaration<FieldErrorsPipe, "fieldErrors", true>;
+}
+
+export { BUILT_IN_ERROR_MESSAGES, DEFAULT_VALIDATORS_TOKEN, ERROR_MESSAGES_TOKEN, FieldErrorsPipe, clearFileControl, entity, entityForm, patchFileControl, provideDefaultValidators, provideErrorMessages, provideErrorMessagesLocale };
+export type { ControlConfig, ControlOptions, DefaultValidatorsConfig, EntityFields, EntityForm, ErrorMessageFn, ErrorMessageValue, ErrorMessages, FieldError, GroupOptions, SupportedLocale };