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,367 @@
1
+ /**
2
+ * group.js binds every table to its rows, partitions the grouped one, and
3
+ * resolves aggregate placeholders.
4
+ *
5
+ * An aggregate has to be worked out over some set of rows, and there are only
6
+ * two sets a band can mean:
7
+ *
8
+ * groupHeader / groupFooter - that group's rows, and only that group's.
9
+ * They are templates rather than bands: one copy is drawn per group, so
10
+ * each copy has a different answer. Filled in per fragment by paginate.js,
11
+ * where which group is being drawn is known.
12
+ *
13
+ * every other band - a whole dataset. Filled in here, once.
14
+ *
15
+ * Which dataset, now that a report can hold more than one table: the one the
16
+ * expression names, as `{sum(sales.amount)}` or `{count(sales)}`, and the
17
+ * first table's when it names none - which is what every expression written
18
+ * before there could be a second table meant.
19
+ */
20
+
21
+ import { ReportError } from './validate.js';
22
+ import { tablesOf, datasetOf, groupingOf } from './tables.js';
23
+
24
+
25
+ const REGEX = /\{([^{}]+)\}/g;
26
+
27
+
28
+ export function group(resolvedJson, data) {
29
+ const json = structuredClone(resolvedJson);
30
+ const bands = json.bands;
31
+ const tables = tablesOf(json);
32
+
33
+ if (json.groupBy != null && tables.length === 0) {
34
+ throw new ReportError(
35
+ `group: layout.groupBy is "${json.groupBy}" but no band contains a table to group`
36
+ );
37
+ }
38
+
39
+ const grouping = groupingOf(json);
40
+ const named = namedDatasets(data);
41
+
42
+ /** the rows each table reads, bound as they are found */
43
+ const bound = tables.map(table => {
44
+ const rows = datasetFor(table, json, data);
45
+ named.set(datasetOf(table, json), rows);
46
+ return { table, rows };
47
+ });
48
+
49
+ for (const { table, rows } of bound) {
50
+ if (table === grouping?.table) {
51
+ bindGroups(table, rows, grouping.by, bands, datasetOf(table, json));
52
+ } else {
53
+ table.row = rows;
54
+ }
55
+ }
56
+
57
+ /** a report of nothing but text bands is legal - there is simply nothing to bind */
58
+ const scope = { rows: bound[0]?.rows ?? [], named };
59
+
60
+ aggregate(bands, scope);
61
+ return json;
62
+ }
63
+
64
+
65
+ /**
66
+ * Splits the grouped table's rows into groups, each carrying its own totals.
67
+ * @param {object} table
68
+ * @param {object[]} rows
69
+ * @param {string} by the field that decides which group a row is in
70
+ * @param {object[]} bands
71
+ * @param {string|null} dataset the table's dataset name, which a group band's
72
+ * aggregate may carry as a prefix
73
+ */
74
+ function bindGroups(table, rows, by, bands, dataset) {
75
+ const groupedData = groupedRows(rows, by);
76
+ const groupedAggregates = groupedAggregate(bands, groupedData, dataset);
77
+
78
+ table.groups = Object.entries(groupedData).map(([key, groupRows]) => ({
79
+ key,
80
+ rows: groupRows,
81
+ aggregates: groupedAggregates[key]
82
+ }));
83
+ }
84
+
85
+
86
+ /**
87
+ * Every top-level array in the payload, by name - the datasets an aggregate
88
+ * can name. Not only the ones a table is bound to: a total of payments is a
89
+ * reasonable thing to print under an invoice that draws no table of them.
90
+ * @param {object} data
91
+ * @returns {Map<string, object[]>}
92
+ */
93
+ function namedDatasets(data) {
94
+ const found = new Map();
95
+
96
+ for (const [name, value] of Object.entries(data ?? {})) {
97
+ if (Array.isArray(value)) found.set(name, value);
98
+ }
99
+
100
+ return found;
101
+ }
102
+
103
+
104
+ /**
105
+ * The rows a table is bound to. A missing dataset is a layout/data mismatch
106
+ * worth naming rather than a silent empty table.
107
+ * @param {object} table the table item
108
+ * @param {object} json
109
+ * @param {object} data
110
+ * @returns {object[]}
111
+ */
112
+ function datasetFor(table, json, data) {
113
+ const key = datasetOf(table, json);
114
+ const dataset = key == null ? undefined : data[key];
115
+
116
+ if (dataset === undefined) {
117
+ throw new ReportError(
118
+ `group: table "${table.id}" is bound to dataset "${key}", which is not present in the data`
119
+ );
120
+ }
121
+
122
+ if (!Array.isArray(dataset)) {
123
+ throw new ReportError(
124
+ `group: dataset "${key}" must be an array of rows, got ${typeof dataset}`
125
+ );
126
+ }
127
+
128
+ return dataset;
129
+ }
130
+
131
+
132
+ /**
133
+ * The bands whose aggregates belong to one group rather than to the report.
134
+ *
135
+ * They are left alone here on purpose. Filling them in with the report's totals
136
+ * would not merely be the wrong number - it would consume the placeholder, and
137
+ * paginate.js would find nothing left to put the group's own answer into.
138
+ */
139
+ const GROUP_SCOPED = ['groupHeader', 'groupFooter'];
140
+
141
+
142
+ /**
143
+ * Report-wide aggregates: every band except the two that mean a group.
144
+ * @param {object[]} bands
145
+ * @param {{rows: object[], named: Map<string, object[]>}} scope
146
+ */
147
+ function aggregate(bands, scope) {
148
+ for (const band of bands) {
149
+ if (GROUP_SCOPED.includes(band.type)) continue;
150
+
151
+ for (const item of band.items) {
152
+ if (item.type != "text") continue;
153
+
154
+ /**
155
+ * Build on `text`, never on `value`. resolve.js has already put the
156
+ * data placeholders in and deliberately left the aggregate tokens
157
+ * standing; re-resolving from `value` here would discard its work
158
+ * and leave "{authorizer}" printed literally on the report.
159
+ */
160
+ item.text = fillAggregates(item.text ?? item.value, scope);
161
+ }
162
+ }
163
+ }
164
+
165
+
166
+ /**
167
+ * Replaces every aggregate placeholder in a value while keeping the literal
168
+ * text around it, so "Items: {count()}" stays "Items: 48" rather than "48".
169
+ * Non-aggregate placeholders were already handled by resolve.js and are left
170
+ * as they are.
171
+ * @param {string} value
172
+ * @param {{rows: object[], named: Map<string, object[]>}} scope
173
+ * @returns {string}
174
+ */
175
+ function fillAggregates(value, scope) {
176
+ return value.replace(REGEX, (match, key) => {
177
+ const expr = parseAggregate(key.trim());
178
+ if (!expr) return match;
179
+
180
+ const { rows, field } = scoped(expr.field, scope);
181
+ const result = compute({ key: expr.key, field }, rows);
182
+ return result == null ? '' : String(result);
183
+ });
184
+ }
185
+
186
+
187
+ /**
188
+ * Which rows an aggregate's argument means, and which field of them.
189
+ *
190
+ * count(sales) every row of `sales`
191
+ * sum(sales.amount) `amount` over the rows of `sales`
192
+ * sum(amount) `amount` over the first table's rows, as ever
193
+ *
194
+ * A prefix is only a dataset if the payload has an array of that name. Rows are
195
+ * flat, so a dot has never meant anything inside a row field and nothing that
196
+ * worked before is read differently now.
197
+ *
198
+ * @param {string} field the expression's argument
199
+ * @param {{rows: object[], named: Map<string, object[]>}} scope
200
+ * @returns {{rows: object[], field: string}}
201
+ */
202
+ function scoped(field, scope) {
203
+ if (scope.named.has(field)) return { rows: scope.named.get(field), field: '' };
204
+
205
+ const dot = field.indexOf('.');
206
+
207
+ if (dot > 0) {
208
+ const name = field.slice(0, dot);
209
+ if (scope.named.has(name)) {
210
+ return { rows: scope.named.get(name), field: field.slice(dot + 1) };
211
+ }
212
+ }
213
+
214
+ return { rows: scope.rows, field };
215
+ }
216
+
217
+
218
+ function parseAggregate(expr) {
219
+ const match = expr.match(/^(\w+)\((.*?)\)$/);
220
+ if (!match) return null;
221
+ return {
222
+ key: match[1],
223
+ field: match[2].trim()
224
+ }
225
+ }
226
+
227
+
228
+ /**
229
+ * Per-group aggregates, keyed on both dimensions that matter: the group key and
230
+ * the field the expression targets. Dropping either makes groups overwrite each
231
+ * other, or {sum(price)} collide with {sum(qty)}.
232
+ *
233
+ * Both group bands are read, not just the footer. "Region A - 12 orders" is a
234
+ * heading, and a count that worked in the footer and printed blank in the
235
+ * header is the same fault this file exists to have stopped having.
236
+ *
237
+ * Keyed on the expression's argument as written, because that is what
238
+ * paginate.js looks it up by - so `{sum(sales.amount)}` in a group footer is
239
+ * stored under "sales.amount" and computed over the group's `amount`. A group
240
+ * band only ever means its group's rows; naming the grouped dataset is allowed
241
+ * because it is the same thing said in full.
242
+ *
243
+ * Shape: aggregates[groupKey][field] = { count, sum, avg, min, max }
244
+ * @param {object[]} bands
245
+ * @param {object} dataset grouped rows, keyed by group key
246
+ * @param {string|null} name the grouped table's dataset
247
+ * @returns {object}
248
+ */
249
+ function groupedAggregate(bands, dataset, name) {
250
+ const aggregates = {};
251
+
252
+ /** every group gets a slot, even one no groupFooter expression touches */
253
+ for (const key of Object.keys(dataset)) {
254
+ aggregates[key] = {};
255
+ }
256
+
257
+ for (const band of bands) {
258
+ if (!GROUP_SCOPED.includes(band.type)) continue;
259
+
260
+ for (const item of band.items) {
261
+ if (item.type != "text") continue;
262
+
263
+ for (const expr of parseAll(item.value)) {
264
+ const field = withoutScope(expr.field, name);
265
+
266
+ for (const [key, rows] of Object.entries(dataset)) {
267
+ if (!aggregates[key][expr.field]) {
268
+ aggregates[key][expr.field] = {
269
+ count: null,
270
+ sum: null,
271
+ avg: null,
272
+ min: null,
273
+ max: null
274
+ };
275
+ }
276
+
277
+ aggregates[key][expr.field][expr.key] =
278
+ compute({ key: expr.key, field }, rows);
279
+ }
280
+ }
281
+ }
282
+ }
283
+
284
+ return aggregates;
285
+ }
286
+
287
+
288
+ /** `sales.amount` to `amount`, and `sales` to nothing, when sales is the dataset */
289
+ function withoutScope(field, name) {
290
+ if (name == null) return field;
291
+ if (field === name) return '';
292
+ return field.startsWith(`${name}.`) ? field.slice(name.length + 1) : field;
293
+ }
294
+
295
+
296
+ /** every aggregate expression in a value, not just the first */
297
+ function parseAll(value) {
298
+ const found = [];
299
+ for (const [, key] of value.matchAll(REGEX)) {
300
+ const expr = parseAggregate(key.trim());
301
+ if (expr) found.push(expr);
302
+ }
303
+ return found;
304
+ }
305
+
306
+
307
+ function groupedRows(dataset, groupBy) {
308
+ const grouped = {};
309
+ for (const row of dataset) {
310
+ const key = row[groupBy];
311
+ if (!grouped[key]) {
312
+ grouped[key] = [];
313
+ }
314
+ grouped[key].push(row);
315
+ }
316
+ return grouped;
317
+ }
318
+
319
+
320
+ /**
321
+ * Runs one aggregate over one set of rows.
322
+ * Non-numeric cells are skipped rather than counted as zero - a blank price
323
+ * should not drag an average down, and Math.max of nothing is -Infinity, which
324
+ * is not a number anyone wants printed on a report.
325
+ * @param {object} expr {key, field}
326
+ * @param {object[]} rows
327
+ * @returns {number|null} null where the answer is undefined for these rows
328
+ */
329
+ function compute(expr, rows) {
330
+ if (expr.key === 'count') return rows.length;
331
+
332
+ const values = rows
333
+ .map(row => row?.[expr.field])
334
+ /** Number('') is 0, so blanks have to be dropped before coercion */
335
+ .filter(v => v !== null && v !== undefined && v !== '')
336
+ .map(Number)
337
+ .filter(n => Number.isFinite(n));
338
+
339
+ switch (expr.key) {
340
+ case 'sum':
341
+ /** the sum of no rows is zero; the sum of no numbers is not */
342
+ return values.length ? round(values.reduce((a, b) => a + b, 0)) : null;
343
+ case 'avg':
344
+ return values.length
345
+ ? round(values.reduce((a, b) => a + b, 0) / values.length)
346
+ : null;
347
+ case 'max':
348
+ return values.length ? Math.max(...values) : null;
349
+ case 'min':
350
+ return values.length ? Math.min(...values) : null;
351
+ default:
352
+ console.warn(`Unknown aggregate "${expr.key}()"; it has no value.`);
353
+ return null;
354
+ }
355
+ }
356
+
357
+
358
+ /**
359
+ * Floating point sums produce 0.1 + 0.2 = 0.30000000000000004, which has no
360
+ * place on a printed report. Twelve significant digits is well past any real
361
+ * currency or quantity and short of the artefacts.
362
+ * @param {number} n
363
+ * @returns {number}
364
+ */
365
+ function round(n) {
366
+ return Number(n.toPrecision(12));
367
+ }
@@ -0,0 +1,35 @@
1
+ /**
2
+ * The engine's public surface.
3
+ *
4
+ * Spec 4: buildPages(layout, data) -> PageList, in four ordered stages, each a
5
+ * pure function over plain objects. Nothing here imports React, and nothing
6
+ * here touches the DOM beyond the offscreen canvas used for text measurement.
7
+ */
8
+
9
+ import { resolve } from './resolve.js';
10
+ import { group } from './group.js';
11
+ import { measure } from './measure.js';
12
+ import { paginate } from './paginate.js';
13
+
14
+ export { resolve } from './resolve.js';
15
+ export { group } from './group.js';
16
+ export { measure } from './measure.js';
17
+ export { paginate } from './paginate.js';
18
+ export { validateLayout, ReportError } from './validate.js';
19
+ export { search, searchPages } from './search.js';
20
+ export { pageRegions, bandZoneHeight, resolveHeight, DEFAULT_BAND_HEIGHTS } from './regions.js';
21
+ export { toCSV, toReportCSV, reportFilename, reportTables } from './csv.js';
22
+ export { tablesOf, datasetOf, groupingOf } from './tables.js';
23
+ export { measureText, wrapLines, textHeight, LINE_HEIGHT_RATIO } from './text-metrics.js';
24
+
25
+
26
+ /**
27
+ * Turns a layout file plus a data payload into a page list.
28
+ * @param {object} layout the report layout file
29
+ * @param {object} data the host application's data, keyed by dataset name
30
+ * @returns {object} the layout, with a `pages` array of positioned bands
31
+ * @throws {ReportError} when the layout or data cannot be used
32
+ */
33
+ export function buildPages(layout, data) {
34
+ return paginate(measure(group(resolve(layout, data), data)));
35
+ }