@perspective-dev/viewer 4.5.2 → 5.0.0

package/dist/esm/plugin.d.ts

@@ -15,6 +15,36 @@ import { PluginStaticConfig } from "./ts-rs/PluginStaticConfig.js";
  * level (if packaged as a library), or during application init to ensure global
  * availability of a plugin.
  *
+ * ## Dispatch contract
+ *
+ * The host dispatches each method for exactly one reason, and never
+ * defensively — implementations may rely on these meanings:
+ *
+ * - `draw(view)` — `view` is NEW to this plugin: a new engine `View` was
+ *   constructed, or this plugin was freshly selected and owes its first
+ *   render. Safe to reset zoom/scroll/selection state.
+ * - `update(view)` — same `View`, but a plugin-visible input genuinely
+ *   changed: new data (`View.on_update`), an effective view-config delta
+ *   without a rebuild, a *changed* plugin/columns config just delivered
+ *   via `restore()`, changed CSS just applied via `restyle()`, a
+ *   render-limits change, or an explicit public `viewer.restore()` call
+ *   (the no-op-restore refresh affordance). Host-internal operations that
+ *   change none of these dispatch nothing.
+ * - `resize(view)` — geometry or visibility changed (including panel
+ *   activation); repaint from retained state, no data or CSS re-read.
+ * - `restyle()` — the effective theme genuinely changed; when a
+ *   `draw`/`update` is part of the same operation, `restyle()` is called
+ *   immediately BEFORE it, so one render pass paints in the new theme.
+ * - `restore()`/`save()` — state transfer only. Plugins must NOT render
+ *   from `restore()` (a changed restore is always followed by exactly one
+ *   `update`) and must NOT call host APIs from inside it — a
+ *   `restore()` echo re-enters the host's public surface and forces
+ *   a redundant render (the classic double-render-on-load bug).
+ *
+ * Rendering methods (`draw`, `update`, `resize`, `render`, `clear`) and
+ * `delete` are serialized per element — the host never overlaps them, and
+ * each call runs to completion before the next begins.
+ *
  * @example
  * ```javascript
  * const BasePlugin = customElements.get("perspective-viewer-plugin");
@@ -53,6 +83,14 @@ export interface IPerspectiveViewerPlugin {
      * provision to cancel a render in progress per se, calling a method on
      * a `View` which has been deleted will throw an exception.
      *
+     * The host invokes `draw` ONLY when `view` is NEW to this plugin — a
+     * new engine `View` was constructed for a config change, or this plugin
+     * element was freshly selected and owes its first render of the bound
+     * `View` — so implementations may treat it as "new data shape" and
+     * reset zoom/scroll/selection-domain state. Repaints of the same
+     * `View` arrive as `update()` (data or style refresh) or `resize()`
+     * (geometry/chrome), never `draw()`.
+     *
      * @example
      * ```
      * async draw(view: perspective.View): Promise<void> {
@@ -63,9 +101,9 @@ export interface IPerspectiveViewerPlugin {
      */
     draw(view: View): Promise<void>;
     /**
-     * Draw under the assumption that the `ViewConfig` has not changed since
-     * the previous call to `draw()`, but the underlying data has.  Defaults to
-     * dispatch to `draw()`.
+     * Draw under the assumption that the `View` has not changed since the
+     * previous call to `draw()`, but some plugin-visible input has.
+     * Defaults to dispatch to `draw()`.
      *
      * @example
      * ```javascript
@@ -91,18 +129,46 @@ export interface IPerspectiveViewerPlugin {
     clear(): Promise<void>;
     /**
      * Like `update()`, but for when the dimensions of the plugin have changed
-     * and the underlying data has not.
+     * and the underlying data has not — a repaint from retained state,
+     * invoked ONLY when geometry or visibility changed: box resizes,
+     * presize sweeps, and the panel-ACTIVATION chrome nudge (multi-panel),
+     * so implementations should repaint activation-dependent chrome here
+     * and no-op while hidden (`offsetParent == null`).
      */
     resize(view: View): Promise<void>;
     /**
      * Notify the plugin that the style environment has changed.  Useful for
-     * plugins which read CSS styles via `window.getComputedStyle()`.
+     * plugins which read CSS styles via `window.getComputedStyle()` — this
+     * is the ONLY point at which a plugin is expected to (re-)read them
+     * (besides its first `draw()`), so implementations may cache computed
+     * styles between `restyle()` calls.
      */
     restyle(): void;
     /**
      * Restore this plugin to a state previously returned by `save()`.
+     *
+     * State transfer ONLY — implementations must not render from
+     * `restore()` (the host follows a restore that genuinely changed
+     * plugin state with exactly one `update()` in the same serialized
+     * sequence), and must not call host `<perspective-viewer>` APIs from
+     * inside it: an echoed `restore()` re-enters the host's public
+     * surface where it is indistinguishable from a user call and forces a
+     * redundant render. Host API calls to persist plugin state belong to
+     * genuine user-gesture handlers (e.g. a toolbar click), never to the
+     * `restore()` delivery path.
      */
     restore(config: any): void;
+    /**
+     * OPTIONAL — clear any visible user selection state (highlighted rows,
+     * pinned tooltips) WITHOUT emitting selection events. The host
+     * `<perspective-viewer>` invokes this when an element-level global
+     * filter contributed by this plugin's selection is removed from the
+     * global filter bar, so the selection visual can't outlive the filter
+     * it produced. Called under the host's per-panel render serialization
+     * (like `draw`), so implementations may redraw. Plugins without a
+     * selection UI may omit it.
+     */
+    deselect?(): Promise<void>;
     /**
      * Free any resources acquired by this plugin and prepare to be deleted.
      */

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

@@ -0,0 +1,7 @@
+/**
+ * The `eject` argument: the loaded client to remove by name; the active
+ * panel's client when omitted.
+ */
+export type ClientOptions = {
+    client?: string;
+};

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

@@ -0,0 +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";

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

@@ -0,0 +1,9 @@
+import type { ExportMethod } from "./ExportMethod.js";
+/**
+ * The `download` / `export` / `copy` argument: the `ExportMethod` and target
+ * panel.
+ */
+export type ExportOptions = {
+    method?: ExportMethod;
+    panel?: string;
+};

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

@@ -0,0 +1,8 @@
+/**
+ * The `getClient` argument: whether to `wait` for a `Client`, and the target
+ * panel.
+ */
+export type GetClientOptions = {
+    wait?: boolean;
+    panel?: string;
+};

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

@@ -0,0 +1,8 @@
+/**
+ * The `getTable` argument: whether to `wait` for a `Table`, and the target
+ * panel.
+ */
+export type GetTableOptions = {
+    wait?: boolean;
+    panel?: string;
+};

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

@@ -0,0 +1,11 @@
+import type { SplitLayout } from "./SplitLayout.js";
+import type { TabLayout } from "./TabLayout.js";
+/**
+ * A serde mirror of `regular-layout`'s serialized layout tree, as returned by
+ * [`RegularLayout::save`] and accepted by [`RegularLayout::restore`].
+ */
+export type Layout = {
+    "type": "split-layout";
+} & SplitLayout | {
+    "type": "tab-layout";
+} & TabLayout;

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

@@ -0,0 +1,4 @@
+/**
+ * The orientation of a [`SplitLayout`].
+ */
+export type Orientation = "horizontal" | "vertical";

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

@@ -0,0 +1,7 @@
+/**
+ * Selects the target panel of a panel-scoped `<perspective-viewer>` method;
+ * the active panel when `panel` is omitted.
+ */
+export type PanelOptions = {
+    panel?: string;
+};

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

@@ -0,0 +1,39 @@
+import type { Aggregate } from "./Aggregate.js";
+import type { Expressions } from "./Expressions.js";
+import type { Filter } from "./Filter.js";
+import type { FilterReducer } from "./FilterReducer.js";
+import type { GroupRollupMode } from "./GroupRollupMode.js";
+import type { Sort } from "./Sort.js";
+import type { JsonValue } from "./serde_json/JsonValue.js";
+/**
+ * The per-panel state of a [`ViewerConfig`] — everything except the
+ * element-level `settings` flag. This is the `panels` entry type of the
+ * whole-element config format.
+ */
+export type PanelViewerConfig<V = string> = {
+    version: V;
+    columns_config: {
+        [key in string]?: {
+            [key in string]?: JsonValue;
+        };
+    };
+    plugin: string;
+    plugin_config: {
+        [key in string]?: JsonValue;
+    };
+    table: string | null;
+    theme: string | null;
+    title: string | null;
+    group_by: Array<string>;
+    split_by: Array<string>;
+    sort: Array<Sort>;
+    filter: Array<Filter>;
+    group_rollup_mode: GroupRollupMode;
+    filter_op?: FilterReducer;
+    expressions: Expressions;
+    columns: Array<string | null>;
+    aggregates: {
+        [key in string]?: Aggregate;
+    };
+    group_by_depth?: number | null;
+};

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

@@ -0,0 +1,7 @@
+import type { Layout } from "./Layout.js";
+import type { Orientation } from "./Orientation.js";
+export type SplitLayout = {
+    children: Array<Layout>;
+    sizes: Array<number>;
+    orientation: Orientation;
+};

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

@@ -0,0 +1,10 @@
+export type TabLayout = {
+    /**
+     * Panel ids (slot names) in this stack.
+     */
+    tabs: Array<string>;
+    /**
+     * Index of the selected tab within `tabs`.
+     */
+    selected?: number;
+};

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

@@ -7,9 +7,14 @@ import type { Sort } from "./Sort.js";
 import type { JsonValue } from "./serde_json/JsonValue.js";
 /**
  * The state of an entire `custom_elements::PerspectiveViewerElement` component
- * and its `Plugin`.
+ * and its `Plugin`: the element-level `settings` flag plus the per-panel
+ * [`PanelViewerConfig`]. The split exists so the whole-element config format
+ * can serialize panel entries *without* a `settings` key (it is element-level
+ * state there, carried by the top-level `active` field instead), while the
+ * single-panel format flattens back to the legacy shape.
  */
 export type ViewerConfig<V = string> = {
+    settings: boolean;
     version: V;
     columns_config: {
         [key in string]?: {
@@ -20,7 +25,6 @@ export type ViewerConfig<V = string> = {
     plugin_config: {
         [key in string]?: JsonValue;
     };
-    settings: boolean;
     table: string | null;
     theme: string | null;
     title: string | null;

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

@@ -0,0 +1,40 @@
+import type { Filter } from "./Filter.js";
+import type { Layout } from "./Layout.js";
+import type { PanelViewerConfig } from "./PanelViewerConfig.js";
+/**
+ * The whole-element config format (`{version, active?, layout, panels}`) —
+ * the multi-panel counterpart of the single-panel [`ViewerConfig`] — as
+ * emitted by [`PerspectiveViewerElement::save`].
+ *
+ * - `panels` entries are [`PanelViewerConfig`]s: per-panel state only, no
+ *   `settings` key (element-level state).
+ * - `active` names the panel targeted by the *open* settings sidebar; it is
+ *   omitted when the sidebar is closed.
+ */
+export type WorkspaceConfig = {
+    version: string;
+    active?: string;
+    layout: Layout | null;
+    /**
+     * `BTreeMap` (not `HashMap`) so `save()` serializes panels in a
+     * DETERMINISTIC (sorted) key order — a fresh `HashMap` per call
+     * iterates in a per-instance random order, which made consecutive
+     * `save()` outputs byte-unstable.
+     */
+    panels: {
+        [key in string]?: PanelViewerConfig<string>;
+    };
+    /**
+     * The element-level global (master/detail cross-) filters. A transient
+     * overlay on every detail panel's view — persisted here, never in a
+     * per-panel entry. Omitted when empty.
+     */
+    global_filters?: Array<Filter>;
+    /**
+     * The MASTER (filter-source) panels' ids, referencing `panels` keys.
+     * Roles are layout state (like the panel arrangement), so they persist;
+     * which master contributed which clause does not — restored
+     * `global_filters` are one unattributed bucket. Omitted when empty.
+     */
+    masters?: Array<string>;
+};

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

@@ -0,0 +1,28 @@
+import type { Filter } from "./Filter.js";
+import type { Layout } from "./Layout.js";
+import type { ViewerConfigUpdate } from "./ViewerConfigUpdate.js";
+/**
+ * The parse target of a whole-element config in
+ * [`PerspectiveViewerElement::restore`]. Mirrors [`WorkspaceConfig`],
+ * but `panels` entries are full [`ViewerConfigUpdate`]s so a stray per-panel
+ * `settings` can be detected (warned, then ignored — `create_panel` strips
+ * it).
+ */
+export type WorkspaceConfigUpdate = {
+    active?: string;
+    layout?: Layout;
+    panels: {
+        [key in string]?: ViewerConfigUpdate;
+    };
+    /**
+     * 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.
+     */
+    global_filters?: Array<Filter>;
+    /**
+     * The master (filter-source) panels, by saved `panels` key. An id not in
+     * `panels` warns and is dropped.
+     */
+    masters?: Array<string>;
+};