report-studio 1.2.3 → 1.3.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 (53) hide show
  1. package/README.md +254 -3
  2. package/dist/designer-_sWqzOj8.js +5052 -0
  3. package/dist/designer.js +1 -1
  4. package/dist/index.js +2 -2
  5. package/dist/react-designer.js +1 -1
  6. package/dist/react.js +1 -1
  7. package/dist/viewer-4I7C1Rnd.js +4083 -0
  8. package/package.json +2 -2
  9. package/src/designer/blank.js +0 -1
  10. package/src/designer/canvas.js +172 -54
  11. package/src/designer/choice.js +368 -0
  12. package/src/designer/designer.js +342 -12
  13. package/src/designer/dialog.js +634 -6
  14. package/src/designer/fields.js +345 -36
  15. package/src/designer/geometry.js +77 -4
  16. package/src/designer/grouping.js +556 -0
  17. package/src/designer/icons.js +22 -0
  18. package/src/designer/menu.js +50 -6
  19. package/src/designer/panel.js +872 -69
  20. package/src/designer/rulers.js +14 -6
  21. package/src/designer/sample-data.js +112 -31
  22. package/src/designer/select.js +24 -3
  23. package/src/designer/structure.js +126 -12
  24. package/src/designer/styles.css +2017 -732
  25. package/src/designer/tokens.js +38 -11
  26. package/src/engine/calculate.js +487 -0
  27. package/src/engine/csv.js +17 -9
  28. package/src/engine/format.js +483 -0
  29. package/src/engine/group.js +350 -70
  30. package/src/engine/highlight.js +224 -0
  31. package/src/engine/index.js +8 -1
  32. package/src/engine/measure.js +53 -26
  33. package/src/engine/paginate.js +189 -92
  34. package/src/engine/resolve.js +117 -10
  35. package/src/engine/rows.js +71 -8
  36. package/src/engine/search.js +12 -4
  37. package/src/engine/tables.js +309 -11
  38. package/src/engine/validate.js +304 -8
  39. package/src/engine/xlsx-style.js +50 -4
  40. package/src/engine/xlsx.js +91 -21
  41. package/src/index.js +18 -0
  42. package/src/preview/chrome.css +302 -84
  43. package/src/preview/chrome.js +70 -58
  44. package/src/preview/viewer.js +137 -85
  45. package/src/render/items.js +61 -10
  46. package/src/render/report.css +0 -5
  47. package/src/shared/dropdown.css +78 -45
  48. package/src/shared/dropdown.js +105 -5
  49. package/src/shared/modal.css +78 -13
  50. package/types/index.d.ts +104 -9
  51. package/types/layout.d.ts +164 -2
  52. package/dist/designer-DQlfKnTr.js +0 -3416
  53. package/dist/viewer-BSPNCNRU.js +0 -2912
@@ -5,6 +5,13 @@
5
5
  * one - the same move theme.css, report.css and modal.css made before it. A
6
6
  * second copy is a second thing to keep in step, and the one that falls behind
7
7
  * is always the one nobody is looking at.
8
+ *
9
+ * Laid out the way a design tool lays out its menus, Figma's in particular -
10
+ * a quiet grey trigger with a chevron, a compact menu with a tick beside the
11
+ * chosen item - but in the product's own palette rather than Figma's dark one:
12
+ * paper, a hairline border, and the accent on the item under the pointer or
13
+ * the keys. The designer's properties rail opens the same menu from its own
14
+ * choices (.dz-listbox), so every list in the product looks like this one.
8
15
  */
9
16
 
10
17
  .dropdown {
@@ -18,23 +25,29 @@
18
25
  min-width: 92px;
19
26
  height: 32px;
20
27
  padding: 0 10px;
21
- border: 1px solid var(--border);
28
+ border: 1px solid transparent;
22
29
  border-radius: 6px;
23
- background: var(--surface);
30
+ background: var(--surface-muted);
24
31
  color: var(--ink);
25
32
  font: inherit;
26
- font-size: 10px;
33
+ font-size: 11px;
27
34
  cursor: pointer;
28
35
  }
29
36
 
30
37
  .dropdown-trigger:hover {
31
- background: var(--accent-soft);
32
- border-color: var(--accent);
38
+ border-color: var(--border);
39
+ }
40
+
41
+ .dropdown-trigger:focus-visible {
42
+ outline: none;
43
+ border-color: var(--accent-strong);
44
+ box-shadow: inset 0 0 0 1px var(--accent-strong);
33
45
  }
34
46
 
35
47
  .dropdown-trigger[aria-expanded="true"] {
36
48
  border-color: var(--accent-strong);
37
- background: var(--accent-soft);
49
+ box-shadow: inset 0 0 0 1px var(--accent-strong);
50
+ background: var(--surface);
38
51
  }
39
52
 
40
53
  .dropdown-value {
@@ -43,29 +56,31 @@
43
56
  font-variant-numeric: tabular-nums;
44
57
  }
45
58
 
46
- /* drawn rather than typed, so it does not depend on a glyph being present */
59
+ /* a drawn chevron, so it does not depend on a glyph being present */
47
60
  .dropdown-caret {
48
- width: 7px;
49
- height: 7px;
50
- margin-top: -3px;
51
- border-right: 1.5px solid var(--ink-soft);
52
- border-bottom: 1.5px solid var(--ink-soft);
53
- transform: rotate(45deg);
54
- transition: transform .12s ease;
55
- }
56
-
57
- .dropdown-trigger[aria-expanded="true"] .dropdown-caret {
58
- margin-top: 2px;
59
- transform: rotate(-135deg);
61
+ flex: none;
62
+ width: 9px;
63
+ height: 6px;
64
+ background: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 10 6'%3E%3Cpath d='M1 1l4 4 4-4' fill='none' stroke='%23667080' stroke-width='1.3' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E") center / 9px 6px no-repeat;
60
65
  }
61
66
 
62
- /* the bar is at the top of the window, so the menu always has room below it */
67
+ /**
68
+ * Fixed to the window and placed by dropdown.js under its trigger, so a card
69
+ * that scrolls - a dialog's - neither clips the menu nor grows to hold it. The
70
+ * trigger's width arrives as a custom property, because 100% of a fixed box is
71
+ * the window's width, not the trigger's.
72
+ *
73
+ * It scrolls inside itself when it is cut short, and a wheel that reaches its
74
+ * end stops there rather than going on to scroll whatever is behind it.
75
+ */
63
76
  .dropdown-menu {
64
- position: absolute;
65
- top: calc(100% + 6px);
77
+ position: fixed;
78
+ top: 0;
66
79
  left: 0;
67
- min-width: 100%;
80
+ min-width: var(--dropdown-trigger-width, 0);
68
81
  z-index: 30;
82
+ overflow-y: auto;
83
+ overscroll-behavior: contain;
69
84
 
70
85
  margin: 0;
71
86
  padding: 4px;
@@ -74,7 +89,9 @@
74
89
  background: var(--surface);
75
90
  border: 1px solid var(--border);
76
91
  border-radius: 8px;
77
- box-shadow: 0 8px 24px rgba(34, 39, 44, .16);
92
+ box-shadow: 0 8px 24px rgb(34 39 44 / .14);
93
+
94
+ color: var(--ink);
78
95
  }
79
96
 
80
97
  .dropdown-menu[hidden] {
@@ -84,53 +101,69 @@
84
101
  .dropdown-item {
85
102
  display: flex;
86
103
  align-items: center;
87
- gap: 8px;
88
- padding: 7px 10px 7px 8px;
89
- border-radius: 5px;
90
- font-size: 10px;
91
- color: var(--ink);
104
+ gap: 6px;
105
+ min-height: 24px;
106
+ padding: 4px 12px 4px 6px;
107
+ border-radius: 4px;
108
+ font-size: 11px;
109
+ line-height: 16px;
110
+ color: inherit;
92
111
  white-space: nowrap;
93
- cursor: pointer;
112
+ cursor: default;
94
113
  font-variant-numeric: tabular-nums;
95
114
  }
96
115
 
97
116
  /**
98
117
  * The tick occupies its width whether or not it is showing, so choosing a
99
- * different zoom does not shuffle every label sideways.
118
+ * different item does not shuffle every label sideways.
119
+ *
120
+ * Painted through a mask, so its colour is set here: the accent's darker
121
+ * shade on paper, and ink once the item it sits in is on the accent itself.
100
122
  */
101
123
  .dropdown-item::before {
102
124
  content: "";
125
+ flex: none;
103
126
  width: 12px;
104
127
  height: 12px;
105
- flex: none;
106
- background: none;
107
128
  }
108
129
 
130
+ /* the chosen item is said twice - the tick, and its label in the accent's ink */
109
131
  .dropdown-item[aria-selected="true"] {
110
- background: var(--accent-soft);
132
+ color: var(--accent-ink);
111
133
  font-weight: 600;
112
134
  }
113
135
 
114
136
  .dropdown-item[aria-selected="true"]::before {
115
- /* a tick drawn from two borders - no glyph, no icon font */
116
- width: 5px;
117
- height: 9px;
118
- margin: -3px 4px 0 3px;
119
- border-right: 2px solid var(--accent-ink);
120
- border-bottom: 2px solid var(--accent-ink);
121
- transform: rotate(45deg);
137
+ background-color: var(--accent-strong);
138
+ -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 12 12'%3E%3Cpath d='M2.5 6.2l2.4 2.4 4.6-5.2' fill='none' stroke='black' stroke-width='1.6' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E") center / 12px 12px no-repeat;
139
+ mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 12 12'%3E%3Cpath d='M2.5 6.2l2.4 2.4 4.6-5.2' fill='none' stroke='black' stroke-width='1.6' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E") center / 12px 12px no-repeat;
122
140
  }
123
141
 
142
+ /* the accent is ink-on-orange, never white: #ff9c4b is a light colour */
124
143
  .dropdown-item:hover,
125
144
  .dropdown-item.is-active {
126
- background: var(--accent-tint);
145
+ background: var(--accent);
146
+ color: var(--ink);
147
+ }
148
+
149
+ /* on the accent, the chosen item's tick and label go to ink with the rest */
150
+ .dropdown-item[aria-selected="true"]:hover,
151
+ .dropdown-item[aria-selected="true"].is-active {
152
+ color: var(--ink);
153
+ }
154
+
155
+ .dropdown-item[aria-selected="true"]:hover::before,
156
+ .dropdown-item[aria-selected="true"].is-active::before {
157
+ background-color: var(--ink);
127
158
  }
128
159
 
129
160
  .dropdown-item:focus {
130
161
  outline: none;
131
162
  }
132
163
 
133
- .dropdown-item.is-active {
134
- outline: 2px solid var(--accent-strong);
135
- outline-offset: -2px;
164
+ /* a hairline between groups of items, as the right-click menu has */
165
+ .dropdown-sep {
166
+ height: 1px;
167
+ margin: 4px 6px;
168
+ background: var(--border);
136
169
  }
@@ -7,9 +7,23 @@
7
7
  *
8
8
  * It keeps the two members of the select API the viewer used - `value` and
9
9
  * addEventListener('change') - so swapping it in changed almost nothing there.
10
+ *
11
+ * The menu is fixed to the window and placed under its trigger when it opens,
12
+ * not hung off the wrapper. A dialog's card scrolls, and a menu absolutely
13
+ * positioned inside it was clipped by the card and stretched it instead - a
14
+ * scrollbar on the card, another on the menu, and the wheel and the arrow keys
15
+ * scrolling the dialog out from under the list. choice.js places its lists the
16
+ * same way for the same reason.
10
17
  */
11
18
 
12
19
 
20
+ /** the space kept between the menu and the window's edges */
21
+ const EDGE = 8;
22
+
23
+ /** the space between the trigger and the menu */
24
+ const OFFSET = 4;
25
+
26
+
13
27
  /**
14
28
  * @param {HTMLElement} root the .dropdown wrapper
15
29
  * @returns {object} a select-shaped handle over the listbox
@@ -28,6 +42,7 @@ export function createDropdown(root) {
28
42
  * a designer opened in its own window has a different one from this module.
29
43
  */
30
44
  const doc = () => trigger.ownerDocument;
45
+ const view = () => doc().defaultView;
31
46
 
32
47
  let value = items.find(i => i.dataset.selected === 'true')?.dataset.value
33
48
  ?? items[0]?.dataset.value
@@ -59,6 +74,68 @@ export function createDropdown(root) {
59
74
  if (notify && changed) for (const fn of listeners) fn();
60
75
  }
61
76
 
77
+ /* ---------------- placing ---------------- */
78
+
79
+ /**
80
+ * Under the trigger, as wide as it at least, and inside the window: above
81
+ * the trigger when there is more room there, and cut to a scrolling height
82
+ * when neither side has room for all of it.
83
+ */
84
+ function place() {
85
+ const box = trigger.getBoundingClientRect();
86
+ const win = view();
87
+ const { style } = menu;
88
+
89
+ style.top = '0px';
90
+ style.left = '0px';
91
+ style.maxHeight = '';
92
+ style.setProperty('--dropdown-trigger-width', `${box.width}px`);
93
+
94
+ /**
95
+ * Where 0,0 actually landed. A transformed ancestor - the designer's
96
+ * floating foot is one - becomes a fixed element's frame instead of
97
+ * the window, and this is how far that frame is from the window's.
98
+ */
99
+ const origin = menu.getBoundingClientRect();
100
+ const height = menu.offsetHeight;
101
+ const width = menu.offsetWidth;
102
+
103
+ const below = win.innerHeight - box.bottom - OFFSET - EDGE;
104
+ const above = box.top - OFFSET - EDGE;
105
+
106
+ let top;
107
+ if (height <= below || below >= above) {
108
+ top = box.bottom + OFFSET;
109
+ if (height > below) style.maxHeight = `${Math.max(below, 0)}px`;
110
+ } else {
111
+ if (height > above) style.maxHeight = `${above}px`;
112
+ top = box.top - OFFSET - Math.min(height, above);
113
+ }
114
+
115
+ const left = Math.max(Math.min(box.left, win.innerWidth - width - EDGE), EDGE);
116
+
117
+ style.top = `${Math.round(top - origin.top)}px`;
118
+ style.left = `${Math.round(left - origin.left)}px`;
119
+ }
120
+
121
+ /**
122
+ * Focus the item without the browser scrolling every box around it to
123
+ * show it, then scroll the menu - and only the menu - so it is in view.
124
+ */
125
+ function reveal(item) {
126
+ if (!item) return;
127
+
128
+ item.focus({ preventScroll: true });
129
+
130
+ const top = item.offsetTop;
131
+ const bottom = top + item.offsetHeight;
132
+
133
+ if (top < menu.scrollTop) menu.scrollTop = top;
134
+ else if (bottom > menu.scrollTop + menu.clientHeight) {
135
+ menu.scrollTop = bottom - menu.clientHeight;
136
+ }
137
+ }
138
+
62
139
  /* ---------------- opening ---------------- */
63
140
 
64
141
  const isOpen = () => !menu.hidden;
@@ -71,13 +148,30 @@ export function createDropdown(root) {
71
148
 
72
149
  active = Math.max(items.findIndex(i => i.dataset.value === value), 0);
73
150
  paint();
74
- items[active]?.focus();
151
+ place();
152
+ reveal(items[active]);
75
153
 
76
154
  /**
77
155
  * Registered on the next tick, or the click that opened the menu would
78
156
  * bubble up to this same handler and close it again straight away.
79
157
  */
80
- setTimeout(() => doc().addEventListener('pointerdown', onOutside), 0);
158
+ setTimeout(() => {
159
+ if (isOpen()) doc().addEventListener('pointerdown', onOutside);
160
+ }, 0);
161
+
162
+ /**
163
+ * The menu is fixed to the window, so anything that moves the trigger
164
+ * - the dialog scrolling, the window resizing - would leave it behind.
165
+ * It closes instead, as a native select does.
166
+ */
167
+ doc().addEventListener('scroll', onAway, true);
168
+ view().addEventListener('resize', onAway);
169
+ }
170
+
171
+ function unlisten() {
172
+ doc().removeEventListener('pointerdown', onOutside);
173
+ doc().removeEventListener('scroll', onAway, true);
174
+ view()?.removeEventListener('resize', onAway);
81
175
  }
82
176
 
83
177
  function close({ focusTrigger = true } = {}) {
@@ -85,7 +179,7 @@ export function createDropdown(root) {
85
179
 
86
180
  menu.hidden = true;
87
181
  trigger.setAttribute('aria-expanded', 'false');
88
- doc().removeEventListener('pointerdown', onOutside);
182
+ unlisten();
89
183
 
90
184
  if (focusTrigger) trigger.focus();
91
185
  }
@@ -94,10 +188,16 @@ export function createDropdown(root) {
94
188
  if (!root.contains(event.target)) close({ focusTrigger: false });
95
189
  }
96
190
 
191
+ /** a long list scrolling inside itself is not the trigger moving */
192
+ function onAway(event) {
193
+ if (event.type === 'scroll' && menu.contains(event.target)) return;
194
+ close({ focusTrigger: false });
195
+ }
196
+
97
197
  function move(to) {
98
198
  active = (to + items.length) % items.length;
99
199
  paint();
100
- items[active]?.focus();
200
+ reveal(items[active]);
101
201
  }
102
202
 
103
203
  /* ---------------- events ---------------- */
@@ -159,7 +259,7 @@ export function createDropdown(root) {
159
259
  get isOpen() { return isOpen(); },
160
260
 
161
261
  destroy() {
162
- doc().removeEventListener('pointerdown', onOutside);
262
+ unlisten();
163
263
  listeners.clear();
164
264
  }
165
265
  };
@@ -9,6 +9,13 @@
9
9
  * environment the specs run in, and a stubbed showModal would test the stub
10
10
  * instead of the behaviour.
11
11
  *
12
+ * Laid out the way a design tool lays out a dialog, Figma's in particular, in
13
+ * the product's own palette: a rounded card lifted by its shadow rather than
14
+ * outlined, a title bar ruled off from the body, a footer ruled off below it
15
+ * with the buttons on the right, and the accent kept for the one button that
16
+ * does the thing. The markup is a title, a body and a .modal-actions row; the
17
+ * bars are drawn from those, so no dialog had to be rewritten for them.
18
+ *
12
19
  * What is NOT here: anything about what a particular dialog contains. The
13
20
  * export format cards stay with the preview, and the designer's own fields stay
14
21
  * with the designer.
@@ -25,6 +32,7 @@
25
32
  display: grid;
26
33
  place-items: center;
27
34
  font-family: "Instrument Sans", system-ui, sans-serif;
35
+ font-size: 12px;
28
36
  color: var(--ink);
29
37
  }
30
38
 
@@ -32,53 +40,110 @@
32
40
  .modal-backdrop {
33
41
  position: absolute;
34
42
  inset: 0;
35
- background: rgba(34, 39, 44, .45);
43
+ background: rgba(34, 39, 44, .32);
36
44
  }
37
45
 
38
46
  .modal-card {
47
+ --modal-x: 16px;
48
+
39
49
  position: relative;
40
50
  width: min(420px, calc(100vw - 32px));
41
- padding: 20px;
42
- border: 1px solid var(--border);
51
+ max-height: calc(100vh - 48px);
52
+ overflow-y: auto;
53
+ padding: 0 var(--modal-x) var(--modal-x);
54
+ border-radius: 12px;
43
55
  background: var(--surface);
44
- box-shadow: 0 12px 40px rgba(34, 39, 44, .22);
56
+ box-shadow:
57
+ 0 0 0 1px rgba(34, 39, 44, .08),
58
+ 0 2px 6px rgba(34, 39, 44, .06),
59
+ 0 20px 48px rgba(34, 39, 44, .22);
45
60
  }
46
61
 
62
+ /**
63
+ * The title is the dialog's title bar: ruled off from the body, across the
64
+ * whole card, sticky while a long dialog scrolls under it. Room is left on
65
+ * the right for the close button, which sits in it.
66
+ */
47
67
  .modal-card h2 {
48
- margin-bottom: 14px;
49
- font-size: 16px;
68
+ position: sticky;
69
+ top: 0;
70
+ z-index: 1;
71
+ display: flex;
72
+ align-items: center;
73
+ height: 48px;
74
+ margin: 0 calc(-1 * var(--modal-x)) var(--modal-x);
75
+ padding: 0 48px 0 var(--modal-x);
76
+ border-bottom: 1px solid var(--border);
77
+ background: var(--surface);
78
+ font-size: 13px;
50
79
  font-weight: 600;
51
80
  }
52
81
 
82
+ /* the ×: a glyph button in the title bar, as a design tool's dialog has */
83
+ .modal-close {
84
+ position: absolute;
85
+ top: 10px;
86
+ right: 10px;
87
+ z-index: 2;
88
+ display: grid;
89
+ place-items: center;
90
+ width: 28px;
91
+ height: 28px;
92
+ padding: 0;
93
+ border: 0;
94
+ border-radius: 6px;
95
+ background: none;
96
+ color: var(--ink-soft);
97
+ cursor: pointer;
98
+ }
99
+
100
+ .modal-close:hover {
101
+ background: var(--surface-muted);
102
+ color: var(--ink);
103
+ }
104
+
105
+ .modal-close:focus-visible {
106
+ outline: 2px solid var(--accent-strong);
107
+ outline-offset: -2px;
108
+ }
109
+
53
110
  .modal-summary {
54
111
  min-height: 18px;
55
- margin: 12px 2px 0;
112
+ margin: 12px 0 0;
56
113
  font-size: 12px;
114
+ line-height: 1.5;
57
115
  color: var(--ink-soft);
58
116
  }
59
117
 
118
+ /**
119
+ * The footer: ruled off from the body across the whole card, the buttons on
120
+ * the right. Negative margins take it to the card's edges, whatever it sits
121
+ * in - a form, or the card itself.
122
+ */
60
123
  .modal-actions {
61
124
  display: flex;
62
125
  justify-content: flex-end;
63
126
  gap: 8px;
64
- margin-top: 16px;
127
+ margin: 20px calc(-1 * var(--modal-x)) calc(-1 * var(--modal-x));
128
+ padding: 12px var(--modal-x);
129
+ border-top: 1px solid var(--border);
65
130
  }
66
131
 
67
132
  .modal-actions button {
68
- height: 34px;
69
- padding: 0 16px;
133
+ height: 32px;
134
+ padding: 0 14px;
70
135
  border: 1px solid var(--border);
71
136
  border-radius: 6px;
72
137
  background: var(--surface);
73
138
  color: var(--ink);
74
139
  font: inherit;
75
- font-size: 13px;
140
+ font-size: 12px;
141
+ font-weight: 500;
76
142
  cursor: pointer;
77
143
  }
78
144
 
79
145
  .modal-actions button:hover:not(:disabled) {
80
- background: var(--accent-soft);
81
- border-color: var(--accent);
146
+ background: var(--surface-muted);
82
147
  }
83
148
 
84
149
  /* dark ink on the accent, never white: 7.25:1 against 2.08:1 */
package/types/index.d.ts CHANGED
@@ -3,7 +3,8 @@
3
3
  */
4
4
 
5
5
  import type {
6
- Band, BandType, Layout, PaginatedReport, Page, ReportData, TableItem, TextStyle
6
+ Band, BandType, FormatDefaults, GroupBand, GroupFragment, GroupLevel, Layout, PaginatedReport,
7
+ HighlightRule, Page, ReportData, TableColumn, TableItem, TextStyle, ValueFormat
7
8
  } from './layout.js';
8
9
 
9
10
  export type * from './layout.js';
@@ -19,7 +20,11 @@ export function buildPages(layout: Layout, data: ReportData): PaginatedReport;
19
20
 
20
21
  /** stage 1 of buildPages: fills in placeholders from the data */
21
22
  export function resolve(layout: Layout, data: ReportData): Layout;
22
- /** stage 2: splits the grouped table's rows into groups */
23
+ /**
24
+ * stage 2: binds each table to its rows and splits every grouped table's rows
25
+ * into groups. Grouping written the older way comes out as each table's own
26
+ * `grouping` - see normalizeGrouping.
27
+ */
23
28
  export function group(resolved: Layout, data: ReportData): Layout;
24
29
  /** stage 3: measures text and table rows */
25
30
  export function measure(grouped: Layout): Layout;
@@ -87,10 +92,16 @@ export interface CSVOptions {
87
92
  header?: boolean;
88
93
  /** prepend the group key on a grouped table; default true */
89
94
  groupColumn?: boolean;
90
- /** default `'Group'` */
91
- groupLabel?: string;
95
+ /**
96
+ * the group column's heading; default `'Group'`. A list names one column
97
+ * per level of a nested grouping, whose columns are otherwise named after
98
+ * the fields they group by
99
+ */
100
+ groupLabel?: string | string[];
92
101
  /** stop cells starting `=`, `+`, `-` or `@` running as formulas; default true */
93
102
  neutraliseFormulas?: boolean;
103
+ /** write each cell as printed, ₹1,00,000.00, rather than its value; default false */
104
+ formatted?: boolean;
94
105
  }
95
106
 
96
107
  export type ReportCSVOptions = Pick<CSVOptions, 'delimiter' | 'newline' | 'neutraliseFormulas'>;
@@ -122,8 +133,12 @@ export interface XLSXOptions {
122
133
  reportSheetName?: string;
123
134
  /** prepend the group key on a grouped table's sheet; default true */
124
135
  groupColumn?: boolean;
125
- /** default `'Group'` */
126
- groupLabel?: string;
136
+ /**
137
+ * the group column's heading; default `'Group'`. A list names one column
138
+ * per level of a nested grouping, whose columns are otherwise named after
139
+ * the fields they group by
140
+ */
141
+ groupLabel?: string | string[];
127
142
  }
128
143
 
129
144
  /**
@@ -161,8 +176,81 @@ export function tablesOf(layout: Layout): TableItem[];
161
176
  /** the dataset a table reads: its own, or the layout's */
162
177
  export function datasetOf(table: TableItem, layout: Layout): string | null;
163
178
 
164
- /** the grouped table and its field, or null when nothing is grouped */
165
- export function groupingOf(layout: Layout): { table: TableItem; by: string } | null;
179
+ /** a grouped table, its field, and the bands its groups are drawn with */
180
+ export interface TableGrouping {
181
+ table: TableItem;
182
+ by: string;
183
+ header: GroupBand | Band | null;
184
+ footer: GroupBand | Band | null;
185
+ /** every level, outermost first; the fields above are the first's */
186
+ levels: Array<{ by: string; header: GroupBand | Band | null; footer: GroupBand | Band | null }>;
187
+ }
188
+
189
+ /** every grouped table, in the order they are drawn, either way it is grouped */
190
+ export function groupingsOf(layout: Layout): TableGrouping[];
191
+
192
+ /** the first grouped table, or null when nothing is grouped */
193
+ export function groupingOf(layout: Layout): TableGrouping | null;
194
+
195
+ /** the text a value prints as, under a format and the report's defaults */
196
+ export function formatValue(value: unknown, format?: ValueFormat | null, defaults?: FormatDefaults | null): string;
197
+
198
+ /** a format in one line, such as "Currency · ₹12,34,567.89" */
199
+ export function describeFormat(format?: ValueFormat | null, defaults?: FormatDefaults | null): string;
200
+
201
+ /** the Excel number format code that shows a value as formatValue prints it, or null */
202
+ export function excelNumberFormat(format?: ValueFormat | null, defaults?: FormatDefaults | null): string | null;
203
+
204
+ /** international digit groups, no symbol, ISO dates */
205
+ export const DEFAULT_FORMAT: Readonly<Required<ValueFormat>>;
206
+
207
+ /** the style the first rule that holds gives a value, or null */
208
+ export function highlightFor(
209
+ rules: HighlightRule[] | null | undefined, value: unknown, row?: Record<string, unknown> | null
210
+ ): HighlightRule['style'] | null;
211
+
212
+ /** a table cell's style: its row's rules, then its column's own on top */
213
+ export function cellHighlight(
214
+ table: TableItem, column: TableColumn, row: Record<string, unknown>
215
+ ): HighlightRule['style'] | null;
216
+
217
+ /** "None", "1 rule", "3 rules" */
218
+ export function describeHighlight(rules: HighlightRule[] | null | undefined): string;
219
+
220
+ /** ₹, 1,00,000 and dd/MM/yyyy - what the designer's one-click Indian button sets */
221
+ export const INDIAN_DEFAULTS: Readonly<FormatDefaults>;
222
+
223
+ /** the most levels a table may be grouped at; validateLayout refuses more */
224
+ export const MAX_GROUP_LEVELS: number;
225
+
226
+ /** a table's grouping levels as the layout states them; empty when it has none */
227
+ export function levelsOf(table: TableItem): GroupLevel[];
228
+
229
+ /** whether a table is grouped, by `grouping` or by the older `groupBy` */
230
+ export function isGrouped(table: TableItem): boolean;
231
+
232
+ /**
233
+ * the bands one level of a table's groups are drawn with - the outermost's
234
+ * when no level is named - from a layout past normalizeGrouping
235
+ */
236
+ export function groupBandsOf(
237
+ table: TableItem, level?: number
238
+ ): { header: GroupBand | null; footer: GroupBand | null };
239
+
240
+ /**
241
+ * a built group fragment's bands in drawing order: headers outermost first,
242
+ * footers innermost first
243
+ */
244
+ export function fragmentBandsOf(
245
+ fragment: GroupFragment
246
+ ): { headers: Array<GroupBand & { level?: number }>; footers: Array<GroupBand & { level?: number }> };
247
+
248
+ /**
249
+ * A copy of a layout with grouping written one way only: `layout.groupBy`,
250
+ * `table.groupBy` and the report's groupHeader/groupFooter bands become that
251
+ * table's own `grouping`. Idempotent; the layout given is not changed.
252
+ */
253
+ export function normalizeGrouping<T extends Layout>(layout: T): T;
166
254
 
167
255
  /** width of one line of text, in pixels */
168
256
  export function measureText(text: string, style?: TextStyle): number;
@@ -208,9 +296,15 @@ export interface ViewerHandle {
208
296
  * from URLs fetches them first, so its download starts a moment later
209
297
  */
210
298
  downloadXLSX(): boolean;
299
+ /** opens the export menu under the toolbar's Export button */
211
300
  openExport(): void;
212
301
  closeExport(): void;
213
- confirmExport(): void;
302
+ /**
303
+ * exports in a format and closes the menu: the one named, or the item the
304
+ * keyboard is on, or PDF. Does nothing for a format the report has
305
+ * nothing to write in
306
+ */
307
+ confirmExport(format?: 'pdf' | 'csv' | 'xlsx'): void;
214
308
  setZoom(zoom: number): void;
215
309
  zoomIn(): void;
216
310
  zoomOut(): void;
@@ -220,6 +314,7 @@ export interface ViewerHandle {
220
314
  readonly page: number;
221
315
  readonly pageCount: number;
222
316
  readonly zoom: number;
317
+ /** whether the export menu is open */
223
318
  readonly exportOpen: boolean;
224
319
  }
225
320