@jxsuite/schema 3.0.0 → 4.1.0

package/src/component-meta.ts

@@ -14,21 +14,23 @@
  * @license MIT
  */
 
-import type { JsonValue } from "../types";
+import { isJsonObject, isNonNullObject, isNumber, isString } from "./guards";
+import type { JsonObject, JsonValue } from "../types";
 
 /** One `<slot>` found in a component's tree. */
 export interface ComponentSlotDef {
   /** The slot's name; `""` for the unnamed slot. */
   name: string;
   /** Fallback children rendered when nothing is slotted in. */
-  fallback?: unknown[];
+  fallback?: JsonValue[];
 }
 
 /** One editable prop, derived from a `state` entry. */
 export interface ComponentPropDef {
   name: string;
   type?: unknown;
-  default?: JsonValue;
+  /** Absent for a full-form entry that declares no `default`. */
+  default?: JsonValue | undefined;
   format?: unknown;
 }
 
@@ -40,6 +42,12 @@ export interface ComponentMetaOut {
   props: ComponentPropDef[];
   slots?: ComponentSlotDef[];
   hasElements: boolean;
+  /**
+   * The custom-element tags its own tree renders, sorted; absent when there are none. A component
+   * written against the project's other components by bare `tagName` declares no `$elements`, so
+   * this is how a live renderer learns what one instance pulls in without fetching the definition.
+   */
+  uses?: string[];
 }
 
 /**
@@ -48,27 +56,29 @@ export interface ComponentMetaOut {
  * Whitespace-only names count as unnamed (`""`), and only static `children` arrays are walked — a
  * slot produced by a `$map` or a `$switch` has no fixed identity to report.
  *
- * @param {unknown} node - A node of the component document.
+ * @param {JsonValue | undefined} node - A node of the component document.
  * @param {ComponentSlotDef[]} [out] - Accumulator, for the recursive walk.
  * @returns {ComponentSlotDef[]}
  */
-export function collectSlotDefs(node: unknown, out: ComponentSlotDef[] = []): ComponentSlotDef[] {
-  if (!node || typeof node !== "object" || Array.isArray(node)) {
+export function collectSlotDefs(
+  node: JsonValue | undefined,
+  out: ComponentSlotDef[] = [],
+): ComponentSlotDef[] {
+  if (!isJsonObject(node)) {
     return out;
   }
-  const el = node as Record<string, unknown>;
-  if (el.tagName === "slot") {
-    const attrs = el.attributes as Record<string, unknown> | undefined;
-    const rawName = attrs?.name;
-    const name = typeof rawName === "string" ? rawName.trim() : "";
-    const { children } = el;
-    out.push({
-      name,
-      ...(Array.isArray(children) && children.length > 0 ? { fallback: children } : {}),
-    });
+  const { children } = node;
+  if (node.tagName === "slot") {
+    const attrs = node.attributes;
+    const rawName = isJsonObject(attrs) ? attrs.name : undefined;
+    const slot: ComponentSlotDef = { name: isString(rawName) ? rawName.trim() : "" };
+    if (Array.isArray(children) && children.length > 0) {
+      slot.fallback = children;
+    }
+    out.push(slot);
   }
-  if (Array.isArray(el.children)) {
-    for (const c of el.children) {
+  if (Array.isArray(children)) {
+    for (const c of children) {
       collectSlotDefs(c, out);
     }
   }
@@ -76,24 +86,76 @@ export function collectSlotDefs(node: unknown, out: ComponentSlotDef[] = []): Co
 }
 
 /**
- * Whether a `state` entry is an editable prop.
+ * Every custom-element tag (a `tagName` with a hyphen) in a document tree, its root excluded.
+ *
+ * Walks every place a node can sit — `children`, a repeater's `map`, a `$switch`'s `cases` — since
+ * an instance rendered through any of them still needs its definition registered.
+ *
+ * @param {JsonValue | undefined} node - The document, or a node of it.
+ * @param {Set<string>} [out] - Accumulator, for the recursive walk.
+ * @returns {Set<string>}
+ */
+export function collectUsedTags(node: JsonValue | undefined, out = new Set<string>()): Set<string> {
+  if (!isJsonObject(node)) {
+    return out;
+  }
+  const visit = (child: JsonValue | undefined) => {
+    if (isJsonObject(child)) {
+      if (isString(child.tagName) && child.tagName.includes("-")) {
+        out.add(child.tagName);
+      }
+      collectUsedTags(child, out);
+    }
+  };
+  const { cases, children, map } = node;
+  const nodes = [...(Array.isArray(children) ? children : [children]), map];
+  if (isJsonObject(cases)) {
+    nodes.push(...Object.values(cases));
+  }
+  for (const child of nodes) {
+    visit(child);
+  }
+  return out;
+}
+
+/** What `typeof` names a shorthand `state` entry's value: the only type a shorthand has on offer. */
+function shorthandTypeName(value: string | number | boolean): "string" | "number" | "boolean" {
+  if (isString(value)) {
+    return "string";
+  }
+  return isNumber(value) ? "number" : "boolean";
+}
+
+/**
+ * The editable prop a `state` entry offers, or null when it is not one.
  *
  * The shorthand form (`"title": "Hello"`) always is. The full form is one only when it is plain
  * data: a computed value, a handler or a prototype entry is machinery the author does not type
  * into, and offering it as a prop would put a text box in front of a function.
  *
- * @param {unknown} def - The `state` entry.
- * @returns {boolean}
+ * @param {string} name - The `state` key.
+ * @param {JsonValue} def - The `state` entry.
+ * @returns {ComponentPropDef | null}
  */
-function isPropEntry(def: unknown): boolean {
+function propFrom(name: string, def: JsonValue): ComponentPropDef | null {
   if (def == null) {
-    return false;
+    return null;
+  }
+  if (!isNonNullObject(def)) {
+    // Shorthand: the value IS the default, and its runtime type is the only type on offer.
+    return { default: def, name, type: shorthandTypeName(def) };
   }
-  if (typeof def !== "object") {
-    return true;
+  // An array entry declares nothing, so it reads as a full-form entry with every field absent.
+  const fields: JsonObject = isJsonObject(def) ? def : {};
+  if (fields.$prototype || fields.$handler || fields.$compute) {
+    return null;
   }
-  const obj = def as Record<string, unknown>;
-  return !obj.$prototype && !obj.$handler && !obj.$compute;
+  return {
+    default: fields.default,
+    format: fields.format,
+    name,
+    type: fields.type,
+  };
 }
 
 /**
@@ -103,41 +165,47 @@ function isPropEntry(def: unknown): boolean {
  * hyphen. That single test is what keeps a page or a data file from being reported as a component
  * when a whole project tree is scanned.
  *
- * @param {unknown} doc - The parsed document.
+ * @param {JsonValue | undefined} doc - The parsed document.
  * @param {string} path - Project-relative path, reported verbatim.
  * @returns {ComponentMetaOut | null}
  */
-export function componentMetaFrom(doc: unknown, path: string): ComponentMetaOut | null {
-  if (!doc || typeof doc !== "object" || Array.isArray(doc)) {
+export function componentMetaFrom(
+  doc: JsonValue | undefined,
+  path: string,
+): ComponentMetaOut | null {
+  if (!isJsonObject(doc)) {
     return null;
   }
-  const content = doc as Record<string, unknown>;
-  const { tagName } = content;
-  if (typeof tagName !== "string" || !tagName.includes("-")) {
+  const { tagName } = doc;
+  if (!isString(tagName) || !tagName.includes("-")) {
     return null;
   }
-  const slots = collectSlotDefs(content);
-  const state = (content.state ?? {}) as Record<string, unknown>;
-  return {
-    $id: typeof content.$id === "string" && content.$id ? content.$id : null,
-    hasElements: Array.isArray(content.$elements) && content.$elements.length > 0,
+  const slots = collectSlotDefs(doc);
+  /*
+   * `state` is read the way `Object.entries` reads whatever is there: a malformed array or string
+   * yields its members, and a scalar or a missing entry yields nothing.
+   */
+  const declared = doc.state;
+  const state =
+    isJsonObject(declared) || Array.isArray(declared) || isString(declared)
+      ? Object.entries(declared)
+      : [];
+  // Everything before `tagName`, so `slots` lands where it always has in the serialized order.
+  const meta: Omit<ComponentMetaOut, "tagName"> = {
+    $id: isString(doc.$id) && doc.$id ? doc.$id : null,
+    hasElements: Array.isArray(doc.$elements) && doc.$elements.length > 0,
     path,
-    props: Object.entries(state)
-      .filter(([, def]) => isPropEntry(def))
-      .map(([name, def]) => {
-        if (typeof def !== "object" || def === null) {
-          // Shorthand: the value IS the default, and its runtime type is the only type on offer.
-          return { default: def as JsonValue, name, type: typeof def };
-        }
-        const obj = def as Record<string, unknown>;
-        return {
-          default: obj.default as JsonValue,
-          format: obj.format,
-          name,
-          type: obj.type,
-        };
-      }),
-    ...(slots.length > 0 ? { slots } : {}),
-    tagName,
+    props: state.flatMap(([name, def]) => {
+      const prop = propFrom(name, def);
+      return prop === null ? [] : [prop];
+    }),
   };
+  if (slots.length > 0) {
+    meta.slots = slots;
+  }
+  const uses = [...collectUsedTags(doc)].filter((tag) => tag !== tagName).toSorted();
+  if (uses.length > 0) {
+    meta.uses = uses;
+  }
+  return { ...meta, tagName };
 }

package/src/dialogs.ts

@@ -32,6 +32,7 @@ import {
   isPopover,
   labelOf,
   literalAttr,
+  OVERLAY_DOCS,
   popoverIdsIn,
   scalar,
   tagOf,
@@ -73,6 +74,12 @@ export const POPOVER_COMMANDS: ReadonlySet<string> = new Set([
 /** The values `closedby` takes. */
 export const DIALOG_CLOSEDBY = ["any", "closerequest", "none"] as const;
 
+/** {@link INVOKER_COMMANDS} as a lookup an attribute's literal text can be tested against. */
+const INVOKER_COMMAND_SET: ReadonlySet<string> = new Set(INVOKER_COMMANDS);
+
+/** {@link DIALOG_CLOSEDBY} as a lookup an attribute's literal text can be tested against. */
+const DIALOG_CLOSEDBY_SET: ReadonlySet<string> = new Set(DIALOG_CLOSEDBY);
+
 /**
  * Only a `<button>` carries `command` and `commandfor` (`HTMLButtonElement`, and no other
  * interface).
@@ -106,8 +113,6 @@ export interface DialogDefect {
   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";
@@ -142,7 +147,7 @@ export function documentHasDialog(doc: JxElement): boolean {
 
 /** 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;
+  const handler = node.oncommand;
   return handler !== undefined && handler !== null;
 }
 
@@ -240,7 +245,7 @@ function invokerDefects(
       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}`,
+        `and do nothing. Make it a <button>, or remove both attributes. ${OVERLAY_DOCS}`,
       fix: "invoker",
       message: `<${tag || "element"}> carries command/commandfor, which only <button> supports.`,
       path,
@@ -250,16 +255,12 @@ function invokerDefects(
     return out;
   }
 
-  if (
-    command !== null &&
-    !(INVOKER_COMMANDS as readonly string[]).includes(command) &&
-    !isCustomCommand(command)
-  ) {
+  if (command !== null && !INVOKER_COMMAND_SET.has(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}`,
+        `button in that state does nothing when clicked. ${OVERLAY_DOCS}`,
       message: `${label} declares command="${command}", which is not a built-in or --custom command.`,
       path,
       rule: "command-invalid",
@@ -277,7 +278,7 @@ function invokerDefects(
       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}`,
+          `A commandfor that names nothing does nothing, silently. ${OVERLAY_DOCS}`,
         message: `commandfor="${target}" names nothing in this document.`,
         path,
         rule: "command-target-missing",
@@ -290,7 +291,7 @@ function invokerDefects(
         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}`,
+            `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."} ${OVERLAY_DOCS}`,
           message: `${label} sends ${command} to "${target}", which is not a dialog.`,
           path,
           rule: "command-target-mismatch",
@@ -300,7 +301,7 @@ function invokerDefects(
         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}`,
+            `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."} ${OVERLAY_DOCS}`,
           message: `${label} sends ${command} to "${target}", which is not a popover.`,
           path,
           rule: "command-target-mismatch",
@@ -311,7 +312,7 @@ function invokerDefects(
           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}`,
+            `\`event#/command\`, or use a built-in command. ${OVERLAY_DOCS}`,
           message: `${label} sends ${command} to "${target}", which handles no command.`,
           path,
           rule: "custom-command-unhandled",
@@ -335,12 +336,12 @@ function dialogDefects(
   const { style } = node;
 
   const closedby = literalAttr(node, "closedby");
-  if (closedby !== null && !(DIALOG_CLOSEDBY as readonly string[]).includes(closedby)) {
+  if (closedby !== null && !DIALOG_CLOSEDBY_SET.has(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}`,
+        `invalid-value default, \`auto\`, which is the same as leaving it out. ${OVERLAY_DOCS}`,
       message: `${label} declares closedby="${closedby}", which is not any, closerequest or none.`,
       path,
       rule: "dialog-closedby-invalid",
@@ -354,7 +355,7 @@ function dialogDefects(
         "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}`,
+        `nowhere else. ${OVERLAY_DOCS}`,
       fix: "display",
       message: `${label} sets display in its base rule.`,
       path,
@@ -372,7 +373,7 @@ function dialogDefects(
       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}`,
+        `way for a reader to open it. ${OVERLAY_DOCS}`,
       message: `${label} has no invoker in this document.`,
       path,
       rule: "dialog-no-invoker",
@@ -386,7 +387,7 @@ function dialogDefects(
         "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}`,
+        `drop \`closedby="none"\`. ${OVERLAY_DOCS}`,
       message: `${label} opens modally, closes on nothing, and has no close button.`,
       path,
       rule: "modal-without-close",