@shotleybuilder/svelte-table-kit 0.2.0 → 0.5.0

package/README.md

@@ -19,10 +19,11 @@ Svelte Table Kit brings Airtable-like functionality to your Svelte applications
 - ↔️ **Column spacing control** - 3 sizes: narrow, normal, wide
 - 🔍 **Advanced filtering** - 12 operators with AND/OR logic
 - 📊 **Multi-level grouping** - Up to 3 nested levels (like Airtable)
-- ⬆️ Multi-column sorting with visual indicators
+- ⬆️ **Flexible sorting** - Column header or Airtable-style sort control
 - 📄 Pagination with customizable page sizes
 - 💾 LocalStorage persistence for all user preferences
 - ✂️ Text truncation with ellipsis for long content
+- 📋 **Column context menu** - Quick access to sort, filter, group, and hide actions
 
 **Advanced Filtering:**
 - 12 filter operators: equals, contains, starts with, greater than, etc.
@@ -31,6 +32,13 @@ Svelte Table Kit brings Airtable-like functionality to your Svelte applications
 - Active filter count badge
 - Real-time filtering as you type
 
+**Sorting Options:**
+- **Column header mode** (default) - Click headers to sort with ↑↓↕ indicators
+- **Airtable-style control** - Dedicated sort dropdown with multi-level sorting
+- Choose column and direction (A → Z or Z → A)
+- Multiple sort levels applied top to bottom
+- Collapsible SortBar UI
+
 **Grouping & Hierarchy:**
 - Group by up to 3 columns simultaneously
 - Expand/collapse groups with chevron buttons
@@ -38,6 +46,15 @@ Svelte Table Kit brings Airtable-like functionality to your Svelte applications
 - Item count per group
 - Collapsible GroupBar UI
 
+**Column Context Menu:**
+- Hover over column headers to reveal menu trigger (chevron icon)
+- **Sort A → Z / Sort Z → A** - Quick sort with active state indication
+- **Filter by this field** - Creates pre-filled filter condition
+- **Group by this field** - Adds column to grouping configuration
+- **Hide field** - Remove column from view
+- Actions conditionally shown based on feature flags
+- Seamlessly integrates with existing controls
+
 **Developer Experience:**
 - 🎨 Headless design - style it your way
 - 📦 Built on TanStack Table v8 (battle-tested, powerful)
@@ -49,6 +66,7 @@ Svelte Table Kit brings Airtable-like functionality to your Svelte applications
 **AI-Ready:**
 - 🤖 JSON-schema driven configuration
 - 🧠 AI agents can generate table configs from natural language
+- ⚡ **Reactive config prop** - Update table state dynamically without remounting (v0.5.0+)
 - 📋 Preset configurations for common use cases
 - 🔧 Programmatic table setup and state management
 
@@ -107,19 +125,30 @@ The simplest way to use TableKit:
 
 ### With Configuration
 
-Use AI-generated or predefined configurations:
+Customize initial table state programmatically:
 
 ```svelte
 <script>
-  import { TableKit, presets } from '@shotleybuilder/svelte-table-kit';
-
-  const config = presets.dashboard; // or generate with AI
+  import { TableKit } from '@shotleybuilder/svelte-table-kit';
 </script>
 
 <TableKit
   {data}
   {columns}
-  {config}
+  config={{
+    id: 'my-view-v1',
+    version: '1.0',
+    defaultColumnOrder: ['name', 'role', 'age', 'id'],
+    defaultColumnSizing: { name: 200, role: 150 },
+    defaultVisibleColumns: ['name', 'role', 'age'],
+    defaultFilters: [
+      { id: 'f1', field: 'role', operator: 'equals', value: 'Developer' }
+    ],
+    defaultSorting: [
+      { columnId: 'name', direction: 'asc' }
+    ],
+    filterLogic: 'and'
+  }}
   features={{
     columnVisibility: true,
     filtering: true,
@@ -129,6 +158,66 @@ Use AI-generated or predefined configurations:
 />
 ```
 
+### Reactive Configuration (v0.5.0+)
+
+**The `config` prop is fully reactive** - update it dynamically to change table state without remounting:
+
+```svelte
+<script>
+  import { TableKit } from '@shotleybuilder/svelte-table-kit';
+
+  let tableConfig = $state({
+    id: 'query-1',
+    version: '1.0',
+    defaultFilters: [
+      { id: 'f1', field: 'status', operator: 'equals', value: 'active' }
+    ]
+  });
+
+  // Update config - table reacts automatically
+  function showPendingItems() {
+    tableConfig = {
+      id: 'query-2',  // New ID triggers update
+      version: '1.0',
+      defaultFilters: [
+        { id: 'f1', field: 'status', operator: 'equals', value: 'pending' }
+      ]
+    };
+  }
+</script>
+
+<button on:click={showPendingItems}>Show Pending</button>
+<TableKit {data} {columns} config={tableConfig} persistState={false} />
+```
+
+**Perfect for AI-driven tables:**
+
+```svelte
+<script>
+  let aiConfig = $state(undefined);
+
+  async function askAI(question) {
+    const response = await fetch('/api/nl-query', {
+      method: 'POST',
+      body: JSON.stringify({ question })
+    });
+    aiConfig = await response.json();  // Table updates automatically
+  }
+</script>
+
+<input
+  placeholder="Ask a question about the data..."
+  on:submit={(e) => askAI(e.target.value)}
+/>
+<TableKit {data} {columns} config={aiConfig} persistState={false} />
+```
+
+**Key Points:**
+- Config changes detected by comparing `config.id`
+- Set `persistState={false}` to prevent localStorage conflicts
+- When config is active, localStorage is automatically ignored
+- No `{#key}` blocks needed - updates are smooth and instant
+
 ### Feature Flags
 
 Control which features are enabled:
@@ -143,6 +232,7 @@ Control which features are enabled:
     columnReordering: true,
     filtering: true,
     sorting: true,
+    sortingMode: 'control',  // 'header' (default) or 'control' (Airtable-style)
     pagination: true,
     rowSelection: false,
     grouping: false
@@ -150,6 +240,10 @@ Control which features are enabled:
 />
 ```
 
+**Sorting Modes:**
+- `sortingMode: 'header'` - Click column headers to sort (default behavior)
+- `sortingMode: 'control'` - Use Airtable-style sort dropdown with multi-level support
+
 ### Event Handlers
 
 Listen to table events:
@@ -201,10 +295,10 @@ TableKit is headless by default. You can:
 |------|------|---------|-------------|
 | `data` | `T[]` | `[]` | Table data array |
 | `columns` | `ColumnDef<T>[]` | `[]` | Column definitions |
-| `config` | `TableConfig` | `undefined` | AI-generated or preset config |
+| `config` | `TableConfig` | `undefined` | Reactive table configuration (requires `id` and `version`) |
 | `features` | `TableFeatures` | All enabled | Feature flags |
 | `storageKey` | `string` | `undefined` | LocalStorage key for persistence |
-| `persistState` | `boolean` | `true` | Enable state persistence |
+| `persistState` | `boolean` | `true` | Enable state persistence (auto-disabled when config is active) |
 | `theme` | `'light' \| 'dark' \| 'auto'` | `'light'` | Theme mode |
 | `align` | `'left' \| 'center' \| 'right'` | `'left'` | Column text alignment |
 | `rowHeight` | `'short' \| 'medium' \| 'tall' \| 'extra_tall'` | `'medium'` | Row height preset |
@@ -213,6 +307,25 @@ TableKit is headless by default. You can:
 | `onRowSelect` | `(rows: T[]) => void` | `undefined` | Row selection handler |
 | `onStateChange` | `(state: TableState) => void` | `undefined` | State change handler |
 
+### TableConfig Type
+
+```typescript
+interface TableConfig {
+  id: string;                              // Required: Unique identifier for change detection
+  version: string;                         // Required: Config version
+  defaultColumnOrder?: string[];           // Column IDs in display order
+  defaultColumnSizing?: Record<string, number>;  // Column widths in pixels
+  defaultVisibleColumns?: string[];        // Visible column IDs (others hidden)
+  defaultFilters?: FilterCondition[];      // Initial filter conditions
+  defaultSorting?: SortConfig[];           // Initial sort configuration
+  filterLogic?: 'and' | 'or';              // Filter combination logic
+  pagination?: {
+    pageSize: number;
+    pageSizeOptions?: number[];
+  };
+}
+```
+
 ---
 
 ## 🎯 Use Cases

package/dist/TableKit.svelte

@@ -23,8 +23,11 @@ import {
 import { applyFilters } from "./utils/filters";
 import FilterBar from "./components/FilterBar.svelte";
 import GroupBar from "./components/GroupBar.svelte";
+import SortBar from "./components/SortBar.svelte";
+import ColumnMenu from "./components/ColumnMenu.svelte";
 export let data = [];
 export let columns = [];
+export let config = void 0;
 export let storageKey = "table-kit";
 export let persistState = true;
 export let align = "left";
@@ -36,38 +39,123 @@ export let features = {
   columnReordering: true,
   filtering: true,
   sorting: true,
+  sortingMode: "header",
+  // 'header' or 'control'
   pagination: true
 };
 export let onRowClick = void 0;
 export let onRowSelect = void 0;
 export let onStateChange = void 0;
 let sorting = writable([]);
-let columnVisibility = writable(
-  persistState && storageKey ? loadColumnVisibility(storageKey) : {}
-);
-let columnSizing = writable(
-  persistState && storageKey ? loadColumnSizing(storageKey) : {}
-);
-let columnFilters = writable(
-  persistState && storageKey ? loadColumnFilters(storageKey) : []
-);
-let columnOrder = writable(
-  persistState && storageKey ? loadColumnOrder(storageKey) : []
-);
+let columnVisibility = writable({});
+let columnSizing = writable({});
+let columnFilters = writable([]);
+let columnOrder = writable([]);
 let filterConditions = writable([]);
 let filterLogic = writable("and");
+let filterBarExpanded = false;
+let previousConfigId = config?.id;
+let configInitialized = false;
 let grouping = writable([]);
 let expanded = writable(true);
+let groupBarExpanded = false;
+$: {
+  const configChanged = config?.id && config.id !== previousConfigId;
+  const hasConfig = config !== void 0 && config !== null;
+  if (hasConfig && config && (configChanged || !configInitialized)) {
+    if (config.defaultColumnOrder && config.defaultColumnOrder.length > 0) {
+      columnOrder.set(config.defaultColumnOrder);
+    }
+    if (config.defaultVisibleColumns && columns.length > 0) {
+      const visibilityMap = {};
+      columns.forEach((col) => {
+        const colId = col.accessorKey || col.id;
+        if (config && config.defaultVisibleColumns) {
+          visibilityMap[colId] = config.defaultVisibleColumns.includes(colId);
+        }
+      });
+      columnVisibility.set(visibilityMap);
+    }
+    if (config.defaultSorting) {
+      sorting.set(config.defaultSorting);
+    }
+    if (config.defaultFilters) {
+      filterConditions.set(config.defaultFilters);
+    }
+    if (config.filterLogic) {
+      filterLogic.set(config.filterLogic);
+    }
+    if (config.defaultColumnSizing) {
+      columnSizing.set(config.defaultColumnSizing);
+    }
+    previousConfigId = config.id;
+    configInitialized = true;
+  } else if (!hasConfig && persistState && storageKey && !configInitialized) {
+    columnOrder.set(loadColumnOrder(storageKey) || []);
+    columnVisibility.set(loadColumnVisibility(storageKey) || {});
+    columnSizing.set(loadColumnSizing(storageKey) || {});
+    columnFilters.set(loadColumnFilters(storageKey) || []);
+    configInitialized = true;
+  } else if (!hasConfig && !configInitialized) {
+    configInitialized = true;
+  }
+}
 $: horizontalPadding = columnSpacing === "narrow" ? 0.5 : columnSpacing === "wide" ? 2 : 1;
 $: verticalPadding = rowHeight === "short" ? 0.375 : rowHeight === "tall" ? 1 : rowHeight === "extra_tall" ? 1.5 : 0.75;
 $: filteredData = applyFilters(data, $filterConditions, $filterLogic);
-$: if (persistState && storageKey && isBrowser) {
-  saveColumnVisibility(storageKey, $columnVisibility);
-  saveColumnSizing(storageKey, $columnSizing);
-  saveColumnFilters(storageKey, $columnFilters);
-  saveColumnOrder(storageKey, $columnOrder);
+$: {
+  const hasActiveConfig = config !== void 0 && config !== null;
+  const shouldPersist = persistState && !hasActiveConfig && storageKey && isBrowser;
+  if (shouldPersist) {
+    saveColumnVisibility(storageKey, $columnVisibility);
+    saveColumnSizing(storageKey, $columnSizing);
+    saveColumnFilters(storageKey, $columnFilters);
+    saveColumnOrder(storageKey, $columnOrder);
+  }
 }
 let showColumnPicker = false;
+let columnPickerButton = null;
+let columnPickerPosition = { top: 0, left: 0 };
+let openColumnMenuId = null;
+function generateFilterId() {
+  return `filter-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+}
+function addFilterForColumn(columnId) {
+  const newCondition = {
+    id: generateFilterId(),
+    field: columnId,
+    operator: "equals",
+    value: ""
+  };
+  filterConditions.update((conditions) => [...conditions, newCondition]);
+  filterBarExpanded = true;
+}
+function addGroupForColumn(columnId) {
+  grouping.update((groups) => {
+    if (groups.includes(columnId)) {
+      return groups;
+    }
+    if (groups.length >= 3) {
+      return groups;
+    }
+    return [...groups, columnId];
+  });
+  groupBarExpanded = true;
+}
+function updateColumnPickerPosition() {
+  if (columnPickerButton && showColumnPicker) {
+    const rect = columnPickerButton.getBoundingClientRect();
+    columnPickerPosition = {
+      top: rect.bottom + 8,
+      // 8px margin (0.5rem)
+      left: rect.right - 224
+      // 224px = 14rem dropdown width
+    };
+  }
+}
+$: if (showColumnPicker) {
+  updateColumnPickerPosition();
+}
 let showRowHeightMenu = false;
 let showColumnSpacingMenu = false;
 let draggedColumnId = null;
@@ -194,6 +282,7 @@ $: if ($columnOrder.length === 0 && columns.length > 0) {
   columnOrder.set(columns.map((col) => col.accessorKey || col.id));
 }
 $: hasActiveFilters = $filterConditions.length > 0;
+$: totalTableWidth = $table.getVisibleLeafColumns().reduce((sum, col) => sum + col.getSize(), 0);
 $: if (onStateChange) {
   onStateChange({
     columnVisibility: $columnVisibility,
@@ -208,7 +297,7 @@ $: if (onStateChange) {
 
 <div class="table-kit-container align-{align}">
 	<!-- Filters and Controls -->
-	{#if features.filtering !== false || features.grouping !== false || features.columnVisibility !== false}
+	{#if features.filtering !== false || features.grouping !== false || features.columnVisibility !== false || (features.sorting !== false && features.sortingMode === 'control')}
 		<div class="table-kit-toolbar">
 			<!-- Filter Controls -->
 			{#if features.filtering !== false}
@@ -219,6 +308,19 @@ $: if (onStateChange) {
 						onConditionsChange={(newConditions) => filterConditions.set(newConditions)}
 						logic={$filterLogic}
 						onLogicChange={(newLogic) => filterLogic.set(newLogic)}
+						isExpanded={filterBarExpanded}
+						onExpandedChange={(expanded) => (filterBarExpanded = expanded)}
+					/>
+				</div>
+			{/if}
+
+			<!-- Sort Controls (when sortingMode is 'control') -->
+			{#if features.sorting !== false && features.sortingMode === 'control'}
+				<div class="table-kit-sorts">
+					<SortBar
+						{columns}
+						sorting={$sorting}
+						onSortingChange={(newSorting) => sorting.set(newSorting)}
 					/>
 				</div>
 			{/if}
@@ -230,6 +332,8 @@ $: if (onStateChange) {
 						{columns}
 						grouping={$grouping}
 						onGroupingChange={(newGrouping) => grouping.set(newGrouping)}
+						isExpanded={groupBarExpanded}
+						onExpandedChange={(expanded) => (groupBarExpanded = expanded)}
 					/>
 				</div>
 			{/if}
@@ -405,6 +509,7 @@ $: if (onStateChange) {
 				<div class="table-kit-column-picker">
 					<div class="relative">
 						<button
+							bind:this={columnPickerButton}
 							on:click={() => (showColumnPicker = !showColumnPicker)}
 							class="column-picker-btn"
 						>
@@ -423,7 +528,10 @@ $: if (onStateChange) {
 							<!-- svelte-ignore a11y-click-events-have-key-events -->
 							<!-- svelte-ignore a11y-no-static-element-interactions -->
 							<div class="backdrop" on:click={() => (showColumnPicker = false)} />
-							<div class="column-picker-dropdown">
+							<div
+								class="column-picker-dropdown"
+								style="top: {columnPickerPosition.top}px; left: {columnPickerPosition.left}px;"
+							>
 								<div class="dropdown-header">
 									<span>Toggle Columns</span>
 									<div class="header-actions">
@@ -465,7 +573,7 @@ $: if (onStateChange) {
 		</div>
 	{:else}
 		<div class="table-kit-scroll">
-			<table class="table-kit-table">
+			<table class="table-kit-table" style="width: {totalTableWidth}px;">
 				<thead>
 					{#each $table.getHeaderGroups() as headerGroup}
 						<tr>
@@ -477,34 +585,97 @@ $: if (onStateChange) {
 									style="width: {header.getSize()}px;"
 								>
 									{#if !header.isPlaceholder}
-										<div
-											class="th-content"
-											style="padding: {verticalPadding}rem {horizontalPadding}rem; cursor: {features.columnReordering !==
-											false
-												? 'grab'
-												: 'default'};"
-											draggable={features.columnReordering !== false}
-											on:dragstart={() => handleDragStart(header.column.id)}
-										>
-											<button
-												class="sort-btn"
-												class:sortable={header.column.getCanSort()}
-												on:click={header.column.getToggleSortingHandler()}
+										<div class="th-wrapper">
+											<div
+												class="th-content"
+												style="padding: {verticalPadding}rem {horizontalPadding}rem; cursor: {features.columnReordering !==
+												false
+													? 'grab'
+													: 'default'};"
+												draggable={features.columnReordering !== false}
+												on:dragstart={() => handleDragStart(header.column.id)}
 											>
-												<span class="header-text">
-													<svelte:component
-														this={flexRender(header.column.columnDef.header, header.getContext())}
-													/>
-												</span>
-												{#if features.sorting !== false && header.column.getCanSort()}
-													<span class="sort-icon">
-														{{
-															asc: '↑',
-															desc: '↓'
-														}[header.column.getIsSorted()] ?? '↕'}
+												{#if features.sorting !== false && features.sortingMode !== 'control' && header.column.getCanSort()}
+													<button
+														class="sort-btn"
+														class:sortable={header.column.getCanSort()}
+														on:click={header.column.getToggleSortingHandler()}
+													>
+														<span class="header-text">
+															<svelte:component
+																this={flexRender(header.column.columnDef.header, header.getContext())}
+															/>
+														</span>
+														<span class="sort-icon">
+															{{
+																asc: '↑',
+																desc: '↓'
+															}[header.column.getIsSorted()] ?? '↕'}
+														</span>
+													</button>
+												{:else}
+													<span class="header-text">
+														<svelte:component
+															this={flexRender(header.column.columnDef.header, header.getContext())}
+														/>
 													</span>
 												{/if}
-											</button>
+
+												<!-- Column Menu Trigger -->
+												<button
+													class="column-menu-trigger"
+													on:click|stopPropagation={() => {
+														openColumnMenuId =
+															openColumnMenuId === header.column.id ? null : header.column.id;
+													}}
+													aria-label="Column options"
+												>
+													<svg
+														width="12"
+														height="12"
+														viewBox="0 0 12 12"
+														fill="none"
+														xmlns="http://www.w3.org/2000/svg"
+													>
+														<path
+															d="M3 5L6 8L9 5"
+															stroke="currentColor"
+															stroke-width="1.5"
+															stroke-linecap="round"
+															stroke-linejoin="round"
+														/>
+													</svg>
+												</button>
+											</div>
+
+											<!-- Column Menu -->
+											<ColumnMenu
+												column={header.column}
+												isOpen={openColumnMenuId === header.column.id}
+												canSort={features.sorting !== false}
+												canFilter={features.filtering !== false}
+												canGroup={features.grouping !== false}
+												on:sort={(e) => {
+													const direction = e.detail.direction;
+													header.column.toggleSorting(direction === 'desc');
+													openColumnMenuId = null;
+												}}
+												on:filter={() => {
+													addFilterForColumn(header.column.id);
+													openColumnMenuId = null;
+												}}
+												on:group={() => {
+													addGroupForColumn(header.column.id);
+													openColumnMenuId = null;
+												}}
+												on:hide={() => {
+													header.column.toggleVisibility(false);
+													openColumnMenuId = null;
+												}}
+												on:close={() => {
+													openColumnMenuId = null;
+												}}
+											/>
 										</div>
 										<!-- Resize Handle -->
 										{#if features.columnResizing !== false && header.column.getCanResize()}
@@ -822,9 +993,9 @@ $: if (onStateChange) {
 	}
 
 	.column-picker-dropdown {
-		position: absolute;
-		right: 0;
-		z-index: 20;
+		position: fixed; /* Use fixed to break out of container constraints */
+		right: auto;
+		z-index: 30;
 		margin-top: 0.5rem;
 		width: 14rem;
 		border-radius: 0.375rem;
@@ -871,7 +1042,8 @@ $: if (onStateChange) {
 	}
 
 	.column-list {
-		max-height: 16rem;
+		min-height: 12rem; /* Ensure picker stays usable even when all columns hidden */
+		max-height: 20rem;
 		overflow-y: auto;
 	}
 
@@ -910,9 +1082,9 @@ $: if (onStateChange) {
 	}
 
 	.table-kit-table {
-		width: auto;
 		border-collapse: collapse;
 		table-layout: fixed;
+		min-width: 100%; /* Ensure table is at least full container width */
 	}
 
 	thead {
@@ -1006,6 +1178,39 @@ $: if (onStateChange) {
 		color: #9ca3af;
 	}
 
+	.th-wrapper {
+		position: relative;
+		display: flex;
+		align-items: center;
+		width: 100%;
+	}
+
+	.column-menu-trigger {
+		flex-shrink: 0;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		padding: 0.25rem;
+		margin-left: 0.25rem;
+		background: transparent;
+		border: none;
+		border-radius: 0.25rem;
+		cursor: pointer;
+		color: #9ca3af;
+		transition: all 0.15s;
+		opacity: 0;
+	}
+
+	.th-wrapper:hover .column-menu-trigger,
+	.column-menu-trigger:focus {
+		opacity: 1;
+	}
+
+	.column-menu-trigger:hover {
+		background-color: #f3f4f6;
+		color: #374151;
+	}
+
 	.resize-handle {
 		position: absolute;
 		top: 0;

package/dist/TableKit.svelte.d.ts

@@ -5,6 +5,7 @@ declare class __sveltets_Render<T> {
     props(): {
         data?: T[] | undefined;
         columns?: ColumnDef<T>[] | undefined;
+        config?: TableKitProps<T_1>["config"];
         storageKey?: TableKitProps<T_1>["storageKey"];
         persistState?: TableKitProps<T_1>["persistState"];
         align?: TableKitProps<T_1>["align"];