@rxdi/forms 0.7.213 → 0.7.215

package/README.md

@@ -1,595 +1,353 @@
-# Reactive forms binding for LitHtml
+# Reactive Forms for LitHtml (Enhanced)
 
-#### Install
-```bash
-npm i @rxdi/forms
-```
+A lightweight, strongly-typed, reactive forms library for LitHtml applications.
 
+## Features
 
+- **Strict Typing**: Full TypeScript support with `UnwrapValue` and `NestedKeyOf` for deep property inference.
+- **Nested Forms**: Support for deep `FormGroup` nesting and `FormArray`.
+- **Automatic Binding**: Bind component models directly to forms with `@Form({ model: 'myModel' })`.
+- **Reactive**: based on `rxjs` `BehaviorSubject` for value streams.
+- **Recursive Updates**: `patchValue` updates deep structures recursively.
 
-#### Using it inside component
+## Installation
 
-##### Important!
-
-> Define `<form>` element with `name` `<form name"my-form"></form>`
+```bash
+npm i @rxdi/forms
+```
 
-> Put `my-form` inside @Form({ name: 'my-form' }) decorator since this will be our form selector
+## Basic Usage
 
+### 1. Define Model & Component
 
 ```typescript
-import { html, Component } from '@rxdi/lit-html';
-import { FormGroup, Form } from '@rxdi/forms';
-import { BaseComponent } from '../shared/base.component';
+import { html, Component, LitElement } from '@rxdi/lit-html';
+import { Form, FormGroup } from '@rxdi/forms';
+
+interface UserParams {
+  firstName: string;
+  address: {
+    city: string;
+    street: string;
+  };
+}
 
-/**
- * @customElement login-component
- */
 @Component({
-  selector: 'login-component',
-  template(this: LoginComponent) {
+  selector: 'user-profile',
+  template(this: UserProfile) {
     return html`
-      <form name="my-form" @submit=${this.onSubmit}>
+      <form name="user-form" @submit=${this.onSubmit}>
+        <!-- Deep Binding with Dot Notation -->
         <input
-          style="margin-bottom: 20px;"
-          name="email"
-          type="email"
-          value=${this.form.value.email}
-          placeholder="Email address"
-          required
-          autofocus
+          name="firstName"
+          .value=${this.form.value.firstName}
+          @blur=${() => this.requestUpdate()}
         />
+
+        <!-- Nested Group Binding -->
         <input
-          type="password"
-          value=${this.form.value.password}
-          name="password"
-          placeholder="Password"
-          required=""
+          name="address.city"
+          .value=${this.form.value.address.city}
+          @blur=${() => this.requestUpdate()}
         />
-        <div>
-          <label>
-            <input name="rememberMe" type="checkbox" /> Remember me
-          </label>
-        </div>
-        <button type="submit">
-          Sign in
-        </button>
+
+        <button type="submit">Save</button>
       </form>
     `;
-  }
+  },
 })
-export class LoginComponent extends BaseComponent {
+export class UserProfile extends LitElement {
+  // Model to bind
+  @property({ type: Object })
+  user: UserParams = {
+    firstName: 'John',
+    address: { city: 'New York', street: '5th Ave' },
+  };
+
   @Form({
+    name: 'user-form',
     strategy: 'change',
-    name: 'my-form'
+    model: 'user', // Automatic Model Binding!
   })
-  private form = new FormGroup({
-    password: '',
-    email: '',
-    rememberMe: ''
+  form = new FormGroup({
+    firstName: '',
+    address: new FormGroup({
+      city: '',
+      street: '',
+    }),
   });
 
-  OnInit() {
-    this.form.valueChanges.subscribe(values => {
-      values; // password, email, rememberMe
-    });
-    this.form.getValue('password');
-    this.form.setValue('email', 'blabla');
-  }
-
-  onSubmit(event: Event) {
-    this.form.values;
+  onSubmit(e: Event) {
+    e.preventDefault();
+    console.log(this.form.value);
+    // Output: { firstName: 'John', address: { city: 'New York', street: '5th Ave' } }
   }
 }
-
 ```
 
+## New Features
 
+### Automatic Model Binding
 
-#### Error handling and validators
+Use the `model` property in the `@Form` decorator to automatically populate the form from a component property.
 
 ```typescript
-import { html, Component } from '@rxdi/lit-html';
-import { FormGroup, Form } from '@rxdi/forms';
-import { BaseComponent } from '../shared/base.component';
-
-/**
- * @customElement login-component
- */
-@Component({
-  selector: 'login-component',
-  template(this: LoginComponent) {
-    return html`
-      <form name="my-form" @submit=${this.onSubmit}>
-        <input
-          style="margin-bottom: 20px;"
-          name="email"
-          type="email"
-          placeholder="Email address"
-          required
-          autofocus
-        />
-        ${this.form.hasError('email', 'blabla') ? html`${this.form.getError('email', 'blabla')}` : ''}
-        <input
-          type="password"
-          name="password"
-          placeholder="Password"
-          required=""
-        />
-        <div>
-          <label>
-            <input name="rememberMe" type="checkbox" /> Remember me
-          </label>
-        </div>
-        <button type="submit">
-          Sign in
-        </button>
-      </form>
-    `;
-  }
+@Form({
+  name: 'my-form',
+  model: 'myData' // matches this.myData
 })
-export class LoginComponent extends BaseComponent {
-  @Form({
-    strategy: 'change',
-    name: 'my-form'
-  })
-  private form = new FormGroup({
-    password: '',
-    email: ['', [this.validateEmail]],
-    rememberMe: ''
-  });
-
-  OnUpdate() {
-    this.form.getValue('password');
-    this.form.setValue('email', 'blabla');
+form = new FormGroup({ ... });
+```
 
-    this.form.get('password'); // returns HTMLIntputElement
-    this.form.hasError('email', 'blabla')
-  }
+The library reads `this.myData` during initialization and calls `form.patchValue(this.myData)`.
 
-  onSubmit(event: Event) {
-    this.form.values;
-  }
+### Nested FormGroups & FormArray
 
-  validateEmail(element: HTMLInputElement) {
-    if (element.value === 'restrictedEmail@gmail.com') {
-      return { key: 'blabla', message: 'Please specify different email'};
-    }
-  }
-}
+You can nest `FormGroup`s arbitrarily deep.
 
+```typescript
+form = new FormGroup({
+  meta: new FormGroup({
+    id: 1,
+    flags: new FormGroup({
+      isActive: true,
+      isAdmin: false,
+    }),
+  }),
+  tags: new FormArray([new FormGroup({ label: 'red' })]),
+});
 ```
 
+**Template Binding:**
+Use dot notation for nested controls:
 
+```html
+<input name="meta.flags.isActive" type="checkbox" />
+```
 
-#### Group multiple inputs with single check intaraction
+### Type Safety & Autosuggestion
 
-> By default all inputs with same attribute `name` are binded together,
+The library now extensively uses advanced TypeScript features:
+
+- **`form.value`**: Returns the unwrapped pure object type (e.g., `{ meta: { flags: { isActive: boolean } } }`).
+- **`form.get('path.to.prop')`**: Provides autocomplete for deep paths and infers return types!
+  - `form.get('key')` returns exact control type (e.g. `FormArray`) without casting.
 
 ```typescript
-  @Form({
-    strategy: 'change',
-    name: 'my-form'
-  })
-  private form = new FormGroup({
-    condition: ''
-  });
-```
+// TypeScript knows this is valid:
+this.form.get('meta.flags.isActive');
 
-```html
-<label>
-  <input
-    name="condition"
-    type="checkbox"
-    value='none'
-  />
-  None
-</label>
-
-<label>
-  <input
-    name="condition"
-    type="checkbox"
-    value='checked'
-  />
-  Checked
-</label>
-
-<label>
-  <input
-    name="condition"
-    type="checkbox"
-    value='not-checked'
-  />
-  Not checked
-</label>
+// And this is invalid:
+this.form.get('meta.flags.wrongProp'); // Error!
 ```
 
+### Recursive PatchValue
 
-#### Group multiple inputs with multi check intaraction
+Update multiple fields deeply at once:
 
+````typescript
+this.form.patchValue({
+  meta: {
+    flags: {
+      isActive: false
+    }
+  }
+});
+// Only updates 'isActive', leaves other fields untouched.
+### Dynamic Array Inputs (FormArray)
+
+For lists of primitive values, use `FormArray` with an `itemFactory` and automatic model binding. This removes the need for manual population.
 
-> To remove binding we can set `multi: false` when defining our form
+#### Full Working Example
 
 ```typescript
+import { Component, html, LitElement, property } from '@rxdi/lit-html';
+import { Form, FormGroup, FormArray } from '@rxdi/forms';
+
+
+@Component({
+  selector: 'tags-component',
+  template(this: TagsComponent) {
+    return html`
+      <form @submit=${(e) => e.preventDefault()}>
+        <h3>Tags</h3>
+
+        <!-- List Tags -->
+        ${this.form.get('tags').controls.map(
+          (control, index) => html`
+            <div class="tag-row">
+              <input name="tags[${index}].value" .value=${control.value.value} @blur=${() => this.requestUpdate()} />
+              <button type="button" @click=${() => this.removeTag(index)}>Remove</button>
+            </div>
+          `
+        )}
+
+        <button type="button" @click=${() => this.addTag()}>Add Tag</button>
+        <button type="button" @click=${() => this.onSubmit()}>Submit</button>
+      </form>
+    `;
+  },
+})
+export class TagsComponent extends LitElement {
+  // Model automatically binds to 'tags' in form
+  @property({ type: Array })
+  tags = ['news', 'tech'];
+
   @Form({
-    strategy: 'change',
-    name: 'my-form',
-    multi: false
+    name: 'tags-form',
+    model: 'tags', // Triggers form.patchValue(this.tags) on INIT
   })
-  private form = new FormGroup({
-    condition: ''
+  form = new FormGroup({
+    tags: new FormArray<{ value: string }>([], {
+      name: 'tags',
+      // Factory describes how to create new controls from model data
+      itemFactory: (value) => new FormGroup({ value: value.value || value }),
+    }),
   });
-```
 
+  addTag() {
+    this.form.get('tags').push(new FormGroup({ value: '' }));
+  }
 
+  removeTag(index: number) {
+    this.form.get('tags').removeAt(index);
+  }
 
-#### Native browser errors
+  onSubmit() {
+    const dirtyTags = this.form.value.tags;
+    console.log(dirtyTags.map((t) => t.value));
+  }
+}
 
-By default this library uses native error messages provided by HTML5 form validation API
+````
 
+## API Reference
 
-You can create your error template as follow:
+### Validators
 
-```typescript
-import { html } from '@rxdi/lit-html';
+Validators are async functions returning `InputErrorMessage` or `void`.
 
-export function InputErrorTemplate(input: HTMLInputElement | AbstractInput) {
-  // Check 'touched' to show errors only after interaction
-  // Check 'validity.valid' silently to avoid side effects
-  if (input && input.touched && !input.validity.valid) {
-    return html`
-      <div style="color:red; font-size: 13px;">${input.validationMessage}</div>
-    `;
+```typescript
+export function CustomValidator(element: AbstractInput) {
+  if (element.value === 'invalid') {
+    return { key: 'customError', message: 'Value is invalid' };
   }
-  return '';
 }
-```
 
-> **Note:** Using `!input.validity.valid` is preferred over `!input.checkValidity()` inside templates because `checkValidity()` fires an `invalid` event which can cause recursive validation loops.
+// Usage
+new FormGroup({
+  field: ['', [CustomValidator]],
+});
 ```
 
+### Error Display Information
 
-Usage
+Use the `touched` and `validity.valid` properties for clean UI.
 
-```html
-<form>
-  <input
-    name="email"
-    type="email"
-    value=${this.form.value.email}
-    class="form-control"
-    placeholder="Email address"
-    required
-    autofocus
-  />
-  ${InputErrorTemplate(this.form.get('email'))}
-</form>
+```typescript
+function ErrorTemplate(input: AbstractInput) {
+  if (input?.touched && !input.validity.valid) {
+    return html`<div class="error">${input.validationMessage}</div>`;
+  }
+  return html``;
+}
 ```
 
+## Advanced Usage
 
+### 1. Grouping Multiple Inputs (Checkbox Groups)
 
+By default, inputs with the same `name` attribute are treated as a single value (last write wins). However, for checkboxes, you often want an array of values.
 
-##### Native HTML with JS
+**Scenario:** A list of permissions where multiple can be selected.
 
 ```typescript
-
-import { FormGroup } from '@rxdi/forms';
-
-export function EmailValidator(element: HTMLInputElement) {
-  const regex = /^([a-zA-Z0-9_\.\-]+)@([a-zA-Z0-9_\.\-]+)\.([a-zA-Z]{2,5})$/;
-  if (!regex.test(element.value)) {
-    element.classList.add('is-invalid');
-    return {
-      key: 'email-validator',
-      message: 'Email is not valid'
-    };
-  }
-  element.classList.remove('is-invalid');
-}
-
-const form = new FormGroup({
-  email: ['', [EmailValidator]],
-  password: '',
+@Form({
+  name: 'permissions-form',
+  multi: true // Enable multi-value binding for same-name inputs
+})
+form = new FormGroup({
+  roles: [] // Will be an array of values
 });
-
-form
-  .setParentElement(document.body)
-  .setOptions({ name: 'my-form' })
-  .prepareValues()
-  .setFormElement(form.querySelectForm(document.body))
-  .setInputs(form.mapEventToInputs(form.querySelectorAllInputs()));
-
 ```
 
 ```html
-<form name="my-form">
-  <input
-    name="email"
-    type="email"
-    placeholder="Email address"
-    required
-    autofocus
-  />
-  <input
-    name="password"
-    type="password"
-    required
-  />
-</form>
-<script src="./main.ts"></script>
+<label> <input name="roles" type="checkbox" value="admin" /> Admin </label>
+<label> <input name="roles" type="checkbox" value="editor" /> Editor </label>
+<label> <input name="roles" type="checkbox" value="viewer" /> Viewer </label>
 ```
 
-#### Nested Forms (FormArray)
+If the user checks "Admin" and "Viewer", `form.value.roles` will be `['admin', 'viewer']`.
 
-You can create nested forms using `FormArray` and `FormGroup`.
+### 2. Single Selection Checkbox (Radio Behavior with Checkboxes)
 
-```typescript
-import { FormArray, FormGroup } from '@rxdi/forms';
+If you want multiple checkboxes to act like a radio button (only one valid at a time) but with uncheck capability:
 
-const form = new FormGroup({
-  users: new FormArray([
-    new FormGroup({
-      name: 'User 1',
-      email: 'user1@gmail.com'
-    })
-  ])
+```typescript
+@Form({
+  name: 'settings-form',
+  multi: false // Default behavior
+})
+form = new FormGroup({
+  mode: ''
 });
 ```
 
-Template usage:
-
 ```html
-${this.form.get('users').controls.map((group, index) => html`
-  <div>
-    <input
-      name="users[${index}].name"
-      .value=${group.value.name}
-    />
-    <input
-      name="users[${index}].email"
-      .value=${group.value.email}
-    />
-    <button @click=${() => this.removeUser(index)}>Remove</button>
-  </div>
-`)}
-<button @click=${() => this.addUser()}>Add User</button>
+<label> <input name="mode" type="checkbox" value="dark" /> Dark </label>
+<label> <input name="mode" type="checkbox" value="light" /> Light </label>
 ```
 
-Adding items dynamically:
-
-```typescript
-addUser() {
-  (this.form.get('users') as FormArray).push(
-    new FormGroup({ name: '', email: '' })
-  );
-}
-
-removeUser(index: number) {
-  (this.form.get('users') as FormArray).removeAt(index);
-}
-```
+Checking "Dark" unchecks "Light" automatically.
 
-#### Type Safety & Decorator Checking
+### 3. Framework-Agnostic Usage (Vanilla JS)
 
-The `@Form` decorator now proactively checks that the decorated property is strongly typed as `FormGroup`.
+You can use this library without Decorators or LitHtml, with any UI library or vanilla HTML.
 
 ```typescript
-export class MyComponent {
-  @Form({ name: 'my-form' })
-  form: FormGroup; // Must be typed as FormGroup!
-}
-```
-
-If you incorrectly type it (e.g., `form: string`), the library will throw a helpful error at runtime (requires `emitDecoratorMetadata: true` in `tsconfig`).
+import { FormGroup } from '@rxdi/forms';
 
-Validators are also type-safe using the `ValidatorFn` type:
+const form = new FormGroup({
+  email: '',
+  password: '',
+});
 
-```typescript
-import { ValidatorFn, AbstractInput, InputErrorMessage } from '@rxdi/forms';
+// manually attach to DOM
+const formElement = document.querySelector('form');
+form
+  .setParentElement(document.body)
+  .setOptions({ name: 'my-form' })
+  .setFormElement(formElement)
+  .prepareValues()
+  .setInputs(form.mapEventToInputs(form.querySelectorAllInputs()));
 
-const myValidator: ValidatorFn = async (element: AbstractInput) => {
-  // ... validation logic
-};
+// Listen to changes
+form.valueChanges.subscribe((val) => console.log(val));
 ```
 
-#### Complete Component Example
+### 4. Custom Error Handling Strategies
 
-Here is a complete, copy-pasteable example of a component using `@rxdi/forms` with best practices for validation and type safety.
+By default, verification happens on `change` or `blur`. You can control this via `strategy`.
 
 ```typescript
-import { Component, html, LitElement } from '@rxdi/lit-html';
-import { Form, FormGroup, AbstractInput } from '@rxdi/forms';
-
-/**
- * Helper to display errors safely.
- * Checks 'touched' (user interacted) and 'validity.valid' (silent check).
- */
-function ErrorTemplate(input: AbstractInput) {
-  if (input && input.touched && !input.validity.valid) {
-    return html`<div class="error">${input.validationMessage}</div>`;
-  }
-  return html``;
-}
-
-@Component({
-  selector: 'user-profile-form',
-  template(this: UserProfileForm) {
-    return html`
-      <form
-        name="user-form"
-        @submit=${(e: Event) => {
-          e.preventDefault();
-          console.log('Form Value:', this.form.value);
-        }}
-      >
-        <!-- Email Field -->
-        <div>
-          <label>Email</label>
-          <input
-            type="email"
-            name="email"
-            required
-            .value=${this.form.value.email}
-            @blur=${() => this.requestUpdate()} 
-          />
-          <!-- 
-            @blur triggers a re-render so 'touched' state is reflected.
-            The library handles 'touched' internally on blur, but we need 
-            to request an update to show the error message immediately.
-          -->
-          ${ErrorTemplate(this.form.get('email'))}
-        </div>
-
-        <!-- Password Field -->
-        <div>
-          <label>Password</label>
-          <input
-            type="password"
-            name="password"
-            required
-            minlength="6"
-            .value=${this.form.value.password}
-            @blur=${() => this.requestUpdate()}
-          />
-          ${ErrorTemplate(this.form.get('password'))}
-        </div>
-
-        <button type="submit" ?disabled=${this.form.invalid}>
-          Save Profile
-        </button>
-      </form>
-    `;
-  },
+@Form({
+  name: 'login',
+  strategy: 'input' // Validate on every keystroke
 })
-export class UserProfileForm extends LitElement {
-  @Form({
-    name: 'user-form', // Must match <form name="...">
-    strategy: 'change', // Validate on change/blur
-  })
-  form = new FormGroup({
-    email: '',
-    password: '',
-  });
-}
 ```
 
-### Key Takeaways for Templates
-
-1.  **Name Matching**: The `<form name="X">` attribute must match the `@Form({ name: 'X' })` name.
-2.  **Input Binding**: Use `.value=${this.form.value.fieldName}` to bind data. The library updates the model on user input automatically.
-3.  **Error Display**: Use a helper like `ErrorTemplate` that checks `.touched` and `.validity.valid`.
-    *   **Wait until touched**: `if (input.touched)` prevents errors from showing on load.
-    *   **Silent Check**: `!input.validity.valid` prevents side effects (looping).
-4.  **Re-rendering**: Since validation often updates on `blur`, ensure your component re-renders to show the error state (e.g., via `@blur=${() => this.requestUpdate()}` or generic event handlers).
-
-#### Complete Nested Form Example (FormArray)
-
-This example demonstrates managing a dynamic list of items (e.g., Team Members) using `FormArray`.
+You can also manually check error states (e.g. for async validation):
 
 ```typescript
-import { Component, html, LitElement } from '@rxdi/lit-html';
-import { Form, FormGroup, FormArray, AbstractInput } from '@rxdi/forms';
-
-function ErrorTemplate(input: AbstractInput) {
-  if (input && input.touched && !input.validity.valid) {
-    return html`<div class="error">${input.validationMessage}</div>`;
+async validateEmail(element: HTMLInputElement) {
+  const exists = await checkServer(element.value);
+  if (exists) {
+    return { key: 'emailExists', message: 'Email already taken' };
   }
-  return html``;
 }
 
-@Component({
-  selector: 'team-form',
-  template(this: TeamForm) {
-    return html`
-      <form @submit=${(e) => e.preventDefault()}>
-        
-        <!-- Main Form Field -->
-        <div>
-          <label>Team Name</label>
-          <input
-            name="teamName"
-            required
-            .value=${this.form.value.teamName}
-            @blur=${() => this.requestUpdate()}
-          />
-          ${ErrorTemplate(this.form.get('teamName'))}
-        </div>
-
-        <h3>Members</h3>
-        
-        <!-- FormArray Iteration -->
-        ${this.members.controls.map((control, index) => html`
-          <div class="member-row">
-            
-            <!-- Nested Field: Name -->
-            <!-- Notice the name syntax: arrayName[index].fieldName -->
-            <div class="field">
-              <input
-                placeholder="Member Name"
-                name="members[${index}].name" 
-                required
-                .value=${control.value.name}
-                @blur=${() => this.requestUpdate()}
-              />
-              <!-- Access nested control using .get() on the group -->
-              ${ErrorTemplate(control.get('name'))}
-            </div>
-
-            <!-- Nested Field: Role -->
-            <div class="field">
-              <input
-                placeholder="Role"
-                name="members[${index}].role"
-                required
-                .value=${control.value.role}
-                @blur=${() => this.requestUpdate()}
-              />
-              ${ErrorTemplate(control.get('role'))}
-            </div>
-
-            <button type="button" @click=${() => this.removeMember(index)}>
-              Remove
-            </button>
-          </div>
-        `)}
-
-        <button type="button" @click=${() => this.addMember()}>
-          Add Member
-        </button>
-
-        <button type="submit" ?disabled=${this.form.invalid}>
-          Submit Team
-        </button>
-      </form>
-    `;
-  },
-})
-export class TeamForm extends LitElement {
-  @Form({
-    name: 'team-form',
-    strategy: 'change',
-  })
-  form = new FormGroup({
-    teamName: '',
-    members: new FormArray<{ name: string; role: string }>([]),
-  });
-
-  // Helper to cast the control to FormArray for better typing
-  get members() {
-    return this.form.get('members') as FormArray;
-  }
-
-  addMember() {
-    this.members.push(
-      new FormGroup({
-        name: '',
-        role: '',
-      })
-    );
-  }
-
-  removeMember(index: number) {
-    this.members.removeAt(index);
-  }
-}
-```
+// In Template
+${this.form.hasError('email', 'emailExists')
+  ? html`<div class="error">Email taken!</div>`
+  : ''}
+```

package/dist/form.array.d.ts

@@ -1,6 +1,9 @@
 import { LitElement } from '@rxdi/lit-html';
 import { BehaviorSubject } from 'rxjs';
 import { AbstractControl, FormOptions } from './form.tokens';
+export interface FormArrayOptions<T = any> extends FormOptions {
+    itemFactory?: (value: T) => AbstractControl;
+}
 export declare class FormArray<T = any> implements AbstractControl<T[]> {
     controls: AbstractControl<T>[];
     readonly valueChanges: BehaviorSubject<T[]>;
@@ -13,9 +16,9 @@ export declare class FormArray<T = any> implements AbstractControl<T[]> {
     private form;
     private options;
     private subscriptions;
-    constructor(controls?: AbstractControl<T>[], name?: string);
+    constructor(controls?: AbstractControl<T>[], nameOrOptions?: string | FormArrayOptions<T>);
     get value(): T[];
-    getOptions(): FormOptions;
+    getOptions(): FormArrayOptions<T>;
     setOptions(options: FormOptions): void;
     push(control: AbstractControl<T>): Promise<void>;
     removeAt(index: number): void;
@@ -28,4 +31,5 @@ export declare class FormArray<T = any> implements AbstractControl<T[]> {
     init(): void;
     getParentElement(): LitElement;
     set value(values: T[]);
+    patchValue(values: T[]): void;
 }

package/dist/form.array.js

@@ -12,7 +12,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.FormArray = void 0;
 const rxjs_1 = require("rxjs");
 class FormArray {
-    constructor(controls = [], name = '') {
+    constructor(controls = [], nameOrOptions = '') {
         this.controls = [];
         this.valid = true;
         this.invalid = false;
@@ -20,7 +20,13 @@ class FormArray {
         this.options = {};
         this.subscriptions = new Map();
         this.controls = controls;
-        this.name = name;
+        if (typeof nameOrOptions === 'string') {
+            this.name = nameOrOptions;
+        }
+        else {
+            this.name = nameOrOptions.name || '';
+            this.options = nameOrOptions;
+        }
         this._valueChanges = new rxjs_1.BehaviorSubject(this.value);
         this.valueChanges = this._valueChanges;
         this.controls.forEach((c) => this.subscribeToControl(c));
@@ -32,7 +38,7 @@ class FormArray {
         return this.options;
     }
     setOptions(options) {
-        this.options = options;
+        this.options = Object.assign(Object.assign({}, this.options), options);
         this.controls.forEach((c, index) => {
             c.setOptions(Object.assign(Object.assign({}, options), { namespace: `${this.name}[${index}]` }));
         });
@@ -106,6 +112,7 @@ class FormArray {
     getParentElement() {
         return this.parentElement;
     }
+    // eslint-disable-next-line @typescript-eslint/adjacent-overload-signatures
     set value(values) {
         if (!Array.isArray(values)) {
             return;
@@ -117,5 +124,24 @@ class FormArray {
         });
         this.updateValue();
     }
+    patchValue(values) {
+        if (!Array.isArray(values)) {
+            return;
+        }
+        values.forEach((v, i) => {
+            if (this.controls[i]) {
+                if (this.controls[i]['patchValue']) {
+                    this.controls[i]['patchValue'](v);
+                }
+                else {
+                    this.controls[i].value = v;
+                }
+            }
+            else if (this.options.itemFactory) {
+                this.push(this.options.itemFactory(v));
+            }
+        });
+        this.updateValue();
+    }
 }
 exports.FormArray = FormArray;

package/dist/form.decorator.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Form = Form;
-const form_group_1 = require("./form.group");
+/* eslint-disable @typescript-eslint/no-explicit-any */
 const rxjs_1 = require("rxjs");
+const form_group_1 = require("./form.group");
 function Form(options = {
     strategy: 'none',
 }) {
@@ -18,6 +19,9 @@ function Form(options = {
                 throw new Error('Value provided is not an instance of FormGroup!');
             }
             this[name].setParentElement(this).setOptions(options).prepareValues();
+            if (options.model && this[options.model]) {
+                this[name].patchValue(this[options.model]);
+            }
             return Connect.call(this);
         };
         clazz.constructor.prototype.firstUpdated = function () {

package/dist/form.group.d.ts

@@ -1,12 +1,12 @@
 import { LitElement } from '@rxdi/lit-html';
-import { AbstractControl, AbstractInput, ErrorObject, FormInputOptions, FormOptions, ValidatorFn } from './form.tokens';
+import { AbstractControl, AbstractInput, ErrorObject, FormInputOptions, FormOptions, NestedKeyOf, UnwrapValue, ValidatorFn, DeepPropType } from './form.tokens';
 export declare class FormGroup<T = FormInputOptions, E = {
     [key: string]: never;
-}> implements AbstractControl<T> {
+}> implements AbstractControl<UnwrapValue<T>> {
     validators: Map<string, ValidatorFn[]>;
     valid: boolean;
     invalid: boolean;
-    errors: T;
+    errors: UnwrapValue<T>;
     private controls;
     private readonly _valueChanges;
     private form;
@@ -22,7 +22,7 @@ export declare class FormGroup<T = FormInputOptions, E = {
     getParentElement(): LitElement;
     setOptions(options: FormOptions): this;
     getOptions(): FormOptions;
-    get valueChanges(): import("rxjs").Observable<T>;
+    get valueChanges(): import("rxjs").Observable<UnwrapValue<T>>;
     updateValueAndValidity(): Promise<(ErrorObject | {
         message: string;
     })[]>;
@@ -38,18 +38,19 @@ export declare class FormGroup<T = FormInputOptions, E = {
     private getModelKeyName;
     validate(element: AbstractInput): Promise<ErrorObject>;
     private mapInputErrors;
-    get(name: keyof T): AbstractControl<any> | AbstractInput;
+    get<K extends NestedKeyOf<T>>(name: K): DeepPropType<T, K>;
     getError(inputName: keyof T, errorKey: string): never;
     hasError(inputName: keyof T, errorKey: string): boolean;
     reset(): void;
     setFormValidity(validity?: boolean): void;
     resetErrors(): void;
-    get value(): T;
-    set value(value: T);
+    get value(): UnwrapValue<T>;
+    set value(value: UnwrapValue<T>);
     unsubscribe(): void;
     getValue(name: keyof T): T[keyof T];
+    patchValue(value: Partial<UnwrapValue<T>>): void;
     setValue(name: keyof T, value: unknown): void;
-    setFormValue(value: T): void;
+    setFormValue(value: UnwrapValue<T>): void;
     setFormElement(form: HTMLFormElement): this;
     setInputs(inputs: AbstractInput[]): void;
     getFormElement(): HTMLFormElement;

package/dist/form.group.js

@@ -26,7 +26,10 @@ class FormGroup {
         this._valueChanges = new rxjs_1.BehaviorSubject(value);
         if (value) {
             Object.keys(value).forEach((key) => {
-                if (typeof value[key] === 'object' && value[key] !== null && (value[key]['controls'] || value[key]['push'])) {
+                if (typeof value[key] === 'object' &&
+                    value[key] !== null &&
+                    (value[key]['controls'] || value[key]['push']) &&
+                    value[key]['valueChanges']) {
                     // It's likely a FormGroup or FormArray
                     const control = value[key];
                     if (control.name === '' || control.name === undefined) {
@@ -63,7 +66,12 @@ class FormGroup {
                         this.validators.set(v, [...oldValidators, val]);
                     });
                 }
-                if (value[0].constructor === String || value[0].constructor === Number || value[0].constructor === Boolean) {
+                if (value[0] === undefined || value[0] === null) {
+                    this.value[v] = '';
+                }
+                else if (value[0].constructor === String ||
+                    value[0].constructor === Number ||
+                    value[0].constructor === Boolean) {
                     this.value[v] = value[0];
                 }
                 else {
@@ -88,8 +96,9 @@ class FormGroup {
     setOptions(options) {
         this.options = options;
         this.controls.forEach((c) => {
-            if (c.setOptions)
-                c.setOptions(options);
+            if (c.setOptions) {
+                c.setOptions(Object.assign(Object.assign({}, options), { namespace: this.options.namespace ? `${this.options.namespace}.${c.name}` : c.name }));
+            }
         });
         return this;
     }
@@ -322,6 +331,14 @@ class FormGroup {
         if (this.controls.has(name)) {
             return this.controls.get(name);
         }
+        if (String(name).includes('.')) {
+            const names = String(name).split('.');
+            const key = names.shift();
+            const control = this.controls.get(key);
+            if (control && control.get) {
+                return control.get(names.join('.'));
+            }
+        }
         return this.inputs.get(name);
     }
     getError(inputName, errorKey) {
@@ -368,6 +385,19 @@ class FormGroup {
     getValue(name) {
         return this.value[name];
     }
+    patchValue(value) {
+        if (!value) {
+            return;
+        }
+        Object.keys(value).forEach((key) => {
+            if (this.controls.has(key) && this.controls.get(key)['patchValue']) {
+                this.controls.get(key)['patchValue'](value[key]);
+            }
+            else {
+                this.setValue(key, value[key]);
+            }
+        });
+    }
     setValue(name, value) {
         const input = this.get(name);
         if (!input) {

package/dist/form.tokens.d.ts

@@ -1,5 +1,15 @@
 import { LitElement } from '@rxdi/lit-html';
 import { Observable } from 'rxjs';
+export type UnwrapValue<T> = T extends AbstractControl<infer U> ? U : T extends {
+    [key: string]: any;
+} ? {
+    [K in keyof T]: UnwrapValue<T[K]>;
+} : T;
+type Prev = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, ...0[]];
+export type NestedKeyOf<T, D extends number = 3> = [D] extends [0] ? never : T extends object ? {
+    [K in keyof T & (string | number)]: T[K] extends AbstractControl<infer U> ? U extends object ? `${K}` | `${K}.${NestedKeyOf<U, Prev[D]>}` : `${K}` : T[K] extends object ? `${K}` | `${K}.${NestedKeyOf<T[K], Prev[D]>}` : `${K}`;
+}[keyof T & (string | number)] : never;
+export type DeepPropType<T, P extends string> = P extends keyof T ? T[P] : P extends `${infer K}.${infer R}` ? K extends keyof T ? DeepPropType<T[K], R> : any : any;
 export type FormStrategies = keyof WindowEventMap;
 export interface FormOptions {
     /** Name of the form element */
@@ -20,6 +30,10 @@ export interface FormOptions {
      * Internal property for handling nested forms.
      */
     namespace?: string;
+    /**
+     * Property name of the model to bind to the form
+     */
+    model?: string;
 }
 export interface AbstractControl<T = any> {
     setOptions(options: FormOptions): this | void;
@@ -69,3 +83,4 @@ export declare const InputValidityState: {
     valueMissing: "valueMissing";
 };
 export type InputValidityState = keyof typeof InputValidityState;
+export {};

package/package.json

@@ -1,27 +1,27 @@
 {
- "name": "@rxdi/forms",
- "version": "0.7.213",
- "main": "./dist/index.js",
- "author": "Kristiyan Tachev",
- "license": "MIT",
- "repository": {
-  "type": "git",
-  "url": "https://github.com/rxdi/forms"
- },
- "scripts": {
-  "build": "tsc"
- },
- "devDependencies": {
-  "@rxdi/lit-html": "^0.7.212",
-  "@types/node": "^25.0.3",
-  "rxjs": "^7.8.2",
-  "typescript": "^5.9.3"
- },
- "peerDependencies": {
-  "rxjs": "^7.8.2",
-  "@rxdi/lit-html": "*"
- },
- "types": "./dist/index.d.ts",
- "module": "./dist/index.js",
- "typings": "./dist/index.d.ts"
+  "name": "@rxdi/forms",
+  "version": "0.7.215",
+  "main": "./dist/index.js",
+  "author": "Kristiyan Tachev",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rxdi/forms"
+  },
+  "scripts": {
+    "build": "tsc"
+  },
+  "devDependencies": {
+    "@rxdi/lit-html": "^0.7.214",
+    "@types/node": "^25.0.3",
+    "rxjs": "^7.8.2",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "rxjs": "^7.8.2",
+    "@rxdi/lit-html": "*"
+  },
+  "types": "./dist/index.d.ts",
+  "module": "./dist/index.js",
+  "typings": "./dist/index.d.ts"
 }