@lavalogic/scoria 0.37.55 → 0.38.0

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

@@ -1,105 +1,62 @@
-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';
-import type { VisibilityState } from '../Columns/VisibilityState.js';
-import type { SortingState as SortingStateArray } from '../DataRepository/SortingState.js';
+import { type JSONActiveView } from '../Persistence/JSONActiveView.js';
+import { type JSONTableFilter } from '../Persistence/JSONTableFilter.js';
 import type { SavedTableSettings, TableSettings } from './TableSettings.js';
-/**
- * Conservative typeguard for the persisted preset list. Storage is
- * same-origin-writable so only the array shape can be trusted;
- * downstream `reassignDefsToPresets` performs deeper checks and drops
- * presets that fail. Asserts the outer envelope plus the bare minimum
- * per entry: a string `name` and an array `columnDefs`.
- */
-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.
  */
 export declare function isSavedTableSettings(raw: unknown): raw is SavedTableSettings;
-/**
- * Typeguard for a non-empty string. Used for the persisted selected
- * preset name slot.
- */
-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.
+ * `userIdSegment` derived reads `getUserId()` lazily.
  */
-export interface PreferencesStateDeps<T extends object> {
+export interface PreferencesStateDeps {
     /** 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. */
+     *  cannot read each other's persisted layout / filter state. */
     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. The
-     *  writer is a best-effort hook (`paginationRepo?.updateSorting?.()`
-     *  no-ops when no pagination repository is attached yet). */
-    applySortingState: (state: SortingStateArray) => void;
-    /** Logger gate; mirrors the parent `TableContext.debug` field. */
-    getDebug: () => boolean;
+    /** The stable per-table `datatableUuid` when the host supplied one
+     *  (FPM 403). Preferred over `getTableName()` for the storage-key
+     *  middle segment so two tables that happen to share the same `name`
+     *  do not collide on the same persisted slots. Returns `undefined`
+     *  for tables that opt out of datatable views. */
+    getDatatableUuid: () => string | undefined;
 }
 /**
  * Sub-context owning every persistence / preferences concern:
  *
- * - `_columnPresets` (persisted preset list `$state`);
- * - `_selectedPreset` (currently-active preset `$state`);
  * - `userIdSegment` (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);
- * - schema-validation typeguards (`isJSONColumnDefSetArray`,
- *   `isSavedTableSettings`, `isNonEmptyString`) - exported alongside
- *   the class.
+ * - `loadSavedSettings()` / `persistSettings()` (the per-table
+ *   TableSettings blob: compact, alternate rows, etc.);
+ * - `loadLayout()` / `persistLayout()` / `clearLayout()` (the
+ *   auto-saved live-layout working copy);
+ * - `loadActiveView()` / `persistActiveView()` / `clearActiveView()`
+ *   (the DB-backed view selection envelope);
+ * - the filter counterparts (`loadFilter` / `persistFilter` /
+ *   `clearFilter`, `loadActiveFilterView` / `persistActiveFilterView` /
+ *   `clearActiveFilterView`);
+ * - schema-validation typeguards (`isSavedTableSettings`) - exported
+ *   alongside the class.
  *
  * 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> {
+export declare class PreferencesState {
     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.
+     * cannot read each other's persisted layout / filter state, 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
@@ -112,54 +69,19 @@ export declare class PreferencesState<T extends object> {
      *             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);
+    constructor(deps: PreferencesStateDeps);
     /**
-     * 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' | 'layout'): 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.
+     * Build the canonical `scoria-table:<user>:<scope>:<suffix>` storage
+     * key. Centralised so every persisted-state slot reaches for the same
+     * namespacing convention; the `<user>` segment is `getUserId() ??
+     * 'anon'` (see `userIdSegment`).
      *
-     * `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).
-     * Emits a dev-only warning on `getItem` failure.
+     * The `<scope>` segment is the host-supplied `datatableUuid` when one
+     * is present, falling back to the table `name`. Preferring the UUID
+     * keeps two tables that share a `name` option from colliding on the
+     * same localStorage slots.
      */
-    loadSelectedPresetName(): string | null;
+    storageKey(suffix: 'settings' | 'layout' | 'active-view' | 'filter' | 'active-filter-view'): string;
     /**
      * Boot-time hydration helper. Reads the persisted per-table
      * settings blob (`isCompact`, `singleClickEditing`, etc.). Returns
@@ -167,12 +89,6 @@ export declare class PreferencesState<T extends object> {
      * 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;
     /**
      * Boot-time hydration helper. Reads the auto-saved live-layout
      * snapshot (column order / visibility / pinning / sizing the user
@@ -198,43 +114,86 @@ export declare class PreferencesState<T extends object> {
      */
     clearLayout(): void;
     /**
-     * Persist the selected-preset name as plain text (no JSON
-     * envelope - the slot is a single string by design).
+     * Boot-time hydration helper. Reads the persisted active-view
+     * envelope (which saved view, if any, the live working copy belongs
+     * to, plus its dirty flag). 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 view.
+     *
+     * `localStorage` access is gated by the parent's `browser` check;
+     * this method assumes the caller already verified the environment.
      */
-    persistSelectedPresetName(name: string): void;
+    loadActiveView(): JSONActiveView | null;
     /**
-     * Persist the per-table settings blob (`isCompact`,
-     * `singleClickEditing`, etc.) as JSON.
+     * Persist the active-view envelope. Written by the parent (debounced,
+     * alongside the working-copy layout) on every layout change, wrapped
+     * in a versioned envelope so a future schema bump drops stale
+     * snapshots cleanly. Storage failures are swallowed inside
+     * `writeJSON`.
      */
-    persistSettings(settings: TableSettings): void;
+    persistActiveView(v: JSONActiveView): 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`.
+     * Drop the persisted active-view envelope. Called when table state is
+     * explicitly reset; the next mount falls back to the Default view.
      */
-    persistPresets(presets: ReadonlyArray<ColumnDefSet<T>>): void;
+    clearActiveView(): void;
     /**
-     * Apply a saved column preset to the live table layout and persist
-     * the selection by name:
+     * Boot-time hydration helper. Reads the auto-saved live-filter
+     * snapshot (the per-column filter values and modes the user built up
+     * in the quick-filter row / advanced filter panel without saving a
+     * named view). Returns `null` for a missing slot, a schema-version
+     * mismatch, or a value that fails validation, so the parent can fall
+     * back to the empty filter state.
      *
-     * 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`.
+     * The filter counterpart of `loadLayout`. `localStorage` access is
+     * gated by the parent's `browser` check; this method assumes the
+     * caller already verified the environment.
+     */
+    loadFilter(): JSONTableFilter | null;
+    /**
+     * Persist the live-filter snapshot. Written by the parent (debounced)
+     * on every filter value / mode change, wrapped in a versioned
+     * envelope so a future schema bump drops stale snapshots cleanly.
+     * Storage failures are swallowed inside `writeJSON`. The filter
+     * counterpart of `persistLayout`.
+     */
+    persistFilter(filter: JSONTableFilter): void;
+    /**
+     * Drop the persisted live-filter snapshot. Called when the snapshot
+     * no longer matches the table's column set (schema drift) or when
+     * table state is explicitly reset. The filter counterpart of
+     * `clearLayout`.
+     */
+    clearFilter(): void;
+    /**
+     * Boot-time hydration helper. Reads the persisted *filter*
+     * active-view envelope (which saved filter view, if any, the live
+     * filter working copy belongs to, plus its dirty flag). 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
+     * filter view. The filter counterpart of `loadActiveView`.
      *
-     * Bound as a class property so callers (notably the toolbar
-     * dropdown) can pass the reference around without binding `this`.
+     * `localStorage` access is gated by the parent's `browser` check;
+     * this method assumes the caller already verified the environment.
+     */
+    loadActiveFilterView(): JSONActiveView | null;
+    /**
+     * Persist the *filter* active-view envelope. Written by the parent
+     * (debounced, alongside the working-copy filter) on every filter
+     * change, wrapped in a versioned envelope so a future schema bump
+     * drops stale snapshots cleanly. Storage failures are swallowed
+     * inside `writeJSON`. The filter counterpart of `persistActiveView`.
      */
-    readonly setSelectedPreset: (preset: ColumnDefSet<T>) => void;
+    persistActiveFilterView(v: JSONActiveView): 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). No-op when
-     * `name` is empty.
+     * Drop the persisted *filter* active-view envelope. Called when table
+     * state is explicitly reset; the next mount falls back to the Default
+     * filter view. The filter counterpart of `clearActiveView`.
      */
-    readonly saveColumnPreset: (name: string) => void;
+    clearActiveFilterView(): void;
+    /**
+     * Persist the per-table settings blob (`isCompact`,
+     * `singleClickEditing`, etc.) as JSON.
+     */
+    persistSettings(settings: TableSettings): void;
 }