@perspective-dev/viewer 5.4.0 → 5.5.1

package/dist/esm/plugin.d.ts

@@ -88,6 +88,15 @@ export interface IPerspectiveViewerPlugin {
             kind: string;
         }>;
     };
+    /**
+     * The plugin-level settings schema as it applies to `current_value`, the
+     * `plugin_config` state the schema should describe.
+     */
+    plugin_config_schema?(view_config?: Record<string, unknown>, current_value?: Record<string, unknown> | null): {
+        fields: Array<Record<string, unknown> & {
+            kind: string;
+        }>;
+    };
     /**
      * Render this plugin using the provided `View`.  While there is no
      * provision to cancel a render in progress per se, calling a method on

package/dist/esm/ts-rs/AddPanelOptions.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Options for the `addPanel()` method.
+ */
+export type AddPanelOptions = {
+    /**
+     * As `RestoreOptions::wait_for_table`.
+     */
+    wait_for_table?: boolean;
+};

package/dist/esm/ts-rs/ExportMethod.d.ts

@@ -1 +1 @@
-export type ExportMethod = "csv" | "csv-all" | "csv-selected" | "json" | "json-all" | "json-selected" | "ndjson" | "ndjson-all" | "ndjson-selected" | "html" | "plugin" | "arrow" | "arrow-selected" | "arrow-all" | "json-config";
+export type ExportMethod = "csv" | "csv-all" | "csv-selected" | "json" | "json-all" | "json-selected" | "ndjson" | "ndjson-all" | "ndjson-selected" | "html" | "plugin" | "arrow" | "arrow-selected" | "arrow-all" | "arrow-lz4" | "arrow-lz4-selected" | "arrow-lz4-all" | "arrow-zstd" | "arrow-zstd-selected" | "arrow-zstd-all" | "json-config";

package/dist/esm/ts-rs/GetViewMode.d.ts

@@ -0,0 +1,4 @@
+/**
+ * How `getView` resolves the `View` it returns.
+ */
+export type GetViewMode = "live" | "clone" | "auto";

package/dist/esm/ts-rs/GetViewOptions.d.ts

@@ -0,0 +1,8 @@
+import type { GetViewMode } from "./GetViewMode.js";
+/**
+ * The `getView` argument: the `mode` and the target panel.
+ */
+export type GetViewOptions = {
+    mode?: GetViewMode;
+    panel?: string;
+};

package/dist/esm/ts-rs/RestoreOptions.d.ts

@@ -16,4 +16,10 @@ export type RestoreOptions = {
      * known-good config to recover exactly.
      */
     suppress_errors?: boolean;
+    /**
+     * When `true`, a `table` no loaded client hosts yet leaves the panel
+     * empty and pending until the table is created, instead of the default
+     * error.
+     */
+    wait_for_table?: boolean;
 };

package/dist/esm/ts-rs/RestoreWorkspaceOptions.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Options for the `restoreWorkspace()` method.
+ */
+export type RestoreWorkspaceOptions = {
+    /**
+     * As `RestoreOptions::wait_for_table`, applied to every panel entry.
+     */
+    wait_for_table?: boolean;
+};

package/dist/esm/ts-rs/WorkspaceConfigUpdate.d.ts

@@ -1,39 +1,47 @@
 import type { Filter } from "./Filter.js";
 import type { Layout } from "./Layout.js";
+import type { OptionalUpdate } from "./OptionalUpdate.js";
 import type { ViewerConfigInitial } from "./ViewerConfigInitial.js";
 /**
- * The parse target of a workspace config in
- * [`PerspectiveViewerElement::restoreWorkspace`]. Mirrors
- * [`WorkspaceConfig`], but `panels` entries are [`ViewerConfigInitial`]s —
- * every entry creates a NEW panel, so `table` is required by type (a
- * stray per-panel `settings` key is ignored; it is element-level state,
- * carried by the top-level `active` field).
+ * The [`PerspectiveViewerElement::restoreWorkspace`] argument: a field-wise
+ * update of the element's workspace state, like [`ViewerConfigUpdate`] for a
+ * panel, where an absent key is unchanged, `null` resets and a value
+ * replaces.
  */
 export type WorkspaceConfigUpdate = {
-    active?: string;
+    /**
+     * The panel to activate with the settings sidebar open, by `panels` key
+     * or existing panel id; `null` closes the sidebar.
+     */
+    active?: OptionalUpdate<string>;
+    /**
+     * The layout tree to stage, naming `panels` keys or existing panel ids.
+     */
     layout?: Layout;
-    panels: {
+    /**
+     * The complete replacement panel set, each [`ViewerConfigInitial`] entry
+     * creating a new panel (`{}` empties the element); absent keeps the
+     * existing panels.
+     */
+    panels?: {
         [key in string]?: ViewerConfigInitial;
     };
     /**
-     * The element-level global (master/detail cross-) filters to re-apply as
-     * a transient overlay on every DETAIL panel. Restored as one
-     * unattributed bucket: the next selection on any master replaces it.
-     * `Option` so an explicit `undefined` property deserializes as
-     * `None` like an absent key (also `masters` / `palette` below).
+     * The element-level cross-filter set applied to every detail panel as
+     * one unattributed bucket, replacing the current set; `null` clears it.
      */
-    global_filters?: Array<Filter> | null;
+    global_filters?: OptionalUpdate<Array<Filter>>;
     /**
-     * The master (filter-source) panels, by saved `panels` key. An id not in
-     * `panels` warns and is dropped.
+     * The master (filter-source) panels by `panels` key or existing panel
+     * id, unknown ids dropped with a warning; `null` demotes every panel.
      */
-    masters?: Array<string> | null;
+    masters?: OptionalUpdate<Array<string>>;
     /**
-     * Named color-scale definitions to apply to the host (see
-     * [`WorkspaceConfig::palette`]), replacing any previously restored
-     * palette.
+     * Named color-scale definitions applied to the host (see
+     * [`WorkspaceConfig::palette`]), replacing the previous palette; `null`
+     * clears it.
      */
-    palette?: {
+    palette?: OptionalUpdate<{
         [key in string]?: string;
-    } | null;
+    }>;
 };

package/dist/wasm/perspective-viewer.d.ts

@@ -113,25 +113,29 @@ export type * from "../../src/ts/ts-rs/WorkspaceConfigUpdate.d.ts";
 export type * from "../../src/ts/ts-rs/ExportMethod.d.ts";
 export type * from "../../src/ts/ts-rs/PanelOptions.d.ts";
 export type * from "../../src/ts/ts-rs/RestoreOptions.d.ts";
+export type * from "../../src/ts/ts-rs/RestoreWorkspaceOptions.d.ts";
+export type * from "../../src/ts/ts-rs/AddPanelOptions.d.ts";
 export type * from "../../src/ts/ts-rs/SaveWorkspaceOptions.d.ts";
 export type * from "../../src/ts/ts-rs/ClientOptions.d.ts";
 export type * from "../../src/ts/ts-rs/ExportOptions.d.ts";
 export type * from "../../src/ts/ts-rs/GetTableOptions.d.ts";
 export type * from "../../src/ts/ts-rs/GetClientOptions.d.ts";
+export type * from "../../src/ts/ts-rs/GetViewOptions.d.ts";
+export type * from "../../src/ts/ts-rs/GetViewMode.d.ts";
 export type * from "../../src/ts/ts-rs/CustomNumberFormatConfig.d.ts";
 export type * from "../../src/ts/ts-rs/NumberFormatStyle.d.ts";
 export type * from "../../src/ts/ts-rs/Notation.d.ts";
 export type * from "../../src/ts/ts-rs/DatetimeFormatType.d.ts";
-export type * from "../../src/ts/ts-rs/StringColorMode.d.ts";
-export type * from "../../src/ts/ts-rs/DatetimeColorMode.d.ts";
-export type * from "../../src/ts/ts-rs/FormatMode.d.ts";
 
 import type {GetTableOptions} from "../../src/ts/ts-rs/GetTableOptions.d.ts";
 import type {PanelOptions} from "../../src/ts/ts-rs/PanelOptions.d.ts";
 import type {RestoreOptions} from "../../src/ts/ts-rs/RestoreOptions.d.ts";
+import type {RestoreWorkspaceOptions} from "../../src/ts/ts-rs/RestoreWorkspaceOptions.d.ts";
+import type {AddPanelOptions} from "../../src/ts/ts-rs/AddPanelOptions.d.ts";
 import type {SaveWorkspaceOptions} from "../../src/ts/ts-rs/SaveWorkspaceOptions.d.ts";
 import type {ExportOptions} from "../../src/ts/ts-rs/ExportOptions.d.ts";
 import type {GetClientOptions} from "../../src/ts/ts-rs/GetClientOptions.d.ts";
+import type {GetViewOptions} from "../../src/ts/ts-rs/GetViewOptions.d.ts";
 import type {ClientOptions} from "../../src/ts/ts-rs/ClientOptions.d.ts";
 import type {ViewerConfig} from "../../src/ts/ts-rs/ViewerConfig.d.ts";
 import type {ViewerConfigUpdate} from "../../src/ts/ts-rs/ViewerConfigUpdate.d.ts";
@@ -525,8 +529,15 @@ export class PerspectiveViewerElement {
      *
      * The element-level `settings` field does not exist on the argument
      * type (it is shared across the element, not per-panel).
+     *
+     * # Arguments
+     *
+     * - `config` - The new panel's initial config, whose `table` is required.
+     * - `options.wait_for_table` - when `true`, a `table` no loaded client
+     *   hosts yet creates the panel empty and pending until the table is
+     *   created, instead of the default rejection.
      */
-    addPanel(config: ViewerConfigInitial): Promise<any>;
+    addPanel(config: ViewerConfigInitial, options?: AddPanelOptions | null): Promise<any>;
     /**
      * Configure the embedded LLM agent (see `prompt()`), replacing any prior
      * configuration and conversation.
@@ -814,27 +825,46 @@ export class PerspectiveViewerElement {
     getTable(options?: GetTableOptions | null): Promise<any>;
     getThemes(): Promise<any>;
     /**
-     * Get the underlying [`View`] for this viewer.
+     * Get a [`View`] for a panel of this viewer, as currently configured by
+     * the user.
      *
-     * Use this method to get promgrammatic access to the [`View`] as currently
-     * configured by the user, for e.g. serializing as an
-     * [Apache Arrow](https://arrow.apache.org/) before passing to another
-     * library.
+     * # Arguments
      *
-     * The [`View`] returned by this method is owned by the
-     * [`PerspectiveViewerElement`] and may be _invalidated_ by
-     * [`View::delete`] at any time. Plugins which rely on this [`View`] for
-     * their [`HTMLPerspectiveViewerPluginElement::draw`] implementations
-     * should treat this condition as a _cancellation_ by silently aborting on
-     * "View already deleted" errors from method calls.
+     * - `mode` - which [`View`] to return:
+     *   - `"live"` (default) - the panel's own [`View`], which the viewer
+     *     replaces on every config change and deletes when auto-paused or
+     *     [`PerspectiveViewerElement::delete`]d, so calls on it may fail with
+     *     "View already deleted", it must never be deleted by the caller, and
+     *     it rejects with `No View for panel "<name>"` while none is bound
+     *     (auto-paused or not yet rendered).
+     *   - `"clone"` - a new [`View`] built from the panel's effective config
+     *     (global filter included), independent of the render lifecycle, which
+     *     the caller owns and must [`View::delete`].
+     *   - `"auto"` - `"live"` when the panel has a bound [`View`], else
+     *     `"clone"`.
+     * - `panel` - the target panel, or the active panel when omitted.
+     *
+     * Plugins which rely on the live [`View`] for their
+     * [`HTMLPerspectiveViewerPluginElement::draw`] implementations should
+     * treat "View already deleted" as a _cancellation_ by silently aborting.
      *
      * # JavaScript Examples
      *
      * ```javascript
      * const view = await viewer.getView();
      * ```
+     *
+     * Export every panel without borrowing the viewer's own [`View`]:
+     *
+     * ```javascript
+     * for (const panel of viewer.getPanelNames()) {
+     *     const view = await viewer.getView({ panel, mode: "clone" });
+     *     const arrow = await view.to_arrow();
+     *     await view.delete();
+     * }
+     * ```
      */
-    getView(options?: PanelOptions | null): Promise<any>;
+    getView(options?: GetViewOptions | null): Promise<any>;
     /**
      * Get a copy of the [`ViewConfig`] for the current [`View`]. This is
      * non-blocking as it does not need to access the plugin (unlike
@@ -1035,12 +1065,13 @@ export class PerspectiveViewerElement {
      * - `options.panel` - The panel to target, or the active panel when
      *   omitted.
      * - `options.suppress_errors` - when `true`, a failed restore only rejects
-     *   the returned `Promise`; the error is NOT committed to the viewer's
-     *   visible error state and the session remains usable. The view config is
-     *   rolled back to its pre-call value, so a rejected patch cannot re-merge
-     *   into a later restore. Element-level state the call already applied
-     *   (theme, title, a plugin swap) is NOT undone — restore a known-good
-     *   config to recover those exactly.
+     *   the returned `Promise` and rolls the view config back, leaving the
+     *   viewer's visible error state and any element-level state the call
+     *   already applied (theme, title, plugin, a successful `table` change)
+     *   untouched.
+     * - `options.wait_for_table` - when `true`, a `table` no loaded client
+     *   hosts yet leaves the panel empty and pending until the table is
+     *   created, instead of the default error.
      *
      * # JavaScript Examples
      *
@@ -1060,20 +1091,33 @@ export class PerspectiveViewerElement {
      */
     restore(update: ViewerConfigUpdate, options?: RestoreOptions | null): Promise<void>;
     /**
-     * Restore the ENTIRE element from a [`WorkspaceConfigUpdate`]
-     * (`{version, active?, layout, panels, ...}`) —
-     * the multi-panel counterpart of [`Self::restore`]. Every existing panel
-     * is replaced by the `panels` entries, and the layout tree + master/detail
-     * cross-filter state re-applied. Unlike [`Self::restore`], this never
-     * falls back to the single-panel path.
+     * Apply a [`WorkspaceConfigUpdate`] to the element — the multi-panel
+     * counterpart of [`Self::restore`] and like it a field-wise update, where
+     * an absent field is unchanged, `null` resets and a value replaces.
+     *
+     * # Arguments
+     *
+     * - `update` - The workspace config update: a [`Self::saveWorkspace`]
+     *   token replaces every panel (`panels` is the whole set), while a token
+     *   without `panels` keeps them and `layout`, `active` and `masters` name
+     *   them by their existing ids.
+     * - `options.wait_for_table` - when `true`, a panel whose `table` no
+     *   loaded client hosts yet is created empty and pending until the table
+     *   is created, instead of the default error.
      *
      * # JavaScript Examples
      *
      * ```javascript
      * await viewer.restoreWorkspace(await otherViewer.saveWorkspace());
      * ```
+     *
+     * Cross-filter the current panels without re-creating them:
+     *
+     * ```javascript
+     * await viewer.restoreWorkspace({ global_filters: [["Region", "==", "West"]] });
+     * ```
      */
-    restoreWorkspace(update: WorkspaceConfigUpdate): Promise<void>;
+    restoreWorkspace(update: WorkspaceConfigUpdate, options?: RestoreWorkspaceOptions | null): Promise<void>;
     /**
      * Restyle all plugins from current document.
      *
@@ -1647,6 +1691,17 @@ export class View {
     set_depth(depth: number): Promise<void>;
     /**
      * Serializes a [`View`] to the Apache Arrow data format.
+     *
+     * # Arguments
+     *
+     * - `window` - a [`ViewWindow`]; its `compression` key selects Arrow IPC
+     *   body compression, `"lz4"` or `"zstd"` (uncompressed when omitted).
+     *
+     * # JavaScript Examples
+     *
+     * ```javascript
+     * const arrow = await view.to_arrow({ compression: "zstd" });
+     * ```
      */
     to_arrow(window?: ViewWindow | null): Promise<ArrayBuffer>;
     /**
@@ -1755,7 +1810,7 @@ export interface InitOutput {
     readonly perspectivedebugpluginelement_select_mode: (a: number, b: number) => void;
     readonly perspectivedebugpluginelement_update: (a: number, b: number) => number;
     readonly perspectiveviewerelement___get_model: (a: number) => number;
-    readonly perspectiveviewerelement_addPanel: (a: number, b: number) => number;
+    readonly perspectiveviewerelement_addPanel: (a: number, b: number, c: number) => number;
     readonly perspectiveviewerelement_agentConfig: (a: number, b: number, c: number) => void;
     readonly perspectiveviewerelement_agentPrompt: (a: number, b: number, c: number) => number;
     readonly perspectiveviewerelement_agentReset: (a: number) => number;
@@ -1786,7 +1841,7 @@ export interface InitOutput {
     readonly perspectiveviewerelement_resetThemes: (a: number, b: number, c: number) => number;
     readonly perspectiveviewerelement_resize: (a: number, b: number) => number;
     readonly perspectiveviewerelement_restore: (a: number, b: number, c: number) => number;
-    readonly perspectiveviewerelement_restoreWorkspace: (a: number, b: number) => number;
+    readonly perspectiveviewerelement_restoreWorkspace: (a: number, b: number, c: number) => number;
     readonly perspectiveviewerelement_restyleElement: (a: number) => number;
     readonly perspectiveviewerelement_save: (a: number, b: number) => number;
     readonly perspectiveviewerelement_saveWorkspace: (a: number, b: number) => number;
@@ -1895,22 +1950,22 @@ export interface InitOutput {
     readonly virtualdataslice_setStringCol: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
     readonly virtualserver_handleRequest: (a: number, b: number, c: number) => number;
     readonly virtualserver_new: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_18575: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_19286: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_20199: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_4417: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_24952: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_33110: (a: number, b: number, c: number, d: number) => void;
-    readonly __wasm_bindgen_func_elem_18694: (a: number, b: number, c: number) => void;
-    readonly __wasm_bindgen_func_elem_19291: (a: number, b: number, c: number) => void;
-    readonly __wasm_bindgen_func_elem_7737: (a: number, b: number, c: number) => void;
-    readonly __wasm_bindgen_func_elem_7738: (a: number, b: number, c: number) => void;
-    readonly __wasm_bindgen_func_elem_7739: (a: number, b: number, c: number) => void;
-    readonly __wasm_bindgen_func_elem_7735: (a: number, b: number, c: number) => void;
-    readonly __wasm_bindgen_func_elem_24969: (a: number, b: number, c: number) => void;
-    readonly __wasm_bindgen_func_elem_21238: (a: number, b: number) => number;
-    readonly __wasm_bindgen_func_elem_19290: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_21239: (a: number, b: number) => void;
+    readonly __wasm_bindgen_func_elem_18919: (a: number, b: number) => void;
+    readonly __wasm_bindgen_func_elem_4482: (a: number, b: number) => void;
+    readonly __wasm_bindgen_func_elem_19628: (a: number, b: number) => void;
+    readonly __wasm_bindgen_func_elem_20538: (a: number, b: number) => void;
+    readonly __wasm_bindgen_func_elem_25347: (a: number, b: number) => void;
+    readonly __wasm_bindgen_func_elem_33507: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_19039: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_7893: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_7894: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_7895: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_7891: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_19633: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_25364: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_21577: (a: number, b: number) => number;
+    readonly __wasm_bindgen_func_elem_19632: (a: number, b: number) => void;
+    readonly __wasm_bindgen_func_elem_21578: (a: number, b: number) => void;
     readonly __wbindgen_export: (a: number, b: number) => number;
     readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
     readonly __wbindgen_export3: (a: number) => void;