pivotkit-react 0.6.0 → 0.7.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/dist/styles.css CHANGED
@@ -1024,7 +1024,7 @@
1024
1024
  gap: 1px;
1025
1025
  }
1026
1026
  .pk-subsection + .pk-subsection {
1027
- border-top: 1px dashed var(--pk-border);
1027
+ border-top: 1px dashed var(--pk-rule);
1028
1028
  margin-top: 4px;
1029
1029
  padding-top: 4px;
1030
1030
  }
@@ -1939,6 +1939,9 @@
1939
1939
  padding: 0;
1940
1940
  border: 0;
1941
1941
  }
1942
+ .pk-condition.pk-rules {
1943
+ flex-wrap: nowrap;
1944
+ }
1942
1945
  .pk-condition legend {
1943
1946
  margin-bottom: 4px;
1944
1947
  color: var(--pk-muted);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pivotkit-react",
3
- "version": "0.6.0",
3
+ "version": "0.7.0",
4
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>",
@@ -38,12 +38,16 @@
38
38
  "default": "./dist/labels.js"
39
39
  },
40
40
  "./import-worker": "./dist/import-worker.js",
41
- "./styles.css": "./dist/styles.css",
41
+ "./styles.css": {
42
+ "types": "./styles.css.d.ts",
43
+ "default": "./dist/styles.css"
44
+ },
42
45
  "./package.json": "./package.json"
43
46
  },
44
47
  "files": [
45
48
  "dist",
46
49
  "types",
50
+ "styles.css.d.ts",
47
51
  "README.md",
48
52
  "CHANGELOG.md",
49
53
  "LICENSE"
@@ -64,8 +68,8 @@
64
68
  "dependencies": {
65
69
  "@dnd-kit/core": "6.3.1",
66
70
  "@dnd-kit/sortable": "10.0.0",
67
- "pivotkit-core": "^0.6.0",
68
- "pivotkit-report": "^0.2.0"
71
+ "pivotkit-core": "^0.7.0",
72
+ "pivotkit-report": "^0.3.0"
69
73
  },
70
74
  "devDependencies": {
71
75
  "echarts": "6.1.0"
@@ -0,0 +1,3 @@
1
+ // The types of `import "pivotkit-react/styles.css"`: a stylesheet, no exports. It lets a strict
2
+ // TypeScript project import it without a bundler's own CSS types (TS2882 otherwise).
3
+ export {};
@@ -15,11 +15,11 @@ export declare function rowsText({ shown, count }: {
15
15
  * @param {DrillExportKind} kind
16
16
  * @param {{ drill: { name: string, count: number, locale: string, indices: ArrayLike<number>, formats: Record<string, string>,
17
17
  * columns: Array<{ name: string, label?: string }>, rows: string[][] },
18
- * encoded: import("pivotkit-core").Encoded, labels: import("./labels.js").UiLabels,
18
+ * encoded: import("pivotkit-core").Encoded, labels: import("./labels.js").UiLabels, columns?: string[],
19
19
  * onExport?: (file: import("./export-run.js").ExportFile) => unknown,
20
20
  * announce: (text: string, extra?: { tone?: "error" }) => void, root: HTMLElement | null }} context
21
21
  */
22
- export declare function exportDrill(kind: DrillExportKind, { drill, encoded, labels, onExport, announce, root }: {
22
+ export declare function exportDrill(kind: DrillExportKind, { drill, encoded, labels, columns, onExport, announce, root }: {
23
23
  drill: {
24
24
  name: string;
25
25
  count: number;
@@ -34,6 +34,7 @@ export declare function exportDrill(kind: DrillExportKind, { drill, encoded, lab
34
34
  };
35
35
  encoded: import("pivotkit-core").Encoded;
36
36
  labels: import("./labels.js").UiLabels;
37
+ columns?: string[];
37
38
  onExport?: (file: import("./export-run.js").ExportFile) => unknown;
38
39
  announce: (text: string, extra?: {
39
40
  tone?: "error";
@@ -4,9 +4,10 @@ export type Drill = import("./drill-table.js").Drill;
4
4
  /**
5
5
  * @param {{ drill: import("./drill-table.js").DrillSource | null, onClose: () => void, labels: import("./labels.js").UiLabels, locale: string,
6
6
  * exportContext?: { encoded: import("pivotkit-core").Encoded, onExport?: (file: import("./export-run.js").ExportFile) => unknown,
7
- * announce: (text: string, extra?: { tone?: "error" }) => void, root: React.RefObject<HTMLElement | null> } }} props
7
+ * announce: (text: string, extra?: { tone?: "error" }) => void, root: React.RefObject<HTMLElement | null>, exportData?: unknown } }} props
8
+ * `exportContext`: the panel's exports; the host's exportData `{ columns }` keeps them to those (#259)
8
9
  */
9
- export declare function DrillPanel({ drill: source, onClose, labels, locale, exportContext }: {
10
+ export declare function DrillPanel({ drill: source, onClose, labels, locale, exportContext: context }: {
10
11
  drill: import("./drill-table.js").DrillSource | null;
11
12
  onClose: () => void;
12
13
  labels: import("./labels.js").UiLabels;
@@ -18,5 +19,6 @@ export declare function DrillPanel({ drill: source, onClose, labels, locale, exp
18
19
  tone?: "error";
19
20
  }) => void;
20
21
  root: React.RefObject<HTMLElement | null>;
22
+ exportData?: unknown;
21
23
  };
22
24
  }): React.JSX.Element | null;
@@ -10,6 +10,18 @@ export declare function loadExporters(): Promise<typeof import("pivotkit-core/ex
10
10
  export declare const exportersNow: () => typeof import("pivotkit-core/export") | null;
11
11
  /** Starts loading the export module (a menu that copies, when it opens); a failure waits for the click. */
12
12
  export declare const prepareExporters: () => undefined;
13
+ /**
14
+ * Makes the Export menu's exports ready to happen in the click (use-export.js). When the menu opens
15
+ * ("menu"): the export module (a copy) and an empty print frame (print-frame.js); the function it
16
+ * returns removes the frame when the menu closes without a print. When Print is pointed at or focused
17
+ * ("print"): the report's modules, ECharts with them (a chunk too large to load whenever the menu
18
+ * opens). A failure waits for the click.
19
+ * @param {"menu" | "print"} what
20
+ * @param {React.RefObject<HTMLElement | null>} root the report's root
21
+ * @param {(() => Promise<any>) | undefined} loadECharts chart.jsx's
22
+ * @returns {(() => void) | undefined}
23
+ */
24
+ export declare function prepareExport(what: "menu" | "print", root: React.RefObject<HTMLElement | null>, loadECharts: (() => Promise<any>) | undefined): (() => void) | undefined;
13
25
  /**
14
26
  * Hands the file to the host's onExport, then downloads it unless onExport returned false.
15
27
  * @returns {boolean} whether the report downloaded it
@@ -64,7 +76,7 @@ export type ExportContext = {
64
76
  fileName: string;
65
77
  result: import("pivotkit-core").PivotResult | null;
66
78
  encoded?: import("pivotkit-core").Encoded | null;
67
- exportData?: boolean;
79
+ exportData?: unknown;
68
80
  locale: string;
69
81
  labels: import("./labels.js").UiLabels;
70
82
  limits: object | undefined;
@@ -79,13 +91,14 @@ export type ExportContext = {
79
91
  loadECharts?: () => Promise<any>;
80
92
  };
81
93
  /**
82
- * @typedef {{ fileName: string, result: import("pivotkit-core").PivotResult | null, encoded?: import("pivotkit-core").Encoded | null, exportData?: boolean, locale: string,
94
+ * @typedef {{ fileName: string, result: import("pivotkit-core").PivotResult | null, encoded?: import("pivotkit-core").Encoded | null, exportData?: unknown, locale: string,
83
95
  * labels: import("./labels.js").UiLabels, limits: object | undefined, root: React.RefObject<HTMLElement | null>,
84
96
  * chartRef: React.RefObject<any>, announce: (text: string, extra?: { tone?: "error" }) => void,
85
97
  * onExport?: (file: ExportFile) => unknown, title?: string | null, source?: string | null, loadECharts?: () => Promise<any> }} ExportContext
86
98
  * `title`: the report's title in an HTML report (the loaded view's name); `source`: the data's name;
87
99
  * `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);
100
+ * with the host's `exportData` (read by export-scope.js: the menu hides it otherwise, and no other
101
+ * way reaches it; `{ columns }`: only those);
89
102
  * `loadECharts`: chart.jsx's loader of dist/echarts.js (passed in: a module of the menus that
90
103
  * imported chart.jsx would move it out of the first load into a shared chunk)
91
104
  */
@@ -0,0 +1,47 @@
1
+ export type ExportDataOption = boolean | {
2
+ columns?: string[];
3
+ };
4
+ export type DataExport = {
5
+ source: boolean;
6
+ columns?: string[];
7
+ unknown: string[];
8
+ notList?: boolean;
9
+ };
10
+ /**
11
+ * @typedef {boolean | { columns?: string[] }} ExportDataOption
12
+ * @typedef {{ source: boolean, columns?: string[], unknown: string[], notList?: boolean }} DataExport
13
+ * `source`: Source data is offered; `columns`: the host's columns as the data names them (only
14
+ * these, in this order, in Source data and in the drill-down's exports); `unknown`: names the host
15
+ * gave that no column of the data has; `notList`: `columns` was given but is no list
16
+ */
17
+ /**
18
+ * The host's `exportData` against the data's own columns (not the derived fields a view adds):
19
+ * - off (false, absent, or a shape it does not know): no Source data; the drill-down's exports as
20
+ * they are, every column;
21
+ * - `{ columns }` that is no list (`"Region"`, a function): both off, as an empty list, so a mistake
22
+ * hands out nothing;
23
+ * - true or `{}`: Source data with every column;
24
+ * - `{ columns }`: Source data and the drill-down's exports with those columns only, matched
25
+ * case-insensitively, each once; none that matches (or an empty list): no Source data, and the
26
+ * drill-down's exports go too, since they would hold no column.
27
+ * @param {unknown} exportData
28
+ * @param {string[]} names the data's columns, without derived fields
29
+ * @returns {DataExport}
30
+ */
31
+ export declare function dataExportOf(exportData: unknown, names: string[]): DataExport;
32
+ /**
33
+ * The places of the wanted columns among `names`, in the wanted order, matched case-insensitively as
34
+ * pivotkit-core's exporters match them; a name not there is left out, each column once.
35
+ * @param {string[]} names
36
+ * @param {string[] | undefined} wanted undefined: every column, in its order
37
+ * @returns {number[]}
38
+ */
39
+ export declare function pickColumns(names: string[], wanted: string[] | undefined): number[];
40
+ /**
41
+ * dataExportOf against the data shown (its columns without derived fields), with the host's names
42
+ * that match nothing said once in the console.
43
+ * @param {unknown} exportData
44
+ * @param {import("pivotkit-core").Encoded | null | undefined} encoded
45
+ * @returns {DataExport}
46
+ */
47
+ export declare function dataExportFor(exportData: unknown, encoded: import("pivotkit-core").Encoded | null | undefined): DataExport;
@@ -19,7 +19,8 @@ export type ImportJob = {
19
19
  n: number;
20
20
  sheet?: string;
21
21
  auto?: boolean;
22
- done?: (loaded: boolean, refused?: boolean) => void;
22
+ view?: string;
23
+ done?: (loaded: boolean, refused?: boolean, other?: boolean) => void;
23
24
  };
24
25
  /**
25
26
  * Files picked or dropped: one opens its preview, more than one is said to be too many. The error
@@ -31,13 +32,15 @@ export declare function startFiles(api: ImportApi, files: File[]): void;
31
32
  /**
32
33
  * Reads another sheet of the file shown and loads it at once (a saved view made on that sheet was
33
34
  * 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).
35
+ * says why there. `done` is told whether the sheet was loaded (Cancel, a failure, a host's refusal and
36
+ * another sheet picked in the preview are not).
36
37
  * @param {ImportApi} api
37
38
  * @param {string} sheet
38
- * @param {(loaded: boolean, refused?: boolean) => void} done `refused`: the host refused it (onDataLoad)
39
+ * @param {string} view the name of the view that needs the sheet, for the dialog
40
+ * @param {(loaded: boolean, refused?: boolean, other?: boolean) => void} done `refused`: the host
41
+ * refused it (onDataLoad); `other`: another sheet was picked in the preview and loaded
39
42
  */
40
- export declare function loadSheet(api: ImportApi, sheet: string, done: (loaded: boolean, refused?: boolean) => void): void;
43
+ export declare function loadSheet(api: ImportApi, sheet: string, view: string, done: (loaded: boolean, refused?: boolean, other?: boolean) => void): void;
41
44
  /**
42
45
  * A view that names a sheet (sheet-views.js: sheetPlan): another sheet of the workbook shown is read
43
46
  * first (loadSheet), and `then` runs once its data is shown (the report's `afterData`); a sheet the
@@ -65,10 +65,13 @@ export declare const en: {
65
65
  archiveEntries: string;
66
66
  unpackedBytes: string;
67
67
  };
68
+ workbookCells: string;
68
69
  sourceLine: string;
69
70
  sourceSheet: string;
70
71
  sheetMissing: string;
71
72
  sheetRefused: string;
73
+ sheetForView: string;
74
+ sheetOther: string;
72
75
  notes: {
73
76
  ENCODING: string;
74
77
  SEPARATOR: string;
@@ -192,10 +195,13 @@ export declare const IMPORT_TEXTS: Readonly<{
192
195
  archiveEntries: string;
193
196
  unpackedBytes: string;
194
197
  };
198
+ workbookCells: string;
195
199
  sourceLine: string;
196
200
  sourceSheet: string;
197
201
  sheetMissing: string;
198
202
  sheetRefused: string;
203
+ sheetForView: string;
204
+ sheetOther: string;
199
205
  notes: {
200
206
  ENCODING: string;
201
207
  SEPARATOR: string;
@@ -313,10 +319,13 @@ export declare const IMPORT_TEXTS: Readonly<{
313
319
  archiveEntries: string;
314
320
  unpackedBytes: string;
315
321
  };
322
+ workbookCells: string;
316
323
  sourceLine: string;
317
324
  sourceSheet: string;
318
325
  sheetMissing: string;
319
326
  sheetRefused: string;
327
+ sheetForView: string;
328
+ sheetOther: string;
320
329
  notes: {
321
330
  ENCODING: string;
322
331
  SEPARATOR: string;
@@ -393,9 +402,11 @@ export declare function noteText(note: {
393
402
  }): string;
394
403
  /**
395
404
  * 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`).
405
+ * pivotkit-core (`LIMIT_EXCEEDED` with a limit this version has words for; `importCells` reached
406
+ * by a workbook's shared strings and formats, as `details.what` says, in the words of
407
+ * `workbookCells`) in the report's language with its key (`limits.rows`, whose words fit
408
+ * `importLimits` too), else the reader's own English message without the file's name in front
409
+ * (`"name": ` of `fileError`, `"name" ` of `limitError`).
399
410
  * @param {unknown} error
400
411
  * @param {string} name the file's name
401
412
  * @param {ImportTexts} texts
@@ -14,14 +14,6 @@ export declare function acceptOf(plugins: readonly any[]): string;
14
14
  export declare const formatsOf: (plugins: readonly any[], names?: Record<string, string>) => any[];
15
15
  /** How long a worker may take to say it is ready before the page reads the file itself (ms). */
16
16
  export declare const WORKER_READY_MS = 10000;
17
- /**
18
- * A reader's table as the import UI uses it: what checkTable of pivotkit-core does not ask for, but
19
- * retype and the preview need, filled in from what is there (a plugin may return the minimal shape),
20
- * and notes that are no `{ code, params }` left out.
21
- * @param {any} table
22
- * @returns {import("pivotkit-core/import").ImportTable}
23
- */
24
- export declare function completeTable(table: any): import("pivotkit-core/import").ImportTable;
25
17
  export type ImportRead = {
26
18
  /**
27
19
  * the host's reader plugins
@@ -96,8 +96,10 @@ export type LoadedData = {
96
96
  * the focus moves in, Tab stays inside, Escape cancels, the focus goes back to where it was. A file
97
97
  * that cannot be read closes it with a note; the report's data stays. A job with `sheet` starts on that
98
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,
99
+ * (a saved view opened on another sheet of the file shown: the person asked for that sheet already),
100
+ * unless the reader has notes about it or it has no rows: then the preview stays, as for a file, and
101
+ * says which view needs that sheet (`view`); another sheet picked there never loads by itself.
102
+ * @param {{ job: { file: File, n: number, sheet?: string, auto?: boolean, view?: string }, labels: any, locale: string, plugins: any[], worker?: () => Worker,
101
103
  * limits?: object, timeZone?: string, onApply: (data: LoadedData) => void, onClose: () => void,
102
104
  * announce: (text: string, extra?: { tone?: "error" }) => void }} props
103
105
  */
@@ -107,6 +109,7 @@ export declare function ImportDialog({ job, labels, locale, plugins, worker, lim
107
109
  n: number;
108
110
  sheet?: string;
109
111
  auto?: boolean;
112
+ view?: string;
110
113
  };
111
114
  labels: any;
112
115
  locale: string;
package/types/index.d.ts CHANGED
@@ -274,11 +274,15 @@ export type PivotReportProps = {
274
274
  */
275
275
  onExport?: (file: ExportFile) => unknown;
276
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;
277
+ * the Export menu's "Source data": every row
278
+ * of the data shown, as a CSV or JSON file, for the user's own analysis or the command line.
279
+ * `true`: every column; `{ columns }`: only these, in this order, which the drill-down panel's
280
+ * copies and files keep to as well (none left: both off). Default false: the rows may hold more
281
+ * than the report shows (docs/security.md)
282
+ */
283
+ exportData?: boolean | {
284
+ columns?: string[];
285
+ };
282
286
  /**
283
287
  * the tips above the result: "on" (default), "off"
284
288
  * (none, and no switch in Options), or the ids of the tips allowed (an array, or a comma-separated text)
@@ -563,9 +567,11 @@ export type TipDismiss = {
563
567
  * @property {(file: ExportFile) => unknown} [onExport] every exported file before its download, and
564
568
  * every copy before it goes on the clipboard; returning false skips the download or the copy (the
565
569
  * 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)
570
+ * @property {boolean | { columns?: string[] }} [exportData] the Export menu's "Source data": every row
571
+ * of the data shown, as a CSV or JSON file, for the user's own analysis or the command line.
572
+ * `true`: every column; `{ columns }`: only these, in this order, which the drill-down panel's
573
+ * copies and files keep to as well (none left: both off). Default false: the rows may hold more
574
+ * than the report shows (docs/security.md)
569
575
  * @property {"on" | "off" | string | string[]} [tips] the tips above the result: "on" (default), "off"
570
576
  * (none, and no switch in Options), or the ids of the tips allowed (an array, or a comma-separated text)
571
577
  * @property {string} [storageKey] remembers dismissed tips in localStorage under this key (one per
@@ -40,6 +40,15 @@ export declare function NumberField({ value, onChange, problem, label, testId, c
40
40
  onFocus?: () => void;
41
41
  autoFocus?: boolean;
42
42
  }): React.JSX.Element;
43
+ /**
44
+ * A menu's radio button, focused by a click: WebKit on macOS picks a radio on a click without focusing
45
+ * it, so the focus would land elsewhere after a pick (#148, #203).
46
+ * @param {React.InputHTMLAttributes<HTMLInputElement> & { "data-testid"?: string, "data-autofocus"?: string }} props
47
+ */
48
+ export declare function Radio(props: React.InputHTMLAttributes<HTMLInputElement> & {
49
+ "data-testid"?: string;
50
+ "data-autofocus"?: string;
51
+ }): React.JSX.Element;
43
52
  /**
44
53
  * The keys of a field that applies what is typed: Enter applies now; Escape gives back what applies,
45
54
  * or, when nothing was changed, goes back a level.
@@ -407,3 +407,26 @@ export declare function rowsInRange(range: {
407
407
  from: string | null;
408
408
  to: string;
409
409
  }, dict: ArrayLike<unknown>, counts: ArrayLike<number>): number;
410
+ /**
411
+ * The years Years combined keeps, in the Filter level's summary: "2024–2025 combined" for years in a
412
+ * row (all of them, or a run), else listed; "2026 only" for one; each year as the table writes it.
413
+ * @param {number[]} on the years kept, ascending
414
+ * @param {number[]} all the years of the data
415
+ * @param {any} labels
416
+ * @param {string} locale
417
+ */
418
+ export declare function combinedYearsText(on: number[], all: number[], labels: any, locale: string): string;
419
+ /** Whether the day of `a` (an ISO day or minute) is on or before the day of `b`, by their ms. */
420
+ export declare const dayOnOrBefore: (a: any, b: any) => boolean;
421
+ /**
422
+ * An ISO day (or minute) as an `<input type="date">` holds it: the year with four or more digits and
423
+ * no sign ("10000-01-01" of "+010000-01-01"); "" for a year before 1, which the field cannot hold.
424
+ * @param {string} iso
425
+ */
426
+ export declare const dateInputValue: (iso: string) => string;
427
+ /**
428
+ * What an `<input type="date">` holds as an ISO day ("+010000-01-01" of "10000-01-01"), or null while
429
+ * it is no whole day of a year from 1 that a Date holds.
430
+ * @param {string} text
431
+ */
432
+ export declare function dateFromInput(text: string): string | null;
package/types/menus.d.ts CHANGED
@@ -5,4 +5,4 @@ export { DrillPanel } from "./drill-panel.jsx";
5
5
  export { DataMenu } from "./data-menu.jsx";
6
6
  export { addMenuTexts, hasMenuTexts, menuLabels } from "./menu-labels.js";
7
7
  export { storedViews } from "./view-store.js";
8
- export { prepareExporters, runExport } from "./export-run.js";
8
+ export { prepareExport, runExport } from "./export-run.js";
package/types/names.d.ts CHANGED
@@ -43,9 +43,22 @@ export declare function valueConditionText(view: any, f: {
43
43
  value: number;
44
44
  value2?: number;
45
45
  }, labels: import("./labels.js").UiLabels, locale: string): any;
46
- /** A calendar day ("2022-03-01") as the locale writes a date. */
46
+ /** Wall-clock ms of an ISO day (or of a minute's day). */
47
+ export declare const dayMs: (iso: any) => number;
48
+ /** The year of an ISO day: 2026 of "2026-03-01", -1 of "-000001-01-11". */
49
+ export declare const yearOf: (iso: any) => number;
50
+ /** A year as an ISO day writes it: "0002", "2026", "-000001", "+010000". */
51
+ export declare const isoYear: (y: any) => string;
52
+ /**
53
+ * A year as the table writes it (pivotkit-core's year grouping): "2026", before 1 AD with its era
54
+ * ("2 BC", "2 v. Chr."), always in the Gregorian calendar.
55
+ * @param {number} y astronomical: 0 is 1 BC
56
+ * @param {string} locale
57
+ */
58
+ export declare const yearText: (y: number, locale: string) => string;
59
+ /** A calendar day ("2022-03-01") as the locale writes a date, a year before 1 AD with its era (pivotkit-core's `date` format). */
47
60
  export declare const dayText: (iso: any, locale: any) => string;
48
- /** A calendar day of wall-clock ms ("2022-03-01"), as a date column holds dates. */
61
+ /** A calendar day of wall-clock ms ("2022-03-01", "-000001-01-11"), as a date column holds dates. */
49
62
  export declare const isoDay: (ms: any) => string;
50
63
  /**
51
64
  * The days a relative filter keeps, both included (pivotkit-core's relativeDateRange): counted back
@@ -95,7 +108,7 @@ export declare const plainRange: (f: {
95
108
  export declare function periodText(range: {
96
109
  from: string;
97
110
  to: string;
98
- }, unit: string, locale: string): any;
111
+ }, unit: string, locale: string): string;
99
112
  /**
100
113
  * The days a relative date range keeps, as the unit writes them: "2022–2026" for years, "Dec
101
114
  * 2025–Nov 2026" for months, dates for days; one period alone ("2026"); "" for no range.
@@ -109,7 +122,7 @@ export declare function rangeText(f: {
109
122
  unit: string;
110
123
  count: number;
111
124
  anchor?: string;
112
- }, locale: string, timeZone: string, now?: Date | number | string, latest?: number | null): any;
125
+ }, locale: string, timeZone: string, now?: Date | number | string, latest?: number | null): string;
113
126
  /**
114
127
  * The data's share of a range: which of its days have data and which have none. Null when the data
115
128
  * cover the whole range; `none` when they cover none of it; else the days with data (`data`) and
@@ -160,11 +173,12 @@ export declare function relativeText(f: {
160
173
  max: number;
161
174
  } | null, weekStart?: number): any;
162
175
  /**
163
- * The years two calendar days bound as whole years (Jan 1 to Dec 31), or null: the days a comparison
164
- * on a date grouping's source dates gets from Years combined.
165
- * @returns {[string, string] | null}
176
+ * The years two calendar days bound as whole years (Jan 1 to Dec 31; in the first and last year a
177
+ * Date holds, its first and last day), or null: the days a comparison on a date grouping's source
178
+ * dates gets from Years combined.
179
+ * @returns {[number, number] | null}
166
180
  */
167
- export declare function wholeYears(from: any, to: any): [string, string] | null;
181
+ export declare function wholeYears(from: any, to: any): [number, number] | null;
168
182
  /**
169
183
  * A comparison of the item itself in short: "from 2022", "2022 to 2024" for a date or a date
170
184
  * grouping, "≥ 10" for a number. `labelOf` gives an item's label (a grouping's "Mar 2025").
@@ -15,10 +15,39 @@ export declare function printParts(html: string, parser: DOMParser): {
15
15
  title: string;
16
16
  body: HTMLElement;
17
17
  };
18
+ export type PrintSlot = {
19
+ frame: HTMLIFrameElement;
20
+ loaded: Promise<boolean>;
21
+ isLoaded: boolean;
22
+ };
18
23
  /**
19
- * Prints the report's HTML from a hidden frame in `container`.
20
- * @param {string} html pivotkit-report's HTML (format "html", chartEmbed "inline")
24
+ * Makes an empty frame ready in `container` for the next print, unless one is (the Export menu, when
25
+ * it opens).
26
+ * @param {HTMLElement} container the report's root
27
+ */
28
+ export declare function preparePrintFrame(container: HTMLElement): void;
29
+ /**
30
+ * Removes the ready frame no print took (the Export menu, when it closes).
31
+ * @param {HTMLElement} container
32
+ */
33
+ export declare function releasePrintFrame(container: HTMLElement): void;
34
+ /**
35
+ * Takes the frame for a print, in the click before anything is awaited (so the menu, closing, leaves
36
+ * it): the ready one, or a new one when none is. Every other print frame in `container` goes.
21
37
  * @param {HTMLElement} container the report's root
38
+ * @returns {PrintSlot}
39
+ */
40
+ export declare function takePrintFrame(container: HTMLElement): PrintSlot;
41
+ /**
42
+ * Removes a frame takePrintFrame gave that will not print (the host took the report, or it failed).
43
+ * @param {PrintSlot} slot
44
+ */
45
+ export declare const dropPrintFrame: (slot: PrintSlot) => void;
46
+ /**
47
+ * Prints the report's HTML from a frame takePrintFrame gave: at once when the frame has loaded (in
48
+ * the click), else once it has.
49
+ * @param {string} html pivotkit-report's HTML (format "html", chartEmbed "inline")
50
+ * @param {PrintSlot} slot
22
51
  * @returns {Promise<boolean>} false when the frame could not be used (blocked by the page)
23
52
  */
24
- export declare function printHtml(html: string, container: HTMLElement): Promise<boolean>;
53
+ export declare function printHtml(html: string, slot: PrintSlot): Promise<boolean>;
@@ -6,6 +6,11 @@ export { render };
6
6
  * The chart's lengths in px come from the chart's module (LENGTH_TOKENS).
7
7
  */
8
8
  export declare const REPORT_TOKENS: readonly string[];
9
+ /**
10
+ * The colours of an HTML report on a dark screen, as the report's dark theme resolves them
11
+ * (export-run.js): pivotkit-report's dark colours and a host's middle colour of a colour scale.
12
+ */
13
+ export declare const REPORT_DARK_TOKENS: readonly string[];
9
14
  /**
10
15
  * The HTML report's font sizes, in px as the report resolves them (export-run.js): its text and
11
16
  * secondary text, so the file's text is the size the screen's is, and a host's title and print sizes
@@ -0,0 +1,17 @@
1
+ /**
2
+ * Tokens as the report's `theme` resolves them, in either theme the report shows: the light ones for
3
+ * a workbook and an HTML report (so a host's light colours go into them from a dark report too), the
4
+ * dark ones for the HTML report on a dark screen. A report showing the other theme shows this one for
5
+ * the read, on its root and, inside pivotkit-element, on the element whose :host rules declare the
6
+ * tokens, and its own again in the same task, so nothing is drawn in between; --pk-duration is 0ms
7
+ * meanwhile (on the root, important), so no transition of the report's starts on the way there or
8
+ * back. A host's rules on data-pk-theme="dark" (or "light") are read that way; rules on something
9
+ * else (an html[data-theme] of the page) apply in both. Lengths are resolved by the chart's module
10
+ * (chart-decorate.js, tokenLengths), passed in as `more`, read in that theme too.
11
+ * @param {HTMLElement} root the report's root
12
+ * @param {"light" | "dark"} theme
13
+ * @param {readonly string[]} names
14
+ * @param {() => Record<string, string>} [more] further tokens read while that theme shows
15
+ * @returns {Record<string, string>} the tokens that are set
16
+ */
17
+ export declare function themeTokens(root: HTMLElement, theme: "light" | "dark", names: readonly string[], more?: () => Record<string, string>): Record<string, string>;
@@ -72,9 +72,11 @@ export declare function ViewsPanel({ templates, labels, onLoad, actions, close,
72
72
  }): React.JSX.Element;
73
73
  /**
74
74
  * One entry of an export menu: the option and, when it needs explaining, its "i".
75
- * @param {{ icon: string, text: string, info?: string, onSelect: () => void, testId: string, disabled?: boolean, reason?: string }} props
75
+ * @param {{ icon: string, text: string, info?: string, onSelect: () => void, testId: string, disabled?: boolean, reason?: string, onIntent?: () => void }} props
76
+ * `onIntent`: when the pointer comes to the entry, presses on it or the focus does (an entry with
77
+ * its "i")
76
78
  */
77
- export declare function ExportOption({ icon, text, info, onSelect, testId, disabled, reason }: {
79
+ export declare function ExportOption({ icon, text, info, onSelect, testId, disabled, reason, onIntent }: {
78
80
  icon: string;
79
81
  text: string;
80
82
  info?: string;
@@ -82,15 +84,19 @@ export declare function ExportOption({ icon, text, info, onSelect, testId, disab
82
84
  testId: string;
83
85
  disabled?: boolean;
84
86
  reason?: string;
87
+ onIntent?: () => void;
85
88
  }): React.JSX.Element;
86
89
  /**
87
90
  * The Export menu: the table as a file (Excel, CSV), the chart as an image (PNG, SVG), an HTML report,
88
91
  * printing (or saving as PDF from the print dialog), the table on the clipboard (as shown, or its data
89
92
  * as JSON), and last, when the host turns it on (exportData), the source data: every row as it is,
90
93
  * CSV or JSON, apart from the table's exports so the two are not taken for each other. The export module loads when the menu opens, so a copy happens right in
91
- * the click. An empty report (no field placed) has no table to export: those entries are off, and say
94
+ * the click; so does a print (the print frame is made ready when the menu opens, the report's modules
95
+ * load when Print is pointed at or focused: use-export.js). An empty report (no field placed) has no table to export: those entries are off, and say
92
96
  * so; the source data is there all the same. The chart's images are off while the table is shown.
93
- * @param {{ labels: import("./labels.js").UiLabels, onExport: (kind: string) => void, chartReady: boolean, display: string, empty?: boolean, dataExport?: boolean, prepare: () => void, close: () => void }} props
97
+ * `dataExport`: the host's exportData with the data shown, read by export-scope.js (#259).
98
+ * @param {{ labels: import("./labels.js").UiLabels, onExport: (kind: string) => void, chartReady: boolean, display: string, empty?: boolean,
99
+ * dataExport?: { exportData: unknown, encoded: import("pivotkit-core").Encoded | null }, prepare: (what: "menu" | "print") => (() => void) | undefined, close: () => void }} props
94
100
  */
95
101
  export declare function ExportPanel({ labels, onExport, chartReady, display, empty, dataExport, prepare, close }: {
96
102
  labels: import("./labels.js").UiLabels;
@@ -98,7 +104,10 @@ export declare function ExportPanel({ labels, onExport, chartReady, display, emp
98
104
  chartReady: boolean;
99
105
  display: string;
100
106
  empty?: boolean;
101
- dataExport?: boolean;
102
- prepare: () => void;
107
+ dataExport?: {
108
+ exportData: unknown;
109
+ encoded: import("pivotkit-core").Encoded | null;
110
+ };
111
+ prepare: (what: "menu" | "print") => (() => void) | undefined;
103
112
  close: () => void;
104
113
  }): React.JSX.Element;
@@ -1,7 +1,11 @@
1
1
  /**
2
2
  * @param {import("./export-run.js").ExportContext} context
3
- * @returns {(kind: "xlsx" | "csv" | "png" | "html" | "svg" | "print" | "copy-table" | "copy-json" | "data-csv" | "data-json") => Promise<void>}
3
+ * @returns {{ run: (kind: "xlsx" | "csv" | "png" | "html" | "svg" | "print" | "copy-table" | "copy-json" | "data-csv" | "data-json") => Promise<void>,
4
+ * prepare: (what: "menu" | "print") => (() => void) | undefined }}
5
+ * `prepare`: the Export menu's, when it opens ("menu"; it returns what ends the menu's print frame)
6
+ * and when Print is pointed at or focused ("print"); one function for the report's lifetime
4
7
  */
5
- export declare function useExport(context: import("./export-run.js").ExportContext): (kind: "xlsx" | "csv" | "png" | "html" | "svg" | "print" | "copy-table" | "copy-json" | "data-csv" | "data-json") => Promise<void>;
6
- /** Starts loading the export module when a menu that copies opens: a copy right in the click is allowed everywhere. */
7
- export declare const prepareExporters: () => undefined;
8
+ export declare function useExport(context: import("./export-run.js").ExportContext): {
9
+ run: (kind: "xlsx" | "csv" | "png" | "html" | "svg" | "print" | "copy-table" | "copy-json" | "data-csv" | "data-json") => Promise<void>;
10
+ prepare: (what: "menu" | "print") => (() => void) | undefined;
11
+ };