@ornery/ui-grid-vanilla 0.1.10 → 1.0.0

package/dist/index.d.mts

@@ -1,14 +1,217 @@
-import { GridOptions, GridLabels, GridColumnDef, PipelineResult, SortState, PinnedColumnState, GridCellPosition, UiGridApi, GridRecord, DisplayItem, SortDirection, PinDirection, GridRow, GroupItem, BuildGridPipelineContext } from '@ornery/ui-grid-core';
+import { GridCellTemplateContext, GridLabels, GridExpandableTemplateContext, GridColumnDef, GridHeaderTemplateContext, GridRow, GroupItem, GridOptions, PipelineResult, SortState, PinnedColumnState, GridCellPosition, UiGridApi, GridRecord, DisplayItem, SortDirection, PinDirection, GridSelectionState, resolveGridSelectionOptions, GridInfiniteScrollState, GridValidatorRegistry, BuildGridPipelineContext } from '@ornery/ui-grid-core';
 export { GridOptions, UiGridApi } from '@ornery/ui-grid-core';
 
+/**
+ * Framework-rendered slot bridge for the vanilla grid element.
+ *
+ * The vanilla grid renders every cell / header / filter / group / expandable
+ * / empty-state via string-interpolated templates by default. When a
+ * framework wrapper (Angular, React, or any other consumer) wants to own
+ * rendering of a slot with its own templating engine, it calls
+ * `setFrameworkRenderedSlots()` on the element to flip slot kinds into
+ * "slot placeholder" mode.
+ *
+ * In that mode the element emits `<slot name="…">` placeholders at the
+ * usual render sites. The wrapper listens for the `*SlotsChanged` event
+ * this module dispatches and inserts light-DOM nodes with matching `slot`
+ * attributes carrying its framework-rendered content. Slot projection then
+ * composes the wrapper's view back into the shadow tree without the
+ * wrapper ever touching the shadow DOM directly.
+ *
+ * Slot naming conventions:
+ *   - `cell-<columnName>-<rowId>`     per-cell (one slot per rendered body cell)
+ *   - `header-<columnName>`           per-column, singleton
+ *   - `filter-<columnName>`           per-column, singleton
+ *   - `group-row-<groupId>`           per-group
+ *   - `expandable-row-<rowId>`        per-row
+ *   - `empty`                         singleton
+ */
+
+/** Which slot kinds the element should render as `<slot>` placeholders. */
+interface FrameworkRenderedSlotsConfig {
+    /** Column names whose body cells are framework-rendered. Everything else
+     * continues to use the vanilla interpolation path. */
+    cells?: readonly string[];
+    /** Column names whose header cells are framework-rendered. */
+    headers?: readonly string[];
+    /** Column names whose filter cells are framework-rendered. */
+    filters?: readonly string[];
+    /** When true, group rows are emitted as slot placeholders. */
+    groupRow?: boolean;
+    /** When true, expandable detail rows are emitted as slot placeholders. */
+    expandableRow?: boolean;
+    /** When true, the empty-state panel is emitted as a slot placeholder. */
+    emptyState?: boolean;
+}
+interface FrameworkCellSlot {
+    slotName: string;
+    columnName: string;
+    rowId: string;
+    rowIndex: number;
+    context: GridCellTemplateContext;
+}
+interface FrameworkHeaderSlot {
+    slotName: string;
+    columnName: string;
+    context: GridHeaderTemplateContext;
+}
+interface FrameworkFilterSlot {
+    slotName: string;
+    columnName: string;
+    value: string;
+    placeholder: string;
+    disabled: boolean;
+    column: GridColumnDef;
+}
+interface FrameworkGroupRowSlot {
+    slotName: string;
+    groupId: string;
+    field: string;
+    label: string;
+    count: number;
+    depth: number;
+    collapsed: boolean;
+}
+interface FrameworkExpandableRowSlot {
+    slotName: string;
+    rowId: string;
+    rowIndex: number;
+    context: GridExpandableTemplateContext;
+}
+interface FrameworkEmptyStateSlot {
+    slotName: 'empty';
+    heading: string;
+    description: string;
+    labels: GridLabels;
+}
+interface FrameworkSlotDelta<TSlot> {
+    added: TSlot[];
+    removed: TSlot[];
+}
+/**
+ * Bridge state + behavior. The element creates one instance, reads the
+ * `has*` methods during render to decide which path to take, calls the
+ * `stage*` methods as it emits slot placeholders, and calls `flush()` at
+ * the end of each render pass to emit the add/remove delta.
+ */
+declare class FrameworkSlotBridge {
+    private readonly host;
+    private flaggedCells;
+    private flaggedHeaders;
+    private flaggedFilters;
+    private flaggedGroupRow;
+    private flaggedExpandableRow;
+    private flaggedEmptyState;
+    private lastCellSlots;
+    private lastExpandableRowSlots;
+    private lastGroupRowSlots;
+    private lastHeaderSlots;
+    private lastFilterSlots;
+    private lastEmptyStateSlot;
+    private pendingCellSlots;
+    private pendingExpandableRowSlots;
+    private pendingGroupRowSlots;
+    private pendingHeaderSlots;
+    private pendingFilterSlots;
+    private pendingEmptyStateSlot;
+    constructor(host: EventTarget);
+    /**
+     * Apply a slots config. Returns true when the structural set changed (and
+     * therefore a re-render is required), false when the config is a no-op.
+     */
+    configure(config: FrameworkRenderedSlotsConfig): boolean;
+    hasCell(columnName: string): boolean;
+    hasHeader(columnName: string): boolean;
+    hasFilter(columnName: string): boolean;
+    hasGroupRow(): boolean;
+    hasExpandableRow(): boolean;
+    hasEmptyState(): boolean;
+    stageCell(column: GridColumnDef, row: GridRow, rowIndex: number): void;
+    stageExpandableRow(row: GridRow, rowIndex: number): void;
+    stageGroupRow(group: GroupItem): void;
+    stageHeader(column: GridColumnDef): void;
+    stageFilter(column: GridColumnDef, value: string, placeholder: string, disabled: boolean): void;
+    stageEmptyState(heading: string, description: string, labels: GridLabels): void;
+    /**
+     * Diff pending vs. last, dispatch `*SlotsChanged` events for every kind
+     * that moved, then swap last = pending and reset pending. Called at the
+     * end of every render pass.
+     */
+    flush(): void;
+    /**
+     * Data-only patch variant: merge pending entries into last without firing
+     * events, since the slot structure hasn't changed (only cell contexts
+     * refreshed). Wrappers that need context updates subscribe to
+     * `rowsVisibleChanged`.
+     */
+    mergePendingIntoLast(): void;
+    /**
+     * On element teardown, emit `removed` for every remaining slot so wrappers
+     * can destroy their views.
+     */
+    flushRemovals(): void;
+    private diffAndEmit;
+    private diffAndEmitSingleton;
+}
+
+/**
+ * Icon registry for the vanilla grid element.
+ *
+ * The grid draws its own sort / group / tree / expand / pin / pagination
+ * icons via inline SVGs. Consumers can override any individual icon by
+ * passing an `iconOverrides` map in GridOptions or by writing to the
+ * element's `controlIcons` property at runtime. This module owns the
+ * icon registry class plus the SVG markup helpers so the element file
+ * doesn't have to.
+ */
+type UiGridControlIconKey = 'sortNone' | 'sortAsc' | 'sortDesc' | 'group' | 'groupExpanded' | 'groupCollapsed' | 'treeExpanded' | 'treeCollapsed' | 'expandExpanded' | 'expandCollapsed' | 'pin' | 'pinLeft' | 'pinRight' | 'paginationPrev' | 'paginationNext';
+interface UiGridIconDefinition {
+    viewBox?: string;
+    path: string;
+}
+type UiGridIconOverrides = Partial<Record<UiGridControlIconKey, UiGridIconDefinition>>;
+/**
+ * Holds the active set of icons (defaults merged with consumer overrides)
+ * and renders the inline SVG markup for each one. A single instance lives
+ * on the element.
+ */
+declare class IconRegistry {
+    private overrides;
+    private resolved;
+    getOverrides(): UiGridIconOverrides;
+    setOverrides(value: UiGridIconOverrides): void;
+    resolve(key: UiGridControlIconKey): UiGridIconDefinition;
+    /** Render the SVG markup for a control icon (sort, group, pin, …). */
+    renderControlIcon(key: UiGridControlIconKey): string;
+    /** Render the SVG markup with an arbitrary wrapper class. */
+    renderIconWithClass(svgClass: string, key: UiGridControlIconKey): string;
+}
+
+/**
+ * Complete grid save state — parity with the old `ui.grid.saveState`
+ * module. Every field is optional so partial saves / restores work too.
+ *
+ * Opt-in/out behaviour mirrors the old module: by default save() serialises
+ * everything; consumers can disable per-field capture via
+ * `saveSort`/`saveFilter`/... options on `GridOptions`. Restore tolerates
+ * missing fields.
+ */
 interface GridSaveState {
-    sortState: SortState;
-    activeFilters: Record<string, string>;
-    groupByColumns: string[];
-    pinnedColumns: PinnedColumnState;
-    columnOrder: string[];
-    currentPage: number;
-    pageSize: number;
+    sortState?: SortState;
+    activeFilters?: Record<string, string>;
+    groupByColumns?: string[];
+    collapsedGroups?: Record<string, boolean>;
+    pinnedColumns?: PinnedColumnState;
+    columnOrder?: string[];
+    columnWidthOverrides?: Record<string, string>;
+    currentPage?: number;
+    pageSize?: number;
+    selectedRowIds?: string[];
+    focusedCell?: GridCellPosition | null;
+    expandedRows?: Record<string, boolean>;
+    expandedTreeRows?: Record<string, boolean>;
+    scrollTop?: number;
+    scrollLeft?: number;
 }
 interface GridControllerSnapshot {
     options: GridOptions;
@@ -28,6 +231,13 @@ interface GridControllerSnapshot {
     pageSize: number;
     editingCell: GridCellPosition | null;
     editingValue: string;
+    /** Row ids currently selected. A ReadonlySet for surgical DOM updates —
+     * the renderer toggles the .ui-grid-row-selected class on every cell
+     * whose data-row matches one of these ids. */
+    selectedRowIds: ReadonlySet<string>;
+    selectAll: boolean;
+    focusedRowId: string | null;
+    selectedCount: number;
 }
 type GridControllerSubscriber = (snapshot: GridControllerSnapshot) => void;
 declare class VanillaGridController {
@@ -46,6 +256,21 @@ declare class VanillaGridController {
     private pageSize;
     private editingCell;
     private editingValue;
+    private exporterOverrides;
+    private validatorRegistry;
+    private rowEditState;
+    private rowEditTimers;
+    private rowEditSavePromiseOverrides;
+    private selectionState;
+    /** cellNav state. Persists the last focused cell so the public API's
+     * getFocusedCell returns the right value across re-renders, and tracks
+     * the focused-cells history for getCurrentSelection. */
+    private cellNavLastRowCol;
+    private cellNavFocusedCells;
+    /** Infinite-scroll state. Direction flags seed from options; dataLoading
+     * + previousVisibleRows are runtime bookkeeping for saveScrollPercentage /
+     * dataRemovedTop / dataRemovedBottom. */
+    private infiniteScrollState;
     private pipeline;
     private labels;
     private visibleColumns;
@@ -53,6 +278,11 @@ declare class VanillaGridController {
     private readonly subscribers;
     readonly gridApi: UiGridApi;
     constructor(options: GridOptions);
+    /** Disposer for the i18n language-change listener — cleared when the
+     * controller is torn down (matches the pattern used for other global
+     * subscriptions). */
+    private disposeLanguageListener;
+    dispose(): void;
     setOptions(options: GridOptions): void;
     /**
      * Fast-path: swap only the row data and rebuild the pipeline without
@@ -81,10 +311,81 @@ declare class VanillaGridController {
     expandAllTreeRows(): void;
     collapseAllTreeRows(): void;
     setTreeRowExpanded(row: GridRow | GridRecord | string, expanded: boolean): void;
-    beginCellEdit(row: GridRow | GridRecord | string, columnName: string, triggerEvent?: Event | KeyboardEvent | null): void;
+    beginCellEdit(row: GridRow | GridRecord | string, columnName: string, triggerEvent?: Event | KeyboardEvent | null, initialValue?: string): void;
     updateEditingValue(value: string): void;
     commitCellEdit(): void;
     cancelCellEdit(): void;
+    /** Internal: run a core selection mutation, raise events, trigger a render. */
+    private applySelectionChange;
+    private allGridRows;
+    toggleRowSelectionByEntity(rowEntity: GridRecord, evt?: Event | null): void;
+    selectRow(rowEntity: GridRecord, evt?: Event | null): void;
+    selectRowByVisibleIndex(rowNum: number, evt?: Event | null): void;
+    selectRowByKey(isInEntity: boolean, key: string, comparator: unknown, evt?: Event | null, lookInRows?: readonly GridRow[]): void;
+    unSelectRow(rowEntity: GridRecord, evt?: Event | null): void;
+    unSelectRowByVisibleIndex(rowNum: number, evt?: Event | null): void;
+    unSelectRowByKey(isInEntity: boolean, key: string, comparator: unknown, evt?: Event | null, lookInRows?: readonly GridRow[]): void;
+    selectAllRows(evt?: Event | null): void;
+    selectAllVisibleRows(evt?: Event | null): void;
+    clearSelectedRows(evt?: Event | null): void;
+    shiftSelectRow(rowEntity: GridRecord, evt?: Event | null): void;
+    getSelectedRows(): GridRecord[];
+    getUnSelectedRows(): GridRecord[];
+    getSelectedGridRows(): GridRow[];
+    getUnSelectedGridRows(): GridRow[];
+    setMultiSelect(multiSelect: boolean): void;
+    setModifierKeysToMultiSelect(value: boolean): void;
+    /** Focus a row by id — the old module's `row.setFocused(true)` with all
+     * the book-keeping. Raises rowFocusChanged and refreshes. */
+    setRowFocused(rowId: string, focused: boolean, evt?: Event | null): void;
+    getRowSelectionState(): Readonly<GridSelectionState>;
+    /** Resolved/defaulted selection options — exposed for the element layer
+     * so it can decide whether to wire pointer handlers without duplicating
+     * default logic. */
+    getResolvedSelectionOptions(): ReturnType<typeof resolveGridSelectionOptions>;
+    /** Public analogue of findRowById — the element uses this during drag
+     * painting to resolve a row-id back to its entity without calling the
+     * selection API methods that would double-raise events. */
+    findRowByIdPublic(rowId: string): GridRow | null;
+    /** Record a navigation event. Pushes to the focused-cells history,
+     * updates lastRowCol, and raises cellNav.navigate on the public API. */
+    setCellNavFocus(rowId: string | null, columnName: string | null, opts?: {
+        appendToSelection?: boolean;
+    }): void;
+    /** Raise viewPortKeyDown / viewPortKeyPress on behalf of the element.
+     * Element gates this with `options.keyDownOverrides`. */
+    raiseCellNavKeyEvent(type: 'keydown' | 'keypress', event: KeyboardEvent): void;
+    private cellNavGetFocusedCell;
+    private cellNavGetCurrentSelection;
+    private cellNavRowColSelectIndex;
+    private resolveCellNavRowCol;
+    /** cellNav.scrollToFocus — resolves rowEntity + colDef into a logical
+     * focus and delegates to the element (if attached) for actual scrolling.
+     * When the element isn't wired (e.g. bare controller in tests), the
+     * state still updates and the promise resolves immediately. */
+    private cellNavScrollToFocus;
+    /** Element registers its scroll-and-focus handler here so the API
+     * binding above can delegate DOM work. Controller stays DOM-free. */
+    private cellNavScrollRequest;
+    setCellNavScrollHandler(handler: ((rowId: string | null, columnName: string | null) => void) | null): void;
+    /** Read-only accessor for the current options. Used by the element to
+     * inspect keyDownOverrides / modifierKeysToMultiSelectCells without
+     * coupling it to a private field. */
+    getOptions(): GridOptions;
+    /** Evaluate whether the current scroll position should request more
+     * data at the top or bottom. Called from the element's scroll frame. */
+    evaluateInfiniteScroll(startIndex: number, visibleRows: number, viewportRows: number): void;
+    private infiniteScrollDataLoaded;
+    private infiniteScrollResetScroll;
+    private infiniteScrollSavePercentage;
+    private infiniteScrollDataRemovedTop;
+    private infiniteScrollDataRemovedBottom;
+    private infiniteScrollSetDirections;
+    /** Element registers a scroll-to-top handler here so resetScroll can
+     * bring the viewport back to 0. Keeps the controller DOM-free. */
+    private infiniteScrollScrollToTopRequest;
+    setInfiniteScrollResetHandler(handler: (() => void) | null): void;
+    getInfiniteScrollState(): Readonly<GridInfiniteScrollState>;
     canResizeColumns(): boolean;
     setColumnWidthOverride(columnName: string, widthPx: number): void;
     /** Returns the grid-template-columns string as if `columnName` had the given width,
@@ -106,6 +407,12 @@ declare class VanillaGridController {
     getSortDirection(column: GridColumnDef): SortDirection;
     isPinningEnabled(): boolean;
     isColumnPinnable(column: GridColumnDef): boolean;
+    /** True when the given column is editable in principle — does NOT evaluate
+     * a per-row `cellEditableCondition`. Use isCellEditable for that. */
+    isColumnEditable(column: GridColumnDef): boolean;
+    /** True when the (row, column) cell is editable, respecting both the
+     * column's `enableCellEdit` flag and any `cellEditableCondition`. */
+    isCellEditable(row: GridRow, column: GridColumnDef): boolean;
     isPinned(column: GridColumnDef): boolean;
     isPinnedLeftLast(column: GridColumnDef): boolean;
     isPinnedRightFirst(column: GridColumnDef): boolean;
@@ -124,8 +431,26 @@ declare class VanillaGridController {
     expandToggleLabel(row: GridRow): string;
     editorInputType(column: GridColumnDef): string;
     isEditingCell(rowId: string, columnName: string): boolean;
+    /**
+     * Serialise the current grid state. Mirrors `ui.grid.saveState.save`:
+     * every field is gated by an `options.save*` flag with the old grid's
+     * defaults. A missing flag keeps the matching field out of the result.
+     */
     getState(): GridSaveState;
+    /**
+     * Apply a previously saved state. All fields are optional — missing
+     * fields are left at whatever the controller currently has. Matches the
+     * old grid's `ui.grid.saveState.restore`.
+     */
     setState(state: Partial<GridSaveState>): void;
+    /** Element injects its scroll accessor so save() can capture scrollTop/
+     * scrollLeft. Controller stays DOM-free. */
+    private saveStateScrollSnapshot;
+    private saveStateScrollRestore;
+    setSaveStateScrollHandlers(snapshot: (() => {
+        scrollTop: number;
+        scrollLeft: number;
+    }) | null, restore: ((scrollTop: number, scrollLeft: number) => void) | null): void;
     private refresh;
     private emit;
     private findRowById;
@@ -141,6 +466,67 @@ declare class VanillaGridController {
     private setRowInvisible;
     private clearRowInvisible;
     private benchmark;
+    /** Returns the rows that match the requested exporter row-type. Mirrors
+     * the old grid's row selection logic: `all` uses the full data set (or
+     * `exporterAllDataFn` when provided), `visible` uses the current pipeline
+     * output, `selected` uses the selection state. */
+    private exporterRowsFor;
+    private resolveExporterOptions;
+    private buildCsv;
+    private exportCsv;
+    private buildPdfDocDefinition;
+    private exportPdf;
+    private buildExcelSheetData;
+    private exportExcel;
+    /** Runs the validators declared on `colDef.validators` against the new
+     * value and flips `$$invalid<col>` / `$$errors<col>` on the entity. On
+     * failure raises `validate.validationFailed`. Async validators are
+     * awaited so the caller can `await` for complete results. */
+    private validateRunValidators;
+    private validateGetFormattedErrors;
+    private validateGetTitleFormattedErrors;
+    private validateGetInvalidRows;
+    /** Test hook — exposes the validator registry so consumers can inspect or
+     * extend it outside of the gridApi surface (e.g. from a controller-level
+     * plugin). */
+    getValidatorRegistry(): GridValidatorRegistry;
+    /** Set by the element so `importAFile()` can trigger its file-picker flow.
+     * Controller stays DOM-free: it just invokes whatever handler was wired. */
+    private importerFilePickerRequest;
+    setImporterFilePickerHandler(handler: (() => void) | null): void;
+    private resolveImporterOptions;
+    private importerRequestFile;
+    private importerDispatchObjects;
+    private importerImportText;
+    private importerImportThisFile;
+    private buildExporterMenuItems;
+    /** Menu items the importer contributes. Just the single "Import"
+     * entry when the feature is enabled; returns an empty array otherwise. */
+    private buildImporterMenuItems;
+    /** Menu items row-edit contributes: "Save changes" + "Retry errored
+     * rows". Each entry is gated by both a gridOption flag and a runtime
+     * predicate (`hasDirtyRows` / `hasErrorRows`) so the menu only surfaces
+     * actions that have something to do. */
+    private buildRowEditMenuItems;
+    private rowEditSetSavePromise;
+    private rowEditGetDirtyRows;
+    private rowEditGetErrorRows;
+    private rowEditFlushDirtyRows;
+    /** Re-fires `saveRow` for every row currently in the error state. The
+     * "Retry errored rows" menu entry funnels through here. Returns a
+     * promise that resolves once every retry promise has settled. */
+    private rowEditRetryErroredRows;
+    private rowEditSetRowsDirty;
+    private rowEditSetRowsClean;
+    private considerSetRowEditTimer;
+    private cancelRowEditTimer;
+    private runRowEditSave;
+    /** Test hook — reports the current row-edit dirty / error / saving state. */
+    getRowEditState(): {
+        dirtyRowIds: string[];
+        errorRowIds: string[];
+        savingRowIds: string[];
+    };
 }
 declare function createVanillaGridController(options: GridOptions): VanillaGridController;
 
@@ -155,49 +541,86 @@ type VanillaUiGridElement = HTMLElement & {
      */
     setData(rows: GridRecord[]): void;
 };
-type UiGridControlIconKey = 'sortNone' | 'sortAsc' | 'sortDesc' | 'group' | 'groupExpanded' | 'groupCollapsed' | 'treeExpanded' | 'treeCollapsed' | 'expandExpanded' | 'expandCollapsed' | 'pin' | 'pinLeft' | 'pinRight' | 'paginationPrev' | 'paginationNext';
-interface UiGridIconDefinition {
-    viewBox?: string;
-    path: string;
-}
-type UiGridIconOverrides = Partial<Record<UiGridControlIconKey, UiGridIconDefinition>>;
+type VanillaGridOptions = GridOptions & {
+    iconOverrides?: UiGridIconOverrides;
+};
 declare class UiGridStandaloneElement extends HTMLElement {
-    private controller;
-    private snapshot;
-    private unsubscribe;
-    private activeOptions;
-    private attributeOptions;
-    private attributeSyncScheduled;
-    private iconOverrides;
-    private templateObserver;
-    private openPinMenuColumn;
-    private focusedCell;
-    private draggedColumnName;
-    private dropTargetColumnName;
-    private scrollPosition;
-    private horizontalScrollPosition;
-    private scrollFrame;
-    private suppressScrollEvent;
-    private lastVirtualStartIndex;
-    private measuredHeaderStickyHeight;
-    private measuredFilterStickyHeight;
-    private stickyHeightRelayoutQueued;
-    private benchmarkAverage;
-    private skipNextRender;
-    private dataFrame;
-    private pendingPatchedRowIds;
-    private pendingDataRefreshMode;
-    private lastScrollActivityAt;
+    /** @internal */ controller: VanillaGridController | null;
+    /** @internal */ snapshot: GridControllerSnapshot | null;
+    /** @internal */ unsubscribe: (() => void) | null;
+    /** @internal */ activeOptions: VanillaGridOptions | null;
+    /** @internal */ attributeOptions: Partial<GridOptions>;
+    /** @internal */ attributeSyncScheduled: boolean;
+    /** @internal Owns the SVG-icon registry: defaults merged with consumer
+     * overrides plus rendering helpers. See `./icons.ts`. */
+    icons: IconRegistry;
+    /** @internal */ templateObserver: MutationObserver | null;
+    /** @internal */ openPinMenuColumn: string | null;
+    /** @internal */ focusedCell: {
+        rowId: string;
+        columnName: string;
+    } | null;
+    /** @internal */ draggedColumnName: string | null;
+    /** @internal */ dropTargetColumnName: string | null;
+    /** @internal */ scrollPosition: number;
+    /** @internal */ horizontalScrollPosition: number;
+    /** @internal */ scrollFrame: number | null;
+    /** @internal */ suppressScrollEvent: boolean;
+    /** @internal */ lastVirtualStartIndex: number;
+    /** @internal */ measuredHeaderStickyHeight: number;
+    /** @internal */ measuredFilterStickyHeight: number;
+    /** @internal */ stickyHeightRelayoutQueued: boolean;
+    /** @internal */ benchmarkAverage: string;
+    /** @internal */ skipNextRender: boolean;
+    /** @internal */ autoResizeObserver: ResizeObserver | null;
+    /** @internal */ autoResizeDebounceHandle: number | null;
+    gridTitle: string;
+    gridTableStyle: string;
+    bodyViewportStyle: string;
+    templateColumns: string;
+    slotRegistry: string;
+    headerContent: string;
+    filterRowContent: string;
+    bodyContent: string;
+    paginationContent: string;
+    /** @internal */ dataFrame: number | null;
+    /** @internal */ pendingPatchedRowIds: Set<string> | null;
+    /** @internal */ pendingDataRefreshMode: 'patch' | 'virtual' | 'full' | null;
+    /** @internal */ lastScrollActivityAt: number;
+    /** @internal */ lastStructureKey: string | null;
+    /** @internal */ lastItemsFingerprint: string | null;
+    /** @internal */ lastVirtualOffset: number;
+    /** @internal */ lastTotalVirtualHeight: number;
+    /**
+     * @internal Framework-rendered slot bridge. See `./framework-slots.ts`.
+     */
+    frameworkSlots: FrameworkSlotBridge;
     static get observedAttributes(): string[];
     get options(): GridOptions;
     set options(value: GridOptions);
+    /**
+     * Declare which slots are framework-rendered. When a slot is flagged, the
+     * element renders a `<slot name="…">` placeholder at the usual site instead
+     * of running its string-interpolation template, and dispatches
+     * `*SlotsChanged` events so a wrapper can insert light-DOM content with a
+     * matching `slot` attribute.
+     *
+     * Pass an empty object (or `{}`) to revert every slot kind back to the
+     * default interpolation path. Individual fields behave the same way:
+     * omitting `cells` means the cells list is unchanged; passing
+     * `cells: []` clears it.
+     *
+     * This is the bridge the Angular / React wrappers use to project native
+     * templates (ng-template, JSX render props) into the grid. Consumers of
+     * the web component directly can ignore this method — the default
+     * `<template slot="cell-columnName">` workflow still works.
+     */
+    setFrameworkRenderedSlots(config: FrameworkRenderedSlotsConfig): void;
     attributeChangedCallback(_name: string, _oldValue: string | null, _newValue: string | null): void;
     private syncAttributesToOptions;
-    private parseBooleanAttribute;
-    private parseNumberAttribute;
-    private parseJsonAttribute;
     get controlIcons(): UiGridIconOverrides;
     set controlIcons(value: UiGridIconOverrides);
+    private resolveIcon;
     get gridId(): string;
     set gridId(value: string);
     get title(): string;
@@ -206,8 +629,6 @@ declare class UiGridStandaloneElement extends HTMLElement {
     set rowHeight(value: number);
     get headerRowHeight(): number;
     set headerRowHeight(value: number);
-    get viewportHeight(): number;
-    set viewportHeight(value: number);
     get paginationPageSize(): number;
     set paginationPageSize(value: number);
     get paginationCurrentPage(): number;
@@ -289,21 +710,87 @@ declare class UiGridStandaloneElement extends HTMLElement {
     private patchCells;
     connectedCallback(): void;
     disconnectedCallback(): void;
-    private ensureShadowRoot;
-    private ensureController;
+    /** @internal */
+    ensureShadowRoot(): ShadowRoot;
+    /** @internal */
+    ensureController(options: VanillaGridOptions): void;
+    /** Hidden file input used by `gridApi.importer.importAFile()`. Lazily
+     * created on first use and reused thereafter. */
+    private importerFileInput;
+    private openImporterFilePicker;
     private observeTemplateSlots;
-    private buildEffectiveOptions;
     private bindEvents;
+    private syncHeaderHorizontalScroll;
+    private maybeTriggerInfiniteScroll;
+    /** @internal */
+    buildEffectiveOptions(options: VanillaGridOptions): VanillaGridOptions;
+    /**
+     * Ask the controller to evaluate whether the current scroll position
+     * should request more data at the top or bottom — ports the old grid's
+     * handleScroll → loadData check. The controller does the actual
+     * needLoadMoreData / needLoadMoreDataTop raise.
+     */
+    /**
+     * Mirror horizontal scroll from the body viewport onto the header + filter
+     * strips by setting `scrollLeft` on them. Because those strips are real
+     * scroll containers (with their scrollbars hidden), `position: sticky` on
+     * pinned header / filter cells anchors to the strip's scroll position the
+     * same way body cells anchor to `.grid-body-viewport`. This is the
+     * imperative sync strategy the old ui-grid used in ui-grid-viewport.js.
+     */
     /**
      * Targeted update for virtual scroll: replaces only the rendered rows inside
      * the existing `.grid-virtual-body` without touching the scroll container.
      * This preserves momentum/inertia scrolling because the `.grid-table` element
      * is never destroyed.
      */
-    private renderVirtualBody;
-    private render;
+    /** @internal */
+    renderVirtualBody(): void;
+    /** @internal */
+    render(): void;
+    /** @internal */
+    private inAutoAdjust;
+    private lastAutoHeight;
+    private autoAdjustHeight;
+    measuredPaginationHeight(): number;
+    /** @internal */
+    setupAutoResize(): void;
+    /** @internal */
+    teardownAutoResize(): void;
+    private buildRenderPlan;
+    private renderFull;
+    private renderPatch;
+    private reconcileBodyRoot;
+    private reconcilePagination;
+    private patchFilterCells;
+    private fingerprintItems;
+    private patchExistingRows;
+    private patchGroupRow;
+    private patchBodyCell;
+    private patchPagination;
     private renderHeaderCell;
     private renderFilterCell;
+    /**
+     * Commit the in-flight edit, then move keyboard focus relative to the
+     * committed cell. Splits commit + focus across two paint frames: commit
+     * runs synchronously (editor unmounts, cell re-renders with the new value),
+     * then focus moves to the adjacent cell. Scheduling the focus in a
+     * microtask avoids racing the blur handler's re-entry guard and ensures
+     * the destination cell is fully reattached in the DOM.
+     *
+     * If the source cell was being edited, the destination cell enters edit
+     * mode too (provided the destination column is editable). This keeps
+     * Tab/Enter nav inside an edit session continuous — you keep editing as
+     * you move. Arrow nav outside an edit session does NOT auto-enter edit.
+     */
+    private commitAndMove;
+    private moveGridFocus;
+    private scrollFocusedRowIntoView;
+    private handleRowSelectionClick;
+    private handleRowHeaderCheckboxClick;
+    private matchesKeyOverride;
+    private applyFocusedCellClass;
+    private focusCellElement;
     private measureAutoColumnWidth;
     private renderDisplayItem;
     private renderBodyCell;
@@ -313,18 +800,51 @@ declare class UiGridStandaloneElement extends HTMLElement {
     private renderCellTemplateFromMarkup;
     private renderExpandableTemplate;
     private getTemplateMarkup;
-    private interpolateTemplate;
-    private resolveTemplateValue;
+    /** @internal Used by the render module to interpolate consumer templates. */
+    interpolateTemplate(templateMarkup: string, context: Record<string, unknown>): string;
     private rowIndexFor;
     private classifyDataRefresh;
     private getRenderedDisplayWindow;
     private cellSlotName;
-    private downloadCsv;
+    private renderEmptyState;
+    /** @internal */
+    downloadCsv(rowType?: 'all' | 'visible' | 'selected', colType?: 'all' | 'visible'): void;
     private renderControlIcon;
     private renderIconWithClass;
 }
 declare function defineStandaloneUiGridElement(tagName?: string): Promise<void>;
 
+/**
+ * A declarative template element for defining reusable cell/row templates
+ * without writing JavaScript.
+ *
+ * Supports both `${this.prop}` and `{{prop}}` binding syntax.
+ *
+ * @example
+ * ```html
+ * <template is="ui-grid-template" name="ui-status-badge" status="unknown">
+ *   <style>
+ *     :host { display: inline-block; }
+ *     .badge { padding: 2px 8px; border-radius: 4px; font-size: 0.8em; }
+ *     .badge-active { background: #d1fae5; color: #065f46; }
+ *     .badge-inactive { background: #fee2e2; color: #991b1b; }
+ *   </style>
+ *   <span class="badge badge-${this.status}">${this.status}</span>
+ * </template>
+ *
+ * <ui-grid-element>
+ *   <template slot="cell-status">
+ *     <ui-status-badge status="{{value}}"></ui-status-badge>
+ *   </template>
+ * </ui-grid-element>
+ * ```
+ */
+declare class UIGridTemplate extends HTMLTemplateElement {
+    static readonly TAG = "ui-grid-template";
+    connectedCallback(): void;
+    static define(tagName?: string): void;
+}
+
 interface UiGridRustWebModule {
     default(input?: unknown): Promise<unknown>;
     build_pipeline_js(context: BuildGridPipelineContext): PipelineResult;
@@ -333,4 +853,4 @@ interface UiGridRustWebModule {
 declare function registerVanillaUiGridRustModule(module: UiGridRustWebModule, input?: unknown): Promise<void>;
 declare function mountVanillaUiGrid(target: Element, options: GridOptions, rustModule?: UiGridRustWebModule, tagName?: string): Promise<VanillaUiGridElement>;
 
-export { type GridControllerSnapshot, type GridSaveState, type UiGridControlIconKey, type UiGridIconDefinition, type UiGridIconOverrides, type UiGridRustWebModule, UiGridStandaloneElement, VanillaGridController, type VanillaUiGridElement, createVanillaGridController, defineStandaloneUiGridElement, defineStandaloneUiGridElement as defineUiGridElement, mountVanillaUiGrid, registerVanillaUiGridRustModule };
+export { type FrameworkCellSlot, type FrameworkEmptyStateSlot, type FrameworkExpandableRowSlot, type FrameworkFilterSlot, type FrameworkGroupRowSlot, type FrameworkHeaderSlot, type FrameworkRenderedSlotsConfig, type FrameworkSlotDelta, type GridControllerSnapshot, type GridSaveState, UIGridTemplate, type UiGridControlIconKey, type UiGridIconDefinition, type UiGridIconOverrides, type UiGridRustWebModule, UiGridStandaloneElement, VanillaGridController, type VanillaUiGridElement, createVanillaGridController, defineStandaloneUiGridElement, defineStandaloneUiGridElement as defineUiGridElement, mountVanillaUiGrid, registerVanillaUiGridRustModule };