@jxsuite/studio 6.1.0 → 6.1.2

package/src/ui/formula-chips.ts

@@ -13,28 +13,42 @@
  * set. The lit drawing lives beside its one remaining caller in `ui/expression-editor.ts` and dies
  * with that conversion; nothing here has to be touched when it does.
  *
- * The preview is taken structurally (`{ values }`) rather than as a named type, because the two
- * callers hold two spellings of the same record — `EditorPreview` and `services/preview-eval.ts`'s
- * `ExpressionPreview` — and a chip only ever reads one field of it.
+ * The preview is taken structurally (`{ values }`) rather than as `services/preview-eval.ts`'s
+ * `ExpressionPreview`, because a chip only ever reads that one field of it.
  */
 
-import { isJsonObject, isRef } from "@jxsuite/schema/guards";
+import { isJsonObject, isRef, isString } from "@jxsuite/schema/guards";
+import type { JxDocumentValue } from "@jxsuite/schema/types";
 
 type NodePath = (string | number)[];
 
+/**
+ * A value of an expression tree: anything a document holds, or a node an editor rebuilt from one.
+ *
+ * The rebuilt half is why this is not just `JxDocumentValue`. Replacing one operand spreads the
+ * node it sits in, and a member the source node lacked can come through as `undefined` (a blank
+ * node's `target`); it serializes away, and until then `"target" in node` still sees the key.
+ */
+export type ExpressionValue = JxDocumentValue | ExpressionFields | ExpressionValue[];
+
+/** An expression node's members by name — `operator`, `target`, `value`, `cases`, … */
+export interface ExpressionFields {
+  [key: string]: ExpressionValue | undefined;
+}
+
 /** What a chip needs to know about the live evaluation: display strings keyed by node path. */
 export interface ChipPreview {
   values: Map<string, string>;
 }
 
 interface ChainLink {
-  node: Record<string, unknown>;
+  node: ExpressionFields;
   path: NodePath;
 }
 
 interface Chain {
   /** The innermost target operand (ref/literal), absent for target-less roots. */
-  head: { value: unknown; path: NodePath } | null;
+  head: { value: ExpressionValue | undefined; path: NodePath } | null;
   /** Operator nodes, deepest target first → outermost operator last. */
   links: ChainLink[];
 }
@@ -60,8 +74,8 @@ export interface FormulaChip {
   group: boolean;
 }
 
-function isExprNode(value: unknown): value is Record<string, unknown> {
-  return isJsonObject(value) && typeof value.operator === "string";
+function isExprNode(value: ExpressionValue | undefined): value is ExpressionFields {
+  return isJsonObject(value) && isString(value.operator);
 }
 
 /** Human label for a pointer ref: strips the #/state/ and window#/ prefixes. */
@@ -76,14 +90,14 @@ function refLabel(ref: string): string {
 }
 
 /** Compact label for a non-node operand (ref or literal). */
-function operandLabel(value: unknown): string {
+function operandLabel(value: ExpressionValue | undefined): string {
   if (isRef(value)) {
     return refLabel(value.$ref);
   }
   if (isExprNode(value)) {
     return `(${chipSummary(value)})`;
   }
-  if (typeof value === "string") {
+  if (isString(value)) {
     return JSON.stringify(value);
   }
   return String(value);
@@ -95,10 +109,10 @@ function targetPath(basePath: NodePath, hops: number): NodePath {
 }
 
 /** Unroll a node's target chain into head operand + operator links (deepest first). */
-function unrollChain(node: Record<string, unknown>, basePath: NodePath): Chain {
+function unrollChain(node: ExpressionFields, basePath: NodePath): Chain {
   // Collect the chain root-first, then materialize each link's path from its descent depth.
-  const nodes: Record<string, unknown>[] = [];
-  let current: Record<string, unknown> = node;
+  const nodes: ExpressionFields[] = [];
+  let current: ExpressionFields = node;
   for (;;) {
     nodes.push(current);
     const next = current.target;
@@ -109,8 +123,9 @@ function unrollChain(node: Record<string, unknown>, basePath: NodePath): Chain {
     }
   }
   const deepest = nodes.at(-1)!;
+  // Reading an absent key yields undefined, so `in` alone decides whether a head operand exists.
   const head: Chain["head"] =
-    "target" in deepest || deepest.target !== undefined
+    "target" in deepest
       ? { path: targetPath(basePath, nodes.length), value: deepest.target }
       : null;
   const rootFirst = nodes.map((n, i) => ({ node: n, path: targetPath(basePath, i) }));
@@ -118,7 +133,7 @@ function unrollChain(node: Record<string, unknown>, basePath: NodePath): Chain {
 }
 
 /** Compact one-line text form of a node: head operand followed by the operator chain. */
-export function chipSummary(node: unknown): string {
+export function chipSummary(node: ExpressionValue | undefined): string {
   if (!isExprNode(node)) {
     return operandLabel(node);
   }
@@ -155,7 +170,7 @@ function chip(
 /** Group chips for a link's non-target expression operands (value / initial / cases / default). */
 function groupChips(link: ChainLink, preview: ChipPreview | null | undefined): FormulaChip[] {
   const chips: FormulaChip[] = [];
-  const add = (operand: unknown, path: NodePath) => {
+  const add = (operand: ExpressionValue | undefined, path: NodePath) => {
     if (isExprNode(operand)) {
       chips.push(chip(`(${chipSummary(operand)})`, path, preview, true));
     }
@@ -185,13 +200,13 @@ function groupChips(link: ChainLink, preview: ChipPreview | null | undefined): F
  * strip of no chips and no strip at all are the same thing on screen, and saying it here keeps both
  * drawings from having to decide.
  *
- * @param {unknown} node The expression node to read.
+ * @param {ExpressionValue | undefined} node The expression node to read.
  * @param {{ preview?: ChipPreview | null; path?: NodePath }} [opts] The live evaluation, and the
  *   document position `node` sits at — every chip path is prefixed with it.
  * @returns {FormulaChip[]}
  */
 export function formulaChipStrip(
-  node: unknown,
+  node: ExpressionValue | undefined,
   opts: { preview?: ChipPreview | null; path?: NodePath } = {},
 ): FormulaChip[] {
   if (!isExprNode(node)) {

package/src/ui/layers.ts

@@ -12,7 +12,8 @@
  * array and owns exactly two things that array does not: the timer that retires a resting toast,
  * and the transition account {@link overlayIdleBlockers} publishes.
  */
-import { render as litRender, nothing } from "lit-html";
+import { isFunction, isString } from "@jxsuite/schema/guards";
+import { render, nothing } from "lit-html";
 import { overlayRegion, REGION_ATTR } from "./regions";
 import { openDialogSurface } from "../surfaces/dialog";
 import { mountSurface, registerSurface } from "./surface";
@@ -21,20 +22,20 @@ import { dismiss, toasts } from "../services/notify";
 import { activeRegistry } from "../commands/active-registry";
 import { runReported } from "../commands/run-reported";
 import { effect, effectScope, reactive } from "../reactivity";
-import type { DialogChoiceOption, DialogSurfaceOptions } from "../surfaces/dialog";
+import type { DialogSurfaceOptions } from "../surfaces/dialog";
 import type { Notification, Severity } from "../services/notify";
 import type { EffectScope } from "@vue/reactivity";
-import type { SurfaceHandle } from "./surface";
-import type { JxDocument } from "@jxsuite/schema/types";
+import type { SurfaceHandle, SurfaceOption } from "./surface";
 import type { TemplateResult } from "lit-html";
 
 /** The four fixed layer hosts, by name. Also the `kind` half of every overlay region id. */
 export type LayerKind = "popover" | "modal" | "dialog" | "toast";
 
-let _popoverLayer: HTMLElement;
-let _modalLayer: HTMLElement;
-let _dialogLayer: HTMLElement;
-let _toastLayer: HTMLElement;
+/* Null until `initLayers()` runs, and still null afterwards for a page without that host element. */
+let _popoverLayer: HTMLElement | null = null;
+let _modalLayer: HTMLElement | null = null;
+let _dialogLayer: HTMLElement | null = null;
+let _toastLayer: HTMLElement | null = null;
 
 /**
  * The host a layer kind renders into, falling back to `<body>` before `initLayers()` has run.
@@ -52,14 +53,15 @@ export function layerHost(kind: LayerKind): HTMLElement {
         : kind === "toast"
           ? _toastLayer
           : _dialogLayer;
-  return host || document.body;
+  return host ?? document.body;
 }
 
 export function initLayers() {
-  _popoverLayer = document.querySelector("#layer-popover") as HTMLElement;
-  _modalLayer = document.querySelector("#layer-modal") as HTMLElement;
-  _dialogLayer = document.querySelector("#layer-dialog") as HTMLElement;
-  _toastLayer = document.querySelector("#layer-toast") as HTMLElement;
+  // The four hosts are `<div>`s in the shell frame (`src/shell/tree.ts`).
+  _popoverLayer = document.querySelector<HTMLElement>("#layer-popover");
+  _modalLayer = document.querySelector<HTMLElement>("#layer-modal");
+  _dialogLayer = document.querySelector<HTMLElement>("#layer-dialog");
+  _toastLayer = document.querySelector<HTMLElement>("#layer-toast");
   mountToastHost();
 }
 
@@ -214,12 +216,12 @@ export function showSaveDiscardDialog(
 function messageOptions(
   message: string | TemplateResult,
 ): Pick<DialogSurfaceOptions, "message" | "island"> {
-  if (typeof message === "string") {
+  if (isString(message)) {
     return { message };
   }
   return {
     island: (host) => {
-      litRender(message, host);
+      render(message, host);
     },
   };
 }
@@ -344,8 +346,8 @@ export function showPromptDialog(
    * still refuses, because `confirm()` runs `check` unconditionally.
    */
   let touched = false;
-  const placeholderNow = () => (typeof placeholder === "function" ? placeholder() : placeholder);
-  const optionsNow = (): DialogChoiceOption[] =>
+  const placeholderNow = () => (isFunction(placeholder) ? placeholder() : placeholder);
+  const optionsNow = (): SurfaceOption[] =>
     choice ? choice.options().map((option) => ({ label: option.label, value: option.value })) : [];
 
   return new Promise((resolve) => {
@@ -362,15 +364,11 @@ export function showPromptDialog(
       error = next;
       handle.update({ error, invalid: error !== "" });
     };
-    const handle = openDialogSurface({
+    const surfaceOptions: DialogSurfaceOptions = {
       cancelLabel,
       confirmLabel,
       headline,
       layer: layerHost("dialog"),
-      ...(message === undefined ? {} : messageOptions(message)),
-      ...(choice ? { choice: { chosen, label: choice.label, options: optionsNow() } } : {}),
-      field: { mono, multiline, placeholder: placeholderNow(), rows, select, value },
-      ...(size === undefined ? {} : { size }),
       onCancel: () => done(null),
       onClosed: () => done(null),
       onConfirm: () => {
@@ -408,7 +406,18 @@ export function showPromptDialog(
           placeholder: placeholderNow(),
         });
       },
-    });
+    };
+    if (message !== undefined) {
+      Object.assign(surfaceOptions, messageOptions(message));
+    }
+    if (choice) {
+      surfaceOptions.choice = { chosen, label: choice.label, options: optionsNow() };
+    }
+    surfaceOptions.field = { mono, multiline, placeholder: placeholderNow(), rows, select, value };
+    if (size !== undefined) {
+      surfaceOptions.size = size;
+    }
+    const handle = openDialogSurface(surfaceOptions);
   });
 }
 
@@ -452,7 +461,7 @@ export function clearLayerSlot(layer: LayerKind, id: string) {
   const key = `${layer}:${id}`;
   const slot = _namedSlots.get(key);
   if (slot) {
-    litRender(nothing, slot);
+    render(nothing, slot);
     slot.remove();
     _namedSlots.delete(key);
   }
@@ -491,7 +500,11 @@ const _toastEntering = new Set<string>();
  * means the answer has to be able to change.
  */
 function reducedMotion(): boolean {
-  return globalThis.matchMedia?.("(prefers-reduced-motion: reduce)").matches === true;
+  // A realm without `matchMedia` (a bare test runtime) has no preference to honour.
+  if (!("matchMedia" in globalThis)) {
+    return false;
+  }
+  return globalThis.matchMedia("(prefers-reduced-motion: reduce)").matches === true;
 }
 
 /**
@@ -515,7 +528,7 @@ function reducedMotion(): boolean {
  */
 export function toastsAreHeld(): boolean {
   try {
-    return new URLSearchParams(globalThis.location?.search ?? "").get("automation") === "1";
+    return new URLSearchParams(globalThis.location.search).get("automation") === "1";
   } catch {
     // Intentionally ignored: no location (a bare test realm) means no automation.
     return false;
@@ -580,13 +593,13 @@ export interface ToastProjection {
   actionTitle: string;
 }
 
-interface ToastScope extends Record<string, unknown> {
+interface ToastScope {
   toasts: ToastProjection[];
   runAction: (id: string) => void;
   dismissToast: (id: string) => void;
 }
 
-registerSurface("toasts", toastsDoc as unknown as JxDocument);
+registerSurface("toasts", toastsDoc);
 
 let _toastState: ToastScope | null = null;
 let _toastMount: Promise<SurfaceHandle> | null = null;
@@ -610,7 +623,7 @@ function toastScope(): ToastScope {
       void runReported(registry, record.action, record.actionArgs, "Notifications");
     },
     toasts: [],
-  }) as ToastScope;
+  });
   return _toastState;
 }
 
@@ -631,12 +644,12 @@ function projectToast(record: Notification): ToastProjection {
     actionDisabled: reason !== undefined,
     actionLabel: command?.title ?? "",
     actionTitle:
-      command === null || command === undefined
+      command === null
         ? ""
         : reason === undefined
           ? command.title
           : `${command.title} — requires ${reason}`,
-    hasAction: command !== null && command !== undefined,
+    hasAction: command !== null,
     icon: TOAST_ICON[record.severity],
     id: record.id,
     message: record.message,

package/src/ui/media-picker.ts

@@ -48,7 +48,11 @@ import {
 } from "../files/media-meta";
 import { mediaSiteUrl, previewFileSrc } from "../files/media-paths";
 import { notedListing } from "../files/asset-versions";
-import type { MediaBrowserRow, MediaBrowserSurfaceHandle } from "../surfaces/media-browser";
+import type {
+  MediaBrowserRow,
+  MediaBrowserSurfaceHandle,
+  MediaBrowserView,
+} from "../surfaces/media-browser";
 import type { MediaFieldHandle, MediaFieldView } from "../surfaces/media-field";
 
 // ─── Media file cache ────────────────────────────────────────────────────────
@@ -139,7 +143,7 @@ let _browserFilter = "";
 let _browserOrigin = { x: 0, y: 0 };
 
 /** What the panel shows for the filter that stands now. */
-function browserView() {
+function browserView(): MediaBrowserView {
   const query = _browserFilter.toLowerCase();
   const filtered = query
     ? mediaCache.filter(
@@ -164,9 +168,9 @@ function browserView() {
     emptyLabel: "No matches",
     filter: _browserFilter,
     moreLabel: `…${filtered.length - BROWSE_LIMIT} more`,
-    moreState: (filtered.length > BROWSE_LIMIT ? "shown" : "hidden") as "hidden" | "shown",
+    moreState: filtered.length > BROWSE_LIMIT ? "shown" : "hidden",
     rows,
-    rowsState: (rows.length > 0 ? "listed" : "empty") as "empty" | "listed",
+    rowsState: rows.length > 0 ? "listed" : "empty",
     x: _browserOrigin.x,
     y: _browserOrigin.y,
   };
@@ -293,12 +297,16 @@ export function pickAndUpload(onCommit: (val: string) => void) {
 const FIELD_DEBOUNCE_MS = 400;
 
 /** One mounted field, and the decisions that move under it between repaints. */
-interface FieldEntry {
-  handle: MediaFieldHandle;
+/** What a field's callbacks read at call time; a re-mount rewrites both in place. */
+interface FieldBinding {
   prop: string;
   commit: (value: string) => void;
 }
 
+interface FieldEntry extends FieldBinding {
+  handle: MediaFieldHandle;
+}
+
 /**
  * The fields this module has mounted, by the host they were mounted into.
  *
@@ -347,8 +355,8 @@ export function mountMediaPicker(
     existing.handle.update(fieldView(prop, value));
     return;
   }
-  const entry: FieldEntry = { commit: onCommit, handle: null as unknown as MediaFieldHandle, prop };
-  entry.handle = mountMediaFieldSurface(host, fieldView(prop, value), {
+  const entry: FieldBinding = { commit: onCommit, prop };
+  const handle = mountMediaFieldSurface(host, fieldView(prop, value), {
     browse: (anchor: HTMLElement) => {
       void loadMediaCache();
       showMediaPickerPopover(anchor, (val: string) => entry.commit(val));
@@ -364,7 +372,8 @@ export function mountMediaPicker(
       void loadMediaCache();
     },
   });
-  _fields.set(host, entry);
+  // The same object, so the callbacks above see a later re-mount's `prop` and `commit`.
+  _fields.set(host, Object.assign(entry, { handle }));
 }
 
 /**

package/src/ui/popover-surface.ts

@@ -30,8 +30,8 @@
 import { layerHost } from "./layers";
 import { overlayRegion, REGION_ATTR } from "./regions";
 import { mountSurface } from "./surface";
-import type { JxMountOptions } from "@jxsuite/runtime/types";
-import type { SurfaceHandle } from "./surface";
+import type { JxHostScope, JxMountOptions, JxScope } from "@jxsuite/runtime/types";
+import type { MountSurfaceOptions, SurfaceHandle } from "./surface";
 
 /** A popover panel element, as the platform's popover API sees it. */
 type PanelElement = HTMLElement & {
@@ -51,13 +51,14 @@ export interface PopoverSurfaceHandle {
   readonly close: () => void;
 }
 
-export interface OpenPopoverSurfaceOptions {
+/** How a popover surface is opened. `S` is the scope's own type, held to `JxHostScope` on open. */
+export interface OpenPopoverSurfaceOptions<S = JxScope> {
   /** The registered surface name — its document's root must be a `jx-popover`. */
   name: string;
   /** The panel's instance name; its region becomes `overlay.<kind>:<id>`. */
   slot: string;
   /** The reactive scope the document reads. */
-  scope: Record<string, unknown>;
+  scope: S;
   /**
    * The control it was opened from. It becomes the popover's invoker, so a press on that control
    * does not light-dismiss the panel its own click is about to toggle, and focus goes back to it.
@@ -78,7 +79,9 @@ export interface OpenPopoverSurfaceOptions {
  * @param {OpenPopoverSurfaceOptions} options
  * @returns {PopoverSurfaceHandle}
  */
-export function openPopoverSurface(options: OpenPopoverSurfaceOptions): PopoverSurfaceHandle {
+export function openPopoverSurface<S extends JxHostScope<S>>(
+  options: OpenPopoverSurfaceOptions<S>,
+): PopoverSurfaceHandle {
   const { anchor, name, scope, slot: slotId } = options;
   const host = document.createElement("div");
   host.style.pointerEvents = "auto";
@@ -88,6 +91,8 @@ export function openPopoverSurface(options: OpenPopoverSurfaceOptions): PopoverS
   let panel: PanelElement | null = null;
   let mounted: SurfaceHandle | null = null;
   let closed = false;
+  // A function rather than a property read, because the signal can abort across every `await` below.
+  const aborted = (): boolean => controller.signal.aborted;
 
   const finish = (fromPlatform: boolean): void => {
     if (closed) {
@@ -104,21 +109,24 @@ export function openPopoverSurface(options: OpenPopoverSurfaceOptions): PopoverS
   };
 
   const ready = (async () => {
-    const surface = await mountSurface(name, scope, host, {
-      signal: controller.signal,
-      ...(options.onNodeCreated ? { onNodeCreated: options.onNodeCreated } : {}),
-    });
-    if (controller.signal.aborted) {
+    const mountOptions: MountSurfaceOptions = { signal: controller.signal };
+    if (options.onNodeCreated) {
+      mountOptions.onNodeCreated = options.onNodeCreated;
+    }
+    const surface = await mountSurface(name, scope, host, mountOptions);
+    if (aborted()) {
       return;
     }
     mounted = surface;
+    /* SAFETY: `name` must register a document whose root is a `jx-popover` (see
+       OpenPopoverSurfaceOptions.name), an HTMLElement carrying `open` and the popover methods. */
     panel = surface.root as PanelElement;
     /* On the PANEL as well as the slot: a popover is `position: fixed` in the top layer, so the
        slot around it has a zero-height box and the screenshots lane refuses it ("has an empty
        box"). Both carry the id; the measurement takes the last match, which is the panel. */
     panel.setAttribute(REGION_ATTR, overlayRegion("popover", slotId));
     panel.addEventListener("toggle", (event) => {
-      if ((event as { newState?: string }).newState === "closed") {
+      if ("newState" in event && event.newState === "closed") {
         finish(true);
       }
     });
@@ -130,7 +138,7 @@ export function openPopoverSurface(options: OpenPopoverSurfaceOptions): PopoverS
         panel?.addEventListener("jx-ready", () => resolve(), { once: true });
       });
     }
-    if (controller.signal.aborted) {
+    if (aborted()) {
       return;
     }
     panel.showPopover(anchor ? { source: anchor } : undefined);

package/src/ui/progress-modal.ts

@@ -29,7 +29,7 @@ import { beginActivity } from "../panels/activity-panel";
 import { setBottomTab } from "../shell";
 import { layerHost } from "./layers";
 import { openProgressSurface } from "../surfaces/progress-modal";
-import type { ActivityHandle } from "../panels/activity-panel";
+import type { ActivityHandle, ActivityOptions } from "../panels/activity-panel";
 
 export interface ProgressModalHandle {
   /** Update the status line shown under the title. Also the Activity entry's status. */
@@ -68,12 +68,17 @@ export interface ProgressModalOptions {
 export function showProgressModal(opts: ProgressModalOptions): ProgressModalHandle {
   let closed = false;
 
-  const activity = beginActivity({
-    title: opts.title,
-    ...(opts.status === undefined ? {} : { status: opts.status }),
-    ...(opts.source === undefined ? {} : { source: opts.source }),
-    ...(opts.cancel === undefined ? {} : { cancel: opts.cancel }),
-  });
+  const activityOptions: ActivityOptions = { title: opts.title };
+  if (opts.status !== undefined) {
+    activityOptions.status = opts.status;
+  }
+  if (opts.source !== undefined) {
+    activityOptions.source = opts.source;
+  }
+  if (opts.cancel !== undefined) {
+    activityOptions.cancel = opts.cancel;
+  }
+  const activity = beginActivity(activityOptions);
 
   const close = () => {
     if (closed) {
@@ -118,7 +123,7 @@ export function showProgressModal(opts: ProgressModalOptions): ProgressModalHand
       // CAPTURED LOG as their message — `result.log ?? "bun install failed"` — so a multi-line one
       // Is split the way the old view split it: "<title> failed" as the headline, the whole text
       // As the detail. A Problems list whose first row is 400 lines of `bun` output is not a list.
-      const text = (message ?? "").trim();
+      const text = message.trim();
       if (text === "" || text.includes("\n")) {
         activity.log(text);
         activity.fail(`${opts.title} failed`);

package/src/ui/regions.ts

@@ -97,16 +97,17 @@ export function parseRegionId(id: string): ParsedRegionId | null {
       }
     }
   }
-  if (!(REGION_SURFACES as readonly string[]).includes(surface)) {
+  const known = REGION_SURFACES.find((candidate) => candidate === surface);
+  if (known === undefined) {
     return null;
   }
   return instance === undefined
     ? part === undefined
-      ? { surface: surface as RegionSurface }
-      : { part, surface: surface as RegionSurface }
+      ? { surface: known }
+      : { part, surface: known }
     : part === undefined
-      ? { instance, surface: surface as RegionSurface }
-      : { instance, part, surface: surface as RegionSurface };
+      ? { instance, surface: known }
+      : { instance, part, surface: known };
 }
 
 /** Whether a string is a well-formed region id. */
@@ -267,7 +268,7 @@ export const REGION_FOR_FOCUS: Readonly<Record<FocusRegion, string>> = {
   status: "statusbar",
 };
 
-const FOCUS_FOR_SURFACE: Readonly<Record<string, FocusRegion>> = {
+const FOCUS_FOR_SURFACE: Readonly<Partial<Record<RegionSurface, FocusRegion>>> = {
   "dock.bottom": "dock",
   inspector: "inspector",
   navigator: "navigator",