@perspective-dev/viewer 5.0.0 → 5.2.0

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

@@ -0,0 +1,175 @@
+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 { SplitRollupMode } from "./SplitRollupMode.js";
+import type { Windows } from "./Windows.js";
+import type { JsonValue } from "./serde_json/JsonValue.js";
+/**
+ * The initial configuration of a NEW panel (`addPanel`, `restore`'s
+ * panel-creating upsert, `restoreWorkspace` `panels` entries). Unlike
+ * [`ViewerConfigUpdate`] — a patch against existing state — creation has
+ * no prior state: `table` is REQUIRED (a placed panel without a table
+ * binding would be permanently blank), absent fields mean "default"
+ * rather than "leave unchanged" (so no [`OptionalUpdate`] tri-state), and
+ * there is no `settings` field (element-level, not per-panel).
+ */
+export type ViewerConfigInitial = {
+    /**
+     * Name of the `Table` the new panel renders, as hosted on the
+     * `Client`. REQUIRED: a placed panel with no table binding would be
+     * permanently blank.
+     */
+    table: string;
+    /**
+     * The `@perspective-dev/viewer` version a saved config was written
+     * by. Omit it when creating a panel.
+     */
+    version?: string;
+    /**
+     * Name of the visualization plugin, from the set registered on the
+     * page (the `list_plugins` agent tool, or the plugin picker).
+     * Decides what the view fields MEAN: `columns` is positional and
+     * every plugin reads the positions differently, and
+     * `group_by`/`split_by` draw different things per plugin. Absent
+     * uses the default plugin.
+     */
+    plugin?: string;
+    /**
+     * Panel title, shown in its tab. Absent renders the default title.
+     */
+    title?: string;
+    /**
+     * Theme NAME (e.g. `"Pro Dark"`) — not a CSS value. Valid names are
+     * the Perspective themes loaded on the page. Absent uses the
+     * default.
+     */
+    theme?: string;
+    /**
+     * Plugin-wide settings (as opposed to the per-column
+     * [`Self::columns_config`]). Opaque to the viewer and defined by
+     * the ACTIVE plugin; query the valid keys with `get_style_schema`
+     * rather than guessing.
+     */
+    plugin_config?: {
+        [key in string]?: JsonValue;
+    };
+    /**
+     * Per-column styling — formatting, colors, and other per-column
+     * controls — keyed by column name. Plugin-defined like
+     * [`Self::plugin_config`]; see `get_style_schema`.
+     */
+    columns_config?: {
+        [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.
+     * 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` is the ONLY thing that orders a `View`'s rows — without it
+     * they keep the `Table`'s natural (insertion) order, which any
+     * consumer reading rows sequentially will reflect. Not to be
+     * confused with a window column's `order_by`, which orders rows
+     * WITHIN a window frame and does not reorder the `View`.
+     */
+    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;
+    /**
+     * The `windows` property declares ordered, partitioned rolling
+     * computations (moving aggregates, cumulative sums) as _new_ columns
+     * keyed by output alias (`{"name": {...spec}}`, symmetric with
+     * `expressions`), analogous to SQL window functions. See
+     * [`crate::config::WindowSpec`].
+     */
+    windows?: Windows;
+    /**
+     * 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.
+     *
+     * An aggregate also determines the column's RESULT TYPE, which need
+     * not match the input: `"count"` yields an `integer` whatever it
+     * counts, so a `date` column left on the default `"count"` is an
+     * `integer` in the resulting `View` — no longer a date. Set an
+     * aggregate that preserves the type (e.g. `"any"`, `"last"`) when
+     * the original type matters, such as a date used as a chart axis.
+     */
+    aggregates?: {
+        [key in string]?: Aggregate;
+    };
+    group_by_depth?: number;
+    filter_op?: FilterReducer;
+    group_rollup_mode?: GroupRollupMode;
+    split_rollup_mode?: SplitRollupMode;
+};

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

@@ -5,17 +5,67 @@ import type { FilterReducer } from "./FilterReducer.js";
 import type { GroupRollupMode } from "./GroupRollupMode.js";
 import type { OptionalUpdate } from "./OptionalUpdate.js";
 import type { Sort } from "./Sort.js";
+import type { SplitRollupMode } from "./SplitRollupMode.js";
+import type { Windows } from "./Windows.js";
 import type { JsonValue } from "./serde_json/JsonValue.js";
 export type ViewerConfigUpdate = {
+    /**
+     * The `@perspective-dev/viewer` version a saved config was written
+     * by, used to migrate older tokens. Omit it — the viewer stamps
+     * the current version on save.
+     */
     version?: OptionalUpdate<string>;
+    /**
+     * Name of the visualization plugin to switch to, from the set
+     * registered on the page (the `list_plugins` agent tool, or the
+     * plugin picker). Changing it changes what the view fields MEAN:
+     * `columns` is positional and every plugin reads the positions
+     * differently, and `group_by`/`split_by` draw different things per
+     * plugin — so read the new plugin's roles before writing `columns`
+     * for it.
+     */
     plugin?: OptionalUpdate<string>;
+    /**
+     * Panel title, shown in its tab. `null` restores the default
+     * title; omitting the field leaves the current one.
+     */
     title?: OptionalUpdate<string>;
+    /**
+     * Name of the `Table` to render, as hosted on this panel's
+     * `Client`. Rebinding an existing panel to another table keeps the
+     * rest of the config, so column names that do not exist in the new
+     * table will fail validation.
+     */
     table?: OptionalUpdate<string>;
+    /**
+     * Theme NAME (e.g. `"Pro Dark"`) — not a CSS value. Valid names are
+     * the Perspective themes loaded on the page, re-scanned by
+     * `resetThemes()`. `null` selects the default.
+     */
     theme?: OptionalUpdate<string>;
+    /**
+     * Whether the settings sidebar is OPEN. Purely cosmetic chrome —
+     * it does not affect what the viewer renders, and it is
+     * element-level rather than per-panel.
+     */
     settings?: OptionalUpdate<boolean>;
+    /**
+     * Plugin-wide settings (as opposed to the per-column
+     * [`Self::columns_config`]). The viewer passes these through
+     * opaquely — their valid keys are defined by the ACTIVE plugin and
+     * vary by plugin and by state, so query them with the
+     * `get_style_schema` agent tool rather than guessing.
+     */
     plugin_config?: OptionalUpdate<{
         [key in string]?: JsonValue;
     }>;
+    /**
+     * Per-column styling — formatting, colors, and other per-column
+     * controls — keyed by column name. Opaque to the viewer and
+     * plugin-defined like [`Self::plugin_config`]; `get_style_schema`
+     * reports the valid keys for a given column under the active
+     * plugin.
+     */
     columns_config?: OptionalUpdate<{
         [key in string]?: {
             [key in string]?: JsonValue;
@@ -76,6 +126,12 @@ export type ViewerConfigUpdate = {
      * 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` is the ONLY thing that orders a `View`'s rows — without it
+     * they keep the `Table`'s natural (insertion) order, which any
+     * consumer reading rows sequentially will reflect. Not to be
+     * confused with a window column's `order_by`, which orders rows
+     * WITHIN a window frame and does not reorder the `View`.
      */
     sort?: Array<Sort>;
     /**
@@ -86,6 +142,14 @@ export type ViewerConfigUpdate = {
      * panel.
      */
     expressions?: Expressions;
+    /**
+     * The `windows` property declares ordered, partitioned rolling
+     * computations (moving aggregates, cumulative sums) as _new_ columns
+     * keyed by output alias (`{"name": {...spec}}`, symmetric with
+     * `expressions`), analogous to SQL window functions. See
+     * [`crate::config::WindowSpec`].
+     */
+    windows?: Windows;
     /**
      * Aggregates perform a calculation over an entire column, and are
      * displayed when one or more [Group By](#group-by) are applied to the
@@ -98,6 +162,13 @@ export type ViewerConfigUpdate = {
      * 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.
+     *
+     * An aggregate also determines the column's RESULT TYPE, which need
+     * not match the input: `"count"` yields an `integer` whatever it
+     * counts, so a `date` column left on the default `"count"` is an
+     * `integer` in the resulting `View` — no longer a date. Set an
+     * aggregate that preserves the type (e.g. `"any"`, `"last"`) when
+     * the original type matters, such as a date used as a chart axis.
      */
     aggregates?: {
         [key in string]?: Aggregate;
@@ -105,4 +176,5 @@ export type ViewerConfigUpdate = {
     group_by_depth?: number;
     filter_op?: FilterReducer;
     group_rollup_mode?: GroupRollupMode;
+    split_rollup_mode?: SplitRollupMode;
 };

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

@@ -0,0 +1,7 @@
+import type { WindowSortDir } from "./WindowSortDir.js";
+/**
+ * The `Table` column which orders each partition, with its direction -
+ * serialized as a two-element array (`["ts", "desc"]`), symmetric with the
+ * `ViewConfig`'s `sort` field.
+ */
+export type WindowSort = [string, WindowSortDir];

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

@@ -0,0 +1,6 @@
+/**
+ * A window's order direction. A dedicated two-variant enum rather than
+ * [`crate::config::SortDir`] - the column-sort extras (`col asc`, `abs`,
+ * `none`) are meaningless inside a window frame and unrepresentable here.
+ */
+export type WindowSortDir = "asc" | "desc";

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

@@ -0,0 +1,47 @@
+import type { WindowSort } from "./WindowSort.js";
+/**
+ * The serialized form of [`WindowSpec`].
+ */
+export type WindowSpec = {
+    /**
+     * The input column - either a real `Table` column or an expression
+     * alias from the same `ViewConfig`.
+     */
+    column: string;
+    aggregate: string;
+    /**
+     * Columns whose distinct value tuples partition the rows; empty
+     * partitions the whole `Table` as one group.
+     */
+    partition_by?: Array<string>;
+    /**
+     * The `Table` column which orders each partition, and the direction.
+     * This orders rows WITHIN the window frame only — it does not
+     * reorder the `View`, which is what the view-level `sort` does.
+     */
+    order_by?: WindowSort | null;
+    /**
+     * A frame of the `rows` preceding each row, plus the row itself.
+     * Mutually exclusive with `range` and `cumulative`.
+     */
+    rows?: number | null;
+    /**
+     * A frame of the rows whose `order_by` value lies within `range` of
+     * each row's, requiring a numeric or temporal `order_by`. Mutually
+     * exclusive with `rows` and `cumulative`.
+     */
+    range?: number | null;
+    /**
+     * `true` frames all rows from the partition start through each row.
+     * Default can be omitted.
+     */
+    cumulative?: boolean | null;
+    /**
+     * Row offset for `lag`/`lead` (default 1).
+     */
+    offset?: number | null;
+    /**
+     * Smoothing factor in `(0, 1]` for `ema`.
+     */
+    alpha?: number | null;
+};

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

@@ -0,0 +1,10 @@
+import type { WindowSpec } from "./WindowSpec.js";
+/**
+ * The window columns of a `ViewConfig`, keyed by output column alias -
+ * symmetric with `expressions` (`{"name": {...spec}}`). An alias must not
+ * collide with a `Table` column, expression alias, or another window's
+ * key.
+ */
+export type Windows = {
+    [key in string]?: WindowSpec;
+};

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

@@ -1,18 +1,19 @@
 import type { Filter } from "./Filter.js";
 import type { Layout } from "./Layout.js";
-import type { ViewerConfigUpdate } from "./ViewerConfigUpdate.js";
+import type { ViewerConfigInitial } from "./ViewerConfigInitial.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).
+ * [`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).
  */
 export type WorkspaceConfigUpdate = {
     active?: string;
     layout?: Layout;
     panels: {
-        [key in string]?: ViewerConfigUpdate;
+        [key in string]?: ViewerConfigInitial;
     };
     /**
      * The element-level global (master/detail cross-) filters to re-apply as