@jxsuite/studio 4.0.0 → 5.0.0

package/src/surfaces/jump-bar.ts

@@ -0,0 +1,129 @@
+/// <reference lib="dom" />
+/**
+ * ⑥ The jump bar, as a Jx document over the kit — the mount seam, and nothing else.
+ *
+ * `jump-bar.json` is the markup, the ARIA and the style; `panels/jump-bar.ts` is the flow — which
+ * pane this bar is about, what its address is, which of its steps the registry can actually run,
+ * and what a chevron opens. This module is the seam between them: one scope per pane, one document
+ * mounted into that pane's cell, and an `update()` that ASSIGNS rather than re-mounts.
+ *
+ * **One mount per pane, not one per bar.** Two cells draw two addresses, so `attachJumpBarHost`
+ * hands this module a host per pane and gets a handle back. The scope is reactive, so a repaint is
+ * an assignment to `segments` and the keyed `$map` reconciles: a step whose key survives keeps its
+ * node, and the chevron the reader is aiming at does not move under them.
+ *
+ * **The bar hides rather than un-mounts when a pane has no address.** A pane with no tab open has
+ * no address to print, and the document's own `hidden` is what takes it off the screen — the mount
+ * stays, because the next tab open is one assignment away and re-mounting would cost a frame of
+ * blank chrome. The stage's `--jump-bar-h` offset is written by the flow, which is the one number
+ * this surface and its stylesheet-free document share.
+ *
+ * @docs studio/interface
+ */
+
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import jumpBarDoc from "./jump-bar.json";
+import type { JxDocument } from "@jxsuite/schema/types";
+import type { SurfaceHandle } from "../ui/surface";
+
+registerSurface("jump-bar", jumpBarDoc as unknown as JxDocument);
+
+/**
+ * One step of the address, as the document reads it.
+ *
+ * Every field is present on every step whatever its `control`, because a binding renders a value
+ * and a `$switch` chooses on one: a step that omitted `title` would leave the readout case reading
+ * an absent path.
+ */
+export interface ProjectedStep extends Record<string, unknown> {
+  /** Unique within one bar: the repeater's key, and the argument `run` and `choose` receive. */
+  key: string;
+  /** `project` | `file` | `editor` | `node` — stamped so a test names a step without its text. */
+  kind: string;
+  label: string;
+  /** The step's own context, then the command's title and chord. */
+  title: string;
+  /** `button` when the registry can run the step's command, `readout` when it cannot. */
+  control: "button" | "readout";
+  /** A button whose command is registered but refuses right now; its reason is in the title. */
+  disabled: boolean;
+  /** The leaf: where you are. Marked, never un-controlled. */
+  current: boolean;
+  /** The first step draws no separator before it. */
+  leading: boolean;
+  /** More than one place to go. One alternative is not a choice and renders no chevron. */
+  hasChoices: boolean;
+  /** The chevron's accessible name and tooltip. */
+  altsLabel: string;
+}
+
+/** What a gesture on the bar asks of the flow. Read once, when the scope is made. */
+export interface JumpBarActions {
+  /** A step was pressed: run the command it names, with its args. */
+  run: (key: string) => void;
+  /** A chevron was pressed: open that step's siblings, hanging under the control that was hit. */
+  choose: (key: string, anchor: HTMLElement | null) => void;
+}
+
+export interface JumpBarSurface {
+  /** Bring the standing document up to date. An assignment; the mount is never rebuilt. */
+  update: (steps: readonly ProjectedStep[]) => void;
+  /** Take the document down. Idempotent. */
+  dispose: () => void;
+}
+
+/** The scope `jump-bar.json` reads. */
+interface JumpBarScope extends Record<string, unknown>, JumpBarActions {
+  region: string;
+  segments: ProjectedStep[];
+  empty: boolean;
+}
+
+/**
+ * Mount one pane's bar into the host its cell built for it.
+ *
+ * The host is CLEARED first: a cell hands the bar a slot of its own, and whatever was in it belongs
+ * to a pane this bar is no longer drawing.
+ *
+ * @param {HTMLElement} host The cell's slot for the bar.
+ * @param {string} region The `data-jx-region` the bar stamps on itself — `pane.<id>/jump`.
+ * @param {JumpBarActions} actions What a press does. Read once, when the scope is made.
+ * @returns {JumpBarSurface}
+ */
+export function mountJumpBarSurface(
+  host: HTMLElement,
+  region: string,
+  actions: JumpBarActions,
+): JumpBarSurface {
+  const scope = reactive<JumpBarScope>({
+    ...actions,
+    empty: true,
+    region,
+    segments: [],
+  }) as JumpBarScope;
+
+  host.replaceChildren();
+  let mounted: SurfaceHandle | null = null;
+  let disposed = false;
+  void mountSurface("jump-bar", scope, host).then((surface) => {
+    if (disposed) {
+      surface.dispose();
+      return;
+    }
+    mounted = surface;
+  });
+
+  return {
+    dispose() {
+      disposed = true;
+      mounted?.dispose();
+      mounted = null;
+      host.replaceChildren();
+    },
+    update(steps) {
+      scope.segments = [...steps];
+      scope.empty = steps.length === 0;
+    },
+  };
+}

package/src/surfaces/jxsuite-update.json

@@ -0,0 +1,146 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioJxsuiteUpdate",
+  "$description": "The on-open offer to bring a project's `@jxsuite/*` dependencies up to their newest published versions: one sentence, and the packages that would move. A `jx-dialog`, so the platform owns modality, Escape, focus restoration and the backdrop, and the kit draws both answers. Nothing here asks the registry or writes a manifest: `packages/jxsuite-update.ts` keeps the lookup, the dismissal key and the install, and this document only says what is on offer.",
+  "tagName": "jx-dialog",
+  "$props": {
+    "headline": "Update @jxsuite packages?",
+    "confirmLabel": "Update",
+    "cancelLabel": "Not now",
+    "size": "sm"
+  },
+  "attributes": {
+    "part": "jxsuite-update"
+  },
+  "onconfirm": {
+    "$prototype": "Function",
+    "body": [
+      {
+        "operator": "call",
+        "target": {
+          "$ref": "#/state/confirm"
+        },
+        "value": []
+      }
+    ]
+  },
+  "oncancel": {
+    "$prototype": "Function",
+    "body": [
+      {
+        "operator": "call",
+        "target": {
+          "$ref": "#/state/cancel"
+        },
+        "value": []
+      }
+    ]
+  },
+  "onclose": {
+    "$prototype": "Function",
+    "body": [
+      {
+        "operator": "call",
+        "target": {
+          "$ref": "#/state/closed"
+        },
+        "value": []
+      }
+    ]
+  },
+  "style": {
+    "$description": "The old body was a lit template with no stylesheet at all, which is why the conversion is mostly a deletion. Two `<br />`s stood in for a paragraph break, and one `<span style=\"white-space: pre-line\">` held every package as a single `\\n`-joined string — a list spelled as whitespace. Neither is addressable and neither announces as what it is, so a screen reader read one run-on line and a test could only match a substring of it. It is a `<ul>` of keyed rows now: the list says how many packages there are, and each row is `[data-package]`. The one token repair travels with it — that span asked for `--spectrum-font-size-75`, which resolves only inside `<sp-theme>`, and a document mounted in the dialog layer is outside it, so the size silently fell back to the hard-coded `12px` written beside it.",
+    "& [part=\"offer\"]": {
+      "display": "flex",
+      "flexDirection": "column",
+      "gap": "var(--jx-space-3)"
+    },
+    "& [part=\"lede\"]": {
+      "margin": "0"
+    },
+    "& [part=\"list\"]": {
+      "$description": "Capped and scrolling, because the count is the registry's rather than this dialog's: a project that has not been opened in a year can have every `@jxsuite/*` package behind at once, and a dialog that grows past the viewport puts its own Update button off screen.",
+      "listStyle": "none",
+      "margin": "0",
+      "padding": "0",
+      "display": "flex",
+      "flexDirection": "column",
+      "gap": "var(--jx-space-1)",
+      "maxHeight": "240px",
+      "overflowY": "auto"
+    },
+    "& [part=\"package\"]": {
+      "display": "flex",
+      "justifyContent": "space-between",
+      "alignItems": "baseline",
+      "gap": "var(--jx-space-3)",
+      "fontSize": "var(--jx-text-sm)"
+    },
+    "& [part=\"package-name\"]": {
+      "color": "var(--fg)"
+    },
+    "& [part=\"package-move\"]": {
+      "$description": "Tabular figures, so a column of versions does not jitter between rows of different widths.",
+      "color": "var(--fg-dim)",
+      "fontVariantNumeric": "tabular-nums",
+      "whiteSpace": "nowrap"
+    }
+  },
+  "children": [
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "offer"
+      },
+      "children": [
+        {
+          "tagName": "p",
+          "attributes": {
+            "part": "lede"
+          },
+          "textContent": "Newer versions of these packages have been published. Update the project to them?"
+        },
+        {
+          "tagName": "ul",
+          "attributes": {
+            "part": "list"
+          },
+          "children": [
+            {
+              "$prototype": "Array",
+              "items": {
+                "$ref": "#/state/packages"
+              },
+              "key": {
+                "$ref": "$map/item/name"
+              },
+              "map": {
+                "tagName": "li",
+                "attributes": {
+                  "part": "package",
+                  "data-package": "${$map.item.name}"
+                },
+                "children": [
+                  {
+                    "tagName": "span",
+                    "attributes": {
+                      "part": "package-name"
+                    },
+                    "textContent": "${$map.item.name}"
+                  },
+                  {
+                    "tagName": "span",
+                    "attributes": {
+                      "part": "package-move"
+                    },
+                    "textContent": "${$map.item.current} → ${$map.item.target}"
+                  }
+                ]
+              }
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/src/surfaces/jxsuite-update.ts

@@ -0,0 +1,149 @@
+/// <reference lib="dom" />
+/**
+ * The "newer @jxsuite packages are available" offer, as a mounted document.
+ *
+ * `packages/jxsuite-update.ts` is the flow — it asks the registry which packages are behind their
+ * own newest publish, remembers a decline against the exact set of versions declined, and runs the
+ * install behind a progress modal — and this is the surface it draws into: the rows, the two
+ * answers, and a mount that lives in the dialog layer until the flow takes it down.
+ *
+ * **The range operator is the flow's, not the document's.** A row arrives with `target` already
+ * spelled `^1.4.0`, because the same string is what `setPackageVersions` writes into the manifest:
+ * a document that composed the caret itself would be a second author of the range, and the two
+ * could disagree about what Update was going to do. The arrow between the two versions IS the
+ * document's — that is markup around two facts rather than a third fact.
+ *
+ * **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/projects/dependencies
+ */
+
+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 jxsuiteUpdateDoc from "./jxsuite-update.json";
+import type { SurfaceHandle } from "../ui/surface";
+import type { JxDocument } from "@jxsuite/schema/types";
+
+registerSurface("jxsuite-update", jxsuiteUpdateDoc as unknown as JxDocument);
+
+/** One package the offer would move. Every field is already the string the row prints. */
+export interface JxsuiteUpdateRow {
+  /** The package name, which is also the row's key and its `data-package`. */
+  name: string;
+  /** The range the manifest pins today, e.g. `^1.2.0`. */
+  current: string;
+  /** The range Update would write, caret included — the flow's own spelling of it. */
+  target: string;
+}
+
+export interface JxsuiteUpdateSurfaceOptions {
+  /** Where the dialog is mounted — the dialog layer, handed in so this never reaches back. */
+  layer: HTMLElement;
+  /** The packages on offer, in the order the flow found them. */
+  packages: JxsuiteUpdateRow[];
+  /** Update, please. */
+  onConfirm: () => void;
+  /** Not now — the Cancel button, or Escape. */
+  onCancel: () => void;
+  /** The dialog closed, for any reason the platform owns as well as this module's `close`. */
+  onClosed: () => void;
+}
+
+export interface JxsuiteUpdateSurfaceHandle {
+  /** The slot in the dialog layer that carries the region. */
+  host: HTMLElement;
+  /** Resolves with the `jx-dialog` element once it has rendered and been opened. */
+  ready: Promise<HTMLElement>;
+  /** Close the dialog (the platform restores focus) and dispose the document. Idempotent. */
+  close: () => void;
+}
+
+interface JxsuiteUpdateScope extends Record<string, unknown> {
+  packages: JxsuiteUpdateRow[];
+  confirm: () => void;
+  cancel: () => void;
+  closed: () => void;
+}
+
+/** Open the offer. The handle's `ready` resolves once the dialog is showing. */
+export function openJxsuiteUpdateSurface(
+  options: JxsuiteUpdateSurfaceOptions,
+): JxsuiteUpdateSurfaceHandle {
+  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";
+  slot.setAttribute(REGION_ATTR, overlayRegion("dialog", "jxsuite-update"));
+  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` event, which `close()`
+   * provokes, and `close()` on a dialog that never got as far as being shown.
+   */
+  const finish = (): void => {
+    if (closed) {
+      return;
+    }
+    closed = true;
+    options.onClosed();
+  };
+
+  const scope = reactive<JxsuiteUpdateScope>({
+    cancel: () => {
+      options.onCancel();
+    },
+    closed: finish,
+    confirm: () => {
+      options.onConfirm();
+    },
+    packages: options.packages,
+  }) as JxsuiteUpdateScope;
+
+  let mounted: SurfaceHandle | null = null;
+  const ready = mountSurface("jxsuite-update", scope, slot).then(async (surface) => {
+    mounted = surface;
+    const element = surface.root as HTMLElement;
+    if (closed) {
+      surface.dispose();
+      return element;
+    }
+    await whenReady(element);
+    if (closed) {
+      return element;
+    }
+    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 dialog 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,
+  };
+}