@urbicon-ui/table 6.1.4

package/dist/core/TableProvider.svelte

@@ -0,0 +1,271 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import { attachTableContext, createTableState } from '..';
+  import { useTableI18n } from '../i18n';
+  import { ColumnValidation } from '../factories/ColumnValidation';
+  import type { Column, TableItem, TableQuery, TableQueryResult } from '../types/tableTypes';
+  import type { SummaryConfig } from '../stores/TableStore.svelte';
+
+  const tt = useTableI18n();
+
+  export type TableProviderProps = {
+    items: TableItem[];
+    columns: Column[];
+    itemsPerPage?: number;
+    initialPage?: number;
+    groupOrder?: string[];
+    groupByKey?: string | null;
+    initialGroupBy?: string | null;
+    initialSummaryConfigs?: SummaryConfig[];
+    multiExpand?: boolean;
+    loading?: boolean;
+    children?: Snippet;
+    persistenceConfig?: {
+      tableId: string;
+      storage?: 'localStorage' | 'sessionStorage';
+      debounceMs?: number;
+      persistFilters?: boolean;
+      persistSearch?: boolean;
+      persistGroupByKey?: boolean;
+      persistSummaryConfigs?: boolean;
+    };
+    mode?: 'client' | 'server';
+    serverTotalItems?: number;
+    queryFn?: (query: TableQuery, options: { signal: AbortSignal }) => Promise<TableQueryResult>;
+    onQueryChange?: (query: TableQuery) => void;
+    queryDebounceMs?: number;
+    enableLiveUpdates?: boolean;
+    autoApplyOnNavigation?: boolean;
+    selectionMode?: 'none' | 'single' | 'multi';
+    selectedIds?: Array<string | number>;
+    onSelectionChange?: (selectedItems: TableItem[]) => void;
+  };
+
+  let {
+    items = [],
+    columns = [],
+    itemsPerPage = 10,
+    initialPage = 1,
+    groupOrder = [],
+    groupByKey = null,
+    initialGroupBy = null,
+    initialSummaryConfigs = [],
+    multiExpand = false,
+    loading = false,
+    children,
+    persistenceConfig,
+    mode = 'client',
+    serverTotalItems = 0,
+    queryFn = undefined,
+    onQueryChange = undefined,
+    queryDebounceMs = 300,
+    enableLiveUpdates = false,
+    autoApplyOnNavigation = true,
+    selectionMode = 'none',
+    selectedIds = undefined,
+    onSelectionChange = undefined
+  }: TableProviderProps = $props();
+
+  const tableState = createTableState(persistenceConfig);
+  attachTableContext(tableState);
+
+  const {
+    state,
+    setItems,
+    setColumns,
+    setLoading,
+    setPage,
+    setItemsPerPage,
+    setGroupByKey,
+    setGroupOrder,
+    setError
+  } = tableState;
+
+  // ── Sync props → store ──
+
+  $effect(() => {
+    if (columns && columns.length > 0) {
+      setColumns(columns);
+      if (import.meta.env?.DEV) {
+        const result = ColumnValidation.validateColumns(columns);
+        if (!result.isValid) {
+          console.warn('[Table] Column validation:', result.errors);
+        }
+      }
+    }
+  });
+
+  if (import.meta.env?.DEV && mode === 'server' && !queryFn && !onQueryChange) {
+    console.warn(
+      '[Table] mode="server" without queryFn or onQueryChange — the table has no way to fetch data.'
+    );
+  }
+
+  $effect(() => {
+    // In server mode, items come from queryFn or external; skip direct sync if queryFn manages it
+    if (items && items.length > 0 && !(mode === 'server' && queryFn)) {
+      setItems(items);
+    }
+  });
+
+  $effect(() => {
+    if (groupOrder && groupOrder.length > 0) {
+      setGroupOrder(groupOrder);
+    }
+  });
+
+  $effect(() => {
+    setItemsPerPage(itemsPerPage);
+  });
+
+  $effect(() => {
+    setPage(initialPage);
+  });
+
+  $effect(() => {
+    state.multiExpand = multiExpand;
+  });
+
+  $effect(() => {
+    state.mode = mode;
+  });
+
+  $effect(() => {
+    if (mode === 'server') {
+      state.serverTotalItems = serverTotalItems;
+    }
+  });
+
+  $effect(() => {
+    state.selectionMode = selectionMode;
+  });
+
+  $effect(() => {
+    if (selectedIds) {
+      tableState.setSelectedIds(selectedIds);
+    }
+  });
+
+  $effect(() => {
+    if (onSelectionChange && state.selectionMode !== 'none') {
+      const selected = tableState.selectedItems;
+      onSelectionChange(selected);
+    }
+  });
+
+  $effect(() => {
+    setLoading(loading);
+  });
+
+  $effect(() => {
+    if (groupByKey) {
+      setGroupByKey(groupByKey);
+    } else if (initialGroupBy && columns && columns.length > 0) {
+      setGroupByKey(initialGroupBy);
+    }
+  });
+
+  $effect(() => {
+    if (
+      initialSummaryConfigs &&
+      initialSummaryConfigs.length > 0 &&
+      state.summaryConfigs.length === 0
+    ) {
+      tableState.setSummaryConfigs(initialSummaryConfigs);
+    }
+  });
+
+  // ── Server mode: queryFn lifecycle ──
+
+  let abortController: AbortController | null = null;
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  let initialFetchDone = false;
+
+  $effect(() => {
+    if (mode !== 'server') return;
+
+    // Track the queryKey to detect changes
+    const currentQueryKey = tableState.queryKey;
+
+    // Debounce: clear previous timer
+    if (debounceTimer) clearTimeout(debounceTimer);
+
+    // For the initial fetch, don't debounce
+    const delay = initialFetchDone ? queryDebounceMs : 0;
+
+    debounceTimer = setTimeout(() => {
+      const currentQuery = tableState.query;
+
+      if (queryFn) {
+        executeManagedFetch(currentQuery);
+      } else if (onQueryChange) {
+        onQueryChange(currentQuery);
+      }
+
+      initialFetchDone = true;
+    }, delay);
+
+    return () => {
+      if (debounceTimer) clearTimeout(debounceTimer);
+    };
+  });
+
+  async function executeManagedFetch(query: TableQuery) {
+    if (!queryFn) return;
+
+    // Cancel previous in-flight request
+    if (abortController) {
+      abortController.abort();
+    }
+
+    abortController = new AbortController();
+    const { signal } = abortController;
+
+    tableState.setServerLoading();
+
+    try {
+      const result = await queryFn(query, { signal });
+
+      // Ignore result if this request was aborted (superseded by a newer one)
+      if (signal.aborted) return;
+
+      tableState.setServerResult(result);
+    } catch (e) {
+      // Don't treat abort as an error
+      if (e instanceof DOMException && e.name === 'AbortError') return;
+      if (signal.aborted) return;
+
+      const message = e instanceof Error ? e.message : tt('error.fetchFailed');
+      tableState.setServerError(message);
+    }
+  }
+
+  // ── Live updates: auto-apply on navigation ──
+  $effect(() => {
+    if (!enableLiveUpdates || !autoApplyOnNavigation) return;
+    if (!tableState.hasPendingUpdates) return;
+
+    // Track navigation state changes
+    void state.currentPage;
+    void state.sortColumn;
+    void state.sortDirection;
+    void state.searchTerm;
+    void state.activeFilters;
+    void state.groupByKey;
+
+    // Auto-apply pending changes when the user navigates (view is already changing)
+    tableState.applyAllUpdates();
+  });
+
+  // Cleanup on component destroy
+  $effect(() => {
+    return () => {
+      if (abortController) abortController.abort();
+      if (debounceTimer) clearTimeout(debounceTimer);
+    };
+  });
+</script>
+
+{#if children}
+  {@render children()}
+{/if}

package/dist/core/TableProvider.svelte.d.ts

@@ -0,0 +1,40 @@
+import type { Snippet } from 'svelte';
+import type { Column, TableItem, TableQuery, TableQueryResult } from '../types/tableTypes';
+import type { SummaryConfig } from '../stores/TableStore.svelte';
+export type TableProviderProps = {
+    items: TableItem[];
+    columns: Column[];
+    itemsPerPage?: number;
+    initialPage?: number;
+    groupOrder?: string[];
+    groupByKey?: string | null;
+    initialGroupBy?: string | null;
+    initialSummaryConfigs?: SummaryConfig[];
+    multiExpand?: boolean;
+    loading?: boolean;
+    children?: Snippet;
+    persistenceConfig?: {
+        tableId: string;
+        storage?: 'localStorage' | 'sessionStorage';
+        debounceMs?: number;
+        persistFilters?: boolean;
+        persistSearch?: boolean;
+        persistGroupByKey?: boolean;
+        persistSummaryConfigs?: boolean;
+    };
+    mode?: 'client' | 'server';
+    serverTotalItems?: number;
+    queryFn?: (query: TableQuery, options: {
+        signal: AbortSignal;
+    }) => Promise<TableQueryResult>;
+    onQueryChange?: (query: TableQuery) => void;
+    queryDebounceMs?: number;
+    enableLiveUpdates?: boolean;
+    autoApplyOnNavigation?: boolean;
+    selectionMode?: 'none' | 'single' | 'multi';
+    selectedIds?: Array<string | number>;
+    onSelectionChange?: (selectedItems: TableItem[]) => void;
+};
+declare const TableProvider: import("svelte").Component<TableProviderProps, {}, "">;
+type TableProvider = ReturnType<typeof TableProvider>;
+export default TableProvider;

package/dist/core/TableRow.svelte

@@ -0,0 +1,171 @@
+<script lang="ts">
+  import {
+    resolveIcon,
+    Checkbox,
+    ChevronDownIcon as ChevronDownIconDefault
+  } from '@urbicon-ui/blocks';
+  import { slide } from 'svelte/transition';
+
+  const ChevronDownIcon = resolveIcon('chevronDown', ChevronDownIconDefault);
+  import { getTableContext } from '../stores/TableStore.svelte';
+  import { useTableI18n } from '../i18n';
+  import { tableRowVariants } from '../variants';
+  import { getTableStyleConfig, resolveSlotClass } from './table-style-context';
+  import TableCell from './TableCell.svelte';
+  import { resolveColumnId } from '../utils';
+  import type { Column, TableItem } from '../types/tableTypes';
+  import type { Snippet } from 'svelte';
+
+  const tt = useTableI18n();
+
+  const tableContext = getTableContext();
+  const { state: tableState, toggleExpand, isItemExpanded } = tableContext;
+  const styleConfig = getTableStyleConfig();
+
+  let selectable = $derived(tableState.selectionMode !== 'none');
+
+  let {
+    item,
+    expandable = false,
+    virtualized = false,
+    virtualIndex = 0,
+    virtualItemHeight = 48,
+    rowIndex = 0,
+    expandedRowContent = undefined as Snippet<[item: TableItem]> | undefined,
+    cell = undefined as Snippet<[item: TableItem, value: unknown, column: Column]> | undefined,
+    onRowClick = undefined as ((item: TableItem) => void) | undefined,
+    size = 'md' as const
+  } = $props();
+
+  let isFocused = $derived(tableContext.isFocusedRow(rowIndex));
+  let interactive = $derived(selectable || expandable || !!onRowClick);
+
+  const itemId = $derived.by((): string | number => {
+    const candidate = item.id ?? item.__index;
+    return typeof candidate === 'string' || typeof candidate === 'number' ? candidate : -1;
+  });
+  let isExpanded = $derived(isItemExpanded(itemId));
+
+  let isRowSelected = $derived(selectable && tableContext.isSelected(itemId));
+  let isRecentlyUpdated = $derived(tableContext.isRecentlyUpdated(itemId));
+
+  const totalColumnsCount = $derived.by(() => {
+    let count = tableState.columns.length;
+    if (tableState.groupByKey) count += 1;
+    if (expandable) count += 1;
+    if (selectable) count += 1;
+    return count;
+  });
+
+  function handleRowClick() {
+    if (onRowClick) {
+      onRowClick(item);
+    }
+    if (expandable) {
+      toggleExpand(itemId);
+    }
+  }
+
+  function handleCheckboxClick(e: MouseEvent) {
+    e.stopPropagation();
+  }
+
+  function handleChevronClick(e: MouseEvent) {
+    e.stopPropagation();
+    if (expandable) {
+      toggleExpand(itemId);
+    }
+  }
+
+  const rowStyles = $derived(
+    tableRowVariants({
+      state: isRowSelected ? 'selected' : isExpanded ? 'expanded' : 'default',
+      size
+    })
+  );
+</script>
+
+<!-- Main row -->
+<tr
+  id={String(itemId)}
+  onclick={handleRowClick}
+  class={resolveSlotClass(
+    rowStyles.row(),
+    styleConfig.slotClasses.row,
+    styleConfig.unstyled,
+    [
+      expandable || onRowClick ? 'cursor-pointer select-none' : '',
+      isRecentlyUpdated
+        ? 'ring-success/30 bg-success-subtle/30 ring-2 transition-[box-shadow,background-color] duration-1000 ring-inset'
+        : ''
+    ]
+      .filter(Boolean)
+      .join(' ')
+  )}
+  style={virtualized
+    ? `position: absolute; transform: translateY(${virtualIndex * virtualItemHeight}px);`
+    : ''}
+  tabindex={interactive ? (isFocused ? 0 : -1) : undefined}
+  aria-rowindex={rowIndex + 1}
+  aria-expanded={expandable ? isExpanded : undefined}
+  aria-selected={selectable ? isRowSelected : undefined}
+  data-row-index={rowIndex}
+  data-testid={`table-row-${itemId}`}
+>
+  {#if selectable}
+    <td class="{rowStyles.cell()} w-12" onclick={handleCheckboxClick}>
+      <div class="flex h-full w-full items-center justify-center">
+        <Checkbox
+          checked={isRowSelected}
+          onchange={() => tableContext.toggleItem(itemId)}
+          aria-label={isRowSelected ? tt('selection.deselectRow') : tt('selection.selectRow')}
+          size="sm"
+          data-testid={`selection-checkbox-${itemId}`}
+        />
+      </div>
+    </td>
+  {/if}
+
+  {#if expandable}
+    <td class="{rowStyles.cell()} w-10">
+      <div class="flex h-full w-full items-center justify-center px-2 py-2">
+        <button
+          class="table-expand-button rounded-modify flex h-6 w-6 items-center justify-center transition-transform duration-(--blocks-duration-fast) {isExpanded
+            ? 'rotate-180'
+            : ''}"
+          onclick={handleChevronClick}
+          aria-label={isExpanded ? tt('actions.hideDetails') : tt('actions.showDetails')}
+          data-testid={`expand-button-${itemId}`}
+        >
+          <ChevronDownIcon class="h-4 w-4" />
+        </button>
+      </div>
+    </td>
+  {/if}
+
+  {#each tableContext.orderedColumns as column, colIdx (resolveColumnId(column))}
+    <TableCell
+      {item}
+      {column}
+      {cell}
+      {size}
+      colIndex={colIdx}
+      cellClass={resolveSlotClass(
+        rowStyles.cell(),
+        styleConfig.slotClasses.cell,
+        styleConfig.unstyled
+      )}
+      testIdPrefix="cell"
+    />
+  {/each}
+</tr>
+
+{#if isExpanded && expandedRowContent}
+  <tr data-testid={`expanded-row-${itemId}`} class="border-b-0">
+    <td colspan={totalColumnsCount} class="p-0">
+      <div class="bg-surface-elevated/50 px-6 py-4" transition:slide={{ duration: 150 }}>
+        {@render expandedRowContent(item)}
+      </div>
+    </td>
+  </tr>
+{/if}

package/dist/core/TableRow.svelte.d.ts

@@ -0,0 +1,16 @@
+import type { Column, TableItem } from '../types/tableTypes';
+import type { Snippet } from 'svelte';
+declare const TableRow: import("svelte").Component<{
+    item: any;
+    expandable?: boolean;
+    virtualized?: boolean;
+    virtualIndex?: number;
+    virtualItemHeight?: number;
+    rowIndex?: number;
+    expandedRowContent?: Snippet<[item: TableItem]> | undefined;
+    cell?: Snippet<[item: TableItem, value: unknown, column: Column]> | undefined;
+    onRowClick?: ((item: TableItem) => void) | undefined;
+    size?: const;
+}, {}, "">;
+type TableRow = ReturnType<typeof TableRow>;
+export default TableRow;

package/dist/core/index.d.ts

@@ -0,0 +1,17 @@
+export type { EmptyStateProps } from './EmptyState.svelte';
+export { default as EmptyState } from './EmptyState.svelte';
+export type { ErrorStateProps } from './ErrorState.svelte';
+export { default as ErrorState } from './ErrorState.svelte';
+export type { GroupedRowProps } from './GroupedRow.svelte';
+export { default as GroupedRow } from './GroupedRow.svelte';
+export type { LoadingStateProps } from './LoadingState.svelte';
+export { default as LoadingState } from './LoadingState.svelte';
+export type { MobileCardProps } from './MobileCard.svelte';
+export { default as MobileCard } from './MobileCard.svelte';
+export type { TableCellProps } from './TableCell.svelte';
+export { default as TableCell } from './TableCell.svelte';
+export { default as TableHead } from './TableHead.svelte';
+export type { TableProviderProps } from './TableProvider.svelte';
+export { default as TableProvider } from './TableProvider.svelte';
+export { default as TableRow } from './TableRow.svelte';
+export { default as Table } from './table/Table.svelte';

package/dist/core/index.js

@@ -0,0 +1,14 @@
+// Core table components
+// State components
+export { default as EmptyState } from './EmptyState.svelte';
+export { default as ErrorState } from './ErrorState.svelte';
+// Advanced components
+export { default as GroupedRow } from './GroupedRow.svelte';
+export { default as LoadingState } from './LoadingState.svelte';
+// Mobile components
+export { default as MobileCard } from './MobileCard.svelte';
+export { default as TableCell } from './TableCell.svelte';
+export { default as TableHead } from './TableHead.svelte';
+export { default as TableProvider } from './TableProvider.svelte';
+export { default as TableRow } from './TableRow.svelte';
+export { default as Table } from './table/Table.svelte';

package/dist/core/sticky-context.svelte.d.ts

@@ -0,0 +1,48 @@
+export type StickyProp = boolean | 'toolbar' | 'header' | 'both';
+export interface StickyMode {
+    /** Sticky toolbar (L1) enabled */
+    toolbar: boolean;
+    /** Sticky thead (L2) enabled */
+    header: boolean;
+    /** Sticky group-header (L3) enabled */
+    group: boolean;
+}
+/**
+ * Resolve the `sticky` prop to a per-layer mode.
+ *
+ * | Prop value      | toolbar | header | group |
+ * |-----------------|---------|--------|-------|
+ * | `false` (def.)  | ❌      | ❌     | ❌    |
+ * | `true` / `'both'` | ✅    | ✅     | ✅    |
+ * | `'toolbar'`     | ✅      | ❌     | ❌    |
+ * | `'header'`      | ❌      | ✅     | ✅    |
+ *
+ * Note: `'header'` enables group-header pinning too, because the group-header
+ * is part of the "header" semantic (the contextual section marker).
+ *
+ * When `contained` is set (`fit="viewport"`), the table is its own scroll box:
+ * the header + group header always pin to the top of the box and the toolbar is
+ * a static flex sibling (never page-pinned), so `contained` supersedes the
+ * `sticky` prop entirely.
+ */
+export declare function resolveStickyMode(sticky: StickyProp | undefined, contained?: boolean): StickyMode;
+export interface StickyContext {
+    readonly mode: StickyMode;
+    /** Whether the toolbar is currently in its pinned state (sentinel out of view) */
+    readonly toolbarStuck: boolean;
+    /** Whether the thead is currently in its pinned state */
+    readonly headerStuck: boolean;
+    setToolbarStuck(value: boolean): void;
+    setHeaderStuck(value: boolean): void;
+}
+declare const setStickyContext: any;
+export { setStickyContext };
+export declare function getStickyContext(): StickyContext;
+/**
+ * Reactive state holder for the sticky context. Backed by `$state` so child
+ * components see live updates of `toolbarStuck` / `headerStuck`.
+ *
+ * `getMode` is a getter so that switching the `sticky` prop at runtime
+ * propagates to all sub-components without re-creating the context.
+ */
+export declare function createStickyState(getMode: () => StickyMode): StickyContext;

package/dist/core/sticky-context.svelte.js

@@ -0,0 +1,88 @@
+/**
+ * STICKY-PINNING CONTEXT
+ *
+ * Shared state for the three Table sticky layers (toolbar, thead, group-header).
+ * - Sets the resolved `StickyMode` derived from the `sticky` prop.
+ * - Tracks `toolbarStuck` / `headerStuck` so child components can mirror the
+ *   "stuck" data-attribute for the box-shadow + border accent.
+ *
+ * Background: docs/STICKY-PINNING.md
+ */
+import { createOptionalContext } from '@urbicon-ui/blocks';
+/**
+ * Resolve the `sticky` prop to a per-layer mode.
+ *
+ * | Prop value      | toolbar | header | group |
+ * |-----------------|---------|--------|-------|
+ * | `false` (def.)  | ❌      | ❌     | ❌    |
+ * | `true` / `'both'` | ✅    | ✅     | ✅    |
+ * | `'toolbar'`     | ✅      | ❌     | ❌    |
+ * | `'header'`      | ❌      | ✅     | ✅    |
+ *
+ * Note: `'header'` enables group-header pinning too, because the group-header
+ * is part of the "header" semantic (the contextual section marker).
+ *
+ * When `contained` is set (`fit="viewport"`), the table is its own scroll box:
+ * the header + group header always pin to the top of the box and the toolbar is
+ * a static flex sibling (never page-pinned), so `contained` supersedes the
+ * `sticky` prop entirely.
+ */
+export function resolveStickyMode(sticky, contained = false) {
+    if (contained) {
+        return { toolbar: false, header: true, group: true };
+    }
+    if (sticky === true || sticky === 'both') {
+        return { toolbar: true, header: true, group: true };
+    }
+    if (sticky === 'toolbar') {
+        return { toolbar: true, header: false, group: false };
+    }
+    if (sticky === 'header') {
+        return { toolbar: false, header: true, group: true };
+    }
+    return { toolbar: false, header: false, group: false };
+}
+const [getStickyContextRaw, setStickyContext] = createOptionalContext();
+export { setStickyContext };
+/**
+ * Off-tree default (used by sub-components rendered outside a `<Table>` wrapper
+ * — e.g. when consumers compose `<TableHead>` directly).
+ */
+const OFF = {
+    mode: { toolbar: false, header: false, group: false },
+    toolbarStuck: false,
+    headerStuck: false,
+    setToolbarStuck: () => { },
+    setHeaderStuck: () => { }
+};
+export function getStickyContext() {
+    return getStickyContextRaw() ?? OFF;
+}
+/**
+ * Reactive state holder for the sticky context. Backed by `$state` so child
+ * components see live updates of `toolbarStuck` / `headerStuck`.
+ *
+ * `getMode` is a getter so that switching the `sticky` prop at runtime
+ * propagates to all sub-components without re-creating the context.
+ */
+export function createStickyState(getMode) {
+    let toolbarStuck = $state(false);
+    let headerStuck = $state(false);
+    return {
+        get mode() {
+            return getMode();
+        },
+        get toolbarStuck() {
+            return toolbarStuck;
+        },
+        get headerStuck() {
+            return headerStuck;
+        },
+        setToolbarStuck(value) {
+            toolbarStuck = value;
+        },
+        setHeaderStuck(value) {
+            headerStuck = value;
+        }
+    };
+}