report-studio 0.0.1 → 1.0.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 (63) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +238 -4
  3. package/dist/designer.js +3209 -0
  4. package/dist/index.js +2 -4
  5. package/dist/viewer-D-c0lKzQ.js +1576 -0
  6. package/package.json +66 -33
  7. package/src/asset/images/icon.png +0 -0
  8. package/src/asset/images/logo.png +0 -0
  9. package/src/cli/index.js +282 -0
  10. package/src/cli/serve.js +135 -0
  11. package/src/designer/blank.js +53 -0
  12. package/src/designer/canvas.js +518 -0
  13. package/src/designer/designer.js +1900 -0
  14. package/src/designer/dialog.js +708 -0
  15. package/src/designer/fields.js +584 -0
  16. package/src/designer/geometry.js +154 -0
  17. package/src/designer/guides.js +370 -0
  18. package/src/designer/history.js +113 -0
  19. package/src/designer/icons.js +118 -0
  20. package/src/designer/index.html +28 -0
  21. package/src/designer/main.js +39 -0
  22. package/src/designer/menu.js +126 -0
  23. package/src/designer/panel.js +478 -0
  24. package/src/designer/preview.js +95 -0
  25. package/src/designer/rulers.js +231 -0
  26. package/src/designer/sample-data.js +240 -0
  27. package/src/designer/select.js +699 -0
  28. package/src/designer/structure.js +604 -0
  29. package/src/designer/styles.css +1616 -0
  30. package/src/designer/toast.js +62 -0
  31. package/src/designer/tokens.js +284 -0
  32. package/src/engine/csv.js +315 -0
  33. package/src/engine/group.js +304 -0
  34. package/src/engine/index.js +34 -0
  35. package/src/engine/measure.js +390 -0
  36. package/src/engine/paginate.js +861 -0
  37. package/src/engine/regions.js +175 -0
  38. package/src/engine/resolve.js +171 -0
  39. package/src/engine/search.js +129 -0
  40. package/src/engine/text-metrics.js +206 -0
  41. package/src/engine/validate.js +328 -0
  42. package/src/index.html +79 -0
  43. package/src/index.js +50 -0
  44. package/src/preview/chrome.css +505 -0
  45. package/src/preview/chrome.js +147 -0
  46. package/src/preview/index.html +28 -0
  47. package/src/preview/main.js +66 -0
  48. package/src/preview/styles.css +16 -0
  49. package/src/preview/viewer.js +745 -0
  50. package/src/render/items.js +425 -0
  51. package/src/render/render.js +98 -0
  52. package/src/render/report.css +202 -0
  53. package/src/server/routes.js +331 -0
  54. package/src/shared/brand.css +29 -0
  55. package/src/shared/dropdown.css +136 -0
  56. package/src/shared/dropdown.js +166 -0
  57. package/src/shared/modal.css +125 -0
  58. package/src/shared/prefix.js +13 -0
  59. package/src/shared/store.js +145 -0
  60. package/src/shared/theme.css +72 -0
  61. package/src/shared/window.js +138 -0
  62. package/src/vite/index.js +53 -0
  63. package/dist/react.js +0 -4
@@ -0,0 +1,604 @@
1
+ /**
2
+ * structure.js changes the shape of a report: which bands exist, what items are
3
+ * on them, and what columns a table has.
4
+ *
5
+ * Pure functions over the layout object, so every rule that matters - a table
6
+ * keeps at least one column, a new id does not collide, a band lands in page
7
+ * order - is specified without a browser.
8
+ *
9
+ * One thing from validate.js shapes all of it: a band type may appear only
10
+ * once. Bands are therefore a *set* of at most seven, not an ordered list, and
11
+ * their order on the page is regions.js's decision rather than the author's.
12
+ * That removes reordering from the designer entirely.
13
+ */
14
+
15
+ import { GRID, snap, designHeight } from './geometry.js';
16
+ import { FONT_STACKS } from './fields.js';
17
+ import { absoluteTop, designZones } from './canvas.js';
18
+
19
+
20
+ /** every band type, in the order they appear down the page */
21
+ export const BAND_TYPES = [
22
+ 'pageHeader',
23
+ 'reportHeader',
24
+ 'groupHeader',
25
+ 'detail',
26
+ 'groupFooter',
27
+ 'reportFooter',
28
+ 'pageFooter'
29
+ ];
30
+
31
+
32
+ /**
33
+ * What a band is worth when it is first switched on.
34
+ *
35
+ * regions.js defaults an undeclared band to 10% of the printable height, which
36
+ * is a tenth of the page given away without being asked for. These are the
37
+ * pixel figures a report actually tends to want. `detail` is absent on purpose:
38
+ * it takes whatever the other zones leave.
39
+ */
40
+ const NEW_BAND_HEIGHTS = {
41
+ pageHeader: 40,
42
+ reportHeader: 80,
43
+ groupHeader: 36,
44
+ groupFooter: 36,
45
+ reportFooter: 60,
46
+ pageFooter: 40
47
+ };
48
+
49
+ /**
50
+ * What a column is worth before anyone sets it. Narrow on purpose: a new table
51
+ * is usually several columns, and starting each one narrow means the author
52
+ * widens the two that matter rather than shrinking all six.
53
+ */
54
+ export const DEFAULT_COLUMN_WIDTH = 50;
55
+
56
+ /** how many columns the table tool offers to start with */
57
+ export const DEFAULT_COLUMNS = 3;
58
+
59
+
60
+ /** a band that says what it is, for the ones whose purpose is not obvious */
61
+ export const BAND_NOTES = {
62
+ reportHeader: 'First page only',
63
+ pageHeader: 'Every page',
64
+ groupHeader: 'Before each group',
65
+ detail: 'The rows',
66
+ groupFooter: 'After each group',
67
+ reportFooter: 'Last page only',
68
+ pageFooter: 'Every page'
69
+ };
70
+
71
+
72
+ /**
73
+ * The band list, always as an array.
74
+ *
75
+ * The report rail is drawn for whatever layout is loaded, including one that is
76
+ * currently invalid - so `bands` may legitimately be a string someone typed, or
77
+ * missing entirely, and every reader here has to survive that. A broken layout
78
+ * is reported by the validator, not by a TypeError three calls down.
79
+ */
80
+ function bandList(layout) {
81
+ return Array.isArray(layout?.bands) ? layout.bands : [];
82
+ }
83
+
84
+
85
+ /**
86
+ * How many tables the report has. The engine binds one (see validateOneTable in
87
+ * validate.js), so this is what says whether another may be added.
88
+ *
89
+ * @param {object} layout
90
+ * @returns {number}
91
+ */
92
+ export function tableCount(layout) {
93
+ return bandList(layout)
94
+ .flatMap(b => b.items || [])
95
+ .filter(i => i?.type === 'table')
96
+ .length;
97
+ }
98
+
99
+
100
+ /** whether this report can take a table - one, for now */
101
+ export function canAddTable(layout) {
102
+ return tableCount(layout) < 1;
103
+ }
104
+
105
+
106
+ export function findBand(layout, type) {
107
+ return bandList(layout).find(b => b.type === type) ?? null;
108
+ }
109
+
110
+
111
+ export function hasBand(layout, type) {
112
+ return findBand(layout, type) != null;
113
+ }
114
+
115
+
116
+ /**
117
+ * Switches a band on. Inserted in page order rather than appended - nothing in
118
+ * the engine reads the array's order, but a hand-edited layout file is read by
119
+ * people, and a file whose bands run top to bottom is the one they can follow.
120
+ *
121
+ * @returns {object|null} the band, or null if it was already there
122
+ */
123
+ export function addBand(layout, type) {
124
+ if (!BAND_TYPES.includes(type)) return null;
125
+ if (hasBand(layout, type)) return null;
126
+
127
+ const band = { type, items: [] };
128
+ if (NEW_BAND_HEIGHTS[type] != null) band.height = NEW_BAND_HEIGHTS[type];
129
+
130
+ /** replaces a `bands` that is not a list, rather than throwing on it */
131
+ if (!Array.isArray(layout.bands)) layout.bands = [];
132
+
133
+ const rank = (t) => BAND_TYPES.indexOf(t);
134
+ const at = layout.bands.findIndex(b => rank(b.type) > rank(type));
135
+
136
+ if (at === -1) layout.bands.push(band);
137
+ else layout.bands.splice(at, 0, band);
138
+
139
+ return band;
140
+ }
141
+
142
+
143
+ /**
144
+ * Switches a band off, and everything on it with it.
145
+ * @returns {boolean} whether there was one to remove
146
+ */
147
+ export function removeBand(layout, type) {
148
+ const at = bandList(layout).findIndex(b => b.type === type);
149
+ if (at === -1) return false;
150
+
151
+ layout.bands.splice(at, 1);
152
+ return true;
153
+ }
154
+
155
+
156
+ /** every item id in the report, across every band */
157
+ function usedIds(layout) {
158
+ return new Set(bandList(layout)
159
+ .flatMap(b => (b.items || []).map(i => i.id)));
160
+ }
161
+
162
+
163
+ /**
164
+ * A free id of the form "text-1".
165
+ *
166
+ * Counted rather than randomised: the layout file is saved to disk and read in
167
+ * diffs, and an id that changes shape every time makes every save look like a
168
+ * rewrite.
169
+ */
170
+ export function nextItemId(layout, prefix) {
171
+ const taken = usedIds(layout);
172
+
173
+ for (let n = 1; ; n++) {
174
+ const id = `${prefix}-${n}`;
175
+ if (!taken.has(id)) return id;
176
+ }
177
+ }
178
+
179
+
180
+ /** the first free grid line below everything already on the band */
181
+ function nextY(band) {
182
+ const items = band.items || [];
183
+ if (!items.length) return 0;
184
+
185
+ const bottom = Math.max(...items.map(i => (i.y ?? 0) + designHeight(i)));
186
+ return Math.ceil(bottom / GRID) * GRID;
187
+ }
188
+
189
+
190
+ /** the printable width, which is as wide as an item can usefully be */
191
+ function contentWidth(layout) {
192
+ const { page } = layout;
193
+ return page.width - page.margin.left - page.margin.right;
194
+ }
195
+
196
+
197
+ /**
198
+ * A new text box, placed below whatever is already on the band.
199
+ * @returns {object} the item; it has not been added to anything yet
200
+ */
201
+ export function createText(layout, band) {
202
+ return {
203
+ id: nextItemId(layout, 'text'),
204
+ type: 'text',
205
+ x: 0,
206
+ y: nextY(band),
207
+ w: 200,
208
+ h: 20,
209
+ value: 'Text',
210
+ style: {
211
+ fontFamily: FONT_STACKS[0].value,
212
+ fontSize: 12,
213
+ fontWeight: 'normal',
214
+ fontStyle: 'normal',
215
+ color: '#000000',
216
+ align: 'left',
217
+ background: null,
218
+ border: null,
219
+ padding: 0
220
+ }
221
+ };
222
+ }
223
+
224
+
225
+ /**
226
+ * How tall a horizontal line's box is, and how wide a vertical one's.
227
+ *
228
+ * Not the thickness: a hairline that was its own box would be a 1px target on
229
+ * the canvas. This is a box that can be grabbed, with the rule drawn down the
230
+ * middle of it - and it matches MIN_H, so the first thing a resize does is not
231
+ * to jump.
232
+ */
233
+ export const LINE_BOX = 12;
234
+
235
+
236
+ /**
237
+ * A new line, full printable width, below whatever is already on the band.
238
+ *
239
+ * A hairline rule, because that is what a line under a heading almost always
240
+ * is; thickness and dashes are one field away in the rail.
241
+ *
242
+ * @param {object} layout
243
+ * @param {object} band the band it is going onto, for its vertical place
244
+ * @param {string} [orientation] 'horizontal' or 'vertical'
245
+ * @returns {object} the item; it has not been added to anything yet
246
+ */
247
+ export function createLine(layout, band, orientation = 'horizontal') {
248
+ const vertical = orientation === 'vertical';
249
+
250
+ return {
251
+ id: nextItemId(layout, 'line'),
252
+ type: 'line',
253
+ x: 0,
254
+ y: nextY(band),
255
+ w: vertical ? LINE_BOX : contentWidth(layout),
256
+ h: vertical ? 80 : LINE_BOX,
257
+ orientation: vertical ? 'vertical' : 'horizontal',
258
+ style: {
259
+ thickness: 1,
260
+ lineStyle: 'solid',
261
+ color: '#000000'
262
+ }
263
+ };
264
+ }
265
+
266
+
267
+ /**
268
+ * A new box, full printable width, below whatever is already on the band.
269
+ *
270
+ * A plain hairline rectangle with nothing inside it: a box is most often drawn
271
+ * round something else, and a fill it did not ask for would hide whatever it
272
+ * was put there to frame.
273
+ *
274
+ * @param {object} layout
275
+ * @param {object} band the band it is going onto, for its vertical place
276
+ * @returns {object} the item; it has not been added to anything yet
277
+ */
278
+ export function createBox(layout, band) {
279
+ return {
280
+ id: nextItemId(layout, 'box'),
281
+ type: 'box',
282
+ x: 0,
283
+ y: nextY(band),
284
+ w: contentWidth(layout),
285
+ h: 80,
286
+ style: {
287
+ borderStyle: 'solid',
288
+ borderWidth: 1,
289
+ borderColor: '#000000',
290
+ background: null,
291
+ radius: 0
292
+ }
293
+ };
294
+ }
295
+
296
+
297
+ /** a column at its default width, numbered by where it sits */
298
+ export function makeColumn(n) {
299
+ return {
300
+ field: `field${n}`,
301
+ label: `Column ${n}`,
302
+ width: DEFAULT_COLUMN_WIDTH,
303
+ align: 'left'
304
+ };
305
+ }
306
+
307
+
308
+ /**
309
+ * A new table, full printable width, with the columns asked for.
310
+ *
311
+ * Never fewer than one: validate.js will not accept an empty `columns`, and a
312
+ * table with none is not a table but an error waiting for whoever opens the
313
+ * file next. The row count is absent on purpose - rows come from the data at
314
+ * print time (spec 3.3), so there is nothing here to ask for or to store.
315
+ *
316
+ * @param {object} layout
317
+ * @param {object} band the band it is going onto, for its vertical place
318
+ * @param {number} [columns] how many columns to start with
319
+ */
320
+ export function createTable(layout, band, columns = DEFAULT_COLUMNS) {
321
+ const count = Math.max(1, Math.floor(Number(columns) || DEFAULT_COLUMNS));
322
+
323
+ return {
324
+ id: nextItemId(layout, 'table'),
325
+ type: 'table',
326
+ x: 0,
327
+ y: nextY(band),
328
+ w: contentWidth(layout),
329
+ dataset: layout.dataset ?? null,
330
+ rowHeight: 24,
331
+ headerHeight: 28,
332
+ showHeader: true,
333
+
334
+ /**
335
+ * A cell wider than its column runs onto another line and the row grows
336
+ * to hold it. Written down rather than left to the default, because it
337
+ * decides how many rows fit on a page - and a report file should say
338
+ * what it does rather than leave the next reader to find out.
339
+ */
340
+ wrap: true,
341
+
342
+ columns: Array.from({ length: count }, (_, i) => makeColumn(i + 1)),
343
+ style: {
344
+ /** the font the engine wraps against; report.css draws this one */
345
+ fontFamily: 'Helvetica, Arial, sans-serif',
346
+ fontSize: 12,
347
+ color: '#000000',
348
+ borderStyle: 'solid',
349
+ borderWidth: 1,
350
+ borderColor: '#cccccc'
351
+ }
352
+ };
353
+ }
354
+
355
+
356
+ export function addItem(layout, bandType, item) {
357
+ const band = findBand(layout, bandType);
358
+ if (!band) return null;
359
+
360
+ band.items ??= [];
361
+ band.items.push(item);
362
+
363
+ return item;
364
+ }
365
+
366
+
367
+ /**
368
+ * How far a copy sits from its original: one grid step down and across, so the
369
+ * copy is visibly a second item rather than hiding the first, and still lands
370
+ * on the grid everything else snaps to.
371
+ */
372
+ const DUPLICATE_OFFSET = GRID;
373
+
374
+
375
+ /**
376
+ * The id a copy should count from.
377
+ *
378
+ * "text-2" copies as "text-3", and a hand-named "rh_title" as "rh_title-1".
379
+ * Keeping the author's naming matters more than uniformity here: a layout file
380
+ * is read in diffs, and a copy of "rh_title" called "text-7" is a rename as
381
+ * much as a copy.
382
+ *
383
+ * @param {object} item
384
+ * @returns {string}
385
+ */
386
+ function idPrefix(item) {
387
+ const base = String(item.id ?? '').replace(/-\d+$/, '');
388
+ return base || item.type || 'item';
389
+ }
390
+
391
+
392
+ /** keeps a copy on the page when its original already sits at the right edge */
393
+ function clampX(layout, x, w) {
394
+ if (!Number.isFinite(layout?.page?.width)) return Math.max(0, x);
395
+
396
+ const limit = Math.max(0, contentWidth(layout) - (w ?? 0));
397
+ return Math.min(Math.max(0, x), limit);
398
+ }
399
+
400
+
401
+ /**
402
+ * Copies an item onto the band it is already on, offset so both can be seen.
403
+ *
404
+ * Deep-cloned rather than spread: a text item's `style` and a table's `columns`
405
+ * are objects, and a shallow copy would share them - so editing the copy's font
406
+ * would quietly change the original's too, which is the sort of thing that is
407
+ * only noticed once the report prints.
408
+ *
409
+ * @param {object} layout
410
+ * @param {string} bandType the band the original is on
411
+ * @param {string} id
412
+ * @returns {object|null} the copy, already added to the band, or null when
413
+ * there is nothing by that id there
414
+ */
415
+ export function duplicateItem(layout, bandType, id) {
416
+ const band = findBand(layout, bandType);
417
+ if (!band) return null;
418
+
419
+ const original = (band.items || []).find(i => i.id === id);
420
+ if (!original) return null;
421
+
422
+ /** a copy of the table would be the second one, which the engine cannot bind */
423
+ if (original.type === 'table' && !canAddTable(layout)) return null;
424
+
425
+ const copy = structuredClone(original);
426
+
427
+ copy.id = nextItemId(layout, idPrefix(original));
428
+ copy.x = clampX(layout, (original.x ?? 0) + DUPLICATE_OFFSET, copy.w);
429
+ copy.y = Math.max(0, (original.y ?? 0) + DUPLICATE_OFFSET);
430
+
431
+ band.items ??= [];
432
+ band.items.push(copy);
433
+
434
+ return copy;
435
+ }
436
+
437
+
438
+ /** the design-time height of a band's zone, or null when there is no page to measure against */
439
+ function zoneHeight(layout, bandType) {
440
+ if (!Number.isFinite(layout?.page?.height)) return null;
441
+
442
+ return designZones(layout).find(z => z.type === bandType)?.height ?? null;
443
+ }
444
+
445
+
446
+ /**
447
+ * Brings a y into a band's zone.
448
+ *
449
+ * Only used when something arrives from a *different* band: a y of 400 means a
450
+ * position in a 900px detail zone and means nothing at all in a 40px page
451
+ * footer, and an item pasted below its band is an item the author cannot see to
452
+ * drag back.
453
+ */
454
+ function clampY(layout, bandType, y, item) {
455
+ const height = zoneHeight(layout, bandType);
456
+ if (height == null) return Math.max(0, y);
457
+
458
+ const limit = Math.max(0, height - designHeight(item));
459
+ return Math.min(Math.max(0, y), limit);
460
+ }
461
+
462
+
463
+ /**
464
+ * Puts copies of items onto a band - what a paste does.
465
+ *
466
+ * Offset by the same step a duplicate uses, so a second paste of the same
467
+ * clipboard cascades rather than stacking one copy exactly on another.
468
+ *
469
+ * @param {object} layout
470
+ * @param {string} bandType the band to paste onto
471
+ * @param {{band: string, item: object}[]} entries what was copied, each with the
472
+ * band it came from - a paste into a different band has to reposition, since
473
+ * the y no longer means what it meant where it was cut
474
+ * @returns {object[]} the pasted items, already added to the band
475
+ */
476
+ export function pasteItems(layout, bandType, entries) {
477
+ const band = findBand(layout, bandType);
478
+ if (!band) return [];
479
+
480
+ band.items ??= [];
481
+
482
+ const made = [];
483
+
484
+ for (const { band: from, item } of (entries || [])) {
485
+ if (!item) continue;
486
+
487
+ /**
488
+ * A pasted table is skipped rather than refusing the whole paste: a
489
+ * clipboard of five items should place the four it can.
490
+ */
491
+ if (item.type === 'table' && !canAddTable(layout)) continue;
492
+
493
+ const copy = structuredClone(item);
494
+ const y = Math.max(0, (item.y ?? 0) + DUPLICATE_OFFSET);
495
+
496
+ copy.id = nextItemId(layout, idPrefix(item));
497
+ copy.x = clampX(layout, (item.x ?? 0) + DUPLICATE_OFFSET, copy.w);
498
+ copy.y = from === bandType ? y : clampY(layout, bandType, y, copy);
499
+
500
+ band.items.push(copy);
501
+ made.push(copy);
502
+ }
503
+
504
+ return made;
505
+ }
506
+
507
+
508
+ export function removeItem(layout, bandType, id) {
509
+ const band = findBand(layout, bandType);
510
+ if (!band) return false;
511
+
512
+ const at = (band.items || []).findIndex(i => i.id === id);
513
+ if (at === -1) return false;
514
+
515
+ band.items.splice(at, 1);
516
+ return true;
517
+ }
518
+
519
+
520
+ /**
521
+ * Moves an item from one band to another, keeping it where it looks.
522
+ *
523
+ * An item's y is relative to its band (spec 3.3), so carrying the same number
524
+ * across would jump it - 10px from the top of the detail band is a long way
525
+ * from 10px from the top of the page footer. The position is lifted into page
526
+ * coordinates, the item is moved, and the offset is worked out again against
527
+ * where it has arrived.
528
+ *
529
+ * @param {object} layout
530
+ * @param {string} from
531
+ * @param {string} to
532
+ * @param {string} id
533
+ * @returns {boolean} whether it moved
534
+ */
535
+ export function moveItemToBand(layout, from, to, id) {
536
+ if (from === to) return false;
537
+
538
+ const source = findBand(layout, from);
539
+ const target = findBand(layout, to);
540
+ if (!source || !target) return false;
541
+
542
+ const item = (source.items || []).find(i => i.id === id);
543
+ if (!item) return false;
544
+
545
+ const page = absoluteTop(layout, from, item.y ?? 0);
546
+
547
+ removeItem(layout, from, id);
548
+ addItem(layout, to, item);
549
+
550
+ const landed = absoluteTop(layout, to, 0);
551
+ if (page !== null && landed !== null) item.y = Math.round(page - landed);
552
+
553
+ return true;
554
+ }
555
+
556
+
557
+ /**
558
+ * Adds a column, at the default width rather than by redistributing the others.
559
+ *
560
+ * Resizing every column because a new one arrived would silently undo widths
561
+ * that were set on purpose. A table wider than its item is the author's to fix,
562
+ * and `table-layout: fixed` draws it predictably meanwhile.
563
+ */
564
+ export function addColumn(table) {
565
+ table.columns ??= [];
566
+
567
+ const column = makeColumn(table.columns.length + 1);
568
+ table.columns.push(column);
569
+
570
+ return column;
571
+ }
572
+
573
+
574
+ /**
575
+ * @returns {boolean} false when the column is the last one, which must stay -
576
+ * validate.js requires a non-empty `columns`, and a table with none is not a
577
+ * table but a validation error waiting for whoever opens the file next
578
+ */
579
+ export function removeColumn(table, index) {
580
+ if (!Array.isArray(table.columns) || table.columns.length <= 1) return false;
581
+ if (index < 0 || index >= table.columns.length) return false;
582
+
583
+ table.columns.splice(index, 1);
584
+ return true;
585
+ }
586
+
587
+
588
+ /**
589
+ * Where a newly added item should go: the band the selection is on, or the
590
+ * detail band, or whatever band exists at all.
591
+ *
592
+ * @param {object} layout
593
+ * @param {{band: string}|null} selection
594
+ * @returns {string|null}
595
+ */
596
+ export function targetBand(layout, selection) {
597
+ if (selection && hasBand(layout, selection.band)) return selection.band;
598
+ if (hasBand(layout, 'detail')) return 'detail';
599
+
600
+ return bandList(layout)[0]?.type ?? null;
601
+ }
602
+
603
+
604
+ export { snap };