@jxsuite/schema 5.5.0 → 6.0.0

package/README.md

@@ -48,6 +48,7 @@ Two subpaths let any host edit and write a Jx document the way Studio does, with
 
 - **`@jxsuite/schema/doc-ops`** is the document-op vocabulary. A `JxDocOp` (`set-key`, `insert-child`, `remove-child`, `set-child`, `move-child`) is a value-carrying mutation addressed by `JxPath`. `applyDocOpToDoc(doc, op)` applies one to a plain tree; `inverseOf(doc, op)` computes the op that undoes it, against the document as it stands before the op, in the coordinates of the document after it; `applyDocOpsWithInverse(doc, ops)` applies a sequence and answers each forward/inverse pair. Studio's history, the canvas iframe's shadow document and the collab bridge all replay through this one implementation, and `@jxsuite/collab/ops` re-exports it. Undoing an insert or move into a node that had no `children` leaves `children: []` behind, as Studio's history always has.
 - **`@jxsuite/schema/json-layout`** is the layout-preserving JSON serializer behind every save. `parseJsonDocument(text)` answers the document and the facts about its text the formatter keeps; `serializeJson(document, layout)` writes it back with those honoured, so a one-value edit is a one-line diff.
+- **`@jxsuite/schema/dynamic-tag`** reads the structured subset of template expressions an editor can show as fields: `parseDynamicTag(expr)` takes the text inside one `${…}` and answers a tag (a path, optionally through `state.<formula>(…)`, optionally negated, optionally with a `??` or `||` fallback literal) or `null` for anything else; `printDynamicTag(tag)` writes it back, byte for byte for canonical input; `dynamicTagLabel(tag)` names it; `templateSegments(template)` splits a whole template string into literal text, tags and custom expressions, each tag with its verbatim source.
 
 ## Component schema coverage
 

package/class-schema.json

@@ -8,6 +8,7 @@
           "type": "string"
         },
         "body": {
+          "description": "The member's body in erasable TypeScript, which plain JavaScript already is (spec §23.1), as one string or as an array of lines.",
           "oneOf": [
             {
               "type": "string"
@@ -120,6 +121,7 @@
           "type": "string"
         },
         "body": {
+          "description": "The member's body in erasable TypeScript, which plain JavaScript already is (spec §23.1), as one string or as an array of lines.",
           "oneOf": [
             {
               "type": "string"

package/defs/class-def.schema.ts

@@ -67,6 +67,8 @@ export const classConstructorDefSchema = {
   properties: {
     $prototype: { const: "Function", type: "string" },
     body: {
+      description:
+        "The member's body in erasable TypeScript, which plain JavaScript already is (spec §23.1), as one string or as an array of lines.",
       oneOf: [{ type: "string" }, { items: { type: "string" }, type: "array" }],
     },
     description: { type: "string" },
@@ -103,6 +105,8 @@ export const classMethodDefSchema = {
     $prototype: { const: "Function", type: "string" },
     access: { enum: ["public", "private", "protected"], type: "string" },
     body: {
+      description:
+        "The member's body in erasable TypeScript, which plain JavaScript already is (spec §23.1), as one string or as an array of lines.",
       oneOf: [{ type: "string" }, { items: { type: "string" }, type: "array" }],
     },
     description: { type: "string" },

package/defs/function-def.schema.ts

@@ -2,8 +2,9 @@ export const functionDefSchema = {
   additionalProperties: false,
   description:
     'A function declaration. $prototype must be "Function". ' +
-    "body (inline) and $src (external) are mutually exclusive. " +
+    "body (inline) and $src (external) are mutually exclusive; declaring both is an error. " +
     "First parameter is always state (the reactive scope).",
+  not: { required: ["body", "$src"] },
   properties: {
     $export: {
       description: "Named export in $src module. Defaults to the state key name.",
@@ -32,11 +33,12 @@ export const functionDefSchema = {
     },
     body: {
       description:
-        "Inline function body: an opaque JS source string (first implicit parameter is state), or a structured statement array (spec §20) — explicit structured function declaration, analyzable by tooling and editable visually. The escalation ladder within the shape is structured statements → JS string.",
+        "Inline function body: a source string in erasable TypeScript, which plain JavaScript already is (spec §23.1; types are erased before it is analysed or run; first implicit parameter is state), or a structured statement array (spec §20) — explicit structured function declaration, analyzable by tooling and editable visually. The escalation ladder within the shape is structured statements → source string.",
       examples: [
         "state.count++",
         'state.items.push({ id: Date.now(), text: "", done: false })',
         'return state.score >= 90 ? "gold" : "silver"',
+        "const input = event.target as HTMLInputElement; state.label = input.value",
         [
           { operator: "push", target: { $ref: "#/state/cart" }, value: 1 },
           { dispatchEvent: "cart-changed", detail: { $ref: "#/state/cart" } },

package/package.json

@@ -18,6 +18,7 @@
     "./project-schemas": "./src/project-schemas.ts",
     "./validate-project": "./src/validate-project.ts",
     "./types": "./types.ts",
+    "./function-role": "./src/function-role.ts",
     "./guards": "./src/guards.ts",
     "./locale": "./src/locale.ts",
     "./intl": "./src/intl.ts",
@@ -29,9 +30,14 @@
     "./ijson": "./src/ijson.ts",
     "./parse": "./src/parse.ts",
     "./jxn": "./src/jxn/index.ts",
+    "./virtual-types": "./src/jxn/virtual-types.ts",
+    "./virtual-document": "./src/jxn/virtual-document.ts",
+    "./jxn-completion": "./src/jxn/complete.ts",
     "./project-file": "./src/project-file.ts",
     "./project-file/node": "./src/project-file-node.ts",
     "./doc-ops": "./src/doc-ops.ts",
+    "./document-scripts": "./src/document-scripts.ts",
+    "./dynamic-tag": "./src/dynamic-tag.ts",
     "./json-layout": "./src/json-layout.ts",
     "./defs": "./defs/index.ts",
     "./schema.json": "./schema.json",
@@ -66,7 +72,7 @@
     "upgrade": "bun update --latest && bun install"
   },
   "type": "module",
-  "version": "5.5.0",
+  "version": "6.0.0",
   "devDependencies": {
     "json-schema-to-ts": "^3.1.1"
   }

package/schema.json

@@ -205,7 +205,13 @@
     },
     "FunctionDef": {
       "additionalProperties": false,
-      "description": "A function declaration. $prototype must be \"Function\". body (inline) and $src (external) are mutually exclusive. First parameter is always state (the reactive scope).",
+      "description": "A function declaration. $prototype must be \"Function\". body (inline) and $src (external) are mutually exclusive; declaring both is an error. First parameter is always state (the reactive scope).",
+      "not": {
+        "required": [
+          "body",
+          "$src"
+        ]
+      },
       "properties": {
         "$export": {
           "description": "Named export in $src module. Defaults to the state key name.",
@@ -241,11 +247,12 @@
           "type": "array"
         },
         "body": {
-          "description": "Inline function body: an opaque JS source string (first implicit parameter is state), or a structured statement array (spec §20) — explicit structured function declaration, analyzable by tooling and editable visually. The escalation ladder within the shape is structured statements → JS string.",
+          "description": "Inline function body: a source string in erasable TypeScript, which plain JavaScript already is (spec §23.1; types are erased before it is analysed or run; first implicit parameter is state), or a structured statement array (spec §20) — explicit structured function declaration, analyzable by tooling and editable visually. The escalation ladder within the shape is structured statements → source string.",
           "examples": [
             "state.count++",
             "state.items.push({ id: Date.now(), text: \"\", done: false })",
             "return state.score >= 90 ? \"gold\" : \"silver\"",
+            "const input = event.target as HTMLInputElement; state.label = input.value",
             [
               {
                 "operator": "push",
@@ -506,6 +513,7 @@
           "type": "string"
         },
         "body": {
+          "description": "The member's body in erasable TypeScript, which plain JavaScript already is (spec §23.1), as one string or as an array of lines.",
           "oneOf": [
             {
               "type": "string"
@@ -577,6 +585,7 @@
           "type": "string"
         },
         "body": {
+          "description": "The member's body in erasable TypeScript, which plain JavaScript already is (spec §23.1), as one string or as an array of lines.",
           "oneOf": [
             {
               "type": "string"
@@ -28500,6 +28509,21 @@
         }
       ]
     },
+    "$script": {
+      "additionalProperties": false,
+      "description": "This document's own modules, as TypeScript module text (spec.md §23.2). A state entry names an export of one with `$src: \"#client\"` or `$src: \"#server\"`. `client` runs in the browser; `server` runs only on the server and is never sent to one.",
+      "properties": {
+        "client": {
+          "description": "The module the browser runs. A Function entry with `$src: \"#client\"` is one of its exports.",
+          "type": "string"
+        },
+        "server": {
+          "description": "The module the server runs. A `timing: \"server\"` entry with `$src: \"#server\"` is one of its exports, called with `(args, env)`.",
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
     "$shadow": {
       "description": "Render this component into a shadow root instead of the light DOM (spec.md §16.6). Off unless set: a shadow root isolates the component's styles from the page and replaces the <slot> emulation with real slot distribution, so it changes how the component composes. Overrides `defaults.shadow` in both directions — `false` opts one component out of a project that opted in.",
       "oneOf": [

package/src/component-meta.ts

@@ -32,6 +32,11 @@ export interface ComponentPropDef {
   /** Absent for a full-form entry that declares no `default`. */
   default?: JsonValue | undefined;
   format?: unknown;
+  /**
+   * The values the entry admits, read from its JSON Schema `enum` (spec.md §5.3). Absent when the
+   * entry declares none, so a prop with a closed set of values is told apart from free text.
+   */
+  enum?: JsonValue[];
 }
 
 /** What discovery reports for one component document. */
@@ -150,12 +155,16 @@ function propFrom(name: string, def: JsonValue): ComponentPropDef | null {
   if (fields.$prototype || fields.$handler || fields.$compute) {
     return null;
   }
-  return {
+  const prop: ComponentPropDef = {
     default: fields.default,
     format: fields.format,
     name,
     type: fields.type,
   };
+  if (Array.isArray(fields.enum)) {
+    prop.enum = fields.enum;
+  }
+  return prop;
 }
 
 /**

package/src/document-scripts.ts

@@ -0,0 +1,304 @@
+/**
+ * A document's own modules (spec.md §23.2): how a `$src` names them, and how that name is given the
+ * document it belongs to.
+ *
+ * A document carries its client and server modules as text in `$script`, and an entry names one
+ * with `$src: "#client"` or `$src: "#server"`. Those two strings say nothing about WHICH document,
+ * and everything downstream keys a module on the specifier it was spelled with: the interpreter's
+ * module cache, the build's bundle table, the site worker's one-route-per-export rule. A page and
+ * its layout each naming `#client` would be one module to all of them.
+ *
+ * So a document is **qualified** once, as it is read and before anything merges it with another:
+ * `#client` becomes `jx-script:<path>#client`, where `<path>` is the document's own address. After
+ * that a page's module and its layout's are different strings, and nothing downstream needs to know
+ * that document scripts exist.
+ *
+ * Pure string and tree work, with no node imports, so every host can use it.
+ *
+ * @docs framework/concepts/functions
+ */
+
+import { isJsonObject, isString } from "./guards";
+import type { JsonValue, JxDocument, JxDocumentValue, JxElement } from "../types";
+
+export type { JxDocumentScripts } from "../types";
+
+/** The two modules a document may carry: one the browser runs, one the server runs. */
+export type ScriptSide = "client" | "server";
+
+/** What a qualified script specifier starts with. */
+export const SCRIPT_SPECIFIER_PREFIX = "jx-script:";
+
+/** The authored `$src` of an entry naming its own document's client module. */
+export const CLIENT_SCRIPT_REF = "#client";
+
+/** The authored `$src` of an entry naming its own document's server module. */
+export const SERVER_SCRIPT_REF = "#server";
+
+/** A qualified specifier, read back: the document it names, and which of its modules. */
+/** A URL path naming a TypeScript module. */
+const TYPESCRIPT_PATH = /\.[cm]?ts$/iu;
+
+/**
+ * True when a URL path names a TypeScript module: text a browser cannot import as written, which a
+ * page's module loader erases first.
+ *
+ * @param pathname A URL's path, without its query or fragment.
+ */
+export function isTypeScriptPath(pathname: string): boolean {
+  return TYPESCRIPT_PATH.test(pathname);
+}
+
+/**
+ * A document as a browser may have it: without its server module. The module is called over the
+ * network and never imported by a page, so its text is nothing a reader should be sent.
+ *
+ * The document given is not changed, and one with no server module is returned as it is. `$script`
+ * itself stays, however little is left in it: it is what says the document has modules of its own,
+ * which is what has a host qualify the entries that name them.
+ *
+ * @param doc The document as read.
+ */
+export function withoutServerScript<T extends JxDocument>(doc: T): T {
+  const script = doc.$script;
+  if (script?.server === undefined) {
+    return doc;
+  }
+  const { server: _server, ...kept } = script;
+  return { ...doc, $script: kept };
+}
+
+export interface ScriptSpecifier {
+  /** The document's address, as it was qualified: `/`-separated and without a leading `./`. */
+  path: string;
+  side: ScriptSide;
+}
+
+/** The side an authored `$src` names when it names its own document's module, else `null`. */
+export function scriptRefSide(src: string): ScriptSide | null {
+  if (src === CLIENT_SCRIPT_REF) {
+    return "client";
+  }
+  if (src === SERVER_SCRIPT_REF) {
+    return "server";
+  }
+  return null;
+}
+
+/** A document address in the one spelling a specifier uses: `/` separators, no leading `./`. */
+function normalizedPath(path: string): string {
+  return path.replaceAll("\\", "/").replace(/^(?:\.\/)+/, "");
+}
+
+/**
+ * The specifier naming one of a document's modules: `jx-script:components/counter.jxn#client`.
+ *
+ * @param path The document's address, project-relative in a project.
+ * @param side Which module.
+ */
+export function scriptSpecifier(path: string, side: ScriptSide): string {
+  return `${SCRIPT_SPECIFIER_PREFIX}${normalizedPath(path)}#${side}`;
+}
+
+/** True when a `$src` is a qualified script specifier. */
+export function isScriptSpecifier(src: string): boolean {
+  return src.startsWith(SCRIPT_SPECIFIER_PREFIX);
+}
+
+/**
+ * Read a qualified specifier back into the document it names and the side. `null` for anything
+ * else, including a `jx-script:` specifier that names no document or neither side.
+ */
+export function parseScriptSpecifier(src: string): ScriptSpecifier | null {
+  if (!isScriptSpecifier(src)) {
+    return null;
+  }
+  const rest = src.slice(SCRIPT_SPECIFIER_PREFIX.length);
+  const hash = rest.lastIndexOf("#");
+  if (hash <= 0) {
+    return null;
+  }
+  const side = rest.slice(hash + 1);
+  if (side !== "client" && side !== "server") {
+    return null;
+  }
+  return { path: rest.slice(0, hash), side };
+}
+
+/**
+ * One value of a document with every `$src` naming its own document's module qualified. A value
+ * with nothing to qualify is returned as it was given, so an untouched subtree is shared rather
+ * than copied.
+ */
+function qualifiedValue(value: JxDocumentValue, path: string): JxDocumentValue {
+  if (Array.isArray(value)) {
+    const items = value.map((item) => qualifiedValue(item, path));
+    /* SAFETY: `items` holds what `value` held, each member either itself or its qualified copy, so
+       it is the same kind of array `value` was. */
+    return items.some((item, index) => item !== value[index]) ? (items as JsonValue[]) : value;
+  }
+  if (!isJsonObject(value)) {
+    return value;
+  }
+  let copy: Record<string, JxDocumentValue> | null = null;
+  for (const [key, member] of Object.entries(value)) {
+    let next: JxDocumentValue = member;
+    if (key === "$src" && isString(member)) {
+      const side = scriptRefSide(member);
+      next = side === null ? member : scriptSpecifier(path, side);
+    } else if (key !== "$script") {
+      next = qualifiedValue(member, path);
+    }
+    if (next !== member) {
+      copy ??= { ...value };
+      copy[key] = next;
+    }
+  }
+  /* SAFETY: `copy` is `value` with some members replaced by their qualified copies, which are the
+     same kinds of value, so it is the kind of object `value` was. */
+  return copy === null ? value : (copy as JxDocumentValue);
+}
+
+/**
+ * A document with every `$src: "#client"` and `$src: "#server"` in it naming THIS document:
+ * `jx-script:<path>#client`. Run once as a document is read, before a layout merge or a project
+ * state merge, because after either nothing records which file an entry was written in.
+ *
+ * The document given is not changed, and one with no such entry is returned as it is. `$script`
+ * itself is left alone: it is the text the specifier names. Qualifying twice changes nothing.
+ *
+ * @param doc The document as read.
+ * @param path The document's address: project-relative in a project, with either separator.
+ */
+export function qualifyScripts<T extends JxDocument>(doc: T, path: string): T {
+  /* SAFETY: `qualifiedValue` returns its argument or a copy of it with `$src` strings replaced, so
+     a document goes in and the same kind of document comes out. */
+  return qualifiedValue(doc, path) as T;
+}
+
+// ─── Advice ─────────────────────────────────────────────────────────────────────
+
+/** The two things worth saying about how a document names its modules. */
+export type ScriptAdviceRule = "relative-src" | "lazy-shares-script";
+
+/**
+ * One piece of advice about a `$src`. Advice, not a defect: the document is correct and runs as
+ * written everywhere, so nothing that reports one may fail on it.
+ */
+export interface ScriptAdvice {
+  rule: ScriptAdviceRule;
+  /** The entry the `$src` is written on, in the segment vocabulary a document path uses. */
+  path: (string | number)[];
+  /** One sentence naming what was found, in the author's language. */
+  message: string;
+  /** What to do instead, and what happens when nothing is done. */
+  detail: string;
+}
+
+/** Matches a `$src` naming a file beside its document: `./counter.js`, `../lib/format.ts`. */
+const RELATIVE_SRC = /^\.{1,2}\//u;
+
+/** Matches a `$src` naming a JSON document, which is a class schema and never a script (§12.2). */
+const JSON_SRC = /\.json$/iu;
+
+/**
+ * True when a `$src` names a script file by a relative path: the one spelling a document's own
+ * script can stand in for. An `npm:` package, a kit behaviour (`jx-ui:/…`), an absolute URL and a
+ * `.class.json` schema have no other spelling, and `#client` is already the script.
+ *
+ * @param src An entry's `$src`.
+ */
+export function isRelativeScriptSrc(src: string): boolean {
+  return RELATIVE_SRC.test(src) && !JSON_SRC.test(src);
+}
+
+/** True when a `$src` names its document's client module, as authored or once qualified. */
+function namesClientScript(src: string): boolean {
+  return scriptRefSide(src) === "client" || parseScriptSpecifier(src)?.side === "client";
+}
+
+/** An entry carrying a `$src`, as the walk found it. */
+interface SrcEntry {
+  path: (string | number)[];
+  src: string;
+  lazy: boolean;
+}
+
+/** Every object in a document that carries a string `$src`, in document order. */
+function srcEntries(
+  value: JxDocumentValue,
+  path: (string | number)[],
+  found: SrcEntry[],
+): SrcEntry[] {
+  if (Array.isArray(value)) {
+    for (const [index, item] of value.entries()) {
+      srcEntries(item, [...path, index], found);
+    }
+    return found;
+  }
+  if (!isJsonObject(value)) {
+    return found;
+  }
+  if (isString(value.$src)) {
+    found.push({ lazy: value.$lazy === true, path, src: value.$src });
+  }
+  for (const [key, member] of Object.entries(value)) {
+    // `$script` is the modules' text, not entries that name one.
+    if (key !== "$script") {
+      srcEntries(member, [...path, key], found);
+    }
+  }
+  return found;
+}
+
+/** What an entry is called in a sentence: its key, or `this entry` for one in a list. */
+function entryName(path: (string | number)[]): string {
+  const last = path.at(-1);
+  return isString(last) ? `"${last}"` : "this entry";
+}
+
+/**
+ * What there is to say about how a document names its modules (spec.md §23.2).
+ *
+ * - **`relative-src`**: an entry imports a file beside the document. A module only that document uses
+ *   can be the document's own script, which makes the document one file. A `$lazy` entry is left
+ *   alone: a module of its own is exactly what it needs.
+ * - **`lazy-shares-script`**: a `$lazy` entry names the client script that another entry loads up
+ *   front. A document has one client script, so the deferral defers nothing.
+ *
+ * `jx validate` and Studio's Problems both report from here, so the two say the same thing about
+ * the same document.
+ *
+ * @param doc The document as written, or as qualified: both spellings of `#client` are read.
+ */
+export function findScriptAdvice(doc: JxDocument | JxElement): ScriptAdvice[] {
+  const entries = srcEntries(doc, [], []);
+  const eagerClient = entries.some((entry) => !entry.lazy && namesClientScript(entry.src));
+  const advice: ScriptAdvice[] = [];
+  for (const entry of entries) {
+    const name = entryName(entry.path);
+    if (!entry.lazy && isRelativeScriptSrc(entry.src)) {
+      advice.push({
+        detail:
+          "A module only this document uses can be the document's own script: move the code " +
+          'into the client script (the server script for a `timing: "server"` entry) and name ' +
+          'it with `$src: "#client"` or `$src: "#server"`. A module several documents import ' +
+          "stays a file, and this one keeps working as it is.",
+        message: `${name} imports ${entry.src}, which the document could carry as its own script`,
+        path: entry.path,
+        rule: "relative-src",
+      });
+    } else if (entry.lazy && eagerClient && namesClientScript(entry.src)) {
+      advice.push({
+        detail:
+          "A document has one client script, and another entry imports it as the page loads, " +
+          "so `$lazy` defers nothing here. Move this export to a `$src` module of its own to " +
+          "load it on its first call.",
+        message: `${name} is $lazy, but the script it is in loads with the page`,
+        path: entry.path,
+        rule: "lazy-shares-script",
+      });
+    }
+  }
+  return advice;
+}