@lavalogic/scoria 0.37.56 → 0.38.0

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

@@ -2,16 +2,19 @@ import { ClipboardState } from './ClipboardState.svelte.js';
 import { PreferencesState } from './PreferencesState.svelte.js';
 import { QueryValuesState } from './QueryValuesState.svelte.js';
 import { SelectionState } from './SelectionState.svelte.js';
+import { ViewState } from './ViewState.svelte.js';
 import { SvelteMap } from 'svelte/reactivity';
 import type { Updater } from 'svelte/store';
 import type { ColumnPinningState } from '../Columns/ColumnPinningState.js';
 import type { ColumnSizingState } from '../Columns/ColumnSizingState.js';
 import type { ColumnDef } from '../Columns/Definitions/ColumnDef.svelte.js';
-import type { ColumnDefSet } from '../Columns/Definitions/ColumnDefSet.js';
 import type { DefsWrapper } from '../Columns/DefsWrapper.js';
 import type { VisibilityState } from '../Columns/VisibilityState.js';
 import type { CellCoordinates } from '../Coordinates/CellCoordinates.js';
 import type { VisualColumnIndex } from '../Coordinates/ColumnIndices.js';
+import type { RemoteTableLayoutAdapter } from '../Persistence/RemoteTableLayoutAdapter.js';
+import type { DatatableView } from '../Persistence/DatatableView.js';
+import type { DatatableViewKind } from '../Persistence/DatatableViewKind.js';
 import type { IDataRepository } from '../DataRepository/IDataRepository.js';
 import { SortingState } from './SortingState.svelte.js';
 import { FilteringState } from './FilteringState.svelte.js';
@@ -60,6 +63,18 @@ export declare class TableContext<T extends object, RowIdType extends Primitive>
     selectionExtractor: TableInitOptions<T, RowIdType>['selectionExtractor'];
     getUserId: () => string | undefined;
     private _onEditCell;
+    /**
+     * Stable per-table identifier supplied by the host app, or
+     * `undefined` when remote saved views are disabled. Stored only;
+     * later steps consume it.
+     */
+    readonly datatableUuid: string | undefined;
+    /**
+     * Injected backend adapter for saved layouts/filters, or
+     * `undefined` when remote saved views are disabled. Stored only;
+     * later steps consume it.
+     */
+    readonly remoteLayouts: RemoteTableLayoutAdapter | undefined;
     readonly debug: boolean;
     static readonly identifier: unique symbol;
     /**
@@ -71,7 +86,19 @@ export declare class TableContext<T extends object, RowIdType extends Primitive>
      * `init`.
      */
     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);
+    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'], 
+    /**
+     * Stable per-table identifier supplied by the host app, or
+     * `undefined` when remote saved views are disabled. Stored only;
+     * later steps consume it.
+     */
+    datatableUuid: string | undefined, 
+    /**
+     * Injected backend adapter for saved layouts/filters, or
+     * `undefined` when remote saved views are disabled. Stored only;
+     * later steps consume it.
+     */
+    remoteLayouts: RemoteTableLayoutAdapter | undefined, debug: boolean);
     private isSelectable;
     /**
      * `false` until the boot-time layout hydration (`_hydrateLayout`)
@@ -88,6 +115,13 @@ export declare class TableContext<T extends object, RowIdType extends Primitive>
      * to run after the component is gone.
      */
     private _layoutPersistTimer;
+    /**
+     * Pending debounce timer for the filter auto-persist. The filter
+     * counterpart of `_layoutPersistTimer`; deliberately not cleared on
+     * teardown for the same reason - a still-pending `persistFilter`
+     * write should flush, and it only touches `localStorage`.
+     */
+    private _filterPersistTimer;
     private _paginationRepo;
     get paginationRepo(): IDataRepository<T> | undefined;
     set paginationRepo(v: IDataRepository<T> | undefined);
@@ -129,16 +163,6 @@ export declare class TableContext<T extends object, RowIdType extends Primitive>
     /** Delegates to `_columnLayout.columnDefs`. */
     get columnDefs(): Array<ColumnDef<T>>;
     set columnDefs(v: Array<ColumnDef<T>>);
-    /**
-     * Delegates to `_preferences._columnPresets`. The setter is private
-     * because the public write path is `saveColumnPreset` (which also
-     * persists to localStorage); internal call sites that need to
-     * mutate the list directly call `_preferences.setPresets(...)`.
-     */
-    get columnPresets(): ReadonlyArray<ColumnDefSet<T>>;
-    /** Delegates to `_preferences._selectedPreset`. */
-    get selectedPreset(): ColumnDefSet<T> | undefined;
-    set selectedPreset(v: ColumnDefSet<T> | undefined);
     /**
      * Delegates to `_focus._focusedRowIndices`. Populated by the
      * focus-derived `$effect` in the constructor through
@@ -329,27 +353,81 @@ export declare class TableContext<T extends object, RowIdType extends Primitive>
     /**
      * Persistence / preferences sub-context:
      *
-     * - saved column-presets list and currently-selected preset
-     *   (`columnPresets`, `selectedPreset`);
      * - `userIdSegment` `$derived` (namespaces every
      *   `scoria-table:<user>:<tableName>:<suffix>` storage key);
-     * - `saveColumnPreset` / `setSelectedPreset` writers (apply layout
-     *   AND persist);
-     * - `loadPresets` / `loadSelectedPresetName` / `loadSavedSettings`
-     *   boot-time hydration helpers;
-     * - `persistSettings` writer used by the in-app settings toggles
+     * - `loadSavedSettings` boot-time hydration helper and the
+     *   `persistSettings` writer used by the in-app settings toggles
      *   (`setIsCompact`, `setAlternateRowColours`, etc.);
-     * - schema-validation typeguards (exported alongside the sub-context
-     *   for unit testing).
+     * - the layout / active-view / filter / active-filter-view
+     *   load / persist / clear helpers driving the FPM 403 datatable
+     *   views;
+     * - the `isSavedTableSettings` schema-validation typeguard (exported
+     *   alongside the sub-context for unit testing).
      *
      * The settings fields themselves (`isCompact`, `singleClickEditing`,
      * `alternateRowColours`, etc.) stay on `TableContext` because each
      * drives reactive UI; only the localStorage round-trip lives here.
-     * Delegating getters / setters / methods on `TableContext` cover the
-     * full surface (`columnPresets`, `selectedPreset`, `saveColumnPreset`,
-     * `setSelectedPreset`, `setIsCompact`, etc.).
      */
-    readonly _preferences: PreferencesState<T>;
+    readonly _preferences: PreferencesState;
+    /**
+     * Datatable view-selection sub-context (FPM 403):
+     *
+     * - `activeView` - which view the live table belongs to (the
+     *   code-defined Default layout, or a named saved `DatatableView`);
+     * - `isDirty` - whether the live layout has diverged from the active
+     *   view's saved baseline;
+     * - the saved views per kind - `'layout'` and `'filter'` - fetched
+     *   through the injected `remoteLayouts` adapter;
+     * - `dropdownLabel(kind)` - the `$derived` label the toolbar
+     *   view-picker renders.
+     *
+     * `ViewState` tracks the `'layout'` and `'filter'` kinds as two fully
+     * independent slices: applying or dirtying one never touches the
+     * other. It is a pure state holder - the apply / capture / baseline
+     * tracking / adapter calls all live on this class (`_applyLayout` /
+     * `_captureLayout` / `_applyFilter` / `_captureFilter`,
+     * `_viewBaseline` / `_filterBaseline`, the `applyDatatableView` /
+     * `resetToDefault` / `saveCurrentAsNewView` / `saveActiveView` /
+     * `refreshSavedViews` methods below), mirroring how `SelectionState`
+     * keeps its effects on the parent. The dirty comparisons run in the
+     * two debounced auto-persist `$effect`s in the constructor.
+     */
+    readonly _viewState: ViewState;
+    /**
+     * Baseline `JSONTableLayout` the dirty comparison is measured
+     * against: the saved state of whatever view `_viewState.activeView`
+     * points at. Set to the Default snapshot once `setupDefaultColumnDefs`
+     * completes, and re-pointed at a saved view's `body.layout` whenever
+     * one is applied. `undefined` only in the brief window before the
+     * boot chain captures the Default snapshot.
+     */
+    private _viewBaseline;
+    /**
+     * The Default-layout snapshot, captured once right after
+     * `setupDefaultColumnDefs` (before the working copy is applied). Kept
+     * separately from `_viewBaseline` so `resetToDefault` can restore the
+     * factory layout regardless of which saved view was active.
+     */
+    private _defaultLayoutSnapshot;
+    /**
+     * Baseline `JSONTableFilter` the *filter* dirty comparison is
+     * measured against: the saved state of whatever filter view
+     * `_viewState.activeView('filter')` points at. Set to the Default
+     * filter snapshot once the boot chain runs, and re-pointed at a saved
+     * view's `body.filter` whenever one is applied. The filter
+     * counterpart of `_viewBaseline`; kept entirely separate so layout
+     * and filter dirtiness never cross-contaminate.
+     */
+    private _filterBaseline;
+    /**
+     * The Default-filter snapshot, captured once during the boot chain
+     * (the empty / initial filter state, before the working copy is
+     * applied). Kept separately from `_filterBaseline` so a future
+     * filter-reset can restore the initial filter state regardless of
+     * which saved filter view was active. The filter counterpart of
+     * `_defaultLayoutSnapshot`.
+     */
+    private _defaultFilterSnapshot;
     /**
      * Selection + highlighting + key-cache sub-context:
      *
@@ -603,24 +681,6 @@ export declare class TableContext<T extends object, RowIdType extends Primitive>
     readonly setCopyWithHeaders: (value: boolean) => void;
     /** Toggles CSV vs TSV copy-to-clipboard separator and persists. */
     readonly setCommaSeparatedCopy: (value: boolean) => void;
-    /**
-     * Applies the preset to the live column layout, forwards the
-     * preset's `sortingState` to the data-repository updater, and
-     * persists the selected name. Delegates to
-     * `_preferences.setSelectedPreset`.
-     *
-     * The "no sorting state found" debug warning is emitted here (not
-     * inside the sub-context) so the public surface stays byte-identical
-     * - `_preferences.applySortingState` already no-ops when
-     * `paginationRepo.updateSorting` is absent.
-     */
-    readonly setSelectedPreset: (preset: ColumnDefSet<T>) => void;
-    /**
-     * Adds or replaces a saved preset for the current column layout and
-     * persists the full preset list to localStorage. Delegates to
-     * `_preferences.saveColumnPreset`.
-     */
-    readonly saveColumnPreset: (name: string) => void;
     /**
      * Delegates to `_focus.setFocusEnd`. This listener should be added
      * and removed based on `isMousingDown`.
@@ -656,6 +716,226 @@ export declare class TableContext<T extends object, RowIdType extends Primitive>
      * No-op when no snapshot is stored.
      */
     private _hydrateLayout;
+    /**
+     * Boot-time hydration for the FPM 403 view-state machine. Reads the
+     * persisted `JSONActiveView` envelope and restores the active-view
+     * selection on top of whatever `_hydrateLayout` produced:
+     *
+     * - no slot / Default ref: the active view stays Default and the
+     *   baseline stays the Default snapshot (already set by the caller);
+     * - a saved-view ref: `activeView` is re-pointed at it, and the
+     *   baseline is repointed at the matching view's `body.layout` IF the
+     *   saved-views list has already loaded. The list is fetched
+     *   fire-and-forget, so it usually has NOT loaded yet at boot - in
+     *   that case the persisted ref is restored as-is and `refreshSavedViews`
+     *   reconciles the baseline once the network resolves.
+     *
+     * The persisted `dirty` flag is restored verbatim via `markDirty`;
+     * the live working copy that `_hydrateLayout` applied is the source
+     * of truth for the layout contents.
+     *
+     * Runs before the `_layoutHydrated` gate opens so the auto-persist
+     * effect does not clobber the restored selection.
+     */
+    private _hydrateActiveView;
+    /**
+     * Re-point `_viewBaseline` at the active view's saved layout. For a
+     * Default active view the baseline is the Default snapshot; for a
+     * saved active view it is the matching `savedLayouts` entry's
+     * `body.layout` (when that entry is known - if the saved-views list
+     * has not loaded yet the baseline is left unchanged and is reconciled
+     * later by `refreshSavedViews`).
+     *
+     * Does NOT recompute the dirty flag - the next auto-persist tick does
+     * that against the updated baseline.
+     */
+    private _reconcileBaselineForActiveView;
+    /**
+     * Persist the current layout `{ active, dirty }` selection as a
+     * `JSONActiveView` envelope. Called (debounced) from the layout
+     * auto-persist `$effect` alongside the working-copy layout write.
+     */
+    private _persistActiveView;
+    /**
+     * Snapshot the live filter state - the per-column filter values and
+     * per-column filter modes - into the persistable `JSONTableFilter`
+     * shape. The filter counterpart of `_captureLayout`.
+     *
+     * Reads the repository's `filtering` array (`{ id, value }` entries)
+     * and `filterModes` map; reading both makes the filter auto-persist
+     * `$effect` re-subscribe whenever either changes. The `SvelteMap` of
+     * modes is flattened to a plain `Record<string,string>` (a `Map` does
+     * not survive `JSON.stringify`). Entries and mode keys are sorted so
+     * the captured object is deterministic and a stable `JSON.stringify`
+     * comparison drives the dirty flag.
+     *
+     * Sort order and pagination are deliberately excluded - a saved
+     * filter is values + modes only.
+     *
+     * `filtering` and `filterModes` are mandatory on the `IDataRepository`
+     * contract and present on every repo kind (local, built-in remote,
+     * custom remote), so no method is missing here; `Array.isArray` /
+     * `keys()` guard only against a genuinely malformed value.
+     */
+    private _captureFilter;
+    /**
+     * Apply a persisted `JSONTableFilter` to the live filter state. The
+     * filter counterpart of `_applyLayout`.
+     *
+     * 1. `resetFilters()` clears every active filter value first, so the
+     *    applied filter fully replaces (rather than merges into) whatever
+     *    was live;
+     * 2. each `{ id, value }` whose `id` still maps to a live column is
+     *    re-applied via `filterBy` - stale ids (a column removed since
+     *    the filter was saved) are dropped, mirroring how `_applyLayout`
+     *    drops unknown ids;
+     * 3. each mode whose `id` still maps to a live column AND whose mode
+     *    string is a recognised `StringFilterMode` / `NumberDateFilterMode`
+     *    value is re-applied via `setFilterMode`; unknown modes are
+     *    dropped rather than forwarded.
+     *
+     * Modes are applied before values so a value-bearing mode (e.g.
+     * "Empty") sees the column's mode already set. Defensive: a repo
+     * missing `resetFilters` / `filterBy` / `setFilterMode` no-ops the
+     * corresponding step rather than crashing.
+     */
+    private _applyFilter;
+    /**
+     * Boot-time hydration. Reads the auto-saved live-filter snapshot and
+     * applies it, restoring the user's last per-column filter values /
+     * modes. No-op when no snapshot is stored. The filter counterpart of
+     * `_hydrateLayout`.
+     */
+    private _hydrateFilter;
+    /**
+     * Boot-time hydration for the FPM 403 filter view-state machine.
+     * Reads the persisted *filter* `JSONActiveView` envelope and restores
+     * the filter active-view selection on top of whatever `_hydrateFilter`
+     * produced. The filter counterpart of `_hydrateActiveView`; runs
+     * independently and never touches the layout slice.
+     *
+     * Runs before the `_layoutHydrated` gate opens so the filter
+     * auto-persist effect does not clobber the restored selection.
+     */
+    private _hydrateActiveFilterView;
+    /**
+     * Re-point `_filterBaseline` at the active filter view's saved
+     * filter. The filter counterpart of `_reconcileBaselineForActiveView`:
+     * for a Default active filter view the baseline is the Default filter
+     * snapshot; for a saved one it is the matching saved-filter entry's
+     * `body.filter` (when that entry is known).
+     *
+     * Does NOT recompute the dirty flag - the next filter auto-persist
+     * tick does that against the updated baseline.
+     */
+    private _reconcileBaselineForActiveFilterView;
+    /**
+     * Persist the current filter `{ active, dirty }` selection as a
+     * `JSONActiveView` envelope into the `active-filter-view` slot.
+     * Called (debounced) from the filter auto-persist `$effect` alongside
+     * the working-copy filter write. The filter counterpart of
+     * `_persistActiveView`.
+     */
+    private _persistActiveFilterView;
+    /**
+     * Apply a saved `DatatableView` to the live table and mark it as the
+     * active view of its kind. Branches on `view.body.kind`:
+     *
+     * - `'layout'`: apply `view.body.layout` via `_applyLayout`, set the
+     *   *layout* active view to `{ kind:'saved', id, name }`, re-point the
+     *   *layout* baseline at that layout, clear the *layout* dirty flag.
+     *   The filter state, columns' filter values and the filter dirty
+     *   flag are left untouched.
+     * - `'filter'`: apply `view.body.filter` via `_applyFilter`, set the
+     *   *filter* active view, re-point the *filter* baseline at that
+     *   filter, clear the *filter* dirty flag. The column layout and the
+     *   layout dirty flag are left untouched.
+     *
+     * Applying one kind never mutates the other kind's state - the layout
+     * and filter view machines are fully independent.
+     *
+     * Bound as a class property so the toolbar view-picker (built later)
+     * can pass the reference around without re-binding `this`.
+     */
+    readonly applyDatatableView: (view: DatatableView) => void;
+    /**
+     * Reset the live table for `kind` back to its code-defined Default:
+     * apply the captured Default snapshot, set that kind's `activeView`
+     * back to Default, re-point that kind's baseline at the Default
+     * snapshot, and clear that kind's dirty flag.
+     *
+     * - `'layout'`: restores `_defaultLayoutSnapshot` via `_applyLayout`,
+     *   touching only the layout slice;
+     * - `'filter'`: restores `_defaultFilterSnapshot` via `_applyFilter`,
+     *   touching only the filter slice.
+     *
+     * Resetting one kind never mutates the other - it honours the same
+     * layout/filter independence guarantee as `applyDatatableView`.
+     *
+     * `kind` defaults to `'layout'` so the A2/A3 layout call sites that
+     * call `resetToDefault()` with no argument keep working unchanged.
+     *
+     * No-op (with a dev log) when the relevant Default snapshot has not
+     * been captured yet (i.e. before the boot chain completes).
+     *
+     * Bound as a class property so the toolbar view-picker and the Table
+     * Configuration modal can pass the reference around without
+     * re-binding `this`.
+     */
+    readonly resetToDefault: (kind?: DatatableViewKind) => void;
+    /**
+     * Save the live state of `kind` as a brand-new saved view through the
+     * injected `remoteLayouts` adapter:
+     *
+     * 1. build a `CreateDatatableViewRequest` whose `body` is, by `kind`,
+     *    either `{ kind:'layout', layout: _captureLayout() }` or
+     *    `{ kind:'filter', filter: _captureFilter() }`, plus the
+     *    host-supplied `datatableUuid` and the owning user;
+     * 2. `await remoteLayouts.createView(...)`;
+     * 3. push the returned `DatatableView` into the matching kind's
+     *    saved-views list;
+     * 4. apply it via `applyDatatableView`, which re-points that kind's
+     *    baseline and clears that kind's dirty flag.
+     *
+     * Only the named kind's state is touched. No-op (dev-logged via
+     * `devCatch`) when remote saved views are disabled (`datatableUuid` /
+     * `remoteLayouts` absent) or no owning user id is available - scoria
+     * stays backend-agnostic, so it never fabricates these. An adapter
+     * rejection is routed to `devCatch` and never breaks the table.
+     */
+    readonly saveCurrentAsNewView: (name: string, kind: DatatableViewKind) => Promise<void>;
+    /**
+     * Overwrite the currently-active saved view of `kind` with the live
+     * state of that kind through the injected `remoteLayouts` adapter:
+     *
+     * 1. require that kind's `activeView` to be `kind: 'saved'` (Default
+     *    cannot be saved over - the caller uses `saveCurrentAsNewView`
+     *    instead);
+     * 2. build an `UpdateDatatableViewRequest` whose `body` is the
+     *    captured live layout or filter, by `kind`;
+     * 3. `await remoteLayouts.updateView(...)`;
+     * 4. refresh the matching entry in that kind's saved-views list,
+     *    re-select it, re-point that kind's baseline, clear that kind's
+     *    dirty flag.
+     *
+     * Only the named kind's state is touched. No-op (dev-logged) when
+     * that kind's active view is Default or remote saved views are
+     * disabled. An adapter rejection is routed to `devCatch`.
+     */
+    readonly saveActiveView: (kind: DatatableViewKind) => Promise<void>;
+    /**
+     * Fetch the saved views for this datatable through the injected
+     * `remoteLayouts` adapter and publish them into `_viewState`, split by
+     * `kind`: `kind: 'layout'` views into the layout saved-views list and
+     * `kind: 'filter'` views into the filter saved-views list. After the
+     * lists land, reconcile both `_viewBaseline` and `_filterBaseline`
+     * against the now-known body of any persisted saved-view ref.
+     *
+     * No-op when remote saved views are disabled (`datatableUuid` /
+     * `remoteLayouts` absent). An adapter rejection is routed to
+     * `devCatch` and never breaks the table.
+     */
+    readonly refreshSavedViews: () => Promise<void>;
     /**
      * Drop the persisted live-layout snapshot for this table. The next
      * mount falls back to the default column layout. Exposed so a host
@@ -696,6 +976,5 @@ export declare class TableContext<T extends object, RowIdType extends Primitive>
     private _getUserDefaults;
     private _setNewPinningState;
     readonly getToggleSortingHandler: (def: ColumnDef<T>) => () => void;
-    private reassignDefsToPresets;
 }
 export declare function isSearchable<T extends object, FilterValueType, CD extends ColumnDef<T, FilterValueType>>(def: CD): def is CD & HasCustomFilterFunction;