@jxsuite/studio 6.1.1 → 8.0.0

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();
 }
 
@@ -97,6 +99,19 @@ export function isModalOpen(): boolean {
   return Boolean(_dialogLayer?.querySelector(UNDERLAID) || _modalLayer?.querySelector(UNDERLAID));
 }
 
+/**
+ * Whether a popover is showing anywhere in the chrome: a kit `jx-popover`, a menu, any element in
+ * the platform's popover top layer.
+ *
+ * A popover leaves Escape to the platform, which closes it as the keystroke's default action, so an
+ * app chord on bare Escape has to stand down while one is up: cancelling the keystroke would cancel
+ * the close as well, and whatever the chord did would happen under a popover that stays open. Asked
+ * of the live DOM for the reason {@link isModalOpen} is.
+ */
+export function isPopoverOpen(): boolean {
+  return document.querySelector(":popover-open") !== null;
+}
+
 /*
  * `showDialog` was here, with `openOverlaySlot`, `focusOverlay`, `focusablesIn` and
  * `BODY_FOCUSABLE` under it — and all five are GONE together.
@@ -214,12 +229,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 +359,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 +377,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 +419,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 +474,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 +513,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 +541,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 +606,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 +636,7 @@ function toastScope(): ToastScope {
       void runReported(registry, record.action, record.actionArgs, "Notifications");
     },
     toasts: [],
-  }) as ToastScope;
+  });
   return _toastState;
 }
 
@@ -631,12 +657,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,