@mnaoumov/obsidian-lib 10.11.0 → 11.0.0

package/dist/lib/esm/components/workspace-layout-state-component.d.mts

@@ -0,0 +1,239 @@
+/// <reference path="../library-references.d.mts" />
+/**
+ * @file
+ *
+ * Keeps a plugin's layout-scoped state in the workspace layout itself, so each saved workspace remembers its own value
+ * and switching workspaces restores it, instead of one global value in `data.json`.
+ *
+ * Read from Obsidian `1.15.1`: `Workspace.getLayout()` builds a fresh object (`main`, `left`, `right`, `left-ribbon`,
+ * `floating`, `active`) and `Workspace.setLayout()` ignores every other top-level key. `deserializeLayout` keeps each
+ * item's `id`, popout leaves included. The Workspaces core plugin saves through `getLayout()` and loads through
+ * `changeLayout()`, which calls `setLayout()`. Startup goes through `loadLayout()`, `readWorkspaceFile()` and
+ * `setLayout()`, after the plugins enabled at startup have loaded. So two patches on the `app.workspace` instance carry
+ * the whole thing: `getLayout` writes the records under {@link WORKSPACE_LAYOUT_STATE_LAYOUT_KEY}, and `setLayout`
+ * replaces them from the layout it is handed before any view is restored. Per-leaf state is keyed by leaf id at the
+ * layout level, so no `WorkspaceItem.serialize` or `deserializeLayout` patch is needed.
+ *
+ * A view the plugin owns needs none of this: `View.getState` / `setState` already ride in each leaf's state. This
+ * component is for the scope those methods cannot represent: the whole layout, and leaves of views the plugin does not
+ * own.
+ *
+ * Every plugin bundles its own copy of this library, so the records, the subscriptions and ONE installation of the
+ * patches live in the shared-state bag under a versioned key, owned by one subscriber. When the owner unloads while
+ * others remain, the next subscriber installs again from its own copy. What crosses that boundary is a wire format
+ * between copies of different versions: plain objects and plain functions only, fields only ever added, and a change of
+ * meaning moves to a new key. The layout record is a wire format too, persisted in `workspace.json` and in every saved
+ * workspace.
+ */
+import type { App, WorkspaceLeaf } from 'obsidian';
+import type { JsonValue } from 'type-fest';
+import { ComponentEx } from './component-ex.mjs';
+/**
+ * The top-level key of a serialized layout that holds the records.
+ */
+export declare const WORKSPACE_LAYOUT_STATE_LAYOUT_KEY = "obsidianLibLayoutStateV1";
+/**
+ * A change of one key's value, in one scope.
+ *
+ * @typeParam T - The value type.
+ */
+export interface WorkspaceLayoutStateChange<T> {
+    /**
+     * The leaf whose value changed, or `null` for the workspace scope or a leaf no longer in the layout.
+     */
+    readonly leaf: null | WorkspaceLeaf;
+    /**
+     * The id of the leaf whose value changed, or `null` for the workspace scope.
+     */
+    readonly leafId: null | string;
+    /**
+     * The value before the change, as {@link WorkspaceLayoutStateKey.get} read it.
+     */
+    readonly oldValue: T;
+    /**
+     * The value after the change, as {@link WorkspaceLayoutStateKey.get} reads it.
+     */
+    readonly value: T;
+}
+/**
+ * Parameters for {@link WorkspaceLayoutStateComponent}.
+ */
+export interface WorkspaceLayoutStateComponentConstructorParams {
+    /**
+     * The Obsidian app instance.
+     */
+    readonly app: App;
+    /**
+     * The id of the plugin the values belong to. Every value is namespaced by it.
+     */
+    readonly pluginId: string;
+}
+/**
+ * A typed handle to one layout-scoped key.
+ *
+ * Every method takes an optional leaf. Without one, the value belongs to the whole layout (the workspace scope).
+ *
+ * @typeParam T - The value type.
+ */
+export interface WorkspaceLayoutStateKey<T> {
+    /**
+     * Reads the value: a clone of the stored one, or of the default when nothing is stored or the stored value fails the
+     * key's guard.
+     *
+     * @param leaf - The leaf, or nothing for the workspace scope.
+     * @returns The value.
+     */
+    readonly get: (leaf?: WorkspaceLeaf) => T;
+    /**
+     * Checks whether a value is stored, valid or not.
+     *
+     * @param leaf - The leaf, or nothing for the workspace scope.
+     * @returns Whether a value is stored.
+     */
+    readonly has: (leaf?: WorkspaceLeaf) => boolean;
+    /**
+     * The key name, unique within the plugin.
+     */
+    readonly key: string;
+    /**
+     * Subscribes to changes of this key made through `set` or `unset`, in any scope and from any copy of the library. A
+     * layout load is reported through {@link WorkspaceLayoutStateComponent.onLayoutLoad} instead.
+     *
+     * @param callback - Called after each change.
+     * @returns A function that unsubscribes. Unloading the component unsubscribes too.
+     */
+    readonly onChange: (callback: (change: WorkspaceLayoutStateChange<T>) => void) => () => void;
+    /**
+     * Stores a clone of the value and requests a layout save. Storing a value equal to the stored one does nothing.
+     *
+     * @param value - The value. It must be JSON-safe; `null` is stored as `null`.
+     * @param leaf - The leaf, or nothing for the workspace scope.
+     * @throws A `TypeError` if the value is not JSON-safe.
+     */
+    readonly set: (value: T, leaf?: WorkspaceLeaf) => void;
+    /**
+     * Removes the stored value, so `get` reads the default again, and requests a layout save.
+     *
+     * @param leaf - The leaf, or nothing for the workspace scope.
+     */
+    readonly unset: (leaf?: WorkspaceLeaf) => void;
+}
+/**
+ * Defines a layout-scoped key.
+ *
+ * @typeParam T - The value type.
+ */
+export interface WorkspaceLayoutStateKeyDefinition<T> {
+    /**
+     * The value read when nothing valid is stored.
+     */
+    readonly defaultValue: T;
+    /**
+     * Checks a stored value. A value that fails reads as the default and stays stored until it is replaced or unset.
+     *
+     * @default Accepts every JSON value.
+     */
+    readonly isValid?: (value: unknown) => value is T;
+    /**
+     * The key name, unique within the plugin.
+     */
+    readonly key: string;
+}
+/**
+ * One plugin's records. Fields a newer copy adds are preserved.
+ */
+export interface WorkspaceLayoutStatePluginRecord {
+    /**
+     * The values by leaf id, then by key.
+     */
+    readonly leaves: Record<string, JsonRecord>;
+    /**
+     * Fields a newer copy of the library added.
+     */
+    readonly [field: string]: unknown;
+    /**
+     * The workspace-scope values by key.
+     */
+    readonly workspace: JsonRecord;
+}
+/**
+ * The record persisted under {@link WORKSPACE_LAYOUT_STATE_LAYOUT_KEY}. Fields a newer copy adds are preserved.
+ */
+export interface WorkspaceLayoutStateRecord {
+    /**
+     * The records by plugin id.
+     */
+    readonly plugins: Record<string, WorkspaceLayoutStatePluginRecord>;
+    /**
+     * Fields a newer copy of the library added.
+     */
+    readonly [field: string]: unknown;
+}
+type JsonRecord = Record<string, JsonValue>;
+/**
+ * Keeps a plugin's layout-scoped values in the workspace layout, so saved workspaces each restore their own.
+ *
+ * Any number of these, in any number of plugins, share one installation per {@link App}. Values are restored when a
+ * layout loads, which REPLACES every value: write them after {@link Workspace.onLayoutReady}, and re-read them in
+ * {@link onLayoutLoad}.
+ */
+export declare class WorkspaceLayoutStateComponent extends ComponentEx {
+    /**
+     * The Obsidian app instance.
+     */
+    protected readonly app: App;
+    /**
+     * The id of the plugin the values belong to.
+     */
+    protected readonly pluginId: string;
+    private readonly layoutLoadListeners;
+    private readonly recordChangeListeners;
+    /**
+     * Creates a new workspace layout state component.
+     *
+     * @param params - The parameters.
+     * @throws A `TypeError` if the plugin id is empty.
+     */
+    constructor(params: WorkspaceLayoutStateComponentConstructorParams);
+    /**
+     * Defines a typed key.
+     *
+     * @typeParam T - The value type.
+     * @param definition - The key definition.
+     * @returns The key handle.
+     * @throws A `TypeError` if the key is empty or the default value is not JSON-safe.
+     */
+    defineKey<T>(definition: WorkspaceLayoutStateKeyDefinition<T>): WorkspaceLayoutStateKey<T>;
+    /**
+     * Subscribes to layout loads: a saved workspace loaded, the layout restored at startup, or the saved layout read when
+     * the component is first loaded after layout-ready. Every value may have changed.
+     *
+     * @param callback - Called after the layout is loaded, once its leaves exist.
+     * @returns A function that unsubscribes. Unloading the component unsubscribes too.
+     */
+    onLayoutLoad(callback: () => void): () => void;
+    /**
+     * Subscribes to the shared installation, installing it when nobody has yet.
+     */
+    onload(): void;
+    private subscribeToRecordChanges;
+}
+/**
+ * Parses a persisted record. A part that is malformed is dropped one level at a time: a malformed record reads as
+ * empty, a malformed plugin record drops only that plugin, and a malformed leaf bucket drops only that leaf. Fields this
+ * copy does not know are kept.
+ *
+ * @param value - The value found under {@link WORKSPACE_LAYOUT_STATE_LAYOUT_KEY}.
+ * @returns The parsed record, sharing nothing with the input.
+ */
+export declare function parseWorkspaceLayoutStateRecord(value: unknown): WorkspaceLayoutStateRecord;
+/**
+ * Builds the record to persist into a serialized layout: leaf buckets for leaves absent from the layout are left out,
+ * and so are plugins with nothing left.
+ *
+ * @param record - The current record.
+ * @param layout - The serialized layout.
+ * @returns The record to persist, or `null` when there is nothing to persist.
+ */
+export declare function serializeWorkspaceLayoutStateRecord(record: WorkspaceLayoutStateRecord, layout: unknown): null | WorkspaceLayoutStateRecord;
+export {};