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
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Mohammed Shafick A
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,4 +1,363 @@
1
- **REPORT STUDIO**
2
-
3
- *description:* studio that helps to create report seamlessly.
4
-
1
+ # Report Studio
2
+
3
+ Design paginated reports in the browser, then render them inside your own app.
4
+
5
+ You draw the report once in a visual designer — headers, footers, groups,
6
+ tables, text — and it is saved as a plain JSON file. At runtime your app feeds
7
+ that layout its own data and gets back a page-by-page report viewer, with
8
+ navigation, zoom, search, print and CSV export.
9
+
10
+ No framework, no runtime dependencies. The renderer is plain DOM, so it works
11
+ in any project: plain JS, or React through the included components.
12
+
13
+ ## Installation
14
+
15
+ ```sh
16
+ npm install report-studio
17
+ ```
18
+
19
+ Requires Node 18.3 or newer for the designer command. The viewer itself runs in
20
+ the browser and needs nothing.
21
+
22
+ ## Designer setup
23
+
24
+ Start the designer from your project folder:
25
+
26
+ ```sh
27
+ npx report-studio design --dir ./reports
28
+ ```
29
+
30
+ `--dir` is the folder your reports are read from and saved to. It is created
31
+ for you if it does not exist. The command prints a URL and opens a browser
32
+ window on it.
33
+
34
+ Other options:
35
+
36
+ | Option | Default | What it does |
37
+ | --- | --- | --- |
38
+ | `--dir <path>` | `./reports` | where report files live |
39
+ | `--port <n>` | `5177` | port to listen on |
40
+ | `--host <addr>` | `127.0.0.1` | address to bind |
41
+ | `--tab` | — | open a normal browser tab instead of an app window |
42
+ | `--no-open` | — | do not open a browser at all |
43
+
44
+ Press `Ctrl+C` to stop it.
45
+
46
+ Saving a report called *Sales Summary* writes two files into `--dir`:
47
+
48
+ * `sales-summary.json` — the layout: page size, bands, fields, styles.
49
+ * `sales-summary.data.json` — sample data, so the designer has something to
50
+ preview with.
51
+
52
+ The sample file is written from the layout itself, so it covers everything the
53
+ report asks for: a key for every text placeholder, a row array for every table,
54
+ and the fields your totals are taken over. Read it as the answer to "what does
55
+ my app have to supply?" — it is the shape, filled in with placeholder values.
56
+
57
+ It is created the first time a report is saved. Later saves only *add* to it,
58
+ for anything the layout has asked for since: a new table's rows, a new
59
+ placeholder's key, a new image field. Values already in the file, including
60
+ real figures you have typed in, are never changed. Your app never reads this
61
+ file; it passes its own data to `buildPages`.
62
+
63
+ The designer is a design-time tool. It reads and writes files inside `--dir`
64
+ and nowhere else — keep it on localhost and do not run it in production.
65
+
66
+ ## Preview setup
67
+
68
+ Two files: an HTML page with one empty element, and a module that fills it.
69
+
70
+ **index.html**
71
+
72
+ ```html
73
+ <!DOCTYPE html>
74
+ <html lang="en">
75
+ <head>
76
+ <meta charset="UTF-8">
77
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
78
+ <title>Reports</title>
79
+
80
+ <!-- the viewer's stylesheet; the report's own styles are included in it -->
81
+ <link rel="stylesheet"
82
+ href="./node_modules/report-studio/src/preview/styles.css">
83
+
84
+ <!--
85
+ A browser resolves imports by URL and has no node_modules lookup, so the
86
+ bare name has to be mapped to a path. If you use a bundler (Vite,
87
+ webpack, …) it does this for you: drop the import map and the link
88
+ above, and import the stylesheet by name instead - see below.
89
+ -->
90
+ <script type="importmap">
91
+ {
92
+ "imports": {
93
+ "report-studio": "./node_modules/report-studio/dist/index.js"
94
+ }
95
+ }
96
+ </script>
97
+
98
+ <style>
99
+ html, body { height: 100%; margin: 0; }
100
+ </style>
101
+ </head>
102
+ <body>
103
+ <!-- one empty element; the viewer builds everything inside it -->
104
+ <div id="out" style="height: 100vh"></div>
105
+
106
+ <script type="module" src="./main.js"></script>
107
+ </body>
108
+ </html>
109
+ ```
110
+
111
+ **main.js**
112
+
113
+ ```js
114
+ import { buildPages, createViewer } from 'report-studio';
115
+
116
+ // the layout file the designer saved
117
+ const layout = await fetch('./reports/sales-summary.json').then(r => r.json());
118
+
119
+ // your data, keyed by dataset name. The designer shows you the shape it
120
+ // expects; sales-summary.data.json is an example of it.
121
+ const data = {
122
+ report: { period: 'June 2026', currency: 'USD' },
123
+ sales: [
124
+ { date: '2026-06-01', customer: 'Acme', region: 'North', amount: 250 },
125
+ { date: '2026-06-02', customer: 'Globex', region: 'South', amount: 500 }
126
+ ]
127
+ };
128
+
129
+ createViewer({
130
+ mount: '#out',
131
+ paginated: buildPages(layout, data),
132
+ title: layout.name
133
+ });
134
+ ```
135
+
136
+ That is the whole integration:
137
+
138
+ * `buildPages(layout, data)` turns the layout plus your data into a page list.
139
+ * `createViewer({ mount, paginated, title })` mounts the full report viewer
140
+ into the element you give it and returns a handle for paging, zoom, search,
141
+ print, export and `destroy()`.
142
+
143
+ To open the report in a window of its own instead of inside your page, use
144
+ `openViewerWindow({ paginated, title })` — same viewer, called from a click or
145
+ a keypress so the browser does not block the window.
146
+
147
+ ### Several tables
148
+
149
+ A report can hold any number of tables. Each one reads the dataset named in
150
+ its *Dataset* property, or the report's dataset if it names none, so each gets
151
+ its own array in your data:
152
+
153
+ ```js
154
+ buildPages(layout, {
155
+ orders: [ { item: 'Widget', qty: 2, amount: 50 } ],
156
+ refunds: [ { item: 'Gadget', qty: 1, amount: 20 } ]
157
+ });
158
+ ```
159
+
160
+ Tables in the same band are stacked, one under another. Each splits across
161
+ pages on its own, and a table below another moves down by however far the one
162
+ above really ran. Two tables side by side are refused, because they would print
163
+ one after the other rather than together.
164
+
165
+ Totals can name the dataset they add up:
166
+
167
+ | Placeholder | Means |
168
+ | --- | --- |
169
+ | `{sum(orders.amount)}` | `amount` summed over every row of `orders` |
170
+ | `{count(refunds)}` | the number of rows in `refunds` |
171
+ | `{sum(amount)}` | `amount` over the first table's rows, as before |
172
+
173
+ The named dataset does not need a table of its own. Any array in the data can
174
+ be totalled this way.
175
+
176
+ One table per report can be grouped. Set *Group by* on that table. A layout
177
+ with a report-wide *Group by* still groups its first table. The group header
178
+ and footer bands are shared, which is why only one table can use them.
179
+
180
+ For CSV, the viewer's export writes every table in the order they print. From
181
+ code, `toCSV(pages, { table: 'refunds' })` writes one table, and
182
+ `reportTables(pages)` lists the tables a report has.
183
+
184
+ ### Images
185
+
186
+ An image item can get its picture in two ways:
187
+
188
+ * **Stored in the layout.** In the designer, click *Upload* in the image's
189
+ properties. The picture is saved inside the layout JSON as a `data:` URI, so
190
+ keep it small: files over 200 KB show a warning and files over 1 MB are
191
+ refused. PNG, JPEG, GIF and WebP are accepted.
192
+ * **Read from your data.** Set *From data* to a path such as `company.logo`,
193
+ and supply that path's URL in the data you pass to `buildPages`:
194
+
195
+ ```js
196
+ buildPages(layout, {
197
+ company: { logo: 'https://cdn.example.com/acme.png' },
198
+ sales: [ /* ... */ ]
199
+ });
200
+ ```
201
+
202
+ If an image has both, the data wins, so a stored picture works as a default
203
+ that your data can replace per customer. *Fit* controls how the picture sits in
204
+ its box: `contain` (fit inside), `cover` (fill and crop) or `fill` (stretch).
205
+
206
+ Image URLs may be `http:`, `https:`, `blob:`, relative paths, or `data:` URIs
207
+ for PNG, JPEG, GIF, WebP, AVIF and BMP. Anything else, including `javascript:`
208
+ and SVG `data:` URIs, is not drawn. Remote images must be reachable from the
209
+ viewer's page. The viewer waits for images to finish loading before it prints.
210
+
211
+ ### With a bundler
212
+
213
+ Vite, webpack and the rest resolve bare names themselves, so there is no import
214
+ map and no path into `node_modules`. Import the stylesheet by name too:
215
+
216
+ ```js
217
+ import { buildPages, createViewer } from 'report-studio';
218
+ import 'report-studio/viewer.css';
219
+ ```
220
+
221
+ | Import | What it is |
222
+ | --- | --- |
223
+ | `report-studio` | the engine and the viewer |
224
+ | `report-studio/designer` | the designer, which most apps do not ship |
225
+ | `report-studio/viewer.css` | the viewer's styles, the report's included |
226
+ | `report-studio/designer.css` | the designer's styles, likewise |
227
+ | `report-studio/report.css` | the report alone, for drawing pages with no chrome |
228
+
229
+ ## React
230
+
231
+ React components are included. React itself is not bundled: install it
232
+ yourself (version 18 or newer). Apps that don't use React never load it.
233
+
234
+ ```jsx
235
+ import { ReportViewer } from 'report-studio/react';
236
+ import 'report-studio/viewer.css';
237
+
238
+ function SalesReport({ layout, sales }) {
239
+ return (
240
+ <ReportViewer
241
+ layout={layout}
242
+ data={{ report: { period: 'June 2026' }, sales }}
243
+ title={layout.name}
244
+ style={{ height: '100vh' }}
245
+ />
246
+ );
247
+ }
248
+ ```
249
+
250
+ * Pass `layout` and `data`, or `paginated` if you've already called
251
+ `buildPages`.
252
+ * Give the component a height. The viewer fills it and scrolls inside it.
253
+ * When `data` changes, the report is rebuilt and the reader stays on the same
254
+ page and zoom level. Passing the same objects again rebuilds nothing, so keep
255
+ `data` stable (state or `useMemo`) rather than building a new object on every
256
+ render.
257
+ * A layout or data the engine can't use throws a `ReportError` while
258
+ rendering. Wrap the component in an error boundary to show it.
259
+ * A `ref` gives you the viewer's controls: `next()`, `prev()`, `show(index)`,
260
+ `find(text)`, `print()`, `downloadCSV()`, `setZoom(n)`, `fitWidth()`, and
261
+ `page`, `pageCount` and `zoom`.
262
+
263
+ The designer is a separate import, like the plain-JS one:
264
+
265
+ ```jsx
266
+ import { ReportDesigner } from 'report-studio/react/designer';
267
+ import 'report-studio/designer.css';
268
+
269
+ // a new report: no layout, the designer starts blank
270
+ <ReportDesigner store={store} style={{ height: '100vh' }} />
271
+
272
+ // reopening a saved report: pass it, with its id so Save writes back to it
273
+ <ReportDesigner id="sales-summary" layout={savedLayout} store={store}
274
+ style={{ height: '100vh' }} />
275
+ ```
276
+
277
+ `layout` and `id` are optional. Leave both out for a new report, and Save asks
278
+ for a name the first time.
279
+
280
+ `layout` is only where the designer *starts*, like an input's `defaultValue`.
281
+ From then on the designer owns it, so edits, selection and undo history
282
+ survive your component re-rendering. `onChange` is called after every edit,
283
+ undo and redo. It receives the designer's own object, so clone it before
284
+ storing it. To open a different report, change `id` (or the component's
285
+ `key`). `store` works as described under *Designing inside your own app*.
286
+ `createDesigner` also takes the same `onChange` option.
287
+
288
+ ## Designing inside your own app
289
+
290
+ The command above is the usual way in, and it is a whole application. If you
291
+ would rather put the designer in a page of your own — an admin screen where
292
+ your users build their own reports — mount it the same way you mount the
293
+ viewer: one empty element, and it builds the rest inside it.
294
+
295
+ ```js
296
+ import { createDesigner } from 'report-studio/designer';
297
+ import 'report-studio/designer.css';
298
+
299
+ const designer = createDesigner({
300
+ mount: '#design',
301
+ layout, // a saved layout, or omit for a blank report
302
+ id: 'sales-summary', // its filename stem, if it has one
303
+ store // where Open and Save read and write; see below
304
+ });
305
+ ```
306
+
307
+ `store` is how the designer reaches your reports. Leave it out and it talks to
308
+ the dev server the CLI runs, which is what the bundled designer page does.
309
+ Supply your own to save through your API instead:
310
+
311
+ ```js
312
+ const api = '/api/reports';
313
+ const json = { 'content-type': 'application/json' };
314
+
315
+ const store = {
316
+ // required: Open, and Save
317
+ list: async () => fetch(api).then(r => r.json()),
318
+ load: async (id) => fetch(`${api}/${id}`).then(r => r.json()),
319
+ save: async (id, layout) => fetch(`${api}/${id}`,
320
+ { method: 'PUT', headers: json, body: JSON.stringify(layout) }),
321
+
322
+ // optional: the sample data the designer previews with. Without these two
323
+ // the preview falls back to data derived from the layout, which is a
324
+ // working designer - just one that never remembers your figures.
325
+ loadData: async (id) => fetch(`${api}/${id}/data`)
326
+ .then(r => (r.ok ? r.json() : null)),
327
+ saveData: async (id, data) => fetch(`${api}/${id}/data`,
328
+ { method: 'PUT', headers: json, body: JSON.stringify(data) }),
329
+
330
+ // optional: Delete, in the report picker
331
+ remove: async (id) => fetch(`${api}/${id}`, { method: 'DELETE' })
332
+ };
333
+ ```
334
+
335
+ `list` returns `{ id, name }` objects — the picker shows the name and opens the
336
+ id. `loadData` must resolve to `null`, not throw, when a report has no data
337
+ file yet: that is an ordinary state, not a failure.
338
+
339
+ `createDesigner` returns a handle with the current `layout`, `redraw()` and
340
+ `destroy()`. `openDesignerWindow(options)` opens the same designer in a window
341
+ of its own, for the same reason `openViewerWindow` does.
342
+
343
+ ## Reports in a project that already runs Vite
344
+
345
+ The CLI is the primary way in because it works for any project. If yours is
346
+ already a Vite one, the same read-and-write routes can be mounted in the dev
347
+ server you have:
348
+
349
+ ```js
350
+ import { defineConfig } from 'vite';
351
+ import { reportStudio } from 'report-studio/vite';
352
+
353
+ export default defineConfig({
354
+ plugins: [reportStudio({ dir: 'reports' })]
355
+ });
356
+ ```
357
+
358
+ Dev only, deliberately: it writes files, and mounting that in front of a
359
+ production build would be a hole rather than a feature.
360
+
361
+ ## Licence
362
+
363
+ MIT