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

package/types/toolbox-web-grid-angular-features-editing.d.ts

@@ -1,9 +1,10 @@
 export { _Augmentation as _EditingAugmentation } from '@toolbox-web/grid/features/editing';
 import * as _angular_core from '@angular/core';
-import { OnInit, OnDestroy } from '@angular/core';
+import { OnInit, OnDestroy, ElementRef, TemplateRef } from '@angular/core';
 import { CellCommitEvent, RowCommitEvent } from '@toolbox-web/grid-angular';
-export { BaseGridEditor, BaseGridEditorCVA, BaseOverlayEditor, FormArrayContext, GridColumnEditor, GridEditorContext, GridFormArray, GridLazyForm, LazyFormFactory, OverlayPosition, RowFormChangeEvent, StructuralEditorContext, TbwEditor, getFormArrayContext, getLazyFormContext } from '@toolbox-web/grid-angular';
 import { EditingConfig, CellCancelDetail, ChangedRowsResetDetail, EditOpenDetail, BeforeEditCloseDetail, EditCloseDetail, DirtyChangeDetail } from '@toolbox-web/grid/plugins/editing';
+import { AbstractControl, ControlValueAccessor, FormGroup, FormArray } from '@angular/forms';
+import { ColumnConfig } from '@toolbox-web/grid';
 
 /**
  * Owns the binding(s) `[editing], [cellCommit], [cellCancel], [rowCommit], [changedRowsReset], [editOpen], [beforeEditClose], [editClose], [dirtyChange]` on `<tbw-grid>` for the matching feature plugin. See `GridFilteringDirective` for the full rationale.
@@ -12,7 +13,7 @@ import { EditingConfig, CellCancelDetail, ChangedRowsResetDetail, EditOpenDetail
  */
 declare class GridEditingDirective implements OnInit, OnDestroy {
     private readonly elementRef;
-    readonly editing: _angular_core.InputSignal<boolean | EditingConfig | "click" | "dblclick" | "manual" | undefined>;
+    readonly editing: _angular_core.InputSignal<boolean | "click" | EditingConfig | "dblclick" | "manual" | undefined>;
     readonly cellCommit: _angular_core.OutputEmitterRef<CellCommitEvent<unknown, unknown>>;
     readonly cellCancel: _angular_core.OutputEmitterRef<CellCancelDetail>;
     readonly rowCommit: _angular_core.OutputEmitterRef<RowCommitEvent<unknown>>;
@@ -30,5 +31,1181 @@ declare class GridEditingDirective implements OnInit, OnDestroy {
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<GridEditingDirective, "tbw-grid[editing], tbw-grid[cellCommit], tbw-grid[cellCancel], tbw-grid[rowCommit], tbw-grid[changedRowsReset], tbw-grid[editOpen], tbw-grid[beforeEditClose], tbw-grid[editClose], tbw-grid[dirtyChange]", never, { "editing": { "alias": "editing"; "required": false; "isSignal": true; }; }, { "cellCommit": "cellCommit"; "cellCancel": "cellCancel"; "rowCommit": "rowCommit"; "changedRowsReset": "changedRowsReset"; "editOpen": "editOpen"; "beforeEditClose": "beforeEditClose"; "editClose": "editClose"; "dirtyChange": "dirtyChange"; }, never, never, true, never>;
 }
 
-export { GridEditingDirective };
+/**
+ * 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
+ */
+declare abstract class BaseGridEditor<TRow = unknown, TValue = unknown> {
+    protected readonly elementRef: ElementRef<any>;
+    private readonly _destroyRef;
+    /** Cleanup function for the edit-close listener */
+    private _editCloseCleanup;
+    /**
+     * The cell value. Used when FormControl is not available.
+     * When a FormControl is provided, value is derived from control.value instead.
+     */
+    readonly value: _angular_core.InputSignal<TValue | undefined>;
+    /**
+     * The full row data object.
+     */
+    readonly row: _angular_core.InputSignal<TRow | undefined>;
+    /**
+     * The column configuration.
+     */
+    readonly column: _angular_core.InputSignal<ColumnConfig<TRow> | undefined>;
+    /**
+     * 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.
+     */
+    readonly control: _angular_core.InputSignal<AbstractControl<any, any, any> | undefined>;
+    /**
+     * Emits when the user commits a new value.
+     * Emits `null` when a nullable field is cleared.
+     */
+    readonly commit: _angular_core.OutputEmitterRef<TValue | null>;
+    /**
+     * Emits when the user cancels editing.
+     */
+    readonly cancel: _angular_core.OutputEmitterRef<void>;
+    /**
+     * 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.
+     */
+    readonly currentValue: _angular_core.Signal<TValue | undefined>;
+    /**
+     * Whether the control is invalid (has validation errors).
+     * Returns false if no FormControl is available.
+     */
+    readonly isInvalid: _angular_core.Signal<boolean>;
+    /**
+     * Whether the control is dirty (has been modified).
+     * Returns false if no FormControl is available.
+     */
+    readonly isDirty: _angular_core.Signal<boolean>;
+    /**
+     * Whether the control has been touched.
+     * Returns false if no FormControl is available.
+     */
+    readonly isTouched: _angular_core.Signal<boolean>;
+    /**
+     * Whether the control has any validation errors.
+     */
+    readonly hasErrors: _angular_core.Signal<boolean>;
+    /**
+     * The first error message from the control's validation errors.
+     * Returns an empty string if no errors.
+     */
+    readonly firstErrorMessage: _angular_core.Signal<string>;
+    /**
+     * All error messages from the control's validation errors.
+     */
+    readonly allErrorMessages: _angular_core.Signal<string[]>;
+    constructor();
+    private _initEditCloseListener;
+    /**
+     * 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`.
+     */
+    protected isCellFocused(): boolean;
+    /**
+     * 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.
+     */
+    protected onBeforeEditClose(): void;
+    /**
+     * 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.
+     */
+    protected onEditClose(): void;
+    /**
+     * 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: TValue): void;
+    /**
+     * 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: TValue | null): void;
+    /**
+     * Cancel editing. Emits the cancel output AND dispatches a DOM event.
+     * Call this when the user cancels (e.g., presses Escape).
+     */
+    cancelEdit(): void;
+    /**
+     * 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
+     */
+    protected getErrorMessage(errorKey: string, errorValue?: unknown): string;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<BaseGridEditor<any, any>, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<BaseGridEditor<any, any>, never, never, { "value": { "alias": "value"; "required": false; "isSignal": true; }; "row": { "alias": "row"; "required": false; "isSignal": true; }; "column": { "alias": "column"; "required": false; "isSignal": true; }; "control": { "alias": "control"; "required": false; "isSignal": true; }; }, { "commit": "commit"; "cancel": "cancel"; }, never, never, true, never>;
+}
+
+/**
+ * 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
+ */
+declare abstract class BaseGridEditorCVA<TRow = unknown, TValue = unknown> extends BaseGridEditor<TRow, TValue> implements ControlValueAccessor {
+    /** Internal onChange callback registered by the form control. */
+    private _onChange;
+    /** Internal onTouched callback registered by the form control. */
+    private _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`).
+     */
+    protected readonly cvaValue: _angular_core.WritableSignal<TValue | null>;
+    /**
+     * Signal tracking the disabled state set by the form control.
+     * Updated when `setDisabledState()` is called by Angular's forms module.
+     */
+    readonly disabledState: _angular_core.WritableSignal<boolean>;
+    /**
+     * 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.
+     */
+    readonly displayValue: _angular_core.Signal<TValue | null>;
+    /**
+     * Called by Angular forms when the form control value changes programmatically.
+     */
+    writeValue(value: TValue | null): void;
+    /**
+     * Called by Angular forms to register a change callback.
+     */
+    registerOnChange(fn: (value: TValue | null) => void): void;
+    /**
+     * Called by Angular forms to register a touched callback.
+     */
+    registerOnTouched(fn: () => void): void;
+    /**
+     * Called by Angular forms to set the disabled state.
+     */
+    setDisabledState(isDisabled: boolean): void;
+    /**
+     * 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
+     */
+    protected commitBoth(value: TValue | null): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<BaseGridEditorCVA<any, any>, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<BaseGridEditorCVA<any, any>, never, never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Position of the overlay panel relative to its anchor cell.
+ *
+ * - `'below'` — panel appears below the cell, left-aligned (default)
+ * - `'above'` — panel appears above the cell, left-aligned
+ * - `'below-right'` — panel appears below the cell, right-aligned
+ * - `'over-top-left'` — panel top-left corner aligns with cell top-left corner (opens downward)
+ * - `'over-bottom-left'` — panel bottom-left corner aligns with cell bottom-left corner (opens upward)
+ * @since 0.13.0
+ */
+type OverlayPosition = 'below' | 'above' | 'below-right' | 'over-top-left' | 'over-bottom-left';
+/**
+ * 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
+ */
+declare abstract class BaseOverlayEditor<TRow = unknown, TValue = unknown> extends BaseGridEditor<TRow, TValue> {
+    private readonly _elementRef;
+    private readonly _overlayDestroyRef;
+    /**
+     * Position of the overlay panel relative to the anchor cell.
+     * Override in subclasses to change the default position.
+     *
+     * @default 'below'
+     */
+    protected overlayPosition: OverlayPosition;
+    /** The overlay panel element (set via `initOverlay()`). */
+    private _panel;
+    /** Whether the overlay is currently visible. */
+    protected _isOpen: boolean;
+    /** Unique anchor ID for CSS Anchor Positioning. */
+    private _anchorId;
+    /** Whether the browser supports CSS Anchor Positioning. */
+    private _supportsAnchor;
+    /** AbortController for all overlay-related listeners. */
+    private _abortCtrl;
+    /** MutationObserver watching cell focus class changes. */
+    protected _focusObserver: MutationObserver | null;
+    constructor();
+    /**
+     * 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
+     */
+    protected initOverlay(panel: HTMLElement): void;
+    /**
+     * Show the overlay panel.
+     *
+     * If CSS Anchor Positioning is not supported, falls back to JS-based
+     * positioning using `getBoundingClientRect()`.
+     */
+    protected showOverlay(): void;
+    /**
+     * Hide the overlay panel.
+     *
+     * @param suppressTabAdvance - When `true`, skip synthetic Tab dispatch
+     *   (useful when hiding is triggered by an external focus change).
+     */
+    protected hideOverlay(suppressTabAdvance?: boolean): void;
+    /**
+     * Close and immediately re-open the overlay.
+     * Useful after the panel content changes size and needs repositioning.
+     */
+    protected reopenOverlay(): void;
+    /**
+     * 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.
+     */
+    protected teardownOverlay(): void;
+    /**
+     * Override in `edit-close` handler to also hide the overlay.
+     * This is called automatically by `BaseGridEditor` when the grid
+     * ends the editing session.
+     */
+    protected onEditClose(): void;
+    /**
+     * 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: KeyboardEvent): void;
+    /**
+     * Click handler for the inline input.
+     * Opens the overlay and calls {@link onOverlayOpened}.
+     *
+     * Bind this to `(click)` on your inline input element.
+     */
+    onInlineClick(): void;
+    /**
+     * 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.
+     */
+    protected handleEscape(event: Event): void;
+    /**
+     * 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.
+     */
+    protected advanceGridFocus(backward?: boolean): void;
+    /**
+     * Return the inline input element, if any.
+     *
+     * Used by overlay infrastructure to return focus after hiding.
+     * Return `null` if there is no inline input.
+     */
+    protected abstract getInlineInput(): HTMLInputElement | null;
+    /**
+     * Called when a pointerdown event occurs outside the overlay panel
+     * and outside the editor's host element.
+     *
+     * Typically, subclasses call `hideOverlay()` here.
+     */
+    protected abstract onOverlayOutsideClick(): void;
+    /**
+     * Called after the overlay is shown.
+     *
+     * Override to focus an element inside the panel, start animations, etc.
+     * Default implementation is a no-op.
+     */
+    protected onOverlayOpened(): void;
+    /** Find the parent cell element for this editor. */
+    private _getCell;
+    /** Find the parent `<tbw-grid>` element for this editor. */
+    private _getGridElement;
+    /**
+     * JS fallback positioning for browsers without CSS Anchor Positioning.
+     * Uses `getBoundingClientRect()` with viewport overflow detection.
+     */
+    private _positionWithJs;
+    /**
+     * Document pointerdown handler for click-outside detection.
+     * Fires `onOverlayOutsideClick()` if the click is outside the panel
+     * and outside the editor's host element.
+     */
+    private _onDocumentPointerDown;
+    /**
+     * 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.
+     */
+    private _onGridScroll;
+    /**
+     * 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.
+     */
+    protected _setupFocusObserver(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<BaseOverlayEditor<any, any>, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<BaseOverlayEditor<any, any>, never, never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Context object passed to the cell editor template.
+ * Contains the cell value, row data, column configuration, and commit/cancel functions.
+ * @since 0.1.0
+ */
+interface GridEditorContext<TValue = unknown, TRow = unknown> {
+    /** The cell value for this column */
+    $implicit: TValue;
+    /** The cell value (explicit binding) */
+    value: TValue;
+    /** The full row data object */
+    row: TRow;
+    /** Field name being edited */
+    field: string;
+    /** The column configuration */
+    column: unknown;
+    /** Stable row identifier (from `getRowId`). Empty string if no `getRowId` is configured. */
+    rowId: string;
+    /**
+     * Callback function to commit the edited value.
+     * Use with Angular event binding: `(commit)="onCommit($event)"`
+     */
+    onCommit: (value: TValue) => void;
+    /**
+     * Callback function to cancel editing.
+     * Use with Angular event binding: `(cancel)="onCancel()"`
+     */
+    onCancel: () => void;
+    /**
+     * Update other fields in this row while the editor is open.
+     * Changes trigger `cell-change` events with source `'cascade'`.
+     */
+    updateRow: (changes: Partial<TRow>) => void;
+    /**
+     * Register a callback to receive value updates when the cell is modified
+     * externally (e.g., via `updateRow()` from another cell's commit).
+     *
+     * The framework adapter auto-patches `value`/`$implicit` for template editors,
+     * but custom components may use this for additional reactivity.
+     */
+    onValueChange?: (callback: (newValue: TValue) => void) => void;
+    /**
+     * The FormControl for this cell, if the grid is bound to a FormArray with FormGroups.
+     *
+     * This allows custom editors to bind directly to the control for validation display:
+     * ```html
+     * <input *tbwEditor="let value; control as ctrl"
+     *        [formControl]="ctrl"
+     *        [class.is-invalid]="ctrl?.invalid && ctrl?.touched" />
+     * ```
+     *
+     * Returns `undefined` if:
+     * - The grid is not bound to a FormArray
+     * - The FormArray doesn't contain FormGroups
+     * - The field doesn't exist in the FormGroup
+     */
+    control?: AbstractControl;
+}
+/**
+ * Gets the editor template registered for a given element.
+ * Used by AngularGridAdapter to retrieve templates at render time.
+ */
+declare function getEditorTemplate(element: HTMLElement): TemplateRef<GridEditorContext> | undefined;
+/**
+ * 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
+ */
+declare class GridColumnEditor {
+    private elementRef;
+    /**
+     * Query for the ng-template content child.
+     */
+    template: _angular_core.Signal<TemplateRef<any> | undefined>;
+    /** Effect that triggers when the template is available */
+    private onTemplateReceived;
+    /**
+     * Static type guard for template context.
+     * Enables type inference in templates.
+     */
+    static ngTemplateContextGuard(dir: GridColumnEditor, ctx: unknown): ctx is GridEditorContext;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<GridColumnEditor, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<GridColumnEditor, "tbw-grid-column-editor", never, {}, {}, ["template"], never, true, never>;
+}
+
+/**
+ * Context provided to the grid containing form-related information.
+ * This can be accessed by other directives to get form controls.
+ * @since 0.5.0
+ */
+interface FormArrayContext {
+    /** Get the row data at a specific index */
+    getRow<T = unknown>(rowIndex: number): T | null;
+    /** Update a field value at a specific row */
+    updateField(rowIndex: number, field: string, value: unknown): void;
+    /** Get the current form value (all rows) */
+    getValue<T = unknown>(): T[];
+    /**
+     * Get the FormControl for a specific cell.
+     * Only available when using FormArray with FormGroup rows.
+     *
+     * @param rowIndex - The row index
+     * @param field - The field name
+     * @returns The AbstractControl for the cell, or undefined if not available
+     */
+    getControl(rowIndex: number, field: string): AbstractControl | undefined;
+    /**
+     * Whether the grid is backed by a FormArray of FormGroups.
+     * When true, `getControl()` will return cell-level controls.
+     */
+    hasFormGroups: boolean;
+    /**
+     * Get the FormGroup for a specific row.
+     * Only available when using FormArray with FormGroup rows.
+     *
+     * @param rowIndex - The row index
+     * @returns The FormGroup for the row, or undefined if not available
+     */
+    getRowFormGroup(rowIndex: number): FormGroup | undefined;
+    /**
+     * Check if a row is valid (all controls in the FormGroup are valid).
+     * Returns true if not using FormArray or if the row doesn't exist.
+     *
+     * @param rowIndex - The row index
+     * @returns true if the row is valid, false if any control is invalid
+     */
+    isRowValid(rowIndex: number): boolean;
+    /**
+     * Check if a row has been touched (any control in the FormGroup is touched).
+     * Returns false if not using FormArray or if the row doesn't exist.
+     *
+     * @param rowIndex - The row index
+     * @returns true if any control in the row is touched
+     */
+    isRowTouched(rowIndex: number): boolean;
+    /**
+     * Check if a row is dirty (any control in the FormGroup is dirty).
+     * Returns false if not using FormArray or if the row doesn't exist.
+     *
+     * @param rowIndex - The row index
+     * @returns true if any control in the row is dirty
+     */
+    isRowDirty(rowIndex: number): boolean;
+    /**
+     * Get validation errors for a specific row.
+     * Aggregates errors from all controls in the FormGroup.
+     *
+     * @param rowIndex - The row index
+     * @returns Object with field names as keys and their errors, or null if no errors
+     */
+    getRowErrors(rowIndex: number): Record<string, unknown> | null;
+}
+/**
+ * Gets the FormArrayContext from a grid element, if present.
+ * @internal
+ * @since 0.5.0
+ */
+declare function getFormArrayContext(gridElement: HTMLElement): FormArrayContext | undefined;
+/**
+ * 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
+ */
+declare class GridFormArray implements OnInit, OnDestroy {
+    #private;
+    private readonly destroyRef;
+    private elementRef;
+    private cellCommitUnsub;
+    private cellCancelUnsub;
+    private rowCommitUnsub;
+    private touchListener;
+    private valueChangesSubscription;
+    private statusChangesSubscriptions;
+    /**
+     * The FormArray to bind to the grid.
+     */
+    readonly formArray: _angular_core.InputSignal<FormArray<any>>;
+    /**
+     * 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
+     */
+    readonly syncValidation: _angular_core.InputSignal<boolean>;
+    /**
+     * Effect that sets up valueChanges subscription when FormArray changes.
+     * This handles both initial binding and when the FormArray reference changes.
+     */
+    private syncFormArrayToGrid;
+    ngOnInit(): void;
+    ngOnDestroy(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<GridFormArray, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<GridFormArray, "tbw-grid[formArray]", never, { "formArray": { "alias": "formArray"; "required": true; "isSignal": true; }; "syncValidation": { "alias": "syncValidation"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Gets the FormArrayContext from a grid element, if present.
+ * @internal
+ * @since 0.11.0
+ */
+declare function getLazyFormContext(gridElement: HTMLElement): FormArrayContext | undefined;
+/**
+ * Factory function type for creating FormGroups lazily.
+ * Called when a row enters edit mode for the first time.
+ *
+ * @template TRow The row data type
+ * @param row The row data object
+ * @param rowIndex The row index in the grid
+ * @returns A FormGroup for the row (only include editable fields)
+ * @since 0.11.0
+ */
+type LazyFormFactory<TRow = unknown> = (row: TRow, rowIndex: number) => FormGroup;
+/**
+ * Event emitted when a row's form values have changed.
+ * @since 0.11.0
+ */
+interface RowFormChangeEvent<TRow = unknown> {
+    /** The row index */
+    rowIndex: number;
+    /** The row ID (if available) */
+    rowId?: string;
+    /** The original row data */
+    row: TRow;
+    /** The FormGroup for this row */
+    formGroup: FormGroup;
+    /** The current form values */
+    values: Partial<TRow>;
+    /** Whether the form is valid */
+    valid: boolean;
+    /** Whether the form is dirty */
+    dirty: boolean;
+}
+/**
+ * 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
+ */
+declare class GridLazyForm<TRow = unknown> implements OnInit, OnDestroy {
+    #private;
+    private elementRef;
+    private formGroupCache;
+    private rowIndexMap;
+    private editingRowIndex;
+    private cellCommitUnsub;
+    private rowCommitUnsub;
+    private rowsChangeUnsub;
+    /**
+     * 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)]],
+     * });
+     * ```
+     */
+    readonly lazyForm: _angular_core.InputSignal<LazyFormFactory<TRow>>;
+    /**
+     * 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
+     */
+    readonly syncValidation: _angular_core.InputSignal<boolean>;
+    /**
+     * 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
+     */
+    readonly keepFormGroups: _angular_core.InputSignal<boolean>;
+    /**
+     * Emitted when a row's form values change.
+     * Useful for auto-save, validation display, or syncing to external state.
+     */
+    readonly rowFormChange: _angular_core.OutputEmitterRef<RowFormChangeEvent<TRow>>;
+    ngOnInit(): void;
+    ngOnDestroy(): void;
+    /**
+     * 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: number): FormGroup | undefined;
+    /**
+     * Gets all cached FormGroups.
+     * Useful for bulk validation or inspection.
+     *
+     * @returns Map of row objects to their FormGroups
+     */
+    getAllFormGroups(): ReadonlyMap<TRow, FormGroup>;
+    /**
+     * Clears all cached FormGroups.
+     * Useful when the underlying data changes significantly.
+     */
+    clearAllFormGroups(): void;
+    /**
+     * Validates all currently cached FormGroups.
+     *
+     * @returns true if all FormGroups are valid, false otherwise
+     */
+    validateAll(): boolean;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<GridLazyForm<any>, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<GridLazyForm<any>, "tbw-grid[lazyForm]", never, { "lazyForm": { "alias": "lazyForm"; "required": true; "isSignal": true; }; "syncValidation": { "alias": "syncValidation"; "required": false; "isSignal": true; }; "keepFormGroups": { "alias": "keepFormGroups"; "required": false; "isSignal": true; }; }, { "rowFormChange": "rowFormChange"; }, never, never, true, never>;
+}
+
+/**
+ * Context type for structural editor directives with `any` defaults.
+ * This provides better ergonomics in templates without requiring explicit type annotations.
+ *
+ * @internal Use `GridEditorContext` in application code for stricter typing.
+ * @since 0.1.1
+ */
+interface StructuralEditorContext<TValue = any, TRow = any> {
+    /** The cell value for this column */
+    $implicit: TValue;
+    /** The cell value (explicit binding) */
+    value: TValue;
+    /** The full row data object */
+    row: TRow;
+    /** The column configuration */
+    column: any;
+    /**
+     * Callback function to commit the edited value.
+     */
+    onCommit: (value: TValue) => void;
+    /**
+     * Callback function to cancel editing.
+     */
+    onCancel: () => void;
+    /**
+     * The FormControl for this cell, if the grid is bound to a FormArray with FormGroups.
+     *
+     * Returns `undefined` if:
+     * - The grid is not bound to a FormArray
+     * - The FormArray doesn't contain FormGroups
+     * - The field doesn't exist in the FormGroup
+     */
+    control?: AbstractControl;
+}
+/**
+ * Gets the editor template registered by the structural directive for a given column element.
+ * Falls back to the non-structural directive registry.
+ */
+declare function getStructuralEditorTemplate(columnElement: HTMLElement): TemplateRef<StructuralEditorContext> | 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
+ */
+declare class TbwEditor implements OnDestroy {
+    private template;
+    private elementRef;
+    private columnElement;
+    constructor();
+    private registerTemplate;
+    ngOnDestroy(): void;
+    /**
+     * Static type guard for template context.
+     * Uses `any` defaults for ergonomic template usage.
+     */
+    static ngTemplateContextGuard(dir: TbwEditor, ctx: unknown): ctx is StructuralEditorContext;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TbwEditor, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<TbwEditor, "[tbwEditor]", never, {}, {}, never, never, true, never>;
+}
+
+export { BaseGridEditor, BaseGridEditorCVA, BaseOverlayEditor, GridColumnEditor, GridEditingDirective, GridFormArray, GridLazyForm, TbwEditor, getEditorTemplate, getFormArrayContext, getLazyFormContext, getStructuralEditorTemplate };
+export type { FormArrayContext, GridEditorContext, LazyFormFactory, OverlayPosition, RowFormChangeEvent, StructuralEditorContext };
 //# sourceMappingURL=toolbox-web-grid-angular-features-editing.d.ts.map