@jxsuite/schema 1.4.0 → 1.8.0

package/class-schema.json

@@ -181,6 +181,7 @@
             "resolvePaths",
             "lower",
             "emit",
+            "head",
             "assets",
             "mount",
             "dialect",

package/defs/children-value.schema.ts

@@ -23,8 +23,17 @@ export const childrenValueSchema = {
   oneOf: [
     {
       items: {
-        oneOf: [
+        /* `anyOf`, not `oneOf`, and SwitchNode is the reason for both halves of that.
+           `$defs.SwitchNode` was defined and referenced from nowhere — a node the compiler fully
+           renders (`shared.ts` renderSwitch) that no position in the schema admitted, so every
+           document with a `$switch` child failed `jx validate`. Adding the ref under `oneOf` would
+           have traded one break for another: a switch child that also carries `tagName` (its
+           container element) matches ElementDef AND SwitchNode, and "exactly one" then rejects the
+           form that works today. `anyOf` accepts both, and still rejects a child object that is
+           neither. */
+        anyOf: [
           { $ref: "#/$defs/ElementDef" },
+          { $ref: "#/$defs/SwitchNode" },
           { $ref: "#/$defs/ArrayNamespace" },
           { type: "string" },
           { type: "number" },

package/defs/class-def.schema.ts

@@ -15,6 +15,7 @@ export const CLASS_METHOD_ROLES = [
   "resolvePaths",
   "lower",
   "emit",
+  "head",
   "assets",
   "mount",
   "dialect",

package/defs/element-def.schema.ts

@@ -100,7 +100,7 @@ export const elementDefSchema = {
     src: { $ref: "#/$defs/StringOrRef" },
     style: { $ref: "#/$defs/StyleObject" },
     tabIndex: { $ref: "#/$defs/NumberOrRef" },
-    tagName: { $ref: "#/$defs/TagName" },
+    tagName: { $ref: "#/$defs/ElementTagName" },
     textContent: { $ref: "#/$defs/StringOrRef" },
     title: { $ref: "#/$defs/StringOrRef" },
     type: { $ref: "#/$defs/StringOrRef" },

package/defs/expression-node.schema.ts

@@ -1,3 +1,5 @@
+import { intlHelpersClause } from "../src/intl.ts";
+
 export const expressionPointerSchema = {
   additionalProperties: false,
   description:
@@ -199,7 +201,8 @@ export const expressionNodeSchema = {
     },
     {
       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.",
+        "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 " +
+        `${intlHelpersClause()}) — 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" },

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

@@ -57,8 +57,26 @@ export const externalClassDefSchema = {
     default: {},
     description: { type: "string" },
     domain: { type: "string" },
-    expires: { type: "string" },
-    filter: { $ref: "#/$defs/RefObject" },
+    /* Widened to mirror `sort` below, because this one grab-bag of properties is shared by EVERY
+       state `$prototype` with no discrimination on which prototype is in play. `filter` as a
+       reactive `$ref` is what the built-in `Array` prototype wants; `@jxsuite/parser`'s
+       ContentCollection and `@jxsuite/connector`'s TableQuery both declare their own `filter` as a
+       rule ARRAY, and the core shape silently overrode the class's own declaration — so a document
+       using a documented class parameter correctly failed `jx validate` with "must be object". */
+    filter: {
+      anyOf: [
+        { $ref: "#/$defs/RefObject" },
+        { description: "A single filter object, e.g. an equality shorthand.", type: "object" },
+        {
+          description: 'Ordered filter rules, e.g. [{ field: "Slug", op: "not empty" }].',
+          items: { type: "object" },
+          type: "array",
+        },
+      ],
+      description:
+        "Filter configuration: a reactive $ref binding, a single filter object, or an ordered " +
+        "array of rules.",
+    },
     headers: { additionalProperties: { type: "string" }, type: "object" },
     indexes: {
       items: {

package/defs/field-schema.schema.ts

@@ -56,3 +56,78 @@ export const relationshipRefSchema = {
   required: ["$ref"],
   type: "object",
 } as const;
+
+/**
+ * The CORE `$paths` source shapes — the members the shipped default paths union carries, and the
+ * ones every per-project entry document unions extension shapes on top of.
+ *
+ * These mirror `resolvePathEntries` in the compiler's pages-discovery exactly (specs/
+ * site-architecture.md §4.3): an explicit value list, a JSON data-file reference, and the legacy
+ * bare array of parameter objects. Anything else is dispatched by discriminator key to an
+ * extension's `resolvePaths` capability, so extension shapes reach the union through the entry
+ * document rather than from here.
+ *
+ * Each shape is CLOSED (`additionalProperties: false`). `$paths` is a build-time instruction with a
+ * fully specified grammar and no forward-compatible extension points of its own — a stray or
+ * misspelled key means the route silently expands to nothing, which is exactly the failure worth
+ * catching in the editor.
+ */
+export const documentPathsCoreMembers = [
+  {
+    additionalProperties: false,
+    description:
+      'Explicit value list: generates one page per value, bound to `param` (default "value").',
+    properties: {
+      param: { description: 'Route parameter to fill (default "value").', type: "string" },
+      values: { description: "The values to expand.", type: "array" },
+    },
+    required: ["values"],
+    type: "object",
+  },
+  {
+    additionalProperties: false,
+    description:
+      "JSON data-file source: loads a project-relative file that must contain an array, and " +
+      "generates one page per item.",
+    properties: {
+      $ref: {
+        description: "Project-relative path to a .json file containing an array.",
+        type: "string",
+      },
+      field: {
+        description: 'Item field providing the parameter value (default "id").',
+        type: "string",
+      },
+      param: { description: 'Route parameter to fill (default "id").', type: "string" },
+    },
+    required: ["$ref"],
+    type: "object",
+  },
+  {
+    description:
+      "Legacy explicit form: an array of ready-made parameter objects, used as-is with no " +
+      "expansion. Prefer one of the source shapes above.",
+    items: { additionalProperties: { type: "string" }, type: "object" },
+    type: "array",
+  },
+] as const;
+
+/**
+ * The extra member the SHIPPED DEFAULT union carries and a per-project entry document does not.
+ *
+ * A default cannot know which extensions a project enables, so without this any extension source
+ * shape — `{ contentType: "blog" }` with the parser on — would be a FALSE ERROR wherever the
+ * default is what is in play: the studio's offline fallback before per-project schemas arrive, and
+ * clients that fetch the canonical URL. Spec §5.4 promises that path degrades to
+ * _under-suggestion_, never false errors, so the default accepts any non-empty object and the entry
+ * document — which does know the enabled extensions, and is what `jx validate` and every editor
+ * actually resolve — is the strict one.
+ */
+export const documentPathsUnknownSourceMember = {
+  description:
+    "A source shape contributed by an extension this schema cannot see. The project's generated " +
+    "document.schema.json validates these exactly; enable the owning extension and regenerate " +
+    "with `jx schema` to get precise checking here.",
+  minProperties: 1,
+  type: "object",
+} as const;

package/defs/head-entry.schema.ts

@@ -10,7 +10,12 @@ export const headEntrySchema = {
     },
     children: { items: { $ref: "#/$defs/HeadEntry" }, type: "array" },
     tagName: { type: "string" },
-    textContent: { type: "string" },
+    textContent: {
+      description:
+        "Element content. An object is serialized to JSON inside the tag — that is how a " +
+        'JSON-LD block (`<script type="application/ld+json">`) is authored.',
+      oneOf: [{ type: "string" }, { type: "object" }],
+    },
   },
   required: ["tagName"],
   type: "object",

package/defs/image-config.schema.ts

@@ -4,6 +4,13 @@ export const imageConfigSchema = {
     formats: { items: { type: "string" }, type: "array" },
     lazyLoad: { type: "boolean" },
     optimize: { type: "boolean" },
+    picture: {
+      description:
+        "Wrap a multi-format image in a <picture> with one <source> per format (default true). " +
+        "With it off the <img> carries a srcset in the preferred format alone, which browsers " +
+        "that cannot decode that format will still select from.",
+      type: "boolean",
+    },
     quality: {
       properties: {
         avif: { type: "number" },

package/defs/index.ts

@@ -1,4 +1,5 @@
 // Leaf schemas
+export { elementTagNameSchema, tagExpressionSchema } from "./tag-expression.schema";
 export { tagNameSchema } from "./tag-name.schema";
 export { stringOrRefSchema, boolOrRefSchema, numberOrRefSchema } from "./string-or-ref.schema";
 export { headEntrySchema } from "./head-entry.schema";
@@ -83,7 +84,7 @@ export {
 } from "./class-def.schema";
 
 // Project
-export { projectConfigSchema } from "./project-config.schema";
+export { projectConfigSchema, REDIRECT_STATUSES } from "./project-config.schema";
 
 // Extensions (specs/extensions.md)
 export { extensionManifestSchema } from "./extension-manifest.schema";

package/defs/project-config.schema.ts

@@ -1,3 +1,14 @@
+import { LANGUAGE_TAG_PATTERN } from "../src/locale.ts";
+
+/**
+ * The RFC 9110 §15.4 redirection statuses a static host can express. 303 preserves the "see other,
+ * with GET" semantics; 307 and 308 preserve the request method, which 301 and 302 historically do
+ * not. **200 is not here**: a host's rewrite/proxy convention is not a redirection status, and
+ * modelling it as one is what let the compiler emit a meta-refresh page for a rewrite. Rewrites are
+ * `{ destination, rewrite: true }`.
+ */
+export const REDIRECT_STATUSES = [301, 302, 303, 307, 308] as const;
+
 export const projectConfigSchema = {
   description:
     "Schema for Jx project.json files. " +
@@ -126,6 +137,116 @@ export const projectConfigSchema = {
           description: "Output directory for compiled site.",
           type: "string",
         },
+        headers: {
+          additionalProperties: false,
+          description:
+            "Emit dist/_headers — the response headers only the build can know. Honored by " +
+            "Cloudflare Pages/Workers assets and Netlify; on the node/bun adapters the file " +
+            "documents what a reverse proxy in front of them must send.",
+          properties: {
+            cache: {
+              default: "auto",
+              description:
+                '"auto" marks the content-addressed image variants immutable (RFC 8246) and ' +
+                'revalidates everything else (RFC 9111). "off" emits no Cache-Control at all.',
+              enum: ["auto", "off"],
+              type: "string",
+            },
+            enabled: { default: true, type: "boolean" },
+            rules: {
+              additionalProperties: { additionalProperties: { type: "string" }, type: "object" },
+              description: "Verbatim rules, merged after the generated block.",
+              propertyNames: { pattern: "^/" },
+              type: "object",
+            },
+            security: {
+              additionalProperties: false,
+              properties: {
+                contentTypeOptions: { default: true, type: "boolean" },
+                csp: {
+                  default: false,
+                  description:
+                    "CSP Level 3. Off by default: unlike the other security headers this one " +
+                    "governs code the build cannot see — a third-party script that loads a " +
+                    "second script, a widget that opens a frame — so turning it on is a change " +
+                    "to verify in the browser console, not a safe default. `script-src` is " +
+                    "derived from the inline scripts and external origins the build emitted; " +
+                    "`style-src` keeps 'unsafe-inline', because per-page <style> blocks and " +
+                    "per-element style attributes have no site-wide hash.",
+                  oneOf: [
+                    { type: "boolean" },
+                    { const: "report-only" },
+                    {
+                      additionalProperties: false,
+                      properties: {
+                        directives: {
+                          additionalProperties: {
+                            oneOf: [{ type: "string" }, { const: false }],
+                          },
+                          description:
+                            "Replace (string) or remove (false) a computed directive. A " +
+                            "replacement is wholesale, so an addition restates the defaults.",
+                          type: "object",
+                        },
+                        mode: { default: "enforce", enum: ["enforce", "report-only"] },
+                        reportUri: { format: "uri-reference", type: "string" },
+                      },
+                      type: "object",
+                    },
+                  ],
+                },
+                frameOptions: {
+                  default: "SAMEORIGIN",
+                  oneOf: [{ enum: ["DENY", "SAMEORIGIN"], type: "string" }, { const: false }],
+                },
+                hsts: {
+                  default: false,
+                  description:
+                    "RFC 6797. Off by default: a wrong max-age locks the apex domain to HTTPS " +
+                    "for that long, and the mistake is invisible until a certificate lapses. " +
+                    "`preload` requires `includeSubDomains` and is a build error without it.",
+                  oneOf: [
+                    { type: "boolean" },
+                    {
+                      additionalProperties: false,
+                      properties: {
+                        includeSubDomains: { default: true, type: "boolean" },
+                        maxAge: { default: 31_536_000, minimum: 0, type: "integer" },
+                        preload: { default: false, type: "boolean" },
+                      },
+                      type: "object",
+                    },
+                  ],
+                },
+                permissionsPolicy: {
+                  default: "camera=(), microphone=(), geolocation=()",
+                  oneOf: [{ type: "string" }, { const: false }],
+                },
+                referrerPolicy: {
+                  default: "strict-origin-when-cross-origin",
+                  oneOf: [
+                    {
+                      enum: [
+                        "no-referrer",
+                        "no-referrer-when-downgrade",
+                        "origin",
+                        "origin-when-cross-origin",
+                        "same-origin",
+                        "strict-origin",
+                        "strict-origin-when-cross-origin",
+                        "unsafe-url",
+                      ],
+                      type: "string",
+                    },
+                    { const: false },
+                  ],
+                },
+              },
+              type: "object",
+            },
+          },
+          type: "object",
+        },
         sitemap: {
           default: true,
           description:
@@ -155,9 +276,17 @@ export const projectConfigSchema = {
           description: "Default charset for the page.",
           type: "string",
         },
+        dir: {
+          description:
+            "Base direction for the <html> element. Omitted when unset — a page's `$dir` " +
+            "overrides it. Right-to-left content renders left-to-right without this.",
+          enum: ["ltr", "rtl", "auto"],
+          type: "string",
+        },
         lang: {
           default: "en",
-          description: "Default lang attribute for the <html> element.",
+          description:
+            "Default lang attribute for the <html> element. A page's `$lang` overrides it.",
           type: "string",
         },
         layout: {
@@ -168,6 +297,18 @@ export const projectConfigSchema = {
           examples: ["./layouts/base.json"],
           oneOf: [{ type: "string" }, { type: "null" }],
         },
+        shadow: {
+          default: false,
+          description:
+            "Default shadow-DOM mode for every component (spec.md §16.6). Off unless set: a " +
+            "shadow root isolates component styles from the page and replaces the <slot> " +
+            "emulation with real slot distribution. A component's own `$shadow` overrides this " +
+            "in both directions.",
+          oneOf: [
+            { enum: ["open", "closed"], type: "string" },
+            { const: false, type: "boolean" },
+          ],
+        },
       },
       type: "object",
     },
@@ -179,18 +320,127 @@ export const projectConfigSchema = {
       items: { type: "string" },
       type: "array",
     },
+    manifest: {
+      additionalProperties: false,
+      description:
+        'W3C Web App Manifest, emitted as manifest.webmanifest with a <link rel="manifest"> ' +
+        "on every page. Absent means no manifest: it is a claim that a site is meant to be " +
+        "installed, and most are not.",
+      properties: {
+        backgroundColor: { type: "string" },
+        categories: { items: { type: "string" }, type: "array" },
+        description: { type: "string" },
+        dir: { enum: ["ltr", "rtl", "auto"], type: "string" },
+        display: {
+          default: "standalone",
+          enum: ["fullscreen", "standalone", "minimal-ui", "browser"],
+          type: "string",
+        },
+        enabled: { default: true, type: "boolean" },
+        icons: {
+          description:
+            "Icons at 192px and 512px are what browsers require before offering to install " +
+            "the site; the build warns when either is missing.",
+          items: {
+            additionalProperties: false,
+            properties: {
+              purpose: { type: "string" },
+              sizes: { examples: ["192x192"], type: "string" },
+              src: { type: "string" },
+              type: { type: "string" },
+            },
+            required: ["src"],
+            type: "object",
+          },
+          type: "array",
+        },
+        lang: { type: "string" },
+        name: { description: "Defaults to the project name.", type: "string" },
+        orientation: { type: "string" },
+        scope: { type: "string" },
+        shortName: { type: "string" },
+        startUrl: { default: "/", type: "string" },
+        themeColor: { type: "string" },
+      },
+      type: "object",
+    },
+    serviceWorker: {
+      default: false,
+      description:
+        "W3C Service Worker, emitted as sw.js. Off unless declared — a worker is sticky, so it " +
+        "is the one output that can keep breaking visitors after a deploy tries to fix them. " +
+        "**Turning it off means `false`, not deleting the key**: `false` emits a tombstone at " +
+        "the same URL that unregisters the old worker and clears its caches, and a 404 there is " +
+        "not an instruction to stop. HTML is always network-first; only the content-addressed " +
+        "/images/_optimized/* is served cache-first.",
+      oneOf: [
+        { type: "boolean" },
+        {
+          additionalProperties: false,
+          properties: {
+            enabled: { default: true, type: "boolean" },
+            offlineFallback: {
+              description:
+                "Page served for a failed navigation. Added to `precache` if not already there.",
+              type: "string",
+            },
+            precache: {
+              description:
+                "Site-absolute URLs fetched at install time. Each must be a file this build " +
+                "produces; one that is not fails the build, because a single unreachable entry " +
+                "stops the worker installing at all.",
+              items: { pattern: "^/", type: "string" },
+              type: "array",
+            },
+            scope: { default: "/", type: "string" },
+          },
+          type: "object",
+        },
+      ],
+    },
+    securityTxt: {
+      additionalProperties: false,
+      description:
+        "RFC 9116 security.txt, emitted at .well-known/security.txt. `expires` is required by " +
+        "§2.5.5 and an absent or past value is a build error — an expired file advertises a " +
+        "reporting channel while telling the reporter not to trust it. A hand-placed " +
+        "public/.well-known/security.txt shadows this, which is how a clearsigned file ships.",
+      properties: {
+        acknowledgments: { items: { type: "string" }, type: "array" },
+        canonical: { type: "string" },
+        contact: {
+          description: "At least one mailto:, https: or tel: URI (§2.5.3).",
+          items: { type: "string" },
+          type: "array",
+        },
+        enabled: { default: true, type: "boolean" },
+        encryption: { items: { type: "string" }, type: "array" },
+        expires: { format: "date-time", type: "string" },
+        hiring: { items: { type: "string" }, type: "array" },
+        policy: { items: { type: "string" }, type: "array" },
+        preferredLanguages: {
+          description: "BCP 47 tags, validated and canonicalized like i18n.locales.",
+          items: { pattern: LANGUAGE_TAG_PATTERN, type: "string" },
+          type: "array",
+        },
+      },
+      type: "object",
+    },
     i18n: {
       description: "Internationalization configuration.",
       properties: {
         defaultLocale: {
-          description: "Default locale code.",
+          description:
+            "Default locale, as a BCP 47 language tag. The pattern catches shape errors " +
+            "(`en_US`, `en--US`); the build is the authority on well-formedness.",
           examples: ["en"],
+          pattern: LANGUAGE_TAG_PATTERN,
           type: "string",
         },
         locales: {
-          description: "Available locale codes.",
+          description: "Available locales, as BCP 47 language tags.",
           examples: [["en", "fr", "de"]],
-          items: { type: "string" },
+          items: { pattern: LANGUAGE_TAG_PATTERN, type: "string" },
           type: "array",
         },
         routing: {
@@ -222,9 +472,51 @@ export const projectConfigSchema = {
       type: "string",
     },
     redirects: {
-      additionalProperties: { type: "string" },
-      description: "Static redirect rules. Maps source paths to destination paths.",
-      examples: [{ "/old-about": "/about" }],
+      additionalProperties: {
+        oneOf: [
+          { description: "Destination path or URL; implies a 301.", type: "string" },
+          {
+            additionalProperties: false,
+            description: "A redirect with an explicit RFC 9110 §15.4 status.",
+            properties: {
+              destination: { type: "string" },
+              status: {
+                default: 301,
+                description:
+                  "RFC 9110 §15.4 redirection status. 307 and 308 preserve the request method; " +
+                  "301 and 302 historically do not.",
+                enum: [...REDIRECT_STATUSES],
+                type: "integer",
+              },
+            },
+            required: ["destination"],
+            type: "object",
+          },
+          {
+            additionalProperties: false,
+            description:
+              "A rewrite (proxy): the destination's content is served AT the source URL, with no " +
+              "redirect. Emitted as status 200 in `_redirects`, which is the host convention — " +
+              "not an HTTP redirection status.",
+            properties: {
+              destination: { type: "string" },
+              rewrite: { const: true, type: "boolean" },
+            },
+            required: ["destination", "rewrite"],
+            type: "object",
+          },
+        ],
+      },
+      description:
+        "Static redirect and rewrite rules. Keys are source paths in URLPattern pathname syntax.",
+      examples: [
+        {
+          "/api/*": { destination: "https://api.example.com/*", rewrite: true },
+          "/legacy/*": { destination: "/archive/*", status: 308 },
+          "/old-about": "/about",
+        },
+      ],
+      propertyNames: { pattern: "^/" },
       type: "object",
     },
     state: {