report-studio 1.0.0 → 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 (47) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +129 -4
  3. package/dist/designer-qy59eEux.js +3416 -0
  4. package/dist/designer.js +2 -3209
  5. package/dist/index.js +2 -2
  6. package/dist/react-designer.js +41 -0
  7. package/dist/react.js +60 -0
  8. package/dist/{viewer-D-c0lKzQ.js → viewer-xa17tyMJ.js} +682 -537
  9. package/package.json +80 -66
  10. package/src/cli/serve.js +135 -135
  11. package/src/designer/designer.js +2054 -1900
  12. package/src/designer/dialog.js +708 -708
  13. package/src/designer/fields.js +51 -2
  14. package/src/designer/icons.js +5 -0
  15. package/src/designer/index.html +28 -28
  16. package/src/designer/main.js +39 -39
  17. package/src/designer/menu.js +2 -2
  18. package/src/designer/panel.js +21 -1
  19. package/src/designer/sample-data.js +180 -9
  20. package/src/designer/structure.js +87 -6
  21. package/src/designer/styles.css +1654 -1616
  22. package/src/designer/tokens.js +9 -0
  23. package/src/engine/csv.js +350 -315
  24. package/src/engine/group.js +128 -65
  25. package/src/engine/index.js +35 -34
  26. package/src/engine/measure.js +13 -12
  27. package/src/engine/paginate.js +8 -4
  28. package/src/engine/resolve.js +37 -0
  29. package/src/engine/tables.js +87 -0
  30. package/src/engine/validate.js +97 -22
  31. package/src/index.html +79 -79
  32. package/src/index.js +51 -50
  33. package/src/preview/chrome.css +505 -505
  34. package/src/preview/chrome.js +147 -147
  35. package/src/preview/index.html +28 -28
  36. package/src/preview/viewer.js +763 -745
  37. package/src/react/designer.js +87 -0
  38. package/src/react/index.js +117 -0
  39. package/src/render/items.js +94 -1
  40. package/src/render/report.css +30 -0
  41. package/src/server/routes.js +331 -331
  42. package/src/shared/brand.css +29 -29
  43. package/src/shared/dropdown.css +136 -136
  44. package/src/shared/modal.css +125 -125
  45. package/src/shared/store.js +145 -145
  46. package/src/shared/theme.css +72 -72
  47. package/src/shared/window.js +138 -138
@@ -0,0 +1,87 @@
1
+ /**
2
+ * report-studio/react/designer - the designer as a React component.
3
+ *
4
+ * The same kind of wrapper as the viewer's: one element, and createDesigner
5
+ * mounted into it in an effect.
6
+ *
7
+ * The designer owns the layout while it is open. Every edit, undo and redo is
8
+ * made to its own copy, so the `layout` prop is where it *starts* - like an
9
+ * input's defaultValue - and `onChange` is how the host hears where it has got
10
+ * to. Remounting on every change would throw away the selection, the history
11
+ * and whatever the user was typing. To open a different report, change `id`
12
+ * (or the component's `key`), which is a different report and a fresh designer.
13
+ */
14
+
15
+ import {
16
+ createElement, forwardRef, useEffect, useImperativeHandle, useRef
17
+ } from 'react';
18
+ import { createDesigner } from '../designer/designer.js';
19
+
20
+
21
+ /**
22
+ * The report designer.
23
+ *
24
+ * Import `report-studio/designer.css` once, and give the component a height.
25
+ *
26
+ * @param {object} props
27
+ * @param {object} [props.layout] the report to start from; absent starts a blank one
28
+ * @param {string} [props.id] the report's filename stem. Changing it opens a
29
+ * fresh designer on whatever `layout` is then
30
+ * @param {object} [props.store] where Open and Save read and write - see the
31
+ * README; the dev server's routes when absent
32
+ * @param {boolean} [props.guardUnload=true] ask before a tab with unsaved
33
+ * changes closes. Read once, when the designer mounts
34
+ * @param {(layout: object) => void} [props.onChange] the layout after every
35
+ * edit. The designer's own object: clone it before keeping it
36
+ * @param {string} [props.className]
37
+ * @param {object} [props.style]
38
+ * @param {object} ref receives the designer's handle: layout, redraw,
39
+ * togglePreview, select and the rest createDesigner returns
40
+ */
41
+ export const ReportDesigner = forwardRef(function ReportDesigner(
42
+ { layout, id = null, store, guardUnload = true, onChange, className, style }, ref
43
+ ) {
44
+ const element = useRef(null);
45
+ const designer = useRef(null);
46
+
47
+ /**
48
+ * The latest of the props read at mount, so a host passing a new arrow
49
+ * function every render - which is most of them - gets its current callback
50
+ * called, without the designer being torn down to pick it up.
51
+ */
52
+ const latest = useRef({ layout, store, guardUnload, onChange });
53
+ latest.current = { layout, store, guardUnload, onChange };
54
+
55
+ useEffect(() => {
56
+ if (!element.current) return undefined;
57
+
58
+ const mounted = createDesigner({
59
+ mount: element.current,
60
+ layout: latest.current.layout,
61
+ id,
62
+ store: latest.current.store,
63
+ guardUnload: latest.current.guardUnload,
64
+ onChange: (next) => latest.current.onChange?.(next)
65
+ });
66
+
67
+ designer.current = mounted;
68
+
69
+ return () => {
70
+ mounted.destroy();
71
+ if (designer.current === mounted) designer.current = null;
72
+ };
73
+ }, [id]);
74
+
75
+ /** forwards to whichever designer is mounted, like the viewer's ref */
76
+ useImperativeHandle(ref, () => new Proxy({}, {
77
+ get(_, name) {
78
+ const current = designer.current;
79
+ if (!current) return undefined;
80
+
81
+ const value = current[name];
82
+ return typeof value === 'function' ? value.bind(current) : value;
83
+ }
84
+ }), []);
85
+
86
+ return createElement('div', { ref: element, className, style });
87
+ });
@@ -0,0 +1,117 @@
1
+ /**
2
+ * report-studio/react - the viewer as a React component.
3
+ *
4
+ * A wrapper and nothing more. The viewer is plain DOM and builds everything
5
+ * inside one element, so the component renders that element and hands it to
6
+ * createViewer in an effect - the same two steps a plain-JS host takes. None of
7
+ * the engine or the viewer knows React is here, which is what keeps the rest of
8
+ * the package usable without it (see framework-free.test.js).
9
+ *
10
+ * Written with createElement rather than JSX, so the package ships as it is
11
+ * built and asks no JSX transform of the host.
12
+ *
13
+ * The designer is a separate entry, `report-studio/react/designer`, for the
14
+ * reason the core package gives: most applications ship reports, not the tool
15
+ * that drew them.
16
+ */
17
+
18
+ import {
19
+ createElement, forwardRef, useEffect, useImperativeHandle, useMemo, useRef
20
+ } from 'react';
21
+ import { buildPages } from '../engine/index.js';
22
+ import { createViewer } from '../preview/viewer.js';
23
+
24
+
25
+ /** the viewer's methods, forwarded from the ref to whichever viewer is mounted */
26
+ const VIEWER_METHODS = [
27
+ 'show', 'next', 'prev', 'find', 'print', 'downloadCSV',
28
+ 'openExport', 'closeExport', 'confirmExport',
29
+ 'setZoom', 'zoomIn', 'zoomOut', 'fitWidth'
30
+ ];
31
+
32
+
33
+ /**
34
+ * The report viewer: paging, zoom, search, print and CSV.
35
+ *
36
+ * Give it a layout and data, or pages already built with buildPages. New data
37
+ * builds new pages and remounts the viewer inside the same element, keeping the
38
+ * page and the zoom the reader was on - a report refreshed under someone should
39
+ * not throw them back to page one at 100%.
40
+ *
41
+ * A layout or data the engine cannot use throws while rendering, as a ReportError,
42
+ * so an error boundary around the component is where a host shows it.
43
+ *
44
+ * Import `report-studio/viewer.css` once, and give the component a height: the
45
+ * viewer fills its element and scrolls inside it.
46
+ *
47
+ * @param {object} props
48
+ * @param {object} [props.layout] a layout the designer saved
49
+ * @param {object} [props.data] the data for it, keyed by dataset name
50
+ * @param {object} [props.paginated] a buildPages result, in place of layout and data
51
+ * @param {string} [props.title] shown in the viewer's toolbar
52
+ * @param {string} [props.className]
53
+ * @param {object} [props.style]
54
+ * @param {object} ref receives the viewer's controls: show, next, prev, find,
55
+ * print, downloadCSV, setZoom, zoomIn, zoomOut, fitWidth, and page, pageCount
56
+ * and zoom
57
+ */
58
+ export const ReportViewer = forwardRef(function ReportViewer(
59
+ { layout, data, paginated, title, className, style }, ref
60
+ ) {
61
+ const element = useRef(null);
62
+ const viewer = useRef(null);
63
+
64
+ /** where the reader was, carried across a remount */
65
+ const place = useRef(null);
66
+
67
+ /**
68
+ * Built during render rather than in the effect, so a layout the engine
69
+ * refuses throws where an error boundary can catch it. Memoised on the
70
+ * objects themselves: a host that passes the same layout and data gets the
71
+ * same pages, and nothing is rebuilt.
72
+ */
73
+ const pages = useMemo(
74
+ () => paginated ?? (layout ? buildPages(layout, data ?? {}) : null),
75
+ [paginated, layout, data]
76
+ );
77
+
78
+ useEffect(() => {
79
+ if (!pages || !element.current) return undefined;
80
+
81
+ const mounted = createViewer({ mount: element.current, paginated: pages, title });
82
+ viewer.current = mounted;
83
+
84
+ const was = place.current;
85
+ if (was) {
86
+ mounted.setZoom(was.zoom);
87
+ mounted.show(Math.min(was.page, mounted.pageCount) - 1);
88
+ }
89
+
90
+ return () => {
91
+ place.current = { page: mounted.page, zoom: mounted.zoom };
92
+ mounted.destroy();
93
+ if (viewer.current === mounted) viewer.current = null;
94
+ };
95
+ }, [pages, title]);
96
+
97
+ /**
98
+ * One object for the life of the component, forwarding to whichever viewer
99
+ * is mounted now - so a host that kept the ref across a data refresh is not
100
+ * left holding a destroyed viewer.
101
+ */
102
+ useImperativeHandle(ref, () => {
103
+ const handle = {
104
+ get page() { return viewer.current?.page ?? 0; },
105
+ get pageCount() { return viewer.current?.pageCount ?? 0; },
106
+ get zoom() { return viewer.current?.zoom ?? 1; }
107
+ };
108
+
109
+ for (const name of VIEWER_METHODS) {
110
+ handle[name] = (...args) => viewer.current?.[name]?.(...args);
111
+ }
112
+
113
+ return handle;
114
+ }, []);
115
+
116
+ return createElement('div', { ref: element, className, style });
117
+ });
@@ -1,5 +1,6 @@
1
1
  /**
2
- * items.js draws the things that live inside a band: text boxes and tables.
2
+ * items.js draws the things that live inside a band: text boxes, tables,
3
+ * rules, boxes and images.
3
4
  *
4
5
  * Split out of render.js because the designer canvas needs exactly this and
5
6
  * nothing more. The preview wraps these in anchored, paginated bands; the
@@ -106,6 +107,8 @@ export function items(list) {
106
107
  return line(i)
107
108
  case "box":
108
109
  return box(i)
110
+ case "image":
111
+ return image(i)
109
112
  default:
110
113
  console.warn(`Unknown item type "${i?.type}"; it is not drawn.`);
111
114
  return '';
@@ -176,6 +179,96 @@ function box(i) {
176
179
  }
177
180
 
178
181
 
182
+ /** how a picture may be fitted to its box; anything else is `contain` */
183
+ const IMAGE_FITS = ['contain', 'cover', 'fill'];
184
+
185
+ /**
186
+ * The raster formats a `data:` URI may carry.
187
+ *
188
+ * SVG is left out on purpose. As an <img> it cannot run script, but it is also
189
+ * the one image format that is a document, and a layout or a payload is a file
190
+ * an application may let its own users write - "save image as" and "open in
191
+ * new tab" both turn it back into a page that can.
192
+ */
193
+ const DATA_IMAGE = /^data:image\/(png|jpe?g|gif|webp|avif|bmp);base64,[a-z0-9+/=\s]*$/i;
194
+
195
+ /** the schemes an image may be fetched from, besides a data: URI and a relative path */
196
+ const IMAGE_SCHEMES = ['http:', 'https:', 'blob:'];
197
+
198
+
199
+ /**
200
+ * An image URL, or '' when it is not one a report should load.
201
+ *
202
+ * The picture's address comes from the layout or from the host's data, and it
203
+ * ends up in a `src` attribute - so `javascript:` and its relatives are refused
204
+ * here, once, for every route to the page. `esc` still runs over what is
205
+ * returned; this decides *whether* to load it, not how to write it down.
206
+ *
207
+ * Whitespace and control characters are stripped before the scheme is read,
208
+ * because a browser does the same: "java\tscript:" is `javascript:` to it.
209
+ *
210
+ * @param {*} value
211
+ * @returns {string}
212
+ */
213
+ export function imageSrc(value) {
214
+ if (typeof value !== 'string') return '';
215
+
216
+ const url = value.trim();
217
+ if (url === '') return '';
218
+
219
+ /** read for its scheme only - a space in the middle of a path is the path's */
220
+ const bare = url.replace(/[\u0000-\u0020\u007f]+/g, '');
221
+
222
+ if (/^data:/i.test(bare)) return DATA_IMAGE.test(bare) ? bare : '';
223
+
224
+ /** a scheme is letters up to the first colon, before any / ? or # */
225
+ const scheme = bare.match(/^([a-z][a-z0-9+.-]*:)/i)?.[1]?.toLowerCase();
226
+
227
+ if (scheme == null) return url;
228
+
229
+ return IMAGE_SCHEMES.includes(scheme) ? url : '';
230
+ }
231
+
232
+
233
+ /**
234
+ * A picture, scaled into a fixed box.
235
+ *
236
+ * The box is the item and the <img> fills it, so `w` and `h` mean what they
237
+ * mean for every other item and `fit` decides how the picture sits inside -
238
+ * letterboxed, cropped, or stretched. The engine paginated against `h`, and an
239
+ * image that grew to its natural size would undo that.
240
+ *
241
+ * Three states, told apart by `resolvedSrc`, which only the engine writes:
242
+ * a picture - drawn
243
+ * engine, no picture - an empty frame; the report prints nothing there
244
+ * designer canvas - a placeholder naming the field it will be read from,
245
+ * since a frame with nothing in it cannot be found again
246
+ */
247
+ function image(i) {
248
+ const built = Object.prototype.hasOwnProperty.call(i, 'resolvedSrc');
249
+ const src = imageSrc(built ? i.resolvedSrc : i.src);
250
+ const fit = IMAGE_FITS.includes(i.fit) ? i.fit : 'contain';
251
+
252
+ let inner = '';
253
+
254
+ if (src) {
255
+ inner = `<img src="${esc(src)}" alt="${esc(i.alt ?? '')}" ` +
256
+ `style="object-fit:${fit}" draggable="false">`;
257
+ } else if (!built) {
258
+ const field = typeof i.field === 'string' ? i.field.trim() : '';
259
+ inner = `<span class="image-empty">${field ? esc(`{${field}}`) : 'Image'}</span>`;
260
+ }
261
+
262
+ return `
263
+ <div id="${esc(i.id)}" class="image" style="
264
+ width:${px(i.w)}px;
265
+ height:${px(i.h)}px;
266
+ ${position(i)}
267
+ " data-item-id="${esc(i.id)}" data-item-type="image">${inner}</div>
268
+ `
269
+ }
270
+
271
+
179
272
  /**
180
273
  * The pen a line is drawn with, as one CSS border shorthand.
181
274
  *
@@ -162,6 +162,36 @@
162
162
  box-sizing: border-box;
163
163
  }
164
164
 
165
+ /* the box is the item; the picture is scaled into it and never resizes it */
166
+ .page .image {
167
+ position: absolute;
168
+ overflow: hidden;
169
+ }
170
+
171
+ .page .image img {
172
+ display: block;
173
+ width: 100%;
174
+ height: 100%;
175
+ }
176
+
177
+ /* an image with no picture yet, on the designer canvas only - a built report
178
+ prints an empty frame instead */
179
+ .page .image-empty {
180
+ display: flex;
181
+ align-items: center;
182
+ justify-content: center;
183
+ box-sizing: border-box;
184
+ width: 100%;
185
+ height: 100%;
186
+ padding: 4px;
187
+ overflow: hidden;
188
+ border: 1px dashed #9aa0a6;
189
+ color: #6b7280;
190
+ font: 11px/1.2 Helvetica, Arial, sans-serif;
191
+ text-align: center;
192
+ word-break: break-all;
193
+ }
194
+
165
195
  /**
166
196
  * A line is a box with a rule down the middle of it, not a rule that is the box:
167
197
  * see items.js. The box is what the designer can grab and what the engine