@jxsuite/studio 4.0.0 → 5.0.0

package/src/surfaces/logic-workspace.ts

@@ -0,0 +1,238 @@
+/// <reference lib="dom" />
+/**
+ * ⑪ · Logic — the Bottom dock tab, as a mounted document.
+ *
+ * This is the adapter. `panels/formula-workspace.ts` is the flow — it reads which of the two
+ * surfaces is open, resolves the expression at that document position, keeps the chip selection,
+ * evaluates the live preview and turns every edit into a transaction — and this is the surface it
+ * draws into. Nothing here reads a document, unrolls a tree or evaluates anything.
+ *
+ * **Three islands, all through `onNodeCreated`** (specs/studio-ui-guidelines.md §9.4).
+ * `[part="code-host"]` receives Monaco, `[part="editor-host"]` receives the expression editor —
+ * still a lit surface of its own, and another conversion's to move — and one `[part="tree-host"]`
+ * per data-rail entry receives the value tree, which is a mounted document of its own. Each is
+ * announced as it is CREATED, one reconcile step before it is in the page, so connectedness is
+ * deliberately not consulted: "is it connected" answers no for exactly the node that needs
+ * filling.
+ *
+ * **A host is held, never re-found.** A keyed `$map` keeps a rail entry's node across an update, so
+ * a tree host whose entry moved under it would still be showing the previous one's value; the flow
+ * repaints the hosts it holds after every projection rather than querying the tab for them.
+ *
+ * **The mount does not clear its host, and that is the difference between this seam and the
+ * Inspector's.** The Bottom dock renders its tabs with lit, and the Logic record draws `nothing` —
+ * so what the document is appended into still holds lit's own comment markers, and taking them away
+ * would break the dock's next paint. The runtime appends rather than replacing, so leaving them
+ * alone costs nothing; {@link LogicWorkspaceSurface.connected} is how the flow finds out that a
+ * repaint for another tab has swept the document away.
+ *
+ * @docs studio/logic/formula-workspace
+ */
+
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import logicWorkspaceDoc from "./logic-workspace.json";
+import type { JxDocument, JxElement } from "@jxsuite/schema/types";
+import type { JxScope } from "@jxsuite/runtime/types";
+import type { SurfaceHandle } from "../ui/surface";
+
+registerSurface("logic-workspace", logicWorkspaceDoc as unknown as JxDocument);
+
+/** One chip of the pipeline, as the document draws it. */
+export interface LogicChipView {
+  /** The joined node path: the repeater's key, the chip's `data-path`, and what a click reports. */
+  key: string;
+  /** The operand's label or the operator's spelling — the chip's text and its own tooltip. */
+  label: string;
+  /** The live value at this node. Empty draws nothing. */
+  badge: string;
+  /** Whether the preview has a value here at all: `""` is a legitimate one. */
+  hasBadge: boolean;
+}
+
+/** One entry of the data rail: a name in the canvas's scope, and what kind of value it holds. */
+export interface LogicScopeEntryView {
+  /** The entry name — the repeater's key, and the identity its tree host is announced with. */
+  key: string;
+  name: string;
+  /** `object`, `array (3)`, `string` — whatever `panels/data-explorer.ts` calls it. */
+  type: string;
+}
+
+/** Everything the Logic tab shows, already decided. */
+export interface LogicWorkspaceView {
+  /** `empty` (nothing open in the tab) or `ready`. */
+  state: string;
+  /** What the tab is for, said when nothing is open in it (§11.1). */
+  emptyMessage: string;
+  /** Which body the ready state draws: `formula`, `code`, or `missing`. */
+  surface: string;
+  /** `fx` or `ƒ` — which of the two things is open, before you read its name. */
+  glyph: string;
+  name: string;
+  /** `state expression`, `event handler` — the kind, beside the name. */
+  kind: string;
+  /** The title's tooltip: the document position, which the name alone does not give. */
+  titleHint: string;
+  /** The formula surface offers the catalog; the code surface has Monaco's own completions. */
+  hasCatalog: boolean;
+  /** The `missing` surface's sentence: a target the document no longer holds an expression at. */
+  missingMessage: string;
+  chips: LogicChipView[];
+  /** `root`, or the one-line summary of the chip-selected sub-node. */
+  selectedSummary: string;
+  hasScope: boolean;
+  scopeEmptyMessage: string;
+  scopeEntries: LogicScopeEntryView[];
+  /** `value`, `error` or `pending` — which of the three answers the result line is giving. */
+  resultTone: string;
+  resultText: string;
+  /** `(mutates target)`. Empty draws nothing. */
+  resultNote: string;
+  hasResultNote: boolean;
+}
+
+/** What the tab may ask the flow to do. */
+export interface LogicWorkspaceActions {
+  /** A chip was pressed; the key is the one the projection gave it. */
+  selectChip: (key: string) => void;
+  /** Open the formula catalog, anchored on the control that asked. */
+  browseCatalog: (anchor: HTMLElement) => void;
+  /** Close whichever surface is open. The only thing that clears the tab's target. */
+  close: () => void;
+}
+
+/** Where the flow's islands land. */
+export interface LogicWorkspaceIslands {
+  /** Monaco's container. */
+  codeSlot: (host: HTMLElement) => void;
+  /** The expression editor's container. */
+  editorSlot: (host: HTMLElement) => void;
+  /** One rail entry's value tree, announced with the entry name it belongs to. */
+  treeSlot: (key: string, host: HTMLElement) => void;
+}
+
+interface LogicWorkspaceScope
+  extends Record<string, unknown>, LogicWorkspaceView, LogicWorkspaceActions {}
+
+export interface LogicWorkspaceSurface {
+  /** Re-project. The document's bindings skip every value that did not move. */
+  update: (view: LogicWorkspaceView) => void;
+  /** Whether the mounted root is still where it was put. */
+  connected: () => boolean;
+  /** Resolves when the document has rendered, so a caller may read the DOM it drew. */
+  ready: Promise<void>;
+  dispose: () => void;
+}
+
+/** The tab with nothing open in it — the state it opens in, and the one Close returns it to. */
+export function emptyLogicWorkspaceView(): LogicWorkspaceView {
+  return {
+    chips: [],
+    emptyMessage: "",
+    glyph: "",
+    hasCatalog: false,
+    hasResultNote: false,
+    hasScope: false,
+    kind: "",
+    missingMessage: "",
+    name: "",
+    resultNote: "",
+    resultText: "",
+    resultTone: "pending",
+    scopeEmptyMessage: "",
+    scopeEntries: [],
+    selectedSummary: "",
+    state: "empty",
+    surface: "formula",
+    titleHint: "",
+  };
+}
+
+/** Assign the projection field by field: the runtime writes only the bindings that moved. */
+function project(scope: LogicWorkspaceScope, view: LogicWorkspaceView): void {
+  for (const [key, value] of Object.entries(view)) {
+    (scope as Record<string, unknown>)[key] = value;
+  }
+}
+
+/** The `part` a node was rendered with, or "". */
+function partOf(def: JxElement | string): string {
+  const part = typeof def === "string" ? undefined : def.attributes?.["part"];
+  return typeof part === "string" ? part : "";
+}
+
+/** The `key` of the `$map` item a node was rendered inside, or "". */
+function itemKey(state: JxScope | undefined): string {
+  const item = (state?.["$map"] as { item?: unknown } | undefined)?.item;
+  const key =
+    item !== null && typeof item === "object" ? (item as Record<string, unknown>).key : "";
+  return typeof key === "string" ? key : "";
+}
+
+/**
+ * Mount the Logic tab into `host` — the Bottom dock's body, which the dock re-paints for its other
+ * tabs and which therefore keeps whatever lit left in it.
+ *
+ * @param {HTMLElement} host The dock body the Logic tab was painted into.
+ * @param {LogicWorkspaceView} view The first projection.
+ * @param {LogicWorkspaceActions} actions What a control does; read once, when the surface is
+ *   mounted.
+ * @param {LogicWorkspaceIslands} islands Where Monaco, the expression editor and the trees land.
+ * @returns {LogicWorkspaceSurface}
+ */
+export function mountLogicWorkspace(
+  host: HTMLElement,
+  view: LogicWorkspaceView,
+  actions: LogicWorkspaceActions,
+  islands: LogicWorkspaceIslands,
+): LogicWorkspaceSurface {
+  const scope = reactive<LogicWorkspaceScope>({
+    ...emptyLogicWorkspaceView(),
+    ...actions,
+  } as LogicWorkspaceScope) as LogicWorkspaceScope;
+  project(scope, view);
+
+  let mounted: SurfaceHandle | null = null;
+  let disposed = false;
+  const ready = mountSurface("logic-workspace", scope, host, {
+    onNodeCreated: (element, _path, def, state) => {
+      if (!(element instanceof HTMLElement)) {
+        return;
+      }
+      const part = partOf(def);
+      if (part === "code-host") {
+        islands.codeSlot(element);
+      } else if (part === "editor-host") {
+        islands.editorSlot(element);
+      } else if (part === "tree-host") {
+        /* Read out of the node's own `$map` scope rather than off the element. A node is announced
+           when it is BUILT, one append before its attributes are settled, so `dataset` answers ""
+           for exactly the host that needs filling. */
+        islands.treeSlot(itemKey(state), element);
+      }
+    },
+  }).then((surface) => {
+    if (disposed) {
+      surface.dispose();
+      return;
+    }
+    mounted = surface;
+  });
+
+  return {
+    connected: () => {
+      const root = mounted?.root;
+      return root instanceof HTMLElement ? root.isConnected : !disposed;
+    },
+    dispose() {
+      disposed = true;
+      mounted?.dispose();
+      mounted = null;
+    },
+    ready,
+    update(next) {
+      project(scope, next);
+    },
+  };
+}

package/src/surfaces/media-browser.json

@@ -0,0 +1,303 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioMediaBrowser",
+  "$description": "The project's media, offered under whatever control asked for them. **Not the kit menu, and the difference is the thumbnails.** `surfaces/menu.json` is the settled answer to \"a list of actions\" and a `MenuRowProjection` carries a title, a chord and a gate — there is nowhere in it for a picture, nowhere for the size caption beside it, and a `jx-menu` is itself `popover=auto`, so a filter field cannot stand above one inside a panel. This is a browser: you pick an image by looking at it. **It is a `jx-popover`, so the PLATFORM owns dismissal** — light dismiss, Escape, the top layer and focus back to the invoker are the popover's contract, which is why nothing here binds a document listener and why the panel can paint over a modal `<dialog>` that the layer-div popover it replaces could not. The rows are plain buttons in a group, exactly as `grid-views.json`'s saved views are: a list of buttons is reachable by Tab, and a `role=\"listbox\"` would be a keyboard contract nothing here implements.",
+  "tagName": "jx-popover",
+  "attributes": {
+    "part": "media-browser"
+  },
+  "$props": {
+    "label": "Project media",
+    "x": {
+      "$ref": "#/state/x"
+    },
+    "y": {
+      "$ref": "#/state/y"
+    }
+  },
+  "children": [
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "body"
+      },
+      "style": {
+        "$description": "A search box that stays put and a list that scrolls under it. The panel itself never scrolls — `jx-popover` says why — so the box is here rather than on the host.",
+        "display": "flex",
+        "flexDirection": "column",
+        "gap": "var(--jx-space-2)",
+        "padding": "var(--jx-space-2)",
+        "minWidth": "260px",
+        "maxHeight": "360px",
+        "fontFamily": "var(--jx-font-sans)",
+        "fontSize": "var(--jx-text-md)",
+        "color": "var(--fg)",
+        "& [part=\"rows\"]": {
+          "display": "flex",
+          "flexDirection": "column",
+          "gap": "2px",
+          "overflowY": "auto",
+          "minHeight": "0"
+        },
+        "& [part=\"row\"]": {
+          "display": "flex",
+          "alignItems": "center",
+          "gap": "var(--jx-space-2)",
+          "textAlign": "left",
+          "background": "none",
+          "border": "none",
+          "color": "var(--fg)",
+          "font": "inherit",
+          "padding": "var(--jx-space-1) var(--jx-space-2)",
+          "borderRadius": "var(--jx-radius-sm)",
+          "cursor": "pointer",
+          "minWidth": "0"
+        },
+        "& [part=\"row\"]:hover": {
+          "background": "var(--bg-hover)"
+        },
+        "& [part=\"row\"]:focus-visible": {
+          "outline": "var(--jx-focus-ring)",
+          "outlineOffset": "-2px"
+        },
+        "& [part=\"row-thumb\"]": {
+          "width": "24px",
+          "height": "24px",
+          "objectFit": "cover",
+          "borderRadius": "var(--jx-radius-sm)",
+          "flexShrink": "0"
+        },
+        "& [part=\"row-text\"]": {
+          "display": "flex",
+          "flexDirection": "column",
+          "minWidth": "0"
+        },
+        "& [part=\"row-name\"]": {
+          "overflow": "hidden",
+          "textOverflow": "ellipsis",
+          "whiteSpace": "nowrap"
+        },
+        "& [part=\"row-caption\"]": {
+          "color": "var(--fg-dim)",
+          "fontSize": "var(--jx-text-xs)"
+        },
+        "& [part=\"empty\"]": {
+          "margin": "0",
+          "color": "var(--fg-dim)",
+          "fontSize": "var(--jx-text-xs)"
+        },
+        "& [part=\"more\"]": {
+          "margin": "0",
+          "color": "var(--fg-dim)",
+          "fontSize": "var(--jx-text-xs)"
+        }
+      },
+      "children": [
+        {
+          "tagName": "jx-textfield",
+          "attributes": {
+            "part": "filter"
+          },
+          "$props": {
+            "type": "search",
+            "size": "sm",
+            "label": "Search media",
+            "placeholder": "Search media…",
+            "autocomplete": "off",
+            "value": {
+              "$ref": "#/state/filter"
+            }
+          },
+          "oninput": {
+            "$prototype": "Function",
+            "body": [
+              {
+                "operator": "call",
+                "target": {
+                  "$ref": "#/state/setFilter"
+                },
+                "value": [
+                  {
+                    "$ref": "event#/target/value"
+                  }
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "tagName": "div",
+          "attributes": {
+            "part": "rows-slot",
+            "role": "none"
+          },
+          "style": {
+            "display": "contents"
+          },
+          "$switch": {
+            "$ref": "#/state/rowsState"
+          },
+          "cases": {
+            "empty": {
+              "tagName": "p",
+              "attributes": {
+                "part": "empty"
+              },
+              "textContent": "${state.emptyLabel}"
+            },
+            "listed": {
+              "tagName": "div",
+              "attributes": {
+                "part": "rows"
+              },
+              "children": [
+                {
+                  "$prototype": "Array",
+                  "items": {
+                    "$ref": "#/state/rows"
+                  },
+                  "key": {
+                    "$ref": "$map/item/key"
+                  },
+                  "map": {
+                    "$description": "One file. The row hands back the value a pick writes — the site URL — rather than an index, so the list may be filtered under it without changing what any row means.",
+                    "tagName": "button",
+                    "attributes": {
+                      "part": "row",
+                      "type": "button",
+                      "data-path": "${$map.item.path}"
+                    },
+                    "onclick": {
+                      "$prototype": "Function",
+                      "body": [
+                        {
+                          "operator": "call",
+                          "target": {
+                            "$ref": "#/state/pick"
+                          },
+                          "value": [
+                            {
+                              "$ref": "$map/item/path"
+                            }
+                          ]
+                        }
+                      ]
+                    },
+                    "children": [
+                      {
+                        "tagName": "span",
+                        "attributes": {
+                          "part": "row-thumb-slot",
+                          "role": "none"
+                        },
+                        "style": {
+                          "display": "contents"
+                        },
+                        "$switch": {
+                          "$ref": "$map/item/thumbState"
+                        },
+                        "cases": {
+                          "shown": {
+                            "$description": "Decorative: the row's own text names the file. The load handler is the whole of the dimensions caption — measuring an image is a decode the `<img>` has finished by the time `load` fires, so the numbers are a read of work already done rather than a second fetch per row.",
+                            "tagName": "img",
+                            "attributes": {
+                              "part": "row-thumb",
+                              "src": "${$map.item.thumbSrc}",
+                              "alt": ""
+                            },
+                            "onload": {
+                              "$prototype": "Function",
+                              "body": [
+                                {
+                                  "operator": "call",
+                                  "target": {
+                                    "$ref": "#/state/measure"
+                                  },
+                                  "value": [
+                                    {
+                                      "$ref": "$map/item/file"
+                                    },
+                                    {
+                                      "$ref": "event#/target/naturalWidth"
+                                    },
+                                    {
+                                      "$ref": "event#/target/naturalHeight"
+                                    }
+                                  ]
+                                }
+                              ]
+                            }
+                          }
+                        }
+                      },
+                      {
+                        "tagName": "span",
+                        "attributes": {
+                          "part": "row-text"
+                        },
+                        "children": [
+                          {
+                            "tagName": "span",
+                            "attributes": {
+                              "part": "row-name"
+                            },
+                            "textContent": "${$map.item.name}"
+                          },
+                          {
+                            "tagName": "span",
+                            "attributes": {
+                              "part": "row-caption-slot",
+                              "role": "none"
+                            },
+                            "style": {
+                              "display": "contents"
+                            },
+                            "$switch": {
+                              "$ref": "$map/item/captionState"
+                            },
+                            "cases": {
+                              "shown": {
+                                "tagName": "span",
+                                "attributes": {
+                                  "part": "row-caption"
+                                },
+                                "textContent": "${$map.item.caption}"
+                              }
+                            }
+                          }
+                        ]
+                      }
+                    ]
+                  }
+                }
+              ]
+            }
+          }
+        },
+        {
+          "tagName": "div",
+          "attributes": {
+            "part": "more-slot",
+            "role": "none"
+          },
+          "style": {
+            "display": "contents"
+          },
+          "$switch": {
+            "$ref": "#/state/moreState"
+          },
+          "cases": {
+            "shown": {
+              "$description": "A truncated list says so. Fifty rows is the cap the list has always had; the sentence is what keeps the cap from reading as \"that is all there is\".",
+              "tagName": "p",
+              "attributes": {
+                "part": "more"
+              },
+              "textContent": "${state.moreLabel}"
+            }
+          }
+        }
+      ]
+    }
+  ]
+}

package/src/surfaces/media-browser.ts

@@ -0,0 +1,145 @@
+/// <reference lib="dom" />
+/**
+ * The project's media browser, as a mounted document.
+ *
+ * This is the adapter. `ui/media-picker.ts` is the flow — which files count as media, what a row's
+ * caption says, what a pick writes and what a loaded thumbnail is worth — and this is the panel it
+ * draws into. Every row arrives already decided: a name, a URL, two words of caption, and the
+ * string a pick commits.
+ *
+ * **The platform owns dismissal.** The root is a `jx-popover`, so Escape, light dismissal, the top
+ * layer and focus back to the invoker are its contract rather than three document listeners and a
+ * `z-index` chosen from the layer the anchor happened to be in. That is not only tidier: an overlay
+ * drawn into a layer div paints UNDERNEATH a modal `<dialog>` and is inert besides (`specs/ui.md`
+ * §7), which is the whole reason `panels/seo-modal.ts` had to fork its own Browse onto the kit
+ * menu, and a top-layer popover has no such problem.
+ *
+ * **The filter takes the caret, and the adapter is what puts it there.** A `jx-popover` moves focus
+ * into itself but has no opinion about which control; the panel is a search box over a list, so the
+ * box is where typing should land. The node is reached through the mounted root rather than a
+ * document-wide selector, the way `surfaces/slash-menu.ts` reaches its own.
+ *
+ * @docs studio/projects/media
+ */
+
+import { openPopoverSurface } from "../ui/popover-surface";
+import { reactive } from "../reactivity";
+import { registerSurface } from "../ui/surface";
+import mediaBrowserDoc from "./media-browser.json";
+import type { JxDocument } from "@jxsuite/schema/types";
+import type { PopoverSurfaceHandle } from "../ui/popover-surface";
+
+registerSurface("media-browser", mediaBrowserDoc as unknown as JxDocument);
+
+/** The slot id, and so the panel's region: `overlay.menu:media-picker`. */
+const SLOT = "media-picker";
+
+/** One browsable file, in the shape the document reads. */
+export interface MediaBrowserRow {
+  /** The row's identity across a filter keystroke: the file's path on disk. */
+  key: string;
+  /** What a pick commits — the site URL, which is the authored form. */
+  path: string;
+  /** The project-relative file, which is the key every measurement is stored under. */
+  file: string;
+  name: string;
+  thumbState: "hidden" | "shown";
+  thumbSrc: string;
+  captionState: "hidden" | "shown";
+  /** "1200 × 800 · 84 KB", or the half of it that is known. */
+  caption: string;
+}
+
+/** Everything the panel draws, as one value. */
+export interface MediaBrowserView {
+  /** Where the panel opens, in viewport pixels. The kit clamps it into the viewport. */
+  x: number;
+  y: number;
+  filter: string;
+  rowsState: "empty" | "listed";
+  rows: MediaBrowserRow[];
+  /** What stands in for the list when nothing matches. */
+  emptyLabel: string;
+  moreState: "hidden" | "shown";
+  /** "…10 more" — the cap is fifty and a truncated list says so. */
+  moreLabel: string;
+}
+
+/** What a control asks the flow to do. */
+export interface MediaBrowserActions {
+  setFilter: (value: string) => void;
+  pick: (path: string) => void;
+  /** A thumbnail finished decoding at that size. The flow decides whether it is news. */
+  measure: (file: string, width: number, height: number) => void;
+  /** The platform closed the panel: clicked outside, Escape, or a second press on the invoker. */
+  dismissed?: () => void;
+}
+
+export interface MediaBrowserSurfaceHandle extends PopoverSurfaceHandle {
+  update: (view: MediaBrowserView) => void;
+}
+
+interface MediaBrowserScope
+  extends Record<string, unknown>, MediaBrowserView, Omit<MediaBrowserActions, "dismissed"> {}
+
+/** Write a projection into the scope. */
+function project(scope: MediaBrowserScope, view: MediaBrowserView): void {
+  scope.x = view.x;
+  scope.y = view.y;
+  scope.filter = view.filter;
+  scope.rowsState = view.rowsState;
+  scope.rows = view.rows;
+  scope.emptyLabel = view.emptyLabel;
+  scope.moreState = view.moreState;
+  scope.moreLabel = view.moreLabel;
+}
+
+/**
+ * Open the media browser under `anchor`.
+ *
+ * @param {MediaBrowserView} view - What it shows to begin with
+ * @param {MediaBrowserActions} actions - What each control does
+ * @param {HTMLElement | null} anchor - The control it was opened from
+ * @returns {MediaBrowserSurfaceHandle}
+ */
+export function openMediaBrowserSurface(
+  view: MediaBrowserView,
+  actions: MediaBrowserActions,
+  anchor: HTMLElement | null,
+): MediaBrowserSurfaceHandle {
+  const scope = reactive<MediaBrowserScope>({
+    emptyLabel: view.emptyLabel,
+    filter: view.filter,
+    measure: actions.measure,
+    moreLabel: view.moreLabel,
+    moreState: view.moreState,
+    pick: actions.pick,
+    rows: view.rows,
+    rowsState: view.rowsState,
+    setFilter: actions.setFilter,
+    x: view.x,
+    y: view.y,
+  }) as MediaBrowserScope;
+
+  const handle = openPopoverSurface({
+    anchor,
+    name: "media-browser",
+    scope,
+    slot: SLOT,
+    ...(actions.dismissed ? { onDismissed: actions.dismissed } : {}),
+  });
+
+  void handle.ready.then(() => {
+    if (handle.isOpen()) {
+      handle.host.querySelector<HTMLInputElement>('[part="filter"] [part="input"]')?.focus();
+    }
+  });
+
+  return {
+    close: handle.close,
+    host: handle.host,
+    isOpen: handle.isOpen,
+    ready: handle.ready,
+    update: (next) => project(scope, next),
+  };
+}