@perspective-dev/viewer 4.0.0

package/dist/esm/plugin.d.ts

@@ -0,0 +1,195 @@
+import { 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
+ * Custom Elements API or otherwise.  Rather than implement this API from
+ * 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.
+ *
+ * Note that plugins are frozen once a `<perspective-viewer>` has been
+ * instantiated, so generally new plugin code must be executed at the module
+ * level (if packaged as a library), or during application init to ensure global
+ * availability of a plugin.
+ *
+ * @example
+ * ```javascript
+ * const BasePlugin = customElements.get("perspective-viewer-plugin");
+ * class MyPlugin extends BasePlugin {
+ *     get name() {
+ *         return "My Plugin";
+ *     }
+ *     async draw(view) {
+ *         const count = await view.num_rows();
+ *         this.innerHTML = `View has ${count} rows`;
+ *     }
+ * }
+ *
+ * customElements.define("my-plugin", MyPlugin);
+ * const Viewer = customElements.get("perspective-viewer");
+ * Viewer.registerPlugin("my-plugin");
+ * ```
+ * @noInheritDoc
+ */
+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.
+     */
+    can_render_column_styles?: (view_type: string, group: string) => boolean;
+    /**
+     * 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.
+     */
+    column_style_config?: (view_type: string, group: string) => any;
+    /**
+     * Render this plugin using the provided `View`.  While there is no
+     * provision to cancel a render in progress per se, calling a method on
+     * a `View` which has been deleted will throw an exception.
+     *
+     * @example
+     * ```
+     * async draw(view: perspective.View): Promise<void> {
+     *     const csv = await view.to_csv();
+     *     this.innerHTML = `<pre>${csv}</pre>`;
+     * }
+     * ```
+     */
+    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()`.
+     *
+     * @example
+     * ```javascript
+     * async update(view: perspective.View): Promise<void> {
+     *     return this.draw(view);
+     * }
+     * ```
+     */
+    update(view: View): Promise<void>;
+    /**
+     * Clear this plugin, though it is up to the discretion of the plugin
+     * author to determine what this means.  Defaults to resetting this
+     * element's `innerHTML`, so be sure to override if you want custom
+     * behavior.
+     *
+     * @example
+     * ```javascript
+     * async clear(): Promise<void> {
+     *     this.innerHTML = "";
+     * }
+     * ```
+     */
+    clear(): Promise<void>;
+    /**
+     * Like `update()`, but for when the dimensions of the plugin have changed
+     * and the underlying data has not.
+     */
+    resize(): 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>;
+    /**
+     * Restore this plugin to a state previously returned by `save()`.
+     */
+    restore(config: any): Promise<void>;
+    /**
+     * Free any resources acquired by this plugin and prepare to be deleted.
+     */
+    delete(): Promise<void>;
+}
+/**
+ * The `<perspective-viewer-plugin>` element, the default perspective plugin
+ * which is registered and activated automcatically when a
+ * `<perspective-viewer>` is loaded without plugins.  While you will not
+ * typically instantiate this class directly, it is simple enough to function
+ * as a good "default" plugin implementation which can be extended to create
+ * custom plugins.
+ *
+ * @example
+ * ```javascript
+ * class MyPlugin extends customElements.get("perspective-viewer-plugin") {
+ *    // Custom plugin overrides
+ * }
+ * ```
+ * @noInheritDoc
+ */
+export declare class HTMLPerspectiveViewerPluginElement extends HTMLElement implements IPerspectiveViewerPlugin {
+    constructor();
+    get name(): string;
+    get select_mode(): "select" | "toggle";
+    get min_config_columns(): number | undefined;
+    get config_column_names(): string[] | undefined;
+    get priority(): number;
+    can_render_column_styles(): boolean;
+    column_style_config(): any;
+    update(view: View): Promise<void>;
+    draw(view: View): Promise<void>;
+    clear(): Promise<void>;
+    resize(): Promise<void>;
+    restyle(): Promise<void>;
+    save(): Promise<any>;
+    restore(): Promise<void>;
+    delete(): Promise<void>;
+}

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

@@ -0,0 +1 @@
+export type Aggregate = string | [string, Array<string>];

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

@@ -0,0 +1,31 @@
+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

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

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

@@ -0,0 +1,15 @@
+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

@@ -0,0 +1,18 @@
+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

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

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

@@ -0,0 +1,6 @@
+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/Expressions.d.ts

@@ -0,0 +1,3 @@
+export type Expressions = {
+    [key in string]?: string;
+};

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

@@ -0,0 +1,2 @@
+import type { FilterTerm } from "./FilterTerm.js";
+export type Filter = [string, string, FilterTerm];

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

@@ -0,0 +1 @@
+export type FilterReducer = "and" | "or";

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

@@ -0,0 +1,2 @@
+import type { Scalar } from "./Scalar.js";
+export type FilterTerm = Array<Scalar> | Scalar;

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

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

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

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

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

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

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

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

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

@@ -0,0 +1 @@
+export type OptionalUpdate<T> = null | T;

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

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

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

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

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

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

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

@@ -0,0 +1,5 @@
+/**
+ * This type represents the ViewConfig serializable type, which must be JSON
+ * safe.
+ */
+export type Scalar = number | string | boolean | null;

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

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

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

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

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

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

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

@@ -0,0 +1,2 @@
+import type { SortDir } from "./SortDir.js";
+export type Sort = [string, SortDir];

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

@@ -0,0 +1 @@
+export type SortDir = "none" | "desc" | "asc" | "col desc" | "col asc" | "desc abs" | "asc abs" | "col desc abs" | "col asc abs";

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

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

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

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

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

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

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

@@ -0,0 +1,102 @@
+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 { OptionalUpdate } from "./OptionalUpdate.js";
+import type { PluginConfig } from "./PluginConfig.js";
+import type { Sort } from "./Sort.js";
+export type ViewerConfigUpdate = {
+    version?: OptionalUpdate<string>;
+    plugin?: OptionalUpdate<string>;
+    title?: OptionalUpdate<string>;
+    theme?: OptionalUpdate<string>;
+    settings?: OptionalUpdate<boolean>;
+    plugin_config?: PluginConfig | null;
+    columns_config?: OptionalUpdate<{
+        [key in string]?: ColumnConfigValues;
+    }>;
+    /**
+     * 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.
+     * The underlying dataset is aggregated to show the values belonging to
+     * each group, and a total row is calculated for each group, showing
+     * the currently selected aggregated value (e.g. `sum`) of the column.
+     * Group by are useful for hierarchies, categorizing data and
+     * attributing values, i.e. showing the number of units sold based on
+     * State and City. In Perspective, group by are represented as an array
+     * of string column names to pivot, are applied in the order provided;
+     * For example, a group by of `["State", "City", "Postal Code"]` shows
+     * the values for each Postal Code, which are grouped by City,
+     * which are in turn grouped by State.
+     */
+    group_by?: Array<string>;
+    /**
+     * A split by _splits_ the dataset by the unique values of each column used
+     * as a split by. The underlying dataset is not aggregated, and a new
+     * column is created for each unique value of the split by. Each newly
+     * created column contains the parts of the dataset that correspond to
+     * the column header, i.e. a `View` that has `["State"]` as its split
+     * by will have a new column for each state. In Perspective, Split By
+     * are represented as an array of string column names to pivot.
+     */
+    split_by?: Array<string>;
+    /**
+     * The `columns` property specifies which columns should be included in the
+     * [`crate::View`]'s output. This allows users to show or hide a specific
+     * subset of columns, as well as control the order in which columns
+     * appear to the user. This is represented in Perspective as an array
+     * of string column names.
+     */
+    columns?: Array<string | null>;
+    /**
+     * The `filter` property specifies columns on which the query can be
+     * filtered, returning rows that pass the specified filter condition.
+     * This is analogous to the `WHERE` clause in SQL. There is no limit on
+     * the number of columns where `filter` is applied, but the resulting
+     * dataset is one that passes all the filter conditions, i.e. the
+     * filters are joined with an `AND` condition.
+     *
+     * Perspective represents `filter` as an array of arrays, with the values
+     * of each inner array being a string column name, a string filter
+     * operator, and a filter operand in the type of the column.
+     */
+    filter?: Array<Filter>;
+    /**
+     * The `sort` property specifies columns on which the query should be
+     * sorted, analogous to `ORDER BY` in SQL. A column can be sorted
+     * regardless of its data type, and sorts can be applied in ascending
+     * or descending order. Perspective represents `sort` as an array of
+     * arrays, with the values of each inner array being a string column
+     * name and a string sort direction. When `column-pivots` are applied,
+     * the additional sort directions `"col asc"` and `"col desc"` will
+     * determine the order of pivot columns groups.
+     */
+    sort?: Array<Sort>;
+    /**
+     * The `expressions` property specifies _new_ columns in Perspective that
+     * are created using existing column values or arbitary scalar values
+     * defined within the expression. In `<perspective-viewer>`,
+     * expressions are added using the "New Column" button in the side
+     * panel.
+     */
+    expressions?: Expressions;
+    /**
+     * Aggregates perform a calculation over an entire column, and are
+     * displayed when one or more [Group By](#group-by) are applied to the
+     * `View`. Aggregates can be specified by the user, or Perspective will
+     * use the following sensible default aggregates based on column type:
+     *
+     * - "sum" for `integer` and `float` columns
+     * - "count" for all other columns
+     *
+     * Perspective provides a selection of aggregate functions that can be
+     * applied to columns in the `View` constructor using a dictionary of
+     * column name to aggregate function name.
+     */
+    aggregates?: {
+        [key in string]?: Aggregate;
+    };
+    group_by_depth?: number;
+    filter_op?: FilterReducer;
+};

package/dist/esm/ts-rs/serde_json/JsonValue.d.ts

@@ -0,0 +1,3 @@
+export type JsonValue = number | string | boolean | Array<JsonValue> | {
+    [key in string]?: JsonValue;
+} | null;