ezfw-core 1.0.0

package/components/grid/types.ts

@@ -0,0 +1,607 @@
+// ==========================================================
+// EzGrid Type Definitions
+// ==========================================================
+// Central type definitions for the EzGrid component system.
+// All grid-related types should be defined or re-exported here.
+// ==========================================================
+
+// ==========================================================
+// Basic Types
+// ==========================================================
+
+export type SortDirection = 'ASC' | 'DESC';
+export type SelectionMode = 'single' | 'multi';
+export type DataMode = 'local' | 'remote';
+export type HeaderAlign = 'left' | 'center' | 'right';
+export type FilterMode = 'onInput' | 'onEnter';
+
+// ==========================================================
+// Row & Data Types
+// ==========================================================
+
+/** Generic row data - can be any object */
+export type RowData = Record<string, unknown>;
+
+/** Function to extract row key from row data */
+export type RowKeyFn = (row: RowData) => string | number;
+
+/** Context passed to row click callbacks */
+export interface RowClickContext {
+    rowKey: string | number | null;
+    index?: number;
+    grid?: EzGridRef;
+}
+
+/** Context passed to row context menu callbacks */
+export interface RowContextMenuContext {
+    rowKey: string | number | null;
+    grid?: EzGridRef;
+}
+
+/** Callback for row click events */
+export type RowCallback = (row: RowData, ctx: RowClickContext) => void;
+
+/** Callback for row context menu */
+export type RowContextMenuCallback = (row: RowData, ctx: RowContextMenuContext) => void;
+
+// ==========================================================
+// Column Types
+// ==========================================================
+
+/** Column render function */
+export type ColumnRenderFn = (value: unknown, row: RowData, cell: HTMLElement) => unknown;
+
+/** Column configuration as provided by user */
+export interface ColumnConfig {
+    index?: string;
+    type?: 'selection' | 'actions' | string;
+    text?: string;
+    flex?: number;
+    width?: number;
+    render?: ColumnRenderFn;
+    header?: {
+        align?: HeaderAlign;
+    };
+    sort?: boolean;
+    filter?: boolean | string | FilterConfig;
+    actions?: ActionConfig[];
+    wrap?: boolean | number;
+    resizable?: boolean;
+    reorderable?: boolean;
+    summary?: string | SummaryConfig;
+}
+
+/** Normalized column after processing */
+export interface NormalizedColumn {
+    _id: string;
+    index?: string;
+    type?: string;
+    text: string;
+    flex: number | null;
+    width?: number;
+    render: ColumnRenderFn | null;
+    header: {
+        align: HeaderAlign;
+    };
+    sortable: boolean;
+    filter: FilterConfig | null;
+    actions?: ActionConfig[];
+    wrap: number | false;
+    resizable: boolean;
+    reorderable: boolean;
+    summary: SummaryConfig | null;
+}
+
+/** Action button configuration */
+export interface ActionConfig {
+    icon?: string;
+    tooltip?: string;
+    danger?: boolean;
+    onClick?: (row: RowData, cell: unknown) => void;
+    eztype?: string;
+    [key: string]: unknown;
+}
+
+/** Summary configuration */
+export interface SummaryConfig {
+    type: 'count' | 'sum' | 'avg' | 'average' | 'min' | 'max';
+}
+
+// ==========================================================
+// Filter Types
+// ==========================================================
+
+export interface FilterConfig {
+    operator?: string;
+    itemRender?: unknown;
+}
+
+export interface FilterCondition {
+    field: string;
+    operator: string;
+    value: unknown;
+}
+
+export interface FilterSnapshot {
+    field: string;
+    operator: string;
+    value: unknown;
+}
+
+// ==========================================================
+// Sort Types
+// ==========================================================
+
+export interface Sorter {
+    property: string;
+    direction: SortDirection;
+}
+
+export interface SortConfig {
+    property: string;
+    direction?: SortDirection | string;
+}
+
+export interface SortSnapshot {
+    property: string;
+    direction: SortDirection;
+}
+
+// ==========================================================
+// Selection Types
+// ==========================================================
+
+export interface SelectionConfig {
+    mode?: SelectionMode;
+    toggle?: boolean;
+    selected?: (string | number)[];
+    width?: number;
+}
+
+export interface SelectionSnapshot {
+    mode: SelectionMode;
+    selected: string[];
+    lastIndex: number | null;
+}
+
+// ==========================================================
+// Header Types
+// ==========================================================
+
+export interface HeaderConfig {
+    align?: HeaderAlign;
+    cls?: string;
+    height?: number;
+    visible?: boolean;
+}
+
+// ==========================================================
+// Controller Types
+// ==========================================================
+
+export interface EzGridControllerState {
+    data: RowData[];
+    loading: boolean;
+    error: Error | null;
+    page: number;
+    pageSize: number;
+    total: number;
+    mode: DataMode;
+}
+
+export interface TransportParams {
+    page: number;
+    pageSize: number;
+    sort: SortSnapshot | null;
+    filters: FilterSnapshot[] | null;
+    [key: string]: unknown;
+}
+
+export interface TransportResult {
+    data: RowData[];
+    total?: number;
+}
+
+export type TransportFn = (params: TransportParams) => Promise<TransportResult>;
+
+export interface RemoteConfig {
+    transport: TransportFn | null;
+    autoLoad: boolean;
+    pageSize: number;
+}
+
+export interface EzGridModel {
+    primaryKey?: string;
+    process(record: RowData): RowData;
+    processAll(records: RowData[]): RowData[];
+}
+
+// ==========================================================
+// Remote Config Types
+// ==========================================================
+
+export interface RemoteApiConfig {
+    read?: string;
+    create?: string;
+    update?: string;
+    delete?: string;
+}
+
+export interface RemoteSourceConfig {
+    dataPath?: string;
+    countPath?: string;
+}
+
+export interface RemoteListenTo {
+    beforeLoad?: ((params: TransportParams, ctx: BeforeLoadContext) => TransportParams | void) | string;
+    afterLoad?: ((result: TransportResult, ctx: AfterLoadContext) => TransportResult | void) | string;
+    onError?: ((error: Error, ctx: ErrorContext) => void) | string;
+}
+
+export interface RemoteConfigInput {
+    api: string | RemoteApiConfig;
+    source?: RemoteSourceConfig;
+    filter?: FilterMode;
+    listenTo?: RemoteListenTo;
+}
+
+export interface BeforeLoadContext {
+    grid: EzGridRef;
+    remote: unknown;
+}
+
+export interface AfterLoadContext {
+    grid: EzGridRef;
+    remote: unknown;
+    params: TransportParams;
+    response: unknown;
+}
+
+export interface ErrorContext {
+    grid: EzGridRef;
+    remote: unknown;
+    params: TransportParams;
+}
+
+// ==========================================================
+// Persistence Types
+// ==========================================================
+
+export interface ColumnsSnapshot {
+    visibility: Record<string, boolean>;
+    order: string[] | null;
+    widths: Record<string, number>;
+}
+
+export interface GridStateSnapshot {
+    columnState: ColumnsSnapshot | null;
+    sortState: Sorter[] | null;
+    selectionState: SelectionSnapshot | null;
+}
+
+// ==========================================================
+// Event Types
+// ==========================================================
+
+export type EventCallback = (payload?: unknown) => void;
+
+export interface SelectionChangeEvent {
+    keys: string[];
+    rows: RowData[];
+    count: number;
+}
+
+// ==========================================================
+// TitleBar Types
+// ==========================================================
+
+export interface TitleBarContext {
+    grid: EzGridRef;
+    controller: EzGridController | null;
+    selection: {
+        keys: string[];
+        rows: RowData[];
+        count: number;
+    };
+    state: EzGridControllerState | null;
+    bind: unknown;
+    config: EzGridConfig;
+}
+
+export interface ToolConfig {
+    requiresSelection?: boolean;
+    minSelection?: number;
+    onClick?: (grid: EzGridRef) => void;
+    eztype?: string;
+    [key: string]: unknown;
+}
+
+// ==========================================================
+// Grid Config Types
+// ==========================================================
+
+export interface EzGridConfig {
+    id?: string;
+    columns?: ColumnConfig[];
+    data?: RowData[];
+    bind?: { data?: string; title?: string };
+    selection?: boolean | SelectionConfig;
+    header?: boolean | HeaderConfig;
+    sort?: SortConfig | SortConfig[];
+    variant?: 'elevated' | 'flat' | 'outlined' | string;
+    stateful?: boolean;
+    statefulPersist?: boolean;
+    rowKey?: string | RowKeyFn;
+    controller?: string;
+    model?: string;
+    remote?: RemoteConfigInput;
+    store?: unknown;
+    autoLoad?: boolean;
+    pageSize?: number;
+    overRules?: string;
+    listenTo?: {
+        onRowClick?: RowCallback | string;
+        onRowDoubleClick?: RowCallback | string;
+        onRowContextMenu?: RowContextMenuCallback | string;
+    };
+    onRowClick?: RowCallback | string;
+    onRowDoubleClick?: RowCallback | string;
+    onRowContextMenu?: RowContextMenuCallback | string;
+    cls?: string | string[];
+    layout?: 'vbox' | 'hbox';
+    flex?: number;
+    init?: (grid: EzGridRef) => void;
+    skipInit?: boolean;
+    title?: string | ((ctx: TitleBarContext) => unknown);
+    tools?: ToolConfig[] | ((ctx: TitleBarContext) => ToolConfig[]);
+    titleBar?: (ctx: TitleBarContext) => unknown;
+    showSelectionCount?: boolean;
+    rowHeight?: number;
+    emptyText?: string;
+    [key: string]: unknown;
+}
+
+// ==========================================================
+// Grid Reference Types (for cross-module communication)
+// ==========================================================
+
+/** Main grid reference interface */
+export interface EzGridRef {
+    el?: HTMLElement | null;
+    config: EzGridConfig;
+    controller: EzGridController | null;
+    selection: EzGridSelectionRef;
+    columns: NormalizedColumn[];
+    header: HeaderConfig | false;
+    rowKey: RowKeyFn;
+    stateful?: boolean;
+    statefulPersist?: boolean;
+
+    // Instances
+    headerInstance?: EzGridHeaderRef;
+    _bodyInstance?: EzGridBodyRef;
+    _footerInstance?: EzGridFooterRef;
+    _filtersInstance?: EzGridFiltersRef;
+
+    // Internal state
+    _lifecycle?: EzGridLifecycleRef;
+    _persistence?: EzGridPersistenceRef;
+    _remote?: EzGridRemoteRef;
+    _context?: { route?: string; view?: string };
+    _localSortBaseline?: RowData[] | null;
+    _hasLocalSortBaseline?: boolean;
+    _rowClickHandler?: RowCallback | null;
+    _rowDoubleClickHandler?: RowCallback | null;
+    _rowContextMenuHandler?: RowContextMenuCallback | null;
+
+    // Callbacks
+    _onLoadingChanged?: (loading: boolean) => void;
+    _onError?: (error: Error | null) => void;
+    _onColumnsChanged: () => void;
+    _onSelectionChanged: () => void;
+    _onFiltersChanged?: (snapshot: FilterSnapshot[] | null) => void;
+
+    // Public methods
+    getSelection: () => string[];
+    isSelected: (row: RowData) => boolean;
+    isAllSelected: () => boolean;
+    selectAll: () => void;
+    clearSelection: () => void;
+    toggleRow: (row: RowData, index: number) => void;
+    selectRange: (toIndex: number) => void;
+    getVisibleColumns: () => NormalizedColumn[];
+    isRemoteMode: () => boolean;
+    isColumnSorted?: (colId: string) => boolean;
+    getColumnSortDirection?: (colId: string) => SortDirection | null;
+    toggleSort?: (colId: string) => void;
+    setColumnWidth?: (colId: string, width: number) => void;
+    moveColumn?: (colId: string, toIndex: number) => void;
+    refreshBody: () => Promise<void>;
+    on: (event: string, callback: EventCallback) => void;
+    off: (event: string, callback: EventCallback) => void;
+    emit: (event: string, payload?: unknown) => void;
+}
+
+// ==========================================================
+// Controller Interface
+// ==========================================================
+
+export interface EzGridController {
+    grid: EzGridRef;
+    state: EzGridControllerState;
+    _model?: EzGridModel;
+    _remoteConfig?: RemoteConfig;
+    _isLoadingRemote: boolean;
+    _pendingRemoteReload: boolean;
+    _lastSortSnapshot: SortSnapshot | null;
+    _lastFilterSnapshot: FilterSnapshot[] | null;
+
+    // Event methods
+    on: (event: string, fn: EventCallback) => void;
+    off: (event: string, fn: EventCallback) => void;
+    emit: (event: string, payload?: unknown) => void;
+
+    // State methods
+    load: (params?: Partial<TransportParams>) => Promise<void>;
+    reload: () => Promise<void>;
+    requestReload: (reason?: string) => Promise<void>;
+    setPage: (page: number) => void;
+    setPageSize: (size: number) => void;
+    setSortSnapshot: (snapshot: SortSnapshot | null) => void;
+    setFilterSnapshot: (snapshot: FilterSnapshot[] | null) => void;
+    setData: (data: RowData[], meta?: { total?: number }) => void;
+    setLoading: (value: boolean) => void;
+    setError: (error: Error | null) => void;
+    setRemoteConfig: (config: Partial<RemoteConfig & { transport?: TransportFn }>) => void;
+    appendData: (data: RowData[]) => void;
+    clear: () => void;
+    addRecord: (record: RowData) => void;
+    updateRecord: (key: unknown, updates: Partial<RowData>) => boolean;
+    removeRecord: (key: unknown) => boolean;
+
+    // Hooks for controller
+    beforeRowRender?: (row: RowData, ctx: RowRenderContext) => boolean | void;
+    afterRowRender?: (el: HTMLElement, row: RowData, ctx: RowRenderContext) => void;
+    beforeCellRender?: (value: unknown, row: RowData, column: NormalizedColumn, ctx: RowRenderContext) => boolean | void;
+    afterCellRender?: (el: HTMLElement, value: unknown, row: RowData, column: NormalizedColumn, ctx: RowRenderContext) => void;
+
+    // Remote support
+    supportsRemoteSort?: boolean;
+    sort?: (columnId: string, direction: SortDirection) => void;
+}
+
+export interface RowRenderContext {
+    index: number;
+    row: RowData;
+    rowId: string | number | null;
+    columns: NormalizedColumn[];
+    grid: EzGridRef;
+    rowEl: HTMLElement | null;
+    isFirst: boolean;
+    isLast: boolean;
+}
+
+// ==========================================================
+// Sub-component Reference Interfaces
+// ==========================================================
+
+export interface EzGridSelectionRef {
+    enabled: boolean;
+    mode: SelectionMode;
+    toggle: boolean;
+    selected: Set<string>;
+    lastIndex: number | null;
+    isEnabled: () => boolean;
+    isSelected: (row: RowData) => boolean;
+    getSelection: () => string[];
+    clear: () => void;
+    toggleRow: (row: RowData, index: number) => void;
+    selectRange: (toIndex: number) => void;
+    selectAll: () => void;
+    isAllSelected: () => boolean;
+    snapshot: () => SelectionSnapshot | null;
+    restore: (snapshot: SelectionSnapshot | null) => void;
+}
+
+export interface EzGridColumnsRef {
+    columns: NormalizedColumn[];
+    state: {
+        visibility: Record<string, boolean>;
+        order: string[] | null;
+        widths: Record<string, number>;
+    };
+    getVisibleColumns: () => NormalizedColumn[];
+    hide: (colId: string) => void;
+    show: (colId: string) => void;
+    toggle: (colId: string) => void;
+    setWidth: (colId: string, width: number) => void;
+    resetWidth: (colId: string) => void;
+    move: (colId: string, toIndex: number) => void;
+    snapshot: () => ColumnsSnapshot;
+    restore: (snapshot: ColumnsSnapshot | null) => void;
+}
+
+export interface EzGridSortRef {
+    sorters: Sorter[];
+    getSorters: () => Sorter[];
+    getSorterFor: (property: string) => Sorter | null;
+    isSorted: (property: string) => boolean;
+    toggleSort: (property: string) => void;
+    clear: () => void;
+    sortBy: (colId: string, direction?: SortDirection) => void;
+    snapshot: () => Sorter[] | null;
+    restore: (snapshot: Sorter[] | null) => void;
+    getSortSnapshot: () => SortSnapshot | null;
+    applyLocalSort: () => void;
+}
+
+export interface EzGridLifecycleRef {
+    onControllerDataChange: () => void;
+    markHydrated: () => void;
+    suspend: <T>(fn: () => Promise<T>) => Promise<void>;
+    destroy: () => void;
+    onLoadingChanged: (loading: boolean) => void;
+    onError: (error: Error | null) => void;
+}
+
+export interface EzGridPersistenceRef {
+    getStateKey: () => string;
+    getStorageKey: () => string;
+    load: () => GridStateSnapshot | null;
+    save: () => void;
+    getRegistryEntry: () => unknown;
+    setRegistryEntry: (controller: unknown) => void;
+    hasRegistryEntry: () => boolean;
+    updateColumnState: (snapshot: ColumnsSnapshot | null) => void;
+    updateSortState: (snapshot: Sorter[] | null) => void;
+    updateSelectionState: (snapshot: SelectionSnapshot | null) => void;
+}
+
+export interface EzGridRemoteRef {
+    config: {
+        api: RemoteApiConfig;
+        source: { dataPath: string; countPath: string };
+        filter: FilterMode;
+        listenTo: RemoteListenTo;
+    } | null;
+    isEnabled: () => boolean;
+    load: (params?: Partial<TransportParams>) => Promise<TransportResult>;
+}
+
+export interface EzGridHeaderRef {
+    refreshColumns: () => Promise<void>;
+}
+
+export interface EzGridBodyRef {
+    data: RowData[];
+    setLoading: (loading: boolean) => void;
+    setError: (error: Error | null) => void;
+    updateSelectionVisuals: () => void;
+    refreshData: (data: RowData[]) => Promise<void>;
+}
+
+export interface EzGridFooterRef {
+    refresh: () => void;
+}
+
+export interface EzGridFiltersRef {
+    clear: () => void;
+    refresh: () => void;
+}
+
+// ==========================================================
+// Export Options
+// ==========================================================
+
+export interface ExportCSVOptions {
+    filename?: string;
+    includeHeaders?: boolean;
+    separator?: string;
+    selectedOnly?: boolean;
+}
+
+export interface ExportExcelOptions {
+    filename?: string;
+    includeHeaders?: boolean;
+    selectedOnly?: boolean;
+}