pivotkit-react 0.4.0 → 0.6.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 (59) hide show
  1. package/CHANGELOG.md +267 -1
  2. package/README.md +5 -2
  3. package/dist/chunks/{chunk-YITKWZ4L.js → chunk-2RAVX4DO.js} +604 -505
  4. package/dist/chunks/{chunk-ZYEYZSYL.js → chunk-7LERNGUW.js} +36 -2
  5. package/dist/chunks/{chunk-EM23V5GH.js → chunk-E6M57YLL.js} +19 -8
  6. package/dist/chunks/{chunk-RWYHJRQO.js → chunk-JMRTIOX4.js} +17 -7
  7. package/dist/chunks/{chunk-XN55BQ4M.js → chunk-RIOSIYGC.js} +54 -7
  8. package/dist/chunks/{chunk-LEN5RPBM.js → chunk-TR2HROIK.js} +43 -7
  9. package/dist/chunks/chunk-W2KIPREL.js +36 -0
  10. package/dist/chunks/{chunk-6MDAL3IO.js → chunk-XN5HNKJ2.js} +88 -101
  11. package/dist/chunks/{chunk-WB4GKWFQ.js → chunk-YXLANLGL.js} +34 -6
  12. package/dist/chunks/report-run-BZBFOMPF.js +12 -0
  13. package/dist/chunks/{unused-texts-K3VFH65P.js → unused-texts-Y4R67XSN.js} +1 -1
  14. package/dist/chunks/{unused-texts-de-OW4TGIVX.js → unused-texts-de-6YVPTNVS.js} +1 -1
  15. package/dist/echarts.js +38 -156
  16. package/dist/import-ui.js +69 -168
  17. package/dist/index.js +160 -102
  18. package/dist/labels.js +6 -6
  19. package/dist/menu-texts-de.js +1 -1
  20. package/dist/menus.js +778 -277
  21. package/dist/styles.css +207 -93
  22. package/package.json +8 -4
  23. package/types/chart-decorate.d.ts +28 -4
  24. package/types/chart-types.d.ts +2 -4
  25. package/types/echarts.d.ts +1 -1
  26. package/types/export-run.d.ts +42 -4
  27. package/types/field-info.d.ts +3 -10
  28. package/types/filter.d.ts +1 -1
  29. package/types/icons.d.ts +1 -0
  30. package/types/import-host.d.ts +34 -8
  31. package/types/import-labels.d.ts +47 -0
  32. package/types/import-limits.d.ts +6 -0
  33. package/types/import-module.d.ts +1 -1
  34. package/types/import-steps.d.ts +8 -0
  35. package/types/import-ui.d.ts +18 -4
  36. package/types/index.d.ts +76 -17
  37. package/types/labels.d.ts +200 -24
  38. package/types/light-tokens.d.ts +16 -0
  39. package/types/menu-labels.d.ts +43 -14
  40. package/types/menu-ops.d.ts +166 -43
  41. package/types/menu-topics.d.ts +7 -4
  42. package/types/names.d.ts +47 -19
  43. package/types/place.d.ts +24 -0
  44. package/types/print-frame.d.ts +24 -0
  45. package/types/report-run.d.ts +14 -0
  46. package/types/share-actions.d.ts +17 -3
  47. package/types/share.d.ts +13 -17
  48. package/types/sheet-views.d.ts +60 -0
  49. package/types/templates.d.ts +21 -1
  50. package/types/theme.d.ts +2 -16
  51. package/types/tips.d.ts +5 -0
  52. package/types/toolbar-panels.d.ts +9 -6
  53. package/types/unused-texts.d.ts +13 -3
  54. package/types/use-export.d.ts +2 -2
  55. package/types/view-ops.d.ts +65 -6
  56. package/types/view-save.d.ts +10 -6
  57. package/types/view-store.d.ts +21 -11
  58. package/types/chart-layout.d.ts +0 -111
  59. package/types/import-source.d.ts +0 -32
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "pivotkit-react",
3
- "version": "0.4.0",
4
- "description": "React 18/19 pivot report builder on pivotkit-core: drag-and-drop fields, table and Apache ECharts chart, filters, templates as JSON, undo, Excel and CSV export.",
3
+ "version": "0.6.0",
4
+ "description": "React 18/19 pivot report builder on pivotkit-core: drag-and-drop fields, table and Apache ECharts chart, filters, views as JSON files, undo, Excel and CSV export.",
5
5
  "license": "MIT",
6
6
  "author": "eizedev <oss@eize.dev>",
7
7
  "homepage": "https://pivotkit.eize.dev",
@@ -18,7 +18,10 @@
18
18
  "reporting",
19
19
  "drag-and-drop",
20
20
  "echarts",
21
- "self-service-bi"
21
+ "self-service-bi",
22
+ "pivot-grid",
23
+ "pivottable",
24
+ "excel-export"
22
25
  ],
23
26
  "type": "module",
24
27
  "sideEffects": [
@@ -61,7 +64,8 @@
61
64
  "dependencies": {
62
65
  "@dnd-kit/core": "6.3.1",
63
66
  "@dnd-kit/sortable": "10.0.0",
64
- "pivotkit-core": "^0.4.0"
67
+ "pivotkit-core": "^0.6.0",
68
+ "pivotkit-report": "^0.2.0"
65
69
  },
66
70
  "devDependencies": {
67
71
  "echarts": "6.1.0"
@@ -1,8 +1,6 @@
1
1
  /**
2
- * Mark styles on top of the core's option: rounded bar ends, 2 px lines, tooltips in the theme, built
3
- * as DOM nodes (chart-tooltip.js) so a strict Content-Security-Policy allows them.
4
2
  * @param {any} option
5
- * @param {CSSStyleDeclaration} style the report's computed style (the --pk-* tokens)
3
+ * @param {{ getPropertyValue(name: string): string }} style the report's tokens (chartStyle)
6
4
  * @param {number} [height] the chart's height in px, for the room around a pie
7
5
  * @param {Document} [doc] the chart's document, for the tooltip's nodes
8
6
  * @param {number} [width] the chart's width in px, for the column names of a heatmap and the category axis
@@ -10,7 +8,33 @@
10
8
  * tooltip's title when the axis writes them shorter) and the view's chart.axisLabels
11
9
  * @returns {any} the option; `axisEvery` (not ECharts') is n when the category axis writes every n-th label
12
10
  */
13
- export declare function decorate(option: any, style: CSSStyleDeclaration, height?: number, doc?: Document, width?: number, extra?: {
11
+ export declare function decorate(option: any, style: {
12
+ getPropertyValue(name: string): string;
13
+ }, height?: number, doc?: Document, width?: number, extra?: {
14
14
  categoryNames?: string[];
15
15
  axisLabels?: string;
16
16
  }): any;
17
+ /**
18
+ * The tokens the chart reads as lengths in px (chartThemeFrom, decorateOption): the title's and the
19
+ * other text's size, the marks' corners. A computed custom property keeps the calc(), max() and em it
20
+ * was written with, so the report resolves them first.
21
+ */
22
+ export declare const LENGTH_TOKENS: readonly string[];
23
+ /**
24
+ * Tokens that are lengths, in px as the report resolves them (em of its font): a probe inside the root
25
+ * takes each one as its margin. A token not set, or not a length CSS takes (a keyword: its margin would
26
+ * be 0), is left out, so the chart keeps its default.
27
+ * @param {HTMLElement} root the report's root
28
+ * @param {readonly string[]} [names]
29
+ * @returns {Record<string, string>} "16px" per token
30
+ */
31
+ export declare function tokenLengths(root: HTMLElement, names?: readonly string[]): Record<string, string>;
32
+ /**
33
+ * The report's computed style with its length tokens in px: what chartThemeFrom and pivotkit-core's
34
+ * decorateOption read.
35
+ * @param {HTMLElement} root
36
+ * @returns {{ getPropertyValue(name: string): string }}
37
+ */
38
+ export declare function chartStyle(root: HTMLElement): {
39
+ getPropertyValue(name: string): string;
40
+ };
@@ -27,10 +27,8 @@ export declare function chartTypeOf(chart: {
27
27
  horizontal?: boolean;
28
28
  }): string;
29
29
  /**
30
- * What the chart draws for a view. A type the user chose is drawn as it is. "auto" (the default)
31
- * draws lines when a date is on Rows; with a date on Columns only it draws lines too, with rows and
32
- * columns swapped for the chart alone (`swap`), so the dates run along the axis and the table keeps
33
- * its layout; else bars (pivotkit-core's autoChartType decides).
30
+ * What the chart draws for a view: pivotkit-core's chartPlan (the same on the screen, in an SVG and a
31
+ * printed report) with the picker entry drawn.
34
32
  * @param {{ rows: string[], cols: string[], derived: any[], chart: { type: string, stacked?: boolean, horizontal?: boolean } }} view
35
33
  * @param {import("pivotkit-core").Encoded} encoded
36
34
  * @returns {{ name: string, auto: boolean, swap: boolean, chart: { type: string, stacked: boolean, horizontal: boolean } }}
@@ -1,4 +1,4 @@
1
1
  import { init } from "echarts/core";
2
2
  export { init };
3
3
  export { cleanChartOptions, mergeChartOptions } from "./chart-options.js";
4
- export { decorate } from "./chart-decorate.js";
4
+ export { LENGTH_TOKENS, chartStyle, decorate, tokenLengths } from "./chart-decorate.js";
@@ -32,9 +32,39 @@ export declare function copyOut(text: string, { type, container, onExport, ...fi
32
32
  container: HTMLElement | null;
33
33
  onExport?: (file: ExportFile) => unknown;
34
34
  }): Promise<"copied" | "kept" | "blocked">;
35
+ /**
36
+ * A CSS colour as "#rrggbb", or null: through a canvas's fillStyle, which writes an opaque sRGB colour
37
+ * that way whatever syntax it was given (a name, rgb(), hsl()). A text that is no colour is refused
38
+ * first (a canvas would keep the colour it had).
39
+ * @param {string} text
40
+ * @param {{ fillStyle: unknown } | null} ctx a 2D context
41
+ * @param {(text: string) => boolean} [supports] whether the text is a colour
42
+ */
43
+ export declare function hexColor(text: string, ctx: {
44
+ fillStyle: unknown;
45
+ } | null, supports?: (text: string) => boolean): string | null;
46
+ /** The tokens of a workbook's colours: its colour scale (--pk-scale-mid only when a host sets it) and data bars. */
47
+ export declare const XLSX_TOKENS: readonly string[];
48
+ /**
49
+ * The colours of the theme the workbook gets for a conditional format whose view names none, as the
50
+ * report resolves its tokens (pivotkit-core's chartThemeFrom): the colour scale (--pk-scale-low, the
51
+ * host's --pk-scale-mid, -high) and the data bars (--pk-chart-1). Each one missing or not a colour
52
+ * stays pivotkit-core's default; a middle colour that is none is left out.
53
+ * @param {{ getPropertyValue(name: string): string }} style the report's light tokens
54
+ * @param {(text: string) => string | null} toHex
55
+ * @returns {{ colorScale?: string[], dataBar?: string }}
56
+ */
57
+ export declare function xlsxThemeOf(style: {
58
+ getPropertyValue(name: string): string;
59
+ }, toHex: (text: string) => string | null): {
60
+ colorScale?: string[];
61
+ dataBar?: string;
62
+ };
35
63
  export type ExportContext = {
36
64
  fileName: string;
37
65
  result: import("pivotkit-core").PivotResult | null;
66
+ encoded?: import("pivotkit-core").Encoded | null;
67
+ exportData?: boolean;
38
68
  locale: string;
39
69
  labels: import("./labels.js").UiLabels;
40
70
  limits: object | undefined;
@@ -44,16 +74,24 @@ export type ExportContext = {
44
74
  tone?: "error";
45
75
  }) => void;
46
76
  onExport?: (file: ExportFile) => unknown;
77
+ title?: string | null;
78
+ source?: string | null;
79
+ loadECharts?: () => Promise<any>;
47
80
  };
48
81
  /**
49
- * @typedef {{ fileName: string, result: import("pivotkit-core").PivotResult | null, locale: string,
82
+ * @typedef {{ fileName: string, result: import("pivotkit-core").PivotResult | null, encoded?: import("pivotkit-core").Encoded | null, exportData?: boolean, locale: string,
50
83
  * labels: import("./labels.js").UiLabels, limits: object | undefined, root: React.RefObject<HTMLElement | null>,
51
84
  * chartRef: React.RefObject<any>, announce: (text: string, extra?: { tone?: "error" }) => void,
52
- * onExport?: (file: ExportFile) => unknown }} ExportContext
85
+ * onExport?: (file: ExportFile) => unknown, title?: string | null, source?: string | null, loadECharts?: () => Promise<any> }} ExportContext
86
+ * `title`: the report's title in an HTML report (the loaded view's name); `source`: the data's name;
87
+ * `encoded`: the data shown (the host's or a loaded file's), which the source data exports, only
88
+ * with `exportData` (the host's prop: the menu hides it otherwise, and no other way reaches it);
89
+ * `loadECharts`: chart.jsx's loader of dist/echarts.js (passed in: a module of the menus that
90
+ * imported chart.jsx would move it out of the first load into a shared chunk)
53
91
  */
54
92
  /**
55
93
  * One export of the Export menu.
56
- * @param {"xlsx" | "csv" | "png" | "copy-table" | "copy-json"} kind
94
+ * @param {"xlsx" | "csv" | "png" | "html" | "svg" | "print" | "copy-table" | "copy-json" | "data-csv" | "data-json"} kind
57
95
  * @param {ExportContext} context
58
96
  */
59
- export declare function runExport(kind: "xlsx" | "csv" | "png" | "copy-table" | "copy-json", { fileName, result, locale, labels, limits, root, chartRef, announce, onExport }: ExportContext): Promise<void>;
97
+ export declare function runExport(kind: "xlsx" | "csv" | "png" | "html" | "svg" | "print" | "copy-table" | "copy-json" | "data-csv" | "data-json", { fileName, result, encoded, exportData, locale, labels, limits, root, chartRef, announce, onExport, title, source, loadECharts }: ExportContext): Promise<void>;
@@ -1,3 +1,4 @@
1
+ import { isIdentifierName } from "pivotkit-core";
1
2
  export type FieldInfo = {
2
3
  label?: string;
3
4
  description?: string;
@@ -32,16 +33,8 @@ export declare function typesOf(fieldDefaults: unknown): Record<string, string>
32
33
  * @param {FieldInfo | undefined} info
33
34
  */
34
35
  export declare function fieldMatches(field: string, query: string, info: FieldInfo | undefined): boolean;
35
- /**
36
- * Whether a field's name says it is an identifier: its last word is ID, Nr, No, Number, Key or "#",
37
- * in any case. Words are split at a space, "_", "-", ".", "/", ":", a change from a small letter to
38
- * a capital ("CustomerId", "CustomerID") and from a letter to a digit; a "#" is a word of its own
39
- * ("Serial#" as "Serial #"). Before the last word is read, a part in parentheses at the end ("ID
40
- * (Asset)") and digits at the end ("userID2") are left out. "Paid", "PAID" and "UUID" are one word,
41
- * not one ending in "id"; "Number of items" ends in "items".
42
- * @param {string} name
43
- */
44
- export declare function isIdentifierName(name: string): boolean;
36
+ /** Whether a field's name says it is an identifier: pivotkit-core's rule, which its suggestions share. */
37
+ export { isIdentifierName };
45
38
  /**
46
39
  * Whether a column is an identifier: a number column of whole numbers whose name says so
47
40
  * (isIdentifierName). That every value is another is no sign: a count per row is too.
package/types/filter.d.ts CHANGED
@@ -35,7 +35,7 @@ export declare function ValueList({ items, selected, onChange, labels, locale, a
35
35
  /**
36
36
  * @param {{ target: { field: string, anchor: HTMLElement, base?: object } | null, onClose: () => void, view: object,
37
37
  * encoded: import("pivotkit-core").Encoded, locale: string, labels: import("./labels.js").UiLabels, commit: (v: object, note?: any) => void }} props
38
- * `target.base`: the draft view of a field that is not placed yet (it goes into Filters on Apply)
38
+ * `target.base`: the draft view of a field that is not in Filters yet (it goes there on Apply)
39
39
  */
40
40
  export declare function FilterPopover({ target, onClose, view, encoded, locale, labels, commit }: {
41
41
  target: {
package/types/icons.d.ts CHANGED
@@ -44,6 +44,7 @@ declare const PATHS: {
44
44
  warn: string;
45
45
  image: string;
46
46
  file: string;
47
+ print: string;
47
48
  newFile: string;
48
49
  swap: string;
49
50
  top: string;
@@ -1,13 +1,7 @@
1
1
  import React from "react";
2
2
  export type ImportApi = import("./import-steps.js").ImportContext & {
3
- job: {
4
- file: File;
5
- n: number;
6
- } | null;
7
- setJob: React.Dispatch<React.SetStateAction<{
8
- file: File;
9
- n: number;
10
- } | null>>;
3
+ job: ImportJob | null;
4
+ setJob: React.Dispatch<React.SetStateAction<ImportJob | null>>;
11
5
  dismiss?: (id: number) => void;
12
6
  dragging: boolean;
13
7
  encoded: import("pivotkit-core").Encoded;
@@ -18,6 +12,14 @@ export type ImportApi = import("./import-steps.js").ImportContext & {
18
12
  timeZone?: string;
19
13
  box: () => DOMRect | undefined;
20
14
  pick: () => void;
15
+ afterData: (run: (() => void) | null) => void;
16
+ };
17
+ export type ImportJob = {
18
+ file: File;
19
+ n: number;
20
+ sheet?: string;
21
+ auto?: boolean;
22
+ done?: (loaded: boolean, refused?: boolean) => void;
21
23
  };
22
24
  /**
23
25
  * Files picked or dropped: one opens its preview, more than one is said to be too many. The error
@@ -26,6 +28,30 @@ export type ImportApi = import("./import-steps.js").ImportContext & {
26
28
  * @param {File[]} files
27
29
  */
28
30
  export declare function startFiles(api: ImportApi, files: File[]): void;
31
+ /**
32
+ * Reads another sheet of the file shown and loads it at once (a saved view made on that sheet was
33
+ * opened, sheet-views.js): the dialog shows the progress and has Cancel, a sheet that cannot be read
34
+ * says why there. `done` is told whether the sheet was loaded (Cancel, a failure and a host's refusal
35
+ * are not).
36
+ * @param {ImportApi} api
37
+ * @param {string} sheet
38
+ * @param {(loaded: boolean, refused?: boolean) => void} done `refused`: the host refused it (onDataLoad)
39
+ */
40
+ export declare function loadSheet(api: ImportApi, sheet: string, done: (loaded: boolean, refused?: boolean) => void): void;
41
+ /**
42
+ * A view that names a sheet (sheet-views.js: sheetPlan): another sheet of the workbook shown is read
43
+ * first (loadSheet), and `then` runs once its data is shown (the report's `afterData`); a sheet the
44
+ * workbook does not have is said, and the view loads on the sheet shown. A sheet the host refuses
45
+ * (onDataLoad) is said too; Cancel is not. Returns what the plan was.
46
+ * @param {ImportApi} api
47
+ * @param {{ id?: string | null, sheet?: string | null }} made the data and sheet the view names
48
+ * @param {string} name the view's name
49
+ * @param {() => void} then
50
+ */
51
+ export declare function openOnSheet(api: ImportApi, made: {
52
+ id?: string | null;
53
+ sheet?: string | null;
54
+ }, name: string, then: () => void): "missing" | "none" | "switch";
29
55
  /**
30
56
  * Opens the browser's file picker: the report's hidden file input.
31
57
  * @param {HTMLInputElement | null} input
@@ -56,8 +56,19 @@ export declare const en: {
56
56
  originalShown: string;
57
57
  failed: string;
58
58
  refused: string;
59
+ overLimit: string;
60
+ limitWhat: {
61
+ rows: string;
62
+ columns: string;
63
+ fileBytes: string;
64
+ importCells: string;
65
+ archiveEntries: string;
66
+ unpackedBytes: string;
67
+ };
59
68
  sourceLine: string;
60
69
  sourceSheet: string;
70
+ sheetMissing: string;
71
+ sheetRefused: string;
61
72
  notes: {
62
73
  ENCODING: string;
63
74
  SEPARATOR: string;
@@ -172,8 +183,19 @@ export declare const IMPORT_TEXTS: Readonly<{
172
183
  originalShown: string;
173
184
  failed: string;
174
185
  refused: string;
186
+ overLimit: string;
187
+ limitWhat: {
188
+ rows: string;
189
+ columns: string;
190
+ fileBytes: string;
191
+ importCells: string;
192
+ archiveEntries: string;
193
+ unpackedBytes: string;
194
+ };
175
195
  sourceLine: string;
176
196
  sourceSheet: string;
197
+ sheetMissing: string;
198
+ sheetRefused: string;
177
199
  notes: {
178
200
  ENCODING: string;
179
201
  SEPARATOR: string;
@@ -282,8 +304,19 @@ export declare const IMPORT_TEXTS: Readonly<{
282
304
  originalShown: string;
283
305
  failed: string;
284
306
  refused: string;
307
+ overLimit: string;
308
+ limitWhat: {
309
+ rows: string;
310
+ columns: string;
311
+ fileBytes: string;
312
+ importCells: string;
313
+ archiveEntries: string;
314
+ unpackedBytes: string;
315
+ };
285
316
  sourceLine: string;
286
317
  sourceSheet: string;
318
+ sheetMissing: string;
319
+ sheetRefused: string;
287
320
  notes: {
288
321
  ENCODING: string;
289
322
  SEPARATOR: string;
@@ -358,3 +391,17 @@ export declare function noteText(note: {
358
391
  lang: string;
359
392
  locale: string;
360
393
  }): string;
394
+ /**
395
+ * Why a file could not be read, after "{name} could not be loaded:", which names the file: a limit of
396
+ * pivotkit-core (`LIMIT_EXCEEDED` with a limit this version has words for) in the report's language
397
+ * with its key (`limits.rows`, whose words fit `importLimits` too), else the reader's own English
398
+ * message without the file's name in front (`"name": ` of `fileError`, `"name" ` of `limitError`).
399
+ * @param {unknown} error
400
+ * @param {string} name the file's name
401
+ * @param {ImportTexts} texts
402
+ * @param {{ lang: string, locale: string }} where
403
+ */
404
+ export declare function errorText(error: unknown, name: string, texts: ImportTexts, where: {
405
+ lang: string;
406
+ locale: string;
407
+ }): string;
@@ -0,0 +1,6 @@
1
+ /**
2
+ * @param {unknown} limits the host's `limits`
3
+ * @param {unknown} importLimits the host's `importLimits`
4
+ * @returns {Partial<import("pivotkit-core").Limits> | undefined} to pass as `options.limits`
5
+ */
6
+ export declare function importLimitsOf(limits: unknown, importLimits: unknown): Partial<import("pivotkit-core").Limits> | undefined;
@@ -1,2 +1,2 @@
1
- export { DataMenuPanel, ImportLayer, SourceLine, pickFile, startFiles } from "./import-host.jsx";
1
+ export { DataMenuPanel, ImportLayer, SourceLine, loadSheet, openOnSheet, pickFile, startFiles } from "./import-host.jsx";
2
2
  export { moveData, restoreData } from "./import-steps.js";
@@ -9,6 +9,14 @@ export type ShownData = {
9
9
  name: string;
10
10
  };
11
11
  sheet: string | null;
12
+ /**
13
+ * the workbook's sheets (names)
14
+ */
15
+ sheets?: readonly string[];
16
+ /**
17
+ * the file, to read another of its sheets
18
+ */
19
+ blob?: File;
12
20
  file: {
13
21
  name: string;
14
22
  size: number;
@@ -47,7 +47,7 @@ export declare function SourceLine({ labels, source }: {
47
47
  export type LoadedData = {
48
48
  encoded: import("pivotkit-core").Encoded;
49
49
  /**
50
- * the id for the saved views (import-source.js), the name shown
50
+ * the id for the saved views (pivotkit-core/import's sourceIdOf), the name shown
51
51
  */
52
52
  source: {
53
53
  id: string;
@@ -59,6 +59,14 @@ export type LoadedData = {
59
59
  type: string;
60
60
  };
61
61
  sheet: string | null;
62
+ /**
63
+ * the names of the workbook's sheets ([] for a file with one table)
64
+ */
65
+ sheets: readonly string[];
66
+ /**
67
+ * the file itself, to read another of its sheets (a view made on it, sheet-views.js)
68
+ */
69
+ blob: File;
62
70
  rows: number;
63
71
  columns: Array<{
64
72
  name: string;
@@ -73,9 +81,11 @@ export type LoadedData = {
73
81
  /**
74
82
  * @typedef {object} LoadedData what "Load data" hands the report
75
83
  * @property {import("pivotkit-core").Encoded} encoded
76
- * @property {{ id: string, name: string }} source the id for the saved views (import-source.js), the name shown
84
+ * @property {{ id: string, name: string }} source the id for the saved views (pivotkit-core/import's sourceIdOf), the name shown
77
85
  * @property {{ name: string, size: number, type: string }} file
78
86
  * @property {string | null} sheet
87
+ * @property {readonly string[]} sheets the names of the workbook's sheets ([] for a file with one table)
88
+ * @property {File} blob the file itself, to read another of its sheets (a view made on it, sheet-views.js)
79
89
  * @property {number} rows
80
90
  * @property {Array<{ name: string, type: string }>} columns
81
91
  * @property {Array<{ code: string, params: Record<string, unknown>, message: string }>} notes
@@ -84,8 +94,10 @@ export type LoadedData = {
84
94
  * Reads a file (progress, Cancel) and shows it before it replaces the data: the sheet, the first
85
95
  * rows with a type per column, the readers' notes; "Load data" or Cancel. Modal, in the top layer:
86
96
  * the focus moves in, Tab stays inside, Escape cancels, the focus goes back to where it was. A file
87
- * that cannot be read closes it with a note; the report's data stays.
88
- * @param {{ job: { file: File, n: number }, labels: any, locale: string, plugins: any[], worker?: () => Worker,
97
+ * that cannot be read closes it with a note; the report's data stays. A job with `sheet` starts on that
98
+ * sheet (a name); with `auto` it loads as soon as the sheet is read, without waiting for "Load data"
99
+ * (a saved view opened on another sheet of the file shown: the person asked for that sheet already).
100
+ * @param {{ job: { file: File, n: number, sheet?: string, auto?: boolean }, labels: any, locale: string, plugins: any[], worker?: () => Worker,
89
101
  * limits?: object, timeZone?: string, onApply: (data: LoadedData) => void, onClose: () => void,
90
102
  * announce: (text: string, extra?: { tone?: "error" }) => void }} props
91
103
  */
@@ -93,6 +105,8 @@ export declare function ImportDialog({ job, labels, locale, plugins, worker, lim
93
105
  job: {
94
106
  file: File;
95
107
  n: number;
108
+ sheet?: string;
109
+ auto?: boolean;
96
110
  };
97
111
  labels: any;
98
112
  locale: string;
package/types/index.d.ts CHANGED
@@ -27,6 +27,21 @@ export type Template = {
27
27
  };
28
28
  export type TemplateScope = {
29
29
  scope: "shared" | "user";
30
+ /**
31
+ * for a save: the data shown
32
+ */
33
+ source?: TemplateSource | null;
34
+ };
35
+ export type TemplateSource = {
36
+ /**
37
+ * the source's id (the host's `source.id`, a loaded file's name and hash)
38
+ */
39
+ id: string;
40
+ name?: string;
41
+ /**
42
+ * a loaded workbook's sheet: `{ sheet }`
43
+ */
44
+ params?: Record<string, string>;
30
45
  };
31
46
  export type FieldDefaults = {
32
47
  /**
@@ -99,11 +114,14 @@ export type CellClick = {
99
114
  };
100
115
  export type ExportFile = {
101
116
  /**
102
- * "json": the view file (Views, "Download view"); "copy-table", "copy-json": Export → Copy table,
117
+ * "html": the HTML report; "svg": the chart as SVG; "print": the HTML report before it is printed
118
+ * (returning false prints nothing: the host prints it, e.g. as a PDF of its own);
119
+ * "json": the view file (Views, "Download view"); "data-csv", "data-json": Export → Source data, every
120
+ * row of the data shown as it is (`<fileName>-data.csv`, `<fileName>-data.json`); "copy-table", "copy-json": Export → Copy table,
103
121
  * Copy data as JSON; "drill-*": the drill-down panel's Export menu (Copy, Copy as JSON, Download
104
122
  * CSV, Download Excel)
105
123
  */
106
- kind: "xlsx" | "csv" | "png" | "json" | "copy-table" | "copy-json" | "drill-copy" | "drill-json" | "drill-csv" | "drill-xlsx";
124
+ kind: "xlsx" | "csv" | "png" | "html" | "svg" | "print" | "json" | "data-csv" | "data-json" | "copy-table" | "copy-json" | "drill-copy" | "drill-json" | "drill-csv" | "drill-xlsx";
107
125
  /**
108
126
  * with the extension ("pivot.xlsx"), made safe; for a copy the name it
109
127
  * would have as a file ("pivot.tsv", "Central – Jul 2026.json")
@@ -156,8 +174,9 @@ export type PivotReportProps = {
156
174
  templates?: Template[];
157
175
  /**
158
176
  * shows
159
- * "Save" when set (`where.scope` is "user"); "saved" is shown when it returns or the promise it
160
- * returns resolves, an error when it throws or rejects. It wins over `templateStore`
177
+ * "Save" when set (`where.scope` is "user", `where.source` the data shown, null without a source id);
178
+ * "saved" is shown when it returns or the promise it returns resolves, an error when it throws or
179
+ * rejects. It wins over `templateStore`
161
180
  */
162
181
  onSaveTemplate?: (name: string, view: View, where: TemplateScope) => unknown;
163
182
  /**
@@ -168,9 +187,13 @@ export type PivotReportProps = {
168
187
  /**
169
188
  * with `canPublish`:
170
189
  * "Publish as shared view" on each of the user's views; the host makes it a shared entry of
171
- * `templates`; "published" is shown when it returns or its promise resolves
190
+ * `templates`; "published" is shown when it returns or its promise resolves; `where.source` the data the
191
+ * view was made for: the data shown (null without a source id), or the data a view file or a view of
192
+ * the browser store names (its id and sheet; its name when that is the data shown)
172
193
  */
173
- onPublishTemplate?: (name: string, view: ViewInput) => unknown;
194
+ onPublishTemplate?: (name: string, view: ViewInput, where: {
195
+ source: TemplateSource | null;
196
+ }) => unknown;
174
197
  /**
175
198
  * the user may publish views for everyone (an admin); default false
176
199
  */
@@ -223,7 +246,17 @@ export type PivotReportProps = {
223
246
  * least height: "on" by default without `height`, "off" with it
224
247
  */
225
248
  grow?: "on" | "off";
249
+ /**
250
+ * pivotkit-core's limits for the host's data
251
+ * (and for a loaded file, where `importLimits` leaves a key out)
252
+ */
226
253
  limits?: Partial<import("pivotkit-core").Limits>;
254
+ /**
255
+ * the limits a file loaded with
256
+ * `allowImport` is read and shown with, merged key by key over `limits` (default: `limits`), so a
257
+ * host can keep uploads small without capping its own data
258
+ */
259
+ importLimits?: Partial<import("pivotkit-core").Limits>;
227
260
  /**
228
261
  * the name of the report's region landmark (default the labels' `report`);
229
262
  * several reports on one page each need their own
@@ -240,6 +273,12 @@ export type PivotReportProps = {
240
273
  * host keeps the file or the text, for example to upload it)
241
274
  */
242
275
  onExport?: (file: ExportFile) => unknown;
276
+ /**
277
+ * the Export menu's "Source data": every row and every column of the
278
+ * data shown, as a CSV or JSON file, for the user's own analysis or the command line. Default false:
279
+ * the rows may hold more than the report shows (docs/security.md)
280
+ */
281
+ exportData?: boolean;
243
282
  /**
244
283
  * the tips above the result: "on" (default), "off"
245
284
  * (none, and no switch in Options), or the ids of the tips allowed (an array, or a comma-separated text)
@@ -309,8 +348,8 @@ export type PivotReportProps = {
309
348
  sources?: ViewSource[];
310
349
  /**
311
350
  * the `$schema` of the view files the report writes: by default
312
- * https://pivotkit.eize.dev/schema/view-file-1.json, a host's own copy of the schema (it ships in
313
- * pivotkit-core as "pivotkit-core/schema/view-file-1.json"), or null or "" to leave it out; loading a
351
+ * https://pivotkit.eize.dev/schema/view-file-2.json, a host's own copy of the schema (it ships in
352
+ * pivotkit-core as "pivotkit-core/schema/view-file-2.json"), or null or "" to leave it out; loading a
314
353
  * view never depends on it
315
354
  */
316
355
  schemaUrl?: string | null;
@@ -415,6 +454,13 @@ export type TipDismiss = {
415
454
  /**
416
455
  * @typedef {object} TemplateScope where a template is or goes
417
456
  * @property {"shared" | "user"} scope
457
+ * @property {TemplateSource | null} [source] for a save: the data shown
458
+ */
459
+ /**
460
+ * @typedef {object} TemplateSource the data a view is saved or published from, as a view file names it
461
+ * @property {string} id the source's id (the host's `source.id`, a loaded file's name and hash)
462
+ * @property {string} [name]
463
+ * @property {Record<string, string>} [params] a loaded workbook's sheet: `{ sheet }`
418
464
  */
419
465
  /**
420
466
  * @typedef {object} FieldDefaults the host's settings for a field. A number field of whole numbers
@@ -450,8 +496,11 @@ export type TipDismiss = {
450
496
  /**
451
497
  * @typedef {object} ExportFile a file the report made, before it is downloaded, or a text before it
452
498
  * goes on the clipboard
453
- * @property {"xlsx" | "csv" | "png" | "json" | "copy-table" | "copy-json" | "drill-copy" | "drill-json" | "drill-csv" | "drill-xlsx"} kind
454
- * "json": the view file (Views, "Download view"); "copy-table", "copy-json": Export → Copy table,
499
+ * @property {"xlsx" | "csv" | "png" | "html" | "svg" | "print" | "json" | "data-csv" | "data-json" | "copy-table" | "copy-json" | "drill-copy" | "drill-json" | "drill-csv" | "drill-xlsx"} kind
500
+ * "html": the HTML report; "svg": the chart as SVG; "print": the HTML report before it is printed
501
+ * (returning false prints nothing: the host prints it, e.g. as a PDF of its own);
502
+ * "json": the view file (Views, "Download view"); "data-csv", "data-json": Export → Source data, every
503
+ * row of the data shown as it is (`<fileName>-data.csv`, `<fileName>-data.json`); "copy-table", "copy-json": Export → Copy table,
455
504
  * Copy data as JSON; "drill-*": the drill-down panel's Export menu (Copy, Copy as JSON, Download
456
505
  * CSV, Download Excel)
457
506
  * @property {string} fileName with the extension ("pivot.xlsx"), made safe; for a copy the name it
@@ -473,13 +522,16 @@ export type TipDismiss = {
473
522
  * @property {(view: View) => void} [onViewChange] every change, normalized
474
523
  * @property {Template[]} [templates] the entries of the Views menu, in two groups by `scope`
475
524
  * @property {(name: string, view: View, where: TemplateScope) => unknown} [onSaveTemplate] shows
476
- * "Save" when set (`where.scope` is "user"); "saved" is shown when it returns or the promise it
477
- * returns resolves, an error when it throws or rejects. It wins over `templateStore`
525
+ * "Save" when set (`where.scope` is "user", `where.source` the data shown, null without a source id);
526
+ * "saved" is shown when it returns or the promise it returns resolves, an error when it throws or
527
+ * rejects. It wins over `templateStore`
478
528
  * @property {(name: string, where: TemplateScope) => unknown} [onDeleteTemplate] deletes a template
479
529
  * marked `deletable` (`where.scope`: its group); the entry goes when it returns (or its promise resolves)
480
- * @property {(name: string, view: ViewInput) => unknown} [onPublishTemplate] with `canPublish`:
530
+ * @property {(name: string, view: ViewInput, where: { source: TemplateSource | null }) => unknown} [onPublishTemplate] with `canPublish`:
481
531
  * "Publish as shared view" on each of the user's views; the host makes it a shared entry of
482
- * `templates`; "published" is shown when it returns or its promise resolves
532
+ * `templates`; "published" is shown when it returns or its promise resolves; `where.source` the data the
533
+ * view was made for: the data shown (null without a source id), or the data a view file or a view of
534
+ * the browser store names (its id and sheet; its name when that is the data shown)
483
535
  * @property {boolean} [canPublish] the user may publish views for everyone (an admin); default false
484
536
  * @property {"browser"} [templateStore] "browser": the user's own views are kept in this browser's
485
537
  * localStorage under `storageKey` (only this browser and device, lost when the site's data is
@@ -499,7 +551,11 @@ export type TipDismiss = {
499
551
  * (the page scrolls); with it the report stays inside that height and its result scrolls
500
552
  * @property {"on" | "off"} [grow] whether the report grows past its height to keep the result's
501
553
  * least height: "on" by default without `height`, "off" with it
502
- * @property {Partial<import("pivotkit-core").Limits>} [limits]
554
+ * @property {Partial<import("pivotkit-core").Limits>} [limits] pivotkit-core's limits for the host's data
555
+ * (and for a loaded file, where `importLimits` leaves a key out)
556
+ * @property {Partial<import("pivotkit-core").Limits>} [importLimits] the limits a file loaded with
557
+ * `allowImport` is read and shown with, merged key by key over `limits` (default: `limits`), so a
558
+ * host can keep uploads small without capping its own data
503
559
  * @property {string} [label] the name of the report's region landmark (default the labels' `report`);
504
560
  * several reports on one page each need their own
505
561
  * @property {string} [className]
@@ -507,6 +563,9 @@ export type TipDismiss = {
507
563
  * @property {(file: ExportFile) => unknown} [onExport] every exported file before its download, and
508
564
  * every copy before it goes on the clipboard; returning false skips the download or the copy (the
509
565
  * host keeps the file or the text, for example to upload it)
566
+ * @property {boolean} [exportData] the Export menu's "Source data": every row and every column of the
567
+ * data shown, as a CSV or JSON file, for the user's own analysis or the command line. Default false:
568
+ * the rows may hold more than the report shows (docs/security.md)
510
569
  * @property {"on" | "off" | string | string[]} [tips] the tips above the result: "on" (default), "off"
511
570
  * (none, and no switch in Options), or the ids of the tips allowed (an array, or a comma-separated text)
512
571
  * @property {string} [storageKey] remembers dismissed tips in localStorage under this key (one per
@@ -539,8 +598,8 @@ export type TipDismiss = {
539
598
  * @property {ViewSource[]} [sources] the other data the host can show: a view made for one of them
540
599
  * offers "Switch to <name> and load" (with `onSourceSwitch`)
541
600
  * @property {string | null} [schemaUrl] the `$schema` of the view files the report writes: by default
542
- * https://pivotkit.eize.dev/schema/view-file-1.json, a host's own copy of the schema (it ships in
543
- * pivotkit-core as "pivotkit-core/schema/view-file-1.json"), or null or "" to leave it out; loading a
601
+ * https://pivotkit.eize.dev/schema/view-file-2.json, a host's own copy of the schema (it ships in
602
+ * pivotkit-core as "pivotkit-core/schema/view-file-2.json"), or null or "" to leave it out; loading a
544
603
  * view never depends on it
545
604
  * @property {(request: SourceSwitch) => void} [onSourceSwitch] the user chose to switch to the data a
546
605
  * view was made for and load it there: the host shows that data and the view (as its start view)