@jxsuite/studio 4.0.0 → 5.0.0

package/src/surfaces/preferences.ts

@@ -0,0 +1,332 @@
+/// <reference lib="dom" />
+/**
+ * Preferences (⌘,) as a mounted document.
+ *
+ * `settings/preferences-dialog.ts` is the flow — which section is showing, what the shell's theme
+ * record holds, what `preferences-accounts.ts` enumerates, and the whole of the Keyboard sheet's
+ * state machine (the filter, the armed capture, the last refusal) — and this is the surface it
+ * draws into: the reactive scope the document reads, the four flags it discriminates on, and the
+ * mount that lives in the dialog layer until the flow takes it down.
+ *
+ * **The flow states facts; the surface derives what the document branches on.** Whether there is a
+ * registry at all, whether a filter matched anything, whether a refusal names a conflict — the flow
+ * answers each of those as a SENTENCE or an empty string, and `derive` turns "empty" into the case
+ * name. So no branch of the document is spelled twice.
+ *
+ * **Assistant is two islands.** `ui/ai-managed-connect.ts` and `ui/ai-credentials-form.ts` each own
+ * an element that three other credentials gates also embed, and a repaint of this sheet must never
+ * rebuild three fields a reader is typing into. So the document renders `managed-slot` and
+ * `creds-slot` empty and this module reports them through `onNodeCreated`, one `connectedCallback`
+ * earlier than awaiting the element would be — the island rule of studio-ui-guidelines.md §9.4.
+ *
+ * **Await the ELEMENT, not just the mount.** `mountSurface` resolving means the DOCUMENT rendered;
+ * a `jx-dialog`'s own template is one `connectedCallback` later, and `showModal` in between finds
+ * no `<dialog>` to open — the body is all there, correctly styled, and never shows. `whenReady` is
+ * shared with `surfaces/dialog.ts` rather than reimplemented.
+ *
+ * @docs studio/interface/preferences
+ */
+
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import { overlayRegion, REGION_ATTR } from "../ui/regions";
+import { close as closeDialog, showModal } from "@jxsuite/ui/behaviors/dialog";
+import { whenReady } from "./dialog";
+import preferencesDoc from "./preferences.json";
+import type { JxElement, JxDocument } from "@jxsuite/schema/types";
+import type { JxScope } from "@jxsuite/runtime/types";
+import type { SurfaceHandle } from "../ui/surface";
+
+registerSurface("preferences", preferencesDoc as unknown as JxDocument);
+
+/** One row of the section list. `current` is the string `aria-current` takes. */
+export interface PreferencesSectionRow {
+  id: string;
+  title: string;
+  current: string;
+}
+
+/** One segment of the theme control. `checked` is the string `aria-checked` takes. */
+export interface PreferencesThemeRow {
+  value: string;
+  label: string;
+  checked: string;
+}
+
+/** One button on an account row. */
+export interface PreferencesAccountAction {
+  /** `"<account>/<action>"` — what `onAccountAction` takes, so a click names both halves. */
+  key: string;
+  /** The action's own id, which the row carries as `data-action`. */
+  id: string;
+  label: string;
+  /** The kit's button variant; `"secondary"` for the default treatment. */
+  variant: string;
+}
+
+/** One stored credential, as the Accounts section draws it. Never the secret. */
+export interface PreferencesAccountRow {
+  id: string;
+  label: string;
+  detail: string;
+  actions: PreferencesAccountAction[];
+}
+
+/** One live binding. Every field is a string or a boolean the flow decided. */
+export interface PreferencesKeyRow {
+  /** The row's identity for the keyed map: a command with two chords has two rows. */
+  key: string;
+  commandId: string;
+  /** The chord as the platform prints it, or the invitation while this row is capturing. */
+  chord: string;
+  title: string;
+  /** This row is listening for the next chord. */
+  capturing: boolean;
+  /** The binding came from the author's layer, so there is something to reset. */
+  overridden: boolean;
+  /** What the change button reads: "Change", or "Cancel" while it is listening. */
+  changeLabel: string;
+  /** The change button's accessible name, which says WHICH shortcut it changes. */
+  changeName: string;
+  /** The reset button's accessible name. */
+  resetName: string;
+}
+
+/** One scope's worth of bindings, under the heading the reference gives that scope. */
+export interface PreferencesKeyGroup {
+  scope: string;
+  label: string;
+  rows: PreferencesKeyRow[];
+}
+
+/**
+ * What the flow knows. Not one field is a case name: the words are the flow's, and which of them
+ * add up to which branch is {@link derive}'s.
+ */
+export interface PreferencesView {
+  /** The showing section's id — the document's outermost discriminant. */
+  section: string;
+  sections: PreferencesSectionRow[];
+  sectionTitle: string;
+  sectionBlurb: string;
+  themes: PreferencesThemeRow[];
+  accounts: PreferencesAccountRow[];
+  /** Why there is no keyboard sheet at all. Empty means there is one. */
+  keyboardEmpty: string;
+  /** What the search field shows: typed text, or a captured chord as it prints. */
+  keyQuery: string;
+  /** What the keystroke toggle reads, which is also whether it is listening. */
+  keystrokeLabel: string;
+  capturingSearch: boolean;
+  /** The last refusal, verbatim from whoever raised it. Empty draws nothing. */
+  refusal: string;
+  /** "Show Redo" — the one thing that can be done about a conflict. Empty draws no button. */
+  conflictLabel: string;
+  /** Why the list is empty under the current filter. Empty means it is not. */
+  rowsEmpty: string;
+  groups: PreferencesKeyGroup[];
+}
+
+/** The two islands the Assistant section renders and does not fill. */
+export type PreferencesIsland = "managed" | "creds";
+
+export interface PreferencesSurfaceOptions {
+  /** Where the sheet is mounted — the dialog layer, handed in so this never reaches back. */
+  layer: HTMLElement;
+  /** What to draw before anything has changed: the flow's own view, so there is one builder. */
+  view: PreferencesView;
+  onSelectSection: (id: string) => void;
+  onSetTheme: (value: string) => void;
+  /** One account button was pressed, named by its `"<account>/<action>"` key. */
+  onAccountAction: (key: string) => void;
+  onKeyQuery: (value: string) => void;
+  onToggleKeystroke: () => void;
+  onToggleRebind: (commandId: string) => void;
+  onResetBinding: (commandId: string) => void;
+  onShowConflict: () => void;
+  /** A keydown inside the keyboard sheet, whatever it was. The flow decides if it is a chord. */
+  onCaptureKey: (event: KeyboardEvent) => void;
+  /** An island was created: the flow puts the surface it owns inside it. */
+  onIsland: (island: PreferencesIsland, host: HTMLElement) => void;
+  /** The sheet closed, for any reason the platform owns as well as this module's `close`. */
+  onClosed: () => void;
+}
+
+export interface PreferencesSurfaceHandle {
+  /** The slot in the dialog layer the document is mounted into. */
+  host: HTMLElement;
+  /** Resolves with the `jx-dialog` element once it has rendered and been opened. */
+  ready: Promise<HTMLElement>;
+  /** Redraw from the flow's current view. */
+  update: (view: PreferencesView) => void;
+  /** Close the dialog (the platform restores focus) and dispose the document. Idempotent. */
+  close: () => void;
+}
+
+/** What the document discriminates on. Derived here, never handed in. */
+interface PreferencesFlags {
+  /** `"none"` draws the reason instead of the whole sheet; `"keys"` draws the sheet. */
+  keyboardState: string;
+  /** `"empty"` draws the reason under the search box; `"rows"` draws the groups. */
+  rowsState: string;
+  hasRefusal: boolean;
+  hasConflict: boolean;
+}
+
+interface PreferencesScope extends Record<string, unknown>, PreferencesView, PreferencesFlags {
+  selectSection: (id: string) => void;
+  setTheme: (value: string) => void;
+  runAccountAction: (key: string) => void;
+  setKeyQuery: (value: string) => void;
+  toggleKeystroke: () => void;
+  toggleRebind: (commandId: string) => void;
+  resetBinding: (commandId: string) => void;
+  showConflict: () => void;
+  capture: (scope: JxScope, event: Event) => void;
+  closed: () => void;
+}
+
+/** The view plus the four flags the document branches on. */
+function derive(view: PreferencesView): PreferencesView & PreferencesFlags {
+  return {
+    ...view,
+    hasConflict: view.conflictLabel !== "",
+    hasRefusal: view.refusal !== "",
+    keyboardState: view.keyboardEmpty === "" ? "keys" : "none",
+    rowsState: view.rowsEmpty === "" ? "rows" : "empty",
+  };
+}
+
+/** The `part` a node's definition carries, or `""` for a text node or an unmarked element. */
+function partOf(def: JxElement | string): string {
+  const part = typeof def === "string" ? undefined : def.attributes?.["part"];
+  return typeof part === "string" ? part : "";
+}
+
+/**
+ * Open Preferences. The handle's `ready` resolves once the sheet is showing.
+ *
+ * @param options What to draw, and every decision a control can ask the flow for.
+ * @returns The handle the flow updates and closes.
+ */
+export function openPreferencesSurface(
+  options: PreferencesSurfaceOptions,
+): PreferencesSurfaceHandle {
+  const slot = document.createElement("div");
+  /* The layer is `pointer-events: none` so a click passes through it when nothing is up, and every
+     slot in it turns them back on for its own content. `pointer-events` INHERITS, and the top layer
+     changes paint order rather than inheritance, so a modal `<dialog>` in a slot that skipped this
+     is painted above everything and hit-tests to nothing. */
+  slot.style.pointerEvents = "auto";
+  options.layer.append(slot);
+
+  let closed = false;
+  /**
+   * Say it is over, once.
+   *
+   * Two paths reach here and either may be first: the platform's own `close`, which `close()`
+   * provokes, and `close()` on a sheet that never got as far as being shown.
+   */
+  const finish = (): void => {
+    if (closed) {
+      return;
+    }
+    closed = true;
+    options.onClosed();
+  };
+
+  const scope = reactive({
+    ...derive(options.view),
+    capture: (_scope: JxScope, event: Event) => {
+      options.onCaptureKey(event as KeyboardEvent);
+    },
+    closed: finish,
+    resetBinding: (commandId: string) => {
+      options.onResetBinding(commandId);
+    },
+    runAccountAction: (key: string) => {
+      options.onAccountAction(key);
+    },
+    selectSection: (id: string) => {
+      options.onSelectSection(id);
+    },
+    setKeyQuery: (value: string) => {
+      /* What the control now holds, first and unconditionally. A binding only writes when the
+         scope CHANGES, so a surface that decided a query without announcing the raw one would
+         leave the field showing something the scope does not have (§9.3). */
+      scope.keyQuery = value;
+      options.onKeyQuery(value);
+    },
+    setTheme: (value: string) => {
+      options.onSetTheme(value);
+    },
+    showConflict: () => {
+      options.onShowConflict();
+    },
+    toggleKeystroke: () => {
+      options.onToggleKeystroke();
+    },
+    toggleRebind: (commandId: string) => {
+      options.onToggleRebind(commandId);
+    },
+  }) as PreferencesScope;
+
+  let mounted: SurfaceHandle | null = null;
+  const ready = mountSurface("preferences", scope, slot, {
+    onNodeCreated: (element, _path, def) => {
+      if (!(element instanceof HTMLElement)) {
+        return;
+      }
+      const part = partOf(def);
+      if (part === "managed-slot") {
+        options.onIsland("managed", element);
+      } else if (part === "creds-slot") {
+        options.onIsland("creds", element);
+      }
+    },
+  }).then(async (surface) => {
+    mounted = surface;
+    const element = surface.root as HTMLElement;
+    if (closed) {
+      surface.dispose();
+      return element;
+    }
+    await whenReady(element);
+    if (closed) {
+      return element;
+    }
+    /* The region goes on the platform's own `<dialog>`, which is the one element here that HAS a
+       box: `jx-dialog` is `display: contents`, and the slot wraps a dialog the top layer takes out
+       of flow, so both measure 0×0 — and a region whose box is empty is refused outright by
+       `scripts/screenshots/lib/shot.ts`. The kit treats that node as a seam already; its own
+       behaviour sidecar finds it by exactly this selector. */
+    const box = element.querySelector<HTMLElement>('dialog[part="dialog"]') ?? element;
+    box.setAttribute(REGION_ATTR, overlayRegion("dialog", "preferences"));
+    showModal(element);
+    return element;
+  });
+
+  return {
+    close() {
+      /* Guarded on the WORK rather than on `closed`, and the difference is a slot that would
+         otherwise be left behind: the platform's own `close` runs `finish()` before any caller
+         reaches here, so a `close()` that returned early on `closed` would take the sheet down and
+         leave its host div in the layer. Every line below is idempotent instead. */
+      const element = mounted?.root;
+      if (element instanceof HTMLElement) {
+        // The platform's close first, so focus goes back where it came from; then the document.
+        closeDialog(element);
+      }
+      // A mount that has not landed yet is disposed by `ready` when it does — `finish` tells it so.
+      mounted?.dispose();
+      mounted = null;
+      slot.remove();
+      finish();
+    },
+    host: slot,
+    ready,
+    update(view) {
+      Object.assign(scope, derive(view));
+    },
+  };
+}

package/src/surfaces/progress-modal.json

@@ -0,0 +1,110 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioProgressModal",
+  "$description": "The one surface in Studio that blocks while it works: the operation's name, a spinner, the line under it, and the two ways out. A `jx-dialog`, so the platform owns modality, the backdrop, focus restoration and Escape — which is what retired the `sp-underlay` this surface used to paint beside itself, and with it the fixed box, the panel, the shadow and the `z-index: 1000` that box needed to climb back out from under its own scrim. The two answers are the dialog's own: confirm is `Run in the background`, which stops the BLOCKING and leaves the work running in Activity, and the secondary answer is Cancel, drawn only when the operation handed one over. It is the secondary rather than the cancel answer for a reason that is behavioural, not cosmetic: the platform raises one `cancel` for Escape, for a light dismissal and for the cancel button alike, and a surface that cannot tell them apart would stop a dependency install on a keystroke. Escape therefore means what confirm means — stop blocking, not stop working — and the answer that stops the work is a button and only a button.",
+  "tagName": "jx-dialog",
+  "$props": {
+    "headline": {
+      "$ref": "#/state/title"
+    },
+    "confirmLabel": "Run in the background",
+    "secondaryLabel": {
+      "$ref": "#/state/cancelLabel"
+    },
+    "cancelLabel": "",
+    "size": "sm"
+  },
+  "attributes": {
+    "part": "progress"
+  },
+  "onconfirm": {
+    "$prototype": "Function",
+    "body": [
+      {
+        "operator": "call",
+        "target": {
+          "$ref": "#/state/background"
+        },
+        "value": []
+      }
+    ]
+  },
+  "onsecondary": {
+    "$prototype": "Function",
+    "body": [
+      {
+        "operator": "call",
+        "target": {
+          "$ref": "#/state/cancel"
+        },
+        "value": []
+      }
+    ]
+  },
+  "oncancel": {
+    "$prototype": "Function",
+    "body": [
+      {
+        "operator": "call",
+        "target": {
+          "$ref": "#/state/background"
+        },
+        "value": []
+      }
+    ]
+  },
+  "onclose": {
+    "$prototype": "Function",
+    "body": [
+      {
+        "operator": "call",
+        "target": {
+          "$ref": "#/state/closed"
+        },
+        "value": []
+      }
+    ]
+  },
+  "style": {
+    "$description": "What is left once `jx-dialog` has drawn the dialog. `.progress-modal` is gone rather than moved — it positioned a fixed box, painted its panel, border, radius and shadow, capped its height and then lifted itself above the scrim it rendered beside — and a modal `<dialog>` in the top layer is every one of those. `.progress-title` went the same way: the operation's name is the dialog's headline, which is also its accessible name, so nothing here draws a title.",
+    "& [part=\"row\"]": {
+      "display": "flex",
+      "alignItems": "center",
+      "gap": "var(--jx-space-4)"
+    },
+    "& [part=\"status\"]": {
+      "$description": "`anywhere`, because a status line is usually a path or a package spec with no space in it, and one of those would otherwise be the thing that decides how wide the dialog is. `min-width: 0` is what lets it wrap at all: a flex item's automatic minimum is its content, so without this the row refuses to shrink and the text overflows instead.",
+      "minWidth": "0",
+      "color": "var(--fg-dim)",
+      "fontSize": "var(--jx-text-md)",
+      "overflowWrap": "anywhere"
+    }
+  },
+  "children": [
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "row"
+      },
+      "children": [
+        {
+          "tagName": "jx-spinner",
+          "attributes": {
+            "part": "busy"
+          },
+          "$props": {
+            "size": "lg"
+          }
+        },
+        {
+          "tagName": "span",
+          "attributes": {
+            "part": "status",
+            "aria-live": "polite"
+          },
+          "textContent": "${state.status}"
+        }
+      ]
+    }
+  ]
+}

package/src/surfaces/progress-modal.ts

@@ -0,0 +1,150 @@
+/// <reference lib="dom" />
+/**
+ * The blocking progress surface: a `jx-dialog` mounted into the modal layer and opened modally.
+ *
+ * This is the adapter. `ui/progress-modal.ts` keeps the flow — the Activity entry the operation is
+ * recorded in, what a failure does to Problems, which of the two exits hands the app back — and
+ * hands this module a projection: a title, a status line, and whether the operation can be stopped.
+ * The document renders that; the platform's `<dialog>` owns modality, the backdrop, focus
+ * restoration and Escape.
+ *
+ * Nothing here traps Tab, focuses the first control or paints a scrim, and that is the whole
+ * substance of the conversion rather than a tidy-up. The lit version was a card beside an
+ * `<sp-underlay>` in a slot that ran a keydown listener; the scrim painted at `z-index: 1` and the
+ * card at `auto`, so `Run in the background` — the only way out of a running install — was visible
+ * through the scrim and could not be clicked. A modal `<dialog>` is in the top layer by
+ * construction, so there is no stacking left to get wrong.
+ *
+ * @docs studio/interface
+ */
+
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import { overlayRegion, REGION_ATTR } from "../ui/regions";
+import { close as closeDialog, showModal } from "@jxsuite/ui/behaviors/dialog";
+import { whenReady } from "./dialog";
+import progressDoc from "./progress-modal.json";
+import type { SurfaceHandle } from "../ui/surface";
+import type { JxDocument } from "@jxsuite/schema/types";
+
+registerSurface("progress-modal", progressDoc as unknown as JxDocument);
+
+/** What the flow hands the surface. Everything is a projection; the flow keeps the operation. */
+export interface ProgressSurfaceOptions {
+  /** Where the dialog is mounted — the modal layer, handed in so this module never reaches back. */
+  layer: HTMLElement;
+  /** The operation's name, which the dialog draws as its headline and its accessible name. */
+  title: string;
+  /** The line under it, which is also the surface's live region. */
+  status: string;
+  /**
+   * The operation handed over a way to stop it, so a Cancel answer is drawn.
+   *
+   * Absent means it genuinely cannot be stopped and no button claims otherwise — but the confirm
+   * answer is offered regardless, because "let me use the app" is a promise this surface can always
+   * keep.
+   */
+  cancellable: boolean;
+  /** Stop blocking and keep working. The confirm button and Escape both mean this. */
+  onBackground: () => void;
+  /** Stop the work. Reachable only when `cancellable`. */
+  onCancel: () => void;
+  /** The dialog closed, for any reason the platform owns as well as this module's `close`. */
+  onClosed: () => void;
+}
+
+export interface ProgressSurfaceHandle {
+  /** The slot in the modal layer that carries the region. */
+  host: HTMLElement;
+  /** Resolves with the `jx-dialog` element once it has rendered and been opened. */
+  ready: Promise<HTMLElement>;
+  /** Rewrite the status line. A no-op once the dialog is gone. */
+  setStatus: (text: string) => void;
+  /** Close the dialog (the platform restores focus) and dispose the document. Idempotent. */
+  close: () => void;
+}
+
+interface ProgressScope extends Record<string, unknown> {
+  title: string;
+  status: string;
+  /**
+   * The secondary answer's label, empty for none — which is how "this cannot be stopped" is said.
+   *
+   * It is the SECONDARY answer rather than the cancel one because the platform raises a single
+   * `cancel` for Escape, for a light dismissal and for a cancel button alike. A surface that cannot
+   * tell those apart would stop a dependency install on a keystroke, and Escape here has always
+   * meant stop blocking rather than stop working.
+   */
+  cancelLabel: string;
+  background: () => void;
+  cancel: () => void;
+  closed: () => void;
+}
+
+/** Open the progress dialog. The handle's `ready` resolves once it is showing. */
+export function openProgressSurface(options: ProgressSurfaceOptions): ProgressSurfaceHandle {
+  const slot = document.createElement("div");
+  /* The layer is `pointer-events: none` so a click passes through it when nothing is up, and every
+     slot in it turns them back on for its own content. */
+  slot.style.pointerEvents = "auto";
+  slot.setAttribute(REGION_ATTR, overlayRegion("modal", "progress"));
+  options.layer.append(slot);
+
+  let closed = false;
+  const scope = reactive<ProgressScope>({
+    background: () => {
+      options.onBackground();
+    },
+    cancel: () => {
+      options.onCancel();
+    },
+    cancelLabel: options.cancellable ? "Cancel" : "",
+    closed: () => {
+      options.onClosed();
+    },
+    status: options.status,
+    title: options.title,
+  }) as ProgressScope;
+
+  let mounted: SurfaceHandle | null = null;
+  const ready = mountSurface("progress-modal", scope, slot).then(async (surface) => {
+    const element = surface.root as HTMLElement;
+    if (closed) {
+      surface.dispose();
+      return element;
+    }
+    mounted = surface;
+    /* `whenReady` before `showModal`, and it is not belt and braces: the mount resolving means the
+       DOCUMENT rendered, while the element's OWN template is one `connectedCallback` later.
+       `showModal` in between finds no `<dialog>` to open, and the surface never shows. */
+    await whenReady(element);
+    if (closed) {
+      return element;
+    }
+    showModal(element);
+    return element;
+  });
+
+  return {
+    close() {
+      if (closed) {
+        return;
+      }
+      closed = true;
+      const element = mounted?.root;
+      if (element instanceof HTMLElement) {
+        // The platform's close first, so focus goes back where it came from; then the document.
+        closeDialog(element);
+      }
+      // A mount that has not landed yet is disposed by `ready` when it does.
+      mounted?.dispose();
+      mounted = null;
+      slot.remove();
+    },
+    host: slot,
+    ready,
+    setStatus(text: string) {
+      scope.status = text;
+    },
+  };
+}