@rxdi/forms 0.7.212 → 0.7.214

package/README.md

@@ -1,315 +1,290 @@
-# Reactive forms binding for LitHtml
-
-#### Install
-```bash
-npm i @rxdi/forms
-```
+# Reactive Forms for LitHtml (Enhanced)
 
+A lightweight, strongly-typed, reactive forms library for LitHtml applications.
 
+## Features
 
-#### Using it inside component
+- **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.
 
-##### Important!
+## Installation
 
-> 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
+Use the `model` property in the `@Form` decorator to automatically populate the form from a component property.
+
+```typescript
+@Form({
+  name: 'my-form',
+  model: 'myData' // matches this.myData
+})
+form = new FormGroup({ ... });
 ```
+The library reads `this.myData` during initialization and calls `form.patchValue(this.myData)`.
 
+### Nested FormGroups & FormArray
+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' })
+  ])
+});
+```
 
-#### Error handling and validators
+**Template Binding:**
+Use dot notation for nested controls:
+```html
+<input name="meta.flags.isActive" type="checkbox" />
+```
 
+### Type Safety & Autosuggestion
+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!
 ```typescript
-import { html, Component } from '@rxdi/lit-html';
-import { FormGroup, Form } from '@rxdi/forms';
-import { BaseComponent } from '../shared/base.component';
+// TypeScript knows this is valid:
+this.form.get('meta.flags.isActive');
 
-/**
- * @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>
-    `;
-  }
-})
-export class LoginComponent extends BaseComponent {
-  @Form({
-    strategy: 'change',
-    name: 'my-form'
-  })
-  private form = new FormGroup({
-    password: '',
-    email: ['', [this.validateEmail]],
-    rememberMe: ''
-  });
+// And this is invalid:
+this.form.get('meta.flags.wrongProp'); // Error!
+```
 
-  OnUpdate() {
-    this.form.getValue('password');
-    this.form.setValue('email', 'blabla');
+### Recursive PatchValue
+Update multiple fields deeply at once:
 
-    this.form.get('password'); // returns HTMLIntputElement
-    this.form.hasError('email', 'blabla')
+```typescript
+this.form.patchValue({
+  meta: {
+    flags: {
+      isActive: false
+    }
   }
+});
+// Only updates 'isActive', leaves other fields untouched.
+```
 
-  onSubmit(event: Event) {
-    this.form.values;
-  }
+## API Reference
 
-  validateEmail(element: HTMLInputElement) {
-    if (element.value === 'restrictedEmail@gmail.com') {
-      return { key: 'blabla', message: 'Please specify different email'};
-    }
+### Validators
+Validators are async functions returning `InputErrorMessage` or `void`.
+
+```typescript
+export function CustomValidator(element: AbstractInput) {
+  if (element.value === 'invalid') {
+    return { key: 'customError', message: 'Value is invalid' };
   }
 }
 
+// Usage
+new FormGroup({
+  field: ['', [CustomValidator]]
+})
+```
+
+### Error Display Information
+Use the `touched` and `validity.valid` properties for clean UI.
+
+```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)
 
-#### Group multiple inputs with single check intaraction
+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.
 
-> By default all inputs with same attribute `name` are binded together,
+**Scenario:** A list of permissions where multiple can be selected.
 
 ```typescript
-  @Form({
-    strategy: 'change',
-    name: 'my-form'
-  })
-  private form = new FormGroup({
-    condition: ''
-  });
+@Form({
+  name: 'permissions-form',
+  multi: true // Enable multi-value binding for same-name inputs
+})
+form = new FormGroup({
+  roles: [] // Will be an array of values
+});
 ```
 
 ```html
 <label>
-  <input
-    name="condition"
-    type="checkbox"
-    value='none'
-  />
-  None
+  <input name="roles" type="checkbox" value="admin" /> Admin
 </label>
-
 <label>
-  <input
-    name="condition"
-    type="checkbox"
-    value='checked'
-  />
-  Checked
+  <input name="roles" type="checkbox" value="editor" /> Editor
 </label>
-
 <label>
-  <input
-    name="condition"
-    type="checkbox"
-    value='not-checked'
-  />
-  Not checked
+  <input name="roles" type="checkbox" value="viewer" /> Viewer
 </label>
 ```
 
+If the user checks "Admin" and "Viewer", `form.value.roles` will be `['admin', 'viewer']`.
 
-#### Group multiple inputs with multi check intaraction
-
+### 2. Single Selection Checkbox (Radio Behavior with Checkboxes)
 
-> To remove binding we can set `multi: false` when defining our form
+If you want multiple checkboxes to act like a radio button (only one valid at a time) but with uncheck capability:
 
 ```typescript
-  @Form({
-    strategy: 'change',
-    name: 'my-form',
-    multi: false
-  })
-  private form = new FormGroup({
-    condition: ''
-  });
-```
-
-
-
-#### Native browser errors
-
-By default this library uses native error messages provided by HTML5 form validation API
-
-
-You can create your error template as follow:
-
-```typescript
-import { html } from '@rxdi/lit-html';
-
-export function InputErrorTemplate(input: HTMLInputElement) {
-  if (input && !input.checkValidity()) {
-    return html`
-      <div>${input.validationMessage}</div>
-    `;
-  }
-  return '';
-}
+@Form({
+  name: 'settings-form',
+  multi: false // Default behavior
+})
+form = new FormGroup({
+  mode: ''
+});
 ```
 
-
-Usage
-
 ```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>
+<label>
+  <input name="mode" type="checkbox" value="dark" /> Dark
+</label>
+<label>
+  <input name="mode" type="checkbox" value="light" /> Light
+</label>
 ```
+Checking "Dark" unchecks "Light" automatically.
 
+### 3. Framework-Agnostic Usage (Vanilla JS)
 
-
-
-##### Native HTML with JS
+You can use this library without Decorators or LitHtml, with any UI library or vanilla HTML.
 
 ```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: '',
+  email: '',
+  password: ''
 });
 
+// manually attach to DOM
+const formElement = document.querySelector('form');
 form
   .setParentElement(document.body)
   .setOptions({ name: 'my-form' })
+  .setFormElement(formElement)
   .prepareValues()
-  .setFormElement(form.querySelectForm(document.body))
   .setInputs(form.mapEventToInputs(form.querySelectorAllInputs()));
 
+// Listen to changes
+form.valueChanges.subscribe(val => console.log(val));
 ```
 
-```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>
+### 4. Custom Error Handling Strategies
+
+By default, verification happens on `change` or `blur`. You can control this via `strategy`.
+
+```typescript
+@Form({
+  name: 'login',
+  strategy: 'input' // Validate on every keystroke
+})
+```
+
+You can also manually check error states (e.g. for async validation):
+
+```typescript
+async validateEmail(element: HTMLInputElement) {
+  const exists = await checkServer(element.value);
+  if (exists) {
+    return { key: 'emailExists', message: 'Email already taken' };
+  }
+}
+
+// In Template
+${this.form.hasError('email', 'emailExists') 
+  ? html`<div class="error">Email taken!</div>` 
+  : ''}
 ```

package/dist/form.array.d.ts

@@ -0,0 +1,31 @@
+import { LitElement } from '@rxdi/lit-html';
+import { BehaviorSubject } from 'rxjs';
+import { AbstractControl, FormOptions } from './form.tokens';
+export declare class FormArray<T = any> implements AbstractControl<T[]> {
+    controls: AbstractControl<T>[];
+    readonly valueChanges: BehaviorSubject<T[]>;
+    private readonly _valueChanges;
+    parentElement: LitElement;
+    name: string;
+    valid: boolean;
+    invalid: boolean;
+    errors: {};
+    private form;
+    private options;
+    private subscriptions;
+    constructor(controls?: AbstractControl<T>[], name?: string);
+    get value(): T[];
+    getOptions(): FormOptions;
+    setOptions(options: FormOptions): void;
+    push(control: AbstractControl<T>): Promise<void>;
+    removeAt(index: number): void;
+    private subscribeToControl;
+    unsubscribe(): void;
+    updateValue(): void;
+    requestUpdate(): void;
+    setParentElement(parent: LitElement): void;
+    setFormElement(form: HTMLFormElement): void;
+    init(): void;
+    getParentElement(): LitElement;
+    set value(values: T[]);
+}

package/dist/form.array.js

@@ -0,0 +1,122 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FormArray = void 0;
+const rxjs_1 = require("rxjs");
+class FormArray {
+    constructor(controls = [], name = '') {
+        this.controls = [];
+        this.valid = true;
+        this.invalid = false;
+        this.errors = {};
+        this.options = {};
+        this.subscriptions = new Map();
+        this.controls = controls;
+        this.name = name;
+        this._valueChanges = new rxjs_1.BehaviorSubject(this.value);
+        this.valueChanges = this._valueChanges;
+        this.controls.forEach((c) => this.subscribeToControl(c));
+    }
+    get value() {
+        return this.controls.map((c) => c.value);
+    }
+    getOptions() {
+        return this.options;
+    }
+    setOptions(options) {
+        this.options = options;
+        this.controls.forEach((c, index) => {
+            c.setOptions(Object.assign(Object.assign({}, options), { namespace: `${this.name}[${index}]` }));
+        });
+    }
+    push(control) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.controls.push(control);
+            this.subscribeToControl(control);
+            const index = this.controls.length - 1;
+            control.setOptions(Object.assign(Object.assign(Object.assign({}, this.options), control.getOptions()), { namespace: `${this.name}[${index}]` }));
+            this.updateValue();
+            this.requestUpdate();
+            if (this.parentElement) {
+                yield this.parentElement.updateComplete;
+                control.setParentElement(this.parentElement);
+                if (this.form) {
+                    control.setFormElement(this.form);
+                    control.init();
+                }
+                else if (control.getFormElement()) {
+                    control.init();
+                }
+                else if (this.controls[0] && this.controls[0].getFormElement()) {
+                    control.setFormElement(this.controls[0].getFormElement());
+                    control.init();
+                }
+            }
+        });
+    }
+    removeAt(index) {
+        const control = this.controls[index];
+        if (this.subscriptions.has(control)) {
+            this.subscriptions.get(control).unsubscribe();
+            this.subscriptions.delete(control);
+        }
+        this.controls.splice(index, 1);
+        this.updateValue();
+        this.requestUpdate();
+    }
+    subscribeToControl(control) {
+        if (control.valueChanges) {
+            this.subscriptions.set(control, control.valueChanges.subscribe(() => {
+                this.updateValue();
+            }));
+        }
+    }
+    unsubscribe() {
+        this.subscriptions.forEach((sub) => sub.unsubscribe());
+        this.subscriptions.clear();
+        this.controls.forEach((c) => c.unsubscribe && c.unsubscribe());
+    }
+    updateValue() {
+        this._valueChanges.next(this.value);
+    }
+    requestUpdate() {
+        if (this.parentElement) {
+            this.parentElement.requestUpdate();
+        }
+    }
+    setParentElement(parent) {
+        this.parentElement = parent;
+        this.controls.forEach((c) => c.setParentElement(parent));
+    }
+    setFormElement(form) {
+        this.form = form;
+        this.controls.forEach((c) => c.setFormElement(form));
+    }
+    init() {
+        this.controls.forEach((c) => c.init());
+    }
+    getParentElement() {
+        return this.parentElement;
+    }
+    // eslint-disable-next-line @typescript-eslint/adjacent-overload-signatures
+    set value(values) {
+        if (!Array.isArray(values)) {
+            return;
+        }
+        values.forEach((v, i) => {
+            if (this.controls[i]) {
+                this.controls[i].value = v;
+            }
+        });
+        this.updateValue();
+    }
+}
+exports.FormArray = FormArray;

package/dist/form.decorator.d.ts

@@ -1,2 +1,2 @@
 import { FormOptions } from './form.tokens';
-export declare function Form(options?: FormOptions): (clazz: Object, name: string | number | symbol) => void;
+export declare function Form(options?: FormOptions): (clazz: any, name: string | number | symbol) => void;