ezfw-core 1.0.0

package/components/grid/state/EzGridSort.ts

@@ -0,0 +1,286 @@
+// EzGrid/state/EzGridSort.ts
+
+import type {
+    SortDirection,
+    Sorter,
+    SortConfig,
+    SortSnapshot,
+    NormalizedColumn,
+    RowData
+} from '../types.js';
+
+export interface EzGridSortRef {
+    controller?: {
+        state: {
+            data: RowData[];
+        };
+        setSortSnapshot?: (snapshot: SortSnapshot | null) => void;
+        supportsRemoteSort?: boolean;
+        sort?: (columnId: string, direction: SortDirection) => void;
+    };
+    stateful?: boolean;
+    columns: NormalizedColumn[];
+    headerInstance?: {
+        refreshColumns?: () => void;
+    };
+    _persistence?: {
+        updateSortState: (snapshot: Sorter[] | null) => void;
+        save: () => void;
+    };
+    _hasLocalSortBaseline?: boolean;
+    _localSortBaseline?: RowData[] | null;
+    refreshBody: () => Promise<void>;
+}
+
+// Re-export types for backwards compatibility
+export type { SortDirection, Sorter, SortConfig, SortSnapshot } from '../types.js';
+
+export class EzGridSort {
+    grid: EzGridSortRef;
+    sorters: Sorter[];
+
+    constructor(grid: EzGridSortRef, config: SortConfig | SortConfig[] | null = null) {
+        this.grid = grid;
+
+        // WARNING: Sort state must be owned exclusively by this module.
+        // EzGrid should never mutate sorters directly.
+        this.sorters = [];
+
+        if (config) {
+            this._initFromConfig(config);
+        }
+    }
+
+    // ==========================================================
+    // Initialization
+    // ==========================================================
+
+    private _initFromConfig(config: SortConfig | SortConfig[]): void {
+        // NOTE: Supports both single sorter and array of sorters
+        if (Array.isArray(config)) {
+            this.sorters = config
+                .map(c => this._normalizeSorter(c))
+                .filter((s): s is Sorter => s !== null);
+        } else {
+            const s = this._normalizeSorter(config);
+            if (s) this.sorters = [s];
+        }
+    }
+
+    private _normalizeSorter(sorter: SortConfig | null): Sorter | null {
+        if (!sorter || !sorter.property) return null;
+
+        return {
+            property: sorter.property,
+            direction:
+                sorter.direction === 'DESC' ? 'DESC' : 'ASC'
+        };
+    }
+
+    // ==========================================================
+    // Public API
+    // ==========================================================
+
+    getSorters(): Sorter[] {
+        return this.sorters;
+    }
+
+    getSorterFor(property: string): Sorter | null {
+        return this.sorters.find(s => s.property === property) || null;
+    }
+
+    isSorted(property: string): boolean {
+        return !!this.getSorterFor(property);
+    }
+
+    toggleSort(property: string): void {
+        const existing = this.getSorterFor(property);
+
+        if (!existing) {
+            this.sorters = [{
+                property,
+                direction: 'ASC'
+            }];
+        } else if (existing.direction === 'ASC') {
+            existing.direction = 'DESC';
+        } else {
+            // WARNING: Clearing sort removes all sorters for now.
+            // This matches current single-sort behavior.
+            this.sorters = [];
+        }
+
+        this._changed();
+    }
+
+    clear(): void {
+        if (this.sorters.length === 0) return;
+
+        this.sorters = [];
+        this._changed();
+    }
+
+    sortBy(colId: string, direction?: SortDirection): void {
+        if (!colId) return;
+
+        const dir: SortDirection = direction === 'DESC' ? 'DESC' : 'ASC';
+        this.sorters = [{ property: colId, direction: dir }];
+        this._changed();
+    }
+
+    // ==========================================================
+    // Snapshot / Restore
+    // ==========================================================
+
+    snapshot(): Sorter[] | null {
+        if (!this.sorters.length) return null;
+
+        return this.sorters.map(s => ({
+            property: s.property,
+            direction: s.direction
+        }));
+    }
+
+    restore(snapshot: Sorter[] | null): void {
+        if (!Array.isArray(snapshot)) {
+            this.sorters = [];
+            return;
+        }
+
+        this.sorters = snapshot
+            .map(s => this._normalizeSorter(s))
+            .filter((s): s is Sorter => s !== null);
+    }
+
+    getSortSnapshot(): Sorter | null {
+        // NOTE: Returns snapshot format for remote controller
+        const sorter = this.sorters[0];
+        if (!sorter) return null;
+
+        return {
+            property: sorter.property,
+            direction: sorter.direction
+        };
+    }
+
+    // ==========================================================
+    // Sort Handler (main logic moved from EzGrid)
+    // ==========================================================
+
+    handleSortChanged(): void {
+        const grid = this.grid;
+        const sorter = this.sorters[0] ?? null;
+
+        if (!sorter) {
+            this._handleClearSort();
+            return;
+        }
+
+        const { property: columnId, direction } = sorter;
+
+        // Forward active sort snapshot to controller (remote contract)
+        grid.controller?.setSortSnapshot?.(this.getSortSnapshot());
+
+        // Save state if stateful
+        if (grid.stateful) {
+            grid._persistence?.updateSortState(this.snapshot());
+            grid._persistence?.save();
+        }
+
+        // Refresh header to show sort indicators
+        grid.headerInstance?.refreshColumns?.();
+
+        // Remote sorting
+        if (grid.controller?.supportsRemoteSort) {
+            grid.controller.sort?.(columnId, direction);
+            return;
+        }
+
+        // Local sorting
+        this.applyLocalSort();
+    }
+
+    private _handleClearSort(): void {
+        const grid = this.grid;
+
+        // Restore baseline data for local mode
+        if (!grid.controller?.supportsRemoteSort) {
+            if (grid._hasLocalSortBaseline === true && Array.isArray(grid._localSortBaseline)) {
+                grid.controller!.state.data = [...grid._localSortBaseline];
+            }
+
+            grid._localSortBaseline = null;
+            grid._hasLocalSortBaseline = false;
+        }
+
+        // Clear persisted state
+        if (grid.stateful) {
+            grid._persistence?.updateSortState(null);
+            grid._persistence?.save();
+        }
+
+        // Refresh header to clear sort icons
+        grid.headerInstance?.refreshColumns?.();
+
+        // Forward cleared sort snapshot to controller
+        grid.controller?.setSortSnapshot?.(null);
+
+        // Refresh body to reflect unsorted data
+        void grid.refreshBody();
+    }
+
+    // ==========================================================
+    // Local Sort Execution
+    // ==========================================================
+
+    applyLocalSort(): void {
+        const grid = this.grid;
+        const sorter = this.sorters[0];
+
+        if (!sorter) return;
+
+        const { property: columnId, direction } = sorter;
+
+        if (!columnId || !direction) {
+            void grid.refreshBody();
+            return;
+        }
+
+        const col = grid.columns.find(c => c._id === columnId);
+        if (!col || !col.index) return;
+
+        // Capture baseline once per dataset, before applying the first local sort
+        if (grid._hasLocalSortBaseline !== true) {
+            grid._localSortBaseline = [...grid.controller!.state.data];
+            grid._hasLocalSortBaseline = true;
+        }
+
+        const data = [...grid.controller!.state.data];
+
+        data.sort((a, b) => {
+            const va = a?.[col.index!];
+            const vb = b?.[col.index!];
+
+            const isAsc = direction === 'ASC';
+
+            if (va == null && vb == null) return 0;
+            if (va == null) return isAsc ? -1 : 1;
+            if (vb == null) return isAsc ? 1 : -1;
+
+            if (va < vb) return isAsc ? -1 : 1;
+            if (va > vb) return isAsc ? 1 : -1;
+            return 0;
+        });
+
+        grid.controller!.state.data = data;
+        void grid.refreshBody();
+    }
+
+    // ==========================================================
+    // Internal
+    // ==========================================================
+
+    private _changed(): void {
+        // NOTE: Delegate to handler
+        this.handleSortChanged();
+    }
+}

package/components/grid/title/EzGridActionBar.ts

@@ -0,0 +1,98 @@
+// EzGrid/title/EzGridActionBar.ts
+
+import { EzGridContainer, EzGridContainerConfig } from '../EzGridContainer.js';
+
+export interface ToolConfig {
+    requiresSelection?: boolean;
+    minSelection?: number;
+    onClick?: (grid: any) => void;
+    [key: string]: any;
+}
+
+export interface ToolInstance {
+    tool: ToolConfig;
+    cfg: any;
+}
+
+export interface EzGridActionBarRef {
+    on?: (event: string, callback: (e: { keys: string[] }) => void) => void;
+    getSelection?: () => string[];
+}
+
+export interface EzGridActionBarConfig extends EzGridContainerConfig {
+    grid?: EzGridActionBarRef;
+    tools?: ToolConfig[];
+}
+
+export class EzGridActionBar extends EzGridContainer {
+    declare config: EzGridActionBarConfig;
+    declare el: HTMLElement | null;
+
+    grid: EzGridActionBarRef | undefined;
+    tools: ToolConfig[];
+    private _toolInstances: ToolInstance[];
+
+    constructor(config: EzGridActionBarConfig = {}) {
+        super(config);
+
+        this.grid = config.grid;
+        this.tools = Array.isArray(config.tools) ? config.tools : [];
+
+        this.config.cls = 'ez-grid-titlebar-tools';
+        this.config.layout = 'hbox';
+
+        this._toolInstances = [];
+
+        this._buildItems();
+        this._bindSelection();
+    }
+
+    private _buildItems(): void {
+        this._toolInstances = [];
+
+        this.config.items = this.tools.map(tool => {
+            const cfg: any = {
+                ...tool,
+                disabled: true,
+                onClick: () => {
+                    tool.onClick?.(this.grid);
+                }
+            };
+
+            this._toolInstances.push({ tool, cfg });
+            return cfg;
+        });
+    }
+
+    private _bindSelection(): void {
+        if (!this.grid?.on) return;
+
+        this.grid.on('selectionchange', (e: { keys: string[] }) => {
+            this._updateTools(e.keys.length);
+        });
+
+        // initial state
+        this._updateTools(this.grid.getSelection?.()?.length ?? 0);
+    }
+
+    private _updateTools(count: number): void {
+        for (const { tool, cfg } of this._toolInstances) {
+            let enabled = true;
+
+            if (tool.requiresSelection === true) {
+                enabled = count > 0;
+            }
+
+            if (typeof tool.minSelection === 'number') {
+                enabled = count >= tool.minSelection;
+            }
+
+            cfg.disabled = !enabled;
+        }
+
+        // force repaint
+        if (this.el) {
+            this.el.querySelectorAll('[disabled]').forEach(() => {});
+        }
+    }
+}

package/components/grid/title/EzGridTitle.ts

@@ -0,0 +1,114 @@
+// EzGrid/title/EzGridTitle.ts
+
+import { EzGridContainer, EzGridContainerConfig } from '../EzGridContainer.js';
+import type { TitleBarContext, RowData } from '../types.js';
+
+declare const ez: {
+    _createElement(config: any): Promise<HTMLElement | null>;
+};
+
+export interface EzGridTitleRef {
+    on?: (event: string, callback: () => void) => void;
+    getSelection: () => string[];
+    isSelected: (row: any) => boolean;
+    controller?: {
+        state?: {
+            data: any[];
+        };
+    };
+}
+
+export interface EzGridTitleConfig extends EzGridContainerConfig {
+    grid?: EzGridTitleRef;
+    title?: string | ((ctx: TitleBarContext) => any);
+    ctx?: TitleBarContext;
+    showSelectionCount?: boolean;
+}
+
+export class EzGridTitle extends EzGridContainer {
+    declare config: EzGridTitleConfig;
+
+    grid: EzGridTitleRef | undefined;
+    title: string | ((ctx: TitleBarContext) => any) | undefined;
+    ctx: TitleBarContext | undefined;
+    showSelectionCount: boolean;
+    private _el: HTMLElement | null;
+
+    constructor(config: EzGridTitleConfig = {}) {
+        super(config);
+
+        this.grid = config.grid;
+        this.title = config.title;
+        this.ctx = config.ctx;
+        this.showSelectionCount = config.showSelectionCount === true;
+
+        this.config.cls = 'ez-grid-titlebar-title';
+        this.config.flex = 1;
+
+        this._el = null;
+    }
+
+    async render(): Promise<HTMLDivElement> {
+        const el = document.createElement('div');
+
+        el.className = this.config.cls as string;
+        el.style.flex = String(this.config.flex);
+
+        this._el = el;
+
+        // initial render
+        await this._renderTitle();
+
+        // reactive only if function
+        if ((typeof this.title === 'function' || this.showSelectionCount === true) && this.grid?.on) {
+            this.grid.on('selectionchange', () => {
+                this._renderTitle();
+            });
+        }
+
+        return el;
+    }
+
+    private async _renderTitle(): Promise<void> {
+        if (!this._el) return;
+
+        // clear previous content
+        this._el.innerHTML = '';
+
+        let result: any = this.title;
+
+        if (typeof this.title === 'function') {
+            const ctx: TitleBarContext = {
+                ...this.ctx!,
+                selection: {
+                    keys: this.grid!.getSelection(),
+                    rows: this.grid!.controller?.state?.data?.filter(row =>
+                        this.grid!.isSelected(row)
+                    ) ?? [],
+                    count: this.grid!.getSelection().length
+                }
+            };
+
+            result = this.title(ctx);
+        }
+
+        // append selection count (sugar)
+        if (
+            this.showSelectionCount === true &&
+            typeof result === 'string'
+        ) {
+            const count = this.grid!.getSelection().length;
+            result = `${result} (${count})`;
+        }
+
+        // simple string
+        if (typeof result === 'string') {
+            this._el.textContent = result;
+        }
+        // EZ component
+        else if (typeof result === 'object') {
+            const child = await ez._createElement(result);
+            if (child) this._el.appendChild(child);
+        }
+    }
+}

package/components/grid/title/EzGridTitleBar.scss

@@ -0,0 +1,65 @@
+// ==========================================================
+// EzGridTitleBar
+// ==========================================================
+
+.ez-grid-titlebar {
+  display: flex;
+  align-items: center;
+
+  min-height: 48px;
+  padding: 0 16px;
+
+  background-color: var(--ez-grid-surface);
+  border-bottom: 1px solid var(--ez-grid-border);
+
+  // ----------------------------------------------------------
+  // Title
+  // ----------------------------------------------------------
+  .ez-grid-titlebar-title {
+    display: flex;
+    align-items: center;
+
+    font-size: var(--ez-grid-font-size-lg);
+    font-weight: var(--ez-grid-font-weight-semibold);
+    color: var(--ez-grid-text);
+
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+
+  // ----------------------------------------------------------
+  // Action bar (tools)
+  // ----------------------------------------------------------
+  .ez-grid-titlebar-tools {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+
+    button,
+    .ez-button {
+      height: 32px;
+      padding: 0 12px;
+
+      font-size: var(--ez-grid-font-size);
+      font-weight: var(--ez-grid-font-weight-medium);
+
+      border-radius: var(--ez-grid-radius-sm);
+      background-color: var(--ez-grid-bg);
+      border: 1px solid var(--ez-grid-border);
+      color: var(--ez-grid-text);
+
+      cursor: pointer;
+      transition: all 0.15s ease;
+
+      &:hover {
+        background-color: var(--ez-grid-surface-hover);
+        border-color: var(--ez-grid-border);
+      }
+
+      &:active {
+        background-color: var(--ez-grid-surface-active);
+      }
+    }
+  }
+}

package/components/grid/title/EzGridTitleBar.ts

@@ -0,0 +1,87 @@
+// EzGrid/title/EzGridTitleBar.ts
+
+import './EzGridTitleBar.scss';
+import { EzGridContainer, EzGridContainerConfig } from '../EzGridContainer.js';
+import type { TitleBarContext } from '../types.js';
+
+export interface EzGridTitleBarConfig extends EzGridContainerConfig {
+    title?: string | ((ctx: TitleBarContext) => any);
+    tools?: any[] | ((ctx: TitleBarContext) => any[]);
+    bind?: any;
+    grid?: any;
+    titleOverride?: ((ctx: TitleBarContext) => any) | null;
+    toolsOverride?: ((ctx: TitleBarContext) => any[]) | null;
+    ctx?: TitleBarContext;
+}
+
+export class EzGridTitleBar extends EzGridContainer {
+    declare config: EzGridTitleBarConfig;
+
+    constructor(config: EzGridTitleBarConfig = {}) {
+        super(config);
+
+        this.config.cls = (this.config.cls || '') + ' ez-grid-titlebar';
+        this.config.layout = 'hbox';
+
+        this._buildItems();
+    }
+
+    private _buildItems(): void {
+        const {
+            title,
+            tools,
+            bind,
+            grid,
+            titleOverride,
+            toolsOverride,
+            ctx
+        } = this.config;
+
+        const items: any[] = [];
+
+        // -----------------------------
+        // TITLE (default / override)
+        // -----------------------------
+        let resolvedTitle: any = title;
+
+        if (typeof titleOverride === 'function') {
+            resolvedTitle = titleOverride;
+        }
+
+        if (resolvedTitle) {
+            items.push({
+                eztype: 'EzGridTitle',
+                title: resolvedTitle,
+                grid,
+                ctx,
+                showSelectionCount: this.config.grid?.config?.showSelectionCount === true
+            });
+        }
+
+        // -----------------------------
+        // TOOLS (default / override)
+        // -----------------------------
+        let resolvedTools: any = tools;
+
+        if (typeof toolsOverride === 'function' && ctx) {
+            resolvedTools = toolsOverride(ctx);
+        }
+
+        if (resolvedTools) {
+            // override total del action bar
+            if (!Array.isArray(resolvedTools)) {
+                items.push(resolvedTools);
+            }
+            // default EzGridActionBar
+            else {
+                items.push({
+                    eztype: 'EzGridActionBar',
+                    tools: resolvedTools,
+                    grid
+                });
+            }
+        }
+
+        this.config.items = items;
+    }
+}