report-studio 1.2.2 → 1.3.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 (46) hide show
  1. package/README.md +254 -3
  2. package/dist/designer-Dj330bWd.js +4690 -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-BewnkhfP.js +4028 -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/designer.js +313 -12
  12. package/src/designer/dialog.js +609 -5
  13. package/src/designer/fields.js +128 -11
  14. package/src/designer/geometry.js +77 -4
  15. package/src/designer/grouping.js +556 -0
  16. package/src/designer/icons.js +9 -0
  17. package/src/designer/menu.js +50 -6
  18. package/src/designer/panel.js +478 -38
  19. package/src/designer/rulers.js +14 -6
  20. package/src/designer/sample-data.js +112 -31
  21. package/src/designer/select.js +3 -2
  22. package/src/designer/structure.js +126 -12
  23. package/src/designer/styles.css +661 -27
  24. package/src/designer/tokens.js +38 -11
  25. package/src/engine/calculate.js +487 -0
  26. package/src/engine/csv.js +17 -9
  27. package/src/engine/format.js +483 -0
  28. package/src/engine/group.js +350 -70
  29. package/src/engine/highlight.js +224 -0
  30. package/src/engine/index.js +8 -1
  31. package/src/engine/measure.js +53 -26
  32. package/src/engine/paginate.js +189 -92
  33. package/src/engine/resolve.js +117 -10
  34. package/src/engine/rows.js +71 -8
  35. package/src/engine/search.js +12 -4
  36. package/src/engine/tables.js +309 -11
  37. package/src/engine/validate.js +265 -8
  38. package/src/engine/xlsx-style.js +50 -4
  39. package/src/engine/xlsx.js +91 -21
  40. package/src/index.js +18 -0
  41. package/src/render/items.js +61 -10
  42. package/src/render/report.css +0 -5
  43. package/types/index.d.ts +96 -8
  44. package/types/layout.d.ts +156 -2
  45. package/dist/designer-DQlfKnTr.js +0 -3416
  46. package/dist/viewer-BSPNCNRU.js +0 -2912
@@ -19,7 +19,8 @@
19
19
  */
20
20
 
21
21
  import { PLACEHOLDER, isEngineKey, isRowScoped } from '../engine/resolve.js';
22
- import { groupingOf, datasetOf } from '../engine/tables.js';
22
+ import { groupingsOf, datasetOf, tablesOf, levelsOf } from '../engine/tables.js';
23
+ import { isCalculated, expressionFields } from '../engine/calculate.js';
23
24
 
24
25
 
25
26
  /** enough rows to show a group break, few enough to read at a glance */
@@ -30,7 +31,11 @@ const GROUPS = ['North', 'South'];
30
31
  const NUMERIC = /(amount|amt|price|qty|quantity|total|subtotal|cost|rate|balance|discount|tax)$/i;
31
32
 
32
33
  /** an aggregate expression, for the fields the layout takes a sum of */
33
- const AGGREGATE = /\{\s*(\w+)\(([^)]*)\)\s*\}/g;
34
+ /**
35
+ * An aggregate and its field, wherever it stands - on its own, `{sum(amount)}`,
36
+ * or inside another, `{percentage(sum(amount), 50000)}`.
37
+ */
38
+ const AGGREGATE = /\b(count|sum|avg|min|max)\(([^()]*)\)/g;
34
39
 
35
40
  /** and ones that want a date */
36
41
  const DATEISH = /(date|day|when)$/i;
@@ -53,13 +58,47 @@ export const SAMPLE_IMAGE = 'data:image/png;base64,' +
53
58
  * @returns {{root: string[], row: string[]}} paths, de-duplicated
54
59
  */
55
60
  export function requiredKeys(layout) {
61
+ return keysIn(everyBand(layout));
62
+ }
63
+
64
+
65
+ /**
66
+ * Every band whose items the report prints, as `{ band, rowScoped }`: the
67
+ * report's own, and each grouped table's group bands - which are row-scoped
68
+ * whatever they say their type is, since that is where they are drawn.
69
+ *
70
+ * @param {object} layout
71
+ * @returns {{band: object, rowScoped: boolean}[]}
72
+ */
73
+ function everyBand(layout) {
74
+ const report = (Array.isArray(layout?.bands) ? layout.bands : [])
75
+ .map(band => ({ band, rowScoped: isRowScoped(band?.type) }));
76
+
77
+ return [...report, ...tableGroupBands(tablesOf(layout))
78
+ .map(band => ({ band, rowScoped: true }))];
79
+ }
80
+
81
+
82
+ /** the group bands the given tables carry, skipping any that are not bands */
83
+ function tableGroupBands(tables) {
84
+ return tables
85
+ .flatMap(table => levelsOf(table))
86
+ .flatMap(level => [level?.header, level?.footer])
87
+ .filter(band => band && typeof band === 'object' && Array.isArray(band.items));
88
+ }
89
+
90
+
91
+ /**
92
+ * The placeholder keys in some bands, split by the scope each is read in.
93
+ * @param {{band: object, rowScoped: boolean}[]} bands
94
+ * @returns {{root: string[], row: string[]}}
95
+ */
96
+ function keysIn(bands) {
56
97
  const root = new Set();
57
98
  const row = new Set();
58
99
 
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 || [])) {
100
+ for (const { band, rowScoped } of bands) {
101
+ for (const item of (band?.items || [])) {
63
102
  if (item.type !== 'text' || typeof item.value !== 'string') continue;
64
103
 
65
104
  for (const [, raw] of item.value.matchAll(PLACEHOLDER)) {
@@ -96,7 +135,7 @@ export function requiredKeys(layout) {
96
135
  export function imageKeys(layout) {
97
136
  const found = new Set();
98
137
 
99
- for (const band of (Array.isArray(layout?.bands) ? layout.bands : [])) {
138
+ for (const { band } of everyBand(layout)) {
100
139
  for (const item of (band.items || [])) {
101
140
  if (item.type !== 'image' || typeof item.field !== 'string') continue;
102
141
 
@@ -133,26 +172,55 @@ export function datasets(layout) {
133
172
 
134
173
  const fields = fieldsOf(item.dataset || fallback);
135
174
  for (const column of (item.columns || [])) {
136
- if (column?.field) fields.add(column.field);
175
+ /**
176
+ * A calculated column's own field is worked out, not read: the
177
+ * data needs the fields its calculation reads instead.
178
+ */
179
+ if (isCalculated(column)) {
180
+ for (const name of expressionFields(column.expression)) fields.add(name);
181
+ } else if (column?.field) {
182
+ fields.add(column.field);
183
+ }
137
184
  }
138
185
  }
139
186
  }
140
187
 
188
+ /**
189
+ * Each grouped table's rows carry the field it is grouped by, and the row
190
+ * fields its own group bands print: a group band's `{region}` is read off
191
+ * the rows of the table it belongs to, and no other table's.
192
+ */
193
+ const groupings = groupingsOf(layout);
194
+ const covered = new Set();
195
+
196
+ for (const grouping of groupings) {
197
+ const fields = fieldsOf(datasetOf(grouping.table, layout) || fallback);
198
+ const bands = grouping.levels
199
+ .flatMap(level => [level.header, level.footer])
200
+ .filter(band => band && typeof band === 'object');
201
+
202
+ for (const level of grouping.levels) {
203
+ if (level.by) fields.add(level.by);
204
+ }
205
+
206
+ for (const band of bands) covered.add(band);
207
+ for (const key of keysIn(bands.map(band => ({ band, rowScoped: true }))).row) {
208
+ fields.add(key);
209
+ }
210
+ }
211
+
141
212
  /**
142
213
  * 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.
214
+ * table - a group band nothing is grouped by, a `groupBy` with no table to
215
+ * group - so the rows they read are created if anything needs them at all.
146
216
  */
147
- const { row } = requiredKeys(layout);
148
- const grouping = groupingOf(layout);
149
- const by = grouping?.by ?? layout?.groupBy ?? null;
217
+ const loose = keysIn(everyBand(layout).filter(({ band }) => !covered.has(band))).row;
218
+ const by = groupings.length ? null : (layout?.groupBy ?? null);
150
219
 
151
- if (row.length || by) {
152
- const fields = fieldsOf(
153
- (grouping && datasetOf(grouping.table, layout)) || fallback);
220
+ if (loose.length || by) {
221
+ const fields = fieldsOf(fallback);
154
222
 
155
- for (const key of row) fields.add(key);
223
+ for (const key of loose) fields.add(key);
156
224
  if (by) fields.add(by);
157
225
  }
158
226
 
@@ -192,7 +260,7 @@ export function sampleData(layout) {
192
260
  const groupedBy = groupedFieldsByDataset(layout);
193
261
 
194
262
  for (const [name, fields] of datasets(layout)) {
195
- data[name] = rowsFor([...fields], groupedBy.get(name) ?? null, summed);
263
+ data[name] = rowsFor([...fields], groupedBy.get(name) ?? [], summed);
196
264
  }
197
265
 
198
266
  return data;
@@ -278,7 +346,7 @@ function isPlainObject(value) {
278
346
  export function summedFields(layout) {
279
347
  const found = new Set();
280
348
 
281
- for (const band of (Array.isArray(layout?.bands) ? layout.bands : [])) {
349
+ for (const { band } of everyBand(layout)) {
282
350
  for (const item of (band.items || [])) {
283
351
  if (item.type !== 'text') continue;
284
352
 
@@ -299,16 +367,18 @@ export function summedFields(layout) {
299
367
 
300
368
 
301
369
  /**
302
- * The field each dataset is grouped by - one at most, the grouped table's.
370
+ * The fields each dataset is grouped by, outermost level first: each grouped
371
+ * table's, on its own dataset. Two tables grouped differently over one dataset
372
+ * get the first's.
303
373
  * @param {object} layout
304
- * @returns {Map<string, string>}
374
+ * @returns {Map<string, string[]>}
305
375
  */
306
376
  function groupedFieldsByDataset(layout) {
307
377
  const found = new Map();
308
- const grouping = groupingOf(layout);
309
378
 
310
- if (grouping) {
311
- found.set(datasetOf(grouping.table, layout) || layout?.dataset || 'rows', grouping.by);
379
+ for (const grouping of groupingsOf(layout)) {
380
+ const name = datasetOf(grouping.table, layout) || layout?.dataset || 'rows';
381
+ if (!found.has(name)) found.set(name, grouping.levels.map(level => level.by).filter(Boolean));
312
382
  }
313
383
 
314
384
  return found;
@@ -325,7 +395,7 @@ function groupedFieldsByDataset(layout) {
325
395
  function scopedAggregates(layout) {
326
396
  const found = [];
327
397
 
328
- for (const band of (Array.isArray(layout?.bands) ? layout.bands : [])) {
398
+ for (const { band } of everyBand(layout)) {
329
399
  for (const item of (band.items || [])) {
330
400
  if (item.type !== 'text') continue;
331
401
 
@@ -364,6 +434,11 @@ function place(data, path, value) {
364
434
  }
365
435
 
366
436
 
437
+ /**
438
+ * @param {string[]} fields
439
+ * @param {string[]} groupBy the fields the rows are grouped by, outermost first
440
+ * @param {Set<string>} [summed]
441
+ */
367
442
  function rowsFor(fields, groupBy, summed = new Set()) {
368
443
  if (!fields.length) return [];
369
444
 
@@ -371,13 +446,19 @@ function rowsFor(fields, groupBy, summed = new Set()) {
371
446
  const row = {};
372
447
 
373
448
  for (const field of fields) {
449
+ const level = groupBy.indexOf(field);
450
+
374
451
  /**
375
- * The grouping field repeats, or every row is its own group and the
376
- * sample shows nothing about how grouping looks.
452
+ * A grouping field repeats, or every row is its own group and the
453
+ * sample shows nothing about how grouping looks. Each level inside
454
+ * the first changes half as often as the one before, so every outer
455
+ * group holds more than one inner one.
377
456
  */
378
- row[field] = field === groupBy
379
- ? GROUPS[index % GROUPS.length]
380
- : valueFor(field, index, summed.has(field));
457
+ row[field] = level === -1
458
+ ? valueFor(field, index, summed.has(field))
459
+ : level === 0
460
+ ? GROUPS[index % GROUPS.length]
461
+ : `${label(field)} ${Math.floor(index / 2 ** level) % 2 + 1}`;
381
462
  }
382
463
 
383
464
  return row;
@@ -19,6 +19,7 @@ import {
19
19
  itemBox, moveTo, resizeBy, applyBox, resizableAxes, GRID
20
20
  } from './geometry.js';
21
21
  import { bandUnder, bandBox } from './canvas.js';
22
+ import { findBand } from './structure.js';
22
23
  import { guidesFor, gapsAround, unionBox } from './guides.js';
23
24
  import {
24
25
  addGuide, moveGuide, removeGuide, guideNear, guidesInBand
@@ -142,7 +143,7 @@ export function attachEditing({
142
143
  function lookup(one) {
143
144
  if (!one) return null;
144
145
 
145
- const band = (getLayout().bands || []).find(b => b.type === one.band);
146
+ const band = findBand(getLayout(), one.band);
146
147
  return (band?.items || []).find(i => i.id === one.id) ?? null;
147
148
  }
148
149
 
@@ -156,7 +157,7 @@ export function attachEditing({
156
157
  * @returns {object[]} boxes, in band coordinates
157
158
  */
158
159
  function neighbours(bandType, moving) {
159
- const band = (getLayout().bands || []).find(b => b.type === bandType);
160
+ const band = findBand(getLayout(), bandType);
160
161
  const dragged = new Set(moving.map(entry => entry.where.id));
161
162
 
162
163
  return (band?.items || [])
@@ -10,11 +10,19 @@
10
10
  * once. Bands are therefore a *set* of at most seven, not an ordered list, and
11
11
  * their order on the page is regions.js's decision rather than the author's.
12
12
  * That removes reordering from the designer entirely.
13
+ *
14
+ * A grouped table's own group bands are addressed alongside them by a key that
15
+ * names the table - `groupHeader:refunds` - which every function here that
16
+ * takes a band type also takes. See grouping.js.
13
17
  */
14
18
 
15
19
  import { GRID, snap, designHeight } from './geometry.js';
16
20
  import { FONT_STACKS } from './fields.js';
17
- import { absoluteTop, designZones } from './canvas.js';
21
+ import { absolutePoint, designZones } from './canvas.js';
22
+ import {
23
+ GROUP_KINDS, parseBandKey, groupBandAt, groupBandsIn, groupedTables,
24
+ setGroupBand, isGroupKind, needsNormalizing
25
+ } from './grouping.js';
18
26
 
19
27
 
20
28
  /** every band type, in the order they appear down the page */
@@ -141,8 +149,12 @@ function datasetForNewTable(layout) {
141
149
  *
142
150
  * Tables are stacked rather than overlapped - validate.js refuses two that
143
151
  * share any height of a band - so the copy goes below everything on the band
144
- * rather than a step down and across. And it is not grouped by a field of its
145
- * own, since a report groups one table and the original is already that one.
152
+ * rather than a step down and across.
153
+ *
154
+ * A grouping of its own comes with it, header and footer included: any number
155
+ * of tables may be grouped, and a copy that lost its group design would be a
156
+ * copy of only half the table. The older `groupBy` does not, because that
157
+ * borrows the report's group bands and only one table may.
146
158
  *
147
159
  * @param {object} copy mutated in place
148
160
  * @param {object} band the band it is going onto, before the copy is added
@@ -153,11 +165,80 @@ function settleTable(copy, band) {
153
165
  }
154
166
 
155
167
 
168
+ /**
169
+ * A band by its key: a report band by its type, or a table's group band by
170
+ * `groupHeader:<table id>`.
171
+ * @param {object} layout
172
+ * @param {string} type
173
+ * @returns {object|null}
174
+ */
156
175
  export function findBand(layout, type) {
176
+ if (parseBandKey(type)) return groupBandAt(layout, type);
177
+
157
178
  return bandList(layout).find(b => b.type === type) ?? null;
158
179
  }
159
180
 
160
181
 
182
+ /**
183
+ * Every band the report has, by key, in the order they run down the page: a
184
+ * table's group header with the report's own, before the detail, and its
185
+ * footer after.
186
+ *
187
+ * @param {object} layout
188
+ * @returns {string[]}
189
+ */
190
+ export function bandKeys(layout) {
191
+ const tableBands = groupBandsIn(layout);
192
+ const keys = [];
193
+
194
+ for (const type of BAND_TYPES) {
195
+ if (hasBand(layout, type)) keys.push(type);
196
+
197
+ if (GROUP_KINDS.includes(type)) {
198
+ keys.push(...tableBands.filter(b => b.kind === type).map(b => b.key));
199
+ }
200
+ }
201
+
202
+ return keys;
203
+ }
204
+
205
+
206
+ /**
207
+ * The bands the rail offers a checkbox for, in page order: every report band
208
+ * type, and both group bands of each grouped table.
209
+ *
210
+ * The report's own groupHeader and groupFooter are only offered while the
211
+ * report has one, or is grouped the older way and so needs one. A table's
212
+ * grouping carries its own now, and the report's are the older form - left in
213
+ * a file by a report that is no longer grouped, and listed so that they can be
214
+ * removed.
215
+ *
216
+ * @param {object} layout
217
+ * @returns {string[]}
218
+ */
219
+ export function railBands(layout) {
220
+ const grouped = groupedTables(layout);
221
+ const olderForm = needsNormalizing(layout);
222
+ const keys = [];
223
+
224
+ for (const type of BAND_TYPES) {
225
+ if (!GROUP_KINDS.includes(type) || hasBand(layout, type) || olderForm) keys.push(type);
226
+
227
+ if (GROUP_KINDS.includes(type)) {
228
+ const slot = GROUP_KINDS.indexOf(type);
229
+
230
+ /** headers run outermost first down the page, footers innermost first */
231
+ for (const g of grouped) {
232
+ const levels = type === 'groupFooter' ? [...g.levels].reverse() : g.levels;
233
+ keys.push(...levels.map(level => level.keys[slot]));
234
+ }
235
+ }
236
+ }
237
+
238
+ return keys;
239
+ }
240
+
241
+
161
242
  export function hasBand(layout, type) {
162
243
  return findBand(layout, type) != null;
163
244
  }
@@ -171,6 +252,11 @@ export function hasBand(layout, type) {
171
252
  * @returns {object|null} the band, or null if it was already there
172
253
  */
173
254
  export function addBand(layout, type) {
255
+ if (parseBandKey(type)) {
256
+ const made = setGroupBand(layout, type, true);
257
+ return made && typeof made === 'object' ? made : null;
258
+ }
259
+
174
260
  if (!BAND_TYPES.includes(type)) return null;
175
261
  if (hasBand(layout, type)) return null;
176
262
 
@@ -192,9 +278,16 @@ export function addBand(layout, type) {
192
278
 
193
279
  /**
194
280
  * Switches a band off, and everything on it with it.
281
+ *
282
+ * A table's group band is switched off on the table's grouping, which keeps
283
+ * its field; switching off its last one leaves a grouping validate.js names as
284
+ * a problem, as switching off a report band under a groupBy always did.
285
+ *
195
286
  * @returns {boolean} whether there was one to remove
196
287
  */
197
288
  export function removeBand(layout, type) {
289
+ if (parseBandKey(type)) return setGroupBand(layout, type, false) === true;
290
+
198
291
  const at = bandList(layout).findIndex(b => b.type === type);
199
292
  if (at === -1) return false;
200
293
 
@@ -203,13 +296,22 @@ export function removeBand(layout, type) {
203
296
  }
204
297
 
205
298
 
206
- /** every item id in the report, across every band */
299
+ /** every item id in the report, across every band - a table's group bands too */
207
300
  function usedIds(layout) {
208
- return new Set(bandList(layout)
301
+ return new Set([...bandList(layout), ...groupBandsIn(layout).map(g => g.band)]
209
302
  .flatMap(b => (b.items || []).map(i => i.id)));
210
303
  }
211
304
 
212
305
 
306
+ /**
307
+ * Whether an item may go onto a band. Anything may, except a table onto a
308
+ * group band: a group band is drawn inside its table, once per group.
309
+ */
310
+ function fits(type, item) {
311
+ return !(item?.type === 'table' && isGroupKind(type));
312
+ }
313
+
314
+
213
315
  /**
214
316
  * A free id of the form "text-1".
215
317
  *
@@ -433,7 +535,7 @@ export function createTable(layout, band, columns = DEFAULT_COLUMNS) {
433
535
 
434
536
  export function addItem(layout, bandType, item) {
435
537
  const band = findBand(layout, bandType);
436
- if (!band) return null;
538
+ if (!band || !fits(bandType, item)) return null;
437
539
 
438
540
  band.items ??= [];
439
541
  band.items.push(item);
@@ -568,6 +670,7 @@ export function pasteItems(layout, bandType, entries) {
568
670
  * clipboard of five items should place the four it can.
569
671
  */
570
672
  if (item.type === 'table' && !canAddTable(layout)) continue;
673
+ if (!fits(bandType, item)) continue;
571
674
 
572
675
  const copy = structuredClone(item);
573
676
  const y = Math.max(0, (item.y ?? 0) + DUPLICATE_OFFSET);
@@ -621,15 +724,23 @@ export function moveItemToBand(layout, from, to, id) {
621
724
  if (!source || !target) return false;
622
725
 
623
726
  const item = (source.items || []).find(i => i.id === id);
624
- if (!item) return false;
727
+ if (!item || !fits(to, item)) return false;
625
728
 
626
- const page = absoluteTop(layout, from, item.y ?? 0);
729
+ const page = absolutePoint(layout, from, item.x ?? 0, item.y ?? 0);
627
730
 
628
731
  removeItem(layout, from, id);
629
732
  addItem(layout, to, item);
630
733
 
631
- const landed = absoluteTop(layout, to, 0);
632
- if (page !== null && landed !== null) item.y = Math.round(page - landed);
734
+ /**
735
+ * Both axes: a table's group band starts where its table does, so an x
736
+ * carried across unchanged would jump the item sideways by that much.
737
+ */
738
+ const landed = absolutePoint(layout, to, 0, 0);
739
+
740
+ if (page && landed) {
741
+ item.x = Math.round(page.x - landed.x);
742
+ item.y = Math.round(page.y - landed.y);
743
+ }
633
744
 
634
745
  return true;
635
746
  }
@@ -672,10 +783,13 @@ export function removeColumn(table, index) {
672
783
  *
673
784
  * @param {object} layout
674
785
  * @param {{band: string}|null} selection
786
+ * @param {object} [options]
787
+ * @param {boolean} [options.table] it is a table, which no group band takes
675
788
  * @returns {string|null}
676
789
  */
677
- export function targetBand(layout, selection) {
678
- if (selection && hasBand(layout, selection.band)) return selection.band;
790
+ export function targetBand(layout, selection, { table = false } = {}) {
791
+ if (selection && hasBand(layout, selection.band)
792
+ && !(table && isGroupKind(selection.band))) return selection.band;
679
793
  if (hasBand(layout, 'detail')) return 'detail';
680
794
 
681
795
  return bandList(layout)[0]?.type ?? null;