@lavalogic/scoria 0.37.52 → 0.37.53

package/dist/Components/Table/Types/Columns/JSONTableLayout.d.ts

@@ -0,0 +1,42 @@
+import type { ColumnSizingState } from './ColumnSizingState.js';
+import type { JSONColumnPinningState } from './JSONColumnPinningState.js';
+import type { VisibilityState } from './VisibilityState.js';
+/**
+ * Persisted-to-localStorage snapshot of a table's *live* column layout -
+ * the order / visibility / pinning / width state a user builds up by
+ * dragging, hiding and resizing columns, as distinct from an explicitly
+ * saved named preset (`JSONColumnDefSet`).
+ *
+ * `TableContext` writes this automatically on every layout change and
+ * re-applies it on the next mount, so a user's tweaks survive navigation
+ * and reloads without having to save a preset - persisted until the
+ * browser storage is cleared or the table's column set changes (schema
+ * drift, which drops the stale snapshot).
+ *
+ * Only ids and primitive maps are stored - never the column-def objects
+ * themselves - so the snapshot stays small and is trivially validated.
+ */
+export interface JSONTableLayout {
+    /** Column ids in display order (memory-index order). */
+    columnOrder: Array<string>;
+    /** Tri-state per-column visibility map. */
+    visibility: VisibilityState;
+    /** Pinned-left / pinned-right column ids with their pinned widths. */
+    pinning: JSONColumnPinningState;
+    /** Per-column user-set widths in pixels. */
+    sizing: ColumnSizingState;
+}
+/**
+ * Schema version for the persisted `JSONTableLayout` envelope. Bump when
+ * the shape changes in a backwards-incompatible way; `readVersionedJSON`
+ * silently drops envelopes written under a different version.
+ */
+export declare const TABLE_LAYOUT_SCHEMA_VERSION = 1;
+/**
+ * Conservative typeguard for a persisted `JSONTableLayout`. localStorage
+ * is same-origin-writable so the decoded value is untrusted; this checks
+ * the envelope shape and every field's primitive type. `TableContext`
+ * performs the deeper "do these ids still match the live column set"
+ * check before applying.
+ */
+export declare function isJSONTableLayout(raw: unknown): raw is JSONTableLayout;

package/dist/Components/Table/Types/Columns/JSONTableLayout.js

@@ -0,0 +1,58 @@
+/**
+ * Schema version for the persisted `JSONTableLayout` envelope. Bump when
+ * the shape changes in a backwards-incompatible way; `readVersionedJSON`
+ * silently drops envelopes written under a different version.
+ */
+export const TABLE_LAYOUT_SCHEMA_VERSION = 1;
+/**
+ * Conservative typeguard for a persisted `JSONTableLayout`. localStorage
+ * is same-origin-writable so the decoded value is untrusted; this checks
+ * the envelope shape and every field's primitive type. `TableContext`
+ * performs the deeper "do these ids still match the live column set"
+ * check before applying.
+ */
+export function isJSONTableLayout(raw) {
+    if (typeof raw !== 'object' || raw === null) {
+        return false;
+    }
+    const candidate = raw;
+    if (!Array.isArray(candidate.columnOrder) ||
+        !candidate.columnOrder.every((id) => typeof id === 'string')) {
+        return false;
+    }
+    if (!isPrimitiveRecord(candidate.visibility, (v) => typeof v === 'boolean')) {
+        return false;
+    }
+    if (!isPrimitiveRecord(candidate.sizing, (v) => typeof v === 'number')) {
+        return false;
+    }
+    return isJSONPinningState(candidate.pinning);
+}
+/** Validates a plain (non-array) object whose values all satisfy `valueGuard`. */
+function isPrimitiveRecord(raw, valueGuard) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return false;
+    }
+    return Object.values(raw).every(valueGuard);
+}
+/** Validates the `{ left?, right? }` array-pair pinning shape. */
+function isJSONPinningState(raw) {
+    if (typeof raw !== 'object' || raw === null) {
+        return false;
+    }
+    const candidate = raw;
+    return isPinSide(candidate.left) && isPinSide(candidate.right);
+}
+/** Validates one optional pinning side: absent, or an array of `[id, width]`. */
+function isPinSide(raw) {
+    if (raw === undefined) {
+        return true;
+    }
+    if (!Array.isArray(raw)) {
+        return false;
+    }
+    return raw.every((entry) => Array.isArray(entry) &&
+        entry.length === 2 &&
+        typeof entry[0] === 'string' &&
+        typeof entry[1] === 'number');
+}

package/dist/Components/Table/Types/Context/PreferencesState.svelte.d.ts

@@ -1,4 +1,5 @@
 import type { ColumnPinningState } from '../Columns/ColumnPinningState.js';
+import { type JSONTableLayout } from '../Columns/JSONTableLayout.js';
 import type { ColumnDef } from '../Columns/Definitions/ColumnDef.svelte.js';
 import type { ColumnDefSet } from '../Columns/Definitions/ColumnDefSet.js';
 import type { JSONColumnDefSet } from '../Columns/Definitions/JSONColumnDefSet.js';
@@ -139,7 +140,7 @@ export declare class PreferencesState<T extends object> {
      * for the same namespacing convention; the `<user>` segment is
      * `getUserId() ?? 'anon'` (see `userIdSegment`).
      */
-    storageKey(suffix: 'presets' | 'selected-preset-name' | 'settings'): string;
+    storageKey(suffix: 'presets' | 'selected-preset-name' | 'settings' | 'layout'): string;
     /**
      * Boot-time hydration helper. Reads the persisted preset list from
      * `localStorage`, validates it against `isJSONColumnDefSetArray`,
@@ -172,6 +173,30 @@ export declare class PreferencesState<T extends object> {
      * the live column-def shape (schema drift or column-set change).
      */
     clearPresetsAndSelection(): void;
+    /**
+     * Boot-time hydration helper. Reads the auto-saved live-layout
+     * snapshot (column order / visibility / pinning / sizing the user
+     * built up without saving a named preset). Returns `null` for a
+     * missing slot, a schema-version mismatch, or a value that fails
+     * validation, so the parent can fall back to the default layout.
+     *
+     * `localStorage` access is gated by the parent's `browser` check;
+     * this method assumes the caller already verified the environment.
+     */
+    loadLayout(): JSONTableLayout | null;
+    /**
+     * Persist the live-layout snapshot. Written by the parent on every
+     * column order / visibility / pinning / sizing change, wrapped in a
+     * versioned envelope so a future schema bump drops stale snapshots
+     * cleanly. Storage failures are swallowed inside `writeJSON`.
+     */
+    persistLayout(layout: JSONTableLayout): void;
+    /**
+     * Drop the persisted live-layout snapshot. Called when the snapshot
+     * no longer matches the table's column set (schema drift) or when
+     * table state is explicitly reset.
+     */
+    clearLayout(): void;
     /**
      * Persist the selected-preset name as plain text (no JSON
      * envelope - the slot is a single string by design).

package/dist/Components/Table/Types/Context/PreferencesState.svelte.js

@@ -1,5 +1,6 @@
 import { dev } from '$app/environment';
-import { readJSON } from '../../../../Helpers/Storage.js';
+import { readJSON, readVersionedJSON, writeJSON } from '../../../../Helpers/Storage.js';
+import { isJSONTableLayout, TABLE_LAYOUT_SCHEMA_VERSION, } from '../Columns/JSONTableLayout.js';
 /**
  * Conservative typeguard for the persisted preset list. Storage is
  * same-origin-writable so only the array shape can be trusted;
@@ -192,6 +193,53 @@ export class PreferencesState {
         localStorage.removeItem(this.storageKey('presets'));
         localStorage.removeItem(this.storageKey('selected-preset-name'));
     }
+    /**
+     * Boot-time hydration helper. Reads the auto-saved live-layout
+     * snapshot (column order / visibility / pinning / sizing the user
+     * built up without saving a named preset). Returns `null` for a
+     * missing slot, a schema-version mismatch, or a value that fails
+     * validation, so the parent can fall back to the default layout.
+     *
+     * `localStorage` access is gated by the parent's `browser` check;
+     * this method assumes the caller already verified the environment.
+     */
+    loadLayout() {
+        // Reference-equality sentinel: `readVersionedJSON` demands a
+        // fallback of the value type, so a distinct object instance is
+        // used to distinguish "no usable slot" from a real snapshot.
+        const fallback = {
+            columnOrder: [],
+            visibility: {},
+            pinning: {},
+            sizing: {},
+        };
+        const saved = readVersionedJSON(localStorage, this.storageKey('layout'), TABLE_LAYOUT_SCHEMA_VERSION, isJSONTableLayout, fallback);
+        return saved === fallback ? null : saved;
+    }
+    /**
+     * Persist the live-layout snapshot. Written by the parent on every
+     * column order / visibility / pinning / sizing change, wrapped in a
+     * versioned envelope so a future schema bump drops stale snapshots
+     * cleanly. Storage failures are swallowed inside `writeJSON`.
+     */
+    persistLayout(layout) {
+        writeJSON(localStorage, this.storageKey('layout'), layout, TABLE_LAYOUT_SCHEMA_VERSION);
+    }
+    /**
+     * Drop the persisted live-layout snapshot. Called when the snapshot
+     * no longer matches the table's column set (schema drift) or when
+     * table state is explicitly reset.
+     */
+    clearLayout() {
+        try {
+            localStorage.removeItem(this.storageKey('layout'));
+        }
+        catch (e) {
+            if (dev) {
+                console.warn('table layout slot clear failed:', e);
+            }
+        }
+    }
     /**
      * Persist the selected-preset name as plain text (no JSON
      * envelope - the slot is a single string by design).

package/dist/Components/Table/Types/Context/TableContext.svelte.d.ts

@@ -73,6 +73,21 @@ export declare class TableContext<T extends object, RowIdType extends Primitive>
     static init<T extends object, RowIdType extends Primitive>(defaultColumnDefs: DefsWrapper<T>, tableName: string, dataRepo: IDataRepository<T>, options: TableInitOptions<T, RowIdType>): TableContext<T, RowIdType>;
     protected constructor(INTERNAL_ONLY: symbol, defaultColumnDefs: DefsWrapper<T>, tableName: string, dataRepo: IDataRepository<T>, allowCopy: boolean, enableResize: boolean, allowColumnReordering: boolean, allowQuickFiltering: boolean, showQuickFilterByDefault: boolean, allowAdvancedFiltering: boolean, toolbarPosition: ToolbarPosition, displayFooter: boolean, selectionExtractor: TableInitOptions<T, RowIdType>['selectionExtractor'], getUserId: () => string | undefined, _onEditCell: TableInitOptions<T, RowIdType>['onEditCell'], debug: boolean);
     private isSelectable;
+    /**
+     * `false` until the boot-time layout hydration (`_hydrateLayout`)
+     * has run. The auto-persist `$effect` reads this gate so the live
+     * layout is not written back during construction / hydration -
+     * which would clobber the saved snapshot with the default layout.
+     */
+    private _layoutHydrated;
+    /**
+     * Pending debounce timer for the layout auto-persist. Deliberately
+     * not cleared on teardown: a still-pending write should flush even
+     * if the user navigates away mid-debounce, and `persistLayout` only
+     * touches `localStorage` (no reactive state, no DOM) so it is safe
+     * to run after the component is gone.
+     */
+    private _layoutPersistTimer;
     private _paginationRepo;
     get paginationRepo(): IDataRepository<T> | undefined;
     set paginationRepo(v: IDataRepository<T> | undefined);
@@ -620,6 +635,33 @@ export declare class TableContext<T extends object, RowIdType extends Primitive>
      * persistence boundary lives in the sub-context.
      */
     private _updateLocalStorageSettings;
+    /**
+     * Snapshot the live column layout - order / visibility / pinning /
+     * sizing - into the persistable `JSONTableLayout` shape. Reads every
+     * layout `$state` slot so the auto-persist `$effect` re-runs whenever
+     * any of them change.
+     */
+    private _captureLayout;
+    /**
+     * Apply a persisted `JSONTableLayout` to the live column state. The
+     * snapshot is dropped (and ignored) when its column-id set no longer
+     * matches the table's current columns - a column added or removed
+     * since the snapshot was written invalidates it.
+     */
+    private _applyLayout;
+    /**
+     * Boot-time hydration. Reads the auto-saved live-layout snapshot and
+     * applies it on top of whatever the preset flow produced, restoring
+     * the user's last column order / visibility / pinning / sizing.
+     * No-op when no snapshot is stored.
+     */
+    private _hydrateLayout;
+    /**
+     * Drop the persisted live-layout snapshot for this table. The next
+     * mount falls back to the default column layout. Exposed so a host
+     * app can wire an explicit "reset table layout" control.
+     */
+    clearPersistedLayout(): void;
     /**
      * Delegates to `_columnLayout.visualColumns`. The underscore prefix
      * is preserved so the existing read sites in `tabForward` /

package/dist/Components/Table/Types/Context/TableContext.svelte.js

@@ -19,6 +19,13 @@ import { PaginationType } from '../Pagination/PaginationType.js';
 import { ToolbarPosition } from '../Toolbar/ToolbarPosition.js';
 const SORTING_ICON_WIDTH = 24;
 const InternalSymbol = Symbol();
+/**
+ * Debounce window (ms) for the auto-persist of the live column layout.
+ * Collapses a burst of changes - notably a drag-resize, which fires a
+ * width update on every pointer move - into a single `localStorage`
+ * write once the user settles.
+ */
+const LAYOUT_PERSIST_DEBOUNCE_MS = 250;
 /**
  * Default values applied by `TableContext.init` for any `TableInitOptions`
  * field the consumer omits. Frozen so callers (notably `NestedTable`)
@@ -339,6 +346,26 @@ export class TableContext {
         if (hasPagination(dataRepo)) {
             this.paginationRepo = dataRepo;
         }
+        // Auto-persist the live column layout (order / visibility /
+        // pinning / sizing) to localStorage on every change, so a user's
+        // drag-reorder, hide/show and resize tweaks survive navigation
+        // and reload without having to save a named preset. Gated on
+        // `_layoutHydrated` so the boot-time hydration below does not race
+        // a write of the default layout over the saved snapshot, and
+        // debounced so a drag-resize storm collapses to a single write.
+        $effect(() => {
+            const snapshot = this._captureLayout();
+            if (!this._layoutHydrated) {
+                return;
+            }
+            if (this._layoutPersistTimer !== undefined) {
+                clearTimeout(this._layoutPersistTimer);
+            }
+            this._layoutPersistTimer = setTimeout(() => {
+                this._layoutPersistTimer = undefined;
+                this._preferences.persistLayout(snapshot);
+            }, LAYOUT_PERSIST_DEBOUNCE_MS);
+        });
         if (browser) {
             this._getUserDefaults();
             const removeInvalidPresets = () => {
@@ -400,6 +427,13 @@ export class TableContext {
                     }
                     this._preferences.setPresets(presets);
                 }
+            })
+                .then(() => {
+                // Restore the auto-saved live layout on top of whatever
+                // the preset flow produced, then open the auto-persist
+                // gate. Runs regardless of which preset branch was taken.
+                this._hydrateLayout();
+                this._layoutHydrated = true;
             })
                 .catch(devCatch);
         }
@@ -407,6 +441,21 @@ export class TableContext {
     // #endregion
     // #region stores
     isSelectable = $state(false);
+    /**
+     * `false` until the boot-time layout hydration (`_hydrateLayout`)
+     * has run. The auto-persist `$effect` reads this gate so the live
+     * layout is not written back during construction / hydration -
+     * which would clobber the saved snapshot with the default layout.
+     */
+    _layoutHydrated = $state(false);
+    /**
+     * Pending debounce timer for the layout auto-persist. Deliberately
+     * not cleared on teardown: a still-pending write should flush even
+     * if the user navigates away mid-debounce, and `persistLayout` only
+     * touches `localStorage` (no reactive state, no DOM) so it is safe
+     * to run after the component is gone.
+     */
+    _layoutPersistTimer = undefined;
     _paginationRepo = $state();
     get paginationRepo() {
         return this._paginationRepo;
@@ -1762,6 +1811,95 @@ export class TableContext {
         };
         this._preferences.persistSettings(settingsObject);
     }
+    /**
+     * Snapshot the live column layout - order / visibility / pinning /
+     * sizing - into the persistable `JSONTableLayout` shape. Reads every
+     * layout `$state` slot so the auto-persist `$effect` re-runs whenever
+     * any of them change.
+     */
+    _captureLayout() {
+        const columnOrder = this.columnDefs
+            .slice()
+            .sort((a, b) => a.index - b.index)
+            .map((def) => def.id);
+        const pinning = {
+            left: [...(this.columnPinning.left?.entries() ?? [])],
+            right: [...(this.columnPinning.right?.entries() ?? [])],
+        };
+        return {
+            columnOrder,
+            visibility: { ...this.columnVisibility },
+            pinning,
+            sizing: { ...this.columnSizing },
+        };
+    }
+    /**
+     * Apply a persisted `JSONTableLayout` to the live column state. The
+     * snapshot is dropped (and ignored) when its column-id set no longer
+     * matches the table's current columns - a column added or removed
+     * since the snapshot was written invalidates it.
+     */
+    _applyLayout(layout) {
+        const defs = this.columnDefs;
+        // Keyed by plain `string` (not the branded `ColumnId`) so the
+        // persisted-snapshot ids - read back as plain strings - look up
+        // cleanly.
+        // eslint-disable-next-line svelte/prefer-svelte-reactivity
+        const byId = new Map(defs.map((def) => [def.id, def]));
+        // Schema-drift guard: the snapshot must describe exactly the
+        // current column set, otherwise it is stale and is discarded.
+        const matchesColumnSet = layout.columnOrder.length === defs.length && layout.columnOrder.every((id) => byId.has(id));
+        if (!matchesColumnSet) {
+            this._preferences.clearLayout();
+            return;
+        }
+        // Order: re-index the defs into the saved order.
+        const ordered = layout.columnOrder.map((id, index) => {
+            const def = byId.get(id);
+            if (!def) {
+                throw new Error(`_applyLayout: missing column def for id "${id}"`);
+            }
+            def.index = index;
+            return def;
+        });
+        this.columnDefs = ordered;
+        // Visibility / sizing: keep only ids still present in the table.
+        const visibility = {};
+        for (const [id, visible] of Object.entries(layout.visibility)) {
+            if (byId.has(id)) {
+                visibility[id] = visible;
+            }
+        }
+        this.columnVisibility = visibility;
+        const sizing = {};
+        for (const [id, width] of Object.entries(layout.sizing)) {
+            if (byId.has(id)) {
+                sizing[id] = width;
+            }
+        }
+        this.columnSizing = sizing;
+        this.columnPinning = adaptJSONPinningState(layout.pinning);
+    }
+    /**
+     * Boot-time hydration. Reads the auto-saved live-layout snapshot and
+     * applies it on top of whatever the preset flow produced, restoring
+     * the user's last column order / visibility / pinning / sizing.
+     * No-op when no snapshot is stored.
+     */
+    _hydrateLayout() {
+        const layout = this._preferences.loadLayout();
+        if (layout) {
+            this._applyLayout(layout);
+        }
+    }
+    /**
+     * Drop the persisted live-layout snapshot for this table. The next
+     * mount falls back to the default column layout. Exposed so a host
+     * app can wire an explicit "reset table layout" control.
+     */
+    clearPersistedLayout() {
+        this._preferences.clearLayout();
+    }
     /**
      * Delegates to `_columnLayout.visualColumns`. The underscore prefix
      * is preserved so the existing read sites in `tabForward` /

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lavalogic/scoria",
   "description": "Svelte components used for the FloWMS Web Frontend",
-  "version": "0.37.52",
+  "version": "0.37.53",
   "publishConfig": {
     "access": "restricted"
   },