@jxsuite/studio 4.0.0 → 5.0.0

package/src/grid/redirects-grid.ts

@@ -24,11 +24,10 @@
  * @docs studio/projects/settings
  */
 
-import { html } from "lit-html";
 import { getPlatform } from "../platform";
 import { projectState } from "../store";
-import { clearProblems, notify } from "../services/notify";
-import { showDialog } from "../ui/layers";
+import { clearProblems, notify, problemFindings } from "../services/notify";
+import { showPromptDialog } from "../ui/layers";
 import { activateTab, openTab, workspace } from "../workspace/workspace";
 import { PROJECT_CONFIG_PATH, commitProjectConfig } from "../tabs/project-config";
 import { pageRoute } from "../panels/tab-strip";
@@ -400,37 +399,26 @@ export async function openRedirectsGrid(): Promise<GridController> {
 
 // ─── Import ───────────────────────────────────────────────────────────────────
 
-/** The paste box. One textarea, because both formats are things an author copies out of a file. */
+/**
+ * The paste box.
+ *
+ * It is `showPromptDialog` with a multiline field, not a dialog of its own. An import is one value
+ * the author pastes and one answer they give, which is what that flow already is (§12.5); what it
+ * needed was a field tall enough to read the value back in, and a monospaced one, because both
+ * formats are column-aligned in the file they were copied out of.
+ */
 export function promptRedirectImport(): Promise<string | null> {
-  let text = "";
-  return showDialog<string | null>(
-    (done) => html`
-      <sp-dialog-wrapper
-        open
-        dismissable
-        underlay
-        headline="Import Redirects"
-        confirm-label="Import"
-        cancel-label="Cancel"
-        @confirm=${() => done(text)}
-        @cancel=${() => done(null)}
-        @close=${() => done(null)}
-      >
-        <p>
-          Paste a Netlify/Cloudflare <code>_redirects</code> file, or CSV with
-          <code>source,destination,status</code> columns. Rows are staged for review — nothing is
-          written until you save.
-        </p>
-        <textarea
-          class="jx-grid-input jx-redirect-import"
-          rows="10"
-          placeholder="/old-page  /new-page  301"
-          @input=${(e: Event) => (text = (e.target as HTMLTextAreaElement).value)}
-        ></textarea>
-      </sp-dialog-wrapper>
-    `,
-    { region: "redirects/import" },
-  );
+  return showPromptDialog("Import Redirects", {
+    confirmLabel: "Import",
+    message:
+      "Paste a Netlify/Cloudflare _redirects file, or CSV with source,destination,status columns. " +
+      "Rows are staged for review — nothing is written until you save.",
+    mono: true,
+    multiline: true,
+    placeholder: "/old-page  /new-page  301",
+    rows: "10",
+    size: "md",
+  });
 }
 
 /**
@@ -515,11 +503,8 @@ export function redirectsCommands(): AnyCommand[] {
       group: "5_data",
       requires: "an open project",
       when: (ctx) => ctx.project.open,
-      aiTool: {
-        description:
-          "Open the site's redirect rules as an editable table, validated for chains, loops and rules shadowed by a real page.",
-        name: "open_redirects",
-      },
+      /* No `aiTool`, by §12.4's first deletion rule: this opens a surface for a person, and the
+         check it runs on the way is `validate_redirects`, which is projected. */
       run: async () => {
         await openRedirectsGrid();
         reportRedirectProblems(rulesFromConfig(currentConfig()), await projectRoutes());
@@ -536,8 +521,22 @@ export function redirectsCommands(): AnyCommand[] {
       when: (ctx) => ctx.project.open,
       aiTool: {
         description:
-          "Check the site's redirect rules for chains, loops and rules shadowed by a real page. Reports each finding as a Problem.",
+          "Check the site's redirect rules for chains, loops and rules shadowed by a real page. " +
+          "Reports each finding as a Problem, and returns the findings as data.",
         name: "validate_redirects",
+        /* The only way to check redirects without reading the routes yourself: the Problems store
+           filtered by this source, which is what the panel renders. */
+        report: () => {
+          const findings = problemFindings(REDIRECTS_PROBLEM_SOURCE);
+          const n = findings.length;
+          return {
+            data: findings,
+            summary:
+              n === 0
+                ? "No redirect problems: no chains, loops or shadowed rules."
+                : `Filed ${n} redirect problem${n === 1 ? "" : "s"} in Problems.`,
+          };
+        },
       },
       run: async () => {
         const rules = rulesFromConfig(currentConfig());
@@ -569,11 +568,8 @@ export function redirectsCommands(): AnyCommand[] {
       group: "5_data",
       requires: "an open project",
       when: (ctx) => ctx.project.open,
-      aiTool: {
-        description:
-          "Import redirect rules from _redirects or CSV text. Rows are staged in the redirect table for review, not written.",
-        name: "import_redirects",
-      },
+      /* No `aiTool`, by §12.4's second deletion rule: without `text`, `run` awaits a paste dialog
+         the person answers, and the staged rows are a surface for that person to review. */
       run: async (_ctx, args) => {
         const given = optionalStringArg("redirects.import", args, "text");
         const text = given ?? (await promptRedirectImport());

package/src/hosting/document.ts

@@ -15,6 +15,7 @@ import {
   assetUrl,
   STUDIO_BUNDLE_CSS,
   STUDIO_ENTRY,
+  STUDIO_FAVICON,
   STUDIO_IFRAME_ENTRY,
   STUDIO_STYLESHEETS,
 } from "./layout";
@@ -71,6 +72,7 @@ export function studioShellHtml(options: DocumentOptions = {}): string {
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>${options.title ?? "Jx Studio"}</title>
+    <link rel="icon" href="${url(STUDIO_FAVICON)}" />
 ${links}
   </head>
   <body>

package/src/hosting/layout.ts

@@ -66,6 +66,13 @@ export const STUDIO_ASSETS: readonly StudioAsset[] = [
     required: true,
     why: "the canvas iframe document. Without it every canvas frame 404s at boot.",
   },
+  {
+    dir: false,
+    kind: "asset",
+    path: "favicon.ico",
+    required: true,
+    why: "the shell document's <link rel=\"icon\">. A Chromium --app window (the NixOS desktop install) has no native title-bar icon of its own and falls back to the page's favicon, so without this the window chrome shows a generic icon even though the taskbar/dock entry is already branded via the .desktop file.",
+  },
   {
     dir: false,
     kind: "entry",
@@ -143,6 +150,7 @@ export const PUBLISHED_EXTRAS: readonly string[] = ["src", "data"];
 
 export const STUDIO_SHELL = "index.html";
 export const STUDIO_CANVAS = "canvas.html";
+export const STUDIO_FAVICON = "favicon.ico";
 export const STUDIO_ENTRY = "dist/studio.js";
 export const STUDIO_IFRAME_ENTRY = "dist/iframe-entry.js";
 export const STUDIO_BUNDLE_CSS = "dist/studio.css";
@@ -165,6 +173,8 @@ export const STUDIO_WORKERS: readonly string[] = [
  */
 export const STUDIO_STYLESHEETS: readonly string[] = [
   "styles/tokens.css",
+  /* The frame before the surfaces that fill it: generated from styles/shell-frame.json. */
+  "styles/shell-frame.css",
   "styles/shell.css",
   "styles/canvas.css",
   "styles/panels.css",

package/src/i18n/i18n-commands.ts

@@ -21,21 +21,30 @@
  * first language of a project unreachable by every door except a text editor, which is the state
  * this family exists to end.
  *
- * The locale enums are GETTERS. A command record is built at module scope — `commands/
- * app-commands.ts` builds the whole set before a project is open — so `enumProperty(locales(), …)`
- * would freeze the list at `[]` for the lifetime of the window, a defect this repo has already
- * shipped once (`content/entry-commands.ts` carries the post-mortem).
+ * The locale enums are GETTERS — `command-args.ts`'s `derivedEnumProperty`, the one definition of
+ * that shape. A command record is built at module scope — `commands/app-commands.ts` builds the
+ * whole set before a project is open — so `enumProperty(locales(), …)` would freeze the list at
+ * `[]` for the lifetime of the window, a defect this repo has already shipped once
+ * (`content/entry-commands.ts` carries the post-mortem). This file used to carry a private copy of
+ * the getter; `coerceArgs` reads the getter to resolve a derived list at run time, so a second
+ * spelling of it is exactly the kind of drift the coercion exists to end.
  */
 
 import { getPlatform } from "../platform";
 import { getEffectiveLocales } from "../site-context";
-import { localeLabel, translationPathFor } from "@jxsuite/schema/locale";
+import { canonicalizeLocale, localeLabel, translationPathFor } from "@jxsuite/schema/locale";
 import { notify } from "../services/notify";
 import { setActivityTab } from "../shell";
 import { tabOfPane } from "../canvas/canvas-surface";
 import { activeTab } from "../workspace/workspace";
 import { addProjectLocale } from "../settings/locales-section";
-import { argsSchema, optionalStringArg, stringArg, stringProperty } from "../commands/command-args";
+import {
+  argsSchema,
+  derivedEnumProperty,
+  optionalStringArg,
+  stringArg,
+  stringProperty,
+} from "../commands/command-args";
 import type { CommandArgValues } from "../commands/command-args";
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
 import type { Tab } from "../tabs/tab";
@@ -46,35 +55,49 @@ function declaredLocales(): string[] {
 }
 
 /**
- * An enum property whose values are derived WHEN THE SCHEMA IS READ, not when the record is built.
+ * Whether the last `i18n.addLocale` wrote `project.json`, for the report.
  *
- * The getter is the whole difference from `command-args.ts`'s `enumProperty`, and it is invisible
- * in a unit test that builds the record with a project already open — see this module's header.
+ * A latch beside `run` rather than a fact on the context, because the context carries
+ * `isMultilingual` and not the list: going from one language to two flips it, going from two to
+ * three does not. The value is `addProjectLocale`'s own answer, not a second reading of "is it
+ * declared" made here: that reading compared against the RESOLVED locales, which carry a
+ * `defaultLocale` the raw array may not, so with `{ defaultLocale: "en", locales: ["fr"] }` the
+ * write declared `en` and the report said it was already there. One predicate, in the function that
+ * writes.
  */
-function derivedEnumProperty(declared: () => readonly string[], description: string): object {
-  return {
-    description,
-    get enum() {
-      return [...declared()];
-    },
-    type: "string",
-  };
-}
+let _lastAddLocaleWrote = false;
 
 /**
- * The document a translation verb acts on: the named pane's, or the focused one's.
+ * The document a translation verb acts on, as a project-relative path: the file `path` names, the
+ * named pane's, or the focused one's.
+ *
+ * `path` is how the Languages panel addresses a row — a grid of files against locales has no pane
+ * for each square, and the row's own file is the one its cells are about (`panels/i18n-panel.ts`
+ * says so at `projectRow`). It is also what a toast's action carries, so "Create Translation" from
+ * the warning `openTranslation` raises still writes beside the document that raised it after the
+ * author has switched tabs.
  *
  * `pane` is optional because the palette addresses the focus and the pane's own context bar
  * addresses itself. Refusing by name rather than falling back to the active tab is deliberate: a
  * caller that named a pane meant that pane, and quietly translating a different document is worse
- * than doing nothing.
+ * than doing nothing. The same rule refuses `path` AND `pane` together: two addresses that could
+ * disagree are not a document, and the caller that sent both has already said two things.
  *
  * A tab with no `documentPath` is refused here too. Every one of these verbs is a statement about
  * where a file LIVES, and a document that has never been written has no locale directory to be
  * beside.
  */
-function addressedTab(commandId: string, args: CommandArgValues): Tab & { documentPath: string } {
+function addressedDocument(commandId: string, args: CommandArgValues): string {
+  const path = optionalStringArg(commandId, args, "path");
   const paneId = optionalStringArg(commandId, args, "pane");
+  if (path !== undefined) {
+    if (paneId !== undefined) {
+      throw new RangeError(
+        `command "${commandId}" argument "path": names a file while "pane" names a pane — give one`,
+      );
+    }
+    return path;
+  }
   const tab = paneId === undefined ? (activeTab.value as Tab | null) : tabOfPane(paneId);
   if (!tab) {
     throw new RangeError(
@@ -86,7 +109,7 @@ function addressedTab(commandId: string, args: CommandArgValues): Tab & { docume
   if (tab.documentPath === null) {
     throw new RangeError(`command "${commandId}" needs a document that has been saved to a file`);
   }
-  return tab as Tab & { documentPath: string };
+  return tab.documentPath;
 }
 
 /**
@@ -96,9 +119,9 @@ function addressedTab(commandId: string, args: CommandArgValues): Tab & { docume
  * which: an undeclared tag, a project with no locales at all, and a path that cannot carry a locale
  * segment (a component, a layout, a file at the project root).
  */
-function siblingPath(tab: Tab & { documentPath: string }, locale: string): string | null {
+function siblingPath(documentPath: string, locale: string): string | null {
   const i18n = getEffectiveLocales();
-  const path = translationPathFor(tab.documentPath, locale, i18n);
+  const path = translationPathFor(documentPath, locale, i18n);
   if (path !== null) {
     return path;
   }
@@ -110,12 +133,12 @@ function siblingPath(tab: Tab & { documentPath: string }, locale: string): strin
     });
     return null;
   }
-  notify.error(`${tab.documentPath} cannot have a translation.`, {
+  notify.error(`${documentPath} cannot have a translation.`, {
     detail:
       "A translation is the same file under a locale directory, so only files that live under a " +
       "routed directory — pages and content entries — have one. A layout, a component or a file " +
       "at the project root is shared by every language.",
-    path: tab.documentPath,
+    path: documentPath,
     source: "Languages",
   });
   return null;
@@ -133,6 +156,21 @@ async function fileExists(path: string): Promise<boolean> {
   }
 }
 
+/**
+ * The two ways a translation verb is addressed, as {@link addressedDocument} reads them.
+ *
+ * Declared on both records because `registry.run` coerces every received key against the schema
+ * before `run`: the Languages panel's `{ locale, path }` was an undeclared key — a synchronous
+ * refusal out of a click — until `path` was written down here.
+ */
+const ADDRESS_PROPERTIES = {
+  pane: stringProperty("Pane whose document to translate. Defaults to the focused one."),
+  path: stringProperty(
+    "Project-relative path of the document to translate. Defaults to the addressed pane's " +
+      "document; not combined with `pane`.",
+  ),
+};
+
 /** The four records. */
 export function i18nCommands(): AnyCommand[] {
   return [
@@ -143,7 +181,7 @@ export function i18nCommands(): AnyCommand[] {
             declaredLocales,
             "The language to open this document's translation in.",
           ),
-          pane: stringProperty("Pane whose document to translate. Defaults to the focused one."),
+          ...ADDRESS_PROPERTIES,
         },
         ["locale"],
       ),
@@ -158,28 +196,29 @@ export function i18nCommands(): AnyCommand[] {
       group: "2_navigate",
       requires: "a document open in a project that declares more than one language",
       when: (ctx) => ctx.project.isMultilingual && ctx.document.open,
-      aiTool: {
-        description:
-          "Open this document's translation in another language — the sibling file under that " +
-          "locale's directory. Does not create one; use create_translation for that.",
-        name: "open_translation",
-      },
+      /* No `aiTool`, by §12.4's first deletion rule: this opens a surface for a person, and the
+         model has `open_document` for the file it names. */
       run: async (_ctx, args) => {
-        const tab = addressedTab("i18n.openTranslation", args);
+        const source = addressedDocument("i18n.openTranslation", args);
         const locale = stringArg("i18n.openTranslation", args, "locale");
-        const path = siblingPath(tab, locale);
+        const path = siblingPath(source, locale);
         if (path === null) {
           return;
         }
-        if (path === tab.documentPath) {
-          notify.info(`${tab.documentPath} is already the ${localeLabel(locale)} copy.`, {
+        if (path === source) {
+          notify.info(`${source} is already the ${localeLabel(locale)} copy.`, {
             source: "Languages",
           });
           return;
         }
         if (!(await fileExists(path))) {
+          /* `actionArgs` carries the whole address, not just the locale: the toast's button runs
+             `registry.run(action, actionArgs)` whenever the author clicks it, and by then the
+             focused document may be another file. `locale` is required, so without it the action
+             was a refusal before `run`. */
           notify.warn(`There is no ${localeLabel(locale)} translation of this document yet.`, {
             action: "i18n.createTranslation",
+            actionArgs: { locale, path: source },
             detail: `Create Translation writes ${path}, seeded from the document you are on.`,
             path,
             source: "Languages",
@@ -192,12 +231,16 @@ export function i18nCommands(): AnyCommand[] {
       title: "Open Translation",
     },
     {
-      args: argsSchema({
-        locale: derivedEnumProperty(
-          declaredLocales,
-          "The language to create this document's translation in.",
-        ),
-      }),
+      args: argsSchema(
+        {
+          locale: derivedEnumProperty(
+            declaredLocales,
+            "The language to create this document's translation in.",
+          ),
+          ...ADDRESS_PROPERTIES,
+        },
+        ["locale"],
+      ),
       category: "File",
       id: "i18n.createTranslation",
       level: "document",
@@ -208,22 +251,21 @@ export function i18nCommands(): AnyCommand[] {
       /* The document history cannot hold this: the change is a file that did not exist, and
          `undo: "project"` would claim `project.json` moved, which it did not. */
       undo: "none",
-      aiTool: {
-        description:
-          "Create the missing translation of this document in another language, seeded with a " +
-          "copy of the document being translated, and open it.",
-        name: "create_translation",
-      },
+      /* No `aiTool`, by §12.4's second deletion rule: `createFileIn` awaits the New File prompt
+         for the name, which the loop does not count as interactive, and a cancel resolves `null`
+         with nothing thrown — a report would describe a file that was never made. An optional
+         `name` argument that skips the prompt is the way back in, and is a UX call (issue 273). */
       run: async (_ctx, args) => {
-        const tab = addressedTab("i18n.createTranslation", args);
+        const source = addressedDocument("i18n.createTranslation", args);
         const locale = stringArg("i18n.createTranslation", args, "locale");
-        const path = siblingPath(tab, locale);
+        const path = siblingPath(source, locale);
         if (path === null) {
           return;
         }
         if (await fileExists(path)) {
           notify.info(`The ${localeLabel(locale)} translation already exists.`, {
             action: "i18n.openTranslation",
+            actionArgs: { locale, path: source },
             path,
             source: "Languages",
           });
@@ -235,11 +277,11 @@ export function i18nCommands(): AnyCommand[] {
            they saved. */
         let content: string;
         try {
-          content = await getPlatform().readFile(tab.documentPath);
+          content = await getPlatform().readFile(source);
         } catch {
           // An unreadable source is not a translation that can be seeded, and the path says which.
-          notify.error(`Could not read ${tab.documentPath} to copy it.`, {
-            path: tab.documentPath,
+          notify.error(`Could not read ${source} to copy it.`, {
+            path: source,
             source: "Languages",
           });
           return;
@@ -267,12 +309,7 @@ export function i18nCommands(): AnyCommand[] {
       group: "2_view",
       requires: "a project that declares more than one language",
       when: (ctx) => ctx.project.isMultilingual,
-      aiTool: {
-        description:
-          "Show the Languages panel — every page in the project against every declared language, " +
-          "and which translations are missing or older than their source.",
-        name: "show_translation_parity",
-      },
+      /* No `aiTool`, by §12.4's first deletion rule: the panel is a surface for a person. */
       /* The panel is off the rail — it spends no rail slot and shifts no ⌘1-8 chord — so this
          command and the generated `panel.focus.i18n` are its only two doors, and both open the
          same one. The TITLES must differ even though the behaviour does not: the palette is a flat
@@ -305,11 +342,39 @@ export function i18nCommands(): AnyCommand[] {
       aiTool: {
         description:
           "Declare a language for this project, adding it to project.json's i18n.locales. Every " +
-          "other language surface reads that list.",
+          "other language surface reads that list. Canonicalizes the tag; a malformed one is " +
+          "refused.",
         name: "add_project_locale",
+        /* The read is the same one the translation verbs' enum makes — the effective locales —
+           so "what did that unlock" is answered from the list the next round's schemas are built
+           from. The already-declared case is a statement, not a change: `addProjectLocale` toasts
+           and returns `false`, the sentence here says so rather than reporting a declaration, and
+           `wrote: []` keeps the ledger from filing a `project.json` the run never touched. */
+        report: ({ args }) => {
+          const canonical = canonicalizeLocale(stringArg("i18n.addLocale", args, "locale")) ?? "";
+          const declared = declaredLocales().join(", ") || canonical;
+          return _lastAddLocaleWrote
+            ? `Declared ${canonical}; project locales are now ${declared}.`
+            : {
+                summary: `${localeLabel(canonical)} was already one of this project's languages; the locales are ${declared}.`,
+                wrote: [],
+              };
+        },
       },
       run: async (_ctx, args) => {
-        await addProjectLocale(stringArg("i18n.addLocale", args, "locale"));
+        const tag = stringArg("i18n.addLocale", args, "locale");
+        /* Refuse by THROWING, not by toasting. `addProjectLocale` notifies a malformed tag and
+           returns, because its other caller is the Locales form, which has already refused it under
+           the field — but a projected `run` is read by the model, and a toast is a refusal only the
+           person can read. The canonical check is the section's own (`canonicalizeLocale`), read
+           here rather than respelled. */
+        if (canonicalizeLocale(tag) === null) {
+          throw new RangeError(
+            `command "i18n.addLocale" argument "locale": "${tag}" is not a well-formed BCP 47 ` +
+              `tag — a language, optionally a script and a region: fr, pt-BR, zh-Hant`,
+          );
+        }
+        _lastAddLocaleWrote = await addProjectLocale(tag);
       },
       title: "Add Language",
     },