@aquera/ngx-smart-table 0.0.2-alpha

package/lib/renderer/models/table-state.class.d.ts

@@ -0,0 +1,313 @@
+/**
+ * TableState - Reactive state management for table operations
+ * Event-driven architecture: tracks state, emits events, consumer handles async data operations
+ */
+import { Observable } from 'rxjs';
+import { ColumnConfig } from '../../models/column-config.interface';
+import { PaginationState, SortDirection, FilterOperator, TableStateChangeEvent, TableStateSnapshot, CellFocusPosition } from './table-types';
+import { TableStateConfig } from './table-state.interface';
+import { NavigationDirection } from '../../models/cell-types';
+import { TableValidationState } from './table-validation-state.interface';
+/**
+ * TableState class - Column-driven, event-emitting state management
+ * NO data manipulation - only state tracking and event emission
+ */
+export declare class TableState {
+    private _columns;
+    private _pagination$;
+    private _stateChange$;
+    private _initialConfig;
+    private _rowNumberWidth;
+    private _settingsColumnWidth;
+    private _focusedCellPosition$;
+    readonly focusedCellPosition$: Observable<CellFocusPosition | null>;
+    private _editingCellPosition$;
+    readonly editingCellPosition$: Observable<CellFocusPosition | null>;
+    private _tableValidationState$;
+    readonly tableValidationState$: Observable<TableValidationState>;
+    private _rowCount;
+    private _columnCount;
+    /**
+     * Observable of complete state snapshot
+     */
+    readonly state$: Observable<TableStateSnapshot>;
+    /**
+     * Observable of state change events
+     */
+    readonly stateChange$: Observable<TableStateChangeEvent>;
+    /**
+     * Observable of pagination state changes
+     */
+    readonly paginationChange$: Observable<PaginationState>;
+    /**
+     * Constructor
+     * @param columns Reference to columns array
+     * @param config Initial configuration
+     */
+    constructor(columns: ColumnConfig<any>[], config?: TableStateConfig);
+    /**
+     * Get current state snapshot
+     */
+    getState(): TableStateSnapshot;
+    /**
+     * Get current pagination state
+     */
+    getPagination(): PaginationState;
+    /**
+     * Get columns with sorting enabled
+     */
+    getSortedColumns(): ColumnConfig<any>[];
+    /**
+     * Get columns with filtering enabled
+     */
+    getFilteredColumns(): ColumnConfig<any>[];
+    /**
+     * Get current columns reference
+     */
+    getColumns(): ColumnConfig<any>[];
+    /**
+     * Set current page
+     * @param page Page number (0-indexed)
+     */
+    setPage(page: number): void;
+    /**
+     * Set page size
+     * @param size Number of items per page
+     */
+    setPageSize(size: number): void;
+    /**
+     * Set total items (called after API response)
+     * @param total Total number of items
+     */
+    setTotalItems(total: number): void;
+    /**
+     * Go to next page
+     */
+    nextPage(): void;
+    /**
+     * Go to previous page
+     */
+    previousPage(): void;
+    /**
+     * Go to first page
+     */
+    firstPage(): void;
+    /**
+     * Go to last page
+     */
+    lastPage(): void;
+    /**
+     * Check if there is a next page
+     */
+    hasNextPage(): boolean;
+    /**
+     * Check if there is a previous page
+     */
+    hasPreviousPage(): boolean;
+    /**
+     * Set sort on a column (clears other sorts)
+     * @param columnKey Column key
+     * @param direction Sort direction
+     */
+    setSortOnColumn(columnKey: string, direction: SortDirection): void;
+    /**
+     * Add sort to a column (for multi-column sorting)
+     * @param columnKey Column key
+     * @param direction Sort direction
+     */
+    addSortToColumn(columnKey: string, direction: SortDirection): void;
+    /**
+     * Toggle sort on a column (cycles through none -> asc -> desc -> none)
+     * @param columnKey Column key
+     */
+    toggleSortOnColumn(columnKey: string): void;
+    /**
+     * Clear all sorting
+     */
+    clearAllSorting(): void;
+    /**
+     * Get sort configuration for a column
+     * @param columnKey Column key
+     * @returns Sort configuration or null
+     */
+    getSortForColumn(columnKey: string): {
+        direction: SortDirection;
+        enabled: boolean;
+    } | null;
+    /**
+     * Set filter on a column
+     * @param columnKey Column key
+     * @param operator Filter operator
+     * @param value Filter value
+     */
+    setFilterOnColumn(columnKey: string, operator: FilterOperator, value: any): void;
+    /**
+     * Clear filter on a column
+     * @param columnKey Column key
+     */
+    clearFilterOnColumn(columnKey: string): void;
+    /**
+     * Clear all filters
+     */
+    clearAllFilters(): void;
+    /**
+     * Set filter enabled state
+     * @param columnKey Column key
+     * @param enabled Whether filter is enabled
+     */
+    setFilterEnabled(columnKey: string, enabled: boolean): void;
+    /**
+     * Get filter configuration for a column
+     * @param columnKey Column key
+     * @returns Filter configuration or null
+     */
+    getFilterForColumn(columnKey: string): {
+        operator: FilterOperator;
+        value: any;
+        enabled: boolean;
+    } | null;
+    /**
+     * Get sticky columns grouped by position
+     * @returns Object with left and right sticky column keys
+     */
+    getStickyColumns(): {
+        left: string[];
+        right: string[];
+    };
+    /**
+     * Set sticky position for a column
+     * @param columnKey Column key
+     * @param position Sticky position ('left', 'right', or false)
+     */
+    setStickyColumn(columnKey: string, position: 'left' | 'right' | false): void;
+    /**
+     * Calculate sticky offsets for all sticky columns
+     * This calculates cumulative widths for positioning
+     * @param rowNumberWidth Optional width of row number column to account for in left offset
+     * @param settingsColumnWidth Optional width of settings column to account for in right offset
+     */
+    calculateStickyOffsets(rowNumberWidth?: number, settingsColumnWidth?: number): void;
+    /**
+     * Update columns reference
+     * @param columns New columns array
+     */
+    updateColumns(columns: ColumnConfig<any>[]): void;
+    /**
+     * Toggle visibility of a column
+     * @param columnKey Column key
+     */
+    toggleColumnVisibility(columnKey: string): void;
+    /**
+     * Set visibility of a column
+     * @param columnKey Column key
+     * @param visible Whether column should be visible
+     */
+    setColumnVisibility(columnKey: string, visible: boolean): void;
+    /**
+     * Get all visible columns
+     * @returns Array of visible column configs
+     */
+    getVisibleColumns(): ColumnConfig<any>[];
+    /**
+     * Get visibility state for all columns
+     * @returns Array of column visibility info
+     */
+    getAllColumnsVisibility(): {
+        key: string;
+        header: string;
+        visible: boolean;
+        hideable: boolean;
+    }[];
+    /**
+     * Set table dimensions for navigation boundaries
+     */
+    setDimensions(rowCount: number, columnCount: number): void;
+    /**
+     * Focus a cell by position
+     */
+    focusCell(rowIndex: number, columnIndex: number): void;
+    /**
+     * Get currently focused position
+     */
+    getFocusedPosition(): CellFocusPosition | null;
+    /**
+     * Notify that a cell entered edit mode
+     */
+    setEditingCell(rowIndex: number, columnIndex: number): void;
+    /**
+     * Notify that edit mode ended
+     */
+    clearEditingCell(): void;
+    /**
+     * Check if any cell is currently editing
+     */
+    isAnyCellEditing(): boolean;
+    /**
+     * Get currently editing position
+     */
+    getEditingPosition(): CellFocusPosition | null;
+    /**
+     * Move focus in a direction using NavigationDirection enum
+     */
+    moveFocus(direction: NavigationDirection): boolean;
+    /**
+     * Clear focus
+     */
+    clearFocus(): void;
+    /**
+     * Check if navigation is active
+     */
+    isNavigationActive(): boolean;
+    /**
+     * Update cell validation and accumulate into row/table validation state
+     * Only stores invalid states - valid rows are automatically removed
+     */
+    updateCellValidation(rowIndex: number, columnKey: string, isValid: boolean, error?: string): void;
+    /**
+     * Get current table validation state
+     */
+    getTableValidationState(): TableValidationState;
+    /**
+     * Set total rows for validation state tracking
+     */
+    setValidationRowCount(totalRows: number): void;
+    /**
+     * Reset to initial configuration
+     */
+    reset(): void;
+    /**
+     * Reset pagination only
+     */
+    resetPagination(): void;
+    /**
+     * Reset all column sorts
+     */
+    resetAllSorting(): void;
+    /**
+     * Reset all column filters
+     */
+    resetAllFilters(): void;
+    /**
+     * Find a column by key
+     * @param columnKey Column key
+     * @returns Column config or undefined
+     */
+    private findColumn;
+    /**
+     * Calculate total pages
+     * @param totalItems Total number of items
+     * @param pageSize Page size
+     * @returns Total number of pages
+     */
+    private calculateTotalPages;
+    /**
+     * Emit state change event
+     * @param type Type of change
+     */
+    private emitStateChange;
+    /**
+     * Build state snapshot from current state
+     * @returns State snapshot
+     */
+    private buildStateSnapshot;
+}

package/lib/renderer/models/table-state.interface.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Table state interfaces for configuration and initialization
+ */
+/**
+ * Configuration options for initializing TableState
+ */
+export interface TableStateConfig {
+    /**
+     * Initial page number (0-indexed)
+     * @default 0
+     */
+    initialPage?: number;
+    /**
+     * Number of items per page
+     * @default 25
+     */
+    pageSize?: number;
+}

package/lib/renderer/models/table-types.d.ts

@@ -0,0 +1,228 @@
+/**
+ * Table types and enumerations for state management
+ */
+import type { ColumnConfig } from '../../models/column-config.interface';
+/**
+ * Sort direction for columns
+ */
+export declare enum SortDirection {
+    NONE = "none",
+    ASC = "asc",
+    DESC = "desc"
+}
+/**
+ * Filter operators for column filtering
+ */
+export declare enum FilterOperator {
+    EQUALS = "equals",
+    CONTAINS = "contains",
+    STARTS_WITH = "startsWith",
+    ENDS_WITH = "endsWith",
+    GT = "gt",
+    LT = "lt",
+    GTE = "gte",
+    LTE = "lte",
+    BETWEEN = "between",
+    IN = "in"
+}
+/**
+ * Pagination state for table
+ */
+export interface PaginationState {
+    currentPage: number;
+    pageSize: number;
+    totalItems: number;
+    totalPages: number;
+}
+/**
+ * Sort state for a column
+ * Contains full information about an active sort operation
+ */
+export interface ColumnSortState {
+    columnKey: string;
+    direction: SortDirection;
+    priority?: number;
+}
+/**
+ * Filter state for a column
+ * Contains full information about an active filter operation
+ */
+export interface ColumnFilterState {
+    columnKey: string;
+    operator: FilterOperator;
+    value: any;
+    enabled: boolean;
+}
+/**
+ * Cell focus position for keyboard navigation
+ */
+export interface CellFocusPosition {
+    rowIndex: number;
+    columnIndex: number;
+}
+/**
+ * Table state change event
+ */
+export interface TableStateChangeEvent {
+    type: 'pagination' | 'sorting' | 'filtering' | 'column-config' | 'column-visibility' | 'cell-focus' | 'cell-edit-start' | 'cell-edit-end';
+    state: TableStateSnapshot;
+    focusPosition?: CellFocusPosition;
+    editingPosition?: CellFocusPosition;
+}
+/**
+ * Snapshot of current table state
+ * Contains complete state information for sorting, filtering, and pagination
+ */
+export interface TableStateSnapshot {
+    pagination: PaginationState;
+    sortedColumns: ColumnSortState[];
+    filteredColumns: ColumnFilterState[];
+}
+/**
+ * Column resize event
+ * Emitted when a column is resized by the user
+ */
+export interface ColumnResizeEvent {
+    /**
+     * Key of the resized column
+     */
+    columnKey: string;
+    /**
+     * Previous width before resize
+     */
+    oldWidth: number;
+    /**
+     * New width after resize
+     */
+    newWidth: number;
+    /**
+     * The column configuration
+     */
+    column: ColumnConfig;
+}
+/**
+ * Column sort toggle event
+ * Emitted when a column's sort direction is changed
+ */
+export interface ColumnSortEvent {
+    /**
+     * Key of the sorted column
+     */
+    columnKey: string;
+    /**
+     * New sort direction
+     */
+    direction: SortDirection;
+    /**
+     * Previous sort direction
+     */
+    previousDirection: SortDirection;
+    /**
+     * The column configuration
+     */
+    column: ColumnConfig;
+    /**
+     * Current table state snapshot
+     */
+    tableState: TableStateSnapshot;
+}
+/**
+ * Column filter change event
+ * Emitted when a column filter is modified
+ */
+export interface ColumnFilterEvent {
+    /**
+     * Key of the filtered column
+     */
+    columnKey: string;
+    /**
+     * Filter operator
+     */
+    operator: FilterOperator;
+    /**
+     * Filter value
+     */
+    value: any;
+    /**
+     * Previous filter value
+     */
+    previousValue?: any;
+    /**
+     * Whether filter is enabled
+     */
+    enabled: boolean;
+    /**
+     * The column configuration
+     */
+    column: ColumnConfig;
+    /**
+     * Current table state snapshot
+     */
+    tableState: TableStateSnapshot;
+}
+/**
+ * Column moved event
+ * Emitted when a column is reordered
+ */
+export interface ColumnMoveEvent {
+    /**
+     * Key of the moved column
+     */
+    columnKey: string;
+    /**
+     * Direction of movement
+     */
+    direction: 'left' | 'right';
+    /**
+     * Original column index
+     */
+    oldIndex: number;
+    /**
+     * New column index after move
+     */
+    newIndex: number;
+    /**
+     * The column configuration
+     */
+    column: ColumnConfig;
+}
+/**
+ * Column added event
+ * Emitted when a new column is added to the table
+ */
+export interface ColumnAddEvent {
+    /**
+     * The newly added column configuration
+     */
+    column: ColumnConfig;
+    /**
+     * Index where column was added
+     */
+    index: number;
+    /**
+     * Total number of columns after addition
+     */
+    totalColumns: number;
+}
+/**
+ * Data change event
+ * Emitted when table data is updated (via sync or async input)
+ */
+export interface DataChangeEvent {
+    /**
+     * Previous data array reference
+     */
+    previousData: any[];
+    /**
+     * Current data array reference
+     */
+    currentData: any[];
+    /**
+     * Timestamp when change occurred
+     */
+    timestamp: number;
+    /**
+     * Source of the data change
+     */
+    source: 'sync' | 'async';
+}

package/lib/renderer/models/table-validation-state.interface.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Table validation state interface
+ * Aggregates validation results from all rows in the table
+ * Note: Only invalid rows are stored in rowStates - absence means row is valid
+ */
+import { RowValidationState } from './row-validation-state.interface';
+export interface TableValidationState {
+    /**
+     * Whether all rows in the table are valid
+     * True when rowStates is empty (no invalid rows)
+     */
+    isValid: boolean;
+    /**
+     * Total number of rows in the table
+     */
+    totalRows: number;
+    /**
+     * Number of valid rows (calculated as totalRows - invalidRows)
+     */
+    validRows: number;
+    /**
+     * Number of invalid rows (size of rowStates map)
+     */
+    invalidRows: number;
+    /**
+     * Map of row indices to their validation states
+     * Only contains INVALID rows - if a row is not in this map, it's valid
+     */
+    rowStates: Map<number, RowValidationState>;
+    /**
+     * Timestamp of the last validation state update
+     */
+    lastUpdated: Date;
+}

package/lib/renderer/models/workbook-state.class.d.ts

@@ -0,0 +1,117 @@
+/**
+ * WorkbookState - Reactive state management for workbook operations
+ * Manages multiple sheet states and workbook-level state
+ */
+import { BehaviorSubject, Observable } from 'rxjs';
+import { TableState } from './table-state.class';
+import { WorkbookStateConfig, WorkbookMetadata, WorkbookStateSnapshot } from './workbook-state.interface';
+import { ColumnConfig } from '../../models/column-config.interface';
+import { TableStateConfig } from './table-state.interface';
+/**
+ * WorkbookState class - Manages workbook-level state and sheet TableStates
+ */
+export declare class WorkbookState {
+    /**
+     * Workbook identity
+     */
+    readonly id: string;
+    /**
+     * Observable workbook name
+     */
+    readonly name$: BehaviorSubject<string>;
+    /**
+     * Map of TableState instances (one per sheet)
+     * Key: sheetId, Value: TableState
+     */
+    private _sheetTableStates;
+    /**
+     * Active sheet tracking
+     */
+    private _activeSheetIndex$;
+    readonly activeSheetIndex$: Observable<number>;
+    /**
+     * Fullscreen state
+     */
+    private _isFullscreen$;
+    readonly isFullscreen$: Observable<boolean>;
+    /**
+     * Workbook metadata
+     */
+    private _metadata$;
+    readonly metadata$: Observable<WorkbookMetadata>;
+    /**
+     * Constructor
+     * @param config Workbook state configuration
+     */
+    constructor(config: WorkbookStateConfig);
+    /**
+     * Get or create TableState for a sheet
+     * @param sheetId Sheet ID
+     * @param columns Column configurations for the sheet
+     * @param tableStateConfig Optional table state configuration
+     * @returns TableState instance for the sheet
+     */
+    getSheetTableState(sheetId: string, columns: ColumnConfig<any>[], tableStateConfig?: TableStateConfig): TableState;
+    /**
+     * Set TableState for a sheet (useful for lazy initialization)
+     * @param sheetId Sheet ID
+     * @param tableState TableState instance to set
+     */
+    setSheetTableState(sheetId: string, tableState: TableState): void;
+    /**
+     * Remove TableState for a sheet
+     * @param sheetId Sheet ID to remove
+     */
+    removeSheetTableState(sheetId: string): void;
+    /**
+     * Set active sheet index
+     * @param index Sheet index (0-based)
+     */
+    setActiveSheetIndex(index: number): void;
+    /**
+     * Get current active sheet index
+     */
+    getActiveSheetIndex(): number;
+    /**
+     * Toggle fullscreen mode
+     */
+    toggleFullscreen(): void;
+    /**
+     * Set fullscreen mode
+     * @param fullscreen Fullscreen state
+     */
+    setFullscreen(fullscreen: boolean): void;
+    /**
+     * Get current fullscreen state
+     */
+    isFullscreen(): boolean;
+    /**
+     * Update workbook name
+     * @param name New workbook name
+     */
+    updateName(name: string): void;
+    /**
+     * Get current workbook name
+     */
+    getName(): string;
+    /**
+     * Get complete state snapshot
+     */
+    getSnapshot(): WorkbookStateSnapshot;
+    /**
+     * Update last accessed timestamp
+     */
+    private updateLastAccessed;
+    /**
+     * Update last modified timestamp
+     */
+    private updateLastModified;
+    /**
+     * Update sheet count in metadata
+     */
+    private updateSheetCount;
+    /**
+     * Get current metadata
+     */
+    getMetadata(): WorkbookMetadata;
+}