@jxsuite/schema 5.5.0 → 6.0.0

package/src/jxn/virtual-types.ts

@@ -0,0 +1,205 @@
+/**
+ * The TypeScript a checker reads for one function body (`spec.md` §23.3).
+ *
+ * A body is the inside of a function, so no checker can read it alone: `return` is not allowed at
+ * the top of a file, and `state` is not declared anywhere. This module writes the file around it. A
+ * checker is handed {@link VirtualBody.text}, finds its errors there, and {@link bodyOffsetOf} puts
+ * each one back at its place in the body the author wrote. The body is copied into the file
+ * verbatim, so that mapping is a single shift and cannot drift.
+ *
+ * It is pure and has no dependency on a compiler, a DOM or Node, so every surface that checks types
+ * (Studio's editor, and later a mapper for `tsc`) reads the same file and cannot disagree about
+ * what a document's types are.
+ *
+ * **What `State` says is what the document can prove, and no more.** A literal gives its type, an
+ * object its shape and an array the types of its items. Anything a document does not determine (a
+ * `$prototype` instance, an `$expression`, a template, a `timing: "server"` call, a `null`) is
+ * `any`, because an error about code the author cannot fix teaches them to ignore the checker. What
+ * `State` does not declare is an error: `state.nope = 1` is the case this exists to catch.
+ *
+ * @docs framework/concepts/functions
+ */
+import { isJsonObject } from "../guards";
+import {
+  boundEvents,
+  eventLines,
+  eventType,
+  itemType,
+  EXCEPT,
+  heritageOf,
+  membersOf,
+  readsRow,
+  rootSite,
+  siteInto,
+} from "./document-scopes";
+import type { Site, StateScope } from "./document-scopes";
+import { definitionParts, definitionsOf, pointerInto, propertyName, written } from "./schema-types";
+import { declaredParameters, stateIndex, typeOfEntry } from "./state-types";
+import type { OutsideState } from "./state-types";
+import type { JsonObject, JsonValue, JxElement } from "../../types";
+
+export { givenByProject, outsideAt } from "./state-types";
+export type { OutsideState, ProjectGives } from "./state-types";
+
+/** Where a body sits in a document. */
+export type VirtualTarget =
+  | {
+      /** A `state` entry of the document root. */
+      kind: "state";
+      key: string;
+    }
+  | {
+      /** An inline `on*` handler on the element at `path`. */
+      kind: "event";
+      eventKey: string;
+      path: readonly (string | number)[];
+    };
+
+/** One body, wrapped for a checker. */
+export interface VirtualBody {
+  /** The file a checker reads. */
+  text: string;
+  /** Where the body's first character is in {@link VirtualBody.text}. */
+  bodyStart: number;
+  /** One past the body's last character in {@link VirtualBody.text}. */
+  bodyEnd: number;
+  /** The names the function is called with, as the runtime binds them. */
+  params: string[];
+}
+
+/**
+ * Diagnostic codes that say a module could not be found. A body is not a module: it cannot `import`
+ * statically, and a dynamic `import("x")` resolves in the browser, not in the checker, so an
+ * unresolved specifier is not something the author can fix from here (`studio.md` §16.7).
+ */
+export const UNRESOLVED_MODULE_CODES: ReadonlySet<number> = new Set([2307, 2792, 7016]);
+
+/** What a target names: the function entry, and what surrounds the element that holds it. */
+interface Located {
+  definition: JsonValue | undefined;
+  /** The type of the event the body is given. */
+  event: string;
+  site: Site;
+}
+
+/** Find a target in a document. */
+function locate(doc: JsonObject, target: VirtualTarget): Located {
+  let site = rootSite(doc);
+  if (target.kind === "state") {
+    const event = boundEvents(doc).get(pointerInto("/state", target.key)) ?? "any";
+    return { definition: isJsonObject(doc.state) ? doc.state[target.key] : undefined, event, site };
+  }
+  let owner: JsonValue | undefined = doc;
+  let pointer = "";
+  for (const segment of target.path) {
+    const child: JsonValue | undefined = Array.isArray(owner)
+      ? owner[Number(segment)]
+      : isJsonObject(owner)
+        ? owner[String(segment)]
+        : undefined;
+    pointer = pointerInto(pointer, segment);
+    site = siteInto(site, owner, segment, child, pointer);
+    owner = child;
+  }
+  return isJsonObject(owner)
+    ? { definition: owner[target.eventKey], event: eventType(owner, target.eventKey, site), site }
+    : { definition: undefined, event: "any", site };
+}
+
+/**
+ * Write the `State` a body reads: one interface for each element on the way down that has `state`,
+ * each under the one around it, and over them the row of the map the body is drawn in.
+ */
+function stateLines(site: Site, index: string, defs: boolean): string[] {
+  const chain: StateScope[] = [];
+  for (let at: StateScope | null = site.scope; at; at = at.parent) {
+    chain.unshift(at);
+  }
+  const inRow = site.row !== null && readsRow(site.scope);
+  // The innermost is `State` itself, unless the row is written over it.
+  const nameOf = (scope: StateScope): string =>
+    scope === site.scope && !inRow ? "State" : `State$${chain.indexOf(scope)}`;
+  // The helper is declared only where a scope reads through it: an unused one is a finding.
+  const lines: string[] = chain.some((scope) => membersOf(scope).shadowed.length > 0)
+    ? [EXCEPT]
+    : [];
+  for (const scope of chain) {
+    const { own, shadowed } = membersOf(scope);
+    const around = scope.parent ? nameOf(scope.parent) : null;
+    const heritage = around === null ? "" : ` extends ${heritageOf(around, shadowed)}`;
+    lines.push(`interface ${nameOf(scope)}${heritage} {`);
+    for (const { entry, key, role } of own) {
+      lines.push(`  ${propertyName(key)}: ${typeOfEntry(entry, role, defs)};`);
+    }
+    lines.push(...(around === null ? [`  ${index}`, "}"] : ["}"]));
+  }
+  if (site.row && inRow) {
+    lines.push(
+      `interface State extends ${nameOf(site.scope)} {`,
+      `  $map: { item: ${itemType(site.row, nameOf)}; index: number };`,
+      "}",
+    );
+  }
+  return lines;
+}
+
+/**
+ * Wrap one body for a checker.
+ *
+ * @param doc The document the body is in.
+ * @param target Which body: a root `state` entry, or an inline handler on an element.
+ * @param body The body's text, which need not be the text the document holds yet (an editor's
+ *   buffer is checked as typed).
+ * @param outside What the document's project gives it, which makes `State` open. Nothing, when the
+ *   reader knows of no project.
+ * @returns The file to check, and where the body sits in it.
+ */
+export function generateBodyTypes(
+  doc: JxElement,
+  target: VirtualTarget,
+  body: string,
+  outside: OutsideState = {},
+): VirtualBody {
+  // SAFETY: a document is JSON data; its types name what it holds.
+  const data = doc as JsonObject;
+  const located = locate(data, target);
+  const defs = definitionsOf(data);
+  const declared = declaredParameters(located.definition, { defs: defs !== null, pointer: "" });
+  const params = declared.map((parameter) => parameter.name);
+  /* The event a handler receives is bound to a name only when the entry declares one, though the
+     runtime passes it and `window.event` holds it. Not declaring it would call a working handler
+     an error, so it is declared wherever it is not a parameter. */
+  const event = eventLines(located.event, params);
+  /* A handler is called with its state and the event, in that order (`spec.md` §5.3), and a
+     parameter that declares a type is that type, the event's place included (§23.3). */
+  const signature = declared.map((parameter, at) => {
+    const untyped = at === 1 ? event.parameter : "any";
+    const type = parameter.type === null ? untyped : written(parameter.type);
+    return `${parameter.name}: ${at === 0 ? "State" : type}`;
+  });
+  const head = [
+    "export {};",
+    ...(defs ? [written(definitionParts(defs, false))] : []),
+    ...stateLines(located.site, stateIndex(doc, outside), defs !== null),
+    `${event.head}async function body(${["this: any", ...signature].join(", ")}) {`,
+    "",
+  ].join("\n");
+  return {
+    bodyEnd: head.length + body.length,
+    bodyStart: head.length,
+    params,
+    text: `${head}${body}\n}\n`,
+  };
+}
+
+/**
+ * Where a position in {@link VirtualBody.text} is in the body, or null when it is outside it (the
+ * wrapper, which the author did not write).
+ *
+ * @param unit The wrapped body.
+ * @param offset An offset in `unit.text`.
+ * @returns An offset in the body, or null.
+ */
+export function bodyOffsetOf(unit: VirtualBody, offset: number): number | null {
+  return offset >= unit.bodyStart && offset <= unit.bodyEnd ? offset - unit.bodyStart : null;
+}

package/src/schema.ts

@@ -408,6 +408,28 @@ export async function generateSchema() {
         examples: ["./layouts/base.json"],
         oneOf: [{ type: "string" }, { const: false, type: "boolean" }],
       },
+      $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). " +

package/types.ts

@@ -385,6 +385,20 @@ export interface JxMappedArray {
   key?: JxRef;
 }
 
+/**
+ * A document's own modules, as `$script` holds them: TypeScript module text for each side.
+ *
+ * A type alias rather than an interface, because a document member has to be a `JxDocumentValue`,
+ * and only an alias is given the implicit index signature that makes an object type one.
+ */
+// oxlint-disable-next-line typescript/consistent-type-definitions -- See above.
+export type JxDocumentScripts = {
+  /** The module the browser runs. Its exports are what `$src: "#client"` entries name. */
+  client?: string;
+  /** The module the server runs. Its exports are what `$src: "#server"` entries name. */
+  server?: string;
+};
+
 export interface JxDocument extends JxElement {
   /**
    * The custom element's NAME, always a literal.
@@ -397,6 +411,8 @@ export interface JxDocument extends JxElement {
   tagName?: string;
   state?: Record<string, JxStateDefinition>;
   $layout?: string | false;
+  /** This document's own client and server modules (spec.md §23.2). */
+  $script?: JxDocumentScripts;
   /** This page's identity across languages, overriding the one its path implies (§13.5). */
   $translationKey?: string;
   $paths?: JxPathsDef;