@jxsuite/studio 6.1.2 → 8.0.0

package/src/settings/extension-sections.ts

@@ -8,21 +8,31 @@
  * path.
  */
 
-import { isNonNullObject } from "@jxsuite/schema/guards";
+import { isNonNullObject, isString } from "@jxsuite/schema/guards";
 import { getFormats, loadExtensions, loadFormats } from "../format/format-host";
-import { registerSettingsSection, unregisterSettingsSection } from "./section-registry";
+import {
+  DEFAULT_SETTINGS_GROUP,
+  isSettingsGroupId,
+  registerSettingsSection,
+  unregisterSettingsSection,
+} from "./section-registry";
 import { renderContributedSection } from "./contributed-section";
 import { dataSectionActions } from "../panels/data-grid";
 import type { ExtensionContributionInfo } from "../types";
 import type { JsonSchema } from "../ui/schema-form";
 import type { ContributedSectionOptions, SettingsContribution } from "./contributed-section";
+import type { SettingsGroupId } from "./section-registry";
 
 /** The `$studio.settings` block shape consumed here (nav metadata + the renderer inputs). */
 interface StudioSettingsBlock {
   icon?: string;
   label?: string;
+  /** The nav group: `general`, `integrations` (the default) or `advanced`. */
+  group?: string;
   order?: number;
   layout?: "map" | "form";
+  /** The sentence the section body opens with, in place of its group's (extensions.md §9.1). */
+  intro?: string;
   entry?: SettingsContribution["settings"]["entry"];
 }
 
@@ -30,7 +40,9 @@ interface StudioSettingsBlock {
 export interface DerivedSettingsSection {
   key: string;
   label: string;
+  group: SettingsGroupId;
   icon?: string | undefined;
+  intro?: string | undefined;
   order: number;
   contribution: SettingsContribution;
 }
@@ -85,7 +97,11 @@ export function deriveSettingsSection(
       settings: sectionSettings,
       title: label,
     },
+    /* A group the nav does not draw falls back to the default rather than hiding the section:
+       an extension naming a group from a later vocabulary still gets its section listed. */
+    group: isSettingsGroupId(settings.group) ? settings.group : DEFAULT_SETTINGS_GROUP,
     icon: settings.icon,
+    intro: isString(settings.intro) ? settings.intro : undefined,
     key,
     label,
     order: settings.order ?? DEFAULT_SECTION_ORDER,
@@ -144,7 +160,9 @@ async function runSync(): Promise<void> {
       }
       const { contribution } = derived;
       registerSettingsSection({
+        group: derived.group,
         icon: derived.icon,
+        intro: derived.intro,
         key: derived.key,
         label: derived.label,
         order: derived.order,

package/src/settings/general-settings.ts

@@ -21,8 +21,12 @@ import { errorMessage } from "@jxsuite/schema/parse";
 import { projectState } from "../store";
 import { updateSiteConfig } from "../site-context";
 import { activeRegistry } from "../commands/active-registry";
+import { runActiveReported } from "../commands/run-reported";
+import { closeSettingsDialog } from "./settings-dialog";
 import { getPlatform } from "../platform";
 import { mountOverviewSurface } from "../surfaces/settings-overview";
+import { previewAssetSrcFor } from "../canvas/asset-refs";
+import { PROJECT_CONFIG_PATH } from "../tabs/tab";
 
 import type {
   OverviewActions,
@@ -90,6 +94,65 @@ function headWithDescription(head: JxHeadEntry[], text: string): JxHeadEntry[] {
   );
 }
 
+// ─── Favicon ($head link) ───────────────────────────────────────────────────
+
+/**
+ * True for a `<link>` whose `rel` names the `icon` relation.
+ *
+ * `rel` is a set of space-separated, ASCII case-insensitive tokens (HTML Standard, link types), so
+ * the legacy `rel="shortcut icon"` every favicon snippet still carries is the same relation as
+ * `rel="icon"`. `apple-touch-icon` is a different token and is not the favicon.
+ */
+function isIconLink(entry: JxHeadEntry): boolean {
+  const rel = entry.attributes?.rel;
+  return (
+    entry.tagName === "link" &&
+    isString(rel) &&
+    rel
+      .toLowerCase()
+      .split(/\s+/u)
+      .some((token) => token === "icon")
+  );
+}
+
+/**
+ * The site favicon. Like the description it is not a top-level `project.json` key (the composed
+ * schema is closed, and no compiler stage reads one): it is the `<link rel="icon">` in `$head`,
+ * which is what every starter and `@jxsuite/create` write and what the browser reads
+ * (`site-architecture.md` §2).
+ */
+function readFavicon(cfg: ProjectConfig): string {
+  const href = (cfg.$head ?? []).find((e) => isIconLink(e))?.attributes?.href;
+  return isString(href) ? href : "";
+}
+
+/**
+ * `$head` with the icon link pointing at `href`.
+ *
+ * The existing link is rewritten in place, so its position among the head entries and any other
+ * attribute an author gave it (`sizes`, a media query) survive. `type` is the one attribute that is
+ * dropped: it describes the file being replaced, and a new upload may be a different format.
+ */
+function headWithFavicon(head: JxHeadEntry[], href: string): JxHeadEntry[] {
+  if (!head.some((e) => isIconLink(e))) {
+    return [...head, { attributes: { href, rel: "icon" }, tagName: "link" }];
+  }
+  return head.map((entry) => {
+    if (!isIconLink(entry)) {
+      return entry;
+    }
+    const { type: _type, ...attributes } = entry.attributes ?? {};
+    return { ...entry, attributes: { ...attributes, href } };
+  });
+}
+
+/** The file name an uploaded favicon is stored under: `favicon` plus the upload's own extension. */
+function faviconFileName(file: File): string {
+  const dot = file.name.lastIndexOf(".");
+  const ext = dot > 0 ? file.name.slice(dot + 1).toLowerCase() : "";
+  return /^[a-z0-9]+$/u.test(ext) ? `favicon.${ext}` : "favicon.ico";
+}
+
 /**
  * The patch that _removes_ `url`. `undefined` survives the object spread inside `updateSiteConfig`
  * and `JSON.stringify` then drops the key, so clearing the field clears the setting instead of
@@ -100,31 +163,36 @@ function headWithDescription(head: JxHeadEntry[], text: string): JxHeadEntry[] {
  */
 const CLEAR_URL: ProjectConfigPatch = { url: undefined };
 
+/** The record the Global Styles button is drawn from: **Go to Styles**, the workspace's ⌘4. */
+const STYLES_COMMAND = "workspace.focus.styles";
+
 // ─── Projection ──────────────────────────────────────────────────────────────
 
 /**
  * What the surface should be showing, from the configuration and the registry as they stand now.
  *
- * The Project Styles button is rendered FROM the `styles.open` record, so it is disabled rather
- * than absent when it cannot act (`studio-ui-guidelines.md` §12.3) and it cannot drift from the
- * palette row or the gear menu. The record's TITLE, and nothing else off the registry:
+ * The Global Styles button is rendered FROM the `workspace.focus.styles` record (**Go to Styles**,
+ * ⌘4), whose run is `view.setWorkspace { workspace: "styles" }`, so it is disabled rather than
+ * absent when it cannot act (`studio-ui-guidelines.md` §12.3) and it cannot drift from the palette
+ * row or the switcher's tab. The record's TITLE, and nothing else off the registry:
  * `disabledReason` would be the `studio-ui-guidelines.md` §12.3 shape for a control that can be
- * inapplicable, but this one cannot be — `styles.open` is gated on `ctx.project.open` and Overview
- * is a section of the project's own configuration document, so by the time this renders the answer
- * is always yes. Asking anyway would also be a FOCUS read inside a function that was handed a
- * container, which is what `scripts/check-pane-singletons.ts` rule 4 forbids: a pane-scoped surface
- * must not report the focused pane's state. A project-level verb happens to read the same in every
- * pane, but the way to be right about that is not to ask. The one thing that can genuinely be
- * missing is the registry itself (bootstrap order, a test), and that is an existence check, not a
- * state read.
+ * inapplicable, but this one cannot be — the switch is gated on `ctx.project.open` and Overview is
+ * a section of the project's own configuration, so by the time this renders the answer is always
+ * yes. Asking anyway would also be a FOCUS read inside a function that was handed a container,
+ * which is what `scripts/check-pane-singletons.ts` rule 4 forbids: a pane-scoped surface must not
+ * report the focused pane's state. A project-level verb happens to read the same in every pane, but
+ * the way to be right about that is not to ask. The one thing that can genuinely be missing is the
+ * registry itself (bootstrap order, a test), and that is an existence check, not a state read.
  */
 function values(container: HTMLElement): OverviewValues {
   const cfg = config();
-  const command = activeRegistry()?.get("styles.open");
+  const command = activeRegistry()?.get(STYLES_COMMAND);
   return {
     description: readDescription(cfg),
     error: errors.get(container) ?? null,
-    favicon: isString(cfg.favicon) ? cfg.favicon : "",
+    favicon: readFavicon(cfg),
+    // `project.json` authored it, whatever tab is in front: the section is project-level.
+    faviconSrc: previewAssetSrcFor(readFavicon(cfg), PROJECT_CONFIG_PATH),
     name: cfg.name ?? "",
     stylesDisabled: command === undefined,
     stylesTitle: command?.title ?? "",
@@ -178,29 +246,31 @@ function actions(container: HTMLElement): OverviewActions {
       if (!file) {
         return;
       }
+      // `public/` is copied to the site root verbatim, so `public/favicon.svg` is `/favicon.svg`.
+      const name = faviconFileName(file);
       try {
-        await getPlatform().uploadFile("public/favicon.ico", file);
+        await getPlatform().uploadFile(`public/${name}`, file);
       } catch (error) {
         reject("favicon", `Could not upload the favicon — ${errorMessage(error)}`);
         return;
       }
-      await persist({ favicon: "/favicon.ico" }, "favicon");
+      await persist({ $head: headWithFavicon(config().$head ?? [], `/${name}`) }, "favicon");
     });
     input.click();
   };
 
   return {
     /*
-     * Project Styles is the SAME document in a different editor, and `styles.open` is the one place
-     * that says so. This used to write `session.ui.canvasMode` here directly — a second
+     * Global styles are the Styles workspace's, and the workspace switch is the one place that
+     * says how to get there. This used to write `session.ui.canvasMode` here directly — a second
      * implementation of a capability, `studio-ui-guidelines.md` §12.5's defect in miniature: the
      * button and the command could disagree about what "open Project Styles" means, and only one of
-     * them was reachable by name. The mode is still a fact about the TAB, and there is exactly one
-     * `project.json` tab, so `revealTab`'s `focusPane` puts the keyboard on whichever pane holds
-     * it.
+     * them was reachable by name. Overview is drawn in the settings dialog, so the dialog closes
+     * first: left up, it would cover the workspace the reader just asked for.
      */
     openStyles: () => {
-      void activeRegistry()?.run("styles.open");
+      closeSettingsDialog();
+      void runActiveReported("view.setWorkspace", { workspace: "styles" }, "Settings");
     },
     setDescription: (value: string) => {
       echo({ description: value });

package/src/settings/preferences-dialog.ts

@@ -11,7 +11,8 @@
  * Four sections, and each one closes a hole the shell redesign named:
  *
  * - **Appearance** — the chrome theme. `shell.theme` and `view.setTheme` already existed; nothing
- *   rendered them, so the only way to change the theme was to run a command by hand.
+ *   rendered them, so the only way to change the theme was to run a command by hand. Beside it,
+ *   **Show developer panels**, which puts Files and Packages on the Design rail (§5.1).
  * - **Assistant** — the provider key. It used to live in `Assistant: Settings…`, a dialog reachable
  *   only from inside the assistant panel, which meant a key had to be configured from the surface
  *   that was broken for want of one. That dialog is deleted; this is where it went.
@@ -62,6 +63,7 @@ import {
 } from "./preferences-accounts";
 import { applyKeybindingOverrides, rebindCommand, resetKeybinding } from "./preferences-keymap";
 import { openPreferencesSurface } from "../surfaces/preferences";
+import { developerPanelsShown, setDeveloperPanelsShown } from "./developer-panels";
 
 import type { ShortcutRow } from "../commands/reference";
 import type { RebindResult } from "./preferences-keymap";
@@ -550,6 +552,7 @@ function view(): PreferencesView {
     sectionTitle: active?.title ?? "",
     sections: sectionsView(),
     themes: themesView(),
+    developerPanels: developerPanelsShown(),
     ...(_section === "keyboard" ? keyboardView() : KEYBOARD_IDLE),
   };
 }
@@ -612,6 +615,10 @@ export function openPreferences(section?: string): Promise<null> {
       onResetBinding: resetBinding,
       onSelectSection: selectSection,
       onSetTheme: setTheme,
+      onSetDeveloperPanels: (show: boolean) => {
+        setDeveloperPanelsShown(show);
+        repaint();
+      },
       onShowConflict: showConflict,
       onToggleKeystroke: toggleKeystroke,
       onToggleRebind: toggleRebind,

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.
  *
@@ -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;
@@ -102,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));
 }
 
 /**