pivotkit-react 0.7.0 → 0.8.1

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 (55) hide show
  1. package/CHANGELOG.md +191 -1
  2. package/README.md +33 -15
  3. package/dist/chunks/{chunk-JMRTIOX4.js → chunk-2N2UGSIG.js} +7 -0
  4. package/dist/chunks/{chunk-XN5HNKJ2.js → chunk-3WWWKPB4.js} +98 -33
  5. package/dist/chunks/{chunk-ZK5RVCHP.js → chunk-6OWC6X5W.js} +1 -1
  6. package/dist/chunks/{chunk-YXLANLGL.js → chunk-GUSQWPTH.js} +56 -3
  7. package/dist/chunks/{chunk-E6M57YLL.js → chunk-MU5BTKSY.js} +7 -0
  8. package/dist/chunks/{chunk-4WZ5F2TJ.js → chunk-W2SVDHGN.js} +371 -32
  9. package/dist/chunks/{chunk-TR2HROIK.js → chunk-ZM45YU3W.js} +66 -5
  10. package/dist/chunks/{unused-texts-Y4R67XSN.js → unused-texts-LRYVWFFN.js} +1 -1
  11. package/dist/chunks/{unused-texts-de-6YVPTNVS.js → unused-texts-de-GB3IWWEM.js} +1 -1
  12. package/dist/echarts.js +426 -35
  13. package/dist/import-ui.js +2 -2
  14. package/dist/index.js +728 -393
  15. package/dist/labels.js +6 -6
  16. package/dist/menu-texts-de.js +1 -1
  17. package/dist/menus.js +1534 -1020
  18. package/dist/styles.css +292 -171
  19. package/package.json +3 -3
  20. package/types/PivotReport.d.ts +6 -0
  21. package/types/add-menu.d.ts +48 -0
  22. package/types/chart-colors.d.ts +8 -0
  23. package/types/chart-decorate.d.ts +66 -3
  24. package/types/chart-legend.d.ts +176 -0
  25. package/types/chart-summary.d.ts +8 -3
  26. package/types/chart-tooltip.d.ts +159 -17
  27. package/types/chart.d.ts +21 -3
  28. package/types/date-context.d.ts +30 -0
  29. package/types/drill-panel.d.ts +4 -2
  30. package/types/echarts.d.ts +7 -3
  31. package/types/export-run.d.ts +7 -14
  32. package/types/export-scope.d.ts +13 -2
  33. package/types/field-info.d.ts +12 -0
  34. package/types/files.d.ts +14 -0
  35. package/types/filter.d.ts +18 -0
  36. package/types/group-context.d.ts +20 -0
  37. package/types/index.d.ts +35 -6
  38. package/types/label-room.d.ts +13 -0
  39. package/types/labels.d.ts +85 -16
  40. package/types/lazy-menus.d.ts +2 -2
  41. package/types/levels.d.ts +16 -7
  42. package/types/menu-labels.d.ts +67 -1
  43. package/types/menu-ops.d.ts +10 -0
  44. package/types/menu-topics.d.ts +110 -21
  45. package/types/menus.d.ts +2 -1
  46. package/types/names.d.ts +32 -3
  47. package/types/overflow.d.ts +18 -30
  48. package/types/rove.d.ts +10 -0
  49. package/types/toolbar-panels.d.ts +34 -10
  50. package/types/unused-texts.d.ts +7 -0
  51. package/types/use-big-result.d.ts +24 -9
  52. package/types/use-export.d.ts +2 -2
  53. package/types/view-ops.d.ts +19 -8
  54. package/types/view-tabs.d.ts +12 -0
  55. package/types/zones.d.ts +41 -9
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pivotkit-react",
3
- "version": "0.7.0",
3
+ "version": "0.8.1",
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>",
@@ -68,8 +68,8 @@
68
68
  "dependencies": {
69
69
  "@dnd-kit/core": "6.3.1",
70
70
  "@dnd-kit/sortable": "10.0.0",
71
- "pivotkit-core": "^0.7.0",
72
- "pivotkit-report": "^0.3.0"
71
+ "pivotkit-core": "^0.8.0",
72
+ "pivotkit-report": "^0.4.0"
73
73
  },
74
74
  "devDependencies": {
75
75
  "echarts": "6.1.0"
@@ -9,6 +9,12 @@ export declare const COMPACT_HEIGHT = 600;
9
9
  export declare const COMPACT_HEIGHT_NARROW = 820;
10
10
  /** Whether a report of this width class and height starts compact. */
11
11
  export declare const compactAt: (size: any, height: any) => boolean;
12
+ /**
13
+ * The zones' start state from the host's `zones`: folded (true), open (false), or null, the report's
14
+ * height decides (compactAt). Any other value is null too.
15
+ * @param {unknown} zones
16
+ */
17
+ export declare const zonesStart: (zones: unknown) => boolean | null;
12
18
  /** Rows above which the report shows its skeleton first and encodes the data in the next frame. */
13
19
  export declare const DEFER_ROWS = 10000;
14
20
  /**
@@ -0,0 +1,48 @@
1
+ import React from "react";
2
+ /**
3
+ * Where a field is now that a pick for `zone` would take it from (null: nowhere, or it stays there
4
+ * too), and whether the pick would change nothing. `name` is what the pick places (a date's grouping).
5
+ * @param {any} view
6
+ * @param {string} zone
7
+ * @param {string} name
8
+ * @returns {{ from: string | null, already: boolean }}
9
+ */
10
+ export declare function addEffect(view: any, zone: string, name: string): {
11
+ from: string | null;
12
+ already: boolean;
13
+ };
14
+ /**
15
+ * @param {{ zone: string, view: any, fields: Array<{ name: string, type: string }>, placed: Map<string, string[]>,
16
+ * nameOf: (field: string) => string, info: Map<string, import("./field-info.js").FieldInfo>, labels: any,
17
+ * close: () => void, placeName: (field: string, zone: string) => string, onAdd: (field: string, zone: string) => boolean,
18
+ * filterDraft: (field: string) => { field: string, base: object | undefined }, onAdded: (from: string | null, run: () => boolean) => void,
19
+ * commit: (view: object, note?: any) => boolean, encoded: import("pivotkit-core").Encoded, locale: string,
20
+ * fullText: (zone: string, count: number) => string | null }} props
21
+ * `placeName`: what a pick places (a date's grouping); `onAdded`: says where a field came from before
22
+ * `run` places it (the zones then focus its chip and say so); `fullText`: why a zone with `count`
23
+ * entries takes no more, or null
24
+ */
25
+ export declare function AddMenu({ zone, view, fields, placed, nameOf, info, labels, close, placeName, onAdd, filterDraft, onAdded, commit, encoded, locale, fullText }: {
26
+ zone: string;
27
+ view: any;
28
+ fields: Array<{
29
+ name: string;
30
+ type: string;
31
+ }>;
32
+ placed: Map<string, string[]>;
33
+ nameOf: (field: string) => string;
34
+ info: Map<string, import("./field-info.js").FieldInfo>;
35
+ labels: any;
36
+ close: () => void;
37
+ placeName: (field: string, zone: string) => string;
38
+ onAdd: (field: string, zone: string) => boolean;
39
+ filterDraft: (field: string) => {
40
+ field: string;
41
+ base: object | undefined;
42
+ };
43
+ onAdded: (from: string | null, run: () => boolean) => void;
44
+ commit: (view: object, note?: any) => boolean;
45
+ encoded: import("pivotkit-core").Encoded;
46
+ locale: string;
47
+ fullText: (zone: string, count: number) => string | null;
48
+ }): React.JSX.Element;
@@ -0,0 +1,8 @@
1
+ /**
2
+ * The host's colorMap with one colour per name for `theme`: a text as it is, a list of two the first
3
+ * for light and the second for dark. Other values are left out.
4
+ * @param {unknown} map the host's colorMap, `{ [name]: color | [light, dark] }`
5
+ * @param {string} theme "light" or "dark", as the report shows
6
+ * @returns {Record<string, string> | undefined}
7
+ */
8
+ export declare function colorMapFor(map: unknown, theme: string): Record<string, string> | undefined;
@@ -4,8 +4,13 @@
4
4
  * @param {number} [height] the chart's height in px, for the room around a pie
5
5
  * @param {Document} [doc] the chart's document, for the tooltip's nodes
6
6
  * @param {number} [width] the chart's width in px, for the column names of a heatmap and the category axis
7
- * @param {{ categoryNames?: string[], axisLabels?: string }} [extra] the categories' whole names (the
8
- * tooltip's title when the axis writes them shorter) and the view's chart.axisLabels
7
+ * @param {{ categoryNames?: string[], axisLabels?: string, zoom?: string, zoomAt?: { start: number, end: number }, timeline?: boolean, touch?: boolean, pixelOf?: (value: number) => number, parseColor?: (color: string) => unknown, tooltip?: { mode?: string, share?: boolean, hover?: { current: { seriesIndex: number, dataIndex: number } | null }, totalLabel?: string, moreLabel?: string, moreInTotalLabel?: string, values?: Array<{ agg?: string, showAs?: { type: string, axis?: string } | null } | undefined>, lines?: ReturnType<typeof import("pivotkit-core/chart").referenceLines> } }} [extra]
8
+ * the categories' whole names (the tooltip's title when the axis writes them shorter), the view's
9
+ * chart.axisLabels and chart.zoom (the slider, pivotkit-core's chart-zoom.js); tooltip: the view's chart.tooltip and chart.tooltipShare, the chart's hover state (chart.jsx writes the
10
+ * element under the pointer into `current`, the formatter reads it), the name of a stack's total,
11
+ * the lines that say how many series were cut, each series' value (whether it adds up) and the
12
+ * chart's reference lines (pivotkit-core's referenceLines), named at the category;
13
+ * parseColor: ECharts' colour parser, for a heatmap's colours (screenColor)
9
14
  * @returns {any} the option; `axisEvery` (not ECharts') is n when the category axis writes every n-th label
10
15
  */
11
16
  export declare function decorate(option: any, style: {
@@ -13,10 +18,68 @@ export declare function decorate(option: any, style: {
13
18
  }, height?: number, doc?: Document, width?: number, extra?: {
14
19
  categoryNames?: string[];
15
20
  axisLabels?: string;
21
+ zoom?: string;
22
+ zoomAt?: {
23
+ start: number;
24
+ end: number;
25
+ };
26
+ timeline?: boolean;
27
+ touch?: boolean;
28
+ pixelOf?: (value: number) => number;
29
+ parseColor?: (color: string) => unknown;
30
+ tooltip?: {
31
+ mode?: string;
32
+ share?: boolean;
33
+ hover?: {
34
+ current: {
35
+ seriesIndex: number;
36
+ dataIndex: number;
37
+ } | null;
38
+ };
39
+ totalLabel?: string;
40
+ moreLabel?: string;
41
+ moreInTotalLabel?: string;
42
+ values?: Array<{
43
+ agg?: string;
44
+ showAs?: {
45
+ type: string;
46
+ axis?: string;
47
+ } | null;
48
+ } | undefined>;
49
+ lines?: ReturnType<typeof import("pivotkit-core/chart").referenceLines>;
50
+ };
16
51
  }): any;
52
+ /**
53
+ * Draws the view's option on the chart: the report's marks (decorate), the host's chartOptions over
54
+ * them (`hostOptions`, checked, mergeChartOptions), and then the labels of lying reference lines
55
+ * placed at their lines' real heights: after the first draw ECharts knows where each value is
56
+ * (convertToPixel), so the marks are laid out again with it (pivotkit-core's decorateOption,
57
+ * pixelOf) and only the series are set again.
58
+ * @param {any} instance the chart's ECharts instance
59
+ * @param {any} option pivotkit-core's toEChartsOption
60
+ * @param {{ getPropertyValue(name: string): string }} style
61
+ * @param {Document} doc
62
+ * @param {Parameters<typeof decorate>[5]} extra
63
+ * @param {Record<string, unknown> | null | undefined} hostOptions
64
+ * @returns {any} the report's option as first drawn, before the host's: its `axisEvery` and `dataZoom`
65
+ */
66
+ export declare function drawOption(instance: any, option: any, style: {
67
+ getPropertyValue(name: string): string;
68
+ }, doc: Document, extra: Parameters<typeof decorate>[5], hostOptions: Record<string, unknown> | null | undefined): any;
69
+ /**
70
+ * A heatmap colour as ECharts can mix it (pivotkit-core's decorateOption, readColor): a colour ECharts'
71
+ * parser reads stays as it is; any other the browser draws (oklch(), rgb() with spaces) is read back
72
+ * from one pixel of a canvas as #rrggbb, so the screen shows the host's colour; null for a text that
73
+ * is no colour, or one the canvas does not take. The pixel is sRGB without alpha: a P3 colour is
74
+ * clipped and a transparent one drawn opaque.
75
+ * @param {Document} doc
76
+ * @param {(color: string) => unknown} parse ECharts' colour parser
77
+ * @returns {(color: string) => string | null}
78
+ */
79
+ export declare function screenColor(doc: Document, parse: (color: string) => unknown): (color: string) => string | null;
17
80
  /**
18
81
  * 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
82
+ * other text's size, the marks' corners, the zoom slider's thickness (a control's, a finger's). A computed custom property keeps the calc(), max() and em it
20
83
  * was written with, so the report resolves them first.
21
84
  */
22
85
  export declare const LENGTH_TOKENS: readonly string[];
@@ -0,0 +1,176 @@
1
+ /** How long the zoom slider rests before a window of another size lays its labels out again, in ms. */
2
+ export declare const RELAYOUT_WAIT = 250;
3
+ export type ZoomWindow = {
4
+ names: readonly string[];
5
+ start: number;
6
+ end: number;
7
+ };
8
+ /**
9
+ * @typedef {{ names: readonly string[], start: number, end: number }} ZoomWindow
10
+ * the categories the window was moved over, and its first and last one by index
11
+ */
12
+ /**
13
+ * The window kept from the last draw, for pivotkit-core's decorateOption (`zoomAt`): only while the
14
+ * same categories are drawn in the same order; other categories start where decorateOption starts them.
15
+ * @param {ZoomWindow | null} kept
16
+ * @param {readonly string[]} names the categories drawn now
17
+ * @returns {{ start: number, end: number } | undefined}
18
+ */
19
+ export declare function keptWindow(kept: ZoomWindow | null, names: readonly string[]): {
20
+ start: number;
21
+ end: number;
22
+ } | undefined;
23
+ /**
24
+ * Follows a click on the legend and the zoom slider of an ECharts instance.
25
+ * @param {any} instance
26
+ * @param {{ onLegend: (change: { name: string, shown: boolean }) => void, onZoom: (start: number, end: number) => void }} on
27
+ * onLegend: an entry is shown or hidden now; onZoom: the slider's window, first and last category by index
28
+ */
29
+ export declare function followChart(instance: any, { onLegend, onZoom }: {
30
+ onLegend: (change: {
31
+ name: string;
32
+ shown: boolean;
33
+ }) => void;
34
+ onZoom: (start: number, end: number) => void;
35
+ }): void;
36
+ export type ZoomControl = {
37
+ start: number;
38
+ end: number;
39
+ count: number;
40
+ beside: boolean;
41
+ offset: number;
42
+ size: number;
43
+ move: (start: number, end: number) => void;
44
+ };
45
+ /**
46
+ * @typedef {{ start: number, end: number, count: number, beside: boolean, offset: number, size: number,
47
+ * move: (start: number, end: number) => void }} ZoomControl the slider's window, where it is, and how to move it
48
+ */
49
+ /**
50
+ * Follows the legend and the zoom slider of a chart (followChart) and keeps the slider's window.
51
+ * @param {any} instance the chart's ECharts instance
52
+ * @param {{ categories: () => readonly string[] | undefined, onLegend: (change: { name: string, shown: boolean }) => void, redraw: () => void,
53
+ * onWindow: (control: ZoomControl | null) => void }} on
54
+ * categories: the categories drawn now; redraw: draws the chart again (a window of another size);
55
+ * onWindow: the slider's window and place as they change (zoomKeyProps draws its keyboard control
56
+ * from it), null without a slider
57
+ */
58
+ export declare function chartKeeper(instance: any, { categories, onLegend, redraw, onWindow }: {
59
+ categories: () => readonly string[] | undefined;
60
+ onLegend: (change: {
61
+ name: string;
62
+ shown: boolean;
63
+ }) => void;
64
+ redraw: () => void;
65
+ onWindow: (control: ZoomControl | null) => void;
66
+ }): {
67
+ /**
68
+ * decorateOption's zoom settings: the view's chart.zoom, the window kept, the latest categories
69
+ * first over dates (a date on Rows), a finger's slider on a touch screen
70
+ * @param {import("pivotkit-core").PivotResult} result
71
+ * @param {readonly string[]} names
72
+ * @param {Document} doc
73
+ */
74
+ zoomOf: (result: import("pivotkit-core").PivotResult, names: readonly string[], doc: Document) => {
75
+ zoom: string;
76
+ zoomAt: {
77
+ start: number;
78
+ end: number;
79
+ } | undefined;
80
+ timeline: boolean;
81
+ touch: boolean;
82
+ };
83
+ /**
84
+ * The slider drawn: its window's size, to tell a move from a new size, and its keyboard control.
85
+ * @param {any[] | undefined} dataZoom decorateOption's
86
+ */
87
+ drawn: (dataZoom: any[] | undefined) => void;
88
+ dispose: () => void;
89
+ };
90
+ /**
91
+ * What the chart's text alternative counts (chart-summary.js): the series shown, without the legend
92
+ * entries hidden (series, or for a pie and a donut categories), and whether it is a 100 % stack (its
93
+ * parts carry their value as `raw`, pivotkit-core's chart.js).
94
+ * @param {ReturnType<typeof import("pivotkit-core").toSeries>} s
95
+ * @param {any} option toEChartsOption's
96
+ * @param {readonly string[] | undefined} hidden the view's chart.hidden
97
+ * @param {boolean} slices a pie or a donut
98
+ */
99
+ export declare function shownOf(s: ReturnType<typeof import("pivotkit-core").toSeries>, option: any, hidden: readonly string[] | undefined, slices: boolean): {
100
+ series: {
101
+ categories: string[];
102
+ categoryLevels: any[][];
103
+ categoryCount: number;
104
+ categoryPaths: (string | number | boolean)[][];
105
+ series: any[];
106
+ totals: number[][];
107
+ };
108
+ shares: any;
109
+ };
110
+ /**
111
+ * The chart data as it is shown: without the legend entries hidden (chart.hidden), series or, for a
112
+ * pie and a donut, categories.
113
+ * @param {ReturnType<typeof import("pivotkit-core").toSeries>} s
114
+ * @param {readonly string[]} hidden
115
+ * @param {boolean} slices
116
+ */
117
+ export declare function shownOnly(s: ReturnType<typeof import("pivotkit-core").toSeries>, hidden: readonly string[], slices: boolean): {
118
+ categories: string[];
119
+ categoryLevels: any[][];
120
+ categoryCount: number;
121
+ categoryPaths: (string | number | boolean)[][];
122
+ series: any[];
123
+ totals: number[][];
124
+ };
125
+ /** Keys that move the window forward (right, or down the categories of horizontal bars) and back. */
126
+ export declare const FORWARD: Set<string>;
127
+ export declare const BACK: Set<string>;
128
+ /**
129
+ * The window after a key, or null for a key that does not change it:
130
+ * - an arrow moves it by one category; Page Up and Page Down by its own size
131
+ * - Shift with an arrow makes it one category larger (forward) or smaller (back), at least two
132
+ * - Home and End move it to the first and the last categories
133
+ * @param {{ start: number, end: number }} at the first and last category shown, by index
134
+ * @param {number} count the categories
135
+ * @param {string} key
136
+ * @param {boolean} shift
137
+ * @returns {{ start: number, end: number } | null}
138
+ */
139
+ export declare function nextWindow({ start, end }: {
140
+ start: number;
141
+ end: number;
142
+ }, count: number, key: string, shift: boolean): {
143
+ start: number;
144
+ end: number;
145
+ } | null;
146
+ /**
147
+ * The zoom slider by keyboard (#575): ECharts draws its slider on the canvas, which takes no focus.
148
+ * An element of our own lies over the slider's row: a focusable ARIA slider that moves and resizes
149
+ * the window with the keys (nextWindow), says which categories it shows, and draws the focus ring. It
150
+ * takes no pointer input (styles.css), so the mouse and a finger still reach ECharts' slider below.
151
+ * These are its props; the chart draws it as a plain element, so this chunk needs no React.
152
+ * Its value is the window's first category: from 1 to the last place the window can start
153
+ * (`count - span`). A vertical slider (horizontal bars) runs as the axis does, the first category at
154
+ * the top, so Up shows earlier categories and lowers the value, as the order on the screen reads.
155
+ * @param {ZoomControl} control
156
+ * @param {{ chartZoom: string, chartZoomWindow: string }} labels
157
+ * @param {(text: string, values: Record<string, string>) => string} fill labels.js's
158
+ * @param {string} [locale]
159
+ */
160
+ export declare function zoomKeyProps({ start, end, count, beside, offset, size, move }: ZoomControl, labels: {
161
+ chartZoom: string;
162
+ chartZoomWindow: string;
163
+ }, fill: (text: string, values: Record<string, string>) => string, locale?: string): {
164
+ ref: (/** @type {HTMLElement | null} */ el: HTMLElement | null) => void;
165
+ role: string;
166
+ tabIndex: number;
167
+ className: string;
168
+ "aria-label": string;
169
+ "aria-orientation": "vertical" | "horizontal";
170
+ "aria-valuemin": number;
171
+ "aria-valuemax": number;
172
+ "aria-valuenow": number;
173
+ "aria-valuetext": string;
174
+ "data-testid": string;
175
+ onKeyDown: (/** @type {KeyboardEvent} */ e: KeyboardEvent) => void;
176
+ };
@@ -1,12 +1,17 @@
1
1
  /**
2
- * "Bars: Sum of Revenue by Region. 4 categories, 3 series. Highest 1,234 at North / A; lowest ..."
2
+ * "Bars: Sum of Revenue by Region. 4 categories, 3 series. Highest 1,234 at North / A; lowest ...
3
+ * Reference lines: Average 617; Target 1,000."
4
+ * `s`: the series shown (chart-legend.js shownOf leaves hidden ones out); `shares`: a 100 % stack, said so.
3
5
  * @param {ReturnType<typeof import("pivotkit-core").toSeries>} s
4
- * @param {{ type: string, rows: string[], valueNames: string[], labels: import("./labels.js").UiLabels, locale: string }} options
6
+ * @param {{ type: string, rows: string[], valueNames: string[], labels: import("./labels.js").UiLabels, locale: string, shares?: boolean, linesText?: string }} options
7
+ * linesText: the sentence on the reference lines (chart-tooltip.js linesSummary, loaded with the chart)
5
8
  */
6
- export declare function chartSummary(s: ReturnType<typeof import("pivotkit-core").toSeries>, { type, rows, valueNames, labels, locale }: {
9
+ export declare function chartSummary(s: ReturnType<typeof import("pivotkit-core").toSeries>, { type, rows, valueNames, labels, locale, shares, linesText }: {
7
10
  type: string;
8
11
  rows: string[];
9
12
  valueNames: string[];
10
13
  labels: import("./labels.js").UiLabels;
11
14
  locale: string;
15
+ shares?: boolean;
16
+ linesText?: string;
12
17
  }): string;
@@ -1,3 +1,6 @@
1
+ import { referenceLineChecks, referenceLines } from "pivotkit-core/chart";
2
+ import { valueAddsUp } from "pivotkit-core";
3
+ export { valueAddsUp };
1
4
  export type TooltipLine = {
2
5
  /**
3
6
  * the series' or slice's colour, null when it is not a plain colour
@@ -5,34 +8,173 @@ export type TooltipLine = {
5
8
  color: string | null;
6
9
  name: string;
7
10
  value: string;
11
+ /**
12
+ * the element under the pointer, among other lines
13
+ */
14
+ hovered?: boolean;
15
+ /**
16
+ * its share: of the total (chart.tooltipShare), or of its 100 % stack
17
+ */
18
+ share?: string;
8
19
  };
9
- /**
10
- * @typedef {object} TooltipLine
11
- * @property {string | null} color the series' or slice's colour, null when it is not a plain colour
12
- * @property {string} name
13
- * @property {string} value
14
- */
15
- /**
16
- * What a tooltip shows for ECharts' formatter parameters: a title and one line per series or slice.
17
- * @param {any} params one item (trigger "item") or a list (trigger "axis")
18
- * @param {{ valueFormatter?: (v: unknown) => string, xNames?: string[], yNames?: string[], categoryNames?: string[] }} [options]
19
- * valueFormatter: the core's; xNames, yNames: the categories of a heatmap's axes; categoryNames: the
20
- * whole name of each category, for an axis that writes them shorter (cut, or without their group)
21
- * @returns {{ title: string, lines: TooltipLine[] }}
22
- */
23
- export declare function tooltipContent(params: any, { valueFormatter, xNames, yNames, categoryNames }?: {
20
+ export type TooltipReference = {
21
+ /**
22
+ * "Average", "Average (A)" when the chart has more than one series
23
+ */
24
+ name: string;
25
+ /**
26
+ * the series it belongs to; null for a target or a stack's total
27
+ */
28
+ series: number | null;
29
+ /**
30
+ * for a line of no series; a series' line takes its series' colour
31
+ */
32
+ color: string | null;
33
+ /**
34
+ * its value at a category, null where it has none
35
+ */
36
+ value: (dataIndex: number) => string | null;
37
+ };
38
+ export type TooltipOptions = {
39
+ /**
40
+ * the core's
41
+ */
24
42
  valueFormatter?: (v: unknown) => string;
43
+ /**
44
+ * the core's: a share in percent as the locale writes it
45
+ */
46
+ shareFormatter?: (v: number) => string;
47
+ /**
48
+ * chart.tooltipShare: each line with its share of the total
49
+ */
50
+ share?: boolean;
51
+ /**
52
+ * each series' total over the categories: the share of a chart with one series
53
+ */
54
+ seriesTotals?: number[];
55
+ /**
56
+ * a heatmap's column names
57
+ */
25
58
  xNames?: string[];
59
+ /**
60
+ * a heatmap's row names
61
+ */
26
62
  yNames?: string[];
63
+ /**
64
+ * each category's whole name, for an axis that writes them shorter
65
+ */
27
66
  categoryNames?: string[];
67
+ /**
68
+ * chart.tooltip: "auto" (the element under the pointer wins) or "axis"
69
+ * (every series at the category)
70
+ */
71
+ mode?: string;
72
+ /**
73
+ * each series' type,
74
+ * stack and whether its values add up (additive false: an average, a median; no total then)
75
+ */
76
+ series?: Array<{
77
+ type?: string;
78
+ stack?: string;
79
+ additive?: boolean;
80
+ }>;
81
+ /**
82
+ * the element under the pointer
83
+ */
84
+ hover?: {
85
+ seriesIndex: number;
86
+ dataIndex: number;
87
+ } | null;
88
+ /**
89
+ * the name of a stack's total
90
+ */
91
+ totalLabel?: string;
92
+ /**
93
+ * the most series lines that fit; more are cut, with `moreLabel`
94
+ */
95
+ maxLines?: number;
96
+ /**
97
+ * "+{count} more": the line that says how many were cut
98
+ */
99
+ moreLabel?: string;
100
+ /**
101
+ * the same line when a total is shown: the cut ones are in it
102
+ */
103
+ moreInTotalLabel?: string;
104
+ /**
105
+ * the chart's reference lines (tooltipReferences)
106
+ */
107
+ references?: TooltipReference[];
108
+ };
109
+ /**
110
+ * The reference lines in the chart's text alternative (chart-summary.js), named as the tooltip names
111
+ * them: "Reference lines: Average 25; Trend from 10 to 40; Target 35." Empty without lines.
112
+ * @param {ReturnType<typeof import("pivotkit-core/chart").referenceLines>} lines pivotkit-core's referenceLines
113
+ * @param {string[]} seriesNames the chart's series, by index
114
+ * @param {{ chartLines: string, chartTrendSpan: string }} labels
115
+ */
116
+ export declare function linesSummary(lines: ReturnType<typeof import("pivotkit-core/chart").referenceLines>, seriesNames: string[], labels: {
117
+ chartLines: string;
118
+ chartTrendSpan: string;
119
+ }): string;
120
+ /**
121
+ * A drawn chart's reference lines (chart.jsx): the lines as numbers for the tooltip, their sentence
122
+ * for the text alternative (linesSummary) and which ones the chart can draw, with the first series'
123
+ * format (pivotkit-core's referenceLineChecks), for the Display menu.
124
+ * @param {import("pivotkit-core").PivotResult} result
125
+ * @param {{ series: ReturnType<typeof import("pivotkit-core").toSeries>, chart?: { type: string, stacked: boolean, horizontal: boolean } | null, labels: any, locale: string }} options
126
+ * @returns {{ lines: ReturnType<typeof referenceLines>, text: string, checks: ReturnType<typeof referenceLineChecks> & { format?: string } }}
127
+ */
128
+ export declare function chartLines(result: import("pivotkit-core").PivotResult, { series, chart, labels, locale }: {
129
+ series: ReturnType<typeof import("pivotkit-core").toSeries>;
130
+ chart?: {
131
+ type: string;
132
+ stacked: boolean;
133
+ horizontal: boolean;
134
+ } | null;
135
+ labels: any;
136
+ locale: string;
28
137
  }): {
138
+ lines: ReturnType<typeof referenceLines>;
139
+ text: string;
140
+ checks: ReturnType<typeof referenceLineChecks> & {
141
+ format?: string;
142
+ };
143
+ };
144
+ /**
145
+ * The reference lines as the tooltip names them: a series' line by its name and the series' name
146
+ * when there is more than one series ("Average (A)"); a trend's value at a category between its
147
+ * first and last, an average's and a target's everywhere.
148
+ * @param {ReturnType<typeof import("pivotkit-core/chart").referenceLines>} lines pivotkit-core's referenceLines
149
+ * @param {string[]} seriesNames the chart's series, by index
150
+ * @param {string | null} color the colour of a line of no series (--pk-chart-reference)
151
+ * @returns {TooltipReference[]}
152
+ */
153
+ export declare function tooltipReferences(lines: ReturnType<typeof import("pivotkit-core/chart").referenceLines>, seriesNames: string[], color: string | null): TooltipReference[];
154
+ /**
155
+ * What a tooltip shows for ECharts' formatter parameters: a title, one line per series or slice and,
156
+ * for a stack, its total; on bars, lines and areas the reference lines at the category.
157
+ * @param {any} params one item (trigger "item") or a list (trigger "axis")
158
+ * @param {TooltipOptions} [options]
159
+ * @returns {{ title: string, lines: TooltipLine[], more?: string, total?: { name: string, value: string }, references?: TooltipLine[] }}
160
+ */
161
+ export declare function tooltipContent(params: any, { valueFormatter, shareFormatter, share, seriesTotals, xNames, yNames, categoryNames, mode, series, hover, totalLabel, maxLines, moreLabel, moreInTotalLabel, references }?: TooltipOptions): {
29
162
  title: string;
30
163
  lines: TooltipLine[];
164
+ more?: string;
165
+ total?: {
166
+ name: string;
167
+ value: string;
168
+ };
169
+ references?: TooltipLine[];
31
170
  };
32
171
  /**
33
172
  * A tooltip formatter for ECharts that returns DOM nodes (see the top of this module).
34
173
  * @param {Document} doc the chart's document
35
- * @param {Parameters<typeof tooltipContent>[1]} options
174
+ * @param {TooltipOptions & { hoverOf?: () => TooltipOptions["hover"] }} options hoverOf: the element
175
+ * under the pointer when ECharts asks (the chart's hover state), instead of a fixed `hover`
36
176
  * @returns {(params: any) => HTMLElement}
37
177
  */
38
- export declare function tooltipFormatter(doc: Document, options: Parameters<typeof tooltipContent>[1]): (params: any) => HTMLElement;
178
+ export declare function tooltipFormatter(doc: Document, { hoverOf, ...options }: TooltipOptions & {
179
+ hoverOf?: () => TooltipOptions["hover"];
180
+ }): (params: any) => HTMLElement;
package/types/chart.d.ts CHANGED
@@ -6,13 +6,19 @@ export declare function loadECharts(): Promise<any>;
6
6
  * labels: import("./labels.js").UiLabels, locale: string,
7
7
  * themeName: string, root: React.RefObject<HTMLElement>, onInstance: (chart: any) => void,
8
8
  * onPoint: (point: { rowPath: any[], colPath: any[], valueIndex: number, value: unknown }) => void,
9
- * valueNames: string[], chartOptions?: Record<string, unknown> | null,
9
+ * onLines?: (checks: { average: boolean, trend: boolean, target: boolean, notes: string[], format?: string } | null) => void,
10
+ * onLegend?: (change: { name: string, shown: boolean }) => void,
11
+ * valueNames: string[], chartOptions?: Record<string, unknown> | null, colorMap?: unknown,
10
12
  * plan?: { name: string, chart: { type: string, stacked: boolean, horizontal: boolean } } }} props
11
13
  * `series`: pivotkit-core's toSeries with MAX_CATEGORIES, null when there is nothing to draw;
12
14
  * `chartOptions`: the host's plain JSON (chart-options.js, checked), merged over everything else;
13
- * `plan`: what to draw (chart-types.js chartPlan), the view's type resolved when it is "auto"
15
+ * `colorMap`: the host's colour per series or slice name, one or one per theme (chart-colors.js);
16
+ * `plan`: what to draw (chart-types.js chartPlan), the view's type resolved when it is "auto";
17
+ * `onLines`: which reference lines the drawn chart can draw (pivotkit-core's referenceLineChecks,
18
+ * with the first series' format), null when none is drawn;
19
+ * `onLegend`: a legend entry was clicked, and is shown or hidden now
14
20
  */
15
- export declare function PivotChart({ result, series, labels, locale, themeName, root, onInstance, onPoint, valueNames, chartOptions, plan }: {
21
+ export declare function PivotChart({ result, series, labels, locale, themeName, root, onInstance, onPoint, onLines, onLegend, valueNames, chartOptions, colorMap, plan }: {
16
22
  result: import("pivotkit-core").PivotResult;
17
23
  series: ReturnType<typeof import("pivotkit-core").toSeries> | null;
18
24
  labels: import("./labels.js").UiLabels;
@@ -26,8 +32,20 @@ export declare function PivotChart({ result, series, labels, locale, themeName,
26
32
  valueIndex: number;
27
33
  value: unknown;
28
34
  }) => void;
35
+ onLines?: (checks: {
36
+ average: boolean;
37
+ trend: boolean;
38
+ target: boolean;
39
+ notes: string[];
40
+ format?: string;
41
+ } | null) => void;
42
+ onLegend?: (change: {
43
+ name: string;
44
+ shown: boolean;
45
+ }) => void;
29
46
  valueNames: string[];
30
47
  chartOptions?: Record<string, unknown> | null;
48
+ colorMap?: unknown;
31
49
  plan?: {
32
50
  name: string;
33
51
  chart: {
@@ -0,0 +1,30 @@
1
+ /** @param {string} locale @param {Intl.DateTimeFormatOptions} options */
2
+ export declare function dateFormatter(locale: string, options: Intl.DateTimeFormatOptions): Intl.DateTimeFormat;
3
+ /** Safe locale for display-only metadata, independent of pivot success.
4
+ * Invalid input still reaches computePivot's controlled error path.
5
+ * @param {string} locale */
6
+ export declare function dateDisplayLocale(locale: string): string;
7
+ /** @param {{min: number, max: number} | null} span @param {string} locale */
8
+ export declare function dateRangeText(span: {
9
+ min: number;
10
+ max: number;
11
+ } | null, locale: string): string;
12
+ /** Up to 32 distinct observed years after filters, never the interval between endpoints.
13
+ * @param {import("pivotkit-core").PivotResult} result @param {string} field */
14
+ export declare function yearsOf(result: import("pivotkit-core").PivotResult, field: string): any[];
15
+ /** List only years actually included, coalescing consecutive runs.
16
+ * @param {number[]} years @param {string} [locale] */
17
+ export declare function yearSetText(years: number[], locale?: string): string;
18
+ /** @param {import("pivotkit-core").PivotResult | null} result @param {import("./labels.js").UiLabels} labels
19
+ * `titles`: a grouping's title with its years, by the grouping's name (the table's and the chart's
20
+ * titles take it through `labels`; a chip keeps the plain name and shows it as its tooltip)
21
+ * @returns {{result: import("pivotkit-core").PivotResult | null, labels: import("./labels.js").UiLabels, ranges: {field: string, text: string}[], titles: Map<string, string>}} */
22
+ export declare function dateContext(result: import("pivotkit-core").PivotResult | null, labels: import("./labels.js").UiLabels): {
23
+ result: import("pivotkit-core").PivotResult | null;
24
+ labels: import("./labels.js").UiLabels;
25
+ ranges: {
26
+ field: string;
27
+ text: string;
28
+ }[];
29
+ titles: Map<string, string>;
30
+ };