@jxsuite/schema 0.23.2 → 0.24.0

package/defs/cem.schema.ts

@@ -0,0 +1,30 @@
+export const cemParameterSchema = {
+  description:
+    "A CEM-compatible parameter definition for a function. " +
+    "Follows the Custom Elements Manifest Parameter shape.",
+  type: "object",
+  required: ["name"],
+  properties: {
+    name: { description: "Parameter name.", type: "string" },
+    type: { description: "Parameter type (JSON Schema or CEM { text } format)." },
+    description: { description: "Parameter documentation.", type: "string" },
+    optional: { description: "Whether the parameter is optional.", type: "boolean" },
+    default: { description: "Default value for the parameter." },
+  },
+} as const;
+
+export const cemEventSchema = {
+  description:
+    "A CEM-compatible event definition. " + "Describes a CustomEvent the function dispatches.",
+  type: "object",
+  required: ["name"],
+  properties: {
+    name: { description: "Event name (e.g. 'task-toggled').", type: "string" },
+    type: { description: "Event type (e.g. { text: 'CustomEvent' })." },
+    description: { description: "Event documentation.", type: "string" },
+    deprecated: {
+      description: "Deprecation notice.",
+      oneOf: [{ type: "boolean" }, { type: "string" }],
+    },
+  },
+} as const;

package/defs/children-value.schema.ts

@@ -0,0 +1,28 @@
+export const arrayNamespaceSchema = {
+  description: "Dynamic mapped list. Re-renders when the items state entry changes.",
+  type: "object",
+  required: ["$prototype", "items", "map"],
+  properties: {
+    $prototype: { type: "string", const: "Array" },
+    items: {
+      oneOf: [{ $ref: "#/$defs/RefObject" }, { type: "array" }],
+    },
+    map: { $ref: "#/$defs/ElementDef" },
+    filter: { $ref: "#/$defs/RefObject" },
+    sort: { $ref: "#/$defs/RefObject" },
+  },
+  additionalProperties: false,
+} as const;
+
+export const childrenValueSchema = {
+  description: "Static array of child definitions, or an Array namespace for dynamic lists.",
+  oneOf: [
+    {
+      type: "array",
+      items: {
+        oneOf: [{ $ref: "#/$defs/ElementDef" }, { type: "string" }, { type: "number" }],
+      },
+    },
+    { $ref: "#/$defs/ArrayNamespace" },
+  ],
+} as const;

package/defs/class-def.schema.ts

@@ -0,0 +1,169 @@
+export const classParameterDefSchema = {
+  description: "A typed parameter definition for a class.",
+  type: "object",
+  required: ["identifier"],
+  properties: {
+    identifier: { type: "string" },
+    type: {},
+    format: {
+      description: 'When "json-schema", this parameter\'s value is itself a JSON Schema.',
+      type: "string",
+    },
+    description: { type: "string" },
+    default: {},
+    examples: { type: "array" },
+  },
+} as const;
+
+export const classFieldDefSchema = {
+  description: "A class field definition with access control and scope.",
+  type: "object",
+  properties: {
+    role: { type: "string", const: "field" },
+    access: { type: "string", enum: ["public", "private", "protected"] },
+    scope: { type: "string", enum: ["instance", "static"] },
+    identifier: { type: "string" },
+    type: {},
+    $prototype: {
+      description: 'Data source prototype for this field (e.g., "Request").',
+      type: "string",
+    },
+    initializer: {},
+    default: {},
+    description: { type: "string" },
+    examples: { type: "array" },
+  },
+} as const;
+
+export const classConstructorDefSchema = {
+  description: "Class constructor definition.",
+  type: "object",
+  properties: {
+    role: { type: "string", const: "constructor" },
+    $prototype: { type: "string", const: "Function" },
+    parameters: {
+      type: "array",
+      items: {
+        oneOf: [
+          {
+            type: "object",
+            required: ["$ref"],
+            properties: { $ref: { type: "string" } },
+            additionalProperties: false,
+          },
+          { $ref: "#/$defs/ClassParameterDef" },
+        ],
+      },
+    },
+    superCall: {
+      type: "object",
+      properties: {
+        arguments: { type: "array", items: { type: "string" } },
+      },
+    },
+    body: {
+      oneOf: [{ type: "string" }, { type: "array", items: { type: "string" } }],
+    },
+    description: { type: "string" },
+  },
+} as const;
+
+export const classMethodDefSchema = {
+  description: "A class method or accessor definition.",
+  type: "object",
+  properties: {
+    role: { type: "string", enum: ["method", "accessor"] },
+    $prototype: { type: "string", const: "Function" },
+    access: { type: "string", enum: ["public", "private", "protected"] },
+    scope: { type: "string", enum: ["instance", "static"] },
+    identifier: { type: "string" },
+    parameters: {
+      type: "array",
+      items: {
+        oneOf: [
+          {
+            type: "object",
+            required: ["$ref"],
+            properties: { $ref: { type: "string" } },
+            additionalProperties: false,
+          },
+          { $ref: "#/$defs/ClassParameterDef" },
+        ],
+      },
+    },
+    returnType: {},
+    body: {
+      oneOf: [{ type: "string" }, { type: "array", items: { type: "string" } }],
+    },
+    getter: {
+      type: "object",
+      properties: { body: { type: "string" } },
+    },
+    setter: {
+      type: "object",
+      properties: {
+        parameters: { type: "array" },
+        body: { type: "string" },
+      },
+    },
+    description: { type: "string" },
+  },
+} as const;
+
+export const classDefSchema = {
+  description:
+    'A .class.json schema-defined class. $prototype must be "Class". ' +
+    "Defines fields, constructor, methods, and type parameters via $defs. " +
+    "Optionally points to a JS module via $implementation for hybrid execution.",
+  type: "object",
+  required: ["$prototype", "title"],
+  properties: {
+    $schema: { type: "string" },
+    $id: { type: "string" },
+    $prototype: { type: "string", const: "Class" },
+    title: {
+      description: "PascalCase class name, used as the export name.",
+      type: "string",
+    },
+    description: { type: "string" },
+    extends: {
+      description: "Base class — string name or $ref to another .class.json.",
+      oneOf: [
+        { type: "string" },
+        { type: "object", required: ["$ref"], properties: { $ref: { type: "string" } } },
+      ],
+    },
+    $implementation: {
+      description: "Relative path to a JS module containing the actual class implementation.",
+      type: "string",
+    },
+    $defs: {
+      description: "Class members: parameters, returnTypes, fields, constructor, methods.",
+      type: "object",
+      properties: {
+        parameters: {
+          description: "Reusable typed parameter schemas, keyed by name.",
+          type: "object",
+          additionalProperties: { $ref: "#/$defs/ClassParameterDef" },
+        },
+        returnTypes: {
+          description: "Output type schemas, keyed by name.",
+          type: "object",
+          additionalProperties: { type: "object" },
+        },
+        fields: {
+          description: "Class fields with role, access, scope, and type information.",
+          type: "object",
+          additionalProperties: { $ref: "#/$defs/ClassFieldDef" },
+        },
+        constructor: { $ref: "#/$defs/ClassConstructorDef" },
+        methods: {
+          description: "Class methods and accessors.",
+          type: "object",
+          additionalProperties: { $ref: "#/$defs/ClassMethodDef" },
+        },
+      },
+    },
+  },
+  additionalProperties: false,
+} as const;

package/defs/content-type-def.schema.ts

@@ -0,0 +1,34 @@
+export const contentTypeDefSchema = {
+  description:
+    "Content type definition. Defines the source directory, frontmatter schema, and element dependencies.",
+  type: "object",
+  properties: {
+    source: {
+      description: "Path to the content directory relative to the project root.",
+      type: "string",
+      examples: ["./content/blog/", "./content/docs/"],
+    },
+    format: {
+      type: "string",
+      enum: ["md", "json", "csv", "yaml"],
+    },
+    schema: {
+      description: "JSON Schema for validating frontmatter of content type entries.",
+      type: "object",
+    },
+    $elements: {
+      description: "Custom elements available in markdown directives for this content type.",
+      type: "array",
+      items: {
+        oneOf: [
+          {
+            type: "object",
+            required: ["$ref"],
+            properties: { $ref: { type: "string" } },
+          },
+          { type: "string" },
+        ],
+      },
+    },
+  },
+} as const;

package/defs/element-def.schema.ts

@@ -0,0 +1,98 @@
+export const attributesObjectSchema = {
+  description: "HTML attributes and ARIA attributes set via element.setAttribute().",
+  type: "object",
+  additionalProperties: {
+    oneOf: [
+      { type: "string" },
+      { type: "number" },
+      { type: "boolean" },
+      { $ref: "#/$defs/RefObject" },
+    ],
+  },
+} as const;
+
+export const propsObjectSchema = {
+  description: "Explicit prop passing at a component boundary.",
+  type: "object",
+  additionalProperties: {
+    oneOf: [
+      { type: "string" },
+      { type: "number" },
+      { type: "boolean" },
+      { type: "array" },
+      { type: "object" },
+      { $ref: "#/$defs/RefObject" },
+    ],
+  },
+} as const;
+
+export const elementPropertyValueSchema = {
+  oneOf: [
+    { type: "string" },
+    { type: "number" },
+    { type: "boolean" },
+    { type: "null" },
+    { $ref: "#/$defs/RefObject" },
+  ],
+} as const;
+
+export const switchDefSchema = {
+  description: "Reactive $ref that drives which case to render.",
+  type: "object",
+  required: ["$ref"],
+  properties: { $ref: { $ref: "#/$defs/InternalRef" } },
+  additionalProperties: false,
+} as const;
+
+export const switchNodeSchema = {
+  type: "object",
+  required: ["$switch", "cases"],
+  properties: {
+    tagName: { $ref: "#/$defs/TagName" },
+    $switch: { $ref: "#/$defs/SwitchDef" },
+    cases: {
+      type: "object",
+      additionalProperties: {
+        oneOf: [{ $ref: "#/$defs/ElementDef" }, { $ref: "#/$defs/ExternalComponentRef" }],
+      },
+    },
+  },
+} as const;
+
+export const elementDefSchema = {
+  description: "A Jx element definition. Maps directly to a DOM element.",
+  type: "object",
+  required: ["tagName"],
+  properties: {
+    tagName: { $ref: "#/$defs/TagName" },
+    id: { type: "string" },
+    className: { $ref: "#/$defs/StringOrRef" },
+    textContent: { $ref: "#/$defs/StringOrRef" },
+    innerHTML: { $ref: "#/$defs/StringOrRef" },
+    innerText: { $ref: "#/$defs/StringOrRef" },
+    hidden: { $ref: "#/$defs/BoolOrRef" },
+    tabIndex: { $ref: "#/$defs/NumberOrRef" },
+    title: { $ref: "#/$defs/StringOrRef" },
+    lang: { $ref: "#/$defs/StringOrRef" },
+    dir: { type: "string", enum: ["ltr", "rtl", "auto"] },
+    value: { $ref: "#/$defs/StringOrRef" },
+    checked: { $ref: "#/$defs/BoolOrRef" },
+    disabled: { $ref: "#/$defs/BoolOrRef" },
+    selected: { $ref: "#/$defs/BoolOrRef" },
+    src: { $ref: "#/$defs/StringOrRef" },
+    href: { $ref: "#/$defs/StringOrRef" },
+    alt: { $ref: "#/$defs/StringOrRef" },
+    type: { $ref: "#/$defs/StringOrRef" },
+    name: { $ref: "#/$defs/StringOrRef" },
+    placeholder: { $ref: "#/$defs/StringOrRef" },
+    children: { $ref: "#/$defs/ChildrenValue" },
+    style: { $ref: "#/$defs/StyleObject" },
+    attributes: { $ref: "#/$defs/AttributesObject" },
+    $switch: { $ref: "#/$defs/SwitchDef" },
+    $ref: { $ref: "#/$defs/ExternalRef" },
+    $props: { $ref: "#/$defs/PropsObject" },
+    "$map/item": { $ref: "#/$defs/RefObject" },
+    "$map/index": { $ref: "#/$defs/RefObject" },
+  },
+  additionalProperties: { $ref: "#/$defs/ElementPropertyValue" },
+} as const;

package/defs/expression-node.schema.ts

@@ -0,0 +1,140 @@
+export const expressionPointerSchema = {
+  description: "A JSON Pointer $ref operand within an expression node.",
+  type: "object",
+  properties: {
+    $ref: {
+      type: "string",
+      pattern: "^(\\$map/|\\$reduce/|event#/|#/|parent#/|window#/|document#/)",
+    },
+  },
+  required: ["$ref"],
+  additionalProperties: false,
+} as const;
+
+export const expressionLiteralSchema = {
+  description: "A non-reactive operand: scalar or array of operands.",
+  anyOf: [
+    { type: "string", not: { pattern: "\\$\\{" } },
+    { type: "number" },
+    { type: "boolean" },
+    { type: "null" },
+    { type: "array", items: { $ref: "#/$defs/ExpressionOperand" } },
+  ],
+} as const;
+
+export const expressionOperandSchema = {
+  description:
+    "Anything that may appear in target or value: a pointer, a literal, or a nested expression node.",
+  anyOf: [
+    { $ref: "#/$defs/ExpressionPointer" },
+    { $ref: "#/$defs/ExpressionNode" },
+    { $ref: "#/$defs/ExpressionLiteral" },
+  ],
+} as const;
+
+export const unaryOperatorSchema = { enum: ["!", "-"] } as const;
+export const binaryOperatorSchema = {
+  enum: ["+", "-", "*", "/", "%", "===", "!==", "<", "<=", ">", ">=", "&&", "||"],
+} as const;
+export const assignmentOperatorSchema = { enum: ["=", "+=", "-=", "*=", "/="] } as const;
+export const noArgMethodSchema = { enum: ["pop", "shift"] } as const;
+export const oneArgMethodSchema = { enum: ["push", "unshift"] } as const;
+export const spliceMethodSchema = { const: "splice" } as const;
+export const reduceMethodSchema = { const: "reduce" } as const;
+export const mapFilterMethodSchema = { enum: ["map", "filter"] } as const;
+
+export const expressionNodeSchema = {
+  description: "The core expression node. operator + target, with value gated by arity.",
+  type: "object",
+  required: ["operator", "target"],
+  additionalProperties: false,
+  properties: {
+    operator: { type: "string" },
+    target: { $ref: "#/$defs/ExpressionOperand" },
+    value: { $ref: "#/$defs/ExpressionOperand" },
+    initial: { $ref: "#/$defs/ExpressionOperand" },
+  },
+  oneOf: [
+    {
+      title: "Unary — target only, no value",
+      properties: { operator: { $ref: "#/$defs/UnaryOperator" } },
+      required: ["operator"],
+      not: { anyOf: [{ required: ["value"] }, { required: ["initial"] }] },
+    },
+    {
+      title: "Binary — left in target, right in value",
+      properties: { operator: { $ref: "#/$defs/BinaryOperator" } },
+      required: ["operator", "value"],
+      not: { required: ["initial"] },
+    },
+    {
+      title: "Assignment — writable target, value required",
+      properties: {
+        operator: { $ref: "#/$defs/AssignmentOperator" },
+        target: { $ref: "#/$defs/ExpressionPointer" },
+      },
+      required: ["operator", "value"],
+      not: { required: ["initial"] },
+    },
+    {
+      title: "pop / shift — array receiver, no value",
+      properties: {
+        operator: { $ref: "#/$defs/NoArgMethod" },
+        target: { $ref: "#/$defs/ExpressionPointer" },
+      },
+      required: ["operator"],
+      not: { anyOf: [{ required: ["value"] }, { required: ["initial"] }] },
+    },
+    {
+      title: "push / unshift — array receiver, single value argument",
+      properties: {
+        operator: { $ref: "#/$defs/OneArgMethod" },
+        target: { $ref: "#/$defs/ExpressionPointer" },
+      },
+      required: ["operator", "value"],
+      not: { required: ["initial"] },
+    },
+    {
+      title: "splice — array receiver, [start, deleteCount, ...items]",
+      properties: {
+        operator: { $ref: "#/$defs/SpliceMethod" },
+        target: { $ref: "#/$defs/ExpressionPointer" },
+        value: { type: "array", items: { $ref: "#/$defs/ExpressionOperand" }, minItems: 1 },
+      },
+      required: ["operator", "value"],
+      not: { required: ["initial"] },
+    },
+    {
+      title: "reduce — pure fold; per-item expression in value, seed in initial",
+      properties: {
+        operator: { $ref: "#/$defs/ReduceMethod" },
+        target: { $ref: "#/$defs/ExpressionPointer" },
+        value: { $ref: "#/$defs/ExpressionNode" },
+      },
+      required: ["operator", "value", "initial"],
+    },
+    {
+      title: "map / filter — pure; per-item expression in value, no initial",
+      properties: {
+        operator: { $ref: "#/$defs/MapFilterMethod" },
+        target: { $ref: "#/$defs/ExpressionPointer" },
+        value: { $ref: "#/$defs/ExpressionNode" },
+      },
+      required: ["operator", "value"],
+      not: { required: ["initial"] },
+    },
+  ],
+} as const;
+
+export const expressionEntrySchema = {
+  description:
+    "A declarative expression entry (Shape 5). Used as a state entry or inline event handler.",
+  type: "object",
+  required: ["$expression"],
+  properties: {
+    $expression: { $ref: "#/$defs/ExpressionNode" },
+    $title: { type: "string" },
+    $description: { type: "string" },
+  },
+  additionalProperties: false,
+} as const;

package/defs/external-class-def.schema.ts

@@ -0,0 +1,107 @@
+export const BUILT_IN_PROTOTYPES = [
+  "Function",
+  "Request",
+  "URLSearchParams",
+  "FormData",
+  "LocalStorage",
+  "SessionStorage",
+  "Cookie",
+  "IndexedDB",
+  "Array",
+  "Set",
+  "Map",
+  "Blob",
+  "ReadableStream",
+] as const;
+
+export const externalClassDefSchema = {
+  description:
+    'An external class / data source. $prototype is a constructor name (not "Function"). ' +
+    "When $prototype is not in the built-in registry, $src is required. " +
+    "All state entries are reactive by default.",
+  type: "object",
+  required: ["$prototype"],
+  properties: {
+    $prototype: {
+      description: "Constructor name — built-in Web API class or external class name.",
+      type: "string",
+      not: { const: "Function" },
+      examples: [
+        "Request",
+        "URLSearchParams",
+        "FormData",
+        "LocalStorage",
+        "SessionStorage",
+        "Cookie",
+        "IndexedDB",
+        "Array",
+        "Set",
+        "Map",
+        "Blob",
+        "ReadableStream",
+        "MarkdownCollection",
+        "MyParser",
+      ],
+    },
+    $src: {
+      description: "External module specifier. Required when $prototype is not a built-in.",
+      type: "string",
+      examples: ["@jxsuite/md", "./lib/my-parser.js", "npm:@myorg/data"],
+    },
+    $export: {
+      description: "Named export in $src module. Defaults to the $prototype value.",
+      type: "string",
+    },
+    timing: { type: "string", enum: ["compiler", "server", "client"] },
+    manual: { type: "boolean" },
+    debounce: { type: "integer", minimum: 0 },
+    url: { $ref: "#/$defs/StringOrRef" },
+    method: {
+      type: "string",
+      enum: ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"],
+    },
+    headers: { type: "object", additionalProperties: { type: "string" } },
+    body: {},
+    responseType: {
+      type: "string",
+      enum: ["json", "text", "blob", "arraybuffer", "document", ""],
+    },
+    key: { type: "string" },
+    name: { type: "string" },
+    maxAge: { type: "integer" },
+    expires: { type: "string" },
+    path: { type: "string" },
+    domain: { type: "string" },
+    secure: { type: "boolean" },
+    sameSite: { type: "string", enum: ["strict", "lax", "none"] },
+    database: { type: "string" },
+    store: { type: "string" },
+    version: { type: "integer", minimum: 1 },
+    keyPath: { type: "string" },
+    autoIncrement: { type: "boolean" },
+    indexes: {
+      type: "array",
+      items: {
+        type: "object",
+        required: ["name", "keyPath"],
+        properties: {
+          name: { type: "string" },
+          keyPath: {
+            oneOf: [{ type: "string" }, { type: "array", items: { type: "string" } }],
+          },
+          unique: { type: "boolean" },
+        },
+      },
+    },
+    default: {},
+    description: { type: "string" },
+    items: {},
+    map: { $ref: "#/$defs/ElementDef" },
+    filter: { $ref: "#/$defs/RefObject" },
+    sort: { $ref: "#/$defs/RefObject" },
+    src: {
+      description: "Configuration property passed to external class constructor.",
+      type: "string",
+    },
+  },
+} as const;

package/defs/function-def.schema.ts

@@ -0,0 +1,59 @@
+export const functionDefSchema = {
+  description:
+    'A function declaration. $prototype must be "Function". ' +
+    "body (inline) and $src (external) are mutually exclusive. " +
+    "First parameter is always state (the reactive scope).",
+  type: "object",
+  required: ["$prototype"],
+  properties: {
+    $prototype: { type: "string", const: "Function" },
+    body: {
+      description: "Inline function body string. First implicit parameter is state.",
+      type: "string",
+      examples: [
+        "state.count++",
+        'state.items.push({ id: Date.now(), text: "", done: false })',
+        'return state.score >= 90 ? "gold" : "silver"',
+      ],
+    },
+    parameters: {
+      description:
+        "Function parameters (after the implicit state parameter). " +
+        "Accepts CEM-compatible parameter objects or bare string names for backward compatibility.",
+      type: "array",
+      items: {
+        oneOf: [{ type: "string" }, { $ref: "#/$defs/CemParameter" }],
+      },
+      examples: [
+        ["event"],
+        [{ name: "event", type: { text: "Event" } }],
+        [{ name: "id", type: { text: "number" }, description: "Item identifier" }],
+      ],
+    },
+    name: {
+      description: "Explicit function name. Defaults to the state key name.",
+      type: "string",
+    },
+    $src: {
+      description: "External module specifier. Mutually exclusive with body.",
+      type: "string",
+      examples: ["./counter.js", "npm:@myorg/validators"],
+    },
+    $export: {
+      description: "Named export in $src module. Defaults to the state key name.",
+      type: "string",
+    },
+    type: {
+      description: "Return type for tooling (JSON Schema or CEM { text } format).",
+    },
+    emits: {
+      description:
+        "Array of CEM-compatible Event objects this function dispatches. " +
+        "Used for CEM extraction and studio event discovery.",
+      type: "array",
+      items: { $ref: "#/$defs/CemEvent" },
+    },
+    description: { type: "string" },
+  },
+  additionalProperties: false,
+} as const;

package/defs/head-entry.schema.ts

@@ -0,0 +1,17 @@
+export const headEntrySchema = {
+  description: "A page-level <head> entry. Defines meta tags, link tags, script tags, etc.",
+  type: "object",
+  required: ["tagName"],
+  properties: {
+    tagName: { type: "string" },
+    attributes: {
+      type: "object",
+      additionalProperties: {
+        oneOf: [{ type: "string" }, { type: "boolean" }],
+      },
+    },
+    textContent: { type: "string" },
+    children: { type: "array", items: { $ref: "#/$defs/HeadEntry" } },
+  },
+  additionalProperties: true,
+} as const;