@perspective-dev/viewer 5.1.0 → 5.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (175) hide show
  1. package/dist/cdn/perspective-viewer.js +9 -9
  2. package/dist/cdn/perspective-viewer.js.map +4 -4
  3. package/dist/css/botanical.css +1 -1
  4. package/dist/css/dracula.css +1 -1
  5. package/dist/css/gruvbox-dark.css +1 -1
  6. package/dist/css/gruvbox.css +1 -1
  7. package/dist/css/intl/de.css +1 -1
  8. package/dist/css/intl/es.css +1 -1
  9. package/dist/css/intl/fr.css +1 -1
  10. package/dist/css/intl/ja.css +1 -1
  11. package/dist/css/intl/pt.css +1 -1
  12. package/dist/css/intl/zh.css +1 -1
  13. package/dist/css/intl.css +1 -1
  14. package/dist/css/monokai.css +1 -1
  15. package/dist/css/phosphor.css +1 -1
  16. package/dist/css/pro-dark.css +1 -1
  17. package/dist/css/pro.css +1 -1
  18. package/dist/css/solarized-dark.css +1 -1
  19. package/dist/css/solarized.css +1 -1
  20. package/dist/css/themes.css +1 -1
  21. package/dist/css/vaporwave.css +1 -1
  22. package/dist/docs/perspective-docs.json +1 -0
  23. package/dist/esm/column-format.d.ts +19 -28
  24. package/dist/esm/perspective-viewer.d.ts +2 -0
  25. package/dist/esm/perspective-viewer.inline.js +8 -8
  26. package/dist/esm/perspective-viewer.inline.js.map +4 -4
  27. package/dist/esm/perspective-viewer.js +9 -9
  28. package/dist/esm/perspective-viewer.js.map +4 -4
  29. package/dist/esm/providers.d.ts +79 -0
  30. package/dist/esm/ts-rs/CompactDisplay.d.ts +5 -0
  31. package/dist/esm/ts-rs/CurrencyCode.d.ts +1 -0
  32. package/dist/esm/ts-rs/CurrencyDisplay.d.ts +1 -0
  33. package/dist/esm/ts-rs/CurrencyNumberFormatStyle.d.ts +8 -0
  34. package/dist/esm/ts-rs/CurrencySign.d.ts +1 -0
  35. package/dist/esm/ts-rs/CustomDatetimeFormat.d.ts +1 -0
  36. package/dist/esm/ts-rs/CustomDatetimeStyleConfig.d.ts +54 -0
  37. package/dist/esm/ts-rs/CustomNumberFormatConfig.d.ts +34 -0
  38. package/dist/esm/ts-rs/DatetimeColorMode.d.ts +1 -0
  39. package/dist/esm/ts-rs/DatetimeFormatType.d.ts +6 -0
  40. package/dist/esm/ts-rs/FormatMode.d.ts +1 -0
  41. package/dist/esm/ts-rs/FormatUnit.d.ts +1 -0
  42. package/dist/esm/ts-rs/Notation.d.ts +17 -0
  43. package/dist/esm/ts-rs/NumberFormatStyle.d.ts +18 -0
  44. package/dist/esm/ts-rs/PanelViewerConfig.d.ts +41 -1
  45. package/dist/esm/ts-rs/PluginStaticConfig.d.ts +35 -0
  46. package/dist/esm/ts-rs/RestoreOptions.d.ts +19 -0
  47. package/dist/esm/ts-rs/RoundingMode.d.ts +1 -0
  48. package/dist/esm/ts-rs/RoundingPriority.d.ts +1 -0
  49. package/dist/esm/ts-rs/SignDisplay.d.ts +1 -0
  50. package/dist/esm/ts-rs/SimpleDatetimeFormat.d.ts +1 -0
  51. package/dist/esm/ts-rs/SimpleDatetimeStyleConfig.d.ts +24 -0
  52. package/dist/esm/ts-rs/SplitRollupMode.d.ts +9 -0
  53. package/dist/esm/ts-rs/StringColorMode.d.ts +1 -0
  54. package/dist/esm/ts-rs/TrailingZeroDisplay.d.ts +1 -0
  55. package/dist/esm/ts-rs/Unit.d.ts +1 -0
  56. package/dist/esm/ts-rs/UnitDisplay.d.ts +1 -0
  57. package/dist/esm/ts-rs/UnitNumberFormatStyle.d.ts +6 -0
  58. package/dist/esm/ts-rs/UseGrouping.d.ts +1 -0
  59. package/dist/esm/ts-rs/ViewerConfig.d.ts +41 -1
  60. package/dist/esm/ts-rs/ViewerConfigInitial.d.ts +175 -0
  61. package/dist/esm/ts-rs/ViewerConfigUpdate.d.ts +63 -0
  62. package/dist/esm/ts-rs/WindowSpec.d.ts +3 -2
  63. package/dist/esm/ts-rs/WorkspaceConfigUpdate.d.ts +7 -6
  64. package/dist/wasm/perspective-viewer.d.ts +134 -25
  65. package/dist/wasm/perspective-viewer.js +367 -124
  66. package/dist/wasm/perspective-viewer.wasm +0 -0
  67. package/dist/wasm/perspective-viewer.wasm.d.ts +18 -15
  68. package/package.json +2 -1
  69. package/src/css/_viewer_bundle.css +1 -0
  70. package/src/css/column-selector.css +8 -0
  71. package/src/css/config-selector.css +38 -3
  72. package/src/css/form/code-editor.css +2 -3
  73. package/src/css/form/mirrored-textarea.css +81 -0
  74. package/src/css/viewer.css +328 -0
  75. package/src/rust/agent/client/mod.rs +19 -0
  76. package/src/rust/agent/client/protocol.rs +320 -0
  77. package/src/rust/agent/client/transport.rs +287 -0
  78. package/src/rust/agent/client/turn.rs +174 -0
  79. package/src/rust/agent/config.rs +159 -0
  80. package/src/rust/agent/docs.rs +293 -0
  81. package/src/rust/agent/markdown/block.rs +509 -0
  82. package/src/rust/agent/markdown/entity.rs +52 -0
  83. package/src/rust/agent/markdown/events.rs +71 -0
  84. package/src/rust/agent/markdown/inline.rs +497 -0
  85. package/src/rust/agent/markdown/mod.rs +466 -0
  86. package/src/rust/agent/mod.rs +23 -0
  87. package/src/rust/agent/preamble.md +16 -0
  88. package/src/rust/agent/runtime.rs +201 -0
  89. package/src/rust/agent/slot.rs +236 -0
  90. package/src/rust/agent/tools.rs +1110 -0
  91. package/src/rust/components/chat_panel.rs +289 -0
  92. package/src/rust/components/column_selector/config_selector.rs +76 -7
  93. package/src/rust/components/column_selector.rs +7 -0
  94. package/src/rust/components/containers/dragdrop_list.rs +37 -0
  95. package/src/rust/components/form/code_editor.rs +14 -23
  96. package/src/rust/components/form/debug.rs +8 -5
  97. package/src/rust/components/form/mirrored_textarea.rs +165 -0
  98. package/src/rust/components/form/mod.rs +1 -0
  99. package/src/rust/components/mod.rs +2 -0
  100. package/src/rust/components/settings_panel.rs +80 -2
  101. package/src/rust/components/viewer/panels.rs +9 -14
  102. package/src/rust/components/viewer/render.rs +2 -0
  103. package/src/rust/components/window_editor.rs +75 -103
  104. package/src/rust/config/datetime_column_style/custom.rs +17 -0
  105. package/src/rust/config/datetime_column_style/simple.rs +10 -0
  106. package/src/rust/config/number_string_format.rs +33 -0
  107. package/src/rust/config/options.rs +18 -0
  108. package/src/rust/config/plugin_static_config.rs +120 -5
  109. package/src/rust/config/viewer_config.rs +220 -1
  110. package/src/rust/config/workspace_config.rs +7 -6
  111. package/src/rust/custom_elements/viewer.rs +209 -18
  112. package/src/rust/custom_events.rs +29 -0
  113. package/src/rust/lib.rs +13 -0
  114. package/src/rust/presentation.rs +8 -0
  115. package/src/rust/queries/get_viewer_config.rs +5 -1
  116. package/src/rust/session/column_defaults_update.rs +18 -0
  117. package/src/rust/session/metadata.rs +18 -20
  118. package/src/rust/session/replace_expression_update.rs +1 -0
  119. package/src/rust/tasks/create_panel.rs +18 -8
  120. package/src/rust/tasks/edit_window.rs +1 -1
  121. package/src/rust/tasks/restore_panel.rs +34 -17
  122. package/src/rust/tasks/sync_update_panels.rs +7 -23
  123. package/src/rust/workspace.rs +112 -20
  124. package/src/themes/intl/de.css +16 -0
  125. package/src/themes/intl/es.css +16 -0
  126. package/src/themes/intl/fr.css +16 -0
  127. package/src/themes/intl/ja.css +16 -0
  128. package/src/themes/intl/pt.css +16 -0
  129. package/src/themes/intl/zh.css +16 -0
  130. package/src/themes/intl.css +16 -0
  131. package/src/ts/column-format.ts +67 -46
  132. package/src/ts/perspective-viewer.ts +2 -0
  133. package/src/ts/providers.ts +96 -0
  134. package/src/ts/ts-rs/CompactDisplay.ts +3 -0
  135. package/src/ts/ts-rs/CurrencyCode.ts +3 -0
  136. package/src/ts/ts-rs/CurrencyDisplay.ts +3 -0
  137. package/src/ts/ts-rs/CurrencyNumberFormatStyle.ts +6 -0
  138. package/src/ts/ts-rs/CurrencySign.ts +3 -0
  139. package/src/ts/ts-rs/CustomDatetimeFormat.ts +3 -0
  140. package/src/ts/ts-rs/CustomDatetimeStyleConfig.ts +54 -0
  141. package/src/ts/ts-rs/CustomNumberFormatConfig.ts +25 -0
  142. package/src/ts/ts-rs/DatetimeColorMode.ts +3 -0
  143. package/src/ts/ts-rs/DatetimeFormatType.ts +8 -0
  144. package/src/ts/ts-rs/FormatMode.ts +3 -0
  145. package/src/ts/ts-rs/FormatUnit.ts +3 -0
  146. package/src/ts/ts-rs/Notation.ts +11 -0
  147. package/src/ts/ts-rs/NumberFormatStyle.ts +12 -0
  148. package/src/ts/ts-rs/PanelViewerConfig.ts +47 -1
  149. package/src/ts/ts-rs/PluginStaticConfig.ts +36 -1
  150. package/src/ts/ts-rs/RestoreOptions.ts +20 -0
  151. package/src/ts/ts-rs/RoundingMode.ts +3 -0
  152. package/src/ts/ts-rs/RoundingPriority.ts +3 -0
  153. package/src/ts/ts-rs/SignDisplay.ts +3 -0
  154. package/src/ts/ts-rs/SimpleDatetimeFormat.ts +3 -0
  155. package/src/ts/ts-rs/SimpleDatetimeStyleConfig.ts +25 -0
  156. package/src/ts/ts-rs/SplitRollupMode.ts +11 -0
  157. package/src/ts/ts-rs/StringColorMode.ts +3 -0
  158. package/src/ts/ts-rs/TrailingZeroDisplay.ts +3 -0
  159. package/src/ts/ts-rs/Unit.ts +3 -0
  160. package/src/ts/ts-rs/UnitDisplay.ts +3 -0
  161. package/src/ts/ts-rs/UnitNumberFormatStyle.ts +5 -0
  162. package/src/ts/ts-rs/UseGrouping.ts +3 -0
  163. package/src/ts/ts-rs/ViewerConfig.ts +47 -1
  164. package/src/ts/ts-rs/ViewerConfigInitial.ts +164 -0
  165. package/src/ts/ts-rs/ViewerConfigUpdate.ts +72 -2
  166. package/src/ts/ts-rs/WindowSpec.ts +3 -2
  167. package/src/ts/ts-rs/WorkspaceConfigUpdate.ts +7 -6
  168. package/dist/esm/ts-rs/WindowAggregate.d.ts +0 -1
  169. package/src/ts/ts-rs/WindowAggregate.ts +0 -3
  170. /package/dist/wasm/snippets/{perspective-viewer-8a8c7d5d696b43ae → perspective-viewer-02e461f3d7062b26}/inline0.js +0 -0
  171. /package/dist/wasm/snippets/{perspective-viewer-8a8c7d5d696b43ae → perspective-viewer-02e461f3d7062b26}/inline1.js +0 -0
  172. /package/dist/wasm/snippets/{perspective-viewer-8a8c7d5d696b43ae → perspective-viewer-02e461f3d7062b26}/inline2.js +0 -0
  173. /package/dist/wasm/snippets/{perspective-viewer-8a8c7d5d696b43ae → perspective-viewer-02e461f3d7062b26}/inline3.js +0 -0
  174. /package/dist/wasm/snippets/{perspective-viewer-8a8c7d5d696b43ae → perspective-viewer-02e461f3d7062b26}/inline4.js +0 -0
  175. /package/dist/wasm/snippets/{perspective-viewer-8a8c7d5d696b43ae → perspective-viewer-02e461f3d7062b26}/inline5.js +0 -0
@@ -0,0 +1,175 @@
1
+ import type { Aggregate } from "./Aggregate.js";
2
+ import type { Expressions } from "./Expressions.js";
3
+ import type { Filter } from "./Filter.js";
4
+ import type { FilterReducer } from "./FilterReducer.js";
5
+ import type { GroupRollupMode } from "./GroupRollupMode.js";
6
+ import type { Sort } from "./Sort.js";
7
+ import type { SplitRollupMode } from "./SplitRollupMode.js";
8
+ import type { Windows } from "./Windows.js";
9
+ import type { JsonValue } from "./serde_json/JsonValue.js";
10
+ /**
11
+ * The initial configuration of a NEW panel (`addPanel`, `restore`'s
12
+ * panel-creating upsert, `restoreWorkspace` `panels` entries). Unlike
13
+ * [`ViewerConfigUpdate`] — a patch against existing state — creation has
14
+ * no prior state: `table` is REQUIRED (a placed panel without a table
15
+ * binding would be permanently blank), absent fields mean "default"
16
+ * rather than "leave unchanged" (so no [`OptionalUpdate`] tri-state), and
17
+ * there is no `settings` field (element-level, not per-panel).
18
+ */
19
+ export type ViewerConfigInitial = {
20
+ /**
21
+ * Name of the `Table` the new panel renders, as hosted on the
22
+ * `Client`. REQUIRED: a placed panel with no table binding would be
23
+ * permanently blank.
24
+ */
25
+ table: string;
26
+ /**
27
+ * The `@perspective-dev/viewer` version a saved config was written
28
+ * by. Omit it when creating a panel.
29
+ */
30
+ version?: string;
31
+ /**
32
+ * Name of the visualization plugin, from the set registered on the
33
+ * page (the `list_plugins` agent tool, or the plugin picker).
34
+ * Decides what the view fields MEAN: `columns` is positional and
35
+ * every plugin reads the positions differently, and
36
+ * `group_by`/`split_by` draw different things per plugin. Absent
37
+ * uses the default plugin.
38
+ */
39
+ plugin?: string;
40
+ /**
41
+ * Panel title, shown in its tab. Absent renders the default title.
42
+ */
43
+ title?: string;
44
+ /**
45
+ * Theme NAME (e.g. `"Pro Dark"`) — not a CSS value. Valid names are
46
+ * the Perspective themes loaded on the page. Absent uses the
47
+ * default.
48
+ */
49
+ theme?: string;
50
+ /**
51
+ * Plugin-wide settings (as opposed to the per-column
52
+ * [`Self::columns_config`]). Opaque to the viewer and defined by
53
+ * the ACTIVE plugin; query the valid keys with `get_style_schema`
54
+ * rather than guessing.
55
+ */
56
+ plugin_config?: {
57
+ [key in string]?: JsonValue;
58
+ };
59
+ /**
60
+ * Per-column styling — formatting, colors, and other per-column
61
+ * controls — keyed by column name. Plugin-defined like
62
+ * [`Self::plugin_config`]; see `get_style_schema`.
63
+ */
64
+ columns_config?: {
65
+ [key in string]?: {
66
+ [key in string]?: JsonValue;
67
+ };
68
+ };
69
+ /**
70
+ * A group by _groups_ the dataset by the unique values of each column used
71
+ * as a group by - a close analogue in SQL to the `GROUP BY` statement.
72
+ * The underlying dataset is aggregated to show the values belonging to
73
+ * each group, and a total row is calculated for each group, showing
74
+ * the currently selected aggregated value (e.g. `sum`) of the column.
75
+ * Group by are useful for hierarchies, categorizing data and
76
+ * attributing values, i.e. showing the number of units sold based on
77
+ * State and City. In Perspective, group by are represented as an array
78
+ * of string column names to pivot, are applied in the order provided;
79
+ * For example, a group by of `["State", "City", "Postal Code"]` shows
80
+ * the values for each Postal Code, which are grouped by City,
81
+ * which are in turn grouped by State.
82
+ */
83
+ group_by?: Array<string>;
84
+ /**
85
+ * A split by _splits_ the dataset by the unique values of each column used
86
+ * as a split by. The underlying dataset is not aggregated, and a new
87
+ * column is created for each unique value of the split by. Each newly
88
+ * created column contains the parts of the dataset that correspond to
89
+ * the column header, i.e. a `View` that has `["State"]` as its split
90
+ * by will have a new column for each state. In Perspective, Split By
91
+ * are represented as an array of string column names to pivot.
92
+ */
93
+ split_by?: Array<string>;
94
+ /**
95
+ * The `columns` property specifies which columns should be included in the
96
+ * [`crate::View`]'s output. This allows users to show or hide a specific
97
+ * subset of columns, as well as control the order in which columns
98
+ * appear to the user. This is represented in Perspective as an array
99
+ * of string column names.
100
+ */
101
+ columns?: Array<string | null>;
102
+ /**
103
+ * The `filter` property specifies columns on which the query can be
104
+ * filtered, returning rows that pass the specified filter condition.
105
+ * This is analogous to the `WHERE` clause in SQL. There is no limit on
106
+ * the number of columns where `filter` is applied, but the resulting
107
+ * dataset is one that passes all the filter conditions, i.e. the
108
+ * filters are joined with an `AND` condition.
109
+ *
110
+ * Perspective represents `filter` as an array of arrays, with the values
111
+ * of each inner array being a string column name, a string filter
112
+ * operator, and a filter operand in the type of the column.
113
+ */
114
+ filter?: Array<Filter>;
115
+ /**
116
+ * The `sort` property specifies columns on which the query should be
117
+ * sorted, analogous to `ORDER BY` in SQL. A column can be sorted
118
+ * regardless of its data type, and sorts can be applied in ascending
119
+ * or descending order. Perspective represents `sort` as an array of
120
+ * arrays, with the values of each inner array being a string column
121
+ * name and a string sort direction. When `column-pivots` are applied,
122
+ * the additional sort directions `"col asc"` and `"col desc"` will
123
+ * determine the order of pivot columns groups.
124
+ *
125
+ * `sort` is the ONLY thing that orders a `View`'s rows — without it
126
+ * they keep the `Table`'s natural (insertion) order, which any
127
+ * consumer reading rows sequentially will reflect. Not to be
128
+ * confused with a window column's `order_by`, which orders rows
129
+ * WITHIN a window frame and does not reorder the `View`.
130
+ */
131
+ sort?: Array<Sort>;
132
+ /**
133
+ * The `expressions` property specifies _new_ columns in Perspective that
134
+ * are created using existing column values or arbitary scalar values
135
+ * defined within the expression. In `<perspective-viewer>`,
136
+ * expressions are added using the "New Column" button in the side
137
+ * panel.
138
+ */
139
+ expressions?: Expressions;
140
+ /**
141
+ * The `windows` property declares ordered, partitioned rolling
142
+ * computations (moving aggregates, cumulative sums) as _new_ columns
143
+ * keyed by output alias (`{"name": {...spec}}`, symmetric with
144
+ * `expressions`), analogous to SQL window functions. See
145
+ * [`crate::config::WindowSpec`].
146
+ */
147
+ windows?: Windows;
148
+ /**
149
+ * Aggregates perform a calculation over an entire column, and are
150
+ * displayed when one or more [Group By](#group-by) are applied to the
151
+ * `View`. Aggregates can be specified by the user, or Perspective will
152
+ * use the following sensible default aggregates based on column type:
153
+ *
154
+ * - "sum" for `integer` and `float` columns
155
+ * - "count" for all other columns
156
+ *
157
+ * Perspective provides a selection of aggregate functions that can be
158
+ * applied to columns in the `View` constructor using a dictionary of
159
+ * column name to aggregate function name.
160
+ *
161
+ * An aggregate also determines the column's RESULT TYPE, which need
162
+ * not match the input: `"count"` yields an `integer` whatever it
163
+ * counts, so a `date` column left on the default `"count"` is an
164
+ * `integer` in the resulting `View` — no longer a date. Set an
165
+ * aggregate that preserves the type (e.g. `"any"`, `"last"`) when
166
+ * the original type matters, such as a date used as a chart axis.
167
+ */
168
+ aggregates?: {
169
+ [key in string]?: Aggregate;
170
+ };
171
+ group_by_depth?: number;
172
+ filter_op?: FilterReducer;
173
+ group_rollup_mode?: GroupRollupMode;
174
+ split_rollup_mode?: SplitRollupMode;
175
+ };
@@ -5,18 +5,67 @@ import type { FilterReducer } from "./FilterReducer.js";
5
5
  import type { GroupRollupMode } from "./GroupRollupMode.js";
6
6
  import type { OptionalUpdate } from "./OptionalUpdate.js";
7
7
  import type { Sort } from "./Sort.js";
8
+ import type { SplitRollupMode } from "./SplitRollupMode.js";
8
9
  import type { Windows } from "./Windows.js";
9
10
  import type { JsonValue } from "./serde_json/JsonValue.js";
10
11
  export type ViewerConfigUpdate = {
12
+ /**
13
+ * The `@perspective-dev/viewer` version a saved config was written
14
+ * by, used to migrate older tokens. Omit it — the viewer stamps
15
+ * the current version on save.
16
+ */
11
17
  version?: OptionalUpdate<string>;
18
+ /**
19
+ * Name of the visualization plugin to switch to, from the set
20
+ * registered on the page (the `list_plugins` agent tool, or the
21
+ * plugin picker). Changing it changes what the view fields MEAN:
22
+ * `columns` is positional and every plugin reads the positions
23
+ * differently, and `group_by`/`split_by` draw different things per
24
+ * plugin — so read the new plugin's roles before writing `columns`
25
+ * for it.
26
+ */
12
27
  plugin?: OptionalUpdate<string>;
28
+ /**
29
+ * Panel title, shown in its tab. `null` restores the default
30
+ * title; omitting the field leaves the current one.
31
+ */
13
32
  title?: OptionalUpdate<string>;
33
+ /**
34
+ * Name of the `Table` to render, as hosted on this panel's
35
+ * `Client`. Rebinding an existing panel to another table keeps the
36
+ * rest of the config, so column names that do not exist in the new
37
+ * table will fail validation.
38
+ */
14
39
  table?: OptionalUpdate<string>;
40
+ /**
41
+ * Theme NAME (e.g. `"Pro Dark"`) — not a CSS value. Valid names are
42
+ * the Perspective themes loaded on the page, re-scanned by
43
+ * `resetThemes()`. `null` selects the default.
44
+ */
15
45
  theme?: OptionalUpdate<string>;
46
+ /**
47
+ * Whether the settings sidebar is OPEN. Purely cosmetic chrome —
48
+ * it does not affect what the viewer renders, and it is
49
+ * element-level rather than per-panel.
50
+ */
16
51
  settings?: OptionalUpdate<boolean>;
52
+ /**
53
+ * Plugin-wide settings (as opposed to the per-column
54
+ * [`Self::columns_config`]). The viewer passes these through
55
+ * opaquely — their valid keys are defined by the ACTIVE plugin and
56
+ * vary by plugin and by state, so query them with the
57
+ * `get_style_schema` agent tool rather than guessing.
58
+ */
17
59
  plugin_config?: OptionalUpdate<{
18
60
  [key in string]?: JsonValue;
19
61
  }>;
62
+ /**
63
+ * Per-column styling — formatting, colors, and other per-column
64
+ * controls — keyed by column name. Opaque to the viewer and
65
+ * plugin-defined like [`Self::plugin_config`]; `get_style_schema`
66
+ * reports the valid keys for a given column under the active
67
+ * plugin.
68
+ */
20
69
  columns_config?: OptionalUpdate<{
21
70
  [key in string]?: {
22
71
  [key in string]?: JsonValue;
@@ -77,6 +126,12 @@ export type ViewerConfigUpdate = {
77
126
  * name and a string sort direction. When `column-pivots` are applied,
78
127
  * the additional sort directions `"col asc"` and `"col desc"` will
79
128
  * determine the order of pivot columns groups.
129
+ *
130
+ * `sort` is the ONLY thing that orders a `View`'s rows — without it
131
+ * they keep the `Table`'s natural (insertion) order, which any
132
+ * consumer reading rows sequentially will reflect. Not to be
133
+ * confused with a window column's `order_by`, which orders rows
134
+ * WITHIN a window frame and does not reorder the `View`.
80
135
  */
81
136
  sort?: Array<Sort>;
82
137
  /**
@@ -107,6 +162,13 @@ export type ViewerConfigUpdate = {
107
162
  * Perspective provides a selection of aggregate functions that can be
108
163
  * applied to columns in the `View` constructor using a dictionary of
109
164
  * column name to aggregate function name.
165
+ *
166
+ * An aggregate also determines the column's RESULT TYPE, which need
167
+ * not match the input: `"count"` yields an `integer` whatever it
168
+ * counts, so a `date` column left on the default `"count"` is an
169
+ * `integer` in the resulting `View` — no longer a date. Set an
170
+ * aggregate that preserves the type (e.g. `"any"`, `"last"`) when
171
+ * the original type matters, such as a date used as a chart axis.
110
172
  */
111
173
  aggregates?: {
112
174
  [key in string]?: Aggregate;
@@ -114,4 +176,5 @@ export type ViewerConfigUpdate = {
114
176
  group_by_depth?: number;
115
177
  filter_op?: FilterReducer;
116
178
  group_rollup_mode?: GroupRollupMode;
179
+ split_rollup_mode?: SplitRollupMode;
117
180
  };
@@ -1,4 +1,3 @@
1
- import type { WindowAggregate } from "./WindowAggregate.js";
2
1
  import type { WindowSort } from "./WindowSort.js";
3
2
  /**
4
3
  * The serialized form of [`WindowSpec`].
@@ -9,7 +8,7 @@ export type WindowSpec = {
9
8
  * alias from the same `ViewConfig`.
10
9
  */
11
10
  column: string;
12
- aggregate: WindowAggregate;
11
+ aggregate: string;
13
12
  /**
14
13
  * Columns whose distinct value tuples partition the rows; empty
15
14
  * partitions the whole `Table` as one group.
@@ -17,6 +16,8 @@ export type WindowSpec = {
17
16
  partition_by?: Array<string>;
18
17
  /**
19
18
  * The `Table` column which orders each partition, and the direction.
19
+ * This orders rows WITHIN the window frame only — it does not
20
+ * reorder the `View`, which is what the view-level `sort` does.
20
21
  */
21
22
  order_by?: WindowSort | null;
22
23
  /**
@@ -1,18 +1,19 @@
1
1
  import type { Filter } from "./Filter.js";
2
2
  import type { Layout } from "./Layout.js";
3
- import type { ViewerConfigUpdate } from "./ViewerConfigUpdate.js";
3
+ import type { ViewerConfigInitial } from "./ViewerConfigInitial.js";
4
4
  /**
5
5
  * The parse target of a whole-element config in
6
- * [`PerspectiveViewerElement::restore`]. Mirrors [`WorkspaceConfig`],
7
- * but `panels` entries are full [`ViewerConfigUpdate`]s so a stray per-panel
8
- * `settings` can be detected (warned, then ignored — `create_panel` strips
9
- * it).
6
+ * [`PerspectiveViewerElement::restoreWorkspace`]. Mirrors
7
+ * [`WorkspaceConfig`], but `panels` entries are [`ViewerConfigInitial`]s —
8
+ * every entry creates a NEW panel, so `table` is required by type (a
9
+ * stray per-panel `settings` key is ignored; it is element-level state,
10
+ * carried by the top-level `active` field).
10
11
  */
11
12
  export type WorkspaceConfigUpdate = {
12
13
  active?: string;
13
14
  layout?: Layout;
14
15
  panels: {
15
- [key in string]?: ViewerConfigUpdate;
16
+ [key in string]?: ViewerConfigInitial;
16
17
  };
17
18
  /**
18
19
  * The element-level global (master/detail cross-) filters to re-apply as
@@ -104,22 +104,33 @@ import type {
104
104
 
105
105
  export type * from "../../src/ts/ts-rs/ViewerConfig.d.ts";
106
106
  export type * from "../../src/ts/ts-rs/ViewerConfigUpdate.d.ts";
107
+ export type * from "../../src/ts/ts-rs/ViewerConfigInitial.d.ts";
107
108
  export type * from "../../src/ts/ts-rs/PluginStaticConfig.d.ts";
108
109
  export type * from "../../src/ts/ts-rs/WorkspaceConfig.d.ts";
109
110
  export type * from "../../src/ts/ts-rs/WorkspaceConfigUpdate.d.ts";
110
111
  export type * from "../../src/ts/ts-rs/ExportMethod.d.ts";
111
112
  export type * from "../../src/ts/ts-rs/PanelOptions.d.ts";
113
+ export type * from "../../src/ts/ts-rs/RestoreOptions.d.ts";
112
114
  export type * from "../../src/ts/ts-rs/ClientOptions.d.ts";
113
115
  export type * from "../../src/ts/ts-rs/ExportOptions.d.ts";
114
116
  export type * from "../../src/ts/ts-rs/GetTableOptions.d.ts";
115
117
  export type * from "../../src/ts/ts-rs/GetClientOptions.d.ts";
118
+ export type * from "../../src/ts/ts-rs/CustomNumberFormatConfig.d.ts";
119
+ export type * from "../../src/ts/ts-rs/NumberFormatStyle.d.ts";
120
+ export type * from "../../src/ts/ts-rs/Notation.d.ts";
121
+ export type * from "../../src/ts/ts-rs/DatetimeFormatType.d.ts";
122
+ export type * from "../../src/ts/ts-rs/StringColorMode.d.ts";
123
+ export type * from "../../src/ts/ts-rs/DatetimeColorMode.d.ts";
124
+ export type * from "../../src/ts/ts-rs/FormatMode.d.ts";
116
125
  import type {GetTableOptions} from "../../src/ts/ts-rs/GetTableOptions.d.ts";
117
126
  import type {PanelOptions} from "../../src/ts/ts-rs/PanelOptions.d.ts";
127
+ import type {RestoreOptions} from "../../src/ts/ts-rs/RestoreOptions.d.ts";
118
128
  import type {ExportOptions} from "../../src/ts/ts-rs/ExportOptions.d.ts";
119
129
  import type {GetClientOptions} from "../../src/ts/ts-rs/GetClientOptions.d.ts";
120
130
  import type {ClientOptions} from "../../src/ts/ts-rs/ClientOptions.d.ts";
121
131
  import type {ViewerConfig} from "../../src/ts/ts-rs/ViewerConfig.d.ts";
122
132
  import type {ViewerConfigUpdate} from "../../src/ts/ts-rs/ViewerConfigUpdate.d.ts";
133
+ import type {ViewerConfigInitial} from "../../src/ts/ts-rs/ViewerConfigInitial.d.ts";
123
134
  import type {WorkspaceConfig} from "../../src/ts/ts-rs/WorkspaceConfig.d.ts";
124
135
  import type {WorkspaceConfigUpdate} from "../../src/ts/ts-rs/WorkspaceConfigUpdate.d.ts";
125
136
 
@@ -529,14 +540,98 @@ export class PerspectiveViewerElement {
529
540
  __get_model(): PerspectiveViewerElement;
530
541
  /**
531
542
  * Add a new, independent panel to this viewer's layout, rendering the
532
- * supplied [`ViewerConfigUpdate`] into it. The panel uses the default
533
- * [`perspective_client::Client`] (the first passed to [`Self::load`]) to
534
- * resolve its `table`. Returns the generated panel id.
543
+ * supplied [`ViewerConfigInitial`] into it. Unlike [`Self::restore`]'s
544
+ * update-shaped argument, a new panel has no prior state, so `table`
545
+ * is REQUIRED — a table-less call rejects before the layout is
546
+ * touched. The panel uses the default [`perspective_client::Client`]
547
+ * (the first passed to [`Self::load`]) to resolve its `table`. Returns
548
+ * the generated panel id.
549
+ *
550
+ * The element-level `settings` field does not exist on the argument
551
+ * type (it is shared across the element, not per-panel).
552
+ */
553
+ addPanel(config: ViewerConfigInitial): Promise<any>;
554
+ /**
555
+ * Configure the embedded LLM agent (see `prompt()`), replacing any prior
556
+ * configuration and conversation.
557
+ *
558
+ * The agent core is provider-agnostic: one OpenAI-chat-completions
559
+ * protocol over primitive connection fields. Exactly one of
560
+ * `config.url` or `config.engine` is required; the `providers` presets
561
+ * exported by this package are plain spreadable collections of these
562
+ * fields (`{...providers.anthropic, apiKey}`).
563
+ *
564
+ * - `config.url` - a full chat-completions endpoint URL (any
565
+ * OpenAI-compatible service: Anthropic/Gemini compatibility endpoints,
566
+ * LM Studio, Ollama, OpenRouter, a proxy...).
567
+ * - `config.engine` - an in-page engine object with an OpenAI-compatible
568
+ * `chat.completions.create(request)` method (e.g. WebLLM's `MLCEngine`);
569
+ * mutually exclusive with `url`.
570
+ * - `config.headers` - extra request headers, sent verbatim.
571
+ * - `config.apiKey` - sugar for the `Authorization: Bearer` header.
572
+ * - `config.model` - model id sent with each request; local servers and
573
+ * engines generally answer with whatever model is loaded.
574
+ * - `config.name` - cosmetic label for the chat badge (presets set this).
575
+ * - `config.systemPrompt` - extra system-prompt context appended to the
576
+ * agent's built-in instructions.
577
+ * - `config.maxTurns` - max model turns (tool-call rounds + the final
578
+ * answer) per `prompt()` call. Defaults to 16.
579
+ * - `config.docs` - the agent metadata bundle, which supplies the
580
+ * `search_docs` corpus and the rich tool parameter schemas: the packaged
581
+ * `dist/docs/perspective-docs.json` asset as a parsed object (`import
582
+ * docs from "…json" with { type: "json" }`), a `fetch()` `Response`, an
583
+ * `ArrayBuffer`, a JSON string, or a `Promise` of any of those — and/or
584
+ * an inline array of `{title?, text}` entries for host data definitions.
585
+ * Omitted, `search_docs` searches an empty corpus and the parameter
586
+ * schemas degrade to permissive objects.
587
+ * - `config.systemRole` - where the preamble (plus `systemPrompt`) is
588
+ * placed: `"system"` (default) or `"user"`. Some engines refuse a system
589
+ * message alongside `tools` because they substitute their own — WebLLM's
590
+ * Hermes function calling throws `CustomSystemPromptError` on ANY system
591
+ * message — and those need `"user"`, which folds the same text into the
592
+ * opening user turn.
593
+ * - `config.entitlements` - access grants limiting which tools the agent
594
+ * is offered (and may call): any of `"read_view"`, `"configure_view"`,
595
+ * `"manage_layout"`, `"read_docs"`, `"read_data"`. Omitted, all but
596
+ * `"read_data"` are granted; `["read_view", "read_docs"]` yields a
597
+ * read-only agent.
535
598
  *
536
- * Element-level config fields (`settings`, `theme`) in the argument are
537
- * ignored — those are shared across the element, not per-panel.
599
+ * # JavaScript Examples
600
+ *
601
+ * ```javascript
602
+ * import { providers } from "@perspective-dev/viewer";
603
+ *
604
+ * viewer.agentConfig({
605
+ * ...providers.anthropic,
606
+ * apiKey: "sk-ant-...",
607
+ * docs: fetch(
608
+ * "node_modules/@perspective-dev/viewer/dist/docs/perspective-docs.json",
609
+ * ),
610
+ * });
611
+ * ```
612
+ */
613
+ agentConfig(config: any): void;
614
+ /**
615
+ * Run one conversational turn of the embedded LLM agent (configured via
616
+ * `agentConfig()`), resolving with the agent's final text response after
617
+ * any tool calls have been applied to this element. Turns share a
618
+ * conversation history (and the chat sidebar's transcript) until
619
+ * `agentReset()`; a call made while a turn is already running rejects.
620
+ * Tool activity is emitted as `perspective-agent-tool` CustomEvents on
621
+ * this element.
622
+ *
623
+ * # JavaScript Examples
624
+ *
625
+ * ```javascript
626
+ * await viewer.agentPrompt("Show me sales by region as a bar chart");
627
+ * ```
628
+ */
629
+ agentPrompt(prompt: string): Promise<any>;
630
+ /**
631
+ * Clear the agent's conversation (history and chat transcript), keeping
632
+ * its configuration. Cancels any in-flight turn.
538
633
  */
539
- addPanel(update: ViewerConfigUpdate): Promise<any>;
634
+ agentReset(): Promise<any>;
540
635
  connectedCallback(): void;
541
636
  /**
542
637
  * Copy this viewer's `View` or `Table` data as CSV to the system
@@ -935,9 +1030,12 @@ export class PerspectiveViewerElement {
935
1030
  * optional `{panel}` selector.
936
1031
  *
937
1032
  * If `panel` names no existing panel, a NEW panel is created with that id
938
- * and the config restored into it (an upsert), equivalent to
939
- * [`Self::addPanel`] but with a caller-chosen id. As with a created panel,
1033
+ * and the config restored into it (an upsert). As with a created panel,
940
1034
  * the element-level `settings`/`theme` fields are ignored in that case.
1035
+ * Unlike [`Self::addPanel`], the argument is a PATCH, so a `table` is
1036
+ * optional: creating without one yields a DEFERRED panel that the next
1037
+ * [`Self::load`] binds. Such a panel renders but cannot be serialized —
1038
+ * [`Self::save`] rejects with "Panel has no `table`" until it is bound.
941
1039
  *
942
1040
  * On an empty element with a pending [`Self::load`] whose payload is not
943
1041
  * yet classified, the active-target form (no `panel`) instead claims and
@@ -956,7 +1054,15 @@ export class PerspectiveViewerElement {
956
1054
  *
957
1055
  * - `update` - The config to restore to, as returned by [`Self::save`] in
958
1056
  * either "json", "string" or "arraybuffer" format.
959
- * - `name` - The panel to target, or `None` for the active panel.
1057
+ * - `options.panel` - The panel to target, or the active panel when
1058
+ * omitted.
1059
+ * - `options.suppress_errors` - when `true`, a failed restore only rejects
1060
+ * the returned `Promise`; the error is NOT committed to the viewer's
1061
+ * visible error state and the session remains usable. The view config is
1062
+ * rolled back to its pre-call value, so a rejected patch cannot re-merge
1063
+ * into a later restore. Element-level state the call already applied
1064
+ * (theme, title, a plugin swap) is NOT undone — restore a known-good
1065
+ * config to recover those exactly.
960
1066
  *
961
1067
  * # JavaScript Examples
962
1068
  *
@@ -974,7 +1080,7 @@ export class PerspectiveViewerElement {
974
1080
  * await viewer.restore({group_by: ["State"]});
975
1081
  * ```
976
1082
  */
977
- restore(update: ViewerConfigUpdate, options?: PanelOptions | null): Promise<void>;
1083
+ restore(update: ViewerConfigUpdate, options?: RestoreOptions | null): Promise<void>;
978
1084
  /**
979
1085
  * Restore the ENTIRE element from a whole-element
980
1086
  * [`WorkspaceConfigUpdate`] (`{version, active?, layout, panels, ...}`) —
@@ -1655,6 +1761,9 @@ export interface InitOutput {
1655
1761
  readonly perspectivedebugpluginelement_update: (a: number, b: number) => number;
1656
1762
  readonly perspectiveviewerelement___get_model: (a: number) => number;
1657
1763
  readonly perspectiveviewerelement_addPanel: (a: number, b: number) => number;
1764
+ readonly perspectiveviewerelement_agentConfig: (a: number, b: number, c: number) => void;
1765
+ readonly perspectiveviewerelement_agentPrompt: (a: number, b: number, c: number) => number;
1766
+ readonly perspectiveviewerelement_agentReset: (a: number) => number;
1658
1767
  readonly perspectiveviewerelement_connectedCallback: (a: number, b: number) => void;
1659
1768
  readonly perspectiveviewerelement_copy: (a: number, b: number) => number;
1660
1769
  readonly perspectiveviewerelement_delete: (a: number) => number;
@@ -1791,21 +1900,21 @@ export interface InitOutput {
1791
1900
  readonly virtualdataslice_setStringCol: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
1792
1901
  readonly virtualserver_handleRequest: (a: number, b: number, c: number) => number;
1793
1902
  readonly virtualserver_new: (a: number, b: number) => void;
1794
- readonly __wasm_bindgen_func_elem_3667: (a: number, b: number) => void;
1795
- readonly __wasm_bindgen_func_elem_16364: (a: number, b: number) => void;
1796
- readonly __wasm_bindgen_func_elem_19409: (a: number, b: number) => void;
1797
- readonly __wasm_bindgen_func_elem_20067: (a: number, b: number) => void;
1798
- readonly __wasm_bindgen_func_elem_20096: (a: number, b: number) => void;
1799
- readonly __wasm_bindgen_func_elem_27549: (a: number, b: number, c: number, d: number) => void;
1800
- readonly __wasm_bindgen_func_elem_6430: (a: number, b: number, c: number) => void;
1801
- readonly __wasm_bindgen_func_elem_6431: (a: number, b: number, c: number) => void;
1802
- readonly __wasm_bindgen_func_elem_6432: (a: number, b: number, c: number) => void;
1803
- readonly __wasm_bindgen_func_elem_6428: (a: number, b: number, c: number) => void;
1804
- readonly __wasm_bindgen_func_elem_19529: (a: number, b: number, c: number) => void;
1805
- readonly __wasm_bindgen_func_elem_20072: (a: number, b: number, c: number) => void;
1806
- readonly __wasm_bindgen_func_elem_20113: (a: number, b: number, c: number) => void;
1807
- readonly __wasm_bindgen_func_elem_17084: (a: number, b: number) => number;
1808
- readonly __wasm_bindgen_func_elem_20071: (a: number, b: number) => void;
1903
+ readonly __wasm_bindgen_func_elem_17003: (a: number, b: number) => void;
1904
+ readonly __wasm_bindgen_func_elem_17713: (a: number, b: number) => void;
1905
+ readonly __wasm_bindgen_func_elem_18571: (a: number, b: number) => void;
1906
+ readonly __wasm_bindgen_func_elem_3989: (a: number, b: number) => void;
1907
+ readonly __wasm_bindgen_func_elem_23208: (a: number, b: number) => void;
1908
+ readonly __wasm_bindgen_func_elem_31328: (a: number, b: number, c: number, d: number) => void;
1909
+ readonly __wasm_bindgen_func_elem_17122: (a: number, b: number, c: number) => void;
1910
+ readonly __wasm_bindgen_func_elem_17718: (a: number, b: number, c: number) => void;
1911
+ readonly __wasm_bindgen_func_elem_6981: (a: number, b: number, c: number) => void;
1912
+ readonly __wasm_bindgen_func_elem_6982: (a: number, b: number, c: number) => void;
1913
+ readonly __wasm_bindgen_func_elem_6983: (a: number, b: number, c: number) => void;
1914
+ readonly __wasm_bindgen_func_elem_6979: (a: number, b: number, c: number) => void;
1915
+ readonly __wasm_bindgen_func_elem_23225: (a: number, b: number, c: number) => void;
1916
+ readonly __wasm_bindgen_func_elem_19569: (a: number, b: number) => number;
1917
+ readonly __wasm_bindgen_func_elem_17717: (a: number, b: number) => void;
1809
1918
  readonly __wbindgen_export: (a: number, b: number) => number;
1810
1919
  readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
1811
1920
  readonly __wbindgen_export3: (a: number) => void;