@jxsuite/studio 4.1.0 → 5.1.0

package/src/settings/extension-rows.ts

@@ -0,0 +1,113 @@
+/// <reference lib="dom" />
+/**
+ * The Extensions row model — what this project could turn on, what it has, and what is on.
+ *
+ * Its own module because BOTH the section that renders the rows and the commands that act on them
+ * need it, and one shared definition is what keeps "what the switch shows" and "what the verb
+ * refuses" a single answer. It is also what stops the two forming an import cycle.
+ *
+ * Three sources, and the split is the point: the catalogue says what is OFFERED, the package list
+ * says what is HERE, and `project.json` says what is ON. None can answer for the others, which is
+ * why the row carries all three rather than a single "state".
+ */
+
+import { getExtensionCatalog, getExtensions } from "../format/format-host";
+import { projectState } from "../store";
+import type { PackageInfo } from "../types";
+import type { ProjectConfig } from "@jxsuite/schema/types";
+
+/** Where a row came from — decides its group heading and whether Remove is offered. */
+export type ExtensionOrigin = "catalog" | "installed" | "configured";
+
+/** One rendered row: an offer, its state in this project, and why it may not be actionable. */
+export interface ExtensionRow {
+  /** Package name — the row key, and what addPackage/removePackage take. */
+  name: string;
+  /** The string that is (or would be) in `project.json` `extensions[]`. */
+  specifier: string;
+  title: string;
+  description?: string | undefined;
+  /** `project.json` keys this extension owns. */
+  sections: string[];
+  origin: ExtensionOrigin;
+  enabled: boolean;
+  installed: boolean;
+  /** The host resolves it without a project install, so enabling is a config write alone. */
+  bundled: boolean;
+  /** Why this backend cannot run it, as one sentence. Absent means it can. */
+  unavailable?: string | undefined;
+  /** Enabled but not installed — the state that fails the next build. */
+  broken: boolean;
+}
+
+/** The live project configuration, or an empty one before a project is open. */
+export function projectConfig(): ProjectConfig {
+  return (projectState?.projectConfig ?? {}) as ProjectConfig;
+}
+
+/** The specifiers `project.json` currently enables. */
+export function enabledSpecifiers(): string[] {
+  return projectConfig().extensions ?? [];
+}
+
+/**
+ * Compose the rows.
+ *
+ * `sections` for an ENABLED row comes from the extensions payload, because the backend resolved
+ * that one for real; for an offer it comes from the catalogue, which is the only source that can
+ * describe a package the project has not installed yet.
+ *
+ * @param {PackageInfo[] | null} packages - The project's dependencies, when they have been read
+ * @returns {ExtensionRow[]}
+ */
+export function buildRows(packages: PackageInfo[] | null = null): ExtensionRow[] {
+  const enabled = new Set(enabledSpecifiers());
+  const installed = new Set((packages ?? []).map((p) => p.name));
+  const resolved = new Map(getExtensions().map((e) => [e.name, e]));
+  const rows: ExtensionRow[] = [];
+
+  for (const entry of getExtensionCatalog()) {
+    const specifier = entry.specifier ?? entry.name;
+    const here = entry.installed ?? installed.has(entry.name);
+    const bundled = entry.bundled ?? false;
+    const info = resolved.get(entry.name);
+    rows.push({
+      broken: enabled.has(specifier) && !here && !bundled,
+      bundled,
+      enabled: enabled.has(specifier),
+      installed: here,
+      name: entry.name,
+      origin: entry.source === "first-party" ? "catalog" : "installed",
+      sections: info
+        ? info.contributions.map((c) => c.project.key)
+        : entry.sections.map((s) => s.key),
+      specifier,
+      title: entry.title ?? entry.name,
+      ...(entry.description === undefined ? {} : { description: entry.description }),
+      ...(entry.problem === undefined ? {} : { unavailable: entry.problem }),
+    });
+  }
+
+  // Anything project.json names that the backend did not describe. It can still be turned OFF,
+  // Which is what matters most for exactly the rows nothing can explain.
+  for (const specifier of enabled) {
+    if (rows.some((row) => row.specifier === specifier)) {
+      continue;
+    }
+    const info = resolved.get(specifier);
+    rows.push({
+      broken: !installed.has(specifier) && info === undefined,
+      bundled: false,
+      enabled: true,
+      installed: installed.has(specifier),
+      name: specifier,
+      origin: "configured",
+      sections: info ? info.contributions.map((c) => c.project.key) : [],
+      specifier,
+      title: info?.title ?? specifier,
+      ...(info?.description === undefined ? {} : { description: info.description }),
+    });
+  }
+
+  return rows;
+}

package/src/settings/extensions-section.ts

@@ -0,0 +1,287 @@
+/// <reference lib="dom" />
+/**
+ * The Extensions section of Project Settings — what this project can turn on, and what it has.
+ *
+ * **The section exists because enabling an extension is two writes, and nothing kept them
+ * together.** A project names an extension in `project.json` `extensions[]`, and the package has to
+ * be a dependency for the registry to resolve it. The section this replaces wrote only the first,
+ * so typing a name that was not installed appended a string and the next build threw `Extension "…"
+ * is not resolvable`. A toggle here does both halves, in the one order that cannot leave the
+ * project broken (see `enableExtension`).
+ *
+ * **What is offered comes from the backend, not from a list here.** Not every host can run every
+ * extension — a Worker ships a fixed set of packages (specs/extensions.md §5.5) — so the catalogue
+ * is a platform capability, and a host that cannot answer simply offers nothing. That is also why
+ * there is no `@jxsuite/` prefix test below: which extensions are first-party is the backend's
+ * answer, and a second definition of it here would be wrong for a fork.
+ *
+ * **The markup left.** The section is the `settings-extensions` surface
+ * (`surfaces/settings-extensions.json`), mounted by `surfaces/settings-extensions.ts`; what is here
+ * is what was always this module's — what the three sources add up to, which sentence a row's state
+ * deserves, why a control cannot be used, and what a failed operation says.
+ * `renderExtensionsSection` is unchanged as a contract: the registry hands a container to a
+ * `render`, and this one mounts a document into it instead of rendering lit.
+ *
+ * @docs studio/projects/settings
+ */
+
+import { errorMessage } from "@jxsuite/schema/parse";
+import { buildRows } from "./extension-rows";
+import { getPlatform } from "../platform";
+import {
+  disableExtension,
+  enableExtension,
+  extensionOpInFlight,
+  removeExtensionPackage,
+} from "./extension-commands";
+import { mountExtensionsSurface } from "../surfaces/settings-extensions";
+import type { ExtensionOrigin, ExtensionRow } from "./extension-rows";
+import type {
+  ExtensionGroupView,
+  ExtensionRowView,
+  ExtensionsActions,
+  ExtensionsSurfaceHandle,
+  ExtensionsView,
+} from "../surfaces/settings-extensions";
+import type { PackageInfo } from "../types";
+
+/** Group headings, in render order, each with the sentence that says what the group is. */
+const GROUPS: { origin: ExtensionOrigin; label: string; blurb: string }[] = [
+  {
+    blurb:
+      "Extensions this project can turn on. Enabling one installs its package first if it is missing.",
+    label: "Available",
+    origin: "catalog",
+  },
+  {
+    blurb: "Extension packages already in this project's dependencies.",
+    label: "Installed",
+    origin: "installed",
+  },
+  {
+    blurb:
+      "Named in project.json, but this backend does not describe them. You can still turn them off.",
+    label: "Named in project.json",
+    origin: "configured",
+  },
+];
+
+/**
+ * The project's dependencies, re-read whenever an operation may have changed them.
+ *
+ * Module-level rather than per container, because it is a fact about the PROJECT: two panes showing
+ * this section are not looking at two dependency lists.
+ */
+let _packages: PackageInfo[] | null = null;
+
+/** The surface mounted in each container, so a redraw updates one rather than making another. */
+const mounted = new WeakMap<HTMLElement, ExtensionsSurfaceHandle>();
+
+/**
+ * The last failed operation, per rendered section, shown under the section title.
+ *
+ * Keyed by container, the shape `general-settings.ts` and `locales-section.ts` use, and for the
+ * reason they use it: a message belongs to the copy of the section the reader was looking at when
+ * the operation failed. It is cleared when the next operation starts and when one succeeds, and a
+ * section the reader navigated away from and back is drawn into a fresh host
+ * (`panels/settings-pane.ts`), so it starts with nothing to say rather than with a stale
+ * complaint.
+ */
+const errors = new WeakMap<HTMLElement, string>();
+
+/** The sentence a row's state deserves, and the tone it is said in. */
+function noteFor(row: ExtensionRow): { note: string; noteTone: ExtensionRowView["noteTone"] } {
+  if (row.unavailable !== undefined) {
+    return { note: row.unavailable, noteTone: "warn" };
+  }
+  if (row.broken) {
+    return {
+      note:
+        `${row.name} is named in project.json but is not installed, so the next build will fail. ` +
+        `Turn it off, or turn it off and on again to install it.`,
+      noteTone: "warn",
+    };
+  }
+  if (!row.installed && !row.bundled) {
+    return { note: "Not installed. Turning this on installs it first.", noteTone: "note" };
+  }
+  if (row.bundled) {
+    return { note: "Ships with this backend, so it needs no install.", noteTone: "note" };
+  }
+  return { note: "", noteTone: "none" };
+}
+
+/** Why a row's toggle cannot be used right now, or `""` when it can. */
+function blockedReason(row: ExtensionRow): string {
+  // Turning something OFF is always safe, even on a backend that cannot run it — otherwise a row
+  // That arrived unsupported could never be removed from the project that names it.
+  if (row.unavailable !== undefined && !row.enabled) {
+    return row.unavailable;
+  }
+  const busy = extensionOpInFlight();
+  return busy === null ? "" : `Waiting for ${busy} to finish.`;
+}
+
+/**
+ * The per-row Remove, as the document reads it.
+ *
+ * Refused while the extension is still enabled, and DISABLED with the reason rather than hidden
+ * (guidelines §10): removing the package while `project.json` still names it manufactures exactly
+ * the broken state this section exists to eliminate. It is absent only when there is nothing to
+ * remove — a package the project never installed, or one the backend bundles.
+ */
+function removeFor(
+  row: ExtensionRow,
+): Pick<ExtensionRowView, "canRemove" | "removeDisabled" | "removeHint" | "removeLabel"> {
+  const refusal = row.enabled
+    ? `Turn ${row.title} off first. Removing the package while project.json still names it would fail the next build.`
+    : "";
+  return {
+    canRemove: row.installed && !row.bundled,
+    removeDisabled: refusal !== "" || extensionOpInFlight() !== null,
+    removeHint: refusal === "" ? `Remove ${row.name}` : refusal,
+    removeLabel: `Remove ${row.name}`,
+  };
+}
+
+/** One row, projected. */
+function rowView(row: ExtensionRow): ExtensionRowView {
+  const blocked = blockedReason(row);
+  return {
+    blocked: blocked !== "",
+    blockedReason: blocked,
+    broken: row.broken,
+    description: row.description ?? "",
+    enabled: row.enabled,
+    hasDescription: (row.description ?? "") !== "",
+    hasSections: row.sections.length > 0,
+    name: row.name,
+    sections: row.sections.map((key) => ({ key })),
+    specifier: row.specifier,
+    title: row.title,
+    ...noteFor(row),
+    ...removeFor(row),
+  };
+}
+
+/**
+ * What the section shows right now.
+ *
+ * A group with no rows is left out rather than drawn empty: the three origins are a classification
+ * of what happens to exist, not a set of shelves a project is expected to fill.
+ */
+function view(container: HTMLElement): ExtensionsView {
+  const rows = buildRows(_packages);
+  const groups: ExtensionGroupView[] = [];
+  for (const group of GROUPS) {
+    const matching = rows.filter((row) => row.origin === group.origin);
+    if (matching.length > 0) {
+      groups.push({
+        blurb: group.blurb,
+        label: group.label,
+        origin: group.origin,
+        rows: matching.map((row) => rowView(row)),
+      });
+    }
+  }
+  return { error: errors.get(container) ?? "", groups };
+}
+
+/** Draw the section, or bring the surface already there up to date. */
+function refresh(container: HTMLElement): void {
+  const standing = mounted.get(container);
+  if (standing?.connected()) {
+    standing.update(view(container));
+    return;
+  }
+  standing?.dispose();
+  mounted.set(container, mountExtensionsSurface(container, view(container), actions(container)));
+}
+
+/** Re-read the package list, then repaint. Installed-ness is what a config write cannot move. */
+async function reload(container: HTMLElement): Promise<void> {
+  try {
+    _packages = await getPlatform().listPackages();
+  } catch {
+    _packages = [];
+  }
+  refresh(container);
+}
+
+async function onToggle(
+  container: HTMLElement,
+  specifier: string,
+  checked: boolean,
+): Promise<void> {
+  /* The echo, first and before anything is decided: the scope is made to agree with the switch, so
+     that the projection which follows — the file's answer — is a real move rather than a
+     restatement of a value the scope never left. */
+  mounted.get(container)?.echo(specifier, checked);
+  errors.delete(container);
+  // Intent is the DOCUMENT's truth inverted, never the switch's own `checked` — the browser has
+  // Already moved that by the time this fires, so reading it would compound a double event.
+  const row = buildRows(_packages).find((candidate) => candidate.specifier === specifier);
+  if (row === undefined) {
+    refresh(container);
+    return;
+  }
+  // Started, THEN painted: both operations take the in-flight latch synchronously before their
+  // First await, so this repaint is what disables every other switch for the duration.
+  const op = row.enabled ? disableExtension(row.specifier) : enableExtension(row.specifier);
+  refresh(container);
+  try {
+    await op;
+  } catch (error) {
+    errors.set(container, errorMessage(error));
+  }
+  // Either way the row repaints from `project.json`, so a switch the operation did not earn is put
+  // Back where the document says it belongs.
+  await reload(container);
+}
+
+async function onRemove(container: HTMLElement, name: string): Promise<void> {
+  errors.delete(container);
+  const op = removeExtensionPackage(name);
+  refresh(container);
+  try {
+    await op;
+  } catch (error) {
+    errors.set(container, errorMessage(error));
+  }
+  await reload(container);
+}
+
+/**
+ * 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 pair on every refresh would be a scope write that says
+ * nothing.
+ */
+const bound = new WeakMap<HTMLElement, ExtensionsActions>();
+
+function actions(container: HTMLElement): ExtensionsActions {
+  let acts = bound.get(container);
+  if (!acts) {
+    acts = {
+      remove: (name: string) => {
+        void onRemove(container, name);
+      },
+      toggle: (specifier: string, checked: boolean) => {
+        void onToggle(container, specifier, checked);
+      },
+    };
+    bound.set(container, acts);
+  }
+  return acts;
+}
+
+/**
+ * Render the Extensions section into a settings-document container.
+ *
+ * @param {HTMLElement} container
+ */
+export function renderExtensionsSection(container: HTMLElement): void {
+  refresh(container);
+  void reload(container);
+}