pivotkit-react 0.0.0-stage → 0.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 (89) hide show
  1. package/CHANGELOG.md +442 -0
  2. package/LICENSE +21 -0
  3. package/README.md +77 -2
  4. package/dist/chunks/chunk-53ZMK4BH.js +177 -0
  5. package/dist/chunks/chunk-F6MVUAQD.js +741 -0
  6. package/dist/chunks/chunk-LQCWFJBS.js +310 -0
  7. package/dist/chunks/chunk-OYY4BKIL.js +93 -0
  8. package/dist/chunks/chunk-QBD4FOBB.js +254 -0
  9. package/dist/chunks/chunk-X7H7BAVT.js +1752 -0
  10. package/dist/chunks/unused-texts-YTNJCFFC.js +10 -0
  11. package/dist/chunks/unused-texts-de-SGOHV4N7.js +6 -0
  12. package/dist/echarts.js +347 -0
  13. package/dist/index.js +3482 -0
  14. package/dist/labels.js +21 -0
  15. package/dist/menu-texts-de.js +6 -0
  16. package/dist/menus.js +1681 -0
  17. package/dist/styles.css +2529 -0
  18. package/package.json +70 -4
  19. package/types/PivotReport.d.ts +20 -0
  20. package/types/all-labels.d.ts +5 -0
  21. package/types/chart-decorate.d.ts +16 -0
  22. package/types/chart-layout.d.ts +111 -0
  23. package/types/chart-options.d.ts +23 -0
  24. package/types/chart-summary.d.ts +12 -0
  25. package/types/chart-tooltip.d.ts +38 -0
  26. package/types/chart-types.d.ts +61 -0
  27. package/types/chart.d.ts +39 -0
  28. package/types/chip-menus.d.ts +32 -0
  29. package/types/clear-input.d.ts +20 -0
  30. package/types/dnd-moves.d.ts +45 -0
  31. package/types/dnd.d.ts +101 -0
  32. package/types/dom.d.ts +52 -0
  33. package/types/drill-export.d.ts +42 -0
  34. package/types/drill-panel.d.ts +22 -0
  35. package/types/drill-table.d.ts +71 -0
  36. package/types/drill.d.ts +26 -0
  37. package/types/echarts.d.ts +4 -0
  38. package/types/export-run.d.ts +59 -0
  39. package/types/field-info.d.ts +34 -0
  40. package/types/fields.d.ts +32 -0
  41. package/types/files.d.ts +27 -0
  42. package/types/filter.d.ts +21 -0
  43. package/types/help.d.ts +21 -0
  44. package/types/icons.d.ts +80 -0
  45. package/types/index.d.ts +536 -0
  46. package/types/info.d.ts +34 -0
  47. package/types/iso.d.ts +2 -0
  48. package/types/labels.d.ts +663 -0
  49. package/types/lazy-menus.d.ts +28 -0
  50. package/types/menu-labels-de.d.ts +2 -0
  51. package/types/menu-labels.d.ts +317 -0
  52. package/types/menu-ops.d.ts +145 -0
  53. package/types/menu-texts.d.ts +2 -0
  54. package/types/menus.d.ts +7 -0
  55. package/types/names.d.ts +80 -0
  56. package/types/numbers.d.ts +13 -0
  57. package/types/overflow.d.ts +62 -0
  58. package/types/place.d.ts +43 -0
  59. package/types/popover.d.ts +93 -0
  60. package/types/rove.d.ts +20 -0
  61. package/types/section.d.ts +25 -0
  62. package/types/sections.d.ts +2 -0
  63. package/types/share-actions.d.ts +99 -0
  64. package/types/share.d.ts +114 -0
  65. package/types/skeleton.d.ts +9 -0
  66. package/types/storage.d.ts +24 -0
  67. package/types/table.d.ts +29 -0
  68. package/types/templates.d.ts +46 -0
  69. package/types/theme.d.ts +24 -0
  70. package/types/tip-list.d.ts +20 -0
  71. package/types/tips.d.ts +300 -0
  72. package/types/toasts.d.ts +26 -0
  73. package/types/toolbar-panels.d.ts +93 -0
  74. package/types/toolbar.d.ts +5 -0
  75. package/types/unused-load.d.ts +23 -0
  76. package/types/unused-texts-de.d.ts +2 -0
  77. package/types/unused-texts.d.ts +130 -0
  78. package/types/unused.d.ts +22 -0
  79. package/types/use-big-result.d.ts +29 -0
  80. package/types/use-export.d.ts +7 -0
  81. package/types/use-theme.d.ts +11 -0
  82. package/types/use-view-history.d.ts +37 -0
  83. package/types/version.d.ts +2 -0
  84. package/types/view-history.d.ts +106 -0
  85. package/types/view-ops.d.ts +293 -0
  86. package/types/view-save.d.ts +76 -0
  87. package/types/view-store.d.ts +59 -0
  88. package/types/virtual.d.ts +44 -0
  89. package/types/zones.d.ts +42 -0
@@ -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";
@@ -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
@@ -0,0 +1,2 @@
1
+ import { useLayoutEffect } from "react";
2
+ export declare const useIsoLayoutEffect: typeof useLayoutEffect;