justskill-design 0.0.1 → 3.2.0

package/canvas/tree.mjs

@@ -0,0 +1,249 @@
+/**
+ * canvas/tree.mjs — the layer tree, as data.
+ *
+ * No DOM, and no imports at all. The canvas decides how a tree looks; this file
+ * decides what the tree *is*: which row is inside which, which rows are visible
+ * under the current expansion, what a selection has to open to be seen, and which
+ * page a selection names.
+ *
+ * That split is the point. Everything here runs under `node --test` — a browser
+ * is not needed to know that collapsing a node hides its grandchildren, or that
+ * selecting a deeply nested element opens exactly the path down to it. The DOM
+ * half of the tree (`renderLayerTree` in `app.mjs`) is then thin enough to read.
+ *
+ * The input rows are what `pageTree()` in `lib/render.mjs` already produces:
+ * document order, one row per element, with a `depth`:
+ *
+ *     { id, type, tag, name, depth, hidden, childCount, text }
+ */
+
+/**
+ * A view is the expansion state, in three parts:
+ *
+ *   `all`       — the standing intent: everything open, everything closed, or
+ *                 "nobody has said" and each node decides for itself (which, on
+ *                 a fresh view, means closed)
+ *   `expanded`  — nodes opened against that intent
+ *   `collapsed` — nodes closed against it
+ *
+ * A tree opens closed. An imported design can be thousands of rows, and one that
+ * greets you as a wall of text is one nobody reads; a page list is a map, and a
+ * map you can see the shape of is worth more than the first level of detail.
+ * The two buttons at the top of the panel are the two ways out of that, and
+ * selecting something on the canvas opens exactly the path down to it.
+ */
+export function newView() {
+  return { all: "closed", expanded: new Set(), collapsed: new Set() };
+}
+
+/**
+ * Depth-first rows -> nested nodes, in document order.
+ *
+ * A row's parent is the nearest row above it with a smaller depth, which is how
+ * the flat form carries the structure. A malformed jump (0 -> 3 with no 1 or 2)
+ * attaches to the nearest ancestor that exists instead of throwing: the file is
+ * the authority, and a layer list is not the place to refuse to draw one.
+ */
+export function nest(rows) {
+  const roots = [];
+  const stack = [];
+  for (const row of rows) {
+    const depth = Math.max(0, row.depth | 0);
+    const node = { ...row, depth, children: [] };
+    const parent = depth === 0 ? null : nearestAncestor(stack, depth - 1);
+    (parent ? parent.children : roots).push(node);
+    stack.length = depth;
+    stack[depth] = node;
+  }
+  return roots;
+}
+
+function nearestAncestor(stack, depth) {
+  for (let d = Math.min(depth, stack.length - 1); d >= 0; d -= 1) {
+    if (stack[d]) return stack[d];
+  }
+  return null;
+}
+
+/** Every node in document order, open or closed. */
+export function walk(nodes, visit) {
+  for (const node of nodes) {
+    visit(node);
+    walk(node.children, visit);
+  }
+}
+
+/** id -> node, for the whole tree. */
+export function byId(nodes) {
+  const index = new Map();
+  walk(nodes, (node) => index.set(node.id, node));
+  return index;
+}
+
+/** The ancestors of `id`, root first, ending with `id` itself. */
+export function pathTo(nodes, id) {
+  let found = null;
+  const walkPath = (list, trail) => {
+    for (const node of list) {
+      const next = [...trail, node.id];
+      if (node.id === id) { found = next; return; }
+      walkPath(node.children, next);
+      if (found) return;
+    }
+  };
+  walkPath(nodes, []);
+  return found ?? [];
+}
+
+export function hasChildren(node) {
+  return (node.children?.length ?? 0) > 0;
+}
+
+/**
+ * Is this node open?
+ *
+ * Exceptions first, then the standing intent. A node the user closed stays
+ * closed even under "expand all"; a node they opened stays open even under
+ * "collapse all" — which is what makes both buttons useful rather than absolute
+ * (collapse everything, then open the one branch you are working on), and what
+ * makes the two directions of a single toggle both stick.
+ */
+export function isOpen(node, view) {
+  if (!hasChildren(node)) return false;
+  if (view.collapsed.has(node.id)) return false;
+  if (view.expanded.has(node.id)) return true;
+  return view.all === "open";
+}
+
+/** Open every node, discarding the per-node exceptions. */
+export function expandAll(view) {
+  view.all = "open";
+  view.expanded.clear();
+  view.collapsed.clear();
+}
+
+/** Close every node, discarding the per-node exceptions. */
+export function collapseAll(view) {
+  view.all = "closed";
+  view.expanded.clear();
+  view.collapsed.clear();
+}
+
+/** Open or close one node, in place, remembering the choice. */
+export function toggleNode(node, view) {
+  if (!hasChildren(node)) return false;
+  if (isOpen(node, view)) {
+    view.expanded.delete(node.id);
+    view.collapsed.add(node.id);
+  } else {
+    view.collapsed.delete(node.id);
+    view.expanded.add(node.id);
+  }
+  return isOpen(node, view);
+}
+
+/**
+ * Open everything above `id`, so a selected row can actually be seen.
+ *
+ * A selection is often made from the canvas, and a row that is selected while
+ * its ancestors are closed is a row the user cannot find — the panel looks like
+ * it lost the selection rather than like it folded it away.
+ */
+export function openPath(nodes, id, view) {
+  const path = pathTo(nodes, id);
+  for (const ancestor of path.slice(0, -1)) {
+    view.collapsed.delete(ancestor);
+    view.expanded.add(ancestor);
+  }
+  return path;
+}
+
+/**
+ * Where a pointer at `path` lands, given the rung the panel is standing on.
+ *
+ * `path` is the chain from the page down to the element under the pointer, so
+ * `path[0]` is the page and `path[d]` is the container `d` rungs down. The rung
+ * is a *depth*, not an element: hovering a different section at the same depth
+ * has to land on that section, which is what "the solid box follows the mouse"
+ * means. And the pointer is always either inside one of the level's children —
+ * the thing a click selects — or on the level itself, when it is over padding or
+ * a gap.
+ *
+ * `path` may be shorter than the rung (the pointer is on the page itself, or on
+ * a page with no elements): then the deepest rung that exists is the level.
+ */
+export function rungAt(path, levelDepth) {
+  if (path.length === 0) return null;
+  const depth = Math.max(0, Math.min(levelDepth, path.length - 1));
+  const insideChild = path.length > depth + 1;
+  return {
+    depth,
+    levelId: path[depth],
+    underId: insideChild ? path[depth + 1] : path[depth],
+    insideChild,
+  };
+}
+
+/** The rows to draw, in document order: everything not inside a closed node. */
+export function visibleNodes(nodes, view) {
+  const out = [];
+  const visit = (list) => {
+    for (const node of list) {
+      out.push(node);
+      if (hasChildren(node) && isOpen(node, view)) visit(node.children);
+    }
+  };
+  visit(nodes);
+  return out;
+}
+
+/**
+ * The page a selection names, or null when it names none.
+ *
+ * A canvas shows every page at once, and a page is a separate shadow root, so an id
+ * is not unique in the document: a selected element says which element, never which
+ * page. Only the page itself can answer the question `Export` has to ask, and that is
+ * the same id in both fields — an element whose id equals its page's id *is* the page
+ * mount, so the equality is exact rather than a guess.
+ *
+ * The page also has to be in the model: after an undo that removed it, the selection
+ * outlives what it names, and a stale id is not exportable.
+ */
+export function selectedPage(pages, selection, selectionPage) {
+  if (!selection || selection !== selectionPage) return null;
+  return (pages ?? []).find((page) => page.id === selection) ?? null;
+}
+
+/**
+ * The page roots of a document model, each with its element tree nested under it.
+ *
+ * The page is a rung of the tree, not a label above it, so its elements start one
+ * level deeper than `pageTree()` reported them. Without the shift a page and its
+ * top-level elements would both be depth 0, and every depth-keyed decision —
+ * the default open limit, `aria-level`, the indent — would be off by one.
+ */
+export function pageRoots(pages, rowsOf) {
+  return pages.map((page) => {
+    const children = shiftDepth(nest(rowsOf(page)), 1);
+    return {
+      id: page.id,
+      kind: "page",
+      depth: 0,
+      name: page.name,
+      type: "page",
+      tag: "section",
+      hidden: false,
+      childCount: children.length,
+      children,
+    };
+  });
+}
+
+/** Re-number a nested tree's depths, in place, and return it. */
+function shiftDepth(nodes, by) {
+  for (const node of nodes) {
+    node.depth += by;
+    shiftDepth(node.children, by);
+  }
+  return nodes;
+}

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+# Bundle layer contributed by justskill-design.
+#
+# The row loads this package's main entry (`dsh/index.js`) as a plain Cordis
+# host plugin. The `dsh.client` declaration in package.json makes the Web app
+# load `dsh/client.js` as the browser half.
+- insert:
+    - id: justskill-design
+      name: 'justskill-design'

package/design.mjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+/**
+ * justSkill v2 — the single entry point.
+ *
+ *   node design.mjs <verb> [args]
+ *
+ * Verbs load lazily, so `--help` works before the module a verb needs exists,
+ * and a session that only validates never imports the pen reader.
+ *
+ * Exit codes (docs/format-v3.md §10):
+ *   0  success
+ *   1  refused or invalid
+ *   2  unreadable file or bad arguments
+ */
+
+import fs from "node:fs";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+import { isMainModule } from "./lib/node/cli.mjs";
+import { assertNodeVersion } from "./lib/node/fs.mjs";
+
+/**
+ * The verb table, exported so a test can derive it instead of copying it.
+ *
+ * `test/contract.test.mjs` checks three things against this object: every verb has a
+ * module that exports `USAGE`, every verb is named in `SKILL.md`, and no document names
+ * a verb that is not here. A hand-written list in the test would pass while the CLI and
+ * the docs drifted apart, which is the failure the check exists to catch.
+ */
+export const VERBS = {
+  new: () => import("./lib/node/verbs/new.mjs"),
+  validate: () => import("./lib/node/verbs/validate.mjs"),
+  format: () => import("./lib/node/verbs/format.mjs"),
+  ls: () => import("./lib/node/verbs/ls.mjs"),
+  show: () => import("./lib/node/verbs/show.mjs"),
+  add: () => import("./lib/node/verbs/add.mjs"),
+  set: () => import("./lib/node/verbs/set.mjs"),
+  remove: () => import("./lib/node/verbs/remove.mjs"),
+  move: () => import("./lib/node/verbs/move.mjs"),
+  rename: () => import("./lib/node/verbs/rename.mjs"),
+  migrate: () => import("./lib/node/verbs/migrate.mjs"),
+  tokens: () => import("./lib/node/verbs/tokens.mjs"),
+  export: () => import("./lib/node/verbs/export.mjs"),
+  import: () => import("./lib/node/verbs/import.mjs"),
+  serve: () => import("./lib/node/verbs/serve.mjs"),
+};
+
+export const USAGE = `justSkill — design web pages as a validated HTML file
+
+Usage: node design.mjs <verb> [args]
+
+Verbs:
+  new <file> [--name N] [--title T] [--tokens neutral|brand|dark | --tokens-file P] [--size WxH]
+  validate <file> [--json] [--strict]
+  format <file> [--check] [--dry-run]
+  ls <file> [--pages] [--in <data-id>] [--depth n] [--json]
+  show <file> <data-id> [--json]
+  add <file> --html-file f | --html - [--in <data-id>] [--as <id>] [--index n]
+  set <file> <data-id> [--style 'a:b;c:d'] [--text T] [--attr name=value] [--unset name]
+  remove <file> <data-id>
+  move <file> <data-id> [--before X | --after X | --index n | --into P]
+  rename <file> <old-id> <new-id>
+  migrate <file>
+  tokens <file> ls | set <组.名> <值> | rm <组.名>
+  export <file> [--page <id>] [--all] [-o path] [--resolve-tokens] [--stdout]
+  import pen <file> [-o out.html] [--report ledger.json]
+  serve [<file>] [--port 0] [--ttl 30] [--no-open]
+
+Shared flags: --json  --quiet  --dry-run  --force  --help
+
+Exit codes: 0 success, 1 refused or invalid, 2 unreadable file or bad arguments.
+
+Each line above lists the flags that matter most, not all of them; "export" alone has
+nine. Run "node design.mjs <verb> --help" for the full set of one verb.`;
+
+function print(text, stream = process.stdout) {
+  stream.write(text.endsWith("\n") ? text : `${text}\n`);
+}
+
+function version() {
+  try {
+    const file = fileURLToPath(new URL("./package.json", import.meta.url));
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    return typeof parsed.version === "string" ? parsed.version : "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+/**
+ * Map a thrown error to an exit code and a message on stderr.
+ *
+ * @param {any} error
+ * @returns {number}
+ */
+function reportError(error) {
+  const message = error && error.message ? error.message : String(error);
+  const name = error && error.name;
+  if (name === "CliError") {
+    print(message, process.stderr);
+    return Number.isInteger(error.exitCode) ? error.exitCode : 2;
+  }
+  if (name === "FsError") {
+    print(`ERROR  ${message}`, process.stderr);
+    return error.code === "fs/no-write" ? 1 : 2;
+  }
+  if (name === "SpansError" || name === "DetectError") {
+    print(`ERROR  ${message}`, process.stderr);
+    return 2;
+  }
+  print(`ERROR  ${message}`, process.stderr);
+  if (process.env.SD_TRACE && error && error.stack) print(error.stack, process.stderr);
+  return 1;
+}
+
+/**
+ * Run one command line.
+ *
+ * @param {string[]} [argv] defaults to `process.argv.slice(2)`
+ * @returns {Promise<number>} the exit code
+ */
+export async function main(argv = process.argv.slice(2)) {
+  const args = Array.isArray(argv) ? argv.map(String) : [];
+  const verb = args[0];
+
+  try {
+    assertNodeVersion();
+  } catch (error) {
+    return reportError(error);
+  }
+
+  if (verb === undefined) {
+    print(USAGE, process.stderr);
+    return 2;
+  }
+  if (verb === "help" || verb === "--help" || verb === "-h") {
+    print(USAGE);
+    return 0;
+  }
+  if (verb === "--version" || verb === "-v") {
+    print(version());
+    return 0;
+  }
+  if (verb.startsWith("-")) {
+    print(`Unknown option: ${verb}\n\n${USAGE}`, process.stderr);
+    return 2;
+  }
+
+  const load = Object.prototype.hasOwnProperty.call(VERBS, verb) ? VERBS[verb] : null;
+  if (!load) {
+    print(`Unknown verb: ${verb}\n\n${USAGE}`, process.stderr);
+    return 2;
+  }
+
+  try {
+    const mod = await load();
+    const run = typeof mod.default === "function" ? mod.default : mod.run;
+    if (typeof run !== "function") {
+      print(`The ${verb} verb exports no run()`, process.stderr);
+      return 1;
+    }
+    const code = await run(args.slice(1));
+    return Number.isInteger(code) ? code : 0;
+  } catch (error) {
+    return reportError(error);
+  }
+}
+
+if (isMainModule(import.meta.url)) {
+  process.exitCode = await main();
+}