pivotkit-react 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/CHANGELOG.md +300 -0
  2. package/LICENSE +21 -0
  3. package/README.md +327 -2
  4. package/dist/chunks/chunk-C32TYSHG.js +441 -0
  5. package/dist/chunks/chunk-ILHFIV2P.js +784 -0
  6. package/dist/chunks/chunk-KKJO36W5.js +1833 -0
  7. package/dist/chunks/chunk-XYP47DJ3.js +123 -0
  8. package/dist/echarts.js +262 -0
  9. package/dist/index.js +3390 -0
  10. package/dist/labels.js +12 -0
  11. package/dist/menus.js +1085 -0
  12. package/dist/styles.css +2447 -0
  13. package/package.json +70 -4
  14. package/types/PivotReport.d.ts +20 -0
  15. package/types/all-labels.d.ts +5 -0
  16. package/types/chart-decorate.d.ts +16 -0
  17. package/types/chart-options.d.ts +23 -0
  18. package/types/chart-summary.d.ts +12 -0
  19. package/types/chart-tooltip.d.ts +38 -0
  20. package/types/chart-types.d.ts +152 -0
  21. package/types/chart.d.ts +39 -0
  22. package/types/chip-menus.d.ts +32 -0
  23. package/types/clear-input.d.ts +20 -0
  24. package/types/dnd-moves.d.ts +45 -0
  25. package/types/dnd.d.ts +101 -0
  26. package/types/dom.d.ts +52 -0
  27. package/types/drill-export.d.ts +42 -0
  28. package/types/drill-panel.d.ts +39 -0
  29. package/types/drill.d.ts +62 -0
  30. package/types/echarts.d.ts +4 -0
  31. package/types/export-run.d.ts +59 -0
  32. package/types/field-info.d.ts +34 -0
  33. package/types/fields.d.ts +32 -0
  34. package/types/files.d.ts +27 -0
  35. package/types/filter.d.ts +21 -0
  36. package/types/icons.d.ts +76 -0
  37. package/types/index.d.ts +536 -0
  38. package/types/info.d.ts +34 -0
  39. package/types/iso.d.ts +2 -0
  40. package/types/labels.d.ts +721 -0
  41. package/types/lazy-menus.d.ts +16 -0
  42. package/types/menu-labels.d.ts +255 -0
  43. package/types/menus.d.ts +7 -0
  44. package/types/names.d.ts +80 -0
  45. package/types/numbers.d.ts +13 -0
  46. package/types/overflow.d.ts +59 -0
  47. package/types/place.d.ts +43 -0
  48. package/types/popover.d.ts +89 -0
  49. package/types/rove.d.ts +20 -0
  50. package/types/section.d.ts +42 -0
  51. package/types/share.d.ts +123 -0
  52. package/types/skeleton.d.ts +9 -0
  53. package/types/storage.d.ts +24 -0
  54. package/types/table.d.ts +23 -0
  55. package/types/templates.d.ts +40 -0
  56. package/types/theme.d.ts +24 -0
  57. package/types/tip-list.d.ts +20 -0
  58. package/types/tips.d.ts +298 -0
  59. package/types/toasts.d.ts +26 -0
  60. package/types/toolbar-panels.d.ts +90 -0
  61. package/types/toolbar.d.ts +5 -0
  62. package/types/use-big-result.d.ts +29 -0
  63. package/types/use-export.d.ts +7 -0
  64. package/types/use-theme.d.ts +11 -0
  65. package/types/use-view-history.d.ts +34 -0
  66. package/types/version.d.ts +2 -0
  67. package/types/view-history.d.ts +89 -0
  68. package/types/view-ops.d.ts +344 -0
  69. package/types/view-store.d.ts +52 -0
  70. package/types/virtual.d.ts +44 -0
  71. package/types/zones.d.ts +42 -0
@@ -0,0 +1,123 @@
1
+ /** pivotkit-core/link (fflate), loaded once, on first use. */
2
+ export declare function loadLink(): Promise<typeof import("pivotkit-core/link")>;
3
+ /** The link module when it is loaded already, else null (see loadLink). */
4
+ export declare const linkNow: () => typeof import("pivotkit-core/link") | null;
5
+ /**
6
+ * The name of a report's view in the URL fragment: "pivot", or "pivot-<storageKey>" so several reports
7
+ * on one page each have their own.
8
+ * @param {string | undefined} storageKey
9
+ */
10
+ export declare function linkParam(storageKey: string | undefined): string;
11
+ /**
12
+ * The encoded view of a fragment ("#pivot=1.abc&pivot-sales=1.def") under a name, or null. The
13
+ * fragment is read as it is, not as form data, so a hash route next to it ("#/reports/a?tab=2&pivot=...")
14
+ * does not matter.
15
+ * @param {string} hash location.hash, with or without "#"
16
+ * @param {string} param
17
+ */
18
+ export declare function readLinkParam(hash: string, param: string): any;
19
+ /**
20
+ * A URL with the encoded view under `param` in its fragment. Only that entry is added, replaced or
21
+ * removed; the rest of the fragment (another report's entry, a hash route such as "#/reports/a?tab=2",
22
+ * an anchor) stays byte for byte.
23
+ * @param {string} url
24
+ * @param {string} param
25
+ * @param {string | null} encoded null removes the entry
26
+ */
27
+ export declare function withLinkParam(url: string, param: string, encoded: string | null): string;
28
+ /**
29
+ * The address a shared link points to: the host's base URL as given, or for `true` the page's own
30
+ * address without its query (it may hold tokens or ids the host did not mean to share) and with its
31
+ * fragment (other entries, a hash route); null when links are off.
32
+ * @param {unknown} shareLink the prop: true, a URL, or anything else for off
33
+ * @param {string | undefined} here the page's address (location.href)
34
+ * @returns {string | null}
35
+ */
36
+ export declare function shareBase(shareLink: unknown, here: string | undefined): string | null;
37
+ /** The sessionStorage key of a report's view: one per storageKey. */
38
+ export declare const viewStorageName: (key: any) => string;
39
+ /**
40
+ * The stored view of a report (persistView="session") as JSON text, or null (none, no storage, blocked).
41
+ * @param {string | undefined} key
42
+ * @param {Pick<Storage, "getItem"> | null | undefined} storage
43
+ */
44
+ export declare function readStoredView(key: string | undefined, storage: Pick<Storage, "getItem"> | null | undefined): string | null;
45
+ /**
46
+ * Stores a report's view; quietly nothing when the browser refuses (private mode, quota).
47
+ * @param {string | undefined} key
48
+ * @param {Pick<Storage, "setItem"> | null | undefined} storage
49
+ * @param {object} view
50
+ */
51
+ export declare function writeStoredView(key: string | undefined, storage: Pick<Storage, "setItem"> | null | undefined, view: object): void;
52
+ /** The characters a view file or pasted JSON may have (pivotkit-core's VIEW_FILE_LIMITS.text). */
53
+ export declare const VIEW_TEXT_MAX: 1000000;
54
+ /**
55
+ * What normalize() left out, in plain words for the person who loaded the view: the fields the data
56
+ * does not have by name, the rest counted. The core's messages stay for developers (onViewChange gets
57
+ * the view only).
58
+ * @param {import("pivotkit-core").Issue[]} issues
59
+ * @param {import("./labels.js").UiLabels} labels
60
+ * @returns {string[]} one line per kind, at most a few
61
+ */
62
+ export declare function issueLines(issues: import("pivotkit-core").Issue[], labels: import("./labels.js").UiLabels): string[];
63
+ export type LoadedView = {
64
+ /**
65
+ * normalized against the data; null when nothing can be used
66
+ */
67
+ view: import("pivotkit-core").View | null;
68
+ /**
69
+ * what normalize() left out
70
+ */
71
+ issues: import("pivotkit-core").Issue[];
72
+ /**
73
+ * why nothing can be used: "empty", "tooLarge", "notJson", "notView", "newer"
74
+ */
75
+ failed: string | null;
76
+ /**
77
+ * the view file as read (name, source, compatible)
78
+ */
79
+ file: import("pivotkit-core").ViewFileRead | null;
80
+ };
81
+ /**
82
+ * A view from text someone pasted or a file they chose: a view file (pivotkit-core's fromViewFile), a
83
+ * bare view or a template { name, view }, normalized against the data.
84
+ * @param {string} text
85
+ * @param {import("pivotkit-core").Encoded} encoded
86
+ * @param {{ limits?: object, sourceId?: string }} [options]
87
+ * @returns {LoadedView}
88
+ */
89
+ export declare function viewFromText(text: string, encoded: import("pivotkit-core").Encoded, options?: {
90
+ limits?: object;
91
+ sourceId?: string;
92
+ }): LoadedView;
93
+ /**
94
+ * A view from a parsed object (a link's) or a text, read as a view file and normalized against the
95
+ * data; `file.compatible` says how it fits (the same source by `options.sourceId`, its fields there).
96
+ * @param {unknown} input
97
+ * @param {import("pivotkit-core").Encoded} encoded
98
+ * @param {{ limits?: object, sourceId?: string }} [options]
99
+ * @returns {LoadedView}
100
+ */
101
+ export declare function viewFromObject(input: unknown, encoded: import("pivotkit-core").Encoded, options?: {
102
+ limits?: object;
103
+ sourceId?: string;
104
+ }): LoadedView;
105
+ /**
106
+ * What to ask before a view for other data is applied, or null when it fits: the lines that say why
107
+ * (the source it was made for, the fields missing, the fields of another type) and, when the host
108
+ * can switch to that source (`sources`), its entry. Names from the file are plain text.
109
+ * @param {LoadedView} loaded
110
+ * @param {import("./labels.js").UiLabels} labels
111
+ * @param {Array<{ id: string, name?: string }>} [sources] the sources the host can switch to
112
+ * @returns {{ lines: string[], switchTo: { id: string, name: string } | null } | null}
113
+ */
114
+ export declare function loadCheck(loaded: LoadedView, labels: import("./labels.js").UiLabels, sources?: Array<{
115
+ id: string;
116
+ name?: string;
117
+ }>): {
118
+ lines: string[];
119
+ switchTo: {
120
+ id: string;
121
+ name: string;
122
+ } | null;
123
+ } | null;
@@ -0,0 +1,9 @@
1
+ import React from "react";
2
+ /**
3
+ * The whole report waiting (`full`), or only its result area (the report is there, its data reloads).
4
+ * @param {{ text: string, full?: boolean }} props
5
+ */
6
+ export declare function Skeleton({ text, full }: {
7
+ text: string;
8
+ full?: boolean;
9
+ }): React.JSX.Element;
@@ -0,0 +1,24 @@
1
+ /** The browser's localStorage, or null where it is missing or blocked (a sandboxed frame throws). */
2
+ export declare function localStore(): Storage | null;
3
+ /**
4
+ * The stored text of an item, or null (no storage, nothing stored, blocked).
5
+ * @param {string} name
6
+ * @param {Pick<Storage, "getItem"> | null | undefined} storage
7
+ * @returns {string | null}
8
+ */
9
+ export declare function readItem(name: string, storage: Pick<Storage, "getItem"> | null | undefined): string | null;
10
+ /**
11
+ * Listens to an item: a write in this page (writeItem) or in another tab (the storage event).
12
+ * @param {string} name
13
+ * @param {() => void} callback
14
+ * @returns {() => void} stops listening
15
+ */
16
+ export declare function subscribeItem(name: string, callback: () => void): () => void;
17
+ /**
18
+ * Stores the text of an item (null removes it) and tells its listeners in this page. False when the
19
+ * browser refused (blocked, private mode, quota); nothing is thrown.
20
+ * @param {string} name
21
+ * @param {Pick<Storage, "setItem" | "removeItem"> | null | undefined} storage
22
+ * @param {string | null} text
23
+ */
24
+ export declare function writeItem(name: string, storage: Pick<Storage, "setItem" | "removeItem"> | null | undefined, text: string | null): boolean;
@@ -0,0 +1,23 @@
1
+ import React from "react";
2
+ /**
3
+ * @param {{ grid: import("pivotkit-core").Grid, view: any, labels: import("./labels.js").UiLabels,
4
+ * onToggle: (axis: string, path: any[]) => void, onCell: (cell: object) => void, version: unknown, hintId?: string,
5
+ * onRowLabel?: (label: string | null) => void, infoOf?: (field: string) => { description?: string } | undefined, showInfo?: boolean }} props
6
+ * `onRowLabel`: the whole label of the row of a focused value or a tapped row label while the table
7
+ * is virtual (its labels are cut to one line); null when there is none to show; `infoOf`: the host's
8
+ * description of a field; `showInfo` false: no tooltip for it (the accessible description stays)
9
+ */
10
+ export declare function PivotTable({ grid, view, labels, onToggle: toggleGroup, onCell, version, hintId, onRowLabel, infoOf, showInfo }: {
11
+ grid: import("pivotkit-core").Grid;
12
+ view: any;
13
+ labels: import("./labels.js").UiLabels;
14
+ onToggle: (axis: string, path: any[]) => void;
15
+ onCell: (cell: object) => void;
16
+ version: unknown;
17
+ hintId?: string;
18
+ onRowLabel?: (label: string | null) => void;
19
+ infoOf?: (field: string) => {
20
+ description?: string;
21
+ } | undefined;
22
+ showInfo?: boolean;
23
+ }): React.JSX.Element;
@@ -0,0 +1,40 @@
1
+ /** The localStorage item of a report's views: one per storageKey ("pivotkit:views" without one). */
2
+ export declare const viewsName: (key: any) => string;
3
+ export type TemplateEntry = {
4
+ name: string;
5
+ /**
6
+ * not normalized: the report normalizes it when it is loaded
7
+ */
8
+ view: Record<string, unknown>;
9
+ scope: "shared" | "user";
10
+ deletable: boolean;
11
+ /**
12
+ * its place in the browser store; only for the store's own entries
13
+ */
14
+ at?: number;
15
+ };
16
+ /**
17
+ * @typedef {object} TemplateEntry an entry of the Views menu
18
+ * @property {string} name
19
+ * @property {Record<string, unknown>} view not normalized: the report normalizes it when it is loaded
20
+ * @property {"shared" | "user"} scope
21
+ * @property {boolean} deletable
22
+ * @property {number} [at] its place in the browser store; only for the store's own entries
23
+ */
24
+ /**
25
+ * The entries of the Views menu: the host's templates (an entry with `file` is read as a view file;
26
+ * one without a usable view or name is left out), then the browser store's. An entry without a
27
+ * `scope` is the user's own when it is deletable, else shared (with a console warning once: a
28
+ * deletable shared view would land under "My views"). A host's entry can be deleted only when it is
29
+ * marked `deletable` and the host takes the delete (`hostDeletes`). Every name is plain text
30
+ * (plainNames), as a name from a file or the store is.
31
+ * @param {unknown} templates the host's
32
+ * @param {Array<{ name: string, view: Record<string, unknown>, at: number }>} stored
33
+ * @param {boolean} hostDeletes
34
+ * @returns {TemplateEntry[]}
35
+ */
36
+ export declare function templateEntries(templates: unknown, stored: Array<{
37
+ name: string;
38
+ view: Record<string, unknown>;
39
+ at: number;
40
+ }>, hostDeletes: boolean): TemplateEntry[];
@@ -0,0 +1,24 @@
1
+ /**
2
+ * The theme to show.
3
+ * @param {"auto" | "light" | "dark" | undefined} wanted the theme prop
4
+ * @param {string | null | undefined} htmlTheme the value of <html data-theme>
5
+ * @param {boolean} prefersDark matchMedia("(prefers-color-scheme: dark)").matches
6
+ * @returns {"light" | "dark"}
7
+ */
8
+ export declare function resolveTheme(wanted: "auto" | "light" | "dark" | undefined, htmlTheme: string | null | undefined, prefersDark: boolean): "light" | "dark";
9
+ /** Number of categorical chart colours (--pk-chart-1 ... --pk-chart-8). */
10
+ export declare const CHART_COLORS = 8;
11
+ /**
12
+ * The ECharts theme of pivotkit-core's toEChartsOption from the computed style of the report's root.
13
+ * @param {{ getPropertyValue(name: string): string }} style getComputedStyle(root)
14
+ */
15
+ export declare function chartThemeFrom(style: {
16
+ getPropertyValue(name: string): string;
17
+ }): {
18
+ colors: any[];
19
+ textColor: string | undefined;
20
+ axisColor: string | undefined;
21
+ gridColor: string | undefined;
22
+ fontFamily: string | undefined;
23
+ backgroundColor: string;
24
+ };
@@ -0,0 +1,20 @@
1
+ import React from "react";
2
+ /**
3
+ * @param {{ tips: Array<{ id: string, text: string, icon: string, action: string, actionText: string, notice?: boolean }>,
4
+ * labels: import("./labels.js").UiLabels, onDismiss: (id: string) => void, onAction: (id: string, action: string) => void,
5
+ * focusFallback: () => void }} props
6
+ */
7
+ export declare function Tips({ tips, labels, onDismiss, onAction, focusFallback }: {
8
+ tips: Array<{
9
+ id: string;
10
+ text: string;
11
+ icon: string;
12
+ action: string;
13
+ actionText: string;
14
+ notice?: boolean;
15
+ }>;
16
+ labels: import("./labels.js").UiLabels;
17
+ onDismiss: (id: string) => void;
18
+ onAction: (id: string, action: string) => void;
19
+ focusFallback: () => void;
20
+ }): React.JSX.Element;
@@ -0,0 +1,298 @@
1
+ /** Tips shown at a time: one, the most important; the next waits until it is followed or dismissed. */
2
+ export declare const TIP_LIMIT = 1;
3
+ /** When the tips show; each number is documented in the React reference (tips). */
4
+ export declare const TIP_THRESHOLDS: Readonly<{
5
+ /** columns of an ungrouped date on Columns from which grouping it is suggested */
6
+ dateColumns: 12;
7
+ /** rows of an ungrouped date on Rows from which grouping it is suggested */
8
+ dateRows: 60;
9
+ /** columns from which swapping rows and columns is suggested (when there are fewer rows) */
10
+ manyColumns: 20;
11
+ /** changes of the view in this session after which saving it as a template is suggested */
12
+ changesBeforeSave: 5;
13
+ /** changes after the first drag during which the Undo and menu tip stays */
14
+ afterDragChanges: 3;
15
+ /** slices from which a pie or a donut suggests bars: a circle reads well up to about 7 parts */
16
+ pieSlices: 7;
17
+ }>;
18
+ export type TipContext = {
19
+ /**
20
+ * the normalized view
21
+ */
22
+ view: any;
23
+ /**
24
+ * nothing placed
25
+ */
26
+ empty: boolean;
27
+ /**
28
+ * the result cannot be shown (an error is shown instead)
29
+ */
30
+ failed: boolean;
31
+ /**
32
+ * the type of a field's source column
33
+ */
34
+ typeOf: (field: string) => string;
35
+ encoded: import("pivotkit-core").Encoded;
36
+ /**
37
+ * display names (labels.core.fields)
38
+ */
39
+ fields?: Record<string, string>;
40
+ /**
41
+ * rows of the innermost row field (1 without row fields)
42
+ */
43
+ rowLeaves: number;
44
+ /**
45
+ * columns of the innermost column field (1 without column fields)
46
+ */
47
+ colLeaves: number;
48
+ /**
49
+ * source rows left after the filters
50
+ */
51
+ matched: number;
52
+ /**
53
+ * source rows of the data
54
+ */
55
+ dataRows: number;
56
+ /**
57
+ * the chart's series, when the chart shows
58
+ */
59
+ series: {
60
+ series: any[];
61
+ categories: any[];
62
+ categoryCount: number;
63
+ } | null;
64
+ /**
65
+ * the table (with cells) is on screen
66
+ */
67
+ tableShown: boolean;
68
+ /**
69
+ * a value was opened once
70
+ */
71
+ drilled: boolean;
72
+ /**
73
+ * changes of the view in this session
74
+ */
75
+ changes: number;
76
+ /**
77
+ * `changes` when the first drag ended, null before
78
+ */
79
+ dragAt: number | null;
80
+ /**
81
+ * the host lets the user save templates
82
+ */
83
+ canSave: boolean;
84
+ /**
85
+ * `changes` when the view was last saved (0: not saved in this session)
86
+ */
87
+ savedAt: number;
88
+ /**
89
+ * what the chart draws
90
+ * (chart-types.js chartPlan): the type, whether the data chose it, rows and columns swapped for it
91
+ */
92
+ chartPlan: {
93
+ name: string;
94
+ auto: boolean;
95
+ swap: boolean;
96
+ };
97
+ };
98
+ export type TipEntry = {
99
+ id: string;
100
+ /**
101
+ * null: not now; else the
102
+ * placeholders of its text (and `action` data)
103
+ */
104
+ when: (ctx: TipContext) => Record<string, any> | null;
105
+ /**
106
+ * the action of its button: a key of labels.tipActions and of PivotReport's actions
107
+ */
108
+ action?: string;
109
+ /**
110
+ * a notice: always shown, not dismissible, outside the tips' limit
111
+ */
112
+ kind?: "notice";
113
+ icon?: string;
114
+ };
115
+ /** @type {readonly TipEntry[]} the tips, most important first: that is the order they show in */
116
+ export declare const TIPS: readonly TipEntry[];
117
+ /** Every tip id, for a host's `tips` list and for stored dismissals. */
118
+ export declare const TIP_IDS: readonly string[];
119
+ /** The notices: shown whenever they hold, whatever the tips settings are. */
120
+ export declare const NOTICE_IDS: readonly string[];
121
+ /** The dismissal that switches every tip off ("Show tips" in Options). */
122
+ export declare const ALL_TIPS = "*";
123
+ /**
124
+ * The other switch of Options → Help, "Show explanations", kept in the same list (and storage) as the
125
+ * tips: off, it hides every "i" - of the settings, of the zones and of the field descriptions -
126
+ * except those a host forces on (the props settingInfo, zoneInfo and fieldInfo).
127
+ */
128
+ export declare const NO_EXPLANATIONS = "-explanations";
129
+ /** The field list collapsed to a rail by the user (a wide or medium report), kept in the same list. */
130
+ export declare const FIELDS_COLLAPSED = "-fields";
131
+ /** Entries of the list that are switches, not dismissed tips: "Show dismissed tips again" keeps them. */
132
+ export declare const SWITCHES: readonly string[];
133
+ /**
134
+ * Whether the field list is collapsed: the user's choice in this session, else the host's
135
+ * `fieldList` ("open" or "collapsed"), else what the user chose before (the list).
136
+ * @param {boolean | null} session
137
+ * @param {unknown} forced
138
+ * @param {readonly string[]} dismissed
139
+ */
140
+ export declare function fieldsCollapsed(session: boolean | null, forced: unknown, dismissed: readonly string[]): boolean;
141
+ /**
142
+ * The sections of the menus that fold, and whether each is open until the user folds or opens it:
143
+ * the frequent ones open, the rest folded. The user's choice is kept in the same list (and storage)
144
+ * as the tips, as "open:<id>" or "closed:<id>" where it differs from this default.
145
+ */
146
+ export declare const SECTIONS: Readonly<{
147
+ summarize: true;
148
+ showAs: true;
149
+ format: false;
150
+ highlight: false;
151
+ name: false;
152
+ valueFilters: false;
153
+ move: false;
154
+ sort: true;
155
+ groupBy: true;
156
+ bins: true;
157
+ topN: true;
158
+ filters: true;
159
+ totals: true;
160
+ folding: true;
161
+ help: true;
162
+ exportDownload: true;
163
+ exportCopy: true;
164
+ sharedViews: true;
165
+ myViews: true;
166
+ share: true;
167
+ chartType: true;
168
+ chartDisplay: true;
169
+ }>;
170
+ /** Whether a section is open: the user's choice in the list, else its default. */
171
+ export declare function sectionOpen(id: any, dismissed: any): any;
172
+ /** The list with a section opened or folded: an entry only where it differs from the default. */
173
+ export declare function withSection(dismissed: any, id: any, open: any): any;
174
+ /** Entries "Show dismissed tips again" keeps: the switches and the sections' states. */
175
+ export declare const keptOnReset: (id: any) => boolean;
176
+ /**
177
+ * Whether one kind of "i" shows: the host's "on" or "off" forces it (and the user's switch leaves it
178
+ * alone), else the user's "Show explanations" in the list, on by default.
179
+ * @param {unknown} forced the host's prop (settingInfo, zoneInfo or fieldInfo)
180
+ * @param {readonly string[]} dismissed
181
+ * @param {string} [off] the switch's entry, NO_EXPLANATIONS
182
+ * @returns {{ on: boolean, user: boolean }} `user`: the user's switch decides
183
+ */
184
+ export declare function helpSwitch(forced: unknown, dismissed: readonly string[], off?: string): {
185
+ on: boolean;
186
+ user: boolean;
187
+ };
188
+ /**
189
+ * The keyboard shortcuts of the help section in Options: the keys (with "Mod" for Ctrl or ⌘) and
190
+ * the key of their text in labels.shortcuts.
191
+ */
192
+ export declare const SHORTCUTS: readonly {
193
+ keys: string[];
194
+ text: string;
195
+ }[];
196
+ /**
197
+ * What the conditions read, from the report's state. Pure.
198
+ * @param {{ view: any, result: import("pivotkit-core").PivotResult | null, encoded: import("pivotkit-core").Encoded,
199
+ * failed: boolean, empty: boolean, typeOf: (field: string) => string, fields?: Record<string, string>,
200
+ * series?: TipContext["series"], tableShown?: boolean, drilled?: boolean, changes?: number, dragAt?: number | null, canSave?: boolean,
201
+ * savedAt?: number, chartPlan?: TipContext["chartPlan"] }} state
202
+ * @returns {TipContext}
203
+ */
204
+ export declare function tipContext({ view, result, encoded, failed, empty, typeOf, fields, series, tableShown, drilled, changes, dragAt, canSave, savedAt, chartPlan }: {
205
+ view: any;
206
+ result: import("pivotkit-core").PivotResult | null;
207
+ encoded: import("pivotkit-core").Encoded;
208
+ failed: boolean;
209
+ empty: boolean;
210
+ typeOf: (field: string) => string;
211
+ fields?: Record<string, string>;
212
+ series?: TipContext["series"];
213
+ tableShown?: boolean;
214
+ drilled?: boolean;
215
+ changes?: number;
216
+ dragAt?: number | null;
217
+ canSave?: boolean;
218
+ savedAt?: number;
219
+ chartPlan?: TipContext["chartPlan"];
220
+ }): TipContext;
221
+ /**
222
+ * What to show now, the most important first: every notice whose condition holds, then the tips
223
+ * whose condition holds, allowed by the host and not dismissed, at most `limit` of them.
224
+ * @param {TipContext} ctx
225
+ * @param {{ allowed: "on" | "off" | readonly string[], dismissed: ReadonlySet<string> | readonly string[], limit?: number }} options
226
+ * @returns {Array<{ id: string, params: Record<string, any>, entry: TipEntry }>}
227
+ */
228
+ export declare function activeTips(ctx: TipContext, { allowed, dismissed, limit }: {
229
+ allowed: "on" | "off" | readonly string[];
230
+ dismissed: ReadonlySet<string> | readonly string[];
231
+ limit?: number;
232
+ }): Array<{
233
+ id: string;
234
+ params: Record<string, any>;
235
+ entry: TipEntry;
236
+ }>;
237
+ /**
238
+ * The text of a tip in the labels' language; numbers in the locale.
239
+ * @param {string} id
240
+ * @param {Record<string, any>} params
241
+ * @param {import("./labels.js").UiLabels} labels
242
+ * @param {string} locale
243
+ */
244
+ export declare function tipText(id: string, params: Record<string, any>, labels: import("./labels.js").UiLabels, locale: string): any;
245
+ /**
246
+ * The text of a tip's button.
247
+ * @param {TipEntry} entry
248
+ * @param {Record<string, any>} params
249
+ * @param {import("./labels.js").UiLabels} labels
250
+ */
251
+ export declare function tipActionText(entry: TipEntry, params: Record<string, any>, labels: import("./labels.js").UiLabels): string;
252
+ /**
253
+ * A host's `tips` prop or attribute: "on" (default), "off", or the ids it allows (an array, or a
254
+ * comma-separated text); unknown ids are left out.
255
+ * @param {unknown} value
256
+ * @returns {"on" | "off" | string[]}
257
+ */
258
+ export declare function allowedTips(value: unknown): "on" | "off" | string[];
259
+ /** Dismissed ids from anywhere (storage, a host): known ids and the switches only, once each. */
260
+ export declare function cleanDismissed(value: any): any[];
261
+ /** The localStorage key of a report's tips: one per `storageKey`, so two reports never share one. */
262
+ export declare const storageName: (key: any) => string;
263
+ /**
264
+ * The stored text of a report's dismissed tips, or null (no key, no storage, blocked). A text, so a
265
+ * React store snapshot of it compares by value.
266
+ * @param {string | undefined} key
267
+ * @param {Pick<Storage, "getItem"> | null | undefined} storage
268
+ * @returns {string | null}
269
+ */
270
+ export declare function readStored(key: string | undefined, storage: Pick<Storage, "getItem"> | null | undefined): string | null;
271
+ /** The dismissed ids of a stored text: [] for nothing or broken JSON. @param {string | null} raw */
272
+ export declare function parseStored(raw: string | null): any[];
273
+ /**
274
+ * The dismissed tips stored for a report, or [] (no key, no storage, blocked, broken JSON).
275
+ * @param {string | undefined} key
276
+ * @param {Pick<Storage, "getItem"> | null | undefined} storage
277
+ */
278
+ export declare function readDismissed(key: string | undefined, storage: Pick<Storage, "getItem"> | null | undefined): any[];
279
+ /**
280
+ * Listens to the stored tips of a key: a write in this page (writeDismissed) or in another tab of
281
+ * the same site. For useSyncExternalStore, so the report reads the storage only after hydration (its
282
+ * server snapshot is "nothing stored").
283
+ * @param {string | undefined} key
284
+ * @param {() => void} callback
285
+ * @returns {() => void} stops listening
286
+ */
287
+ export declare function subscribeStored(key: string | undefined, callback: () => void): () => void;
288
+ /**
289
+ * Stores the dismissed tips of a report and tells the reports of the page that use the key; nothing
290
+ * without a key or storage, and quietly when the browser refuses (private mode, quota): the tips stay
291
+ * dismissed until the page is loaded again.
292
+ * @param {string | undefined} key
293
+ * @param {Pick<Storage, "setItem" | "removeItem"> | null | undefined} storage
294
+ * @param {readonly string[]} dismissed
295
+ */
296
+ export declare function writeDismissed(key: string | undefined, storage: Pick<Storage, "setItem" | "removeItem"> | null | undefined, dismissed: readonly string[]): void;
297
+ /** The Filters zone fields, kept with empty filters, and every other filter gone: "Remove filter". */
298
+ export declare function withoutFilters(view: any): any;
@@ -0,0 +1,26 @@
1
+ import React from "react";
2
+ /** How long a note stays, in milliseconds. */
3
+ export declare const SHOWN_MS = 6000;
4
+ export type Toast = {
5
+ id: number;
6
+ text: string;
7
+ action?: {
8
+ label: string;
9
+ run: () => void;
10
+ };
11
+ tone?: "error";
12
+ };
13
+ /** @typedef {{ id: number, text: string, action?: { label: string, run: () => void }, tone?: "error" }} Toast */
14
+ export declare function useToasts(): {
15
+ toasts: Toast[];
16
+ push: (toast: Omit<Toast, "id">) => void;
17
+ dismiss: (id: any) => void;
18
+ pause: (on: any, list: any) => void;
19
+ };
20
+ /** @param {{ toasts: Toast[], dismiss: (id: number) => void, pause: (on: boolean, list: Toast[]) => void, closeLabel: string }} props */
21
+ export declare function Toasts({ toasts, dismiss, pause, closeLabel }: {
22
+ toasts: Toast[];
23
+ dismiss: (id: number) => void;
24
+ pause: (on: boolean, list: Toast[]) => void;
25
+ closeLabel: string;
26
+ }): React.JSX.Element;