@urbicon-ui/table 6.1.4

package/dist/utils/index.js

@@ -0,0 +1,330 @@
+import { createPersistentState } from '@urbicon-ui/blocks';
+/**
+ * Retrieves a nested value from an object using dot notation
+ * e.g. getNestedValue(user, 'address.city')
+ */
+export function getNestedValue(item, key) {
+    if (!item || !key)
+        return undefined;
+    const keys = key.split('.');
+    let value = item;
+    for (const k of keys) {
+        if (value === undefined || value === null)
+            return undefined;
+        value = value[k];
+    }
+    return value;
+}
+/**
+ * Resolves the stable identifier of a column. Mirrors the discriminated
+ * union shape from `tableTypes.ts`:
+ *
+ * - string accessor → defaults to `accessor` if `id` is omitted
+ * - function accessor → `id` is required
+ * - synthetic column → `id` is required
+ *
+ * Throws when neither `id` nor a string `accessor` is present — this
+ * combination can only occur when a caller bypasses the type system, and
+ * returning a sentinel (e.g. empty string) would silently corrupt the
+ * filter/sort/group/visibility state that targets columns by id.
+ */
+export function resolveColumnId(column) {
+    if (column.id !== undefined && column.id !== '')
+        return column.id;
+    // DataColumnString fallback: id defaults to the accessor string.
+    if (typeof column.accessor === 'string' && column.accessor !== '')
+        return column.accessor;
+    throw new Error('Column has no resolvable id. Provide `id` for function-accessor or synthetic columns, or a non-empty string `accessor`.');
+}
+/**
+ * Resolves the human-readable label of a column for use in table chrome
+ * (column-visibility menu, header menu, filter/grouping/summary menus).
+ *
+ * Resolution order: `menuTitle` → `title` → humanized column id. The last
+ * step guarantees a non-empty label even for icon-only columns
+ * (`{ id: 'actions', title: '' }` → "Actions") so menu entries never render
+ * blank. Header cells render `title` verbatim on purpose — an empty header
+ * is a deliberate design choice, an empty menu entry is not.
+ */
+export function resolveColumnLabel(column) {
+    return column.menuTitle || column.title || humanizeColumnId(resolveColumnId(column));
+}
+/**
+ * Turns a column id into a readable Title-Case label: splits camelCase,
+ * kebab-case, snake_case and dot-paths into words and capitalizes each
+ * (`quickActions` / `quick-actions` / `quick_actions` → "Quick Actions").
+ */
+function humanizeColumnId(id) {
+    return id
+        .replace(/([a-z\d])([A-Z])/g, '$1 $2')
+        .split(/[-_.\s]+/)
+        .filter(Boolean)
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(' ');
+}
+/**
+ * Resolves the canonical value of a cell — the single source of truth that
+ * search, sort, group, summary and the default cell renderer all read from.
+ * Display via `cell`/`component`/`formatter` is decoupled and may transform
+ * this value further for rendering, but the derived operations always
+ * operate on the accessor's output.
+ *
+ * - string accessor → property lookup (dot-paths supported via `getNestedValue`)
+ * - function accessor → invoke with the item
+ * - synthetic column (no accessor) → `undefined`
+ */
+export function resolveColumnValue(column, item) {
+    if (typeof column.accessor === 'function') {
+        return column.accessor(item);
+    }
+    if (typeof column.accessor === 'string') {
+        return getNestedValue(item, column.accessor);
+    }
+    return undefined;
+}
+/**
+ * Looks up a column from the table's column list by its resolved id.
+ * Returns `undefined` when no column matches — used by concerns that
+ * keep only the id in their state (filters, sort, group, summary).
+ */
+export function findColumnById(columns, id) {
+    return columns.find((col) => resolveColumnId(col) === id);
+}
+/**
+ * Resolves a column's value by its id, falling back to a raw nested-key
+ * lookup when no matching column is registered. The fallback preserves the
+ * pre-2.0 behaviour for transient state (e.g. persisted filters that
+ * reference a column which has since been removed from the definition).
+ */
+export function resolveValueById(columns, item, id) {
+    const column = findColumnById(columns, id);
+    if (column)
+        return resolveColumnValue(column, item);
+    return getNestedValue(item, id);
+}
+/**
+ * Formats a cell value based on the column definition. The displayed value
+ * starts from the accessor's output — `formatter` then has a chance to
+ * transform it into a presentation string.
+ */
+export function formatCellValue(item, column) {
+    const value = resolveColumnValue(column, item);
+    // Use custom formatter when available
+    if (column.formatter) {
+        // The discriminated union narrows `formatter`'s value parameter to
+        // either `unknown` (string accessor / synthetic) or the function's
+        // return type V. Cast through `never` to bridge that to a callable
+        // signature without losing the runtime narrowing above.
+        const formatted = column.formatter(value, item);
+        if (formatted !== null)
+            return formatted;
+    }
+    // Default formatting based on data type
+    if (value === undefined || value === null)
+        return '';
+    if (typeof value === 'boolean') {
+        return value ? 'Yes' : 'No';
+    }
+    if (value instanceof Date) {
+        if (Number.isNaN(value.getTime()))
+            return 'Invalid Date';
+        return value.toLocaleDateString();
+    }
+    return String(value);
+}
+/**
+ * Groups items by a column-id, routing the lookup through {@link resolveValueById}
+ * so that function-accessor columns aggregate the computed value (not the
+ * non-existent property of the same name). Returns `{ ungrouped: items }`
+ * when no group id is provided.
+ */
+export function groupItems(items, columns, groupByKey) {
+    if (!groupByKey)
+        return { ungrouped: items };
+    const grouped = {};
+    for (const item of items) {
+        const groupValue = resolveValueById(columns, item, groupByKey);
+        const groupKey = groupValue !== undefined && groupValue !== null ? String(groupValue) : 'Unassigned';
+        if (!grouped[groupKey]) {
+            grouped[groupKey] = [];
+        }
+        grouped[groupKey].push(item);
+    }
+    return grouped;
+}
+/**
+ * Normalizes items for table consumption. Items without an `id` property
+ * get an `__index` assigned as stable fallback key.
+ */
+export function normalizeItems(items) {
+    return items.map((item, i) => (item.id !== undefined ? item : { ...item, __index: i }));
+}
+/**
+ * Resolves the ID of an item
+ */
+export function getItemId(item) {
+    if (!item)
+        return -1;
+    if (item.id !== undefined)
+        return item.id;
+    if (item.ID !== undefined)
+        return item.ID;
+    if (item._id !== undefined)
+        return item._id;
+    return -1;
+}
+/**
+ * Computes aggregate summary values for a set of items given summary configs.
+ * Extracted from the store for testability.
+ *
+ * The optional `getValue` resolver lets callers supply a column-aware lookup
+ * (typically `(item, id) => resolveValueById(state.columns, item, id)`) so
+ * that summary aggregations honour function accessors and computed values.
+ * When omitted, the legacy `getNestedValue` fallback is used — sufficient
+ * for primitive property keys and required by the standalone unit tests.
+ */
+export function calculateSummary(items, configs, getValue = (item, columnId) => getNestedValue(item, columnId)) {
+    const result = {};
+    configs.forEach((config) => {
+        const values = items
+            .map((item) => getValue(item, config.column))
+            .filter((value) => {
+            if (value === undefined || value === null || value === '')
+                return false;
+            if (['sum', 'avg', 'min', 'max'].includes(config.type)) {
+                return !Number.isNaN(Number(value));
+            }
+            return true;
+        });
+        if (config.type === 'count') {
+            result[config.column] = values.length;
+        }
+        else if (values.length === 0) {
+            result[config.column] = NaN;
+        }
+        else {
+            switch (config.type) {
+                case 'sum':
+                    result[config.column] = values.reduce((s, val) => s + Number(val ?? 0), 0);
+                    break;
+                case 'avg': {
+                    const total = values.reduce((s, val) => s + Number(val ?? 0), 0);
+                    result[config.column] = total / values.length;
+                    break;
+                }
+                case 'min':
+                    result[config.column] = Math.min(...values.map((v) => Number(v)));
+                    break;
+                case 'max':
+                    result[config.column] = Math.max(...values.map((v) => Number(v)));
+                    break;
+                default:
+                    result[config.column] = NaN;
+            }
+        }
+    });
+    return result;
+}
+/**
+ * Tests whether a single item value matches a filter condition.
+ */
+export function matchesFilter(itemValue, filterValue, operator) {
+    const value = itemValue.toLowerCase();
+    const filter = filterValue.toLowerCase();
+    switch (operator) {
+        case 'contains':
+            return value.includes(filter);
+        case 'equals':
+            return value === filter;
+        case 'startsWith':
+            return value.startsWith(filter);
+        case 'endsWith':
+            return value.endsWith(filter);
+        case 'greaterThan':
+            return Number(value) > Number(filter);
+        case 'lessThan':
+            return Number(value) < Number(filter);
+        default:
+            if (import.meta.env?.DEV)
+                console.warn(`[Table] Unknown filter operator "${operator}" — row excluded.`);
+            return false;
+    }
+}
+/**
+ * Splits text into segments based on a search term, marking matching parts as highlighted.
+ * Used by SearchHighlight to render matches without {@html} (XSS-safe).
+ */
+export function splitSearchSegments(text, searchTerm) {
+    if (!searchTerm || !text)
+        return [{ text, highlighted: false }];
+    const escaped = searchTerm.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const regex = new RegExp(`(${escaped})`, 'gi');
+    const parts = text.split(regex);
+    return parts
+        .filter((part) => part !== '')
+        .map((part) => ({
+        text: part,
+        highlighted: part.toLowerCase() === searchTerm.toLowerCase()
+    }));
+}
+export function createPersistentFilters(config) {
+    return createPersistentState({
+        key: `table_filters_${config.tableId}`,
+        defaultValue: [],
+        storage: config.storage || 'localStorage',
+        debounceMs: config.debounceMs || 500
+    });
+}
+/**
+ * Specialized hook for search term persistence
+ */
+export function createPersistentSearchTerm(config) {
+    return createPersistentState({
+        key: `table_search_${config.tableId}`,
+        defaultValue: '',
+        storage: config.storage || 'localStorage',
+        debounceMs: config.debounceMs || 500
+    });
+}
+export function createPersistentGroupByKey(config) {
+    return createPersistentState({
+        key: `table_group_by_${config.tableId}`,
+        defaultValue: null,
+        storage: config.storage || 'localStorage',
+        debounceMs: config.debounceMs || 500
+    });
+}
+export function createPersistentSummaryConfigs(config) {
+    return createPersistentState({
+        key: `table_summary_configs_${config.tableId}`,
+        defaultValue: [],
+        storage: config.storage || 'localStorage',
+        debounceMs: config.debounceMs || 500
+    });
+}
+export function createPersistentSortState(config) {
+    return createPersistentState({
+        key: `table_sort_${config.tableId}`,
+        defaultValue: { column: '', direction: 'asc' },
+        storage: config.storage || 'localStorage',
+        debounceMs: config.debounceMs || 500
+    });
+}
+export function createPersistentHiddenColumns(config) {
+    return createPersistentState({
+        key: `table_hidden_columns_${config.tableId}`,
+        defaultValue: [],
+        storage: config.storage || 'localStorage',
+        debounceMs: config.debounceMs || 500
+    });
+}
+export function createPersistentColumnOrder(config) {
+    return createPersistentState({
+        key: `table_column_order_${config.tableId}`,
+        defaultValue: [],
+        storage: config.storage || 'localStorage',
+        debounceMs: config.debounceMs || 500
+    });
+}
+// Sticky-pinning measurement helpers
+export { measureToCssVar, measureViewportOffsetTop, observeStuck } from './sticky-measure';

package/dist/utils/sticky-measure.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `{@attach}` factory that observes the height of an element with `ResizeObserver`
+ * and writes it to a CSS custom property on a target element.
+ *
+ * The target defaults to the closest ancestor matching `[data-table-container]`,
+ * which is the outer container set by `Table.svelte`. This keeps the three
+ * sticky-pinning layers (toolbar, thead, group-header) reading from the same
+ * coordinate origin.
+ *
+ * @example
+ * ```svelte
+ * <div {@attach measureToCssVar('--blocks-table-toolbar-h')}>
+ *   ...toolbar...
+ * </div>
+ * ```
+ */
+export declare function measureToCssVar(property: string, targetSelector?: string): (element: HTMLElement) => () => void;
+/**
+ * `{@attach}` factory that measures an element's distance from the top of the
+ * document (`getBoundingClientRect().top + scrollY`) and writes it to a CSS
+ * custom property on the closest `[data-table-container]` (the element itself
+ * when attached to the container).
+ *
+ * Used by `fit="viewport"` to size the contained scroll box via
+ * `max-height: calc(100dvh - <offset>)`. The offset is measured
+ * document-relative — i.e. invariant under page scroll — so re-measuring can
+ * never feed back into the page's own scroll position. It re-measures on
+ * viewport resize and when content *above* the table reflows (observed via the
+ * document body, whose height tracks the document flow).
+ *
+ * Offsets *inside* the container (e.g. a growing toolbar / filter chips) do NOT
+ * change this value and are absorbed by the flex layout instead.
+ *
+ * @example
+ * ```svelte
+ * <div data-table-container {@attach measureViewportOffsetTop('--blocks-table-avail-top')}>
+ *   ...
+ * </div>
+ * ```
+ */
+export declare function measureViewportOffsetTop(property: string, targetSelector?: string): (element: HTMLElement) => () => void;
+/**
+ * `{@attach}` factory that toggles `data-stuck` on an element based on whether
+ * a sentinel placed just above it is visible.
+ *
+ * The sentinel is the previous-sibling element with the `data-sticky-sentinel`
+ * attribute. When the sentinel scrolls out of view (intersectionRatio = 0),
+ * the element is considered "stuck" and the callback fires with `true`.
+ *
+ * @param onStuck callback receiving the latest stuck-state
+ * @param rootMarginTop CSS rootMargin top offset (negative pixel string), used
+ *   to fire the stuck transition exactly at the pin line (sticky-top).
+ */
+export declare function observeStuck(onStuck: (stuck: boolean) => void, rootMarginTop?: string): (element: HTMLElement) => (() => void) | undefined;

package/dist/utils/sticky-measure.js

@@ -0,0 +1,107 @@
+/**
+ * `{@attach}` factory that observes the height of an element with `ResizeObserver`
+ * and writes it to a CSS custom property on a target element.
+ *
+ * The target defaults to the closest ancestor matching `[data-table-container]`,
+ * which is the outer container set by `Table.svelte`. This keeps the three
+ * sticky-pinning layers (toolbar, thead, group-header) reading from the same
+ * coordinate origin.
+ *
+ * @example
+ * ```svelte
+ * <div {@attach measureToCssVar('--blocks-table-toolbar-h')}>
+ *   ...toolbar...
+ * </div>
+ * ```
+ */
+export function measureToCssVar(property, targetSelector = '[data-table-container]') {
+    return (element) => {
+        const target = element.closest(targetSelector) ?? element;
+        const apply = (height) => {
+            target.style.setProperty(property, `${Math.round(height)}px`);
+        };
+        apply(element.getBoundingClientRect().height);
+        const observer = new ResizeObserver((entries) => {
+            for (const entry of entries) {
+                apply(entry.contentRect.height);
+            }
+        });
+        observer.observe(element);
+        return () => {
+            observer.disconnect();
+            target.style.removeProperty(property);
+        };
+    };
+}
+/**
+ * `{@attach}` factory that measures an element's distance from the top of the
+ * document (`getBoundingClientRect().top + scrollY`) and writes it to a CSS
+ * custom property on the closest `[data-table-container]` (the element itself
+ * when attached to the container).
+ *
+ * Used by `fit="viewport"` to size the contained scroll box via
+ * `max-height: calc(100dvh - <offset>)`. The offset is measured
+ * document-relative — i.e. invariant under page scroll — so re-measuring can
+ * never feed back into the page's own scroll position. It re-measures on
+ * viewport resize and when content *above* the table reflows (observed via the
+ * document body, whose height tracks the document flow).
+ *
+ * Offsets *inside* the container (e.g. a growing toolbar / filter chips) do NOT
+ * change this value and are absorbed by the flex layout instead.
+ *
+ * @example
+ * ```svelte
+ * <div data-table-container {@attach measureViewportOffsetTop('--blocks-table-avail-top')}>
+ *   ...
+ * </div>
+ * ```
+ */
+export function measureViewportOffsetTop(property, targetSelector = '[data-table-container]') {
+    return (element) => {
+        const target = element.closest(targetSelector) ?? element;
+        const apply = () => {
+            const offset = element.getBoundingClientRect().top + window.scrollY;
+            target.style.setProperty(property, `${Math.max(0, Math.round(offset))}px`);
+        };
+        apply();
+        // `resize` covers viewport changes; observing the body covers reflow of
+        // content above the table (tabs, banners) that shifts the container down.
+        const observer = new ResizeObserver(apply);
+        observer.observe(document.body);
+        window.addEventListener('resize', apply);
+        return () => {
+            observer.disconnect();
+            window.removeEventListener('resize', apply);
+            target.style.removeProperty(property);
+        };
+    };
+}
+/**
+ * `{@attach}` factory that toggles `data-stuck` on an element based on whether
+ * a sentinel placed just above it is visible.
+ *
+ * The sentinel is the previous-sibling element with the `data-sticky-sentinel`
+ * attribute. When the sentinel scrolls out of view (intersectionRatio = 0),
+ * the element is considered "stuck" and the callback fires with `true`.
+ *
+ * @param onStuck callback receiving the latest stuck-state
+ * @param rootMarginTop CSS rootMargin top offset (negative pixel string), used
+ *   to fire the stuck transition exactly at the pin line (sticky-top).
+ */
+export function observeStuck(onStuck, rootMarginTop = '0px') {
+    return (element) => {
+        const sentinel = element.previousElementSibling;
+        if (!sentinel || sentinel.dataset.stickySentinel === undefined)
+            return;
+        const observer = new IntersectionObserver(([entry]) => {
+            if (!entry)
+                return;
+            onStuck(!entry.isIntersecting);
+        }, {
+            threshold: [0, 1],
+            rootMargin: `${rootMarginTop} 0px 0px 0px`
+        });
+        observer.observe(sentinel);
+        return () => observer.disconnect();
+    };
+}

package/dist/utils/virtualizer.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Lightweight row virtualizer for fixed-height table rows.
+ * Only renders rows visible in the scroll viewport plus an overscan buffer.
+ *
+ * This avoids adding @tanstack/virtual as an external dependency and is fully
+ * compatible with Svelte 5 runes.
+ */
+export interface VirtualItem {
+    /** Index in the source data array */
+    index: number;
+    /** Pixel offset from the top of the scroll container */
+    offsetTop: number;
+    /** Height of this item in pixels */
+    height: number;
+}
+export interface VirtualizerOptions {
+    /** Total number of items */
+    count: number;
+    /** Fixed height per row in pixels */
+    rowHeight: number;
+    /** Number of rows to render above/below the viewport */
+    overscan?: number;
+}
+export interface VirtualizerResult {
+    /** Items to render */
+    virtualItems: VirtualItem[];
+    /** Total height of all rows (sets the scroll container's inner height) */
+    totalHeight: number;
+    /** Index of the first rendered item */
+    startIndex: number;
+    /** Index of the last rendered item (exclusive) */
+    endIndex: number;
+}
+/**
+ * Row height in pixels for each table size variant.
+ * Matches TABLE_DIMENSIONS.height.row in table.system.ts.
+ */
+export declare const ROW_HEIGHTS: Record<string, number>;
+/**
+ * Computes which rows are visible given a scroll position and viewport height.
+ * Pure function – no side effects, easy to test.
+ */
+export declare function computeVirtualItems(scrollTop: number, viewportHeight: number, options: VirtualizerOptions): VirtualizerResult;

package/dist/utils/virtualizer.js

@@ -0,0 +1,43 @@
+/**
+ * Lightweight row virtualizer for fixed-height table rows.
+ * Only renders rows visible in the scroll viewport plus an overscan buffer.
+ *
+ * This avoids adding @tanstack/virtual as an external dependency and is fully
+ * compatible with Svelte 5 runes.
+ */
+/**
+ * Row height in pixels for each table size variant.
+ * Matches TABLE_DIMENSIONS.height.row in table.system.ts.
+ */
+export const ROW_HEIGHTS = {
+    sm: 48,
+    md: 56,
+    lg: 64
+};
+/**
+ * Computes which rows are visible given a scroll position and viewport height.
+ * Pure function – no side effects, easy to test.
+ */
+export function computeVirtualItems(scrollTop, viewportHeight, options) {
+    const { count, rowHeight, overscan = 5 } = options;
+    if (count === 0 || viewportHeight === 0) {
+        return { virtualItems: [], totalHeight: 0, startIndex: 0, endIndex: 0 };
+    }
+    const totalHeight = count * rowHeight;
+    // Calculate visible range
+    const rawStart = Math.floor(scrollTop / rowHeight);
+    const rawEnd = Math.ceil((scrollTop + viewportHeight) / rowHeight);
+    // Apply overscan
+    const startIndex = Math.max(0, rawStart - overscan);
+    const endIndex = Math.min(count, rawEnd + overscan);
+    // Build virtual items
+    const virtualItems = [];
+    for (let i = startIndex; i < endIndex; i++) {
+        virtualItems.push({
+            index: i,
+            offsetTop: i * rowHeight,
+            height: rowHeight
+        });
+    }
+    return { virtualItems, totalHeight, startIndex, endIndex };
+}

package/dist/variants/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * TABLE VARIANTS EXPORTS
+ *
+ * Internal system tokens (TABLE_DIMENSIONS, TABLE_LAYOUTS, TABLE_STATES, etc.)
+ * are intentionally NOT re-exported here — they are implementation details
+ * consumed by the variant files, not part of the public API.
+ */
+export * from './table.variants';
+export * from './table-cells.variants';
+export * from './table-features.variants';
+export * from './table-states.variants';

package/dist/variants/index.js

@@ -0,0 +1,15 @@
+/**
+ * TABLE VARIANTS EXPORTS
+ *
+ * Internal system tokens (TABLE_DIMENSIONS, TABLE_LAYOUTS, TABLE_STATES, etc.)
+ * are intentionally NOT re-exported here — they are implementation details
+ * consumed by the variant files, not part of the public API.
+ */
+// Core table variants
+export * from './table.variants';
+// Cell variants
+export * from './table-cells.variants';
+// Feature variants
+export * from './table-features.variants';
+// State variants
+export * from './table-states.variants';