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,328 @@
1
+ /**
2
+ * validate.js checks a layout file before the engine walks it.
3
+ *
4
+ * Spec 6.1 chose a hand-written validator over a schema library specifically to
5
+ * get errors that name the band and item at fault. A malformed layout should
6
+ * say so here, not surface as a TypeError three stages downstream.
7
+ */
8
+
9
+
10
+ const BAND_TYPES = [
11
+ 'reportHeader',
12
+ 'pageHeader',
13
+ 'groupHeader',
14
+ 'detail',
15
+ 'groupFooter',
16
+ 'reportFooter',
17
+ 'pageFooter'
18
+ ];
19
+
20
+ const ITEM_TYPES = ['text', 'table', 'line', 'box'];
21
+
22
+ /** spec 3.3: a line runs along one axis; which one is the item's to say */
23
+ const LINE_ORIENTATIONS = ['horizontal', 'vertical'];
24
+
25
+ /** the four CSS border styles that read as a rule rather than a box */
26
+ const LINE_STYLES = ['solid', 'dashed', 'dotted', 'double'];
27
+
28
+ /** a table's grid may also be turned off, which a line cannot be */
29
+ const RULE_STYLES = [...LINE_STYLES, 'none'];
30
+
31
+
32
+ /** Thrown for a layout the engine cannot work with. */
33
+ export class ReportError extends Error {
34
+ constructor(message, issues = []) {
35
+ super(issues.length ? `${message}\n - ${issues.join('\n - ')}` : message);
36
+ this.name = 'ReportError';
37
+ this.issues = issues;
38
+ }
39
+ }
40
+
41
+
42
+ /**
43
+ * Collects everything wrong with a layout, rather than stopping at the first
44
+ * problem - a designer fixing five typos wants all five named at once.
45
+ * @param {*} json
46
+ * @returns {string[]} human-readable issues, empty when the layout is usable
47
+ */
48
+ export function validateLayout(json) {
49
+ const issues = [];
50
+
51
+ if (json == null || typeof json !== 'object' || Array.isArray(json)) {
52
+ return ['layout must be an object'];
53
+ }
54
+
55
+ validatePage(json.page, issues);
56
+
57
+ if (!Array.isArray(json.bands)) {
58
+ issues.push('layout.bands must be an array');
59
+ return issues;
60
+ }
61
+
62
+ if (json.bands.length === 0) {
63
+ issues.push('layout.bands is empty - there is nothing to render');
64
+ }
65
+
66
+ if (json.groupBy != null && typeof json.groupBy !== 'string') {
67
+ issues.push('layout.groupBy must be a field name or null');
68
+ }
69
+
70
+ const seenTypes = new Set();
71
+
72
+ json.bands.forEach((band, i) => {
73
+ const where = `bands[${i}]`;
74
+
75
+ if (band == null || typeof band !== 'object') {
76
+ issues.push(`${where} must be an object`);
77
+ return;
78
+ }
79
+
80
+ if (!BAND_TYPES.includes(band.type)) {
81
+ issues.push(`${where}.type "${band.type}" is not one of: ${BAND_TYPES.join(', ')}`);
82
+ } else if (seenTypes.has(band.type)) {
83
+ issues.push(`${where}.type "${band.type}" appears more than once; the engine places one band of each type`);
84
+ } else {
85
+ seenTypes.add(band.type);
86
+ }
87
+
88
+ if (!Array.isArray(band.items)) {
89
+ issues.push(`${where}.items must be an array`);
90
+ return;
91
+ }
92
+
93
+ band.items.forEach((item, j) =>
94
+ validateItem(item, `${where}.items[${j}]`, issues));
95
+ });
96
+
97
+ if (json.groupBy != null && !seenTypes.has('groupHeader') && !seenTypes.has('groupFooter')) {
98
+ issues.push('layout.groupBy is set but there is no groupHeader or groupFooter band to show it');
99
+ }
100
+
101
+ validateOneTable(json.bands, issues);
102
+
103
+ return issues;
104
+ }
105
+
106
+
107
+ /**
108
+ * One table per report, for now.
109
+ *
110
+ * group.js binds the dataset to the first table it finds and stops, so a second
111
+ * one renders its header and no rows - and nothing anywhere said so. The
112
+ * designer drew sample rows in both, the validator passed it, and the fault
113
+ * only showed up in the printed report.
114
+ *
115
+ * Refused rather than warned about, because the alternative is a report that
116
+ * quietly leaves data out. Binding a table each is a real feature and a bigger
117
+ * change than a guard: it needs a dataset per table through group.js, more than
118
+ * one splittable item per band in paginate.js, and an answer for what a CSV
119
+ * export of two tables means. Until then this is the honest boundary, and it is
120
+ * one function to delete when that lands.
121
+ *
122
+ * @param {object[]} bands
123
+ * @param {string[]} issues
124
+ */
125
+ function validateOneTable(bands, issues) {
126
+ const tables = [];
127
+
128
+ for (const band of bands) {
129
+ if (!Array.isArray(band?.items)) continue;
130
+
131
+ for (const item of band.items) {
132
+ if (item?.type === 'table') tables.push(item.id ?? '(unnamed)');
133
+ }
134
+ }
135
+
136
+ if (tables.length > 1) {
137
+ issues.push(
138
+ `layout has ${tables.length} tables (${tables.map(id => `"${id}"`).join(', ')}); ` +
139
+ `a report binds one - the rest would print their header and no rows`);
140
+ }
141
+ }
142
+
143
+
144
+ function validatePage(page, issues) {
145
+ if (page == null || typeof page !== 'object') {
146
+ issues.push('layout.page must be an object with width, height and margin');
147
+ return;
148
+ }
149
+
150
+ for (const key of ['width', 'height']) {
151
+ if (!(typeof page[key] === 'number' && page[key] > 0)) {
152
+ issues.push(`layout.page.${key} must be a positive number`);
153
+ }
154
+ }
155
+
156
+ if (page.margin == null || typeof page.margin !== 'object') {
157
+ issues.push('layout.page.margin must be an object with top, right, bottom and left');
158
+ return;
159
+ }
160
+
161
+ for (const side of ['top', 'right', 'bottom', 'left']) {
162
+ if (!(typeof page.margin[side] === 'number' && page.margin[side] >= 0)) {
163
+ issues.push(`layout.page.margin.${side} must be a number of pixels`);
164
+ }
165
+ }
166
+
167
+ const printable = page.height - (page.margin.top + page.margin.bottom);
168
+ if (printable <= 0) {
169
+ issues.push(`layout.page margins leave no printable height (${printable}px)`);
170
+ }
171
+ }
172
+
173
+
174
+ function validateItem(item, where, issues) {
175
+ if (item == null || typeof item !== 'object') {
176
+ issues.push(`${where} must be an object`);
177
+ return;
178
+ }
179
+
180
+ if (!ITEM_TYPES.includes(item.type)) {
181
+ issues.push(`${where}.type "${item.type}" is not one of: ${ITEM_TYPES.join(', ')}`);
182
+ return;
183
+ }
184
+
185
+ if (typeof item.id !== 'string' || item.id === '') {
186
+ issues.push(`${where}.id must be a non-empty string`);
187
+ }
188
+
189
+ if (item.type === 'text') {
190
+ if (typeof item.value !== 'string') {
191
+ issues.push(`${where}.value must be a string`);
192
+ }
193
+ return;
194
+ }
195
+
196
+ if (item.type === 'line') {
197
+ validateLine(item, where, issues);
198
+ return;
199
+ }
200
+
201
+ if (item.type === 'box') {
202
+ validateBox(item, where, issues);
203
+ return;
204
+ }
205
+
206
+ /** table */
207
+ if (!(typeof item.rowHeight === 'number' && item.rowHeight > 0)) {
208
+ issues.push(`${where}.rowHeight must be a positive number`);
209
+ }
210
+
211
+ if (item.style?.borderStyle != null
212
+ && !RULE_STYLES.includes(item.style.borderStyle)) {
213
+ issues.push(
214
+ `${where}.style.borderStyle "${item.style.borderStyle}" is not one of: ` +
215
+ RULE_STYLES.join(', '));
216
+ }
217
+
218
+ if (item.style?.borderWidth != null
219
+ && !(typeof item.style.borderWidth === 'number' && item.style.borderWidth > 0)) {
220
+ issues.push(`${where}.style.borderWidth must be a positive number of pixels`);
221
+ }
222
+
223
+ if (!Array.isArray(item.columns) || item.columns.length === 0) {
224
+ issues.push(`${where}.columns must be a non-empty array`);
225
+ return;
226
+ }
227
+
228
+ item.columns.forEach((col, k) => {
229
+ if (col == null || typeof col.field !== 'string' || col.field === '') {
230
+ issues.push(`${where}.columns[${k}].field must be a non-empty string`);
231
+ }
232
+ });
233
+ }
234
+
235
+
236
+ /**
237
+ * A box carries no content either - it is a rule bent round four sides - so what
238
+ * there is to check is the pen and the corner. Everything is optional: a bare
239
+ * `{type: "box"}` is a hairline rectangle, which is what a box usually is.
240
+ */
241
+ function validateBox(item, where, issues) {
242
+ const style = item.style;
243
+ if (style == null) return;
244
+
245
+ if (typeof style !== 'object' || Array.isArray(style)) {
246
+ issues.push(`${where}.style must be an object`);
247
+ return;
248
+ }
249
+
250
+ if (style.borderStyle != null && !RULE_STYLES.includes(style.borderStyle)) {
251
+ issues.push(
252
+ `${where}.style.borderStyle "${style.borderStyle}" is not one of: ` +
253
+ RULE_STYLES.join(', '));
254
+ }
255
+
256
+ for (const key of ['borderWidth', 'radius']) {
257
+ const value = style[key];
258
+
259
+ /** a radius of nothing is a square corner, so zero is allowed there */
260
+ const floor = key === 'radius' ? 0 : 1;
261
+
262
+ if (value != null && !(typeof value === 'number' && value >= floor)) {
263
+ issues.push(
264
+ `${where}.style.${key} must be a number of pixels` +
265
+ (floor ? ' greater than zero' : ' of zero or more'));
266
+ }
267
+ }
268
+ }
269
+
270
+
271
+ /**
272
+ * A line carries no content, so what there is to get wrong is its direction and
273
+ * its pen. Both are optional in the file - a bare `{type: "line"}` draws a
274
+ * hairline rule, which is what a line usually is - and only a value that is
275
+ * present and wrong is reported.
276
+ */
277
+ function validateLine(item, where, issues) {
278
+ if (item.orientation != null
279
+ && !LINE_ORIENTATIONS.includes(item.orientation)) {
280
+ issues.push(
281
+ `${where}.orientation "${item.orientation}" is not one of: ` +
282
+ LINE_ORIENTATIONS.join(', '));
283
+ }
284
+
285
+ const style = item.style;
286
+ if (style == null) return;
287
+
288
+ if (typeof style !== 'object' || Array.isArray(style)) {
289
+ issues.push(`${where}.style must be an object`);
290
+ return;
291
+ }
292
+
293
+ if (style.thickness != null
294
+ && !(typeof style.thickness === 'number' && style.thickness > 0)) {
295
+ issues.push(`${where}.style.thickness must be a positive number of pixels`);
296
+ }
297
+
298
+ if (style.lineStyle != null && !LINE_STYLES.includes(style.lineStyle)) {
299
+ issues.push(
300
+ `${where}.style.lineStyle "${style.lineStyle}" is not one of: ` +
301
+ LINE_STYLES.join(', '));
302
+ }
303
+ }
304
+
305
+
306
+ /**
307
+ * Throws unless the layout is usable.
308
+ * @param {*} json
309
+ * @param {string} stage the engine stage asking, so the message says who refused
310
+ */
311
+ export function assertLayout(json, stage) {
312
+ const issues = validateLayout(json);
313
+ if (issues.length) {
314
+ throw new ReportError(`${stage}: the layout file is not usable`, issues);
315
+ }
316
+ }
317
+
318
+
319
+ /**
320
+ * The data payload is the host application's, so it gets the same treatment.
321
+ * @param {*} data
322
+ * @param {string} stage
323
+ */
324
+ export function assertData(data, stage) {
325
+ if (data == null || typeof data !== 'object' || Array.isArray(data)) {
326
+ throw new ReportError(`${stage}: data must be an object keyed by dataset name`);
327
+ }
328
+ }
package/src/index.html ADDED
@@ -0,0 +1,79 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+
4
+ <head>
5
+ <meta charset="UTF-8">
6
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
7
+ <title>Report Studio</title>
8
+ <link rel="icon" type="image/png" href="./asset/images/icon.png">
9
+ <link rel="stylesheet" href="./shared/theme.css">
10
+ <link rel="preconnect" href="https://fonts.googleapis.com">
11
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
12
+ <link
13
+ href="https://fonts.googleapis.com/css2?family=Courier+Prime:ital,wght@0,400;0,700&family=Instrument+Sans:ital,wght@0,400..700&display=swap"
14
+ rel="stylesheet">
15
+ <style>
16
+ body {
17
+ min-height: 100vh;
18
+ display: grid;
19
+ place-content: center;
20
+ gap: 20px;
21
+ background: var(--backdrop);
22
+ font-family: "Instrument Sans", system-ui, sans-serif;
23
+ color: var(--ink);
24
+ }
25
+
26
+ /* the wordmark stands in for the heading; the text stays for readers */
27
+ h1 {
28
+ height: 26px;
29
+ width: calc(26px * var(--brand-logo-ratio));
30
+
31
+ background-image: var(--brand-logo);
32
+ background-repeat: no-repeat;
33
+ background-position: left center;
34
+ background-size: contain;
35
+
36
+ text-indent: -9999px;
37
+ overflow: hidden;
38
+ white-space: nowrap;
39
+ }
40
+
41
+ p {
42
+ color: var(--ink-soft);
43
+ font-size: 13px;
44
+ max-width: 40ch;
45
+ }
46
+
47
+ nav {
48
+ display: flex;
49
+ gap: 12px;
50
+ }
51
+
52
+ a {
53
+ padding: 10px 18px;
54
+ background: var(--surface);
55
+ border: 1px solid var(--border);
56
+ border-radius: 6px;
57
+ color: var(--ink);
58
+ text-decoration: none;
59
+ font-size: 14px;
60
+ }
61
+
62
+ a:hover {
63
+ border-color: var(--accent);
64
+ background: var(--accent-soft);
65
+ }
66
+ </style>
67
+ </head>
68
+
69
+ <body>
70
+ <h1>Report Studio</h1>
71
+ <p>The development playground. Both screens run straight from
72
+ <code>src/</code> with no build step.</p>
73
+ <nav>
74
+ <a href="./designer/">Designer</a>
75
+ <a href="./preview/">Preview</a>
76
+ </nav>
77
+ </body>
78
+
79
+ </html>
package/src/index.js ADDED
@@ -0,0 +1,50 @@
1
+ /**
2
+ * report-studio - the package's main entry point.
3
+ *
4
+ * The engine and the viewer, and nothing that touches the document on import -
5
+ * so an application that only builds pages, or only renders them on a server,
6
+ * pays for nothing it does not use.
7
+ *
8
+ * The designer is a separate entry (`report-studio/designer`) because it is the
9
+ * larger half and most applications ship the reports rather than the tool that
10
+ * drew them. Each screen has a stylesheet of its own to link beside it:
11
+ * `report-studio/viewer.css` and `report-studio/designer.css`, or
12
+ * `report-studio/report.css` alone to draw a report with no chrome at all.
13
+ */
14
+
15
+ export {
16
+ buildPages,
17
+ resolve,
18
+ group,
19
+ measure,
20
+ paginate,
21
+ validateLayout,
22
+ ReportError,
23
+ search,
24
+ searchPages,
25
+ toCSV,
26
+ toReportCSV,
27
+ reportFilename,
28
+ measureText,
29
+ wrapLines,
30
+ textHeight,
31
+ LINE_HEIGHT_RATIO
32
+ } from './engine/index.js';
33
+
34
+ export { render } from './render/render.js';
35
+
36
+ /**
37
+ * The viewer: paging, zoom, search, print and CSV over a page list.
38
+ *
39
+ * It takes one empty element and builds the rest, the same way createDesigner
40
+ * does. Link `report-studio/viewer.css` beside it - the report's own stylesheet
41
+ * is included there, so that one file is enough.
42
+ */
43
+ export { createViewer, openViewerWindow } from './preview/viewer.js';
44
+
45
+ /**
46
+ * Opens a blank window with the host's stylesheets in it, ready to be mounted
47
+ * into - for a host that wants a screen of its own without using one of the
48
+ * two helpers above.
49
+ */
50
+ export { openWindow } from './shared/window.js';