@toolbox-web/grid-angular 1.9.0 → 2.0.0-beta

package/fesm2022/toolbox-web-grid-angular-features-editing.mjs

@@ -1,8 +1,691 @@
-import { registerFeatureClaim, claimEvent, unregisterFeatureClaim, unclaimEvent, registerEditorMountHook, makeFlushFocusedInput } from '@toolbox-web/grid-angular';
-export { BaseGridEditor, BaseGridEditorCVA, BaseOverlayEditor, GridColumnEditor, GridFormArray, GridLazyForm, TbwEditor, getFormArrayContext, getLazyFormContext } from '@toolbox-web/grid-angular';
+import { registerFeatureClaim, claimEvent, unregisterFeatureClaim, unclaimEvent, registerEditorSpecBridge, registerEditorMountHook, makeFlushFocusedInput } from '@toolbox-web/grid-angular';
 import '@toolbox-web/grid/features/editing';
 import * as i0 from '@angular/core';
-import { inject, ElementRef, input, output, Directive } from '@angular/core';
+import { inject, ElementRef, contentChild, TemplateRef, effect, Directive, DestroyRef, input, output, computed, afterNextRender, signal } from '@angular/core';
+import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
+import { FormGroup } from '@angular/forms';
+import { startWith, debounceTime } from 'rxjs/operators';
+
+// Global registry mapping DOM elements to their templates
+const editorTemplateRegistry = new Map();
+/**
+ * Gets the editor template registered for a given element.
+ * Used by AngularGridAdapter to retrieve templates at render time.
+ */
+function getEditorTemplate(element) {
+    return editorTemplateRegistry.get(element);
+}
+/**
+ * Directive that captures an `<ng-template>` for use as a cell editor.
+ *
+ * This enables declarative Angular component usage with proper input bindings
+ * that satisfy Angular's AOT compiler.
+ *
+ * ## Usage
+ *
+ * ```html
+ * <tbw-grid-column field="status" editable>
+ *   <tbw-grid-column-editor>
+ *     <ng-template let-value let-row="row" let-onCommit="onCommit" let-onCancel="onCancel">
+ *       <app-status-select
+ *         [value]="value"
+ *         [row]="row"
+ *         (commit)="onCommit($event)"
+ *         (cancel)="onCancel()"
+ *       />
+ *     </ng-template>
+ *   </tbw-grid-column-editor>
+ * </tbw-grid-column>
+ * ```
+ *
+ * The template context provides:
+ * - `$implicit` / `value`: The cell value
+ * - `row`: The full row data object
+ * - `column`: The column configuration
+ * - `onCommit`: Callback function to commit the new value
+ * - `onCancel`: Callback function to cancel editing
+ *
+ * Import the directive in your component:
+ *
+ * ```typescript
+ * import { GridColumnEditor } from '@toolbox-web/grid-angular/features/editing';
+ *
+ * @Component({
+ *   imports: [GridColumnEditor],
+ *   // ...
+ * })
+ * ```
+ *
+ * @category Directive
+ *
+ * @since 0.1.0
+ */
+class GridColumnEditor {
+    elementRef = inject((ElementRef));
+    /**
+     * Query for the ng-template content child.
+     */
+    template = contentChild((TemplateRef), ...(ngDevMode ? [{ debugName: "template" }] : /* istanbul ignore next */ []));
+    /** Effect that triggers when the template is available */
+    onTemplateReceived = effect(() => {
+        const template = this.template();
+        if (template) {
+            // Register the template for this element
+            editorTemplateRegistry.set(this.elementRef.nativeElement, template);
+        }
+    }, ...(ngDevMode ? [{ debugName: "onTemplateReceived" }] : /* istanbul ignore next */ []));
+    /**
+     * Static type guard for template context.
+     * Enables type inference in templates.
+     */
+    static ngTemplateContextGuard(dir, ctx) {
+        return true;
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.5", ngImport: i0, type: GridColumnEditor, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.2.0", version: "21.2.5", type: GridColumnEditor, isStandalone: true, selector: "tbw-grid-column-editor", queries: [{ propertyName: "template", first: true, predicate: (TemplateRef), descendants: true, isSignal: true }], ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.5", ngImport: i0, type: GridColumnEditor, decorators: [{
+            type: Directive,
+            args: [{ selector: 'tbw-grid-column-editor' }]
+        }], propDecorators: { template: [{ type: i0.ContentChild, args: [i0.forwardRef(() => TemplateRef), { isSignal: true }] }] } });
+
+// Symbol for storing form context on the grid element
+const FORM_ARRAY_CONTEXT$1 = Symbol('formArrayContext');
+/**
+ * Gets the FormArrayContext from a grid element, if present.
+ * @internal
+ * @since 0.5.0
+ */
+function getFormArrayContext(gridElement) {
+    return gridElement[FORM_ARRAY_CONTEXT$1];
+}
+/**
+ * Directive that binds a FormArray directly to the grid.
+ *
+ * This is the recommended way to integrate tbw-grid with Angular Reactive Forms.
+ * Use a FormArray of FormGroups for row-level validation and cell-level control access.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { Component, inject } from '@angular/core';
+ * import { FormBuilder, ReactiveFormsModule } from '@angular/forms';
+ * import { Grid, GridFormArray } from '@toolbox-web/grid-angular/features/editing';
+ *
+ * @Component({
+ *   imports: [Grid, GridFormArray, ReactiveFormsModule],
+ *   template: \`
+ *     <form [formGroup]="form">
+ *       <tbw-grid [formArray]="form.controls.rows" [columns]="columns" />
+ *     </form>
+ *   \`
+ * })
+ * export class MyComponent {
+ *   private fb = inject(FormBuilder);
+ *
+ *   form = this.fb.group({
+ *     rows: this.fb.array([
+ *       this.fb.group({ name: 'Alice', age: 30 }),
+ *       this.fb.group({ name: 'Bob', age: 25 }),
+ *     ])
+ *   });
+ *
+ *   columns = [
+ *     { field: 'name', header: 'Name', editable: true },
+ *     { field: 'age', header: 'Age', editable: true }
+ *   ];
+ * }
+ * ```
+ *
+ * ## How It Works
+ *
+ * - **FormArray → Grid**: The grid displays the FormArray's value as rows
+ * - **Grid → FormArray**: When a cell is edited, the corresponding FormControl is updated
+ * - FormArrayContext is available for accessing cell-level controls
+ *
+ * ## Features
+ *
+ * - Works naturally with FormArray inside a FormGroup
+ * - Provides cell-level FormControl access for validation
+ * - Supports row-level validation state aggregation
+ * - Automatically syncs FormArray changes to the grid
+ *
+ * @example
+ * ```html
+ * <form [formGroup]="form">
+ *   <tbw-grid [formArray]="form.controls.rows" [columns]="columns" />
+ * </form>
+ * ```
+ *
+ * @category Directive
+ *
+ * @since 0.5.0
+ */
+class GridFormArray {
+    destroyRef = inject(DestroyRef);
+    elementRef = inject((ElementRef));
+    cellCommitUnsub = null;
+    cellCancelUnsub = null;
+    rowCommitUnsub = null;
+    touchListener = null;
+    valueChangesSubscription = null;
+    statusChangesSubscriptions = [];
+    /**
+     * The FormArray to bind to the grid.
+     */
+    formArray = input.required(...(ngDevMode ? [{ debugName: "formArray" }] : /* istanbul ignore next */ []));
+    /**
+     * Whether to automatically sync Angular validation state to grid's visual invalid styling.
+     *
+     * When enabled:
+     * - After a cell commit, if the FormControl is invalid, the cell is marked with `setInvalid()`
+     * - When a FormControl becomes valid, `clearInvalid()` is called
+     * - On `row-commit`, if the row's FormGroup has invalid controls, the commit is prevented
+     * - In grid mode: validation state is synced on initial render and updated reactively
+     *
+     * @default true
+     */
+    syncValidation = input(true, ...(ngDevMode ? [{ debugName: "syncValidation" }] : /* istanbul ignore next */ []));
+    /**
+     * Effect that sets up valueChanges subscription when FormArray changes.
+     * This handles both initial binding and when the FormArray reference changes.
+     */
+    syncFormArrayToGrid = effect(() => {
+        const formArray = this.formArray();
+        const grid = this.elementRef.nativeElement;
+        if (!grid || !formArray)
+            return;
+        // Unsubscribe from previous FormArray if any
+        this.valueChangesSubscription?.unsubscribe();
+        // Subscribe to valueChanges to sync grid rows when FormArray content changes.
+        // Use startWith to immediately sync the current value.
+        // Note: We use getRawValue() to include disabled controls.
+        //
+        // In grid mode, editors bind directly to FormControls, so every keystroke
+        // fires valueChanges. We skip the sync when an editor input is focused to
+        // prevent destroying/recreating editors mid-edit (which orphans overlays
+        // like mat-autocomplete/mat-select panels and causes focus loss).
+        this.valueChangesSubscription = formArray.valueChanges
+            .pipe(startWith(formArray.getRawValue()), takeUntilDestroyed(this.destroyRef))
+            .subscribe(() => {
+            // Skip sync while an editor is actively focused in the grid.
+            // The FormArray already has the latest values via its own controls;
+            // re-setting grid.rows would create new object references and trigger
+            // an unnecessary render cycle.
+            if (this.#isEditorFocused(grid))
+                return;
+            grid.rows = formArray.getRawValue();
+        });
+    }, ...(ngDevMode ? [{ debugName: "syncFormArrayToGrid" }] : /* istanbul ignore next */ []));
+    ngOnInit() {
+        const grid = this.elementRef.nativeElement;
+        if (!grid)
+            return;
+        // Store the form context on the grid element for other directives to access
+        this.#storeFormContext(grid);
+        // Intercept cell-commit events to update the FormArray
+        this.cellCommitUnsub = grid.on('cell-commit', (detail) => {
+            this.#handleCellCommit(detail);
+        });
+        // Intercept cell-cancel events to revert FormControls (grid mode Escape)
+        this.cellCancelUnsub = grid.on('cell-cancel', (detail) => {
+            this.#handleCellCancel(detail);
+        });
+        // Intercept row-commit events to prevent if FormGroup is invalid
+        this.rowCommitUnsub = grid.on('row-commit', (detail, event) => {
+            if (!this.syncValidation())
+                return;
+            this.#handleRowCommit(event, detail);
+        });
+        // Mark FormArray as touched on first interaction
+        this.touchListener = () => {
+            this.formArray().markAsTouched();
+            // Remove after first touch
+            if (this.touchListener) {
+                grid.removeEventListener('click', this.touchListener);
+                this.touchListener = null;
+            }
+        };
+        grid.addEventListener('click', this.touchListener);
+        // If in grid mode with syncValidation, set up reactive validation
+        // Wait for grid to be ready so we can detect the editing mode
+        grid.ready?.().then(() => {
+            if (this.syncValidation() && this.#isGridMode()) {
+                this.#setupReactiveValidation();
+                // Sync initial validation state for all existing controls
+                this.#syncAllValidationState();
+            }
+        });
+    }
+    ngOnDestroy() {
+        const grid = this.elementRef.nativeElement;
+        if (!grid)
+            return;
+        this.cellCommitUnsub?.();
+        this.cellCancelUnsub?.();
+        this.rowCommitUnsub?.();
+        if (this.touchListener) {
+            grid.removeEventListener('click', this.touchListener);
+        }
+        if (this.valueChangesSubscription) {
+            this.valueChangesSubscription.unsubscribe();
+        }
+        // Clean up status change subscriptions (grid mode)
+        this.statusChangesSubscriptions.forEach((sub) => sub.unsubscribe());
+        this.statusChangesSubscriptions = [];
+        this.#clearFormContext(grid);
+    }
+    /**
+     * Checks if the EditingPlugin is in 'grid' mode.
+     */
+    #isGridMode() {
+        const grid = this.elementRef.nativeElement;
+        if (!grid)
+            return false;
+        const editingPlugin = grid.getPluginByName?.('editing');
+        return editingPlugin?.config?.mode === 'grid';
+    }
+    /**
+     * Checks if a focusable editor element inside the grid currently has focus.
+     * Used to skip valueChanges → grid.rows sync while a user is actively editing,
+     * preventing editor destruction (which orphans overlay panels like autocomplete/select).
+     */
+    #isEditorFocused(grid) {
+        if (!this.#isGridMode())
+            return false;
+        const active = document.activeElement;
+        if (!active)
+            return false;
+        // Check if the focused element is inside the grid
+        return grid.contains(active) && active.closest('.editing') != null;
+    }
+    /**
+     * Sets up reactive validation syncing for grid mode.
+     * Subscribes to statusChanges on all FormControls to update validation state in real-time.
+     */
+    #setupReactiveValidation() {
+        const formArray = this.formArray();
+        const grid = this.elementRef.nativeElement;
+        if (!grid)
+            return;
+        // Clean up any existing subscriptions
+        this.statusChangesSubscriptions.forEach((sub) => sub.unsubscribe());
+        this.statusChangesSubscriptions = [];
+        // Subscribe to each FormGroup's statusChanges
+        for (let rowIndex = 0; rowIndex < formArray.length; rowIndex++) {
+            const rowFormGroup = this.#getRowFormGroup(rowIndex);
+            if (!rowFormGroup)
+                continue;
+            // Get the row ID for this row
+            const rowId = this.#getRowId(grid, rowIndex);
+            if (!rowId)
+                continue;
+            // Subscribe to status changes for each control in the FormGroup
+            Object.keys(rowFormGroup.controls).forEach((field) => {
+                const control = rowFormGroup.get(field);
+                if (!control)
+                    return;
+                const sub = control.statusChanges.pipe(debounceTime(50), takeUntilDestroyed(this.destroyRef)).subscribe(() => {
+                    this.#syncControlValidationToGrid(rowId, field, control);
+                });
+                this.statusChangesSubscriptions.push(sub);
+            });
+        }
+    }
+    /**
+     * Syncs validation state for all controls in the FormArray.
+     * Called once on init in grid mode to show pre-existing validation errors.
+     */
+    #syncAllValidationState() {
+        const formArray = this.formArray();
+        const grid = this.elementRef.nativeElement;
+        if (!grid)
+            return;
+        for (let rowIndex = 0; rowIndex < formArray.length; rowIndex++) {
+            const rowFormGroup = this.#getRowFormGroup(rowIndex);
+            if (!rowFormGroup)
+                continue;
+            const rowId = this.#getRowId(grid, rowIndex);
+            if (!rowId)
+                continue;
+            Object.keys(rowFormGroup.controls).forEach((field) => {
+                const control = rowFormGroup.get(field);
+                if (control) {
+                    this.#syncControlValidationToGrid(rowId, field, control);
+                }
+            });
+        }
+    }
+    /**
+     * Gets the row ID for a given row index using the grid's getRowId method.
+     */
+    #getRowId(grid, rowIndex) {
+        try {
+            const rows = grid.rows;
+            const row = rows?.[rowIndex];
+            if (!row)
+                return undefined;
+            return grid.getRowId?.(row);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Checks if the FormArray contains FormGroups.
+     */
+    #isFormArrayOfFormGroups() {
+        const formArray = this.formArray();
+        if (formArray.length === 0)
+            return false;
+        return formArray.at(0) instanceof FormGroup;
+    }
+    /**
+     * Gets the FormGroup at a specific row index.
+     */
+    #getRowFormGroup(rowIndex) {
+        const formArray = this.formArray();
+        const rowControl = formArray.at(rowIndex);
+        return rowControl instanceof FormGroup ? rowControl : undefined;
+    }
+    /**
+     * Stores the FormArrayContext on the grid element.
+     */
+    #storeFormContext(grid) {
+        const getRowFormGroup = (rowIndex) => this.#getRowFormGroup(rowIndex);
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        const self = this;
+        const context = {
+            getRow: (rowIndex) => {
+                const formArray = this.formArray();
+                const rowControl = formArray.at(rowIndex);
+                return rowControl ? rowControl.value : null;
+            },
+            updateField: (rowIndex, field, value) => {
+                const rowFormGroup = getRowFormGroup(rowIndex);
+                if (rowFormGroup) {
+                    const control = rowFormGroup.get(field);
+                    if (control) {
+                        control.setValue(value);
+                        control.markAsDirty();
+                    }
+                }
+            },
+            getValue: () => {
+                return this.formArray().getRawValue();
+            },
+            get hasFormGroups() {
+                return self.#isFormArrayOfFormGroups();
+            },
+            getControl: (rowIndex, field) => {
+                const rowFormGroup = getRowFormGroup(rowIndex);
+                if (!rowFormGroup)
+                    return undefined;
+                return rowFormGroup.get(field) ?? undefined;
+            },
+            getRowFormGroup,
+            isRowValid: (rowIndex) => {
+                const rowFormGroup = getRowFormGroup(rowIndex);
+                if (!rowFormGroup)
+                    return true;
+                return rowFormGroup.valid;
+            },
+            isRowTouched: (rowIndex) => {
+                const rowFormGroup = getRowFormGroup(rowIndex);
+                if (!rowFormGroup)
+                    return false;
+                return rowFormGroup.touched;
+            },
+            isRowDirty: (rowIndex) => {
+                const rowFormGroup = getRowFormGroup(rowIndex);
+                if (!rowFormGroup)
+                    return false;
+                return rowFormGroup.dirty;
+            },
+            getRowErrors: (rowIndex) => {
+                const rowFormGroup = getRowFormGroup(rowIndex);
+                if (!rowFormGroup)
+                    return null;
+                const errors = {};
+                let hasErrors = false;
+                Object.keys(rowFormGroup.controls).forEach((field) => {
+                    const control = rowFormGroup.get(field);
+                    if (control?.errors) {
+                        errors[field] = control.errors;
+                        hasErrors = true;
+                    }
+                });
+                if (rowFormGroup.errors) {
+                    errors['_group'] = rowFormGroup.errors;
+                    hasErrors = true;
+                }
+                return hasErrors ? errors : null;
+            },
+        };
+        grid[FORM_ARRAY_CONTEXT$1] = context;
+    }
+    /**
+     * Clears the FormArrayContext from the grid element.
+     */
+    #clearFormContext(grid) {
+        delete grid[FORM_ARRAY_CONTEXT$1];
+    }
+    /**
+     * Handles cell-commit events by updating the FormControl in the FormGroup.
+     */
+    #handleCellCommit(detail) {
+        const { rowIndex, field, value, rowId } = detail;
+        const rowFormGroup = this.#getRowFormGroup(rowIndex);
+        if (rowFormGroup) {
+            const control = rowFormGroup.get(field);
+            if (control) {
+                control.setValue(value);
+                control.markAsDirty();
+                control.markAsTouched();
+                // Sync Angular validation state to grid's visual invalid styling
+                if (this.syncValidation() && rowId) {
+                    this.#syncControlValidationToGrid(rowId, field, control);
+                }
+            }
+        }
+    }
+    /**
+     * Handles row-commit events - prevents commit if FormGroup has invalid controls.
+     */
+    #handleRowCommit(event, detail) {
+        const { rowIndex } = detail;
+        const rowFormGroup = this.#getRowFormGroup(rowIndex);
+        if (rowFormGroup && rowFormGroup.invalid) {
+            // Prevent row commit if the FormGroup is invalid
+            event.preventDefault();
+        }
+    }
+    /**
+     * Handles cell-cancel events (grid mode Escape) — reverts the FormControl
+     * to the value it had before the edit session began.
+     */
+    #handleCellCancel(detail) {
+        const { rowIndex, field, previousValue } = detail;
+        const rowFormGroup = this.#getRowFormGroup(rowIndex);
+        if (rowFormGroup) {
+            const control = rowFormGroup.get(field);
+            if (control) {
+                control.setValue(previousValue, { emitEvent: false });
+                control.markAsPristine();
+            }
+        }
+    }
+    /**
+     * Syncs a FormControl's validation state to the grid's visual invalid styling.
+     */
+    #syncControlValidationToGrid(rowId, field, control) {
+        const grid = this.elementRef.nativeElement;
+        if (!grid)
+            return;
+        // Get EditingPlugin via getPluginByName
+        const editingPlugin = grid.getPluginByName?.('editing');
+        if (!editingPlugin)
+            return;
+        if (control.invalid) {
+            // Get first error message to display
+            const errorMessage = this.#getFirstErrorMessage(control);
+            editingPlugin.setInvalid(rowId, field, errorMessage);
+        }
+        else {
+            editingPlugin.clearInvalid(rowId, field);
+        }
+    }
+    /**
+     * Gets a human-readable error message from the first validation error.
+     */
+    #getFirstErrorMessage(control) {
+        const errors = control.errors;
+        if (!errors)
+            return '';
+        const firstKey = Object.keys(errors)[0];
+        const error = errors[firstKey];
+        // Common Angular validators
+        switch (firstKey) {
+            case 'required':
+                return 'This field is required';
+            case 'minlength':
+                return `Minimum length is ${error.requiredLength}`;
+            case 'maxlength':
+                return `Maximum length is ${error.requiredLength}`;
+            case 'min':
+                return `Minimum value is ${error.min}`;
+            case 'max':
+                return `Maximum value is ${error.max}`;
+            case 'email':
+                return 'Invalid email address';
+            case 'pattern':
+                return 'Invalid format';
+            default:
+                // Custom validators may provide a message property
+                return typeof error === 'string' ? error : (error?.message ?? `Validation error: ${firstKey}`);
+        }
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.5", ngImport: i0, type: GridFormArray, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.2.5", type: GridFormArray, isStandalone: true, selector: "tbw-grid[formArray]", inputs: { formArray: { classPropertyName: "formArray", publicName: "formArray", isSignal: true, isRequired: true, transformFunction: null }, syncValidation: { classPropertyName: "syncValidation", publicName: "syncValidation", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.5", ngImport: i0, type: GridFormArray, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: 'tbw-grid[formArray]',
+                }]
+        }], propDecorators: { formArray: [{ type: i0.Input, args: [{ isSignal: true, alias: "formArray", required: true }] }], syncValidation: [{ type: i0.Input, args: [{ isSignal: true, alias: "syncValidation", required: false }] }] } });
+
+// Registry for structural editor templates
+const structuralEditorRegistry = new Map();
+/**
+ * Gets the editor template registered by the structural directive for a given column element.
+ * Falls back to the non-structural directive registry.
+ */
+function getStructuralEditorTemplate(columnElement) {
+    // First check structural directive registry
+    const template = structuralEditorRegistry.get(columnElement);
+    if (template)
+        return template;
+    // Fall back to the nested element registry
+    const editorEl = columnElement.querySelector('tbw-grid-column-editor');
+    if (editorEl) {
+        return getEditorTemplate(editorEl);
+    }
+    return undefined;
+}
+/**
+ * Structural directive for cell editor rendering.
+ *
+ * This provides a cleaner syntax for defining custom cell editors without
+ * the nested `<tbw-grid-column-editor>` and `<ng-template>` boilerplate.
+ *
+ * ## Usage
+ *
+ * ```html
+ * <!-- Instead of this verbose syntax: -->
+ * <tbw-grid-column field="status">
+ *   <tbw-grid-column-editor>
+ *     <ng-template let-value let-onCommit="onCommit" let-onCancel="onCancel">
+ *       <app-status-editor [value]="value" (commit)="onCommit($event)" (cancel)="onCancel()" />
+ *     </ng-template>
+ *   </tbw-grid-column-editor>
+ * </tbw-grid-column>
+ *
+ * <!-- Use this cleaner syntax (with auto-wiring - no explicit bindings needed!): -->
+ * <tbw-grid-column field="status">
+ *   <app-status-editor *tbwEditor="let value" [value]="value" />
+ * </tbw-grid-column>
+ * ```
+ *
+ * ## Template Context
+ *
+ * The structural directive provides the same context as `GridColumnEditor`:
+ * - `$implicit` / `value`: The cell value
+ * - `row`: The full row data object
+ * - `column`: The column configuration
+ * - `onCommit`: Callback function to commit the new value (optional - auto-wired if component emits `commit` event)
+ * - `onCancel`: Callback function to cancel editing (optional - auto-wired if component emits `cancel` event)
+ *
+ * ## Import
+ *
+ * ```typescript
+ * import { TbwEditor } from '@toolbox-web/grid-angular/features/editing';
+ *
+ * @Component({
+ *   imports: [TbwEditor],
+ *   // ...
+ * })
+ * ```
+ *
+ * @example
+ * ```html
+ * <tbw-grid-column field="status" editable>
+ *   <app-status-editor *tbwEditor="let value" [value]="value" />
+ * </tbw-grid-column>
+ * ```
+ *
+ * @category Directive
+ * @since 0.1.1
+ */
+class TbwEditor {
+    template = inject((TemplateRef));
+    elementRef = inject((ElementRef));
+    columnElement = null;
+    constructor() {
+        effect(() => {
+            this.registerTemplate();
+        });
+    }
+    registerTemplate() {
+        // Find the parent tbw-grid-column element
+        let parent = this.elementRef.nativeElement?.parentElement;
+        while (parent && parent.tagName !== 'TBW-GRID-COLUMN') {
+            parent = parent.parentElement;
+        }
+        if (parent) {
+            this.columnElement = parent;
+            structuralEditorRegistry.set(parent, this.template);
+        }
+    }
+    ngOnDestroy() {
+        if (this.columnElement) {
+            structuralEditorRegistry.delete(this.columnElement);
+        }
+    }
+    /**
+     * Static type guard for template context.
+     * Uses `any` defaults for ergonomic template usage.
+     */
+    static ngTemplateContextGuard(dir, ctx) {
+        return true;
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.5", ngImport: i0, type: TbwEditor, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "21.2.5", type: TbwEditor, isStandalone: true, selector: "[tbwEditor]", ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.5", ngImport: i0, type: TbwEditor, decorators: [{
+            type: Directive,
+            args: [{ selector: '[tbwEditor]' }]
+        }], ctorParameters: () => [] });
 
 /**
  * `GridEditingDirective` — owns `[editing]` and the editing-specific
@@ -96,6 +779,1555 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.5", ngImpor
                 }]
         }], ctorParameters: () => [], propDecorators: { editing: [{ type: i0.Input, args: [{ isSignal: true, alias: "editing", required: false }] }], cellCommit: [{ type: i0.Output, args: ["cellCommit"] }], cellCancel: [{ type: i0.Output, args: ["cellCancel"] }], rowCommit: [{ type: i0.Output, args: ["rowCommit"] }], changedRowsReset: [{ type: i0.Output, args: ["changedRowsReset"] }], editOpen: [{ type: i0.Output, args: ["editOpen"] }], beforeEditClose: [{ type: i0.Output, args: ["beforeEditClose"] }], editClose: [{ type: i0.Output, args: ["editClose"] }], dirtyChange: [{ type: i0.Output, args: ["dirtyChange"] }] } });
 
+/**
+ * Base class for grid cell editors.
+ *
+ * Provides common functionality for Angular cell editors:
+ * - Automatic value resolution from FormControl or value input
+ * - Common inputs (value, row, column, control)
+ * - Common outputs (commit, cancel)
+ * - Validation state helpers
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { Component } from '@angular/core';
+ * import { BaseGridEditor } from '@toolbox-web/grid-angular/features/editing';
+ *
+ * @Component({
+ *   selector: 'app-my-editor',
+ *   template: \`
+ *     <input
+ *       [value]="currentValue()"
+ *       [class.is-invalid]="isInvalid()"
+ *       (input)="commitValue($event.target.value)"
+ *       (keydown.escape)="cancelEdit()"
+ *     />
+ *     @if (hasErrors()) {
+ *       <div class="error">{{ firstErrorMessage() }}</div>
+ *     }
+ *   \`
+ * })
+ * export class MyEditorComponent extends BaseGridEditor<MyRow, string> {
+ *   // Override to customize error messages
+ *   protected override getErrorMessage(errorKey: string): string {
+ *     if (errorKey === 'required') return 'This field is required';
+ *     if (errorKey === 'minlength') return 'Too short';
+ *     return super.getErrorMessage(errorKey);
+ *   }
+ * }
+ * ```
+ *
+ * ## Template Syntax
+ *
+ * When using the base class, you only need to pass the control:
+ *
+ * ```html
+ * <tbw-grid-column field="name">
+ *   <app-my-editor *tbwEditor="let _; control as control" [control]="control" />
+ * </tbw-grid-column>
+ * ```
+ *
+ * Or without FormArray binding (fallback to value):
+ *
+ * ```html
+ * <tbw-grid-column field="name">
+ *   <app-my-editor *tbwEditor="let value" [value]="value" />
+ * </tbw-grid-column>
+ * ```
+ *
+ * @typeParam TRow - The row data type
+ * @typeParam TValue - The cell value type
+ *
+ * @since 0.5.0
+ */
+class BaseGridEditor {
+    elementRef = inject(ElementRef);
+    _destroyRef = inject(DestroyRef);
+    /** Cleanup function for the edit-close listener */
+    _editCloseCleanup = null;
+    // ============================================================================
+    // Inputs
+    // ============================================================================
+    /**
+     * The cell value. Used when FormControl is not available.
+     * When a FormControl is provided, value is derived from control.value instead.
+     */
+    value = input(...(ngDevMode ? [undefined, { debugName: "value" }] : /* istanbul ignore next */ []));
+    /**
+     * The full row data object.
+     */
+    row = input(...(ngDevMode ? [undefined, { debugName: "row" }] : /* istanbul ignore next */ []));
+    /**
+     * The column configuration.
+     */
+    column = input(...(ngDevMode ? [undefined, { debugName: "column" }] : /* istanbul ignore next */ []));
+    /**
+     * The FormControl for this cell, if the grid is bound to a FormArray.
+     * When provided, the editor uses control.value instead of the value input.
+     */
+    control = input(...(ngDevMode ? [undefined, { debugName: "control" }] : /* istanbul ignore next */ []));
+    // ============================================================================
+    // Outputs
+    // ============================================================================
+    /**
+     * Emits when the user commits a new value.
+     * Emits `null` when a nullable field is cleared.
+     */
+    commit = output();
+    /**
+     * Emits when the user cancels editing.
+     */
+    cancel = output();
+    // ============================================================================
+    // Computed State
+    // ============================================================================
+    /**
+     * The current value, derived from FormControl if available, otherwise from value input.
+     * This is the recommended way to get the current value in your editor template.
+     */
+    currentValue = computed(() => {
+        const ctrl = this.control();
+        if (ctrl) {
+            return ctrl.value;
+        }
+        return this.value();
+    }, ...(ngDevMode ? [{ debugName: "currentValue" }] : /* istanbul ignore next */ []));
+    /**
+     * Whether the control is invalid (has validation errors).
+     * Returns false if no FormControl is available.
+     */
+    isInvalid = computed(() => {
+        return this.control()?.invalid ?? false;
+    }, ...(ngDevMode ? [{ debugName: "isInvalid" }] : /* istanbul ignore next */ []));
+    /**
+     * Whether the control is dirty (has been modified).
+     * Returns false if no FormControl is available.
+     */
+    isDirty = computed(() => {
+        return this.control()?.dirty ?? false;
+    }, ...(ngDevMode ? [{ debugName: "isDirty" }] : /* istanbul ignore next */ []));
+    /**
+     * Whether the control has been touched.
+     * Returns false if no FormControl is available.
+     */
+    isTouched = computed(() => {
+        return this.control()?.touched ?? false;
+    }, ...(ngDevMode ? [{ debugName: "isTouched" }] : /* istanbul ignore next */ []));
+    /**
+     * Whether the control has any validation errors.
+     */
+    hasErrors = computed(() => {
+        const ctrl = this.control();
+        return ctrl?.errors != null && Object.keys(ctrl.errors).length > 0;
+    }, ...(ngDevMode ? [{ debugName: "hasErrors" }] : /* istanbul ignore next */ []));
+    /**
+     * The first error message from the control's validation errors.
+     * Returns an empty string if no errors.
+     */
+    firstErrorMessage = computed(() => {
+        const ctrl = this.control();
+        if (!ctrl?.errors)
+            return '';
+        const firstKey = Object.keys(ctrl.errors)[0];
+        return this.getErrorMessage(firstKey, ctrl.errors[firstKey]);
+    }, ...(ngDevMode ? [{ debugName: "firstErrorMessage" }] : /* istanbul ignore next */ []));
+    /**
+     * All error messages from the control's validation errors.
+     */
+    allErrorMessages = computed(() => {
+        const ctrl = this.control();
+        if (!ctrl?.errors)
+            return [];
+        return Object.entries(ctrl.errors).map(([key, value]) => this.getErrorMessage(key, value));
+    }, ...(ngDevMode ? [{ debugName: "allErrorMessages" }] : /* istanbul ignore next */ []));
+    // ============================================================================
+    // Lifecycle
+    // ============================================================================
+    constructor() {
+        afterNextRender(() => this._initEditCloseListener());
+        this._destroyRef.onDestroy(() => {
+            this._editCloseCleanup?.();
+            this._editCloseCleanup = null;
+        });
+    }
+    _initEditCloseListener() {
+        const grid = this.elementRef.nativeElement.closest('tbw-grid, [data-tbw-grid]');
+        if (!grid)
+            return;
+        let unsubBefore;
+        let unsubClose;
+        unsubBefore = grid.on('before-edit-close', () => {
+            this.onBeforeEditClose();
+            unsubBefore?.();
+            unsubBefore = undefined;
+        });
+        unsubClose = grid.on('edit-close', () => {
+            this.onEditClose();
+            unsubClose?.();
+            unsubClose = undefined;
+        });
+        this._editCloseCleanup = () => {
+            unsubBefore?.();
+            unsubClose?.();
+        };
+    }
+    // ============================================================================
+    // Methods
+    // ============================================================================
+    /**
+     * Whether this editor's cell is the currently focused cell.
+     *
+     * In row editing mode the grid creates editors for every editable cell
+     * in the row simultaneously. Use this to conditionally auto-focus inputs
+     * or open panels only in the active cell.
+     *
+     * Performs a synchronous DOM check — safe to call from `ngAfterViewInit`.
+     */
+    isCellFocused() {
+        return this.elementRef.nativeElement.closest('[part="cell"]')?.classList.contains('cell-focus') ?? false;
+    }
+    /**
+     * Called **before** the grid clears editing state and destroys editor DOM.
+     *
+     * At this point the commit callback is still active, so subclasses can
+     * call {@link commitValue} to flush any pending/deferred values.
+     *
+     * This fires only on the **commit** path (not on revert/cancel).
+     * Use {@link onEditClose} for cleanup that should happen on both paths.
+     */
+    onBeforeEditClose() {
+        // Default: no-op. Subclasses override to flush pending values.
+    }
+    /**
+     * Called when the grid ends the editing session for this cell.
+     *
+     * Override to perform cleanup such as closing overlay panels, autocomplete
+     * dropdowns, or other floating UI that lives at `<body>` level and would
+     * otherwise persist after the editor DOM is removed.
+     *
+     * The listener is set up automatically via `afterNextRender` — no manual
+     * wiring required.
+     */
+    onEditClose() {
+        // Default: no-op. Subclasses override.
+    }
+    /**
+     * Called by the grid adapter when the cell value changes externally
+     * (e.g., via `updateRow()` cascade or undo/redo).
+     *
+     * Override in subclasses to reset internal state (search text, selection
+     * flags, etc.) so the editor displays the updated value.
+     *
+     * This runs **synchronously** before the value input is updated, giving
+     * the editor a chance to clear stale state before the next change-detection
+     * pass re-reads the template.
+     *
+     * @param _newVal The new cell value being pushed from the grid
+     */
+    onExternalValueChange(_newVal) {
+        // Default: no-op. Subclasses override as needed.
+    }
+    /**
+     * Commit a new value. Emits the commit output AND dispatches a DOM event.
+     * The DOM event enables the grid's auto-wiring to catch the commit.
+     * Call this when the user confirms their edit.
+     */
+    commitValue(newValue) {
+        // Emit Angular output for template bindings
+        this.commit.emit(newValue);
+        // Dispatch DOM CustomEvent for grid's auto-wiring
+        // This allows the adapter to catch commits without explicit (commit)="..." bindings
+        this.elementRef.nativeElement.dispatchEvent(new CustomEvent('commit', { detail: newValue, bubbles: true }));
+    }
+    /**
+     * Cancel editing. Emits the cancel output AND dispatches a DOM event.
+     * Call this when the user cancels (e.g., presses Escape).
+     */
+    cancelEdit() {
+        // Emit Angular output for template bindings
+        this.cancel.emit();
+        // Dispatch DOM CustomEvent for grid's auto-wiring
+        this.elementRef.nativeElement.dispatchEvent(new CustomEvent('cancel', { bubbles: true }));
+    }
+    /**
+     * Get a human-readable error message for a validation error.
+     * Override this method to customize error messages for your editor.
+     *
+     * @param errorKey - The validation error key (e.g., 'required', 'minlength')
+     * @param errorValue - The error value (e.g., { requiredLength: 5, actualLength: 3 })
+     * @returns A human-readable error message
+     */
+    getErrorMessage(errorKey, errorValue) {
+        switch (errorKey) {
+            case 'required':
+                return 'This field is required';
+            case 'minlength': {
+                const err = errorValue;
+                return `Minimum length is ${err?.requiredLength ?? 'unknown'}`;
+            }
+            case 'maxlength': {
+                const err = errorValue;
+                return `Maximum length is ${err?.requiredLength ?? 'unknown'}`;
+            }
+            case 'min': {
+                const err = errorValue;
+                return `Minimum value is ${err?.min ?? 'unknown'}`;
+            }
+            case 'max': {
+                const err = errorValue;
+                return `Maximum value is ${err?.max ?? 'unknown'}`;
+            }
+            case 'email':
+                return 'Invalid email address';
+            case 'pattern':
+                return 'Invalid format';
+            default:
+                return `Invalid value (${errorKey})`;
+        }
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.5", ngImport: i0, type: BaseGridEditor, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.2.5", type: BaseGridEditor, isStandalone: true, inputs: { value: { classPropertyName: "value", publicName: "value", isSignal: true, isRequired: false, transformFunction: null }, row: { classPropertyName: "row", publicName: "row", isSignal: true, isRequired: false, transformFunction: null }, column: { classPropertyName: "column", publicName: "column", isSignal: true, isRequired: false, transformFunction: null }, control: { classPropertyName: "control", publicName: "control", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { commit: "commit", cancel: "cancel" }, ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.5", ngImport: i0, type: BaseGridEditor, decorators: [{
+            type: Directive
+        }], ctorParameters: () => [], propDecorators: { value: [{ type: i0.Input, args: [{ isSignal: true, alias: "value", required: false }] }], row: [{ type: i0.Input, args: [{ isSignal: true, alias: "row", required: false }] }], column: [{ type: i0.Input, args: [{ isSignal: true, alias: "column", required: false }] }], control: [{ type: i0.Input, args: [{ isSignal: true, alias: "control", required: false }] }], commit: [{ type: i0.Output, args: ["commit"] }], cancel: [{ type: i0.Output, args: ["cancel"] }] } });
+
+/**
+ * Base class for grid editors that also work as Angular form controls.
+ *
+ * Combines `BaseGridEditor` with `ControlValueAccessor` so the same component
+ * can be used inside a `<tbw-grid>` **and** in a standalone `<form>`.
+ *
+ * ## What it provides
+ *
+ * | Member | Purpose |
+ * |--------|---------|
+ * | `cvaValue` | Signal holding the value written by the form control |
+ * | `disabledState` | Signal tracking `setDisabledState` calls |
+ * | `displayValue` | Computed that prefers grid value (`currentValue`) and falls back to `cvaValue` |
+ * | `commitBoth(v)` | Commits via both CVA `onChange` and grid `commitValue` |
+ * | `writeValue` / `registerOn*` / `setDisabledState` | Full CVA implementation |
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { Component, forwardRef } from '@angular/core';
+ * import { NG_VALUE_ACCESSOR } from '@angular/forms';
+ * import { BaseGridEditorCVA } from '@toolbox-web/grid-angular/features/editing';
+ *
+ * @Component({
+ *   selector: 'app-date-picker',
+ *   providers: [{
+ *     provide: NG_VALUE_ACCESSOR,
+ *     useExisting: forwardRef(() => DatePickerComponent),
+ *     multi: true,
+ *   }],
+ *   template: `
+ *     <input
+ *       type="date"
+ *       [value]="displayValue()"
+ *       [disabled]="disabledState()"
+ *       (change)="commitBoth($event.target.value)"
+ *       (keydown.escape)="cancelEdit()"
+ *     />
+ *   `
+ * })
+ * export class DatePickerComponent extends BaseGridEditorCVA<MyRow, string> {}
+ * ```
+ *
+ * > **Note:** Subclasses must still provide `NG_VALUE_ACCESSOR` themselves
+ * > because `forwardRef(() => ConcreteClass)` must reference the concrete
+ * > component — this is an Angular limitation.
+ *
+ * @typeParam TRow - The row data type
+ * @typeParam TValue - The cell/control value type
+ *
+ * @since 0.13.0
+ */
+class BaseGridEditorCVA extends BaseGridEditor {
+    // ============================================================================
+    // CVA State
+    // ============================================================================
+    /** Internal onChange callback registered by the form control. */
+    // eslint-disable-next-line @typescript-eslint/no-empty-function
+    _onChange = () => { };
+    /** Internal onTouched callback registered by the form control. */
+    // eslint-disable-next-line @typescript-eslint/no-empty-function
+    _onTouched = () => { };
+    /**
+     * Signal holding the value written by the form control via `writeValue()`.
+     * Updated when the form control pushes a new value (e.g. `patchValue`, `setValue`).
+     */
+    cvaValue = signal(null, ...(ngDevMode ? [{ debugName: "cvaValue" }] : /* istanbul ignore next */ []));
+    /**
+     * Signal tracking the disabled state set by the form control.
+     * Updated when `setDisabledState()` is called by Angular's forms module.
+     */
+    disabledState = signal(false, ...(ngDevMode ? [{ debugName: "disabledState" }] : /* istanbul ignore next */ []));
+    /**
+     * Resolved display value.
+     *
+     * Prefers `currentValue()` (grid context — from `control.value` or `value` input)
+     * and falls back to `cvaValue()` (standalone form context — from `writeValue`).
+     *
+     * Use this in your template instead of reading `currentValue()` directly
+     * so the component works in both grid and standalone form contexts.
+     */
+    displayValue = computed(() => {
+        return this.currentValue() ?? this.cvaValue();
+    }, ...(ngDevMode ? [{ debugName: "displayValue" }] : /* istanbul ignore next */ []));
+    // ============================================================================
+    // ControlValueAccessor Implementation
+    // ============================================================================
+    /**
+     * Called by Angular forms when the form control value changes programmatically.
+     */
+    writeValue(value) {
+        this.cvaValue.set(value);
+    }
+    /**
+     * Called by Angular forms to register a change callback.
+     */
+    registerOnChange(fn) {
+        this._onChange = fn;
+    }
+    /**
+     * Called by Angular forms to register a touched callback.
+     */
+    registerOnTouched(fn) {
+        this._onTouched = fn;
+    }
+    /**
+     * Called by Angular forms to set the disabled state.
+     */
+    setDisabledState(isDisabled) {
+        this.disabledState.set(isDisabled);
+    }
+    // ============================================================================
+    // Dual-Commit Helpers
+    // ============================================================================
+    /**
+     * Commit a value through both the CVA (form control) and the grid.
+     *
+     * - Calls the CVA `onChange` callback (updates the form control)
+     * - Marks the control as touched
+     * - Calls `commitValue()` (emits grid commit event + DOM `CustomEvent`)
+     *
+     * Use this instead of `commitValue()` when your editor doubles as a form control.
+     *
+     * @param value - The new value to commit
+     */
+    commitBoth(value) {
+        // Update CVA
+        this.cvaValue.set(value);
+        this._onChange(value);
+        this._onTouched();
+        // Update grid (null is valid for nullable columns — the grid's cell-commit
+        // handler and EditingPlugin will apply it correctly)
+        this.commitValue(value);
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.5", ngImport: i0, type: BaseGridEditorCVA, deps: null, target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "21.2.5", type: BaseGridEditorCVA, isStandalone: true, usesInheritance: true, ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.5", ngImport: i0, type: BaseGridEditorCVA, decorators: [{
+            type: Directive
+        }] });
+
+// #endregion
+// #region Global Styles
+/** Tracks whether the global overlay stylesheet has been injected. */
+let overlayStylesInjected = false;
+/**
+ * CSS for the overlay panel base layer.
+ * Injected once into `<head>` on first `BaseOverlayEditor` use.
+ *
+ * Uses CSS Anchor Positioning as primary strategy with a JS fallback
+ * for browsers that don't support it (Firefox, Safari as of late 2025).
+ */
+const OVERLAY_STYLES = /* css */ `
+.tbw-overlay-panel {
+  position: fixed;
+  z-index: 10000;
+  background: var(--tbw-overlay-bg, #fff);
+  border: 1px solid var(--tbw-overlay-border, #ccc);
+  border-radius: var(--tbw-overlay-radius, 4px);
+  box-shadow: var(--tbw-overlay-shadow, 0 4px 12px rgba(0, 0, 0, 0.15));
+  box-sizing: border-box;
+  overflow: auto;
+}
+
+/* Hide panels that have not been initialised via initOverlay() yet.
+   Prevents a flash-of-unstyled-content when the subclass defers
+   the initOverlay call (e.g. via setTimeout or afterNextRender). */
+.tbw-overlay-panel:not([data-anchor-id]) {
+  display: none;
+}
+
+.tbw-overlay-panel:popover-open {
+  display: block;
+}
+
+@supports (anchor-name: --a) {
+  .tbw-overlay-panel[data-anchor-id] {
+    position: fixed;
+    position-anchor: var(--tbw-overlay-anchor);
+    inset: unset;
+  }
+  .tbw-overlay-panel[data-pos="below"] {
+    top: anchor(bottom);
+    left: anchor(left);
+    position-try-fallbacks: flip-block;
+  }
+  .tbw-overlay-panel[data-pos="above"] {
+    bottom: anchor(top);
+    left: anchor(left);
+    position-try-fallbacks: flip-block;
+  }
+  .tbw-overlay-panel[data-pos="below-right"] {
+    top: anchor(bottom);
+    right: anchor(right);
+    position-try-fallbacks: flip-block;
+  }
+  .tbw-overlay-panel[data-pos="over-top-left"] {
+    top: anchor(top);
+    left: anchor(left);
+  }
+  .tbw-overlay-panel[data-pos="over-bottom-left"] {
+    bottom: anchor(bottom);
+    left: anchor(left);
+  }
+}
+`;
+function ensureOverlayStyles() {
+    if (overlayStylesInjected)
+        return;
+    overlayStylesInjected = true;
+    const style = document.createElement('style');
+    style.setAttribute('data-tbw-overlay', '');
+    style.textContent = OVERLAY_STYLES;
+    document.head.appendChild(style);
+}
+// #endregion
+// #region Anchor ID Counter
+let anchorCounter = 0;
+// #endregion
+/**
+ * Base class for grid editors that display a floating overlay panel.
+ *
+ * Provides infrastructure for:
+ * - **Overlay positioning** — CSS Anchor Positioning with JS fallback
+ * - **Focus gating** — in row editing mode, the panel only opens for the focused cell
+ * - **Click-outside detection** — closes the panel when clicking outside
+ * - **MutationObserver** — detects cell focus changes (row editing mode)
+ * - **Escape handling** — closes the panel and returns focus to the inline input
+ * - **Synthetic Tab dispatch** — advances grid focus after overlay close
+ * - **Automatic teardown** — removes the panel from `<body>` and cleans up listeners
+ * - **External focus registration** — auto-registers the panel via `grid.registerExternalFocusContainer()` so the grid keeps `data-has-focus` and editors stay open while the overlay has focus
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { Component, viewChild, ElementRef, effect } from '@angular/core';
+ * import { BaseOverlayEditor } from '@toolbox-web/grid-angular/features/editing';
+ *
+ * @Component({
+ *   selector: 'app-date-editor',
+ *   template: `
+ *     <input
+ *       #inlineInput
+ *       readonly
+ *       [value]="currentValue()"
+ *       (click)="onInlineClick()"
+ *       (keydown)="onInlineKeydown($event)"
+ *     />
+ *     <div #panel class="tbw-overlay-panel" style="width: 280px;">
+ *       <!-- your date picker UI here -->
+ *       <div class="actions">
+ *         <button (click)="selectAndClose(selectedDate)">OK</button>
+ *         <button (click)="hideOverlay()">Cancel</button>
+ *       </div>
+ *     </div>
+ *   `
+ * })
+ * export class DateEditorComponent extends BaseOverlayEditor<MyRow, string> {
+ *   panelRef = viewChild.required<ElementRef<HTMLElement>>('panel');
+ *   inputRef = viewChild.required<ElementRef<HTMLInputElement>>('inlineInput');
+ *
+ *   protected override overlayPosition = 'below' as const;
+ *
+ *   constructor() {
+ *     super();
+ *     effect(() => {
+ *       const panel = this.panelRef().nativeElement;
+ *       this.initOverlay(panel);
+ *       if (this.isCellFocused()) this.showOverlay();
+ *     });
+ *   }
+ *
+ *   protected getInlineInput(): HTMLInputElement | null {
+ *     return this.inputRef()?.nativeElement ?? null;
+ *   }
+ *
+ *   protected onOverlayOutsideClick(): void {
+ *     this.hideOverlay();
+ *   }
+ *
+ *   selectAndClose(date: string): void {
+ *     this.commitValue(date);
+ *     this.hideOverlay();
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     <input #inlineInput readonly [value]="currentValue()"
+ *       (click)="onInlineClick()" (keydown)="onInlineKeydown($event)" />
+ *     <div #panel style="width: 280px">
+ *       <!-- overlay content -->
+ *     </div>
+ *   `
+ * })
+ * export class MyEditor extends BaseOverlayEditor<MyRow, string> {
+ *   panelRef = viewChild.required<ElementRef<HTMLElement>>('panel');
+ *   inputRef = viewChild.required<ElementRef<HTMLInputElement>>('inlineInput');
+ *
+ *   constructor() {
+ *     super();
+ *     effect(() => this.initOverlay(this.panelRef().nativeElement));
+ *   }
+ *
+ *   protected getInlineInput() { return this.inputRef()?.nativeElement ?? null; }
+ *   protected onOverlayOutsideClick() { this.hideOverlay(); }
+ * }
+ * ```
+ *
+ * @typeParam TRow - The row data type
+ * @typeParam TValue - The cell value type
+ *
+ * @since 0.13.0
+ */
+class BaseOverlayEditor extends BaseGridEditor {
+    _elementRef = inject(ElementRef);
+    _overlayDestroyRef = inject(DestroyRef);
+    // ============================================================================
+    // Configuration
+    // ============================================================================
+    /**
+     * Position of the overlay panel relative to the anchor cell.
+     * Override in subclasses to change the default position.
+     *
+     * @default 'below'
+     */
+    overlayPosition = 'below';
+    // ============================================================================
+    // Internal State
+    // ============================================================================
+    /** The overlay panel element (set via `initOverlay()`). */
+    _panel = null;
+    /** Whether the overlay is currently visible. */
+    _isOpen = false;
+    /** Unique anchor ID for CSS Anchor Positioning. */
+    _anchorId = '';
+    /** Whether the browser supports CSS Anchor Positioning. */
+    _supportsAnchor = false;
+    /** AbortController for all overlay-related listeners. */
+    _abortCtrl = null;
+    /** MutationObserver watching cell focus class changes. */
+    _focusObserver = null;
+    // ============================================================================
+    // Lifecycle
+    // ============================================================================
+    constructor() {
+        super();
+        this._supportsAnchor = typeof CSS !== 'undefined' && CSS.supports('anchor-name', '--a');
+        ensureOverlayStyles();
+        afterNextRender(() => this._setupFocusObserver());
+        this._overlayDestroyRef.onDestroy(() => this.teardownOverlay());
+    }
+    // ============================================================================
+    // Public API — Subclass Interface
+    // ============================================================================
+    /**
+     * Initialise the overlay with the panel element.
+     *
+     * Call this in an `effect()` or `afterNextRender()` with your `viewChild` panel reference.
+     * The panel is moved to `<body>` and hidden until {@link showOverlay} is called.
+     *
+     * @param panel - The overlay panel DOM element
+     */
+    initOverlay(panel) {
+        this._panel = panel;
+        // Assign a unique anchor ID
+        this._anchorId = `tbw-anchor-${++anchorCounter}`;
+        panel.classList.add('tbw-overlay-panel');
+        panel.setAttribute('data-pos', this.overlayPosition);
+        panel.setAttribute('data-anchor-id', this._anchorId);
+        panel.style.display = 'none';
+        // Set up CSS Anchor Positioning on the cell
+        if (this._supportsAnchor) {
+            const cell = this._getCell();
+            if (cell) {
+                cell.style.setProperty('anchor-name', `--${this._anchorId}`);
+                panel.style.setProperty('--tbw-overlay-anchor', `--${this._anchorId}`);
+            }
+        }
+        // Move panel to body so it escapes grid overflow clipping
+        document.body.appendChild(panel);
+        // Register the panel as an external focus container on the grid
+        // so focus moving into the overlay is treated as "still in the grid"
+        this._getGridElement()?.registerExternalFocusContainer?.(panel);
+        // Set up click-outside detection
+        this._abortCtrl = new AbortController();
+        document.addEventListener('pointerdown', (e) => this._onDocumentPointerDown(e), {
+            signal: this._abortCtrl.signal,
+        });
+        // Close overlay when the grid viewport scrolls. Mirrors outside-click
+        // semantics so subclasses' `onOverlayOutsideClick()` drives commit/cancel.
+        // Uses the public `tbw-scroll` CustomEvent dispatched on the grid host —
+        // no shadow-DOM reach-arounds required (composed: true crosses boundaries).
+        const grid = this._getGridElement();
+        if (grid) {
+            grid.addEventListener('tbw-scroll', () => this._onGridScroll(), {
+                signal: this._abortCtrl.signal,
+            });
+        }
+        // If the focus observer already fired before the panel was initialised
+        // (e.g. initOverlay called from a deferred setTimeout), the showOverlay()
+        // call was silently ignored because _panel was still null.  Catch up now.
+        if (this._getCell()?.classList.contains('cell-focus')) {
+            this.showOverlay();
+            this.onOverlayOpened();
+        }
+    }
+    /**
+     * Show the overlay panel.
+     *
+     * If CSS Anchor Positioning is not supported, falls back to JS-based
+     * positioning using `getBoundingClientRect()`.
+     */
+    showOverlay() {
+        if (!this._panel || this._isOpen)
+            return;
+        this._isOpen = true;
+        this._panel.style.display = '';
+        // JS fallback positioning for browsers without CSS Anchor Positioning
+        if (!this._supportsAnchor) {
+            this._positionWithJs();
+        }
+    }
+    /**
+     * Hide the overlay panel.
+     *
+     * @param suppressTabAdvance - When `true`, skip synthetic Tab dispatch
+     *   (useful when hiding is triggered by an external focus change).
+     */
+    hideOverlay(suppressTabAdvance) {
+        if (!this._panel || !this._isOpen)
+            return;
+        this._isOpen = false;
+        this._panel.style.display = 'none';
+        if (!suppressTabAdvance) {
+            this.getInlineInput()?.focus();
+        }
+    }
+    /**
+     * Close and immediately re-open the overlay.
+     * Useful after the panel content changes size and needs repositioning.
+     */
+    reopenOverlay() {
+        if (!this._panel)
+            return;
+        this._isOpen = false;
+        this._panel.style.display = 'none';
+        this.showOverlay();
+    }
+    /**
+     * Remove the overlay from the DOM and clean up all listeners.
+     *
+     * Called automatically on `DestroyRef.onDestroy`. Can also be called
+     * manually if the editor needs early cleanup.
+     */
+    teardownOverlay() {
+        this._abortCtrl?.abort();
+        this._abortCtrl = null;
+        this._focusObserver?.disconnect();
+        this._focusObserver = null;
+        // Unregister the panel from the grid's external focus container registry
+        if (this._panel) {
+            this._getGridElement()?.unregisterExternalFocusContainer?.(this._panel);
+        }
+        if (this._panel?.parentNode) {
+            this._panel.parentNode.removeChild(this._panel);
+        }
+        this._panel = null;
+        this._isOpen = false;
+        // Clean up anchor-name on the cell
+        if (this._supportsAnchor) {
+            const cell = this._getCell();
+            if (cell) {
+                cell.style.removeProperty('anchor-name');
+            }
+        }
+    }
+    /**
+     * Override in `edit-close` handler to also hide the overlay.
+     * This is called automatically by `BaseGridEditor` when the grid
+     * ends the editing session.
+     */
+    onEditClose() {
+        this.hideOverlay(true);
+    }
+    // ============================================================================
+    // Keyboard & Click Helpers
+    // ============================================================================
+    /**
+     * Keydown handler for the inline readonly input.
+     *
+     * - **Enter / Space / ArrowDown / F2** → open overlay
+     * - **Escape** → calls {@link handleEscape}
+     *
+     * Bind this to `(keydown)` on your inline input element.
+     */
+    onInlineKeydown(event) {
+        switch (event.key) {
+            case 'Enter':
+            case ' ':
+            case 'ArrowDown':
+            case 'F2':
+                event.preventDefault();
+                this.showOverlay();
+                this.onOverlayOpened();
+                break;
+            case 'Escape':
+                this.handleEscape(event);
+                break;
+        }
+    }
+    /**
+     * Click handler for the inline input.
+     * Opens the overlay and calls {@link onOverlayOpened}.
+     *
+     * Bind this to `(click)` on your inline input element.
+     */
+    onInlineClick() {
+        if (this._isOpen) {
+            this.hideOverlay();
+        }
+        else {
+            this.showOverlay();
+            this.onOverlayOpened();
+        }
+    }
+    /**
+     * Handle Escape key press.
+     *
+     * If the overlay is open, closes it and returns focus to the inline input.
+     * If the overlay is already closed, cancels the edit entirely.
+     */
+    handleEscape(event) {
+        if (this._isOpen) {
+            event.stopPropagation();
+            this.hideOverlay();
+        }
+        else {
+            this.cancelEdit();
+        }
+    }
+    /**
+     * Dispatch a synthetic Tab key event to advance grid focus.
+     *
+     * Call this after committing a value and closing the overlay so the
+     * grid moves focus to the next cell.
+     *
+     * @param backward - When `true`, dispatch Shift+Tab to move backwards.
+     */
+    advanceGridFocus(backward = false) {
+        const cell = this._getCell();
+        if (!cell)
+            return;
+        cell.dispatchEvent(new KeyboardEvent('keydown', {
+            key: 'Tab',
+            shiftKey: backward,
+            bubbles: true,
+            cancelable: true,
+        }));
+    }
+    /**
+     * Called after the overlay is shown.
+     *
+     * Override to focus an element inside the panel, start animations, etc.
+     * Default implementation is a no-op.
+     */
+    onOverlayOpened() {
+        // Default: no-op. Subclasses override.
+    }
+    // ============================================================================
+    // Private Helpers
+    // ============================================================================
+    /** Find the parent cell element for this editor. */
+    _getCell() {
+        return this._elementRef.nativeElement.closest('[part="cell"]') ?? null;
+    }
+    /** Find the parent `<tbw-grid>` element for this editor. */
+    _getGridElement() {
+        return this._elementRef.nativeElement.closest('tbw-grid, [data-tbw-grid]') ?? null;
+    }
+    /**
+     * JS fallback positioning for browsers without CSS Anchor Positioning.
+     * Uses `getBoundingClientRect()` with viewport overflow detection.
+     */
+    _positionWithJs() {
+        const cell = this._getCell();
+        const panel = this._panel;
+        if (!cell || !panel)
+            return;
+        const cellRect = cell.getBoundingClientRect();
+        // Temporarily make visible to measure
+        panel.style.visibility = 'hidden';
+        panel.style.display = '';
+        const panelRect = panel.getBoundingClientRect();
+        panel.style.visibility = '';
+        const viewportH = window.innerHeight;
+        const viewportW = window.innerWidth;
+        let top;
+        let left;
+        switch (this.overlayPosition) {
+            case 'above': {
+                top = cellRect.top - panelRect.height;
+                left = cellRect.left;
+                // Flip to below if off-screen
+                if (top < 0)
+                    top = cellRect.bottom;
+                break;
+            }
+            case 'below-right': {
+                top = cellRect.bottom;
+                left = cellRect.right - panelRect.width;
+                // Flip to above if off-screen
+                if (top + panelRect.height > viewportH)
+                    top = cellRect.top - panelRect.height;
+                break;
+            }
+            case 'over-top-left': {
+                top = cellRect.top;
+                left = cellRect.left;
+                break;
+            }
+            case 'over-bottom-left': {
+                top = cellRect.bottom - panelRect.height;
+                left = cellRect.left;
+                break;
+            }
+            case 'below':
+            default: {
+                top = cellRect.bottom;
+                left = cellRect.left;
+                // Flip to above if off-screen
+                if (top + panelRect.height > viewportH)
+                    top = cellRect.top - panelRect.height;
+                break;
+            }
+        }
+        // Clamp to viewport
+        if (left + panelRect.width > viewportW)
+            left = viewportW - panelRect.width - 4;
+        if (left < 0)
+            left = 4;
+        if (top < 0)
+            top = 4;
+        panel.style.top = `${top}px`;
+        panel.style.left = `${left}px`;
+    }
+    /**
+     * Document pointerdown handler for click-outside detection.
+     * Fires `onOverlayOutsideClick()` if the click is outside the panel
+     * and outside the editor's host element.
+     */
+    _onDocumentPointerDown(event) {
+        if (!this._isOpen || !this._panel)
+            return;
+        const target = event.target;
+        const hostEl = this._elementRef.nativeElement;
+        // Click inside panel or host — ignore
+        if (this._panel.contains(target) || hostEl.contains(target))
+            return;
+        this.onOverlayOutsideClick();
+    }
+    /**
+     * Handle the grid's `tbw-scroll` CustomEvent while the overlay is open.
+     *
+     * When the viewport scrolls, the anchored overlay would otherwise float
+     * over content that no longer corresponds to the edited cell (or the
+     * cell may be virtualized out entirely). Treat scroll as a dismissal
+     * signal equivalent to clicking outside so subclasses' overlay-outside
+     * handler drives the appropriate commit/cancel path.
+     */
+    _onGridScroll() {
+        if (!this._isOpen || !this._panel)
+            return;
+        this.onOverlayOutsideClick();
+    }
+    /**
+     * Set up a MutationObserver on the parent cell to watch for
+     * `cell-focus` class changes. This handles row-editing mode where
+     * all editors exist simultaneously but only the focused cell's
+     * editor should have its overlay visible.
+     *
+     * A `justOpened` flash guard suppresses the observer from
+     * immediately closing the overlay when `beginBulkEdit()` moves
+     * focus to the first editable column. Without this guard,
+     * double-click triggers a "flash open then close" effect.
+     */
+    _setupFocusObserver() {
+        const cell = this._getCell();
+        if (!cell)
+            return;
+        let justOpened = false;
+        let pendingHideRaf = 0;
+        const hostEl = this._elementRef.nativeElement;
+        this._focusObserver = new MutationObserver((mutations) => {
+            // Guard: if the editor's host element is no longer inside the cell,
+            // it means the component was detached (e.g., editing session ended
+            // and the render pipeline cleared the cell DOM). Disconnect to
+            // prevent orphaned observers from opening stale overlay panels.
+            if (!cell.contains(hostEl)) {
+                this._focusObserver?.disconnect();
+                this._focusObserver = null;
+                return;
+            }
+            for (const mutation of mutations) {
+                if (mutation.type !== 'attributes' || mutation.attributeName !== 'class')
+                    continue;
+                const isFocused = cell.classList.contains('cell-focus');
+                if (isFocused && !this._isOpen) {
+                    // Cell just gained focus — cancel any pending hide and open overlay.
+                    if (pendingHideRaf) {
+                        cancelAnimationFrame(pendingHideRaf);
+                        pendingHideRaf = 0;
+                    }
+                    justOpened = true;
+                    this.showOverlay();
+                    this.onOverlayOpened();
+                    // Clear the guard after a macrotask so that an immediate
+                    // focus-away (e.g. beginBulkEdit focus adjustment) does
+                    // not close the overlay in the same event loop tick.
+                    setTimeout(() => {
+                        justOpened = false;
+                    }, 0);
+                }
+                else if (!isFocused && this._isOpen && !justOpened) {
+                    // Cell lost focus — defer hide to allow render cycles to settle.
+                    // Re-renders (e.g., from ResizeObserver after a footer appears)
+                    // may transiently toggle cell-focus within the same frame.
+                    // Deferring to the next animation frame lets the render pipeline
+                    // finish before we decide whether the overlay should actually close.
+                    if (pendingHideRaf)
+                        cancelAnimationFrame(pendingHideRaf);
+                    pendingHideRaf = requestAnimationFrame(() => {
+                        pendingHideRaf = 0;
+                        // Re-check settled state — cell-focus may have been re-applied
+                        if (!cell.classList.contains('cell-focus') && this._isOpen) {
+                            this.hideOverlay(true);
+                        }
+                    });
+                }
+            }
+        });
+        this._focusObserver.observe(cell, { attributes: true, attributeFilter: ['class'] });
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.5", ngImport: i0, type: BaseOverlayEditor, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "21.2.5", type: BaseOverlayEditor, isStandalone: true, usesInheritance: true, ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.5", ngImport: i0, type: BaseOverlayEditor, decorators: [{
+            type: Directive
+        }], ctorParameters: () => [] });
+
+// Symbol for storing form context on the grid element (shared with GridFormArray)
+const FORM_ARRAY_CONTEXT = Symbol('formArrayContext');
+/**
+ * Gets the FormArrayContext from a grid element, if present.
+ * @internal
+ * @since 0.11.0
+ */
+function getLazyFormContext(gridElement) {
+    return gridElement[FORM_ARRAY_CONTEXT];
+}
+/**
+ * Directive that provides lazy FormGroup creation for grid editing.
+ *
+ * Unlike `GridFormArray` which creates all FormGroups upfront, this directive
+ * creates FormGroups on-demand only when a row enters edit mode. This provides
+ * much better performance for large datasets while still enabling full
+ * Angular Reactive Forms integration.
+ *
+ * ## Key Benefits
+ *
+ * - **Performance**: Only creates FormGroups for rows being edited (20-100x fewer controls)
+ * - **Same DX**: Editors still receive `control` in their context for validation
+ * - **Memory efficient**: FormGroups are cleaned up when rows exit edit mode
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { Component, inject, signal } from '@angular/core';
+ * import { FormBuilder, Validators, ReactiveFormsModule } from '@angular/forms';
+ * import { Grid, GridLazyForm, TbwEditor } from '@toolbox-web/grid-angular/features/editing';
+ *
+ * @Component({
+ *   imports: [Grid, GridLazyForm, TbwEditor, ReactiveFormsModule],
+ *   template: \`
+ *     <tbw-grid
+ *       [rows]="employees()"
+ *       [lazyForm]="createRowForm"
+ *       [gridConfig]="config">
+ *
+ *       <tbw-grid-column field="firstName">
+ *         <input *tbwEditor="let _; control as ctrl"
+ *                [formControl]="ctrl"
+ *                [class.is-invalid]="ctrl?.invalid && ctrl?.touched" />
+ *       </tbw-grid-column>
+ *     </tbw-grid>
+ *   \`
+ * })
+ * export class MyComponent {
+ *   private fb = inject(FormBuilder);
+ *   employees = signal(generateEmployees(1000));
+ *
+ *   // Factory called when editing starts - only include editable fields!
+ *   createRowForm = (row: Employee): FormGroup => this.fb.group({
+ *     firstName: [row.firstName, Validators.required],
+ *     lastName: [row.lastName, Validators.minLength(2)],
+ *     salary: [row.salary, [Validators.required, Validators.min(0)]],
+ *   });
+ *
+ *   gridConfig = { columns: [...] };
+ * }
+ * ```
+ *
+ * ## How It Works
+ *
+ * 1. Rows come from `[rows]` input (plain data array)
+ * 2. When a cell enters edit mode, the FormGroup is created lazily
+ * 3. Editors receive the FormControl in their template context
+ * 4. On commit, FormGroup values are synced back to the row
+ * 5. FormGroup is cleaned up when the row exits edit mode (configurable)
+ *
+ * ## Performance Comparison
+ *
+ * | Rows | GridFormArray (20 fields) | GridLazyForm |
+ * |------|---------------------------|--------------|
+ * | 100  | 2,000 controls           | ~20 controls |
+ * | 500  | 10,000 controls          | ~20 controls |
+ * | 1000 | 20,000 controls          | ~20 controls |
+ *
+ * @example
+ * ```html
+ * <tbw-grid [rows]="employees()" [lazyForm]="createRowForm" [gridConfig]="gridConfig" />
+ * ```
+ *
+ * @see GridFormArray For small datasets with full upfront validation
+ * @category Directive
+ *
+ * @since 0.11.0
+ */
+class GridLazyForm {
+    elementRef = inject((ElementRef));
+    // Cache of FormGroups by row reference
+    formGroupCache = new Map();
+    // Map from row reference to rowIndex (needed for getControl)
+    rowIndexMap = new Map();
+    // Track which row is currently being edited
+    editingRowIndex = null;
+    cellCommitUnsub = null;
+    rowCommitUnsub = null;
+    rowsChangeUnsub = null;
+    /**
+     * Factory function to create a FormGroup for a row.
+     * Called lazily when the row first enters edit mode.
+     *
+     * @example
+     * ```typescript
+     * createRowForm = (row: Employee): FormGroup => this.fb.group({
+     *   firstName: [row.firstName, Validators.required],
+     *   lastName: [row.lastName],
+     *   salary: [row.salary, [Validators.min(0)]],
+     * });
+     * ```
+     */
+    lazyForm = input.required(...(ngDevMode ? [{ debugName: "lazyForm" }] : /* istanbul ignore next */ []));
+    /**
+     * Whether to automatically sync Angular validation state to grid's visual invalid styling.
+     *
+     * When enabled:
+     * - After a cell commit, if the FormControl is invalid, the cell is marked with `setInvalid()`
+     * - When a FormControl becomes valid, `clearInvalid()` is called
+     * - On `row-commit`, if the row's FormGroup has invalid controls, the commit is prevented
+     *
+     * @default true
+     */
+    syncValidation = input(true, ...(ngDevMode ? [{ debugName: "syncValidation" }] : /* istanbul ignore next */ []));
+    /**
+     * Whether to keep FormGroups cached after a row exits edit mode.
+     *
+     * - `true`: FormGroups are kept, preserving dirty/touched state across edit sessions
+     * - `false`: FormGroups are disposed when the row exits edit mode (default)
+     *
+     * @default false
+     */
+    keepFormGroups = input(false, ...(ngDevMode ? [{ debugName: "keepFormGroups" }] : /* istanbul ignore next */ []));
+    /**
+     * Emitted when a row's form values change.
+     * Useful for auto-save, validation display, or syncing to external state.
+     */
+    rowFormChange = output();
+    ngOnInit() {
+        const grid = this.elementRef.nativeElement;
+        if (!grid)
+            return;
+        // Store the form context for AngularGridAdapter to access
+        this.#storeFormContext(grid);
+        // Listen for cell-commit to update FormControl and sync validation
+        this.cellCommitUnsub = grid.on('cell-commit', (detail) => {
+            this.#handleCellCommit(detail);
+        });
+        // Listen for row-commit to sync FormGroup values back to row and cleanup
+        this.rowCommitUnsub = grid.on('row-commit', (detail, event) => {
+            this.#handleRowCommit(event, detail);
+        });
+        // Listen for rows-change to update row index mappings
+        this.rowsChangeUnsub = grid.on('rows-change', () => {
+            this.#updateRowIndexMap();
+        });
+        // Initial row index mapping
+        this.#updateRowIndexMap();
+    }
+    ngOnDestroy() {
+        const grid = this.elementRef.nativeElement;
+        if (!grid)
+            return;
+        this.cellCommitUnsub?.();
+        this.rowCommitUnsub?.();
+        this.rowsChangeUnsub?.();
+        this.#clearFormContext(grid);
+        this.formGroupCache.clear();
+        this.rowIndexMap.clear();
+    }
+    // #region FormArrayContext Implementation
+    /**
+     * Gets or creates the FormGroup for a row.
+     * This is the core lazy initialization logic.
+     */
+    #getOrCreateFormGroup(row, rowIndex) {
+        let formGroup = this.formGroupCache.get(row);
+        if (!formGroup) {
+            const factory = this.lazyForm();
+            formGroup = factory(row, rowIndex);
+            this.formGroupCache.set(row, formGroup);
+            this.rowIndexMap.set(row, rowIndex);
+        }
+        return formGroup;
+    }
+    /**
+     * Gets the FormGroup for a row if it exists (without creating).
+     */
+    #getRowFormGroup(rowIndex) {
+        const grid = this.elementRef.nativeElement;
+        const rows = grid?.rows;
+        if (!rows || rowIndex < 0 || rowIndex >= rows.length)
+            return undefined;
+        const row = rows[rowIndex];
+        return this.formGroupCache.get(row);
+    }
+    /**
+     * Stores the FormArrayContext on the grid element.
+     * This uses the same interface as GridFormArray for compatibility.
+     */
+    #storeFormContext(grid) {
+        const context = {
+            getRow: (rowIndex) => {
+                const rows = grid.rows;
+                if (!rows || rowIndex < 0 || rowIndex >= rows.length)
+                    return null;
+                return rows[rowIndex];
+            },
+            updateField: (rowIndex, field, value) => {
+                const formGroup = this.#getRowFormGroup(rowIndex);
+                if (formGroup) {
+                    const control = formGroup.get(field);
+                    if (control) {
+                        control.setValue(value);
+                        control.markAsDirty();
+                    }
+                }
+            },
+            getValue: () => {
+                return (grid.rows ?? []);
+            },
+            // Always true for lazy forms - we create FormGroups on demand
+            hasFormGroups: true,
+            getControl: (rowIndex, field) => {
+                const rows = grid.rows;
+                if (!rows || rowIndex < 0 || rowIndex >= rows.length)
+                    return undefined;
+                const row = rows[rowIndex];
+                // LAZY: Create the FormGroup when first needed
+                const formGroup = this.#getOrCreateFormGroup(row, rowIndex);
+                return formGroup.get(field) ?? undefined;
+            },
+            getRowFormGroup: (rowIndex) => {
+                const rows = grid.rows;
+                if (!rows || rowIndex < 0 || rowIndex >= rows.length)
+                    return undefined;
+                const row = rows[rowIndex];
+                // LAZY: Create the FormGroup when first needed
+                return this.#getOrCreateFormGroup(row, rowIndex);
+            },
+            isRowValid: (rowIndex) => {
+                const formGroup = this.#getRowFormGroup(rowIndex);
+                // If no FormGroup exists yet, consider it valid (not edited)
+                if (!formGroup)
+                    return true;
+                return formGroup.valid;
+            },
+            isRowTouched: (rowIndex) => {
+                const formGroup = this.#getRowFormGroup(rowIndex);
+                if (!formGroup)
+                    return false;
+                return formGroup.touched;
+            },
+            isRowDirty: (rowIndex) => {
+                const formGroup = this.#getRowFormGroup(rowIndex);
+                if (!formGroup)
+                    return false;
+                return formGroup.dirty;
+            },
+            getRowErrors: (rowIndex) => {
+                const formGroup = this.#getRowFormGroup(rowIndex);
+                if (!formGroup)
+                    return null;
+                const errors = {};
+                let hasErrors = false;
+                Object.keys(formGroup.controls).forEach((field) => {
+                    const control = formGroup.get(field);
+                    if (control?.errors) {
+                        errors[field] = control.errors;
+                        hasErrors = true;
+                    }
+                });
+                if (formGroup.errors) {
+                    errors['_group'] = formGroup.errors;
+                    hasErrors = true;
+                }
+                return hasErrors ? errors : null;
+            },
+        };
+        grid[FORM_ARRAY_CONTEXT] = context;
+    }
+    /**
+     * Clears the FormArrayContext from the grid element.
+     */
+    #clearFormContext(grid) {
+        delete grid[FORM_ARRAY_CONTEXT];
+    }
+    // #endregion
+    // #region Event Handlers
+    /**
+     * Updates the row index map when rows change.
+     * This ensures we can find FormGroups by row reference after sorting/filtering.
+     */
+    #updateRowIndexMap() {
+        const grid = this.elementRef.nativeElement;
+        const rows = grid?.rows;
+        if (!rows)
+            return;
+        this.rowIndexMap.clear();
+        rows.forEach((row, index) => {
+            if (this.formGroupCache.has(row)) {
+                this.rowIndexMap.set(row, index);
+            }
+        });
+    }
+    /**
+     * Handles cell-commit events by updating the FormControl in the FormGroup.
+     */
+    #handleCellCommit(detail) {
+        const { rowIndex, field, value, rowId } = detail;
+        const formGroup = this.#getRowFormGroup(rowIndex);
+        if (formGroup) {
+            const control = formGroup.get(field);
+            if (control) {
+                control.setValue(value);
+                control.markAsDirty();
+                control.markAsTouched();
+                // Sync Angular validation state to grid's visual invalid styling
+                if (this.syncValidation() && rowId) {
+                    this.#syncControlValidationToGrid(rowId, field, control);
+                }
+                // Emit change event
+                const grid = this.elementRef.nativeElement;
+                const row = grid?.rows?.[rowIndex];
+                if (row) {
+                    this.rowFormChange.emit({
+                        rowIndex,
+                        rowId,
+                        row,
+                        formGroup,
+                        values: formGroup.value,
+                        valid: formGroup.valid,
+                        dirty: formGroup.dirty,
+                    });
+                }
+            }
+        }
+    }
+    /**
+     * Handles row-commit events.
+     * - Prevents commit if FormGroup is invalid (when syncValidation is true)
+     * - Syncs FormGroup values back to the row
+     * - Cleans up FormGroup if keepFormGroups is false
+     */
+    #handleRowCommit(event, detail) {
+        const { rowIndex, rowId } = detail;
+        const grid = this.elementRef.nativeElement;
+        const rows = grid?.rows;
+        if (!rows || rowIndex < 0 || rowIndex >= rows.length)
+            return;
+        const row = rows[rowIndex];
+        const formGroup = this.formGroupCache.get(row);
+        if (!formGroup)
+            return;
+        // Prevent commit if invalid (when syncValidation is enabled)
+        if (this.syncValidation() && formGroup.invalid) {
+            // Mark all controls as touched to show validation errors
+            formGroup.markAllAsTouched();
+            event.preventDefault();
+            return;
+        }
+        // Sync FormGroup values back to the row object
+        if (formGroup.dirty) {
+            const formValue = formGroup.value;
+            Object.keys(formValue).forEach((field) => {
+                if (field in row) {
+                    row[field] = formValue[field];
+                }
+            });
+        }
+        // Clean up FormGroup if not keeping them
+        if (!this.keepFormGroups()) {
+            this.formGroupCache.delete(row);
+            this.rowIndexMap.delete(row);
+            // Clear any validation state in the grid
+            if (rowId) {
+                const editingPlugin = grid.getPluginByName?.('editing');
+                editingPlugin?.clearRowInvalid(rowId);
+            }
+        }
+    }
+    // #endregion
+    // #region Validation Sync
+    /**
+     * Syncs a FormControl's validation state to the grid's visual invalid styling.
+     */
+    #syncControlValidationToGrid(rowId, field, control) {
+        const grid = this.elementRef.nativeElement;
+        if (!grid)
+            return;
+        const editingPlugin = grid.getPluginByName?.('editing');
+        if (!editingPlugin)
+            return;
+        if (control.invalid) {
+            const errorMessage = this.#getFirstErrorMessage(control);
+            editingPlugin.setInvalid(rowId, field, errorMessage);
+        }
+        else {
+            editingPlugin.clearInvalid(rowId, field);
+        }
+    }
+    /**
+     * Gets a human-readable error message from the first validation error.
+     */
+    #getFirstErrorMessage(control) {
+        const errors = control.errors;
+        if (!errors)
+            return '';
+        const firstKey = Object.keys(errors)[0];
+        const error = errors[firstKey];
+        switch (firstKey) {
+            case 'required':
+                return 'This field is required';
+            case 'minlength':
+                return `Minimum length is ${error.requiredLength}`;
+            case 'maxlength':
+                return `Maximum length is ${error.requiredLength}`;
+            case 'min':
+                return `Minimum value is ${error.min}`;
+            case 'max':
+                return `Maximum value is ${error.max}`;
+            case 'email':
+                return 'Invalid email address';
+            case 'pattern':
+                return 'Invalid format';
+            default:
+                return typeof error === 'string' ? error : (error?.message ?? `Validation error: ${firstKey}`);
+        }
+    }
+    // #endregion
+    // #region Public API
+    /**
+     * Gets the FormGroup for a row, if it exists.
+     * Unlike the context methods, this does NOT create a FormGroup lazily.
+     *
+     * @param rowIndex The row index
+     * @returns The FormGroup or undefined
+     */
+    getFormGroup(rowIndex) {
+        return this.#getRowFormGroup(rowIndex);
+    }
+    /**
+     * Gets all cached FormGroups.
+     * Useful for bulk validation or inspection.
+     *
+     * @returns Map of row objects to their FormGroups
+     */
+    getAllFormGroups() {
+        return this.formGroupCache;
+    }
+    /**
+     * Clears all cached FormGroups.
+     * Useful when the underlying data changes significantly.
+     */
+    clearAllFormGroups() {
+        this.formGroupCache.clear();
+        this.rowIndexMap.clear();
+    }
+    /**
+     * Validates all currently cached FormGroups.
+     *
+     * @returns true if all FormGroups are valid, false otherwise
+     */
+    validateAll() {
+        for (const formGroup of this.formGroupCache.values()) {
+            if (formGroup.invalid) {
+                formGroup.markAllAsTouched();
+                return false;
+            }
+        }
+        return true;
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.5", ngImport: i0, type: GridLazyForm, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.2.5", type: GridLazyForm, isStandalone: true, selector: "tbw-grid[lazyForm]", inputs: { lazyForm: { classPropertyName: "lazyForm", publicName: "lazyForm", isSignal: true, isRequired: true, transformFunction: null }, syncValidation: { classPropertyName: "syncValidation", publicName: "syncValidation", isSignal: true, isRequired: false, transformFunction: null }, keepFormGroups: { classPropertyName: "keepFormGroups", publicName: "keepFormGroups", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { rowFormChange: "rowFormChange" }, ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.5", ngImport: i0, type: GridLazyForm, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: 'tbw-grid[lazyForm]',
+                }]
+        }], propDecorators: { lazyForm: [{ type: i0.Input, args: [{ isSignal: true, alias: "lazyForm", required: true }] }], syncValidation: [{ type: i0.Input, args: [{ isSignal: true, alias: "syncValidation", required: false }] }], keepFormGroups: [{ type: i0.Input, args: [{ isSignal: true, alias: "keepFormGroups", required: false }] }], rowFormChange: [{ type: i0.Output, args: ["rowFormChange"] }] } });
+
 /**
  * Editing feature for @toolbox-web/grid-angular
  *
@@ -116,6 +2348,87 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.5", ngImpor
  *
  * @packageDocumentation
  */
+// ---------------------------------------------------------------------------
+// Install the template-based editor bridge. The grid adapter delegates
+// `createEditor()` / `canHandle()` to this function, which resolves the
+// Angular editor template (`*tbwEditor` or nested `<tbw-grid-column-editor>`),
+// wires the FormArray control (if the grid is bound to a FormArray), and
+// mounts the template via the adapter's generic editor-view primitive.
+// ---------------------------------------------------------------------------
+registerEditorSpecBridge((element, adapter) => {
+    // Resolve the editor template: structural `*tbwEditor` first, then the
+    // nested `<tbw-grid-column-editor>` directive. The cast target is derived
+    // from `getStructuralEditorTemplate` (same package instance as the adapter),
+    // NOT from a local `import type { TemplateRef } from '@angular/core'` — the
+    // latter resolves through Bun's `.bun/` cache during ng-packagr build and
+    // produces a brand-incompatible `TemplateRef` vs the built adapter `.d.ts`
+    // (see the shell feature entry for the same guard). `StructuralEditorContext`
+    // uses `any` type defaults, which preserves assignability with the generic
+    // `GridEditorContext<TValue, TRow>` at the `createEditorTemplateView` call.
+    const template = (getStructuralEditorTemplate(element) ?? getEditorTemplate(element));
+    if (!template) {
+        // No template registered — let the grid use its built-in editors. This
+        // allows columns with only `*tbwRenderer` (no `*tbwEditor`) to remain
+        // editable via the default text/number/boolean editors.
+        return undefined;
+    }
+    // Find the parent grid element for FormArray context access.
+    const gridElement = element.closest('tbw-grid, [data-tbw-grid]');
+    return (ctx) => {
+        const onCommit = (value) => ctx.commit(value);
+        const onCancel = () => ctx.cancel();
+        // Resolve the FormControl from the FormArrayContext, if available.
+        let control;
+        if (gridElement) {
+            const formContext = getFormArrayContext(gridElement);
+            if (formContext?.hasFormGroups) {
+                const gridRows = gridElement.rows;
+                if (gridRows) {
+                    const rowIndex = gridRows.indexOf(ctx.row);
+                    if (rowIndex >= 0) {
+                        control = formContext.getControl(rowIndex, ctx.field);
+                    }
+                }
+            }
+        }
+        const context = {
+            $implicit: ctx.value,
+            value: ctx.value,
+            row: ctx.row,
+            field: ctx.field,
+            column: ctx.column,
+            rowId: ctx.rowId ?? '',
+            onCommit,
+            onCancel,
+            updateRow: ctx.updateRow,
+            onValueChange: ctx.onValueChange,
+            control,
+        };
+        // Mount the template via the adapter's generic editor-view primitive
+        // (tracks the view in the per-cell editor pool, wraps root nodes in a
+        // stable `display:contents` span, and runs editor-mount hooks).
+        const { container, viewRef } = adapter.createEditorTemplateView(template, context);
+        // Auto-wire: listen for commit/cancel events on the rendered component so
+        // components can just emit `(commit)` / `(cancel)` without explicit
+        // template bindings.
+        container.addEventListener('commit', (e) => {
+            ctx.commit(e.detail);
+        });
+        container.addEventListener('cancel', () => {
+            ctx.cancel();
+        });
+        // Auto-update the editor when the value changes externally (e.g. updateRow
+        // cascade or Escape-revert). Angular's own bindings/control flow handle the
+        // re-render; we just re-sync root nodes in case control flow changed them.
+        ctx.onValueChange?.((newVal) => {
+            context.$implicit = newVal;
+            context.value = newVal;
+            viewRef.detectChanges();
+            adapter.syncEditorTemplateView(viewRef, container);
+        });
+        return container;
+    };
+});
 // Bridge the editing plugin's `before-edit-close` event to a synchronous
 // `.blur()` on the focused input/textarea/select inside the editor host.
 // Angular editors that commit on `(blur)` rely on the focused control firing
@@ -131,5 +2444,5 @@ registerEditorMountHook(({ container, gridEl }) => {
  * Generated bundle index. Do not edit.
  */
 
-export { GridEditingDirective };
+export { BaseGridEditor, BaseGridEditorCVA, BaseOverlayEditor, GridColumnEditor, GridEditingDirective, GridFormArray, GridLazyForm, TbwEditor, getEditorTemplate, getFormArrayContext, getLazyFormContext, getStructuralEditorTemplate };
 //# sourceMappingURL=toolbox-web-grid-angular-features-editing.mjs.map