@jxsuite/studio 6.1.1 → 8.0.0

package/src/surfaces/dialog.ts

@@ -25,27 +25,12 @@
 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 { close, showModal } from "@jxsuite/ui/behaviors/dialog";
 import { selectValue } from "@jxsuite/ui/behaviors/textfield";
 import dialogDoc from "./dialog.json";
-import type { SurfaceHandle } from "../ui/surface";
-import type { JxDocument } from "@jxsuite/schema/types";
+import type { SurfaceHandle, SurfaceOption } from "../ui/surface";
 
-registerSurface("dialog", dialogDoc as unknown as JxDocument);
-
-/**
- * One option of a prompt's choice.
- *
- * There is no `selected` here, and its absence is the contract rather than an omission: `jx-select`
- * is a native `<select>`, and the reader's first pick sets an option's dirtiness flag, after which
- * the `selected` content attribute stops moving selectedness (`ui.md` §5.1). A projection that
- * marked a row would be right until the first pick and wrong after it. The chosen row is named by
- * `chosen`, once, beside the list.
- */
-export interface DialogChoiceOption {
-  value: string;
-  label: string;
-}
+registerSurface("dialog", dialogDoc);
 
 /** What a flow hands the surface. Everything is a projection; the flow keeps the state machine. */
 export interface DialogSurfaceOptions {
@@ -61,8 +46,15 @@ export interface DialogSurfaceOptions {
   message?: string;
   /** Render a richer body into the document's island, once the element is ready. */
   island?: (host: HTMLElement) => void;
-  /** A `jx-select` above the field, and which of its rows is chosen. */
-  choice?: { label: string; options: DialogChoiceOption[]; chosen: string };
+  /**
+   * A `jx-select` above the field, and which of its rows is chosen. The rows carry no `selected`,
+   * and that absence is the contract rather than an omission: `jx-select` is a native `<select>`,
+   * and the reader's first pick sets an option's dirtiness flag, after which the `selected` content
+   * attribute stops moving selectedness (`ui.md` §5.1). A projection that marked a row would be
+   * right until the first pick and wrong after it. The chosen row is named by `chosen`, once,
+   * beside the list.
+   */
+  choice?: { label: string; options: SurfaceOption[]; chosen: string };
   /** The prompt's field. */
   field?: {
     value: string;
@@ -104,7 +96,7 @@ export interface DialogSurfacePatch {
   placeholder?: string;
   invalid?: boolean;
   error?: string;
-  options?: DialogChoiceOption[];
+  options?: SurfaceOption[];
   chosen?: string;
 }
 
@@ -118,7 +110,7 @@ export interface DialogSurfaceHandle {
   close: () => void;
 }
 
-interface DialogScope extends Record<string, unknown> {
+interface DialogScope {
   headline: string;
   confirmLabel: string;
   secondaryLabel: string;
@@ -129,7 +121,7 @@ interface DialogScope extends Record<string, unknown> {
   hasMessage: boolean;
   hasChoice: boolean;
   choiceLabel: string;
-  options: DialogChoiceOption[];
+  options: SurfaceOption[];
   hasField: boolean;
   multiline: boolean;
   rows: string;
@@ -195,7 +187,7 @@ export function openDialogSurface(options: DialogSurfaceOptions): DialogSurfaceH
   slot.setAttribute(REGION_ATTR, overlayRegion("dialog", options.region));
   options.layer.append(slot);
 
-  const scope = reactive<DialogScope>({
+  const scope: DialogScope = reactive<DialogScope>({
     cancel: () => {
       options.onCancel();
     },
@@ -236,10 +228,14 @@ export function openDialogSurface(options: DialogSurfaceOptions): DialogSurfaceH
     secondaryLabel: options.secondaryLabel ?? "",
     size: options.size ?? "sm",
     value: options.field?.value ?? "",
-  }) as DialogScope;
+  });
 
   let handle: SurfaceHandle | null = null;
   let closed = false;
+  /* Read through a call, not the bare binding: `close()` can run while the mount is awaiting the
+     element, and a direct `closed` test after that `await` would be narrowed to the value the test
+     before it saw. */
+  const isClosed = (): boolean => closed;
   /* Closing while the element is still rendering must not leave `ready` waiting on a `jx-ready`
      a disposed element will never send, so the wait races against the close. */
   let abort: () => void = () => {};
@@ -248,14 +244,16 @@ export function openDialogSurface(options: DialogSurfaceOptions): DialogSurfaceH
   });
   const mounted = mountSurface("dialog", scope, slot);
   const ready = mounted.then(async (surface) => {
+    /* SAFETY: `dialog.json`'s root definition is a `jx-dialog` element, so the runtime
+       mounts an HTMLElement; a `Text` root only comes from a document whose root is a bare string. */
     const element = surface.root as HTMLElement;
-    if (closed) {
+    if (isClosed()) {
       surface.dispose();
       return element;
     }
     handle = surface;
     await Promise.race([whenReady(element), aborted]);
-    if (closed) {
+    if (isClosed()) {
       return element;
     }
     options.island?.(element.querySelector<HTMLElement>('[part="island"]') ?? element);
@@ -284,7 +282,7 @@ export function openDialogSurface(options: DialogSurfaceOptions): DialogSurfaceH
       const element = handle?.root;
       if (element instanceof HTMLElement) {
         // The platform's close first, so focus goes back where it was; then the document goes.
-        closeDialog(element);
+        close(element);
       }
       // A mount that has not landed yet is disposed by `ready` when it does.
       handle?.dispose();

package/src/surfaces/diff-toolbar.ts

@@ -18,10 +18,9 @@
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import diffToolbarDoc from "./diff-toolbar.json";
-import type { JxDocument } from "@jxsuite/schema/types";
 import type { SurfaceHandle } from "../ui/surface";
 
-registerSurface("diff-toolbar", diffToolbarDoc as unknown as JxDocument);
+registerSurface("diff-toolbar", diffToolbarDoc);
 
 /** Everything the bar draws, as one value. Every field is already a string or a boolean. */
 export interface DiffToolbarView {
@@ -66,7 +65,7 @@ export interface DiffToolbarSurfaceHandle {
 }
 
 /** The scope the document reads: {@link DiffToolbarView} plus the actions its controls call. */
-interface DiffToolbarScope extends Record<string, unknown>, DiffToolbarView, DiffToolbarActions {}
+interface DiffToolbarScope extends DiffToolbarView, DiffToolbarActions {}
 
 /** Write a projection into the scope. */
 function project(scope: DiffToolbarScope, view: DiffToolbarView): void {
@@ -98,7 +97,7 @@ export function mountDiffToolbarSurface(
   actions: DiffToolbarActions,
 ): DiffToolbarSurfaceHandle {
   host.replaceChildren();
-  const scope = reactive<DiffToolbarScope>({
+  const scope: DiffToolbarScope = reactive<DiffToolbarScope>({
     codeChecked: "false",
     countLabel: "",
     degraded: "hidden",
@@ -113,18 +112,21 @@ export function mountDiffToolbarSurface(
     stepper: "hidden",
     viewMode: "choice",
     visualChecked: "true",
-  }) as DiffToolbarScope;
+  });
   project(scope, view);
 
   let mounted: SurfaceHandle | null = null;
   let disposed = false;
   const ready = mountSurface("diff-toolbar", scope, host).then((surface) => {
+    /* SAFETY: `diff-toolbar.json`'s root definition is a `div` element, so the runtime mounts an
+       HTMLElement; a `Text` root only comes from a document whose root is a bare string. */
+    const root = surface.root as HTMLElement;
     if (disposed) {
       surface.dispose();
-      return surface.root as HTMLElement;
+      return root;
     }
     mounted = surface;
-    return surface.root as HTMLElement;
+    return root;
   });
 
   return {

package/src/surfaces/empty-state.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://jxsuite.com/schema/v1",
   "$id": "StudioEmptyState",
-  "$description": "The one empty-state pattern (studio-ui-guidelines.md §11), as the document every region draws it from. Nine surfaces had already copied it into their own JSON — `git-panel.json`, `logic-panel.json`, `panel-outline.json` and the rest each carry a `[part=\"empty\"]` block written from the same rules — because `panels/empty-state.ts` is a lit template a document cannot call. This is the copy those were waiting for: the region that has NO document of its own hands its box to this one instead of rendering the helper, so a shell with three surfaces still lit and eight converted has one empty state rather than two. The copy rules stay where they are stated, in `panels/empty-state.ts`'s header: one sentence saying what the region is FOR, the action that fills it, and one shared verb across equivalent surfaces. Nothing here decides any of them — the adapter is handed a message, an optional second sentence and a list of buttons, and this draws exactly that.",
+  "$description": "The one empty-state pattern (studio-ui-guidelines.md §11), as the document every region draws it from. Nine surfaces had already copied it into their own JSON — the Source Control panel's (since folded into `publish-workspace.json`), `logic-panel.json`, `panel-outline.json` and the rest each carry a `[part=\"empty\"]` block written from the same rules — because `panels/empty-state.ts` is a lit template a document cannot call. This is the copy those were waiting for: the region that has NO document of its own hands its box to this one instead of rendering the helper, so a shell with three surfaces still lit and eight converted has one empty state rather than two. The copy rules stay where they are stated, in `panels/empty-state.ts`'s header: one sentence saying what the region is FOR, the action that fills it, and one shared verb across equivalent surfaces. Nothing here decides any of them — the adapter is handed a message, an optional second sentence and a list of buttons, and this draws exactly that.",
   "tagName": "div",
   "attributes": {
     "part": "empty",

package/src/surfaces/empty-state.ts

@@ -28,13 +28,12 @@ import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import emptyStateDoc from "./empty-state.json";
 import type { EmptyStateSpec } from "../panels/empty-state";
-import type { JxDocument } from "@jxsuite/schema/types";
 import type { SurfaceHandle } from "../ui/surface";
 
-registerSurface("empty-state", emptyStateDoc as unknown as JxDocument);
+registerSurface("empty-state", emptyStateDoc);
 
 /** One button, as the document draws it: a key, a word, and whether it can act. */
-interface EmptyStateActionRow extends Record<string, unknown> {
+interface EmptyStateActionRow {
   /** The repeater's key and what a press is addressed with — this action's slot in the list. */
   id: string;
   label: string;
@@ -44,10 +43,8 @@ interface EmptyStateActionRow extends Record<string, unknown> {
 /**
  * What the document draws, with every branch already decided.
  *
- * Named apart from the scope rather than derived from it with `Omit`: the scope carries the kit's
- * `Record<string, unknown>` index signature, and `Omit` over a type with one keeps the signature
- * and drops every named property — so the projection below would have type-checked against
- * anything.
+ * Named apart from the scope, which adds the one callback, so the projection below is checked
+ * against exactly the fields the document draws.
  */
 interface EmptyStateView {
   message: string;
@@ -59,7 +56,7 @@ interface EmptyStateView {
 }
 
 /** The scope `empty-state.json` reads. Every field is a value; the document asks no question. */
-interface EmptyStateScope extends Record<string, unknown>, EmptyStateView {
+interface EmptyStateScope extends EmptyStateView {
   runAction: (id: string) => void;
 }
 
@@ -89,12 +86,12 @@ export function createEmptyStateSurface(spec: EmptyStateSpec): EmptyStateSurface
 
   /** The handlers, held apart from the scope so `runAction` never has to be reassigned. */
   let handlers: (() => void)[] = [];
-  const scope = reactive<EmptyStateScope>({
+  const scope: EmptyStateScope = reactive<EmptyStateScope>({
     ...project(spec),
     runAction: (id: string) => {
       handlers[Number(id)]?.();
     },
-  }) as EmptyStateScope;
+  });
   handlers = handlersOf(spec);
 
   let mounted: SurfaceHandle | null = null;

package/src/surfaces/entry-editor.json

@@ -56,6 +56,13 @@
       "color": "var(--fg-dim)",
       "fontSize": "var(--jx-text-md)",
       "lineHeight": "1.5"
+    },
+    "& [part=\"record-nav\"]": {
+      "display": "flex",
+      "alignItems": "center",
+      "gap": "var(--jx-space-2)",
+      "color": "var(--fg-dim)",
+      "fontSize": "var(--jx-text-sm)"
     }
   },
   "children": [
@@ -102,6 +109,135 @@
                   },
                   "textContent": "${state.collection}"
                 },
+                {
+                  "tagName": "div",
+                  "attributes": {
+                    "part": "record-slot",
+                    "role": "none"
+                  },
+                  "style": {
+                    "display": "contents"
+                  },
+                  "$switch": {
+                    "$ref": "#/state/recordNav"
+                  },
+                  "cases": {
+                    "shown": {
+                      "$description": "A record of a file-backed collection (a CSV row): which row of the file this is, the rows either side of it, and the grid that shows them all. A file entry has no neighbours to step to, so it draws none of this.",
+                      "tagName": "div",
+                      "attributes": {
+                        "part": "record-nav",
+                        "role": "group",
+                        "aria-label": "Records"
+                      },
+                      "children": [
+                        {
+                          "tagName": "jx-action-button",
+                          "attributes": {
+                            "part": "previous"
+                          },
+                          "$props": {
+                            "size": "sm",
+                            "quiet": true,
+                            "label": "Previous record",
+                            "hint": "Previous record",
+                            "disabled": {
+                              "$ref": "#/state/previousDisabled"
+                            }
+                          },
+                          "onclick": {
+                            "$prototype": "Function",
+                            "body": [
+                              {
+                                "operator": "call",
+                                "target": {
+                                  "$ref": "#/state/showPrevious"
+                                },
+                                "value": []
+                              }
+                            ]
+                          },
+                          "children": [
+                            {
+                              "tagName": "span",
+                              "textContent": "‹ Previous"
+                            }
+                          ]
+                        },
+                        {
+                          "tagName": "span",
+                          "attributes": {
+                            "part": "place"
+                          },
+                          "textContent": "${state.place}"
+                        },
+                        {
+                          "tagName": "jx-action-button",
+                          "attributes": {
+                            "part": "next"
+                          },
+                          "$props": {
+                            "size": "sm",
+                            "quiet": true,
+                            "label": "Next record",
+                            "hint": "Next record",
+                            "disabled": {
+                              "$ref": "#/state/nextDisabled"
+                            }
+                          },
+                          "onclick": {
+                            "$prototype": "Function",
+                            "body": [
+                              {
+                                "operator": "call",
+                                "target": {
+                                  "$ref": "#/state/showNext"
+                                },
+                                "value": []
+                              }
+                            ]
+                          },
+                          "children": [
+                            {
+                              "tagName": "span",
+                              "textContent": "Next ›"
+                            }
+                          ]
+                        },
+                        {
+                          "tagName": "jx-action-button",
+                          "attributes": {
+                            "part": "grid"
+                          },
+                          "$props": {
+                            "size": "sm",
+                            "quiet": true,
+                            "label": "Edit in grid",
+                            "hint": "Every record of the file, as a table"
+                          },
+                          "onclick": {
+                            "$prototype": "Function",
+                            "body": [
+                              {
+                                "operator": "call",
+                                "target": {
+                                  "$ref": "#/state/openGrid"
+                                },
+                                "value": []
+                              }
+                            ]
+                          },
+                          "children": [
+                            {
+                              "tagName": "span",
+                              "textContent": "Edit in grid"
+                            }
+                          ]
+                        }
+                      ]
+                    }
+                  }
+                },
                 {
                   "tagName": "div",
                   "attributes": {

package/src/surfaces/entry-editor.ts

@@ -27,13 +27,14 @@
  * @docs studio/projects/content-types
  */
 
+import { isString } from "@jxsuite/schema/guards";
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import entryEditorDoc from "./entry-editor.json";
-import type { JxDocument } from "@jxsuite/schema/types";
+import type { JxElement } from "@jxsuite/schema/types";
 import type { SurfaceHandle } from "../ui/surface";
 
-registerSurface("entry-editor", entryEditorDoc as unknown as JxDocument);
+registerSurface("entry-editor", entryEditorDoc);
 
 /** Everything the document draws, as one value. */
 export interface EntryEditorView {
@@ -63,6 +64,12 @@ export interface EntryEditorView {
   note: string;
   /** The `empty` stage's first sentence, naming the document it is about. */
   emptyLine: string;
+  /** Whether the entry is a record of a file (a CSV row), which draws its place and its neighbours. */
+  recordNav: "hidden" | "shown";
+  /** Its place among the file's records: "3 of 11". */
+  place: string;
+  previousDisabled: boolean;
+  nextDisabled: boolean;
 }
 
 /** What the reader can do here. Both are decisions the editor owns. */
@@ -71,6 +78,10 @@ export interface EntryEditorActions {
   setDraft: (draft: boolean) => void;
   /** Open Project Settings › Content types — the door out of the `empty` stage. */
   openContentTypes: () => void;
+  /** A record: show the file's previous record, its next one, or the whole file in its grid. */
+  showPrevious: () => void;
+  showNext: () => void;
+  openGrid: () => void;
 }
 
 /** The node the document renders empty for somebody else to fill. */
@@ -89,7 +100,7 @@ export interface EntryEditorSurfaceHandle {
 }
 
 /** The scope the document reads: the view plus the actions, flat. */
-interface EntryEditorScope extends Record<string, unknown>, EntryEditorView, EntryEditorActions {}
+interface EntryEditorScope extends EntryEditorView, EntryEditorActions {}
 
 /** Write a whole view into the scope. Assignment only — the mount is never rebuilt for a repaint. */
 function project(scope: EntryEditorScope, view: EntryEditorView): void {
@@ -104,13 +115,16 @@ function project(scope: EntryEditorScope, view: EntryEditorView): void {
   scope.noteState = view.noteState;
   scope.note = view.note;
   scope.emptyLine = view.emptyLine;
+  scope.recordNav = view.recordNav;
+  scope.place = view.place;
+  scope.previousDisabled = view.previousDisabled;
+  scope.nextDisabled = view.nextDisabled;
 }
 
 /** The `part` a node was authored with, or `""` — the only thing this adapter asks about a node. */
-function partOf(def: unknown): string {
-  const attributes = (def as { attributes?: Record<string, unknown> } | null)?.attributes;
-  const part = attributes?.["part"];
-  return typeof part === "string" ? part : "";
+function partOf(def: JxElement | string): string {
+  const part = isString(def) ? undefined : def.attributes?.["part"];
+  return isString(part) ? part : "";
 }
 
 /**
@@ -133,7 +147,7 @@ export function mountEntryEditorSurface(
   islands: EntryEditorIslands,
 ): EntryEditorSurfaceHandle {
   host.replaceChildren();
-  const scope = reactive<EntryEditorScope>({
+  const scope: EntryEditorScope = reactive<EntryEditorScope>({
     collection: "",
     draft: false,
     draftAxis: "hidden",
@@ -141,13 +155,20 @@ export function mountEntryEditorSurface(
     emptyLine: "",
     fieldsRegion: "",
     name: "",
+    nextDisabled: true,
     note: "",
     noteState: "hidden",
     openContentTypes: actions.openContentTypes,
+    openGrid: actions.openGrid,
+    place: "",
+    previousDisabled: true,
+    recordNav: "hidden",
     region: "",
     setDraft: actions.setDraft,
+    showNext: actions.showNext,
+    showPrevious: actions.showPrevious,
     stage: "empty",
-  }) as EntryEditorScope;
+  });
   project(scope, view);
 
   let mounted: SurfaceHandle | null = null;
@@ -163,12 +184,15 @@ export function mountEntryEditorSurface(
       }
     },
   }).then((surface) => {
+    /* SAFETY: `entry-editor.json`'s root definition is a `div` element, so the runtime mounts an
+       HTMLElement; a `Text` root only comes from a document whose root is a bare string. */
+    const root = surface.root as HTMLElement;
     if (disposed) {
       surface.dispose();
-      return surface.root as HTMLElement;
+      return root;
     }
     mounted = surface;
-    return surface.root as HTMLElement;
+    return root;
   });
 
   return {