@perspective-dev/viewer 4.0.0 → 4.1.0

package/dist/esm/plugin.d.ts

@@ -1,4 +1,4 @@
-import { View } from "@perspective-dev/client";
+import type { View } from "@perspective-dev/client";
 /**
  * The `IPerspectiveViewerPlugin` interface defines the necessary API for a
  * `<perspective-viewer>` plugin, which also must be an `HTMLElement` via the

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

@@ -10,6 +10,7 @@ export type ViewerConfigUpdate = {
     version?: OptionalUpdate<string>;
     plugin?: OptionalUpdate<string>;
     title?: OptionalUpdate<string>;
+    table?: OptionalUpdate<string>;
     theme?: OptionalUpdate<string>;
     settings?: OptionalUpdate<boolean>;
     plugin_config?: PluginConfig | null;

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

@@ -15,6 +15,7 @@ export function registerPlugin(name: string): void;
 export function init(): void;
 
 import type {
+    ColumnType,
     TableInitOptions, 
     ColumnWindow,
     ViewWindow, 
@@ -66,6 +67,7 @@ import type {
  */
 export class Client {
   free(): void;
+  [Symbol.dispose](): void;
   __getClassname(): string;
   constructor(send_request: Function, close?: Function | null);
   new_proxy_session(on_response: Function): ProxySession;
@@ -147,7 +149,7 @@ export class Client {
    * const table = await client.table(data, { index: "Row ID" });
    * ```
    */
-  table(value: string | ArrayBuffer | Record<string, unknown[]> | Record<string, unknown>[], options?: TableInitOptions | null): Promise<Table>;
+  table(value: string | ArrayBuffer | Record<string, unknown[]> | Record<string, unknown>[] | Record<string, ColumnType>, options?: TableInitOptions | null): Promise<Table>;
   /**
    * Terminates this [`Client`], cleaning up any [`crate::View`] handles the
    * [`Client`] has open as well as its callbacks.
@@ -184,7 +186,7 @@ export class Client {
    * const tables = await client.get_hosted_table_names();
    * ```
    */
-  get_hosted_table_names(): Promise<any>;
+  get_hosted_table_names(): Promise<string[]>;
   /**
    * Register a callback which is invoked whenever [`Client::table`] (on this
    * [`Client`]) or [`Table::delete`] (on a [`Table`] belinging to this
@@ -214,9 +216,11 @@ export class Client {
 export class ColumnDropDownElement {
   private constructor();
   free(): void;
+  [Symbol.dispose](): void;
 }
 export class CopyDropDownMenuElement {
   free(): void;
+  [Symbol.dispose](): void;
   constructor(elem: HTMLElement);
   open(target: HTMLElement): void;
   hide(): void;
@@ -225,11 +229,12 @@ export class CopyDropDownMenuElement {
    *
    * Set this custom element model's raw pointer.
    */
-  set_model(parent: PerspectiveViewerElement): void;
+  __set_model(parent: PerspectiveViewerElement): void;
   connected_callback(): void;
 }
 export class ExportDropDownMenuElement {
   free(): void;
+  [Symbol.dispose](): void;
   constructor(elem: HTMLElement);
   open(target: HTMLElement): void;
   hide(): void;
@@ -238,16 +243,35 @@ export class ExportDropDownMenuElement {
    *
    * Set this custom element model's raw pointer.
    */
-  set_model(parent: PerspectiveViewerElement): void;
+  __set_model(parent: PerspectiveViewerElement): void;
   connected_callback(): void;
 }
 export class FilterDropDownElement {
   private constructor();
   free(): void;
+  [Symbol.dispose](): void;
 }
 export class FunctionDropDownElement {
   private constructor();
   free(): void;
+  [Symbol.dispose](): void;
+}
+export class JsVirtualDataSlice {
+  free(): void;
+  [Symbol.dispose](): void;
+  constructor();
+  setCol(dtype: string, name: string, index: number, val: any, group_by_index?: number | null): void;
+  setStringCol(name: string, index: number, val: any, group_by_index?: number | null): void;
+  setIntegerCol(name: string, index: number, val: any, group_by_index?: number | null): void;
+  setFloatCol(name: string, index: number, val: any, group_by_index?: number | null): void;
+  setBooleanCol(name: string, index: number, val: any, group_by_index?: number | null): void;
+  setDatetimeCol(name: string, index: number, val: any, group_by_index?: number | null): void;
+}
+export class JsVirtualServer {
+  free(): void;
+  [Symbol.dispose](): void;
+  constructor(handler: object);
+  handleRequest(bytes: Uint8Array): Promise<any>;
 }
 /**
  * The `<perspective-viewer-plugin>` element.
@@ -267,6 +291,7 @@ export class FunctionDropDownElement {
  */
 export class PerspectiveDebugPluginElement {
   free(): void;
+  [Symbol.dispose](): void;
   constructor(elem: HTMLElement);
   update(view: View): Promise<any>;
   /**
@@ -300,21 +325,61 @@ export class PerspectiveDebugPluginElement {
  * const viewer = document.createElement("perspective-viewer");
  * window.body.appendChild(viewer);
  * ```
+ *
+ * Complete example including loading and restoring the [`Table`]:
+ *
+ * ```javascript
+ * import perspective from "@perspective-dev/viewer";
+ * import perspective from "@perspective-dev/client";
+ *
+ * const viewer = document.createElement("perspective-viewer");
+ * const worker = await perspective.worker();
+ *
+ * await worker.table("x\n1", {name: "table_one"});
+ * await viewer.load(worker);
+ * await viewer.restore({table: "table_one"});
+ * ```
  */
 export class PerspectiveViewerElement {
   free(): void;
+  [Symbol.dispose](): void;
   constructor(elem: HTMLElement);
   connectedCallback(): void;
   /**
-   * Loads a [`Table`] (or rather, a Javascript `Promise` which returns a
-   * [`Table`]) in this viewer.
+   * Loads a [`Client`], or optionally [`Table`], or optionally a Javascript
+   * `Promise` which returns a [`Client`] or [`Table`], in this viewer.
+   *
+   * Loading a [`Client`] does not render, but subsequent calls to
+   * [`PerspectiveViewerElement::restore`] will use this [`Client`] to look
+   * up the proviced `table` name field for the provided
+   * [`ViewerConfigUpdate`].
+   *
+   * Loading a [`Table`] is equivalent to subsequently calling
+   * [`Self::restore`] with the `table` field set to [`Table::get_name`], and
+   * will render the UI in its default state when [`Self::load`] resolves.
+   * If you plan to call [`Self::restore`] anyway, prefer passing a
+   * [`Client`] argument to [`Self::load`] as it will conserve one render.
    *
    * When [`PerspectiveViewerElement::load`] resolves, the first frame of the
    * UI + visualization is guaranteed to have been drawn. Awaiting the result
    * of this method in a `try`/`catch` block will capture any errors
-   * thrown during the loading process, or from the [`Table`] `Promise`
+   * thrown during the loading process, or from the [`Client`] `Promise`
    * itself.
    *
+   * [`PerspectiveViewerElement::load`] may also be called with a [`Table`],
+   * which is equivalent to:
+   *
+   * ```javascript
+   * await viewer.load(await table.get_client());
+   * await viewer.restore({name: await table.get_name()})
+   * ```
+   *
+   * If you plan to call [`PerspectiveViewerElement::restore`] immediately
+   * after [`PerspectiveViewerElement::load`] yourself, as is commonly
+   * done when loading and configuring a new `<perspective-viewer>`, you
+   * should use a [`Client`] as an argument and set the `table` field in the
+   * restore call as
+   *
    * A [`Table`] can be created using the
    * [`@perspective-dev/client`](https://www.npmjs.com/package/@perspective-dev/client)
    * library from NPM (see [`perspective_js`] documentation for details).
@@ -325,7 +390,35 @@ export class PerspectiveViewerElement {
    * import perspective from "@perspective-dev/client";
    *
    * const worker = await perspective.worker();
-   * viewer.load(worker.table("x,y\n1,2"));
+   * viewer.load(worker);
+   * ```
+   *
+   * ... or
+   *
+   * ```javascript
+   * const table = await worker.table(data, {name: "superstore"});
+   * viewer.load(table);
+   * ```
+   *
+   * Complete example:
+   *
+   * ```javascript
+   * const viewer = document.createElement("perspective-viewer");
+   * const worker = await perspective.worker();
+   *
+   * await worker.table("x\n1", {name: "table_one"});
+   * await viewer.load(worker);
+   * await viewer.restore({table: "table_one", columns: ["x"]});
+   * ```
+   *
+   * ... or, if you don't want to pass your own arguments to `restore`:
+   *
+   * ```javascript
+   * const viewer = document.createElement("perspective-viewer");
+   * const worker = await perspective.worker();
+   *
+   * const table = await worker.table("x\n1", {name: "table_one"});
+   * await viewer.load(table);
    * ```
    */
   load(table: any): Promise<any>;
@@ -384,9 +477,18 @@ export class PerspectiveViewerElement {
    * ```
    */
   getView(): 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
+   * [`PerspectiveViewerElement::save`]), and also makes no API calls to the
+   * server (unlike [`PerspectiveViewerElement::getView`] followed by
+   * [`View::get_config`])
+   */
+  getViewConfig(): Promise<any>;
   /**
    * Get the underlying [`Table`] for this viewer (as passed to
-   * [`PerspectiveViewerElement::load`]).
+   * [`PerspectiveViewerElement::load`] or as the `table` field to
+   * [`PerspectiveViewerElement::restore`]).
    *
    * # Arguments
    *
@@ -401,6 +503,24 @@ export class PerspectiveViewerElement {
    * ```
    */
   getTable(wait_for_table?: boolean | null): Promise<any>;
+  /**
+   * Get the underlying [`Client`] for this viewer (as passed to, or
+   * associated with the [`Table`] passed to,
+   * [`PerspectiveViewerElement::load`]).
+   *
+   * # Arguments
+   *
+   * - `wait_for_client` - whether to wait for
+   *   [`PerspectiveViewerElement::load`] to be called, or fail immediately
+   *   if [`PerspectiveViewerElement::load`] has not yet been called.
+   *
+   * # JavaScript Examples
+   *
+   * ```javascript
+   * const client = await viewer.getClient();
+   * ```
+   */
+  getClient(wait_for_client?: boolean | null): Promise<any>;
   /**
    * Get render statistics. Some fields of the returned stats object are
    * relative to the last time [`PerspectiveViewerElement::getRenderStats`]
@@ -436,7 +556,8 @@ export class PerspectiveViewerElement {
   flush(): Promise<any>;
   /**
    * Restores this element from a full/partial
-   * [`perspective_js::JsViewConfig`].
+   * [`perspective_js::JsViewConfig`] (this element's user-configurable
+   * state, including the `Table` name).
    *
    * One of the best ways to use [`Self::restore`] is by first configuring
    * a `<perspective-viewer>` as you wish, then using either the `Debug`
@@ -450,22 +571,30 @@ export class PerspectiveViewerElement {
    *
    * # JavaScript Examples
    *
-   * Apply a `group_by` to the current [`View`], without modifying/resetting
-   * other fields:
+   * Loads a default plugin for the table named `"superstore"`:
+   *
+   * ```javascript
+   * await viewer.restore({table: "superstore"});
+   * ```
+   *
+   * Apply a `group_by` to the same `viewer` element, without
+   * modifying/resetting other fields - you can omit the `table` field,
+   * this has already been set once and is not modified:
    *
    * ```javascript
    * await viewer.restore({group_by: ["State"]});
    * ```
    */
   restore(update: any): Promise<any>;
+  /**
+   * If this element is in an _errored_ state, this method will clear it and
+   * re-render. Calling this method is equivalent to clicking the error reset
+   * button in the UI.
+   */
   resetError(): Promise<any>;
   /**
-   * Save this element to serialized state object, one which can be restored
-   * via the [`Self::restore`] method.
-   *
-   * # Arguments
-   *
-   * - `format` - Supports "json" (default), "arraybuffer" or "string".
+   * Save this element's user-configurable state to a serialized state
+   * object, one which can be restored via the [`Self::restore`] method.
    *
    * # JavaScript Examples
    *
@@ -484,14 +613,14 @@ export class PerspectiveViewerElement {
    * });
    * ```
    */
-  save(format?: string | null): Promise<any>;
+  save(): Promise<any>;
   /**
-   * Download this viewer's internal [`View`] data as a `.csv` file.
+   * Download this viewer's internal [`View`] data via a browser download
+   * event.
    *
    * # Arguments
    *
-   * - `flat` - Whether to use the current [`perspective_js::JsViewConfig`]
-   *   to generate this data, or use the default.
+   * - `method` - The `ExportMethod` to use to render the data to download.
    *
    * # JavaScript Examples
    *
@@ -501,7 +630,28 @@ export class PerspectiveViewerElement {
    * })
    * ```
    */
-  download(flat?: boolean | null): Promise<any>;
+  download(method?: string | null): Promise<any>;
+  /**
+   * Exports this viewer's internal [`View`] as a JavaSript data, the
+   * exact type of which depends on the `method` but defaults to `String`
+   * in CSV format.
+   *
+   * This method is only really useful for the `"plugin"` method, which
+   * will use the configured plugin's export (e.g. PNG for
+   * `@perspective-dev/viewer-d3fc`). Otherwise, prefer to call the
+   * equivalent method on the underlying [`View`] directly.
+   *
+   * # Arguments
+   *
+   * - `method` - The `ExportMethod` to use to render the data to download.
+   *
+   * # JavaScript Examples
+   *
+   * ```javascript
+   * const data = await viewer.export("plugin");
+   * ```
+   */
+  export(method?: string | null): Promise<any>;
   /**
    * Copy this viewer's `View` or `Table` data as CSV to the system
    * clipboard.
@@ -704,7 +854,7 @@ export class PerspectiveViewerElement {
   /**
    * Create a new JavaScript Heap reference for this model instance.
    */
-  get_model(): PerspectiveViewerElement;
+  __get_model(): PerspectiveViewerElement;
   /**
    * Asynchronously opens the column settings for a specific column.
    * When finished, the `<perspective-viewer>` element will emit a
@@ -722,6 +872,7 @@ export class PerspectiveViewerElement {
 }
 export class ProxySession {
   free(): void;
+  [Symbol.dispose](): void;
   constructor(client: Client, on_response: Function);
   handle_request(value: any): Promise<void>;
   close(): Promise<void>;
@@ -729,6 +880,7 @@ export class ProxySession {
 export class Table {
   private constructor();
   free(): void;
+  [Symbol.dispose](): void;
   __getClassname(): string;
   /**
    * Returns the name of the index column for the table.
@@ -740,7 +892,7 @@ export class Table {
    * const index = table.get_index(); // "x"
    * ```
    */
-  get_index(): Promise<string | undefined>;
+  get_index(): Promise<string>;
   /**
    * Get a copy of the [`Client`] this [`Table`] came from.
    */
@@ -816,7 +968,7 @@ export class Table {
    * Note that all [`Table`] columns are _nullable_, regardless of the data
    * type.
    */
-  schema(): Promise<any>;
+  schema(): Promise<Record<string, ColumnType>>;
   /**
    * Returns the column names of this [`Table`] in "natural" order (the
    * ordering implied by the input format).
@@ -905,7 +1057,7 @@ export class Table {
    * await table.update("x,y\n1,2");
    * ```
    */
-  update(input: string | ArrayBuffer | Record<string, unknown[]> | Record<string, unknown>[], options?: UpdateOptions | null): Promise<any>;
+  update(input: string | ArrayBuffer | Record<string, unknown[]> | Record<string, unknown>[] | Record<string, ColumnType>, options?: UpdateOptions | null): Promise<any>;
   /**
    * Create a new [`View`] from this table with a specified
    * [`ViewConfigUpdate`].
@@ -947,6 +1099,7 @@ export class Table {
 export class View {
   private constructor();
   free(): void;
+  [Symbol.dispose](): void;
   __get_model(): View;
   /**
    * Returns an array of strings containing the column paths of the [`View`]
@@ -1133,7 +1286,7 @@ export interface InitOutput {
   readonly copydropdownmenuelement_new: (a: number) => number;
   readonly copydropdownmenuelement_open: (a: number, b: number) => void;
   readonly copydropdownmenuelement_hide: (a: number, b: number) => void;
-  readonly copydropdownmenuelement_set_model: (a: number, b: number) => void;
+  readonly copydropdownmenuelement___set_model: (a: number, b: number) => void;
   readonly copydropdownmenuelement_connected_callback: (a: number) => void;
   readonly __wbg_perspectivedebugpluginelement_free: (a: number, b: number) => void;
   readonly perspectivedebugpluginelement_new: (a: number) => number;
@@ -1145,23 +1298,26 @@ export interface InitOutput {
   readonly perspectivedebugpluginelement_connectedCallback: (a: number) => void;
   readonly exportdropdownmenuelement_open: (a: number, b: number) => void;
   readonly exportdropdownmenuelement_hide: (a: number, b: number) => void;
-  readonly exportdropdownmenuelement_set_model: (a: number, b: number) => void;
+  readonly exportdropdownmenuelement___set_model: (a: number, b: number) => void;
   readonly __wbg_filterdropdownelement_free: (a: number, b: number) => void;
   readonly __wbg_functiondropdownelement_free: (a: number, b: number) => void;
   readonly __wbg_perspectiveviewerelement_free: (a: number, b: number) => void;
   readonly perspectiveviewerelement_new: (a: number) => number;
-  readonly perspectiveviewerelement_connectedCallback: (a: number) => void;
-  readonly perspectiveviewerelement_load: (a: number, b: number) => number;
+  readonly perspectiveviewerelement_connectedCallback: (a: number, b: number) => void;
+  readonly perspectiveviewerelement_load: (a: number, b: number, c: number) => void;
   readonly perspectiveviewerelement_delete: (a: number) => number;
   readonly perspectiveviewerelement_eject: (a: number) => number;
   readonly perspectiveviewerelement_getView: (a: number) => number;
+  readonly perspectiveviewerelement_getViewConfig: (a: number) => number;
   readonly perspectiveviewerelement_getTable: (a: number, b: number) => number;
+  readonly perspectiveviewerelement_getClient: (a: number, b: number) => number;
   readonly perspectiveviewerelement_getRenderStats: (a: number, b: number) => void;
   readonly perspectiveviewerelement_flush: (a: number) => number;
   readonly perspectiveviewerelement_restore: (a: number, b: number) => number;
   readonly perspectiveviewerelement_resetError: (a: number) => number;
-  readonly perspectiveviewerelement_save: (a: number, b: number, c: number) => number;
+  readonly perspectiveviewerelement_save: (a: number) => number;
   readonly perspectiveviewerelement_download: (a: number, b: number) => number;
+  readonly perspectiveviewerelement_export: (a: number, b: number) => number;
   readonly perspectiveviewerelement_copy: (a: number, b: number) => number;
   readonly perspectiveviewerelement_reset: (a: number, b: number) => number;
   readonly perspectiveviewerelement_resize: (a: number, b: number) => number;
@@ -1176,7 +1332,7 @@ export interface InitOutput {
   readonly perspectiveviewerelement_toggleConfig: (a: number, b: number) => number;
   readonly perspectiveviewerelement_getAllPlugins: (a: number) => number;
   readonly perspectiveviewerelement_getPlugin: (a: number, b: number, c: number, d: number) => void;
-  readonly perspectiveviewerelement_get_model: (a: number) => number;
+  readonly perspectiveviewerelement___get_model: (a: number) => number;
   readonly perspectiveviewerelement_toggleColumnSettings: (a: number, b: number, c: number) => number;
   readonly perspectiveviewerelement_openColumnSettings: (a: number, b: number, c: number, d: number) => number;
   readonly registerPlugin: (a: number, b: number) => void;
@@ -1252,21 +1408,37 @@ export interface InitOutput {
   readonly view_collapse: (a: number, b: number) => number;
   readonly view_expand: (a: number, b: number) => number;
   readonly view_set_depth: (a: number, b: number) => number;
+  readonly __wbg_jsvirtualdataslice_free: (a: number, b: number) => void;
+  readonly jsvirtualdataslice_new: () => number;
+  readonly jsvirtualdataslice_setCol: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => void;
+  readonly jsvirtualdataslice_setStringCol: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+  readonly jsvirtualdataslice_setIntegerCol: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+  readonly jsvirtualdataslice_setFloatCol: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+  readonly jsvirtualdataslice_setBooleanCol: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+  readonly jsvirtualdataslice_setDatetimeCol: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+  readonly __wbg_jsvirtualserver_free: (a: number, b: number) => void;
+  readonly jsvirtualserver_new: (a: number, b: number) => void;
+  readonly jsvirtualserver_handleRequest: (a: number, b: number, c: number) => number;
   readonly proxysession_new: (a: number, b: number) => number;
-  readonly __wbindgen_export_0: (a: number, b: number) => number;
-  readonly __wbindgen_export_1: (a: number, b: number, c: number, d: number) => number;
-  readonly __wbindgen_export_2: (a: number) => void;
-  readonly __wbindgen_export_3: (a: number, b: number, c: number) => void;
-  readonly __wbindgen_export_4: WebAssembly.Table;
+  readonly __wasm_bindgen_func_elem_5617: (a: number, b: number, c: number) => void;
+  readonly __wasm_bindgen_func_elem_457: (a: number, b: number) => void;
+  readonly __wasm_bindgen_func_elem_18124: (a: number, b: number) => void;
+  readonly __wasm_bindgen_func_elem_18117: (a: number, b: number) => void;
+  readonly __wasm_bindgen_func_elem_17201: (a: number, b: number, c: number) => void;
+  readonly __wasm_bindgen_func_elem_17129: (a: number, b: number) => void;
+  readonly __wasm_bindgen_func_elem_5616: (a: number, b: number, c: number) => void;
+  readonly __wasm_bindgen_func_elem_452: (a: number, b: number) => void;
+  readonly __wasm_bindgen_func_elem_18145: (a: number, b: number, c: number) => void;
+  readonly __wasm_bindgen_func_elem_18130: (a: number, b: number) => void;
+  readonly __wasm_bindgen_func_elem_5618: (a: number, b: number, c: number) => void;
+  readonly __wasm_bindgen_func_elem_13043: (a: number, b: number) => number;
+  readonly __wasm_bindgen_func_elem_12575: (a: number, b: number) => void;
+  readonly __wasm_bindgen_func_elem_19812: (a: number, b: number, c: number, d: 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;
+  readonly __wbindgen_export4: (a: number, b: number, c: number) => void;
   readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
-  readonly __wbindgen_export_5: (a: number, b: number, c: number) => void;
-  readonly __wbindgen_export_6: (a: number, b: number, c: number) => void;
-  readonly __wbindgen_export_7: (a: number, b: number, c: number) => void;
-  readonly __wbindgen_export_8: (a: number, b: number) => number;
-  readonly __wbindgen_export_9: (a: number, b: number, c: number) => void;
-  readonly __wbindgen_export_10: (a: number, b: number) => void;
-  readonly __wbindgen_export_11: (a: number, b: number, c: number) => void;
-  readonly __wbindgen_export_12: (a: number, b: number, c: number, d: number) => void;
 }
 
 export type SyncInitInput = BufferSource | WebAssembly.Module;