@jxsuite/studio 4.1.0 → 5.0.0

package/src/settings/contexts-section.ts

@@ -27,21 +27,34 @@
  * Failures are surfaced, not swallowed: every write runs through {@link persistMedia}, which
  * schema-validates the candidate `project.json` with `jx-validate` first (the human editing this
  * file used to get **no validation at all** — that was wired to the AI's `write_project_config`
- * alone), parks any rejection under the control that caused it, and re-renders. §7.1's third tier:
+ * alone), parks any rejection under the control that caused it, and re-projects. §7.1's third tier:
  * a bad value belongs at its control, not in a toast that expires.
  *
+ * **The markup is `surfaces/settings-contexts.json`.** This module is the section's decisions —
+ * what a context is, what refuses one, and what reaches disk — and the surface adapter beside that
+ * document owns the mount. The registry seam did not move: `renderContextsSection` is still the
+ * `render(container)` a `SettingsSection` declares, and it is still called again for every change
+ * the host notices. What changed underneath is that a call is now a PROJECTION rather than a
+ * repaint: the reactive scope takes the new view and the runtime touches the rows that differ,
+ * where the lit version rebuilt the whole section on every keystroke's write.
+ *
  * @docs studio/projects/settings
  */
 
-import { html, render as litRender, nothing } from "lit-html";
-import { live } from "lit-html/directives/live.js";
 import { errorMessage } from "@jxsuite/schema/parse";
 import { projectState } from "../store";
 import { updateSiteConfig } from "../site-context";
 import { validateProjectConfig } from "../services/jx-validate";
 import { isSchemeQuery, schemeOfQuery } from "../utils/canvas-media";
 import { mediaDisplayName } from "../panels/shared";
-
+import { mountContextsSurface } from "../surfaces/settings-contexts";
+
+import type {
+  ContextGroupView,
+  ContextRowView,
+  ContextsSurfaceHandle,
+  ContextsView,
+} from "../surfaces/settings-contexts";
 import type { ProjectConfig } from "@jxsuite/schema/types";
 
 /** The `$media` key the base width lives under. Not a query — a number of CSS pixels. */
@@ -123,6 +136,58 @@ export function contextKeyOf(name: string): string {
   return slug ? `--${slug}` : "";
 }
 
+// ─── The three groups ─────────────────────────────────────────────────────────
+
+/** A group's fixed half: its words, and what its add button creates. */
+interface GroupSpec {
+  kind: ContextKind;
+  label: string;
+  desc: string;
+  addLabel: string;
+  empty: string;
+  /** The `--<stem>` an added entry is named after, before de-duplication. */
+  stem: string;
+  /** The query an added entry starts as — always a real one, never a blank to fill in. */
+  newQuery: string;
+}
+
+/**
+ * The groups, in render order.
+ *
+ * A table rather than three call sites, because the only thing that differed between them in the
+ * lit version was seven strings and a control choice — and the control choice is derived from the
+ * kind, so there was nothing left for a hand-written group to decide.
+ */
+const GROUPS: readonly GroupSpec[] = [
+  {
+    addLabel: "Add breakpoint",
+    desc: "Screen widths that get their own canvas and their own style values.",
+    empty: "No breakpoints yet — every width uses the base styles.",
+    kind: "size",
+    label: "Size breakpoints",
+    newQuery: NEW_BREAKPOINT_QUERY,
+    stem: "breakpoint",
+  },
+  {
+    addLabel: "Add colour scheme",
+    desc: "Light and dark renderings. Defining one turns on the Auto / Light / Dark control.",
+    empty: "No colour schemes yet — the project renders one way.",
+    kind: "scheme",
+    label: "Colour schemes",
+    newQuery: "(prefers-color-scheme: dark)",
+    stem: "dark",
+  },
+  {
+    addLabel: "Add feature query",
+    desc: "Anything else a media query can ask: reduced motion, print, hover, orientation.",
+    empty: "No feature queries yet.",
+    kind: "feature",
+    label: "Feature queries",
+    newQuery: NEW_FEATURE_QUERY,
+    stem: "feature",
+  },
+];
+
 // ─── Per-container error state ────────────────────────────────────────────────
 
 /**
@@ -149,321 +214,258 @@ const errors = new WeakMap<HTMLElement, { target: ErrorTarget; message: string }
  */
 const inheritedErrors = new WeakMap<HTMLElement, string[]>();
 
+/** The mounted surface, per container — see {@link renderContextsSection}. */
+const mounts = new WeakMap<HTMLElement, ContextsSurfaceHandle>();
+
 /** Read the current failure for a container — exported for tests and for re-render helpers. */
 export function contextsError(container: HTMLElement): { target: string; message: string } | null {
   return errors.get(container) ?? null;
 }
 
-// ─── Render ───────────────────────────────────────────────────────────────────
+// ─── The project, as it stands now ────────────────────────────────────────────
 
 /**
- * Render Project Settings › Contexts into `container`.
+ * The config and its `$media`, read at the moment they are needed.
  *
- * @param {HTMLElement} container
+ * The lit version closed over both at render time and rebuilt every handler on every render, so a
+ * stale closure was impossible only because there were no long-lived ones. The handlers now outlive
+ * a projection, which makes reading through to the store the thing that keeps them honest.
  */
-export function renderContextsSection(container: HTMLElement): void {
-  const config = (projectState?.projectConfig || {}) as ProjectConfig;
-  const media = (config.$media || {}) as Record<string, string>;
-  const shown = errors.get(container);
-  const { base, entries } = splitContexts(media);
-
-  /** Park a failure under one control without writing anything. */
-  const reject = (target: ErrorTarget, message: string) => {
-    errors.set(container, { message, target });
-    renderContextsSection(container);
-  };
-
-  /**
-   * Write a whole `$media` map, validating it first and surfacing whatever refuses it.
-   *
-   * Both failure modes are real and both used to be invisible here: the schema can refuse the
-   * shape, and the disk can refuse the write. The predecessor surfaces (`Properties › Media` and
-   * the CSS-variables "Enable dark scheme") did `void updateSiteConfig(...)` and dropped the
-   * rejection, so a failed write read as the field snapping back for no reason.
-   *
-   * **Only the errors THIS edit introduces block it.** The candidate is the whole `project.json`,
-   * so a violation anywhere else in the file used to refuse every context edit and park the reason
-   * under whichever control had been touched — typing `1280px` into Base width reported three
-   * unevaluated-property errors about `title`, `description` and `$style`, none of which is a
-   * width. The baseline is validated first and subtracted, the same way `services/ai-tools.ts`
-   * subtracts it before blaming the model for a document it inherited. A pre-existing problem is
-   * still worth saying, so it is reported once at section level, where a whole-file problem belongs
-   * — and it is reported rather than repaired, because `project.json` is the author's file and a
-   * settings screen that silently drops keys it did not recognise is worse than one that names
-   * them.
-   */
-  const persistMedia = async (next: Record<string, string>, target: ErrorTarget) => {
-    const candidate = { ...config, $media: next } as unknown;
-    let schemaErrors: string[] = [];
-    let inherited: string[] = [];
-    try {
-      inherited = await validateProjectConfig(config);
-      const found = await validateProjectConfig(candidate);
-      schemaErrors = found.filter((error) => !inherited.includes(error));
-    } catch (error) {
-      /* A validator that cannot compile must not block the edit — but it must not be silent
-         either, so the message rides the same inline slot the schema errors would have used. */
-      reject(target, `Could not validate project.json — ${errorMessage(error)}`);
-      return;
-    }
-    if (schemaErrors.length > 0) {
-      reject(target, schemaErrors.join("; "));
-      return;
-    }
-    inheritedErrors.set(container, inherited);
-    try {
-      await updateSiteConfig({ $media: next });
-      errors.delete(container);
-    } catch (error) {
-      errors.set(container, {
-        message: `Could not save project.json — ${errorMessage(error)}`,
-        target,
-      });
-    }
-    renderContextsSection(container);
-  };
-
-  /**
-   * What is already wrong with `project.json`, said once and not blamed on a control.
-   *
-   * It does not block anything — the edit that surfaced it went through. It is here because a file
-   * that fails its own schema will keep failing it, and until this notice existed the only place
-   * that fact appeared was as an unexplained refusal of an unrelated field.
-   */
-  const inheritedNotice = () => {
-    const inherited = inheritedErrors.get(container) ?? [];
-    return inherited.length === 0
-      ? nothing
-      : html`<p class="settings-section-notice" role="status">
-          project.json has ${inherited.length} pre-existing schema
-          ${inherited.length === 1 ? "problem" : "problems"} that this section did not cause:
-          ${inherited.join("; ")}
-        </p>`;
-  };
-
-  /** The error line for one control, when that is where the current failure belongs. */
-  const errorFor = (target: ErrorTarget) =>
-    shown?.target === target
-      ? html`<p class="settings-field-error" role="alert">${shown.message}</p>`
-      : nothing;
+function currentConfig(): ProjectConfig {
+  return (projectState?.projectConfig || {}) as ProjectConfig;
+}
 
-  // ─── Base width ────────────────────────────────────────────────────────────
+function currentMedia(): Record<string, string> {
+  return (currentConfig().$media || {}) as Record<string, string>;
+}
 
-  const onBaseChange = (e: Event) => {
-    const value = (e.target as HTMLInputElement).value.trim();
-    if (value && !/^\d+px$/.test(value)) {
-      reject("base", "Enter a width in pixels, like 1280px.");
-      return;
-    }
-    const next = { ...media };
-    if (value) {
-      next[BASE_KEY] = value;
-    } else {
-      delete next[BASE_KEY];
-    }
-    void persistMedia(next, "base");
-  };
+// ─── Writing ──────────────────────────────────────────────────────────────────
 
-  // ─── Row editing ───────────────────────────────────────────────────────────
+/** Park a failure under one control without writing anything. */
+function reject(container: HTMLElement, target: ErrorTarget, message: string): void {
+  errors.set(container, { message, target });
+  renderContextsSection(container);
+}
 
-  const onRename = (oldKey: string) => (e: Event) => {
-    const newKey = contextKeyOf((e.target as HTMLInputElement).value);
-    if (!newKey) {
-      reject(oldKey, "A context needs a name.");
-      return;
-    }
-    if (newKey === oldKey) {
-      return;
-    }
-    if (newKey in media) {
-      reject(oldKey, `"${mediaDisplayName(newKey)}" is already defined.`);
-      return;
-    }
-    /* Rebuild in place so renaming never reorders the list — the order is the order the pane
-       context bar offers them in, and a rename is not a reordering. */
-    const next: Record<string, string> = {};
-    for (const [key, value] of Object.entries(media)) {
-      next[key === oldKey ? newKey : key] = value;
-    }
-    void persistMedia(next, newKey);
-  };
+/**
+ * Write a whole `$media` map, validating it first and surfacing whatever refuses it.
+ *
+ * Both failure modes are real and both used to be invisible here: the schema can refuse the shape,
+ * and the disk can refuse the write. The predecessor surfaces (`Properties › Media` and the
+ * CSS-variables "Enable dark scheme") did `void updateSiteConfig(...)` and dropped the rejection,
+ * so a failed write read as the field snapping back for no reason.
+ *
+ * **Only the errors THIS edit introduces block it.** The candidate is the whole `project.json`, so
+ * a violation anywhere else in the file used to refuse every context edit and park the reason under
+ * whichever control had been touched — typing `1280px` into Base width reported three
+ * unevaluated-property errors about `title`, `description` and `$style`, none of which is a width.
+ * The baseline is validated first and subtracted, the same way `services/ai-tools.ts` subtracts it
+ * before blaming the model for a document it inherited. A pre-existing problem is still worth
+ * saying, so it is reported once at section level, where a whole-file problem belongs — and it is
+ * reported rather than repaired, because `project.json` is the author's file and a settings screen
+ * that silently drops keys it did not recognise is worse than one that names them.
+ */
+async function persistMedia(
+  container: HTMLElement,
+  next: Record<string, string>,
+  target: ErrorTarget,
+): Promise<void> {
+  const config = currentConfig();
+  const candidate = { ...config, $media: next } as unknown;
+  let schemaErrors: string[] = [];
+  let inherited: string[] = [];
+  try {
+    inherited = await validateProjectConfig(config);
+    const found = await validateProjectConfig(candidate);
+    schemaErrors = found.filter((error) => !inherited.includes(error));
+  } catch (error) {
+    /* A validator that cannot compile must not block the edit — but it must not be silent either,
+       so the message rides the same inline slot the schema errors would have used. */
+    reject(container, target, `Could not validate project.json — ${errorMessage(error)}`);
+    return;
+  }
+  if (schemaErrors.length > 0) {
+    reject(container, target, schemaErrors.join("; "));
+    return;
+  }
+  inheritedErrors.set(container, inherited);
+  try {
+    await updateSiteConfig({ $media: next });
+    errors.delete(container);
+  } catch (error) {
+    errors.set(container, {
+      message: `Could not save project.json — ${errorMessage(error)}`,
+      target,
+    });
+  }
+  renderContextsSection(container);
+}
 
-  const onQueryChange = (key: string) => (e: Event) => {
-    const query = (e.target as HTMLInputElement).value.trim();
-    if (!query) {
-      reject(key, "A context needs a media query, like (max-width: 768px).");
-      return;
-    }
-    void persistMedia({ ...media, [key]: query }, key);
+/** What every control in one container does. Built once, and read through to the store. */
+function actionsFor(container: HTMLElement): Parameters<typeof mountContextsSurface>[1] {
+  return {
+    /** Add an entry under the first free `--<stem>` / `--<stem>-2` … name. */
+    add(kind) {
+      const spec = GROUPS.find((group) => group.kind === kind);
+      if (!spec) {
+        return;
+      }
+      const media = currentMedia();
+      let key = `--${spec.stem}`;
+      let n = 2;
+      while (key in media) {
+        key = `--${spec.stem}-${n}`;
+        n += 1;
+      }
+      void persistMedia(container, { ...media, [key]: spec.newQuery }, key);
+    },
+    remove(key) {
+      const next = { ...currentMedia() };
+      delete next[key];
+      void persistMedia(container, next, "section");
+    },
+    rename(oldKey, value) {
+      const media = currentMedia();
+      const newKey = contextKeyOf(value);
+      if (!newKey) {
+        reject(container, oldKey, "A context needs a name.");
+        return;
+      }
+      if (newKey === oldKey) {
+        return;
+      }
+      if (newKey in media) {
+        reject(container, oldKey, `"${mediaDisplayName(newKey)}" is already defined.`);
+        return;
+      }
+      /* Rebuild in place so renaming never reorders the list — the order is the order the pane
+         context bar offers them in, and a rename is not a reordering. */
+      const next: Record<string, string> = {};
+      for (const [key, entry] of Object.entries(media)) {
+        next[key === oldKey ? newKey : key] = entry;
+      }
+      void persistMedia(container, next, newKey);
+    },
+    setBase(value) {
+      const width = value.trim();
+      if (width && !/^\d+px$/.test(width)) {
+        reject(container, "base", "Enter a width in pixels, like 1280px.");
+        return;
+      }
+      const next = { ...currentMedia() };
+      if (width) {
+        next[BASE_KEY] = width;
+      } else {
+        delete next[BASE_KEY];
+      }
+      void persistMedia(container, next, "base");
+    },
+    setQuery(key, value) {
+      const query = value.trim();
+      if (!query) {
+        reject(container, key, "A context needs a media query, like (max-width: 768px).");
+        return;
+      }
+      void persistMedia(container, { ...currentMedia(), [key]: query }, key);
+    },
+    /** The scheme picker writes the canonical query, so a scheme is never mistyped into a feature. */
+    setScheme(key, scheme) {
+      void persistMedia(
+        container,
+        { ...currentMedia(), [key]: `(prefers-color-scheme: ${scheme})` },
+        key,
+      );
+    },
   };
+}
 
-  const onRemove = (key: string) => () => {
-    const next = { ...media };
-    delete next[key];
-    void persistMedia(next, "section");
+// ─── Projection ───────────────────────────────────────────────────────────────
+
+/** One `$media` entry, as the document draws it. */
+function rowView(
+  entry: ContextEntry,
+  shown: { target: ErrorTarget; message: string } | undefined,
+): ContextRowView {
+  const display = mediaDisplayName(entry.key);
+  const invalid = shown?.target === entry.key;
+  return {
+    control: entry.kind === "scheme" ? "scheme" : "query",
+    error: invalid ? shown.message : "",
+    invalid,
+    key: entry.key,
+    name: entry.key.replace(/^--/, ""),
+    nameLabel: `Name for ${display}`,
+    query: entry.query,
+    removeLabel: `Remove ${display}`,
+    scheme: schemeOfQuery(entry.query) ?? "dark",
+    valueLabel:
+      entry.kind === "scheme" ? `Colour scheme for ${display}` : `Media query for ${display}`,
   };
+}
 
-  /** Add an entry under the first free `--<stem>` / `--<stem>-2` … name. */
-  const add = (stem: string, query: string) => () => {
-    let key = `--${stem}`;
-    let n = 2;
-    while (key in media) {
-      key = `--${stem}-${n}`;
-      n += 1;
-    }
-    void persistMedia({ ...media, [key]: query }, key);
-  };
+/**
+ * What the file already got wrong, said once and not blamed on a control.
+ *
+ * It does not block anything — the edit that surfaced it went through. It is here because a file
+ * that fails its own schema will keep failing it, and until this notice existed the only place that
+ * fact appeared was as an unexplained refusal of an unrelated field.
+ */
+function noticeOf(inherited: readonly string[]): string {
+  if (inherited.length === 0) {
+    return "";
+  }
+  const what = inherited.length === 1 ? "problem" : "problems";
+  return `project.json has ${inherited.length} pre-existing schema ${what} that this section did not cause: ${inherited.join("; ")}`;
+}
 
-  /** The scheme picker writes the canonical query, so a scheme is never mistyped into a feature. */
-  const onSchemeChange = (key: string) => (e: Event) => {
-    const scheme = (e.target as HTMLInputElement).value;
-    void persistMedia({ ...media, [key]: `(prefers-color-scheme: ${scheme})` }, key);
+/** The whole section, as one value the document can be handed. */
+function project(container: HTMLElement): ContextsView {
+  const shown = errors.get(container);
+  const { base, entries } = splitContexts(currentMedia());
+  const groups: ContextGroupView[] = GROUPS.map((spec) => {
+    const rows = entries
+      .filter((entry) => entry.kind === spec.kind)
+      .map((entry) => rowView(entry, shown));
+    return {
+      addLabel: spec.addLabel,
+      desc: spec.desc,
+      empty: spec.empty,
+      hasRows: rows.length > 0,
+      kind: spec.kind,
+      label: spec.label,
+      rows,
+    };
+  });
+  return {
+    base,
+    baseError: shown?.target === "base" ? shown.message : "",
+    baseInvalid: shown?.target === "base",
+    groups,
+    notice: noticeOf(inheritedErrors.get(container) ?? []),
+    queryPlaceholder: NEW_BREAKPOINT_QUERY,
+    sectionError: shown?.target === "section" ? shown.message : "",
   };
+}
 
-  // ─── Group templates ───────────────────────────────────────────────────────
-
-  const removeButton = (key: string) => html`
-    <sp-action-button
-      size="s"
-      quiet
-      data-remove=${key}
-      title="Remove ${mediaDisplayName(key)}"
-      @click=${onRemove(key)}
-    >
-      ×
-    </sp-action-button>
-  `;
-
-  const nameField = (key: string) => html`
-    <sp-textfield
-      size="s"
-      class="settings-media-name"
-      .value=${live(key.replace(/^--/, ""))}
-      placeholder="name"
-      ?invalid=${shown?.target === key}
-      @change=${onRename(key)}
-    ></sp-textfield>
-  `;
-
-  const queryRow = (entry: ContextEntry) => html`
-    <div class="settings-media-row" data-context=${entry.key}>
-      ${nameField(entry.key)}
-      <sp-textfield
-        size="s"
-        class="settings-media-value"
-        .value=${live(entry.query)}
-        placeholder=${NEW_BREAKPOINT_QUERY}
-        ?invalid=${shown?.target === entry.key}
-        @change=${onQueryChange(entry.key)}
-      ></sp-textfield>
-      ${removeButton(entry.key)}
-    </div>
-    ${errorFor(entry.key)}
-  `;
-
-  const schemeRow = (entry: ContextEntry) => html`
-    <div class="settings-media-row" data-context=${entry.key}>
-      ${nameField(entry.key)}
-      <sp-picker
-        size="s"
-        class="settings-media-value"
-        label="Scheme"
-        .value=${schemeOfQuery(entry.query) ?? "dark"}
-        @change=${onSchemeChange(entry.key)}
-      >
-        <sp-menu-item value="light">Light</sp-menu-item>
-        <sp-menu-item value="dark">Dark</sp-menu-item>
-      </sp-picker>
-      ${removeButton(entry.key)}
-    </div>
-    ${errorFor(entry.key)}
-  `;
-
-  const group = (
-    kind: ContextKind,
-    label: string,
-    desc: string,
-    row: (entry: ContextEntry) => unknown,
-    addLabel: string,
-    onAdd: () => void,
-    empty: string,
-  ) => {
-    const rows = entries.filter((entry) => entry.kind === kind);
-    return html`
-      <div class="settings-field" data-context-group=${kind}>
-        <label class="settings-field-label">${label}</label>
-        <p class="settings-field-desc">${desc}</p>
-        <div class="settings-media-list">
-          ${
-            rows.length === 0
-              ? html`<p class="settings-field-desc">${empty}</p>`
-              : rows.map((entry) => row(entry))
-          }
-        </div>
-        <sp-action-button size="s" data-add=${kind} @click=${onAdd}>${addLabel}</sp-action-button>
-      </div>
-    `;
-  };
+// ─── Render ───────────────────────────────────────────────────────────────────
 
-  const tpl = html`
-    <div class="settings-section">
-      <h3 class="settings-section-title">Contexts</h3>
-      <p class="settings-field-desc">
-        The conditions this project's pages are rendered under. Define them once here; choose
-        between them on the pane's context control while you edit.
-      </p>
-      ${errorFor("section")} ${inheritedNotice()}
-
-      <div class="settings-field">
-        <label class="settings-field-label">Base width</label>
-        <p class="settings-field-desc">
-          How wide the canvas is when no other context applies. Styles written here apply
-          everywhere.
-        </p>
-        <div class="settings-media-row">
-          <span class="settings-media-name-fixed">Base</span>
-          <sp-textfield
-            size="s"
-            class="settings-media-value"
-            data-context="base"
-            placeholder="1280px"
-            .value=${live(base)}
-            ?invalid=${shown?.target === "base"}
-            @change=${onBaseChange}
-          ></sp-textfield>
-        </div>
-        ${errorFor("base")}
-      </div>
-
-      ${group(
-        "size",
-        "Size breakpoints",
-        "Screen widths that get their own canvas and their own style values.",
-        queryRow,
-        "+ Add breakpoint",
-        add("breakpoint", NEW_BREAKPOINT_QUERY),
-        "No breakpoints yet — every width uses the base styles.",
-      )}
-      ${group(
-        "scheme",
-        "Colour schemes",
-        "Light and dark renderings. Defining one turns on the Auto / Light / Dark control.",
-        schemeRow,
-        "+ Add colour scheme",
-        add("dark", "(prefers-color-scheme: dark)"),
-        "No colour schemes yet — the project renders one way.",
-      )}
-      ${group(
-        "feature",
-        "Feature queries",
-        "Anything else a media query can ask: reduced motion, print, hover, orientation.",
-        queryRow,
-        "+ Add feature query",
-        add("feature", NEW_FEATURE_QUERY),
-        "No feature queries yet.",
-      )}
-    </div>
-  `;
-
-  litRender(tpl, container);
+/**
+ * Render Project Settings › Contexts into `container`.
+ *
+ * One mount per container, re-used for every subsequent call. The host calls this again for any
+ * change it notices, and a section whose container has meanwhile been given to a DIFFERENT section
+ * finds its document gone — `litRender` into the same node replaces everything in it — so the mount
+ * is rebuilt exactly when it has actually been evicted, and disposed on the way out rather than
+ * left running over detached nodes.
+ *
+ * @param {HTMLElement} container
+ */
+export function renderContextsSection(container: HTMLElement): void {
+  let handle = mounts.get(container);
+  if (!handle?.attached()) {
+    handle?.dispose();
+    handle = mountContextsSurface(container, actionsFor(container));
+    mounts.set(container, handle);
+  }
+  handle.update(project(container));
 }