@lavalogic/scoria 0.37.55 → 0.38.0

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

@@ -1,4 +1,5 @@
 import type { CellCoordinates } from '../Coordinates/CellCoordinates.js';
+import type { RemoteTableLayoutAdapter } from '../Persistence/RemoteTableLayoutAdapter.js';
 import type { ToolbarPosition } from '../Toolbar/ToolbarPosition.js';
 /** Allowable primary-key types for the table's `selectionExtractor`. */
 export type Primitive = string | number;
@@ -29,5 +30,13 @@ export interface TableInitOptions<T extends object, Identifier extends Primitive
     displayFooter?: boolean;
     onEditCell?: (item: T, coords: CellCoordinates, value: unknown) => void | Promise<void>;
     getUserId: () => string | undefined;
+    /** Stable per-table identifier supplied by the host app. Identifies
+     *  which datatable saved views belong to. Omit to disable remote views
+     *  (the table then behaves exactly as before). */
+    datatableUuid?: string;
+    /** Injected backend adapter for saved layouts/filters. Omit to disable
+     *  remote views. scoria stays backend-agnostic; the host app supplies
+     *  this. */
+    remoteLayouts?: RemoteTableLayoutAdapter;
     debug?: boolean;
 }

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

@@ -0,0 +1,152 @@
+import type { DatatableView } from '../Persistence/DatatableView.js';
+import type { DatatableViewKind } from '../Persistence/DatatableViewKind.js';
+import type { ActiveViewRef } from '../Persistence/JSONActiveView.js';
+/**
+ * Sub-context owning the datatable *view selection* state machine for
+ * **both** view kinds - column `'layout'` and `'filter'` - as two fully
+ * independent slices (see `ViewKindSlice`). For each kind it tracks:
+ *
+ * - `activeView` - which view the live table belongs to (the code-defined
+ *   Default, or a named saved `DatatableView`);
+ * - `isDirty` - whether the live state has diverged from the active
+ *   view's saved baseline;
+ * - the saved views of that kind fetched through the injected
+ *   `RemoteTableLayoutAdapter`;
+ * - `dropdownLabel` - the `$derived` label the toolbar view-picker
+ *   renders (`'Default'` / `'Custom (unsaved)'` / `'<name>'` / `'<name>
+ *   (unsaved)'`).
+ *
+ * Layouts and filters are *fully independent*: applying or dirtying one
+ * kind never touches the other. The two slices share only the
+ * `deriveDropdownLabel` formatting logic.
+ *
+ * It is a deliberately *pure state holder*: it never applies a layout or
+ * filter to the live table and never calls the remote adapter. Those side
+ * effects live on `TableContext` (which owns `_applyLayout` /
+ * `_captureLayout` / `_applyFilter` / `_captureFilter`, the baseline
+ * tracking and the adapter wiring), mirroring how `SelectionState` and
+ * `PreferencesState` keep their effects on the parent. `TableContext`
+ * drives this sub-context through the writer methods below.
+ *
+ * The sub-context holds no parent reference; it has no dependency thunks
+ * because it reads nothing from the parent - the parent pushes state in.
+ *
+ * ## Public surface
+ *
+ * The kind-aware methods (`markDirty(kind, ...)`,
+ * `selectDefault(kind)`, `selectSavedView(kind, ...)`,
+ * `setActiveView(kind, ...)`, `setSavedViews(kind, ...)`) and the
+ * per-kind getters (`activeView(kind)`, `isDirty(kind)`,
+ * `savedViews(kind)`, `dropdownLabel(kind)`) are the canonical surface.
+ * The unsuffixed `*Layout` aliases (`savedLayouts`, plus the
+ * single-arg behaviour of the kind methods defaulting to `'layout'`)
+ * are retained for the A2 layout call sites.
+ */
+export declare class ViewState {
+    /** Layout-kind slice (column order / visibility / pinning / width). */
+    private readonly _layout;
+    /** Filter-kind slice (per-column filter values and modes). */
+    private readonly _filter;
+    /**
+     * Toolbar label `$derived` for the **layout** kind. Kept as a field
+     * (rather than a method) so the existing A2 layout call sites that
+     * read `dropdownLabelFor('layout')` and the legacy `layoutDropdownLabel`
+     * stay reactive without re-deriving on every read.
+     *
+     * - `'Default'` - Default active, not dirty;
+     * - `'Custom (unsaved)'` - Default active, dirty;
+     * - `'<name>'` - a saved view is active and unmodified;
+     * - `'<name> (unsaved)'` - a saved view is active but has been edited.
+     */
+    readonly layoutDropdownLabel: string;
+    /**
+     * Toolbar label `$derived` for the **filter** kind. Same four-way
+     * matrix as `layoutDropdownLabel`, computed independently from the
+     * filter slice.
+     */
+    readonly filterDropdownLabel: string;
+    /**
+     * Shared label-formatting logic for both kinds. The four-way branch is
+     * driven purely by the active-view ref and the dirty flag, so it is
+     * identical for layouts and filters - hence factored out as a static
+     * pure function consumed by both `$derived` labels above.
+     *
+     * - Default active: `'Default'` (clean) / `'Custom (unsaved)'` (dirty);
+     * - saved active: `'<name>'` (clean) / `'<name> (unsaved)'` (dirty).
+     */
+    private static deriveDropdownLabel;
+    /** Resolve the mutable slice for a `DatatableViewKind`. */
+    private slice;
+    /**
+     * The view the live table currently belongs to for `kind`. Read-only
+     * externally; the writers are `selectDefault` / `selectSavedView` /
+     * `setActiveView`.
+     */
+    activeView(kind: DatatableViewKind): ActiveViewRef;
+    /**
+     * Whether the live state of `kind` has diverged from the active
+     * view's saved baseline. Read-only externally; the writer is
+     * `markDirty`.
+     */
+    isDirty(kind: DatatableViewKind): boolean;
+    /**
+     * The saved views of `kind` available in the view-picker. Read-only
+     * externally; the writer is `setSavedViews`.
+     */
+    savedViews(kind: DatatableViewKind): ReadonlyArray<DatatableView>;
+    /**
+     * The toolbar label for `kind` (see `layoutDropdownLabel` /
+     * `filterDropdownLabel`). A thin kind-keyed accessor over the two
+     * `$derived` label fields.
+     */
+    dropdownLabel(kind: DatatableViewKind): string;
+    /**
+     * Set the dirty flag for `kind`. Called by the parent's debounced
+     * auto-persist `$effect` after comparing the freshly captured layout /
+     * filter against the current baseline. Idempotent - reassigning the
+     * same value short-circuits to avoid a redundant `$state` write.
+     */
+    markDirty(kind: DatatableViewKind, dirty: boolean): void;
+    /**
+     * Mark the Default view of `kind` as active and clear that kind's
+     * dirty flag. The parent calls this after applying the Default
+     * baseline to the live table (`resetToDefault`) or when boot
+     * hydration finds no persisted saved-view ref for the kind. Only the
+     * named kind's slice is touched.
+     */
+    selectDefault(kind: DatatableViewKind): void;
+    /**
+     * Mark a saved view of `kind` as active and clear that kind's dirty
+     * flag. The `ref` carries the server-assigned id and the cached
+     * display name. The parent calls this after applying the view to the
+     * live table (`applyDatatableView` / `saveCurrentAsNewView`) or when
+     * boot hydration restores a persisted saved-view ref. Only the named
+     * kind's slice is touched.
+     */
+    selectSavedView(kind: DatatableViewKind, ref: {
+        id: string;
+        name: string;
+    }): void;
+    /**
+     * Set the active view of `kind` directly from a persisted
+     * `ActiveViewRef`. Used by boot hydration, which reads the
+     * `JSONActiveView` envelope and must restore whatever ref it recorded
+     * *without* clearing the dirty flag (the persisted `dirty` value is
+     * restored separately via `markDirty`). Prefer `selectDefault` /
+     * `selectSavedView` for the normal apply flows, which also reset
+     * dirty.
+     */
+    setActiveView(kind: DatatableViewKind, ref: ActiveViewRef): void;
+    /**
+     * Replace the saved-views list for `kind` with a defensive copy.
+     * Called by the parent when the boot-time `refreshSavedViews` fetch
+     * resolves and after each save flow mutates the list. Only the named
+     * kind's slice is touched.
+     */
+    setSavedViews(kind: DatatableViewKind, views: ReadonlyArray<DatatableView>): void;
+    /**
+     * The `kind: 'layout'` saved views. A2 compatibility alias for
+     * `savedViews('layout')`.
+     */
+    get savedLayouts(): ReadonlyArray<DatatableView>;
+}

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

@@ -0,0 +1,223 @@
+/**
+ * Per-kind slice of the view-selection state machine - the mutable state
+ * for *one* `DatatableViewKind` (`'layout'` or `'filter'`):
+ *
+ * - `activeView` - which view of this kind the live table belongs to (the
+ *   code-defined Default, or a named saved `DatatableView`);
+ * - `isDirty` - whether the live state of this kind has diverged from the
+ *   active view's saved baseline;
+ * - `savedViews` - the saved views of this kind fetched through the
+ *   injected `RemoteTableLayoutAdapter`.
+ *
+ * `ViewState` holds one `ViewKindSlice` per kind so the two are *fully
+ * independent*: dirtying or applying a layout view never touches the
+ * filter slice and vice versa. The `$state` fields live here (rather than
+ * on `ViewState`) so each slice is an independent reactive unit.
+ */
+class ViewKindSlice {
+    /**
+     * The view of this kind the live table currently belongs to. Defaults
+     * to the code-defined Default. Written by the parent through
+     * `selectDefault` / `selectSavedView` when a view is applied (or
+     * restored at boot).
+     */
+    activeView = $state({ kind: 'default' });
+    /**
+     * `true` when the live state of this kind has diverged from the active
+     * view's saved baseline. Written by the parent's debounced
+     * auto-persist `$effect` through `ViewState.markDirty`.
+     */
+    isDirty = $state(false);
+    /**
+     * The saved views of this kind fetched through the injected
+     * `RemoteTableLayoutAdapter`. Empty when remote saved views are
+     * disabled or the fetch has not completed.
+     */
+    savedViews = $state([]);
+}
+/**
+ * Sub-context owning the datatable *view selection* state machine for
+ * **both** view kinds - column `'layout'` and `'filter'` - as two fully
+ * independent slices (see `ViewKindSlice`). For each kind it tracks:
+ *
+ * - `activeView` - which view the live table belongs to (the code-defined
+ *   Default, or a named saved `DatatableView`);
+ * - `isDirty` - whether the live state has diverged from the active
+ *   view's saved baseline;
+ * - the saved views of that kind fetched through the injected
+ *   `RemoteTableLayoutAdapter`;
+ * - `dropdownLabel` - the `$derived` label the toolbar view-picker
+ *   renders (`'Default'` / `'Custom (unsaved)'` / `'<name>'` / `'<name>
+ *   (unsaved)'`).
+ *
+ * Layouts and filters are *fully independent*: applying or dirtying one
+ * kind never touches the other. The two slices share only the
+ * `deriveDropdownLabel` formatting logic.
+ *
+ * It is a deliberately *pure state holder*: it never applies a layout or
+ * filter to the live table and never calls the remote adapter. Those side
+ * effects live on `TableContext` (which owns `_applyLayout` /
+ * `_captureLayout` / `_applyFilter` / `_captureFilter`, the baseline
+ * tracking and the adapter wiring), mirroring how `SelectionState` and
+ * `PreferencesState` keep their effects on the parent. `TableContext`
+ * drives this sub-context through the writer methods below.
+ *
+ * The sub-context holds no parent reference; it has no dependency thunks
+ * because it reads nothing from the parent - the parent pushes state in.
+ *
+ * ## Public surface
+ *
+ * The kind-aware methods (`markDirty(kind, ...)`,
+ * `selectDefault(kind)`, `selectSavedView(kind, ...)`,
+ * `setActiveView(kind, ...)`, `setSavedViews(kind, ...)`) and the
+ * per-kind getters (`activeView(kind)`, `isDirty(kind)`,
+ * `savedViews(kind)`, `dropdownLabel(kind)`) are the canonical surface.
+ * The unsuffixed `*Layout` aliases (`savedLayouts`, plus the
+ * single-arg behaviour of the kind methods defaulting to `'layout'`)
+ * are retained for the A2 layout call sites.
+ */
+export class ViewState {
+    /** Layout-kind slice (column order / visibility / pinning / width). */
+    _layout = new ViewKindSlice();
+    /** Filter-kind slice (per-column filter values and modes). */
+    _filter = new ViewKindSlice();
+    /**
+     * Toolbar label `$derived` for the **layout** kind. Kept as a field
+     * (rather than a method) so the existing A2 layout call sites that
+     * read `dropdownLabelFor('layout')` and the legacy `layoutDropdownLabel`
+     * stay reactive without re-deriving on every read.
+     *
+     * - `'Default'` - Default active, not dirty;
+     * - `'Custom (unsaved)'` - Default active, dirty;
+     * - `'<name>'` - a saved view is active and unmodified;
+     * - `'<name> (unsaved)'` - a saved view is active but has been edited.
+     */
+    layoutDropdownLabel = $derived.by(() => ViewState.deriveDropdownLabel(this._layout.activeView, this._layout.isDirty));
+    /**
+     * Toolbar label `$derived` for the **filter** kind. Same four-way
+     * matrix as `layoutDropdownLabel`, computed independently from the
+     * filter slice.
+     */
+    filterDropdownLabel = $derived.by(() => ViewState.deriveDropdownLabel(this._filter.activeView, this._filter.isDirty));
+    /**
+     * Shared label-formatting logic for both kinds. The four-way branch is
+     * driven purely by the active-view ref and the dirty flag, so it is
+     * identical for layouts and filters - hence factored out as a static
+     * pure function consumed by both `$derived` labels above.
+     *
+     * - Default active: `'Default'` (clean) / `'Custom (unsaved)'` (dirty);
+     * - saved active: `'<name>'` (clean) / `'<name> (unsaved)'` (dirty).
+     */
+    static deriveDropdownLabel(active, dirty) {
+        if (active.kind === 'default') {
+            return dirty ? 'Custom (unsaved)' : 'Default';
+        }
+        return dirty ? `${active.name} (unsaved)` : active.name;
+    }
+    /** Resolve the mutable slice for a `DatatableViewKind`. */
+    slice(kind) {
+        return kind === 'filter' ? this._filter : this._layout;
+    }
+    // #region kind-aware getters
+    /**
+     * The view the live table currently belongs to for `kind`. Read-only
+     * externally; the writers are `selectDefault` / `selectSavedView` /
+     * `setActiveView`.
+     */
+    activeView(kind) {
+        return this.slice(kind).activeView;
+    }
+    /**
+     * Whether the live state of `kind` has diverged from the active
+     * view's saved baseline. Read-only externally; the writer is
+     * `markDirty`.
+     */
+    isDirty(kind) {
+        return this.slice(kind).isDirty;
+    }
+    /**
+     * The saved views of `kind` available in the view-picker. Read-only
+     * externally; the writer is `setSavedViews`.
+     */
+    savedViews(kind) {
+        return this.slice(kind).savedViews;
+    }
+    /**
+     * The toolbar label for `kind` (see `layoutDropdownLabel` /
+     * `filterDropdownLabel`). A thin kind-keyed accessor over the two
+     * `$derived` label fields.
+     */
+    dropdownLabel(kind) {
+        return kind === 'filter' ? this.filterDropdownLabel : this.layoutDropdownLabel;
+    }
+    // #endregion
+    // #region kind-aware writers
+    /**
+     * Set the dirty flag for `kind`. Called by the parent's debounced
+     * auto-persist `$effect` after comparing the freshly captured layout /
+     * filter against the current baseline. Idempotent - reassigning the
+     * same value short-circuits to avoid a redundant `$state` write.
+     */
+    markDirty(kind, dirty) {
+        const slice = this.slice(kind);
+        if (dirty === slice.isDirty) {
+            return;
+        }
+        slice.isDirty = dirty;
+    }
+    /**
+     * Mark the Default view of `kind` as active and clear that kind's
+     * dirty flag. The parent calls this after applying the Default
+     * baseline to the live table (`resetToDefault`) or when boot
+     * hydration finds no persisted saved-view ref for the kind. Only the
+     * named kind's slice is touched.
+     */
+    selectDefault(kind) {
+        const slice = this.slice(kind);
+        slice.activeView = { kind: 'default' };
+        slice.isDirty = false;
+    }
+    /**
+     * Mark a saved view of `kind` as active and clear that kind's dirty
+     * flag. The `ref` carries the server-assigned id and the cached
+     * display name. The parent calls this after applying the view to the
+     * live table (`applyDatatableView` / `saveCurrentAsNewView`) or when
+     * boot hydration restores a persisted saved-view ref. Only the named
+     * kind's slice is touched.
+     */
+    selectSavedView(kind, ref) {
+        const slice = this.slice(kind);
+        slice.activeView = { kind: 'saved', id: ref.id, name: ref.name };
+        slice.isDirty = false;
+    }
+    /**
+     * Set the active view of `kind` directly from a persisted
+     * `ActiveViewRef`. Used by boot hydration, which reads the
+     * `JSONActiveView` envelope and must restore whatever ref it recorded
+     * *without* clearing the dirty flag (the persisted `dirty` value is
+     * restored separately via `markDirty`). Prefer `selectDefault` /
+     * `selectSavedView` for the normal apply flows, which also reset
+     * dirty.
+     */
+    setActiveView(kind, ref) {
+        this.slice(kind).activeView = ref;
+    }
+    /**
+     * Replace the saved-views list for `kind` with a defensive copy.
+     * Called by the parent when the boot-time `refreshSavedViews` fetch
+     * resolves and after each save flow mutates the list. Only the named
+     * kind's slice is touched.
+     */
+    setSavedViews(kind, views) {
+        this.slice(kind).savedViews = [...views];
+    }
+    // #endregion
+    // #region layout-kind aliases (A2 call-site compatibility)
+    /**
+     * The `kind: 'layout'` saved views. A2 compatibility alias for
+     * `savedViews('layout')`.
+     */
+    get savedLayouts() {
+        return this._layout.savedViews;
+    }
+}

package/dist/Components/Table/Types/ExpandedPanel.d.ts

@@ -1,16 +1,20 @@
 /**
  * Discriminator on the currently-visible toolbar sidebar panel:
  *
- * - `None`    - no panel open (currently the `null` state is preferred in
- *   `TableSidebar.svelte`; `None` is kept for symmetry but unused).
- * - `Column`  - column-picker panel.
- * - `Filter`  - advanced filter panel.
- * - `Toolbox` - settings / toolbox panel.
+ * - `None`          - no panel open (currently the `null` state is
+ *   preferred in `TableSidebar.svelte`; `None` is kept for symmetry but
+ *   unused).
+ * - `Column`        - column-picker panel.
+ * - `Filter`        - advanced filter panel.
+ * - `Toolbox`       - settings / toolbox panel.
+ * - `Configuration` - FPM 403 "Table Configuration" modal: saved
+ *   datatable layouts and filters (the new view system).
  */
 export declare const ExpandedPanel: {
     readonly None: "None";
     readonly Column: "Column";
     readonly Filter: "Filter";
     readonly Toolbox: "Toolbox";
+    readonly Configuration: "Configuration";
 };
 export type ExpandedPanel = (typeof ExpandedPanel)[keyof typeof ExpandedPanel];

package/dist/Components/Table/Types/ExpandedPanel.js

@@ -1,16 +1,20 @@
 /**
  * Discriminator on the currently-visible toolbar sidebar panel:
  *
- * - `None`    - no panel open (currently the `null` state is preferred in
- *   `TableSidebar.svelte`; `None` is kept for symmetry but unused).
- * - `Column`  - column-picker panel.
- * - `Filter`  - advanced filter panel.
- * - `Toolbox` - settings / toolbox panel.
+ * - `None`          - no panel open (currently the `null` state is
+ *   preferred in `TableSidebar.svelte`; `None` is kept for symmetry but
+ *   unused).
+ * - `Column`        - column-picker panel.
+ * - `Filter`        - advanced filter panel.
+ * - `Toolbox`       - settings / toolbox panel.
+ * - `Configuration` - FPM 403 "Table Configuration" modal: saved
+ *   datatable layouts and filters (the new view system).
  */
 export const ExpandedPanel = {
     None: 'None',
     Column: 'Column',
     Filter: 'Filter',
     Toolbox: 'Toolbox',
+    Configuration: 'Configuration',
 };
 Object.freeze(ExpandedPanel);

package/dist/Components/Table/Types/Persistence/DatatableView.d.ts

@@ -0,0 +1,95 @@
+import type { DatatableViewBody } from './DatatableViewEnvelope.js';
+import type { DatatableViewKind } from './DatatableViewKind.js';
+/**
+ * A saved datatable view - a named, persisted column layout or filter
+ * that round-trips through a `RemoteTableLayoutAdapter`. This is the
+ * frozen DTO contract the consuming host app codes against; scoria
+ * itself stays backend-agnostic and never constructs the persistence.
+ *
+ * Ownership and sharing in v1:
+ * - The UI always creates exactly one owner: the user who creates the
+ *   view (`ownerUserId`). scoria never interprets that identifier - it
+ *   is an opaque token supplied and understood only by the host app.
+ * - The backend's `editor` permission and `systemOwned` flag are
+ *   reserved no-ops in v1: scoria never sets them and never relies on
+ *   them. Sharing is subscriber-only (see `DatatableViewSubscription`).
+ */
+export interface DatatableView {
+    /** Server-assigned, opaque record id. Set by the backend on create;
+     *  scoria treats it as a meaningless handle for update/delete. */
+    id: string;
+    /** Stable identifier of the datatable this view belongs to (the
+     *  `datatableUuid` constant supplied by the host app). */
+    datatableUuid: string;
+    /** Whether this view holds a column layout or a filter. Matches the
+     *  `kind` discriminant of `body`. */
+    kind: DatatableViewKind;
+    /** Human-readable name shown in the saved-views picker. */
+    name: string;
+    /** The typed payload: a `JSONTableLayout` or a `JSONTableFilter`,
+     *  discriminated by `kind`. */
+    body: DatatableViewBody;
+    /** Opaque identifier of the user who owns this view. scoria never
+     *  interprets it; the UI always sets it to the creating user. */
+    ownerUserId: string;
+    /**
+     * The users this view is currently shared with (v1 sharing is
+     * subscriber-only - see `DatatableViewSubscription`). Optional: the
+     * backend populates it on a view the *current* user owns so the
+     * Table Configuration modal can list and manage subscribers. It is
+     * omitted (or empty) on views the current user merely subscribes to
+     * - a non-owner has no business seeing the full subscriber roster.
+     *
+     * Added in A4a (the modal needs to render an owner's subscriber list
+     * and an Unsubscribe control). scoria never interprets the entries;
+     * `userId` is the same opaque token as `ownerUserId`. `displayName`
+     * is an optional human-readable label the host may attach for the
+     * UI - scoria falls back to `userId` when it is absent.
+     */
+    subscribers?: ReadonlyArray<DatatableViewSubscriber>;
+}
+/**
+ * One entry in a `DatatableView.subscribers` roster: an opaque user
+ * identifier plus an optional human-readable label. scoria never
+ * interprets `userId`; `displayName`, when supplied by the host, is
+ * shown in the Table Configuration modal in preference to the raw id.
+ */
+export interface DatatableViewSubscriber {
+    /** Opaque identifier of the subscribed user (same token space as
+     *  `DatatableView.ownerUserId`). */
+    userId: string;
+    /** Optional human-readable label for the subscriber. The modal falls
+     *  back to `userId` when this is absent. */
+    displayName?: string;
+}
+/**
+ * Request payload for creating a brand-new `DatatableView`. Identical to
+ * `DatatableView` except the server-assigned `id` is omitted - the
+ * backend assigns it and returns the complete record.
+ */
+export type CreateDatatableViewRequest = Omit<DatatableView, 'id'>;
+/**
+ * Request payload for updating an existing `DatatableView`. `id`
+ * identifies the record; `name` and `body` are each optional so a caller
+ * can patch either independently (rename without re-sending the body, or
+ * replace the body without renaming).
+ */
+export interface UpdateDatatableViewRequest {
+    /** Server-assigned id of the view to update. */
+    id: string;
+    /** New name, if the view is being renamed. */
+    name?: string;
+    /** New payload, if the layout/filter is being replaced. */
+    body?: DatatableViewBody;
+}
+/**
+ * A subscriber relationship for a shared `DatatableView`. v1 sharing is
+ * subscriber-only: a non-owner is granted read access by being added as
+ * a subscriber (there is no `editor` role in v1).
+ */
+export interface DatatableViewSubscription {
+    /** Id of the `DatatableView` being shared. */
+    viewId: string;
+    /** Opaque identifier of the subscribed user. */
+    userId: string;
+}

package/dist/Components/Table/Types/Persistence/DatatableViewEnvelope.d.ts

@@ -0,0 +1,21 @@
+import type { JSONTableLayout } from '../Columns/JSONTableLayout.js';
+import type { JSONTableFilter } from './JSONTableFilter.js';
+/**
+ * The typed payload body stored inside a saved `DatatableView`, as a
+ * discriminated union keyed on `kind`:
+ *
+ * - `{ kind: 'layout' }` carries a `JSONTableLayout` (column order,
+ *   visibility, pinning, width).
+ * - `{ kind: 'filter' }` carries a `JSONTableFilter` (per-column filter
+ *   values and modes).
+ *
+ * The `kind` tag matches the `DatatableView.kind` field, so a caller can
+ * narrow the body by switching on a single discriminant.
+ */
+export type DatatableViewBody = {
+    kind: 'layout';
+    layout: JSONTableLayout;
+} | {
+    kind: 'filter';
+    filter: JSONTableFilter;
+};

package/dist/Components/Table/Types/Persistence/DatatableViewEnvelope.js

@@ -0,0 +1 @@
+export {};

package/dist/Components/Table/Types/Persistence/DatatableViewKind.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Discriminant for a saved `DatatableView`: whether the record holds a
+ * column layout (`'layout'` - order / visibility / pinning / width) or a
+ * filter (`'filter'` - per-column filter values and modes).
+ *
+ * The same value appears both on the `DatatableView` DTO and as the
+ * `kind` tag of the `DatatableViewBody` discriminated union, so a caller
+ * can switch on a single field to know which payload shape it holds.
+ */
+export type DatatableViewKind = 'layout' | 'filter';

package/dist/Components/Table/Types/Persistence/DatatableViewKind.js

@@ -0,0 +1 @@
+export {};

package/dist/Components/Table/Types/Persistence/JSONActiveView.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Reference to the datatable view currently driving the table - either the
+ * code-defined Default layout, or a named saved view round-tripped through
+ * a `RemoteTableLayoutAdapter`.
+ *
+ * Discriminated on `kind`:
+ * - `{ kind: 'default' }` - the live table is tracking the factory column
+ *   defs (no saved view selected);
+ * - `{ kind: 'saved', id, name }` - a saved `DatatableView` is selected.
+ *   `id` is the server-assigned record id; `name` is cached alongside it
+ *   so the dropdown label can render before the saved-view list has been
+ *   fetched (boot-time hydration reads this before the network resolves).
+ */
+export type ActiveViewRef = {
+    kind: 'default';
+} | {
+    kind: 'saved';
+    id: string;
+    name: string;
+};
+/**
+ * Persisted-to-localStorage record of which datatable view is active and
+ * whether the live table has diverged from that view's saved baseline.
+ *
+ * This is the view-selection counterpart of `JSONTableLayout` (which
+ * persists the *contents* of the live layout): `JSONActiveView` only
+ * records *which* view the working copy belongs to and the dirty flag, so
+ * after a reload the toolbar dropdown can show e.g. `"Sales (unsaved)"`
+ * rather than resetting to `"Default"`.
+ *
+ * `TableContext` writes this (debounced, alongside the working-copy
+ * layout) on every layout change and reads it back during boot hydration.
+ */
+export interface JSONActiveView {
+    /** Which view the live table belongs to (Default or a saved view). */
+    active: ActiveViewRef;
+    /** Whether the live layout has diverged from `active`'s saved
+     *  baseline. Drives the `"(unsaved)"` suffix in the dropdown label. */
+    dirty: boolean;
+}
+/**
+ * Schema version for the persisted `JSONActiveView` envelope. Bump when
+ * the shape or field semantics change in a backwards-incompatible way;
+ * `readVersionedJSON` silently drops envelopes written under a different
+ * version.
+ */
+export declare const TABLE_ACTIVE_VIEW_SCHEMA_VERSION = 1;
+/**
+ * Conservative typeguard for a persisted `JSONActiveView`. localStorage is
+ * same-origin-writable so the decoded value is untrusted; this checks the
+ * envelope shape, the `active` discriminated union, and every field's
+ * primitive type.
+ *
+ * The `id` referenced by a `kind: 'saved'` slot is *not* verified against
+ * the live saved-view list here - `TableContext` reconciles the persisted
+ * ref against the fetched views once they load.
+ */
+export declare function isJSONActiveView(raw: unknown): raw is JSONActiveView;