@jxsuite/studio 6.1.1 → 8.0.0

package/src/ui/surface.ts

@@ -11,8 +11,9 @@
  * @docs extending/ui-kit
  */
 import { mount, preloadDocument } from "@jxsuite/runtime";
-import type { JxMountOptions, JxScope } from "@jxsuite/runtime/types";
+import type { JxHostScope, JxMountOptions, JxScope } from "@jxsuite/runtime/types";
 import type { JxDocument } from "@jxsuite/schema/types";
+import type { SelectRow } from "@jxsuite/ui/behaviors/select";
 import { registerMount, unregisterMount } from "../services/surface-registry";
 import { kitReady } from "./kit";
 import { REGION_ATTR } from "./regions";
@@ -49,6 +50,61 @@ export function surfaceResolver(url: string): JxDocument | undefined {
   return surfaces.get(url.slice(SURFACES_BASE.length, -".json".length));
 }
 
+/**
+ * One row a surface document draws in a picker (a `jx-select` option, a radio, a segmented button):
+ * the value the control reports back, and the label the reader sees. The kit's own row, the one
+ * `jx-select` draws.
+ */
+export type { SelectRow as SurfaceOption } from "@jxsuite/ui/behaviors/select";
+
+/**
+ * One thing a surface document draws for the reader to act on (an empty state's button, an openable
+ * source): an id only the flow knows the meaning of, and the words on it.
+ */
+export interface SurfaceAction {
+  id: string;
+  label: string;
+}
+
+/** A delimited, labelled run of picker rows: the kit's `optgroup`, which draws both halves of it. */
+export interface SurfaceOptionGroup {
+  id: string;
+  label: string;
+  rows: SelectRow[];
+}
+
+/** A dialog document mounted into the dialog layer, as the flow that opened it holds it. */
+export interface DialogLayerHandle {
+  /** 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;
+}
+
+/** A label, and the key that identifies what it names (a chip, a section, a menu choice). */
+export interface KeyedLabel {
+  key: string;
+  label: string;
+}
+
+/** A label, and the tag it stands for (a declared language, an element a button adds). */
+export interface TaggedLabel {
+  tag: string;
+  label: string;
+}
+
+/** One tab a surface document draws in a tablist strip. */
+export interface SurfaceTab {
+  /** The tab's identity: the row key, the strip's `selected` value, and `data-tab`. */
+  key: string;
+  /** What the tab reads, badge included ("Problems 2"). */
+  label: string;
+  /** The tab element's own id, which the one panel names as its `aria-labelledby`. */
+  tabId: string;
+}
+
 export interface SurfaceHandle {
   readonly scope: JxScope;
   readonly root: HTMLElement | Text;
@@ -69,9 +125,9 @@ export interface MountSurfaceOptions {
  *
  * @throws {Error} When no document is registered under `name`
  */
-export async function mountSurface(
+export async function mountSurface<S extends JxHostScope<S>>(
   name: string,
-  hostScope: Record<string, unknown>,
+  hostScope: S,
   host: HTMLElement,
   options: MountSurfaceOptions = {},
 ): Promise<SurfaceHandle> {
@@ -83,14 +139,21 @@ export async function mountSurface(
   if (options.region) {
     host.setAttribute(REGION_ATTR, options.region);
   }
-  const handle = await mount(doc, host, {
+  const mountOptions: JxMountOptions<S> = {
     scope: hostScope,
     base: SURFACES_BASE,
     resolver: surfaceResolver,
-    ...(options.onNodeCreated ? { onNodeCreated: options.onNodeCreated } : {}),
-    ...(options.onNodeMoved ? { onNodeMoved: options.onNodeMoved } : {}),
-    ...(options.signal ? { signal: options.signal } : {}),
-  });
+  };
+  if (options.onNodeCreated) {
+    mountOptions.onNodeCreated = options.onNodeCreated;
+  }
+  if (options.onNodeMoved) {
+    mountOptions.onNodeMoved = options.onNodeMoved;
+  }
+  if (options.signal) {
+    mountOptions.signal = options.signal;
+  }
+  const handle = await mount(doc, host, mountOptions);
 
   const surfaceHandle = (dispose: () => void): SurfaceHandle => ({
     dispose,

package/src/ui/timing.ts

@@ -35,6 +35,15 @@ export const CODE_DEBOUNCE = 500;
  */
 export const LIVE_PREVIEW = 350;
 
+/**
+ * How long a keystroke in a `<head>` field waits before it is written: the Search-appearance
+ * dialog's fields (a document mutation the previews repaint from) and Project Settings' `$head`
+ * rows (a `project.json` write). Both time each field separately, so editing one field and then
+ * another inside the window lands both, and a `change` (blur, or a clear button) commits at once,
+ * so nothing is lost to the wait.
+ */
+export const HEAD_EDIT_DEBOUNCE = 300;
+
 /*
  * `STATUS_MESSAGE = 3000` used to live here: how long a transient message stayed in the status bar
  * before it erased itself. It had one reader, `statusMessage`, which is deleted — the bar carries

package/src/ui/value-source.ts

@@ -43,7 +43,16 @@ import {
   tagExpressionSchema,
   tagNameSchema,
 } from "@jxsuite/schema/defs";
-import { isFunctionDef, isRef, isTemplateString } from "@jxsuite/schema/guards";
+import {
+  isFunctionDef,
+  isJsonObject,
+  isNonNullObject,
+  isRef,
+  isString,
+  isTemplateString,
+} from "@jxsuite/schema/guards";
+import type { ReadonlyJsonObject, ReadonlyJsonValue } from "@jxsuite/schema/project-schemas";
+import type { JsonValue, JxDocumentValue } from "@jxsuite/schema/types";
 
 /** A rung of the value ladder — one way a document position can produce its value. */
 export type SlotMode = "literal" | "ref" | "template" | "expression" | "function";
@@ -73,7 +82,7 @@ export const VALUE_SOURCE_HINTS: Record<SlotMode, string> = {
 };
 
 /** Detect which rung of the ladder a raw document value occupies. */
-export function slotMode(value: unknown): SlotMode {
+export function slotMode(value: JxDocumentValue | JsonValue | undefined): SlotMode {
   if (isRef(value)) {
     return "ref";
   }
@@ -83,7 +92,7 @@ export function slotMode(value: unknown): SlotMode {
   if (isTemplateString(value)) {
     return "template";
   }
-  if (value && typeof value === "object" && "$expression" in value) {
+  if (isNonNullObject(value) && "$expression" in value) {
     return "expression";
   }
   return "literal";
@@ -91,8 +100,6 @@ export function slotMode(value: unknown): SlotMode {
 
 // ─── Schema walk ────────────────────────────────────────────────────────────
 
-type SchemaNode = Record<string, unknown>;
-
 /**
  * The `on*` property shape that `@jxsuite/schema`'s generator synthesises for every EventHandler
  * IDL attribute (`buildEventHandlerProperties`). It is the only slot position with no declared
@@ -107,40 +114,45 @@ export const EVENT_HANDLER_SCHEMA = {
 } as const;
 
 /** The `$defs` a slot position can actually reach. Anything else is a bug, not a silent no-rung. */
-const REACHABLE_DEFS: Record<string, SchemaNode> = {
-  ExpressionEntry: expressionEntrySchema as unknown as SchemaNode,
-  FunctionDef: functionDefSchema as unknown as SchemaNode,
-  RefObject: refObjectSchema as unknown as SchemaNode,
-  StyleObject: styleObjectSchema as unknown as SchemaNode,
-};
+const REACHABLE_DEFS = new Map<string, ReadonlyJsonObject>([
+  ["ExpressionEntry", expressionEntrySchema],
+  ["FunctionDef", functionDefSchema],
+  ["RefObject", refObjectSchema],
+  ["StyleObject", styleObjectSchema],
+]);
 
 /** A `{ $ref: … }` binding object: `required: ["$ref"]` with a `$ref` property. */
-function isRefObjectSchema(node: SchemaNode): boolean {
-  const { required } = node;
+function isRefObjectSchema(node: ReadonlyJsonObject): boolean {
+  const { properties, required } = node;
   return (
     Array.isArray(required) &&
     required.includes("$ref") &&
-    Boolean((node.properties as SchemaNode | undefined)?.$ref)
+    isJsonObject(properties) &&
+    Boolean(properties.$ref)
   );
 }
 
 /** A `{ $expression: … }` entry. */
-function isExpressionEntrySchema(node: SchemaNode): boolean {
+function isExpressionEntrySchema(node: ReadonlyJsonObject): boolean {
   const { required } = node;
   return Array.isArray(required) && required.includes("$expression");
 }
 
 /** A `$prototype: "Function"` declaration. */
-function isFunctionDefSchema(node: SchemaNode): boolean {
-  const proto = (node.properties as SchemaNode | undefined)?.$prototype as SchemaNode | undefined;
-  return proto?.const === "Function";
+function isFunctionDefSchema(node: ReadonlyJsonObject): boolean {
+  const { properties } = node;
+  return (
+    isJsonObject(properties) &&
+    isJsonObject(properties.$prototype) &&
+    properties.$prototype.const === "Function"
+  );
 }
 
 /**
  * A string branch that will accept `${…}`. A pattern/enum/const-constrained string will not — a
  * `TagName` or a `#/state/…` pointer is a string, but not a place a template may be typed.
  */
-function isFreeStringSchema(node: SchemaNode): boolean {
+function isFreeStringSchema(node: ReadonlyJsonObject): boolean {
   return (
     node.type === "string" &&
     node.pattern === undefined &&
@@ -155,23 +167,24 @@ interface WalkState {
   found: Set<SlotMode>;
   /** Pointers the walk could not resolve — surfaced so a schema move fails loudly. */
   unresolved: Set<string>;
-  seen: Set<SchemaNode>;
+  seen: Set<ReadonlyJsonObject>;
 }
 
-function walk(node: unknown, state: WalkState): void {
-  if (!node || typeof node !== "object") {
+function walk(schema: ReadonlyJsonValue | undefined, state: WalkState): void {
+  /* An array is an object too, but it names no keyword: the walk below found nothing in one, so
+     refusing it here is the same answer reached sooner. */
+  if (!isJsonObject(schema)) {
     return;
   }
-  const schema = node as SchemaNode;
   if (state.seen.has(schema)) {
     return;
   }
   state.seen.add(schema);
 
-  const pointer = typeof schema.$ref === "string" ? schema.$ref : undefined;
+  const pointer = isString(schema.$ref) ? schema.$ref : undefined;
   if (pointer !== undefined && Object.keys(schema).length === 1) {
     const name = pointer.startsWith("#/$defs/") ? pointer.slice("#/$defs/".length) : pointer;
-    const target = REACHABLE_DEFS[name];
+    const target = REACHABLE_DEFS.get(name);
     if (target) {
       walk(target, state);
     } else {
@@ -218,7 +231,7 @@ function walk(node: unknown, state: WalkState): void {
     state.found.add("literal");
     return;
   }
-  if (typeof schema.type === "string" && SCALAR_TYPES.has(schema.type)) {
+  if (isString(schema.type) && SCALAR_TYPES.has(schema.type)) {
     state.found.add("literal");
   }
 }
@@ -230,7 +243,7 @@ export interface DerivedCaps {
 }
 
 /** Derive the rungs a subschema permits, and report any pointer the walk could not follow. */
-export function deriveSlotCapsDetailed(schema: unknown): DerivedCaps {
+export function deriveSlotCapsDetailed(schema: ReadonlyJsonValue | undefined): DerivedCaps {
   const state: WalkState = { found: new Set(), seen: new Set(), unresolved: new Set() };
   walk(schema, state);
   return {
@@ -240,7 +253,7 @@ export function deriveSlotCapsDetailed(schema: unknown): DerivedCaps {
 }
 
 /** Derive the rungs a subschema permits, in ladder order. */
-export function deriveSlotCaps(schema: unknown): SlotMode[] {
+export function deriveSlotCaps(schema: ReadonlyJsonValue | undefined): SlotMode[] {
   return deriveSlotCapsDetailed(schema).caps;
 }
 
@@ -322,7 +335,7 @@ export type SlotPosition = keyof typeof SLOT_POSITION_SCHEMAS;
  * There is deliberately no third form. A caller may not state which rungs it wants: the rungs are
  * derived from a schema or they are not derived at all.
  */
-export type SlotCapsSource = SlotPosition | { schema: unknown };
+export type SlotCapsSource = SlotPosition | { schema: ReadonlyJsonValue };
 
 const capsCache = new Map<SlotPosition, SlotMode[]>();
 
@@ -339,7 +352,7 @@ export function capsForPosition(position: SlotPosition): SlotMode[] {
 
 /** The rungs on offer for a {@link SlotCapsSource} — a named position, or a schema handed in. */
 export function slotCaps(source: SlotCapsSource): SlotMode[] {
-  return typeof source === "string" ? capsForPosition(source) : deriveSlotCaps(source.schema);
+  return isString(source) ? capsForPosition(source) : deriveSlotCaps(source.schema);
 }
 
 /**
@@ -351,7 +364,7 @@ export function slotCaps(source: SlotCapsSource): SlotMode[] {
  * own config at runtime — which no plugin schema declares because it is not the plugin's to
  * declare. Both are stated here, once, rather than assumed at each form.
  */
-export function configFieldSchema(field: unknown): { anyOf: unknown[] } {
+export function configFieldSchema(field: ReadonlyJsonValue): ReadonlyJsonObject {
   const declared = deriveSlotCaps(field).length > 0 ? field : { type: "string" };
   return { anyOf: [declared, { $ref: "#/$defs/RefObject" }] };
 }

package/src/ui/virtual-window.ts

@@ -28,6 +28,7 @@
 
 /// <reference lib="dom" />
 
+import { isFunction } from "@jxsuite/schema/guards";
 import { rectOf } from "../utils/geometry";
 
 /** The measurement a window is computed from. Everything is in CSS pixels. */
@@ -244,7 +245,7 @@ export function createVirtualWindow(options: VirtualWindowOptions): VirtualWindo
   };
 
   let resizeObserver: ResizeObserver | null = null;
-  if (typeof ResizeObserver === "function") {
+  if (isFunction(globalThis.ResizeObserver)) {
     resizeObserver = new ResizeObserver(measureNextFrame);
     resizeObserver.observe(scroller);
     if (list) {
@@ -329,7 +330,7 @@ export function scrollerFor(list: HTMLElement): HTMLElement | null {
   if (cached && cached.isConnected && list.isConnected && cached.contains(list)) {
     return cached;
   }
-  const found = nearestScroller(list);
+  const found = declaredScroller(list) ?? nearestScroller(list);
   if (found) {
     scrollerCache.set(list, found);
   } else {
@@ -338,6 +339,31 @@ export function scrollerFor(list: HTMLElement): HTMLElement | null {
   return found;
 }
 
+/**
+ * The attribute a host stamps on the element it KNOWS scrolls the lists drawn inside it.
+ *
+ * `#left-panel` is the one scroller every Navigator panel draws in (its dock's root is `display:
+ * contents`), and the shell says so in `surfaces/shell.json`.
+ */
+export const SCROLLER_ATTR = "data-jx-scroller";
+
+/**
+ * The scroller a host declared for `list`, found by a node walk that reads no layout, or null.
+ *
+ * {@link nearestScroller}'s walk reads `scrollHeight`, `clientHeight` and computed overflow on every
+ * ancestor, and the moment a list is bound is the moment its panel has just been drawn, so the
+ * first read pays a style recalculation of the whole half-written document. The cache cannot help
+ * there: the Files tree and the Outline are new elements each time their panel is shown again, so
+ * every show of either one walked (12 to 32 ms a show in the perf trace). A declared scroller
+ * answers by identity. It carries the memoized answer's one residue: it is the scroller whether or
+ * not its content overflows right now, and a list that fits is windowed to the whole list, which is
+ * what {@link computeWindow} answers for it anyway. Only a CONNECTED list asks: a list still being
+ * built is not inside its scroller yet.
+ */
+function declaredScroller(list: HTMLElement): HTMLElement | null {
+  return list.isConnected ? list.closest<HTMLElement>(`[${SCROLLER_ATTR}]`) : null;
+}
+
 /**
  * How far `list`'s first row has scrolled above the top of `scroller`'s viewport.
  *
@@ -373,7 +399,7 @@ export function listWindow(
   return computeWindow({
     columns: spec.columns ?? 1,
     count: spec.count,
-    ...(spec.overscanRows === undefined ? {} : { overscanRows: spec.overscanRows }),
+    overscanRows: spec.overscanRows ?? DEFAULT_OVERSCAN_ROWS,
     rowHeight: spec.rowHeight,
     scrollTop: listScrollTop(scroller, list),
     viewportHeight: scroller.clientHeight,

package/src/utils/base64.ts

@@ -3,14 +3,16 @@
  * Base64 encoding for binary payloads that cross an RPC boundary.
  *
  * `StudioPlatform.uploadFile` accepts `string | File | Blob | ArrayBuffer`, but the RPC platforms
- * (electrobun, chromium) JSON-serialize their params — a `File`/`Blob` becomes `{}` on the wire.
- * Those platforms encode here before the call; the HTTP platforms (dev server, cloud) post the
- * binary body directly and must NOT use this.
+ * (the chromium desktop shell) JSON-serialize their params — a `File`/`Blob` becomes `{}` on the
+ * wire. Those platforms encode here before the call; the HTTP platforms (dev server, cloud) post
+ * the binary body directly and must NOT use this.
  *
  * {@link base64ToBytes} is the same boundary in the other direction, for `readFileBytes`: the RPC
  * backends answer a base64 string for the same reason they accept one, and the caller wants bytes.
  */
 
+import { isString } from "@jxsuite/schema/guards";
+
 /** Bytes per `String.fromCodePoint` call — spreading a whole large file blows the call stack. */
 const CHUNK = 32_768;
 
@@ -28,7 +30,7 @@ export function bytesToBase64(bytes: Uint8Array): string {
  * have always received base64 strings, so existing callers keep working.
  */
 export async function toBase64(data: string | File | Blob | ArrayBuffer): Promise<string> {
-  if (typeof data === "string") {
+  if (isString(data)) {
     return data;
   }
   const buffer = data instanceof ArrayBuffer ? data : await data.arrayBuffer();