@jxsuite/studio 4.1.0 → 5.0.0

package/index.html

@@ -7,6 +7,7 @@
     <link rel="icon" href="./favicon.ico" />
     <link rel="stylesheet" href="./dist/studio.css" />
     <link rel="stylesheet" href="./styles/tokens.css" />
+    <link rel="stylesheet" href="./styles/shell-frame.css" />
     <link rel="stylesheet" href="./styles/shell.css" />
     <link rel="stylesheet" href="./styles/canvas.css" />
     <link rel="stylesheet" href="./styles/panels.css" />

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/studio",
-  "version": "4.1.0",
+  "version": "5.0.0",
   "description": "Jx Studio — visual builder for Jx documents",
   "license": "MIT",
   "repository": {
@@ -51,73 +51,39 @@
     "eval": "bun run evals/cli.ts",
     "eval:headless": "bun run tests/harness/run-eval.ts",
     "lint:styles": "bun run scripts/check-styles.ts",
-    "test": "bun run lint:styles && bun test --isolate",
+    "styles:check": "bun run scripts/build-styles.ts",
+    "styles:sync": "bun run scripts/build-styles.ts --fix",
+    "test": "bun run lint:styles && bun run styles:check && bun test --isolate",
     "test:coverage": "bun test --isolate --coverage",
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
     "@atlaskit/pragmatic-drag-and-drop": "^3.1.0",
     "@atlaskit/pragmatic-drag-and-drop-hitbox": "^2.2.0",
-    "@jxsuite/ai": "^0.37.0",
-    "@jxsuite/collab": "^0.8.5",
-    "@jxsuite/create": "^1.3.9",
-    "@jxsuite/formulas": "^0.0.16",
-    "@jxsuite/markup": "^0.4.9",
-    "@jxsuite/protocol": "^2.2.0",
-    "@jxsuite/runtime": "^3.1.0",
-    "@jxsuite/schema": "^2.1.0",
-    "@jxsuite/site": "^1.1.0",
-    "@spectrum-web-components/accordion": "^1.12.2",
-    "@spectrum-web-components/action-bar": "1.12.2",
-    "@spectrum-web-components/action-button": "^1.12.2",
-    "@spectrum-web-components/action-group": "^1.12.2",
-    "@spectrum-web-components/base": "^1.12.2",
-    "@spectrum-web-components/button": "^1.12.2",
-    "@spectrum-web-components/checkbox": "^1.12.2",
-    "@spectrum-web-components/color-area": "^1.12.2",
-    "@spectrum-web-components/color-handle": "^1.12.2",
-    "@spectrum-web-components/color-slider": "^1.12.2",
-    "@spectrum-web-components/combobox": "^1.12.2",
-    "@spectrum-web-components/dialog": "^1.12.2",
-    "@spectrum-web-components/divider": "^1.12.2",
-    "@spectrum-web-components/field-label": "^1.12.2",
-    "@spectrum-web-components/help-text": "^1.12.2",
-    "@spectrum-web-components/icon": "^1.12.2",
-    "@spectrum-web-components/icons-ui": "^1.12.2",
-    "@spectrum-web-components/icons-workflow": "^1.12.2",
-    "@spectrum-web-components/menu": "^1.12.2",
-    "@spectrum-web-components/number-field": "^1.12.2",
-    "@spectrum-web-components/overlay": "^1.12.2",
-    "@spectrum-web-components/overlay-trigger": "^0.1.7",
-    "@spectrum-web-components/picker": "^1.12.2",
-    "@spectrum-web-components/picker-button": "^1.12.2",
-    "@spectrum-web-components/popover": "^1.12.2",
-    "@spectrum-web-components/progress-circle": "^1.12.2",
-    "@spectrum-web-components/search": "^1.12.2",
-    "@spectrum-web-components/swatch": "^1.12.2",
-    "@spectrum-web-components/switch": "^1.12.2",
-    "@spectrum-web-components/table": "^1.12.2",
-    "@spectrum-web-components/tabs": "^1.12.2",
-    "@spectrum-web-components/textfield": "^1.12.2",
-    "@spectrum-web-components/theme": "^1.12.2",
-    "@spectrum-web-components/toast": "^1.12.2",
-    "@spectrum-web-components/tooltip": "^1.12.2",
-    "@spectrum-web-components/underlay": "^1.12.2",
+    "@jxsuite/ai": "^0.37.1",
+    "@jxsuite/collab": "^0.9.0",
+    "@jxsuite/create": "^1.3.10",
+    "@jxsuite/formulas": "^0.0.17",
+    "@jxsuite/markup": "^0.4.10",
+    "@jxsuite/protocol": "^2.3.0",
+    "@jxsuite/runtime": "^4.0.0",
+    "@jxsuite/schema": "^2.2.0",
+    "@jxsuite/site": "^2.0.0",
+    "@jxsuite/ui": "^0.1.0",
     "@vue/reactivity": "3.5.42",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
-    "lit": "^3.3.3",
     "lit-html": "^3.3.3",
     "monaco-editor": "^0.56.0",
     "tabulator-tables": "^6.5.2",
-    "yaml": "^2.9.0"
+    "yaml": "^2.9.1"
   },
   "devDependencies": {
-    "@happy-dom/global-registrator": "^20.12.0",
+    "@happy-dom/global-registrator": "^20.14.5",
     "@types/mdast": "^4.0.4",
-    "@webref/css": "^8.7.3",
+    "@webref/css": "^8.7.4",
     "@webref/elements": "^2.8.0",
-    "@webref/idl": "^3.83.0"
+    "@webref/idl": "^3.83.1"
   },
   "//vue-reactivity": "Exact pin required — must match @jxsuite/runtime to avoid cross-boundary proxy bugs"
 }

package/src/about/about-modal.ts

@@ -1,161 +1,110 @@
 /// <reference lib="dom" />
 /**
- * About modal — shows app version, build metadata, external links, the resolved `@jxsuite/*`
- * package versions, and (on desktop) the release channel / update status.
+ * About — the app's version, build metadata, external links, the resolved `@jxsuite/*` package
+ * versions, and (on desktop) the release channel and update status.
  *
- * Build metadata comes from src/version.ts (injected at bundle time). Package versions are fetched
- * lazily via the platform; desktop update info is shown only when the active platform implements
- * the optional `getAppInfo` method.
+ * The dialog itself is `src/surfaces/about.json`, a `jx-dialog`; this module is the flow around it.
+ * It used to be a lit template with module-level `_packages` and `_appInfo` and a `renderModal()`
+ * that redrew the whole thing whenever either landed — the surface is reactive now, so a list that
+ * arrives late appears without anything else being touched.
+ *
+ * Build metadata comes from `src/version.ts`, injected at bundle time. Both platform reads are
+ * OPTIONAL: `listPackages` failing still leaves the app able to state its own version, and
+ * `getAppInfo` is implemented only by the desktop, so its absence is a missing row rather than an
+ * error to report.
+ *
+ * @docs studio/interface
  */
 
-import { html } from "lit-html";
-import type { TemplateResult } from "lit-html";
-import { openModal } from "../ui/layers";
+import { openAboutSurface } from "../surfaces/about";
+import { layerHost } from "../ui/layers";
 import { getPlatform } from "../platform";
 import { APP_NAME, BUILD_DATE, GIT_COMMIT, LINKS, VERSION } from "../version";
-import type { AppInfo, PackageInfo } from "../types";
+import type { AboutRow, AboutSurfaceHandle } from "../surfaces/about";
+import type { AppInfo } from "../types";
 import type { Command, CommandRegistry } from "../commands/registry";
 
-let _handle: ReturnType<typeof openModal> | null = null;
-
-let _packages: PackageInfo[] | null = null;
-let _appInfo: AppInfo | null = null;
+let _handle: AboutSurfaceHandle | null = null;
 
-export function openAboutModal() {
-  if (_handle) {
-    return;
+/** `—` rather than an empty cell: a row with nothing in it reads as a missing row. */
+function formatBuildDate(iso: string): string {
+  if (!iso) {
+    return "—";
   }
-  _packages = null;
-  _appInfo = null;
-  renderModal();
-  void loadDetails();
+  const date = new Date(iso);
+  return Number.isNaN(date.getTime()) ? iso : date.toLocaleString();
 }
 
-export function closeAboutModal() {
-  if (!_handle) {
-    return;
+/** The metadata rows, with the desktop's two appended when the platform reported them. */
+function metaRows(info: AppInfo | null): AboutRow[] {
+  const rows: AboutRow[] = [
+    { label: "Version", value: VERSION },
+    { label: "Build date", value: formatBuildDate(BUILD_DATE) },
+    { label: "Commit", value: GIT_COMMIT },
+  ];
+  if (info) {
+    rows.push({ label: "Channel", value: info.channel });
+    if (info.updateStatus) {
+      rows.push({ label: "Updates", value: info.updateStatus });
+    }
   }
-  _handle.close();
-  _handle = null;
-  _packages = null;
-  _appInfo = null;
+  return rows;
 }
 
-async function loadDetails() {
+/** Ask the platform for what it can tell us, and patch whatever comes back. */
+async function loadDetails(handle: AboutSurfaceHandle): Promise<void> {
   const platform = getPlatform();
+  let packages: { name: string; version: string }[] = [];
   try {
-    _packages = await platform.listPackages();
+    packages = await platform.listPackages();
   } catch {
-    _packages = [];
+    packages = [];
   }
+  let info: AppInfo | null = null;
   if (platform.getAppInfo) {
     try {
-      _appInfo = await platform.getAppInfo();
+      info = await platform.getAppInfo();
     } catch {
-      _appInfo = null;
+      info = null;
     }
   }
-  if (_handle) {
-    renderModal();
+  if (_handle === handle) {
+    handle.update({ packages, rows: metaRows(info) });
   }
 }
 
-function formatBuildDate(iso: string) {
-  if (!iso) {
-    return "—";
-  }
-  const date = new Date(iso);
-  return Number.isNaN(date.getTime()) ? iso : date.toLocaleString();
-}
-
-function metaRows() {
-  const rows: [string, string][] = [
-    ["Version", VERSION],
-    ["Build date", formatBuildDate(BUILD_DATE)],
-    ["Commit", GIT_COMMIT],
-  ];
-  if (_appInfo) {
-    rows.push(["Channel", _appInfo.channel]);
-    if (_appInfo.updateStatus) {
-      rows.push(["Updates", _appInfo.updateStatus]);
-    }
-  }
-  return rows;
-}
-
-function renderPackages(): TemplateResult {
-  if (_packages === null) {
-    return html`<p class="about-muted">Loading packages…</p>`;
-  }
-  if (_packages.length === 0) {
-    return html`<p class="about-muted">No packages reported.</p>`;
-  }
-  return html`
-    <ul class="about-packages">
-      ${_packages.map(
-        (p) => html`
-          <li class="about-package-row">
-            <span class="about-package-name">${p.name}</span>
-            <span class="about-package-version">${p.version}</span>
-          </li>
-        `,
-      )}
-    </ul>
-  `;
-}
-
-function renderModal() {
-  const tpl = html`
-    <sp-underlay open @close=${closeAboutModal}></sp-underlay>
-    <div class="about-modal">
-      <div class="settings-modal-header">
-        <h2 class="settings-modal-title">About ${APP_NAME}</h2>
-        <sp-action-button quiet size="s" @click=${closeAboutModal} title="Close">
-          <sp-icon-close slot="icon"></sp-icon-close>
-        </sp-action-button>
-      </div>
-      <div class="about-modal-body">
-        <dl class="about-meta">
-          ${metaRows().map(
-            ([label, value]) => html`
-              <div class="about-meta-row">
-                <dt class="about-meta-label">${label}</dt>
-                <dd class="about-meta-value">${value}</dd>
-              </div>
-            `,
-          )}
-        </dl>
-
-        <div class="about-links">
-          <a href=${LINKS.github} target="_blank" rel="noreferrer noopener">GitHub</a>
-          <a href=${LINKS.docs} target="_blank" rel="noreferrer noopener">Documentation</a>
-          <a href=${LINKS.license} target="_blank" rel="noreferrer noopener">License</a>
-        </div>
-
-        <section class="about-section">
-          <h3 class="about-section-title">Packages</h3>
-          ${renderPackages()}
-        </section>
-      </div>
-    </div>
-  `;
-
+export function openAboutModal(): void {
   if (_handle) {
-    _handle.update(tpl);
-  } else {
-    _handle = openModal(tpl, { label: `About ${APP_NAME}`, onDismiss: closeAboutModal });
+    return;
   }
+  const handle = openAboutSurface({
+    headline: `About ${APP_NAME}`,
+    layer: layerHost("dialog"),
+    links: [
+      { href: LINKS.github, label: "GitHub" },
+      { href: LINKS.docs, label: "Documentation" },
+      { href: LINKS.license, label: "License" },
+    ],
+    onClosed: () => {
+      if (_handle === handle) {
+        _handle = null;
+      }
+    },
+    rows: metaRows(null),
+  });
+  _handle = handle;
+  void loadDetails(handle);
 }
 
 /**
- * `Help: About` — the record the rail footer's hand-authored button used to be.
+ * There is no `closeAboutModal`, and its absence is the conversion rather than an omission.
  *
- * The rail foot carries **Preferences** and nothing else (plan §3.2 ②). About is not a view you
- * switch to and it is opened roughly once in an app's lifetime, so it costs a rail slot it cannot
- * repay; instead it sits at the bottom of the ⬢ Studio menu (`commandbar/overflow`, `group:
- * "9_help"` sorts after every other group there) and stays reachable by name from the palette
- * besides.
+ * The dialog dismisses ITSELF now — Escape and the Close button are the platform's and the kit's,
+ * and both arrive as events the document hands back to this module. An exported closer had no
+ * caller left in the running app, which `tests/reachability.test.ts` said out loud: built, tested,
+ * and reachable from nothing.
  */
+
 export function aboutCommands(): Command[] {
   return [
     {

package/src/browse/library-commands.ts

@@ -15,6 +15,7 @@
 
 import {
   argsSchema,
+  derivedEnumProperty,
   enumArg,
   enumProperty,
   optionalStringArg,
@@ -58,12 +59,9 @@ export function libraryCommands(): AnyCommand[] {
       group: "1_file",
       requires: "an open project",
       when: (ctx) => ctx.project.open,
-      aiTool: {
-        description:
-          "Open the Library — every page, layout, component, content entry and media file in " +
-          "the project, as a browsable tab.",
-        name: "open_library",
-      },
+      /* No `aiTool`, by §12.4's first deletion rule: chrome. None of the Library family is
+         projected — every one of these verbs shapes a listing a person reads, and the model has
+         `list_files` / `search_files` for the same facts. */
       run: () => {
         openLibraryTab();
       },
@@ -83,10 +81,7 @@ export function libraryCommands(): AnyCommand[] {
       group: "1_file",
       requires: "an open project",
       when: (ctx) => ctx.project.open,
-      aiTool: {
-        description: "Filter the Library to one category of project file.",
-        name: "set_library_category",
-      },
+      /* No `aiTool`: a listing filter for a person (§12.4, rule 1). */
       run: (_ctx, args) => {
         const key = enumArg("library.setCategory", args, "category", LIBRARY_CATEGORY_KEYS);
         setLibraryCategory(key);
@@ -109,10 +104,7 @@ export function libraryCommands(): AnyCommand[] {
       group: "1_file",
       requires: "an open project",
       when: (ctx) => ctx.project.open,
-      aiTool: {
-        description: "Choose the Library's layout: table, cards, media, calendar or board.",
-        name: "set_library_layout",
-      },
+      /* No `aiTool`: a listing filter for a person (§12.4, rule 1). */
       run: (_ctx, args) => {
         const layout = enumArg<LibraryLayout>("library.setLayout", args, "layout", LIBRARY_LAYOUTS);
         setLibraryLayout(layout);
@@ -134,10 +126,7 @@ export function libraryCommands(): AnyCommand[] {
       group: "1_file",
       requires: "an open project",
       when: (ctx) => ctx.project.open,
-      aiTool: {
-        description: "Filter the Library's items by a text query over name and path.",
-        name: "set_library_search",
-      },
+      /* No `aiTool`: a listing filter for a person; the model has `search_files` (§12.4, rule 1). */
       run: (_ctx, args) => {
         setLibrarySearch(optionalStringArg("library.setSearch", args, "query") ?? "");
       },
@@ -145,21 +134,16 @@ export function libraryCommands(): AnyCommand[] {
     },
     {
       args: argsSchema({
-        locale: {
-          /*
-           * A getter, for the reason `content/entry-commands.ts` gives at length: this record is
-           * built at module scope, before any project is open, so `enum: localeChoices()` would
-           * freeze at `["all"]` and the palette would offer that forever. The getter is read when
-           * the prompt opens and when the AI tool list is serialised.
-           */
-          get enum() {
-            return localeChoices();
-          },
-          description:
-            'Which language the Library lists, as a BCP 47 tag the project declares. "all" ' +
+        /* Derived, for the reason `content/entry-commands.ts` gives at length: this record is
+           built at module scope, before any project is open, so `enumProperty(localeChoices(), …)`
+           would freeze at `["all"]` and the palette would offer that forever. The getter is read
+           when the prompt opens, when the AI tool list is serialised, and when `registry.run`
+           coerces the value. */
+        locale: derivedEnumProperty(
+          localeChoices,
+          'Which language the Library lists, as a BCP 47 tag the project declares. "all" ' +
             "clears the language filter.",
-          type: "string",
-        },
+        ),
       }),
       category: "Project",
       id: "library.setLocale",
@@ -170,13 +154,7 @@ export function libraryCommands(): AnyCommand[] {
       // A monolingual project has no facet to set: the Library draws no picker, and offering the
       // Verb would name a value space with one member in it.
       when: (ctx) => ctx.project.open && ctx.project.isMultilingual,
-      aiTool: {
-        description:
-          "Filter the Library to the files under one language's directory. Files outside a " +
-          "locale directory — which under prefix-except-default includes the default language's " +
-          "own pages — are not in any language's list.",
-        name: "set_library_locale",
-      },
+      /* No `aiTool`: a listing filter for a person (§12.4, rule 1). */
       run: (_ctx, args) => {
         const choice = enumArg("library.setLocale", args, "locale", localeChoices());
         setLibraryLocale(choice === "all" ? "" : choice);
@@ -191,10 +169,7 @@ export function libraryCommands(): AnyCommand[] {
       group: "1_file",
       requires: "an open project",
       when: (ctx) => ctx.project.open,
-      aiTool: {
-        description: "Re-scan the project's files and rebuild the Library's listing.",
-        name: "refresh_library",
-      },
+      /* No `aiTool`: chrome (§12.4, rule 1). */
       run: () => refreshLibrary(),
       title: "Library: Rescan Files",
     },
@@ -218,12 +193,8 @@ export function libraryCommands(): AnyCommand[] {
       requires: "an open project",
       when: (ctx) => ctx.project.open,
       undo: "project",
-      aiTool: {
-        description:
-          "Create a page, layout, component or content entry in the directory its kind belongs " +
-          "to, then open it.",
-        name: "new_library_entry",
-      },
+      /* No `aiTool`, by §12.4's second deletion rule: it waits on the New File prompt;
+         `create_page` / `create_component` cover the job. */
       run: async (_ctx, args) => {
         const declared = libraryNewEntries().map((entry) => entry.key);
         const key = enumArg("library.newEntry", args, "type", declared);