@jxsuite/schema 1.2.0 → 1.3.0

package/schemas/project.core.schema.json

@@ -105,6 +105,24 @@
       },
       "required": ["$ref"],
       "type": "object"
+    },
+    "StyleObject": {
+      "additionalProperties": {
+        "oneOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "number"
+          },
+          {
+            "$ref": "#/$defs/StyleObject"
+          }
+        ]
+      },
+      "description": "CSS style definition. camelCase property names follow CSSOM convention. Keys starting with :, ., &, or [ are treated as nested CSS selectors. Keys matching $media breakpoint names (or other @-prefixed at-rules) group nested rules. Nesting is recursive: selector and at-rule groups may nest to arbitrary depth (e.g. breakpoint → selector → pseudo-class), mirroring the compiler's recursive emission.",
+      "properties": {},
+      "type": "object"
     }
   },
   "$id": "https://jxsuite.com/schema/project/core/v2",
@@ -366,11 +384,11 @@
             "type": "number"
           },
           {
-            "type": "object"
+            "$ref": "#/$defs/StyleObject"
           }
         ]
       },
-      "description": "Global CSS styles applied to the <body> element. Uses the same camelCase CSSOM convention as component styles.",
+      "description": "Global CSS styles applied to the <body> element. Uses the same camelCase CSSOM convention and recursive selector/at-rule nesting as component styles.",
       "type": "object"
     },
     "url": {

package/src/guards.ts

@@ -174,6 +174,16 @@ export function isTemplateString(value?: unknown): value is string {
   return typeof value === "string" && value.includes("${");
 }
 
+/**
+ * Whether a function `body` returns a value — the heuristic that classifies a `$prototype:
+ * "Function"` as a computed value vs an event handler. Uses a word boundary so identifiers like
+ * `returned` do not match. Shared by the runtime interpreter and the compiler so both agree on the
+ * classification.
+ */
+export function bodyReturnsValue(body: string): boolean {
+  return /\breturn\b/.test(body);
+}
+
 // ─── Style guards & accessors ───────────────────────────────────────────────────
 
 /** A nested style object (selector/media block), as opposed to a scalar CSS value. */

package/src/schema.ts

@@ -92,7 +92,10 @@ import {
   classFieldDefSchema,
   classMethodDefSchema,
   classParameterDefSchema,
+  connectorBlockDefSchema,
   formatDefSchema,
+  projectBlockDefSchema,
+  serverBlockDefSchema,
   studioHintsSchema,
 } from "../defs/class-def.schema";
 import { extensionManifestSchema } from "../defs/extension-manifest.schema";
@@ -182,7 +185,11 @@ function buildEventHandlerProperties(eventHandlers: string[]) {
   for (const name of eventHandlers) {
     properties[name] = {
       description: `Event handler for the "${name.slice(2)}" event.`,
-      oneOf: [{ $ref: "#/$defs/RefObject" }, { $ref: "#/$defs/ExpressionEntry" }],
+      oneOf: [
+        { $ref: "#/$defs/RefObject" },
+        { $ref: "#/$defs/ExpressionEntry" },
+        { $ref: "#/$defs/FunctionDef" },
+      ],
     };
   }
   return properties;
@@ -216,6 +223,9 @@ export async function generateSchema() {
       ClassConstructorDef: classConstructorDefSchema,
       ClassMethodDef: classMethodDefSchema,
       FormatDef: formatDefSchema,
+      ProjectBlockDef: projectBlockDefSchema,
+      ServerBlockDef: serverBlockDefSchema,
+      ConnectorBlockDef: connectorBlockDefSchema,
       StudioHints: studioHintsSchema,
       ExternalClassDef: externalClassDefSchema,
       ExpressionPointer: expressionPointerSchema,
@@ -415,6 +425,7 @@ export function generateProjectSchema() {
   return {
     $defs: {
       ImageConfig: imageConfigSchema,
+      StyleObject: styleObjectSchema,
     },
     $id: "https://jxsuite.com/schema/project/v1",
     $schema: "https://json-schema.org/draft/2020-12/schema",
@@ -446,6 +457,7 @@ export function generateProjectCoreSchema() {
       ImageConfig: imageConfigSchema,
       JxFieldSchema: jxFieldSchemaDef,
       RelationshipRef: relationshipRefSchema,
+      StyleObject: styleObjectSchema,
     },
     $id: "https://jxsuite.com/schema/project/core/v2",
     $schema: "https://json-schema.org/draft/2020-12/schema",
@@ -514,7 +526,10 @@ export function generateClassSchema() {
       ClassFieldDef: classFieldDefSchema,
       ClassMethodDef: classMethodDefSchema,
       ClassParameterDef: classParameterDefSchema,
+      ConnectorBlockDef: connectorBlockDefSchema,
       FormatDef: formatDefSchema,
+      ProjectBlockDef: projectBlockDefSchema,
+      ServerBlockDef: serverBlockDefSchema,
       StudioHints: studioHintsSchema,
     },
     $id: "https://jxsuite.com/schema/class/v1",
@@ -565,6 +580,7 @@ export function generateClassSchema() {
       },
       $schema: { type: "string" },
       $studio: { $ref: "#/$defs/StudioHints" },
+      connector: { $ref: "#/$defs/ConnectorBlockDef" },
       description: { type: "string" },
       extends: {
         description: "Base class — string name or $ref to another .class.json.",
@@ -579,6 +595,8 @@ export function generateClassSchema() {
         ],
       },
       format: { $ref: "#/$defs/FormatDef" },
+      project: { $ref: "#/$defs/ProjectBlockDef" },
+      server: { $ref: "#/$defs/ServerBlockDef" },
       title: {
         description: "PascalCase class name, used as the export name.",
         examples: ["MarkdownFile", "DataSource", "Calculator"],
@@ -613,7 +631,19 @@ type AjvCtor = new (opts: {
 }) => AjvInstance;
 type AddFormatsFn = (ajv: AjvInstance) => void;
 
-export async function validateDocument(doc: Record<string, unknown>) {
+/**
+ * Validate a document against an arbitrary JSON Schema 2020-12 document (e.g. a bundled per-project
+ * document.schema.json from `jx schema`). The schema must be self-contained — external refs are not
+ * resolved here.
+ *
+ * @param {Record<string, unknown>} doc - The document to validate
+ * @param {Record<string, unknown>} schema - A self-contained 2020-12 schema
+ * @returns {Promise<{ errors: unknown[] | null; valid: boolean }>}
+ */
+export async function validateWithSchema(
+  doc: Record<string, unknown>,
+  schema: Record<string, unknown>,
+) {
   let Ajv: AjvCtor, addFormats: AddFormatsFn;
   try {
     // The generated schema is JSON Schema 2020-12, so use the matching Ajv build
@@ -628,13 +658,21 @@ export async function validateDocument(doc: Record<string, unknown>) {
   const ajv = new Ajv({ allErrors: true, ownProperties: true, strict: false });
   addFormats(ajv);
 
-  const schema = await generateSchema();
   const validate = ajv.compile(schema);
   const valid = validate(doc);
 
   return { errors: validate.errors ?? null, valid };
 }
 
+export async function validateDocument(doc: Record<string, unknown>) {
+  return validateWithSchema(doc, (await generateSchema()) as Record<string, unknown>);
+}
+
+/** Validate a .class.json class definition against the generated class schema. */
+export async function validateClass(doc: Record<string, unknown>) {
+  return validateWithSchema(doc, generateClassSchema() as Record<string, unknown>);
+}
+
 // ─── CLI ──────────────────────────────────────────────────────────────────────
 
 async function runSchemaCli() {

package/src/validate-project.ts

@@ -133,6 +133,19 @@ async function loadProjectSchemaRef(uri: string, root: string): Promise<Record<s
       const selfRequire = createRequire(import.meta.url);
       resolved = selfRequire.resolve(specifier);
     } catch (error) {
+      // Exports-map subpath resolution is brittle against version-skewed shadowing installs (a
+      // Stale local copy terminates Node's walk-up with ERR_PACKAGE_PATH_NOT_EXPORTED). Our own
+      // Schema files are pure data and the running validator's copy is guaranteed to match, so
+      // Read them straight off this package's disk as the last resort.
+      const ownPrefix = "@jxsuite/schema/";
+      if (specifier.startsWith(ownPrefix)) {
+        const ownFile = fileURLToPath(
+          new URL(`../${specifier.slice(ownPrefix.length)}`, import.meta.url),
+        );
+        if (existsSync(ownFile)) {
+          return JSON.parse(readFileSync(ownFile, "utf8")) as Record<string, unknown>;
+        }
+      }
       throw new Error(
         `Schema ref "${uri}" does not exist and "${specifier}" is not resolvable from the ` +
           `project or the host`,