@jxsuite/schema 4.1.0 → 5.1.0

package/defs/field-schema.schema.ts

@@ -62,10 +62,12 @@ export const relationshipRefSchema = {
  * 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.
+ * site-architecture.md §4.3): an explicit value list, a JSON data-file reference, a paged list, 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. The paged list is expanded by `expandDynamicRoutes` itself rather
+ * than `resolvePathEntries`, because it reads the page's own state; its `each` holds another source
+ * of this union (or an extension's), checked when the route expands.
  *
  * 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
@@ -103,6 +105,37 @@ export const documentPathsCoreMembers = [
     required: ["$ref"],
     type: "object",
   },
+  {
+    additionalProperties: false,
+    description:
+      "Paged list: one route per `pageSize` items of an entry of this page's own state, which must " +
+      "resolve to an array at build time. The page number fills the route's one parameter that " +
+      "`each` does not.",
+    properties: {
+      each: {
+        description:
+          "Another `$paths` source for the route's other parameter: the list is paged once per " +
+          "value of it, as a paged archive per tag is.",
+        type: ["object", "array"],
+      },
+      pageSize: { description: "Items on each page.", minimum: 1, type: "integer" },
+      paginate: {
+        additionalProperties: false,
+        description: "The state entry to page.",
+        properties: {
+          $ref: {
+            description: "A pointer to an entry of this page's state: `#/state/<key>`.",
+            pattern: "^#/state/[^/]+$",
+            type: "string",
+          },
+        },
+        required: ["$ref"],
+        type: "object",
+      },
+    },
+    required: ["paginate", "pageSize"],
+    type: "object",
+  },
   {
     description:
       "Legacy explicit form: an array of ready-made parameter objects, used as-is with no " +

package/package.json

@@ -20,6 +20,7 @@
     "./locale": "./src/locale.ts",
     "./intl": "./src/intl.ts",
     "./media-type": "./src/media-type.ts",
+    "./which": "./src/which.ts",
     "./overlays": "./src/overlays.ts",
     "./dialogs": "./src/dialogs.ts",
     "./a11y": "./src/a11y.ts",
@@ -60,7 +61,7 @@
     "upgrade": "bun update --latest && bun install"
   },
   "type": "module",
-  "version": "4.1.0",
+  "version": "5.1.0",
   "devDependencies": {
     "json-schema-to-ts": "^3.1.1"
   }

package/schema.json

@@ -28351,6 +28351,44 @@
           ],
           "type": "object"
         },
+        {
+          "additionalProperties": false,
+          "description": "Paged list: one route per `pageSize` items of an entry of this page's own state, which must resolve to an array at build time. The page number fills the route's one parameter that `each` does not.",
+          "properties": {
+            "each": {
+              "description": "Another `$paths` source for the route's other parameter: the list is paged once per value of it, as a paged archive per tag is.",
+              "type": [
+                "object",
+                "array"
+              ]
+            },
+            "pageSize": {
+              "description": "Items on each page.",
+              "minimum": 1,
+              "type": "integer"
+            },
+            "paginate": {
+              "additionalProperties": false,
+              "description": "The state entry to page.",
+              "properties": {
+                "$ref": {
+                  "description": "A pointer to an entry of this page's state: `#/state/<key>`.",
+                  "pattern": "^#/state/[^/]+$",
+                  "type": "string"
+                }
+              },
+              "required": [
+                "$ref"
+              ],
+              "type": "object"
+            }
+          },
+          "required": [
+            "paginate",
+            "pageSize"
+          ],
+          "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": {

package/schemas/document.paths.schema.json

@@ -38,6 +38,36 @@
       "required": ["$ref"],
       "type": "object"
     },
+    {
+      "additionalProperties": false,
+      "description": "Paged list: one route per `pageSize` items of an entry of this page's own state, which must resolve to an array at build time. The page number fills the route's one parameter that `each` does not.",
+      "properties": {
+        "each": {
+          "description": "Another `$paths` source for the route's other parameter: the list is paged once per value of it, as a paged archive per tag is.",
+          "type": ["object", "array"]
+        },
+        "pageSize": {
+          "description": "Items on each page.",
+          "minimum": 1,
+          "type": "integer"
+        },
+        "paginate": {
+          "additionalProperties": false,
+          "description": "The state entry to page.",
+          "properties": {
+            "$ref": {
+              "description": "A pointer to an entry of this page's state: `#/state/<key>`.",
+              "pattern": "^#/state/[^/]+$",
+              "type": "string"
+            }
+          },
+          "required": ["$ref"],
+          "type": "object"
+        }
+      },
+      "required": ["paginate", "pageSize"],
+      "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": {

package/src/component-meta.ts

@@ -8,8 +8,8 @@
  *
  * It lives here because THREE backends need the same answer and two of them had already written it
  * twice: `packages/server/src/studio-api.ts` (the dev server's `/__studio/components`) and
- * `packages/desktop/src/project-session.ts`. A third copy in the cloud adapter would have made
- * "which entries in `state` count as props" a question with three answers.
+ * `packages/desktop/src/backend/project-session.ts`. A third copy in the cloud adapter would have
+ * made "which entries in `state` count as props" a question with three answers.
  *
  * @license MIT
  */

package/src/validate-project.ts

@@ -111,9 +111,11 @@ export async function validateProjectFile(projectRoot: string): Promise<ProjectV
 }
 
 /**
- * Restricted schema loader: only `file:` URLs inside the project root are served. Missing files
- * under `<root>/node_modules/` fall back to host resolution of the corresponding bare specifier
- * (in-repo starters have no local node_modules; the fragments still ship with the host).
+ * Restricted schema loader: only `file:` URLs inside the project root are served. A missing file
+ * under `<root>/node_modules/` resolves its bare specifier through the project's own resolution
+ * (in-repo starters have no local node_modules and walk up to the workspace's). Only this package's
+ * own core schemas fall back to the host: an extension's fragments, first-party ones included, are
+ * the project's to supply (specs/extensions.md §5.4).
  *
  * @param {string} uri - The `$ref` target ajv could not resolve from already-loaded resources
  * @param {string} root - Absolute project root
@@ -137,8 +139,8 @@ async function loadProjectSchemaRef(uri: string, root: string): Promise<JsonValu
     return readJson(filePath);
   }
 
-  // Host fallback: <root>/node_modules/<specifier> is absent — resolve the specifier through the
-  // Project's own resolution first, then the host's (workspace symlinks resolve transparently).
+  // <root>/node_modules/<specifier> is absent — resolve the specifier through the project's own
+  // Resolution (workspace symlinks resolve transparently), and through the host only for the core.
   const posixRel = rel.split("\\").join("/");
   const marker = "node_modules/";
   const markerIndex = posixRel.lastIndexOf(marker);
@@ -147,32 +149,37 @@ async function loadProjectSchemaRef(uri: string, root: string): Promise<JsonValu
   }
   const specifier = posixRel.slice(markerIndex + marker.length);
 
+  const ownPrefix = "@jxsuite/schema/";
   let resolved: string;
   try {
     const projRequire = createRequire(resolve(root, "package.json"));
     resolved = projRequire.resolve(specifier);
-  } catch {
+  } catch (error) {
+    if (!specifier.startsWith(ownPrefix)) {
+      throw new Error(
+        `Schema ref "${uri}" does not exist and "${specifier}" is not resolvable from the ` +
+          `project — is the package installed?`,
+        { cause: error },
+      );
+    }
     try {
       const selfRequire = createRequire(import.meta.url);
       resolved = selfRequire.resolve(specifier);
-    } catch (error) {
+    } catch (hostError) {
       // Exports-map subpath resolution is brittle against version-skewed shadowing installs (a
       // Stale local copy terminates Node's walk-up with ERR_PACKAGE_PATH_NOT_EXPORTED). Our own
       // Schema files are pure data and the running validator's copy is guaranteed to match, so
       // Read them straight off this package's disk as the last resort.
-      const ownPrefix = "@jxsuite/schema/";
-      if (specifier.startsWith(ownPrefix)) {
-        const ownFile = fileURLToPath(
-          new URL(`../${specifier.slice(ownPrefix.length)}`, import.meta.url),
-        );
-        if (existsSync(ownFile)) {
-          return readJson(ownFile);
-        }
+      const ownFile = fileURLToPath(
+        new URL(`../${specifier.slice(ownPrefix.length)}`, import.meta.url),
+      );
+      if (existsSync(ownFile)) {
+        return readJson(ownFile);
       }
       throw new Error(
         `Schema ref "${uri}" does not exist and "${specifier}" is not resolvable from the ` +
-          `project or the host`,
-        { cause: error },
+          `project or this host's core`,
+        { cause: hostError },
       );
     }
   }

package/src/which.ts

@@ -0,0 +1,75 @@
+/**
+ * Find an executable the way `Bun.which` does, on `node:fs` alone.
+ *
+ * The desktop backend runs on Electron's Node (specs/desktop.md §7.1), so the code it reaches
+ * cannot call `Bun.which`. The answer is held to Bun's by `tests/which.test.ts`: a name containing
+ * a path separator is resolved against the working directory and returned when it is an executable
+ * regular file; any other name is looked up in each non-empty `PATH` entry in order. On Windows,
+ * where every file passes an `X_OK` check, only a launchable name counts: one that already ends in
+ * `.exe`, `.cmd`, `.bat` or `.com` is tried as written, and any other gets each of those appended
+ * in that order. Like Bun, it ignores `PATHEXT`, whose `.js` and `.vbs` entries name files a
+ * process cannot spawn. The path returned is the one that was tried, so an appended extension is
+ * lower case whatever the file's own case, and never its realpath.
+ *
+ * Node-only: it reads the filesystem, unlike the rest of this package's browser-safe modules.
+ */
+import { accessSync, constants, statSync } from "node:fs";
+import { delimiter, join, resolve } from "node:path";
+
+/** True when `path` is a regular file this process may execute. */
+function isExecutable(path: string): boolean {
+  try {
+    if (!statSync(path).isFile()) {
+      return false;
+    }
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The extensions Bun's `which` tries on Windows, in its order. */
+const WINDOWS_EXTENSIONS = [".exe", ".cmd", ".bat", ".com"];
+
+/**
+ * The names to try for `name`: itself elsewhere; on Windows, only names with a launchable
+ * extension.
+ */
+function candidates(name: string, platform: NodeJS.Platform): string[] {
+  if (platform !== "win32") {
+    return [name];
+  }
+  const lower = name.toLowerCase();
+  if (WINDOWS_EXTENSIONS.some((extension) => lower.endsWith(extension))) {
+    return [name];
+  }
+  return WINDOWS_EXTENSIONS.map((extension) => `${name}${extension}`);
+}
+
+/**
+ * The absolute path of the executable `name`, or null when there is none.
+ *
+ * @param name A command name, or a path (absolute, or relative to the working directory)
+ * @param options `PATH` overrides the environment's search path
+ */
+export function which(
+  name: string,
+  options: { PATH?: string; platform?: NodeJS.Platform } = {},
+): string | null {
+  if (name === "") {
+    return null;
+  }
+  const platform = options.platform ?? process.platform;
+  if (name.includes("/") || (platform === "win32" && name.includes("\\"))) {
+    return candidates(resolve(name), platform).find((path) => isExecutable(path)) ?? null;
+  }
+  const dirs = (options.PATH ?? process.env.PATH ?? "").split(delimiter).filter(Boolean);
+  for (const dir of dirs) {
+    const found = candidates(join(dir, name), platform).find((path) => isExecutable(path));
+    if (found) {
+      return found;
+    }
+  }
+  return null;
+}

package/types.ts

@@ -793,14 +793,16 @@ export interface ProjectConfig {
 export type JxAttributeValue = Bindable<string | number | boolean>;
 
 /**
- * A dynamic-route path source (spec §4.3): explicit values, data-file ref, a legacy array of param
- * objects, or an extension-discriminated source (an object carrying a `resolvePaths` discriminator
- * key registered by an enabled extension, e.g. the parser's `contentType` — the extension owns the
- * narrow shape).
+ * A dynamic-route path source (spec §4.3): explicit values, data-file ref, a paged list of an entry
+ * of the page's own state (with `each` naming the source of a second parameter), a legacy array of
+ * param objects, or an extension-discriminated source (an object carrying a `resolvePaths`
+ * discriminator key registered by an enabled extension, e.g. the parser's `contentType` — the
+ * extension owns the narrow shape).
  */
 export type JxPathsDef =
   | { values: JsonValue[]; param?: string }
   | { $ref: string; param?: string; field?: string }
+  | { paginate: { $ref: string }; pageSize: number; each?: JsonValue }
   | { param?: string; field?: string; [discriminator: string]: JsonValue | undefined }
   | Record<string, JsonValue>[];