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,231 @@
1
+ /**
2
+ * rulers.js is the arithmetic behind the rulers and the guides dragged off them.
3
+ *
4
+ * The alignment guides in guides.js answer "what is this level with?" while
5
+ * something is moving. A ruler answers a different question: where is 240, and
6
+ * can I have a line there. It is the tool for a layout that has to line up with
7
+ * something outside the report - a window in an envelope, a pre-printed form, a
8
+ * column the last six reports used - which nothing already on the page can be
9
+ * aligned to because it is not on the page.
10
+ *
11
+ * Guides live on the layout rather than in the designer's head, so they are
12
+ * saved with the report and come back with it: a column grid worked out once is
13
+ * not something to work out again on Monday. The engine has never read a key it
14
+ * was not looking for, and validate.js does not object to one, so they travel
15
+ * with the file and are ignored by everything that prints it.
16
+ *
17
+ * Coordinates are the printable area's: (0, 0) is inside the margins, which is
18
+ * where an item's own x and y are measured from and therefore what the numbers
19
+ * in the properties rail mean. A ruler that disagreed with the rail would be
20
+ * worse than no ruler.
21
+ */
22
+
23
+
24
+ /** the fine ticks, matching the 10px grid a drag already snaps to */
25
+ export const MINOR = 10;
26
+
27
+ /** and the ones that carry a number */
28
+ export const MAJOR = 50;
29
+
30
+ /**
31
+ * How near the pointer has to be to a guide to pick it up rather than the item
32
+ * under it. A guide is one pixel wide, which nobody can hit.
33
+ */
34
+ export const GRAB = 4;
35
+
36
+
37
+ /**
38
+ * The marks on a ruler of a given length.
39
+ *
40
+ * Both ends are included: the last tick is the edge of the printable area, and
41
+ * a ruler that stopped short of it would be saying the page does.
42
+ *
43
+ * @param {number} length in px
44
+ * @param {object} [options]
45
+ * @param {number} [options.minor] the fine spacing
46
+ * @param {number} [options.major] the labelled spacing; must be a multiple of minor
47
+ * @returns {{at: number, major: boolean}[]}
48
+ */
49
+ export function ticksFor(length, { minor = MINOR, major = MAJOR } = {}) {
50
+ const ticks = [];
51
+
52
+ if (!(length > 0) || !(minor > 0)) return ticks;
53
+
54
+ for (let at = 0; at <= length; at += minor) {
55
+ ticks.push({ at, major: at % major === 0 });
56
+ }
57
+
58
+ /** a length that is not a whole number of ticks still ends where it ends */
59
+ const last = ticks.at(-1);
60
+ if (last && last.at !== length) ticks.push({ at: length, major: true });
61
+
62
+ return ticks;
63
+ }
64
+
65
+
66
+ /**
67
+ * The guides a layout carries, always as two arrays.
68
+ *
69
+ * Read through here rather than off the object, because a layout written by
70
+ * hand - or saved before guides existed - has no `guides` key at all, and every
71
+ * caller having to remember that is how a designer ends up throwing on somebody
72
+ * else's file.
73
+ *
74
+ * @param {object} layout
75
+ * @returns {{x: number[], y: number[]}} sorted, and safe to read
76
+ */
77
+ export function guidesOf(layout) {
78
+ const found = layout?.guides;
79
+
80
+ /**
81
+ * Number(null) is 0, and so is Number('') - so what is not a number has to
82
+ * be dropped before the coercion, or a null in a hand-edited file becomes a
83
+ * guide down the left edge that nobody put there and nobody can explain.
84
+ */
85
+ const axis = (list) => (Array.isArray(list) ? list : [])
86
+ .filter(usable)
87
+ .map(Number)
88
+ .filter(Number.isFinite)
89
+ .sort((a, b) => a - b);
90
+
91
+ return { x: axis(found?.x), y: axis(found?.y) };
92
+ }
93
+
94
+
95
+ /** something that could be a position, as opposed to something Number() pities */
96
+ function usable(value) {
97
+ if (typeof value === 'number') return true;
98
+
99
+ return typeof value === 'string' && value.trim() !== '';
100
+ }
101
+
102
+
103
+ /** the layout's guides object, created on the layout if it has none yet */
104
+ function guideStore(layout) {
105
+ if (!layout.guides || typeof layout.guides !== 'object') {
106
+ layout.guides = { x: [], y: [] };
107
+ }
108
+
109
+ for (const axis of ['x', 'y']) {
110
+ if (!Array.isArray(layout.guides[axis])) layout.guides[axis] = [];
111
+ }
112
+
113
+ return layout.guides;
114
+ }
115
+
116
+
117
+ /**
118
+ * Puts a guide on an axis.
119
+ *
120
+ * Rounded to the pixel, because a guide dragged to 240.3 is a guide at 240 that
121
+ * nothing will ever quite line up with. Duplicates are dropped rather than
122
+ * stacked: two guides on one line are indistinguishable on screen and the
123
+ * second one can only be deleted by accident.
124
+ *
125
+ * @param {object} layout mutated in place, as the rest of structure.js does
126
+ * @param {'x'|'y'} axis
127
+ * @param {number} at
128
+ * @returns {number|null} where it landed, or null if it was not a usable number
129
+ */
130
+ export function addGuide(layout, axis, at) {
131
+ if (!usable(at)) return null;
132
+
133
+ const value = Math.round(Number(at));
134
+ if (!Number.isFinite(value)) return null;
135
+
136
+ const store = guideStore(layout);
137
+
138
+ if (!store[axis].includes(value)) {
139
+ store[axis].push(value);
140
+ store[axis].sort((a, b) => a - b);
141
+ }
142
+
143
+ return value;
144
+ }
145
+
146
+
147
+ /**
148
+ * Takes one off.
149
+ *
150
+ * @param {object} layout
151
+ * @param {'x'|'y'} axis
152
+ * @param {number} at the guide's current position
153
+ * @returns {boolean} whether there was one there
154
+ */
155
+ export function removeGuide(layout, axis, at) {
156
+ const store = guideStore(layout);
157
+ const index = store[axis].indexOf(Math.round(Number(at)));
158
+
159
+ if (index === -1) return false;
160
+
161
+ store[axis].splice(index, 1);
162
+ return true;
163
+ }
164
+
165
+
166
+ /**
167
+ * Moves one, which is a remove and an add - so a guide dragged onto another
168
+ * merges with it rather than hiding it.
169
+ *
170
+ * @param {object} layout
171
+ * @param {'x'|'y'} axis
172
+ * @param {number} from
173
+ * @param {number} to
174
+ * @returns {number|null} where it ended up
175
+ */
176
+ export function moveGuide(layout, axis, from, to) {
177
+ removeGuide(layout, axis, from);
178
+ return addGuide(layout, axis, to);
179
+ }
180
+
181
+
182
+ /**
183
+ * The guide nearest a point on an axis, if one is close enough to have been
184
+ * meant. What makes a guide draggable at all: it is one pixel wide.
185
+ *
186
+ * @param {object} layout
187
+ * @param {'x'|'y'} axis
188
+ * @param {number} at
189
+ * @param {number} [within]
190
+ * @returns {number|null} the guide's position
191
+ */
192
+ export function guideNear(layout, axis, at, within = GRAB) {
193
+ let best = null;
194
+
195
+ for (const guide of guidesOf(layout)[axis]) {
196
+ const distance = Math.abs(guide - at);
197
+
198
+ if (distance <= within && (best === null || distance < Math.abs(best - at))) {
199
+ best = guide;
200
+ }
201
+ }
202
+
203
+ return best;
204
+ }
205
+
206
+
207
+ /**
208
+ * The guides that apply inside one band, in that band's own coordinates.
209
+ *
210
+ * A vertical guide needs no conversion - a band's x origin is the printable
211
+ * area's. A horizontal one does: the same guide is a different `y` in every
212
+ * band, which is the whole reason bands hold their items in their own
213
+ * coordinates in the first place.
214
+ *
215
+ * @param {object} layout
216
+ * @param {{originY: number, h: number}} band from canvas.bandBox
217
+ * @returns {{x: number[], y: number[]}}
218
+ */
219
+ export function guidesInBand(layout, band) {
220
+ const all = guidesOf(layout);
221
+
222
+ if (!band) return { x: all.x, y: [] };
223
+
224
+ return {
225
+ x: all.x,
226
+ /** only the ones that actually cross this band; the rest are elsewhere */
227
+ y: all.y
228
+ .map(at => at - (band.originY ?? 0))
229
+ .filter(at => at >= 0 && at <= (band.h ?? 0))
230
+ };
231
+ }
@@ -0,0 +1,240 @@
1
+ /**
2
+ * sample-data.js works out what data a report is asking for, and writes a
3
+ * payload of the right shape to fill in.
4
+ *
5
+ * A layout is a set of questions - `{customer.name}`, a column on `amount`,
6
+ * grouping by `region` - and until now the only way to learn what they were was
7
+ * to run the report and read the "unresolved placeholder" warnings. This reads
8
+ * them off the layout instead and hands back a `.data.json` with every key in
9
+ * place, so the host application knows exactly what it has to supply.
10
+ *
11
+ * The rules for what comes from the data are imported from resolve.js rather
12
+ * than restated. A second copy of them here would drift, and it would drift in
13
+ * the direction of asking the user for `{page}` while forgetting
14
+ * `{customer.name}` - the two mistakes that make such a file worse than none.
15
+ *
16
+ * Which scope a bare `{name}` belongs to follows the engine (spec 3.4): a
17
+ * dotted path is always the root, and a bare key is a row field inside a
18
+ * row-scoped band and a root key anywhere else.
19
+ */
20
+
21
+ import { PLACEHOLDER, isEngineKey, isRowScoped } from '../engine/resolve.js';
22
+
23
+
24
+ /** enough rows to show a group break, few enough to read at a glance */
25
+ const ROWS = 6;
26
+ const GROUPS = ['North', 'South'];
27
+
28
+ /** field names that plainly want a number rather than a word */
29
+ const NUMERIC = /(amount|amt|price|qty|quantity|total|subtotal|cost|rate|balance|discount|tax)$/i;
30
+
31
+ /** an aggregate expression, for the fields the layout takes a sum of */
32
+ const AGGREGATE = /\{\s*(\w+)\(([^)]*)\)\s*\}/g;
33
+
34
+ /** and ones that want a date */
35
+ const DATEISH = /(date|day|when)$/i;
36
+
37
+
38
+ /**
39
+ * Every placeholder key a layout asks the data for, with the scope it is read in.
40
+ *
41
+ * @param {object} layout
42
+ * @returns {{root: string[], row: string[]}} paths, de-duplicated
43
+ */
44
+ export function requiredKeys(layout) {
45
+ const root = new Set();
46
+ const row = new Set();
47
+
48
+ for (const band of (Array.isArray(layout?.bands) ? layout.bands : [])) {
49
+ const rowScoped = isRowScoped(band.type);
50
+
51
+ for (const item of (band.items || [])) {
52
+ if (item.type !== 'text' || typeof item.value !== 'string') continue;
53
+
54
+ for (const [, raw] of item.value.matchAll(PLACEHOLDER)) {
55
+ const key = raw.trim();
56
+
57
+ /** answered by the engine, not by the payload */
58
+ if (!key || isEngineKey(key)) continue;
59
+
60
+ /**
61
+ * A dotted path is read from the root wherever it appears -
62
+ * `{customer.name}` in a detail band is still the customer, not
63
+ * a column called "customer.name".
64
+ */
65
+ if (key.includes('.') || !rowScoped) root.add(key);
66
+ else row.add(key);
67
+ }
68
+ }
69
+ }
70
+
71
+ return { root: [...root], row: [...row] };
72
+ }
73
+
74
+
75
+ /**
76
+ * The dataset key rows are read from, and the fields each row needs.
77
+ *
78
+ * A table names its own dataset and falls back to the report's (spec 3.3), so a
79
+ * layout with two tables over two datasets produces two arrays.
80
+ *
81
+ * @param {object} layout
82
+ * @returns {Map<string, Set<string>>} dataset name to its fields
83
+ */
84
+ export function datasets(layout) {
85
+ const found = new Map();
86
+ const fallback = layout?.dataset || 'rows';
87
+
88
+ const fieldsOf = (name) => {
89
+ if (!found.has(name)) found.set(name, new Set());
90
+ return found.get(name);
91
+ };
92
+
93
+ for (const band of (Array.isArray(layout?.bands) ? layout.bands : [])) {
94
+ for (const item of (band.items || [])) {
95
+ if (item.type !== 'table') continue;
96
+
97
+ const fields = fieldsOf(item.dataset || fallback);
98
+ for (const column of (item.columns || [])) {
99
+ if (column?.field) fields.add(column.field);
100
+ }
101
+ }
102
+ }
103
+
104
+ /**
105
+ * A report can group and place row placeholders without ever drawing a
106
+ * table, so the fallback dataset is created if anything needs rows at all.
107
+ */
108
+ const { row } = requiredKeys(layout);
109
+
110
+ if (row.length || layout?.groupBy) {
111
+ const fields = fieldsOf(fallback);
112
+
113
+ for (const key of row) fields.add(key);
114
+ if (layout?.groupBy) fields.add(layout.groupBy);
115
+ }
116
+
117
+ return found;
118
+ }
119
+
120
+
121
+ /**
122
+ * A sample payload for a layout.
123
+ *
124
+ * Values are chosen from the field's own name - a column called `amount` gets a
125
+ * number and one called `date` gets a date - because a payload of `"string"`
126
+ * everywhere tells you the shape but not whether you have the right column, and
127
+ * a report full of the word "string" is not worth previewing.
128
+ *
129
+ * @param {object} layout
130
+ * @returns {object} a data payload, ready to fill in
131
+ */
132
+ export function sampleData(layout) {
133
+ const data = {};
134
+ const { root } = requiredKeys(layout);
135
+ const summed = summedFields(layout);
136
+
137
+ for (const path of root) place(data, path);
138
+
139
+ for (const [name, fields] of datasets(layout)) {
140
+ data[name] = rowsFor([...fields], layout?.groupBy, summed);
141
+ }
142
+
143
+ return data;
144
+ }
145
+
146
+
147
+ /**
148
+ * The fields the layout takes an aggregate over.
149
+ *
150
+ * A field called `amt` is not one the name heuristic recognises, so it used to
151
+ * get the word "Amt 1" - and `{sum(amt)}` over six words is not a number, so
152
+ * the total the report was designed around previewed blank. The layout has
153
+ * already said what it is: you do not sum a word. That is a better answer than
154
+ * a longer list of names, because it is the report's own.
155
+ *
156
+ * `count()` is left out on purpose - it takes no field, and the empty string it
157
+ * would contribute is not one.
158
+ *
159
+ * @param {object} layout
160
+ * @returns {Set<string>}
161
+ */
162
+ export function summedFields(layout) {
163
+ const found = new Set();
164
+
165
+ for (const band of (Array.isArray(layout?.bands) ? layout.bands : [])) {
166
+ for (const item of (band.items || [])) {
167
+ if (item.type !== 'text') continue;
168
+
169
+ for (const [, , field] of String(item.value ?? '').matchAll(AGGREGATE)) {
170
+ if (field.trim()) found.add(field.trim());
171
+ }
172
+ }
173
+ }
174
+
175
+ return found;
176
+ }
177
+
178
+
179
+ /** writes a value at a dotted path, building the objects on the way down */
180
+ function place(data, path) {
181
+ const parts = path.split('.').filter(Boolean);
182
+ if (!parts.length) return;
183
+
184
+ const last = parts.pop();
185
+ let node = data;
186
+
187
+ for (const part of parts) {
188
+ if (node[part] == null || typeof node[part] !== 'object') node[part] = {};
189
+ node = node[part];
190
+ }
191
+
192
+ if (node[last] === undefined) node[last] = valueFor(last, 0);
193
+ }
194
+
195
+
196
+ function rowsFor(fields, groupBy, summed = new Set()) {
197
+ if (!fields.length) return [];
198
+
199
+ return Array.from({ length: ROWS }, (_, index) => {
200
+ const row = {};
201
+
202
+ for (const field of fields) {
203
+ /**
204
+ * The grouping field repeats, or every row is its own group and the
205
+ * sample shows nothing about how grouping looks.
206
+ */
207
+ row[field] = field === groupBy
208
+ ? GROUPS[index % GROUPS.length]
209
+ : valueFor(field, index, summed.has(field));
210
+ }
211
+
212
+ return row;
213
+ });
214
+ }
215
+
216
+
217
+ function valueFor(field, index, summed = false) {
218
+ if (summed || NUMERIC.test(field)) return (index + 1) * 250;
219
+
220
+ if (DATEISH.test(field)) {
221
+ /** fixed, not today's: a sample file that changes every read diffs badly */
222
+ const day = String((index % 28) + 1).padStart(2, '0');
223
+ return `2026-06-${day}`;
224
+ }
225
+
226
+ /** the field's own name, so a mis-mapped column is obvious on the page */
227
+ return `${label(field)} ${index + 1}`;
228
+ }
229
+
230
+
231
+ /** "customerName" and "customer_name" both read back as "Customer name" */
232
+ function label(field) {
233
+ const words = String(field)
234
+ .replace(/[_-]+/g, ' ')
235
+ .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
236
+ .trim()
237
+ .toLowerCase();
238
+
239
+ return words.charAt(0).toUpperCase() + words.slice(1);
240
+ }