@jxsuite/studio 4.0.0 → 5.0.0

package/src/surfaces/panel-activity.ts

@@ -0,0 +1,187 @@
+/// <reference lib="dom" />
+/**
+ * The Activity feed, as a Jx document over the kit.
+ *
+ * This is the adapter. `panels/activity-panel.ts` keeps the record — what an operation is, what its
+ * log holds, what Cancel does to it and when a finished one retires — and hands this module a
+ * projection plus the three things a click can ask for. The document
+ * (`surfaces/panel-activity.json`) renders that and decides nothing.
+ *
+ * **The projection is flattened on the panel's side**, for the reason
+ * `surfaces/settings-overview.ts` gives: a document's only conditional is `$switch` over a value,
+ * so "does this entry have a log, and is it unfolded" is two questions the panel answers before the
+ * scope is written.
+ *
+ * **One effect, not a repaint.** The Bottom dock used to re-render the whole tab whenever anything
+ * in the activity store moved, because `render()` read the store from inside the dock's own effect.
+ * A document has no render, so the subscription moved here: {@link mountActivitySurface} opens an
+ * effect scope that reads {@link ActivitySurfaceDeps.project} and writes the result into the scope,
+ * and the runtime updates exactly the bindings whose values changed. A log line appended to an open
+ * row is one text write, not a repaint of twenty rows.
+ *
+ * **Mounting is idempotent because `afterRender` is not.** A panel's hook runs on EVERY paint of
+ * the dock — showing or not (`panels/bottom-dock.ts`) — so this keeps the standing surface when it
+ * is handed the container it is already in, and only mounts into one the document has been taken
+ * out of.
+ *
+ * @docs studio/interface/problems-and-progress
+ */
+
+import { effect, effectScope, reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import activityDoc from "./panel-activity.json";
+import type { EffectScope } from "@vue/reactivity";
+import type { JxDocument } from "@jxsuite/schema/types";
+import type { SurfaceHandle } from "../ui/surface";
+
+registerSurface("panel-activity", activityDoc as unknown as JxDocument);
+
+/** One declared phase of an operation, as the surface reads it. */
+export interface ActivityStepView {
+  /** Stable within the row, so a step list reconciles instead of being rebuilt. */
+  key: string;
+  label: string;
+  /** Drives the row's colour through `data-state`. */
+  state: string;
+  /** The one-character glyph the panel chose for that state. */
+  icon: string;
+}
+
+/** One operation, as the surface reads it. */
+export interface ActivityRowView {
+  id: string;
+  /** `running` | `done` | `failed` | `cancelled`, as `data-state`. */
+  state: string;
+  icon: string;
+  title: string;
+  source: string;
+  hasSource: boolean;
+  /** How long it has taken, already in the coarsest unit that is still true. */
+  duration: string;
+  status: string;
+  hasStatus: boolean;
+  steps: ActivityStepView[];
+  hasSteps: boolean;
+  /** The captured output, already joined — a document renders text, not an array. */
+  logText: string;
+  hasLog: boolean;
+  /** The disclosure's whole wording, which is also its state. */
+  logLabel: string;
+  expanded: boolean;
+  /** `hasLog && expanded`, so the `<pre>` is one `$switch` rather than two nested ones. */
+  showLog: boolean;
+  cancellable: boolean;
+}
+
+/** What the panel says the surface should be showing right now. */
+export interface ActivityView {
+  rows: ActivityRowView[];
+  hasRows: boolean;
+  hasFinished: boolean;
+  /** "Clear 3 finished" — the count is the panel's, so the document holds no arithmetic. */
+  clearLabel: string;
+}
+
+/** What the surface needs from the panel: one projection, and the three decisions it can ask for. */
+export interface ActivitySurfaceDeps {
+  /**
+   * Recompute what the feed shows.
+   *
+   * Called from inside this surface's own effect, so every reactive record it reads on the way —
+   * the activity list, an entry's status, its log — is tracked, and the surface follows a running
+   * operation with nothing subscribing by hand.
+   */
+  project: () => ActivityView;
+  cancel: (id: string) => void;
+  clearFinished: () => void;
+  toggleLog: (id: string) => void;
+}
+
+/** The scope the document reads: the projection, flattened, beside the three callbacks. */
+interface ActivityScope extends Record<string, unknown> {
+  rows: ActivityRowView[];
+  hasRows: boolean;
+  hasFinished: boolean;
+  clearLabel: string;
+  cancel: (id: string) => void;
+  clearFinished: () => void;
+  toggleLog: (id: string) => void;
+}
+
+let _container: HTMLElement | null = null;
+let _scope: EffectScope | null = null;
+let _mount: Promise<SurfaceHandle> | null = null;
+let _handle: SurfaceHandle | null = null;
+
+/** Write a projection into the scope. Replacing `rows` wholesale is what the keyed map wants. */
+function write(scope: ActivityScope, view: ActivityView): void {
+  scope.rows = view.rows;
+  scope.hasRows = view.hasRows;
+  scope.hasFinished = view.hasFinished;
+  scope.clearLabel = view.clearLabel;
+}
+
+/** Whether the document this mounted is still standing in `container`. */
+function standingIn(container: HTMLElement): boolean {
+  if (_container !== container) {
+    return false;
+  }
+  // Still mounting into this very container: a second call must not start a second mount.
+  return _handle === null ? _mount !== null : (_handle.root as Node).parentNode === container;
+}
+
+/**
+ * Draw the feed into `container`, or leave the one already there alone.
+ *
+ * @param {HTMLElement} container The element the panel's template paints for it
+ * @param {ActivitySurfaceDeps} deps The panel's projection and its three callbacks
+ */
+export function mountActivitySurface(container: HTMLElement, deps: ActivitySurfaceDeps): void {
+  if (standingIn(container)) {
+    return;
+  }
+  disposeActivitySurface();
+  _container = container;
+  const scope = reactive<ActivityScope>({
+    cancel: deps.cancel,
+    clearFinished: deps.clearFinished,
+    clearLabel: "",
+    hasFinished: false,
+    hasRows: false,
+    rows: [],
+    toggleLog: deps.toggleLog,
+  }) as ActivityScope;
+  _scope = effectScope();
+  _scope.run(() => {
+    effect(() => {
+      write(scope, deps.project());
+    });
+  });
+  /* Nothing is called on an element here, so the mount is all there is to wait for: the DOCUMENT is
+     what this surface renders, and the kit elements inside it settle their own templates one
+     `connectedCallback` later without anybody asking them to (studio-ui-guidelines.md §1.1). */
+  const pending = mountSurface("panel-activity", scope, container);
+  _mount = pending;
+  void pending.then((handle) => {
+    if (_mount === pending) {
+      _handle = handle;
+    } else {
+      handle.dispose();
+    }
+  });
+}
+
+/** Take the feed down and forget its container. Idempotent. */
+export function disposeActivitySurface(): void {
+  _scope?.stop();
+  _scope = null;
+  const pending = _mount;
+  _mount = null;
+  if (_handle) {
+    _handle.dispose();
+    _handle = null;
+  } else if (pending) {
+    void pending.then((handle) => handle.dispose());
+  }
+  _container = null;
+}

package/src/surfaces/panel-data.json

@@ -0,0 +1,141 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioPanelData",
+  "$description": "Navigator › Data: the value tree under one state entry — what the canvas resolved that entry to, a line per key. The rows arrive FLAT. JSON nests to any depth and a document's one repeater is `$prototype: \"Array\"` over a list, so `panels/data-explorer.ts` walks the value once, applies the item, key and depth caps, and hands over rows that already carry their own indent; recursion is a property of the walk rather than of the markup. Two kinds of line come out of it: a key and the value beside it, and a truncation marker, which is a real button because the reader opened this panel BECAUSE item 40 was the surprising one. The adapter decides what a value reads as and what a marker raises; nothing here knows about the canvas.",
+  "tagName": "div",
+  "attributes": {
+    "part": "tree"
+  },
+  "style": {
+    "$description": "The whole of the tree's look, and two things about it are the conversion. THE SYNTAX COLOURS MOVED: `--data-key` was declared on `<sp-theme>` in `styles/spectrum.css`, where Spectrum's own ramp was in scope, and this document is mounted in the Navigator — outside that element every `var(--data-key)` would have silently taken its hex fallback and stopped following the theme, so the key colour is `var(--accent)`, which is the studio token `--spectrum-blue-700` was chosen to match. Its three neighbours (`--data-string`, `--data-number`, `--data-boolean`) were NOT re-pointed, because no rule ever read them: they were declared for a palette nobody wrote, and inventing one here would have been a visual change nobody asked for. So when `styles/spectrum.css` was deleted the three were not re-homed either — this paragraph is the whole of what remains of them. `data-tone` still carries the type on every value, so the day that palette is designed it has somewhere to land. AND THE INDENT IS A VARIABLE: a row's depth used to be an inline `style=\"padding-left:…\"`, which is one rule per row once the padding is a declaration; `--row-indent` is written inline under its own name and read by one shared rule, so a hundred-row tree interns one.",
+    "display": "block",
+    "& [part=\"row\"], & [part=\"more\"]": {
+      "$description": "Every line, whichever kind. One line high and clipped rather than wrapped: a tree that reflows a long string across three lines stops being a column of keys you can scan.",
+      "display": "block",
+      "boxSizing": "border-box",
+      "width": "100%",
+      "paddingTop": "1px",
+      "paddingBottom": "1px",
+      "paddingRight": "8px",
+      "paddingLeft": "var(--row-indent, 8px)",
+      "fontSize": "var(--jx-text-sm)",
+      "fontFamily": "var(--font-mono, monospace)",
+      "lineHeight": "1.5",
+      "whiteSpace": "nowrap",
+      "overflow": "hidden",
+      "textOverflow": "ellipsis"
+    },
+    "& [part=\"key\"]": {
+      "$description": "The key or index this line is under. Empty for the single line a primitive value renders as, which is why it is always drawn: a span with nothing in it takes no width, and switching it in and out would cost a wrapper element per row to save nothing.",
+      "color": "var(--accent)"
+    },
+    "& [part=\"value\"]": {
+      "color": "var(--fg)"
+    },
+    "& [part=\"value\"][data-tone=\"null\"], & [part=\"value\"][data-tone=\"object\"]": {
+      "$description": "Not a value you are reading: an absence, or a summary standing in for the lines underneath it. Both are dimmed and italic so the eye passes over them on the way to what is real.",
+      "color": "var(--fg-dim)",
+      "fontStyle": "italic"
+    },
+    "& [part=\"more\"]": {
+      "$description": "A truncation marker is a CONTROL, not a caption — it shows more of what the panel already has in hand. Dressed as the text it replaced so the tree does not sprout buttons, and stripped of the chrome a `<button>` brings with it, but focusable and hoverable so that it reads as pressable.",
+      "textAlign": "left",
+      "background": "none",
+      "border": "none",
+      "color": "var(--fg-dim)",
+      "fontStyle": "italic",
+      "cursor": "pointer"
+    },
+    "& [part=\"more\"]:hover, & [part=\"more\"]:focus-visible": {
+      "color": "var(--accent)",
+      "textDecoration": "underline"
+    }
+  },
+  "children": [
+    {
+      "$prototype": "Array",
+      "items": {
+        "$ref": "#/state/rows"
+      },
+      "key": {
+        "$ref": "$map/item/key"
+      },
+      "map": {
+        "tagName": "div",
+        "attributes": {
+          "part": "line-slot",
+          "role": "none"
+        },
+        "style": {
+          "display": "contents"
+        },
+        "$switch": {
+          "$ref": "$map/item/kind"
+        },
+        "cases": {
+          "row": {
+            "tagName": "div",
+            "attributes": {
+              "part": "row"
+            },
+            "style": {
+              "--row-indent": {
+                "$ref": "$map/item/indent"
+              }
+            },
+            "children": [
+              {
+                "tagName": "span",
+                "attributes": {
+                  "part": "key"
+                },
+                "textContent": "${$map.item.label}"
+              },
+              {
+                "tagName": "span",
+                "attributes": {
+                  "part": "value",
+                  "data-tone": "${$map.item.tone}"
+                },
+                "textContent": "${$map.item.text}"
+              }
+            ]
+          },
+          "more": {
+            "tagName": "button",
+            "attributes": {
+              "part": "more",
+              "type": "button",
+              "title": "${$map.item.title}"
+            },
+            "style": {
+              "--row-indent": {
+                "$ref": "$map/item/indent"
+              }
+            },
+            "textContent": "${$map.item.text}",
+            "onclick": {
+              "$prototype": "Function",
+              "body": [
+                {
+                  "operator": "call",
+                  "target": {
+                    "$ref": "#/state/showMore"
+                  },
+                  "value": [
+                    {
+                      "$ref": "$map/item/path"
+                    },
+                    {
+                      "$ref": "$map/item/limit"
+                    }
+                  ]
+                }
+              ]
+            }
+          }
+        }
+      }
+    }
+  ]
+}

package/src/surfaces/panel-data.ts

@@ -0,0 +1,156 @@
+/// <reference lib="dom" />
+/**
+ * The Data panel's value tree, as a Jx document over the kit.
+ *
+ * This is the adapter. `panels/data-explorer.ts` keeps the tree — what a value reads as, where the
+ * item, key and depth caps fall, and what raising one means — and hands this module a flat list of
+ * rows that already carry their own indent. The document renders that list and nothing else.
+ *
+ * The flattening happens on this side of the seam for the same reason the Overview section flattens
+ * its error into five booleans: a document's one repeater walks a LIST, and JSON nests to any
+ * depth, so the recursion belongs to the walk rather than to the markup.
+ *
+ * **One document per tree, and there are several at once.** The Data panel opens as many rows as
+ * the reader asks it to, each with its own value under it, so this module is keyed by host rather
+ * than being a singleton: a repaint finds the mount already standing in a host and only assigns to
+ * its scope, which is what keeps the reader's scroll position inside a long tree and stops a
+ * repeated `afterRender` from rebuilding what is already on screen.
+ *
+ * @docs studio/logic/data
+ */
+
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import dataTreeDoc from "./panel-data.json";
+import type { JxDocument } from "@jxsuite/schema/types";
+import type { SurfaceHandle } from "../ui/surface";
+
+registerSurface("panel-data", dataTreeDoc as unknown as JxDocument);
+
+/**
+ * One line of a value tree, as the document reads it.
+ *
+ * Every field is a string, because a binding renders text and a `$switch` chooses on a value: the
+ * shape of a line is decided here, not by a conditional the document does not have.
+ */
+export interface DataTreeRow {
+  /**
+   * Unique within one tree, and the repeater's key. A raised limit re-renders the whole list, and a
+   * keyed row that survives keeps its node — so showing fifty more items does not rebuild the
+   * twenty already on screen.
+   */
+  key: string;
+  /** `"row"` for a key and its value; `"more"` for a truncation marker, which is a button. */
+  kind: "row" | "more";
+  /** This line's own indent, as a CSS length. Depth is a property of the row, not of the tree. */
+  indent: string;
+  /** `"[0] "` or `"name: "`. Empty for the one line a primitive value renders as. */
+  label: string;
+  /** What the line says: the value's JSON text, `Array(3)`/`{2}`, or the marker's own label. */
+  text: string;
+  /**
+   * Which colour the value takes: the JSON type name, `"null"`, or `"object"` for a summary label
+   * standing in for the lines beneath it. Only the last two are painted today (see the document's
+   * style block); the type is carried anyway, so a syntax palette has somewhere to land.
+   */
+  tone: string;
+  /** A marker's tooltip. Empty on a value row. */
+  title: string;
+  /** The subtree a marker raises the limit of. Empty on a value row. */
+  path: string;
+  /** Which of that subtree's limits it raises — `items`, `keys` or `depth`. Empty on a value row. */
+  limit: string;
+}
+
+/** What a marker can ask the panel to do. The panel owns the limit and the repaint. */
+export interface DataTreeActions {
+  /** Show more of one subtree: raise `limit` on `path` by a step, then repaint the Navigator. */
+  showMore: (path: string, limit: string) => void;
+}
+
+/** The scope the document reads. */
+interface DataTreeScope extends Record<string, unknown>, DataTreeActions {
+  rows: DataTreeRow[];
+}
+
+interface Mounted {
+  scope: DataTreeScope;
+  /** `null` while the mount is still in flight — which is a standing surface, not a missing one. */
+  handle: SurfaceHandle | null;
+  /** Set when the host was given up, so a mount that settles afterwards takes itself down. */
+  disposed: boolean;
+}
+
+/**
+ * Every standing tree, by the host it was mounted into.
+ *
+ * A strong `Map` rather than a `WeakMap`: `mountSurface` records each mount in the surface registry
+ * by host, so a tree whose row was collapsed has to be DISPOSED rather than merely forgotten, and
+ * {@link disposeDetachedDataTrees} is what walks this to find them.
+ */
+const mounts = new Map<HTMLElement, Mounted>();
+
+/**
+ * Draw one value tree into `host`, or bring the one already there up to date.
+ *
+ * @param {HTMLElement} host The element the panel's template left for this tree.
+ * @param {DataTreeRow[]} rows The flattened tree, in the order it is read.
+ * @param {DataTreeActions} actions What a marker may do — read once, when the surface is mounted.
+ */
+export function renderDataTreeSurface(
+  host: HTMLElement,
+  rows: DataTreeRow[],
+  actions: DataTreeActions,
+): void {
+  const existing = mounts.get(host);
+  if (
+    existing &&
+    !existing.disposed &&
+    (existing.handle === null || existing.handle.root.isConnected)
+  ) {
+    existing.scope.rows = rows;
+    return;
+  }
+  takeDown(host, existing);
+  host.textContent = "";
+  const scope = reactive({ rows, showMore: actions.showMore }) as DataTreeScope;
+  const record: Mounted = { disposed: false, handle: null, scope };
+  mounts.set(host, record);
+  /* No race to arbitrate: a repaint arriving while this is in flight takes the branch above — a
+     record with no handle yet IS the standing one — so a second mount into the same host cannot
+     start before this settles. A host given up in the meantime is what `disposed` answers. */
+  void mountSurface("panel-data", scope, host).then((handle) => {
+    if (record.disposed) {
+      handle.dispose();
+      return;
+    }
+    record.handle = handle;
+  });
+}
+
+/**
+ * Take down every tree whose host has left the document.
+ *
+ * A row the reader collapsed takes its host with it, and the mount registry holds the host by
+ * reference, so nothing would ever release it. Called once at the top of each of the panel's
+ * post-render passes rather than per host, which is the only moment this module hears about a
+ * collapse at all.
+ */
+export function disposeDetachedDataTrees(): void {
+  for (const [host, record] of mounts) {
+    if (!host.isConnected) {
+      takeDown(host, record);
+    }
+  }
+}
+
+/** Give up a host: stop its mount (or the one still arriving) and forget it. */
+function takeDown(host: HTMLElement, record: Mounted | undefined): void {
+  if (!record) {
+    return;
+  }
+  record.disposed = true;
+  record.handle?.dispose();
+  record.handle = null;
+  mounts.delete(host);
+}