@classic-homes/theme-svelte 1.25.1 → 1.26.0

package/dist/lib/components/DataTable.svelte

@@ -30,7 +30,7 @@
    * />
    * ```
    */
-  import type { Snippet } from 'svelte';
+  import { untrack, type Snippet } from 'svelte';
   import type { DataTableColumn } from '../types/components.js';
   import { cn } from '../utils.js';
   import { validateNonEmptyArray } from '../validation.js';
@@ -41,7 +41,12 @@
     getColumnWidthStyle,
     getAriaSortValue,
   } from './data-table/utils.js';
-  import type { PaginationState } from './data-table/types.js';
+  import type { ColumnFiltersState, PaginationState } from './data-table/types.js';
+  import DataTableColumnFilter from './data-table/DataTableColumnFilter.svelte';
+  import DataTableColumnVisibility from './data-table/DataTableColumnVisibility.svelte';
+  import DataTableEditableCell from './data-table/DataTableEditableCell.svelte';
+  import DataTableFacetedFilter from './data-table/DataTableFacetedFilter.svelte';
+  import DataTableVirtual from './data-table/DataTableVirtual.svelte';
   import Skeleton from './Skeleton.svelte';
   import Checkbox from './Checkbox.svelte';
 
@@ -69,8 +74,11 @@
     sortColumn?: string;
     /** Current sort direction */
     sortDirection?: 'asc' | 'desc';
-    /** Callback when sort changes - when provided, enables server-side sorting */
-    onSort?: (column: string, direction: 'asc' | 'desc') => void;
+    /**
+     * Callback when sort changes - when provided, enables server-side sorting.
+     * Called with `column: null` when the sort is cleared.
+     */
+    onSort?: (column: string | null, direction: 'asc' | 'desc') => void;
 
     // === Interaction Props ===
     /** Callback when row is clicked */
@@ -79,7 +87,10 @@
     // === Selection Props ===
     /** Enable row selection - can be boolean or function for per-row control */
     enableRowSelection?: boolean | ((row: T) => boolean);
-    /** Enable multi-row selection (default: true when selection enabled) */
+    /**
+     * Allow more than one selected row (default: true). When false, selecting
+     * a row replaces the previous selection and there is no select-all box.
+     */
     enableMultiRowSelection?: boolean;
     /** Controlled row selection state (Set of row IDs) */
     rowSelection?: Set<string>;
@@ -89,7 +100,7 @@
     getRowId?: (row: T, index: number) => string;
 
     // === Visibility Props ===
-    /** Enable column visibility toggling */
+    /** Show a "Columns" menu above the table for hiding and showing columns */
     enableColumnVisibility?: boolean;
     /** Controlled visibility state (Set of hidden column IDs) */
     columnVisibility?: Set<string>;
@@ -97,18 +108,27 @@
     onColumnVisibilityChange?: (hiddenColumns: Set<string>) => void;
 
     // === Filtering Props ===
-    /** Enable filtering features */
+    /**
+     * Show a filter row under the header: a text filter per column, or a
+     * faceted (multi-select) filter for columns that define `filterOptions`
+     */
     enableFiltering?: boolean;
-    /** Enable global filter input */
+    /**
+     * Apply `globalFilter` to the rows. No search input is rendered; bind
+     * `globalFilter` to your own input.
+     */
     enableGlobalFilter?: boolean;
     /** Controlled global filter value */
     globalFilter?: string;
     /** Callback when global filter changes */
     onGlobalFilterChange?: (filter: string) => void;
-    /** Controlled column filters */
-    columnFilters?: Map<string, string>;
+    /**
+     * Controlled column filters. A string value is a substring filter; a
+     * string[] value (what the faceted filter sets) matches those values exactly.
+     */
+    columnFilters?: ColumnFiltersState;
     /** Callback when column filters change */
-    onColumnFiltersChange?: (filters: Map<string, string>) => void;
+    onColumnFiltersChange?: (filters: ColumnFiltersState) => void;
     /** Use server-side filtering (manual mode) */
     manualFiltering?: boolean;
 
@@ -127,15 +147,24 @@
     pageCount?: number;
 
     // === Virtualization Props ===
-    /** Enable row virtualization for large datasets (1000+ rows recommended) */
+    /**
+     * Render rows with DataTableVirtual (only the visible rows are in the DOM)
+     * for large datasets (1000+ rows recommended). Pagination, `row` snippets,
+     * `hideBelow`, and inline editing do not apply in this mode.
+     */
     enableVirtualization?: boolean;
+    /** Height of the scrolling body when virtualized (CSS value, default: 500px) */
+    virtualHeight?: string;
     /** Height of each row in pixels for virtualization (default: 48) */
     virtualRowHeight?: number;
     /** Number of rows to render outside the visible viewport (default: 10) */
     virtualOverscan?: number;
 
     // === Editing Props ===
-    /** Enable inline cell editing */
+    /**
+     * Enable inline cell editing (DataTableEditableCell) for columns that set
+     * `enableEditing: true`. Requires `onCellEdit`.
+     */
     enableEditing?: boolean;
     /** Callback when a cell is edited */
     onCellEdit?: (rowId: string, columnId: string, value: unknown, row: T) => void;
@@ -177,7 +206,7 @@
     enableGlobalFilter = false,
     globalFilter = $bindable(''),
     onGlobalFilterChange,
-    columnFilters = $bindable(new Map<string, string>()),
+    columnFilters = $bindable(new Map() as ColumnFiltersState),
     onColumnFiltersChange,
     manualFiltering = false,
 
@@ -191,6 +220,7 @@
 
     // Virtualization props
     enableVirtualization = false,
+    virtualHeight = '500px',
     virtualRowHeight = 48,
     virtualOverscan = 10,
 
@@ -245,18 +275,22 @@
     initialPageSize: pageSize,
     initialPageIndex: pageIndex,
     initialGlobalFilter: globalFilter,
+    initialHiddenColumns: [...columnVisibility],
+    initialSelectedRows: [...rowSelection],
+    initialColumnFilters: columnFilters,
+    enableMultiRowSelection,
     manualSorting: !!onSort,
     manualFiltering,
     manualPagination,
     // Without the pager every row must render, not just the first page.
-    enablePagination,
+    // The virtual body windows the full row list itself.
+    enablePagination: enablePagination && !enableVirtualization,
     pageCount,
     onSortChange: (col, dir) => {
       sortColumn = col ?? undefined;
       sortDirection = dir;
-      if (col && onSort) {
-        onSort(col, dir);
-      }
+      // A cleared sort is reported too, or a server would stay sorted
+      onSort?.(col, dir);
     },
     onGlobalFilterChange: (filter) => {
       globalFilter = filter;
@@ -281,10 +315,87 @@
     },
   }));
 
-  // Sync external state changes to table
+  // Mirror controlled props into the table. Each effect tracks only its prop
+  // (the comparison runs untracked), so a table-side change such as a filter
+  // resetting the page is never undone by a stale prop value.
+  function sameSet(a: Set<string>, b: Set<string>) {
+    return a.size === b.size && [...a].every((v) => b.has(v));
+  }
+
+  function sameFilters(a: ColumnFiltersState, b: ColumnFiltersState) {
+    if (a.size !== b.size) return false;
+    for (const [key, value] of a) {
+      const other = b.get(key);
+      if (Array.isArray(value) && Array.isArray(other)) {
+        if (value.length !== other.length || value.some((v, i) => v !== other[i])) return false;
+      } else if (value !== other) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  $effect.pre(() => {
+    const value = globalFilter;
+    untrack(() => {
+      if (value !== table.globalFilter) table.setGlobalFilter(value);
+    });
+  });
+
+  $effect.pre(() => {
+    const column = sortColumn ?? null;
+    const direction = sortDirection;
+    untrack(() => {
+      if (column !== table.sortColumn || direction !== table.sortDirection) {
+        table.syncState({ sortColumn: column, sortDirection: direction });
+      }
+    });
+  });
+
+  $effect.pre(() => {
+    const index = pageIndex;
+    const size = pageSize;
+    untrack(() => {
+      if (index !== table.pageIndex || size !== table.pageSize) {
+        table.syncState({ pageIndex: index, pageSize: size });
+      }
+    });
+  });
+
+  $effect.pre(() => {
+    const selection = rowSelection;
+    untrack(() => {
+      if (!sameSet(selection, table.selectedRows)) table.syncState({ selectedRows: selection });
+    });
+  });
+
+  $effect.pre(() => {
+    const hidden = columnVisibility;
+    untrack(() => {
+      if (!sameSet(hidden, table.hiddenColumns)) table.syncState({ hiddenColumns: hidden });
+    });
+  });
+
+  $effect.pre(() => {
+    const filters = columnFilters;
+    untrack(() => {
+      if (!sameFilters(filters, table.columnFilters)) table.syncState({ columnFilters: filters });
+    });
+  });
+
+  const showSelectAll = $derived(!!enableRowSelection && enableMultiRowSelection);
+  const canEdit = $derived(enableEditing && !!onCellEdit);
+  const columnCount = $derived(table.columns.length + (enableRowSelection ? 1 : 0));
+
+  function handleCellEdit(rowId: string, columnId: string, value: unknown, row: T) {
+    onCellEdit?.(rowId, columnId, value, row);
+  }
+
+  // Editing needs somewhere to send the value; say so rather than silently
+  // rendering read-only cells.
   $effect(() => {
-    if (globalFilter !== table.globalFilter) {
-      table.setGlobalFilter(globalFilter);
+    if (enableEditing && !onCellEdit) {
+      console.warn('[DataTable] `enableEditing` has no effect without an `onCellEdit` callback.');
     }
   });
 
@@ -352,141 +463,195 @@
   }
 </script>
 
-<div class={cn('overflow-x-auto rounded-lg border', className)}>
-  <table class="w-full text-sm">
-    {#if caption}
-      <caption class="sr-only">{caption}</caption>
-    {/if}
-
-    <thead class="border-b bg-muted/50">
-      <tr>
-        {#if enableRowSelection}
-          <th scope="col" class="w-10 px-4 py-3">
-            <Checkbox
-              checked={table.isAllSelected}
-              indeterminate={table.isSomeSelected}
-              onCheckedChange={handleSelectAll}
-              aria-label="Select all rows"
-            />
-          </th>
-        {/if}
+{#if enableColumnVisibility}
+  <div class="flex justify-end pb-2">
+    <DataTableColumnVisibility {table} />
+  </div>
+{/if}
 
-        {#each table.columns as column (column.id)}
-          {@const isSorted = table.sortColumn === column.id}
-          <th
-            scope="col"
-            class={cn(
-              'px-4 py-3 font-medium text-muted-foreground',
-              getAlignClass(column.align),
-              column.hideBelow && hideBelowClasses[column.hideBelow],
-              column.sortable && 'cursor-pointer select-none hover:bg-muted-hover'
-            )}
-            style={getColumnWidthStyle(column)}
-            aria-sort={getAriaSortValue(isSorted, table.sortDirection)}
-          >
-            {#if column.sortable}
-              <button
-                type="button"
-                class="inline-flex w-full items-center justify-between gap-2"
-                onclick={() => handleHeaderClick(column.id, true)}
-              >
-                <span>{column.header}</span>
-                <svg
-                  class={cn(
-                    'h-4 w-4 transition-transform',
-                    !isSorted && 'opacity-0',
-                    isSorted && table.sortDirection === 'desc' && 'rotate-180'
-                  )}
-                  fill="none"
-                  viewBox="0 0 24 24"
-                  stroke="currentColor"
-                  stroke-width="2"
+{#if enableVirtualization && !loading}
+  <DataTableVirtual
+    {table}
+    rowHeight={virtualRowHeight}
+    overscan={virtualOverscan}
+    height={virtualHeight}
+    {onRowClick}
+    enableRowSelection={!!enableRowSelection}
+    enableSelectAll={enableMultiRowSelection}
+    class={cn('text-sm', className)}
+  />
+{:else}
+  <div class={cn('overflow-x-auto rounded-lg border', className)}>
+    <table class="w-full text-sm">
+      {#if caption}
+        <caption class="sr-only">{caption}</caption>
+      {/if}
+
+      <thead class="border-b bg-muted/50">
+        <tr>
+          {#if enableRowSelection}
+            <th scope="col" class="w-10 px-4 py-3">
+              {#if showSelectAll}
+                <Checkbox
+                  checked={table.isAllSelected}
+                  indeterminate={table.isSomeSelected}
+                  onCheckedChange={handleSelectAll}
+                  aria-label="Select all rows"
+                />
+              {:else}
+                <span class="sr-only">Select</span>
+              {/if}
+            </th>
+          {/if}
+
+          {#each table.columns as column (column.id)}
+            {@const isSorted = table.sortColumn === column.id}
+            <th
+              scope="col"
+              class={cn(
+                'px-4 py-3 font-medium text-muted-foreground',
+                getAlignClass(column.align),
+                column.hideBelow && hideBelowClasses[column.hideBelow],
+                column.sortable && 'cursor-pointer select-none hover:bg-muted-hover'
+              )}
+              style={getColumnWidthStyle(column)}
+              aria-sort={getAriaSortValue(isSorted, table.sortDirection)}
+            >
+              {#if column.sortable}
+                <button
+                  type="button"
+                  class="inline-flex w-full items-center justify-between gap-2"
+                  onclick={() => handleHeaderClick(column.id, true)}
                 >
-                  <path stroke-linecap="round" stroke-linejoin="round" d="M5 15l7-7 7 7" />
-                </svg>
-              </button>
-            {:else}
-              {column.header}
-            {/if}
-          </th>
-        {/each}
-      </tr>
-    </thead>
-
-    <tbody class="divide-y">
-      {#if loading}
-        {#each Array(loadingRows) as _, i (i)}
+                  <span>{column.header}</span>
+                  <svg
+                    class={cn(
+                      'h-4 w-4 transition-transform',
+                      !isSorted && 'opacity-0',
+                      isSorted && table.sortDirection === 'desc' && 'rotate-180'
+                    )}
+                    fill="none"
+                    viewBox="0 0 24 24"
+                    stroke="currentColor"
+                    stroke-width="2"
+                  >
+                    <path stroke-linecap="round" stroke-linejoin="round" d="M5 15l7-7 7 7" />
+                  </svg>
+                </button>
+              {:else}
+                {column.header}
+              {/if}
+            </th>
+          {/each}
+        </tr>
+        {#if enableFiltering}
           <tr>
             {#if enableRowSelection}
-              <td class="px-4 py-3">
-                <Skeleton class="h-5 w-5" />
-              </td>
+              <td class="px-4 pb-3"></td>
             {/if}
             {#each table.columns as column (column.id)}
-              <td class={cn('px-4 py-3', column.hideBelow && hideBelowClasses[column.hideBelow])}>
-                <Skeleton class="h-4 w-3/4" />
+              <td
+                class={cn(
+                  'px-4 pb-3 font-normal',
+                  column.hideBelow && hideBelowClasses[column.hideBelow]
+                )}
+              >
+                {#if column.filterOptions?.length}
+                  <DataTableFacetedFilter
+                    {table}
+                    columnId={column.id}
+                    title={column.header}
+                    options={column.filterOptions}
+                  />
+                {:else}
+                  <DataTableColumnFilter
+                    {table}
+                    columnId={column.id}
+                    placeholder={column.filterPlaceholder}
+                  />
+                {/if}
               </td>
             {/each}
           </tr>
-        {/each}
-      {:else if table.rows.length === 0}
-        <tr>
-          <td
-            colspan={enableRowSelection ? table.columns.length + 1 : table.columns.length}
-            class="px-4 py-8 text-center text-muted-foreground"
-          >
-            {emptyMessage}
-          </td>
-        </tr>
-      {:else}
-        {#each table.rows as row, index (row.id)}
-          {#if rowSnippet}
-            {@render rowSnippet(row.original, index)}
-          {:else}
-            <tr
-              class={cn(
-                'bg-card',
-                onRowClick && 'cursor-pointer hover:bg-muted-hover',
-                row.isSelected && 'bg-primary/5'
-              )}
-              tabindex={onRowClick ? 0 : undefined}
-              onclick={() => handleRowClick(row.original)}
-              onkeydown={onRowClick ? (e) => handleRowKeydown(e, row.original) : undefined}
-            >
+        {/if}
+      </thead>
+
+      <tbody class="divide-y">
+        {#if loading}
+          {#each Array(loadingRows) as _, i (i)}
+            <tr>
               {#if enableRowSelection}
                 <td class="px-4 py-3">
-                  {#if canSelectRow(row.original)}
-                    <Checkbox
-                      checked={row.isSelected}
-                      onCheckedChange={() => table.toggleRowSelection(row.id)}
-                      aria-label={`Select row ${index + 1}`}
-                      onclick={(e: MouseEvent) => e.stopPropagation()}
-                    />
-                  {/if}
+                  <Skeleton class="h-5 w-5" />
                 </td>
               {/if}
-
               {#each table.columns as column (column.id)}
-                {@const value = getColumnValue(row.original, column)}
-                <td
-                  class={cn(
-                    'px-4 py-3',
-                    getAlignClass(column.align),
-                    column.hideBelow && hideBelowClasses[column.hideBelow]
-                  )}
-                >
-                  {table.getFormattedCellValue(row.original, column)}
+                <td class={cn('px-4 py-3', column.hideBelow && hideBelowClasses[column.hideBelow])}>
+                  <Skeleton class="h-4 w-3/4" />
                 </td>
               {/each}
             </tr>
-          {/if}
-        {/each}
-      {/if}
-    </tbody>
-  </table>
-</div>
+          {/each}
+        {:else if table.rows.length === 0}
+          <tr>
+            <td colspan={columnCount} class="px-4 py-8 text-center text-muted-foreground">
+              {emptyMessage}
+            </td>
+          </tr>
+        {:else}
+          {#each table.rows as row, index (row.id)}
+            {#if rowSnippet}
+              {@render rowSnippet(row.original, index)}
+            {:else}
+              <tr
+                class={cn(
+                  'bg-card',
+                  onRowClick && 'cursor-pointer hover:bg-muted-hover',
+                  row.isSelected && 'bg-primary/5'
+                )}
+                tabindex={onRowClick ? 0 : undefined}
+                onclick={() => handleRowClick(row.original)}
+                onkeydown={onRowClick ? (e) => handleRowKeydown(e, row.original) : undefined}
+              >
+                {#if enableRowSelection}
+                  <td class="px-4 py-3">
+                    {#if canSelectRow(row.original)}
+                      <Checkbox
+                        checked={row.isSelected}
+                        onCheckedChange={() => table.toggleRowSelection(row.id)}
+                        aria-label={`Select row ${index + 1}`}
+                        onclick={(e: MouseEvent) => e.stopPropagation()}
+                      />
+                    {/if}
+                  </td>
+                {/if}
+
+                {#each table.columns as column (column.id)}
+                  {@const value = getColumnValue(row.original, column)}
+                  <td
+                    class={cn(
+                      'px-4 py-3',
+                      getAlignClass(column.align),
+                      column.hideBelow && hideBelowClasses[column.hideBelow]
+                    )}
+                  >
+                    {#if canEdit && column.enableEditing}
+                      <DataTableEditableCell {row} {column} onSave={handleCellEdit} />
+                    {:else}
+                      {table.getFormattedCellValue(row.original, column)}
+                    {/if}
+                  </td>
+                {/each}
+              </tr>
+            {/if}
+          {/each}
+        {/if}
+      </tbody>
+    </table>
+  </div>
+{/if}
 
-{#if enablePagination && !loading && table.rows.length > 0}
+{#if enablePagination && !enableVirtualization && !loading && table.rows.length > 0}
   <!-- Pagination controls -->
   <div class="flex flex-wrap items-center justify-between gap-2 border-t px-4 py-3">
     <div class="text-sm text-muted-foreground">

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

@@ -29,9 +29,9 @@
    * />
    * ```
    */
-import type { Snippet } from 'svelte';
+import { type Snippet } from 'svelte';
 import type { DataTableColumn } from '../types/components.js';
-import type { PaginationState } from './data-table/types.js';
+import type { ColumnFiltersState, PaginationState } from './data-table/types.js';
 declare function $$render<T extends object>(): {
     props: {
         /** Array of data rows */
@@ -54,13 +54,19 @@ declare function $$render<T extends object>(): {
         sortColumn?: string;
         /** Current sort direction */
         sortDirection?: "asc" | "desc";
-        /** Callback when sort changes - when provided, enables server-side sorting */
-        onSort?: (column: string, direction: "asc" | "desc") => void;
+        /**
+         * Callback when sort changes - when provided, enables server-side sorting.
+         * Called with `column: null` when the sort is cleared.
+         */
+        onSort?: (column: string | null, direction: "asc" | "desc") => void;
         /** Callback when row is clicked */
         onRowClick?: (row: T) => void;
         /** Enable row selection - can be boolean or function for per-row control */
         enableRowSelection?: boolean | ((row: T) => boolean);
-        /** Enable multi-row selection (default: true when selection enabled) */
+        /**
+         * Allow more than one selected row (default: true). When false, selecting
+         * a row replaces the previous selection and there is no select-all box.
+         */
         enableMultiRowSelection?: boolean;
         /** Controlled row selection state (Set of row IDs) */
         rowSelection?: Set<string>;
@@ -68,24 +74,33 @@ declare function $$render<T extends object>(): {
         onRowSelectionChange?: (selection: Set<string>) => void;
         /** Function to get unique row ID (defaults to the row's index in `data`) */
         getRowId?: (row: T, index: number) => string;
-        /** Enable column visibility toggling */
+        /** Show a "Columns" menu above the table for hiding and showing columns */
         enableColumnVisibility?: boolean;
         /** Controlled visibility state (Set of hidden column IDs) */
         columnVisibility?: Set<string>;
         /** Callback when visibility changes */
         onColumnVisibilityChange?: (hiddenColumns: Set<string>) => void;
-        /** Enable filtering features */
+        /**
+         * Show a filter row under the header: a text filter per column, or a
+         * faceted (multi-select) filter for columns that define `filterOptions`
+         */
         enableFiltering?: boolean;
-        /** Enable global filter input */
+        /**
+         * Apply `globalFilter` to the rows. No search input is rendered; bind
+         * `globalFilter` to your own input.
+         */
         enableGlobalFilter?: boolean;
         /** Controlled global filter value */
         globalFilter?: string;
         /** Callback when global filter changes */
         onGlobalFilterChange?: (filter: string) => void;
-        /** Controlled column filters */
-        columnFilters?: Map<string, string>;
+        /**
+         * Controlled column filters. A string value is a substring filter; a
+         * string[] value (what the faceted filter sets) matches those values exactly.
+         */
+        columnFilters?: ColumnFiltersState;
         /** Callback when column filters change */
-        onColumnFiltersChange?: (filters: Map<string, string>) => void;
+        onColumnFiltersChange?: (filters: ColumnFiltersState) => void;
         /** Use server-side filtering (manual mode) */
         manualFiltering?: boolean;
         /** Enable built-in pagination */
@@ -100,13 +115,22 @@ declare function $$render<T extends object>(): {
         manualPagination?: boolean;
         /** Total page count (required for server-side pagination) */
         pageCount?: number;
-        /** Enable row virtualization for large datasets (1000+ rows recommended) */
+        /**
+         * Render rows with DataTableVirtual (only the visible rows are in the DOM)
+         * for large datasets (1000+ rows recommended). Pagination, `row` snippets,
+         * `hideBelow`, and inline editing do not apply in this mode.
+         */
         enableVirtualization?: boolean;
+        /** Height of the scrolling body when virtualized (CSS value, default: 500px) */
+        virtualHeight?: string;
         /** Height of each row in pixels for virtualization (default: 48) */
         virtualRowHeight?: number;
         /** Number of rows to render outside the visible viewport (default: 10) */
         virtualOverscan?: number;
-        /** Enable inline cell editing */
+        /**
+         * Enable inline cell editing (DataTableEditableCell) for columns that set
+         * `enableEditing: true`. Requires `onCellEdit`.
+         */
         enableEditing?: boolean;
         /** Callback when a cell is edited */
         onCellEdit?: (rowId: string, columnId: string, value: unknown, row: T) => void;