tablero 1.0.0

package/dist/core.d.ts

@@ -0,0 +1,447 @@
+/**
+ * Sorting functionality
+ *
+ * Single-column sorting implementation, extensible to multi-column sorting.
+ */
+/**
+ * Sort direction type
+ */
+type SortDirection = 'asc' | 'desc' | null;
+/**
+ * Sort state for single-column sorting
+ *
+ * TODO: Extend to multi-column sorting:
+ * - Change to: sorting: Array<{ columnId: string; direction: 'asc' | 'desc' }>
+ * - Add priority/order for multi-sort
+ */
+interface SortState {
+    /** Column ID to sort by, null if no sorting */
+    columnId: string | null;
+    /** Sort direction, null if no sorting */
+    direction: SortDirection;
+}
+/**
+ * Create initial sort state
+ */
+declare function createInitialSortState(): SortState;
+/**
+ * Toggle sort state for a column
+ * Cycles through: none -> asc -> desc -> none
+ */
+declare function toggleSort(currentState: SortState, columnId: string): SortState;
+/**
+ * Set sort state explicitly
+ */
+declare function setSort(columnId: string | null, direction: SortDirection): SortState;
+/**
+ * Clear sort state
+ */
+declare function clearSort(): SortState;
+/**
+ * Type guard to check if sorting is active
+ */
+declare function isSortActive(state: SortState): boolean;
+/**
+ * Value comparator function type
+ */
+type CompareFn<T = unknown> = (a: T, b: T) => number;
+/**
+ * Default comparator for primitive values
+ */
+declare function defaultCompare(a: unknown, b: unknown): number;
+/**
+ * Create a sorted comparator function
+ */
+declare function createComparator<T>(direction: 'asc' | 'desc', compareFn?: CompareFn<T>): CompareFn<T>;
+/**
+ * Sort data array based on sort state
+ *
+ * @param data - Array of data items
+ * @param sortState - Current sort state
+ * @param getValue - Function to extract value from data item for the sorted column
+ * @param compareFn - Optional custom comparator function
+ * @returns New sorted array (immutable)
+ */
+declare function applySort<T>(data: T[], sortState: SortState, getValue: (item: T, columnId: string) => unknown, compareFn?: CompareFn<unknown>): T[];
+
+/**
+ * Pagination functionality
+ *
+ * Client-side pagination implementation.
+ */
+/**
+ * Pagination state
+ */
+interface PaginationState {
+    /** Current page index (0-based) */
+    pageIndex: number;
+    /** Number of items per page */
+    pageSize: number;
+}
+/**
+ * Create initial pagination state
+ */
+declare function createInitialPaginationState(pageSize?: number): PaginationState;
+/**
+ * Calculate total number of pages
+ */
+declare function getPageCount(totalItems: number, pageSize: number): number;
+/**
+ * Get the start index of the current page
+ */
+declare function getPageStartIndex(pageIndex: number, pageSize: number): number;
+/**
+ * Get the end index of the current page (exclusive)
+ */
+declare function getPageEndIndex(pageIndex: number, pageSize: number, totalItems: number): number;
+/**
+ * Check if page index is valid
+ */
+declare function isValidPageIndex(pageIndex: number, totalPages: number): boolean;
+/**
+ * Clamp page index to valid range
+ */
+declare function clampPageIndex(pageIndex: number, totalPages: number): number;
+/**
+ * Go to next page
+ */
+declare function goToNextPage(state: PaginationState, totalPages: number): PaginationState;
+/**
+ * Go to previous page
+ */
+declare function goToPreviousPage(state: PaginationState, totalPages: number): PaginationState;
+/**
+ * Go to specific page
+ */
+declare function goToPage(state: PaginationState, pageIndex: number, totalPages: number): PaginationState;
+/**
+ * Change page size
+ */
+declare function setPageSize(state: PaginationState, pageSize: number, totalItems: number): PaginationState;
+/**
+ * Get paginated slice of data
+ *
+ * @param data - Full data array
+ * @param pagination - Pagination state
+ * @returns Paginated data slice
+ */
+declare function getPaginatedData<T>(data: T[], pagination: PaginationState): T[];
+/**
+ * Check if there is a next page
+ */
+declare function hasNextPage(pageIndex: number, totalPages: number): boolean;
+/**
+ * Check if there is a previous page
+ */
+declare function hasPreviousPage(pageIndex: number): boolean;
+
+/**
+ * Filtering functionality
+ *
+ * Basic text filtering implementation, extensible to advanced filtering.
+ */
+/**
+ * Filter state
+ *
+ * TODO: Extend to support:
+ * - Advanced filter types (number range, date range, etc.)
+ * - Filter operators (equals, contains, greater than, etc.)
+ * - Column-specific filter configurations
+ */
+interface FilterState {
+    /** Global text filter applied across all columns */
+    globalFilter: string;
+    /** Column-specific filters - maps column ID to filter value */
+    columnFilters: Record<string, string>;
+}
+/**
+ * Create initial filter state
+ */
+declare function createInitialFilterState(): FilterState;
+/**
+ * Set global filter
+ */
+declare function setGlobalFilter(filter: string): FilterState;
+/**
+ * Set column filter
+ */
+declare function setColumnFilter(state: FilterState, columnId: string, filter: string): FilterState;
+/**
+ * Clear column filter
+ */
+declare function clearColumnFilter(state: FilterState, columnId: string): FilterState;
+/**
+ * Clear all filters
+ */
+declare function clearAllFilters(): FilterState;
+/**
+ * Check if any filter is active
+ */
+declare function isFilterActive(state: FilterState): boolean;
+/**
+ * Value matcher function type
+ */
+type MatchFn = (value: unknown, filter: string) => boolean;
+/**
+ * Default text matcher - case-insensitive substring match
+ */
+declare function defaultMatch(value: unknown, filter: string): boolean;
+/**
+ * Apply filters to data array
+ *
+ * @param data - Array of data items
+ * @param filterState - Current filter state
+ * @param getValue - Function to extract value from data item for a column
+ * @param matchFn - Optional custom matcher function
+ * @returns Filtered data array (immutable)
+ */
+declare function applyFilters<T>(data: T[], filterState: FilterState, getValue: (item: T, columnId: string) => unknown, matchFn?: MatchFn): T[];
+/**
+ * Get active filter count
+ */
+declare function getActiveFilterCount(state: FilterState): number;
+
+/**
+ * Table state management
+ *
+ * Core state shape and management utilities for data tables.
+ * Supports both controlled and uncontrolled state patterns.
+ */
+
+/**
+ * Core table state interface
+ *
+ * Designed to be extensible for:
+ * - Server-side mode (via mode: 'server' | 'client')
+ * - Multi-sort (sorting can be extended to array)
+ * - URL sync (state can be serialized/deserialized)
+ */
+interface TableState {
+    /** Sorting state - single column for now, extensible to array for multi-sort */
+    sorting: SortState;
+    /** Pagination state */
+    pagination: PaginationState;
+    /** Filtering state */
+    filtering: FilterState;
+    /** Column visibility state - maps column ID to visibility */
+    columnVisibility: Record<string, boolean>;
+    /** Column order - array of column IDs */
+    columnOrder: string[];
+}
+/**
+ * Initial table state with defaults
+ */
+declare function createInitialTableState(columnIds: string[]): TableState;
+/**
+ * Update table state immutably
+ * Returns a new state object with the update applied
+ */
+declare function updateTableState<T extends TableState>(state: T, updates: Partial<TableState>): T;
+/**
+ * Update sorting state
+ */
+declare function updateSorting(state: TableState, sorting: SortState): TableState;
+/**
+ * Update pagination state
+ */
+declare function updatePagination(state: TableState, pagination: Partial<PaginationState>): TableState;
+/**
+ * Update filtering state
+ */
+declare function updateFiltering(state: TableState, filtering: Partial<FilterState>): TableState;
+/**
+ * Update column visibility
+ */
+declare function updateColumnVisibility(state: TableState, columnId: string, visible: boolean): TableState;
+/**
+ * Update column order
+ */
+declare function updateColumnOrder(state: TableState, columnOrder: string[]): TableState;
+/**
+ * Controlled state handler type
+ * Used when state is managed externally
+ */
+type TableStateHandler = {
+    state: TableState;
+    setState: (state: TableState | ((prev: TableState) => TableState)) => void;
+};
+/**
+ * Uncontrolled state handler type
+ * Used when state is managed internally
+ */
+type UncontrolledTableState = {
+    initialState?: Partial<TableState>;
+    onStateChange?: (state: TableState) => void;
+};
+/**
+ * Check if state is controlled
+ */
+declare function isControlledState(handler: TableStateHandler | UncontrolledTableState): handler is TableStateHandler;
+
+/**
+ * Column definitions and utilities
+ *
+ * Type-safe column definition API with extensibility for:
+ * - Custom JSX renderers (via renderCell, renderHeader)
+ * - Grouped headers (via parentId)
+ * - Metadata extension (via meta)
+ */
+/**
+ * Filter type configuration
+ *
+ * TODO: Extend to support more filter types:
+ * - 'number' | 'date' | 'select' | 'range'
+ */
+type FilterType = "text" | "none";
+/**
+ * Column accessor function type
+ * Extracts a value from a data item
+ */
+type AccessorFn<TData, TValue> = (data: TData) => TValue;
+/**
+ * Column accessor - either a key path or a function
+ */
+type ColumnAccessor<TData, TValue> = keyof TData | AccessorFn<TData, TValue>;
+/**
+ * Base column definition
+ *
+ * This is the serializable part of the column definition.
+ * Renderers and other runtime functions are kept separate for serialization.
+ *
+ * TODO: Add support for:
+ * - renderCell: (value: TValue, row: TData) => React.ReactNode
+ * - renderHeader: () => React.ReactNode
+ * - parentId?: string (for grouped headers)
+ * - meta?: Record<string, unknown> (for extensible metadata)
+ */
+interface ColumnDef<TData, TValue = unknown> {
+    /** Unique column identifier - must be stable */
+    id: string;
+    /** Column header label */
+    header?: string;
+    /** Whether column is sortable */
+    sortable?: boolean;
+    /** Filter type for this column */
+    filter?: FilterType;
+    /** Column width in pixels */
+    width?: number;
+    /** Minimum column width */
+    minWidth?: number;
+    /** Maximum column width */
+    maxWidth?: number;
+    /** Whether column is visible by default */
+    visible?: boolean;
+    /** Column alignment */
+    align?: "left" | "center" | "right";
+    /** Accessor function or key path to extract value */
+    accessor?: ColumnAccessor<TData, TValue>;
+    /** Custom metadata for extensibility */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Runtime column representation
+ * Includes the definition plus computed properties
+ */
+interface Column<TData> {
+    /** Column definition */
+    def: ColumnDef<TData>;
+    /** Column ID (stable identifier) */
+    id: string;
+    /** Column header label */
+    header: string;
+    /** Whether column is sortable */
+    sortable: boolean;
+    /** Filter type */
+    filter: FilterType;
+    /** Column width */
+    width?: number;
+    /** Column alignment */
+    align: "left" | "center" | "right";
+    /** Accessor function to extract value from data */
+    accessor: AccessorFn<TData, unknown>;
+}
+/**
+ * Column definition builder options
+ */
+interface ColumnOptions<TData, TValue> {
+    header?: string;
+    sortable?: boolean;
+    filter?: FilterType;
+    width?: number;
+    minWidth?: number;
+    maxWidth?: number;
+    visible?: boolean;
+    align?: "left" | "center" | "right";
+    accessor?: ColumnAccessor<TData, TValue>;
+    meta?: Record<string, unknown>;
+}
+/**
+ * Create a column definition from a key
+ *
+ * @param key - Column key (must exist on TData)
+ * @param options - Column configuration options
+ * @returns Column definition
+ */
+declare function col<TData, TKey extends keyof TData>(key: TKey, options?: ColumnOptions<TData, TData[TKey]>): ColumnDef<TData, TData[TKey]>;
+/**
+ * Create a column definition with a custom accessor
+ *
+ * @param id - Unique column identifier
+ * @param options - Column configuration options (must include accessor)
+ * @returns Column definition
+ */
+declare function colWithAccessor<TData, TValue>(id: string, options: ColumnOptions<TData, TValue> & {
+    accessor: ColumnAccessor<TData, TValue>;
+}): ColumnDef<TData, TValue>;
+/**
+ * Type-safe column definition array builder
+ *
+ * Provides type inference and validation for column definitions.
+ *
+ * @example
+ * ```ts
+ * const columns = defineColumns<User>()([
+ *   col("name", { header: "Name", sortable: true }),
+ *   col("email", { header: "Email", filter: "text" }),
+ * ]);
+ * ```
+ */
+declare function defineColumns<TData>(): <TColumns extends readonly ColumnDef<TData>[]>(columns: TColumns) => TColumns;
+/**
+ * Normalize column accessor to a function
+ */
+declare function normalizeAccessor<TData, TValue>(accessor: ColumnAccessor<TData, TValue>): AccessorFn<TData, TValue>;
+/**
+ * Convert column definition to runtime column
+ */
+declare function createColumn<TData>(def: ColumnDef<TData>): Column<TData>;
+/**
+ * Convert array of column definitions to runtime columns
+ */
+declare function createColumns<TData>(definitions: readonly ColumnDef<TData>[]): Column<TData>[];
+/**
+ * Get column by ID
+ */
+declare function getColumnById<TData>(columns: Column<TData>[], id: string): Column<TData> | undefined;
+/**
+ * Get visible columns
+ */
+declare function getVisibleColumns<TData>(columns: Column<TData>[], visibility: Record<string, boolean>): Column<TData>[];
+/**
+ * Get columns in specified order
+ */
+declare function getOrderedColumns<TData>(columns: Column<TData>[], order: string[]): Column<TData>[];
+/**
+ * Extract column IDs from definitions
+ */
+declare function getColumnIds<TData>(definitions: readonly ColumnDef<TData>[]): string[];
+/**
+ * Validate column definitions
+ * Ensures all columns have unique IDs
+ */
+declare function validateColumns<TData>(definitions: readonly ColumnDef<TData>[]): {
+    valid: boolean;
+    errors: string[];
+};
+
+export { type AccessorFn, type Column, type ColumnAccessor, type ColumnDef, type ColumnOptions, type CompareFn, type FilterState, type FilterType, type MatchFn, type PaginationState, type SortDirection, type SortState, type TableState, type TableStateHandler, type UncontrolledTableState, applyFilters, applySort, clampPageIndex, clearAllFilters, clearColumnFilter, clearSort, col, colWithAccessor, createColumn, createColumns, createComparator, createInitialFilterState, createInitialPaginationState, createInitialSortState, createInitialTableState, defaultCompare, defaultMatch, defineColumns, getActiveFilterCount, getColumnById, getColumnIds, getOrderedColumns, getPageCount, getPageEndIndex, getPageStartIndex, getPaginatedData, getVisibleColumns, goToNextPage, goToPage, goToPreviousPage, hasNextPage, hasPreviousPage, isControlledState, isFilterActive, isSortActive, isValidPageIndex, normalizeAccessor, setColumnFilter, setGlobalFilter, setPageSize, setSort, toggleSort, updateColumnOrder, updateColumnVisibility, updateFiltering, updatePagination, updateSorting, updateTableState, validateColumns };