pivotkit-react 0.0.0-stage → 0.1.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.
- package/CHANGELOG.md +300 -0
- package/LICENSE +21 -0
- package/README.md +327 -2
- package/dist/chunks/chunk-C32TYSHG.js +441 -0
- package/dist/chunks/chunk-ILHFIV2P.js +784 -0
- package/dist/chunks/chunk-KKJO36W5.js +1833 -0
- package/dist/chunks/chunk-XYP47DJ3.js +123 -0
- package/dist/echarts.js +262 -0
- package/dist/index.js +3390 -0
- package/dist/labels.js +12 -0
- package/dist/menus.js +1085 -0
- package/dist/styles.css +2447 -0
- package/package.json +70 -4
- package/types/PivotReport.d.ts +20 -0
- package/types/all-labels.d.ts +5 -0
- package/types/chart-decorate.d.ts +16 -0
- package/types/chart-options.d.ts +23 -0
- package/types/chart-summary.d.ts +12 -0
- package/types/chart-tooltip.d.ts +38 -0
- package/types/chart-types.d.ts +152 -0
- package/types/chart.d.ts +39 -0
- package/types/chip-menus.d.ts +32 -0
- package/types/clear-input.d.ts +20 -0
- package/types/dnd-moves.d.ts +45 -0
- package/types/dnd.d.ts +101 -0
- package/types/dom.d.ts +52 -0
- package/types/drill-export.d.ts +42 -0
- package/types/drill-panel.d.ts +39 -0
- package/types/drill.d.ts +62 -0
- package/types/echarts.d.ts +4 -0
- package/types/export-run.d.ts +59 -0
- package/types/field-info.d.ts +34 -0
- package/types/fields.d.ts +32 -0
- package/types/files.d.ts +27 -0
- package/types/filter.d.ts +21 -0
- package/types/icons.d.ts +76 -0
- package/types/index.d.ts +536 -0
- package/types/info.d.ts +34 -0
- package/types/iso.d.ts +2 -0
- package/types/labels.d.ts +721 -0
- package/types/lazy-menus.d.ts +16 -0
- package/types/menu-labels.d.ts +255 -0
- package/types/menus.d.ts +7 -0
- package/types/names.d.ts +80 -0
- package/types/numbers.d.ts +13 -0
- package/types/overflow.d.ts +59 -0
- package/types/place.d.ts +43 -0
- package/types/popover.d.ts +89 -0
- package/types/rove.d.ts +20 -0
- package/types/section.d.ts +42 -0
- package/types/share.d.ts +123 -0
- package/types/skeleton.d.ts +9 -0
- package/types/storage.d.ts +24 -0
- package/types/table.d.ts +23 -0
- package/types/templates.d.ts +40 -0
- package/types/theme.d.ts +24 -0
- package/types/tip-list.d.ts +20 -0
- package/types/tips.d.ts +298 -0
- package/types/toasts.d.ts +26 -0
- package/types/toolbar-panels.d.ts +90 -0
- package/types/toolbar.d.ts +5 -0
- package/types/use-big-result.d.ts +29 -0
- package/types/use-export.d.ts +7 -0
- package/types/use-theme.d.ts +11 -0
- package/types/use-view-history.d.ts +34 -0
- package/types/version.d.ts +2 -0
- package/types/view-history.d.ts +89 -0
- package/types/view-ops.d.ts +344 -0
- package/types/view-store.d.ts +52 -0
- package/types/virtual.d.ts +44 -0
- package/types/zones.d.ts +42 -0
package/types/index.d.ts
ADDED
|
@@ -0,0 +1,536 @@
|
|
|
1
|
+
export type View = import("pivotkit-core").View;
|
|
2
|
+
export type ViewInput = {
|
|
3
|
+
[K in keyof View]?: View[K] extends Array<infer T> ? Array<T extends object ? Partial<T> : T> : View[K] extends object ? Partial<View[K]> : View[K];
|
|
4
|
+
};
|
|
5
|
+
export type UiLabels = import("./labels.js").UiLabels;
|
|
6
|
+
export type PartialLabels = import("./labels.js").PartialLabels;
|
|
7
|
+
export type Template = {
|
|
8
|
+
/**
|
|
9
|
+
* shown in the menu; default the view file's name (an entry without a name is left out)
|
|
10
|
+
*/
|
|
11
|
+
name?: string;
|
|
12
|
+
view?: ViewInput;
|
|
13
|
+
/**
|
|
14
|
+
* a view file ("pivotkit-view", its object or text)
|
|
15
|
+
* instead of `view`, read by pivotkit-core's fromViewFile
|
|
16
|
+
*/
|
|
17
|
+
file?: Record<string, unknown> | string;
|
|
18
|
+
/**
|
|
19
|
+
* the group: "Shared views" (for everyone) or "My views" (the
|
|
20
|
+
* user's own); default "user" for a deletable entry, else "shared"
|
|
21
|
+
*/
|
|
22
|
+
scope?: "shared" | "user";
|
|
23
|
+
/**
|
|
24
|
+
* shows a delete button when onDeleteTemplate is set (default false)
|
|
25
|
+
*/
|
|
26
|
+
deletable?: boolean;
|
|
27
|
+
};
|
|
28
|
+
export type TemplateScope = {
|
|
29
|
+
scope: "shared" | "user";
|
|
30
|
+
};
|
|
31
|
+
export type FieldDefaults = {
|
|
32
|
+
/**
|
|
33
|
+
* aggregator of a new value, when it fits the field's type ("average" for durations)
|
|
34
|
+
*/
|
|
35
|
+
agg?: string;
|
|
36
|
+
/**
|
|
37
|
+
* a format of pivotkit-core ("duration:h", "currency:EUR") for a new value,
|
|
38
|
+
* and for the field's own numbers in the drill-down unless `drillFormat` is set
|
|
39
|
+
*/
|
|
40
|
+
format?: string;
|
|
41
|
+
/**
|
|
42
|
+
* the format of the field's values in the drill-down: "text" shows an
|
|
43
|
+
* identifier as it is (40072, not 40,072), "date" a date without its time
|
|
44
|
+
*/
|
|
45
|
+
drillFormat?: string;
|
|
46
|
+
/**
|
|
47
|
+
* the field's own order of items on Rows or
|
|
48
|
+
* Columns ("Spring", "Summer", "Autumn", "Winter"): a field placed there is sorted in it, and its
|
|
49
|
+
* menu offers it as "Custom order"; items not listed come after, by label
|
|
50
|
+
*/
|
|
51
|
+
order?: Array<string | number | boolean | null>;
|
|
52
|
+
/**
|
|
53
|
+
* the name shown for the field (chips, headers, value names, exports,
|
|
54
|
+
* chart, drill-down); views and templates keep the field's own name. At most 120 characters
|
|
55
|
+
*/
|
|
56
|
+
label?: string;
|
|
57
|
+
/**
|
|
58
|
+
* plain text shown with an "i" next to the field, in its menu and on
|
|
59
|
+
* its headers; at most 1,000 characters, control characters become spaces
|
|
60
|
+
*/
|
|
61
|
+
description?: string;
|
|
62
|
+
/**
|
|
63
|
+
* an https link shown as "Learn more" with the description; other links are dropped
|
|
64
|
+
*/
|
|
65
|
+
href?: string;
|
|
66
|
+
/**
|
|
67
|
+
* the type the field's column is read as
|
|
68
|
+
* (pivotkit-core's encode `types`): numbers sent as text, dates as numbers
|
|
69
|
+
*/
|
|
70
|
+
type?: "string" | "number" | "date" | "boolean";
|
|
71
|
+
};
|
|
72
|
+
export type CellClick = {
|
|
73
|
+
/**
|
|
74
|
+
* key path of the row ([] is the grand total)
|
|
75
|
+
*/
|
|
76
|
+
row: any[];
|
|
77
|
+
/**
|
|
78
|
+
* key path of the column
|
|
79
|
+
*/
|
|
80
|
+
col: any[];
|
|
81
|
+
/**
|
|
82
|
+
* the raw value of the cell
|
|
83
|
+
*/
|
|
84
|
+
value: unknown;
|
|
85
|
+
valueIndex: number | undefined;
|
|
86
|
+
/**
|
|
87
|
+
* the value as shown
|
|
88
|
+
*/
|
|
89
|
+
text: string | undefined;
|
|
90
|
+
/**
|
|
91
|
+
* source rows behind the cell
|
|
92
|
+
*/
|
|
93
|
+
count: number;
|
|
94
|
+
/**
|
|
95
|
+
* the first `drillDownLimit` of them: the host's row objects (`data`) or
|
|
96
|
+
* rows rebuilt from `encoded`
|
|
97
|
+
*/
|
|
98
|
+
rows: object[];
|
|
99
|
+
};
|
|
100
|
+
export type ExportFile = {
|
|
101
|
+
/**
|
|
102
|
+
* "json": the view file (Views, "Download view"); "copy-table", "copy-json": Export → Copy table,
|
|
103
|
+
* Copy data as JSON; "drill-*": the drill-down panel's Export menu (Copy, Copy as JSON, Download
|
|
104
|
+
* CSV, Download Excel)
|
|
105
|
+
*/
|
|
106
|
+
kind: "xlsx" | "csv" | "png" | "json" | "copy-table" | "copy-json" | "drill-copy" | "drill-json" | "drill-csv" | "drill-xlsx";
|
|
107
|
+
/**
|
|
108
|
+
* with the extension ("pivot.xlsx"), made safe; for a copy the name it
|
|
109
|
+
* would have as a file ("pivot.tsv", "Central – Jul 2026.json")
|
|
110
|
+
*/
|
|
111
|
+
fileName: string;
|
|
112
|
+
blob: Blob;
|
|
113
|
+
/**
|
|
114
|
+
* a copy's text (tab-separated or JSON), the same as the blob's
|
|
115
|
+
*/
|
|
116
|
+
text?: string;
|
|
117
|
+
/**
|
|
118
|
+
* a drill-down export: the rows it holds (the
|
|
119
|
+
* panel's, at most `drillDownLimit`) and the rows behind the value
|
|
120
|
+
*/
|
|
121
|
+
rows?: {
|
|
122
|
+
shown: number;
|
|
123
|
+
count: number;
|
|
124
|
+
};
|
|
125
|
+
};
|
|
126
|
+
export type PivotReportProps = {
|
|
127
|
+
/**
|
|
128
|
+
* the rows; encoded once per array, or once per `dataKey`
|
|
129
|
+
*/
|
|
130
|
+
data?: object[];
|
|
131
|
+
/**
|
|
132
|
+
* identity of `data`: a new array with the same key is not encoded again
|
|
133
|
+
*/
|
|
134
|
+
dataKey?: string | number;
|
|
135
|
+
/**
|
|
136
|
+
* already encoded data, instead of `data`
|
|
137
|
+
*/
|
|
138
|
+
encoded?: import("pivotkit-core").Encoded;
|
|
139
|
+
/**
|
|
140
|
+
* controlled: the view to show; pass back what onViewChange gives
|
|
141
|
+
*/
|
|
142
|
+
view?: ViewInput;
|
|
143
|
+
/**
|
|
144
|
+
* uncontrolled: the start view; the report keeps the view itself
|
|
145
|
+
*/
|
|
146
|
+
defaultView?: ViewInput;
|
|
147
|
+
/**
|
|
148
|
+
* every change, normalized
|
|
149
|
+
*/
|
|
150
|
+
onViewChange?: (view: View) => void;
|
|
151
|
+
/**
|
|
152
|
+
* the entries of the Views menu, in two groups by `scope`
|
|
153
|
+
*/
|
|
154
|
+
templates?: Template[];
|
|
155
|
+
/**
|
|
156
|
+
* shows
|
|
157
|
+
* "Save" when set (`where.scope` is "user"); "saved" is shown when it returns or the promise it
|
|
158
|
+
* returns resolves, an error when it throws or rejects. It wins over `templateStore`
|
|
159
|
+
*/
|
|
160
|
+
onSaveTemplate?: (name: string, view: View, where: TemplateScope) => unknown;
|
|
161
|
+
/**
|
|
162
|
+
* deletes a template
|
|
163
|
+
* marked `deletable` (`where.scope`: its group); the entry goes when it returns (or its promise resolves)
|
|
164
|
+
*/
|
|
165
|
+
onDeleteTemplate?: (name: string, where: TemplateScope) => unknown;
|
|
166
|
+
/**
|
|
167
|
+
* with `canPublish`:
|
|
168
|
+
* "Publish as shared view" on each of the user's views; the host makes it a shared entry of
|
|
169
|
+
* `templates`; "published" is shown when it returns or its promise resolves
|
|
170
|
+
*/
|
|
171
|
+
onPublishTemplate?: (name: string, view: ViewInput) => unknown;
|
|
172
|
+
/**
|
|
173
|
+
* the user may publish views for everyone (an admin); default false
|
|
174
|
+
*/
|
|
175
|
+
canPublish?: boolean;
|
|
176
|
+
/**
|
|
177
|
+
* "browser": the user's own views are kept in this browser's
|
|
178
|
+
* localStorage under `storageKey` (only this browser and device, lost when the site's data is
|
|
179
|
+
* cleared), when `onSaveTemplate` is not set
|
|
180
|
+
*/
|
|
181
|
+
templateStore?: "browser";
|
|
182
|
+
/**
|
|
183
|
+
* per field name: aggregator and format of a new
|
|
184
|
+
* value, custom order, display name, description, column type; pivotkit-core's fieldDefaultsFromSchema
|
|
185
|
+
* builds it from a JSON Schema or OpenAPI document
|
|
186
|
+
*/
|
|
187
|
+
fieldDefaults?: Record<string, FieldDefaults>;
|
|
188
|
+
onCellClick?: (cell: CellClick) => void;
|
|
189
|
+
/**
|
|
190
|
+
* the panel with the rows behind a clicked value (default true)
|
|
191
|
+
*/
|
|
192
|
+
drillDown?: boolean;
|
|
193
|
+
/**
|
|
194
|
+
* rows passed to the panel and onCellClick (default 1000)
|
|
195
|
+
*/
|
|
196
|
+
drillDownLimit?: number;
|
|
197
|
+
/**
|
|
198
|
+
* numbers, dates, sorting and the language of the labels (default "en-US")
|
|
199
|
+
*/
|
|
200
|
+
locale?: string;
|
|
201
|
+
/**
|
|
202
|
+
* the zone `data` is encoded in (default "UTC"); see pivotkit-core
|
|
203
|
+
*/
|
|
204
|
+
timeZone?: string;
|
|
205
|
+
/**
|
|
206
|
+
* partial labels merged over the locale's language (en, de)
|
|
207
|
+
*/
|
|
208
|
+
labels?: PartialLabels;
|
|
209
|
+
/**
|
|
210
|
+
* "auto" follows the nearest data-theme above the report, then the system
|
|
211
|
+
*/
|
|
212
|
+
theme?: "auto" | "light" | "dark";
|
|
213
|
+
/**
|
|
214
|
+
* the report's height (default 640 px). Without it the report
|
|
215
|
+
* grows past 640 px when its toolbar, zones and tips leave the result less than its least height
|
|
216
|
+
* (the page scrolls); with it the report stays inside that height and its result scrolls
|
|
217
|
+
*/
|
|
218
|
+
height?: number | string;
|
|
219
|
+
/**
|
|
220
|
+
* whether the report grows past its height to keep the result's
|
|
221
|
+
* least height: "on" by default without `height`, "off" with it
|
|
222
|
+
*/
|
|
223
|
+
grow?: "on" | "off";
|
|
224
|
+
limits?: Partial<import("pivotkit-core").Limits>;
|
|
225
|
+
/**
|
|
226
|
+
* the name of the report's region landmark (default the labels' `report`);
|
|
227
|
+
* several reports on one page each need their own
|
|
228
|
+
*/
|
|
229
|
+
label?: string;
|
|
230
|
+
className?: string;
|
|
231
|
+
/**
|
|
232
|
+
* name of exported files without extension (default "pivot"); made safe
|
|
233
|
+
*/
|
|
234
|
+
fileName?: string;
|
|
235
|
+
/**
|
|
236
|
+
* every exported file before its download, and
|
|
237
|
+
* every copy before it goes on the clipboard; returning false skips the download or the copy (the
|
|
238
|
+
* host keeps the file or the text, for example to upload it)
|
|
239
|
+
*/
|
|
240
|
+
onExport?: (file: ExportFile) => unknown;
|
|
241
|
+
/**
|
|
242
|
+
* the tips above the result: "on" (default), "off"
|
|
243
|
+
* (none, and no switch in Options), or the ids of the tips allowed (an array, or a comma-separated text)
|
|
244
|
+
*/
|
|
245
|
+
tips?: "on" | "off" | string | string[];
|
|
246
|
+
/**
|
|
247
|
+
* remembers dismissed tips in localStorage under this key (one per
|
|
248
|
+
* report on a page); without it they are remembered until the page is loaded again. The browser
|
|
249
|
+
* store of `templateStore` keeps the user's views under it too
|
|
250
|
+
*/
|
|
251
|
+
storageKey?: string;
|
|
252
|
+
/**
|
|
253
|
+
* dismissed tip ids from the host's own storage ("*": all tips off,
|
|
254
|
+
* "-explanations": "Show explanations" of Options → Help off;
|
|
255
|
+
* "open:<section>" and "closed:<section>": a menu section the user opened or folded)
|
|
256
|
+
*/
|
|
257
|
+
dismissedTips?: string[];
|
|
258
|
+
/**
|
|
259
|
+
* every dismissal, "Show tips" and
|
|
260
|
+
* "Show dismissed tips again", with the whole list, for a host that stores it itself
|
|
261
|
+
*/
|
|
262
|
+
onTipDismiss?: (change: TipDismiss) => void;
|
|
263
|
+
/**
|
|
264
|
+
* plain JSON merged over the ECharts option the
|
|
265
|
+
* report builds (objects key by key; an object given for a list such as `series` into every entry);
|
|
266
|
+
* it wins over the view's chart settings. Functions, values that are not plain JSON and the
|
|
267
|
+
* options that are markup or addresses (a string `formatter`, `rich`, `link`, `image`) are left out
|
|
268
|
+
* with a console warning
|
|
269
|
+
*/
|
|
270
|
+
chartOptions?: Record<string, unknown>;
|
|
271
|
+
/**
|
|
272
|
+
* "Copy link" in the Views menu and opening a shared
|
|
273
|
+
* link: `true` links to the page's own address without its query, a string is the base URL as it is; the view travels in the
|
|
274
|
+
* URL fragment (`#pivot=`, `#pivot-<storageKey>=` with a storageKey). Off by default
|
|
275
|
+
*/
|
|
276
|
+
shareLink?: boolean | string;
|
|
277
|
+
/**
|
|
278
|
+
* "session": the view is kept in sessionStorage for this tab
|
|
279
|
+
* (per `storageKey`) and comes back when the page is loaded again
|
|
280
|
+
*/
|
|
281
|
+
persistView?: "session";
|
|
282
|
+
/**
|
|
283
|
+
* the "i" of the field descriptions: "on" or "off" decides it,
|
|
284
|
+
* whatever the user's "Show explanations" in Options → Help (on by default, remembered like the
|
|
285
|
+
* tips) says; without it that switch decides. Screen readers keep the descriptions either way
|
|
286
|
+
*/
|
|
287
|
+
fieldInfo?: "on" | "off";
|
|
288
|
+
/**
|
|
289
|
+
* the "i" next to the zone titles that explains each zone, as `fieldInfo`
|
|
290
|
+
*/
|
|
291
|
+
zoneInfo?: "on" | "off";
|
|
292
|
+
/**
|
|
293
|
+
* the "i" next to the settings that need explaining (totals,
|
|
294
|
+
* "Show as", "Along", the export formats, chart labels), as `fieldInfo`. Options shows "Show
|
|
295
|
+
* explanations" while one of the three is left to the user
|
|
296
|
+
*/
|
|
297
|
+
settingInfo?: "on" | "off";
|
|
298
|
+
/**
|
|
299
|
+
* the data the report shows: its id and name go into the view files
|
|
300
|
+
* and links it shares, and a view made for another source asks before it is loaded
|
|
301
|
+
*/
|
|
302
|
+
source?: ViewSource;
|
|
303
|
+
/**
|
|
304
|
+
* the other data the host can show: a view made for one of them
|
|
305
|
+
* offers "Switch to <name> and load" (with `onSourceSwitch`)
|
|
306
|
+
*/
|
|
307
|
+
sources?: ViewSource[];
|
|
308
|
+
/**
|
|
309
|
+
* the `$schema` of the view files the report writes: by default
|
|
310
|
+
* https://pivotkit.eize.dev/schema/view-file-1.json, a host's own copy of the schema (it ships in
|
|
311
|
+
* pivotkit-core as "pivotkit-core/schema/view-file-1.json"), or null or "" to leave it out; loading a
|
|
312
|
+
* view never depends on it
|
|
313
|
+
*/
|
|
314
|
+
schemaUrl?: string | null;
|
|
315
|
+
/**
|
|
316
|
+
* the user chose to switch to the data a
|
|
317
|
+
* view was made for and load it there: the host shows that data and the view (as its start view)
|
|
318
|
+
*/
|
|
319
|
+
onSourceSwitch?: (request: SourceSwitch) => void;
|
|
320
|
+
/**
|
|
321
|
+
* the field list of a wide or medium report open or
|
|
322
|
+
* collapsed to a rail; without it the user's choice («, remembered with the tips per storageKey)
|
|
323
|
+
* decides. With it the user can still change it until the page is loaded again
|
|
324
|
+
*/
|
|
325
|
+
fieldList?: "open" | "collapsed";
|
|
326
|
+
/**
|
|
327
|
+
* the host is loading the data: the report shows its skeleton (before
|
|
328
|
+
* the first data) or covers its result (later loads)
|
|
329
|
+
*/
|
|
330
|
+
loading?: boolean;
|
|
331
|
+
};
|
|
332
|
+
export type ViewSource = {
|
|
333
|
+
/**
|
|
334
|
+
* stable, as the host names the data ("sales", a table's or an endpoint's name)
|
|
335
|
+
*/
|
|
336
|
+
id: string;
|
|
337
|
+
/**
|
|
338
|
+
* shown to people ("Sales 2026")
|
|
339
|
+
*/
|
|
340
|
+
name?: string;
|
|
341
|
+
};
|
|
342
|
+
export type SourceSwitch = {
|
|
343
|
+
/**
|
|
344
|
+
* the data to switch to (an entry of `sources`)
|
|
345
|
+
*/
|
|
346
|
+
source: ViewSource;
|
|
347
|
+
/**
|
|
348
|
+
* the view as the file has it, not normalized (it is made for
|
|
349
|
+
* that data): pass it as the start view of the report on it
|
|
350
|
+
*/
|
|
351
|
+
view: Record<string, unknown>;
|
|
352
|
+
/**
|
|
353
|
+
* the view's name in the file
|
|
354
|
+
*/
|
|
355
|
+
name?: string;
|
|
356
|
+
};
|
|
357
|
+
export type TipDismiss = {
|
|
358
|
+
/**
|
|
359
|
+
* the tip dismissed, "*" when every tip was switched off, null when tips came back
|
|
360
|
+
*/
|
|
361
|
+
id: string | null;
|
|
362
|
+
/**
|
|
363
|
+
* every dismissed id now, to pass back as `dismissedTips`
|
|
364
|
+
*/
|
|
365
|
+
dismissed: string[];
|
|
366
|
+
};
|
|
367
|
+
/**
|
|
368
|
+
* A view of pivotkit-core: what the report shows, as JSON. Hosts store and pass it; a partial view is
|
|
369
|
+
* filled with defaults, anything unknown is dropped (pivotkit-core's normalize()).
|
|
370
|
+
* @typedef {import("pivotkit-core").View} View
|
|
371
|
+
* @typedef {{ [K in keyof View]?: View[K] extends Array<infer T> ? Array<T extends object ? Partial<T> : T> : View[K] extends object ? Partial<View[K]> : View[K] }} ViewInput
|
|
372
|
+
* @typedef {import("./labels.js").UiLabels} UiLabels
|
|
373
|
+
* @typedef {import("./labels.js").PartialLabels} PartialLabels
|
|
374
|
+
*/
|
|
375
|
+
/**
|
|
376
|
+
* @typedef {object} Template an entry of the Views menu: a view, or a view file
|
|
377
|
+
* @property {string} [name] shown in the menu; default the view file's name (an entry without a name is left out)
|
|
378
|
+
* @property {ViewInput} [view]
|
|
379
|
+
* @property {Record<string, unknown> | string} [file] a view file ("pivotkit-view", its object or text)
|
|
380
|
+
* instead of `view`, read by pivotkit-core's fromViewFile
|
|
381
|
+
* @property {"shared" | "user"} [scope] the group: "Shared views" (for everyone) or "My views" (the
|
|
382
|
+
* user's own); default "user" for a deletable entry, else "shared"
|
|
383
|
+
* @property {boolean} [deletable] shows a delete button when onDeleteTemplate is set (default false)
|
|
384
|
+
*/
|
|
385
|
+
/**
|
|
386
|
+
* @typedef {object} TemplateScope where a template is or goes
|
|
387
|
+
* @property {"shared" | "user"} scope
|
|
388
|
+
*/
|
|
389
|
+
/**
|
|
390
|
+
* @typedef {object} FieldDefaults the host's settings for a field
|
|
391
|
+
* @property {string} [agg] aggregator of a new value, when it fits the field's type ("average" for durations)
|
|
392
|
+
* @property {string} [format] a format of pivotkit-core ("duration:h", "currency:EUR") for a new value,
|
|
393
|
+
* and for the field's own numbers in the drill-down unless `drillFormat` is set
|
|
394
|
+
* @property {string} [drillFormat] the format of the field's values in the drill-down: "text" shows an
|
|
395
|
+
* identifier as it is (40072, not 40,072), "date" a date without its time
|
|
396
|
+
* @property {Array<string | number | boolean | null>} [order] the field's own order of items on Rows or
|
|
397
|
+
* Columns ("Spring", "Summer", "Autumn", "Winter"): a field placed there is sorted in it, and its
|
|
398
|
+
* menu offers it as "Custom order"; items not listed come after, by label
|
|
399
|
+
* @property {string} [label] the name shown for the field (chips, headers, value names, exports,
|
|
400
|
+
* chart, drill-down); views and templates keep the field's own name. At most 120 characters
|
|
401
|
+
* @property {string} [description] plain text shown with an "i" next to the field, in its menu and on
|
|
402
|
+
* its headers; at most 1,000 characters, control characters become spaces
|
|
403
|
+
* @property {string} [href] an https link shown as "Learn more" with the description; other links are dropped
|
|
404
|
+
* @property {"string" | "number" | "date" | "boolean"} [type] the type the field's column is read as
|
|
405
|
+
* (pivotkit-core's encode `types`): numbers sent as text, dates as numbers
|
|
406
|
+
*/
|
|
407
|
+
/**
|
|
408
|
+
* @typedef {object} CellClick
|
|
409
|
+
* @property {any[]} row key path of the row ([] is the grand total)
|
|
410
|
+
* @property {any[]} col key path of the column
|
|
411
|
+
* @property {unknown} value the raw value of the cell
|
|
412
|
+
* @property {number | undefined} valueIndex
|
|
413
|
+
* @property {string | undefined} text the value as shown
|
|
414
|
+
* @property {number} count source rows behind the cell
|
|
415
|
+
* @property {object[]} rows the first `drillDownLimit` of them: the host's row objects (`data`) or
|
|
416
|
+
* rows rebuilt from `encoded`
|
|
417
|
+
*/
|
|
418
|
+
/**
|
|
419
|
+
* @typedef {object} ExportFile a file the report made, before it is downloaded, or a text before it
|
|
420
|
+
* goes on the clipboard
|
|
421
|
+
* @property {"xlsx" | "csv" | "png" | "json" | "copy-table" | "copy-json" | "drill-copy" | "drill-json" | "drill-csv" | "drill-xlsx"} kind
|
|
422
|
+
* "json": the view file (Views, "Download view"); "copy-table", "copy-json": Export → Copy table,
|
|
423
|
+
* Copy data as JSON; "drill-*": the drill-down panel's Export menu (Copy, Copy as JSON, Download
|
|
424
|
+
* CSV, Download Excel)
|
|
425
|
+
* @property {string} fileName with the extension ("pivot.xlsx"), made safe; for a copy the name it
|
|
426
|
+
* would have as a file ("pivot.tsv", "Central – Jul 2026.json")
|
|
427
|
+
* @property {Blob} blob
|
|
428
|
+
* @property {string} [text] a copy's text (tab-separated or JSON), the same as the blob's
|
|
429
|
+
* @property {{ shown: number, count: number }} [rows] a drill-down export: the rows it holds (the
|
|
430
|
+
* panel's, at most `drillDownLimit`) and the rows behind the value
|
|
431
|
+
*/
|
|
432
|
+
/**
|
|
433
|
+
* @typedef {object} PivotReportProps
|
|
434
|
+
* @property {object[]} [data] the rows; encoded once per array, or once per `dataKey`
|
|
435
|
+
* @property {string | number} [dataKey] identity of `data`: a new array with the same key is not encoded again
|
|
436
|
+
* @property {import("pivotkit-core").Encoded} [encoded] already encoded data, instead of `data`
|
|
437
|
+
* @property {ViewInput} [view] controlled: the view to show; pass back what onViewChange gives
|
|
438
|
+
* @property {ViewInput} [defaultView] uncontrolled: the start view; the report keeps the view itself
|
|
439
|
+
* @property {(view: View) => void} [onViewChange] every change, normalized
|
|
440
|
+
* @property {Template[]} [templates] the entries of the Views menu, in two groups by `scope`
|
|
441
|
+
* @property {(name: string, view: View, where: TemplateScope) => unknown} [onSaveTemplate] shows
|
|
442
|
+
* "Save" when set (`where.scope` is "user"); "saved" is shown when it returns or the promise it
|
|
443
|
+
* returns resolves, an error when it throws or rejects. It wins over `templateStore`
|
|
444
|
+
* @property {(name: string, where: TemplateScope) => unknown} [onDeleteTemplate] deletes a template
|
|
445
|
+
* marked `deletable` (`where.scope`: its group); the entry goes when it returns (or its promise resolves)
|
|
446
|
+
* @property {(name: string, view: ViewInput) => unknown} [onPublishTemplate] with `canPublish`:
|
|
447
|
+
* "Publish as shared view" on each of the user's views; the host makes it a shared entry of
|
|
448
|
+
* `templates`; "published" is shown when it returns or its promise resolves
|
|
449
|
+
* @property {boolean} [canPublish] the user may publish views for everyone (an admin); default false
|
|
450
|
+
* @property {"browser"} [templateStore] "browser": the user's own views are kept in this browser's
|
|
451
|
+
* localStorage under `storageKey` (only this browser and device, lost when the site's data is
|
|
452
|
+
* cleared), when `onSaveTemplate` is not set
|
|
453
|
+
* @property {Record<string, FieldDefaults>} [fieldDefaults] per field name: aggregator and format of a new
|
|
454
|
+
* value, custom order, display name, description, column type; pivotkit-core's fieldDefaultsFromSchema
|
|
455
|
+
* builds it from a JSON Schema or OpenAPI document
|
|
456
|
+
* @property {(cell: CellClick) => void} [onCellClick]
|
|
457
|
+
* @property {boolean} [drillDown] the panel with the rows behind a clicked value (default true)
|
|
458
|
+
* @property {number} [drillDownLimit] rows passed to the panel and onCellClick (default 1000)
|
|
459
|
+
* @property {string} [locale] numbers, dates, sorting and the language of the labels (default "en-US")
|
|
460
|
+
* @property {string} [timeZone] the zone `data` is encoded in (default "UTC"); see pivotkit-core
|
|
461
|
+
* @property {PartialLabels} [labels] partial labels merged over the locale's language (en, de)
|
|
462
|
+
* @property {"auto" | "light" | "dark"} [theme] "auto" follows the nearest data-theme above the report, then the system
|
|
463
|
+
* @property {number | string} [height] the report's height (default 640 px). Without it the report
|
|
464
|
+
* grows past 640 px when its toolbar, zones and tips leave the result less than its least height
|
|
465
|
+
* (the page scrolls); with it the report stays inside that height and its result scrolls
|
|
466
|
+
* @property {"on" | "off"} [grow] whether the report grows past its height to keep the result's
|
|
467
|
+
* least height: "on" by default without `height`, "off" with it
|
|
468
|
+
* @property {Partial<import("pivotkit-core").Limits>} [limits]
|
|
469
|
+
* @property {string} [label] the name of the report's region landmark (default the labels' `report`);
|
|
470
|
+
* several reports on one page each need their own
|
|
471
|
+
* @property {string} [className]
|
|
472
|
+
* @property {string} [fileName] name of exported files without extension (default "pivot"); made safe
|
|
473
|
+
* @property {(file: ExportFile) => unknown} [onExport] every exported file before its download, and
|
|
474
|
+
* every copy before it goes on the clipboard; returning false skips the download or the copy (the
|
|
475
|
+
* host keeps the file or the text, for example to upload it)
|
|
476
|
+
* @property {"on" | "off" | string | string[]} [tips] the tips above the result: "on" (default), "off"
|
|
477
|
+
* (none, and no switch in Options), or the ids of the tips allowed (an array, or a comma-separated text)
|
|
478
|
+
* @property {string} [storageKey] remembers dismissed tips in localStorage under this key (one per
|
|
479
|
+
* report on a page); without it they are remembered until the page is loaded again. The browser
|
|
480
|
+
* store of `templateStore` keeps the user's views under it too
|
|
481
|
+
* @property {string[]} [dismissedTips] dismissed tip ids from the host's own storage ("*": all tips off,
|
|
482
|
+
* "-explanations": "Show explanations" of Options → Help off;
|
|
483
|
+
* "open:<section>" and "closed:<section>": a menu section the user opened or folded)
|
|
484
|
+
* @property {(change: TipDismiss) => void} [onTipDismiss] every dismissal, "Show tips" and
|
|
485
|
+
* "Show dismissed tips again", with the whole list, for a host that stores it itself
|
|
486
|
+
* @property {Record<string, unknown>} [chartOptions] plain JSON merged over the ECharts option the
|
|
487
|
+
* report builds (objects key by key; an object given for a list such as `series` into every entry);
|
|
488
|
+
* it wins over the view's chart settings. Functions, values that are not plain JSON and the
|
|
489
|
+
* options that are markup or addresses (a string `formatter`, `rich`, `link`, `image`) are left out
|
|
490
|
+
* with a console warning
|
|
491
|
+
* @property {boolean | string} [shareLink] "Copy link" in the Views menu and opening a shared
|
|
492
|
+
* link: `true` links to the page's own address without its query, a string is the base URL as it is; the view travels in the
|
|
493
|
+
* URL fragment (`#pivot=`, `#pivot-<storageKey>=` with a storageKey). Off by default
|
|
494
|
+
* @property {"session"} [persistView] "session": the view is kept in sessionStorage for this tab
|
|
495
|
+
* (per `storageKey`) and comes back when the page is loaded again
|
|
496
|
+
* @property {"on" | "off"} [fieldInfo] the "i" of the field descriptions: "on" or "off" decides it,
|
|
497
|
+
* whatever the user's "Show explanations" in Options → Help (on by default, remembered like the
|
|
498
|
+
* tips) says; without it that switch decides. Screen readers keep the descriptions either way
|
|
499
|
+
* @property {"on" | "off"} [zoneInfo] the "i" next to the zone titles that explains each zone, as `fieldInfo`
|
|
500
|
+
* @property {"on" | "off"} [settingInfo] the "i" next to the settings that need explaining (totals,
|
|
501
|
+
* "Show as", "Along", the export formats, chart labels), as `fieldInfo`. Options shows "Show
|
|
502
|
+
* explanations" while one of the three is left to the user
|
|
503
|
+
* @property {ViewSource} [source] the data the report shows: its id and name go into the view files
|
|
504
|
+
* and links it shares, and a view made for another source asks before it is loaded
|
|
505
|
+
* @property {ViewSource[]} [sources] the other data the host can show: a view made for one of them
|
|
506
|
+
* offers "Switch to <name> and load" (with `onSourceSwitch`)
|
|
507
|
+
* @property {string | null} [schemaUrl] the `$schema` of the view files the report writes: by default
|
|
508
|
+
* https://pivotkit.eize.dev/schema/view-file-1.json, a host's own copy of the schema (it ships in
|
|
509
|
+
* pivotkit-core as "pivotkit-core/schema/view-file-1.json"), or null or "" to leave it out; loading a
|
|
510
|
+
* view never depends on it
|
|
511
|
+
* @property {(request: SourceSwitch) => void} [onSourceSwitch] the user chose to switch to the data a
|
|
512
|
+
* view was made for and load it there: the host shows that data and the view (as its start view)
|
|
513
|
+
* @property {"open" | "collapsed"} [fieldList] the field list of a wide or medium report open or
|
|
514
|
+
* collapsed to a rail; without it the user's choice («, remembered with the tips per storageKey)
|
|
515
|
+
* decides. With it the user can still change it until the page is loaded again
|
|
516
|
+
* @property {boolean} [loading] the host is loading the data: the report shows its skeleton (before
|
|
517
|
+
* the first data) or covers its result (later loads)
|
|
518
|
+
*/
|
|
519
|
+
/**
|
|
520
|
+
* @typedef {object} ViewSource the data a view is made for
|
|
521
|
+
* @property {string} id stable, as the host names the data ("sales", a table's or an endpoint's name)
|
|
522
|
+
* @property {string} [name] shown to people ("Sales 2026")
|
|
523
|
+
*/
|
|
524
|
+
/**
|
|
525
|
+
* @typedef {object} SourceSwitch
|
|
526
|
+
* @property {ViewSource} source the data to switch to (an entry of `sources`)
|
|
527
|
+
* @property {Record<string, unknown>} view the view as the file has it, not normalized (it is made for
|
|
528
|
+
* that data): pass it as the start view of the report on it
|
|
529
|
+
* @property {string} [name] the view's name in the file
|
|
530
|
+
*/
|
|
531
|
+
/**
|
|
532
|
+
* @typedef {object} TipDismiss
|
|
533
|
+
* @property {string | null} id the tip dismissed, "*" when every tip was switched off, null when tips came back
|
|
534
|
+
* @property {string[]} dismissed every dismissed id now, to pass back as `dismissedTips`
|
|
535
|
+
*/
|
|
536
|
+
export { PivotReport } from "./PivotReport.jsx";
|
package/types/info.d.ts
ADDED
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
import React from "react";
|
|
2
|
+
/**
|
|
3
|
+
* The description and its link.
|
|
4
|
+
* @param {{ info: { description: string, href?: string }, labels: import("./labels.js").UiLabels, link?: boolean, className?: string }} props
|
|
5
|
+
*/
|
|
6
|
+
export declare function FieldDescription({ info, labels, link, className }: {
|
|
7
|
+
info: {
|
|
8
|
+
description: string;
|
|
9
|
+
href?: string;
|
|
10
|
+
};
|
|
11
|
+
labels: import("./labels.js").UiLabels;
|
|
12
|
+
link?: boolean;
|
|
13
|
+
className?: string;
|
|
14
|
+
}): React.JSX.Element;
|
|
15
|
+
/**
|
|
16
|
+
* @param {{ info: { description: string, href?: string }, name: string, labels: import("./labels.js").UiLabels, className?: string, testId?: string, label?: string,
|
|
17
|
+
* tabIndex?: number, slot?: string }} props
|
|
18
|
+
* `name`: the field's display name, for the button's name; `label` names the button instead
|
|
19
|
+
* ("About Row subtotals" for a setting); `tabIndex`: -1 where a list moves the focus itself, `slot`
|
|
20
|
+
* its place there (the field list, rove.js)
|
|
21
|
+
*/
|
|
22
|
+
export declare function InfoButton({ info, name, labels, className, testId, label: named, tabIndex, slot }: {
|
|
23
|
+
info: {
|
|
24
|
+
description: string;
|
|
25
|
+
href?: string;
|
|
26
|
+
};
|
|
27
|
+
name: string;
|
|
28
|
+
labels: import("./labels.js").UiLabels;
|
|
29
|
+
className?: string;
|
|
30
|
+
testId?: string;
|
|
31
|
+
label?: string;
|
|
32
|
+
tabIndex?: number;
|
|
33
|
+
slot?: string;
|
|
34
|
+
}): React.JSX.Element;
|
package/types/iso.d.ts
ADDED