@lavalogic/scoria 0.35.0 → 0.37.0

package/dist/Components/Table/Types/Context/ITable.d.ts

@@ -8,6 +8,16 @@ import type { ColumnFiltersState } from '../Filtering/ColumnFiltersState.js';
 import type { HeaderGroup } from '../HeaderGroup.js';
 import type { OnChangeFn } from '../OnChangeFn.js';
 import type { PaginationState } from '../Pagination/PaginationState.js';
+/**
+ * Surface returned by `TableContext.table`. Mirrors the tanstack-table shape
+ * scoria's table API was originally derived from, narrowed to the methods the
+ * scoria Table actually exposes.
+ *
+ * The commented-out `extends X, Y, Z` lines record the tanstack-derived
+ * mixins that have not yet been implemented; they are retained as a backlog
+ * marker. Deleting them is deferred (workorder Types-Context-supporting
+ * finding 1) until a decision is made on which mixins to port.
+ */
 export interface ITable<T extends object> {
     data: Array<T>;
     columns: Array<ColumnDef<T>>;

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

@@ -0,0 +1,242 @@
+import type { ColumnPinningState } from '../Columns/ColumnPinningState.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';
+import type { VisibilityState } from '../Columns/VisibilityState.js';
+import type { SortingState as SortingStateArray } from '../DataRepository/SortingState.js';
+import type { SavedTableSettings, TableSettings } from './TableSettings.js';
+/**
+ * Conservative typeguard for the persisted preset list. Storage is
+ * same-origin-writable so the only contract we can rely on is the array
+ * shape; downstream `reassignDefsToPresets` performs deeper checks and
+ * drops presets that fail. We assert the outer envelope and the bare
+ * minimum for each entry: a string `name` and an array `columnDefs`.
+ *
+ * Lifted from `TableContext.svelte.ts` during Phase 6.4 god-object
+ * decomposition; semantics unchanged.
+ */
+export declare function isJSONColumnDefSetArray(raw: unknown): raw is Array<JSONColumnDefSet>;
+/**
+ * Typeguard for the persisted user-level table settings blob. Every
+ * field is optional, but every present field must be boolean: anything
+ * else is a sign of schema drift or a tampered slot.
+ *
+ * Lifted from `TableContext.svelte.ts` during Phase 6.4.
+ */
+export declare function isSavedTableSettings(raw: unknown): raw is SavedTableSettings;
+/**
+ * Typeguard for a non-empty string. Used for the persisted selected
+ * preset name slot.
+ *
+ * Lifted from `TableContext.svelte.ts` during Phase 6.4.
+ */
+export declare function isNonEmptyString(raw: unknown): raw is string;
+/**
+ * Dependency surface that `PreferencesState` reads from the surrounding
+ * `TableContext`. All dependencies are passed as thunks / function refs
+ * so the sub-context never holds a direct reference to the parent; the
+ * `userIdSegment` derived reads `getUserId()` lazily and the
+ * `setSelectedPreset` flow writes back through the column-layout
+ * setters / `paginationRepo` updater.
+ */
+export interface PreferencesStateDeps<T extends object> {
+    /** The static table name, used as the middle segment of every
+     *  persisted key (`scoria-table:<user>:<tableName>:<suffix>`). */
+    getTableName: () => string;
+    /** Caller-supplied user identifier. `userIdSegment` resolves to
+     *  `getUserId() ?? 'anon'` so different users on a shared browser
+     *  cannot read each other's column presets. */
+    getUserId: () => string | undefined;
+    /** Read the current ordered column-defs array (used by
+     *  `saveColumnPreset` to capture the layout into the preset). */
+    getColumnDefs: () => Array<ColumnDef<T>>;
+    /** Read the current visibility map (used by `saveColumnPreset`). */
+    getColumnVisibility: () => VisibilityState;
+    /** Read the current column-pinning map (used by `saveColumnPreset`). */
+    getColumnPinning: () => ColumnPinningState;
+    /** Read the current sort instruction list (used by
+     *  `saveColumnPreset`). May be `undefined` when no pagination
+     *  repository is attached yet. */
+    getSortingArray: () => SortingStateArray | undefined;
+    /** Apply the column-defs slot when a preset is restored. */
+    setColumnDefs: (defs: Array<ColumnDef<T>>) => void;
+    /** Apply the visibility map when a preset is restored. */
+    setColumnVisibility: (state: VisibilityState) => void;
+    /** Apply the column-pinning map when a preset is restored. */
+    setColumnPinning: (state: ColumnPinningState) => void;
+    /** Apply the sort instruction list when a preset is restored. May
+     *  be `undefined` when no pagination repository is attached yet;
+     *  the writer is a best-effort hook (mirrors the pre-extraction
+     *  `paginationRepo?.updateSorting?.()` call). */
+    applySortingState: (state: SortingStateArray) => void;
+    /** Logger gate; mirrors the parent `TableContext.debug` field. */
+    getDebug: () => boolean;
+}
+/**
+ * Phase 6.4 god-object decomposition - sub-context that owns every
+ * persistence / preferences concern previously held directly on
+ * `TableContext`:
+ *
+ * - `_columnPresets` (the persisted preset list `$state`),
+ * - `_selectedPreset` (the currently-active preset `$state`),
+ * - `userIdSegment` (the sanitised user-id segment used in storage
+ *   keys; `$derived` over `getUserId()`),
+ * - `saveColumnPreset(name)` (snapshot the live layout, persist the
+ *   list, mark the new preset as selected),
+ * - `setSelectedPreset(preset)` (apply the preset to the live layout
+ *   and persist the selected name),
+ * - `loadPresets()` / `loadSelectedPresetName()` /
+ *   `loadSavedSettings()` (boot-time hydration helpers; the parent
+ *   owns the orchestration because it depends on `setupDefaultColumnDefs`
+ *   running first),
+ * - `clearPresetsAndSelection()` (drop both persisted slots),
+ * - `persistSettings(settings)` (write the per-table TableSettings
+ *   blob),
+ * - the schema-validation typeguards
+ *   (`isJSONColumnDefSetArray`, `isSavedTableSettings`,
+ *   `isNonEmptyString`) - exported alongside the class.
+ *
+ * `TableContext` retains delegating getters / setters / methods for
+ * every legacy surface (`columnPresets`, `selectedPreset`,
+ * `saveColumnPreset`, `setSelectedPreset`, `_updateLocalStorageSettings`)
+ * so existing consumers need no migration. Future consumers can read
+ * `tableContext._preferences` directly once the migration is complete
+ * (see `src/stories/Concepts/TableContext-decomposition.mdx`).
+ *
+ * Every `localStorage` access is funnelled through this sub-context so
+ * the `scoria-table:<user>:<tableName>:<suffix>` namespace convention
+ * is enforced in a single place.
+ */
+export declare class PreferencesState<T extends object> {
+    private readonly _deps;
+    private _columnPresets;
+    private _selectedPreset;
+    /**
+     * Sanitised segment of the persisted-storage key path. Resolves to
+     * `getUserId() ?? 'anon'` so different users on a shared browser
+     * cannot read each other's column presets, and so anonymous
+     * sessions still have a stable namespace.
+     *
+     * The `$derived.by` form is required here (over plain
+     * `$derived(expr)`) because class-field initialisers run BEFORE
+     * the constructor body assigns `_deps`; the function-form wrapper
+     * defers the read until the derived is first evaluated.
+     */
+    readonly userIdSegment: string;
+    /**
+     * @param deps thunks the sub-context reads from the parent.
+     *             Constructor-only - no implicit setup so the parent
+     *             remains in control of effect ownership and lifecycle.
+     */
+    constructor(deps: PreferencesStateDeps<T>);
+    /**
+     * The current list of saved column presets. Setter is private to
+     * the sub-context; the parent writes through `setPresets` during
+     * the boot-time hydration flow.
+     */
+    get columnPresets(): ReadonlyArray<ColumnDefSet<T>>;
+    /**
+     * Writer for `columnPresets`. Public so the parent boot flow can
+     * publish the hydrated list; not part of the consumer-facing
+     * surface (consumer-facing writes go through `saveColumnPreset`).
+     */
+    setPresets(v: ReadonlyArray<ColumnDefSet<T>>): void;
+    /**
+     * The currently-active preset (the one whose name is persisted in
+     * the `selected-preset-name` slot). Setter is public so the parent
+     * boot flow can publish the resolved preset; the consumer-facing
+     * writer is `setSelectedPreset` below (which also persists the
+     * name).
+     */
+    get selectedPreset(): ColumnDefSet<T> | undefined;
+    set selectedPreset(v: ColumnDefSet<T> | undefined);
+    /**
+     * Build the canonical `scoria-table:<user>:<tableName>:<suffix>`
+     * storage key. Centralised so every persisted-state slot reaches
+     * for the same namespacing convention; the `<user>` segment is
+     * `getUserId() ?? 'anon'` (see `userIdSegment`).
+     */
+    storageKey(suffix: 'presets' | 'selected-preset-name' | 'settings'): string;
+    /**
+     * Boot-time hydration helper. Reads the persisted preset list from
+     * `localStorage`, validates it against `isJSONColumnDefSetArray`,
+     * and returns the parsed array (or an empty array on every failure
+     * path). The parent runs this once `setupDefaultColumnDefs` has
+     * completed so the live `columnDefs` can be compared against the
+     * persisted snapshot.
+     *
+     * `localStorage` access is gated by the parent's `browser` check;
+     * this method assumes the caller already verified the environment.
+     */
+    loadPresets(): Array<JSONColumnDefSet>;
+    /**
+     * Boot-time hydration helper. Reads the persisted selected-preset
+     * name. Returns `null` for missing / empty / storage-error slots
+     * so the parent can fall back to the first preset (or the
+     * default).
+     *
+     * Mirrors the pre-extraction try/catch around `getItem` verbatim:
+     * the same dev-only warning is emitted on read failure.
+     */
+    loadSelectedPresetName(): string | null;
+    /**
+     * Boot-time hydration helper. Reads the persisted per-table
+     * settings blob (`isCompact`, `singleClickEditing`, etc.). Returns
+     * `null` when the slot is missing or fails validation so the
+     * parent can apply its own default policy.
+     */
+    loadSavedSettings(): SavedTableSettings | null;
+    /**
+     * Drop the persisted presets and selected-preset-name slots. Used
+     * by the parent's boot flow when the saved snapshot disagrees with
+     * the live column-def shape (schema drift or column-set change).
+     */
+    clearPresetsAndSelection(): void;
+    /**
+     * Persist the selected-preset name as plain text (no JSON
+     * envelope - the slot is a single string by design).
+     */
+    persistSelectedPresetName(name: string): void;
+    /**
+     * Persist the per-table settings blob (`isCompact`,
+     * `singleClickEditing`, etc.) as JSON. Format and key remain
+     * exactly as before the extraction.
+     */
+    persistSettings(settings: TableSettings): void;
+    /**
+     * Persist the full preset list as JSON. Each preset's
+     * `columnPinningState` (Map-based) is flattened into entry arrays
+     * because Map does not survive `JSON.stringify`; the reader (via
+     * `loadPresets` -> `reassignDefsToPresets`) rehydrates it through
+     * `adaptJSONPinningState`.
+     *
+     * Pulled out of `saveColumnPreset` so the per-preset
+     * `toJSON()` walk is unit-testable in isolation.
+     */
+    persistPresets(presets: ReadonlyArray<ColumnDefSet<T>>): void;
+    /**
+     * Apply a saved column preset to the live table layout and
+     * persist the selection by name. Mirrors the pre-extraction
+     * `TableContext.setSelectedPreset` verbatim:
+     *
+     * 1. Replace `columnDefs`, `columnVisibility`, `columnPinning`.
+     * 2. Forward the preset's `sortingState` to the data-repository
+     *    updater (no-op when the repo has no `updateSorting` hook).
+     * 3. Update `selectedPreset`.
+     * 4. Persist the preset name to `selected-preset-name`.
+     *
+     * Bound as a class property so callers (notably the toolbar
+     * dropdown) can pass the reference around without binding `this`.
+     */
+    readonly setSelectedPreset: (preset: ColumnDefSet<T>) => void;
+    /**
+     * Snapshot the current column layout into a new preset, replacing
+     * any existing preset whose name matches case-insensitively, and
+     * persist the full preset list to `localStorage`. Marks the new
+     * preset as selected (which also persists its name).
+     *
+     * Mirrors the pre-extraction `TableContext.saveColumnPreset`
+     * verbatim. No-op when `name` is empty.
+     */
+    readonly saveColumnPreset: (name: string) => void;
+}

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

@@ -0,0 +1,317 @@
+import { dev } from '$app/environment';
+import { readJSON } from '../../../../Helpers/Storage.js';
+/**
+ * Conservative typeguard for the persisted preset list. Storage is
+ * same-origin-writable so the only contract we can rely on is the array
+ * shape; downstream `reassignDefsToPresets` performs deeper checks and
+ * drops presets that fail. We assert the outer envelope and the bare
+ * minimum for each entry: a string `name` and an array `columnDefs`.
+ *
+ * Lifted from `TableContext.svelte.ts` during Phase 6.4 god-object
+ * decomposition; semantics unchanged.
+ */
+export function isJSONColumnDefSetArray(raw) {
+    if (!Array.isArray(raw)) {
+        return false;
+    }
+    return raw.every((entry) => {
+        if (typeof entry !== 'object' || entry === null) {
+            return false;
+        }
+        const candidate = entry;
+        return typeof candidate.name === 'string' && Array.isArray(candidate.columnDefs);
+    });
+}
+/**
+ * Typeguard for the persisted user-level table settings blob. Every
+ * field is optional, but every present field must be boolean: anything
+ * else is a sign of schema drift or a tampered slot.
+ *
+ * Lifted from `TableContext.svelte.ts` during Phase 6.4.
+ */
+export function isSavedTableSettings(raw) {
+    if (typeof raw !== 'object' || raw === null) {
+        return false;
+    }
+    const candidate = raw;
+    const optionalBoolean = (key) => candidate[key] === undefined || typeof candidate[key] === 'boolean';
+    return (optionalBoolean('isCompact') &&
+        optionalBoolean('singleClickEditing') &&
+        optionalBoolean('alternateRowColours') &&
+        optionalBoolean('changeColourOnHover') &&
+        optionalBoolean('copyWithHeaders') &&
+        optionalBoolean('commaSeparatedCopy'));
+}
+/**
+ * Typeguard for a non-empty string. Used for the persisted selected
+ * preset name slot.
+ *
+ * Lifted from `TableContext.svelte.ts` during Phase 6.4.
+ */
+export function isNonEmptyString(raw) {
+    return typeof raw === 'string' && raw.length > 0;
+}
+/**
+ * Phase 6.4 god-object decomposition - sub-context that owns every
+ * persistence / preferences concern previously held directly on
+ * `TableContext`:
+ *
+ * - `_columnPresets` (the persisted preset list `$state`),
+ * - `_selectedPreset` (the currently-active preset `$state`),
+ * - `userIdSegment` (the sanitised user-id segment used in storage
+ *   keys; `$derived` over `getUserId()`),
+ * - `saveColumnPreset(name)` (snapshot the live layout, persist the
+ *   list, mark the new preset as selected),
+ * - `setSelectedPreset(preset)` (apply the preset to the live layout
+ *   and persist the selected name),
+ * - `loadPresets()` / `loadSelectedPresetName()` /
+ *   `loadSavedSettings()` (boot-time hydration helpers; the parent
+ *   owns the orchestration because it depends on `setupDefaultColumnDefs`
+ *   running first),
+ * - `clearPresetsAndSelection()` (drop both persisted slots),
+ * - `persistSettings(settings)` (write the per-table TableSettings
+ *   blob),
+ * - the schema-validation typeguards
+ *   (`isJSONColumnDefSetArray`, `isSavedTableSettings`,
+ *   `isNonEmptyString`) - exported alongside the class.
+ *
+ * `TableContext` retains delegating getters / setters / methods for
+ * every legacy surface (`columnPresets`, `selectedPreset`,
+ * `saveColumnPreset`, `setSelectedPreset`, `_updateLocalStorageSettings`)
+ * so existing consumers need no migration. Future consumers can read
+ * `tableContext._preferences` directly once the migration is complete
+ * (see `src/stories/Concepts/TableContext-decomposition.mdx`).
+ *
+ * Every `localStorage` access is funnelled through this sub-context so
+ * the `scoria-table:<user>:<tableName>:<suffix>` namespace convention
+ * is enforced in a single place.
+ */
+export class PreferencesState {
+    _deps;
+    _columnPresets = $state([]);
+    //FIXME why was this allowed to be undefined? Mirrors the pre-extraction
+    // `TableContext._selectedPreset` field; retained as `undefined`-capable
+    // for source compatibility.
+    _selectedPreset = $state();
+    /**
+     * Sanitised segment of the persisted-storage key path. Resolves to
+     * `getUserId() ?? 'anon'` so different users on a shared browser
+     * cannot read each other's column presets, and so anonymous
+     * sessions still have a stable namespace.
+     *
+     * The `$derived.by` form is required here (over plain
+     * `$derived(expr)`) because class-field initialisers run BEFORE
+     * the constructor body assigns `_deps`; the function-form wrapper
+     * defers the read until the derived is first evaluated.
+     */
+    userIdSegment = $derived.by(() => this._deps.getUserId() ?? 'anon');
+    /**
+     * @param deps thunks the sub-context reads from the parent.
+     *             Constructor-only - no implicit setup so the parent
+     *             remains in control of effect ownership and lifecycle.
+     */
+    constructor(deps) {
+        this._deps = deps;
+    }
+    /**
+     * The current list of saved column presets. Setter is private to
+     * the sub-context; the parent writes through `setPresets` during
+     * the boot-time hydration flow.
+     */
+    get columnPresets() {
+        return this._columnPresets;
+    }
+    /**
+     * Writer for `columnPresets`. Public so the parent boot flow can
+     * publish the hydrated list; not part of the consumer-facing
+     * surface (consumer-facing writes go through `saveColumnPreset`).
+     */
+    setPresets(v) {
+        this._columnPresets = v;
+    }
+    /**
+     * The currently-active preset (the one whose name is persisted in
+     * the `selected-preset-name` slot). Setter is public so the parent
+     * boot flow can publish the resolved preset; the consumer-facing
+     * writer is `setSelectedPreset` below (which also persists the
+     * name).
+     */
+    get selectedPreset() {
+        return this._selectedPreset;
+    }
+    set selectedPreset(v) {
+        this._selectedPreset = v;
+    }
+    /**
+     * Build the canonical `scoria-table:<user>:<tableName>:<suffix>`
+     * storage key. Centralised so every persisted-state slot reaches
+     * for the same namespacing convention; the `<user>` segment is
+     * `getUserId() ?? 'anon'` (see `userIdSegment`).
+     */
+    storageKey(suffix) {
+        return `scoria-table:${this.userIdSegment}:${this._deps.getTableName()}:${suffix}`;
+    }
+    /**
+     * Boot-time hydration helper. Reads the persisted preset list from
+     * `localStorage`, validates it against `isJSONColumnDefSetArray`,
+     * and returns the parsed array (or an empty array on every failure
+     * path). The parent runs this once `setupDefaultColumnDefs` has
+     * completed so the live `columnDefs` can be compared against the
+     * persisted snapshot.
+     *
+     * `localStorage` access is gated by the parent's `browser` check;
+     * this method assumes the caller already verified the environment.
+     */
+    loadPresets() {
+        return readJSON(localStorage, this.storageKey('presets'), isJSONColumnDefSetArray, []);
+    }
+    /**
+     * Boot-time hydration helper. Reads the persisted selected-preset
+     * name. Returns `null` for missing / empty / storage-error slots
+     * so the parent can fall back to the first preset (or the
+     * default).
+     *
+     * Mirrors the pre-extraction try/catch around `getItem` verbatim:
+     * the same dev-only warning is emitted on read failure.
+     */
+    loadSelectedPresetName() {
+        let savedPresetName = null;
+        try {
+            savedPresetName = localStorage.getItem(this.storageKey('selected-preset-name'));
+        }
+        catch (e) {
+            if (dev) {
+                console.warn('selected-preset-name read failed:', e);
+            }
+        }
+        if (!isNonEmptyString(savedPresetName)) {
+            return null;
+        }
+        return savedPresetName;
+    }
+    /**
+     * Boot-time hydration helper. Reads the persisted per-table
+     * settings blob (`isCompact`, `singleClickEditing`, etc.). Returns
+     * `null` when the slot is missing or fails validation so the
+     * parent can apply its own default policy.
+     */
+    loadSavedSettings() {
+        const fallback = {};
+        const saved = readJSON(localStorage, this.storageKey('settings'), isSavedTableSettings, fallback);
+        if (saved === fallback) {
+            return null;
+        }
+        return saved;
+    }
+    /**
+     * Drop the persisted presets and selected-preset-name slots. Used
+     * by the parent's boot flow when the saved snapshot disagrees with
+     * the live column-def shape (schema drift or column-set change).
+     */
+    clearPresetsAndSelection() {
+        localStorage.removeItem(this.storageKey('presets'));
+        localStorage.removeItem(this.storageKey('selected-preset-name'));
+    }
+    /**
+     * Persist the selected-preset name as plain text (no JSON
+     * envelope - the slot is a single string by design).
+     */
+    persistSelectedPresetName(name) {
+        localStorage.setItem(this.storageKey('selected-preset-name'), name);
+    }
+    /**
+     * Persist the per-table settings blob (`isCompact`,
+     * `singleClickEditing`, etc.) as JSON. Format and key remain
+     * exactly as before the extraction.
+     */
+    persistSettings(settings) {
+        localStorage.setItem(this.storageKey('settings'), JSON.stringify(settings));
+    }
+    /**
+     * Persist the full preset list as JSON. Each preset's
+     * `columnPinningState` (Map-based) is flattened into entry arrays
+     * because Map does not survive `JSON.stringify`; the reader (via
+     * `loadPresets` -> `reassignDefsToPresets`) rehydrates it through
+     * `adaptJSONPinningState`.
+     *
+     * Pulled out of `saveColumnPreset` so the per-preset
+     * `toJSON()` walk is unit-testable in isolation.
+     */
+    persistPresets(presets) {
+        const jsonFriendly = presets.map((preset) => {
+            return {
+                ...preset,
+                columnDefs: preset.columnDefs.map((it) => {
+                    return { ...it.toJSON(), header: it.header.toString() };
+                }),
+                columnPinningState: {
+                    left: [...(preset.columnPinningState.left?.entries() ?? [])],
+                    right: [...(preset.columnPinningState.right?.entries() ?? [])],
+                },
+            };
+        });
+        localStorage.setItem(this.storageKey('presets'), JSON.stringify(jsonFriendly));
+    }
+    /**
+     * Apply a saved column preset to the live table layout and
+     * persist the selection by name. Mirrors the pre-extraction
+     * `TableContext.setSelectedPreset` verbatim:
+     *
+     * 1. Replace `columnDefs`, `columnVisibility`, `columnPinning`.
+     * 2. Forward the preset's `sortingState` to the data-repository
+     *    updater (no-op when the repo has no `updateSorting` hook).
+     * 3. Update `selectedPreset`.
+     * 4. Persist the preset name to `selected-preset-name`.
+     *
+     * Bound as a class property so callers (notably the toolbar
+     * dropdown) can pass the reference around without binding `this`.
+     */
+    setSelectedPreset = (preset) => {
+        if (this._deps.getDebug()) {
+            console.log('setting selected preset:', preset);
+        }
+        this._deps.setColumnDefs(preset.columnDefs);
+        this._deps.applySortingState(preset.sortingState);
+        this._deps.setColumnVisibility(preset.visibilityState);
+        this._deps.setColumnPinning(preset.columnPinningState);
+        this._selectedPreset = preset;
+        this.persistSelectedPresetName(preset.name);
+    };
+    /**
+     * Snapshot the current column layout into a new preset, replacing
+     * any existing preset whose name matches case-insensitively, and
+     * persist the full preset list to `localStorage`. Marks the new
+     * preset as selected (which also persists its name).
+     *
+     * Mirrors the pre-extraction `TableContext.saveColumnPreset`
+     * verbatim. No-op when `name` is empty.
+     */
+    saveColumnPreset = (name) => {
+        if (!name) {
+            return;
+        }
+        const visibilityState = this._deps.getColumnVisibility();
+        const columnPinningState = this._deps.getColumnPinning();
+        const columnDefs = this._deps.getColumnDefs();
+        const sortingState = this._deps.getSortingArray() ?? [];
+        const newPreset = {
+            columnDefs,
+            name,
+            visibilityState,
+            columnPinningState,
+            sortingState,
+        };
+        const lowercasePresetname = name.toLocaleLowerCase();
+        const indexToReplace = this._columnPresets.findIndex((oldPreset) => oldPreset.name.toLocaleLowerCase() === lowercasePresetname);
+        const newPresets = this._columnPresets.concat();
+        if (indexToReplace > -1) {
+            newPresets[indexToReplace] = newPreset;
+        }
+        else {
+            newPresets.push(newPreset);
+        }
+        this._columnPresets = newPresets;
+        this.persistPresets(newPresets);
+        this.setSelectedPreset(newPreset);
+    };
+}

package/dist/Components/Table/Types/Context/ReadonlyRowModel.d.ts

@@ -1,6 +1,17 @@
-import type { SvelteMap } from 'svelte/reactivity';
 import type { Row } from './Row.js';
+/**
+ * Read-only view of a row model.
+ *
+ * Note: historically this interface (despite the `Readonly` name) declared
+ * `rowsById` as a mutable `SvelteMap` while the sibling `RowModel` used
+ * `ReadonlyMap`. The names suggested the inverse of their bodies; both
+ * interfaces now correctly typecheck as `ReadonlyMap<string, Row<T>>`.
+ *
+ * `ReadonlyRowModel` is currently unused inside scoria (no consumer beyond
+ * this file) but is retained as a public type for symmetry with `RowModel`
+ * and to support future read-only model exposure.
+ */
 export interface ReadonlyRowModel<T extends object> {
-    readonly rows: Array<Row<T>>;
-    readonly rowsById: SvelteMap<string, Row<T>>;
+    readonly rows: ReadonlyArray<Row<T>>;
+    readonly rowsById: ReadonlyMap<string, Row<T>>;
 }

package/dist/Components/Table/Types/Context/Row.d.ts

@@ -1,4 +1,22 @@
 import type { TableCell } from '../Columns/TableCell.js';
+/**
+ * `Row<T>` is the per-row handle the Table exposes to cells, repositories, and
+ * application code. Its `getValue` overload is the only point at which a
+ * column id is mapped to a value:
+ *
+ * - When the id is a known property of `T` (data-backed columns such as
+ *   `AccessorDef<T, K>`), the call returns `T[K] | Promise<T[K]>`. Consumers
+ *   in cell components can therefore drop `as` casts and read a narrow type.
+ * - Synthetic columns (`actions-<uuid>`, `is-selectable-<uuid>`, expand
+ *   markers and similar) do not correspond to a property on `T`. The fallback
+ *   `(columnId: string)` signature is retained for those calls and returns
+ *   `unknown | Promise<unknown>`; callers that need a concrete type must
+ *   still narrow it locally.
+ *
+ * The trade-off is intentional: the typed overload covers the common path
+ * (every accessor cell) while the looser signature keeps the synthetic
+ * columns compiling without runtime change.
+ */
 export interface Row<T extends object> {
     getValue: {
         <K extends keyof T>(columnId: K): T[K] | Promise<T[K]>;

package/dist/Components/Table/Types/Context/RowModel.d.ts

@@ -1,4 +1,15 @@
 import type { Row } from './Row.js';
+/**
+ * Mutable row-model container held by `TableContext`. The reactivity is
+ * carried by the surrounding `$state` cell on `TableContext`, not by the map
+ * itself (`new Map(...)` is sufficient because the whole `RowModel` is
+ * reassigned wholesale when sorting / pagination updates).
+ *
+ * - `rows` is the ordered array consumed by the body components.
+ * - `rowsById` is the lookup map. Typed as `ReadonlyMap` deliberately:
+ *   `TableContext` rebuilds the map rather than mutating it in place, and
+ *   downstream consumers must not write to it.
+ */
 export interface RowModel<T extends object> {
     rows: Array<Row<T>>;
     rowsById: ReadonlyMap<string, Row<T>>;