@urbicon-ui/table 6.1.4

package/dist/stores/concerns/useLiveUpdates.svelte.js

@@ -0,0 +1,175 @@
+import { SvelteMap, SvelteSet } from 'svelte/reactivity';
+import { normalizeItems } from '../../utils';
+function pickRowId(item) {
+    const id = item.id ?? item.__index;
+    return typeof id === 'string' || typeof id === 'number' ? id : undefined;
+}
+/**
+ * Live updates concern: manages a pending buffer of inserts, updates, and deletes
+ * that are NOT immediately applied to the visible table.
+ *
+ * Instead, the UI shows a notification (e.g. "3 new, 2 updated") and the user
+ * decides when to merge them. This avoids disorienting UX issues like rows
+ * jumping, disappearing, or conflicting with active selection/editing.
+ *
+ * @param state - Shared table state (items are modified on apply).
+ */
+export function useLiveUpdates(state) {
+    let inserts = $state([]);
+    let updates = $state([]);
+    let deletes = new SvelteSet();
+    /** IDs of rows that were recently updated (for visual highlight). Auto-cleared after timeout. */
+    let recentlyUpdatedIds = new SvelteSet();
+    let highlightTimer = null;
+    const counts = $derived({
+        inserts: inserts.length,
+        updates: updates.length,
+        deletes: deletes.size,
+        total: inserts.length + updates.length + deletes.size
+    });
+    const hasPending = $derived(counts.total > 0);
+    // ── Push methods (called by the developer from WebSocket/SSE/Polling) ──
+    function pushInsert(item) {
+        // Deduplicate: if an item with the same ID is already pending, replace it
+        const id = pickRowId(item);
+        if (id !== undefined) {
+            inserts = inserts.filter((i) => pickRowId(i) !== id);
+        }
+        inserts = [...inserts, item];
+    }
+    function pushUpdate(id, changes) {
+        // Merge with existing pending update for the same ID
+        const existing = updates.findIndex((u) => u.id === id);
+        if (existing >= 0) {
+            updates[existing] = { id, changes: { ...updates[existing].changes, ...changes } };
+            updates = [...updates]; // trigger reactivity
+        }
+        else {
+            updates = [...updates, { id, changes }];
+        }
+    }
+    function pushDelete(id) {
+        const next = new SvelteSet(deletes);
+        next.add(id);
+        deletes = next;
+        // If the item was pending insert, remove it from inserts instead
+        const pendingInsertIdx = inserts.findIndex((i) => pickRowId(i) === id);
+        if (pendingInsertIdx >= 0) {
+            inserts = inserts.filter((_, idx) => idx !== pendingInsertIdx);
+            // Also remove from deletes since it was never in items
+            const cleaned = new SvelteSet(deletes);
+            cleaned.delete(id);
+            deletes = cleaned;
+        }
+    }
+    // ── Apply methods (merge pending changes into state.items) ──
+    function applyAll() {
+        applyDeletes();
+        applyUpdates();
+        applyInserts();
+    }
+    function applyInserts() {
+        if (inserts.length === 0)
+            return;
+        state.items = normalizeItems([...state.items, ...inserts]);
+        inserts = [];
+    }
+    function applyUpdates() {
+        if (updates.length === 0)
+            return;
+        const updateMap = new SvelteMap(updates.map((u) => [u.id, u.changes]));
+        const updatedIds = new SvelteSet(updateMap.keys());
+        state.items = state.items.map((item) => {
+            const id = pickRowId(item);
+            if (id !== undefined && updateMap.has(id)) {
+                updatedIds.delete(id);
+                return { ...item, ...updateMap.get(id) };
+            }
+            return item;
+        });
+        if (import.meta.env?.DEV && updatedIds.size > 0) {
+            console.warn(`[Table] Live update: ${updatedIds.size} orphaned ID(s) not found in items:`, [
+                ...updatedIds
+            ]);
+        }
+        // Mark as recently updated for visual highlight
+        startHighlight(new SvelteSet(updateMap.keys()));
+        updates = [];
+    }
+    function applyDeletes() {
+        if (deletes.size === 0)
+            return;
+        const deletedIds = new SvelteSet(deletes);
+        state.items = state.items.filter((item) => {
+            const id = pickRowId(item);
+            if (id !== undefined && deletedIds.has(id)) {
+                deletedIds.delete(id);
+                return false;
+            }
+            return true;
+        });
+        if (import.meta.env?.DEV && deletedIds.size > 0) {
+            console.warn(`[Table] Live delete: ${deletedIds.size} orphaned ID(s) not found in items:`, [
+                ...deletedIds
+            ]);
+        }
+        // Also remove from selection if selected
+        if (state.selectionMode !== 'none' && state.selectedIds.size > 0) {
+            const nextSelected = new SvelteSet(state.selectedIds);
+            for (const id of deletes) {
+                nextSelected.delete(id);
+            }
+            state.selectedIds = nextSelected;
+        }
+        deletes = new SvelteSet();
+    }
+    function dismissAll() {
+        inserts = [];
+        updates = [];
+        deletes = new SvelteSet();
+    }
+    // ── Highlight management ──
+    function startHighlight(ids) {
+        recentlyUpdatedIds = new SvelteSet([...recentlyUpdatedIds, ...ids]);
+        if (highlightTimer)
+            clearTimeout(highlightTimer);
+        highlightTimer = setTimeout(() => {
+            recentlyUpdatedIds = new SvelteSet();
+            highlightTimer = null;
+        }, 3000);
+    }
+    function isRecentlyUpdated(id) {
+        return recentlyUpdatedIds.has(id);
+    }
+    /** Check if an item is pending deletion (for strikethrough/fade indicator). */
+    function isPendingDelete(id) {
+        return deletes.has(id);
+    }
+    return {
+        get counts() {
+            return counts;
+        },
+        get hasPending() {
+            return hasPending;
+        },
+        get pendingInserts() {
+            return inserts;
+        },
+        get pendingUpdates() {
+            return updates;
+        },
+        get pendingDeletes() {
+            return deletes;
+        },
+        pushInsert,
+        pushUpdate,
+        pushDelete,
+        applyAll,
+        applyInserts,
+        applyUpdates,
+        applyDeletes,
+        dismissAll,
+        isRecentlyUpdated,
+        isPendingDelete
+    };
+}

package/dist/stores/concerns/usePagination.svelte.d.ts

@@ -0,0 +1,18 @@
+import type { TableItem } from '../../types/tableTypes';
+import type { TableState } from './types';
+/**
+ * Pagination concern: manages page state and computes paginated items.
+ * In server mode, items are already paginated by the server — this concern
+ * only computes `totalItems`/`totalPages` from `serverTotalItems`.
+ * @param state - Shared table state.
+ * @param getFilteredItems - Getter for filtered items (client mode: local count).
+ * @param getSortedItems - Getter for upstream sorted items.
+ */
+export declare function usePagination(state: TableState, getFilteredItems: () => TableItem[], getSortedItems: () => TableItem[]): {
+    readonly totalItems: number;
+    readonly totalPages: number;
+    readonly paginatedItems: TableItem[];
+    setPage: (page: number) => void;
+    goToPage: (page: number) => void;
+    setItemsPerPage: (count: number) => void;
+};

package/dist/stores/concerns/usePagination.svelte.js

@@ -0,0 +1,54 @@
+/**
+ * Pagination concern: manages page state and computes paginated items.
+ * In server mode, items are already paginated by the server — this concern
+ * only computes `totalItems`/`totalPages` from `serverTotalItems`.
+ * @param state - Shared table state.
+ * @param getFilteredItems - Getter for filtered items (client mode: local count).
+ * @param getSortedItems - Getter for upstream sorted items.
+ */
+export function usePagination(state, getFilteredItems, getSortedItems) {
+    const totalItems = $derived(state.mode === 'server' ? state.serverTotalItems : getFilteredItems().length);
+    const totalPages = $derived.by(() => {
+        if (state.groupByKey)
+            return 1;
+        if (totalItems === 0)
+            return 1;
+        return Math.ceil(totalItems / state.itemsPerPage);
+    });
+    const paginatedItems = $derived.by(() => {
+        const items = getSortedItems();
+        // In server mode, items are already paginated by the server
+        if (state.mode === 'server')
+            return items;
+        // Skip pagination when grouped (groups should be fully visible)
+        if (state.groupByKey)
+            return items;
+        return items.slice((state.currentPage - 1) * state.itemsPerPage, state.currentPage * state.itemsPerPage);
+    });
+    function setPage(page) {
+        state.currentPage = page;
+    }
+    function goToPage(page) {
+        if (page >= 1 && page <= totalPages) {
+            state.currentPage = page;
+        }
+    }
+    function setItemsPerPage(count) {
+        state.itemsPerPage = count;
+        state.currentPage = 1;
+    }
+    return {
+        get totalItems() {
+            return totalItems;
+        },
+        get totalPages() {
+            return totalPages;
+        },
+        get paginatedItems() {
+            return paginatedItems;
+        },
+        setPage,
+        goToPage,
+        setItemsPerPage
+    };
+}

package/dist/stores/concerns/usePersistence.svelte.d.ts

@@ -0,0 +1,36 @@
+import type { TablePersistenceConfig } from '../TableStore.svelte';
+import type { TableState } from './types';
+/**
+ * Persistence concern: manages syncing table state to/from storage.
+ *
+ * State on the shared `state` object (search, filters, group, summary,
+ * sort) is hydrated directly here before downstream concerns initialise.
+ * State that lives inside other concerns (column visibility, column
+ * order) cannot be reached from here — those values are exposed via the
+ * `initialHiddenColumnIds` / `initialColumnOrder` getters so the host
+ * `TableStore` can hand them back to the owning concern after init.
+ *
+ * Mutating concerns call the matching `sync*` function after each
+ * mutation; `usePersistence` debounces the write to storage internally
+ * (default 500 ms, configurable via `persistenceConfig.debounceMs`).
+ */
+export declare function usePersistence(state: TableState, persistenceConfig?: TablePersistenceConfig): {
+    syncFilters: () => void;
+    syncSearch: () => void;
+    syncGroupByKey: () => void;
+    syncSummaryConfigs: () => void;
+    syncSortState: () => void;
+    syncHiddenColumns: (hiddenIds: string[]) => void;
+    syncColumnOrder: (order: string[]) => void;
+    readonly initialHiddenColumnIds: string[];
+    readonly initialColumnOrder: string[];
+    clearPersistedFilters: () => void | undefined;
+    clearPersistedSearchTerm: () => void | undefined;
+    clearPersistedGroupByKey: () => void | undefined;
+    clearPersistedSummaryConfigs: () => void | undefined;
+    clearPersistedSortState: () => void | undefined;
+    clearPersistedHiddenColumns: () => void | undefined;
+    clearPersistedColumnOrder: () => void | undefined;
+    clearAllPersistentData: () => void;
+    forceSavePersistentData: () => void;
+};

package/dist/stores/concerns/usePersistence.svelte.js

@@ -0,0 +1,167 @@
+import { createPersistentColumnOrder, createPersistentFilters, createPersistentGroupByKey, createPersistentHiddenColumns, createPersistentSearchTerm, createPersistentSortState, createPersistentSummaryConfigs } from '../../utils';
+/**
+ * Persistence concern: manages syncing table state to/from storage.
+ *
+ * State on the shared `state` object (search, filters, group, summary,
+ * sort) is hydrated directly here before downstream concerns initialise.
+ * State that lives inside other concerns (column visibility, column
+ * order) cannot be reached from here — those values are exposed via the
+ * `initialHiddenColumnIds` / `initialColumnOrder` getters so the host
+ * `TableStore` can hand them back to the owning concern after init.
+ *
+ * Mutating concerns call the matching `sync*` function after each
+ * mutation; `usePersistence` debounces the write to storage internally
+ * (default 500 ms, configurable via `persistenceConfig.debounceMs`).
+ */
+export function usePersistence(state, persistenceConfig) {
+    let persistentFilters;
+    let persistentSearchTerm;
+    let persistentGroupByKey;
+    let persistentSummaryConfigs;
+    let persistentSortState;
+    let persistentHiddenColumns;
+    let persistentColumnOrder;
+    if (persistenceConfig) {
+        if (persistenceConfig.persistFilters !== false) {
+            persistentFilters = createPersistentFilters({
+                tableId: persistenceConfig.tableId,
+                storage: persistenceConfig.storage,
+                debounceMs: persistenceConfig.debounceMs
+            });
+            if (persistentFilters.value.length > 0) {
+                state.activeFilters = persistentFilters.value;
+            }
+        }
+        if (persistenceConfig.persistSearch !== false) {
+            persistentSearchTerm = createPersistentSearchTerm({
+                tableId: persistenceConfig.tableId,
+                storage: persistenceConfig.storage,
+                debounceMs: persistenceConfig.debounceMs
+            });
+            if (persistentSearchTerm.value) {
+                state.searchTerm = persistentSearchTerm.value;
+            }
+        }
+        if (persistenceConfig.persistGroupByKey !== false) {
+            persistentGroupByKey = createPersistentGroupByKey({
+                tableId: persistenceConfig.tableId,
+                storage: persistenceConfig.storage,
+                debounceMs: persistenceConfig.debounceMs
+            });
+            if (persistentGroupByKey.value) {
+                state.groupByKey = persistentGroupByKey.value;
+            }
+        }
+        if (persistenceConfig.persistSummaryConfigs !== false) {
+            persistentSummaryConfigs = createPersistentSummaryConfigs({
+                tableId: persistenceConfig.tableId,
+                storage: persistenceConfig.storage,
+                debounceMs: persistenceConfig.debounceMs
+            });
+            if (persistentSummaryConfigs.value.length > 0) {
+                state.summaryConfigs = persistentSummaryConfigs.value;
+                state.showSummary = true;
+            }
+        }
+        if (persistenceConfig.persistSort !== false) {
+            persistentSortState = createPersistentSortState({
+                tableId: persistenceConfig.tableId,
+                storage: persistenceConfig.storage,
+                debounceMs: persistenceConfig.debounceMs
+            });
+            if (persistentSortState.value.column) {
+                state.sortColumn = persistentSortState.value.column;
+                state.sortDirection = persistentSortState.value.direction;
+            }
+        }
+        if (persistenceConfig.persistColumnVisibility !== false) {
+            persistentHiddenColumns = createPersistentHiddenColumns({
+                tableId: persistenceConfig.tableId,
+                storage: persistenceConfig.storage,
+                debounceMs: persistenceConfig.debounceMs
+            });
+        }
+        if (persistenceConfig.persistColumnOrder !== false) {
+            persistentColumnOrder = createPersistentColumnOrder({
+                tableId: persistenceConfig.tableId,
+                storage: persistenceConfig.storage,
+                debounceMs: persistenceConfig.debounceMs
+            });
+        }
+    }
+    // Sync functions called by other concerns after mutations
+    function syncFilters() {
+        if (persistentFilters)
+            persistentFilters.value = state.activeFilters;
+    }
+    function syncSearch() {
+        if (persistentSearchTerm)
+            persistentSearchTerm.value = state.searchTerm;
+    }
+    function syncGroupByKey() {
+        if (persistentGroupByKey)
+            persistentGroupByKey.value = state.groupByKey;
+    }
+    function syncSummaryConfigs() {
+        if (persistentSummaryConfigs)
+            persistentSummaryConfigs.value = state.summaryConfigs;
+    }
+    function syncSortState() {
+        if (persistentSortState)
+            persistentSortState.value = {
+                column: state.sortColumn,
+                direction: state.sortDirection
+            };
+    }
+    function syncHiddenColumns(hiddenIds) {
+        if (persistentHiddenColumns)
+            persistentHiddenColumns.value = hiddenIds;
+    }
+    function syncColumnOrder(order) {
+        if (persistentColumnOrder)
+            persistentColumnOrder.value = order;
+    }
+    // Public API
+    function clearAllPersistentData() {
+        persistentFilters?.reset();
+        persistentSearchTerm?.reset();
+        persistentGroupByKey?.reset();
+        persistentSummaryConfigs?.reset();
+        persistentSortState?.reset();
+        persistentHiddenColumns?.reset();
+        persistentColumnOrder?.reset();
+    }
+    function forceSavePersistentData() {
+        persistentFilters?.forceSave();
+        persistentSearchTerm?.forceSave();
+        persistentGroupByKey?.forceSave();
+        persistentSummaryConfigs?.forceSave();
+        persistentSortState?.forceSave();
+        persistentHiddenColumns?.forceSave();
+        persistentColumnOrder?.forceSave();
+    }
+    return {
+        syncFilters,
+        syncSearch,
+        syncGroupByKey,
+        syncSummaryConfigs,
+        syncSortState,
+        syncHiddenColumns,
+        syncColumnOrder,
+        get initialHiddenColumnIds() {
+            return persistentHiddenColumns?.value ?? [];
+        },
+        get initialColumnOrder() {
+            return persistentColumnOrder?.value ?? [];
+        },
+        clearPersistedFilters: () => persistentFilters?.reset(),
+        clearPersistedSearchTerm: () => persistentSearchTerm?.reset(),
+        clearPersistedGroupByKey: () => persistentGroupByKey?.reset(),
+        clearPersistedSummaryConfigs: () => persistentSummaryConfigs?.reset(),
+        clearPersistedSortState: () => persistentSortState?.reset(),
+        clearPersistedHiddenColumns: () => persistentHiddenColumns?.reset(),
+        clearPersistedColumnOrder: () => persistentColumnOrder?.reset(),
+        clearAllPersistentData,
+        forceSavePersistentData
+    };
+}

package/dist/stores/concerns/useRemoteData.svelte.d.ts

@@ -0,0 +1,21 @@
+import type { TableItem, TableQuery } from '../../types/tableTypes';
+import type { TableState } from './types';
+/**
+ * Remote data concern: derives the current query state for server-side fetching.
+ *
+ * This concern does NOT fetch data itself (keeping the store synchronous).
+ * Instead, it exposes a reactive `query` object and `setServerResult()` for
+ * the component layer to drive the async lifecycle.
+ *
+ * @param state - Shared table state.
+ */
+export declare function useRemoteData(state: TableState): {
+    readonly query: TableQuery;
+    readonly queryKey: string;
+    setServerResult: (result: {
+        items: TableItem[];
+        totalItems: number;
+    }) => void;
+    setServerError: (error: string) => void;
+    setServerLoading: () => void;
+};

package/dist/stores/concerns/useRemoteData.svelte.js

@@ -0,0 +1,64 @@
+/**
+ * Remote data concern: derives the current query state for server-side fetching.
+ *
+ * This concern does NOT fetch data itself (keeping the store synchronous).
+ * Instead, it exposes a reactive `query` object and `setServerResult()` for
+ * the component layer to drive the async lifecycle.
+ *
+ * @param state - Shared table state.
+ */
+export function useRemoteData(state) {
+    /**
+     * Current query derived from table state.
+     * Changes reactively when any filter/sort/page/search state changes.
+     */
+    const query = $derived.by(() => ({
+        page: state.currentPage,
+        itemsPerPage: state.itemsPerPage,
+        sortColumn: state.sortColumn,
+        sortDirection: state.sortDirection,
+        searchTerm: state.searchTerm,
+        activeFilters: [...state.activeFilters],
+        groupByKey: state.groupByKey
+    }));
+    /**
+     * Serialized query string for change detection.
+     * Allows `$effect` to trigger only when the query actually changes.
+     */
+    const queryKey = $derived(JSON.stringify(query));
+    /**
+     * Apply server result to the table state.
+     * Called by the component layer when `queryFn` resolves or when
+     * the developer provides new items in manual mode.
+     */
+    function setServerResult(result) {
+        state.items = result.items;
+        state.serverTotalItems = result.totalItems;
+        state.loading = false;
+        state.error = null;
+    }
+    /**
+     * Set server-side error state.
+     */
+    function setServerError(error) {
+        state.loading = false;
+        state.error = error;
+    }
+    /**
+     * Set loading state (used before fetch).
+     */
+    function setServerLoading() {
+        state.loading = true;
+    }
+    return {
+        get query() {
+            return query;
+        },
+        get queryKey() {
+            return queryKey;
+        },
+        setServerResult,
+        setServerError,
+        setServerLoading
+    };
+}

package/dist/stores/concerns/useSearch.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { TableState } from './types';
+/**
+ * Search concern: manages search term and advanced search toggle.
+ */
+export declare function useSearch(state: TableState): {
+    setSearchTerm: (term: string) => void;
+    toggleAdvancedSearch: () => void;
+};

package/dist/stores/concerns/useSearch.svelte.js

@@ -0,0 +1,16 @@
+/**
+ * Search concern: manages search term and advanced search toggle.
+ */
+export function useSearch(state) {
+    function setSearchTerm(term) {
+        state.searchTerm = term;
+        state.currentPage = 1;
+    }
+    function toggleAdvancedSearch() {
+        state.showAdvancedSearch = !state.showAdvancedSearch;
+    }
+    return {
+        setSearchTerm,
+        toggleAdvancedSearch
+    };
+}

package/dist/stores/concerns/useSelection.svelte.d.ts

@@ -0,0 +1,21 @@
+import type { TableItem } from '../../types/tableTypes';
+import type { TableState } from './types';
+/**
+ * Selection concern: manages row selection state.
+ * Supports single-select and multi-select modes.
+ * @param state - Shared table state.
+ * @param getFilteredItems - Getter for filtered items (used for selectAll scope).
+ */
+export declare function useSelection(state: TableState, getFilteredItems: () => TableItem[]): {
+    readonly selectedItems: TableItem[];
+    readonly allSelected: boolean;
+    readonly someSelected: boolean;
+    selectItem: (id: string | number) => void;
+    deselectItem: (id: string | number) => void;
+    toggleItem: (id: string | number) => void;
+    selectAll: () => void;
+    deselectAll: () => void;
+    toggleAll: () => void;
+    isSelected: (id: string | number) => boolean;
+    setSelectedIds: (ids: Array<string | number>) => void;
+};