@jxsuite/studio 4.1.0 → 5.0.0

package/src/github/github-auth.ts

@@ -34,16 +34,25 @@
  * here — the browser withholds the reason on purpose — so the detail names both rather than
  * guessing between them.
  *
+ * **The waiting room is a document.** `surfaces/github-auth.json` draws the code, the link and the
+ * wait, over the kit's `jx-dialog`; this module keeps the client id, the poll loop, its failure
+ * budget and every report above. The dialog it replaced was an `<sp-dialog-wrapper>` whose one
+ * `@cancel`/`@close` handler both stopped the loop and resolved the promise, so "the reader
+ * dismissed this" and "GitHub answered" were the same code path — and the promise could be resolved
+ * a second time with `null` by the close that a successful sign-in itself provokes. Answering and
+ * closing are two steps now, in that order.
+ *
  * The token is returned to callers and never rendered. In a browser it is stored in `localStorage`;
  * on the desktop it is in the launcher's `0600` credential store and this module holds it only in
  * memory for the session. `settings/preferences-accounts.ts` lists it as _stored or not_ and is the
  * only place it can be revoked (`studio.md` §15 rule 1).
  */
 
-import { html } from "lit-html";
 import { errorMessage } from "@jxsuite/schema/parse";
 import { notify } from "../services/notify";
-import { showDialog } from "../ui/layers";
+import { layerHost } from "../ui/layers";
+import { openGithubAuthSurface } from "../surfaces/github-auth";
+import type { GithubAuthSurfaceHandle } from "../surfaces/github-auth";
 
 const CLIENT_ID = "Ov23liYVlMFpgjOEPXJH";
 const STORAGE_KEY = "jx_github_token";
@@ -247,17 +256,52 @@ export async function authenticateGithub() {
 
   const { device_code, user_code, verification_uri, interval = 5 } = codeData;
 
-  return showDialog<string | null>((done) => {
+  return new Promise<string | null>((resolve) => {
     let cancelled = false;
     let pollTimer: ReturnType<typeof setTimeout> | null = null;
     let failures = 0;
-
-    const stop = () => {
+    let answered = false;
+
+    /**
+     * Stop the loop and answer, once.
+     *
+     * Separate from {@link done} because both ends arrive and either may be first: a token that
+     * lands closes the dialog, which raises `onClosed` behind it, and a dialog the reader dismisses
+     * raises `onClosed` with no token at all. Answering here and closing there is what keeps the
+     * second of those from overwriting the first with `null`.
+     */
+    const settle = (token: string | null): void => {
+      if (answered) {
+        return;
+      }
+      answered = true;
       cancelled = true;
       if (pollTimer) {
         clearTimeout(pollTimer);
+        pollTimer = null;
+      }
+      resolve(token);
+    };
+
+    /**
+     * Take the dialog down, once.
+     *
+     * Guarded here rather than trusted to the handle, because closing is what RAISES `onClosed` —
+     * so a teardown that re-entered through it would call itself until the stack ran out.
+     */
+    let closing = false;
+    const takeDown = (): void => {
+      if (closing) {
+        return;
       }
-      done(null);
+      closing = true;
+      handle.close();
+    };
+
+    /** The poll's own exit: answer, then take the dialog down. */
+    const done = (token: string | null): void => {
+      settle(token);
+      takeDown();
     };
 
     const poll = async () => {
@@ -306,13 +350,11 @@ export async function authenticateGithub() {
               ? "The device code expired before it was entered."
               : `GitHub answered "${tokenData.error ?? "an unrecognised response"}".`,
         );
-        cancelled = true;
         done(null);
       } catch (error) {
         failures += 1;
         if (failures >= MAX_POLL_FAILURES) {
           reportUnreachable(error);
-          cancelled = true;
           done(null);
           return;
         }
@@ -320,27 +362,27 @@ export async function authenticateGithub() {
       }
     };
 
-    pollTimer = setTimeout(poll, interval * 1000);
+    /*
+     * The dialog first, then the timer. `done` reaches for `handle`, and a poll that fired before
+     * the surface existed would find a binding that is not initialised yet — which a zero-second
+     * device interval makes reachable rather than theoretical.
+     */
+    const handle: GithubAuthSurfaceHandle = openGithubAuthSurface({
+      layer: layerHost("dialog"),
+      onCancel: () => {
+        takeDown();
+      },
+      /* `done`, not `settle`: a `close` the flow did not ask for — Escape, or a dismissal the
+         platform allows — must ALSO take the document out of the dialog layer, or the surface
+         outlives the dialog it drew. `settle` is idempotent, so a close that follows a token
+         answers nothing and only cleans up. */
+      onClosed: () => {
+        done(null);
+      },
+      userCode: user_code,
+      verificationUri: verification_uri,
+    });
 
-    return html`
-      <sp-dialog-wrapper
-        open
-        headline="Sign in to GitHub"
-        cancel-label="Cancel"
-        @cancel=${stop}
-        @close=${stop}
-      >
-        <div class="github-auth-dialog">
-          <p>Enter this code on GitHub to authorize Jx Studio:</p>
-          <div class="github-auth-code">${user_code}</div>
-          <p>
-            <a href="${verification_uri}" target="_blank" rel="noopener"
-              >Open ${verification_uri}</a
-            >
-          </p>
-          <p class="github-auth-waiting">Waiting for authorization…</p>
-        </div>
-      </sp-dialog-wrapper>
-    `;
+    pollTimer = setTimeout(poll, interval * 1000);
   });
 }

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,
+    },
+  });
 }