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,231 @@
1
+ /**
2
+ * rulers.js is the arithmetic behind the rulers and the guides dragged off them.
3
+ *
4
+ * The alignment guides in guides.js answer "what is this level with?" while
5
+ * something is moving. A ruler answers a different question: where is 240, and
6
+ * can I have a line there. It is the tool for a layout that has to line up with
7
+ * something outside the report - a window in an envelope, a pre-printed form, a
8
+ * column the last six reports used - which nothing already on the page can be
9
+ * aligned to because it is not on the page.
10
+ *
11
+ * Guides live on the layout rather than in the designer's head, so they are
12
+ * saved with the report and come back with it: a column grid worked out once is
13
+ * not something to work out again on Monday. The engine has never read a key it
14
+ * was not looking for, and validate.js does not object to one, so they travel
15
+ * with the file and are ignored by everything that prints it.
16
+ *
17
+ * Coordinates are the printable area's: (0, 0) is inside the margins, which is
18
+ * where an item's own x and y are measured from and therefore what the numbers
19
+ * in the properties rail mean. A ruler that disagreed with the rail would be
20
+ * worse than no ruler.
21
+ */
22
+
23
+
24
+ /** the fine ticks, matching the 10px grid a drag already snaps to */
25
+ export const MINOR = 10;
26
+
27
+ /** and the ones that carry a number */
28
+ export const MAJOR = 50;
29
+
30
+ /**
31
+ * How near the pointer has to be to a guide to pick it up rather than the item
32
+ * under it. A guide is one pixel wide, which nobody can hit.
33
+ */
34
+ export const GRAB = 4;
35
+
36
+
37
+ /**
38
+ * The marks on a ruler of a given length.
39
+ *
40
+ * Both ends are included: the last tick is the edge of the printable area, and
41
+ * a ruler that stopped short of it would be saying the page does.
42
+ *
43
+ * @param {number} length in px
44
+ * @param {object} [options]
45
+ * @param {number} [options.minor] the fine spacing
46
+ * @param {number} [options.major] the labelled spacing; must be a multiple of minor
47
+ * @returns {{at: number, major: boolean}[]}
48
+ */
49
+ export function ticksFor(length, { minor = MINOR, major = MAJOR } = {}) {
50
+ const ticks = [];
51
+
52
+ if (!(length > 0) || !(minor > 0)) return ticks;
53
+
54
+ for (let at = 0; at <= length; at += minor) {
55
+ ticks.push({ at, major: at % major === 0 });
56
+ }
57
+
58
+ /** a length that is not a whole number of ticks still ends where it ends */
59
+ const last = ticks.at(-1);
60
+ if (last && last.at !== length) ticks.push({ at: length, major: true });
61
+
62
+ return ticks;
63
+ }
64
+
65
+
66
+ /**
67
+ * The guides a layout carries, always as two arrays.
68
+ *
69
+ * Read through here rather than off the object, because a layout written by
70
+ * hand - or saved before guides existed - has no `guides` key at all, and every
71
+ * caller having to remember that is how a designer ends up throwing on somebody
72
+ * else's file.
73
+ *
74
+ * @param {object} layout
75
+ * @returns {{x: number[], y: number[]}} sorted, and safe to read
76
+ */
77
+ export function guidesOf(layout) {
78
+ const found = layout?.guides;
79
+
80
+ /**
81
+ * Number(null) is 0, and so is Number('') - so what is not a number has to
82
+ * be dropped before the coercion, or a null in a hand-edited file becomes a
83
+ * guide down the left edge that nobody put there and nobody can explain.
84
+ */
85
+ const axis = (list) => (Array.isArray(list) ? list : [])
86
+ .filter(usable)
87
+ .map(Number)
88
+ .filter(Number.isFinite)
89
+ .sort((a, b) => a - b);
90
+
91
+ return { x: axis(found?.x), y: axis(found?.y) };
92
+ }
93
+
94
+
95
+ /** something that could be a position, as opposed to something Number() pities */
96
+ function usable(value) {
97
+ if (typeof value === 'number') return true;
98
+
99
+ return typeof value === 'string' && value.trim() !== '';
100
+ }
101
+
102
+
103
+ /** the layout's guides object, created on the layout if it has none yet */
104
+ function guideStore(layout) {
105
+ if (!layout.guides || typeof layout.guides !== 'object') {
106
+ layout.guides = { x: [], y: [] };
107
+ }
108
+
109
+ for (const axis of ['x', 'y']) {
110
+ if (!Array.isArray(layout.guides[axis])) layout.guides[axis] = [];
111
+ }
112
+
113
+ return layout.guides;
114
+ }
115
+
116
+
117
+ /**
118
+ * Puts a guide on an axis.
119
+ *
120
+ * Rounded to the pixel, because a guide dragged to 240.3 is a guide at 240 that
121
+ * nothing will ever quite line up with. Duplicates are dropped rather than
122
+ * stacked: two guides on one line are indistinguishable on screen and the
123
+ * second one can only be deleted by accident.
124
+ *
125
+ * @param {object} layout mutated in place, as the rest of structure.js does
126
+ * @param {'x'|'y'} axis
127
+ * @param {number} at
128
+ * @returns {number|null} where it landed, or null if it was not a usable number
129
+ */
130
+ export function addGuide(layout, axis, at) {
131
+ if (!usable(at)) return null;
132
+
133
+ const value = Math.round(Number(at));
134
+ if (!Number.isFinite(value)) return null;
135
+
136
+ const store = guideStore(layout);
137
+
138
+ if (!store[axis].includes(value)) {
139
+ store[axis].push(value);
140
+ store[axis].sort((a, b) => a - b);
141
+ }
142
+
143
+ return value;
144
+ }
145
+
146
+
147
+ /**
148
+ * Takes one off.
149
+ *
150
+ * @param {object} layout
151
+ * @param {'x'|'y'} axis
152
+ * @param {number} at the guide's current position
153
+ * @returns {boolean} whether there was one there
154
+ */
155
+ export function removeGuide(layout, axis, at) {
156
+ const store = guideStore(layout);
157
+ const index = store[axis].indexOf(Math.round(Number(at)));
158
+
159
+ if (index === -1) return false;
160
+
161
+ store[axis].splice(index, 1);
162
+ return true;
163
+ }
164
+
165
+
166
+ /**
167
+ * Moves one, which is a remove and an add - so a guide dragged onto another
168
+ * merges with it rather than hiding it.
169
+ *
170
+ * @param {object} layout
171
+ * @param {'x'|'y'} axis
172
+ * @param {number} from
173
+ * @param {number} to
174
+ * @returns {number|null} where it ended up
175
+ */
176
+ export function moveGuide(layout, axis, from, to) {
177
+ removeGuide(layout, axis, from);
178
+ return addGuide(layout, axis, to);
179
+ }
180
+
181
+
182
+ /**
183
+ * The guide nearest a point on an axis, if one is close enough to have been
184
+ * meant. What makes a guide draggable at all: it is one pixel wide.
185
+ *
186
+ * @param {object} layout
187
+ * @param {'x'|'y'} axis
188
+ * @param {number} at
189
+ * @param {number} [within]
190
+ * @returns {number|null} the guide's position
191
+ */
192
+ export function guideNear(layout, axis, at, within = GRAB) {
193
+ let best = null;
194
+
195
+ for (const guide of guidesOf(layout)[axis]) {
196
+ const distance = Math.abs(guide - at);
197
+
198
+ if (distance <= within && (best === null || distance < Math.abs(best - at))) {
199
+ best = guide;
200
+ }
201
+ }
202
+
203
+ return best;
204
+ }
205
+
206
+
207
+ /**
208
+ * The guides that apply inside one band, in that band's own coordinates.
209
+ *
210
+ * A vertical guide needs no conversion - a band's x origin is the printable
211
+ * area's. A horizontal one does: the same guide is a different `y` in every
212
+ * band, which is the whole reason bands hold their items in their own
213
+ * coordinates in the first place.
214
+ *
215
+ * @param {object} layout
216
+ * @param {{originY: number, h: number}} band from canvas.bandBox
217
+ * @returns {{x: number[], y: number[]}}
218
+ */
219
+ export function guidesInBand(layout, band) {
220
+ const all = guidesOf(layout);
221
+
222
+ if (!band) return { x: all.x, y: [] };
223
+
224
+ return {
225
+ x: all.x,
226
+ /** only the ones that actually cross this band; the rest are elsewhere */
227
+ y: all.y
228
+ .map(at => at - (band.originY ?? 0))
229
+ .filter(at => at >= 0 && at <= (band.h ?? 0))
230
+ };
231
+ }
@@ -0,0 +1,411 @@
1
+ /**
2
+ * sample-data.js works out what data a report is asking for, and writes a
3
+ * payload of the right shape to fill in.
4
+ *
5
+ * A layout is a set of questions - `{customer.name}`, a column on `amount`,
6
+ * grouping by `region` - and until now the only way to learn what they were was
7
+ * to run the report and read the "unresolved placeholder" warnings. This reads
8
+ * them off the layout instead and hands back a `.data.json` with every key in
9
+ * place, so the host application knows exactly what it has to supply.
10
+ *
11
+ * The rules for what comes from the data are imported from resolve.js rather
12
+ * than restated. A second copy of them here would drift, and it would drift in
13
+ * the direction of asking the user for `{page}` while forgetting
14
+ * `{customer.name}` - the two mistakes that make such a file worse than none.
15
+ *
16
+ * Which scope a bare `{name}` belongs to follows the engine (spec 3.4): a
17
+ * dotted path is always the root, and a bare key is a row field inside a
18
+ * row-scoped band and a root key anywhere else.
19
+ */
20
+
21
+ import { PLACEHOLDER, isEngineKey, isRowScoped } from '../engine/resolve.js';
22
+ import { groupingOf, datasetOf } from '../engine/tables.js';
23
+
24
+
25
+ /** enough rows to show a group break, few enough to read at a glance */
26
+ const ROWS = 6;
27
+ const GROUPS = ['North', 'South'];
28
+
29
+ /** field names that plainly want a number rather than a word */
30
+ const NUMERIC = /(amount|amt|price|qty|quantity|total|subtotal|cost|rate|balance|discount|tax)$/i;
31
+
32
+ /** an aggregate expression, for the fields the layout takes a sum of */
33
+ const AGGREGATE = /\{\s*(\w+)\(([^)]*)\)\s*\}/g;
34
+
35
+ /** and ones that want a date */
36
+ const DATEISH = /(date|day|when)$/i;
37
+
38
+ /**
39
+ * What a bound image previews with: a small grey PNG, stored inline.
40
+ *
41
+ * Inline rather than a placeholder service's URL, so a designer opened on a
42
+ * machine with no network still previews - and so opening one does not tell a
43
+ * third party that it has been.
44
+ */
45
+ export const SAMPLE_IMAGE = 'data:image/png;base64,' +
46
+ 'iVBORw0KGgoAAAANSUhEUgAAAAIAAAABCAAAAADRSSBWAAAAC0lEQVR4nGO4eRcAApIBt+wBgUAAAAAASUVORK5CYII=';
47
+
48
+
49
+ /**
50
+ * Every placeholder key a layout asks the data for, with the scope it is read in.
51
+ *
52
+ * @param {object} layout
53
+ * @returns {{root: string[], row: string[]}} paths, de-duplicated
54
+ */
55
+ export function requiredKeys(layout) {
56
+ const root = new Set();
57
+ const row = new Set();
58
+
59
+ for (const band of (Array.isArray(layout?.bands) ? layout.bands : [])) {
60
+ const rowScoped = isRowScoped(band.type);
61
+
62
+ for (const item of (band.items || [])) {
63
+ if (item.type !== 'text' || typeof item.value !== 'string') continue;
64
+
65
+ for (const [, raw] of item.value.matchAll(PLACEHOLDER)) {
66
+ const key = raw.trim();
67
+
68
+ /** answered by the engine, not by the payload */
69
+ if (!key || isEngineKey(key)) continue;
70
+
71
+ /**
72
+ * A dotted path is read from the root wherever it appears -
73
+ * `{customer.name}` in a detail band is still the customer, not
74
+ * a column called "customer.name".
75
+ */
76
+ if (key.includes('.') || !rowScoped) root.add(key);
77
+ else row.add(key);
78
+ }
79
+ }
80
+ }
81
+
82
+ return { root: [...root], row: [...row] };
83
+ }
84
+
85
+
86
+ /**
87
+ * The data paths the layout's images are bound to.
88
+ *
89
+ * Kept apart from requiredKeys because the answer is a different kind of
90
+ * value: a picture's URL, not a word or a figure. Always read from the root -
91
+ * resolve.js looks an image's field up in the payload whatever band it is in.
92
+ *
93
+ * @param {object} layout
94
+ * @returns {string[]} paths, de-duplicated
95
+ */
96
+ export function imageKeys(layout) {
97
+ const found = new Set();
98
+
99
+ for (const band of (Array.isArray(layout?.bands) ? layout.bands : [])) {
100
+ for (const item of (band.items || [])) {
101
+ if (item.type !== 'image' || typeof item.field !== 'string') continue;
102
+
103
+ const key = item.field.trim();
104
+ if (key) found.add(key);
105
+ }
106
+ }
107
+
108
+ return [...found];
109
+ }
110
+
111
+
112
+ /**
113
+ * The dataset key rows are read from, and the fields each row needs.
114
+ *
115
+ * A table names its own dataset and falls back to the report's (spec 3.3), so a
116
+ * layout with two tables over two datasets produces two arrays.
117
+ *
118
+ * @param {object} layout
119
+ * @returns {Map<string, Set<string>>} dataset name to its fields
120
+ */
121
+ export function datasets(layout) {
122
+ const found = new Map();
123
+ const fallback = layout?.dataset || 'rows';
124
+
125
+ const fieldsOf = (name) => {
126
+ if (!found.has(name)) found.set(name, new Set());
127
+ return found.get(name);
128
+ };
129
+
130
+ for (const band of (Array.isArray(layout?.bands) ? layout.bands : [])) {
131
+ for (const item of (band.items || [])) {
132
+ if (item.type !== 'table') continue;
133
+
134
+ const fields = fieldsOf(item.dataset || fallback);
135
+ for (const column of (item.columns || [])) {
136
+ if (column?.field) fields.add(column.field);
137
+ }
138
+ }
139
+ }
140
+
141
+ /**
142
+ * A report can group and place row placeholders without ever drawing a
143
+ * table, so the rows they read are created if anything needs them at all.
144
+ * They are the grouped table's: a group band's `{region}` is read off the
145
+ * rows of the table being grouped, whichever table that is.
146
+ */
147
+ const { row } = requiredKeys(layout);
148
+ const grouping = groupingOf(layout);
149
+ const by = grouping?.by ?? layout?.groupBy ?? null;
150
+
151
+ if (row.length || by) {
152
+ const fields = fieldsOf(
153
+ (grouping && datasetOf(grouping.table, layout)) || fallback);
154
+
155
+ for (const key of row) fields.add(key);
156
+ if (by) fields.add(by);
157
+ }
158
+
159
+ /**
160
+ * `{sum(payments.amount)}` names a dataset of its own, which the report
161
+ * may total without drawing a table of it - so it needs rows as well.
162
+ */
163
+ for (const scoped of scopedAggregates(layout)) {
164
+ fieldsOf(scoped.dataset).add(scoped.field);
165
+ }
166
+
167
+ return found;
168
+ }
169
+
170
+
171
+ /**
172
+ * A sample payload for a layout.
173
+ *
174
+ * Values are chosen from the field's own name - a column called `amount` gets a
175
+ * number and one called `date` gets a date - because a payload of `"string"`
176
+ * everywhere tells you the shape but not whether you have the right column, and
177
+ * a report full of the word "string" is not worth previewing.
178
+ *
179
+ * @param {object} layout
180
+ * @returns {object} a data payload, ready to fill in
181
+ */
182
+ export function sampleData(layout) {
183
+ const data = {};
184
+ const { root } = requiredKeys(layout);
185
+ const summed = summedFields(layout);
186
+
187
+ /** first, so a text placeholder on the same path does not take it as a word */
188
+ for (const path of imageKeys(layout)) place(data, path, SAMPLE_IMAGE);
189
+
190
+ for (const path of root) place(data, path);
191
+
192
+ const groupedBy = groupedFieldsByDataset(layout);
193
+
194
+ for (const [name, fields] of datasets(layout)) {
195
+ data[name] = rowsFor([...fields], groupedBy.get(name) ?? null, summed);
196
+ }
197
+
198
+ return data;
199
+ }
200
+
201
+
202
+ /**
203
+ * A data payload with whatever the layout now asks for and it lacks filled in -
204
+ * and nothing it already has touched.
205
+ *
206
+ * The data file is written once, on the first save, and after that it is the
207
+ * user's: real figures typed into it must survive every later save. But a
208
+ * report goes on growing after that save - a second table, a new placeholder,
209
+ * an image bound to a field - and a file that never learned about them made the
210
+ * preview fail on a dataset "which is not present in the data". So what is
211
+ * missing is added from the sample, and what is there is left as it is.
212
+ *
213
+ * "Missing" is `undefined`, walked down through plain objects. An existing
214
+ * array is a dataset the user owns, so its rows are never added to or edited,
215
+ * even if a column has appeared since; and a value that is present, `null`
216
+ * included, is an answer rather than a gap.
217
+ *
218
+ * @param {object|null} data what is on disk, or nothing
219
+ * @param {object} layout
220
+ * @returns {{data: object, added: boolean}} a new object, never the one given;
221
+ * `added` says whether anything was filled in
222
+ */
223
+ export function completeData(data, layout) {
224
+ const sample = sampleData(layout);
225
+
226
+ if (data == null || typeof data !== 'object' || Array.isArray(data)) {
227
+ return { data: sample, added: true };
228
+ }
229
+
230
+ const out = structuredClone(data);
231
+ const added = fillMissing(out, sample);
232
+
233
+ return { data: out, added };
234
+ }
235
+
236
+
237
+ /** copies into `target` every key of `source` it lacks; says whether it did */
238
+ function fillMissing(target, source) {
239
+ let added = false;
240
+
241
+ for (const [key, value] of Object.entries(source)) {
242
+ const current = target[key];
243
+
244
+ if (current === undefined) {
245
+ target[key] = structuredClone(value);
246
+ added = true;
247
+ continue;
248
+ }
249
+
250
+ const bothObjects = isPlainObject(current) && isPlainObject(value);
251
+ if (bothObjects && fillMissing(current, value)) added = true;
252
+ }
253
+
254
+ return added;
255
+ }
256
+
257
+
258
+ function isPlainObject(value) {
259
+ return value != null && typeof value === 'object' && !Array.isArray(value);
260
+ }
261
+
262
+
263
+ /**
264
+ * The fields the layout takes an aggregate over.
265
+ *
266
+ * A field called `amt` is not one the name heuristic recognises, so it used to
267
+ * get the word "Amt 1" - and `{sum(amt)}` over six words is not a number, so
268
+ * the total the report was designed around previewed blank. The layout has
269
+ * already said what it is: you do not sum a word. That is a better answer than
270
+ * a longer list of names, because it is the report's own.
271
+ *
272
+ * `count()` is left out on purpose - it takes no field, and the empty string it
273
+ * would contribute is not one.
274
+ *
275
+ * @param {object} layout
276
+ * @returns {Set<string>}
277
+ */
278
+ export function summedFields(layout) {
279
+ const found = new Set();
280
+
281
+ for (const band of (Array.isArray(layout?.bands) ? layout.bands : [])) {
282
+ for (const item of (band.items || [])) {
283
+ if (item.type !== 'text') continue;
284
+
285
+ for (const [, , field] of String(item.value ?? '').matchAll(AGGREGATE)) {
286
+ const name = field.trim();
287
+ if (!name) continue;
288
+
289
+ found.add(name);
290
+
291
+ /** `sales.amount` sums the `amount` of each row of sales */
292
+ if (name.includes('.')) found.add(name.slice(name.indexOf('.') + 1));
293
+ }
294
+ }
295
+ }
296
+
297
+ return found;
298
+ }
299
+
300
+
301
+ /**
302
+ * The field each dataset is grouped by - one at most, the grouped table's.
303
+ * @param {object} layout
304
+ * @returns {Map<string, string>}
305
+ */
306
+ function groupedFieldsByDataset(layout) {
307
+ const found = new Map();
308
+ const grouping = groupingOf(layout);
309
+
310
+ if (grouping) {
311
+ found.set(datasetOf(grouping.table, layout) || layout?.dataset || 'rows', grouping.by);
312
+ }
313
+
314
+ return found;
315
+ }
316
+
317
+
318
+ /**
319
+ * Aggregates that name a dataset, as `{sum(payments.amount)}`: the dataset,
320
+ * and the field of it. The prefix is taken to be a dataset whether or not a
321
+ * table reads it - that is what the engine does when the payload has one.
322
+ * @param {object} layout
323
+ * @returns {{dataset: string, field: string}[]}
324
+ */
325
+ function scopedAggregates(layout) {
326
+ const found = [];
327
+
328
+ for (const band of (Array.isArray(layout?.bands) ? layout.bands : [])) {
329
+ for (const item of (band.items || [])) {
330
+ if (item.type !== 'text') continue;
331
+
332
+ for (const [, , arg] of String(item.value ?? '').matchAll(AGGREGATE)) {
333
+ const [dataset, ...rest] = arg.trim().split('.');
334
+ const field = rest.join('.');
335
+
336
+ if (dataset && field) found.push({ dataset, field });
337
+ }
338
+ }
339
+ }
340
+
341
+ return found;
342
+ }
343
+
344
+
345
+ /**
346
+ * Writes a value at a dotted path, building the objects on the way down.
347
+ * @param {object} data
348
+ * @param {string} path
349
+ * @param {*} [value] what to write; a value made up from the key when absent
350
+ */
351
+ function place(data, path, value) {
352
+ const parts = path.split('.').filter(Boolean);
353
+ if (!parts.length) return;
354
+
355
+ const last = parts.pop();
356
+ let node = data;
357
+
358
+ for (const part of parts) {
359
+ if (node[part] == null || typeof node[part] !== 'object') node[part] = {};
360
+ node = node[part];
361
+ }
362
+
363
+ if (node[last] === undefined) node[last] = value ?? valueFor(last, 0);
364
+ }
365
+
366
+
367
+ function rowsFor(fields, groupBy, summed = new Set()) {
368
+ if (!fields.length) return [];
369
+
370
+ return Array.from({ length: ROWS }, (_, index) => {
371
+ const row = {};
372
+
373
+ for (const field of fields) {
374
+ /**
375
+ * The grouping field repeats, or every row is its own group and the
376
+ * sample shows nothing about how grouping looks.
377
+ */
378
+ row[field] = field === groupBy
379
+ ? GROUPS[index % GROUPS.length]
380
+ : valueFor(field, index, summed.has(field));
381
+ }
382
+
383
+ return row;
384
+ });
385
+ }
386
+
387
+
388
+ function valueFor(field, index, summed = false) {
389
+ if (summed || NUMERIC.test(field)) return (index + 1) * 250;
390
+
391
+ if (DATEISH.test(field)) {
392
+ /** fixed, not today's: a sample file that changes every read diffs badly */
393
+ const day = String((index % 28) + 1).padStart(2, '0');
394
+ return `2026-06-${day}`;
395
+ }
396
+
397
+ /** the field's own name, so a mis-mapped column is obvious on the page */
398
+ return `${label(field)} ${index + 1}`;
399
+ }
400
+
401
+
402
+ /** "customerName" and "customer_name" both read back as "Customer name" */
403
+ function label(field) {
404
+ const words = String(field)
405
+ .replace(/[_-]+/g, ' ')
406
+ .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
407
+ .trim()
408
+ .toLowerCase();
409
+
410
+ return words.charAt(0).toUpperCase() + words.slice(1);
411
+ }