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,685 @@
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.
87
+ *
88
+ * @param {object} layout
89
+ * @returns {number}
90
+ */
91
+ export function tableCount(layout) {
92
+ return bandList(layout)
93
+ .flatMap(b => b.items || [])
94
+ .filter(i => i?.type === 'table')
95
+ .length;
96
+ }
97
+
98
+
99
+ /**
100
+ * Whether this report can take another table. Always, now that each table
101
+ * binds a dataset of its own; kept as the one place to say otherwise, should a
102
+ * limit ever come back, rather than a check at every call site.
103
+ *
104
+ * @param {object} layout
105
+ * @returns {boolean}
106
+ */
107
+ export function canAddTable(layout) {
108
+ return Array.isArray(layout?.bands);
109
+ }
110
+
111
+
112
+ /**
113
+ * The dataset a new table reads.
114
+ *
115
+ * The first table reads the report's, as it always did. Every one after it
116
+ * gets a name of its own - `items2`, `items3` - because a second table on
117
+ * the same rows is rarely what anyone draws a second table for, and a name
118
+ * that is already distinct is one the sample data can fill with its own rows.
119
+ *
120
+ * @param {object} layout
121
+ * @returns {string|null}
122
+ */
123
+ function datasetForNewTable(layout) {
124
+ const count = tableCount(layout);
125
+ if (count === 0) return layout.dataset ?? null;
126
+
127
+ const base = layout.dataset || 'rows';
128
+ const taken = new Set(bandList(layout)
129
+ .flatMap(b => b.items || [])
130
+ .filter(i => i?.type === 'table')
131
+ .map(i => i.dataset ?? layout.dataset));
132
+
133
+ for (let n = count + 1; ; n++) {
134
+ if (!taken.has(`${base}${n}`)) return `${base}${n}`;
135
+ }
136
+ }
137
+
138
+
139
+ /**
140
+ * A copied table, made fit to sit beside its original.
141
+ *
142
+ * Tables are stacked rather than overlapped - validate.js refuses two that
143
+ * 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.
146
+ *
147
+ * @param {object} copy mutated in place
148
+ * @param {object} band the band it is going onto, before the copy is added
149
+ */
150
+ function settleTable(copy, band) {
151
+ copy.y = nextY(band);
152
+ delete copy.groupBy;
153
+ }
154
+
155
+
156
+ export function findBand(layout, type) {
157
+ return bandList(layout).find(b => b.type === type) ?? null;
158
+ }
159
+
160
+
161
+ export function hasBand(layout, type) {
162
+ return findBand(layout, type) != null;
163
+ }
164
+
165
+
166
+ /**
167
+ * Switches a band on. Inserted in page order rather than appended - nothing in
168
+ * the engine reads the array's order, but a hand-edited layout file is read by
169
+ * people, and a file whose bands run top to bottom is the one they can follow.
170
+ *
171
+ * @returns {object|null} the band, or null if it was already there
172
+ */
173
+ export function addBand(layout, type) {
174
+ if (!BAND_TYPES.includes(type)) return null;
175
+ if (hasBand(layout, type)) return null;
176
+
177
+ const band = { type, items: [] };
178
+ if (NEW_BAND_HEIGHTS[type] != null) band.height = NEW_BAND_HEIGHTS[type];
179
+
180
+ /** replaces a `bands` that is not a list, rather than throwing on it */
181
+ if (!Array.isArray(layout.bands)) layout.bands = [];
182
+
183
+ const rank = (t) => BAND_TYPES.indexOf(t);
184
+ const at = layout.bands.findIndex(b => rank(b.type) > rank(type));
185
+
186
+ if (at === -1) layout.bands.push(band);
187
+ else layout.bands.splice(at, 0, band);
188
+
189
+ return band;
190
+ }
191
+
192
+
193
+ /**
194
+ * Switches a band off, and everything on it with it.
195
+ * @returns {boolean} whether there was one to remove
196
+ */
197
+ export function removeBand(layout, type) {
198
+ const at = bandList(layout).findIndex(b => b.type === type);
199
+ if (at === -1) return false;
200
+
201
+ layout.bands.splice(at, 1);
202
+ return true;
203
+ }
204
+
205
+
206
+ /** every item id in the report, across every band */
207
+ function usedIds(layout) {
208
+ return new Set(bandList(layout)
209
+ .flatMap(b => (b.items || []).map(i => i.id)));
210
+ }
211
+
212
+
213
+ /**
214
+ * A free id of the form "text-1".
215
+ *
216
+ * Counted rather than randomised: the layout file is saved to disk and read in
217
+ * diffs, and an id that changes shape every time makes every save look like a
218
+ * rewrite.
219
+ */
220
+ export function nextItemId(layout, prefix) {
221
+ const taken = usedIds(layout);
222
+
223
+ for (let n = 1; ; n++) {
224
+ const id = `${prefix}-${n}`;
225
+ if (!taken.has(id)) return id;
226
+ }
227
+ }
228
+
229
+
230
+ /** the first free grid line below everything already on the band */
231
+ function nextY(band) {
232
+ const items = band.items || [];
233
+ if (!items.length) return 0;
234
+
235
+ const bottom = Math.max(...items.map(i => (i.y ?? 0) + designHeight(i)));
236
+ return Math.ceil(bottom / GRID) * GRID;
237
+ }
238
+
239
+
240
+ /** the printable width, which is as wide as an item can usefully be */
241
+ function contentWidth(layout) {
242
+ const { page } = layout;
243
+ return page.width - page.margin.left - page.margin.right;
244
+ }
245
+
246
+
247
+ /**
248
+ * A new text box, placed below whatever is already on the band.
249
+ * @returns {object} the item; it has not been added to anything yet
250
+ */
251
+ export function createText(layout, band) {
252
+ return {
253
+ id: nextItemId(layout, 'text'),
254
+ type: 'text',
255
+ x: 0,
256
+ y: nextY(band),
257
+ w: 200,
258
+ h: 20,
259
+ value: 'Text',
260
+ style: {
261
+ fontFamily: FONT_STACKS[0].value,
262
+ fontSize: 12,
263
+ fontWeight: 'normal',
264
+ fontStyle: 'normal',
265
+ color: '#000000',
266
+ align: 'left',
267
+ background: null,
268
+ border: null,
269
+ padding: 0
270
+ }
271
+ };
272
+ }
273
+
274
+
275
+ /**
276
+ * How tall a horizontal line's box is, and how wide a vertical one's.
277
+ *
278
+ * Not the thickness: a hairline that was its own box would be a 1px target on
279
+ * the canvas. This is a box that can be grabbed, with the rule drawn down the
280
+ * middle of it - and it matches MIN_H, so the first thing a resize does is not
281
+ * to jump.
282
+ */
283
+ export const LINE_BOX = 12;
284
+
285
+
286
+ /**
287
+ * A new line, full printable width, below whatever is already on the band.
288
+ *
289
+ * A hairline rule, because that is what a line under a heading almost always
290
+ * is; thickness and dashes are one field away in the rail.
291
+ *
292
+ * @param {object} layout
293
+ * @param {object} band the band it is going onto, for its vertical place
294
+ * @param {string} [orientation] 'horizontal' or 'vertical'
295
+ * @returns {object} the item; it has not been added to anything yet
296
+ */
297
+ export function createLine(layout, band, orientation = 'horizontal') {
298
+ const vertical = orientation === 'vertical';
299
+
300
+ return {
301
+ id: nextItemId(layout, 'line'),
302
+ type: 'line',
303
+ x: 0,
304
+ y: nextY(band),
305
+ w: vertical ? LINE_BOX : contentWidth(layout),
306
+ h: vertical ? 80 : LINE_BOX,
307
+ orientation: vertical ? 'vertical' : 'horizontal',
308
+ style: {
309
+ thickness: 1,
310
+ lineStyle: 'solid',
311
+ color: '#000000'
312
+ }
313
+ };
314
+ }
315
+
316
+
317
+ /**
318
+ * A new box, full printable width, below whatever is already on the band.
319
+ *
320
+ * A plain hairline rectangle with nothing inside it: a box is most often drawn
321
+ * round something else, and a fill it did not ask for would hide whatever it
322
+ * was put there to frame.
323
+ *
324
+ * @param {object} layout
325
+ * @param {object} band the band it is going onto, for its vertical place
326
+ * @returns {object} the item; it has not been added to anything yet
327
+ */
328
+ export function createBox(layout, band) {
329
+ return {
330
+ id: nextItemId(layout, 'box'),
331
+ type: 'box',
332
+ x: 0,
333
+ y: nextY(band),
334
+ w: contentWidth(layout),
335
+ h: 80,
336
+ style: {
337
+ borderStyle: 'solid',
338
+ borderWidth: 1,
339
+ borderColor: '#000000',
340
+ background: null,
341
+ radius: 0
342
+ }
343
+ };
344
+ }
345
+
346
+
347
+ /**
348
+ * A new image, below whatever is already on the band.
349
+ *
350
+ * Empty: no picture and no field. The canvas draws it as a dashed frame to be
351
+ * filled from the rail - either a picture uploaded into the layout, or a data
352
+ * field the host supplies a URL in. Logo-sized, because a logo is what goes in
353
+ * a report more often than anything else.
354
+ *
355
+ * @param {object} layout
356
+ * @param {object} band the band it is going onto, for its vertical place
357
+ * @returns {object} the item; it has not been added to anything yet
358
+ */
359
+ export function createImage(layout, band) {
360
+ return {
361
+ id: nextItemId(layout, 'image'),
362
+ type: 'image',
363
+ x: 0,
364
+ y: nextY(band),
365
+ w: 160,
366
+ h: 80,
367
+ src: null,
368
+ field: null,
369
+ fit: 'contain',
370
+ alt: ''
371
+ };
372
+ }
373
+
374
+
375
+ /** a column at its default width, numbered by where it sits */
376
+ export function makeColumn(n) {
377
+ return {
378
+ field: `field${n}`,
379
+ label: `Column ${n}`,
380
+ width: DEFAULT_COLUMN_WIDTH,
381
+ align: 'left'
382
+ };
383
+ }
384
+
385
+
386
+ /**
387
+ * A new table, full printable width, with the columns asked for.
388
+ *
389
+ * Never fewer than one: validate.js will not accept an empty `columns`, and a
390
+ * table with none is not a table but an error waiting for whoever opens the
391
+ * file next. The row count is absent on purpose - rows come from the data at
392
+ * print time (spec 3.3), so there is nothing here to ask for or to store.
393
+ *
394
+ * @param {object} layout
395
+ * @param {object} band the band it is going onto, for its vertical place
396
+ * @param {number} [columns] how many columns to start with
397
+ */
398
+ export function createTable(layout, band, columns = DEFAULT_COLUMNS) {
399
+ const count = Math.max(1, Math.floor(Number(columns) || DEFAULT_COLUMNS));
400
+
401
+ return {
402
+ id: nextItemId(layout, 'table'),
403
+ type: 'table',
404
+ x: 0,
405
+ y: nextY(band),
406
+ w: contentWidth(layout),
407
+ dataset: datasetForNewTable(layout),
408
+ rowHeight: 24,
409
+ headerHeight: 28,
410
+ showHeader: true,
411
+
412
+ /**
413
+ * A cell wider than its column runs onto another line and the row grows
414
+ * to hold it. Written down rather than left to the default, because it
415
+ * decides how many rows fit on a page - and a report file should say
416
+ * what it does rather than leave the next reader to find out.
417
+ */
418
+ wrap: true,
419
+
420
+ columns: Array.from({ length: count }, (_, i) => makeColumn(i + 1)),
421
+ style: {
422
+ /** the font the engine wraps against; report.css draws this one */
423
+ fontFamily: 'Helvetica, Arial, sans-serif',
424
+ fontSize: 12,
425
+ color: '#000000',
426
+ borderStyle: 'solid',
427
+ borderWidth: 1,
428
+ borderColor: '#cccccc'
429
+ }
430
+ };
431
+ }
432
+
433
+
434
+ export function addItem(layout, bandType, item) {
435
+ const band = findBand(layout, bandType);
436
+ if (!band) return null;
437
+
438
+ band.items ??= [];
439
+ band.items.push(item);
440
+
441
+ return item;
442
+ }
443
+
444
+
445
+ /**
446
+ * How far a copy sits from its original: one grid step down and across, so the
447
+ * copy is visibly a second item rather than hiding the first, and still lands
448
+ * on the grid everything else snaps to.
449
+ */
450
+ const DUPLICATE_OFFSET = GRID;
451
+
452
+
453
+ /**
454
+ * The id a copy should count from.
455
+ *
456
+ * "text-2" copies as "text-3", and a hand-named "rh_title" as "rh_title-1".
457
+ * Keeping the author's naming matters more than uniformity here: a layout file
458
+ * is read in diffs, and a copy of "rh_title" called "text-7" is a rename as
459
+ * much as a copy.
460
+ *
461
+ * @param {object} item
462
+ * @returns {string}
463
+ */
464
+ function idPrefix(item) {
465
+ const base = String(item.id ?? '').replace(/-\d+$/, '');
466
+ return base || item.type || 'item';
467
+ }
468
+
469
+
470
+ /** keeps a copy on the page when its original already sits at the right edge */
471
+ function clampX(layout, x, w) {
472
+ if (!Number.isFinite(layout?.page?.width)) return Math.max(0, x);
473
+
474
+ const limit = Math.max(0, contentWidth(layout) - (w ?? 0));
475
+ return Math.min(Math.max(0, x), limit);
476
+ }
477
+
478
+
479
+ /**
480
+ * Copies an item onto the band it is already on, offset so both can be seen.
481
+ *
482
+ * Deep-cloned rather than spread: a text item's `style` and a table's `columns`
483
+ * are objects, and a shallow copy would share them - so editing the copy's font
484
+ * would quietly change the original's too, which is the sort of thing that is
485
+ * only noticed once the report prints.
486
+ *
487
+ * @param {object} layout
488
+ * @param {string} bandType the band the original is on
489
+ * @param {string} id
490
+ * @returns {object|null} the copy, already added to the band, or null when
491
+ * there is nothing by that id there
492
+ */
493
+ export function duplicateItem(layout, bandType, id) {
494
+ const band = findBand(layout, bandType);
495
+ if (!band) return null;
496
+
497
+ const original = (band.items || []).find(i => i.id === id);
498
+ if (!original) return null;
499
+
500
+ if (original.type === 'table' && !canAddTable(layout)) return null;
501
+
502
+ const copy = structuredClone(original);
503
+
504
+ copy.id = nextItemId(layout, idPrefix(original));
505
+ copy.x = clampX(layout, (original.x ?? 0) + DUPLICATE_OFFSET, copy.w);
506
+ copy.y = Math.max(0, (original.y ?? 0) + DUPLICATE_OFFSET);
507
+
508
+ if (copy.type === 'table') settleTable(copy, band);
509
+
510
+ band.items ??= [];
511
+ band.items.push(copy);
512
+
513
+ return copy;
514
+ }
515
+
516
+
517
+ /** the design-time height of a band's zone, or null when there is no page to measure against */
518
+ function zoneHeight(layout, bandType) {
519
+ if (!Number.isFinite(layout?.page?.height)) return null;
520
+
521
+ return designZones(layout).find(z => z.type === bandType)?.height ?? null;
522
+ }
523
+
524
+
525
+ /**
526
+ * Brings a y into a band's zone.
527
+ *
528
+ * Only used when something arrives from a *different* band: a y of 400 means a
529
+ * position in a 900px detail zone and means nothing at all in a 40px page
530
+ * footer, and an item pasted below its band is an item the author cannot see to
531
+ * drag back.
532
+ */
533
+ function clampY(layout, bandType, y, item) {
534
+ const height = zoneHeight(layout, bandType);
535
+ if (height == null) return Math.max(0, y);
536
+
537
+ const limit = Math.max(0, height - designHeight(item));
538
+ return Math.min(Math.max(0, y), limit);
539
+ }
540
+
541
+
542
+ /**
543
+ * Puts copies of items onto a band - what a paste does.
544
+ *
545
+ * Offset by the same step a duplicate uses, so a second paste of the same
546
+ * clipboard cascades rather than stacking one copy exactly on another.
547
+ *
548
+ * @param {object} layout
549
+ * @param {string} bandType the band to paste onto
550
+ * @param {{band: string, item: object}[]} entries what was copied, each with the
551
+ * band it came from - a paste into a different band has to reposition, since
552
+ * the y no longer means what it meant where it was cut
553
+ * @returns {object[]} the pasted items, already added to the band
554
+ */
555
+ export function pasteItems(layout, bandType, entries) {
556
+ const band = findBand(layout, bandType);
557
+ if (!band) return [];
558
+
559
+ band.items ??= [];
560
+
561
+ const made = [];
562
+
563
+ for (const { band: from, item } of (entries || [])) {
564
+ if (!item) continue;
565
+
566
+ /**
567
+ * A pasted table is skipped rather than refusing the whole paste: a
568
+ * clipboard of five items should place the four it can.
569
+ */
570
+ if (item.type === 'table' && !canAddTable(layout)) continue;
571
+
572
+ const copy = structuredClone(item);
573
+ const y = Math.max(0, (item.y ?? 0) + DUPLICATE_OFFSET);
574
+
575
+ copy.id = nextItemId(layout, idPrefix(item));
576
+ copy.x = clampX(layout, (item.x ?? 0) + DUPLICATE_OFFSET, copy.w);
577
+ copy.y = from === bandType ? y : clampY(layout, bandType, y, copy);
578
+
579
+ if (copy.type === 'table') settleTable(copy, band);
580
+
581
+ band.items.push(copy);
582
+ made.push(copy);
583
+ }
584
+
585
+ return made;
586
+ }
587
+
588
+
589
+ export function removeItem(layout, bandType, id) {
590
+ const band = findBand(layout, bandType);
591
+ if (!band) return false;
592
+
593
+ const at = (band.items || []).findIndex(i => i.id === id);
594
+ if (at === -1) return false;
595
+
596
+ band.items.splice(at, 1);
597
+ return true;
598
+ }
599
+
600
+
601
+ /**
602
+ * Moves an item from one band to another, keeping it where it looks.
603
+ *
604
+ * An item's y is relative to its band (spec 3.3), so carrying the same number
605
+ * across would jump it - 10px from the top of the detail band is a long way
606
+ * from 10px from the top of the page footer. The position is lifted into page
607
+ * coordinates, the item is moved, and the offset is worked out again against
608
+ * where it has arrived.
609
+ *
610
+ * @param {object} layout
611
+ * @param {string} from
612
+ * @param {string} to
613
+ * @param {string} id
614
+ * @returns {boolean} whether it moved
615
+ */
616
+ export function moveItemToBand(layout, from, to, id) {
617
+ if (from === to) return false;
618
+
619
+ const source = findBand(layout, from);
620
+ const target = findBand(layout, to);
621
+ if (!source || !target) return false;
622
+
623
+ const item = (source.items || []).find(i => i.id === id);
624
+ if (!item) return false;
625
+
626
+ const page = absoluteTop(layout, from, item.y ?? 0);
627
+
628
+ removeItem(layout, from, id);
629
+ addItem(layout, to, item);
630
+
631
+ const landed = absoluteTop(layout, to, 0);
632
+ if (page !== null && landed !== null) item.y = Math.round(page - landed);
633
+
634
+ return true;
635
+ }
636
+
637
+
638
+ /**
639
+ * Adds a column, at the default width rather than by redistributing the others.
640
+ *
641
+ * Resizing every column because a new one arrived would silently undo widths
642
+ * that were set on purpose. A table wider than its item is the author's to fix,
643
+ * and `table-layout: fixed` draws it predictably meanwhile.
644
+ */
645
+ export function addColumn(table) {
646
+ table.columns ??= [];
647
+
648
+ const column = makeColumn(table.columns.length + 1);
649
+ table.columns.push(column);
650
+
651
+ return column;
652
+ }
653
+
654
+
655
+ /**
656
+ * @returns {boolean} false when the column is the last one, which must stay -
657
+ * validate.js requires a non-empty `columns`, and a table with none is not a
658
+ * table but a validation error waiting for whoever opens the file next
659
+ */
660
+ export function removeColumn(table, index) {
661
+ if (!Array.isArray(table.columns) || table.columns.length <= 1) return false;
662
+ if (index < 0 || index >= table.columns.length) return false;
663
+
664
+ table.columns.splice(index, 1);
665
+ return true;
666
+ }
667
+
668
+
669
+ /**
670
+ * Where a newly added item should go: the band the selection is on, or the
671
+ * detail band, or whatever band exists at all.
672
+ *
673
+ * @param {object} layout
674
+ * @param {{band: string}|null} selection
675
+ * @returns {string|null}
676
+ */
677
+ export function targetBand(layout, selection) {
678
+ if (selection && hasBand(layout, selection.band)) return selection.band;
679
+ if (hasBand(layout, 'detail')) return 'detail';
680
+
681
+ return bandList(layout)[0]?.type ?? null;
682
+ }
683
+
684
+
685
+ export { snap };