@jxsuite/studio 6.1.1 → 8.0.0

package/src/panels/seo-modal.ts

@@ -8,14 +8,14 @@
  * writing. A previewed SERP result is not a field; it is a picture you study, and studying it in a
  * strip above the canvas meant the card grew taller than the thing it describes.
  *
- * So it opens as a modal, from two places — the Document Header card and the Navigator's Page
- * panel. Two doors because the two are different moments: one while writing the page, one while
- * working on its head material. Both run `document.openSeo`, so there is a third door in the
- * palette and no surface owns the capability (one definition site per action, §13).
+ * So it opens as a modal, from the Inspector's Page tab (and, once, from the Document Header card
+ * Edit used to dock above the page, studio.md §4.2). The tab's button runs `document.openSeo`, so
+ * there is a second door in the palette and no surface owns the capability (one definition site per
+ * action, §13).
  *
- * **The card keeps the fields; the modal keeps the picture.** Title still lives on the card,
- * because it is the one head value you type while writing. Everything the modal holds is either a
- * rendering of what the build will emit or a field you set once and leave.
+ * **The Page tab keeps the fields; the modal keeps the picture.** Title lives on the tab, because
+ * it is the one head value you type while writing. Everything the modal holds is either a rendering
+ * of what the build will emit or a field you set once and leave.
  *
  * **This module is the flow; `surfaces/seo.json` is the markup.** What lives here is every
  * judgement the picture rests on: which realm a commit is written into, what each previewed line
@@ -24,30 +24,28 @@
  * decision — it holds the parts, the ARIA and the styling, and it branches on flags this module
  * hands it.
  *
- * The mutation path is the card's, unchanged: a markdown page commits through
- * `applyContentMutation` and a JSON one through `transact`, both taking the tab so the modal edits
- * the document it was opened over rather than whichever pane has focus.
+ * The mutation path is the Page tab's: a markdown page commits through `applyContentMutation` and a
+ * JSON one through `transact`, both taking the tab so the modal edits the document it was opened
+ * over rather than whichever pane has focus.
  *
  * @docs studio/editing/frontmatter
  */
 
 import { activeRegistry } from "../commands/active-registry";
+import { HEAD_EDIT_DEBOUNCE } from "../ui/timing";
 import { previewAssetSrc } from "../canvas/asset-refs";
-import { getPlatform } from "../platform";
 import { layerHost } from "../ui/layers";
-import { mediaSiteUrl } from "../files/media-paths";
-import { openMenu } from "../surfaces/menu";
 import { openSeoSurface } from "../surfaces/seo";
 import { provenanceTitle } from "./provenance";
-import { PUBLIC_DIR } from "@jxsuite/schema/asset-paths";
-import { scanLibrary } from "../browse/library-model";
 import { tabLabel } from "./tab-strip";
 import { transact } from "../tabs/transact";
 import { activeTab } from "../workspace/workspace";
-import { MEDIA_EXTENSIONS, uploadAccept, uploadAssets } from "../files/media-upload";
+import { pickAndUpload, showMediaPickerPopover } from "../ui/media-picker";
 import {
   OG_FIELDS,
   PAGE_FIELDS,
+  pageDescription,
+  setPageDescription,
   applyContentMutation,
   buildHeadDoc,
   findLinkEntry,
@@ -225,6 +223,11 @@ function writeField(
     applyMutation((doc: JxMutableNode) => upsertLink(doc, "icon", trimmed));
     return;
   }
+  if (key === "description") {
+    // The page's one description, written where the build reads it.
+    applyMutation((doc: JxMutableNode) => setPageDescription(doc, trimmed));
+    return;
+  }
   const field = META_BY_KEY.get(key);
   if (!field) {
     return;
@@ -232,15 +235,6 @@ function writeField(
   applyMutation((doc: JxMutableNode) => upsertMeta(doc, field.attr, field.key, trimmed));
 }
 
-/**
- * How long a keystroke waits before it is written.
- *
- * Every commit is a document mutation, and the previews repaint from it, so a write per keystroke
- * would redraw the picture mid-word. A `change` — the control losing focus, or its clear button —
- * cancels the timer and commits immediately, which is why nothing is ever lost to the debounce.
- */
-const EDIT_DEBOUNCE_MS = 300;
-
 /** One timer per field key, so editing Description then Title does not cancel the first write. */
 const _pending = new Map<string, ReturnType<typeof setTimeout>>();
 
@@ -260,35 +254,6 @@ function cancelPending(key?: string): void {
   }
 }
 
-// ─── The project's media ──────────────────────────────────────────────────────
-
-/** The listing, once. Invalidated by an upload, which is the only thing that changes it here. */
-let _media: string[] | null = null;
-
-/**
- * Every media file under `public/`, as the site URLs a pick would write.
- *
- * `browse/library-model.ts`'s walker rather than a second one: it is the scanner the Library pane
- * already runs over the same tree, it records what it could not read instead of swallowing it, and
- * it skips the directories nobody wants walked. The site URL is the authored form — what production
- * serves — and `files/media-paths.ts` holds the one definition of that mapping.
- */
-async function mediaChoices(): Promise<string[]> {
-  if (_media) {
-    return _media;
-  }
-  const { files } = await scanLibrary([PUBLIC_DIR], getPlatform());
-  _media = files
-    .filter((file) => MEDIA_EXTENSIONS.has(file.ext))
-    .map((file) => mediaSiteUrl(file.path));
-  return _media;
-}
-
-/** Forget the listing: it was derived from a tree an upload has just changed. */
-function invalidateMediaChoices(): void {
-  _media = null;
-}
-
 // ─── The modal ───────────────────────────────────────────────────────────────
 
 /** The open surface, or `null`. One at a time: it is about the focused document. */
@@ -300,20 +265,24 @@ let _tab: Tab | null = null;
 /** Where each chip that leads somewhere goes, rebuilt with the view it was drawn from. */
 let _donors = new Map<string, () => void>();
 
+/** What the SEO body reads and writes for one tab: its merged head, and how an edit lands. */
+interface SeoContext {
+  headDoc: JxMutableNode;
+  head: JxHeadEntry[];
+  applyMutation: (fn: (doc: JxMutableNode) => void) => void;
+}
+
 /**
  * What the SEO body needs from a tab, resolved once.
  *
  * Both realms in one place: a markdown page keeps its head material in frontmatter and a JSON one
  * in root properties, and `buildHeadDoc` is the card's own view of that difference.
  */
-function seoContextFor(tab: Tab): {
-  headDoc: JxMutableNode;
-  head: JxHeadEntry[];
-  applyMutation: (fn: (doc: JxMutableNode) => void) => void;
-} {
+function seoContextFor(tab: Tab): SeoContext {
   const isContent = tab.doc.mode === "content";
-  const fm = (tab.doc.content?.frontmatter ?? {}) as Record<string, unknown>;
-  const headDoc = isContent ? buildHeadDoc(tab.doc.document, fm) : tab.doc.document;
+  const headDoc = isContent
+    ? buildHeadDoc(tab.doc.document, tab.doc.content.frontmatter)
+    : tab.doc.document;
   return {
     applyMutation: isContent
       ? (fn: (doc: JxMutableNode) => void) => applyContentMutation(tab, renderSeoModal, fn)
@@ -363,9 +332,12 @@ function buildView(tab: Tab, headDoc: JxMutableNode, head: JxHeadEntry[]): SeoVi
         note: "",
         rows: [
           ...PAGE_FIELDS.map((field) =>
-            editRow(field.key, field.label, metaValue(head, field.key), {
-              multiline: field.multiline,
-            }),
+            editRow(
+              field.key,
+              field.label,
+              field.key === "description" ? pageDescription(headDoc) : metaValue(head, field.key),
+              { multiline: field.multiline },
+            ),
           ),
           editRow(ICON_KEY, "Icon", iconHref, { media: true }),
         ],
@@ -413,69 +385,26 @@ function commitField(key: string, value: string): void {
   renderSeoModal();
 }
 
-/** Open the OS file picker for a media row, and assign the first file it returns. */
+/**
+ * Upload into a media row: the image field's own Upload (`ui/media-picker.ts`), which opens the
+ * picker, uploads through the one core, and hands the first file's ref back. A commit that lands
+ * after the modal closed writes nothing, because {@link commitField} is about the open modal.
+ */
 function uploadInto(key: string): void {
-  /* The input is created per click and discarded after: a hidden one kept in the document would be
-     a node the surface owns outside its own document, which is exactly what a surface may not
-     have. */
-  const input = document.createElement("input");
-  input.type = "file";
-  input.multiple = true;
-  input.accept = uploadAccept();
-  input.addEventListener("change", () => {
-    if (!input.files?.length) {
-      return;
-    }
-    void uploadAssets([...input.files]).then((uploaded) => {
-      invalidateMediaChoices();
-      const [first] = uploaded;
-      if (first) {
-        commitField(key, first.ref);
-      }
-    });
-  });
-  input.click();
+  pickAndUpload((ref: string) => commitField(key, ref));
 }
 
 /**
- * Offer the project's media for one row.
+ * Offer the project's images for one row: the media picker's own compact browser, with its **Browse
+ * all images…** row opening the Media workspace's surface in pick mode.
  *
- * A kit menu rather than the Spectrum popover `ui/media-picker.ts` draws, and it has to be: a modal
- * `<dialog>` is in the top layer, so an overlay painted into a layer div renders UNDERNEATH the
- * dialog that opened it and is inert besides (`specs/ui.md` §7). The menu is shown with the Browse
- * button as its `source`, which is what puts it in the dialog's own top-layer hierarchy.
+ * Not a list of this module's own. It kept one (a walk of `public/` alone, and a kit menu of site
+ * URLs) because the old picker painted into a layer div UNDER the modal; the browser is a top-layer
+ * `jx-popover` now, so it paints over the modal that opened it, and the field and this dialog
+ * answer "what media does this project have" from the same listing (studio.md §9.3).
  */
 function browseFor(key: string, anchor: HTMLElement): void {
-  void mediaChoices().then((choices) => {
-    openMenu({
-      label: "Project media",
-      opener: anchor,
-      region: "seo-media",
-      rows:
-        choices.length > 0
-          ? choices.map((path) => ({
-              destructive: false,
-              disabled: false,
-              dividerAbove: false,
-              id: path,
-              run: () => commitField(key, path),
-              /* The site URL rather than the file name, because it is the string the pick writes
-                 AND the only one of the two that is unique: two `hero.jpg`s in two directories are
-                 one row twice over in a list that shows names. */
-              title: path,
-            }))
-          : [
-              {
-                destructive: false,
-                disabled: true,
-                dividerAbove: false,
-                id: "seo.media.empty",
-                requires: "a file under public/",
-                title: "No media in this project",
-              },
-            ],
-    });
-  });
+  showMediaPickerPopover(anchor, (ref: string) => commitField(key, ref), { images: true });
 }
 
 /** Open it over `tab`. Idempotent — opening it again re-points it at the current document. */
@@ -495,7 +424,7 @@ export function openSeoModal(tab: Tab): void {
           setTimeout(() => {
             _pending.delete(key);
             commitField(key, value);
-          }, EDIT_DEBOUNCE_MS),
+          }, HEAD_EDIT_DEBOUNCE),
         );
       },
       onOpenDonor: (key: string) => {
@@ -533,10 +462,10 @@ export function closeSeoModal(): void {
 /**
  * `document.openSeo` — the one capability behind both buttons.
  *
- * The Document Header card and the Page panel each render a control that runs this, so neither owns
- * it and the palette has it by name. A record rather than two click handlers, for the reason the
- * rendering-context axes became records: a surface that IS the capability is a capability the
- * palette, the assistant and `__jxAutomation` cannot reach.
+ * The Page tab renders a control that runs this, so it does not own it and the palette has it by
+ * name. A record rather than two click handlers, for the reason the rendering-context axes became
+ * records: a surface that IS the capability is a capability the palette, the assistant and
+ * `__jxAutomation` cannot reach.
  *
  * @returns {AnyCommand[]}
  */

package/src/panels/settings-menu.ts

@@ -1,35 +1,37 @@
 /// <reference lib="dom" />
 /**
- * The rail foot's ⚙ Settings menu — a RENDERING of the `settings/menu` placement.
+ * The top bar's ⚙ Settings menu — a RENDERING of the `settings/menu` placement.
  *
  * The gear used to run one command. That was the right shape for a pinned slot and the wrong shape
- * for the question people bring to it: Studio has two settings families at two containment levels —
- * `app.preferences` (the application, ⌘,) and `settings.open` (this project, ⌘⇧,) — plus a third
- * editor over the same project document, `styles.open`. A slot can hold one of those and must lie
- * about the rest by omission. A menu can hold all three and say what each one is, because it prints
- * every row's own name, chord and gate beside it (`studio-ui-guidelines.md` §12.3). That is the
- * whole argument for the matrix row `settings/menu` admitting two levels, and for the divider this
- * file draws where the level changes.
+ * for the question people bring to it: Studio has two settings families at two containment levels,
+ * `app.preferences` (the application, ⌘,) and `settings.open` (this project, ⌘⇧,). A slot can hold
+ * one of those and must lie about the other by omission. A menu can hold both and say what each one
+ * is, because it prints every row's own name, chord and gate beside it (`studio-ui-guidelines.md`
+ * §12.3). That is the whole argument for the matrix row `settings/menu` admitting two levels, and
+ * for the divider this file draws where the level changes. Project Styles is not here: Styles is a
+ * workspace, and the top bar already names it.
  *
  * **Nothing here is a list of actions.** The rows are `registry.forPlacement("settings/menu")`, so
  * a record joins the menu by declaring the placement and leaves by not declaring it. The submenus
  * are the enumeration of each parent command's own `section` ARGUMENT, read from that argument's
  * own definition site — which is state the command already validates, not a second vocabulary
- * (`studio-ui-guidelines.md` §12.5).
+ * (`studio-ui-guidelines.md` §12.5). Project Settings' submenu is GROUPED as its dialog's nav is
+ * (General, Integrations, Advanced), with a divider where the group changes.
  *
  * **A parent row runs its own command AND owns a submenu.** The APG menu pattern does not describe
  * that and Spectrum's stock submenu forbade it outright; the kit's `jx-menu-item` makes it the rule
  * (`ui.md` §5.1), so the deviation `specs/studio-ui-guidelines.md` §8.4 records is now what the
  * element does rather than what this file hand-rolls around it. Nothing is unreachable by keyboard:
  * Enter runs the row, ArrowRight reaches every child, and every child is also in the settings
- * document's own inner nav.
+ * dialog's own nav.
  *
  * The menu is the `menu` surface (`surfaces/menu.json`, through `surfaces/menu.ts`). What is left
  * here is the projection — which records, which sections, what each row runs — and where the panel
- * hangs: off the gear's right edge, its bottom flush with the rail's, which is also the floor every
- * submenu keeps above the status bar. The section subscription lives for as long as the menu is up:
- * six of Project Settings' sections are contributed by extensions and register a tick after the
- * built-ins (`settings/extension-sections.ts`), so a menu opened in that window would otherwise be
+ * hangs: below the gear, right-aligned to it. The gear moved from the rail's foot to the top bar
+ * because the rail is drawn only in the Design workspace, and the settings are every workspace's.
+ * The section subscription lives for as long as the menu is up: six of Project Settings' sections
+ * are contributed by extensions and register a tick after the built-ins
+ * (`settings/extension-sections.ts`), so a menu opened in that window would otherwise be
  * permanently short. It deliberately does NOT call the sync itself: opening a menu must not do IO.
  *
  * @docs studio/interface/preferences
@@ -39,25 +41,25 @@
 import { activeRegistry } from "../commands/active-registry";
 import { runReported } from "../commands/run-reported";
 import { LEVELS } from "../commands/levels";
-import { onSettingsDocumentChanged, sortedSettingsSections } from "../settings/section-registry";
+import { groupedSettingsSections, onSettingsDocumentChanged } from "../settings/section-registry";
 import { PREFERENCES_SECTIONS } from "../settings/preferences-sections";
 import { openMenu } from "../surfaces/menu";
-import { REGION_ATTR } from "../ui/regions";
 import { rectOf } from "../utils/geometry";
 
+import type { CommandArgValues } from "../commands/command-args";
 import type { CommandRegistry } from "../commands/registry";
 import type { Level } from "../commands/levels";
 import type { MenuHandle, MenuRowProjection } from "../surfaces/menu";
+import type { KeyedLabel } from "../ui/surface";
 
-/** The placement the rail's gear renders. One definition site for the string. */
-export const SETTINGS_MENU_PLACEMENT = "settings/menu" as const;
-
-/** One value a parent command's `section` argument accepts. */
-interface MenuSection {
-  key: string;
-  label: string;
+/** One submenu row's source: the argument value, its label, and whether a new group starts here. */
+interface SectionRow extends KeyedLabel {
+  dividerAbove: boolean;
 }
 
+/** The placement the top bar's gear renders. One definition site for the string. */
+export const SETTINGS_MENU_PLACEMENT = "settings/menu" as const;
+
 let _menu: MenuHandle | null = null;
 let _unsubscribe: (() => void) | null = null;
 let _rerender: (() => void) | null = null;
@@ -73,16 +75,32 @@ let _rerender: (() => void) | null = null;
  * `settings.open` refuses anything absent from `settingsSectionKeys()` — so a submenu row can never
  * name a value its own command would refuse.
  */
-const SECTION_SOURCES: Readonly<Record<string, () => readonly MenuSection[]>> = {
-  "app.preferences": () =>
-    PREFERENCES_SECTIONS.map((section) => ({ key: section.id, label: section.title })),
-  "settings.open": () =>
-    sortedSettingsSections().map((section) => ({ key: section.key, label: section.label })),
-};
+const SECTION_SOURCES: ReadonlyMap<string, () => readonly SectionRow[]> = new Map([
+  [
+    "app.preferences",
+    () =>
+      PREFERENCES_SECTIONS.map((section) => ({
+        dividerAbove: false,
+        key: section.id,
+        label: section.title,
+      })),
+  ],
+  [
+    "settings.open",
+    () =>
+      groupedSettingsSections().flatMap((group, groupIndex) =>
+        group.sections.map((section, index) => ({
+          dividerAbove: groupIndex > 0 && index === 0,
+          key: section.key,
+          label: section.label,
+        })),
+      ),
+  ],
+]);
 
 /** The sections a row offers, or none. */
-function menuSectionsFor(id: string): readonly MenuSection[] {
-  return SECTION_SOURCES[id]?.() ?? [];
+function menuSectionsFor(id: string): readonly SectionRow[] {
+  return SECTION_SOURCES.get(id)?.() ?? [];
 }
 
 // ─── Running ──────────────────────────────────────────────────────────────────
@@ -95,7 +113,7 @@ function menuSectionsFor(id: string): readonly MenuSection[] {
  * click throws BEFORE `run`, synchronously. `commands/run-reported.ts` catches both and files the
  * sentence in Problems, under this menu's name.
  */
-function runRow(id: string, args?: Record<string, unknown>): void {
+function runRow(id: string, args?: CommandArgValues): void {
   const registry = activeRegistry();
   if (!registry) {
     return;
@@ -134,7 +152,7 @@ function buildSettingsMenuRows(registry: CommandRegistry): MenuRowProjection[] {
         ? menuSectionsFor(id).map((section) => ({
             destructive: false,
             disabled: false,
-            dividerAbove: false,
+            dividerAbove: section.dividerAbove,
             id: `${id}:${section.key}`,
             // Named by the argument value it passes, never by a reworded command title.
             run: () => runRow(id, { section: section.key }),
@@ -161,26 +179,9 @@ function buildSettingsMenuRows(registry: CommandRegistry): MenuRowProjection[] {
   });
 }
 
-// ─── Geometry ─────────────────────────────────────────────────────────────────
-
-/**
- * The lowest edge any menu in this stack may reach.
- *
- * The trigger's REGION, not the viewport. The gear sits in the rail, whose bottom is the status
- * bar's top — so clamping to the viewport would let a tall submenu run down over the status bar
- * while the root menu sits neatly above it. One floor for both levels is what keeps the stack
- * looking like one surface, and it is expressed through the shell's own addressing grammar rather
- * than a selector into markup — so a menu button in another region would align to that one without
- * this function learning about it.
- */
-function menuFloor(anchor: HTMLElement): number {
-  const host = anchor.closest<HTMLElement>(`[${REGION_ATTR}]`);
-  return host ? rectOf(host).bottom : window.innerHeight;
-}
-
 // ─── Public surface ───────────────────────────────────────────────────────────
 
-/** Whether the gear menu is on screen. The rail reads it for `aria-expanded`. */
+/** Whether the gear menu is on screen. The top bar reads it for `aria-expanded`. */
 export function isSettingsMenuOpen(): boolean {
   return _menu !== null;
 }
@@ -197,7 +198,7 @@ export function dismissSettingsMenu(): void {
  * class stay lit BINDINGS rather than imperative attribute writes; a stale `aria-expanded` is a
  * defect this app has shipped before. Same seam as `showContextMenu(e, path, { rerender })`.
  *
- * @param anchor The control the menu hangs off — the rail's gear.
+ * @param anchor The control the menu hangs off — the top bar's gear.
  */
 export function openSettingsMenu(anchor: HTMLElement, opts: { rerender?: () => void } = {}): void {
   if (_menu) {
@@ -213,9 +214,7 @@ export function openSettingsMenu(anchor: HTMLElement, opts: { rerender?: () => v
     return;
   }
   _rerender = opts.rerender ?? null;
-  const floor = (): number => menuFloor(anchor);
   const handle = openMenu({
-    floor,
     label: "Settings",
     onClosed: (closedHandle) => {
       if (_menu !== closedHandle) {
@@ -230,13 +229,16 @@ export function openSettingsMenu(anchor: HTMLElement, opts: { rerender?: () => v
       rerender?.();
     },
     opener: anchor,
-    /* Hanging off the trigger's right edge, with its BOTTOM flush with the bottom of the region the
-       trigger lives in. Not "below the trigger": the gear is the last control in a full-height rail
-       whose foot abuts the status bar, so a menu dropped below it would be off-screen, and one
-       aligned to the button would float six pixels of `.rail-footer` padding clear of the status
-       bar. Floored at 4, because Project Settings has ~16 sections once extensions have contributed
-       and a menu taller than the area must keep its FIRST rows on screen. */
-    place: (box) => ({ x: rectOf(anchor).right + 4, y: Math.max(4, floor() - box.height) }),
+    /* Below the gear, its RIGHT edge flush with the gear's. The gear sits at the right-hand end of
+       the top bar, just before the dock toggles, so a menu hanging from its left edge would run off
+       the window; right-aligning it is a function of the menu's own width, which is why this is a
+       `place` callback run once the panel has been laid out. Floored at 4 on the left, so a menu
+       wider than the space to the gear's left keeps its leading edge on screen. */
+    place: (box) => {
+      const gear = rectOf(anchor);
+      return { x: Math.max(4, gear.right - box.width), y: gear.bottom + 4 };
+    },
+    placement: "block-end span-inline-start",
     region: "settings",
     rows,
   });