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.
- package/LICENSE +21 -0
- package/README.md +238 -4
- package/dist/designer.js +3209 -0
- package/dist/index.js +2 -4
- package/dist/viewer-D-c0lKzQ.js +1576 -0
- package/package.json +66 -33
- package/src/asset/images/icon.png +0 -0
- package/src/asset/images/logo.png +0 -0
- package/src/cli/index.js +282 -0
- package/src/cli/serve.js +135 -0
- package/src/designer/blank.js +53 -0
- package/src/designer/canvas.js +518 -0
- package/src/designer/designer.js +1900 -0
- package/src/designer/dialog.js +708 -0
- package/src/designer/fields.js +584 -0
- package/src/designer/geometry.js +154 -0
- package/src/designer/guides.js +370 -0
- package/src/designer/history.js +113 -0
- package/src/designer/icons.js +118 -0
- package/src/designer/index.html +28 -0
- package/src/designer/main.js +39 -0
- package/src/designer/menu.js +126 -0
- package/src/designer/panel.js +478 -0
- package/src/designer/preview.js +95 -0
- package/src/designer/rulers.js +231 -0
- package/src/designer/sample-data.js +240 -0
- package/src/designer/select.js +699 -0
- package/src/designer/structure.js +604 -0
- package/src/designer/styles.css +1616 -0
- package/src/designer/toast.js +62 -0
- package/src/designer/tokens.js +284 -0
- package/src/engine/csv.js +315 -0
- package/src/engine/group.js +304 -0
- package/src/engine/index.js +34 -0
- package/src/engine/measure.js +390 -0
- package/src/engine/paginate.js +861 -0
- package/src/engine/regions.js +175 -0
- package/src/engine/resolve.js +171 -0
- package/src/engine/search.js +129 -0
- package/src/engine/text-metrics.js +206 -0
- package/src/engine/validate.js +328 -0
- package/src/index.html +79 -0
- package/src/index.js +50 -0
- package/src/preview/chrome.css +505 -0
- package/src/preview/chrome.js +147 -0
- package/src/preview/index.html +28 -0
- package/src/preview/main.js +66 -0
- package/src/preview/styles.css +16 -0
- package/src/preview/viewer.js +745 -0
- package/src/render/items.js +425 -0
- package/src/render/render.js +98 -0
- package/src/render/report.css +202 -0
- package/src/server/routes.js +331 -0
- package/src/shared/brand.css +29 -0
- package/src/shared/dropdown.css +136 -0
- package/src/shared/dropdown.js +166 -0
- package/src/shared/modal.css +125 -0
- package/src/shared/prefix.js +13 -0
- package/src/shared/store.js +145 -0
- package/src/shared/theme.css +72 -0
- package/src/shared/window.js +138 -0
- package/src/vite/index.js +53 -0
- package/dist/react.js +0 -4
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,238 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
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.
|
|
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 only written the first time a report is saved. Once you have put real
|
|
58
|
+
figures in it, later saves leave it alone. Your app never reads this file; it
|
|
59
|
+
passes its own data to `buildPages`.
|
|
60
|
+
|
|
61
|
+
The designer is a design-time tool. It reads and writes files inside `--dir`
|
|
62
|
+
and nowhere else — keep it on localhost and do not run it in production.
|
|
63
|
+
|
|
64
|
+
## Preview setup
|
|
65
|
+
|
|
66
|
+
Two files: an HTML page with one empty element, and a module that fills it.
|
|
67
|
+
|
|
68
|
+
**index.html**
|
|
69
|
+
|
|
70
|
+
```html
|
|
71
|
+
<!DOCTYPE html>
|
|
72
|
+
<html lang="en">
|
|
73
|
+
<head>
|
|
74
|
+
<meta charset="UTF-8">
|
|
75
|
+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
76
|
+
<title>Reports</title>
|
|
77
|
+
|
|
78
|
+
<!-- the viewer's stylesheet; the report's own styles are included in it -->
|
|
79
|
+
<link rel="stylesheet"
|
|
80
|
+
href="./node_modules/report-studio/src/preview/styles.css">
|
|
81
|
+
|
|
82
|
+
<!--
|
|
83
|
+
A browser resolves imports by URL and has no node_modules lookup, so the
|
|
84
|
+
bare name has to be mapped to a path. If you use a bundler (Vite,
|
|
85
|
+
webpack, …) it does this for you: drop the import map and the link
|
|
86
|
+
above, and import the stylesheet by name instead - see below.
|
|
87
|
+
-->
|
|
88
|
+
<script type="importmap">
|
|
89
|
+
{
|
|
90
|
+
"imports": {
|
|
91
|
+
"report-studio": "./node_modules/report-studio/dist/index.js"
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
</script>
|
|
95
|
+
|
|
96
|
+
<style>
|
|
97
|
+
html, body { height: 100%; margin: 0; }
|
|
98
|
+
</style>
|
|
99
|
+
</head>
|
|
100
|
+
<body>
|
|
101
|
+
<!-- one empty element; the viewer builds everything inside it -->
|
|
102
|
+
<div id="out" style="height: 100vh"></div>
|
|
103
|
+
|
|
104
|
+
<script type="module" src="./main.js"></script>
|
|
105
|
+
</body>
|
|
106
|
+
</html>
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
**main.js**
|
|
110
|
+
|
|
111
|
+
```js
|
|
112
|
+
import { buildPages, createViewer } from 'report-studio';
|
|
113
|
+
|
|
114
|
+
// the layout file the designer saved
|
|
115
|
+
const layout = await fetch('./reports/sales-summary.json').then(r => r.json());
|
|
116
|
+
|
|
117
|
+
// your data, keyed by dataset name. The designer shows you the shape it
|
|
118
|
+
// expects; sales-summary.data.json is an example of it.
|
|
119
|
+
const data = {
|
|
120
|
+
report: { period: 'June 2026', currency: 'USD' },
|
|
121
|
+
sales: [
|
|
122
|
+
{ date: '2026-06-01', customer: 'Acme', region: 'North', amount: 250 },
|
|
123
|
+
{ date: '2026-06-02', customer: 'Globex', region: 'South', amount: 500 }
|
|
124
|
+
]
|
|
125
|
+
};
|
|
126
|
+
|
|
127
|
+
createViewer({
|
|
128
|
+
mount: '#out',
|
|
129
|
+
paginated: buildPages(layout, data),
|
|
130
|
+
title: layout.name
|
|
131
|
+
});
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
That is the whole integration:
|
|
135
|
+
|
|
136
|
+
* `buildPages(layout, data)` turns the layout plus your data into a page list.
|
|
137
|
+
* `createViewer({ mount, paginated, title })` mounts the full report viewer
|
|
138
|
+
into the element you give it and returns a handle for paging, zoom, search,
|
|
139
|
+
print, export and `destroy()`.
|
|
140
|
+
|
|
141
|
+
To open the report in a window of its own instead of inside your page, use
|
|
142
|
+
`openViewerWindow({ paginated, title })` — same viewer, called from a click or
|
|
143
|
+
a keypress so the browser does not block the window.
|
|
144
|
+
|
|
145
|
+
### With a bundler
|
|
146
|
+
|
|
147
|
+
Vite, webpack and the rest resolve bare names themselves, so there is no import
|
|
148
|
+
map and no path into `node_modules`. Import the stylesheet by name too:
|
|
149
|
+
|
|
150
|
+
```js
|
|
151
|
+
import { buildPages, createViewer } from 'report-studio';
|
|
152
|
+
import 'report-studio/viewer.css';
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
| Import | What it is |
|
|
156
|
+
| --- | --- |
|
|
157
|
+
| `report-studio` | the engine and the viewer |
|
|
158
|
+
| `report-studio/designer` | the designer, which most apps do not ship |
|
|
159
|
+
| `report-studio/viewer.css` | the viewer's styles, the report's included |
|
|
160
|
+
| `report-studio/designer.css` | the designer's styles, likewise |
|
|
161
|
+
| `report-studio/report.css` | the report alone, for drawing pages with no chrome |
|
|
162
|
+
|
|
163
|
+
## Designing inside your own app
|
|
164
|
+
|
|
165
|
+
The command above is the usual way in, and it is a whole application. If you
|
|
166
|
+
would rather put the designer in a page of your own — an admin screen where
|
|
167
|
+
your users build their own reports — mount it the same way you mount the
|
|
168
|
+
viewer: one empty element, and it builds the rest inside it.
|
|
169
|
+
|
|
170
|
+
```js
|
|
171
|
+
import { createDesigner } from 'report-studio/designer';
|
|
172
|
+
import 'report-studio/designer.css';
|
|
173
|
+
|
|
174
|
+
const designer = createDesigner({
|
|
175
|
+
mount: '#design',
|
|
176
|
+
layout, // a saved layout, or omit for a blank report
|
|
177
|
+
id: 'sales-summary', // its filename stem, if it has one
|
|
178
|
+
store // where Open and Save read and write; see below
|
|
179
|
+
});
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
`store` is how the designer reaches your reports. Leave it out and it talks to
|
|
183
|
+
the dev server the CLI runs, which is what the bundled designer page does.
|
|
184
|
+
Supply your own to save through your API instead:
|
|
185
|
+
|
|
186
|
+
```js
|
|
187
|
+
const api = '/api/reports';
|
|
188
|
+
const json = { 'content-type': 'application/json' };
|
|
189
|
+
|
|
190
|
+
const store = {
|
|
191
|
+
// required: Open, and Save
|
|
192
|
+
list: async () => fetch(api).then(r => r.json()),
|
|
193
|
+
load: async (id) => fetch(`${api}/${id}`).then(r => r.json()),
|
|
194
|
+
save: async (id, layout) => fetch(`${api}/${id}`,
|
|
195
|
+
{ method: 'PUT', headers: json, body: JSON.stringify(layout) }),
|
|
196
|
+
|
|
197
|
+
// optional: the sample data the designer previews with. Without these two
|
|
198
|
+
// the preview falls back to data derived from the layout, which is a
|
|
199
|
+
// working designer - just one that never remembers your figures.
|
|
200
|
+
loadData: async (id) => fetch(`${api}/${id}/data`)
|
|
201
|
+
.then(r => (r.ok ? r.json() : null)),
|
|
202
|
+
saveData: async (id, data) => fetch(`${api}/${id}/data`,
|
|
203
|
+
{ method: 'PUT', headers: json, body: JSON.stringify(data) }),
|
|
204
|
+
|
|
205
|
+
// optional: Delete, in the report picker
|
|
206
|
+
remove: async (id) => fetch(`${api}/${id}`, { method: 'DELETE' })
|
|
207
|
+
};
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
`list` returns `{ id, name }` objects — the picker shows the name and opens the
|
|
211
|
+
id. `loadData` must resolve to `null`, not throw, when a report has no data
|
|
212
|
+
file yet: that is an ordinary state, not a failure.
|
|
213
|
+
|
|
214
|
+
`createDesigner` returns a handle with the current `layout`, `redraw()` and
|
|
215
|
+
`destroy()`. `openDesignerWindow(options)` opens the same designer in a window
|
|
216
|
+
of its own, for the same reason `openViewerWindow` does.
|
|
217
|
+
|
|
218
|
+
## Reports in a project that already runs Vite
|
|
219
|
+
|
|
220
|
+
The CLI is the primary way in because it works for any project. If yours is
|
|
221
|
+
already a Vite one, the same read-and-write routes can be mounted in the dev
|
|
222
|
+
server you have:
|
|
223
|
+
|
|
224
|
+
```js
|
|
225
|
+
import { defineConfig } from 'vite';
|
|
226
|
+
import { reportStudio } from 'report-studio/vite';
|
|
227
|
+
|
|
228
|
+
export default defineConfig({
|
|
229
|
+
plugins: [reportStudio({ dir: 'reports' })]
|
|
230
|
+
});
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
Dev only, deliberately: it writes files, and mounting that in front of a
|
|
234
|
+
production build would be a hole rather than a feature.
|
|
235
|
+
|
|
236
|
+
## Licence
|
|
237
|
+
|
|
238
|
+
MIT
|