@classic-homes/theme-svelte 0.1.30 → 0.1.31

package/dist/lib/components/DataTable.svelte

@@ -61,6 +61,7 @@
     formatCellValue,
     getAriaSortValue,
     defaultGetRowId,
+    createMemoizedConverter,
   } from './data-table/utils.js';
   import type {
     DataTableProps,
@@ -187,6 +188,10 @@
     enableEditing?: boolean;
     /** Callback when a cell is edited */
     onCellEdit?: (rowId: string, columnId: string, value: unknown, row: T) => void;
+
+    // === Debug Props ===
+    /** Enable verbose debug logging to console */
+    debug?: boolean;
   }
 
   let {
@@ -241,39 +246,63 @@
     // New editing props
     enableEditing = false,
     onCellEdit,
+
+    // Debug props
+    debug = false,
   }: Props = $props();
 
-  // Validate props in development
+  // Validate props
   $effect(() => {
     validateNonEmptyArray(columns, 'columns', 'DataTable');
-  });
 
-  /**
-   * Column definition cache for memoization.
-   * Key: column.id, Value: converted ColumnDef
-   *
-   * This prevents recreating column definitions on every render,
-   * which is especially important for tables with many columns.
-   */
-  const columnDefCache = new Map<string, ColumnDef<T, unknown>>();
+    // Validate column IDs are unique - this MUST be enforced as duplicate IDs
+    // cause silent bugs in sorting, selection, and visibility features
+    const ids = columns.map((c) => c.id);
+    const seen = new Set<string>();
+    const duplicates: string[] = [];
+    for (const id of ids) {
+      if (seen.has(id)) {
+        duplicates.push(id);
+      }
+      seen.add(id);
+    }
+    if (duplicates.length > 0) {
+      throw new Error(
+        `[DataTable] Duplicate column IDs found: ${duplicates.join(', ')}. ` +
+          'Each column must have a unique ID. Duplicate IDs cause bugs in sorting, ' +
+          'selection, filtering, and column visibility features.'
+      );
+    }
+
+    // Warn when using server-side features without a custom getRowId
+    // Using array index as row ID breaks selection when data is reordered or paginated server-side
+    const isServerSide = onSort || manualFiltering || manualPagination;
+    const hasCustomGetRowId = !!getRowId;
+    if (isServerSide && enableRowSelection && !hasCustomGetRowId) {
+      console.warn(
+        '[DataTable] Row selection is enabled with server-side data operations, but no ' +
+          '`getRowId` function was provided. The default uses array index, which will cause ' +
+          'selection to break when data is reordered, filtered, or paginated on the server. ' +
+          'Provide a `getRowId` function that returns a stable unique identifier for each row ' +
+          '(e.g., `getRowId={(row) => row.id}`).'
+      );
+    }
+  });
 
   /**
-   * Convert legacy DataTableColumn to TanStack ColumnDef with memoization.
+   * Memoized column definition converter with LRU cache.
    *
-   * The conversion is cached by column ID. Cache is invalidated when:
-   * - Column properties change (detected by comparing relevant fields)
-   * - The columns array reference changes (cache is cleared)
+   * Features:
+   * - Maximum 100 cached entries (prevents unbounded growth)
+   * - LRU eviction when cache is full
+   * - Cache key includes all properties that affect the ColumnDef
+   * - Clear method for manual cache invalidation
    */
-  function convertToColumnDef(col: DataTableColumn<T>): ColumnDef<T, unknown> {
-    // Create a cache key that includes properties that affect the ColumnDef
-    const cacheKey = `${col.id}:${col.header}:${col.sortable}:${col.enableColumnFilter}:${col.enableHiding}:${col.width}:${col.align}`;
-
-    const cached = columnDefCache.get(cacheKey);
-    if (cached) {
-      return cached;
-    }
-
-    const columnDef: ColumnDef<T, unknown> = {
+  const memoizedConvertToColumnDef = createMemoizedConverter<
+    DataTableColumn<T>,
+    ColumnDef<T, unknown>
+  >(
+    (col) => ({
       id: col.id,
       header: col.header,
       accessorFn:
@@ -293,18 +322,26 @@
         filterPlaceholder: col.filterPlaceholder,
         ...col.meta,
       } satisfies ColumnMeta<T>,
-    };
-
-    columnDefCache.set(cacheKey, columnDef);
-    return columnDef;
-  }
+    }),
+    // Cache key includes all properties that affect the ColumnDef
+    (col) =>
+      `${col.id}:${col.header}:${col.sortable}:${col.enableColumnFilter}:${col.enableHiding}:${col.width}:${col.align}`,
+    100 // Max 100 cached column definitions
+  );
 
   // Clear cache when columns array changes (new reference)
   let previousColumnsRef: DataTableColumn<T>[] | undefined;
   $effect(() => {
     if (previousColumnsRef !== columns) {
-      columnDefCache.clear();
+      memoizedConvertToColumnDef.clear();
       previousColumnsRef = columns;
+
+      if (debug) {
+        console.log('[DataTable] Columns changed, cache cleared', {
+          columnCount: columns.length,
+          columnIds: columns.map((c) => c.id),
+        });
+      }
     }
   });
 
@@ -326,8 +363,8 @@
   // Create TanStack column definitions
   const columnDefs = $derived<ColumnDef<T, unknown>[]>(
     enableRowSelection
-      ? [selectionColumnDef, ...columns.map(convertToColumnDef)]
-      : columns.map(convertToColumnDef)
+      ? [selectionColumnDef, ...columns.map(memoizedConvertToColumnDef)]
+      : columns.map(memoizedConvertToColumnDef)
   );
 
   // Create the TanStack table instance
@@ -389,7 +426,32 @@
   }));
 
   // Get rows to display (respects pagination when enabled)
-  const displayRows = $derived(table.instance.getRowModel().rows);
+  // Must depend on version to re-evaluate when data changes externally
+  const displayRows = $derived.by(() => {
+    void table.reactiveState.version;
+    return table.instance.getRowModel().rows;
+  });
+
+  // Debug logging for table state changes
+  $effect(() => {
+    if (!debug) return;
+
+    // Track version to log on every state change
+    const version = table.reactiveState.version;
+    const rowCount = displayRows.length;
+    const totalRows = data.length;
+
+    console.log('[DataTable] State updated', {
+      version,
+      displayedRows: rowCount,
+      totalRows,
+      sorting: table.sorting,
+      pagination: enablePagination ? table.pagination : 'disabled',
+      globalFilter: enableGlobalFilter ? table.globalFilter : 'disabled',
+      selectedCount: enableRowSelection ? table.selectedRowCount : 'disabled',
+      cacheSize: memoizedConvertToColumnDef.size(),
+    });
+  });
 
   // Handle row click with error boundary
   function handleRowClick(row: T) {

package/dist/lib/components/DataTable.svelte.d.ts

@@ -123,6 +123,8 @@ declare function $$render<T extends object>(): {
         enableEditing?: boolean;
         /** Callback when a cell is edited */
         onCellEdit?: (rowId: string, columnId: string, value: unknown, row: T) => void;
+        /** Enable verbose debug logging to console */
+        debug?: boolean;
     };
     exports: {};
     bindings: "columnVisibility" | "columnFilters" | "globalFilter" | "rowSelection" | "sortColumn" | "sortDirection" | "pageSize" | "pageIndex";

package/dist/lib/components/data-table/createDataTable.svelte.js

@@ -275,10 +275,14 @@ export function createDataTable(options) {
     // Use $derived to create a reactive options snapshot that tracks all dependencies
     const currentOptions = $derived.by(() => {
         const opts = options();
-        // Read all state values to ensure they're tracked as dependencies
-        // This creates a snapshot of the current state
+        // Explicitly read all values that should trigger re-renders.
+        // Svelte 5's fine-grained reactivity requires explicit property access
+        // to establish dependencies - the spread operator alone doesn't track them.
         return {
             ...opts,
+            // Track data and column changes (critical for external updates)
+            _data: opts.data,
+            _columns: opts.columns,
             // Explicitly read state values to track them (these establish reactive dependencies)
             _sorting: opts.state?.sorting ?? opts.sorting ?? internalSorting,
             _columnFilters: opts.state?.columnFilters ?? opts.columnFilters ?? internalColumnFilters,

package/dist/lib/components/data-table/index.d.ts

@@ -16,7 +16,7 @@
  */
 export { createDataTable, type CreateDataTableOptions, type DataTableInstance, type Table, type ColumnDef, type SortingState, type ColumnFiltersState, type VisibilityState, type RowSelectionState, type PaginationState, type Row, type Cell, type Header, type HeaderGroup, type Column, type CellContext, type HeaderContext, createColumnHelper, } from './createDataTable.svelte.js';
 export { type ColumnMeta, type BaseColumnMeta, type DataColumnMeta, type FilterableColumnMeta, type SelectionColumnMeta, type DataTableProps, type DataTableCoreProps, type DataTableSortingProps, type DataTableSelectionProps, type DataTableVisibilityProps, type DataTableFilteringProps, type DataTablePaginationProps, type DataTableVirtualizationProps, type DataTableEditingProps, type DataTableInteractionProps, SVELTE_COMPONENT_SYMBOL, isMarkedComponent, markAsComponent, type MarkedSvelteComponent, type InferRowType, type FormatResult, } from './types.js';
-export { getAlignClass, getMetaAlign, formatCellValue, formatCellValueSafe, getColumnWidthStyle, getColumnFlexStyle, getAriaSortValue, defaultGetRowId, createMemoizedConverter, } from './utils.js';
+export { getAlignClass, getMetaAlign, formatCellValue, formatCellValueSafe, getColumnWidthStyle, getColumnFlexStyle, getAriaSortValue, defaultGetRowId, createMemoizedConverter, type MemoizedFunction, } from './utils.js';
 export { default as FlexRender } from './FlexRender.svelte';
 export { default as DataTableToolbar } from './DataTableToolbar.svelte';
 export { default as DataTableSearch } from './DataTableSearch.svelte';

package/dist/lib/components/data-table/types.d.ts

@@ -97,20 +97,66 @@ export interface DataTableSortingProps {
 }
 /**
  * Props for row selection functionality.
+ *
+ * ## Row ID Requirements
+ *
+ * **Critical**: When using row selection with server-side data (sorting, filtering, or pagination),
+ * you MUST provide a custom `getRowId` function. The default uses array index, which breaks
+ * selection when data is reordered.
+ *
+ * @example
+ * ```svelte
+ * <!-- Always provide getRowId for server-side data -->
+ * <DataTable
+ *   data={serverData}
+ *   columns={columns}
+ *   enableRowSelection
+ *   manualPagination
+ *   getRowId={(row) => row.id}
+ *   rowSelection={selectedRows}
+ *   onRowSelectionChange={(selection) => selectedRows = selection}
+ * />
+ * ```
+ *
+ * ## Selection State Format
+ *
+ * The `rowSelection` state is a record mapping row IDs to booleans:
+ * ```ts
+ * { "user-1": true, "user-3": true } // rows with IDs "user-1" and "user-3" are selected
+ * ```
  */
 export interface DataTableSelectionProps<T> {
     /**
      * Enable row selection.
      * Can be a boolean or a function that returns whether a specific row is selectable.
+     *
+     * @example
+     * ```svelte
+     * <!-- Conditionally disable selection for certain rows -->
+     * <DataTable
+     *   enableRowSelection={(row) => row.status !== 'locked'}
+     * />
+     * ```
      */
     enableRowSelection?: boolean | ((row: T) => boolean);
     /** Enable multi-row selection (default: true when selection enabled) */
     enableMultiRowSelection?: boolean;
-    /** Controlled row selection state (record of rowId -> selected) */
+    /**
+     * Controlled row selection state.
+     * Record of rowId -> boolean (true = selected).
+     */
     rowSelection?: RowSelectionState;
     /** Callback when selection changes */
     onRowSelectionChange?: (selection: RowSelectionState) => void;
-    /** Function to get unique row ID (defaults to index) */
+    /**
+     * Function to get unique row ID.
+     *
+     * **Important**: Required for server-side data! The default uses array index,
+     * which breaks selection when data is sorted, filtered, or paginated server-side.
+     *
+     * @default (row, index) => String(index)
+     * @example getRowId={(row) => row.id}
+     */
     getRowId?: (row: T, index: number) => string;
 }
 /**
@@ -126,13 +172,47 @@ export interface DataTableVisibilityProps {
 }
 /**
  * Props for filtering functionality (global and per-column).
+ *
+ * ## Global Filter Behavior
+ *
+ * The global filter searches across all visible columns by converting cell values to strings.
+ * This works well for primitive values (strings, numbers, booleans) but may produce
+ * unexpected results with complex objects:
+ *
+ * - Objects are stringified as `[object Object]` - not searchable
+ * - Arrays are joined with commas - `["a", "b"]` becomes `"a,b"`
+ * - Dates are converted to ISO strings
+ *
+ * **For complex data**: Use a custom `format` function on columns to control how values
+ * are displayed and searched, or implement server-side filtering with `manualFiltering`.
+ *
+ * ## Server-Side Filtering
+ *
+ * For large datasets or complex filtering logic, use server-side filtering:
+ *
+ * @example
+ * ```svelte
+ * <DataTable
+ *   data={serverData}
+ *   columns={columns}
+ *   enableFiltering
+ *   manualFiltering
+ *   globalFilter={searchQuery}
+ *   onGlobalFilterChange={(filter) => fetchFilteredData(filter)}
+ * />
+ * ```
  */
 export interface DataTableFilteringProps {
-    /** Enable filtering features */
+    /** Enable filtering features (per-column filters) */
     enableFiltering?: boolean;
-    /** Enable global filter input */
+    /** Enable global filter input (searches all columns) */
     enableGlobalFilter?: boolean;
-    /** Controlled global filter value */
+    /**
+     * Controlled global filter value.
+     *
+     * The filter searches stringified cell values across all visible columns.
+     * For complex objects, use column `format` functions to control searchable text.
+     */
     globalFilter?: string;
     /** Callback when global filter changes */
     onGlobalFilterChange?: (filter: string) => void;
@@ -140,7 +220,12 @@ export interface DataTableFilteringProps {
     columnFilters?: ColumnFiltersState;
     /** Callback when column filters change */
     onColumnFiltersChange?: (filters: ColumnFiltersState) => void;
-    /** Use server-side filtering (manual mode) */
+    /**
+     * Use server-side filtering (manual mode).
+     *
+     * When enabled, the table will NOT filter data client-side. You must handle
+     * filtering in your data fetching logic and provide already-filtered data.
+     */
     manualFiltering?: boolean;
 }
 /**
@@ -162,13 +247,60 @@ export interface DataTablePaginationProps {
 }
 /**
  * Props for virtualization (large dataset support).
+ *
+ * ## Important Constraints
+ *
+ * **Fixed Row Height Required**: Virtualization uses windowing to only render visible rows.
+ * This requires ALL rows to have the same height. If your rows have variable heights
+ * (e.g., wrapping text, expandable content), virtualization will cause visual glitches.
+ *
+ * **When to Use**: Enable virtualization when displaying 1000+ rows. For smaller datasets,
+ * standard rendering is often more performant due to virtualization overhead.
+ *
+ * ## Overscan Tuning
+ *
+ * The `virtualOverscan` prop controls how many rows are rendered outside the visible area.
+ * - **Lower values (5)**: Better performance, but may show blank areas during fast scrolling
+ * - **Higher values (20)**: Smoother scrolling, but renders more DOM nodes
+ * - **Default (10)**: Good balance for most use cases
+ *
+ * @example
+ * ```svelte
+ * <!-- Large dataset with custom row height -->
+ * <DataTable
+ *   {data}
+ *   {columns}
+ *   enableVirtualization
+ *   virtualRowHeight={56}
+ *   virtualOverscan={15}
+ * />
+ * ```
  */
 export interface DataTableVirtualizationProps {
-    /** Enable row virtualization for large datasets (1000+ rows recommended) */
+    /**
+     * Enable row virtualization for large datasets.
+     *
+     * Recommended for 1000+ rows. Requires fixed row heights.
+     * @default false
+     */
     enableVirtualization?: boolean;
-    /** Height of each row in pixels for virtualization (default: 48) */
+    /**
+     * Height of each row in pixels for virtualization.
+     *
+     * **Important**: ALL rows must have this exact height. Variable height rows
+     * will cause visual glitches (misaligned rows, flickering).
+     *
+     * @default 48
+     */
     virtualRowHeight?: number;
-    /** Number of rows to render outside the visible viewport (default: 10) */
+    /**
+     * Number of rows to render outside the visible viewport.
+     *
+     * Higher values = smoother scrolling but more DOM nodes.
+     * Lower values = better performance but may flash during fast scrolling.
+     *
+     * @default 10
+     */
     virtualOverscan?: number;
 }
 /**

package/dist/lib/components/data-table/utils.d.ts

@@ -83,18 +83,69 @@ export declare function getAriaSortValue(sortDirection: false | 'asc' | 'desc'):
 /**
  * Default row ID function that uses the array index.
  *
+ * **Warning**: This is only suitable for static, client-side data where the order
+ * never changes. For any of these scenarios, provide a custom `getRowId`:
+ *
+ * - Server-side sorting, filtering, or pagination
+ * - Data that can be reordered by the user
+ * - Data that can be inserted or deleted
+ * - Row selection that must persist across data updates
+ *
+ * Using array index with dynamic data causes:
+ * - Selection jumping to wrong rows after sort/filter
+ * - Selected state appearing on different rows after pagination
+ * - Inconsistent behavior when rows are added/removed
+ *
  * @param _row - The row data (unused)
  * @param index - The row index
  * @returns String representation of the index
+ *
+ * @example
+ * ```ts
+ * // DON'T use defaultGetRowId with server-side data
+ * // DO provide a custom getRowId:
+ * getRowId={(row) => row.id}
+ * getRowId={(row) => `${row.type}-${row.id}`}
+ * ```
  */
 export declare function defaultGetRowId<T>(_row: T, index: number): string;
 /**
- * Simple memoization for column definition conversion.
- * Caches the result based on a stable key derived from the column.
+ * A memoized function with cache management methods.
  */
-export declare function createMemoizedConverter<TInput, TOutput>(converter: (input: TInput) => TOutput, getKey: (input: TInput) => string): (input: TInput) => TOutput;
+export interface MemoizedFunction<TInput, TOutput> {
+    /** Call the memoized function */
+    (input: TInput): TOutput;
+    /** Clear all cached entries */
+    clear: () => void;
+    /** Get the current cache size */
+    size: () => number;
+}
 /**
- * Clear all entries from a memoization cache.
- * Call this when the underlying data structure changes significantly.
+ * Create a memoized converter with LRU cache eviction.
+ *
+ * Features:
+ * - Configurable maximum cache size (default: 100)
+ * - LRU (Least Recently Used) eviction when cache is full
+ * - Exposed `clear()` method to manually clear the cache
+ * - Exposed `size()` method to check current cache size
+ *
+ * @param converter - Function to convert input to output
+ * @param getKey - Function to generate a cache key from input
+ * @param maxSize - Maximum number of entries to cache (default: 100)
+ * @returns Memoized function with cache management methods
+ *
+ * @example
+ * ```ts
+ * const memoizedConvert = createMemoizedConverter(
+ *   (col) => convertColumn(col),
+ *   (col) => col.id,
+ *   50 // max 50 entries
+ * );
+ *
+ * memoizedConvert(column); // Converts and caches
+ * memoizedConvert(column); // Returns cached
+ * memoizedConvert.clear(); // Clears cache
+ * memoizedConvert.size();  // Returns 0
+ * ```
  */
-export declare function clearMemoCache<TInput, TOutput>(_memoizedFn: ReturnType<typeof createMemoizedConverter<TInput, TOutput>>): void;
+export declare function createMemoizedConverter<TInput, TOutput>(converter: (input: TInput) => TOutput, getKey: (input: TInput) => string, maxSize?: number): MemoizedFunction<TInput, TOutput>;

package/dist/lib/components/data-table/utils.js

@@ -181,39 +181,88 @@ export function getAriaSortValue(sortDirection) {
 /**
  * Default row ID function that uses the array index.
  *
+ * **Warning**: This is only suitable for static, client-side data where the order
+ * never changes. For any of these scenarios, provide a custom `getRowId`:
+ *
+ * - Server-side sorting, filtering, or pagination
+ * - Data that can be reordered by the user
+ * - Data that can be inserted or deleted
+ * - Row selection that must persist across data updates
+ *
+ * Using array index with dynamic data causes:
+ * - Selection jumping to wrong rows after sort/filter
+ * - Selected state appearing on different rows after pagination
+ * - Inconsistent behavior when rows are added/removed
+ *
  * @param _row - The row data (unused)
  * @param index - The row index
  * @returns String representation of the index
+ *
+ * @example
+ * ```ts
+ * // DON'T use defaultGetRowId with server-side data
+ * // DO provide a custom getRowId:
+ * getRowId={(row) => row.id}
+ * getRowId={(row) => `${row.type}-${row.id}`}
+ * ```
  */
 export function defaultGetRowId(_row, index) {
     return String(index);
 }
-// =============================================================================
-// Memoization Utilities
-// =============================================================================
 /**
- * Simple memoization for column definition conversion.
- * Caches the result based on a stable key derived from the column.
+ * Create a memoized converter with LRU cache eviction.
+ *
+ * Features:
+ * - Configurable maximum cache size (default: 100)
+ * - LRU (Least Recently Used) eviction when cache is full
+ * - Exposed `clear()` method to manually clear the cache
+ * - Exposed `size()` method to check current cache size
+ *
+ * @param converter - Function to convert input to output
+ * @param getKey - Function to generate a cache key from input
+ * @param maxSize - Maximum number of entries to cache (default: 100)
+ * @returns Memoized function with cache management methods
+ *
+ * @example
+ * ```ts
+ * const memoizedConvert = createMemoizedConverter(
+ *   (col) => convertColumn(col),
+ *   (col) => col.id,
+ *   50 // max 50 entries
+ * );
+ *
+ * memoizedConvert(column); // Converts and caches
+ * memoizedConvert(column); // Returns cached
+ * memoizedConvert.clear(); // Clears cache
+ * memoizedConvert.size();  // Returns 0
+ * ```
  */
-export function createMemoizedConverter(converter, getKey) {
+export function createMemoizedConverter(converter, getKey, maxSize = 100) {
     const cache = new Map();
-    return (input) => {
+    const memoized = (input) => {
         const key = getKey(input);
+        // Check cache first
         const cached = cache.get(key);
         if (cached !== undefined) {
+            // Move to end for LRU (delete and re-add)
+            cache.delete(key);
+            cache.set(key, cached);
             return cached;
         }
+        // Evict oldest entry if cache is full (LRU eviction)
+        if (cache.size >= maxSize) {
+            const oldestKey = cache.keys().next().value;
+            if (oldestKey !== undefined) {
+                cache.delete(oldestKey);
+            }
+        }
+        // Convert and cache
         const result = converter(input);
         cache.set(key, result);
         return result;
     };
-}
-/**
- * Clear all entries from a memoization cache.
- * Call this when the underlying data structure changes significantly.
- */
-export function clearMemoCache(_memoizedFn) {
-    // The cache is encapsulated, so we need to recreate the function
-    // This is a design trade-off for simplicity
-    // In practice, recreating the converter is the cleaner approach
+    // Attach cache management methods
+    memoized.clear = () => cache.clear();
+    memoized.size = () => cache.size;
+    return memoized;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classic-homes/theme-svelte",
-  "version": "0.1.30",
+  "version": "0.1.31",
   "description": "Svelte components for the Classic theme system",
   "type": "module",
   "svelte": "./dist/lib/index.js",