@jxsuite/studio 4.0.0 → 5.0.0

package/src/github/github-publish.ts

@@ -15,16 +15,22 @@
  * that already existed failed the push with a message about pushing. `beginActivity` gives it the
  * ordered steps, the captured log, and `fail()`, which raises the Problem the failure needs and
  * carries the log as its detail (§7.3). The caller therefore never also notifies.
+ *
+ * **The dialog is a document.** `surfaces/github-publish.json` collects the name, the description
+ * and the visibility; this module keeps the token, the requests and the activity. What it used to
+ * be is worth recording, because it is the shape every converted surface starts from: three `ref()`
+ * callbacks holding three Spectrum controls, read for their `.value` at the moment confirm fired.
+ * Nothing owned the reader's answer until the answer was needed.
  */
 
-import { html } from "lit-html";
 import { errorMessage } from "@jxsuite/schema/parse";
-import { ref } from "lit-html/directives/ref.js";
-import { showDialog } from "../ui/layers";
+import { layerHost } from "../ui/layers";
+import { openGithubPublishSurface } from "../surfaces/github-publish";
 import { authenticateGithub } from "./github-auth";
 import { beginActivity } from "../panels/activity-panel";
 import { getPlatform } from "../platform";
 import { notify } from "../services/notify";
+import type { GithubPublishSurfaceHandle, RepoOptions } from "../surfaces/github-publish";
 
 interface GithubErrorResponse {
   errors?: { message?: string }[];
@@ -36,16 +42,57 @@ interface GithubRepoResponse {
   html_url: string;
 }
 
-/** What the dialog collects. */
-export interface RepoOptions {
-  name: string;
-  description: string;
-  isPrivate: boolean;
-}
+/**
+ * What the dialog collects.
+ *
+ * Defined by the surface now and re-exported under the name this module has always exported, so the
+ * record and the document that fills it have one definition between them.
+ */
+export type { RepoOptions } from "../surfaces/github-publish";
 
 /** The ordered steps, named once so the activity and its tests cannot disagree. */
 export const REPO_STEPS = ["Create the repository", "Add the remote", "Push"] as const;
 
+/**
+ * Ask for the repository's name, description and visibility.
+ *
+ * The promise is this module's, not the surface's: the dialog reports three answers as callbacks
+ * and lets the flow decide what each one means, so `resolve` happens here and closing the dialog is
+ * a consequence of that rather than the thing that produces the value. `settle` is guarded because
+ * both ends arrive — confirming closes the dialog, which raises `onClosed` behind it, and a
+ * resolved promise must not be re-resolved with `null` a tick later.
+ *
+ * An empty name falls back to the project's, exactly as the template's `|| projectName` did. That
+ * belongs to the flow: the field is empty because the reader emptied it, and the surface would be
+ * lying about its own state if it reported a name nobody typed.
+ */
+function askForRepoOptions(projectName: string): Promise<RepoOptions | null> {
+  return new Promise((resolve) => {
+    let answered = false;
+    const settle = (value: RepoOptions | null): void => {
+      if (answered) {
+        return;
+      }
+      answered = true;
+      resolve(value);
+    };
+    const handle: GithubPublishSurfaceHandle = openGithubPublishSurface({
+      layer: layerHost("dialog"),
+      name: projectName,
+      onCancel: () => {
+        handle.close();
+      },
+      onClosed: () => {
+        settle(null);
+      },
+      onConfirm: (values) => {
+        settle({ ...values, name: values.name || projectName });
+        handle.close();
+      },
+    });
+  });
+}
+
 /**
  * Full "Create GitHub Repository" flow: 1. Authenticate (or reuse a stored token) 2. Prompt for
  * repo name / visibility 3. Create the repo via the GitHub API 4. Add remote + push
@@ -63,62 +110,7 @@ export async function createGithubRepository({ projectName }: { projectName: str
     return false;
   }
 
-  const repoOpts = await showDialog<RepoOptions | null>((done) => {
-    let _nameInput: HTMLInputElement | null = null;
-    let _descInput: HTMLInputElement | null = null;
-    let _privateToggle: HTMLInputElement | null = null;
-
-    return html`
-      <sp-dialog-wrapper
-        open
-        headline="Create GitHub Repository"
-        confirm-label="Create Repository"
-        cancel-label="Cancel"
-        @confirm=${() => {
-          done({
-            description: _descInput?.value || "",
-            isPrivate: _privateToggle?.checked ?? true,
-            name: _nameInput?.value || projectName,
-          });
-        }}
-        @cancel=${() => done(null)}
-        @close=${() => done(null)}
-      >
-        <div class="github-publish-dialog">
-          <sp-field-label for="repo-name">Repository name</sp-field-label>
-          <sp-textfield
-            id="repo-name"
-            name="repo-name"
-            value="${projectName}"
-            placeholder="my-project"
-            ${ref((el) => {
-              _nameInput = (el as HTMLInputElement | null) || null;
-            })}
-          ></sp-textfield>
-
-          <sp-field-label for="repo-desc">Description (optional)</sp-field-label>
-          <sp-textfield
-            id="repo-desc"
-            name="repo-desc"
-            placeholder="A brief description"
-            ${ref((el) => {
-              _descInput = (el as HTMLInputElement | null) || null;
-            })}
-          ></sp-textfield>
-
-          <sp-field-label>Visibility</sp-field-label>
-          <sp-switch
-            name="repo-private"
-            checked
-            ${ref((el) => {
-              _privateToggle = (el as HTMLInputElement | null) || null;
-            })}
-            >Private repository</sp-switch
-          >
-        </div>
-      </sp-dialog-wrapper>
-    `;
-  });
+  const repoOpts = await askForRepoOptions(projectName);
 
   if (!repoOpts) {
     return false;

package/src/grid/cell-editors.ts

@@ -8,10 +8,52 @@
  * rendered element (never an HTML string, which Tabulator would inject as innerHTML).
  *
  * Native inputs (the data-grid precedent) rather than Spectrum controls: cells are 24px
- * micro-controls where SWC shadow focus handling fights Tabulator's editor lifecycle. Rich popover
- * editors (media, relationship pickers) layer on in a later phase.
+ * micro-controls where SWC shadow focus handling fights Tabulator's editor lifecycle.
+ *
+ * ## This surface stays lit, and the reason is structural rather than a shortage of will
+ *
+ * Every other control in the grid is a document — the frame, the toolbar, both popovers, and the
+ * value picker for the two kinds that edit OUT of the cell (`surfaces/grid-cell.json`). These do
+ * not, because they render into TABULATOR's DOM on Tabulator's clock, and a Jx document is mounted
+ * asynchronously: `ui/surface.ts`'s `mountSurface` awaits `kitReady()` and then `mount()`. Three
+ * things in the engine read the editor's own subtree in the SAME statement sequence that parents
+ * it, so an empty box handed over now and filled a microtask later is not the same object:
+ *
+ * 1. `Edit.edit()` runs `element.appendChild(cellEditor)` and then `rendered()` on the next line —
+ *    that is the `onRendered` callback below, whose whole job is to focus and select the control.
+ *    With nothing in the box there is nothing to focus, so the keystroke that opened the editor
+ *    lands on the table and the edit module blur-cancels the session.
+ * 2. The statement after that walks `element.children` and adds a click-stopper to each. A child that
+ *    arrives later never gets one, so the first click inside the editor bubbles to the cell and the
+ *    SelectRange module reads it as a range interaction.
+ * 3. `navigateNext`/`navigatePrev` call `nextCell.getComponent().edit()` SYNCHRONOUSLY inside the
+ *    keydown handler, so Tab commits one editor and builds the next in one turn. That is what rules
+ *    out the obvious escape — a pool of pre-mounted documents re-seeded per session — because a
+ *    scope write flushes in a microtask (`@vue/reactivity` batches; `src/reactivity.ts` says so at
+ *    its definition), and the second editor would open showing the first cell's value.
+ *
+ * The formatters are blocked a second way, which no seam fixes. `Cell._generateContents()` wipes
+ * the cell and appends whatever the formatter returned, and it runs for every visible cell on every
+ * render; with `renderVertical: "virtual"` (see `grid-view.ts`) `Row.wipe()`/`deleteCells()`
+ * destroy those cells as they scroll out, and NOTHING calls back to say so. A document per cell
+ * would enter `services/surface-registry.ts` on the way in and never leave it — an unbounded
+ * registry keyed to nodes the engine has already thrown away — and would repaint asynchronously
+ * while the reader scrolls.
+ *
+ * So the boundary is the cell, and it is the same boundary §9.4 already draws around Tabulator: the
+ * engine is an island, and this file is the inside of it. The two kinds whose picker is bigger than
+ * a cell escaped it by leaving the cell entirely, and that is the shape any future conversion has
+ * to take — a document ANCHORED at the cell, not mounted in it. What would actually unblock the
+ * rest is a synchronous mount path in the runtime (a document rendered into a detached host with
+ * the kit already registered, no awaits), at which point 1 and 2 dissolve and only the formatter's
+ * lifetime problem is left, which needs a teardown hook Tabulator does not have.
  */
 import { html, render } from "lit-html";
+/* The two cell editors below are re-rendered while they are open — the pill editor calls its own
+   `doRender()` on every Enter — and an `<input>` moves `value`/`checked` itself without reflecting
+   either. A plain property binding is dirty-checked against what lit last committed, so the write
+   would be skipped exactly when the reader had changed it. `check-lit-conventions.ts` rule 1. */
+import { live } from "lit-html/directives/live.js";
 import { cellToText, coerceCellInput } from "./schema-columns";
 import type { GridCellValue, GridColumn } from "./grid-source";
 
@@ -57,7 +99,7 @@ function inputEditor(makeHost: HostFactory, column: GridColumn, inputType: strin
       html`<input
         class="jx-grid-input"
         type=${inputType}
-        .value=${initial}
+        .value=${live(initial)}
         @keydown=${(e: KeyboardEvent) => {
           if (e.key === "Enter") {
             commit((e.target as HTMLInputElement).value);
@@ -86,7 +128,7 @@ function checkboxEditor(makeHost: HostFactory): CellEditorFn {
       html`<input
         class="jx-grid-checkbox"
         type="checkbox"
-        .checked=${cell.getValue() === true}
+        .checked=${live(cell.getValue() === true)}
         @change=${(e: Event) => {
           if (!done) {
             done = true;

package/src/grid/cell-popovers.ts

@@ -1,14 +1,19 @@
 /**
  * Popover cell editors — media paths and relationship pickers.
  *
- * These kinds bypass Tabulator's in-cell editor session entirely: their pickers render Spectrum
- * overlays OUTSIDE the cell, which Tabulator's range module treats as an outside interaction and
- * blur-cancels. Instead, a dblclick on the cell opens an anchored layer popover that writes
- * straight through the edit buffer via `commit`.
+ * These kinds bypass Tabulator's in-cell editor session entirely: their pickers render OUTSIDE the
+ * cell, which Tabulator's range module treats as an outside interaction and blur-cancels. Instead,
+ * a dblclick on the cell opens `surfaces/grid-cell.json` anchored at the cell, and every pick
+ * writes straight through the edit buffer via `commit`.
+ *
+ * **What is left here is the decision, not the markup.** The panel is a document; this module says
+ * which of the two pickers it draws, what the relationship column points at, and what a pick means.
+ * The media picker is a document of its own now (`surfaces/media-field.json`), so it still arrives
+ * through the panel's island seam (specs/studio-ui-guidelines.md §9.4) — the box is drawn by one
+ * document and filled by another, and nothing in this file renders anything.
  */
-import { html, nothing } from "lit-html";
-import { renderPopover } from "../ui/layers";
-import { renderMediaPicker } from "../ui/media-picker";
+import { openGridCellSurface } from "../surfaces/grid-cell";
+import { mountMediaPicker } from "../ui/media-picker";
 import { listCollectionEntryIds } from "./sources/content-source";
 import { cellToText } from "./schema-columns";
 import type { GridCellValue, GridColumn } from "./grid-source";
@@ -36,27 +41,17 @@ export interface CellPopoverArgs {
   commit: (value: GridCellValue) => void;
 }
 
-function popoverShell(
-  column: GridColumn,
-  anchor: CellPopoverArgs["anchor"],
-  body: unknown,
-  dismiss: () => void,
-) {
-  const left = Math.max(4, Math.min(anchor.left, window.innerWidth - 340));
-  const top = Math.max(4, Math.min(anchor.bottom + 2, window.innerHeight - 200));
-  return html`<sp-popover
-    open
-    class="jx-grid-cell-popover"
-    style="position:fixed;z-index:10000;left:${left}px;top:${top}px"
-  >
-    <div class="jx-grid-cell-popover-body">
-      <div class="jx-grid-cell-popover-title">${column.title}</div>
-      ${body}
-      <div class="jx-grid-cell-popover-actions">
-        <sp-button size="s" variant="secondary" @click=${dismiss}>Done</sp-button>
-      </div>
-    </div>
-  </sp-popover>`;
+/**
+ * Where the panel opens: at the cell, kept inside the viewport on both axes.
+ *
+ * The clamp is the panel's own width and a floor for its height, because a cell near the right edge
+ * of a wide grid is exactly where a relationship column tends to be.
+ */
+function placement(anchor: CellPopoverArgs["anchor"]): { x: number; y: number } {
+  return {
+    x: Math.max(4, Math.min(anchor.left, window.innerWidth - 340)),
+    y: Math.max(4, Math.min(anchor.bottom + 2, window.innerHeight - 200)),
+  };
 }
 
 /**
@@ -66,45 +61,53 @@ function popoverShell(
 export async function openCellValuePopover(args: CellPopoverArgs): Promise<void> {
   const { anchor, column, commit, value } = args;
   const current = cellToText(value);
+  const at = placement(anchor);
+  /* The empty string is what every control here says for "no value", and null is what the buffer
+     stores — a cell cleared through this panel must be indistinguishable from one never set. The
+     trim is for the free-text field: an id with a stray space is a reference that resolves to
+     nothing, and it is never what was meant. */
+  const pick = (picked: string) => {
+    const trimmed = picked.trim();
+    commit(trimmed === "" ? null : trimmed);
+  };
 
-  let body;
   if (column.kind === "reference") {
     const targetType = referenceTargetType(column);
     const ids = targetType ? await listCollectionEntryIds(targetType) : [];
-    body = html`
-      ${
-        targetType
-          ? html`<div class="jx-grid-cell-popover-hint">Entries of “${targetType}”</div>`
-          : nothing
-      }
-      <select
-        class="jx-grid-select"
-        @change=${(e: Event) => {
-          const picked = (e.target as HTMLSelectElement).value;
-          commit(picked === "" ? null : picked);
-        }}
-      >
-        <option value="" ?selected=${current === ""}>—</option>
-        ${ids.map((id) => html`<option value=${id} ?selected=${id === current}>${id}</option>`)}
-      </select>
-      <input
-        class="jx-grid-input"
-        placeholder="Custom id…"
-        .value=${ids.includes(current) ? "" : current}
-        @change=${(e: Event) => {
-          const text = (e.target as HTMLInputElement).value.trim();
-          commit(text === "" ? null : text);
-        }}
-      />
-    `;
-  } else {
-    body = renderMediaPicker(column.field, current, (val) => {
-      commit(val === "" ? null : val);
+    const listed = ids.includes(current);
+    openGridCellSurface({
+      pick,
+      view: {
+        /* An id the target collection does not hold is still a legal reference — a draft entry, or
+           one another repository owns — so it shows in the free-text field rather than being
+           silently dropped by a list that has no row for it. */
+        custom: listed ? "" : current,
+        hint: targetType ? `Entries of “${targetType}”` : "",
+        hintState: targetType ? "shown" : "hidden",
+        kind: "reference",
+        options: [{ label: "—", value: "" }, ...ids.map((id) => ({ label: id, value: id }))],
+        title: column.title,
+        value: listed ? current : "",
+        ...at,
+      },
     });
+    return;
   }
 
-  const handle = renderPopover(
-    popoverShell(column, anchor, body, () => handle.dismiss()),
-    { dismissOnOutsideClick: true },
-  );
+  openGridCellSurface({
+    island: (host) => {
+      mountMediaPicker(host, column.field, current, pick);
+    },
+    pick,
+    view: {
+      custom: "",
+      hint: "",
+      hintState: "hidden",
+      kind: "image",
+      options: [],
+      title: column.title,
+      value: current,
+      ...at,
+    },
+  });
 }

package/src/grid/grid-open.ts

@@ -5,10 +5,11 @@
  * "source" alternate; collection/pages/connector grids (later phases) open as virtual tabs with
  * `grid://` ids. All openers dedupe by tab id.
  */
-import { html } from "lit-html";
 import { activateTab, openTab, workspace } from "../workspace/workspace";
 import { formatForPath, loadFormats } from "../format/format-host";
-import { openModal } from "../ui/layers";
+import { layerHost } from "../ui/layers";
+import { openDialogSurface } from "../surfaces/dialog";
+import { mountGridOpenSurface } from "../surfaces/grid-open";
 import { dataSurfaceAvailable, fetchConnections } from "../services/data-service";
 import { createGridController } from "./grid-controller";
 import { createCsvFileSource } from "./sources/csv-file-source";
@@ -18,10 +19,11 @@ import {
   createPagesSource,
 } from "./sources/content-source";
 import { createConnectorSource } from "./sources/connector-source";
-import { makeGridTabId } from "./grid-source";
+import { makeGridTabId, parseGridTabId } from "./grid-source";
 import { libraryTabId } from "../browse/library-source";
 import { argsSchema, optionalStringArg, stringArg, stringProperty } from "../commands/command-args";
 import type { GridSource } from "./grid-source";
+import type { GridOpenSurfaceHandle, GridSourceGroup } from "../surfaces/grid-open";
 import type { Tab } from "../tabs/tab";
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
 
@@ -131,9 +133,63 @@ export function openConnectorGrid(connection: string | undefined, table: string)
   return openVirtualGridTab(createConnectorSource(connection, table));
 }
 
+/**
+ * Open the source a row names.
+ *
+ * The row's id IS the grid tab id it opens, which is what makes each row addressable — a shot or a
+ * test names `[data-source="grid://collection/posts"]` rather than the label somebody typed — and
+ * saves this module a second encoding to keep in step with `makeGridTabId`.
+ */
+function openGridSource(id: string): void {
+  const ref = parseGridTabId(id);
+  if (ref?.kind === "pages") {
+    openPagesGrid();
+  } else if (ref?.kind === "collection") {
+    openCollectionGrid(ref.name);
+  } else if (ref?.kind === "data") {
+    openConnectorGrid(ref.connection, ref.table);
+  }
+}
+
+/** Every grid-able source a project has, grouped by where it comes from. */
+function sourceGroups(
+  collections: readonly { name: string }[],
+  connections: readonly { name: string; tables: string[] }[],
+): GridSourceGroup[] {
+  return [
+    {
+      emptyMessage: "",
+      key: "project",
+      rows: [
+        { id: makeGridTabId({ kind: "pages" }), label: "Pages" },
+        ...collections.map(({ name }) => ({
+          id: makeGridTabId({ kind: "collection", name }),
+          label: `Collection: ${name}`,
+        })),
+      ],
+      state: "listed",
+      title: "Project",
+    },
+    ...connections.map((conn) => ({
+      emptyMessage: "No tables — push a schema first.",
+      key: `data:${conn.name}`,
+      rows: conn.tables.map((table) => ({
+        id: makeGridTabId({ connection: conn.name, kind: "data", table }),
+        label: table,
+      })),
+      state: (conn.tables.length === 0 ? "empty" : "listed") as "empty" | "listed",
+      title: `Data · ${conn.name}`,
+    })),
+  ];
+}
+
 /**
  * Source picker — one dialog listing every grid-able source: pages, content collections, and (when
  * the platform serves the data surface) each connection's tables.
+ *
+ * The dialog is `ui/layers.ts`'s, and the list inside it is `surfaces/grid-open.json`. Nothing here
+ * draws a headline or a cancel button: a second answer to "what is a dialog" is a defect
+ * (specs/studio-ui-guidelines.md §12.5), and what this surface genuinely owns is the grouping.
  */
 export async function openGridSourcePicker(): Promise<void> {
   const collections = collectionDirs();
@@ -143,59 +199,30 @@ export async function openGridSourcePicker(): Promise<void> {
     connections = response?.connections ?? [];
   }
 
-  const handle = openModal(
-    html`<sp-dialog-wrapper
-      open
-      dismissable
-      underlay
-      headline="Open Grid"
-      @close=${() => handle.close()}
-    >
-      <sp-menu class="jx-grid-picker">
-        <sp-menu-group>
-          <span slot="header">Project</span>
-          <sp-menu-item
-            @click=${() => {
-              handle.close();
-              openPagesGrid();
-            }}
-            >Pages</sp-menu-item
-          >
-          ${collections.map(
-            ({ name }) =>
-              html`<sp-menu-item
-                @click=${() => {
-                  handle.close();
-                  openCollectionGrid(name);
-                }}
-                >Collection: ${name}</sp-menu-item
-              >`,
-          )}
-        </sp-menu-group>
-        ${connections.map(
-          (conn) =>
-            html`<sp-menu-group>
-              <span slot="header">Data · ${conn.name}</span>
-              ${
-                conn.tables.length === 0
-                  ? html`<sp-menu-item disabled>No tables — push a schema first</sp-menu-item>`
-                  : conn.tables.map(
-                      (table) =>
-                        html`<sp-menu-item
-                          @click=${() => {
-                            handle.close();
-                            openConnectorGrid(conn.name, table);
-                          }}
-                          >${table}</sp-menu-item
-                        >`,
-                    )
-              }
-            </sp-menu-group>`,
-        )}
-      </sp-menu>
-    </sp-dialog-wrapper>`,
-    { label: "Open Grid" },
-  );
+  let list: GridOpenSurfaceHandle | null = null;
+  const handle = openDialogSurface({
+    cancelLabel: "Cancel",
+    confirmLabel: "",
+    headline: "Open Grid",
+    island: (host) => {
+      list = mountGridOpenSurface(host, sourceGroups(collections, connections), (id) => {
+        handle.close();
+        openGridSource(id);
+      });
+    },
+    layer: layerHost("dialog"),
+    onCancel: () => handle.close(),
+    onClosed: () => {
+      list?.dispose();
+      list = null;
+    },
+    onConfirm: () => {},
+    region: "grid/open",
+  });
+  /* Deliberately not awaited. `handle.ready` settles when the dialog has been SHOWN, and the only
+     caller is a button press that has nothing to do afterwards; awaiting it would make this
+     function's promise depend on a platform event rather than on the fetch it actually performs. */
+  void handle.ready;
 }
 
 // ─── Commands ─────────────────────────────────────────────────────────────────
@@ -228,10 +255,8 @@ export function gridCommands(): AnyCommand[] {
       group: "5_data",
       requires: "a project that declares content collections",
       when: (ctx) => ctx.project.open,
-      aiTool: {
-        description: "Open a content collection's entries as an editable grid in a new tab.",
-        name: "open_collection_grid",
-      },
+      /* No `aiTool`, by §12.4's first deletion rule: this opens a surface for a person; the grid is
+         not a tool surface. */
       run: (_commandCtx, args) => {
         const name = stringArg("collection.editInGrid", args, "name");
         const declared = collectionDirs().map((c) => c.name);
@@ -266,10 +291,7 @@ export function gridCommands(): AnyCommand[] {
       requires: "a platform that serves the data routes",
       when: (ctx) => ctx.project.open,
       enablement: (ctx) => ctx.capability.dataRows,
-      aiTool: {
-        description: "Open a connector table as an editable grid in a new tab.",
-        name: "open_data_grid",
-      },
+      /* No `aiTool`, by §12.4's first deletion rule: this opens a surface for a person. */
       run: (_commandCtx, args) => {
         const table = stringArg("data.openGrid", args, "table");
         openConnectorGrid(optionalStringArg("data.openGrid", args, "connection"), table);