ezfw-core 1.0.0

package/components/grid/state/EzGridNormalizers.test.js

@@ -0,0 +1,273 @@
+// ==========================================================
+// EzGridNormalizers - Unit Tests
+// ==========================================================
+// Para correr: npm test
+// Para correr una vez: npm run test:run
+// Para correr solo este archivo: npm test EzGridNormalizers
+// ==========================================================
+
+import { describe, it, expect } from 'vitest';
+import { EzGridNormalizers } from './EzGridNormalizers.js';
+
+// ==========================================================
+// normalizeHeader
+// ==========================================================
+
+describe('EzGridNormalizers.normalizeHeader', () => {
+
+    it('should return false when header is false', () => {
+        const result = EzGridNormalizers.normalizeHeader(false);
+        expect(result).toBe(false);
+    });
+
+    it('should return default config when header is true', () => {
+        const result = EzGridNormalizers.normalizeHeader(true);
+        expect(result).toEqual({ align: 'left' });
+    });
+
+    it('should return default config when header is null/undefined', () => {
+        expect(EzGridNormalizers.normalizeHeader(null)).toEqual({ align: 'left' });
+        expect(EzGridNormalizers.normalizeHeader(undefined)).toEqual({ align: 'left' });
+    });
+
+    it('should preserve custom align from config', () => {
+        const result = EzGridNormalizers.normalizeHeader({ align: 'center' });
+        expect(result.align).toBe('center');
+    });
+
+    it('should preserve all header properties', () => {
+        const result = EzGridNormalizers.normalizeHeader({
+            align: 'right',
+            cls: 'my-header',
+            height: 50,
+            visible: false
+        });
+
+        expect(result).toEqual({
+            align: 'right',
+            cls: 'my-header',
+            height: 50,
+            visible: false
+        });
+    });
+
+});
+
+// ==========================================================
+// normalizeColumns
+// ==========================================================
+
+describe('EzGridNormalizers.normalizeColumns', () => {
+
+    it('should normalize basic columns', () => {
+        const columns = [
+            { index: 'name', text: 'Name' },
+            { index: 'email', text: 'Email' }
+        ];
+
+        const result = EzGridNormalizers.normalizeColumns(columns);
+
+        expect(result).toHaveLength(2);
+        expect(result[0].index).toBe('name');
+        expect(result[0].text).toBe('Name');
+        expect(result[0].flex).toBe(1); // default flex
+        expect(result[0].sortable).toBe(true); // default sortable
+    });
+
+    it('should set default flex to 1', () => {
+        const columns = [{ index: 'name' }];
+        const result = EzGridNormalizers.normalizeColumns(columns);
+
+        expect(result[0].flex).toBe(1);
+    });
+
+    it('should preserve custom flex value', () => {
+        const columns = [{ index: 'name', flex: 3 }];
+        const result = EzGridNormalizers.normalizeColumns(columns);
+
+        expect(result[0].flex).toBe(3);
+    });
+
+    it('should preserve fixed width', () => {
+        const columns = [{ index: 'name', width: 200 }];
+        const result = EzGridNormalizers.normalizeColumns(columns);
+
+        expect(result[0].width).toBe(200);
+    });
+
+    it('should handle actions column', () => {
+        const columns = [
+            { index: 'name' },
+            { type: 'actions', actions: [{ icon: '✏️' }] }
+        ];
+
+        const result = EzGridNormalizers.normalizeColumns(columns);
+
+        expect(result[1].type).toBe('actions');
+        expect(result[1].width).toBe(96); // default actions width
+        expect(result[1].actions).toHaveLength(1);
+        expect(result[1].header.align).toBe('center');
+    });
+
+    it('should use custom width for actions column', () => {
+        const columns = [
+            { type: 'actions', width: 150, actions: [] }
+        ];
+
+        const result = EzGridNormalizers.normalizeColumns(columns);
+
+        expect(result[0].width).toBe(150);
+    });
+
+    // ----- Selection Column -----
+
+    it('should NOT add selection column when mode is single', () => {
+        const columns = [{ index: 'name' }];
+        const result = EzGridNormalizers.normalizeColumns(columns, {
+            selectionMode: 'single'
+        });
+
+        expect(result).toHaveLength(1);
+        expect(result[0].type).not.toBe('selection');
+    });
+
+    it('should auto-add selection column when mode is multi', () => {
+        const columns = [{ index: 'name' }];
+        const result = EzGridNormalizers.normalizeColumns(columns, {
+            selectionMode: 'multi'
+        });
+
+        expect(result).toHaveLength(2);
+        expect(result[0].type).toBe('selection');
+        expect(result[0].width).toBe(36); // default width
+    });
+
+    it('should use custom selection width', () => {
+        const columns = [{ index: 'name' }];
+        const result = EzGridNormalizers.normalizeColumns(columns, {
+            selectionMode: 'multi',
+            selectionWidth: 50
+        });
+
+        expect(result[0].type).toBe('selection');
+        expect(result[0].width).toBe(50);
+    });
+
+    it('should filter out manually added selection columns', () => {
+        const columns = [
+            { type: 'selection', width: 40 }, // manual - should be ignored
+            { index: 'name' }
+        ];
+
+        const result = EzGridNormalizers.normalizeColumns(columns, {
+            selectionMode: 'multi',
+            selectionWidth: 36
+        });
+
+        // Should have 2: auto-added selection + name
+        expect(result).toHaveLength(2);
+        expect(result[0].type).toBe('selection');
+        expect(result[0].width).toBe(36); // uses selectionWidth, not manual 40
+    });
+
+    // ----- Wrap -----
+
+    it('should normalize wrap: true to 3 lines', () => {
+        const columns = [{ index: 'description', wrap: true }];
+        const result = EzGridNormalizers.normalizeColumns(columns);
+
+        expect(result[0].wrap).toBe(3);
+    });
+
+    it('should preserve numeric wrap value', () => {
+        const columns = [{ index: 'description', wrap: 5 }];
+        const result = EzGridNormalizers.normalizeColumns(columns);
+
+        expect(result[0].wrap).toBe(5);
+    });
+
+    it('should set wrap to false when not specified', () => {
+        const columns = [{ index: 'name' }];
+        const result = EzGridNormalizers.normalizeColumns(columns);
+
+        expect(result[0].wrap).toBe(false);
+    });
+
+    // ----- Sortable -----
+
+    it('should be sortable by default', () => {
+        const columns = [{ index: 'name' }];
+        const result = EzGridNormalizers.normalizeColumns(columns);
+
+        expect(result[0].sortable).toBe(true);
+    });
+
+    it('should disable sort when sort: false', () => {
+        const columns = [{ index: 'name', sort: false }];
+        const result = EzGridNormalizers.normalizeColumns(columns);
+
+        expect(result[0].sortable).toBe(false);
+    });
+
+    // ----- Header Align -----
+
+    it('should use column header align', () => {
+        const columns = [{ index: 'price', header: { align: 'right' } }];
+        const result = EzGridNormalizers.normalizeColumns(columns);
+
+        expect(result[0].header.align).toBe('right');
+    });
+
+    it('should use global headerAlign as fallback', () => {
+        const columns = [{ index: 'name' }];
+        const result = EzGridNormalizers.normalizeColumns(columns, {
+            headerAlign: 'center'
+        });
+
+        expect(result[0].header.align).toBe('center');
+    });
+
+    it('should default to left align', () => {
+        const columns = [{ index: 'name' }];
+        const result = EzGridNormalizers.normalizeColumns(columns);
+
+        expect(result[0].header.align).toBe('left');
+    });
+
+});
+
+// ==========================================================
+// normalizeRowKey
+// ==========================================================
+
+describe('EzGridNormalizers.normalizeRowKey', () => {
+
+    it('should return function as-is', () => {
+        const fn = (row) => row.customId;
+        const result = EzGridNormalizers.normalizeRowKey(fn);
+
+        expect(result).toBe(fn);
+    });
+
+    it('should convert string to accessor function', () => {
+        const result = EzGridNormalizers.normalizeRowKey('userId');
+
+        expect(typeof result).toBe('function');
+        expect(result({ userId: 123 })).toBe(123);
+    });
+
+    it('should default to id field', () => {
+        const result = EzGridNormalizers.normalizeRowKey(undefined);
+
+        expect(typeof result).toBe('function');
+        expect(result({ id: 456 })).toBe(456);
+    });
+
+    it('should handle null row gracefully', () => {
+        const result = EzGridNormalizers.normalizeRowKey('id');
+
+        expect(result(null)).toBe(undefined);
+        expect(result(undefined)).toBe(undefined);
+    });
+
+});

package/components/grid/state/EzGridNormalizers.ts

@@ -0,0 +1,162 @@
+// EzGrid/state/EzGridNormalizers.ts
+
+import type {
+    HeaderAlign,
+    HeaderConfig,
+    ColumnConfig,
+    NormalizedColumn,
+    SelectionMode,
+    RowData,
+    RowKeyFn
+} from '../types.js';
+
+export interface NormalizeColumnsOptions {
+    selectionMode?: SelectionMode;
+    selectionWidth?: number;
+    headerAlign?: HeaderAlign;
+}
+
+// Re-export types for backwards compatibility
+export type {
+    HeaderAlign,
+    HeaderConfig,
+    ColumnConfig,
+    NormalizedColumn
+} from '../types.js';
+
+export type RowKeyFunction = RowKeyFn;
+
+export class EzGridNormalizers {
+
+    // ==========================================================
+    // Header Normalization
+    // ==========================================================
+
+    static normalizeHeader(header: boolean | HeaderConfig | null | undefined): HeaderConfig | false {
+        if (header === false) return false;
+
+        if (header === true || header == null) {
+            return {
+                align: 'left'
+            };
+        }
+
+        if (typeof header === 'object') {
+            return {
+                align: header.align ?? 'left',
+                cls: header.cls,
+                height: header.height,
+                visible: header.visible
+            };
+        }
+
+        return { align: 'left' };
+    }
+
+    // ==========================================================
+    // Columns Normalization
+    // ==========================================================
+
+    static normalizeColumns(columns: ColumnConfig[], options: NormalizeColumnsOptions = {}): NormalizedColumn[] {
+        const { selectionMode, selectionWidth = 36, headerAlign } = options;
+
+        // Filter out manually added selection columns (we'll add it automatically)
+        const filteredColumns = columns.filter(col => col.type !== 'selection');
+
+        const normalizedColumns: NormalizedColumn[] = filteredColumns.map((col, index) => {
+            if (col.type === 'actions') {
+                return {
+                    type: 'actions',
+                    text: '',
+                    flex: 0,
+                    render: null,
+                    sortable: false,
+                    filter: null,
+                    width: col.width ?? 96,
+                    actions: Array.isArray(col.actions) ? col.actions : [],
+                    header: {
+                        align: 'center' as HeaderAlign
+                    },
+                    wrap: false,
+                    resizable: false,
+                    reorderable: false,
+                    summary: null,
+                    _id: `actions-${index}`
+                };
+            }
+
+            // Normalize filter to FilterConfig | null
+            let normalizedFilter: { operator?: string; itemRender?: unknown } | null = null;
+            if (col.filter === true) {
+                normalizedFilter = {};
+            } else if (typeof col.filter === 'string') {
+                normalizedFilter = { operator: col.filter };
+            } else if (col.filter && typeof col.filter === 'object') {
+                normalizedFilter = col.filter;
+            }
+
+            // Normalize summary to SummaryConfig | null
+            let normalizedSummary: { type: 'count' | 'sum' | 'avg' | 'average' | 'min' | 'max' } | null = null;
+            if (typeof col.summary === 'string') {
+                normalizedSummary = { type: col.summary as 'count' | 'sum' | 'avg' | 'average' | 'min' | 'max' };
+            } else if (col.summary && typeof col.summary === 'object') {
+                normalizedSummary = col.summary;
+            }
+
+            return {
+                index: col.index,
+                type: col.type,
+                text: col.text ?? '',
+                flex: col.flex ?? 1,
+                render: typeof col.render === 'function' ? col.render : null,
+                header: {
+                    align: col.header?.align ?? headerAlign ?? 'left'
+                },
+                width: col.width,
+                sortable: col.sort !== false,
+                filter: normalizedFilter,
+                wrap: col.wrap === true ? 3 : (typeof col.wrap === 'number' ? col.wrap : false),
+                resizable: col.resizable !== false,
+                reorderable: col.reorderable !== false,
+                summary: normalizedSummary,
+                _id: col.index || `col-${index}`
+            };
+        });
+
+        // Auto-add selection column for multi mode
+        if (selectionMode === 'multi') {
+            normalizedColumns.unshift({
+                type: 'selection',
+                text: '',
+                flex: 0,
+                render: null,
+                sortable: false,
+                filter: null,
+                width: selectionWidth,
+                header: { align: 'center' },
+                wrap: false,
+                resizable: false,
+                reorderable: false,
+                summary: null,
+                _id: 'selection'
+            });
+        }
+
+        return normalizedColumns;
+    }
+
+    // ==========================================================
+    // RowKey Normalization
+    // ==========================================================
+
+    static normalizeRowKey(rowKey: string | RowKeyFunction | undefined): RowKeyFunction {
+        if (typeof rowKey === 'function') return rowKey;
+
+        if (typeof rowKey === 'string') {
+            return (row: any) => row?.[rowKey];
+        }
+
+        // fallback to 'id' field
+        return (row: any) => row?.id;
+    }
+}

package/components/grid/state/EzGridParts.ts

@@ -0,0 +1,233 @@
+// EzGrid/state/EzGridParts.ts
+
+import type {
+    NormalizedColumn,
+    EzGridController,
+    EzGridSelectionRef,
+    RowData,
+    RowKeyFn,
+    RowCallback,
+    RowContextMenuCallback,
+    TitleBarContext,
+    ToolConfig,
+    EzGridConfig,
+    HeaderConfig,
+    FilterMode,
+    EzGridHeaderRef,
+    EzGridFiltersRef,
+    EzGridBodyRef,
+    EzGridFooterRef,
+    EzGridRemoteRef
+} from '../types.js';
+import type { EzGridSelection } from './EzGridSelection.js';
+
+export interface ComponentConfig {
+    eztype: string;
+    grid?: EzGridPartsRef;
+    _ezAfterRender?: (el: HTMLElement, instance: unknown) => void;
+    [key: string]: unknown;
+}
+
+export interface EzGridPartsRef {
+    config: {
+        titleBar?: (ctx: TitleBarContext) => ComponentConfig | null;
+        title?: string | ((ctx: TitleBarContext) => unknown);
+        tools?: ToolConfig[] | ((ctx: TitleBarContext) => ToolConfig[]);
+        bind?: { data?: string; title?: string };
+        id?: string;
+        controller?: string;
+        overRules?: string;
+        data?: RowData[];
+        rowHeight?: number;
+    };
+    controller: EzGridController | null;
+    header: HeaderConfig | false;
+    selection: EzGridSelection;
+    rowKey: RowKeyFn;
+    headerInstance?: EzGridHeaderRef;
+    _filtersInstance?: EzGridFiltersRef;
+    _bodyInstance?: EzGridBodyRef;
+    _footerInstance?: EzGridFooterRef;
+    _remote?: EzGridRemoteRef;
+    _rowClickHandler?: RowCallback | null;
+    _rowDoubleClickHandler?: RowCallback | null;
+    _rowContextMenuHandler?: RowContextMenuCallback | null;
+    getSelection: () => string[];
+    isSelected: (row: RowData) => boolean;
+    getVisibleColumns: () => NormalizedColumn[];
+    isRemoteMode: () => boolean;
+}
+
+// Re-export for backwards compatibility
+export type { TitleBarContext } from '../types.js';
+
+export class EzGridParts {
+    grid: EzGridPartsRef;
+
+    constructor(grid: EzGridPartsRef) {
+        this.grid = grid;
+    }
+
+    // ==========================================================
+    // Build All Parts
+    // ==========================================================
+
+    build(): ComponentConfig[] {
+        const items: ComponentConfig[] = [];
+
+        items.push(...this._buildTitleBar());
+        items.push(...this._buildHeader());
+        items.push(...this._buildFilters());
+        items.push(...this._buildBody());
+        items.push(...this._buildFooter());
+
+        return items;
+    }
+
+    // ==========================================================
+    // TitleBar
+    // ==========================================================
+
+    private _buildTitleBar(): ComponentConfig[] {
+        const grid = this.grid;
+        const config = grid.config;
+
+        const ctx = {
+            grid: grid as any,
+            controller: grid.controller,
+            selection: {
+                keys: grid.getSelection(),
+                rows: grid.controller?.state?.data?.filter(row =>
+                    grid.isSelected(row)
+                ) ?? [],
+                count: grid.getSelection().length
+            },
+            state: grid.controller?.state ?? null,
+            bind: config.bind ?? null,
+            config: config as any
+        } as TitleBarContext;
+
+        // Full override of titlebar
+        if (typeof config.titleBar === 'function') {
+            const res = config.titleBar(ctx);
+            return res ? [res] : [];
+        }
+
+        // Default titlebar with partial overrides
+        if (config.title || config.tools || config.bind?.title) {
+            return [{
+                eztype: 'EzGridTitleBar',
+                title: config.title,
+                tools: config.tools,
+                bind: config.bind,
+                grid: grid,
+                titleOverride: typeof config.title === 'function'
+                    ? config.title
+                    : null,
+                toolsOverride: typeof config.tools === 'function'
+                    ? config.tools
+                    : null,
+                ctx
+            }];
+        }
+
+        return [];
+    }
+
+    // ==========================================================
+    // Header
+    // ==========================================================
+
+    private _buildHeader(): ComponentConfig[] {
+        const grid = this.grid;
+
+        if (grid.header === false) return [];
+
+        return [{
+            eztype: 'EzGridHeader',
+            header: grid.header,
+            columns: () => grid.getVisibleColumns(),
+            grid: grid,
+            _ezAfterRender: (el: HTMLElement, instance: any) => {
+                grid.headerInstance = instance;
+            }
+        }];
+    }
+
+    // ==========================================================
+    // Filters
+    // ==========================================================
+
+    private _buildFilters(): ComponentConfig[] {
+        const grid = this.grid;
+
+        // Get filter mode from remote config (only applies to remote mode)
+        const filterMode = grid._remote?.config?.filter ?? 'onInput';
+
+        return [{
+            eztype: 'EzGridFilters',
+            grid: grid,
+            columns: () => grid.getVisibleColumns(),
+            filterMode: grid.isRemoteMode() ? filterMode : 'onInput',
+            _ezAfterRender: (el: HTMLElement, instance: any) => {
+                grid._filtersInstance = instance;
+            }
+        }];
+    }
+
+    // ==========================================================
+    // Body
+    // ==========================================================
+
+    private _buildBody(): ComponentConfig[] {
+        const grid = this.grid;
+        const config = grid.config;
+
+        return [{
+            eztype: 'EzGridBody',
+            grid: grid,
+            controller: grid.controller,
+            _ezAfterRender: (el: HTMLElement, instance: any) => {
+                grid._bodyInstance = instance;
+            },
+            overRules: config.overRules,
+            columns: () => grid.getVisibleColumns(),
+            rowKey: grid.rowKey,
+            selection: grid.selection,
+            bind: config.bind,
+            data: config.data,
+            rowHeight: config.rowHeight || null,
+            // Use resolved handlers from listenTo (supports string callbacks)
+            onRowClick: grid._rowClickHandler || null,
+            onRowDoubleClick: grid._rowDoubleClickHandler || null,
+            onRowContextMenu: grid._rowContextMenuHandler || null,
+            flex: 1
+        }];
+    }
+
+    // ==========================================================
+    // Footer
+    // ==========================================================
+
+    private _buildFooter(): ComponentConfig[] {
+        const grid = this.grid;
+
+        return [{
+            eztype: 'EzGridFooter',
+            grid: grid,
+            _ezAfterRender: (el: HTMLElement, instance: any) => {
+                grid._footerInstance = instance;
+            }
+        }];
+    }
+
+    // ==========================================================
+    // Cleanup Config
+    // ==========================================================
+
+    cleanupConfig(): void {
+        delete (this.grid.config as any).title;
+        delete (this.grid.config as any).tools;
+        delete (this.grid.config as any).columns;
+    }
+}