tablero 1.0.0

package/README.md

@@ -0,0 +1,181 @@
+# tablero
+
+A type-safe, framework-agnostic data table library with React bindings. Built with TypeScript for maximum type safety and developer experience.
+
+## Features
+
+- 🎯 **Type-safe** - Full TypeScript support with excellent type inference
+- 🔄 **Framework-agnostic core** - Use the core logic with any framework
+- ⚛️ **React hooks** - `useDataTable` hook for easy React integration
+- 🎨 **Customizable UI** - Flexible, CSS-variable based styling
+- 📊 **Sorting** - Single-column sorting (extensible to multi-column)
+- 📄 **Pagination** - Client-side pagination with configurable page sizes
+- 🔍 **Filtering** - Global and column-specific text filtering
+- 📌 **Sticky headers & columns** - Keep headers and first column visible while scrolling
+- 🔧 **Column resizing** - Resize columns with pointer-based interaction
+- 🎭 **Custom renderers** - Customize cell, header, and row rendering
+- ♿ **Accessible** - ARIA attributes and keyboard support
+
+## Installation
+
+```bash
+npm install tablero
+# or
+pnpm add tablero
+# or
+yarn add tablero
+```
+
+## Quick Start
+
+### React Example
+
+```tsx
+import { useDataTable } from "tablero/react";
+import { DataTable } from "tablero/ui";
+import { defineColumns, col } from "tablero/core";
+import "tablero/dist/ui.css"; // Optional: import default styles
+
+interface User {
+  id: number;
+  name: string;
+  email: string;
+  age: number;
+}
+
+const columns = defineColumns<User>()([
+  col("name", { header: "Name", sortable: true }),
+  col("email", { header: "Email", sortable: true, filter: "text" }),
+  col("age", { header: "Age", sortable: true }),
+]);
+
+function MyTable() {
+  const table = useDataTable({
+    data: users,
+    columns,
+    pageSize: 10,
+  });
+
+  return (
+    <DataTable
+      table={table}
+      stickyHeader
+      bordered
+      maxHeight={400}
+    />
+  );
+}
+```
+
+### Core Usage (Framework-agnostic)
+
+```ts
+import {
+  defineColumns,
+  col,
+  createColumns,
+  createInitialTableState,
+  applyFilters,
+  applySort,
+  getPaginatedData,
+} from "tablero/core";
+
+const columns = defineColumns<User>()([
+  col("name", { header: "Name", sortable: true }),
+  col("email", { header: "Email" }),
+]);
+
+const runtimeColumns = createColumns(columns);
+const state = createInitialTableState(columns.map((c) => c.id));
+
+// Apply filters
+const filtered = applyFilters(data, state.filtering, getValue);
+
+// Apply sorting
+const sorted = applySort(filtered, state.sorting, getValue);
+
+// Paginate
+const paginated = getPaginatedData(sorted, state.pagination);
+```
+
+## Packages
+
+This library is organized into three packages:
+
+- **`tablero/core`** - Framework-agnostic core logic (state management, sorting, filtering, pagination)
+- **`tablero/react`** - React hooks (`useDataTable`)
+- **`tablero/ui`** - React UI components (`DataTable`, `TableHeader`, `TableBody`, `TableCell`)
+
+## API Documentation
+
+### Core API
+
+See the [core package documentation](./packages/core/README.md) for detailed API documentation.
+
+### React Hook
+
+```tsx
+const table = useDataTable({
+  data: TData[],
+  columns: ColumnDef<TData>[],
+  pageSize?: number,
+  state?: TableStateHandler | UncontrolledTableState,
+});
+```
+
+### DataTable Component
+
+```tsx
+<DataTable
+  table={table}
+  bordered={true}
+  stickyHeader={false}
+  stickyFirstColumn={false}
+  enableResizing={false}
+  maxHeight?: number | string
+  slots={{
+    loader?: React.ComponentType,
+    empty?: React.ComponentType<{ columns: Column[] }>,
+    error?: React.ComponentType<{ error: Error | string }>,
+  }}
+  renderCell?: (value, row, column) => React.ReactNode
+  renderHeader?: (column, sortState) => React.ReactNode
+  renderRow?: (row, index, cells) => React.ReactNode
+/>
+```
+
+## Styling
+
+The library uses CSS variables for easy theming. Import the default styles or create your own:
+
+```css
+:root {
+  --tablero-bg: #ffffff;
+  --tablero-header-bg: #f9fafb;
+  --tablero-border-color: #e5e7eb;
+  --tablero-border-width: 1px;
+  --tablero-hover-bg: #f3f4f6;
+  --tablero-text-color: #111827;
+}
+```
+
+## TypeScript Support
+
+Full TypeScript support with excellent type inference:
+
+```tsx
+// Column keys are type-checked
+const columns = defineColumns<User>()([
+  col("name", { ... }), // ✅ Type-safe
+  col("invalid", { ... }), // ❌ Type error
+]);
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+

package/dist/core.d.mts

@@ -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 };