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/package.json CHANGED
@@ -1,33 +1,80 @@
1
1
  {
2
2
  "name": "report-studio",
3
- "version": "0.0.1",
4
- "description": "Design and view reports",
5
- "main": "index.js",
6
- "directories": {
7
- "doc": "docs"
3
+ "version": "1.1.0",
4
+ "description": "Design and preview paginated reports in the browser. Zero runtime dependencies; optional React components.",
5
+ "repository": {
6
+ "type": "git",
7
+ "url": "git+https://github.com/Shafickbinameer/report-studio.git"
8
8
  },
9
- "scripts": {
10
- "dev": "vite",
11
- "build": "vite build",
12
- "test": "vitest"
13
- },
14
- "keywords": [],
15
- "author": "",
9
+ "keywords": [
10
+ "report",
11
+ "designer",
12
+ "pagination",
13
+ "pdf",
14
+ "print",
15
+ "layout",
16
+ "react"
17
+ ],
18
+ "author": "Mohammed Shafick <shafickbinameer@gmail.com>",
16
19
  "license": "MIT",
17
20
  "type": "module",
18
21
  "files": [
19
- "dist"
22
+ "dist",
23
+ "src/asset",
24
+ "src/cli",
25
+ "src/designer",
26
+ "src/engine",
27
+ "src/preview",
28
+ "src/react",
29
+ "src/render",
30
+ "src/server",
31
+ "src/shared",
32
+ "src/vite",
33
+ "src/index.html",
34
+ "src/index.js"
20
35
  ],
21
36
  "exports": {
22
37
  ".": "./dist/index.js",
23
- "./react": "./dist/react.js"
38
+ "./designer": "./dist/designer.js",
39
+ "./react": "./dist/react.js",
40
+ "./react/designer": "./dist/react-designer.js",
41
+ "./vite": "./src/vite/index.js",
42
+ "./report.css": "./src/render/report.css",
43
+ "./viewer.css": "./src/preview/styles.css",
44
+ "./designer.css": "./src/designer/styles.css",
45
+ "./package.json": "./package.json"
24
46
  },
47
+ "scripts": {
48
+ "dev": "vite",
49
+ "design": "node src/cli/index.js design --dir reports",
50
+ "build": "vite build",
51
+ "test": "vitest run",
52
+ "test:watch": "vitest",
53
+ "prepublishOnly": "npm run test && npm run build"
54
+ },
55
+ "bugs": {
56
+ "url": "https://report-studio-docs.vercel.app/report.html"
57
+ },
58
+ "homepage": "https://report-studio-docs.vercel.app",
25
59
  "peerDependencies": {
26
- "react": ">=18",
27
- "react-dom": ">=18"
60
+ "react": ">=18"
61
+ },
62
+ "peerDependenciesMeta": {
63
+ "react": {
64
+ "optional": true
65
+ }
28
66
  },
29
67
  "devDependencies": {
30
- "@vitejs/plugin-react": "^6.0.4",
31
- "vite": "^8.1.5"
68
+ "jsdom": "^29.1.1",
69
+ "react": "^19.3.0",
70
+ "react-dom": "^19.3.0",
71
+ "vite": "^8.1.5",
72
+ "vitest": "^4.1.11"
73
+ },
74
+ "bin": {
75
+ "report-studio": "./src/cli/index.js"
76
+ },
77
+ "engines": {
78
+ "node": ">=18.3"
32
79
  }
33
80
  }
Binary file
Binary file
@@ -0,0 +1,282 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * The `report-studio` command.
4
+ *
5
+ * npx report-studio design --dir ./reports
6
+ *
7
+ * Argument parsing is node:util's parseArgs, which has been built in since
8
+ * 18.3 - the package has no runtime dependencies and a flag parser is not the
9
+ * thing to break that for. Opening the browser is spawned rather than taken
10
+ * from a package for the same reason, and it fails quietly: the URL is printed
11
+ * either way, which is the part that matters.
12
+ */
13
+
14
+ import { parseArgs } from 'node:util';
15
+ import { spawn } from 'node:child_process';
16
+ import { existsSync, realpathSync } from 'node:fs';
17
+ import { join } from 'node:path';
18
+ import { pathToFileURL } from 'node:url';
19
+ import { serve } from './serve.js';
20
+
21
+
22
+ const USAGE = `
23
+ report-studio - design reports in the browser
24
+
25
+ Usage
26
+ report-studio design [options]
27
+
28
+ Options
29
+ --dir <path> where report files live (default: ./reports)
30
+ --port <n> port to listen on (default: 5177)
31
+ --host <addr> address to bind (default: 127.0.0.1)
32
+ --tab open in a browser tab rather than a window of its own
33
+ --no-open do not open a browser
34
+ --help show this
35
+
36
+ The server reads and writes JSON files in --dir and nothing outside it. It is
37
+ a design-time tool: bind it to localhost, and do not run it in production.
38
+ `;
39
+
40
+
41
+ export async function main(argv = process.argv.slice(2)) {
42
+ let parsed;
43
+
44
+ try {
45
+ parsed = parseArgs({
46
+ args: argv,
47
+ allowPositionals: true,
48
+ options: {
49
+ dir: { type: 'string', default: 'reports' },
50
+ port: { type: 'string', default: '5177' },
51
+ host: { type: 'string', default: '127.0.0.1' },
52
+ open: { type: 'boolean', default: true },
53
+ /**
54
+ * Declared rather than relying on parseArgs negating `open`:
55
+ * `allowNegative` only arrived in Node 22.4, and this package
56
+ * says it runs on 18.3. Without it, `--no-open` is an unknown
57
+ * option and the command refuses to start at all.
58
+ */
59
+ 'no-open': { type: 'boolean', default: false },
60
+ tab: { type: 'boolean', default: false },
61
+ help: { type: 'boolean', default: false }
62
+ }
63
+ });
64
+ } catch (error) {
65
+ process.stderr.write(`${error.message}\n${USAGE}`);
66
+ return 1;
67
+ }
68
+
69
+ const { values, positionals } = parsed;
70
+ const command = positionals[0] ?? 'design';
71
+
72
+ if (values.help || command === 'help') {
73
+ process.stdout.write(USAGE);
74
+ return 0;
75
+ }
76
+
77
+ if (command !== 'design') {
78
+ process.stderr.write(`unknown command "${command}"\n${USAGE}`);
79
+ return 1;
80
+ }
81
+
82
+ const port = Number(values.port);
83
+
84
+ if (!Number.isInteger(port) || port < 0 || port > 65535) {
85
+ process.stderr.write(`--port must be a port number, not "${values.port}"\n`);
86
+ return 1;
87
+ }
88
+
89
+ let started;
90
+
91
+ try {
92
+ started = await serve({ dir: values.dir, port, host: values.host });
93
+ } catch (error) {
94
+ const hint = error.code === 'EADDRINUSE'
95
+ ? `port ${port} is already in use - try --port ${port + 1}`
96
+ : error.message;
97
+
98
+ process.stderr.write(`could not start: ${hint}\n`);
99
+ return 1;
100
+ }
101
+
102
+ process.stdout.write(
103
+ `\n report-studio\n` +
104
+ ` designer ${started.url}\n` +
105
+ ` reports ${values.dir}\n\n` +
106
+ ` Ctrl+C to stop.\n\n`
107
+ );
108
+
109
+ if (values.open && !values['no-open']) {
110
+ openBrowser(started.url, { tab: values.tab });
111
+ }
112
+
113
+ return new Promise(resolve => {
114
+ const stop = () => started.close().then(() => resolve(0));
115
+
116
+ process.once('SIGINT', stop);
117
+ process.once('SIGTERM', stop);
118
+ });
119
+ }
120
+
121
+
122
+ /** what an A4 page and the designer's chrome need, on a laptop screen */
123
+ const WINDOW_SIZE = '1400,900';
124
+
125
+
126
+ /**
127
+ * Where a Chromium-based browser is likely to be, per platform.
128
+ *
129
+ * Looked for by path rather than asked of the shell: `start chrome` succeeds
130
+ * whether or not Chrome is there - it hands off to the shell and returns - so
131
+ * there would be no way to tell that the app window never opened and fall back.
132
+ *
133
+ * @returns {Array<{command: string, args: string[]}>} candidates, best first
134
+ */
135
+ function appWindowCandidates(url) {
136
+ const flags = [`--app=${url}`, `--window-size=${WINDOW_SIZE}`];
137
+
138
+ if (process.platform === 'darwin') {
139
+ return [
140
+ { command: 'open', args: ['-na', 'Google Chrome', '--args', ...flags] },
141
+ { command: 'open', args: ['-na', 'Microsoft Edge', '--args', ...flags] }
142
+ ];
143
+ }
144
+
145
+ if (process.platform === 'win32') {
146
+ const roots = [
147
+ process.env['PROGRAMFILES'],
148
+ process.env['PROGRAMFILES(X86)'],
149
+ process.env['LOCALAPPDATA']
150
+ ].filter(Boolean);
151
+
152
+ const exes = [
153
+ ['Google', 'Chrome', 'Application', 'chrome.exe'],
154
+ ['Microsoft', 'Edge', 'Application', 'msedge.exe'],
155
+ ['BraveSoftware', 'Brave-Browser', 'Application', 'brave.exe']
156
+ ];
157
+
158
+ return roots
159
+ .flatMap(root => exes.map(parts => join(root, ...parts)))
160
+ .filter(existsSync)
161
+ .map(command => ({ command, args: flags }));
162
+ }
163
+
164
+ return ['google-chrome', 'chromium', 'chromium-browser', 'microsoft-edge']
165
+ .map(command => ({ command, args: flags }));
166
+ }
167
+
168
+
169
+ /**
170
+ * Opens the designer.
171
+ *
172
+ * In a window of its own where a Chromium-based browser can be found: the
173
+ * designer is a full screen with its own bar and rail, and a tab strip and an
174
+ * address bar above it are chrome about a page that has none of its own. Any
175
+ * browser at all is better than none, though, so a tab is the fallback rather
176
+ * than a failure - and the URL has been printed either way.
177
+ *
178
+ * Best effort throughout, and silent: a browser that will not open is not a
179
+ * reason to fail the command.
180
+ *
181
+ * @param {string} url
182
+ * @param {object} [options]
183
+ * @param {boolean} [options.tab] ask for a tab rather than a window
184
+ */
185
+ function openBrowser(url, { tab = false } = {}) {
186
+ launch(browserLaunch(url, { tab }));
187
+ }
188
+
189
+
190
+ /**
191
+ * Every way of opening the designer that is worth trying, best first.
192
+ *
193
+ * Separated from the spawning so that what is tried, and in what order, can be
194
+ * specified without launching a browser at every assertion.
195
+ *
196
+ * @param {string} url
197
+ * @param {object} [options]
198
+ * @param {boolean} [options.tab] skip the app windows and go straight to a tab
199
+ * @returns {Array<{command: string, args: string[]}>} always at least the fallback
200
+ */
201
+ export function browserLaunch(url, { tab = false } = {}) {
202
+ /** the plain "open this with whatever is registered" of each platform */
203
+ const fallback = process.platform === 'win32'
204
+ ? { command: 'cmd', args: ['/c', 'start', '', url] }
205
+ : process.platform === 'darwin'
206
+ ? { command: 'open', args: [url] }
207
+ : { command: 'xdg-open', args: [url] };
208
+
209
+ return tab ? [fallback] : [...appWindowCandidates(url), fallback];
210
+ }
211
+
212
+
213
+ /**
214
+ * Tries each way of opening a browser until one does not fail immediately.
215
+ *
216
+ * A missing binary shows up as an `error` event rather than a throw, so the
217
+ * next candidate is tried from there. Nothing waits on the browser itself:
218
+ * it is detached and unref'd so the command's own exit does not depend on it.
219
+ *
220
+ * @param {Array<{command: string, args: string[]}>} candidates
221
+ */
222
+ function launch([next, ...rest]) {
223
+ if (!next) return;
224
+
225
+ let child;
226
+
227
+ try {
228
+ child = spawn(next.command, next.args, { stdio: 'ignore', detached: true });
229
+ } catch {
230
+ launch(rest);
231
+ return;
232
+ }
233
+
234
+ child.once('error', () => launch(rest));
235
+ child.unref();
236
+ }
237
+
238
+
239
+ /**
240
+ * Whether this module is the script that was run, rather than one the specs
241
+ * imported.
242
+ *
243
+ * Two ways to get this wrong, and the package has had both.
244
+ *
245
+ * pathToFileURL rather than building the URL by hand: a Windows path becomes
246
+ * `file:///D:/...` - three slashes and a drive letter - so a hand-rolled
247
+ * `file://${path}` never matches and the command silently does nothing at all.
248
+ *
249
+ * realpathSync because argv[1] is whatever was typed, and what npm puts on the
250
+ * PATH is a *symlink*: `node_modules/.bin/report-studio` points at this file on
251
+ * macOS and Linux, which is the path `npx report-studio` runs. Node resolves
252
+ * `import.meta.url` through that link and argv[1] keeps it, so the two sides
253
+ * never match and the command exits zero having printed nothing. It went
254
+ * unnoticed for as long as it did because npm writes a shim holding the real
255
+ * path on Windows, where the failure does not reproduce.
256
+ *
257
+ * @param {string|undefined} argv1 process.argv[1]
258
+ * @param {string} moduleUrl import.meta.url
259
+ * @returns {boolean}
260
+ */
261
+ export function runAsScript(argv1, moduleUrl) {
262
+ if (!argv1) return false;
263
+
264
+ try {
265
+ return moduleUrl === pathToFileURL(realpathSync(argv1)).href;
266
+ } catch {
267
+ /** argv[1] is not a file we can resolve; it is not this module either */
268
+ return false;
269
+ }
270
+ }
271
+
272
+
273
+ const invoked = runAsScript(process.argv[1], import.meta.url);
274
+
275
+ if (invoked) {
276
+ /**
277
+ * `process.exitCode`, not `process.exit()`. Writes to a piped stdout are
278
+ * asynchronous, and exiting outright drops whatever has not flushed. The
279
+ * `design` command keeps the loop alive through its server until stopped.
280
+ */
281
+ main().then(code => { process.exitCode = code; });
282
+ }
@@ -0,0 +1,135 @@
1
+ /**
2
+ * serve.js starts the designer on a local http server.
3
+ *
4
+ * This is the primary way into the designer, and the reason it is a CLI rather
5
+ * than only a Vite plugin: it depends on nothing in the host project, so a
6
+ * plain-JS site, a webpack app, or a folder with no build tooling at all can
7
+ * run `npx report-studio design` and get the same thing.
8
+ *
9
+ * Node's own http server takes the same `(req, res, next)` middleware shape
10
+ * Vite's does, so the routes are shared verbatim - only the mounting differs.
11
+ * Everything here is dev tooling; none of it ships to a browser.
12
+ */
13
+
14
+ import { createServer } from 'node:http';
15
+ import { readFile } from 'node:fs/promises';
16
+ import { resolve, extname, join, sep } from 'node:path';
17
+ import { fileURLToPath } from 'node:url';
18
+ import { createReportRoutes, DEFAULT_PREFIX } from '../server/routes.js';
19
+
20
+
21
+ const TYPES = {
22
+ '.html': 'text/html; charset=utf-8',
23
+ '.js': 'text/javascript; charset=utf-8',
24
+ '.css': 'text/css; charset=utf-8',
25
+ '.json': 'application/json; charset=utf-8',
26
+ '.svg': 'image/svg+xml',
27
+ /* the tab icon, and anything else the pages point at in src/asset */
28
+ '.png': 'image/png',
29
+ '.ico': 'image/x-icon'
30
+ };
31
+
32
+ /** where the designer's own files are, relative to this module */
33
+ const HERE = fileURLToPath(new URL('.', import.meta.url));
34
+
35
+
36
+ /**
37
+ * Starts the server.
38
+ *
39
+ * @param {object} options
40
+ * @param {string} options.dir the report directory
41
+ * @param {number} [options.port]
42
+ * @param {string} [options.host]
43
+ * @param {string} [options.root] the directory the designer's files are served from
44
+ * @returns {Promise<{url: string, port: number, close: () => Promise<void>}>}
45
+ */
46
+ export function serve({
47
+ dir,
48
+ port = 5177,
49
+ host = '127.0.0.1',
50
+ root = resolve(HERE, '..')
51
+ } = {}) {
52
+ const reports = createReportRoutes({ dir, prefix: DEFAULT_PREFIX });
53
+ const base = resolve(root);
54
+
55
+ const server = createServer((req, res) => {
56
+ reports(req, res, () => {
57
+ serveStatic(req, res, base)
58
+ .catch(() => plain(res, 500, 'internal error'));
59
+ });
60
+ });
61
+
62
+ return new Promise((ok, fail) => {
63
+ server.on('error', fail);
64
+
65
+ /**
66
+ * Bound to the loopback address by default. This serves a write
67
+ * endpoint, so it should not be reachable from the network unless
68
+ * somebody deliberately asks for that.
69
+ */
70
+ server.listen(port, host, () => {
71
+ const actual = server.address().port;
72
+
73
+ ok({
74
+ port: actual,
75
+ url: `http://${host}:${actual}/designer/`,
76
+ close: () => new Promise(done => server.close(done))
77
+ });
78
+ });
79
+ });
80
+ }
81
+
82
+
83
+ async function serveStatic(req, res, base) {
84
+ const url = decodeSafely((req.url || '/').split('?')[0]);
85
+ const path = filePath(url, base);
86
+
87
+ if (!path) return plain(res, 403, 'forbidden');
88
+
89
+ let body;
90
+
91
+ try {
92
+ body = await readFile(path);
93
+ } catch {
94
+ return plain(res, 404, 'not found');
95
+ }
96
+
97
+ res.statusCode = 200;
98
+ res.setHeader('Content-Type', TYPES[extname(path)] ?? 'application/octet-stream');
99
+ /** dev tooling: never let a stale designer sit in the browser cache */
100
+ res.setHeader('Cache-Control', 'no-store');
101
+ res.end(body);
102
+ }
103
+
104
+
105
+ /**
106
+ * The file a URL maps to, or null when it escapes the served directory.
107
+ *
108
+ * The same discipline as the report routes: resolve, then confirm the result is
109
+ * still underneath. A static server that can be walked out of with `..` gives
110
+ * away every file the process can read.
111
+ */
112
+ function filePath(url, base) {
113
+ const clean = url.endsWith('/') ? `${url}index.html` : url;
114
+ const path = resolve(join(base, clean));
115
+
116
+ if (path !== base && !path.startsWith(base + sep)) return null;
117
+
118
+ return path;
119
+ }
120
+
121
+
122
+ function decodeSafely(text) {
123
+ try {
124
+ return decodeURIComponent(text);
125
+ } catch {
126
+ return text;
127
+ }
128
+ }
129
+
130
+
131
+ function plain(res, status, text) {
132
+ res.statusCode = status;
133
+ res.setHeader('Content-Type', 'text/plain; charset=utf-8');
134
+ res.end(text);
135
+ }
@@ -0,0 +1,53 @@
1
+ /**
2
+ * blank.js is what a new report starts as.
3
+ *
4
+ * The designer is handed a layout by the host, and "I made an empty file" is
5
+ * the ordinary way to start one - so `{}` has to mean "a new report", not a
6
+ * wall of validation errors about a missing page object.
7
+ *
8
+ * These values are a decision, not a placeholder: A4 at 794x1123 is spec 6.2's
9
+ * pixel size, 40px margins match the fixtures, and the three bands are the
10
+ * smallest set that prints something sensible - a header, the rows, a footer.
11
+ * Heights are declared in pixels rather than left to the 10% defaults in
12
+ * regions.js, because a tenth of the page is a lot of header to be given
13
+ * without asking for it.
14
+ */
15
+
16
+
17
+ /** @returns {object} a fresh, valid, empty report */
18
+ export function blankLayout() {
19
+ return {
20
+ version: 1,
21
+ name: 'Untitled report',
22
+ page: {
23
+ width: 794,
24
+ height: 1123,
25
+ margin: { top: 40, right: 40, bottom: 40, left: 40 }
26
+ },
27
+ dataset: null,
28
+ groupBy: null,
29
+ bands: [
30
+ { type: 'pageHeader', height: 60, items: [] },
31
+ { type: 'detail', items: [] },
32
+ { type: 'pageFooter', height: 40, items: [] }
33
+ ]
34
+ };
35
+ }
36
+
37
+
38
+ /**
39
+ * Whether the host handed us "nothing" rather than a layout.
40
+ *
41
+ * Deliberately narrow: null, undefined, and an object with no keys are a new
42
+ * report. Anything else is a layout the user meant to write, so a mistake in it
43
+ * must be reported rather than quietly replaced with a blank page - losing
44
+ * someone's file to a typo is not a recoverable kind of helpful.
45
+ *
46
+ * @param {*} layout
47
+ * @returns {boolean}
48
+ */
49
+ export function isEmptyLayout(layout) {
50
+ if (layout == null) return true;
51
+ if (typeof layout !== 'object' || Array.isArray(layout)) return false;
52
+ return Object.keys(layout).length === 0;
53
+ }