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,633 @@
1
+ /**
2
+ * fields.js says what can be edited about an item, and how a typed value gets
3
+ * onto it.
4
+ *
5
+ * It is plain data and pure functions, so the fiddly half - which fields a
6
+ * table has, what an empty box means, what happens when someone types "abc"
7
+ * into a font size - is specified without a browser. panel.js draws these and
8
+ * decides nothing, the same division select.js has with geometry.js.
9
+ *
10
+ * The paths ("style.fontSize") are the layout file's own shape from spec 3.3.
11
+ * Nothing here invents a field the engine does not read.
12
+ */
13
+
14
+
15
+ /**
16
+ * Spec 10 left the font list open, and closes it here: web-safe families only.
17
+ *
18
+ * The engine measures text with canvas measureText against this exact string
19
+ * (spec 4.3), so a family the browser does not have is measured as a fallback
20
+ * and paginates to a different page count than it prints. Web-safe stacks
21
+ * remove loading, embedding, and that whole class of bug at once.
22
+ */
23
+ export const FONT_STACKS = [
24
+ { label: 'Helvetica', value: 'Helvetica, Arial, sans-serif' },
25
+ { label: 'Arial', value: 'Arial, Helvetica, sans-serif' },
26
+ { label: 'Verdana', value: 'Verdana, Geneva, sans-serif' },
27
+ { label: 'Trebuchet', value: '"Trebuchet MS", Helvetica, sans-serif' },
28
+ { label: 'Georgia', value: 'Georgia, "Times New Roman", serif' },
29
+ { label: 'Times', value: '"Times New Roman", Times, serif' },
30
+ { label: 'Courier', value: '"Courier New", Courier, monospace' }
31
+ ];
32
+
33
+ const WEIGHTS = [
34
+ { label: 'Regular', value: 'normal' },
35
+ { label: 'Bold', value: 'bold' }
36
+ ];
37
+
38
+ const STYLES = [
39
+ { label: 'Upright', value: 'normal' },
40
+ { label: 'Italic', value: 'italic' }
41
+ ];
42
+
43
+ const ALIGNMENTS = [
44
+ { label: 'Left', value: 'left' },
45
+ { label: 'Centre', value: 'center' },
46
+ { label: 'Right', value: 'right' }
47
+ ];
48
+
49
+ const IMAGE_FITS = [
50
+ { label: 'Fit inside', value: 'contain' },
51
+ { label: 'Fill and crop', value: 'cover' },
52
+ { label: 'Stretch', value: 'fill' }
53
+ ];
54
+
55
+ const ORIENTATIONS = [
56
+ { label: 'Horizontal', value: 'horizontal' },
57
+ { label: 'Vertical', value: 'vertical' }
58
+ ];
59
+
60
+ /**
61
+ * The four CSS border styles that read as a rule. `double` needs 3px before a
62
+ * browser can draw two lines and a gap, which the thickness field allows for.
63
+ */
64
+ const LINE_STYLES = [
65
+ { label: 'Solid', value: 'solid' },
66
+ { label: 'Dashed', value: 'dashed' },
67
+ { label: 'Dotted', value: 'dotted' },
68
+ { label: 'Double', value: 'double' }
69
+ ];
70
+
71
+ /**
72
+ * The same, plus off. A table's grid is often better away entirely - a column
73
+ * of figures usually reads more easily without one - which is not a thing a
74
+ * line can be, so the two lists are not shared.
75
+ */
76
+ const RULE_STYLES = [...LINE_STYLES, { label: 'None', value: 'none' }];
77
+
78
+
79
+ const num = (key, label, extra = {}) =>
80
+ ({ key, label, type: 'number', ...extra });
81
+
82
+
83
+ /**
84
+ * The widest rule a table can be drawn with and still measure what it declares.
85
+ * The same figure items.js clamps to - see maxRuleWidth there for why half the
86
+ * shallowest row is where it stops.
87
+ *
88
+ * @param {object} item a table
89
+ * @returns {number} pixels
90
+ */
91
+ function maxRuleWidth(item) {
92
+ const rowHeight = item.rowHeight ?? 0;
93
+ const headerHeight = item.showHeader ? (item.headerHeight ?? rowHeight) : rowHeight;
94
+
95
+ const shallowest = Math.min(rowHeight || Infinity, headerHeight || Infinity);
96
+
97
+ return Number.isFinite(shallowest) ? Math.max(1, Math.floor(shallowest / 2)) : 1;
98
+ }
99
+
100
+
101
+ /**
102
+ * What a table column carries (spec 3.3). The same descriptor shape again, read
103
+ * and written against the column object rather than the item - which is all
104
+ * readField and writeField need, since they walk a path on whatever they get.
105
+ */
106
+ export const COLUMN_FIELDS = [
107
+ { key: 'field', label: 'Field', type: 'text' },
108
+ { key: 'label', label: 'Label', type: 'text' },
109
+ { key: 'width', label: 'Width', type: 'number', min: 1 },
110
+ { key: 'align', label: 'Align', type: 'choice', options: ALIGNMENTS }
111
+ ];
112
+
113
+
114
+ /**
115
+ * The editable properties of an item, grouped the way the panel shows them.
116
+ *
117
+ * A table has no height row: its height is the header plus its rows (spec 3.3),
118
+ * so a box to type one into would be a promise the layout file cannot keep -
119
+ * the same reason geometry.js gives it no south handle.
120
+ *
121
+ * @param {object} item a layout item
122
+ * @returns {object[]} `{ title, fields }` sections
123
+ */
124
+ export function fieldsFor(item) {
125
+ if (!item) return [];
126
+
127
+ const box = {
128
+ title: 'Position and size',
129
+ fields: [
130
+ num('x', 'X'),
131
+ num('y', 'Y'),
132
+ num('w', 'Width', { min: 1 }),
133
+ ...(item.type === 'table' ? [] : [num('h', 'Height', { min: 1 })])
134
+ ]
135
+ };
136
+
137
+ if (item.type === 'box') {
138
+ return [
139
+ box,
140
+ {
141
+ title: 'Border',
142
+ fields: [
143
+ {
144
+ key: 'style.borderStyle', label: 'Style', type: 'choice',
145
+ options: RULE_STYLES
146
+ },
147
+ num('style.borderWidth', 'Width', { min: 1 }),
148
+ { key: 'style.borderColor', label: 'Colour', type: 'color' },
149
+ num('style.radius', 'Corner', { min: 0 })
150
+ ]
151
+ },
152
+ {
153
+ title: 'Fill',
154
+ fields: [
155
+ {
156
+ key: 'style.background', label: 'Background', type: 'color',
157
+ hint: 'Leave a box unfilled to frame what is behind it'
158
+ }
159
+ ]
160
+ }
161
+ ];
162
+ }
163
+
164
+ if (item.type === 'image') {
165
+ return [
166
+ {
167
+ title: 'Picture',
168
+ fields: [
169
+ {
170
+ key: 'src', label: 'Image', type: 'image',
171
+ hint: 'Stored in the layout file. Keep it small - a logo, ' +
172
+ 'not a photograph'
173
+ },
174
+ {
175
+ key: 'field', label: 'From data', type: 'text', nullable: true,
176
+ hint: 'A data path such as company.logo, whose value is the ' +
177
+ "picture's URL. It replaces the stored image when present"
178
+ },
179
+ { key: 'fit', label: 'Fit', type: 'choice', options: IMAGE_FITS },
180
+ {
181
+ key: 'alt', label: 'Description', type: 'text',
182
+ hint: 'Read out by a screen reader in place of the picture'
183
+ }
184
+ ]
185
+ },
186
+ box
187
+ ];
188
+ }
189
+
190
+ if (item.type === 'line') {
191
+ return [
192
+ box,
193
+ {
194
+ title: 'Line',
195
+ fields: [
196
+ {
197
+ key: 'orientation', label: 'Runs', type: 'choice',
198
+ options: ORIENTATIONS
199
+ },
200
+ num('style.thickness', 'Thickness', { min: 1 }),
201
+ {
202
+ key: 'style.lineStyle', label: 'Style', type: 'choice',
203
+ options: LINE_STYLES
204
+ },
205
+ { key: 'style.color', label: 'Colour', type: 'color' }
206
+ ]
207
+ }
208
+ ];
209
+ }
210
+
211
+ if (item.type === 'table') {
212
+ return [
213
+ box,
214
+ {
215
+ title: 'Data',
216
+ fields: [
217
+ {
218
+ key: 'dataset', label: 'Dataset', type: 'text', nullable: true,
219
+ hint: "The key in the data object whose rows this table " +
220
+ "draws. Blank reads the report's dataset"
221
+ },
222
+ {
223
+ key: 'groupBy', label: 'Group by', type: 'text', nullable: true,
224
+ hint: 'A field to group these rows by, or blank. One table ' +
225
+ 'in a report can be grouped'
226
+ }
227
+ ]
228
+ },
229
+ {
230
+ title: 'Rows',
231
+ fields: [num('rowHeight', 'Row height', { min: 1 })]
232
+ },
233
+ {
234
+ /**
235
+ * The header is the part of a table anyone styles first, and
236
+ * its height was buried among the rows' - which is also the one
237
+ * figure that is not a row's, since the engine paginates a
238
+ * table as headerHeight + rows x rowHeight.
239
+ */
240
+ title: 'Header',
241
+ fields: [
242
+ { key: 'showHeader', label: 'Show header', type: 'toggle' },
243
+ num('headerHeight', 'Height', { min: 1 }),
244
+ { key: 'style.headerBackground', label: 'Fill', type: 'color' },
245
+ {
246
+ key: 'style.headerColor', label: 'Text', type: 'color',
247
+ hint: "Leave these alone to keep the stylesheet's own header"
248
+ }
249
+ ]
250
+ },
251
+ {
252
+ title: 'Appearance',
253
+ fields: [
254
+ {
255
+ key: 'style.fontFamily', label: 'Font', type: 'choice',
256
+ options: FONT_STACKS
257
+ },
258
+ num('style.fontSize', 'Font size', { min: 1 }),
259
+ { key: 'style.color', label: 'Text', type: 'color' },
260
+ {
261
+ key: 'wrap', label: 'Wrap cells', type: 'toggle',
262
+ hint: 'A cell wider than its column runs onto another ' +
263
+ 'line and the row grows; turn this off to keep ' +
264
+ 'every row one line, cut off with an ellipsis'
265
+ },
266
+ {
267
+ key: 'style.borderStyle', label: 'Borders', type: 'choice',
268
+ options: RULE_STYLES
269
+ },
270
+ num('style.borderWidth', 'Border width', {
271
+ min: 1,
272
+ /**
273
+ * A rule taller than half a row makes the cell grow, and
274
+ * a table that outgrows headerHeight + rows x rowHeight
275
+ * is a table pagination has measured wrongly. The rail
276
+ * will not offer the figure that does it.
277
+ */
278
+ max: maxRuleWidth(item)
279
+ }),
280
+ { key: 'style.borderColor', label: 'Border colour', type: 'color' }
281
+ ]
282
+ }
283
+ ];
284
+ }
285
+
286
+ return [
287
+ {
288
+ title: 'Content',
289
+ fields: [{
290
+ key: 'value', label: 'Value', type: 'textarea',
291
+ hint: 'Placeholders in braces: {customer.name}, {page}, {sum(amount)}'
292
+ }]
293
+ },
294
+ box,
295
+ {
296
+ title: 'Type',
297
+ fields: [
298
+ { key: 'style.fontFamily', label: 'Font', type: 'choice', options: FONT_STACKS },
299
+ num('style.fontSize', 'Size', { min: 1 }),
300
+ { key: 'style.fontWeight', label: 'Weight', type: 'choice', options: WEIGHTS },
301
+ { key: 'style.fontStyle', label: 'Style', type: 'choice', options: STYLES },
302
+ { key: 'style.align', label: 'Align', type: 'choice', options: ALIGNMENTS },
303
+ { key: 'style.color', label: 'Colour', type: 'color' }
304
+ ]
305
+ }
306
+ ];
307
+ }
308
+
309
+
310
+ /**
311
+ * Page sizes worth having by name. Spec 6.2: pixels throughout, and these are
312
+ * the two figures it gives - A4 and Letter at screen resolution, which is what
313
+ * browser print produces.
314
+ */
315
+ export const PAGE_PRESETS = [
316
+ { label: 'A2', width: 1587, height: 2245 },
317
+ { label: 'A3', width: 1123, height: 1587 },
318
+ { label: 'A4', width: 794, height: 1123 },
319
+ { label: 'A5', width: 559, height: 794 },
320
+ { label: 'A6', width: 397, height: 559 },
321
+ { label: 'Letter', width: 816, height: 1056 },
322
+ { label: 'Legal', width: 816, height: 1344 },
323
+ { label: 'Tabloid', width: 1056, height: 1632 }
324
+ ];
325
+
326
+ /** what the dropdown says for a page that is not one of them */
327
+ export const CUSTOM_PAPER = 'custom';
328
+
329
+
330
+ /**
331
+ * Which sheet a page is, by its size.
332
+ *
333
+ * Either way round, because a landscape A4 is still A4 - and a dropdown that
334
+ * said "Custom" the moment somebody turned the page would be one nobody could
335
+ * use to turn it back.
336
+ *
337
+ * Derived rather than stored: the size is the fact, the name is a reading of
338
+ * it. A layout hand-edited to 794 x 1123 reads as A4 without anyone having had
339
+ * to also write the word down, and the two can never disagree.
340
+ *
341
+ * The one thing that cannot be derived is somebody having *asked* for the
342
+ * boxes on a page that is currently a named size, so that alone is remembered.
343
+ * Only the absence of a name is ever written down - never a name - so the file
344
+ * has nothing in it that can contradict the size beside it.
345
+ *
346
+ * @param {object} page the layout's page
347
+ * @returns {string} a preset label, or CUSTOM_PAPER
348
+ */
349
+ export function paperOf(page) {
350
+ if (page?.paper === CUSTOM_PAPER) return CUSTOM_PAPER;
351
+
352
+ const w = page?.width;
353
+ const h = page?.height;
354
+
355
+ const found = PAGE_PRESETS.find(sheet =>
356
+ (sheet.width === w && sheet.height === h)
357
+ || (sheet.height === w && sheet.width === h));
358
+
359
+ return found ? found.label : CUSTOM_PAPER;
360
+ }
361
+
362
+
363
+ /** which way up it is, which only means anything once it has a size */
364
+ function orientationOf(page) {
365
+ return (page?.width ?? 0) > (page?.height ?? 0) ? 'landscape' : 'portrait';
366
+ }
367
+
368
+
369
+ /**
370
+ * Puts a named sheet on the layout, keeping the way up it already had.
371
+ *
372
+ * @param {object} layout mutated in place
373
+ * @param {string} label
374
+ * @returns {boolean} whether anything changed
375
+ */
376
+ function setPaper(layout, label) {
377
+ const sheet = PAGE_PRESETS.find(one => one.label === label);
378
+
379
+ /**
380
+ * Custom is not a size, it is the absence of one - so choosing it leaves the
381
+ * page exactly as it is and only reveals the two boxes. Throwing the
382
+ * dimensions away at the moment somebody asked to edit them would be a
383
+ * strange way to help.
384
+ *
385
+ * It has to stick, though. Without the flag, a page that happens to be A4
386
+ * would read as A4 again the instant the rail was rebuilt, and the boxes
387
+ * would vanish before anyone could type in them.
388
+ */
389
+ if (!sheet) {
390
+ if (layout.page.paper === CUSTOM_PAPER) return false;
391
+
392
+ layout.page.paper = CUSTOM_PAPER;
393
+ return true;
394
+ }
395
+
396
+ const landscape = orientationOf(layout.page) === 'landscape';
397
+
398
+ const width = landscape ? sheet.height : sheet.width;
399
+ const height = landscape ? sheet.width : sheet.height;
400
+
401
+ const wasCustom = layout.page.paper === CUSTOM_PAPER;
402
+
403
+ /** a named sheet is a name again; the flag is only ever the lack of one */
404
+ delete layout.page.paper;
405
+
406
+ if (layout.page.width === width && layout.page.height === height) {
407
+ return wasCustom;
408
+ }
409
+
410
+ layout.page.width = width;
411
+ layout.page.height = height;
412
+ return true;
413
+ }
414
+
415
+
416
+ /** turns the page, whatever size it is */
417
+ function setOrientation(layout, value) {
418
+ const wanted = value === 'landscape';
419
+
420
+ if (wanted === (orientationOf(layout.page) === 'landscape')) return false;
421
+
422
+ const { width, height } = layout.page;
423
+
424
+ layout.page.width = height;
425
+ layout.page.height = width;
426
+ return true;
427
+ }
428
+
429
+
430
+ /**
431
+ * The Page section: which sheet, which way up, and - only when the sheet is
432
+ * Custom - the two numbers themselves.
433
+ *
434
+ * The boxes are hidden rather than disabled for a named sheet, because a
435
+ * disabled 794 invites somebody to try to change it and then wonder why they
436
+ * cannot. The number is in the dropdown's own label instead, so nothing is
437
+ * hidden that anyone needed to read.
438
+ *
439
+ * @param {object} layout
440
+ * @returns {object[]}
441
+ */
442
+ function pageFields(layout) {
443
+ const custom = paperOf(layout.page) === CUSTOM_PAPER;
444
+
445
+ const paper = {
446
+ key: 'paper',
447
+ label: 'Paper',
448
+ type: 'choice',
449
+ /** the controls below it differ per sheet, so the rail is rebuilt */
450
+ rebuilds: true,
451
+ options: [
452
+ ...PAGE_PRESETS.map(sheet => ({
453
+ value: sheet.label,
454
+ label: `${sheet.label} ${sheet.width} x ${sheet.height}`
455
+ })),
456
+ { value: CUSTOM_PAPER, label: 'Custom' }
457
+ ],
458
+ read: (target) => paperOf(target.page),
459
+ write: (target, value) => setPaper(target, value)
460
+ };
461
+
462
+ const orientation = {
463
+ key: 'orientation',
464
+ label: 'Orientation',
465
+ type: 'choice',
466
+ rebuilds: true,
467
+ options: [
468
+ { value: 'portrait', label: 'Portrait' },
469
+ { value: 'landscape', label: 'Landscape' }
470
+ ],
471
+ read: (target) => orientationOf(target.page),
472
+ write: (target, value) => setOrientation(target, value)
473
+ };
474
+
475
+ return custom
476
+ ? [paper, num('page.width', 'Width', { min: 1 }),
477
+ num('page.height', 'Height', { min: 1 })]
478
+ : [paper, orientation];
479
+ }
480
+
481
+
482
+ /**
483
+ * The report's own properties - what the rail shows when no item is selected.
484
+ *
485
+ * Deliberately the same descriptor shape as an item's, so panel.js draws both
486
+ * with one set of controls. readField and writeField walk a path on whatever
487
+ * object they are handed, and a layout is just another object.
488
+ *
489
+ * @param {object|null} layout
490
+ * @returns {object[]} `{ title, fields }` sections
491
+ */
492
+ export function reportFields(layout) {
493
+ if (!layout) return [];
494
+
495
+ return [
496
+ {
497
+ title: 'Report',
498
+ fields: [
499
+ { key: 'name', label: 'Name', type: 'text' },
500
+ {
501
+ key: 'dataset', label: 'Dataset', type: 'text', nullable: true,
502
+ hint: 'The key in the data object that drives the rows, ' +
503
+ 'for every table that does not name its own'
504
+ },
505
+ {
506
+ key: 'groupBy', label: 'Group by', type: 'text', nullable: true,
507
+ hint: 'A field name, or blank for no grouping. Groups the ' +
508
+ 'first table, unless a table sets its own'
509
+ }
510
+ ]
511
+ },
512
+ {
513
+ title: 'Page',
514
+ fields: pageFields(layout)
515
+ },
516
+ {
517
+ title: 'Margins',
518
+ fields: [
519
+ num('page.margin.top', 'Top', { min: 0 }),
520
+ num('page.margin.right', 'Right', { min: 0 }),
521
+ num('page.margin.bottom', 'Bottom', { min: 0 }),
522
+ num('page.margin.left', 'Left', { min: 0 })
523
+ ]
524
+ }
525
+ ];
526
+ }
527
+
528
+
529
+ export function allReportFields(layout) {
530
+ return reportFields(layout).flatMap(section => section.fields);
531
+ }
532
+
533
+
534
+ /** every field of every section, flat */
535
+ export function allFields(item) {
536
+ return fieldsFor(item).flatMap(section => section.fields);
537
+ }
538
+
539
+
540
+ function pathOf(key) {
541
+ return key.split('.');
542
+ }
543
+
544
+
545
+ /**
546
+ * The value to show in a field's control.
547
+ * @param {object} item
548
+ * @param {object} field
549
+ * @returns {*} undefined when the item does not carry it
550
+ */
551
+ export function readField(item, field) {
552
+ /**
553
+ * A field that is a reading of the object rather than a place on it - the
554
+ * paper size is the width and the height, said as a name. It has no path to
555
+ * walk, so it says how to be read instead.
556
+ */
557
+ if (field.read) return field.read(item);
558
+
559
+ let node = item;
560
+
561
+ for (const step of pathOf(field.key)) {
562
+ if (node == null) return undefined;
563
+ node = node[step];
564
+ }
565
+
566
+ return node;
567
+ }
568
+
569
+
570
+ /**
571
+ * Puts a typed value onto an item, and says whether anything changed.
572
+ *
573
+ * Refusing a value rather than storing a bad one is deliberate: these controls
574
+ * are bound live, so an empty box is a half-typed number, not a request for
575
+ * NaN. The field keeps its last good value and the canvas stops flickering
576
+ * between drawn and blank while someone retypes a width.
577
+ *
578
+ * @param {object} item mutated in place; it is the layout the host will be given
579
+ * @param {object} field
580
+ * @param {*} raw whatever the control produced
581
+ * @returns {boolean} true when the item changed
582
+ */
583
+ export function writeField(item, field, raw) {
584
+ const value = coerce(field, raw);
585
+ if (value === undefined) return false;
586
+
587
+ /** the other half of a derived field: it says how to be written, too */
588
+ if (field.write) return field.write(item, value);
589
+
590
+ const path = pathOf(field.key);
591
+ const last = path.pop();
592
+
593
+ let node = item;
594
+ for (const step of path) {
595
+ if (node[step] == null || typeof node[step] !== 'object') node[step] = {};
596
+ node = node[step];
597
+ }
598
+
599
+ if (node[last] === value) return false;
600
+
601
+ node[last] = value;
602
+ return true;
603
+ }
604
+
605
+
606
+ /**
607
+ * @returns {*} undefined for a value the field will not accept
608
+ */
609
+ function coerce(field, raw) {
610
+ if (field.type === 'toggle') return Boolean(raw);
611
+
612
+ if (field.type === 'number') {
613
+ if (raw === '' || raw === null || raw === undefined) return undefined;
614
+
615
+ const value = Number(raw);
616
+ if (!Number.isFinite(value)) return undefined;
617
+
618
+ const floored = field.min != null ? Math.max(value, field.min) : value;
619
+
620
+ return field.max != null ? Math.min(floored, field.max) : floored;
621
+ }
622
+
623
+ if (raw === null || raw === undefined) return undefined;
624
+
625
+ /**
626
+ * `groupBy` and `dataset` are "a field name, or nothing" (spec 3.1), and
627
+ * nothing is null - an empty string would be a dataset named "", which the
628
+ * engine would then go looking for.
629
+ */
630
+ if (field.nullable && raw === '') return null;
631
+
632
+ return String(raw);
633
+ }