@happyvertical/smrt-content 0.43.4 → 0.43.6

package/dist/svelte/content-list-saved-views.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Saved views for ContentList (#2452).
+ *
+ * A saved view is a named `DataTableSnapshot` an operator can come back to. The
+ * payload is persisted outside the application's control — today in
+ * `localStorage`, which is writable by anyone with a console — so it is treated
+ * exactly like a URL: untrusted on the way back in.
+ *
+ * Restoration is therefore two gates, in order:
+ *
+ * 1. `hydrateDataTableSnapshot` (smrt-ui) parses the stored payload
+ *    structurally, upgrades version 1/2 into normalized version 3, and throws
+ *    on anything it cannot make sense of. It intentionally runs *without*
+ *    column ids, so it normalizes shape but does not know which columns this
+ *    list publishes.
+ * 2. `sanitizeContentListViewState` (`content-list-url-state.ts`) — the same
+ *    validator the URL path uses — then holds the hydrated state to the
+ *    adapter's published column and operator vocabulary. A stored view can no
+ *    more restore a filter on the hidden `description` column, a structural
+ *    `select`/`actions` column, or a column that has since been removed than a
+ *    crafted link can.
+ *
+ * A stale view is not an error: a snapshot that references a column which no
+ * longer exists restores the valid remainder and reports the drops, so the UI
+ * can say what it discarded instead of refusing to open the list.
+ *
+ * The storage seam is deliberately narrow (`list`/`get`/`save`/`delete`) and
+ * asynchronous, so the server-backed store that lands later is a drop-in
+ * replacement rather than a signature change. Nothing here knows about a
+ * backend, a tenant, or a principal.
+ */
+import { type DataTableSnapshot, type DataTableViewState } from '@happyvertical/smrt-ui/data';
+import { type ContentListStateDrop, type ContentListStateValidationOptions } from './content-list-url-state.js';
+export type { ContentListStateDrop, ContentListStateDropReason, ContentListStateDropScope, } from './content-list-url-state.js';
+/**
+ * Envelope version for a stored view. Bumped only when the envelope around the
+ * snapshot changes; the snapshot carries its own `version` for the state.
+ */
+export declare const CONTENT_LIST_SAVED_VIEW_SCHEMA_VERSION = 1;
+/** Prefix of the `localStorage` key a saved-view store owns. */
+export declare const CONTENT_LIST_SAVED_VIEW_STORAGE_PREFIX = "smrt:content-list:saved-views";
+/**
+ * A stored snapshot exactly as it was persisted: structurally hydrated by
+ * `hydrateDataTableSnapshot`, but **not** validated against this list's column
+ * and operator vocabulary.
+ *
+ * The raw payload is kept on purpose — a stale view has to be able to report
+ * what it referenced (`restoreContentListSavedView` returns those drops), and
+ * sanitizing on read would erase the evidence. Never hand one of these to a
+ * controller directly: go through `restoreContentListSavedView` when the drops
+ * matter, or `applyContentListViewState`, which validates its patch.
+ */
+export type RawContentListViewSnapshot = DataTableSnapshot;
+/** A named, restorable content list view. */
+export interface ContentListSavedView {
+    /** Stable identity. Survives renames and re-saves. */
+    id: string;
+    /** Operator-facing name. */
+    name: string;
+    /** Envelope version, currently `CONTENT_LIST_SAVED_VIEW_SCHEMA_VERSION`. */
+    schemaVersion: number;
+    /**
+     * The persisted view payload — structurally normalized on write, and
+     * deliberately NOT column-validated. See {@link RawContentListViewSnapshot}.
+     */
+    snapshot: RawContentListViewSnapshot;
+    /** ISO timestamps, for ordering the operator's list. */
+    createdAt: string;
+    updatedAt: string;
+}
+/** What a caller supplies to create or update a view. */
+export interface ContentListSavedViewInput {
+    /** Omit to create; supply to overwrite an existing view in place. */
+    id?: string;
+    name: string;
+    snapshot: DataTableSnapshot;
+}
+/**
+ * The persistence seam. Asynchronous on purpose: the `localStorage` default is
+ * synchronous underneath, but a server-backed store cannot be, and changing
+ * the signature later would break every consumer.
+ */
+export interface ContentListSavedViewStore {
+    /**
+     * Every stored view, most recently updated first. Corrupt entries are
+     * skipped. Each `snapshot` is a {@link RawContentListViewSnapshot} — hydrated
+     * but unvalidated. Restore it with `restoreContentListSavedView`, or apply it
+     * through `applyContentListViewState`, which validates.
+     */
+    list(): Promise<ContentListSavedView[]>;
+    /** One view, or `null` when it is absent or unreadable. Snapshot is raw. */
+    get(id: string): Promise<ContentListSavedView | null>;
+    /** Creates or replaces a view. Throws `TypeError` on an unusable snapshot. */
+    save(input: ContentListSavedViewInput): Promise<ContentListSavedView>;
+    /** Removes a view. Resolves `false` when there was nothing to remove. */
+    delete(id: string): Promise<boolean>;
+}
+/** The concrete store also reports whether writes actually persist. */
+export interface ContentListLocalSavedViewStore extends ContentListSavedViewStore {
+    /**
+     * False once the store has fallen back to memory — blocked storage, private
+     * browsing, or a server render. A UI can warn that views will not survive a
+     * reload instead of silently losing them.
+     */
+    isPersistent(): boolean;
+}
+/** The slice of the DOM Storage API this module uses. */
+export interface ContentListSavedViewStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+export interface ContentListSavedViewStoreOptions {
+    /**
+     * Storage backend. Defaults to `globalThis.localStorage` when it is reachable
+     * and writable; `null` forces the in-memory store.
+     */
+    storage?: ContentListSavedViewStorage | null;
+    /** Distinguishes several mounted lists. Defaults to the adapter's surface id. */
+    surfaceId?: string;
+    /** Full storage key override; takes precedence over `surfaceId`. */
+    storageKey?: string;
+    /** Injectable clock, for deterministic tests. */
+    now?: () => Date;
+    /** Injectable id factory, for deterministic tests. */
+    createId?: () => string;
+}
+/** The outcome of restoring a saved view. */
+export interface ContentListSavedViewRestoration {
+    /**
+     * The validated patch to apply, via `applyContentListViewState`. Selection
+     * and expansion are never present: a saved view names a query, not a set of
+     * rows someone had checked.
+     */
+    state: Partial<DataTableViewState>;
+    /** Everything the validator refused, for reporting to the operator. */
+    dropped: ContentListStateDrop[];
+}
+/**
+ * Creates the default saved-view store.
+ *
+ * Backed by `localStorage` when it is reachable and writable, and by an
+ * in-memory map otherwise — a server render, a private window, or a browser
+ * with site data blocked degrades to a store that works for the session
+ * instead of throwing on the first save.
+ */
+export declare function createContentListSavedViewStore(options?: ContentListSavedViewStoreOptions): ContentListLocalSavedViewStore;
+/**
+ * An explicitly non-persistent store, for server rendering and for tests that
+ * must not touch ambient storage.
+ */
+export declare function createContentListMemorySavedViewStore(options?: Omit<ContentListSavedViewStoreOptions, 'storage'>): ContentListLocalSavedViewStore;
+/**
+ * Validates a stored payload and returns the patch to apply.
+ *
+ * Accepts either a whole `ContentListSavedView` or a bare snapshot. Throws
+ * `TypeError` — via `hydrateDataTableSnapshot` — when the payload is not a
+ * supported snapshot at all; column-level problems are reported in `dropped`
+ * so a stale view still opens.
+ */
+export declare function restoreContentListSavedView(value: unknown, options?: ContentListStateValidationOptions): ContentListSavedViewRestoration;
+/**
+ * Builds the input for `store.save` from a controller snapshot.
+ *
+ * Selection and expansion are stripped before the snapshot is stored: a saved
+ * view names a query, and persisting the rows someone had checked would restore
+ * a selection into a list whose rows have since changed.
+ */
+export declare function toContentListSavedViewInput(name: string, snapshot: DataTableSnapshot, options?: {
+    id?: string;
+}): ContentListSavedViewInput;
+//# sourceMappingURL=content-list-saved-views.d.ts.map

package/dist/svelte/content-list-saved-views.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-list-saved-views.d.ts","sourceRoot":"","sources":["../../src/svelte/content-list-saved-views.ts"],"names":[],"mappings":"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"}

package/dist/svelte/content-list-saved-views.js

@@ -0,0 +1,298 @@
+/**
+ * Saved views for ContentList (#2452).
+ *
+ * A saved view is a named `DataTableSnapshot` an operator can come back to. The
+ * payload is persisted outside the application's control — today in
+ * `localStorage`, which is writable by anyone with a console — so it is treated
+ * exactly like a URL: untrusted on the way back in.
+ *
+ * Restoration is therefore two gates, in order:
+ *
+ * 1. `hydrateDataTableSnapshot` (smrt-ui) parses the stored payload
+ *    structurally, upgrades version 1/2 into normalized version 3, and throws
+ *    on anything it cannot make sense of. It intentionally runs *without*
+ *    column ids, so it normalizes shape but does not know which columns this
+ *    list publishes.
+ * 2. `sanitizeContentListViewState` (`content-list-url-state.ts`) — the same
+ *    validator the URL path uses — then holds the hydrated state to the
+ *    adapter's published column and operator vocabulary. A stored view can no
+ *    more restore a filter on the hidden `description` column, a structural
+ *    `select`/`actions` column, or a column that has since been removed than a
+ *    crafted link can.
+ *
+ * A stale view is not an error: a snapshot that references a column which no
+ * longer exists restores the valid remainder and reports the drops, so the UI
+ * can say what it discarded instead of refusing to open the list.
+ *
+ * The storage seam is deliberately narrow (`list`/`get`/`save`/`delete`) and
+ * asynchronous, so the server-backed store that lands later is a drop-in
+ * replacement rather than a signature change. Nothing here knows about a
+ * backend, a tenant, or a principal.
+ */
+import { hydrateDataTableSnapshot, } from '@happyvertical/smrt-ui/data';
+import { CONTENT_LIST_SURFACE_ID } from './content-list-controller.js';
+import { sanitizeContentListViewState, } from './content-list-url-state.js';
+/**
+ * Envelope version for a stored view. Bumped only when the envelope around the
+ * snapshot changes; the snapshot carries its own `version` for the state.
+ */
+export const CONTENT_LIST_SAVED_VIEW_SCHEMA_VERSION = 1;
+/** Prefix of the `localStorage` key a saved-view store owns. */
+export const CONTENT_LIST_SAVED_VIEW_STORAGE_PREFIX = 'smrt:content-list:saved-views';
+function storageKeyFor(options) {
+    if (options.storageKey)
+        return options.storageKey;
+    const surfaceId = options.surfaceId ?? CONTENT_LIST_SURFACE_ID;
+    return `${CONTENT_LIST_SAVED_VIEW_STORAGE_PREFIX}:v${CONTENT_LIST_SAVED_VIEW_SCHEMA_VERSION}:${surfaceId}`;
+}
+/**
+ * Resolves the ambient `localStorage`, or `null` when it is unreachable.
+ *
+ * Reading the property itself throws in some browsers when site data is
+ * blocked, and Safari's private mode throws on the first `setItem` rather than
+ * on access — so availability is probed with a real write, not assumed.
+ */
+function resolveAmbientStorage() {
+    try {
+        const storage = globalThis.localStorage;
+        if (!storage)
+            return null;
+        const probe = `${CONTENT_LIST_SAVED_VIEW_STORAGE_PREFIX}:probe`;
+        storage.setItem(probe, '1');
+        storage.removeItem(probe);
+        return storage;
+    }
+    catch {
+        return null;
+    }
+}
+function createMemoryStorage() {
+    const entries = new Map();
+    return {
+        getItem: (key) => entries.get(key) ?? null,
+        setItem: (key, value) => {
+            entries.set(key, value);
+        },
+        removeItem: (key) => {
+            entries.delete(key);
+        },
+    };
+}
+function defaultCreateId() {
+    try {
+        const cryptoRef = globalThis
+            .crypto;
+        if (typeof cryptoRef?.randomUUID === 'function') {
+            return cryptoRef.randomUUID();
+        }
+    }
+    catch {
+        // Fall through to the non-cryptographic id below.
+    }
+    return `view-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+function isPlainObject(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        (Object.getPrototypeOf(value) === Object.prototype ||
+            Object.getPrototypeOf(value) === null));
+}
+/**
+ * Parses one stored entry, or returns `null` when it is unusable.
+ *
+ * Every stored record goes through `hydrateDataTableSnapshot`, so a hand-edited
+ * or truncated entry is discarded on read rather than handed to the controller.
+ */
+function parseStoredView(value) {
+    if (!isPlainObject(value))
+        return null;
+    const { id, name, snapshot, createdAt, updatedAt, schemaVersion } = value;
+    if (typeof id !== 'string' || id.length === 0)
+        return null;
+    if (typeof name !== 'string')
+        return null;
+    if (schemaVersion !== undefined &&
+        schemaVersion !== CONTENT_LIST_SAVED_VIEW_SCHEMA_VERSION) {
+        return null;
+    }
+    let hydrated;
+    try {
+        hydrated = hydrateDataTableSnapshot(snapshot);
+    }
+    catch {
+        return null;
+    }
+    const created = typeof createdAt === 'string' ? createdAt : '';
+    return {
+        id,
+        name,
+        schemaVersion: CONTENT_LIST_SAVED_VIEW_SCHEMA_VERSION,
+        snapshot: hydrated,
+        createdAt: created,
+        updatedAt: typeof updatedAt === 'string' ? updatedAt : created,
+    };
+}
+function sortViews(views) {
+    return views.sort((left, right) => {
+        if (left.updatedAt === right.updatedAt) {
+            return left.name < right.name ? -1 : left.name > right.name ? 1 : 0;
+        }
+        return left.updatedAt < right.updatedAt ? 1 : -1;
+    });
+}
+/**
+ * Creates the default saved-view store.
+ *
+ * Backed by `localStorage` when it is reachable and writable, and by an
+ * in-memory map otherwise — a server render, a private window, or a browser
+ * with site data blocked degrades to a store that works for the session
+ * instead of throwing on the first save.
+ */
+export function createContentListSavedViewStore(options = {}) {
+    const key = storageKeyFor(options);
+    const now = options.now ?? (() => new Date());
+    const createId = options.createId ?? defaultCreateId;
+    const requested = options.storage === undefined ? resolveAmbientStorage() : options.storage;
+    let storage = requested ?? createMemoryStorage();
+    let persistent = requested !== null && requested !== undefined;
+    /** Demotes to memory the first time the backing storage misbehaves. */
+    function degrade() {
+        if (!persistent)
+            return;
+        persistent = false;
+        storage = createMemoryStorage();
+    }
+    function readAll() {
+        let raw;
+        try {
+            raw = storage.getItem(key);
+        }
+        catch {
+            degrade();
+            return [];
+        }
+        if (!raw)
+            return [];
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return [];
+        }
+        if (!Array.isArray(parsed))
+            return [];
+        const views = [];
+        for (const entry of parsed) {
+            const view = parseStoredView(entry);
+            if (view)
+                views.push(view);
+        }
+        return views;
+    }
+    function writeAll(views) {
+        try {
+            storage.setItem(key, JSON.stringify(views));
+        }
+        catch {
+            // A quota or private-mode failure must not lose the operator's view:
+            // demote to memory and keep the write.
+            degrade();
+            try {
+                storage.setItem(key, JSON.stringify(views));
+            }
+            catch {
+                // The in-memory fallback cannot fail; nothing further to do.
+            }
+        }
+    }
+    return {
+        isPersistent: () => persistent,
+        async list() {
+            return sortViews(readAll());
+        },
+        async get(id) {
+            return readAll().find((view) => view.id === id) ?? null;
+        },
+        async save(input) {
+            if (!input || typeof input.name !== 'string' || !input.name.trim()) {
+                throw new TypeError('A content list saved view requires a name');
+            }
+            // Hydrating on write keeps a malformed payload out of storage entirely,
+            // so the only tampered payloads the read path has to survive are ones
+            // written around this API.
+            const snapshot = hydrateDataTableSnapshot(input.snapshot);
+            const timestamp = now().toISOString();
+            const views = readAll();
+            const existing = input.id
+                ? views.find((view) => view.id === input.id)
+                : undefined;
+            const view = {
+                id: existing?.id ?? input.id ?? createId(),
+                name: input.name.trim(),
+                schemaVersion: CONTENT_LIST_SAVED_VIEW_SCHEMA_VERSION,
+                snapshot,
+                createdAt: existing?.createdAt || timestamp,
+                updatedAt: timestamp,
+            };
+            writeAll([...views.filter((entry) => entry.id !== view.id), view]);
+            return view;
+        },
+        async delete(id) {
+            const views = readAll();
+            const next = views.filter((view) => view.id !== id);
+            if (next.length === views.length)
+                return false;
+            writeAll(next);
+            return true;
+        },
+    };
+}
+/**
+ * An explicitly non-persistent store, for server rendering and for tests that
+ * must not touch ambient storage.
+ */
+export function createContentListMemorySavedViewStore(options = {}) {
+    // `null` is the documented "force memory" signal, so the store also reports
+    // itself as non-persistent rather than claiming durability it does not have.
+    return createContentListSavedViewStore({ ...options, storage: null });
+}
+/**
+ * Validates a stored payload and returns the patch to apply.
+ *
+ * Accepts either a whole `ContentListSavedView` or a bare snapshot. Throws
+ * `TypeError` — via `hydrateDataTableSnapshot` — when the payload is not a
+ * supported snapshot at all; column-level problems are reported in `dropped`
+ * so a stale view still opens.
+ */
+export function restoreContentListSavedView(value, options = {}) {
+    const payload = isPlainObject(value) && Object.hasOwn(value, 'snapshot')
+        ? value.snapshot
+        : value;
+    const hydrated = hydrateDataTableSnapshot(payload);
+    const { state, dropped } = sanitizeContentListViewState(hydrated.state, options);
+    return { state, dropped };
+}
+/**
+ * Builds the input for `store.save` from a controller snapshot.
+ *
+ * Selection and expansion are stripped before the snapshot is stored: a saved
+ * view names a query, and persisting the rows someone had checked would restore
+ * a selection into a list whose rows have since changed.
+ */
+export function toContentListSavedViewInput(name, snapshot, options = {}) {
+    return {
+        ...(options.id ? { id: options.id } : {}),
+        name,
+        snapshot: {
+            ...snapshot,
+            state: {
+                ...snapshot.state,
+                selection: { scope: 'explicit', rowIds: [] },
+                selectedRowIds: [],
+                expandedRowIds: [],
+            },
+        },
+    };
+}