@pritzlaff/celldeck 0.0.0-stage → 0.1.1
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/README.md +49 -2
- package/bin/celldeck.mjs +72 -0
- package/index.html +3362 -0
- package/lib/core.js +1434 -0
- package/lib/store.js +87 -0
- package/package.json +26 -4
package/README.md
CHANGED
|
@@ -1,3 +1,50 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Cell Deck
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Bubble diagrams you pull apart, connect and present as a sequence of saved views.
|
|
4
|
+
|
|
5
|
+
**[▶ Open Cell Deck](https://aaronp.github.io/celldeck/)** ·
|
|
6
|
+
[Example deck](https://aaronp.github.io/celldeck/?src=examples/acme-architecture/deck.json&view=v-pulled-apart)
|
|
7
|
+
|
|
8
|
+
## Layout
|
|
9
|
+
|
|
10
|
+
| Path | What |
|
|
11
|
+
|---|---|
|
|
12
|
+
| `index.html` | The page: styles, markup, rendering and input (the "edge"). No build step. |
|
|
13
|
+
| `lib/core.js` | Pure core: data model (TypeBox schemas, incl. the `deck.json` format), scene reducers, physics. |
|
|
14
|
+
| `lib/store.js` | `createDeckStore(storage, key)`: CRUD over a deck (stage + views), validated on every write, backed by `localStorage` (or `memoryStorage()`). |
|
|
15
|
+
| `examples/` | Data-only repos that open in this viewer. Copy one with `make clone` from its folder. |
|
|
16
|
+
| `test/` | `npm test` (Node's built-in runner). |
|
|
17
|
+
|
|
18
|
+
## Data
|
|
19
|
+
|
|
20
|
+
A deck is one JSON file: `{ version, scene, camera, views: [{ id, name, scene, camera }] }`. See
|
|
21
|
+
`DeckSchema` in `lib/core.js`. `version` is the format version (currently `1`; a file without one is
|
|
22
|
+
read as `1`). A file with a newer version than the page knows is refused rather than misread. Edits are saved in your browser. Use **Download** to save
|
|
23
|
+
`deck.json`, and **Open** to load one from a file (drag-and-drop or pick it) or from a URL.
|
|
24
|
+
|
|
25
|
+
## Editing a file on disk
|
|
26
|
+
|
|
27
|
+
```sh
|
|
28
|
+
npx @pritzlaff/celldeck docs/overview/deck.json # creates it if missing
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Serves the viewer and that deck on localhost (loopback only) and opens it. The File menu's
|
|
32
|
+
**Save to deck.json** writes the deck back to the file (`PORT=…`, `NO_OPEN=1` as for the other tools).
|
|
33
|
+
|
|
34
|
+
## Links
|
|
35
|
+
|
|
36
|
+
| Param | Effect |
|
|
37
|
+
|---|---|
|
|
38
|
+
| `?src=<url>` | open that `deck.json` (relative or absolute; another host must allow CORS). It is not saved in your browser, so a shared link never overwrites your work. |
|
|
39
|
+
| `?view=<id or name>` | open that saved view. The address bar follows as you switch views. |
|
|
40
|
+
| `?present` | start in present mode |
|
|
41
|
+
|
|
42
|
+
## Develop
|
|
43
|
+
|
|
44
|
+
```sh
|
|
45
|
+
make dev # serves the repo on :8000 (python3); open the printed example URL
|
|
46
|
+
make test
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Pushing to `main`/`master` runs the tests, then publishes to GitHub Pages
|
|
50
|
+
(Settings → Pages → Source: **GitHub Actions**).
|
package/bin/celldeck.mjs
ADDED
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// celldeck <deck.json>: serves the viewer and that deck on localhost, then opens it in the browser.
|
|
3
|
+
// The deck is re-read on every request, so reloading shows your latest edits; File → Save writes it back (PUT).
|
|
4
|
+
// A missing file is created as an empty deck, so a project can start from `celldeck docs/overview/deck.json`.
|
|
5
|
+
import { createServer } from 'node:http';
|
|
6
|
+
import { readFile, rename, writeFile } from 'node:fs/promises';
|
|
7
|
+
import { spawn } from 'node:child_process';
|
|
8
|
+
import { basename, resolve } from 'node:path';
|
|
9
|
+
|
|
10
|
+
const file = process.argv[2];
|
|
11
|
+
if (!file || file === '-h' || file === '--help') {
|
|
12
|
+
console.error('Usage: celldeck <deck.json> (PORT=8000 to pick the port, NO_OPEN=1 to skip opening a browser)');
|
|
13
|
+
process.exit(file ? 0 : 1);
|
|
14
|
+
}
|
|
15
|
+
const path = resolve(file);
|
|
16
|
+
await readFile(path).catch(async (e) => {
|
|
17
|
+
if (e.code !== 'ENOENT') { console.error(`celldeck: cannot read ${file}: ${e.message}`); process.exit(1); }
|
|
18
|
+
await writeFile(path, JSON.stringify({ version: 1, scene: { bubbles: [], elements: [], links: [] }, camera: { x: 0, y: 0, zoom: 1 }, views: [] }, null, 2) + '\n');
|
|
19
|
+
console.log(`Created ${file}`);
|
|
20
|
+
});
|
|
21
|
+
|
|
22
|
+
const page = (p) => new URL(`..${p}`, import.meta.url);
|
|
23
|
+
const route = '/' + encodeURIComponent(basename(path));
|
|
24
|
+
// Only these routes, so nothing else on disk is reachable.
|
|
25
|
+
const routes = new Map([
|
|
26
|
+
['/', [page('/index.html'), 'text/html']],
|
|
27
|
+
['/lib/core.js', [page('/lib/core.js'), 'text/javascript']],
|
|
28
|
+
['/lib/store.js', [page('/lib/store.js'), 'text/javascript']],
|
|
29
|
+
[route, [path, 'application/json']],
|
|
30
|
+
]);
|
|
31
|
+
// Loopback names a browser may use for this server. Anything else in Host means DNS rebinding, so it is refused.
|
|
32
|
+
const hosts = (port) => new Set([`127.0.0.1:${port}`, `localhost:${port}`, `[::1]:${port}`]);
|
|
33
|
+
const handler = async (req, res) => {
|
|
34
|
+
if (!hosts(server.address().port).has(req.headers.host)) return res.writeHead(403).end('Forbidden host');
|
|
35
|
+
const [target, type] = routes.get(new URL(req.url, 'http://x').pathname) ?? [];
|
|
36
|
+
if (!target) return res.writeHead(404).end('Not found');
|
|
37
|
+
if (req.method === 'PUT' && target === path) {
|
|
38
|
+
// Cross-site pages cannot get here: a JSON PUT needs a CORS preflight, which this server never answers.
|
|
39
|
+
try {
|
|
40
|
+
const chunks = [];
|
|
41
|
+
for await (const c of req) chunks.push(c);
|
|
42
|
+
const body = Buffer.concat(chunks);
|
|
43
|
+
JSON.parse(body); // never replace the deck with something that isn't JSON
|
|
44
|
+
const tmp = `${path}.celldeck-tmp`;
|
|
45
|
+
await writeFile(tmp, body);
|
|
46
|
+
await rename(tmp, path); // whole file or nothing, never half-written
|
|
47
|
+
return res.writeHead(204).end();
|
|
48
|
+
} catch (e) {
|
|
49
|
+
return res.writeHead(e instanceof SyntaxError ? 400 : 500).end(e.message);
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
if (req.method !== 'GET' && req.method !== 'HEAD') return res.writeHead(405).end('Method not allowed');
|
|
53
|
+
try {
|
|
54
|
+
const body = await readFile(target);
|
|
55
|
+
// x-celldeck-writable tells the page that Save can PUT the deck back to this URL.
|
|
56
|
+
res.writeHead(200, { 'content-type': `${type}; charset=utf-8`, 'cache-control': 'no-store', ...(target === path ? { 'x-celldeck-writable': '1' } : {}) }).end(body);
|
|
57
|
+
} catch (e) {
|
|
58
|
+
res.writeHead(e.code === 'ENOENT' ? 404 : 500).end(e.message);
|
|
59
|
+
}
|
|
60
|
+
};
|
|
61
|
+
const server = createServer(handler);
|
|
62
|
+
|
|
63
|
+
server.listen(Number(process.env.PORT ?? 0), '127.0.0.1', () => {
|
|
64
|
+
const { port } = server.address();
|
|
65
|
+
// Also answer on ::1 so http://localhost:<port> and http://[::1]:<port> work; skipped if IPv6 loopback is unavailable.
|
|
66
|
+
createServer(handler).on('error', () => {}).listen(port, '::1');
|
|
67
|
+
const url = `http://127.0.0.1:${port}/?src=${route}`;
|
|
68
|
+
console.log(`Serving ${file} at ${url} (Ctrl-C to stop)`);
|
|
69
|
+
if (process.env.NO_OPEN) return;
|
|
70
|
+
const [cmd, args] = process.platform === 'darwin' ? ['open', [url]] : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]] : ['xdg-open', [url]];
|
|
71
|
+
spawn(cmd, args, { stdio: 'ignore', detached: true }).on('error', () => {}).unref();
|
|
72
|
+
});
|