@jxsuite/studio 4.1.0 → 5.1.0

package/src/settings/locales-section.ts

@@ -12,38 +12,50 @@
  * of the same merge is how the command and the form would come to disagree about what happens to
  * `defaultLocale` when the first locale is added.
  *
+ * **The form is a document.** The markup and the styling are `surfaces/settings-locales.json`, its
+ * mount is `surfaces/settings-locales.ts`, and what is left here is the part that was always this
+ * module's: what the file says, what a tag is allowed to be, and what each edit writes back. The
+ * section renderer is still `renderLocalesSection`, because a section is a contribution to
+ * CONFIGURATION and the registry's seam does not move when the substrate under it does.
+ *
  * @docs studio/projects/settings
  */
 
-import { html, render as litRender, nothing } from "lit-html";
 import { canonicalizeLocale, isWellFormedLocale, localeLabel } from "@jxsuite/schema/locale";
 import { errorMessage } from "@jxsuite/schema/parse";
 import { notify } from "../services/notify";
 import { projectState } from "../store";
+import { renderLocalesSurface } from "../surfaces/settings-locales";
 import { updateSiteConfig } from "../site-context";
+import type { LocalesActions, LocalesView } from "../surfaces/settings-locales";
 import type { LocaleRouting } from "@jxsuite/schema/locale";
 import type { ProjectConfig } from "@jxsuite/schema/types";
 
 /**
- * The last failed write per rendered section container.
+ * The form beside the file: the tag being typed, and the last write that failed.
  *
- * Keyed by container so two mounted copies (and two tests) never share a message — the same shape
- * `project-sections.ts` and `general-settings.ts` use, and for the same reason: these sections save
- * on change, so a silent rejection would read as "my edit just vanished".
+ * Keyed by container so two mounted copies (and two tests) never share either — the same shape
+ * `project-sections.ts` and `general-settings.ts` use for their own errors, and for the same
+ * reason: these sections save on change, so a silent rejection would read as "my edit just
+ * vanished". The pending tag is here rather than in the document because typing must survive the
+ * section being redrawn from outside — a nav click, an extension registering — and a document that
+ * remounts is a field that empties.
  */
-const errors = new WeakMap<HTMLElement, string>();
-
-/** Drop a parked error and re-render. */
-function clearError(container: HTMLElement): void {
-  errors.delete(container);
+interface Form {
+  pending: string;
+  error: string;
 }
 
-/** The error line for a section, if its last write failed. */
-function errorLine(container: HTMLElement) {
-  const message = errors.get(container);
-  return message === undefined
-    ? nothing
-    : html`<p class="settings-field-error" role="alert">${message}</p>`;
+const forms = new WeakMap<HTMLElement, Form>();
+
+/** This container's form, minted on first sight. */
+function form(container: HTMLElement): Form {
+  let state = forms.get(container);
+  if (!state) {
+    state = { error: "", pending: "" };
+    forms.set(container, state);
+  }
+  return state;
 }
 
 /**
@@ -56,20 +68,15 @@ function errorLine(container: HTMLElement) {
  *
  * @param {HTMLElement} container
  * @param {Partial<ProjectConfig>} patch
- * @param {() => void} rerender
  */
-async function persist(
-  container: HTMLElement,
-  patch: Partial<ProjectConfig>,
-  rerender: () => void,
-): Promise<void> {
+async function persist(container: HTMLElement, patch: Partial<ProjectConfig>): Promise<void> {
   try {
     await updateSiteConfig(patch);
-    clearError(container);
+    form(container).error = "";
   } catch (error) {
-    errors.set(container, `Could not save project.json — ${errorMessage(error)}`);
+    form(container).error = `Could not save project.json — ${errorMessage(error)}`;
   }
-  rerender();
+  refresh(container);
 }
 
 /** The live project configuration, or an empty one before a project is open. */
@@ -121,14 +128,23 @@ function alreadyDeclared(tag: string): boolean {
  * added.
  *
  * Refusals are notified rather than thrown: the palette reports a rejected `run` to the console and
- * nowhere else, so a thrown refusal is one the author never sees. The form disables Add for both of
- * them before it gets here, with the reason under the field.
+ * nowhere else, so a thrown refusal is one the author never sees. The form refuses both of them
+ * before it gets here, with the reason under the field.
+ *
+ * **It answers whether it wrote.** The already-declared case is decided HERE, against the raw
+ * `locales` the author wrote — not against the resolved list, which unshifts a `defaultLocale` the
+ * array does not hold — and `i18n.addLocale`'s report has to tell the model the same thing this
+ * function told the file. A second reading of "is it declared" beside the command would be a second
+ * spelling of this predicate, and the two disagreed exactly on that default: the report said
+ * "already declared" for a tag this function had just written.
  *
  * @param {string} tag - A BCP 47 language tag, in any case.
+ * @returns {Promise<boolean>} `true` when `project.json` was written; `false` for a refused or
+ *   already-declared tag, both of which have been notified.
  * @throws {Error} Whatever `updateSiteConfig` rejects with — the caller decides where a failed
  *   write shows.
  */
-export async function addProjectLocale(tag: string): Promise<void> {
+export async function addProjectLocale(tag: string): Promise<boolean> {
   const canonical = canonicalizeLocale(tag);
   if (canonical === null) {
     notify.error(`"${tag}" is not a well-formed language tag.`, {
@@ -137,22 +153,20 @@ export async function addProjectLocale(tag: string): Promise<void> {
         "`pt-BR`, `zh-Hant`. Underscores and spaces are not part of the grammar.",
       source: "Languages",
     });
-    return;
+    return false;
   }
   if (alreadyDeclared(canonical)) {
     notify.info(`${localeLabel(canonical)} is already one of this project's languages.`, {
       source: "Languages",
     });
-    return;
+    return false;
   }
   await updateSiteConfig({
     i18n: { ...config().i18n, locales: [...declaredLocales(), canonical] },
   });
+  return true;
 }
 
-/** Pending tag per container, so typing survives the section re-rendering. */
-const pendingTag = new WeakMap<HTMLElement, string>();
-
 /**
  * Why the pending tag cannot be added, or `""` when it can.
  *
@@ -161,7 +175,7 @@ const pendingTag = new WeakMap<HTMLElement, string>();
  * happened" is what a silently refused Add looks like.
  */
 function pendingRefusal(container: HTMLElement): string {
-  const tag = (pendingTag.get(container) ?? "").trim();
+  const tag = form(container).pending.trim();
   if (tag === "") {
     return "";
   }
@@ -172,176 +186,112 @@ function pendingRefusal(container: HTMLElement): string {
 }
 
 /**
- * The project's languages, its default, and how a locale is spelled in a URL.
+ * What the section shows right now.
  *
- * Every handler re-reads `config()` instead of closing over the render's values: `projectState` is
- * a plain module binding replaced wholesale on a project switch, and an extension or the raw JSON
- * editor can write `i18n` between this render and the click that follows it.
- *
- * @param {HTMLElement} container
+ * Read from `config()` at the moment of drawing rather than carried from the last one:
+ * `projectState` is a plain module binding replaced wholesale on a project switch, and an extension
+ * or the raw JSON editor can write `i18n` between two of these.
  */
-export function renderLocalesSection(container: HTMLElement): void {
-  const rerender = () => renderLocalesSection(container);
+function view(container: HTMLElement): LocalesView {
   const locales = declaredLocales();
   const { i18n } = config();
-  const pending = pendingTag.get(container) ?? "";
-  const refusal = pendingRefusal(container);
-
-  const add = () => {
-    const tag = (pendingTag.get(container) ?? "").trim();
-    if (tag === "" || pendingRefusal(container) !== "") {
-      return;
-    }
-    pendingTag.delete(container);
-    void persist(
-      container,
-      { i18n: { ...config().i18n, locales: [...declaredLocales(), canonicalizeLocale(tag)!] } },
-      rerender,
-    );
+  const { error, pending } = form(container);
+  return {
+    defaultLocale: i18n?.defaultLocale ?? locales[0] ?? "",
+    error,
+    localeOptions: locales.map((tag) => ({ label: localeLabel(tag), value: tag })),
+    locales: locales.map((tag) => ({ label: localeLabel(tag), tag })),
+    pending,
+    refusal: pendingRefusal(container),
+    routing: i18n?.routing ?? "prefix-except-default",
+    routings: LOCALE_ROUTINGS.map((mode) => ({ label: mode.label, value: mode.value })),
   };
+}
 
-  const remove = (tag: string) => {
-    const kept = declaredLocales().filter((declared) => declared !== tag);
-    if (kept.length === 0) {
-      /* The last language leaves with the block. An `i18n` holding an empty `locales` is a build
-         error (`resolveI18n`: "declared with no usable locale"), so removing the last row would
-         otherwise break the build of a project that is once again ordinary and monolingual. */
-      void persist(container, CLEAR_I18N, rerender);
-      return;
-    }
-    const current = config().i18n;
-    /* A `defaultLocale` naming a locale that is no longer declared does not go away — `resolveI18n`
-       puts it BACK at the head of the list, so deleting the default row without this would delete
-       nothing and reorder the rest. */
-    const orphaned =
-      current?.defaultLocale !== undefined &&
-      canonicalizeLocale(current.defaultLocale) === canonicalizeLocale(tag);
-    void persist(
-      container,
-      { i18n: { ...current, ...(orphaned ? { defaultLocale: kept[0]! } : {}), locales: kept } },
-      rerender,
-    );
-  };
+/** Re-read the file and the form, and let the surface reconcile. */
+function refresh(container: HTMLElement): void {
+  renderLocalesSurface(container, view(container), actions(container));
+}
 
-  const onDefaultChange = (e: Event) => {
-    void persist(
-      container,
-      { i18n: { ...config().i18n, defaultLocale: (e.target as HTMLInputElement).value } },
-      rerender,
-    );
-  };
+/** Add the pending tag, if it is one this project can take. */
+function add(container: HTMLElement): void {
+  const tag = form(container).pending.trim();
+  if (tag === "" || pendingRefusal(container) !== "") {
+    return;
+  }
+  form(container).pending = "";
+  void persist(container, {
+    i18n: { ...config().i18n, locales: [...declaredLocales(), canonicalizeLocale(tag)!] },
+  });
+}
 
-  const onRoutingChange = (e: Event) => {
-    void persist(
-      container,
-      {
-        i18n: {
-          ...config().i18n,
-          routing: (e.target as HTMLInputElement).value as LocaleRouting,
-        },
-      },
-      rerender,
-    );
-  };
+/** Drop a language, and the block itself when it was the last one. */
+function remove(container: HTMLElement, tag: string): void {
+  const kept = declaredLocales().filter((declared) => declared !== tag);
+  if (kept.length === 0) {
+    /* The last language leaves with the block. An `i18n` holding an empty `locales` is a build
+       error (`resolveI18n`: "declared with no usable locale"), so removing the last row would
+       otherwise break the build of a project that is once again ordinary and monolingual. */
+    void persist(container, CLEAR_I18N);
+    return;
+  }
+  const current = config().i18n;
+  /* A `defaultLocale` naming a locale that is no longer declared does not go away — `resolveI18n`
+     puts it BACK at the head of the list, so deleting the default row without this would delete
+     nothing and reorder the rest. */
+  const orphaned =
+    current?.defaultLocale !== undefined &&
+    canonicalizeLocale(current.defaultLocale) === canonicalizeLocale(tag);
+  void persist(container, {
+    i18n: { ...current, ...(orphaned ? { defaultLocale: kept[0]! } : {}), locales: kept },
+  });
+}
 
-  const tpl = html`
-    <div class="settings-section">
-      <h3 class="settings-section-title">Locales</h3>
-      <p class="settings-field-desc">
-        The languages this site is written in. A translation is a file under the locale's directory
-        — pages/fr/about.json beside pages/about.json — so declaring a language here is what makes
-        that directory mean something to the build and to Studio.
-      </p>
-      ${errorLine(container)}
-      <div class="settings-field">
-        <label class="settings-field-label">Languages</label>
-        <div class="settings-list-panel">
-          ${
-            locales.length === 0
-              ? html`<div class="settings-empty-state">No languages declared.</div>`
-              : locales.map(
-                  (tag) => html`
-                    <div class="settings-row">
-                      <span class="settings-row-name">${localeLabel(tag)}</span>
-                      <span class="settings-locale-tag">${tag}</span>
-                      <sp-action-button
-                        size="xs"
-                        quiet
-                        title=${`Remove ${tag}`}
-                        @click=${() => remove(tag)}
-                      >
-                        <sp-icon-delete slot="icon"></sp-icon-delete>
-                      </sp-action-button>
-                    </div>
-                  `,
-                )
-          }
-          <div class="settings-inline-form">
-            <sp-textfield
-              size="s"
-              class="settings-locale-name"
-              placeholder="fr-CA"
-              .value=${pending}
-              @input=${(e: Event) => {
-                const before = pendingRefusal(container);
-                pendingTag.set(container, (e.target as HTMLInputElement).value);
-                /* Re-render only when the VERDICT changes, not per keystroke: redrawing on every
-                   character would push `.value` back into a field the author is typing in, and
-                   never redrawing would leave the refusal below it describing an older tag. */
-                if (pendingRefusal(container) !== before) {
-                  rerender();
-                }
-              }}
-              @keydown=${(e: KeyboardEvent) => {
-                if (e.key === "Enter") {
-                  add();
-                }
-              }}
-            ></sp-textfield>
-            <sp-action-button size="s" @click=${add}>Add</sp-action-button>
-          </div>
-        </div>
-        ${refusal === "" ? nothing : html`<p class="settings-field-error">${refusal}</p>`}
-      </div>
-      <div class="settings-field">
-        <label class="settings-field-label">Default Language</label>
-        <p class="settings-field-desc">
-          The language a page is written in when its file carries no locale directory.
-        </p>
-        <sp-picker
-          size="s"
-          label="Default Language"
-          class="settings-default-locale"
-          .value=${i18n?.defaultLocale ?? locales[0] ?? ""}
-          ?disabled=${locales.length === 0}
-          @change=${onDefaultChange}
-        >
-          ${locales.map(
-            (tag) => html`<sp-menu-item value=${tag}>${localeLabel(tag)}</sp-menu-item>`,
-          )}
-        </sp-picker>
-      </div>
-      <div class="settings-field">
-        <label class="settings-field-label">URL Routing</label>
-        <p class="settings-field-desc">
-          Whether the default language owns the unprefixed URLs, or every language is named in its
-          own.
-        </p>
-        <sp-picker
-          size="s"
-          label="URL Routing"
-          class="settings-locale-routing"
-          .value=${i18n?.routing ?? "prefix-except-default"}
-          ?disabled=${locales.length === 0}
-          @change=${onRoutingChange}
-        >
-          ${LOCALE_ROUTINGS.map(
-            (routing) => html`<sp-menu-item value=${routing.value}>${routing.label}</sp-menu-item>`,
-          )}
-        </sp-picker>
-      </div>
-    </div>
-  `;
+/**
+ * What the reader may do, bound to one container.
+ *
+ * Memoized per container so the surface is handed the same functions every time: they are read
+ * once, when it mounts, and a fresh set on every refresh would be a scope write that says nothing.
+ */
+const bound = new WeakMap<HTMLElement, LocalesActions>();
+
+function actions(container: HTMLElement): LocalesActions {
+  let acts = bound.get(container);
+  if (!acts) {
+    acts = {
+      add: () => {
+        add(container);
+      },
+      chooseDefault: (value: string) => {
+        void persist(container, { i18n: { ...config().i18n, defaultLocale: value } });
+      },
+      chooseRouting: (value: string) => {
+        void persist(container, {
+          i18n: { ...config().i18n, routing: value as LocaleRouting },
+        });
+      },
+      edit: (value: string) => {
+        /* Every keystroke, with no verdict check in front of it. The lit form re-rendered only when
+           the refusal CHANGED, because redrawing pushed `.value` back into the field mid-word; the
+           document writes the same string the field already holds and `jx-textfield` leaves the
+           caret where it is, so the guard has nothing left to protect. */
+        form(container).pending = value;
+        refresh(container);
+      },
+      remove: (tag: string) => {
+        remove(container, tag);
+      },
+    };
+    bound.set(container, acts);
+  }
+  return acts;
+}
 
-  litRender(tpl, container);
+/**
+ * The project's languages, its default, and how a locale is spelled in a URL.
+ *
+ * @param {HTMLElement} container
+ */
+export function renderLocalesSection(container: HTMLElement): void {
+  refresh(container);
 }

package/src/settings/preferences-accounts.ts

@@ -37,7 +37,7 @@ export interface AccountAction {
   /** Stable key — the button's `data-action`, so a test names an intent rather than a label. */
   id: string;
   label: string;
-  /** Spectrum `variant`; omitted for the default treatment. */
+  /** The button's `variant`; omitted for the default treatment. */
   variant?: string;
   /** Do it. Async ones repaint the sheet when they settle. */
   run: () => void | Promise<void>;