@jxsuite/schema 0.35.0 → 1.1.0

package/defs/expression-node.schema.ts

@@ -1,9 +1,10 @@
 export const expressionPointerSchema = {
   additionalProperties: false,
-  description: "A JSON Pointer $ref operand within an expression node.",
+  description:
+    "A JSON Pointer $ref operand within an expression node. $args/<name> resolves a named formula's parameter (callable entries only).",
   properties: {
     $ref: {
-      pattern: "^(\\$map/|\\$reduce/|event#/|#/|parent#/|window#/|document#/)",
+      pattern: "^(\\$map/|\\$reduce/|\\$args/|event#/|#/|parent#/|window#/|document#/)",
       type: "string",
     },
   },
@@ -18,8 +19,14 @@ export const expressionLiteralSchema = {
     { type: "boolean" },
     { type: "null" },
     { items: { $ref: "#/$defs/ExpressionOperand" }, type: "array" },
+    {
+      description:
+        "Plain-object literal (e.g. an Intl options bag). Objects carrying $ref or operator keys are pointers/nodes, never literals.",
+      not: { anyOf: [{ required: ["$ref"] }, { required: ["operator"] }] },
+      type: "object",
+    },
   ],
-  description: "A non-reactive operand: scalar or array of operands.",
+  description: "A non-reactive operand: scalar, plain-object literal, or array of operands.",
 } as const;
 
 export const expressionOperandSchema = {
@@ -34,7 +41,47 @@ export const expressionOperandSchema = {
 
 export const unaryOperatorSchema = { enum: ["!", "-"] } as const;
 export const binaryOperatorSchema = {
-  enum: ["+", "-", "*", "/", "%", "===", "!==", "<", "<=", ">", ">=", "&&", "||"],
+  enum: ["+", "-", "*", "/", "%", "===", "!==", "<", "<=", ">", ">=", "&&", "||", "??"],
+} as const;
+export const conditionalOperatorSchema = { const: "?:" } as const;
+export const switchOperatorSchema = { const: "switch" } as const;
+export const callOperatorSchema = { const: "call" } as const;
+export const pureMethodSchema = {
+  description:
+    "A genuine pure String.prototype / Array.prototype / Number.prototype method (spec §19.4d). The ES2023 change-by-copy family (toSorted, toReversed, toSpliced, with) stands in where mutation would otherwise occur. Receiver in target; value carries the argument (bare scalar) or argument list (array).",
+  enum: [
+    "includes",
+    "indexOf",
+    "lastIndexOf",
+    "join",
+    "slice",
+    "concat",
+    "at",
+    "flat",
+    "toSorted",
+    "toReversed",
+    "toSpliced",
+    "with",
+    "toUpperCase",
+    "toLowerCase",
+    "trim",
+    "trimStart",
+    "trimEnd",
+    "split",
+    "startsWith",
+    "endsWith",
+    "padStart",
+    "padEnd",
+    "replaceAll",
+    "repeat",
+    "charAt",
+    "normalize",
+    "toLocaleUpperCase",
+    "toLocaleLowerCase",
+    "toFixed",
+    "toPrecision",
+    "toLocaleString",
+  ],
 } as const;
 export const assignmentOperatorSchema = { enum: ["=", "+=", "-=", "*=", "/="] } as const;
 export const noArgMethodSchema = { enum: ["pop", "shift"] } as const;
@@ -99,24 +146,80 @@ export const expressionNodeSchema = {
     {
       properties: {
         operator: { $ref: "#/$defs/ReduceMethod" },
-        target: { $ref: "#/$defs/ExpressionPointer" },
+        target: {
+          anyOf: [{ $ref: "#/$defs/ExpressionPointer" }, { $ref: "#/$defs/ExpressionNode" }],
+        },
         value: { $ref: "#/$defs/ExpressionNode" },
       },
       required: ["operator", "value", "initial"],
-      title: "reduce — pure fold; per-item expression in value, seed in initial",
+      title: "reduce — pure fold over a pointer or derived array; seed in initial",
     },
     {
       not: { required: ["initial"] },
       properties: {
         operator: { $ref: "#/$defs/MapFilterMethod" },
-        target: { $ref: "#/$defs/ExpressionPointer" },
+        target: {
+          anyOf: [{ $ref: "#/$defs/ExpressionPointer" }, { $ref: "#/$defs/ExpressionNode" }],
+        },
         value: { $ref: "#/$defs/ExpressionNode" },
       },
       required: ["operator", "value"],
-      title: "map / filter — pure; per-item expression in value, no initial",
+      title: "map / filter — pure over a pointer or derived array; per-item expression in value",
+    },
+    {
+      description:
+        "The ECMAScript conditional (ternary) operator, pure: target is the test, value the consequent, initial the alternate (the reduce precedent for repurposing initial). Chain else-if by nesting another ?: node in initial.",
+      properties: { operator: { $ref: "#/$defs/ConditionalOperator" } },
+      required: ["operator", "value", "initial"],
+      title: "?: — pure conditional; test in target, consequent in value, alternate in initial",
+    },
+    {
+      description:
+        "Value-keyed multiway selection, pure: target is the discriminant (matched against case keys by its string form, like element-level $switch), cases maps matched values to result operands, default is the operand when no case matches (result is undefined without it). Condition-chain branching composes from nested ?: nodes instead.",
+      not: { anyOf: [{ required: ["value"] }, { required: ["initial"] }] },
+      properties: {
+        cases: {
+          additionalProperties: { $ref: "#/$defs/ExpressionOperand" },
+          type: "object",
+        },
+        default: { $ref: "#/$defs/ExpressionOperand" },
+        operator: { $ref: "#/$defs/SwitchOperator" },
+      },
+      required: ["operator", "cases"],
+      title:
+        "switch — pure value-keyed selection; discriminant in target, results in cases/default",
+    },
+    {
+      description:
+        "A pure standard-library method call: target is the receiver (any operand — never mutated; change-by-copy names replace the mutating originals), value the optional argument (bare scalar) or argument list (array). A missing receiver or method yields undefined, matching null-safe path reads.",
+      not: { required: ["initial"] },
+      properties: { operator: { $ref: "#/$defs/PureMethod" } },
+      required: ["operator"],
+      title: "Pure method — genuine prototype methods; receiver in target, args in value",
+    },
+    {
+      description:
+        "Invoke a callable, pure in formula position: target is the callee pointer — a named formula entry (#/state/…) or a blessed pure global via window#/ (Math.*, JSON.*, Object.keys/values/entries, and the Intl helpers Intl/formatNumber, Intl/formatDate, Intl/formatRelativeTime) — and value is the positional argument list (the splice args-in-value precedent). Argument order follows the callee's declared parameters.",
+      not: { required: ["initial"] },
+      properties: {
+        operator: { $ref: "#/$defs/CallOperator" },
+        target: { $ref: "#/$defs/ExpressionPointer" },
+        value: { items: { $ref: "#/$defs/ExpressionOperand" }, type: "array" },
+      },
+      required: ["operator"],
+      title: "call — invoke a named formula or blessed global; callee in target, args in value",
     },
   ],
   properties: {
+    cases: {
+      additionalProperties: { $ref: "#/$defs/ExpressionOperand" },
+      description: "switch only: matched discriminant value (string form) → result operand.",
+      type: "object",
+    },
+    default: {
+      $ref: "#/$defs/ExpressionOperand",
+      description: "switch only: result operand when no case key matches.",
+    },
     initial: { $ref: "#/$defs/ExpressionOperand" },
     operator: { type: "string" },
     target: { $ref: "#/$defs/ExpressionOperand" },
@@ -129,11 +232,17 @@ export const expressionNodeSchema = {
 export const expressionEntrySchema = {
   additionalProperties: false,
   description:
-    "A declarative expression entry (Shape 5). Used as a state entry or inline event handler.",
+    "A declarative expression entry (Shape 5). Used as a state entry or inline event handler. With parameters it is a named formula: a pure, reusable computation invoked via the call operator, its parameters resolved through $args/<name> refs in the body.",
   properties: {
     $description: { type: "string" },
     $expression: { $ref: "#/$defs/ExpressionNode" },
     $title: { type: "string" },
+    parameters: {
+      description:
+        "Named-formula parameters (CEM convention, as on Function entries): bare names or CEM parameter objects. Present ⇒ the entry is callable, not a computed value.",
+      items: { anyOf: [{ type: "string" }, { $ref: "#/$defs/CemParameter" }] },
+      type: "array",
+    },
   },
   required: ["$expression"],
   type: "object",

package/defs/extension-manifest.schema.ts

@@ -0,0 +1,47 @@
+/**
+ * Jx-extension.json manifest schema (specs/extensions.md §4). The manifest is pure data: it
+ * enumerates an extension package's classes and schema fragments; behavior lives in the class
+ * descriptors it points to.
+ */
+
+export const extensionManifestSchema = {
+  additionalProperties: false,
+  description:
+    "Schema for jx-extension.json manifests. Located at the extension package root and " +
+    "exported so hosts can resolve <package>/jx-extension.json through the exports map.",
+  properties: {
+    $schema: { type: "string" },
+    classes: {
+      additionalProperties: { type: "string" },
+      description:
+        "$prototype-visible class name → class descriptor path, relative to the manifest.",
+      type: "object",
+    },
+    description: { description: "One-line description.", type: "string" },
+    name: { description: "Package name; must match package.json.", type: "string" },
+    schemas: {
+      additionalProperties: false,
+      description: "Schema fragments this package contributes, relative to the manifest.",
+      properties: {
+        document: {
+          description: "Document-schema fragment (positions like $paths values).",
+          type: "string",
+        },
+        fields: {
+          description:
+            "Field-union fragment: its $defs members are unioned into the per-project " +
+            "field-schema resource as extension field extras (specs/extensions.md §5.3).",
+          type: "string",
+        },
+        project: {
+          description: "Project-schema fragment (top-level project.json sections).",
+          type: "string",
+        },
+      },
+      type: "object",
+    },
+    title: { description: "Human-readable name for studio surfaces.", type: "string" },
+  },
+  required: ["name"],
+  type: "object",
+} as const;

package/defs/field-schema.schema.ts

@@ -0,0 +1,58 @@
+/**
+ * Field-schema vocabulary (specs/extensions.md §5.3, specs/relationships.md).
+ *
+ * JxFieldSchema is the JSON-Schema-subset shape for a single field inside a section entry schema
+ * (content frontmatter fields, table columns). Recursive positions (`items`, nested `properties`)
+ * reference the well-known **fields resource URI** — a schema resource the generated per-project
+ * entry document re-embeds under the same `$id` with the effective union (core shape +
+ * RelationshipRef + extension extras), shadowing the shipped default by standard compound-document
+ * `$id` resolution. Extension fragments reference the same URI at their field positions.
+ *
+ * (An earlier design used `$dynamicRef`/`$dynamicAnchor` here; ajv restricts `$dynamicAnchor` to
+ * schema-resource roots, which cannot express a non-root recursion unit, so the model uses plain
+ * `$id` indirection instead — verified against ajv 8.20 / 2020-12.)
+ */
+
+/** The well-known $id of the project field-schema union resource. */
+export const PROJECT_FIELDS_SCHEMA_ID = "https://jxsuite.com/schema/project/fields/v2";
+
+/** The well-known $id of the document $paths-value union resource. */
+export const DOCUMENT_PATHS_SCHEMA_ID = "https://jxsuite.com/schema/document/paths/v2";
+
+export const jxFieldSchemaDef = {
+  description:
+    "A single field definition inside a section entry schema — a small, recursive subset of " +
+    "JSON Schema. Recursive positions reference the effective field union via the well-known " +
+    "fields resource $id.",
+  properties: {
+    default: {},
+    description: { type: "string" },
+    enum: { type: "array" },
+    format: { type: "string" },
+    items: { $ref: PROJECT_FIELDS_SCHEMA_ID },
+    properties: {
+      additionalProperties: { $ref: PROJECT_FIELDS_SCHEMA_ID },
+      type: "object",
+    },
+    required: { items: { type: "string" }, type: "array" },
+    type: {
+      enum: ["string", "number", "integer", "boolean", "array", "object"],
+      type: "string",
+    },
+  },
+  required: ["type"],
+  type: "object",
+} as const;
+
+export const relationshipRefSchema = {
+  description:
+    "Relationship reference field: points at a named entry of a referenceable section via " +
+    '"#/<sectionKey>/<name>" (specs/relationships.md). A bare reference is to-one; wrap in an ' +
+    "array field's items for to-many.",
+  properties: {
+    $ref: { pattern: "^#/[A-Za-z][A-Za-z0-9_-]*/[A-Za-z0-9._-]+$", type: "string" },
+    description: { type: "string" },
+  },
+  required: ["$ref"],
+  type: "object",
+} as const;

package/defs/function-def.schema.ts

@@ -16,13 +16,18 @@ export const functionDefSchema = {
       type: "string",
     },
     body: {
-      description: "Inline function body string. First implicit parameter is state.",
+      description:
+        "Inline function body: an opaque JS source string (first implicit parameter is state), or a structured statement array (spec §20) — explicit structured function declaration, analyzable by tooling and editable visually. The escalation ladder within the shape is structured statements → JS string.",
       examples: [
         "state.count++",
         'state.items.push({ id: Date.now(), text: "", done: false })',
         'return state.score >= 90 ? "gold" : "silver"',
+        [
+          { operator: "push", target: { $ref: "#/state/cart" }, value: 1 },
+          { dispatchEvent: "cart-changed", detail: { $ref: "#/state/cart" } },
+        ],
       ],
-      type: "string",
+      oneOf: [{ type: "string" }, { $ref: "#/$defs/StatementList" }],
     },
     description: { type: "string" },
     emits: {

package/defs/index.ts

@@ -34,6 +34,7 @@ export {
 // State shapes
 export { typedStateDefSchema } from "./typed-state-def.schema";
 export { functionDefSchema } from "./function-def.schema";
+export { statementSchema, statementListSchema } from "./statement.schema";
 export { externalClassDefSchema, BUILT_IN_PROTOTYPES } from "./external-class-def.schema";
 export { pureTypeDefSchema } from "./pure-type-def.schema";
 
@@ -46,6 +47,10 @@ export {
   expressionEntrySchema,
   unaryOperatorSchema,
   binaryOperatorSchema,
+  conditionalOperatorSchema,
+  switchOperatorSchema,
+  callOperatorSchema,
+  pureMethodSchema,
   assignmentOperatorSchema,
   noArgMethodSchema,
   oneArgMethodSchema,
@@ -73,6 +78,9 @@ export {
   studioHintsSchema,
 } from "./class-def.schema";
 
-// Content & project
-export { contentTypeDefSchema } from "./content-type-def.schema";
+// Project
 export { projectConfigSchema } from "./project-config.schema";
+
+// Extensions (specs/extensions.md)
+export { extensionManifestSchema } from "./extension-manifest.schema";
+export { jxFieldSchemaDef, relationshipRefSchema } from "./field-schema.schema";

package/defs/project-config.schema.ts

@@ -1,10 +1,11 @@
 export const projectConfigSchema = {
-  additionalProperties: false,
   description:
     "Schema for Jx project.json files. " +
     "A project.json file is the root anchor file for a Jx project, " +
-    "declaring site metadata, default settings, global styles, content types, " +
-    "and build configuration.",
+    "declaring site metadata, default settings, global styles, extensions, " +
+    "and build configuration. Open by design: extension-contributed sections " +
+    "(e.g. `content`) are opaque top-level keys; the generated per-project " +
+    "entry document (project.schema.json) closes the composition.",
   properties: {
     $defs: {
       description: "Global type definitions available to all pages.",
@@ -63,6 +64,12 @@ export const projectConfigSchema = {
       ],
       type: "object",
     },
+    $schema: {
+      description:
+        "Relative path to the generated per-project schema (conventionally " +
+        "./project.schema.json, written by `jx schema`).",
+      type: "string",
+    },
     build: {
       description: "Build configuration.",
       properties: {
@@ -103,7 +110,8 @@ export const projectConfigSchema = {
         },
         format: {
           default: "directory",
-          description: "Output format.",
+          description:
+            "Reserved; currently unused. Accepted for forward compatibility with single-file output (desktop single-file mode) — the build emits per-route directories regardless.",
           enum: ["directory", "single"],
           type: "string",
         },
@@ -127,13 +135,6 @@ export const projectConfigSchema = {
       },
       type: "object",
     },
-    contentTypes: {
-      additionalProperties: { $ref: "#/$defs/ContentTypeDef" },
-      description:
-        "Content type definitions. Each key is a content type name; " +
-        "the value defines the source directory, frontmatter schema, and element dependencies.",
-      type: "object",
-    },
     copy: {
       additionalProperties: { type: "string" },
       description:
@@ -164,6 +165,14 @@ export const projectConfigSchema = {
       },
       type: "object",
     },
+    extensions: {
+      description:
+        "Extension packages: bare package names (resolved project-first through the package " +
+        "exports map) or relative paths. Each must export jx-extension.json.",
+      examples: [["@jxsuite/parser"]],
+      items: { type: "string" },
+      type: "array",
+    },
     i18n: {
       description: "Internationalization configuration.",
       properties: {

package/defs/statement.schema.ts

@@ -0,0 +1,65 @@
+// oxlint-disable unicorn/no-thenable -- `then` is the JSON Schema conditional keyword (spec §20), not a promise
+/**
+ * Statement schema (spec §20) — structured function bodies.
+ *
+ * A Function entry's `body` may be a JSON array of statements instead of an opaque JS source
+ * string: explicit structured function declaration, mirroring ESTree's `BlockStatement.body =
+ * Statement[]`. Every statement kind reuses a web-platform name: bare expression nodes (§19), the
+ * JSON Schema 2020-12 `if`/`then`/`else` keyword triple, the element-level `$switch`/`cases`
+ * convention in statement position, and WHATWG's `dispatchEvent` with `CustomEventInit` members.
+ */
+
+export const statementSchema = {
+  description:
+    "One statement of a structured function body. Either a bare expression node in statement position (a mutation like =/push, or a call — its result discarded unless captured by an assignment), an if/then/else branch (JSON Schema conditional keywords; if holds a pure expression, then/else hold statement lists), a $switch multiway branch (discriminant matched by string form against cases keys, like element-level $switch), or a dispatchEvent statement (WHATWG DOM: dispatches a CustomEvent from the handler's current target, with CustomEventInit members detail/bubbles/composed).",
+  oneOf: [
+    { $ref: "#/$defs/ExpressionNode" },
+    {
+      additionalProperties: false,
+      properties: {
+        else: { items: { $ref: "#/$defs/Statement" }, type: "array" },
+        if: { $ref: "#/$defs/ExpressionOperand" },
+        then: { items: { $ref: "#/$defs/Statement" }, type: "array" },
+      },
+      required: ["if", "then"],
+      title: "if / then / else — conditional branch (JSON Schema keyword triple)",
+      type: "object",
+    },
+    {
+      additionalProperties: false,
+      properties: {
+        $switch: { $ref: "#/$defs/ExpressionOperand" },
+        cases: {
+          additionalProperties: { items: { $ref: "#/$defs/Statement" }, type: "array" },
+          type: "object",
+        },
+        default: { items: { $ref: "#/$defs/Statement" }, type: "array" },
+      },
+      required: ["$switch", "cases"],
+      title: "$switch / cases — multiway branch (element-level convention, ECMA switch semantics)",
+      type: "object",
+    },
+    {
+      additionalProperties: false,
+      properties: {
+        bubbles: { type: "boolean" },
+        composed: { type: "boolean" },
+        detail: { $ref: "#/$defs/ExpressionOperand" },
+        dispatchEvent: {
+          description: "The CustomEvent type to dispatch (WHATWG DOM dispatchEvent).",
+          type: "string",
+        },
+      },
+      required: ["dispatchEvent"],
+      title: "dispatchEvent — emit a CustomEvent (WHATWG naming, CustomEventInit members)",
+      type: "object",
+    },
+  ],
+} as const;
+
+export const statementListSchema = {
+  description:
+    "A structured function body: statements executed sequentially (one yielding a promise is awaited before the next, per ECMA async/await semantics).",
+  items: { $ref: "#/$defs/Statement" },
+  type: "array",
+} as const;

package/extension-manifest.schema.json

@@ -0,0 +1,54 @@
+{
+  "$id": "https://jxsuite.com/schema/extension-manifest/v1",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Jx Extension Manifest",
+  "additionalProperties": false,
+  "description": "Schema for jx-extension.json manifests. Located at the extension package root and exported so hosts can resolve <package>/jx-extension.json through the exports map.",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "classes": {
+      "additionalProperties": {
+        "type": "string"
+      },
+      "description": "$prototype-visible class name → class descriptor path, relative to the manifest.",
+      "type": "object"
+    },
+    "description": {
+      "description": "One-line description.",
+      "type": "string"
+    },
+    "name": {
+      "description": "Package name; must match package.json.",
+      "type": "string"
+    },
+    "schemas": {
+      "additionalProperties": false,
+      "description": "Schema fragments this package contributes, relative to the manifest.",
+      "properties": {
+        "document": {
+          "description": "Document-schema fragment (positions like $paths values).",
+          "type": "string"
+        },
+        "fields": {
+          "description": "Field-union fragment: its $defs members are unioned into the per-project field-schema resource as extension field extras (specs/extensions.md §5.3).",
+          "type": "string"
+        },
+        "project": {
+          "description": "Project-schema fragment (top-level project.json sections).",
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "title": {
+      "description": "Human-readable name for studio surfaces.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "name"
+  ],
+  "type": "object"
+}

package/package.json

@@ -1,25 +1,33 @@
 {
   "dependencies": {
-    "@webref/css": "^8.6.1",
+    "@webref/css": "^8.7.0",
     "@webref/elements": "^2.7.1",
-    "@webref/idl": "^3.81.2",
+    "@webref/idl": "^3.82.0",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1"
   },
   "description": "JSON Schema 2020-12 meta-schema generator for Jx documents",
   "exports": {
     ".": "./src/schema.ts",
+    "./extension-registry": "./src/extension-registry.ts",
     "./format-registry": "./src/format-registry.ts",
+    "./project-schemas": "./src/project-schemas.ts",
+    "./validate-project": "./src/validate-project.ts",
     "./types": "./types.ts",
     "./guards": "./src/guards.ts",
     "./parse": "./src/parse.ts",
     "./defs": "./defs/index.ts",
     "./schema.json": "./schema.json",
-    "./project-schema.json": "./project-schema.json"
+    "./project-schema.json": "./project-schema.json",
+    "./extension-manifest.schema.json": "./extension-manifest.schema.json",
+    "./schemas/project.core.schema.json": "./schemas/project.core.schema.json",
+    "./schemas/project.fields.schema.json": "./schemas/project.fields.schema.json",
+    "./schemas/document.paths.schema.json": "./schemas/document.paths.schema.json"
   },
   "files": [
     "src/",
     "defs/",
+    "schemas/",
     "types.ts",
     "*.json",
     "!package.json"
@@ -41,7 +49,7 @@
     "upgrade": "bunx npm-check-updates -u && bun install"
   },
   "type": "module",
-  "version": "0.35.0",
+  "version": "1.1.0",
   "devDependencies": {
     "json-schema-to-ts": "^3.1.1"
   }