@jxsuite/schema 0.28.0 → 0.28.3

package/types.ts

@@ -1,31 +1,32 @@
 import type { FromSchema } from "json-schema-to-ts";
 
-import { headEntrySchema } from "./defs/head-entry.schema";
-import { imageConfigSchema } from "./defs/image-config.schema";
-import { cemParameterSchema, cemEventSchema } from "./defs/cem.schema";
-import { contentTypeDefSchema } from "./defs/content-type-def.schema";
-import { projectConfigSchema } from "./defs/project-config.schema";
-import { refObjectSchema } from "./defs/ref-object.schema";
-import { styleObjectSchema } from "./defs/style-object.schema";
-import { elementDefSchema } from "./defs/element-def.schema";
-import { functionDefSchema } from "./defs/function-def.schema";
-import { externalClassDefSchema } from "./defs/external-class-def.schema";
-import { typedStateDefSchema } from "./defs/typed-state-def.schema";
-import { pureTypeDefSchema } from "./defs/pure-type-def.schema";
-import { expressionNodeSchema, expressionEntrySchema } from "./defs/expression-node.schema";
-import { stateEntrySchema, stateMapSchema, defsMapSchema } from "./defs/state-entry.schema";
-import {
+import type { headEntrySchema } from "./defs/head-entry.schema";
+import type { imageConfigSchema } from "./defs/image-config.schema";
+import type { cemEventSchema, cemParameterSchema } from "./defs/cem.schema";
+import type { contentTypeDefSchema } from "./defs/content-type-def.schema";
+import type { projectConfigSchema } from "./defs/project-config.schema";
+import type { refObjectSchema } from "./defs/ref-object.schema";
+import type { styleObjectSchema } from "./defs/style-object.schema";
+import type { elementDefSchema } from "./defs/element-def.schema";
+import type { functionDefSchema } from "./defs/function-def.schema";
+import type { externalClassDefSchema } from "./defs/external-class-def.schema";
+import type { typedStateDefSchema } from "./defs/typed-state-def.schema";
+import type { pureTypeDefSchema } from "./defs/pure-type-def.schema";
+import type { expressionEntrySchema, expressionNodeSchema } from "./defs/expression-node.schema";
+import type { defsMapSchema, stateEntrySchema, stateMapSchema } from "./defs/state-entry.schema";
+import type {
+  classConstructorDefSchema,
   classDefSchema,
   classFieldDefSchema,
   classMethodDefSchema,
   classParameterDefSchema,
-  classConstructorDefSchema,
 } from "./defs/class-def.schema";
 
 // ─── Strict Schema-Derived Types ────────────────────────────────────────────────
 // These are the precise types derived from the JSON Schema defs via FromSchema.
 // Use these when you need exact schema conformance (e.g., validation, serialization).
 
+// oxlint-disable typescript/no-namespace, no-shadow -- type-only grouping of schema-derived types whose members intentionally mirror the loose top-level type names (Strict.ImageConfig vs ImageConfig); an ES module split would fragment the schema package's public surface
 export namespace Strict {
   export type HeadEntry = FromSchema<typeof headEntrySchema>;
   export type ImageConfig = FromSchema<typeof imageConfigSchema>;
@@ -51,10 +52,102 @@ export namespace Strict {
   export type ClassConstructorDef = FromSchema<typeof classConstructorDefSchema>;
   export type ProjectConfig = FromSchema<typeof projectConfigSchema>;
 }
+// oxlint-enable typescript/no-namespace, no-shadow
+
+// ─── JSON Value Model ───────────────────────────────────────────────────────────
+// Jx documents are JSON. These types describe what can actually appear in one,
+// As opposed to `unknown` (nothing known) or `any` (checking disabled).
+
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | JsonObject;
+export interface JsonObject {
+  [key: string]: JsonValue;
+}
+
+// ─── Binding Model ──────────────────────────────────────────────────────────────
+// Any bindable position in a document holds either a literal value or a JSON
+// Pointer reference into the reactive scope.
+
+/**
+ * A JSON Pointer reference into document state, e.g. `{ $ref: "#/state/count" }`. (A type literal
+ * rather than an interface so it stays assignable to JsonValue.)
+ */
+export interface JxRef {
+  $ref: string;
+}
+
+/** A value that may be given literally or bound via `$ref`. */
+export type Bindable<T> = T | JxRef;
+
+// ─── Expression Model ───────────────────────────────────────────────────────────
+// Declarative expressions: operator + target (+ value), with operands that are
+// Pointers, literals, or nested expression nodes.
+
+export type JxExpressionOperand =
+  | JxRef
+  | JxExpressionNode
+  | string
+  | number
+  | boolean
+  | null
+  | JxExpressionOperand[];
+
+export interface JxExpressionNode {
+  operator: string;
+  target: JxExpressionOperand;
+  value?: JxExpressionOperand;
+  initial?: JxExpressionOperand;
+}
+
+/** A state entry (or event binding) whose value is computed from a declarative expression. */
+export interface JxExpressionDef {
+  $expression: JxExpressionNode;
+  [key: string]: unknown;
+}
+
+// ─── State Definition Model ─────────────────────────────────────────────────────
+// The shapes a `state` entry can take, mirroring the runtime's five-shape
+// Detection algorithm in buildScope(). Use the guards in `@jxsuite/schema/guards`
+// To discriminate.
+
+/** A function declaration: inline `body` or external `$src`/`$export`. */
+export interface JxFunctionDef {
+  $prototype: "Function";
+  /** Inline function body. The reactive scope is the implicit first parameter. */
+  body?: string;
+  /** Parameters after the implicit scope parameter: bare names or CEM parameter objects. */
+  parameters?: (string | CemParameter)[];
+  /** Explicit function name; defaults to the state key. */
+  name?: string;
+  /** External module specifier; mutually exclusive with `body`. */
+  $src?: string;
+  /** Named export within `$src`; defaults to the state key. */
+  $export?: string;
+  /** Legacy alias for `parameters` (bare names only). */
+  arguments?: string[];
+  timing?: "compiler" | "server" | "client";
+  debounce?: number;
+  emits?: CemEvent[];
+  description?: string;
+  deprecated?: string | boolean;
+  [key: string]: unknown;
+}
+
+/** A `timing: "server"` function proxy — executed server-side, no `$prototype`. */
+export interface JxServerFnDef {
+  timing: "server";
+  $src: string;
+  $export: string;
+  parameters?: (string | CemParameter)[];
+  /** Named arguments forwarded to the server function: literals or `$ref` bindings. */
+  arguments?: Record<string, JsonValue>;
+  debounce?: number;
+  [key: string]: unknown;
+}
 
 // ─── Consumer-Friendly Types ────────────────────────────────────────────────────
 // Relaxed types for everyday use in the runtime/compiler/studio. These add an index
-// signature for dynamic property access while preserving the known property structure.
+// Signature for dynamic property access while preserving the known property structure.
 
 export interface JxHeadEntry {
   tagName: string;
@@ -72,28 +165,42 @@ export interface ImageConfig {
   sizes?: string;
   lazyLoad?: boolean;
   service?: "build" | "cloudflare";
-  binding?: string;
   remoteDomains?: string[];
 }
 
-export type CemParameter = FromSchema<typeof cemParameterSchema>;
-export type CemEvent = FromSchema<typeof cemEventSchema>;
+/** A CEM-compatible function parameter. JSON-precise (assignable to JsonValue). */
+export interface CemParameter {
+  name: string;
+  /** Parameter type — JSON Schema or CEM `{ text }` format. */
+  type?: JsonValue;
+  description?: string;
+  optional?: boolean;
+  default?: JsonValue;
+}
+
+/** A CEM-compatible event a function dispatches. JSON-precise (assignable to JsonValue). */
+export interface CemEvent {
+  name: string;
+  type?: JsonValue;
+  description?: string;
+  deprecated?: boolean | string;
+}
 
 export type ContentTypeDef = FromSchema<typeof contentTypeDefSchema>;
 
 export type RefObject = FromSchema<typeof refObjectSchema>;
 
-export type JxStyle = {
+export interface JxStyle {
   [property: string]: string | number | JxStyle | undefined;
-};
+}
 
 export interface JxElement {
   tagName?: string;
-  textContent?: string | null;
+  textContent?: string | null | JxRef;
   innerHTML?: string;
   children?: (JxElement | string)[] | JxMappedArray;
   style?: JxStyle;
-  attributes?: Record<string, unknown>;
+  attributes?: Record<string, JxAttributeValue>;
   className?: string;
   id?: string;
   hidden?: boolean;
@@ -102,8 +209,8 @@ export interface JxElement {
   lang?: string;
   dir?: string;
   $ref?: string;
-  $props?: Record<string, unknown>;
-  $switch?: { $ref: string };
+  $props?: Record<string, JsonValue>;
+  $switch?: string | JxRef;
   cases?: Record<string, JxElement>;
   $prototype?: string;
   $static?: boolean;
@@ -118,18 +225,20 @@ export interface JxElement {
 
 export interface JxMappedArray {
   $prototype: "Array";
-  items: { $ref: string } | unknown;
+  items: Bindable<JsonValue[]>;
   map?: JxElement;
-  filter?: { $ref: string } | unknown;
-  sort?: { $ref: string } | unknown;
+  filter?: Bindable<string>;
+  sort?: Bindable<string>;
 }
 
 export interface JxDocument extends JxElement {
   state?: Record<string, JxStateDefinition>;
+  $layout?: string | false;
+  $paths?: JxPathsDef;
   $elements?: (JxElement | string)[];
   $head?: JxHeadEntry[];
   $media?: Record<string, string>;
-  $defs?: Record<string, unknown>;
+  $defs?: Record<string, JsonValue>;
   imports?: Record<string, string>;
 }
 
@@ -144,35 +253,88 @@ export type PureTypeDef = FromSchema<typeof pureTypeDefSchema>;
 export type ExpressionNode = FromSchema<typeof expressionNodeSchema>;
 export type ExpressionEntry = FromSchema<typeof expressionEntrySchema>;
 
-export type JxStateDefinition = string | number | boolean | null | JxStateObject | JxPrototypeDef;
+/**
+ * Every shape a `state` entry can take — the runtime's five-shape detection algorithm: naked values
+ * (Shape 1), expanded signals / pure type defs (Shape 2/2b), function declarations (Shape 4),
+ * expressions (Shape 5), prototype instances, and server function proxies. Discriminate with the
+ * guards in `@jxsuite/schema/guards`.
+ */
+export type JxStateDefinition =
+  | JsonPrimitive
+  | JsonValue[]
+  | JxFunctionDef
+  | JxPrototypeDef
+  | JxExpressionDef
+  | JxServerFnDef
+  | JxStateObject;
 
+/** An expanded signal (`{ default }`), pure type definition, or naked plain object. */
 export interface JxStateObject {
   type?: string;
-  default?: unknown;
-  properties?: Record<string, unknown>;
-  items?: unknown;
-  enum?: unknown[];
+  default?: JsonValue;
+  properties?: Record<string, JxStateObject>;
+  items?: JxStateObject | JxStateObject[];
+  enum?: JsonValue[];
+  description?: string;
+  /** Linked HTML attribute name for CEM extraction. */
+  attribute?: string;
+  /** Whether property changes reflect back to the HTML attribute. */
+  reflects?: boolean;
+  deprecated?: string | boolean;
   [key: string]: unknown;
 }
 
+/** A `$prototype` instance entry (Request, Storage, ContentCollection, custom classes, …). */
 export interface JxPrototypeDef {
   $prototype: string;
   $src?: string;
   $export?: string;
-  body?: string;
-  parameters?: string[];
+  /** Function body (Function entries) or request body (Request entries). */
+  body?: string | JsonObject;
+  parameters?: (string | CemParameter)[];
   arguments?: string[];
   timing?: "compiler" | "server" | "client";
-  default?: unknown;
+  default?: JsonValue;
   debounce?: number;
   contentType?: string;
-  filter?: Record<string, unknown>;
+  filter?: Record<string, JsonValue>;
   sort?: { field: string; order?: string };
   limit?: number;
-  id?: string | { $ref: string };
+  id?: Bindable<string>;
+  /** Request prototype config. */
+  url?: string;
+  method?: string;
+  manual?: boolean;
+  headers?: Record<string, string>;
+  /** Storage prototype config (LocalStorage / SessionStorage key). */
+  key?: string;
+  /** Cookie prototype config. */
+  name?: string;
+  maxAge?: number;
+  path?: string;
+  domain?: string;
+  secure?: boolean;
+  sameSite?: string;
+  /** IndexedDB prototype config. */
+  database?: string;
+  store?: string;
+  version?: number;
+  keyPath?: string;
+  autoIncrement?: boolean;
+  indexes?: { name: string; keyPath: string; unique?: boolean }[];
+  /** FormData prototype config. */
+  fields?: Record<string, JsonValue>;
   [key: string]: unknown;
 }
 
+// ─── Event Binding Model ────────────────────────────────────────────────────────
+
+/**
+ * The value of an `on*` document key: a `$ref` to a state function, an inline function declaration,
+ * or a declarative expression.
+ */
+export type JxEventBinding = JxRef | JxFunctionDef | JxExpressionDef;
+
 export type StateMap = FromSchema<typeof stateMapSchema>;
 export type DefsMap = FromSchema<typeof defsMapSchema>;
 
@@ -182,6 +344,84 @@ export type ClassMethodDef = FromSchema<typeof classMethodDefSchema>;
 export type ClassParameterDef = FromSchema<typeof classParameterDefSchema>;
 export type ClassConstructorDef = FromSchema<typeof classConstructorDefSchema>;
 
+// ─── Class Definition Model (consumer-friendly) ────────────────────────────────
+// Working types for .class.json schema-defined classes, mirroring class-def.schema.
+
+/** A typed parameter definition (or a `$ref` into `$defs/parameters`). */
+export interface JxClassParamDef {
+  identifier?: string;
+  $ref?: string;
+  type?: unknown;
+  format?: string;
+  default?: JsonValue;
+  description?: string;
+  [key: string]: unknown;
+}
+
+export interface JxClassFieldDef {
+  role?: "field";
+  access?: "public" | "private" | "protected";
+  scope?: "instance" | "static";
+  identifier?: string;
+  type?: unknown;
+  $prototype?: string;
+  initializer?: JsonValue;
+  default?: JsonValue;
+  description?: string;
+  [key: string]: unknown;
+}
+
+export interface JxClassCtorDef {
+  role?: "constructor";
+  $prototype?: "Function";
+  parameters?: JxClassParamDef[];
+  superCall?: { arguments?: string[] };
+  body?: string | string[];
+  description?: string;
+  [key: string]: unknown;
+}
+
+export interface JxClassMethodDef {
+  role?: "method" | "accessor" | "parse" | "serialize" | "discover" | "load";
+  $prototype?: "Function";
+  access?: "public" | "private" | "protected";
+  scope?: "instance" | "static";
+  identifier?: string;
+  timing?: ("compiler" | "server" | "client")[];
+  parameters?: JxClassParamDef[];
+  returnType?: { $ref?: string };
+  body?: string | string[];
+  getter?: { body?: string };
+  setter?: { parameters?: JxClassParamDef[]; body?: string };
+  description?: string;
+  [key: string]: unknown;
+}
+
+/** A .class.json document: `$prototype: "Class"` with fields/constructor/methods in `$defs`. */
+export interface JxClassDef {
+  $prototype: "Class";
+  $schema?: string;
+  $id?: string;
+  title?: string;
+  description?: string;
+  extends?: string | JxRef;
+  $implementation?: string;
+  $defs?: {
+    fields?: Record<string, JxClassFieldDef>;
+    /**
+     * The constructor definition. On objects parsed from JSON without an explicit "constructor"
+     * key, plain property access yields `Object.prototype.constructor` (a Function) — narrow with
+     * `typeof === "object"` before use.
+     */
+    // oxlint-disable-next-line typescript/ban-types, typescript/no-unsafe-function-type -- only `Function` absorbs the inherited Object.prototype.constructor on plain object literals
+    constructor?: JxClassCtorDef | Function;
+    methods?: Record<string, JxClassMethodDef>;
+    parameters?: Record<string, JxClassParamDef>;
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}
+
 export interface ProjectConfig {
   name?: string;
   url?: string;
@@ -194,36 +434,73 @@ export interface ProjectConfig {
   images?: ImageConfig;
   imports?: Record<string, string>;
   contentTypes?: Record<string, ContentTypeDef>;
-  defaults?: { layout?: string; lang?: string; charset?: string; [key: string]: unknown };
+  /** Redirect map: source path → destination (or destination with HTTP status). */
+  redirects?: Record<string, string | { destination: string; status?: number }>;
+  defaults?: {
+    /** Default layout path; `null` means explicitly no layout. */
+    layout?: string | null;
+    lang?: string;
+    charset?: string;
+    [key: string]: unknown;
+  };
   style?: JxStyle;
   [key: string]: unknown;
 }
 
 // ─── Editor/Mutation Types ──────────────────────────────────────────────────────
 
+/** The value of an HTML attribute in a document: a literal or a `$ref` binding. */
+export type JxAttributeValue = Bindable<string | number | boolean>;
+
+/**
+ * A dynamic-route path source (spec §4.3): content-type based, explicit values, data-file ref, or a
+ * legacy array of param objects.
+ */
+export type JxPathsDef =
+  | { contentType: string; param?: string; field?: string }
+  | { values: JsonValue[]; param?: string }
+  | { $ref: string; param?: string; field?: string }
+  | Record<string, JsonValue>[];
+
+/**
+ * The editor's working representation of a document node. Known properties are fully typed;
+ * unrecognized keys (open schema) surface as `unknown` and must be narrowed with the guards in
+ * `@jxsuite/schema/guards` before use.
+ */
 export interface JxMutableNode {
   tagName?: string;
-  textContent?: string | null;
+  textContent?: string | null | JxRef;
   innerHTML?: string;
-  children?: (JxMutableNode | string)[];
-  style?: Record<string, any>;
-  attributes?: Record<string, any>;
+  children?: (JxMutableNode | string)[] | JxMappedArray;
+  style?: JxStyle;
+  attributes?: Record<string, JxAttributeValue>;
   className?: string;
   id?: string;
+  title?: string;
   $ref?: string;
-  $props?: Record<string, unknown>;
-  $switch?: string | { $ref: string };
+  $props?: Record<string, JsonValue>;
+  $switch?: string | JxRef;
   cases?: Record<string, JxMutableNode>;
   $prototype?: string;
   $title?: string;
   $id?: string;
   $src?: string;
-  state?: Record<string, any>;
-  $elements?: (JxMutableNode | string | { $ref: string })[];
+  $layout?: string | false;
+  $static?: boolean;
+  $paths?: JxPathsDef;
+  state?: Record<string, JxStateDefinition>;
+  /** Repeater fields when this node is a mapped-array container. */
+  items?: Bindable<JsonValue[]>;
+  filter?: Bindable<string>;
+  sort?: Bindable<string>;
+  map?: JxMutableNode;
+  $elements?: (JxMutableNode | string | JxRef)[];
   $head?: JxHeadEntry[];
   $media?: Record<string, string>;
-  $defs?: Record<string, any>;
-  [key: string]: any;
+  $defs?: Record<string, JsonValue>;
+  imports?: Record<string, string>;
+  observedAttributes?: string[];
+  [key: string]: unknown;
 }
 
 // ─── Paths ──────────────────────────────────────────────────────────────────────
@@ -232,8 +509,19 @@ export type JxPath = (string | number)[];
 
 // ─── Content Type Schema ────────────────────────────────────────────────────────
 
+/** One field within a content-type JSON schema; recursive for nested objects. */
+export interface ContentTypeSchemaField {
+  type?: string;
+  $ref?: string;
+  properties?: Record<string, ContentTypeSchemaField>;
+  items?: ContentTypeSchemaField;
+  required?: string[];
+  description?: string;
+  [key: string]: unknown;
+}
+
 export interface ContentTypeSchema {
-  properties?: Record<string, any>;
+  properties?: Record<string, ContentTypeSchemaField>;
   required?: string[];
   [key: string]: unknown;
 }