@perspective-dev/viewer 4.4.0 → 4.5.0

package/src/ts/plugin.ts

@@ -11,8 +11,7 @@
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
 import type { View } from "@perspective-dev/client";
-
-// import type * as perspective from "@perspective-dev/client";
+import { PluginStaticConfig } from "./ts-rs/PluginStaticConfig.js";
 
 /**
  * The `IPerspectiveViewerPlugin` interface defines the necessary API for a
@@ -21,7 +20,8 @@ import type { View } from "@perspective-dev/client";
  * scratch however, the simplest way is to inherit from
  * `<perspective-viewer-plugin>`, which implements `IPerspectiveViewerPlugin`
  * with non-offensive default implementations, where only the `draw()` and
- * `name()` methods need be overridden to get started with a simple plugin.
+ * `get_static_config()` methods need be overridden to get started with a
+ * simple plugin.
  *
  * Note that plugins are frozen once a `<perspective-viewer>` has been
  * instantiated, so generally new plugin code must be executed at the module
@@ -32,8 +32,8 @@ import type { View } from "@perspective-dev/client";
  * ```javascript
  * const BasePlugin = customElements.get("perspective-viewer-plugin");
  * class MyPlugin extends BasePlugin {
- *     get name() {
- *         return "My Plugin";
+ *     get_static_config() {
+ *         return { name: "My Plugin", config_column_names: [] };
  *     }
  *     async draw(view) {
  *         const count = await view.num_rows();
@@ -49,63 +49,17 @@ import type { View } from "@perspective-dev/client";
  */
 export interface IPerspectiveViewerPlugin {
     /**
-     * The name for this plugin, which is used as both it's unique key for use
-     * as a parameter for the `plugin` field of a `ViewerConfig`, and as the
-     * display name for this plugin in the `<perspective-viewer>` UI.
-     */
-    get name(): string;
-
-    /**
-     * Select mode determines how column add/remove buttons behave for this
-     * plugin.  `"select"` mode exclusively selects the added column, removing
-     * other columns.  `"toggle"` mode toggles the column on or off (dependent
-     * on column state), leaving existing columns alone.
-     */
-    get select_mode(): string | undefined;
-
-    /**
-     * The minimum number of columns required for this plugin to operate.
-     * This mostly affects drag/drop and column remove button behavior,
-     * preventing the use from applying configs which violate this min.
-     *
-     * While this option can technically be `undefined` (as in the case of
-     * `@perspective-dev/viewer-datagrid`), doing so currently has nearly
-     * identical behavior to 1.
-     */
-    get min_config_columns(): number | undefined;
-
-    /**
-     * The named column labels, if desired.  Named columns behave differently
-     * in drag/drop mode than unnamed columns, having replace/swap behavior
-     * rather than insert.  If provided, the length of `config_column_names`
-     * _must_ be `>= min_config_columns`, as this is assumed by the drag/drop
-     * logic.
-     */
-    get config_column_names(): string[] | undefined;
-
-    /**
-     * The load priority of the plugin. If the plugin shares priority with another,
-     * the first to load has a higher priority.
-     *
-     * A larger number has a higher priority.
-     *
-     * The plugin with the highest priority will be loaded by default by the Perspective viewer.
-     * If you would like to instead begin with a lower priority plugin, choose it explicitly with
-     * a `HTMLPerspectiveViewerPluginElement.restore` call.
-     */
-    get priority(): number | undefined;
-
-    /**
-     * Given a column's grouping (determined by indexing it in `plugin.config_column_names`)
-     * and its view type, determines whether or not to render column styles in the settings sidebar.
-     * Implementing this function and `column_style_config` allows the plugin to interface with the viewer's column configuration API.
+     * Static plugin configuration. Called exactly once per plugin at
+     * registration time and cached; the result must be stable for the
+     * lifetime of the application.
      */
-    can_render_column_styles?: (view_type: string, group: string) => boolean;
+    get_static_config(): PluginStaticConfig;
 
     /**
      * Determines which column configuration controls are populated in the viewer.
-     * Corresponds to the data the plugin will recieve on save.
-     * Implementing this function and `can_render_column_styles` allows the plugin to interface with the viewer's column configuration API.
+     * Corresponds to the data the plugin will recieve on save. Only
+     * invoked when `can_render_column_styles` is `true` in the static
+     * config.
      */
     column_style_config?: (view_type: string, group: string) => any;
 
@@ -157,36 +111,23 @@ export interface IPerspectiveViewerPlugin {
      * Like `update()`, but for when the dimensions of the plugin have changed
      * and the underlying data has not.
      */
-    resize(): Promise<void>;
+    resize(view: View): Promise<void>;
 
     /**
      * Notify the plugin that the style environment has changed.  Useful for
      * plugins which read CSS styles via `window.getComputedStyle()`.
      */
-    restyle(): Promise<void>;
-
-    /**
-     * Save this plugin's state to a JSON-serializable value.  While this value
-     * can be anything, it should work reciprocally with `restore()` to return
-     * this plugin's renderer to the same state, though potentially with a
-     * different `View`.
-     *
-     * `save()` should be used for user-persistent settings that are
-     * data-agnostic, so the user can have persistent view during refresh or
-     * reload.  For example, `@perspective-dev/viewer-d3fc` uses
-     * `plugin_config` to remember the user-repositionable legend coordinates.
-     */
-    save(): Promise<any>;
+    restyle(): void;
 
     /**
      * Restore this plugin to a state previously returned by `save()`.
      */
-    restore(config: any): Promise<void>;
+    restore(config: any): void;
 
     /**
      * Free any resources acquired by this plugin and prepare to be deleted.
      */
-    delete(): Promise<void>;
+    delete(): void;
 }
 
 /**
@@ -213,33 +154,16 @@ export class HTMLPerspectiveViewerPluginElement
         super();
     }
 
-    get name(): string {
-        return "Debug";
-    }
-
-    get select_mode(): "select" | "toggle" {
-        return "select";
-    }
-
-    get min_config_columns(): number | undefined {
-        return undefined;
-    }
-
-    get config_column_names(): string[] | undefined {
-        return undefined;
-    }
-
-    get priority(): number {
-        return 0;
-    }
-
-    can_render_column_styles(): boolean {
-        return false;
+    get_static_config(): PluginStaticConfig {
+        return {
+            name: "Debug",
+            select_mode: "select",
+            config_column_names: [],
+        };
     }
 
     column_style_config(): any {
-        {
-        }
+        return {};
     }
 
     async update(view: View): Promise<void> {
@@ -257,23 +181,23 @@ export class HTMLPerspectiveViewerPluginElement
         this.innerHTML = "";
     }
 
-    async resize(): Promise<void> {
+    async resize(view: View): Promise<void> {
         // Not Implemented
     }
 
-    async restyle(): Promise<void> {
+    restyle() {
         // Not Implemented
     }
 
-    async save(): Promise<any> {
+    restore(): void {
         // Not Implemented
     }
 
-    async restore(): Promise<void> {
+    async delete(): Promise<void> {
         // Not Implemented
     }
 
-    async delete(): Promise<void> {
-        // Not Implemented
+    get supports_streaming(): boolean {
+        return false;
     }
 }

package/src/ts/ts-rs/{FormatUnit.ts → ColumnSelectMode.ts}

@@ -1,3 +1,3 @@
 // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
 
-export type FormatUnit = "custom";
+export type ColumnSelectMode = "toggle" | "select";

package/src/ts/ts-rs/PluginStaticConfig.ts

@@ -0,0 +1,78 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { ColumnSelectMode } from "./ColumnSelectMode.js";
+import type { GroupRollupMode } from "./GroupRollupMode.js";
+
+/**
+ * Static, immutable configuration for a plugin.
+ *
+ * Returned once per plugin from `get_static_config()` at registration
+ * time and cached in [`crate::renderer::PluginRecord`]. Consumers
+ * (renderer, session, queries, components) read these fields off the
+ * renderer's active-plugin metadata rather than calling back into JS.
+ *
+ * `<perspective-viewer>` reads this exactly once per plugin (at
+ * `registerPlugin` time) and caches it for the lifetime of the
+ * application. The result must be stable; do not mutate any field
+ * after registration.
+ */
+export type PluginStaticConfig = { 
+/**
+ * The unique key for this plugin. Used as the `plugin` field in a
+ * `ViewerConfig` and as the display name key in the
+ * `<perspective-viewer>` UI.
+ */
+name: string, 
+/**
+ * Category in the plugin picker menu.
+ */
+category?: string | null, 
+/**
+ * Soft limit on the number of columns the plugin will render.
+ * Triggers the "Rendering N of M" warning when the view exceeds
+ * this value (until dismissed).
+ */
+max_columns?: number | null, 
+/**
+ * Soft limit on the number of cells (rows × columns) the plugin
+ * will render. Triggers the "Rendering N of M" warning when the view
+ * exceeds this value (until dismissed).
+ */
+max_cells?: number | null, 
+/**
+ * Column add/remove behavior. `"select"` exclusively selects the
+ * added column, removing other columns. `"toggle"` toggles the
+ * column on or off based on its current state, leaving other
+ * columns alone.
+ */
+select_mode?: ColumnSelectMode, 
+/**
+ * Minimum number of columns the plugin requires to render. Mostly
+ * affects drag/drop and column-remove button behavior. `undefined`
+ * is treated identically to `1`.
+ */
+min_config_columns?: number | null, 
+/**
+ * Named column slots. Named columns have replace/swap behavior in
+ * drag/drop rather than insert. The length must be at least
+ * `min_config_columns`.
+ */
+config_column_names?: Array<string>, 
+/**
+ * Group-rollup modes the plugin accepts, in preference order.
+ * The first entry that matches a feature flag becomes the default.
+ */
+group_rollup_modes?: Array<GroupRollupMode> | null, 
+/**
+ * Plugin load priority. Higher numbers win; ties resolve in
+ * registration order. The highest-priority plugin is loaded by
+ * default unless `restore({ plugin })` overrides it.
+ */
+priority?: number | null, 
+/**
+ * Whether this plugin opts into per-column style controls in the
+ * settings sidebar. When `true`, the StyleTab is shown for active
+ * columns and the plugin's `column_config_schema` is queried for
+ * the per-column field set. When `false` or omitted, no StyleTab
+ * is shown.
+ */
+can_render_column_styles?: boolean, };

package/src/ts/ts-rs/ViewerConfig.ts

@@ -0,0 +1,14 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+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 state of an entire `custom_elements::PerspectiveViewerElement` component
+ * and its `Plugin`.
+ */
+export type ViewerConfig<V = string> = { version: V, columns_config: { [key in string]?: { [key in string]?: JsonValue } }, plugin: string, plugin_config: { [key in string]?: JsonValue }, settings: boolean, 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/src/ts/ts-rs/ViewerConfigUpdate.ts

@@ -1,15 +1,14 @@
 // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
 import type { Aggregate } from "./Aggregate.js";
-import type { ColumnConfigValues } from "./ColumnConfigValues.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 { OptionalUpdate } from "./OptionalUpdate.js";
-import type { PluginConfig } from "./PluginConfig.js";
 import type { Sort } from "./Sort.js";
+import type { JsonValue } from "./serde_json/JsonValue.js";
 
-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, columns_config?: OptionalUpdate<{ [key in string]?: ColumnConfigValues }>, 
+export type ViewerConfigUpdate = { version?: OptionalUpdate<string>, plugin?: OptionalUpdate<string>, title?: OptionalUpdate<string>, table?: OptionalUpdate<string>, theme?: OptionalUpdate<string>, settings?: OptionalUpdate<boolean>, plugin_config?: OptionalUpdate<{ [key in string]?: JsonValue }>, columns_config?: OptionalUpdate<{ [key in string]?: { [key in string]?: JsonValue } }>, 
 /**
  * A group by _groups_ the dataset by the unique values of each column used
  * as a group by - a close analogue in SQL to the `GROUP BY` statement.

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

@@ -1,31 +0,0 @@
-import type { CustomNumberFormatConfig } from "./CustomNumberFormatConfig.js";
-import type { DatetimeColorMode } from "./DatetimeColorMode.js";
-import type { DatetimeFormatType } from "./DatetimeFormatType.js";
-import type { FormatMode } from "./FormatMode.js";
-import type { NumberBackgroundMode } from "./NumberBackgroundMode.js";
-import type { NumberForegroundMode } from "./NumberForegroundMode.js";
-import type { StringColorMode } from "./StringColorMode.js";
-/**
- * The value de/serialized and stored in the viewer config.
- * Also passed to the plugin via `plugin.save()`.
- */
-export type ColumnConfigValues = {
-    symbols?: {
-        [key in string]?: string;
-    };
-    number_format?: CustomNumberFormatConfig | null;
-    aggregate_depth?: number;
-    number_fg_mode?: NumberForegroundMode;
-    number_bg_mode?: NumberBackgroundMode;
-    pos_fg_color: string | null;
-    neg_fg_color: string | null;
-    pos_bg_color: string | null;
-    neg_bg_color: string | null;
-    fg_gradient: number | null;
-    bg_gradient: number | null;
-    format?: FormatMode;
-    string_color_mode?: StringColorMode;
-    color?: string | null;
-    date_format?: DatetimeFormatType;
-    datetime_color_mode?: DatetimeColorMode;
-};

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

@@ -1 +0,0 @@
-export type CustomDatetimeFormat = "long" | "short" | "narrow" | "numeric" | "2-digit" | "disabled";

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

@@ -1,15 +0,0 @@
-import type { CustomDatetimeFormat } from "./CustomDatetimeFormat.js";
-import type { FormatUnit } from "./FormatUnit.js";
-export type CustomDatetimeStyleConfig = {
-    format: FormatUnit;
-    timeZone?: string | null;
-    fractionalSecondDigits?: number;
-    second?: CustomDatetimeFormat;
-    minute?: CustomDatetimeFormat;
-    hour?: CustomDatetimeFormat;
-    day?: CustomDatetimeFormat;
-    weekday?: CustomDatetimeFormat;
-    month?: CustomDatetimeFormat;
-    year?: CustomDatetimeFormat;
-    hour12?: boolean;
-};

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

@@ -1,18 +0,0 @@
-import type { RoundingMode } from "./RoundingMode.js";
-import type { RoundingPriority } from "./RoundingPriority.js";
-import type { SignDisplay } from "./SignDisplay.js";
-import type { TrailingZeroDisplay } from "./TrailingZeroDisplay.js";
-import type { UseGrouping } from "./UseGrouping.js";
-export type CustomNumberFormatConfig = {
-    minimumIntegerDigits: number | null;
-    minimumFractionDigits: number | null;
-    maximumFractionDigits: number | null;
-    minimumSignificantDigits: number | null;
-    maximumSignificantDigits: number | null;
-    roundingPriority: RoundingPriority | null;
-    roundingIncrement: number | null;
-    roundingMode: RoundingMode | null;
-    trailingZeroDisplay: TrailingZeroDisplay | null;
-    useGrouping: UseGrouping | null;
-    signDisplay: SignDisplay | null;
-};

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

@@ -1 +0,0 @@
-export type DatetimeColorMode = "none" | "foreground" | "background";

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

@@ -1,6 +0,0 @@
-import type { CustomDatetimeStyleConfig } from "./CustomDatetimeStyleConfig.js";
-import type { SimpleDatetimeStyleConfig } from "./SimpleDatetimeStyleConfig.js";
-/**
- * `Simple` case has all default-able keys and must be last!
- */
-export type DatetimeFormatType = CustomDatetimeStyleConfig | SimpleDatetimeStyleConfig;

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

@@ -1 +0,0 @@
-export type FormatMode = "none" | "link" | "bold" | "italics";

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

@@ -1 +0,0 @@
-export type FormatUnit = "custom";

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

@@ -1 +0,0 @@
-export type NumberBackgroundMode = "disabled" | "color" | "gradient" | "pulse";

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

@@ -1 +0,0 @@
-export type NumberForegroundMode = "disabled" | "color" | "bar";

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

@@ -1,2 +0,0 @@
-import type { JsonValue } from "./serde_json/JsonValue.js";
-export type PluginConfig = JsonValue;

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

@@ -1 +0,0 @@
-export type RoundingMode = "ceil" | "floor" | "expand" | "trunc" | "halfCeil" | "halfFloor" | "halfExpand" | "halfTrunc" | "halfEven";

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

@@ -1 +0,0 @@
-export type RoundingPriority = "auto" | "morePrecision" | "lessPrecision";

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

@@ -1 +0,0 @@
-export type SignDisplay = "auto" | "always" | "exceptZero" | "negative" | "never";

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

@@ -1 +0,0 @@
-export type SimpleDatetimeFormat = "full" | "long" | "medium" | "short" | "disabled";

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

@@ -1,6 +0,0 @@
-import type { SimpleDatetimeFormat } from "./SimpleDatetimeFormat.js";
-export type SimpleDatetimeStyleConfig = {
-    timeZone?: string | null;
-    dateStyle?: SimpleDatetimeFormat;
-    timeStyle?: SimpleDatetimeFormat;
-};

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

@@ -1 +0,0 @@
-export type StringColorMode = "none" | "foreground" | "background" | "series";

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

@@ -1 +0,0 @@
-export type TrailingZeroDisplay = "auto" | "stripIfInteger";

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

@@ -1 +0,0 @@
-export type UseGrouping = "always" | "auto" | "min2" | boolean;