@jxsuite/schema 2.1.0 → 2.3.0

package/src/schema.ts

@@ -199,9 +199,17 @@ function buildEventHandlerProperties(eventHandlers: string[]) {
 }
 
 function buildCssProperties(cssProps: string[]) {
-  const properties: Record<string, unknown> = {};
+  /* The authored `properties` come first so a `$`-prefixed metadata key survives: this function
+     REPLACES the block's properties rather than adding to them, so anything the hand-written schema
+     declared there was silently dropped — which is how `$description` validated as a number. */
+  const properties: Record<string, unknown> = { ...styleObjectSchema.properties };
   for (const name of cssProps) {
-    properties[name] = { oneOf: [{ type: "string" }, { type: "number" }] };
+    /* A `{ $ref }` is a reactive VALUE, which the runtime has always resolved (spec.md §9.6) and
+       only the validator refused: `style: { fontFamily: { $ref: "$map/item/face" } }` reported
+       "must be string". It is what lets a row render in the face it names. */
+    properties[name] = {
+      oneOf: [{ type: "string" }, { type: "number" }, { $ref: "#/$defs/RefObject" }],
+    };
   }
   return properties;
 }
@@ -493,13 +501,29 @@ export async function generateSchema() {
   };
 }
 
+/**
+ * `StyleObject` without the reactive-value branch, for a schema whose style block is emitted
+ * STATICALLY.
+ *
+ * A project's `style` block becomes the site stylesheet at build time, with no live scope to
+ * resolve against — so a `{ $ref }` there could never mean anything, and admitting it would
+ * validate a document the builder must silently drop. The document schema keeps the branch, because
+ * an element's style IS resolved against a scope.
+ */
+const staticStyleObjectSchema = {
+  ...styleObjectSchema,
+  additionalProperties: {
+    anyOf: [{ type: "string" }, { type: "number" }, { $ref: "#/$defs/StyleObject" }],
+  },
+} as const;
+
 // ─── Project Schema Generator ────────────────────────────────────────────────
 
 export function generateProjectSchema() {
   return {
     $defs: {
       ImageConfig: imageConfigSchema,
-      StyleObject: styleObjectSchema,
+      StyleObject: staticStyleObjectSchema,
     },
     $id: "https://jxsuite.com/schema/project/v1",
     $schema: "https://json-schema.org/draft/2020-12/schema",
@@ -531,7 +555,7 @@ export function generateProjectCoreSchema() {
       ImageConfig: imageConfigSchema,
       JxFieldSchema: jxFieldSchemaDef,
       RelationshipRef: relationshipRefSchema,
-      StyleObject: styleObjectSchema,
+      StyleObject: staticStyleObjectSchema,
     },
     $id: "https://jxsuite.com/schema/project/core/v2",
     $schema: "https://json-schema.org/draft/2020-12/schema",

package/types.ts

@@ -149,11 +149,23 @@ export interface JxDispatchStatement {
  * One statement of a structured function body: a bare expression node in statement position
  * (mutation or `call`), a branch, a multiway branch, or an event dispatch.
  */
+/** `{ stopPropagation: true }` — stop the handler's event at the current target (WHATWG DOM). */
+export interface JxStopPropagationStatement {
+  stopPropagation: true;
+}
+
+/** `{ preventDefault: true }` — cancel the handler's event's default action (WHATWG DOM). */
+export interface JxPreventDefaultStatement {
+  preventDefault: true;
+}
+
 export type JxStatement =
   | JxExpressionNode
   | JxIfStatement
   | JxSwitchStatement
-  | JxDispatchStatement;
+  | JxDispatchStatement
+  | JxStopPropagationStatement
+  | JxPreventDefaultStatement;
 
 /** A function declaration: inline `body` or external `$src`/`$export`. */
 export interface JxFunctionDef {
@@ -250,7 +262,14 @@ export interface CemEvent {
 export type RefObject = FromSchema<typeof refObjectSchema>;
 
 export interface JxStyle {
-  [property: string]: string | number | JxStyle | undefined;
+  /**
+   * A declaration's value, a nested block, or SEVERAL blocks under one key.
+   *
+   * The array is what `@font-face` needs: an object's keys are unique, so a key can name a rule
+   * once, and that at-rule's identity is not in its key — a family with three weights has no other
+   * spelling. It means what writing the key that many times would mean, in order (spec.md §9.4).
+   */
+  [property: string]: string | number | RefObject | JxStyle | JxStyle[] | undefined;
 }
 
 /**
@@ -313,6 +332,11 @@ export interface JxMappedArray {
   map?: JxElement;
   filter?: Bindable<string>;
   sort?: Bindable<string>;
+  /**
+   * A `$map/item` pointer naming each row's identity (spec §10.4). Keyed rows keep their DOM node
+   * and effects across reorders, insertions and removals; absent, rows are keyed by index.
+   */
+  key?: JxRef;
 }
 
 export interface JxDocument extends JxElement {