@jxsuite/schema 2.1.0 → 2.3.0

package/README.md

@@ -42,6 +42,13 @@ const schema = await generateSchema(); // component meta-schema object
 const valid = await validateDocument(doc); // validate a Jx document
 ```
 
+## Documents as data
+
+Two subpaths let any host edit and write a Jx document the way Studio does, with no DOM, no reactive store and no yjs:
+
+- **`@jxsuite/schema/doc-ops`** is the document-op vocabulary. A `JxDocOp` (`set-key`, `insert-child`, `remove-child`, `set-child`, `move-child`) is a value-carrying mutation addressed by `JxPath`. `applyDocOpToDoc(doc, op)` applies one to a plain tree; `inverseOf(doc, op)` computes the op that undoes it, against the document as it stands before the op, in the coordinates of the document after it; `applyDocOpsWithInverse(doc, ops)` applies a sequence and answers each forward/inverse pair. Studio's history, the canvas iframe's shadow document and the collab bridge all replay through this one implementation, and `@jxsuite/collab/ops` re-exports it. Undoing an insert or move into a node that had no `children` leaves `children: []` behind, as Studio's history always has.
+- **`@jxsuite/schema/json-layout`** is the layout-preserving JSON serializer behind every save. `parseJsonDocument(text)` answers the document and the facts about its text the formatter keeps; `serializeJson(document, layout)` writes it back with those honoured, so a one-value edit is a one-line diff.
+
 ## Component schema coverage
 
 - **`tagName`**: all standard HTML element names from `@webref/elements`

package/defs/children-value.schema.ts

@@ -7,6 +7,19 @@ export const arrayNamespaceSchema = {
     items: {
       oneOf: [{ $ref: "#/$defs/RefObject" }, { type: "array" }],
     },
+    key: {
+      additionalProperties: false,
+      description:
+        "The identity of each rendered row: a $map/item pointer read per item. A row whose key " +
+        "survives a change keeps its DOM node and its effects across reorders, insertions and " +
+        "removals; without a key, rows are keyed by index. $map/index is not a key — an index " +
+        "names a position, not a row.",
+      properties: {
+        $ref: { pattern: "^\\$map/item(/.+)?$", type: "string" },
+      },
+      required: ["$ref"],
+      type: "object",
+    },
     map: { $ref: "#/$defs/ElementDef" },
     sort: { $ref: "#/$defs/RefObject" },
   },

package/defs/element-def.schema.ts

@@ -40,10 +40,13 @@ export const elementPropertyValueSchema = {
 
 export const switchDefSchema = {
   additionalProperties: false,
-  description: "Reactive $ref that drives which case to render.",
-  // The discriminant is a reactive state path (e.g. "#/state/currentRoute") resolved by
-  // ResolveRef at render time — not a #/$defs/ type pointer.
-  properties: { $ref: { $ref: "#/$defs/StateRef" } },
+  description:
+    "Reactive $ref that drives which case to render: a state entry, or inside a mapped array's template the row's $map/item or $map/index (spec §14.1).",
+  // The discriminant is a reactive state path (e.g. "#/state/currentRoute") or a row pointer
+  // ("$map/item/dividerAbove") resolved by ResolveRef at render time — not a #/$defs/ type pointer.
+  properties: {
+    $ref: { oneOf: [{ $ref: "#/$defs/StateRef" }, { $ref: "#/$defs/MapRef" }], type: "string" },
+  },
   required: ["$ref"],
   type: "object",
 } as const;

package/defs/statement.schema.ts

@@ -6,12 +6,13 @@
  * 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.
+ * convention in statement position, and WHATWG's `dispatchEvent` with `CustomEventInit` members,
+ * `stopPropagation` and `preventDefault`.
  */
 
 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).",
+    "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), a dispatchEvent statement (WHATWG DOM: dispatches a CustomEvent from the handler's current target, with CustomEventInit members detail/bubbles/composed), or the two WHATWG event verbs stopPropagation and preventDefault, each spelled as the member set to true.",
   oneOf: [
     { $ref: "#/$defs/ExpressionNode" },
     {
@@ -54,6 +55,32 @@ export const statementSchema = {
       title: "dispatchEvent — emit a CustomEvent (WHATWG naming, CustomEventInit members)",
       type: "object",
     },
+    {
+      additionalProperties: false,
+      properties: {
+        stopPropagation: {
+          const: true,
+          description:
+            "Stop the handler's event at the current target (WHATWG DOM stopPropagation), so an ancestor's handler for the same event does not run. A body run without an event has nothing to stop.",
+        },
+      },
+      required: ["stopPropagation"],
+      title: "stopPropagation — stop the event here (WHATWG DOM)",
+      type: "object",
+    },
+    {
+      additionalProperties: false,
+      properties: {
+        preventDefault: {
+          const: true,
+          description:
+            "Cancel the handler's event's default action (WHATWG DOM preventDefault): a link's navigation, a form's submission, a key's scroll.",
+        },
+      },
+      required: ["preventDefault"],
+      title: "preventDefault — cancel the event's default action (WHATWG DOM)",
+      type: "object",
+    },
   ],
 } as const;
 

package/defs/style-object.schema.ts

@@ -1,13 +1,62 @@
 export const styleObjectSchema = {
+  /* AnyOf, not oneOf, for the reason `propsObjectSchema` gives: a `{ $ref }` legitimately matches
+     both branches. It is a reactive VALUE, and it is also — vacuously — a nested block holding one
+     declaration named `$ref`, because a block admits a string under any key. Exclusive matching
+     rejects it as ambiguous, which is what `oneOf` did the moment RefObject was added here. The
+     ambiguity is harmless: the runtime reads an object carrying `$ref` as a value, and nothing
+     else can. */
   additionalProperties: {
-    oneOf: [{ type: "string" }, { type: "number" }, { $ref: "#/$defs/StyleObject" }],
+    anyOf: [
+      { type: "string" },
+      { type: "number" },
+      { $ref: "#/$defs/RefObject" },
+      { $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: {},
+    "(e.g. breakpoint → selector → pseudo-class), mirroring the compiler's recursive emission. " +
+    "An object carrying $ref is a reactive VALUE, and the runtime reads it as one. It also " +
+    "matches the nested-block branch vacuously, since a block admits a string under any key, " +
+    "which is why these branches are anyOf rather than oneOf. " +
+    "A DECLARATION at-rule (@font-face, @property, @position-try, @counter-style) may hold an " +
+    "ARRAY of blocks, which is that key written more than once, in order: an object's keys are " +
+    "unique, so @font-face — the at-rule whose identity is not in its key — could not otherwise " +
+    "state a family's second weight at all.",
+  patternProperties: {
+    /*
+     * A DECLARATION at-rule, and only one of those four, may hold several blocks.
+     *
+     * `additionalProperties` below admits no array, so this is the whole of it. The builder scopes
+     * the form the same way (`blocksOf` in `packages/runtime/src/css.ts`), and the two must agree:
+     * a schema that admitted an array under a selector would validate a document the builder
+     * silently drops, which is the same trap `staticStyleObjectSchema` exists to avoid one level up.
+     */
+    "^@(font-face|property|position-try|counter-style)": {
+      anyOf: [
+        { $ref: "#/$defs/StyleObject" },
+        { items: { $ref: "#/$defs/StyleObject" }, minItems: 1, type: "array" },
+      ],
+    },
+  },
+  properties: {
+    /*
+     * Prose, not a declaration: why the rule exists, in the author's words.
+     *
+     * A style block had nowhere to say that, and writing it anyway emitted
+     * `$description: why this exists;` — an invalid declaration the parser drops in silence, with
+     * the prose inside the text the runtime interns rules by. Every `$`-prefixed key is metadata
+     * here for the same reason it is everywhere else in a document, and no CSS property begins with
+     * `$`. A static emitter renders it as a comment; the runtime ignores it.
+     */
+    $description: {
+      description:
+        "Why this rule exists. Emitted as a comment by static builds, ignored at runtime.",
+      type: "string",
+    },
+  },
   type: "object",
 } as const;

package/package.json

@@ -1,8 +1,8 @@
 {
   "dependencies": {
-    "@webref/css": "^8.7.3",
-    "@webref/elements": "^2.8.0",
-    "@webref/idl": "^3.83.0",
+    "@webref/css": "^8.7.5",
+    "@webref/elements": "^2.9.0",
+    "@webref/idl": "^3.84.0",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1"
   },
@@ -20,8 +20,13 @@
     "./locale": "./src/locale.ts",
     "./intl": "./src/intl.ts",
     "./media-type": "./src/media-type.ts",
+    "./overlays": "./src/overlays.ts",
+    "./dialogs": "./src/dialogs.ts",
+    "./a11y": "./src/a11y.ts",
     "./ijson": "./src/ijson.ts",
     "./parse": "./src/parse.ts",
+    "./doc-ops": "./src/doc-ops.ts",
+    "./json-layout": "./src/json-layout.ts",
     "./defs": "./defs/index.ts",
     "./schema.json": "./schema.json",
     "./project-schema.json": "./project-schema.json",
@@ -55,7 +60,7 @@
     "upgrade": "bun update --latest && bun install"
   },
   "type": "module",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "devDependencies": {
     "json-schema-to-ts": "^3.1.1"
   }

package/project-schema.json

@@ -65,7 +65,7 @@
     },
     "StyleObject": {
       "additionalProperties": {
-        "oneOf": [
+        "anyOf": [
           {
             "type": "string"
           },
@@ -77,8 +77,29 @@
           }
         ]
       },
-      "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": {},
+      "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. An object carrying $ref is a reactive VALUE, and the runtime reads it as one. It also matches the nested-block branch vacuously, since a block admits a string under any key, which is why these branches are anyOf rather than oneOf. A DECLARATION at-rule (@font-face, @property, @position-try, @counter-style) may hold an ARRAY of blocks, which is that key written more than once, in order: an object's keys are unique, so @font-face — the at-rule whose identity is not in its key — could not otherwise state a family's second weight at all.",
+      "patternProperties": {
+        "^@(font-face|property|position-try|counter-style)": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/StyleObject"
+            },
+            {
+              "items": {
+                "$ref": "#/$defs/StyleObject"
+              },
+              "minItems": 1,
+              "type": "array"
+            }
+          ]
+        }
+      },
+      "properties": {
+        "$description": {
+          "description": "Why this rule exists. Emitted as a comment by static builds, ignored at runtime.",
+          "type": "string"
+        }
+      },
       "type": "object"
     }
   },