@jxsuite/schema 1.9.0 → 2.1.0

package/README.md

@@ -44,12 +44,12 @@ const valid = await validateDocument(doc); // validate a Jx document
 
 ## Component schema coverage
 
-- **`tagName`** — all standard HTML element names from `@webref/elements`
-- **Element properties** — all DOM IDL properties from `@webref/idl`
-- **`style`** — all CSSOM camelCase properties from `@webref/css`
-- **Event handlers** — all `EventHandler` names (`onclick`, `oninput`, …)
-- **`state` shapes** — naked value, typed value, computed, function, external class
-- **Built-in `$prototype` values** — `Request`, `LocalStorage`, `SessionStorage`, `Cookie`, `IndexedDB`, `Array`, `Set`, `Map`, `Blob`, `ReadableStream`, `URLSearchParams`, `FormData`
+- **`tagName`**: all standard HTML element names from `@webref/elements`
+- **Element properties**: all DOM IDL properties from `@webref/idl`
+- **`style`**: all CSSOM camelCase properties from `@webref/css`
+- **Event handlers**: all `EventHandler` names (`onclick`, `oninput`, …)
+- **`state` shapes**: naked value, typed value, computed, function, external class
+- **Built-in `$prototype` values**: `Request`, `LocalStorage`, `SessionStorage`, `Cookie`, `IndexedDB`, `Array`, `Set`, `Map`, `Blob`, `ReadableStream`, `URLSearchParams`, `FormData`
 
 ## VSCode / editor integration
 

package/class-schema.json

@@ -105,7 +105,7 @@
       "type": "object"
     },
     "ClassMethodDef": {
-      "description": "A class method or accessor definition. Capability roles (parse, serialize, discover, load) mark static methods that hosts (compiler, server, studio) invoke for format dispatch.",
+      "description": "A class method or accessor definition. Capability roles (parse, serialize, rewrite, discover, load) mark static methods that hosts (compiler, server, studio) invoke for format dispatch.",
       "properties": {
         "$prototype": {
           "const": "Function",
@@ -175,6 +175,7 @@
             "accessor",
             "parse",
             "serialize",
+            "rewrite",
             "discover",
             "load",
             "projectData",

package/defs/class-def.schema.ts

@@ -9,6 +9,7 @@ export const CLASS_METHOD_ROLES = [
   "accessor",
   "parse",
   "serialize",
+  "rewrite",
   "discover",
   "load",
   "projectData",
@@ -96,7 +97,7 @@ export const classConstructorDefSchema = {
 
 export const classMethodDefSchema = {
   description:
-    "A class method or accessor definition. Capability roles (parse, serialize, discover, load) " +
+    "A class method or accessor definition. Capability roles (parse, serialize, rewrite, discover, load) " +
     "mark static methods that hosts (compiler, server, studio) invoke for format dispatch.",
   properties: {
     $prototype: { const: "Function", type: "string" },

package/defs/function-def.schema.ts

@@ -9,6 +9,13 @@ export const functionDefSchema = {
       description: "Named export in $src module. Defaults to the state key name.",
       type: "string",
     },
+    $lazy: {
+      description:
+        "Load $src on first call instead of importing it up front. The function then returns a " +
+        "promise, so it may only be called from a handler or lifecycle hook — never bound as a " +
+        "computed value. Use it for code most visitors never reach.",
+      type: "boolean",
+    },
     $prototype: { const: "Function", type: "string" },
     $src: {
       description: "External module specifier. Mutually exclusive with body.",

package/package.json

@@ -1,8 +1,8 @@
 {
   "dependencies": {
-    "@webref/css": "^8.7.2",
-    "@webref/elements": "^2.7.1",
-    "@webref/idl": "^3.82.2",
+    "@webref/css": "^8.7.3",
+    "@webref/elements": "^2.8.0",
+    "@webref/idl": "^3.83.0",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1"
   },
@@ -52,10 +52,10 @@
     "schema": "bun run src/schema.ts",
     "test": "bun test --isolate",
     "test:coverage": "bun test --isolate --coverage",
-    "upgrade": "bunx npm-check-updates -u && bun install"
+    "upgrade": "bun update --latest && bun install"
   },
   "type": "module",
-  "version": "1.9.0",
+  "version": "2.1.0",
   "devDependencies": {
     "json-schema-to-ts": "^3.1.1"
   }

package/schema.json

@@ -211,6 +211,10 @@
           "description": "Named export in $src module. Defaults to the state key name.",
           "type": "string"
         },
+        "$lazy": {
+          "description": "Load $src on first call instead of importing it up front. The function then returns a promise, so it may only be called from a handler or lifecycle hook — never bound as a computed value. Use it for code most visitors never reach.",
+          "type": "boolean"
+        },
         "$prototype": {
           "const": "Function",
           "type": "string"
@@ -558,7 +562,7 @@
       "type": "object"
     },
     "ClassMethodDef": {
-      "description": "A class method or accessor definition. Capability roles (parse, serialize, discover, load) mark static methods that hosts (compiler, server, studio) invoke for format dispatch.",
+      "description": "A class method or accessor definition. Capability roles (parse, serialize, rewrite, discover, load) mark static methods that hosts (compiler, server, studio) invoke for format dispatch.",
       "properties": {
         "$prototype": {
           "const": "Function",
@@ -628,6 +632,7 @@
             "accessor",
             "parse",
             "serialize",
+            "rewrite",
             "discover",
             "load",
             "projectData",
@@ -2565,6 +2570,20 @@
             }
           ]
         },
+        "onconfigurationchange": {
+          "description": "Event handler for the \"configurationchange\" event.",
+          "oneOf": [
+            {
+              "$ref": "#/$defs/RefObject"
+            },
+            {
+              "$ref": "#/$defs/ExpressionEntry"
+            },
+            {
+              "$ref": "#/$defs/FunctionDef"
+            }
+          ]
+        },
         "onconnect": {
           "description": "Event handler for the \"connect\" event.",
           "oneOf": [
@@ -5421,6 +5440,20 @@
             }
           ]
         },
+        "onstream": {
+          "description": "Event handler for the \"stream\" event.",
+          "oneOf": [
+            {
+              "$ref": "#/$defs/RefObject"
+            },
+            {
+              "$ref": "#/$defs/ExpressionEntry"
+            },
+            {
+              "$ref": "#/$defs/FunctionDef"
+            }
+          ]
+        },
         "onsubmit": {
           "description": "Event handler for the \"submit\" event.",
           "oneOf": [
@@ -22776,6 +22809,7 @@
         "body",
         "br",
         "button",
+        "camera",
         "canvas",
         "caption",
         "circle",
@@ -22872,6 +22906,7 @@
         "meter",
         "mfrac",
         "mi",
+        "microphone",
         "mmultiscripts",
         "mn",
         "mo",
@@ -22960,6 +22995,7 @@
         "u",
         "ul",
         "use",
+        "usermedia",
         "var",
         "video",
         "view",

package/src/asset-paths.ts

@@ -538,3 +538,89 @@ export function formatSrcset(candidates: readonly SrcsetCandidate[]): string {
     .map(({ url, descriptor }) => (descriptor ? `${url} ${descriptor}` : url))
     .join(", ");
 }
+
+// ─── Deployment base path (RFC 3986 §5) ──────────────────────────────────────
+
+/**
+ * The path a site is deployed under, derived from `project.json`'s `url`.
+ *
+ * **There is no second key for this, on purpose.** Every URL the build emits is a URI reference,
+ * and `url` is the base URI it is resolved against (RFC 3986 §5). A site at
+ * `https://example.pages.dev/m/my-site/` has already said where it lives; a `build.base` beside it
+ * would be a second writer on one fact, free to disagree with the canonical links and the sitemap
+ * that are built from the same value.
+ *
+ * What went wrong was narrower than a missing option: the compiler resolved its references against
+ * the base's ORIGIN and discarded its path, which is what §5.2 does to an absolute-path reference
+ * (`/assets/x.js`) and is not what a deployment means by one. So the fix is to stop discarding it.
+ *
+ * Returns `""` for a site at an origin root, a missing `url`, or a `url` that will not parse — all
+ * three mean "prefix nothing", and a malformed URL must not take the build down when the only thing
+ * it can affect is a prefix. Never has a trailing slash, so `base + "/assets/x"` is well-formed.
+ *
+ * @param {string | undefined} url - `project.json`'s `url`
+ * @returns {string} `""` or a path with a leading slash and no trailing one
+ */
+export function siteBasePath(url: string | undefined | null): string {
+  if (typeof url !== "string" || url === "") {
+    return "";
+  }
+  let pathname: string;
+  try {
+    ({ pathname } = new URL(url));
+  } catch {
+    return "";
+  }
+  const trimmed = pathname.replace(/\/+$/, "");
+  if (trimmed === "" || trimmed === "/") {
+    return "";
+  }
+  return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+
+/**
+ * Re-root a site-absolute URL onto the deployment base.
+ *
+ * Only an absolute-path reference is affected — the one form whose meaning is "from the site root",
+ * and therefore the one form that moves when the site root does. A protocol-relative `//host/x`, an
+ * absolute URL, a fragment, a query and every relative path already resolve against something else
+ * and are returned untouched.
+ *
+ * **Idempotent**, because a URL may reach this more than once: an emitter that already prefixed and
+ * an output pass that prefixes everything must not compound. A value already under the base is
+ * returned as-is.
+ *
+ * @param {string} base - From {@link siteBasePath}
+ * @param {string} url - A URL as emitted
+ * @returns {string} The URL a browser should be given
+ */
+export function withBase(base: string, url: string): string {
+  if (base === "" || !url.startsWith("/") || url.startsWith("//")) {
+    return url;
+  }
+  if (url === base || url.startsWith(`${base}/`)) {
+    return url;
+  }
+  return base + url;
+}
+
+/**
+ * An absolute URL for a site route, keeping the base's path.
+ *
+ * `new URL("/about", "https://x.dev/m/site/")` is `https://x.dev/about` — RFC 3986 §5.2 replaces
+ * the whole path for an absolute-path reference, which is exactly right for the RFC and exactly
+ * wrong for a canonical link. Resolving the route as a RELATIVE-path reference keeps the base, so
+ * `<link rel="canonical">`, `sitemap.xml` and `robots.txt` name pages that exist.
+ *
+ * @param {string} route - A site route (`/about`), leading slash optional
+ * @param {string} siteUrl - `project.json`'s `url`
+ * @returns {string} The absolute URL
+ */
+export function siteAbsoluteUrl(route: string, siteUrl: string): string {
+  const base = new URL(siteUrl);
+  // A base whose path does not end in "/" would drop its last segment under §5.2's merge.
+  if (!base.pathname.endsWith("/")) {
+    base.pathname += "/";
+  }
+  return new URL(route.replace(/^\/+/, ""), base).href;
+}

package/src/format-registry.ts

@@ -12,11 +12,12 @@
 
 import { mediaTypeEssence, mediaTypeProblem } from "./media-type";
 
-export type FormatCapability = "parse" | "serialize" | "discover" | "load";
+export type FormatCapability = "parse" | "serialize" | "rewrite" | "discover" | "load";
 
 export const FORMAT_CAPABILITIES: readonly FormatCapability[] = [
   "parse",
   "serialize",
+  "rewrite",
   "discover",
   "load",
 ];
@@ -27,6 +28,13 @@ export const FORMAT_CAPABILITIES: readonly FormatCapability[] = [
  * asset emission (`emit`), `<head>` contribution (`head`), static asset mounts (`assets`),
  * server-mount (`mount`), and connector (`dialect`, `deploySchema`, `bindings`, `testConnection`)
  * roles.
+ *
+ * `rewrite` is the narrow sibling of `serialize`, and the two are not ranked: a format may declare
+ * either, both or neither. `serialize` says "this document round-trips through me"; `rewrite` says
+ * only "I can replace these authored values in my own source text and change nothing else". A
+ * load-only format — a CSV collection is read to load entries, never re-emitted as a document — can
+ * honestly promise the second and not the first, which is enough for a rename to repair a reference
+ * living inside it (specs/extensions.md §8).
  */
 export type ExtensionCapability =
   | FormatCapability

package/src/locale.ts

@@ -427,3 +427,27 @@ export function primaryLanguage(tag: unknown): string | null {
   const canonical = canonicalizeLocale(tag);
   return canonical === null ? null : (canonical.split("-")[0] ?? null);
 }
+
+/**
+ * The locale a URL belongs to.
+ *
+ * Matching is on the **first path segment**, compared canonically, so `/fr-CA/about/` resolves for
+ * a project that declared `fr-ca`. A path under no declared locale is the default locale — under
+ * `prefix-except-default` that is the point, and under `prefix-always` it is a page the author put
+ * outside the locale tree, which is theirs to place.
+ *
+ * @param {string} urlPattern - Site-absolute route pattern, e.g. `/fr/about/`
+ * @param {ResolvedI18n | null} i18n
+ * @returns {string | null} A canonical tag, or null when the project has no i18n
+ */
+export function localeOfRoute(urlPattern: string, i18n: ResolvedI18n | null): string | null {
+  if (i18n === null) {
+    return null;
+  }
+  const first = urlPattern.split("/").find(Boolean);
+  if (first === undefined) {
+    return i18n.defaultLocale;
+  }
+  const canonical = canonicalizeLocale(first);
+  return canonical !== null && i18n.locales.includes(canonical) ? canonical : i18n.defaultLocale;
+}

package/types.ts

@@ -171,6 +171,13 @@ export interface JxFunctionDef {
   $src?: string;
   /** Named export within `$src`; defaults to the state key. */
   $export?: string;
+  /**
+   * Load `$src` on first call rather than importing it with the module.
+   *
+   * The function returns a promise once lazy, so it may only be called — never bound as a computed
+   * value. Meant for code most visitors never reach.
+   */
+  $lazy?: boolean;
   /** Legacy alias for `parameters` (bare names only). */
   arguments?: string[];
   timing?: "compiler" | "server" | "client";
@@ -648,6 +655,13 @@ export interface ProjectConfig {
     deploy?: DeployConfig;
     sitemap?: boolean;
     headers?: HeadersConfig;
+    /**
+     * Minify emitted browser JavaScript. Defaults to true.
+     *
+     * Set false to ship readable bundles — debugging a deployed page, or diffing `dist/` where the
+     * two bundler backends agree on semantics but not on minified bytes.
+     */
+    minify?: boolean;
     [key: string]: unknown;
   };
   images?: ImageConfig;