ezfw-core 1.0.0

package/components/grid/state/EzGridController.ts

@@ -0,0 +1,470 @@
+// EzGrid/state/EzGridController.ts
+
+// WARNING: EzGridController is a state owner, NOT a lifecycle or rendering component.
+// It must NEVER:
+// - trigger grid refreshes
+// - access EzGridLifecycle
+// - mutate selection, columns, or sort
+// - perform rendering or persistence
+//
+// Allowed responsibilities:
+// - own controller.state
+// - emit events (datachange)
+// - notify loading / error state via grid callbacks
+
+import type {
+    DataMode,
+    RowData,
+    SortSnapshot,
+    FilterSnapshot,
+    TransportParams,
+    TransportResult,
+    TransportFn,
+    RemoteConfig,
+    EzGridModel,
+    EzGridController,
+    EzGridControllerState,
+    EventCallback
+} from '../types.js';
+
+// NOTE: Remote transport contract:
+// transport(params) => Promise<{ data: RowData[], total?: number }>
+//
+// - params is a plain object (paging, filters, sort, etc.)
+// - controller does NOT know how data is fetched
+// - transport must return an object with "data"
+// - EzGridRemote provides the transport implementation
+
+export interface EzGridControllerRef {
+    _lifecycle?: {
+        onControllerDataChange?: () => void;
+    };
+    _onLoadingChanged?: (loading: boolean) => void;
+    _onError?: (error: Error | null) => void;
+}
+
+type EventListeners = Record<string, EventCallback[]>;
+
+export function createEzGridController(grid: EzGridControllerRef): EzGridController {
+    const listeners: EventListeners = Object.create(null);
+
+    function devWarn(message: string): void {
+        // NOTE: Dev-only warnings. Never executed in production builds.
+        if (import.meta?.env?.DEV) {
+            console.warn(`[EzGridController] ${message}`);
+        }
+    }
+
+    function on(event: string, fn: EventCallback): void {
+        (listeners[event] ??= []).push(fn);
+    }
+
+    function off(event: string, fn: EventCallback): void {
+        if (!listeners[event]) return;
+        listeners[event] = listeners[event].filter(l => l !== fn);
+    }
+
+    function emit(event: string, payload?: unknown): void {
+        // WARNING: 'datachange' is the ONLY event that triggers grid refresh.
+        // Do NOT emit custom events that affect rendering.
+        if (event !== 'datachange') {
+            devWarn(
+                `Emitting non-contract event "${event}". ` +
+                `Only "datachange" is allowed to affect grid rendering.`
+            );
+        }
+
+        if (!listeners[event]) return;
+        for (const fn of listeners[event]) {
+            fn(payload);
+        }
+    }
+
+    // ======================================================
+    // PUBLIC CONTROLLER API
+    // ------------------------------------------------------
+    // The following methods are intended to be used by:
+    // - EzGrid
+    // - Grid behaviors
+    // - Application code (advanced use)
+    //
+    // Public methods:
+    // - load()
+    // - reload()
+    // - requestReload(reason)
+    // - setPage(page)
+    // - setPageSize(size)
+    // - setSortSnapshot(snapshot)
+    // - setFilterSnapshot(snapshot)
+    //
+    // WARNING:
+    // - Methods not listed above are considered INTERNAL.
+    // - Internal methods may change without notice.
+    // - Do NOT call transport directly from outside.
+    // ======================================================
+
+    const controller: EzGridController = {
+        grid: grid as any,
+
+        on,
+        off,
+        emit,
+
+        // NOTE: Prevents concurrent remote loads.
+        _isLoadingRemote: false,
+
+        // NOTE: Ensures page/pageSize changes during an active load are not lost.
+        _pendingRemoteReload: false,
+
+        // NOTE: Latest sort snapshot provided by the grid.
+        _lastSortSnapshot: null,
+
+        // NOTE: Latest filters snapshot provided by the grid.
+        _lastFilterSnapshot: null,
+
+        // NOTE: Controller state is the single source of truth for grid data.
+        // Grid rendering reacts to changes emitted via events.
+        state: {
+            data: [],
+            loading: false,
+            error: null,
+
+            page: 1,
+            pageSize: 25,
+            total: 0,
+
+            // NOTE: Data mode.
+            // 'local' is the default and only active mode for now.
+            // 'remote' is a contract placeholder.
+            mode: 'local' as DataMode
+
+        },
+
+        // ---- lifecycle ----
+        async load(params: Partial<TransportParams> = {}) {
+            // NOTE: Local mode does nothing.
+            if (this.state.mode !== 'remote') {
+                if (import.meta?.env?.DEV) {
+                    console.warn(
+                        '[EzGridController] load() called in local mode. No action taken.'
+                    );
+                }
+                return;
+            }
+
+            const transport = this._remoteConfig?.transport;
+
+            if (typeof transport !== 'function') {
+                if (import.meta?.env?.DEV) {
+                    console.warn(
+                        '[EzGridController] Remote load called without a valid transport.'
+                    );
+                }
+                return;
+            }
+
+            if (this._isLoadingRemote === true) {
+                // NOTE: Do not drop reload requests triggered during an active load.
+                this._pendingRemoteReload = true;
+
+                if (import.meta?.env?.DEV) {
+                    console.warn(
+                        '[EzGridController] Remote load deferred: already loading.'
+                    );
+                }
+                return;
+            }
+
+            this.setLoading(true);
+            this.setError(null);
+
+            // Clear current data before loading new data
+            this.state.data = [];
+            emit('datachange', this.state.data);
+
+            this._isLoadingRemote = true;
+
+            try {
+                // WARNING: transport execution is centralized here.
+                // Controller is the only layer allowed to call it.
+                const finalParams: TransportParams = {
+                    page: this.state.page,
+                    pageSize: this.state.pageSize,
+                    sort: this._lastSortSnapshot,
+                    filters: this._lastFilterSnapshot,
+                    ...params
+                };
+
+                const result = await transport(finalParams);
+
+                const data: RowData[] = Array.isArray(result?.data)
+                    ? result.data
+                    : [];
+
+                const total =
+                    typeof result?.total === 'number'
+                        ? result.total
+                        : data.length;
+
+                this.setData(data, { total });
+            } catch (err) {
+                this.setError(err as Error);
+
+                if (import.meta?.env?.DEV) {
+                    console.error(
+                        '[EzGridController] Remote load failed:',
+                        err
+                    );
+                }
+            } finally {
+                this._isLoadingRemote = false;
+                this.setLoading(false);
+
+                if (this._pendingRemoteReload === true) {
+                    this._pendingRemoteReload = false;
+                    // NOTE: Replay the most recent requested reload.
+                    this.load();
+                }
+            }
+        },
+
+        // ======================================================
+        // STATE SETTERS
+        // ------------------------------------------------------
+        // WARNING:
+        // - These methods mutate controller state.
+        // - Some of them MAY request a reload in remote mode.
+        // - They must NEVER perform transport logic directly.
+        // ======================================================
+
+        // ---- paging ----
+        setPage(page: number) {
+            const next = Number(page);
+            if (!Number.isInteger(next) || next < 1) return;
+
+            if (this.state.page === next) return;
+
+            this.state.page = next;
+
+            if (this.state.mode === 'remote') {
+                this.requestReload('page-change');
+            } else {
+                // Local mode: trigger body refresh
+                this.grid?._lifecycle?.onControllerDataChange?.();
+            }
+        },
+
+        setPageSize(size: number) {
+            const next = Number(size);
+            if (!Number.isInteger(next) || next < 1) return;
+
+            if (this.state.pageSize === next) return;
+
+            this.state.pageSize = next;
+            this.state.page = 1;
+
+            if (this.state.mode === 'remote') {
+                this.requestReload('pageSize-change');
+            } else {
+                // Local mode: trigger body refresh
+                this.grid?._lifecycle?.onControllerDataChange?.();
+            }
+        },
+
+        // ---- sort bridge (remote) ----
+        setSortSnapshot(snapshot: SortSnapshot | null) {
+            // NOTE: Snapshot is owned by EzGridSort.
+            // Controller only stores and forwards it to transport.
+            this._lastSortSnapshot = snapshot;
+
+            if (this.state.mode === 'remote') {
+                this.requestReload('sort-change');
+            }
+        },
+
+        // ---- filters bridge (remote contract) ----
+        setFilterSnapshot(snapshot: FilterSnapshot[] | null) {
+            // NOTE: Snapshot is owned by the grid/filter system.
+            // Controller only stores and forwards it to transport.
+            this._lastFilterSnapshot = snapshot;
+
+            if (this.state.mode === 'remote') {
+                this.requestReload('filter-change');
+            }
+        },
+
+        setData(data: RowData[], meta: { total?: number } = {}) {
+            let processedData = Array.isArray(data) ? data : [];
+
+            // Process through model if defined
+            if (this._model && processedData.length > 0) {
+                processedData = this._model.processAll(processedData);
+            }
+
+            this.state.data = processedData;
+            this.state.total = meta.total ?? this.state.data.length;
+
+            emit('datachange', this.state.data);
+        },
+
+        setLoading(value: boolean) {
+            // NOTE: Loading state notification is delegated to the grid lifecycle.
+            // Controller must not assume how loading is rendered.
+            this.state.loading = !!value;
+            grid._onLoadingChanged?.(this.state.loading);
+        },
+
+        setError(error: Error | null) {
+            // NOTE: Error propagation is delegated to the grid lifecycle.
+            // Controller must not perform UI-side error handling.
+            this.state.error = error;
+            grid._onError?.(error);
+        },
+
+        // ======================================================
+        // ACTIONS (DATA LOADING)
+        // ------------------------------------------------------
+        // WARNING:
+        // - These methods may trigger remote IO.
+        // - load() executes the transport.
+        // - reload() is an alias for load().
+        // - requestReload() is the preferred entry point.
+        // ======================================================
+
+        reload() {
+            return this.load();
+        },
+
+        // ---- reload orchestration (DX) ----
+        requestReload(reason: string = 'unspecified') {
+            // NOTE: Centralized reload request entry point.
+            // This method does NOT change behavior.
+            // It exists to make reload intent explicit and traceable.
+
+            if (import.meta?.env?.DEV) {
+                console.debug(
+                    `[EzGridController] Reload requested (${reason})`
+                );
+            }
+
+            return this.reload();
+        },
+
+        setRemoteConfig(config: Partial<RemoteConfig & { transport?: TransportFn }> = {}) {
+            this.state.mode = 'remote';
+
+            this._remoteConfig = {
+                transport: typeof config.transport === 'function'
+                    ? config.transport
+                    : null,
+
+                autoLoad: config.autoLoad === true,
+                pageSize:
+                    typeof config.pageSize === 'number'
+                        ? config.pageSize
+                        : this.state.pageSize
+            };
+
+            // Apply pageSize from config
+            if (typeof config.pageSize === 'number') {
+                this.state.pageSize = config.pageSize;
+            }
+        },
+
+        appendData(data: RowData[]) {
+            if (Array.isArray(data)) {
+                // Process through model if defined
+                const processed = this._model
+                    ? this._model.processAll(data)
+                    : data;
+
+                this.state.data = this.state.data.concat(processed);
+                emit('datachange', this.state.data);
+            }
+        },
+
+        clear() {
+            this.state.data = [];
+            this.state.total = 0;
+            emit('datachange', this.state.data);
+        },
+
+        // ======================================================
+        // MODEL-AWARE RECORD OPERATIONS
+        // ------------------------------------------------------
+        // These methods leverage the model (if defined) to process
+        // records before adding/updating them in the grid.
+        // ======================================================
+
+        addRecord(record: RowData) {
+            const processed = this._model
+                ? this._model.process(record)
+                : record;
+
+            this.state.data = [...this.state.data, processed];
+            this.state.total = this.state.data.length;
+            emit('datachange', this.state.data);
+        },
+
+        updateRecord(key: unknown, updates: Partial<RowData>): boolean {
+            const primaryKey = this._model?.primaryKey || 'id';
+            const idx = this.state.data.findIndex(r => r[primaryKey] === key);
+
+            if (idx < 0) {
+                if (import.meta?.env?.DEV) {
+                    console.warn(
+                        `[EzGridController] updateRecord: No record found with ${primaryKey}="${key}"`
+                    );
+                }
+                return false;
+            }
+
+            const merged = { ...this.state.data[idx], ...updates };
+            const processed = this._model
+                ? this._model.process(merged)
+                : merged;
+
+            this.state.data[idx] = processed;
+            this.state.data = [...this.state.data]; // Trigger reactivity
+            emit('datachange', this.state.data);
+            return true;
+        },
+
+        removeRecord(key: unknown): boolean {
+            const primaryKey = this._model?.primaryKey || 'id';
+            const idx = this.state.data.findIndex(r => r[primaryKey] === key);
+
+            if (idx < 0) {
+                if (import.meta?.env?.DEV) {
+                    console.warn(
+                        `[EzGridController] removeRecord: No record found with ${primaryKey}="${key}"`
+                    );
+                }
+                return false;
+            }
+
+            this.state.data.splice(idx, 1);
+            this.state.data = [...this.state.data]; // Trigger reactivity
+            this.state.total = this.state.data.length;
+            emit('datachange', this.state.data);
+            return true;
+        }
+
+    };
+
+    return controller;
+}
+
+// Re-export types for backwards compatibility
+export type {
+    DataMode,
+    SortSnapshot,
+    FilterSnapshot,
+    TransportParams,
+    TransportResult,
+    TransportFn,
+    RemoteConfig,
+    EzGridModel,
+    EzGridController,
+    EzGridControllerState
+} from '../types.js';

package/components/grid/state/EzGridLifecycle.ts

@@ -0,0 +1,136 @@
+// EzGrid/state/EzGridLifecycle.ts
+
+import type { EzGridBodyRef } from '../types.js';
+
+export interface EzGridLifecycleRef {
+    el?: HTMLElement | null;
+    _suppressSelectionPersistence?: boolean;
+    _bodyInstance?: EzGridBodyRef;
+    _refreshBodyInternal: () => Promise<void>;
+}
+
+export class EzGridLifecycle {
+    grid: EzGridLifecycleRef;
+    private _isRefreshing: boolean;
+    private _pendingRefresh: boolean;
+    private _refreshSuspended: boolean;
+    private _hydrated: boolean;
+    private _loading: boolean;
+    private _error: Error | null;
+
+    constructor(grid: EzGridLifecycleRef) {
+        this.grid = grid;
+
+        // WARNING: Lifecycle owns refresh orchestration ONLY.
+        // Rendering and side effects remain in EzGrid executor methods.
+        this._isRefreshing = false;
+        this._pendingRefresh = false;
+        this._refreshSuspended = false;
+
+        // NOTE: Tracks whether the grid has completed its first successful hydration.
+        // This controls when selection persistence is allowed.
+        this._hydrated = false;
+
+        this._loading = false;
+        this._error = null;
+    }
+
+    onControllerDataChange(): void {
+        // WARNING: If the grid is not rendered yet, we must NOT attempt a refresh.
+        // The request must be deferred, otherwise the first refresh can be lost.
+        if (!this.grid?.el) {
+            this._pendingRefresh = true;
+            return;
+        }
+
+        if (this._refreshSuspended) {
+            this._pendingRefresh = true;
+            return;
+        }
+
+        if (this._isRefreshing) {
+            this._pendingRefresh = true;
+            return;
+        }
+
+        void this._runRefresh();
+    }
+
+    markHydrated(): void {
+        // WARNING: This must be called exactly once,
+        // after the first successful body refresh.
+        if (this._hydrated === true) return;
+
+        this._hydrated = true;
+
+        // NOTE: Selection persistence is enabled only after hydration.
+        this.grid._suppressSelectionPersistence = false;
+    }
+
+
+    async _runRefresh(): Promise<void> {
+        this._isRefreshing = true;
+
+        try {
+            await this.grid._refreshBodyInternal();
+        } finally {
+            this._isRefreshing = false;
+
+            if (this._pendingRefresh) {
+                // WARNING: Must clear flag BEFORE rerun to avoid endless loops.
+                this._pendingRefresh = false;
+                await this._runRefresh();
+            }
+        }
+    }
+
+    async suspend<T>(fn: () => Promise<T>): Promise<void> {
+        this._refreshSuspended = true;
+
+        try {
+            await fn();
+        } finally {
+            this._refreshSuspended = false;
+
+            if (this._pendingRefresh) {
+                this._pendingRefresh = false;
+                await this._runRefresh();
+            }
+        }
+    }
+
+    destroy(): void {
+        // WARNING: Cleanup must be idempotent.
+        this._pendingRefresh = false;
+        this._refreshSuspended = false;
+        this._isRefreshing = false;
+    }
+
+    onLoadingChanged(loading: boolean): void {
+        // NOTE: Lifecycle receives loading state changes.
+        // It must NOT re-dispatch them back to the grid,
+        // otherwise a recursion loop will occur.
+
+        this._loading = loading;
+
+        // Notify body instance of loading state
+        const body = this.grid._bodyInstance;
+        if (body?.setLoading) {
+            body.setLoading(loading);
+        }
+    }
+
+    onError(error: Error | null): void {
+        // NOTE: Lifecycle receives error state.
+        // It must NOT re-dispatch back to the grid.
+
+        this._error = error;
+
+        // Notify body instance of error state
+        const body = this.grid._bodyInstance;
+        if (body?.setError) {
+            body.setError(error);
+        }
+    }
+
+}