@perspective-dev/viewer 5.1.0 → 5.3.0

package/src/ts/ts-rs/ViewerConfigInitial.ts

@@ -0,0 +1,164 @@
+// 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 { 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/src/ts/ts-rs/ViewerConfigUpdate.ts

@@ -6,10 +6,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 = { 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 } }>, 
+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 } }>, 
 /**
  * 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.
@@ -65,6 +122,12 @@ filter?: Array<Filter>,
  * 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>, 
 /**
@@ -95,5 +158,12 @@ windows?: Windows,
  * 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, };
+aggregates?: { [key in string]?: Aggregate }, group_by_depth?: number, filter_op?: FilterReducer, group_rollup_mode?: GroupRollupMode, split_rollup_mode?: SplitRollupMode, };

package/src/ts/ts-rs/WindowSpec.ts

@@ -1,5 +1,4 @@
 // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
-import type { WindowAggregate } from "./WindowAggregate.js";
 import type { WindowSort } from "./WindowSort.js";
 
 /**
@@ -10,7 +9,7 @@ export type WindowSpec = {
  * The input column - either a real `Table` column or an expression
  * alias from the same `ViewConfig`.
  */
-column: string, aggregate: WindowAggregate, 
+column: string, aggregate: string, 
 /**
  * Columns whose distinct value tuples partition the rows; empty
  * partitions the whole `Table` as one group.
@@ -18,6 +17,8 @@ column: string, aggregate: WindowAggregate,
 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, 
 /**

package/src/ts/ts-rs/WorkspaceConfig.ts

@@ -4,7 +4,7 @@ import type { Layout } from "./Layout.js";
 import type { PanelViewerConfig } from "./PanelViewerConfig.js";
 
 /**
- * The whole-element config format (`{version, active?, layout, panels}`) —
+ * The workspace config format (`{version, active?, layout, panels}`) —
  * the multi-panel counterpart of the single-panel [`ViewerConfig`] — as
  * emitted by [`PerspectiveViewerElement::save`].
  *
@@ -33,4 +33,10 @@ global_filters?: Array<Filter>,
  * which master contributed which clause does not — restored
  * `global_filters` are one unattributed bucket. Omitted when empty.
  */
-masters?: Array<string>, };
+masters?: Array<string>, 
+/**
+ * Named color-scale definitions shared by every panel: CSS custom
+ * property name (`--psp-user--<kind>-<name>`) → canonical CSS
+ * value.
+ */
+palette?: { [key in string]?: string }, };

package/src/ts/ts-rs/WorkspaceConfigUpdate.ts

@@ -1,24 +1,33 @@
 // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
 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).
+ * The parse target of a workspace config in
+ * [`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 }, 
+export type WorkspaceConfigUpdate = { active?: string, layout?: Layout, panels: { [key in string]?: ViewerConfigInitial }, 
 /**
  * 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.
+ * `Option` so an explicit `undefined` property deserializes as
+ * `None` like an absent key (also `masters` / `palette` below).
  */
-global_filters?: Array<Filter>, 
+global_filters?: Array<Filter> | null, 
 /**
  * The master (filter-source) panels, by saved `panels` key. An id not in
  * `panels` warns and is dropped.
  */
-masters?: Array<string>, };
+masters?: Array<string> | null, 
+/**
+ * Named color-scale definitions to apply to the host (see
+ * [`WorkspaceConfig::palette`]), replacing any previously restored
+ * palette.
+ */
+palette?: { [key in string]?: string } | null, };

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

@@ -1 +0,0 @@
-export type WindowAggregate = "sum" | "avg" | "count" | "min" | "max" | "stddev" | "var" | "first" | "last" | "lag" | "lead" | "diff" | "rate" | "ema";

package/src/rust/components/form/color_range_selector.rs

@@ -1,137 +0,0 @@
-// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
-// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
-// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
-// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
-// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
-// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
-// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
-// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
-// ┃ This file is part of the Perspective library, distributed under the terms ┃
-// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
-// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
-
-use wasm_bindgen::JsCast;
-use web_sys::*;
-use yew::prelude::*;
-
-#[derive(Properties, PartialEq, Clone)]
-pub struct ColorRangeProps {
-    /// Extra class appended to the positive input's `class` attribute,
-    /// so callers can target the pos / neg sides independently from CSS.
-    /// Paired with `neg_class`; both default to empty.
-    #[prop_or_default]
-    pub pos_class: Classes,
-    #[prop_or_default]
-    pub neg_class: Classes,
-    pub pos_color: String,
-    pub neg_color: String,
-    pub is_gradient: bool,
-    pub on_pos_color: Callback<String>,
-    pub on_neg_color: Callback<String>,
-    pub on_reset: Callback<()>,
-    pub is_modified: bool,
-}
-
-#[function_component(ColorRangeSelector)]
-pub fn color_chooser_component(props: &ColorRangeProps) -> Html {
-    let on_pos_color = use_callback(
-        props.on_pos_color.clone(),
-        |event: InputEvent, on_pos_color| {
-            let color = event
-                .target()
-                .unwrap()
-                .unchecked_into::<HtmlInputElement>()
-                .value();
-            on_pos_color.emit(color);
-        },
-    );
-
-    let on_neg_color = use_callback(
-        props.on_neg_color.clone(),
-        |event: InputEvent, on_neg_color| {
-            let color = event
-                .target()
-                .unwrap()
-                .unchecked_into::<HtmlInputElement>()
-                .value();
-            on_neg_color.emit(color);
-        },
-    );
-
-    let fg_pos = infer_fg(&props.pos_color);
-    let fg_neg = infer_fg(&props.neg_color);
-    let style = if props.is_gradient {
-        format!(
-            "background:linear-gradient(to right, {} 0%, transparent 50%, {} 100%)",
-            props.pos_color, props.neg_color
-        )
-    } else {
-        format!(
-            "background:linear-gradient(to right, {} 0%, {} 50%, {} 50%,  {} 100%)",
-            props.pos_color, props.pos_color, props.neg_color, props.neg_color
-        )
-    };
-
-    let on_reset = use_callback(props.clone(), |_: MouseEvent, deps| deps.on_reset.emit(()));
-
-    let pos_class = classes!("parameter", "pos-color-param", props.pos_class.clone());
-    let neg_class = classes!("parameter", "neg-color-param", props.neg_class.clone());
-
-    html! {
-        <>
-            <label id="color-range-label" />
-            <div class="color-gradient-container">
-                <div style={fg_pos} class="color-selector">
-                    <input
-                        class={pos_class}
-                        type="color"
-                        value={props.pos_color.to_owned()}
-                        data-value={props.pos_color.to_owned()}
-                        oninput={on_pos_color}
-                    />
-                    <label class="color-label">{ "+" }</label>
-                </div>
-                <div class="color-thermometer" {style} />
-                <div style={fg_neg} class="color-selector">
-                    <input
-                        class={neg_class}
-                        type="color"
-                        value={props.neg_color.to_owned()}
-                        data-value={props.neg_color.to_owned()}
-                        oninput={on_neg_color}
-                    />
-                    <label class="color-label">{ "-" }</label>
-                </div>
-                if props.is_modified {
-                    <span class="reset-default-style" onclick={on_reset} />
-                } else {
-                    <span class="reset-default-style-disabled" />
-                }
-            </div>
-        </>
-    }
-}
-
-fn infer_fg(color: &str) -> &'static str {
-    if color.len() >= 7 {
-        let r = i32::from_str_radix(&color[1..3], 16).unwrap_or(255) as f64;
-        let g = i32::from_str_radix(&color[3..5], 16).unwrap_or(0) as f64;
-        let b = i32::from_str_radix(&color[5..7], 16).unwrap_or(0) as f64;
-        if (r * r * 0.299 + g * g * 0.587 + b * b * 0.114).sqrt() > 130.0 {
-            "--sign--color:var(--psp--color)"
-        } else {
-            "--sign--color:var(--psp--background-color)"
-        }
-    } else if color.len() == 4 {
-        let r = i32::from_str_radix(&color[1..2], 16).unwrap_or(15) as f64;
-        let g = i32::from_str_radix(&color[2..3], 16).unwrap_or(0) as f64;
-        let b = i32::from_str_radix(&color[3..4], 16).unwrap_or(0) as f64;
-        if (r * r * 0.299 + g * g * 0.587 + b * b * 0.114).sqrt() > 8.0 {
-            "--sign--color:var(--psp--color)"
-        } else {
-            "--sign--color:var(--psp--background-color)"
-        }
-    } else {
-        "--sign--color:var(--psp--color)"
-    }
-}

package/src/ts/ts-rs/WindowAggregate.ts

@@ -1,3 +0,0 @@
-// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
-
-export type WindowAggregate = "sum" | "avg" | "count" | "min" | "max" | "stddev" | "var" | "first" | "last" | "lag" | "lead" | "diff" | "rate" | "ema";