@jseeio/jsee 0.8.1 → 0.8.7

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 (11) hide show
  1. package/CHANGELOG.md +8 -0
  2. package/README.md +46 -16
  3. package/dist/jsee.core.js +1 -1
  4. package/dist/jsee.full.js +1 -1
  5. package/dist/jsee.runtime.js +1 -1
  6. package/package.json +4 -1
  7. package/src/cli.js +774 -55
  8. package/src/main.js +7 -0
  9. package/src/utils.js +38 -0
  10. package/templates/common-outputs.js +30 -4
  11. package/templates/minimal-app.vue +2 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,13 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.8.7
4
+ ### Features:
5
+ - Add `jsee --run` for one-shot CLI execution of local JavaScript JSEE apps. Default output is pipeable stdout; `--outputs <dir>` writes all outputs into a directory; named output flags such as `--file out.csv` write individual outputs.
6
+ - Allow raw camelCase schema input names on the CLI, so inputs such as `nSamples` work with both `--nSamples` and sanitized `--nsamples`.
7
+
8
+ ### Fixes:
9
+ - Keep `runPackage(..., ['--run', ...])` output paths relative to the caller working directory instead of the package root.
10
+
3
11
  ## 0.8.1
4
12
  ### Fixes:
5
13
  - Fix `jsee init` JavaScript templates so generated minimal and chat apps accept the default object payload in both browser and server-side execution modes.
package/README.md CHANGED
@@ -34,7 +34,7 @@ Smallest browser example:
34
34
  <script src="https://cdn.jsdelivr.net/npm/@jseeio/jsee@latest/dist/jsee.core.js"></script>
35
35
  ```
36
36
 
37
- Pin a version for production, for example `@jseeio/jsee@0.8.1`.
37
+ Pin a version for production, for example `@jseeio/jsee@0.8.7`.
38
38
 
39
39
  **npm CLI/dev server:**
40
40
 
@@ -117,7 +117,7 @@ Generate a standalone HTML file:
117
117
 
118
118
  ```bash
119
119
  npx @jseeio/jsee schema.json -o app.html
120
- npx @jseeio/jsee schema.json -o app.html --fetch # inline runtime + imports for offline use
120
+ npx @jseeio/jsee schema.json -o app.html --bundle # inline runtime + imports for offline use
121
121
  ```
122
122
 
123
123
  ## When JSEE Fits
@@ -152,8 +152,8 @@ JSEE turns a JSON schema into a working web app. Instead of writing HTML, event
152
152
 
153
153
  1. **Schema** is loaded from a URL, DOM element, function, or JS object
154
154
  2. **Validation** checks schema structure and logs warnings for issues
155
- 3. **Imports** are resolved — JS scripts are loaded in sequence, CSS files are injected as `<link>` tags. In the browser, relative paths resolve against the page URL. In `--fetch` mode, the CLI checks the local filesystem first
156
- 4. **Models** initialize — code is loaded from `url`, `code`, or a hidden DOM cache (`data-src` elements used by `--fetch` bundles and `download()`)
155
+ 3. **Imports** are resolved — JS scripts are loaded in sequence, CSS files are injected as `<link>` tags. In the browser, relative paths resolve against the page URL. In `--bundle` mode, the CLI checks the local filesystem first
156
+ 4. **Models** initialize — code is loaded from `url`, `code`, or a hidden DOM cache (`data-src` elements used by `--bundle` output and `download()`)
157
157
  5. **GUI** is created — a Vue 3 app with reactive inputs, output cards, run/stop buttons and progress bar
158
158
  6. **URL params** are applied — query string values (`?name=value`) set matching inputs, including `alias` matches. File URL params auto-load on init
159
159
 
@@ -167,7 +167,7 @@ JSEE turns a JSON schema into a working web app. Instead of writing HTML, event
167
167
 
168
168
  ### Offline & bundling
169
169
 
170
- - **`jsee --fetch`** bundles everything into a single HTML file: the JSEE runtime, model/view/render code, and all imports are stored in hidden `<script data-src="...">` elements. The result works with no network
170
+ - **`jsee --bundle`** bundles everything into a single HTML file: the JSEE runtime, model/view/render code, and all imports are stored in hidden `<script data-src="...">` elements. The result works with no network
171
171
  - **`jsee.download(title)`** does the same at runtime — exports the current app as a self-contained HTML file
172
172
 
173
173
  ## Schema blocks
@@ -182,7 +182,7 @@ Extra blocks can be provided for further customization:
182
182
 
183
183
  - `render` / `view` — visualization part (optional). Defines custom rendering code
184
184
  - `design` — overall appearance (optional). Defines how the app looks overwriting defaults
185
- - `imports` — a list of scripts and stylesheets to load before the model is initialized. CSS files (`.css` extension) are injected as `<link rel="stylesheet">` in `<head>`, JS files are loaded as scripts. In the browser, relative paths (e.g. `dist/core.js`, `./lib.js`) resolve against the page URL. With `--fetch`, the CLI resolves imports by checking the local filesystem first — if a file exists on disk it is bundled; otherwise it is fetched from CDN
185
+ - `imports` — a list of scripts and stylesheets to load before the model is initialized. CSS files (`.css` extension) are injected as `<link rel="stylesheet">` in `<head>`, JS files are loaded as scripts. In the browser, relative paths (e.g. `dist/core.js`, `./lib.js`) resolve against the page URL. With `--bundle`, the CLI resolves imports by checking the local filesystem first — if a file exists on disk it is bundled; otherwise it is fetched from CDN
186
186
 
187
187
  ```json
188
188
  "imports": [
@@ -369,7 +369,24 @@ Use `columns` on inputs/outputs for dashboard-style layouts:
369
369
  - `outputs` — Outputs definition. Outputs also support `alias` (string) for matching model result keys by alternative names. Per-output `columns` (number, 1-12) sets grid column span, same as inputs
370
370
  - `name`* — Name of the output
371
371
  - `type`* — Type. Possible types:
372
- - `file` — File output (not displayer, but downloaded)
372
+ - `file` — Download-only file output. With a static schema filename, return the file body under the output name:
373
+ ```json
374
+ { "name": "report", "type": "file", "filename": "report.csv" }
375
+ ```
376
+ ```javascript
377
+ return { report: "col1,col2\n1,2\n" }
378
+ ```
379
+ For dynamic filenames, formats, or MIME types, return a descriptor object matching the output name:
380
+ ```javascript
381
+ return {
382
+ file: {
383
+ filename: "dataset.csv",
384
+ content: csvText,
385
+ mime: "text/csv"
386
+ }
387
+ }
388
+ ```
389
+ Descriptor fields: `filename` or `name`; `content`, `value`, `data`, or `url`; optional `mime` or `contentType`.
373
390
  - `object` — JavaScript Object
374
391
  - `html` or `svg` — SVG element
375
392
  - `code` — Code block
@@ -492,7 +509,7 @@ JSEE is part of the [StatSim](https://statsim.com) ecosystem. The schema/runtime
492
509
  ## CLI — Node.js
493
510
 
494
511
  ```
495
- jsee [schema.json] [data...] [options]
512
+ jsee [schema.json|package] [data...] [options]
496
513
  jsee init [template] [--html]
497
514
  ```
498
515
 
@@ -508,16 +525,24 @@ jsee init chat # chat template
508
525
  jsee init --html # single index.html with CDN script
509
526
  ```
510
527
 
511
- #### `jsee <schema> [data...]`
528
+ #### `jsee <schema|package> [data...]`
512
529
 
513
- Start a dev server or generate a static HTML file from a schema.
530
+ Start a dev server or generate a static HTML file from a local schema or a JSEE app package. Package inputs resolve the package `jsee` field, for example `{ "jsee": "schema.json" }`, and use the package directory as the app root. If the app package is not installed locally, let npm provide both packages with `npx -p @jseeio/jsee -p <package> jsee <package> --serve`.
514
531
 
515
532
  ```bash
516
- jsee schema.json # dev server on port 3000
517
- jsee schema.json -o app.html # generate static HTML
518
- jsee schema.json -o app.html -f # self-contained HTML with bundled runtime
533
+ jsee schema.json # dev server on port 3000
534
+ jsee @statsim/gen --serve # serve a resolvable JSEE app package
535
+ jsee schema.json -o app.html # generate static HTML
536
+ jsee @statsim/gen -o app.html --bundle # bundled HTML from package app
537
+ jsee @statsim/gen --run --dataset Moons --nSamples 500
538
+ jsee @statsim/gen --run --dataset Moons --file moons.csv
539
+ npx -p @jseeio/jsee -p @statsim/gen jsee @statsim/gen --serve
519
540
  ```
520
541
 
542
+ JSEE app packages can also expose their own bin with `require('@jseeio/jsee').runPackage(__dirname, process.argv.slice(2))`. The helper reads the package `jsee` field, uses the package root as the app root, and forwards ordinary JSEE CLI options.
543
+
544
+ Use `--run` for one-shot CLI execution. With no output target, JSEE writes a pipeable stdout stream: a single `file` output writes its file content, a single text/table/object output writes that value, and multiple outputs write a JSON object. In `--run` mode, `--outputs <dir>` writes all outputs into a directory, while an output-name flag such as `--file moons.csv` or `--output-file moons.csv` writes one named output to a specific path.
545
+
521
546
  ### Options
522
547
 
523
548
  | Flag | Description |
@@ -527,7 +552,10 @@ jsee schema.json -o app.html -f # self-contained HTML with bundled runtime
527
552
  | `-d, --description <file>` | Markdown file to include as app description |
528
553
  | `-p, --port <number>` | Dev server port (default: `3000`) |
529
554
  | `-v, --version <version>` | JSEE runtime version (`latest`, `dev`, or semver) |
530
- | `-f, --fetch` | Bundle runtime + all deps into a single offline HTML |
555
+ | `-b, --bundle` | Bundle runtime + all deps into a single offline HTML |
556
+ | `-f, --fetch` | Backward-compatible alias for `--bundle` |
557
+ | `-s, --serve` | Serve explicitly (default when no output is provided) |
558
+ | `--run` | Execute the model once from the CLI and write pipeable outputs |
531
559
  | `-e, --execute` | Run models server-side (auto-enabled when serving local .js models) |
532
560
  | `--client` | Force client-side execution (disable auto server-side) |
533
561
  | `-c, --cdn <url\|bool>` | Rewrite model URLs for CDN deployment |
@@ -535,14 +563,16 @@ jsee schema.json -o app.html -f # self-contained HTML with bundled runtime
535
563
  | `--verbose` | Enable verbose logging |
536
564
  | `--help, -h` | Show usage info |
537
565
 
538
- #### `--fetch`
566
+ #### `--bundle`
539
567
 
540
568
  Bundles everything into a single offline HTML: the JSEE runtime, model/view/render code, and all imports are stored in hidden `<script data-src="...">` elements. Local files are detected by checking the filesystem (so bare paths like `dist/core.js` work alongside `./relative.js`); anything not found locally is fetched from CDN.
541
569
 
570
+ Model dependencies and schema `imports` are separate mechanisms: local model files that use `require()` or static `import`/`export` are bundled with optional `esbuild` during `--bundle`, so npm dependencies can become part of the generated HTML; schema `imports` remain explicit browser assets loaded before the model, such as CDN globals, local helper scripts, CSS files, Plot/Three/Leaflet, or other side-effect libraries.
571
+
542
572
  #### `--runtime`
543
573
 
544
574
  Select the runtime source for generated HTML:
545
- - `auto` (default): `inline` when `--fetch`, otherwise `cdn` for file output and `local` for dev server
575
+ - `auto` (default): `inline` when `--bundle`, otherwise `cdn` for file output and `local` for dev server
546
576
  - `local`: `http://localhost:<port>/dist/...`
547
577
  - `cdn`: jsdelivr CDN URL
548
578
  - `inline`: embed runtime code directly in HTML