@jxsuite/schema 0.28.5 → 0.30.1

package/defs/children-value.schema.ts

@@ -15,11 +15,19 @@ export const arrayNamespaceSchema = {
 } as const;
 
 export const childrenValueSchema = {
-  description: "Static array of child definitions, or an Array namespace for dynamic lists.",
+  description:
+    "Array of child definitions — elements, text, or Array namespaces (dynamic lists) mixed " +
+    "freely. A bare Array namespace (the whole children slot is one dynamic list) is also " +
+    "accepted for backward compatibility.",
   oneOf: [
     {
       items: {
-        oneOf: [{ $ref: "#/$defs/ElementDef" }, { type: "string" }, { type: "number" }],
+        oneOf: [
+          { $ref: "#/$defs/ElementDef" },
+          { $ref: "#/$defs/ArrayNamespace" },
+          { type: "string" },
+          { type: "number" },
+        ],
       },
       type: "array",
     },

package/package.json

@@ -1,8 +1,8 @@
 {
   "dependencies": {
-    "@webref/css": "^8.5.8",
+    "@webref/css": "^8.6.0",
     "@webref/elements": "^2.7.1",
-    "@webref/idl": "^3.81.0"
+    "@webref/idl": "^3.81.1"
   },
   "description": "JSON Schema 2020-12 meta-schema generator for Jx documents",
   "exports": {
@@ -39,7 +39,7 @@
     "upgrade": "bunx npm-check-updates -u && bun install"
   },
   "type": "module",
-  "version": "0.28.5",
+  "version": "0.30.1",
   "devDependencies": {
     "json-schema-to-ts": "^3.1.1"
   }

package/schema.json

@@ -4665,7 +4665,7 @@
       "type": "object"
     },
     "ChildrenValue": {
-      "description": "Static array of child definitions, or an Array namespace for dynamic lists.",
+      "description": "Array of child definitions — elements, text, or Array namespaces (dynamic lists) mixed freely. A bare Array namespace (the whole children slot is one dynamic list) is also accepted for backward compatibility.",
       "oneOf": [
         {
           "items": {
@@ -4673,6 +4673,9 @@
               {
                 "$ref": "#/$defs/ElementDef"
               },
+              {
+                "$ref": "#/$defs/ArrayNamespace"
+              },
               {
                 "type": "string"
               },

package/src/guards.ts

@@ -126,6 +126,18 @@ export function isMappedArray(value: unknown): value is JxMappedArray {
   return isJsonObject(value) && value.$prototype === "Array";
 }
 
+/**
+ * Whether a node's `children` holds at least one mapped array — either as the bare whole-children
+ * slot (legacy) or as a member of the children array. Used by renderers and the compiler to decide
+ * if a children list needs inline repeater expansion.
+ */
+export function childrenContainArray(children?: unknown): boolean {
+  if (isMappedArray(children)) {
+    return true;
+  }
+  return Array.isArray(children) && children.some((c) => isMappedArray(c));
+}
+
 /** A .class.json schema-defined class document — `{ $prototype: "Class" }`. */
 export function isClassDef(value: unknown): value is JxClassDef {
   return isJsonObject(value) && value.$prototype === "Class";

package/src/schema.ts

@@ -96,7 +96,24 @@ import { projectConfigSchema } from "../defs/project-config.schema";
 
 // ─── Web standards data loader ────────────────────────────────────────────────
 
-async function loadWebData() {
+let webDataCache: Promise<{
+  cssProps: string[];
+  eventHandlers: string[];
+  tagExamples: string[];
+}> | null = null;
+
+/**
+ * Web-standards parsing (WebIDL / CSS / HTML elements) is expensive and the data is static for the
+ * Process, so memoize it. generateSchema runs several times across a build or test run, and
+ * Re-parsing on each call made the validateDocument / CLI tests load-sensitive (occasionally past
+ * The 5s test timeout under full-suite CPU contention).
+ */
+function loadWebData() {
+  webDataCache ??= computeWebData();
+  return webDataCache;
+}
+
+async function computeWebData() {
   const [elementsData, cssData, idlData] = await Promise.all([
     listElements(),
     css.listAll(),
@@ -487,13 +504,30 @@ export async function generateSchemaString() {
   return JSON.stringify(await generateSchema(), null, 2);
 }
 
+// Minimal structural types for the optional `ajv` / `ajv-formats` peer deps
+// (no direct dependency, and shipping no types usable from here).
+interface AjvValidateFn {
+  (doc: unknown): boolean;
+  errors?: unknown[] | null;
+}
+interface AjvInstance {
+  compile: (schema: unknown) => AjvValidateFn;
+}
+type AjvCtor = new (opts: {
+  allErrors: boolean;
+  ownProperties: boolean;
+  strict: boolean;
+}) => AjvInstance;
+type AddFormatsFn = (ajv: AjvInstance) => void;
+
 export async function validateDocument(doc: Record<string, unknown>) {
-  let Ajv, addFormats;
+  let Ajv: AjvCtor, addFormats: AddFormatsFn;
   try {
+    // The generated schema is JSON Schema 2020-12, so use the matching Ajv build
+    // (the default `ajv` export is draft-07 and can't compile a 2020-12 schema).
+    ({ default: Ajv } = (await import("ajv/dist/2020")) as { default: AjvCtor });
     // @ts-expect-error — optional peer dependency
-    ({ default: Ajv } = await import("ajv"));
-    // @ts-expect-error — optional peer dependency
-    ({ default: addFormats } = await import("ajv-formats"));
+    ({ default: addFormats } = (await import("ajv-formats")) as { default: AddFormatsFn });
   } catch {
     throw new Error("Schema validation requires ajv and ajv-formats: bun add ajv ajv-formats");
   }
@@ -510,11 +544,11 @@ export async function validateDocument(doc: Record<string, unknown>) {
 
 // ─── CLI ──────────────────────────────────────────────────────────────────────
 
-if (process.argv[1] && process.argv[1].endsWith("schema.ts")) {
+async function runSchemaCli() {
   const { writeFileSync } = await import("node:fs");
   const { resolve, dirname } = await import("node:path");
 
-  const schemaDir = dirname(resolve(process.argv[1], ".."));
+  const schemaDir = dirname(resolve(process.argv[1] as string, ".."));
 
   const componentSchema = await generateSchema();
   const projectSchema = generateProjectSchema();
@@ -539,3 +573,9 @@ if (process.argv[1] && process.argv[1].endsWith("schema.ts")) {
     console.error("  class-schema.json");
   }
 }
+
+// Runs when invoked as a script or driven by a test that stages argv[1]. The build lives in an async
+// Function rather than a top-level await: Bun's test runtime drops a dynamically-imported module's
+// Top-level-await continuation on Windows. `ready` lets tests await the same sequence.
+// oxlint-disable-next-line unicorn/prefer-top-level-await
+export const ready = process.argv[1]?.endsWith("schema.ts") ? runSchemaCli() : undefined;

package/types.ts

@@ -198,6 +198,13 @@ export interface JxElement {
   tagName?: string;
   textContent?: string | null | JxRef;
   innerHTML?: string;
+  /**
+   * Child nodes. A repeater (`{ $prototype: "Array", … }`) may appear as a member of the array —
+   * nestled among siblings or as the sole child — and is structurally a `JxElement` (its
+   * `items`/`map`/`filter`/`sort` are absorbed by the open index signature; narrow with
+   * `isMappedArray`). The bare `| JxMappedArray` form (whole children slot is one repeater) is
+   * retained for backward compatibility with legacy docs.
+   */
   children?: (JxElement | string)[] | JxMappedArray;
   style?: JxStyle;
   attributes?: Record<string, JxAttributeValue>;
@@ -471,6 +478,12 @@ export interface JxMutableNode {
   tagName?: string;
   textContent?: string | null | JxRef;
   innerHTML?: string;
+  /**
+   * Child nodes. The editor models a mapped-array (repeater) member as a `JxMutableNode` carrying
+   * `$prototype: "Array"` (plus `items`/`map`/`filter`/`sort` below), so members stay assignable
+   * here. The bare `| JxMappedArray` form (whole children slot is one repeater) is retained for
+   * backward compatibility.
+   */
   children?: (JxMutableNode | string)[] | JxMappedArray;
   style?: JxStyle;
   attributes?: Record<string, JxAttributeValue>;