@jxsuite/schema 2.0.0 → 2.2.0

package/src/asset-paths.ts

@@ -538,3 +538,89 @@ export function formatSrcset(candidates: readonly SrcsetCandidate[]): string {
     .map(({ url, descriptor }) => (descriptor ? `${url} ${descriptor}` : url))
     .join(", ");
 }
+
+// ─── Deployment base path (RFC 3986 §5) ──────────────────────────────────────
+
+/**
+ * The path a site is deployed under, derived from `project.json`'s `url`.
+ *
+ * **There is no second key for this, on purpose.** Every URL the build emits is a URI reference,
+ * and `url` is the base URI it is resolved against (RFC 3986 §5). A site at
+ * `https://example.pages.dev/m/my-site/` has already said where it lives; a `build.base` beside it
+ * would be a second writer on one fact, free to disagree with the canonical links and the sitemap
+ * that are built from the same value.
+ *
+ * What went wrong was narrower than a missing option: the compiler resolved its references against
+ * the base's ORIGIN and discarded its path, which is what §5.2 does to an absolute-path reference
+ * (`/assets/x.js`) and is not what a deployment means by one. So the fix is to stop discarding it.
+ *
+ * Returns `""` for a site at an origin root, a missing `url`, or a `url` that will not parse — all
+ * three mean "prefix nothing", and a malformed URL must not take the build down when the only thing
+ * it can affect is a prefix. Never has a trailing slash, so `base + "/assets/x"` is well-formed.
+ *
+ * @param {string | undefined} url - `project.json`'s `url`
+ * @returns {string} `""` or a path with a leading slash and no trailing one
+ */
+export function siteBasePath(url: string | undefined | null): string {
+  if (typeof url !== "string" || url === "") {
+    return "";
+  }
+  let pathname: string;
+  try {
+    ({ pathname } = new URL(url));
+  } catch {
+    return "";
+  }
+  const trimmed = pathname.replace(/\/+$/, "");
+  if (trimmed === "" || trimmed === "/") {
+    return "";
+  }
+  return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+
+/**
+ * Re-root a site-absolute URL onto the deployment base.
+ *
+ * Only an absolute-path reference is affected — the one form whose meaning is "from the site root",
+ * and therefore the one form that moves when the site root does. A protocol-relative `//host/x`, an
+ * absolute URL, a fragment, a query and every relative path already resolve against something else
+ * and are returned untouched.
+ *
+ * **Idempotent**, because a URL may reach this more than once: an emitter that already prefixed and
+ * an output pass that prefixes everything must not compound. A value already under the base is
+ * returned as-is.
+ *
+ * @param {string} base - From {@link siteBasePath}
+ * @param {string} url - A URL as emitted
+ * @returns {string} The URL a browser should be given
+ */
+export function withBase(base: string, url: string): string {
+  if (base === "" || !url.startsWith("/") || url.startsWith("//")) {
+    return url;
+  }
+  if (url === base || url.startsWith(`${base}/`)) {
+    return url;
+  }
+  return base + url;
+}
+
+/**
+ * An absolute URL for a site route, keeping the base's path.
+ *
+ * `new URL("/about", "https://x.dev/m/site/")` is `https://x.dev/about` — RFC 3986 §5.2 replaces
+ * the whole path for an absolute-path reference, which is exactly right for the RFC and exactly
+ * wrong for a canonical link. Resolving the route as a RELATIVE-path reference keeps the base, so
+ * `<link rel="canonical">`, `sitemap.xml` and `robots.txt` name pages that exist.
+ *
+ * @param {string} route - A site route (`/about`), leading slash optional
+ * @param {string} siteUrl - `project.json`'s `url`
+ * @returns {string} The absolute URL
+ */
+export function siteAbsoluteUrl(route: string, siteUrl: string): string {
+  const base = new URL(siteUrl);
+  // A base whose path does not end in "/" would drop its last segment under §5.2's merge.
+  if (!base.pathname.endsWith("/")) {
+    base.pathname += "/";
+  }
+  return new URL(route.replace(/^\/+/, ""), base).href;
+}

package/src/dialogs.ts

@@ -0,0 +1,428 @@
+/**
+ * Dialog and invoker-command rules — the second half of the overlay lint (spec §8.7).
+ *
+ * `overlays.ts` judges `popover` and `popovertarget`. This module judges the other two things the
+ * platform gives a document for overlays: a `<dialog>`, opened modally with `showModal()` and
+ * closed by Escape or a `close` command, and the **invoker commands** — `command` and `commandfor`
+ * on a `<button>` — that open and close either kind without a line of script. The rules share one
+ * shape and one walker with the popover rules, so a document report can file both under one source
+ * and a repair can address a node by the same path.
+ *
+ * Every rule encodes a fact about the platform that is easy to get wrong and hard to see:
+ *
+ * - `commandfor` and `command` come from `HTMLButtonElement` and nowhere else — not `<input>`, which
+ *   `popovertarget` does allow — so on any other element they parse and do nothing.
+ * - `command` is an enumerated attribute: a value that is not one of the built-in keywords and does
+ *   not start with `--` is invalid, and an invalid value makes the button do nothing.
+ * - `show-modal`, `close` and `request-close` act on a dialog; the three `*-popover` commands act on
+ *   a popover. A command aimed at the other kind is silently ignored.
+ * - A `--custom` command is a `CommandEvent` the target must answer; with no `oncommand` handler
+ *   there, the click does nothing.
+ * - `closedby` is enumerated too: `any`, `closerequest` or `none`.
+ * - A modal dialog that closes on nothing — `closedby="none"` and no close button inside — traps the
+ *   reader, because a modal makes the rest of the page inert.
+ * - A closed dialog is hidden by the browser's own `dialog:not([open]) { display: none }`, which is
+ *   UA-origin, so an author `display` in the base rule shows it on every page. Same defect as a
+ *   popover's, same repair: the `display` belongs in the open rule.
+ */
+import { getNestedStyle } from "./guards.ts";
+import {
+  attrs,
+  idOf,
+  isPopover,
+  labelOf,
+  literalAttr,
+  popoverIdsIn,
+  scalar,
+  tagOf,
+  walk,
+} from "./overlays.ts";
+
+import type { OverlayScope, PopoverPath } from "./overlays.ts";
+import type { JxElement, JxStyle } from "../types.ts";
+
+/**
+ * The built-in invoker commands.
+ *
+ * The six the HTML standard defines for popovers and dialogs. Anything else the button does not
+ * understand — unless it starts with `--`, which is a custom command the target answers itself.
+ */
+export const INVOKER_COMMANDS = [
+  "toggle-popover",
+  "show-popover",
+  "hide-popover",
+  "show-modal",
+  "close",
+  "request-close",
+] as const;
+
+/** The commands that act on a `<dialog>`. */
+export const DIALOG_COMMANDS: ReadonlySet<string> = new Set([
+  "show-modal",
+  "close",
+  "request-close",
+]);
+
+/** The commands that act on a popover. */
+export const POPOVER_COMMANDS: ReadonlySet<string> = new Set([
+  "toggle-popover",
+  "show-popover",
+  "hide-popover",
+]);
+
+/** The values `closedby` takes. */
+export const DIALOG_CLOSEDBY = ["any", "closerequest", "none"] as const;
+
+/**
+ * Only a `<button>` carries `command` and `commandfor` (`HTMLButtonElement`, and no other
+ * interface).
+ */
+export const COMMAND_INVOKER_TAGS: ReadonlySet<string> = new Set(["button"]);
+
+/** Every rule this module can report. */
+export type DialogRule =
+  | "invoker-not-button"
+  | "command-invalid"
+  | "command-target-missing"
+  | "command-target-mismatch"
+  | "custom-command-unhandled"
+  | "dialog-closedby-invalid"
+  | "dialog-no-invoker"
+  | "modal-without-close"
+  | "dialog-display";
+
+/**
+ * The mechanical repair a finding can carry: `display` moves into the open rule, `invoker` removes
+ * the two attributes.
+ */
+export type DialogFix = "display" | "invoker";
+
+export interface DialogDefect {
+  rule: DialogRule;
+  path: PopoverPath;
+  message: string;
+  detail: string;
+  severity: "error" | "warn";
+  fix?: DialogFix;
+}
+
+const DOCS = "See docs/framework/concepts/overlays.";
+
+/** Whether the node is a `<dialog>`. */
+export function isDialog(node: JxElement): boolean {
+  return tagOf(node) === "dialog";
+}
+
+/** Whether the value is a custom command. */
+function isCustomCommand(command: string): boolean {
+  return command.startsWith("--");
+}
+
+/** Every `id` in the document that belongs to a `<dialog>`, in document order. */
+export function dialogIdsIn(doc: JxElement): string[] {
+  const ids: string[] = [];
+  for (const { node } of walk(doc)) {
+    const id = idOf(node);
+    if (isDialog(node) && id !== null && !ids.includes(id)) {
+      ids.push(id);
+    }
+  }
+  return ids;
+}
+
+/** Whether the document holds a `<dialog>` at all — what a "show dialog" verb's enablement asks. */
+export function documentHasDialog(doc: JxElement): boolean {
+  for (const { node } of walk(doc)) {
+    if (isDialog(node)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/** Whether a node declares an `oncommand` handler, in any of the handler spellings. */
+function handlesCommand(node: JxElement): boolean {
+  const handler = (node as Record<string, unknown>).oncommand;
+  return handler !== undefined && handler !== null;
+}
+
+/**
+ * The buttons inside `node` whose command closes it, or closes the dialog they are in through a
+ * form.
+ */
+function hasCloseControl(dialog: JxElement, dialogId: string | null): boolean {
+  for (const { node } of walk(dialog)) {
+    if (node === dialog) {
+      continue;
+    }
+    const tag = tagOf(node);
+    if (tag === "button") {
+      const command = literalAttr(node, "command");
+      const target = literalAttr(node, "commandfor");
+      if (
+        command !== null &&
+        (command === "close" || command === "request-close") &&
+        (target === null || target === dialogId)
+      ) {
+        return true;
+      }
+    }
+    if (tag === "form" && literalAttr(node, "method")?.toLowerCase() === "dialog") {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Every dialog and invoker-command defect in a document, in document order.
+ *
+ * @param doc The document to check.
+ * @returns The defects, most structural first within each node.
+ */
+export function findDialogDefects(doc: JxElement, scope?: OverlayScope): DialogDefect[] {
+  const visits = [...walk(doc, [], null, scope)];
+  const dialogIds = dialogIdsIn(doc);
+  const popoverIds = popoverIdsIn(doc, scope);
+  const hasAnyTarget = dialogIds.length > 0 || popoverIds.length > 0;
+  const byId = new Map<string, JxElement>();
+  const targeted = new Map<string, Set<string>>();
+  for (const { node } of visits) {
+    const id = idOf(node);
+    if (id !== null && !byId.has(id)) {
+      byId.set(id, node);
+    }
+    if (tagOf(node) === "button") {
+      const target = literalAttr(node, "commandfor");
+      const command = literalAttr(node, "command");
+      if (target !== null) {
+        const commands = targeted.get(target) ?? new Set<string>();
+        commands.add(command ?? "");
+        targeted.set(target, commands);
+      }
+    }
+  }
+
+  const defects: DialogDefect[] = [];
+  for (const { node, path } of visits) {
+    defects.push(...invokerDefects(node, path, byId, dialogIds, popoverIds, hasAnyTarget, scope));
+    if (isDialog(node)) {
+      defects.push(...dialogDefects(node, path, targeted));
+    }
+  }
+  return defects;
+}
+
+/** The rules that judge a button carrying `command` or `commandfor`. */
+function invokerDefects(
+  node: JxElement,
+  path: PopoverPath,
+  byId: ReadonlyMap<string, JxElement>,
+  dialogIds: string[],
+  popoverIds: string[],
+  hasAnyTarget: boolean,
+  scope?: OverlayScope,
+): DialogDefect[] {
+  const out: DialogDefect[] = [];
+  const tag = tagOf(node);
+  const forwards = scope?.invokerTags?.has(tag) ?? false;
+  const command = literalAttr(node, "command");
+  const target = literalAttr(node, "commandfor");
+  const carries =
+    command !== null || target !== null || "command" in attrs(node) || "commandfor" in attrs(node);
+  if (!carries) {
+    return out;
+  }
+  const label = labelOf(node, "the element");
+
+  if (!COMMAND_INVOKER_TAGS.has(tag) && !forwards) {
+    out.push({
+      detail:
+        "`command` and `commandfor` are attributes of `HTMLButtonElement` and of no other " +
+        "interface — not even `<input>`, which `popovertarget` does allow. Elsewhere they parse " +
+        `and do nothing. Make it a <button>, or remove both attributes. ${DOCS}`,
+      fix: "invoker",
+      message: `<${tag || "element"}> carries command/commandfor, which only <button> supports.`,
+      path,
+      rule: "invoker-not-button",
+      severity: "error",
+    });
+    return out;
+  }
+
+  if (
+    command !== null &&
+    !(INVOKER_COMMANDS as readonly string[]).includes(command) &&
+    !isCustomCommand(command)
+  ) {
+    out.push({
+      detail:
+        `\`command\` is an enumerated attribute taking ${INVOKER_COMMANDS.map((c) => `\`${c}\``).join(", ")}, ` +
+        "or a custom command starting with `--`. Anything else is the invalid-value state, and a " +
+        `button in that state does nothing when clicked. ${DOCS}`,
+      message: `${label} declares command="${command}", which is not a built-in or --custom command.`,
+      path,
+      rule: "command-invalid",
+      severity: "error",
+    });
+    return out;
+  }
+
+  if (target !== null) {
+    const known = byId.get(target);
+    const targetsDialog = dialogIds.includes(target);
+    const targetsPopover = popoverIds.includes(target);
+    if (!known && hasAnyTarget) {
+      const names = [...dialogIds, ...popoverIds].map((id) => `"${id}"`).join(", ");
+      out.push({
+        detail:
+          `No element in this document has the id "${target}". The dialogs and popovers here are: ${names}. ` +
+          `A commandfor that names nothing does nothing, silently. ${DOCS}`,
+        message: `commandfor="${target}" names nothing in this document.`,
+        path,
+        rule: "command-target-missing",
+        severity: "error",
+      });
+      return out;
+    }
+    if (command !== null && known) {
+      if (DIALOG_COMMANDS.has(command) && !isDialog(known)) {
+        out.push({
+          detail:
+            `\`${command}\` acts on a <dialog>, and "${target}" is ${targetsPopover ? "a popover" : `a <${tagOf(known) || "element"}>`}. ` +
+            `The click is ignored. ${targetsPopover ? "Use `toggle-popover`, `show-popover` or `hide-popover` for a popover." : "Point it at a dialog, or make the target one."} ${DOCS}`,
+          message: `${label} sends ${command} to "${target}", which is not a dialog.`,
+          path,
+          rule: "command-target-mismatch",
+          severity: "error",
+        });
+      } else if (POPOVER_COMMANDS.has(command) && !isPopover(known, scope)) {
+        out.push({
+          detail:
+            `\`${command}\` acts on a popover, and "${target}" is ${targetsDialog ? "a dialog" : `a <${tagOf(known) || "element"}>`} that declares no \`popover\`. ` +
+            `The click is ignored. ${targetsDialog ? "Use `show-modal`, `close` or `request-close` for a dialog." : "Give the target a `popover` attribute, or point the button elsewhere."} ${DOCS}`,
+          message: `${label} sends ${command} to "${target}", which is not a popover.`,
+          path,
+          rule: "command-target-mismatch",
+          severity: "error",
+        });
+      } else if (isCustomCommand(command) && !handlesCommand(known)) {
+        out.push({
+          detail:
+            `A custom command is a \`CommandEvent\` dispatched at its target, and "${target}" has no ` +
+            "`oncommand` handler to answer it — so the click does nothing. Add one that switches on " +
+            `\`event#/command\`, or use a built-in command. ${DOCS}`,
+          message: `${label} sends ${command} to "${target}", which handles no command.`,
+          path,
+          rule: "custom-command-unhandled",
+          severity: "warn",
+        });
+      }
+    }
+  }
+  return out;
+}
+
+/** The rules that judge a `<dialog>` itself. */
+function dialogDefects(
+  node: JxElement,
+  path: PopoverPath,
+  targeted: ReadonlyMap<string, Set<string>>,
+): DialogDefect[] {
+  const out: DialogDefect[] = [];
+  const label = labelOf(node, "the dialog");
+  const id = idOf(node);
+  const { style } = node;
+
+  const closedby = literalAttr(node, "closedby");
+  if (closedby !== null && !(DIALOG_CLOSEDBY as readonly string[]).includes(closedby)) {
+    out.push({
+      detail:
+        "`closedby` is an enumerated attribute taking `any` (light dismiss and Escape), " +
+        "`closerequest` (Escape only, the default for a modal) or `none`. Anything else is the " +
+        `invalid-value default, \`auto\`, which is the same as leaving it out. ${DOCS}`,
+      message: `${label} declares closedby="${closedby}", which is not any, closerequest or none.`,
+      path,
+      rule: "dialog-closedby-invalid",
+      severity: "error",
+    });
+  }
+
+  if (scalar(style, "display") !== null) {
+    out.push({
+      detail:
+        "A closed dialog is hidden by the browser's own `dialog:not([open]) { display: none }`. " +
+        "That rule is UA-origin, so any author `display` beats it, and the dialog is laid out on " +
+        "every page whether or not anyone opened it. `display` belongs in the `&[open]` rule and " +
+        `nowhere else. ${DOCS}`,
+      fix: "display",
+      message: `${label} sets display in its base rule.`,
+      path,
+      rule: "dialog-display",
+      severity: "error",
+    });
+  }
+
+  const commands = id === null ? undefined : targeted.get(id);
+  const opened =
+    literalAttr(node, "open") !== null || attrs(node).open === true || node.open === true;
+  // Its own close button names it too, and closing is not opening.
+  if (id !== null && !commands?.has("show-modal") && !opened) {
+    out.push({
+      detail:
+        'No <button> in this document opens it with `command="show-modal"`. If it is opened from another ' +
+        "file or from a function that calls `showModal()`, this is fine; otherwise there is no " +
+        `way for a reader to open it. ${DOCS}`,
+      message: `${label} has no invoker in this document.`,
+      path,
+      rule: "dialog-no-invoker",
+      severity: "warn",
+    });
+  }
+
+  if (commands?.has("show-modal") && closedby === "none" && !hasCloseControl(node, id)) {
+    out.push({
+      detail:
+        "A modal dialog makes everything outside it inert, so the only ways out are the ones it " +
+        'offers: `closedby="none"` turns off Escape and light dismiss, and nothing inside it ' +
+        'closes it. A reader who opens it cannot leave. Add a <button command="close"> inside, or ' +
+        `drop \`closedby="none"\`. ${DOCS}`,
+      message: `${label} opens modally, closes on nothing, and has no close button.`,
+      path,
+      rule: "modal-without-close",
+      severity: "error",
+    });
+  }
+  return out;
+}
+
+export interface DialogDisplayRepair {
+  /** Properties to delete from the dialog's BASE rule. */
+  base: string[];
+  /** The `display` value to write into `&[open]`, or null when it already declares one. */
+  openDisplay: string | null;
+}
+
+/**
+ * The style edit that repairs a `dialog-display` finding: the base `display` moves into the open
+ * rule. Pure and returned as data, for the same reason `popoverDisplayRepair` is.
+ *
+ * @param style The dialog's own style object.
+ * @returns The properties to remove from the base rule and the value to write into `&[open]`, or
+ *   null when there is nothing to move.
+ */
+export function dialogDisplayRepair(style?: JxStyle): DialogDisplayRepair | null {
+  if (!style) {
+    return null;
+  }
+  const display = scalar(style, "display");
+  if (display === null) {
+    return null;
+  }
+  const existing =
+    getNestedStyle(style, "&[open]") ??
+    getNestedStyle(style, "[open]") ??
+    getNestedStyle(style, "&:open") ??
+    getNestedStyle(style, ":open");
+  return { base: ["display"], openDisplay: scalar(existing, "display") !== null ? null : display };
+}

package/src/format-registry.ts

@@ -12,11 +12,12 @@
 
 import { mediaTypeEssence, mediaTypeProblem } from "./media-type";
 
-export type FormatCapability = "parse" | "serialize" | "discover" | "load";
+export type FormatCapability = "parse" | "serialize" | "rewrite" | "discover" | "load";
 
 export const FORMAT_CAPABILITIES: readonly FormatCapability[] = [
   "parse",
   "serialize",
+  "rewrite",
   "discover",
   "load",
 ];
@@ -27,6 +28,13 @@ export const FORMAT_CAPABILITIES: readonly FormatCapability[] = [
  * asset emission (`emit`), `<head>` contribution (`head`), static asset mounts (`assets`),
  * server-mount (`mount`), and connector (`dialect`, `deploySchema`, `bindings`, `testConnection`)
  * roles.
+ *
+ * `rewrite` is the narrow sibling of `serialize`, and the two are not ranked: a format may declare
+ * either, both or neither. `serialize` says "this document round-trips through me"; `rewrite` says
+ * only "I can replace these authored values in my own source text and change nothing else". A
+ * load-only format — a CSV collection is read to load entries, never re-emitted as a document — can
+ * honestly promise the second and not the first, which is enough for a rename to repair a reference
+ * living inside it (specs/extensions.md §8).
  */
 export type ExtensionCapability =
   | FormatCapability

package/src/guards.ts

@@ -192,9 +192,17 @@ export function bodyReturnsValue(body: string): boolean {
 
 // ─── Style guards & accessors ───────────────────────────────────────────────────
 
-/** A nested style object (selector/media block), as opposed to a scalar CSS value. */
-export function isNestedStyle(value: string | number | JxStyle | undefined): value is JxStyle {
-  return typeof value === "object" && value !== null;
+/**
+ * A nested style object (selector/media block), as opposed to a scalar CSS value.
+ *
+ * An ARRAY of blocks is not one: it is a key written more than once (`@font-face`, spec.md §9.4),
+ * and every caller here reads or edits a single block. Answering true for it would hand a caller an
+ * array to look properties up on, which finds nothing and reports nothing.
+ */
+export function isNestedStyle(
+  value: string | number | JxStyle | JxStyle[] | undefined,
+): value is JxStyle {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
 /** Read a nested style block (`:hover`, `@--md`, `& > li`, …), if present. */
@@ -243,9 +251,39 @@ export function paramNames(parameters: JxFunctionDef["parameters"]): string[] {
   return parameters.map((p) => (typeof p === "string" ? p : p.name));
 }
 
-/** Whether an element's `tagName` is a choice rather than a name. */
+/**
+ * Whether an element's `tagName` is a choice rather than a name.
+ *
+ * **It reads the WHOLE shape, because it promises the whole shape.**
+ * `defs/tag-expression.schema.ts` admits exactly two forms — `?:` with a `TagName` in `value` and
+ * `initial`, and `switch` with a `TagName` per case and a required `default` — and this predicate
+ * is the only thing standing between that promise and the four readers who trust it
+ * ({@link tagNameCandidates}, the runtime's `resolveTagName`, the compiler's `resolveStaticTagName`
+ * and its two target emitters). Answering `true` for any `{ $expression: … }` at all was the
+ * unsound half: a general formula in tag position — which the Inspector's Tag row let a user pick
+ * out of the formula catalog — then reached `Object.values(expression.cases)` with no `cases` to
+ * read, and `Cannot convert undefined or null to object` came out of the Command Bar, the jump bar,
+ * the Inspector and the canvas renderer at once.
+ *
+ * A `$expression` this refuses is not a tag choice, so it has no candidates and no static tag; the
+ * readers fall back to their own "nothing declared" answer (`[]`, `"div"`) instead of throwing.
+ */
 export function isTagExpression(tagName: unknown): tagName is { $expression: JxTagExpression } {
-  return isJsonObject(tagName) && isJsonObject(tagName.$expression);
+  if (!isJsonObject(tagName) || !isJsonObject(tagName.$expression)) {
+    return false;
+  }
+  const expression = tagName.$expression;
+  if (expression.operator === "?:") {
+    return typeof expression.value === "string" && typeof expression.initial === "string";
+  }
+  if (expression.operator === "switch") {
+    return (
+      isJsonObject(expression.cases) &&
+      Object.values(expression.cases).every((tag) => typeof tag === "string") &&
+      typeof expression.default === "string"
+    );
+  }
+  return false;
 }
 
 /**