ezfw-core 1.0.0

package/components/grid/header/EzGridHeader.ts

@@ -0,0 +1,430 @@
+// EzGrid/header/EzGridHeader.ts
+
+import './EzGridHeader.scss';
+import { EzGridContainer, EzGridContainerConfig } from '../EzGridContainer.js';
+import type {
+    NormalizedColumn,
+    HeaderConfig,
+    SortDirection,
+    EzGridSelectionRef
+} from '../types.js';
+
+declare const ez: {
+    _createElement(config: unknown): Promise<HTMLElement | null>;
+};
+
+export interface EzGridHeaderRef {
+    selection?: EzGridSelectionRef;
+    isAllSelected: () => boolean;
+    clearSelection: () => void;
+    selectAll: () => void;
+    isColumnSorted?: (colId: string) => boolean;
+    getColumnSortDirection?: (colId: string) => SortDirection | null;
+    toggleSort?: (colId: string) => void;
+    getVisibleColumns?: () => NormalizedColumn[];
+    columns?: NormalizedColumn[];
+    setColumnWidth?: (colId: string, width: number) => void;
+    moveColumn?: (colId: string, toIndex: number) => void;
+}
+
+export interface EzGridHeaderConfig extends EzGridContainerConfig {
+    header?: HeaderConfig;
+    columns?: (() => NormalizedColumn[]) | NormalizedColumn[];
+    grid?: EzGridHeaderRef;
+    reorderable?: boolean;
+}
+
+export class EzGridHeader extends EzGridContainer {
+    declare config: EzGridHeaderConfig;
+    declare el: HTMLElement | null;
+
+    private _resizing: boolean;
+    private _resizeCol: NormalizedColumn | null;
+    private _resizeStartX: number;
+    private _resizeStartWidth: number;
+    private _reorderable: boolean;
+    private _dragging: boolean;
+    private _dragCol: NormalizedColumn | null;
+    private _dragOverCol: NormalizedColumn | null;
+    private _defaultAlign: 'left' | 'center' | 'right';
+    private _onMouseMove?: (e: MouseEvent) => void;
+    private _onMouseUp?: () => void;
+
+    constructor(config: EzGridHeaderConfig = {}) {
+        super(config);
+
+        const { header } = config;
+
+        this.config.cls = (this.config.cls || '') + ' ez-grid-header';
+        this.config.layout = 'hbox';
+
+        // Resize state
+        this._resizing = false;
+        this._resizeCol = null;
+        this._resizeStartX = 0;
+        this._resizeStartWidth = 0;
+
+        // Drag reorder state
+        this._reorderable = config.reorderable !== false;
+        this._dragging = false;
+        this._dragCol = null;
+        this._dragOverCol = null;
+
+        // Apply global header config
+        this._defaultAlign = header?.align ?? 'left';
+
+        if (header?.cls) {
+            this.config.cls += ` ${header.cls}`;
+        }
+
+        if (header?.height) {
+            this.config.style = {
+                ...(this.config.style || {}),
+                minHeight: `${header.height}px`
+            };
+        }
+
+        if (header?.visible === false) {
+            this.config.style = {
+                ...(this.config.style || {}),
+                display: 'none'
+            };
+        }
+
+        this._buildColumns();
+    }
+
+    private _buildColumns(): void {
+        const rawColumns = this.config.columns;
+
+        const columns: NormalizedColumn[] =
+            typeof rawColumns === 'function'
+                ? rawColumns()
+                : (rawColumns || []);
+
+        const grid = this.config.grid;
+
+        const hasSelection = !!grid?.selection;
+
+        this.config.items = columns.map(col => {
+
+            // NOTE: Sort state must be queried via the Grid API.
+            // Header must not read legacy sortState or internal structures.
+            const isSorted = grid?.isColumnSorted?.(col._id) === true;
+            const dir = grid?.getColumnSortDirection?.(col._id);
+
+            // SELECT ALL
+            if (col.type === 'selection' && hasSelection) {
+                const checked = grid.isAllSelected();
+                const selectionWidth = col.width ?? 36;
+
+                return {
+                    eztype: 'EzComponent',
+                    cls: 'ez-grid-header-cell ez-grid-header-select-all',
+                    style: { width: `${selectionWidth}px`, justifyContent: 'center' },
+
+                    items: [{
+                        eztype: 'input',
+                        attrs: {
+                            type: 'checkbox',
+                            checked: checked ? true : null
+                        },
+                        onClick: (e: MouseEvent) => {
+                            e.stopPropagation();
+
+                            if (grid.isAllSelected()) {
+                                grid.clearSelection();
+                            } else {
+                                grid.selectAll();
+                            }
+                        }
+                    }]
+                };
+            }
+
+            if (col.type === 'actions') {
+                return {
+                    eztype: 'EzComponent',
+                    cls: 'ez-grid-header-cell align-center ez-grid-header-actions',
+                    style: { width: `${col.width}px` }
+                };
+            }
+
+            // width / flex - same logic as EzGridCell
+            const cellStyle = col.width != null
+                ? { width: `${col.width}px` }
+                : undefined;
+
+            const cellFlex = col.width != null
+                ? undefined
+                : (col.flex ?? 1);
+
+            // Check if column is resizable (default true unless explicitly false)
+            const resizable = col.resizable !== false && col.type !== 'selection';
+
+            // Check if column is reorderable
+            const canReorder = this._reorderable &&
+                col.reorderable !== false &&
+                col.type !== 'selection';
+
+            // Column-level align overrides global header.align
+            const cellAlign = col.header?.align ?? this._defaultAlign;
+
+            // Build cell style with alignment
+            const alignJustify = cellAlign === 'center' ? 'center'
+                : cellAlign === 'right' ? 'flex-end'
+                : 'flex-start';
+
+            const mergedStyle = {
+                ...cellStyle,
+                justifyContent: alignJustify
+            };
+
+            const items: any[] = [
+                {
+                    eztype: 'EzComponent',
+                    cls: 'ez-grid-header-text',
+                    text: col.text ?? '',
+                    style: { textAlign: cellAlign }
+                },
+                {
+                    eztype: 'i',
+                    cls: [
+                        'ez-grid-header-sort-icon',
+                        dir === 'ASC'
+                            ? 'fa fa-chevron-up'
+                            : dir === 'DESC'
+                                ? 'fa fa-chevron-down'
+                                : ''
+                    ].filter(Boolean).join(' ')
+                }
+            ];
+
+            // Add resize handle if resizable
+            if (resizable) {
+                items.push({
+                    eztype: 'EzComponent',
+                    cls: 'ez-grid-resize-handle',
+                    attrs: {
+                        'data-col-id': col._id
+                    },
+                    onMouseDown: (e: MouseEvent) => {
+                        e.stopPropagation();
+                        this._startResize(e, col);
+                    }
+                });
+            }
+
+            return {
+                eztype: 'EzComponent',
+                cls: [
+                    'ez-grid-header-cell',
+                    `align-${cellAlign}`,
+                    isSorted && 'is-sorted',
+                    dir === 'ASC' && 'is-sort-asc',
+                    dir === 'DESC' && 'is-sort-desc',
+                    resizable && 'is-resizable',
+                    canReorder && 'is-reorderable'
+                ].filter(Boolean).join(' '),
+
+                style: mergedStyle,
+                flex: cellFlex,
+                attrs: {
+                    'data-col-id': col._id,
+                    draggable: canReorder ? 'true' : undefined
+                },
+
+                items,
+
+                onClick: () => {
+                    // Don't trigger sort while resizing or dragging
+                    if (this._resizing || this._dragging) return;
+
+                    // WARNING: Header must toggle sort state, not force a direction.
+                    // sortBy() is an imperative API and always resets to ASC.
+                    grid?.toggleSort?.(col._id);
+                },
+
+                onDragStart: canReorder ? (e: DragEvent) => {
+                    this._handleDragStart(e, col);
+                } : undefined,
+
+                onDragOver: canReorder ? (e: DragEvent) => {
+                    this._handleDragOver(e, col);
+                } : undefined,
+
+                onDragLeave: canReorder ? (e: DragEvent) => {
+                    this._handleDragLeave(e);
+                } : undefined,
+
+                onDrop: canReorder ? (e: DragEvent) => {
+                    this._handleDrop(e, col);
+                } : undefined,
+
+                onDragEnd: canReorder ? () => {
+                    this._handleDragEnd();
+                } : undefined
+            };
+        });
+    }
+
+    // ==========================================================
+    // Column Reorder (Drag & Drop)
+    // ==========================================================
+
+    private _handleDragStart(e: DragEvent, col: NormalizedColumn): void {
+        this._dragging = true;
+        this._dragCol = col;
+
+        // Set drag data
+        e.dataTransfer!.effectAllowed = 'move';
+        e.dataTransfer!.setData('text/plain', col._id);
+
+        // Add dragging class
+        const cell = (e.target as HTMLElement).closest('.ez-grid-header-cell');
+        if (cell) {
+            cell.classList.add('is-dragging');
+        }
+    }
+
+    private _handleDragOver(e: DragEvent, col: NormalizedColumn): void {
+        if (!this._dragging || !this._dragCol) return;
+        if (this._dragCol._id === col._id) return;
+
+        e.preventDefault();
+        e.dataTransfer!.dropEffect = 'move';
+
+        this._dragOverCol = col;
+
+        // Add visual indicator
+        const cell = (e.target as HTMLElement).closest('.ez-grid-header-cell');
+        if (cell) {
+            // Determine drop position (before or after)
+            const rect = cell.getBoundingClientRect();
+            const midX = rect.left + rect.width / 2;
+
+            cell.classList.remove('drop-before', 'drop-after');
+            cell.classList.add(e.clientX < midX ? 'drop-before' : 'drop-after');
+        }
+    }
+
+    private _handleDragLeave(e: DragEvent): void {
+        const cell = (e.target as HTMLElement).closest('.ez-grid-header-cell');
+        if (cell) {
+            cell.classList.remove('drop-before', 'drop-after');
+        }
+    }
+
+    private _handleDrop(e: DragEvent, col: NormalizedColumn): void {
+        e.preventDefault();
+
+        if (!this._dragging || !this._dragCol || !col) return;
+        if (this._dragCol._id === col._id) return;
+
+        const grid = this.config.grid;
+        if (!grid) return;
+
+        // Determine target index
+        const columns = grid.getVisibleColumns?.() ?? grid.columns ?? [];
+        const targetIndex = columns.findIndex(c => c._id === col._id);
+
+        if (targetIndex === -1) return;
+
+        // Determine if before or after based on drop position
+        const cell = (e.target as HTMLElement).closest('.ez-grid-header-cell');
+        const dropAfter = cell?.classList.contains('drop-after');
+
+        const finalIndex = dropAfter ? targetIndex + 1 : targetIndex;
+
+        // Move column via grid API
+        grid.moveColumn?.(this._dragCol._id, finalIndex);
+
+        // Clean up
+        this._handleDragEnd();
+    }
+
+    private _handleDragEnd(): void {
+        // Remove all drag classes
+        this.el?.querySelectorAll('.ez-grid-header-cell').forEach(cell => {
+            cell.classList.remove('is-dragging', 'drop-before', 'drop-after');
+        });
+
+        // Reset state (delay to prevent click)
+        setTimeout(() => {
+            this._dragging = false;
+            this._dragCol = null;
+            this._dragOverCol = null;
+        }, 50);
+    }
+
+    private _startResize(e: MouseEvent, col: NormalizedColumn): void {
+        e.preventDefault();
+
+        this._resizing = true;
+        this._resizeCol = col;
+        this._resizeStartX = e.clientX;
+
+        // Get current width from element or column config
+        const headerCell = this.el?.querySelector(`[data-col-id="${col._id}"]`) as HTMLElement | null;
+        this._resizeStartWidth = headerCell?.offsetWidth ?? col.width ?? 100;
+
+        // Add document-level listeners
+        this._onMouseMove = this._handleResizeMove.bind(this);
+        this._onMouseUp = this._endResize.bind(this);
+
+        document.addEventListener('mousemove', this._onMouseMove);
+        document.addEventListener('mouseup', this._onMouseUp);
+
+        // Add resizing class to body for cursor
+        document.body.classList.add('ez-grid-resizing');
+    }
+
+    private _handleResizeMove(e: MouseEvent): void {
+        if (!this._resizing || !this._resizeCol) return;
+
+        const delta = e.clientX - this._resizeStartX;
+        const newWidth = Math.max(50, this._resizeStartWidth + delta);
+
+        // Update column width via grid API
+        const grid = this.config.grid;
+        grid?.setColumnWidth?.(this._resizeCol._id, newWidth);
+    }
+
+    private _endResize(): void {
+        // Remove listeners
+        if (this._onMouseMove) {
+            document.removeEventListener('mousemove', this._onMouseMove);
+        }
+        if (this._onMouseUp) {
+            document.removeEventListener('mouseup', this._onMouseUp);
+        }
+
+        // Remove resizing class
+        document.body.classList.remove('ez-grid-resizing');
+
+        // Reset state after a small delay to prevent click event
+        setTimeout(() => {
+            this._resizing = false;
+            this._resizeCol = null;
+        }, 50);
+    }
+
+    async refreshColumns(): Promise<void> {
+        this._buildColumns();
+
+        // Force re-render
+        if (this.el) {
+            this.el.innerHTML = '';
+
+            // Create all elements in parallel but preserve order
+            const children = await Promise.all(
+                (this.config.items || []).map(item => ez._createElement(item))
+            );
+
+            for (const child of children) {
+                if (child) this.el.appendChild(child);
+            }
+        }
+    }
+
+}

package/components/grid/query/EzGridQuery.ts

@@ -0,0 +1,81 @@
+// EzGrid/query/EzGridQuery.ts
+
+export type SortDirection = 'ASC' | 'DESC';
+
+export interface SortEntry {
+    field: string;
+    direction: SortDirection;
+}
+
+export interface FilterRule {
+    field?: string;
+    operator?: string;
+    value?: any;
+    and?: FilterRule[];
+    or?: FilterRule[];
+}
+
+// ---- sort helpers ----
+export function createSort(field: string, direction: SortDirection = 'ASC'): SortEntry[] {
+    return [
+        {
+            field,
+            direction
+        }
+    ];
+}
+
+export function clearSort(): null {
+    return null;
+}
+
+// ---- filter helpers ----
+export function eq(field: string, value: any): FilterRule {
+    return { field, operator: '=', value };
+}
+
+export function ne(field: string, value: any): FilterRule {
+    return { field, operator: '!=', value };
+}
+
+export function gt(field: string, value: any): FilterRule {
+    return { field, operator: '>', value };
+}
+
+export function gte(field: string, value: any): FilterRule {
+    return { field, operator: '>=', value };
+}
+
+export function lt(field: string, value: any): FilterRule {
+    return { field, operator: '<', value };
+}
+
+export function lte(field: string, value: any): FilterRule {
+    return { field, operator: '<=', value };
+}
+
+export function like(field: string, value: any): FilterRule {
+    return { field, operator: 'LIKE', value };
+}
+
+export function and(...rules: FilterRule[]): FilterRule {
+    return { and: rules };
+}
+
+export function or(...rules: FilterRule[]): FilterRule {
+    return { or: rules };
+}
+
+export function between(field: string, from: any, to: any): FilterRule {
+    if (import.meta?.env?.DEV && arguments.length !== 3) {
+        console.warn(
+            '[EzGridQuery] between() expects (field, from, to)'
+        );
+    }
+
+    return {
+        field,
+        operator: 'BETWEEN',
+        value: [from, to]
+    };
+}

package/components/grid/state/EzGridColumns.ts

@@ -0,0 +1,155 @@
+// EzGrid/state/EzGridColumns.ts
+
+import type {
+    NormalizedColumn,
+    ColumnsSnapshot
+} from '../types.js';
+
+export type EzGridColumn = NormalizedColumn;
+
+export interface ColumnsState {
+    visibility: Record<string, boolean>;
+    order: string[] | null;
+    widths: Record<string, number>;
+}
+
+export interface EzGridColumnsRef {
+    _onColumnsChanged: () => void;
+}
+
+// Re-export for backwards compatibility
+export type { ColumnsSnapshot } from '../types.js';
+
+export class EzGridColumns {
+    grid: EzGridColumnsRef;
+    columns: EzGridColumn[];
+    state: ColumnsState;
+
+    constructor(grid: EzGridColumnsRef, initialColumns: EzGridColumn[] = []) {
+        this.grid = grid;
+
+        // WARNING: Column state must be fully owned by this module.
+        // EzGrid should never mutate these objects directly.
+        this.columns = initialColumns;
+
+        this.state = {
+            visibility: Object.create(null),
+            order: null,
+            widths: Object.create(null)
+        };
+    }
+
+    getVisibleColumns(): EzGridColumn[] {
+        const { visibility, order, widths } = this.state;
+
+        let cols = this.columns;
+
+        // 1) Order
+        if (Array.isArray(order)) {
+            const map = new Map(cols.map(c => [c._id, c]));
+            cols = order.map(id => map.get(id)).filter((c): c is EzGridColumn => Boolean(c));
+        }
+
+        // 2) Visibility
+        cols = cols.filter(col => visibility[col._id] !== false);
+
+        // 3) Width override (derived)
+        return cols.map(col => {
+            const w = widths[col._id];
+
+            if (w != null) {
+                return {
+                    ...col,
+                    width: w,
+                    flex: null
+                };
+            }
+
+            return col;
+        });
+    }
+
+    hide(colId: string): void {
+        this.state.visibility[colId] = false;
+        this._changed();
+    }
+
+    show(colId: string): void {
+        this.state.visibility[colId] = true;
+        this._changed();
+    }
+
+    toggle(colId: string): void {
+        const current = this.state.visibility[colId];
+        this.state.visibility[colId] = current === false;
+        this._changed();
+    }
+
+    setWidth(colId: string, width: number): void {
+        if (typeof width !== 'number' || width <= 0) return;
+
+        this.state.widths[colId] = width;
+        this._changed();
+    }
+
+    resetWidth(colId: string): void {
+        if (this.state.widths[colId] != null) {
+            delete this.state.widths[colId];
+            this._changed();
+        }
+    }
+
+    move(colId: string, toIndex: number): void {
+        const ids = this.columns.map(c => c._id);
+
+        const order = this.state.order
+            ? [...this.state.order]
+            : [...ids];
+
+        const fromIndex = order.indexOf(colId);
+        if (fromIndex === -1) return;
+
+        // WARNING: Index is clamped to valid range
+        const target =
+            Math.max(0, Math.min(toIndex, order.length - 1));
+
+        order.splice(fromIndex, 1);
+        order.splice(target, 0, colId);
+
+        this.state.order = order;
+        this._changed();
+    }
+
+    snapshot(): ColumnsSnapshot {
+        const { visibility, order, widths } = this.state;
+
+        return {
+            visibility: { ...visibility },
+            order: order ? [...order] : null,
+            widths: { ...widths }
+        };
+    }
+
+    restore(snapshot: ColumnsSnapshot | null): void {
+        if (!snapshot) return;
+
+        const { visibility, order, widths } = snapshot;
+
+        if (visibility && typeof visibility === 'object') {
+            this.state.visibility = { ...visibility };
+        }
+
+        if (Array.isArray(order)) {
+            this.state.order = [...order];
+        }
+
+        if (widths && typeof widths === 'object') {
+            this.state.widths = { ...widths };
+        }
+    }
+
+    _changed(): void {
+        // NOTE: Delegates side effects to the grid.
+        this.grid._onColumnsChanged();
+    }
+}