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,154 @@
1
+ /**
2
+ * geometry.js is the arithmetic behind moving and resizing an item.
3
+ *
4
+ * All of it is pure - numbers in, numbers out - so the awkward cases (dragging
5
+ * a west handle past the minimum width, a table that has no height of its own)
6
+ * are specified without a browser. What is left in select.js is pointer
7
+ * plumbing, which is the part that cannot be tested and so should be the part
8
+ * that decides nothing.
9
+ */
10
+
11
+
12
+ import { DESIGN_ROWS, designHeight } from '../engine/measure.js';
13
+
14
+
15
+ /** spec 5.2: positions snap to a 10px grid */
16
+ export const GRID = 10;
17
+
18
+ /**
19
+ * Sizes do not snap - spec 5.2 grids the drag and asks only for a minimum on
20
+ * the resize. That distinction is worth keeping: positions want to line up with
21
+ * each other, but a 34px title is 34px on purpose, and rounding it to 30 while
22
+ * someone drags a different edge is a small theft.
23
+ */
24
+ export const MIN_W = 20;
25
+ export const MIN_H = 12;
26
+
27
+ /**
28
+ * Enough rows to show that a table is a table, few enough that it does not
29
+ * swallow the detail zone. The real row count is a print-time fact.
30
+ *
31
+ * Owned by the engine rather than declared here, because it is not only what
32
+ * the canvas draws: paginate.js measures a table's growth from the same figure
33
+ * when it floats what sits below the table down the page. Two copies of it
34
+ * would put the design and the print an invisible three rows apart.
35
+ */
36
+ export const SAMPLE_ROWS = DESIGN_ROWS;
37
+
38
+ /** the eight, clockwise from the top-left */
39
+ const ALL_HANDLES = ['nw', 'n', 'ne', 'e', 'se', 's', 'sw', 'w'];
40
+ const SIDE_HANDLES = ['e', 'w'];
41
+
42
+
43
+ export function snap(value) {
44
+ return Math.round(value / GRID) * GRID;
45
+ }
46
+
47
+
48
+ /**
49
+ * A table declares no `h` (spec 3.3) - its height is the header plus its rows,
50
+ * and at print time the row count is the data's. This is the design-time
51
+ * equivalent, and it is the same figure the canvas draws with, so the selection
52
+ * outline lands exactly on the table rather than near it.
53
+ *
54
+ * Re-exported from the engine rather than written twice: it is also the height
55
+ * paginate.js treats as the table's designed size, and the canvas and the
56
+ * printed page have to agree about that or nothing below a table lands where it
57
+ * was put.
58
+ */
59
+ export { designHeight };
60
+
61
+
62
+ /** an item's box in band-relative coordinates */
63
+ export function itemBox(item) {
64
+ return { x: item.x ?? 0, y: item.y ?? 0, w: item.w ?? 0, h: designHeight(item) };
65
+ }
66
+
67
+
68
+ /**
69
+ * Which axes an item can be resized on.
70
+ *
71
+ * A table's height is derived, so offering a south handle would promise an edit
72
+ * that cannot be stored - there is nowhere in the layout file to put it. Only
73
+ * the two side handles are shown, which says so without a tooltip.
74
+ */
75
+ export function resizableAxes(item) {
76
+ return item.type === 'table' ? 'x' : 'xy';
77
+ }
78
+
79
+
80
+ export function handlesFor(axes) {
81
+ return axes === 'x' ? [...SIDE_HANDLES] : [...ALL_HANDLES];
82
+ }
83
+
84
+
85
+ /**
86
+ * Where an item lands after a drag. The absolute position is snapped, not the
87
+ * delta, so items dragged from different starting offsets end up on the same
88
+ * grid line - which is the point of having one.
89
+ *
90
+ * @param {object} start the box the drag began from
91
+ * @param {number} dx pointer movement in page pixels
92
+ * @param {number} dy
93
+ * @returns {{x: number, y: number}}
94
+ */
95
+ export function moveTo(start, dx, dy) {
96
+ return { x: snap(start.x + dx), y: snap(start.y + dy) };
97
+ }
98
+
99
+
100
+ /**
101
+ * Where an item lands after a handle drag.
102
+ *
103
+ * Dragging a north or west handle moves that edge and leaves the opposite one
104
+ * where it is, so the box is re-derived from the far edge rather than by adding
105
+ * the delta to the origin. Without that, an item shrunk to its minimum keeps
106
+ * sliding as the pointer continues past it.
107
+ *
108
+ * @param {string} handle one of nw n ne e se s sw w
109
+ * @param {object} start the box the drag began from
110
+ * @param {number} dx
111
+ * @param {number} dy
112
+ * @param {string} [axes] 'x' pins the height, for a table
113
+ * @returns {{x: number, y: number, w: number, h: number}}
114
+ */
115
+ export function resizeBy(handle, start, dx, dy, axes = 'xy') {
116
+ let { x, y, w, h } = start;
117
+
118
+ if (handle.includes('w')) {
119
+ w = Math.max(start.w - dx, MIN_W);
120
+ x = start.x + start.w - w;
121
+ } else if (handle.includes('e')) {
122
+ w = Math.max(start.w + dx, MIN_W);
123
+ }
124
+
125
+ if (axes === 'xy') {
126
+ if (handle.includes('n')) {
127
+ h = Math.max(start.h - dy, MIN_H);
128
+ y = start.y + start.h - h;
129
+ } else if (handle.includes('s')) {
130
+ h = Math.max(start.h + dy, MIN_H);
131
+ }
132
+ }
133
+
134
+ return { x, y, w, h };
135
+ }
136
+
137
+
138
+ /**
139
+ * Writes a box back onto a layout item.
140
+ *
141
+ * A table's height is not stored - it is derived from the row count - so it is
142
+ * dropped here rather than written as a field the engine would ignore and the
143
+ * next reader would believe.
144
+ *
145
+ * @param {object} item mutated in place; it is the layout the host will be given
146
+ * @param {object} box
147
+ */
148
+ export function applyBox(item, box) {
149
+ item.x = box.x;
150
+ item.y = box.y;
151
+
152
+ if (box.w != null) item.w = box.w;
153
+ if (box.h != null && item.type !== 'table') item.h = box.h;
154
+ }
@@ -0,0 +1,370 @@
1
+ /**
2
+ * guides.js is the arithmetic behind the alignment guides.
3
+ *
4
+ * Dragging on a 10px grid lines an item up with the grid, which is not the
5
+ * thing anyone is trying to line it up with. What they want is the item beside
6
+ * it, the middle of the band, the left edge of the paragraph above - and no
7
+ * amount of squinting at a grid finds those. So while an item is being dragged
8
+ * this works out what it is nearly level with, pulls it the rest of the way,
9
+ * and says what it snapped to; and separately measures the space left around
10
+ * it, so the gaps can be read off rather than guessed at.
11
+ *
12
+ * All of it is pure - boxes in, boxes out - so what a guide does in the awkward
13
+ * cases is specified without a browser, the same way geometry.js is. Nothing
14
+ * here knows that a box is an item, that a band is a band, or that any of it
15
+ * ends up as a line on a screen.
16
+ *
17
+ * Every number is in the band's own coordinates. Turning those into somewhere
18
+ * on the page is the canvas's job, and doing it here would tie the arithmetic
19
+ * to one way of drawing it.
20
+ */
21
+
22
+
23
+ /**
24
+ * How close, in page pixels, an edge has to be before it is taken as meaning
25
+ * the same thing as the edge beside it.
26
+ *
27
+ * Bigger than the 10px grid step would make the grid unreachable - every drag
28
+ * would be captured by a neighbour and the grid would only apply where there
29
+ * was nothing to align to. Smaller than about four and the snap is too hard to
30
+ * land on to be worth having.
31
+ */
32
+ export const SNAP = 6;
33
+
34
+ /** floating point: two edges a thousandth of a pixel apart are the same edge */
35
+ const EPSILON = 0.01;
36
+
37
+
38
+ /**
39
+ * The three vertical lines a box can be lined up on: its two sides and its
40
+ * middle. Ordered left to right, and `centre` marks the middle one - a guide
41
+ * drawn through two centres reads differently from one drawn down two edges,
42
+ * and the caller is the one that has to say so.
43
+ *
44
+ * @param {{x: number, w: number}} box
45
+ * @returns {{at: number, centre: boolean}[]}
46
+ */
47
+ export function railsX(box) {
48
+ return [
49
+ { at: box.x, centre: false },
50
+ { at: box.x + (box.w ?? 0) / 2, centre: true },
51
+ { at: box.x + (box.w ?? 0), centre: false }
52
+ ];
53
+ }
54
+
55
+
56
+ /**
57
+ * The same three, horizontally: top, middle, bottom.
58
+ *
59
+ * @param {{y: number, h: number}} box
60
+ * @returns {{at: number, centre: boolean}[]}
61
+ */
62
+ export function railsY(box) {
63
+ return [
64
+ { at: box.y, centre: false },
65
+ { at: box.y + (box.h ?? 0) / 2, centre: true },
66
+ { at: box.y + (box.h ?? 0), centre: false }
67
+ ];
68
+ }
69
+
70
+
71
+ /**
72
+ * The smallest box holding all of them, so a group of items is aligned as the
73
+ * one shape it looks like rather than each member finding its own line.
74
+ *
75
+ * @param {object[]} boxes
76
+ * @returns {object|null} null for an empty group, which has no shape
77
+ */
78
+ export function unionBox(boxes) {
79
+ if (!boxes?.length) return null;
80
+
81
+ const left = Math.min(...boxes.map(b => b.x));
82
+ const top = Math.min(...boxes.map(b => b.y));
83
+ const right = Math.max(...boxes.map(b => b.x + (b.w ?? 0)));
84
+ const bottom = Math.max(...boxes.map(b => b.y + (b.h ?? 0)));
85
+
86
+ return { x: left, y: top, w: right - left, h: bottom - top };
87
+ }
88
+
89
+
90
+ /**
91
+ * Everything the moving box could line up against on one axis.
92
+ *
93
+ * Three kinds, in the order a tie between them should be settled:
94
+ *
95
+ * a ruler guide - somebody put it there on purpose, so it outranks anything
96
+ * that merely happens to be nearby;
97
+ * the other items;
98
+ * the band, whose middle is the alignment people reach for most and the one
99
+ * thing a grid can never help with.
100
+ *
101
+ * A target with no box has its guide drawn across the whole band rather than
102
+ * only as far as a neighbour, which is true of both the band's own lines and a
103
+ * ruler guide.
104
+ *
105
+ * @param {object[]} others the boxes already in the band
106
+ * @param {{w: number, h: number}} band its size, in its own coordinates
107
+ * @param {'x'|'y'} axis
108
+ * @param {number[]} [guides] ruler guides, in the band's coordinates
109
+ * @returns {{at: number, centre: boolean, box: object|null}[]}
110
+ */
111
+ export function targetsOn(others, band, axis, guides = []) {
112
+ const rails = axis === 'x' ? railsX : railsY;
113
+
114
+ const fromGuides = (guides || [])
115
+ .filter(Number.isFinite)
116
+ .map(at => ({ at, centre: false, box: null }));
117
+
118
+ const fromItems = (others || []).flatMap(box =>
119
+ rails(box).map(rail => ({ ...rail, box })));
120
+
121
+ const span = axis === 'x' ? (band?.w ?? 0) : (band?.h ?? 0);
122
+
123
+ const fromBand = band
124
+ ? rails({ x: 0, y: 0, w: span, h: span }).map(rail => ({ ...rail, box: null }))
125
+ : [];
126
+
127
+ return [...fromGuides, ...fromItems, ...fromBand];
128
+ }
129
+
130
+
131
+ /**
132
+ * The pull one axis of the moving box feels.
133
+ *
134
+ * The nearest match wins, and a tie goes to the first found - so the band's own
135
+ * edges, which are last in the list, never beat an item the pointer is actually
136
+ * near. What comes back is the distance to travel, not the destination, because
137
+ * the caller has a whole group to move by it.
138
+ *
139
+ * @param {{at: number}[]} rails the moving box's three lines on this axis
140
+ * @param {{at: number}[]} targets what it might line up with
141
+ * @param {number} snap how close is close enough
142
+ * @returns {{delta: number, at: number}|null} null when nothing is near
143
+ */
144
+ export function pullTowards(rails, targets, snap = SNAP) {
145
+ let best = null;
146
+
147
+ for (const rail of rails) {
148
+ for (const target of targets) {
149
+ const delta = target.at - rail.at;
150
+ if (Math.abs(delta) > snap) continue;
151
+
152
+ if (!best || Math.abs(delta) < Math.abs(best.delta) - EPSILON) {
153
+ best = { delta, at: target.at };
154
+ }
155
+ }
156
+ }
157
+
158
+ return best;
159
+ }
160
+
161
+
162
+ /**
163
+ * The guides to draw for one axis, once the box has been pulled into line.
164
+ *
165
+ * A guide is only worth drawing if it says which things agree, so it is drawn
166
+ * from the top of the highest of them to the bottom of the lowest - the line
167
+ * touches everything it is claiming about and nothing else. A line that ran the
168
+ * whole band would be true of the band, not of the two items.
169
+ *
170
+ * @param {object} moved the moving box, already snapped
171
+ * @param {{at: number, centre: boolean, box: object|null}[]} targets
172
+ * @param {number} at the line everything agreed on
173
+ * @param {'x'|'y'} axis
174
+ * @param {{w: number, h: number}} band
175
+ * @returns {{axis: string, at: number, from: number, to: number, centre: boolean}[]}
176
+ */
177
+ export function lineFor(moved, targets, at, axis, band) {
178
+ const matched = targets.filter(t => Math.abs(t.at - at) < EPSILON);
179
+ if (!matched.length) return [];
180
+
181
+ /** across the band when the band itself is what it lined up with */
182
+ const toBand = matched.some(t => t.box === null);
183
+ const boxes = matched.map(t => t.box).filter(Boolean);
184
+
185
+ const along = axis === 'x'
186
+ ? (b) => [b.y, b.y + (b.h ?? 0)]
187
+ : (b) => [b.x, b.x + (b.w ?? 0)];
188
+
189
+ const span = axis === 'x' ? (band?.h ?? 0) : (band?.w ?? 0);
190
+
191
+ const ends = [...along(moved), ...boxes.flatMap(along)];
192
+
193
+ return [{
194
+ axis,
195
+ at,
196
+ from: toBand ? 0 : Math.min(...ends),
197
+ to: toBand ? span : Math.max(...ends),
198
+ centre: matched.every(t => t.centre)
199
+ }];
200
+ }
201
+
202
+
203
+ /**
204
+ * Pulls a box into line with whatever it is nearly level with.
205
+ *
206
+ * The two axes are decided separately, because an item is very often lined up
207
+ * with one thing horizontally and a different thing vertically, and asking for
208
+ * a single winner would throw one of them away.
209
+ *
210
+ * @param {object} moving the box as the pointer has left it
211
+ * @param {object[]} others the other boxes in the band
212
+ * @param {{w: number, h: number}} band
213
+ * @param {object} [options]
214
+ * @param {number} [options.snap]
215
+ * @param {{x: number[], y: number[]}} [options.guides] ruler guides, in the
216
+ * band's own coordinates
217
+ * @returns {{dx: number, dy: number, lines: object[]}} the correction to apply,
218
+ * and the guides that explain it
219
+ */
220
+ export function alignBox(moving, others, band, { snap = SNAP, guides } = {}) {
221
+ if (!moving) return { dx: 0, dy: 0, lines: [] };
222
+
223
+ const acrossTargets = targetsOn(others, band, 'x', guides?.x);
224
+ const downTargets = targetsOn(others, band, 'y', guides?.y);
225
+
226
+ const across = pullTowards(railsX(moving), acrossTargets, snap);
227
+ const down = pullTowards(railsY(moving), downTargets, snap);
228
+
229
+ const dx = across?.delta ?? 0;
230
+ const dy = down?.delta ?? 0;
231
+
232
+ const moved = { ...moving, x: moving.x + dx, y: moving.y + dy };
233
+
234
+ return {
235
+ dx,
236
+ dy,
237
+ lines: [
238
+ ...(across ? lineFor(moved, acrossTargets, across.at, 'x', band) : []),
239
+ ...(down ? lineFor(moved, downTargets, down.at, 'y', band) : [])
240
+ ]
241
+ };
242
+ }
243
+
244
+
245
+ /** do two boxes share any of this axis, so that one is above the other at all */
246
+ function overlaps(a, b, axis) {
247
+ const [pos, size] = axis === 'x' ? ['x', 'w'] : ['y', 'h'];
248
+
249
+ return a[pos] < b[pos] + (b[size] ?? 0)
250
+ && a[pos] + (a[size] ?? 0) > b[pos];
251
+ }
252
+
253
+
254
+ /**
255
+ * The space on one side of the box, and what is on the other side of it.
256
+ *
257
+ * Only a box that is actually across from this one counts: a caption off in the
258
+ * right margin is not what the gap above is measured to, however high up it is.
259
+ * When nothing is across from it the gap is to the band's own edge, which is
260
+ * the answer people want anyway - it is the margin they are setting.
261
+ *
262
+ * @param {object} box the moving box
263
+ * @param {object[]} others
264
+ * @param {{w: number, h: number}} band
265
+ * @param {'up'|'down'|'left'|'right'} side
266
+ * @returns {object|null} the measurement, or null when the box is already past
267
+ * the edge it is being measured to
268
+ */
269
+ export function gapOn(box, others, band, side) {
270
+ const vertical = side === 'up' || side === 'down';
271
+
272
+ const axis = vertical ? 'y' : 'x';
273
+ const across = vertical ? 'x' : 'y';
274
+
275
+ const [pos, size] = vertical ? ['y', 'h'] : ['x', 'w'];
276
+ const near = box[pos];
277
+ const far = box[pos] + (box[size] ?? 0);
278
+ const before = side === 'up' || side === 'left';
279
+
280
+ const facing = (others || []).filter(other => {
281
+ if (!overlaps(box, other, across)) return false;
282
+
283
+ return before
284
+ ? other[pos] + (other[size] ?? 0) <= near
285
+ : other[pos] >= far;
286
+ });
287
+
288
+ const bandEnd = vertical ? (band?.h ?? 0) : (band?.w ?? 0);
289
+
290
+ /** the nearest thing on that side, or the band's edge when there is none */
291
+ const edge = facing.length
292
+ ? (before
293
+ ? Math.max(...facing.map(o => o[pos] + (o[size] ?? 0)))
294
+ : Math.min(...facing.map(o => o[pos])))
295
+ : (before ? 0 : bandEnd);
296
+
297
+ const distance = before ? near - edge : edge - far;
298
+
299
+ /** an item dragged past the top of its band has no gap above it to report */
300
+ if (!(distance >= 0)) return null;
301
+
302
+ /**
303
+ * Down the middle of what the two have in common, so the measurement sits
304
+ * between the boxes it is measuring rather than off beside them.
305
+ */
306
+ const neighbour = facing.find(o => Math.abs(
307
+ (before ? o[pos] + (o[size] ?? 0) : o[pos]) - edge) < EPSILON);
308
+
309
+ const shared = neighbour
310
+ ? [
311
+ Math.max(box[across], neighbour[across]),
312
+ Math.min(
313
+ box[across] + (box[vertical ? 'w' : 'h'] ?? 0),
314
+ neighbour[across] + (neighbour[vertical ? 'w' : 'h'] ?? 0))
315
+ ]
316
+ : [box[across], box[across] + (box[vertical ? 'w' : 'h'] ?? 0)];
317
+
318
+ return {
319
+ side,
320
+ axis,
321
+ at: (shared[0] + shared[1]) / 2,
322
+ from: before ? edge : far,
323
+ to: before ? near : edge,
324
+ distance,
325
+ toBand: facing.length === 0
326
+ };
327
+ }
328
+
329
+
330
+ /**
331
+ * The space on all four sides.
332
+ *
333
+ * @param {object} box
334
+ * @param {object[]} others
335
+ * @param {{w: number, h: number}} band
336
+ * @returns {object[]} the ones that could be measured
337
+ */
338
+ export function gapsAround(box, others, band) {
339
+ if (!box) return [];
340
+
341
+ return ['up', 'down', 'left', 'right']
342
+ .map(side => gapOn(box, others, band, side))
343
+ .filter(Boolean);
344
+ }
345
+
346
+
347
+ /**
348
+ * Everything the canvas needs to draw while one drag frame is on screen: the
349
+ * correction to apply to the items, the guides that explain it, and the space
350
+ * left around them once it has been applied.
351
+ *
352
+ * @param {object[]} moving the boxes being dragged
353
+ * @param {object[]} others the boxes staying put
354
+ * @param {{w: number, h: number}} band
355
+ * @param {object} [options]
356
+ * @param {number} [options.snap]
357
+ * @param {{x: number[], y: number[]}} [options.guides] ruler guides, in the
358
+ * band's own coordinates
359
+ * @returns {{dx: number, dy: number, lines: object[], gaps: object[]}}
360
+ */
361
+ export function guidesFor(moving, others, band, options = {}) {
362
+ const bounds = unionBox(moving);
363
+
364
+ if (!bounds) return { dx: 0, dy: 0, lines: [], gaps: [] };
365
+
366
+ const { dx, dy, lines } = alignBox(bounds, others, band, options);
367
+ const settled = { ...bounds, x: bounds.x + dx, y: bounds.y + dy };
368
+
369
+ return { dx, dy, lines, gaps: gapsAround(settled, others, band) };
370
+ }
@@ -0,0 +1,113 @@
1
+ /**
2
+ * history.js is undo and redo: an array of layout snapshots and an index into
3
+ * it. Spec 6 chose this over a state library, and it is the right size for the
4
+ * job - the layout is one small plain object, so a snapshot is a clone.
5
+ *
6
+ * The one thing that needs thought is typing. The rail's controls are bound
7
+ * live, so "250" typed into a width arrives as three edits, and three undo
8
+ * steps to get back past one number is not undo, it is punishment. Consecutive
9
+ * edits carrying the same `coalesce` key replace the top snapshot instead of
10
+ * stacking on it, so a burst of typing is one step and moving to another
11
+ * control starts the next.
12
+ *
13
+ * Coalescing on a key rather than on elapsed time is deliberate: it needs no
14
+ * timer, behaves the same however fast someone types, and can be specified.
15
+ */
16
+
17
+
18
+ /** far more than anyone reaches for, and small enough to hold clones of */
19
+ const LIMIT = 100;
20
+
21
+
22
+ const clone = (value) => structuredClone(value);
23
+ const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
24
+
25
+
26
+ /**
27
+ * @param {object} initial the layout as it stands now
28
+ * @param {object} [options]
29
+ * @param {number} [options.limit] how many steps to keep
30
+ * @returns {object} the history
31
+ */
32
+ export function createHistory(initial, { limit = LIMIT } = {}) {
33
+ let stack = [clone(initial)];
34
+ let index = 0;
35
+ /** what produced the entry on top, so a burst can be recognised */
36
+ let topKey = null;
37
+
38
+ return {
39
+ /**
40
+ * Records a change.
41
+ *
42
+ * @param {object} layout the layout as it now is
43
+ * @param {string|null} [key] edits sharing a key coalesce into one step
44
+ * @returns {boolean} whether a step was recorded
45
+ */
46
+ push(layout, key = null) {
47
+ if (same(layout, stack[index])) return false;
48
+
49
+ /**
50
+ * A new change abandons whatever was redoable - the future it led
51
+ * to is not reachable from here any more.
52
+ */
53
+ if (index < stack.length - 1) {
54
+ stack = stack.slice(0, index + 1);
55
+ topKey = null;
56
+ }
57
+
58
+ if (key != null && key === topKey) {
59
+ stack[index] = clone(layout);
60
+ return true;
61
+ }
62
+
63
+ stack.push(clone(layout));
64
+ index++;
65
+ topKey = key;
66
+
67
+ if (stack.length > limit) {
68
+ stack.shift();
69
+ index--;
70
+ }
71
+
72
+ return true;
73
+ },
74
+
75
+ /**
76
+ * @returns {object|null} the layout to go back to, or null at the start
77
+ */
78
+ undo() {
79
+ if (index === 0) return null;
80
+
81
+ index--;
82
+ /** the burst is over; the next edit starts its own step */
83
+ topKey = null;
84
+
85
+ return clone(stack[index]);
86
+ },
87
+
88
+ /**
89
+ * @returns {object|null} the layout to go forward to, or null at the end
90
+ */
91
+ redo() {
92
+ if (index >= stack.length - 1) return null;
93
+
94
+ index++;
95
+ topKey = null;
96
+
97
+ return clone(stack[index]);
98
+ },
99
+
100
+ get canUndo() { return index > 0; },
101
+ get canRedo() { return index < stack.length - 1; },
102
+
103
+ /** how many steps are held, for the specs to look at */
104
+ get length() { return stack.length; },
105
+
106
+ /** a different report is a different history, not a continuation */
107
+ reset(layout) {
108
+ stack = [clone(layout)];
109
+ index = 0;
110
+ topKey = null;
111
+ }
112
+ };
113
+ }