report-studio 0.0.1 → 1.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 (68) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +363 -4
  3. package/dist/designer-qy59eEux.js +3416 -0
  4. package/dist/designer.js +2 -0
  5. package/dist/index.js +2 -4
  6. package/dist/react-designer.js +41 -0
  7. package/dist/react.js +58 -2
  8. package/dist/viewer-xa17tyMJ.js +1721 -0
  9. package/package.json +65 -18
  10. package/src/asset/images/icon.png +0 -0
  11. package/src/asset/images/logo.png +0 -0
  12. package/src/cli/index.js +282 -0
  13. package/src/cli/serve.js +135 -0
  14. package/src/designer/blank.js +53 -0
  15. package/src/designer/canvas.js +518 -0
  16. package/src/designer/designer.js +2054 -0
  17. package/src/designer/dialog.js +708 -0
  18. package/src/designer/fields.js +633 -0
  19. package/src/designer/geometry.js +154 -0
  20. package/src/designer/guides.js +370 -0
  21. package/src/designer/history.js +113 -0
  22. package/src/designer/icons.js +123 -0
  23. package/src/designer/index.html +28 -0
  24. package/src/designer/main.js +39 -0
  25. package/src/designer/menu.js +126 -0
  26. package/src/designer/panel.js +498 -0
  27. package/src/designer/preview.js +95 -0
  28. package/src/designer/rulers.js +231 -0
  29. package/src/designer/sample-data.js +411 -0
  30. package/src/designer/select.js +699 -0
  31. package/src/designer/structure.js +685 -0
  32. package/src/designer/styles.css +1654 -0
  33. package/src/designer/toast.js +62 -0
  34. package/src/designer/tokens.js +293 -0
  35. package/src/engine/csv.js +350 -0
  36. package/src/engine/group.js +367 -0
  37. package/src/engine/index.js +35 -0
  38. package/src/engine/measure.js +391 -0
  39. package/src/engine/paginate.js +865 -0
  40. package/src/engine/regions.js +175 -0
  41. package/src/engine/resolve.js +208 -0
  42. package/src/engine/search.js +129 -0
  43. package/src/engine/tables.js +87 -0
  44. package/src/engine/text-metrics.js +206 -0
  45. package/src/engine/validate.js +403 -0
  46. package/src/index.html +79 -0
  47. package/src/index.js +51 -0
  48. package/src/preview/chrome.css +505 -0
  49. package/src/preview/chrome.js +147 -0
  50. package/src/preview/index.html +28 -0
  51. package/src/preview/main.js +66 -0
  52. package/src/preview/styles.css +16 -0
  53. package/src/preview/viewer.js +763 -0
  54. package/src/react/designer.js +87 -0
  55. package/src/react/index.js +117 -0
  56. package/src/render/items.js +518 -0
  57. package/src/render/render.js +98 -0
  58. package/src/render/report.css +232 -0
  59. package/src/server/routes.js +331 -0
  60. package/src/shared/brand.css +29 -0
  61. package/src/shared/dropdown.css +136 -0
  62. package/src/shared/dropdown.js +166 -0
  63. package/src/shared/modal.css +125 -0
  64. package/src/shared/prefix.js +13 -0
  65. package/src/shared/store.js +145 -0
  66. package/src/shared/theme.css +72 -0
  67. package/src/shared/window.js +138 -0
  68. package/src/vite/index.js +53 -0
@@ -0,0 +1,175 @@
1
+ /**
2
+ * regions.js decides where each band sits on a page.
3
+ *
4
+ * Bands do not flow. A page is divided into fixed zones, the way a sheet of
5
+ * headed paper is: a strip at the top for the page and report headers, a strip
6
+ * at the bottom for the report and page footers, and the detail in between.
7
+ *
8
+ * The point of anchoring rather than stacking: a page whose detail band ran out
9
+ * of rows must still print its footer on the bottom edge. Stacking pulls the
10
+ * footer up under the last row, which is not where a footer belongs.
11
+ *
12
+ * +--------------------+ <- content top
13
+ * | pageHeader | 10%
14
+ * | reportHeader | 10% (first page only)
15
+ * | |
16
+ * | detail | whatever is left - 60% when every band is present
17
+ * | |
18
+ * | reportFooter | 10% (last page only)
19
+ * | pageFooter | 10% pinned to the bottom edge
20
+ * +--------------------+ <- content bottom
21
+ *
22
+ * Every figure is a default the layout may override, per band, in px or in
23
+ * percent of the printable height.
24
+ */
25
+
26
+
27
+ /**
28
+ * Spec 3.2 gives band order but no sizes, so these are the sheet-of-paper
29
+ * defaults a report gets before anyone opens the designer. groupHeader and
30
+ * groupFooter are absent on purpose: they are drawn inside the detail band, not
31
+ * given a zone of their own.
32
+ */
33
+ export const DEFAULT_BAND_HEIGHTS = {
34
+ pageHeader: '10%',
35
+ reportHeader: '10%',
36
+ reportFooter: '10%',
37
+ pageFooter: '10%'
38
+ };
39
+
40
+ /** bands that own a zone, top to bottom */
41
+ const HEADER_ZONE = ['pageHeader', 'reportHeader'];
42
+ const FOOTER_ZONE = ['reportFooter', 'pageFooter'];
43
+
44
+
45
+ /**
46
+ * A band height as written in the layout: a number of pixels, or a percentage
47
+ * of the printable height. Anything unusable falls back to the default.
48
+ *
49
+ * @param {number|string|undefined} value the band's `height`
50
+ * @param {number} contentHeight the printable height of the page
51
+ * @param {number|string|undefined} fallback used when value is absent or unusable
52
+ * @returns {number} pixels
53
+ */
54
+ export function resolveHeight(value, contentHeight, fallback) {
55
+ const px = toPixels(value, contentHeight);
56
+ if (px !== null) return px;
57
+
58
+ const backup = toPixels(fallback, contentHeight);
59
+ return backup ?? 0;
60
+ }
61
+
62
+
63
+ function toPixels(value, contentHeight) {
64
+ if (typeof value === 'number' && Number.isFinite(value) && value >= 0) {
65
+ return value;
66
+ }
67
+
68
+ if (typeof value === 'string') {
69
+ const percent = value.trim().match(/^(-?[\d.]+)\s*%$/);
70
+ if (percent) {
71
+ const ratio = Number(percent[1]);
72
+ if (Number.isFinite(ratio) && ratio >= 0) {
73
+ return (ratio / 100) * contentHeight;
74
+ }
75
+ return null;
76
+ }
77
+
78
+ const plain = Number(value.trim().replace(/px$/i, ''));
79
+ if (Number.isFinite(plain) && plain >= 0) return plain;
80
+ }
81
+
82
+ return null;
83
+ }
84
+
85
+
86
+ /**
87
+ * The zone height a band should occupy. The declared height is the design
88
+ * intent, but content is never clipped to it - a band whose text wrapped past
89
+ * its zone grows, and says so.
90
+ *
91
+ * @param {object|null} band
92
+ * @param {number} contentHeight
93
+ * @returns {number}
94
+ */
95
+ export function bandZoneHeight(band, contentHeight) {
96
+ if (!band) return 0;
97
+
98
+ const declared = resolveHeight(
99
+ band.height,
100
+ contentHeight,
101
+ DEFAULT_BAND_HEIGHTS[band.type]
102
+ );
103
+
104
+ const measured = band.measuredHeight ?? 0;
105
+
106
+ if (measured > declared) {
107
+ console.warn(
108
+ `Band "${band.type}" needs ${Math.ceil(measured)}px but its zone is ` +
109
+ `${Math.round(declared)}px; the zone has been grown to fit.`
110
+ );
111
+ return measured;
112
+ }
113
+
114
+ return declared;
115
+ }
116
+
117
+
118
+ /**
119
+ * Where every band sits on one page, in coordinates relative to the printable
120
+ * area - so (0, 0) is inside the margins, not the paper edge.
121
+ *
122
+ * @param {object} options
123
+ * @param {object} options.bands the band templates, keyed by type
124
+ * @param {number} options.contentHeight page height less the top and bottom margins
125
+ * @param {boolean} options.isFirstPage the report header only appears here
126
+ * @param {boolean} options.isLastPage and the report footer only here
127
+ * @returns {object} a zone per band type, plus the detail zone
128
+ */
129
+ export function pageRegions({ bands, contentHeight, isFirstPage, isLastPage }) {
130
+ const regions = {};
131
+
132
+ const shows = (type) => {
133
+ if (type === 'reportHeader') return isFirstPage;
134
+ if (type === 'reportFooter') return isLastPage;
135
+ return true;
136
+ };
137
+
138
+ /* headers, downward from the top */
139
+ let top = 0;
140
+
141
+ for (const type of HEADER_ZONE) {
142
+ const band = bands[type];
143
+ if (!band || !shows(type)) continue;
144
+
145
+ const height = bandZoneHeight(band, contentHeight);
146
+ regions[type] = { top, height };
147
+ top += height;
148
+ }
149
+
150
+ const detailTop = top;
151
+
152
+ /* footers, upward from the bottom, so the page footer lands on the edge */
153
+ let bottom = contentHeight;
154
+
155
+ for (const type of [...FOOTER_ZONE].reverse()) {
156
+ const band = bands[type];
157
+ if (!band || !shows(type)) continue;
158
+
159
+ const height = bandZoneHeight(band, contentHeight);
160
+ bottom -= height;
161
+ regions[type] = { top: bottom, height };
162
+ }
163
+
164
+ /**
165
+ * The detail takes what the two zones leave. With the default 10/10/10/10
166
+ * that is the 60% in the middle; change any band's height and the detail
167
+ * absorbs the difference rather than the footer drifting off the edge.
168
+ */
169
+ regions.detail = {
170
+ top: detailTop,
171
+ height: Math.max(bottom - detailTop, 0)
172
+ };
173
+
174
+ return regions;
175
+ }
@@ -0,0 +1,208 @@
1
+ /**
2
+ * The resolve.js is used to analysis the incoming json using regex and
3
+ * replacing the only the text content into actual data given by the user
4
+ * so the input are @param rptJson and @param rptData
5
+ *
6
+ * Two placeholder families are deliberately left alone here:
7
+ * {sum(field)} and friends - group.js and paginate.js know the scope
8
+ * {page} / {totalPages} - paginate.js is the only stage that knows these
9
+ * Both are left in the output text verbatim so the later stage can fill them in
10
+ * without having to re-resolve `value` and lose everything resolved here.
11
+ */
12
+
13
+ import { assertLayout, assertData } from './validate.js';
14
+
15
+
16
+ const REGEX = /\{([^{}]+)\}/g;
17
+
18
+ /** an aggregate expression: name(field) */
19
+ const AGGREGATE = /^\w+\(.*\)$/;
20
+
21
+ /** placeholders paginate.js owns */
22
+ const PAGE_KEYS = ['page', 'totalPages'];
23
+
24
+ /** bands whose placeholders are scoped to a group, not to the root data */
25
+ const GROUP_BANDS = ['groupHeader', 'groupFooter'];
26
+
27
+
28
+ /**
29
+ * The placeholder pattern, and which keys the host is expected to supply.
30
+ *
31
+ * Exported because the designer derives a sample data file from a layout, and a
32
+ * second copy of these rules there would drift from the ones that actually
33
+ * resolve - so it would ask the user for `{page}` and forget `{customer.name}`.
34
+ */
35
+ export const PLACEHOLDER = REGEX;
36
+
37
+
38
+ /**
39
+ * Whether a placeholder is answered by the engine rather than by the data.
40
+ *
41
+ * Aggregates are group.js's, page numbers are paginate.js's, and `today` is the
42
+ * clock's. Everything else has to come from the payload.
43
+ *
44
+ * @param {string} key the text inside the braces, trimmed
45
+ * @returns {boolean}
46
+ */
47
+ export function isEngineKey(key) {
48
+ return AGGREGATE.test(key) || PAGE_KEYS.includes(key) || key === 'today';
49
+ }
50
+
51
+
52
+ /**
53
+ * Whether a band's placeholders are scoped to a row rather than to the root.
54
+ *
55
+ * The group bands, and only those. Spec 3.4's table says a bare `{field}` is
56
+ * "the current row, else root data" in any band, but that is not what this file
57
+ * does: `deferUnknown` above is set for the group bands alone, and every other
58
+ * band - the detail band included - looks its keys up in the root payload.
59
+ *
60
+ * The engine is the thing that runs, so this reports the engine. Saying
61
+ * otherwise put `{name}` in a detail band into the rows of a sample data file,
62
+ * where the engine never looked for it, and the report printed "Name:" and
63
+ * nothing after it.
64
+ *
65
+ * @param {string} type a band type
66
+ * @returns {boolean}
67
+ */
68
+ export function isRowScoped(type) {
69
+ return GROUP_BANDS.includes(type);
70
+ }
71
+
72
+
73
+ /**
74
+ * Resolves the report JSON with the provided data
75
+ * @param {*} rptJson
76
+ * @param {*} rptData
77
+ * @returns
78
+ */
79
+ export function resolve(rptJson, rptData) {
80
+ assertLayout(rptJson, 'resolve');
81
+ assertData(rptData, 'resolve');
82
+
83
+ // cloning the report json and assigning it to new var
84
+ // so that report will not affect
85
+ const resolved = structuredClone(rptJson);
86
+
87
+ for (const band of resolved.bands) {
88
+ /**
89
+ * A group band's placeholders are mostly row fields ({name} is the
90
+ * group's own value), which only the grouping stage can answer. Anything
91
+ * this stage cannot resolve there is deferred rather than blanked, so
92
+ * grouping still has it to work with.
93
+ */
94
+ const deferUnknown = GROUP_BANDS.includes(band.type);
95
+
96
+ for (const item of band.items) {
97
+ if (item.type == "text")
98
+ item.text = resolveTxt(item, rptData, deferUnknown);
99
+
100
+ if (item.type == "image")
101
+ item.resolvedSrc = resolveImage(item, rptData);
102
+ }
103
+ }
104
+
105
+ return resolved;
106
+ }
107
+
108
+
109
+ /**
110
+ * The picture an image item shows: the value at its `field` when the data has
111
+ * one there, and the `src` stored in the layout otherwise - so a report can
112
+ * carry a default logo that the host replaces per customer.
113
+ *
114
+ * Always written, if only as '', because its presence is what tells the
115
+ * renderer this item went through the engine. The designer canvas draws items
116
+ * straight from the layout and shows a placeholder for a bound image; a built
117
+ * report whose data had no picture should print an empty frame instead.
118
+ *
119
+ * The URL is not checked here. Every route to the page goes through the
120
+ * renderer, which is where it is made safe - checking twice is two lists of
121
+ * schemes to keep in step.
122
+ *
123
+ * @param {object} item an image item
124
+ * @param {object} rptData
125
+ * @returns {string}
126
+ */
127
+ function resolveImage(item, rptData) {
128
+ const field = typeof item.field === 'string' ? item.field.trim() : '';
129
+
130
+ if (field) {
131
+ const value = findVal(field, rptData);
132
+ if (typeof value === 'string' && value !== '') return value;
133
+
134
+ if (!item.src) {
135
+ console.warn(`Unresolved image field "${field}" on item "${item.id}".`);
136
+ }
137
+ }
138
+
139
+ return typeof item.src === 'string' ? item.src : '';
140
+ }
141
+
142
+
143
+ /**
144
+ * Resolves the text value of an item with the provided data
145
+ * @param {*} item
146
+ * @param {*} rptData
147
+ * @param {boolean} deferUnknown leave an unresolvable key for a later stage
148
+ * @returns
149
+ */
150
+ function resolveTxt(item, rptData, deferUnknown) {
151
+ return item.value.replace(REGEX, (match, key) => {
152
+ return validatePlaceHolder(match, key.trim(), rptData, item, deferUnknown);
153
+ })
154
+ }
155
+
156
+ /**
157
+ * Validate the given and find weather the key is system keys or not
158
+ * in-case of system keys return appropriate value
159
+ * eg : key == today the return current date
160
+ * @param {*} match the whole `{...}` token, returned as-is when a later stage owns it
161
+ * @param {*} key
162
+ * @param {*} rptData
163
+ * @param {*} item
164
+ * @param {boolean} deferUnknown
165
+ * @returns
166
+ */
167
+ function validatePlaceHolder(match, key, rptData, item, deferUnknown) {
168
+ /**
169
+ * Handed on rather than reported. An aggregate belongs to grouping and a
170
+ * page key belongs to pagination, so neither is resolvable here and neither
171
+ * is a surprise - these two were logged on the way past, which meant a
172
+ * footer with a page number wrote a line to the console for every page of
173
+ * every report. Only the unresolvable placeholder below is worth a word.
174
+ */
175
+ if (AGGREGATE.test(key)) return match;
176
+
177
+ if (PAGE_KEYS.includes(key)) return match;
178
+
179
+ if (key == 'today') return new Date().toISOString().slice(0, 10);
180
+
181
+ const value = findVal(key, rptData);
182
+
183
+ if (value === undefined || value === null) {
184
+ /** a group's own field, which only has a value once the rows are split */
185
+ if (deferUnknown) return match;
186
+ console.warn(`Unresolved placeholder "{${key}}" on item "${item.id}".`);
187
+ return '';
188
+ }
189
+
190
+ return String(value);
191
+ }
192
+
193
+
194
+ /**
195
+ * Helps to find the value from the given data.
196
+ * Supports dotted paths and array indexes in either notation,
197
+ * so `items.0.name` and `items[0].name` both resolve.
198
+ * @param {*} key
199
+ * @param {*} rptData
200
+ * @returns
201
+ */
202
+ function findVal(key, rptData) {
203
+ return key
204
+ .replace(/\[(\d+)\]/g, '.$1')
205
+ .split('.')
206
+ .filter(part => part !== '')
207
+ .reduce((obj, part) => obj?.[part], rptData);
208
+ }
@@ -0,0 +1,129 @@
1
+ /**
2
+ * search.js finds text across a built report.
3
+ *
4
+ * Spec 2.2: the page list is the seam, and search is one of the consumers that
5
+ * reads only it. So this walks the same structure the renderer draws and knows
6
+ * nothing about grouping, measurement, or the DOM - which is what lets the
7
+ * vanilla preview and a future React Preview share one implementation.
8
+ */
9
+
10
+
11
+ /**
12
+ * Every occurrence of {query} in a built report, in page order.
13
+ *
14
+ * @param {object[]} pages the `pages` array from buildPages
15
+ * @param {string} query what to look for; blank returns no matches
16
+ * @param {object} [options]
17
+ * @param {boolean} [options.caseSensitive=false]
18
+ * @returns {object[]} matches, each { pageNO, bandType, itemId, field, text, start, end }
19
+ */
20
+ export function search(pages, query, { caseSensitive = false } = {}) {
21
+ const needle = String(query ?? '');
22
+ if (needle === '') return [];
23
+
24
+ const matches = [];
25
+
26
+ for (const page of (pages ?? [])) {
27
+ for (const band of (page.bands ?? [])) {
28
+ collectBand(band, page.pageNO, band.type, needle, caseSensitive, matches);
29
+ }
30
+ }
31
+
32
+ return matches;
33
+ }
34
+
35
+
36
+ /**
37
+ * The distinct pages a query appears on, in order. Handy for a page-at-a-time
38
+ * viewer, which cares which pages to offer before it cares about offsets.
39
+ * @param {object[]} pages
40
+ * @param {string} query
41
+ * @param {object} [options]
42
+ * @returns {number[]}
43
+ */
44
+ export function searchPages(pages, query, options) {
45
+ return [...new Set(search(pages, query, options).map(m => m.pageNO))];
46
+ }
47
+
48
+
49
+ function collectBand(band, pageNO, bandType, needle, caseSensitive, matches) {
50
+ for (const item of (band?.items ?? [])) {
51
+ if (item.type === 'text') {
52
+ push(matches, item.text, {
53
+ pageNO, bandType, itemId: item.id, field: null
54
+ }, needle, caseSensitive);
55
+ continue;
56
+ }
57
+
58
+ if (item.type === 'table') {
59
+ collectTable(item, pageNO, bandType, needle, caseSensitive, matches);
60
+ }
61
+ }
62
+ }
63
+
64
+
65
+ function collectTable(item, pageNO, bandType, needle, caseSensitive, matches) {
66
+ const columns = item.columns ?? [];
67
+
68
+ if (item.showHeader) {
69
+ for (const column of columns) {
70
+ push(matches, column.label, {
71
+ pageNO, bandType, itemId: item.id, field: column.field
72
+ }, needle, caseSensitive);
73
+ }
74
+ }
75
+
76
+ if (item.row) {
77
+ collectRows(item.row, columns, item.id, pageNO, bandType, needle, caseSensitive, matches);
78
+ return;
79
+ }
80
+
81
+ /** a grouped table carries its rows inside per-group fragments */
82
+ for (const fragment of (item.groups ?? [])) {
83
+ collectBand(fragment.headerBand, pageNO, 'groupHeader', needle, caseSensitive, matches);
84
+ collectRows(fragment.rows, columns, item.id, pageNO, bandType, needle, caseSensitive, matches);
85
+ if (fragment.showFooter) {
86
+ collectBand(fragment.footerBand, pageNO, 'groupFooter', needle, caseSensitive, matches);
87
+ }
88
+ }
89
+ }
90
+
91
+
92
+ function collectRows(rows, columns, itemId, pageNO, bandType, needle, caseSensitive, matches) {
93
+ for (const row of (rows ?? [])) {
94
+ for (const column of columns) {
95
+ push(matches, row?.[column.field], {
96
+ pageNO, bandType, itemId, field: column.field
97
+ }, needle, caseSensitive);
98
+ }
99
+ }
100
+ }
101
+
102
+
103
+ /**
104
+ * Records every occurrence within one string, not just the first - a page that
105
+ * says "Cable" three times should count as three hits.
106
+ */
107
+ function push(matches, value, where, needle, caseSensitive) {
108
+ if (value == null) return;
109
+
110
+ const text = String(value);
111
+ const haystack = caseSensitive ? text : text.toLowerCase();
112
+ const target = caseSensitive ? needle : needle.toLowerCase();
113
+
114
+ let from = 0;
115
+
116
+ while (from <= haystack.length - target.length) {
117
+ const at = haystack.indexOf(target, from);
118
+ if (at === -1) break;
119
+
120
+ matches.push({
121
+ ...where,
122
+ text,
123
+ start: at,
124
+ end: at + target.length
125
+ });
126
+
127
+ from = at + target.length;
128
+ }
129
+ }
@@ -0,0 +1,87 @@
1
+ /**
2
+ * tables.js answers the questions every stage asks about a report's tables:
3
+ * which there are, which dataset each reads, and which one is grouped.
4
+ *
5
+ * A report used to have one table, so each stage found "the" table on its own -
6
+ * and three copies of "the first table in the first band that has one" agreed
7
+ * only because there was never a second. With more than one, a stage that
8
+ * picked a different table from the others would bind rows to one table and
9
+ * group bands to another. So the rules live here, once.
10
+ *
11
+ * Nothing here throws or validates; validate.js says what is wrong with a
12
+ * layout, and these read whatever they are given as far as it goes.
13
+ */
14
+
15
+
16
+ /**
17
+ * Every table in the layout, in band order and then item order.
18
+ *
19
+ * Band order is the file's, which is page order for any layout the designer
20
+ * wrote - and it is the order "the first table" has always meant.
21
+ *
22
+ * @param {object} layout
23
+ * @returns {object[]} the table items themselves, not copies
24
+ */
25
+ export function tablesOf(layout) {
26
+ const found = [];
27
+
28
+ for (const band of (Array.isArray(layout?.bands) ? layout.bands : [])) {
29
+ for (const item of (Array.isArray(band?.items) ? band.items : [])) {
30
+ if (item?.type === 'table') found.push(item);
31
+ }
32
+ }
33
+
34
+ return found;
35
+ }
36
+
37
+
38
+ /**
39
+ * The dataset a table reads its rows from: its own, or the report's.
40
+ *
41
+ * @param {object} table
42
+ * @param {object} layout
43
+ * @returns {string|null}
44
+ */
45
+ export function datasetOf(table, layout) {
46
+ const own = typeof table?.dataset === 'string' && table.dataset !== '' ? table.dataset : null;
47
+ return own ?? layout?.dataset ?? null;
48
+ }
49
+
50
+
51
+ /**
52
+ * Whether a table asks to be grouped by a field of its own.
53
+ * @param {object} table
54
+ * @returns {boolean}
55
+ */
56
+ export function hasOwnGrouping(table) {
57
+ return typeof table?.groupBy === 'string' && table.groupBy !== '';
58
+ }
59
+
60
+
61
+ /**
62
+ * The grouped table, and the field it is grouped by.
63
+ *
64
+ * A table that names its own `groupBy` is the one. Failing that, a report-wide
65
+ * `layout.groupBy` - which is what every layout written before a report could
66
+ * hold two tables says - means the first table, since that was the only one it
67
+ * could have meant.
68
+ *
69
+ * One at most: groupHeader and groupFooter are the report's bands, not a
70
+ * table's, so two grouped tables would have to share one heading design.
71
+ * validate.js refuses a second; this takes the first.
72
+ *
73
+ * @param {object} layout
74
+ * @returns {{table: object, by: string}|null}
75
+ */
76
+ export function groupingOf(layout) {
77
+ const tables = tablesOf(layout);
78
+
79
+ const own = tables.find(hasOwnGrouping);
80
+ if (own) return { table: own, by: own.groupBy };
81
+
82
+ if (layout?.groupBy != null && tables.length > 0) {
83
+ return { table: tables[0], by: layout.groupBy };
84
+ }
85
+
86
+ return null;
87
+ }