@jxsuite/studio 6.1.1 → 8.0.0

package/src/settings/project-sections.ts

@@ -1,6 +1,6 @@
 /// <reference lib="dom" />
 /**
- * The two Project Settings sections the document adds directly — Deploy and Raw JSON.
+ * Two direct views of `project.json`: Deploy (the build adapter) and Raw JSON (the file itself).
  *
  * They live together because each is a small, direct view of ONE `project.json` key and neither
  * owns a dialog, a picker or a schema form: `build.adapter` (one enum), and the file itself.
@@ -12,8 +12,11 @@
  * error plumbing both still share.
  *
  * **Raw JSON does not open a second editor.** It shows what is on disk and hands the author to the
- * Code editor over the SAME tab — one document, three editors (§17.1), so switching to the text and
- * back keeps one undo stack instead of forking two.
+ * Code editor over the `project.json` tab (§17.1): the host says how, through `editAsCode`, because
+ * the section sits in the settings dialog and the tab it opens is the Styles workspace's.
+ *
+ * **Deploy is no longer a Project Settings section.** Hosting moved to the Publish workspace
+ * (§17.1's Moved footnote), which hosts `renderDeploySection`; the renderer is unchanged.
  *
  * **The markup left.** Each section is a Jx document over the kit — `surfaces/settings-deploy.json`
  * and `surfaces/settings-rawjson.json`, mounted by the adapters beside them — and what is here is
@@ -29,9 +32,8 @@
  */
 
 import { errorMessage } from "@jxsuite/schema/parse";
-import { projectState, updateUi } from "../store";
+import { projectState } from "../store";
 import { serializeProjectConfig } from "../tabs/project-config";
-import { tabOfContainer } from "../canvas/canvas-surface";
 import { updateSiteConfig } from "../site-context";
 import { mountDeploySurface } from "../surfaces/settings-deploy";
 import { mountRawJsonSurface } from "../surfaces/settings-rawjson";
@@ -40,9 +42,6 @@ import type { DeployActions, DeploySurfaceHandle, DeployValues } from "../surfac
 import type { RawJsonSurfaceHandle, RawJsonValues } from "../surfaces/settings-rawjson";
 import type { ProjectConfig } from "@jxsuite/schema/types";
 
-/** The mode the Code editor draws under — `tabs/tab.ts`'s `EDITOR_KIND_BY_MODE` maps it to `code`. */
-const CODE_MODE = "source";
-
 /**
  * The last failed write per rendered section container.
  *
@@ -54,7 +53,7 @@ const errors = new WeakMap<HTMLElement, string>();
 
 /** The live project configuration, or an empty one before a project is open. */
 function config(): ProjectConfig {
-  return (projectState?.projectConfig ?? {}) as ProjectConfig;
+  return projectState?.projectConfig ?? {};
 }
 
 // ─── Deploy ───────────────────────────────────────────────────────────────────
@@ -151,6 +150,17 @@ export function renderDeploySection(container: HTMLElement): void {
   );
 }
 
+/**
+ * Take the Deploy section out of a container its host is leaving (Publish › Hosting, when its pane
+ * is torn down). Idempotent.
+ *
+ * @param {HTMLElement} container
+ */
+export function disposeDeploySection(container: HTMLElement): void {
+  deployMounts.get(container)?.dispose();
+  deployMounts.delete(container);
+}
+
 // ─── Raw JSON ─────────────────────────────────────────────────────────────────
 
 /** The surface mounted in each Raw JSON container. */
@@ -166,12 +176,19 @@ function rawJsonValues(): RawJsonValues {
   return { json: serializeProjectConfig(config()) };
 }
 
+/** What the Raw JSON section asks its host to do. */
+export interface RawJsonSectionActions {
+  /** Open `project.json` in the Code editor, leaving wherever the section is drawn. */
+  editAsCode: () => void;
+}
+
 /**
  * `project.json` as it is written, and the way into editing it as text.
  *
  * @param {HTMLElement} container
+ * @param {RawJsonSectionActions} actions
  */
-export function renderRawJsonSection(container: HTMLElement): void {
+export function renderRawJsonSection(container: HTMLElement, actions: RawJsonSectionActions): void {
   const standing = rawJsonMounts.get(container);
   if (standing?.connected()) {
     standing.update(rawJsonValues());
@@ -181,7 +198,7 @@ export function renderRawJsonSection(container: HTMLElement): void {
   rawJsonMounts.set(
     container,
     mountRawJsonSurface(container, rawJsonValues(), {
-      editAsCode: () => updateUi(tabOfContainer(container), "canvasMode", CODE_MODE),
+      editAsCode: actions.editAsCode,
     }),
   );
 }

package/src/settings/schema-field-ui.ts

@@ -12,6 +12,7 @@
  */
 
 import { isMediaFormat } from "../utils/studio-utils";
+import { localDay } from "../utils/local-day";
 
 export interface SchemaProperty {
   type?: string;
@@ -26,6 +27,15 @@ export const FIELD_TYPES = ["string", "number", "boolean", "array", "object", "r
 
 export const FORMAT_OPTIONS = ["", "image", "date", "color"];
 
+/** What a new field's add row starts as. Spread it: every add row edits its own copy. */
+export const BLANK_FIELD = { format: "", name: "", required: false, type: "string" };
+
+/** One object field's unsubmitted nested field. */
+export interface NestedFieldDraft {
+  name: string;
+  type: string;
+}
+
 /**
  * Detect the studio field type from a JSON Schema property definition.
  *
@@ -93,7 +103,8 @@ export function schemaForType(type: string, format?: string) {
  */
 export function yamlDefault(type: string, format?: string) {
   if (format === "date") {
-    return new Date().toISOString().split("T")[0];
+    // Today where the author is: a UTC "today" is tomorrow every evening west of Greenwich.
+    return localDay(new Date());
   }
   if (isMediaFormat(format)) {
     return '""';

package/src/settings/section-registry.ts

@@ -3,15 +3,16 @@
  *
  * `registerSettingsSection` is a **preserved public contract** (specs/extensions.md §9.1): an
  * extension's `project` class declares a `$studio.settings` block and `settings/extension-sections`
- * turns it into one of these records. Project Settings moved out of a modal and into a document in
- * the pane (§17.1); the registry did not move with it, because a section is a contribution to
- * CONFIGURATION, not to a dialog. Splitting it out is what lets the host be replaced without the
- * contribution point being touched.
+ * turns it into one of these records. Project Settings has moved host twice — a modal, then a
+ * document in the pane, and now a dialog again (§17.1) — and the registry moved with neither,
+ * because a section is a contribution to CONFIGURATION, not to whatever draws it. Splitting it out
+ * is what lets the host be replaced without the contribution point being touched.
  *
- * **This module holds no renderer and imports nothing.** That is load-bearing rather than tidy:
- * `panels/settings-pane.ts` is reached from `canvas/canvas-render.ts`, so anything this module
- * imports becomes part of the canvas's import graph. The section RENDERERS are registered by
- * `settings/settings-document.ts`, which the app loads when it registers its commands.
+ * **This module holds no renderer and imports nothing.** That is load-bearing rather than tidy: the
+ * gear menu (`panels/settings-menu.ts`) enumerates these sections from the top bar, so anything
+ * this module imports becomes part of the chrome's import graph. The section RENDERERS are
+ * registered by `settings/settings-document.ts`, which the app loads when it registers its
+ * commands.
  *
  * **What is requested and what is displayed are two variables, and unregistering touches neither.**
  * The modal had one, and its `unregisterSettingsSection` reset it to `"general"` — which is half of
@@ -22,10 +23,57 @@
  * the key comes back.
  */
 
+/**
+ * The three groups the Project Settings nav is drawn in (§17.1), in display order.
+ *
+ * - **General** is what every author sets: the site's name, address and icon, and its languages.
+ * - **Integrations** is what an extension adds, and so where every contributed section lands unless
+ *   it says otherwise (`specs/extensions.md` §9.1, `group`).
+ * - **Advanced** is the project's machinery, marked "For developers": rendering contexts, the site
+ *   head, data shapes, packages and the raw file.
+ *
+ * `intro` is the sentence the body opens with while a section of that group is showing: what the
+ * group is FOR, so the reader learns that Advanced is the risky one from a sentence rather than
+ * from a two-word qualifier. General's sections need no preamble, so it has none.
+ */
+export const SETTINGS_GROUPS = [
+  { id: "general", intro: "", label: "General", note: "" },
+  {
+    id: "integrations",
+    intro: "Turn on what your site needs. Each one adds its own options where you use it.",
+    label: "Integrations",
+    note: "",
+  },
+  {
+    id: "advanced",
+    intro: "Changes here affect every page. Most sites never need them.",
+    label: "Advanced",
+    note: "For developers",
+  },
+] as const;
+
+/** A settings group's id. */
+export type SettingsGroupId = (typeof SETTINGS_GROUPS)[number]["id"];
+
+/** Where a section with no `group` is listed: the extension default `extensions.md` §9.1 names. */
+export const DEFAULT_SETTINGS_GROUP: SettingsGroupId = "integrations";
+
+/**
+ * Whether a value names one of {@link SETTINGS_GROUPS}.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isSettingsGroupId(value: unknown): value is SettingsGroupId {
+  return SETTINGS_GROUPS.some((group) => group.id === value);
+}
+
 /** A Project Settings section: an inner-nav entry plus a renderer for the content area. */
 export interface SettingsSection {
   key: string;
   label: string;
+  /** Which nav group lists the section. Absent means {@link DEFAULT_SETTINGS_GROUP}. */
+  group?: SettingsGroupId | undefined;
   /**
    * Nav icon name (reserved for future nav treatments).
    *
@@ -37,7 +85,20 @@ export interface SettingsSection {
   icon?: string | undefined;
   /** Sort position — lower orders render higher in the inner nav. */
   order: number;
-  render: (container: HTMLElement) => void;
+  /**
+   * The sentence the body opens with while THIS section shows, in place of its group's `intro`.
+   *
+   * A group's sentence says what the group is for, and a section that is not that (Content Types is
+   * a list of the project's collections, not something to turn on) says what it is instead. Absent
+   * or empty, the group's sentence stands.
+   */
+  intro?: string | undefined;
+  /**
+   * Draw the section into `container`. A renderer that returns a promise is awaited, so a section
+   * whose first paint needs IO fails where the reader is looking: a rejection, like a throw, is
+   * shown in the body in place of the section (`panels/settings-pane.ts`).
+   */
+  render: (container: HTMLElement) => void | Promise<void>;
 }
 
 /** Where a settings document lands when nobody named a section. */
@@ -110,9 +171,53 @@ export function sortedSettingsSections(): SettingsSection[] {
   return [...sections.values()].toSorted((a, b) => a.order - b.order);
 }
 
-/** Every registered section key, built-ins and contributions alike, in display order. */
+/** One nav group and the sections listed under it. */
+export interface SettingsSectionGroup {
+  id: SettingsGroupId;
+  label: string;
+  /** A qualifier drawn beside the label ("For developers"), or the empty string. */
+  note: string;
+  /** What the body opens with while one of this group's sections shows, or the empty string. */
+  intro: string;
+  sections: SettingsSection[];
+}
+
+/**
+ * The registered sections in their nav groups: groups in {@link SETTINGS_GROUPS} order, sections in
+ * `order` within each. A group with no section is left out, so an empty heading is never drawn.
+ *
+ * @returns {SettingsSectionGroup[]}
+ */
+export function groupedSettingsSections(): SettingsSectionGroup[] {
+  const sorted = sortedSettingsSections();
+  return SETTINGS_GROUPS.flatMap((group) => {
+    const listed = sorted.filter(
+      (section) => (section.group ?? DEFAULT_SETTINGS_GROUP) === group.id,
+    );
+    return listed.length === 0
+      ? []
+      : [
+          {
+            id: group.id,
+            intro: group.intro,
+            label: group.label,
+            note: group.note,
+            sections: listed,
+          },
+        ];
+  });
+}
+
+/**
+ * Every registered section key, built-ins and contributions alike, in display order.
+ *
+ * Display order is the GROUPED order (General, then Integrations, then Advanced), so the gear's
+ * submenu and a refusal naming the registered keys list them as the reader sees them.
+ *
+ * @returns {string[]}
+ */
 export function settingsSectionKeys(): string[] {
-  return sortedSettingsSections().map((section) => section.key);
+  return groupedSettingsSections().flatMap((group) => group.sections.map((section) => section.key));
 }
 
 /**

package/src/settings/settings-dialog.ts

@@ -0,0 +1,192 @@
+/// <reference lib="dom" />
+/**
+ * Project Settings as a dialog (§17.1): the flow that opens it, mounts the settings editor into it,
+ * and takes both down.
+ *
+ * Project Settings was a document in the pane, the `project.json` tab under a `settings` editor
+ * mode. The five workspaces made that the wrong home: a tab belongs to exactly one workspace, and
+ * configuration belongs to all of them, so a settings TAB either pulled the author out of the
+ * workspace they were in or had to be special-cased in every one. A dialog is reachable from every
+ * workspace and leaves the one underneath where it was. What made the old modal a problem (a form
+ * that hid the canvas it was tuning) left with the design tokens, which are the Styles workspace's
+ * now; every section still here writes `project.json` as it is edited, through the one chokepoint
+ * (`tabs/project-config.ts`), so the dialog has nothing to confirm and its one answer is Close.
+ *
+ * **Which section shows is the registry's, not this module's.** `settings/section-registry.ts`
+ * holds the requested and the displayed section and outlives the dialog, which is what makes the
+ * dialog reopen where the author left it for the rest of the session.
+ *
+ * Modality, Escape and focus restoration are the platform's: a `jx-dialog` in the dialog layer,
+ * opened with `showModal()`, which puts focus back on whatever opened it when it closes.
+ *
+ * **The frame and the editor are built once per session** and kept, closed, in the dialog layer. A
+ * close suspends the editor (it stops following the section registry) and closes the platform's
+ * dialog; an open resumes it, which redraws the current section, and shows the same dialog again.
+ * Rebuilding both on every open was most of what opening Settings cost, and disposing them inside
+ * the dialog's own `cancel` handler removed a subtree that still held focus from the top layer,
+ * which the browser re-styled on the way out. {@link disposeSettingsDialog} is the teardown, and a
+ * frame whose layer was replaced under it is rebuilt rather than shown.
+ *
+ * @docs studio/projects/settings
+ */
+
+import { activeRegistry } from "../commands/active-registry";
+import { runActiveReported } from "../commands/run-reported";
+import { mountSettingsPane } from "../panels/settings-pane";
+import { openSettingsDialogSurface } from "../surfaces/settings-dialog";
+import { layerHost } from "../ui/layers";
+import type { SettingsPaneMount } from "../panels/settings-pane";
+import type { SettingsDialogHandle } from "../surfaces/settings-dialog";
+import type { InspectorTabId } from "../shell";
+import type { WorkspaceId } from "../workspace/workspace-ids";
+import type { StylesView } from "../style/project-styles";
+import type { PublishTab } from "../publish/publish-ids";
+
+/** The frame, built on the first open and kept across closes; `null` before then. */
+interface SettingsFrame {
+  dialog: SettingsDialogHandle;
+  /** The editor in the frame's body, once the body has been created. */
+  pane: SettingsPaneMount | null;
+}
+
+let _frame: SettingsFrame | null = null;
+
+/** Whether the dialog is asked to be up: true from an open until the close that ends it. */
+let _open = false;
+
+/** {@link _open}, read through a call so a check after an `await` is not narrowed to before it. */
+function isOpen(): boolean {
+  return _open;
+}
+
+/** Build the frame (it opens itself once mounted). */
+function buildFrame(): SettingsFrame {
+  const frame: SettingsFrame = {
+    dialog: openSettingsDialogSurface({
+      body: (host) => {
+        frame.pane = mountSettingsPane(host, {
+          openMoved: (workspace, inspector, view, publishTab) => {
+            void openMoved(workspace, inspector, view, publishTab);
+          },
+        });
+      },
+      /* Escape or Close: the platform closed the dialog, so the flow follows. `close()` is
+         idempotent, so the flow's own close running first is fine. */
+      closed: () => {
+        if (_frame === frame) {
+          closeSettingsDialog();
+        }
+      },
+      layer: layerHost("dialog"),
+    }),
+    pane: null,
+  };
+  return frame;
+}
+
+/**
+ * Leave Settings for the workspace something moved to: the Moved footnote's buttons.
+ *
+ * Closed FIRST, so the workspace the author asked for is what they see and focus returns to the
+ * frame rather than to a row that is going away. A refusal (the switch is gated on an open project)
+ * is filed in Problems under this surface's name instead of being dropped.
+ *
+ * A row that names an Inspector tab ("Head and SEO defaults → Page tab") also shows the Inspector
+ * on that tab, AFTER the switch, because entering a workspace applies its frame preset and would
+ * otherwise put the dock back as the preset has it. The tab is a document-level view, so with no
+ * document open there is no tab to show and asking would only file a refusal; the dock is still
+ * opened, which is where the tab appears once one is.
+ *
+ * A row that names a Styles view ("Colors and fonts → Styles › Variables") runs `styles.open` with
+ * that view instead, which is the same workspace switch followed by the view.
+ *
+ * @param {WorkspaceId} workspace
+ * @param {InspectorTabId} [inspector]
+ * @param {StylesView} [view]
+ * @returns {Promise<void>} Settles once every command the row runs has settled
+ */
+async function openMoved(
+  workspace: WorkspaceId,
+  inspector?: InspectorTabId,
+  view?: StylesView,
+  publishTab?: PublishTab,
+): Promise<void> {
+  closeSettingsDialog();
+  if (view !== undefined) {
+    await runActiveReported("styles.open", { view }, "Settings");
+    return;
+  }
+  // Hosting is a Publish sub-tab, not the workspace's first: the button says where it lands.
+  if (publishTab !== undefined) {
+    await runActiveReported("publish.open", { tab: publishTab }, "Settings");
+    return;
+  }
+  await runActiveReported("view.setWorkspace", { workspace }, "Settings");
+  if (inspector === undefined) {
+    return;
+  }
+  await runActiveReported("view.setRightPanel", { open: true }, "Settings");
+  if (activeRegistry()?.isEnabled("view.setRightTab") === true) {
+    await runActiveReported("view.setRightTab", { tab: inspector }, "Settings");
+  }
+}
+
+/**
+ * Open Project Settings, or leave it up when it already is.
+ *
+ * Re-opening while it is up does not stack a second dialog: the section the caller asked for has
+ * already been written to the registry, which redraws the editor that is showing.
+ *
+ * @returns {Promise<void>} Settles once the dialog is showing and the current section's row holds
+ *   the keyboard
+ */
+export async function openSettingsDialog(): Promise<void> {
+  if (_open && _frame) {
+    await _frame.dialog.ready;
+    return;
+  }
+  _open = true;
+  // A frame whose layer went away (a shell remount) is dead weight, not something to show.
+  if (_frame && !_frame.dialog.host.isConnected) {
+    disposeSettingsDialog();
+    _open = true;
+  }
+  let frame = _frame;
+  if (frame) {
+    frame.pane?.resume();
+    await frame.dialog.show();
+  } else {
+    frame = buildFrame();
+    _frame = frame;
+    await frame.dialog.ready;
+  }
+  /* Read after the wait, from the frame: the body is created while the dialog mounts, and a close
+     in between leaves the editor built but not to be focused. */
+  const mounted = frame.pane;
+  if (mounted === null || _frame !== frame || !isOpen()) {
+    return;
+  }
+  await mounted.ready;
+  if (_frame === frame && isOpen()) {
+    mounted.focusActive();
+  }
+}
+
+/** Close Project Settings if it is open. Idempotent. The frame stays built for the next open. */
+export function closeSettingsDialog(): void {
+  if (!_open) {
+    return;
+  }
+  _open = false;
+  _frame?.pane?.suspend();
+  _frame?.dialog.close();
+}
+
+/** Close Project Settings and take its frame and editor down. Idempotent. */
+export function disposeSettingsDialog(): void {
+  _open = false;
+  const frame = _frame;
+  _frame = null;
+  frame?.pane?.dispose();
+  frame?.dialog.dispose();
+}