ezfw-core 1.0.0

package/components/grid/EzGrid.ts

@@ -0,0 +1,1085 @@
+import './EzGrid.scss';
+import { EzGridContainer } from './EzGridContainer.js';
+import { EzError } from '../../core/EzError.js';
+import { EzGridSelection } from './state/EzGridSelection.js';
+import { EzGridColumns } from './state/EzGridColumns.js';
+import { EzGridSort } from './state/EzGridSort.js';
+import { EzGridLifecycle } from './state/EzGridLifecycle.js';
+import { createEzGridController } from './state/EzGridController.js';
+import { EzGridPersistence } from './state/EzGridPersistence.js';
+import { EzGridNormalizers } from './state/EzGridNormalizers.js';
+import { EzGridParts } from './state/EzGridParts.js';
+import { EzGridRemote } from './state/EzGridRemote.js';
+import type {
+    EzGridConfig,
+    EzGridModel,
+    EventCallback,
+    RowCallback,
+    FilterSnapshot,
+    ExportCSVOptions,
+    ExportExcelOptions,
+    RowData,
+    NormalizedColumn,
+    EzGridController
+} from './types.js';
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+declare const ez: {
+    getController(name: string): any;
+    getGridBehavior(name: string): Promise<Record<string, unknown>>;
+    getModelSync(name: string): EzGridModel | null;
+    _loader: {
+        resolveModel(name: string): Promise<void>;
+    };
+};
+
+// ==========================================================
+// EzGrid Class
+// ==========================================================
+
+export class EzGrid extends EzGridContainer {
+    declare config: any; // EzGridConfig - relaxed for compatibility
+
+    // Selection
+    _selection: any;
+    selection: any;
+    _suppressSelectionPersistence: boolean;
+
+    // Columns
+    _columns: any;
+    columns: any[];
+    columnState: any;
+
+    // Header
+    header: any;
+
+    // Sort
+    _sort: any;
+    sort: any;
+
+    // Lifecycle & Persistence
+    _lifecycle: any;
+    _persistence: any;
+    _parts: any;
+
+    // Controller
+    controller: any;
+
+    // State flags
+    stateful: boolean;
+    statefulPersist: boolean;
+    rowKey: any;
+
+    // Local sort/filter baselines
+    _localSortBaseline: unknown[] | null;
+    _hasLocalSortBaseline: boolean;
+    _localFilterBaseline: unknown[] | null;
+    _hasLocalFilterBaseline: boolean;
+    _lastFilterSnapshot: FilterSnapshot[] | null = null;
+
+    // Store mode
+    _store: any;
+    _storeUnsubscribers: Array<() => void>;
+
+    // Remote mode
+    _remote: any = null;
+    _autoLoadPending: boolean = false;
+    _overRulesApplied: boolean = false;
+
+    // Callbacks
+    _onLoadingChanged: (loading: boolean) => void;
+    _onError: (error: Error | null) => void;
+    _rowClickHandler: RowCallback | null = null;
+    _rowDoubleClickHandler: RowCallback | null = null;
+    _rowContextMenuHandler: RowCallback | null = null;
+
+    // Instances
+    el: HTMLElement | null = null;
+    headerInstance?: any;
+    _bodyInstance?: any;
+    _footerInstance?: any;
+    _filtersInstance?: any;
+
+    constructor(config: EzGridConfig = {}) {
+        super(config as any);
+
+        this._selection = new EzGridSelection(this as any, config.selection);
+        this.selection = this._selection;
+        this._suppressSelectionPersistence = true;
+
+        this.header = EzGridNormalizers.normalizeHeader(config.header);
+
+        const selectionConfig = typeof config.selection === 'object' ? config.selection : undefined;
+        const normalizedColumns = EzGridNormalizers.normalizeColumns(
+            config.columns || [],
+            {
+                selectionMode: selectionConfig?.mode,
+                selectionWidth: selectionConfig?.width,
+                headerAlign: this.header?.align
+            }
+        );
+
+        this._columns = new EzGridColumns(this, normalizedColumns);
+        this.columns = normalizedColumns;
+        this.columnState = this._columns.state;
+
+        this._sort = new EzGridSort(this as any, config.sort);
+        this.sort = this._sort;
+
+        this._lifecycle = new EzGridLifecycle(this as any);
+        this._persistence = new EzGridPersistence(this as any);
+        this._parts = new EzGridParts(this as any);
+
+        this._localSortBaseline = null;
+        this._hasLocalSortBaseline = false;
+        this._localFilterBaseline = null;
+        this._hasLocalFilterBaseline = false;
+
+        const variant = config.variant || 'elevated';
+
+        this.config.cls = [
+            ...(Array.isArray(this.config.cls) ? this.config.cls : [this.config.cls]),
+            'ez-grid',
+            `ez-grid--${variant}`
+        ].filter(Boolean) as string[];
+
+        this.config.layout = 'vbox';
+        this.config.flex ??= 1;
+
+        this.stateful = config.stateful || false;
+        this.statefulPersist = !!config.statefulPersist;
+
+        this.rowKey = EzGridNormalizers.normalizeRowKey(config.rowKey);
+
+        this.config.skipInit = true;
+
+        this._onLoadingChanged = (loading: boolean) => {
+            this._lifecycle.onLoadingChanged(loading);
+        };
+
+        this._onError = (error: Error | null) => {
+            this._lifecycle.onError(error);
+        };
+
+        this._initController();
+
+        this._store = null;
+        this._storeUnsubscribers = [];
+
+        if (config.store) {
+            this._initStore(config);
+        } else if (config.remote) {
+            this._initRemote(config);
+        }
+
+        this.controller.on('datachange', () => {
+            Promise.resolve().then(() => {
+                void this._onControllerDataChange();
+            });
+        });
+
+        this._resolveListeners();
+        this._buildParts();
+    }
+
+    // ==========================================================
+    // ListenTo Resolution
+    // ==========================================================
+
+    private _resolveListeners(): void {
+        const listenTo = this.config.listenTo;
+
+        this._rowClickHandler = this._resolveRowCallback(
+            listenTo?.onRowClick ?? this.config.onRowClick
+        );
+        this._rowDoubleClickHandler = this._resolveRowCallback(
+            listenTo?.onRowDoubleClick ?? this.config.onRowDoubleClick
+        );
+        this._rowContextMenuHandler = this._resolveRowCallback(
+            listenTo?.onRowContextMenu ?? this.config.onRowContextMenu
+        );
+    }
+
+    private _resolveRowCallback(callback: RowCallback | string | undefined | null): RowCallback | null {
+        if (typeof callback === 'function') {
+            return callback;
+        }
+
+        if (typeof callback === 'string') {
+            if (callback.includes(':')) {
+                const [controllerName, fnName] = callback.split(':');
+                const controller = ez.getController(controllerName);
+
+                if (controller && typeof controller[fnName] === 'function') {
+                    return (controller[fnName] as RowCallback).bind(controller);
+                }
+
+                console.warn(`[EzGrid] Could not resolve listenTo callback: ${callback}`);
+                return null;
+            }
+
+            const controllerName = this.config?.controller;
+            if (controllerName) {
+                const controller = ez.getController(controllerName);
+                if (controller && typeof controller[callback] === 'function') {
+                    return (controller[callback] as RowCallback).bind(controller);
+                }
+            }
+
+            return (...args: unknown[]) => {
+                const name = this.config?.controller;
+                if (name) {
+                    const ctrl = ez.getController(name);
+                    if (ctrl && typeof ctrl[callback] === 'function') {
+                        return (ctrl[callback] as RowCallback).apply(ctrl, args as any);
+                    }
+                }
+                console.warn(`[EzGrid] Could not resolve listenTo callback: ${callback}`);
+            };
+        }
+
+        return null;
+    }
+
+    // ==========================================================
+    // Public Rendering API
+    // ==========================================================
+
+    async render(): Promise<HTMLDivElement> {
+        await this._ensureOverRulesApplied();
+        await this._bindData();
+
+        const originalInit = this.config.init;
+        this.config.init = undefined;
+
+        const el = await super.render();
+        this.el = el;
+
+        this.config.init = originalInit;
+
+        if (typeof this.config.init === 'function') {
+            queueMicrotask(() => {
+                this.config.init!(this);
+            });
+        }
+
+        Promise.resolve().then(() => {
+            void this._onControllerDataChange();
+        });
+
+        if (this._autoLoadPending) {
+            this._autoLoadPending = false;
+            queueMicrotask(() => {
+                this.controller.load();
+            });
+        }
+
+        return el;
+    }
+
+    async refreshBody(): Promise<void> {
+        if (this.controller?.state?.mode === 'remote') {
+            this.controller.reload();
+            return;
+        }
+
+        this._lifecycle?.onControllerDataChange?.();
+    }
+
+    // ==========================================================
+    // Public Event API
+    // ==========================================================
+
+    on(event: string, fn: EventCallback): void {
+        if (!this.controller?.on) return;
+        this.controller.on(event, fn);
+    }
+
+    off(event: string, fn: EventCallback): void {
+        if (!this.controller?.off) return;
+        this.controller.off(event, fn);
+    }
+
+    // ==========================================================
+    // Selection Public API
+    // ==========================================================
+
+    _isSelectionEnabled(): boolean {
+        return this._selection?.isEnabled?.() === true;
+    }
+
+    isSelected(row: unknown): boolean {
+        return this._selection?.isSelected(row) === true;
+    }
+
+    getSelection(): unknown[] {
+        return this._selection?.getSelection() ?? [];
+    }
+
+    toggleRow(row: unknown, index: number): void {
+        this._selection?.toggleRow(row, index);
+    }
+
+    selectRange(toIndex: number): void {
+        this._selection?.selectRange(toIndex);
+    }
+
+    clearSelection(): void {
+        this._selection?.clear();
+    }
+
+    selectAll(): void {
+        this._selection?.selectAll();
+    }
+
+    isAllSelected(): boolean {
+        return this._selection?.isAllSelected() === true;
+    }
+
+    _getSelectionStateSnapshot(): any {
+        return this._selection?.snapshot?.() ?? null;
+    }
+
+    _applySelectionStateSnapshot(snapshot: any): void {
+        this._selection?.restore?.(snapshot);
+    }
+
+    _onSelectionChanged(): void {
+        if (this.stateful && this._suppressSelectionPersistence !== true) {
+            this._persistence.updateSelectionState(this._getSelectionStateSnapshot());
+            this._persistence.save();
+        }
+
+        this._emitSelectionChange();
+        this._bodyInstance?.updateSelectionVisuals?.();
+    }
+
+    private _emitSelectionChange(): void {
+        const controller = this.controller;
+        if (!controller?.emit) return;
+
+        const keys = Array.from(this.selection?.selected || []);
+        const data = this.controller?.state?.data || [];
+        const rows = data.filter((row: any) => {
+            const key = this._getRowKey(row);
+            return key != null && this.selection.selected.has(String(key));
+        });
+
+        controller.emit('selectionchange', {
+            grid: this,
+            mode: this.selection?.mode ?? 'single',
+            keys,
+            rows
+        });
+    }
+
+    // ==========================================================
+    // Column Public API
+    // ==========================================================
+
+    getVisibleColumns(): any[] {
+        return this._columns.getVisibleColumns();
+    }
+
+    hideColumn(colId: string): void {
+        this._columns.hide(colId);
+    }
+
+    showColumn(colId: string): void {
+        this._columns.show(colId);
+    }
+
+    toggleColumn(colId: string): void {
+        this._columns.toggle(colId);
+    }
+
+    setColumnWidth(colId: string, width: number): void {
+        this._columns.setWidth(colId, width);
+    }
+
+    resetColumnWidth(colId: string): void {
+        this._columns.resetWidth(colId);
+    }
+
+    moveColumn(colId: string, toIndex: number): void {
+        this._columns.move(colId, toIndex);
+    }
+
+    _getColumnStateSnapshot(): any {
+        return this._columns.snapshot();
+    }
+
+    _onColumnsChanged(): void {
+        if (this.stateful) {
+            this._persistence.updateColumnState(this._columns.snapshot());
+        }
+
+        this.headerInstance?.refreshColumns?.();
+        void this.refreshBody();
+        this._persistence.save();
+    }
+
+    // ==========================================================
+    // Sort Public API
+    // ==========================================================
+
+    toggleSort(property: string): void {
+        this._sort.toggleSort(property);
+    }
+
+    clearSort(): void {
+        this._sort.clear();
+    }
+
+    getSorters(): any[] {
+        return this._sort.getSorters();
+    }
+
+    _getSortStateSnapshot(): any {
+        return this._sort.snapshot();
+    }
+
+    _applySortStateSnapshot(snapshot: any): void {
+        this._sort.restore(snapshot);
+    }
+
+    sortBy(colId: string, direction: string): void {
+        this._sort.sortBy(colId, direction);
+    }
+
+    isColumnSorted(colId: string): boolean {
+        return this._sort.isSorted(colId);
+    }
+
+    getColumnSortDirection(colId: string): string | null {
+        const sorter = this._sort.getSorterFor(colId);
+        return sorter?.direction ?? null;
+    }
+
+    // ==========================================================
+    // Filter Public API
+    // ==========================================================
+
+    _onFiltersChanged(snapshot: FilterSnapshot[] | null): void {
+        this.controller?.setFilterSnapshot?.(snapshot);
+
+        if (this.controller?.state?.mode !== 'remote') {
+            this._applyLocalFilters(snapshot);
+        }
+    }
+
+    private _applyLocalFilters(snapshot: FilterSnapshot[] | null): void {
+        if (!this._hasLocalFilterBaseline) {
+            this._localFilterBaseline = this._localSortBaseline
+                ? [...this._localSortBaseline]
+                : [...(this.controller.state.data ?? [])];
+            this._hasLocalFilterBaseline = true;
+        }
+
+        const baseline = this._localFilterBaseline ?? [];
+
+        if (!snapshot || !Array.isArray(snapshot) || snapshot.length === 0) {
+            this._lastFilterSnapshot = null;
+            this.controller.state.data = [...baseline];
+
+            if (this._localSortBaseline) {
+                this._localSortBaseline = [...baseline];
+            }
+
+            if (this._sort?.sorters?.length) {
+                this._sort.applyLocalSort();
+            } else {
+                void this.refreshBody();
+            }
+            return;
+        }
+
+        this._lastFilterSnapshot = snapshot;
+
+        const filtered = baseline.filter(row => {
+            return this._matchesAllFilters(row, snapshot);
+        });
+
+        this.controller.state.data = filtered;
+
+        if (this._localSortBaseline) {
+            this._localSortBaseline = filtered;
+        }
+
+        if (this._sort?.sorters?.length) {
+            this._sort.applyLocalSort();
+        } else {
+            void this.refreshBody();
+        }
+    }
+
+    private _matchesAllFilters(row: unknown, filters: FilterSnapshot[]): boolean {
+        for (const filter of filters) {
+            if (!this._matchesFilter(row, filter)) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    private _matchesFilter(row: unknown, filter: FilterSnapshot): boolean {
+        const { field, operator, value } = filter;
+        const rowValue = (row as Record<string, unknown>)?.[field];
+
+        if (value === '' || value == null) {
+            return true;
+        }
+
+        switch (operator?.toUpperCase?.() ?? '=') {
+            case '=':
+            case 'EQ':
+                return String(rowValue) === String(value);
+
+            case '!=':
+            case 'NE':
+                return String(rowValue) !== String(value);
+
+            case '>':
+            case 'GT':
+                return Number(rowValue) > Number(value);
+
+            case '>=':
+            case 'GTE':
+                return Number(rowValue) >= Number(value);
+
+            case '<':
+            case 'LT':
+                return Number(rowValue) < Number(value);
+
+            case '<=':
+            case 'LTE':
+                return Number(rowValue) <= Number(value);
+
+            case 'LIKE':
+            case 'CONTAINS': {
+                const pattern = String(value).toLowerCase();
+                const text = String(rowValue ?? '').toLowerCase();
+                return text.includes(pattern);
+            }
+
+            case 'STARTS':
+            case 'STARTSWITH': {
+                const pattern = String(value).toLowerCase();
+                const text = String(rowValue ?? '').toLowerCase();
+                return text.startsWith(pattern);
+            }
+
+            case 'ENDS':
+            case 'ENDSWITH': {
+                const pattern = String(value).toLowerCase();
+                const text = String(rowValue ?? '').toLowerCase();
+                return text.endsWith(pattern);
+            }
+
+            case 'BETWEEN': {
+                if (!Array.isArray(value) || value.length !== 2) {
+                    return true;
+                }
+                const [from, to] = value;
+                const num = Number(rowValue);
+                if (from != null && num < Number(from)) return false;
+                if (to != null && num > Number(to)) return false;
+                return true;
+            }
+
+            case 'IN': {
+                const list = Array.isArray(value) ? value : [value];
+                return list.some(v => String(rowValue) === String(v));
+            }
+
+            case 'NOTIN': {
+                const list = Array.isArray(value) ? value : [value];
+                return !list.some(v => String(rowValue) === String(v));
+            }
+
+            case 'NULL':
+            case 'ISNULL':
+                return rowValue == null;
+
+            case 'NOTNULL':
+            case 'ISNOTNULL':
+                return rowValue != null;
+
+            default:
+                return String(rowValue ?? '').toLowerCase()
+                    .includes(String(value).toLowerCase());
+        }
+    }
+
+    clearFilters(): void {
+        this._filtersInstance?.clear?.();
+        this._onFiltersChanged(null);
+    }
+
+    getFilters(): FilterSnapshot[] | null {
+        return this._lastFilterSnapshot ?? null;
+    }
+
+    // ==========================================================
+    // Remote Mode Public API
+    // ==========================================================
+
+    isRemoteMode(): boolean {
+        const mode = this.controller?.state?.mode;
+        return mode === 'remote' || mode === 'store';
+    }
+
+    isStoreMode(): boolean {
+        return this.controller?.state?.mode === 'store';
+    }
+
+    async load(params?: Record<string, unknown>): Promise<void> {
+        if (!this.isRemoteMode()) {
+            console.warn('[EzGrid] load() is only available in remote mode');
+            return;
+        }
+        return this.controller.load(params);
+    }
+
+    async reload(): Promise<void> {
+        return this.load();
+    }
+
+    getRemote(): EzGridRemote | null {
+        return this._remote;
+    }
+
+    // ==========================================================
+    // Export API
+    // ==========================================================
+
+    exportToCSV(options: ExportCSVOptions = {}): void {
+        const {
+            filename = 'export.csv',
+            includeHeaders = true,
+            separator = ',',
+            selectedOnly = false
+        } = options;
+
+        const csv = this._generateCSV({ includeHeaders, separator, selectedOnly });
+        this._downloadFile(csv, filename, 'text/csv;charset=utf-8;');
+    }
+
+    exportToExcel(options: ExportExcelOptions = {}): void {
+        const {
+            filename = 'export.xls',
+            includeHeaders = true,
+            selectedOnly = false
+        } = options;
+
+        const html = this._generateExcelHTML({ includeHeaders, selectedOnly });
+        this._downloadFile(html, filename, 'application/vnd.ms-excel');
+    }
+
+    private _generateCSV(options: { includeHeaders: boolean; separator: string; selectedOnly: boolean }): string {
+        const { includeHeaders, separator, selectedOnly } = options;
+        const columns = this.getVisibleColumns().filter(c =>
+            c.type !== 'selection' && c.type !== 'actions'
+        );
+
+        const data = this._getExportData(selectedOnly);
+        const lines: string[] = [];
+
+        if (includeHeaders) {
+            const headers = columns.map(c => this._escapeCSV(c.text ?? c.index));
+            lines.push(headers.join(separator));
+        }
+
+        for (const row of data) {
+            const values = columns.map(c => {
+                const value = (row as Record<string, unknown>)[c.index];
+                return this._escapeCSV(value ?? '');
+            });
+            lines.push(values.join(separator));
+        }
+
+        return lines.join('\n');
+    }
+
+    private _generateExcelHTML(options: { includeHeaders: boolean; selectedOnly: boolean }): string {
+        const { includeHeaders, selectedOnly } = options;
+        const columns = this.getVisibleColumns().filter(c =>
+            c.type !== 'selection' && c.type !== 'actions'
+        );
+
+        const data = this._getExportData(selectedOnly);
+
+        let html = '<html><head><meta charset="UTF-8"></head><body>';
+        html += '<table border="1">';
+
+        if (includeHeaders) {
+            html += '<thead><tr>';
+            for (const col of columns) {
+                html += `<th>${this._escapeHTML(col.text ?? col.index)}</th>`;
+            }
+            html += '</tr></thead>';
+        }
+
+        html += '<tbody>';
+        for (const row of data) {
+            html += '<tr>';
+            for (const col of columns) {
+                const value = (row as Record<string, unknown>)[col.index] ?? '';
+                html += `<td>${this._escapeHTML(String(value))}</td>`;
+            }
+            html += '</tr>';
+        }
+        html += '</tbody>';
+
+        html += '</table></body></html>';
+        return html;
+    }
+
+    private _getExportData(selectedOnly: boolean): unknown[] {
+        const data = this.controller?.state?.data ?? [];
+
+        if (!selectedOnly) return data;
+
+        return data.filter((row: any) => this.isSelected(row));
+    }
+
+    private _escapeCSV(value: unknown): string {
+        const str = String(value);
+
+        if (str.includes(',') || str.includes('"') || str.includes('\n')) {
+            return `"${str.replace(/"/g, '""')}"`;
+        }
+        return str;
+    }
+
+    private _escapeHTML(str: string): string {
+        const div = document.createElement('div');
+        div.textContent = str;
+        return div.innerHTML;
+    }
+
+    private _downloadFile(content: string, filename: string, mimeType: string): void {
+        const blob = new Blob([content], { type: mimeType });
+        const url = URL.createObjectURL(blob);
+
+        const link = document.createElement('a');
+        link.href = url;
+        link.download = filename;
+        link.style.display = 'none';
+
+        document.body.appendChild(link);
+        link.click();
+        document.body.removeChild(link);
+
+        URL.revokeObjectURL(url);
+    }
+
+    // ==========================================================
+    // Parts Building
+    // ==========================================================
+
+    private _buildParts(): void {
+        this.config.items = this._parts.build();
+        this._parts.cleanupConfig();
+    }
+
+    // ==========================================================
+    // Store Mode Initialization
+    // ==========================================================
+
+    private _initStore(config: EzGridConfig): void {
+        const store = config.store as any;
+
+        if (!store || typeof store.load !== 'function') {
+            console.warn('[EzGrid] Invalid store provided');
+            return;
+        }
+
+        this._store = store;
+        this.controller.state.mode = 'store';
+        this.controller.state.pageSize = store.state.pageSize;
+        this.controller.state.page = store.state.page;
+
+        this._storeUnsubscribers.push(
+            store.on('datachange', (data: unknown) => {
+                this.controller.state.data = data as RowData[];
+                this.controller.state.total = store.state.total;
+                this.controller.emit('datachange', data);
+            }),
+            store.on('loadingchange', (loading: unknown) => {
+                this.controller.state.loading = loading as boolean;
+                this._onLoadingChanged(loading as boolean);
+            }),
+            store.on('pagechange', (payload: unknown) => {
+                const { page, pageSize } = payload as { page: number; pageSize: number };
+                this.controller.state.page = page;
+                this.controller.state.pageSize = pageSize;
+            })
+        );
+
+        const originalSetPage = this.controller.setPage.bind(this.controller);
+        this.controller.setPage = (page: number) => {
+            if (this._store) {
+                this._store.setPage(page);
+            } else {
+                originalSetPage(page);
+            }
+        };
+
+        const originalSetPageSize = this.controller.setPageSize.bind(this.controller);
+        this.controller.setPageSize = (size: number) => {
+            if (this._store) {
+                this._store.setPageSize(size);
+            } else {
+                originalSetPageSize(size);
+            }
+        };
+
+        this.controller.load = () => {
+            if (this._store) {
+                return this._store.load();
+            }
+            return Promise.resolve();
+        };
+
+        this.controller.reload = () => {
+            if (this._store) {
+                return this._store.reload();
+            }
+            return Promise.resolve();
+        };
+
+        if (config.autoLoad !== false && store.state.data.length === 0 && !store.state.loading) {
+            this._autoLoadPending = true;
+        }
+    }
+
+    getStore(): any {
+        return this._store;
+    }
+
+    // ==========================================================
+    // Remote Mode Initialization
+    // ==========================================================
+
+    private _initRemote(config: EzGridConfig): void {
+        this._remote = new EzGridRemote(this, config.remote!);
+
+        if (!this._remote.isEnabled()) {
+            console.warn('[EzGrid] Remote config provided but not valid');
+            return;
+        }
+
+        if (config.pageSize) {
+            this.controller.state.pageSize = config.pageSize;
+        }
+
+        const transport = async (params: Record<string, unknown>) => {
+            return this._remote!.load(params);
+        };
+
+        this.controller.setRemoteConfig({
+            transport,
+            autoLoad: config.autoLoad === true,
+            pageSize: config.pageSize ?? 25
+        });
+
+        if (config.autoLoad === true) {
+            this._autoLoadPending = true;
+        }
+    }
+
+    private _initController(): void {
+        if (!this.stateful) {
+            this.controller = createEzGridController(this);
+            return;
+        }
+
+        if (!this.config.id) {
+            throw new EzError({
+                code: 'EZ_GRID_STATE_ID_REQUIRED',
+                message: 'Stateful EzGrid requires a unique "id"'
+            });
+        }
+
+        if (this._persistence.hasRegistryEntry()) {
+            this.controller = this._persistence.getRegistryEntry();
+
+            const entry = this._persistence.getRegistryEntry();
+            if (entry?._columnState) {
+                this._columns.restore(entry._columnState);
+            }
+
+            if (entry?._sortState) {
+                this._sort.restore(entry._sortState);
+            }
+
+            if (entry?._selectionState) {
+                this._applySelectionStateSnapshot(entry._selectionState);
+            }
+
+            return;
+        }
+
+        this.controller = createEzGridController(this);
+        this._persistence.setRegistryEntry(this.controller);
+
+        const stored = this._persistence.load();
+        if (stored) {
+            if (stored.columnState) {
+                this._columns.restore(stored.columnState);
+                this.controller._columnState = stored.columnState;
+            }
+
+            if (stored.sortState) {
+                this._applySortStateSnapshot(stored.sortState);
+                this.controller._sortState = stored.sortState;
+            }
+
+            if (stored.selectionState) {
+                this._applySelectionStateSnapshot(stored.selectionState);
+                this.controller._selectionState = stored.selectionState;
+            }
+        }
+    }
+
+    private async _ensureOverRulesApplied(): Promise<void> {
+        if (this._overRulesApplied) return;
+
+        if (!this.config.overRules) {
+            this._overRulesApplied = true;
+            return;
+        }
+
+        const rules = await ez.getGridBehavior(this.config.overRules);
+
+        Object.keys(rules).forEach(key => {
+            (this.controller as Record<string, unknown>)[key] = rules[key];
+        });
+
+        this.controller.onInit?.(this);
+        this._overRulesApplied = true;
+    }
+
+    private async _bindData(): Promise<void> {
+        if (this._store) {
+            if (this._store.state.data.length > 0) {
+                this.controller.state.data = this._store.state.data;
+                this.controller.state.total = this._store.state.total;
+            }
+            return;
+        }
+
+        let data: RowData[] = [];
+
+        if (Array.isArray(this.config.data)) {
+            data = this.config.data as RowData[];
+        } else {
+            const bind = this.config.bind;
+            if (bind && bind.data) {
+                const [controllerName, prop] = bind.data.split(':');
+                const controller = ez.getController(controllerName);
+
+                if (!controller || !controller.state) {
+                    throw new EzError({
+                        code: 'EZ_GRID_BIND_001',
+                        source: 'grid',
+                        message: `Invalid bind.data "${bind.data}"`
+                    });
+                }
+
+                const boundData = controller.state[prop] ?? [];
+                data = Array.isArray(boundData) ? boundData : [];
+            }
+        }
+
+        if (this.config.model) {
+            await ez._loader.resolveModel(this.config.model);
+            const model = ez.getModelSync(this.config.model);
+            this.controller._model = model;
+
+            if (data.length > 0 && model) {
+                data = model.processAll(data);
+            }
+        }
+
+        this.controller.state.data = data;
+        this.controller.state.total = data.length;
+    }
+
+    async _onControllerDataChange(): Promise<void> {
+        this._localSortBaseline = null;
+        this._hasLocalSortBaseline = false;
+        this._lifecycle.onControllerDataChange();
+    }
+
+    async suspendRefresh(fn: () => Promise<void> | void): Promise<void> {
+        await this._lifecycle.suspend(fn);
+    }
+
+    // ==========================================================
+    // Refresh Execution
+    // ==========================================================
+
+    async _refreshBodyInternal(): Promise<void> {
+        if (!this.el) return;
+
+        const fullData = this.controller.state.data ?? [];
+
+        if (typeof this.controller.beforeDataRender === 'function') {
+            try {
+                this.controller.beforeDataRender(this, fullData);
+            } catch (err) {
+                console.error('[EzGrid] beforeDataRender error', err);
+            }
+        }
+
+        try {
+            let displayData = fullData;
+
+            if (this.controller.state.mode !== 'remote') {
+                const { page, pageSize } = this.controller.state;
+                this.controller.state.total = fullData.length;
+
+                if (page && pageSize) {
+                    const start = (page - 1) * pageSize;
+                    const end = start + pageSize;
+                    displayData = fullData.slice(start, end);
+                }
+            }
+
+            this.config.data = displayData;
+
+            const body = this._bodyInstance;
+            if (body?.refreshData) {
+                await body.refreshData(displayData);
+
+                this._lifecycle.markHydrated();
+                this._footerInstance?.refresh?.();
+
+                if (typeof this.controller.afterDataRender === 'function') {
+                    try {
+                        this.controller.afterDataRender(this, fullData);
+                    } catch (err) {
+                        console.error('[EzGrid] afterDataRender error', err);
+                    }
+                }
+            }
+        } finally {
+            // Replay/pending refresh logic is owned by EzGridLifecycle
+        }
+    }
+
+    // ==========================================================
+    // Internal Helpers
+    // ==========================================================
+
+    _getRowKey(row: unknown): string | number | null {
+        const key = this.config.rowKey;
+        if (typeof key === 'function') {
+            return key(row);
+        }
+        return (row as Record<string, unknown>)?.[key as string] as string | number ?? null;
+    }
+}