@jxsuite/studio 4.1.0 → 5.0.0

package/src/surfaces/doc-header.ts

@@ -0,0 +1,223 @@
+/// <reference lib="dom" />
+/**
+ * The Document Header card, as a Jx document over the kit.
+ *
+ * This is the adapter. `panels/frontmatter-panel.ts` keeps the card — which document it is drawn
+ * for, which rows that document has, what each row commits into and where a media or reference row
+ * gets its choices — and hands this module one projection whose every field is already a string.
+ * The document draws it and decides nothing.
+ *
+ * **One row vocabulary, and the discriminant is what a row LOOKS like rather than what it means.**
+ * Title, the Layout picker and every schema-driven frontmatter field are the same `row`; they
+ * differ in what they write, and what they write is reached by the row's `key` through the flow's
+ * own table. That is why {@link DocHeaderRow.key} and {@link DocHeaderRow.prop} are two fields:
+ * `key` is the identity the repeater and every action use, `prop` is the name a reader and the
+ * inspector see. A collection whose schema declares a `layout` property would otherwise share an
+ * identity with the Layout picker.
+ *
+ * **The card is mounted once per PANE.** Two stages can each be drawing a header, so this module is
+ * keyed by nothing at all: it hands back a handle and the flow holds one per pane. A repaint only
+ * ASSIGNS to the standing scope — rebuilding the mount would take a field out from under a reader
+ * mid-edit, which is the whole reason the lit card needed a focus-aware scheduler and the reason
+ * this one does not.
+ *
+ * @docs studio/editing/frontmatter
+ */
+
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import docHeaderDoc from "./doc-header.json";
+import type { JxDocument } from "@jxsuite/schema/types";
+import type { SurfaceHandle } from "../ui/surface";
+
+registerSurface("doc-header", docHeaderDoc as unknown as JxDocument);
+
+/** One choice in a row's picker. The shape `jx-select` reads. */
+export interface DocHeaderChoice {
+  value: string;
+  label: string;
+}
+
+/**
+ * One row of the card, as the document reads it.
+ *
+ * Every field is present on every row whatever its `kind`, because a binding renders a value and a
+ * `$switch` chooses on one: a row that omitted `options` would leave the picker case reading an
+ * absent path.
+ */
+export interface DocHeaderRow extends Record<string, unknown> {
+  /** The row's identity: the repeater's key, and the argument every action is given. */
+  key: string;
+  /** The name on `data-prop` — what a reader, a screenshot region and the inspector call it. */
+  prop: string;
+  /** The visible label, already carrying the required marker where the schema asks for one. */
+  label: string;
+  /** Which control the row draws. */
+  kind: "text" | "number" | "boolean" | "select" | "media";
+  /** Whether the value is set on this document — §4.2's dot, and the row's only clear affordance. */
+  isSet: boolean;
+  /** The dot's accessible name and tooltip, e.g. `Clear title`. */
+  clearLabel: string;
+  /** The text, number or chosen value, always as a string. Empty for a boolean row. */
+  value: string;
+  /** A boolean row's state. `false` on every other kind. */
+  checked: boolean;
+  /** A text row's placeholder. Empty draws none. */
+  placeholder: string;
+  /** A picker's rows, in the order they are offered. Empty on every other kind. */
+  options: DocHeaderChoice[];
+  /** A sentence under the control — an empty collection, or a listing that failed. */
+  note: string;
+  /** Whether {@link DocHeaderRow.note} has anything in it; `$switch` is the document's conditional. */
+  hasNote: boolean;
+  /** A media row's thumbnail source. Empty draws none. */
+  thumb: string;
+  /** Whether {@link DocHeaderRow.thumb} has anything in it. */
+  hasThumb: boolean;
+}
+
+/** One `$head` entry the disclosure lists, read-only. */
+export interface DocHeaderRawEntry extends Record<string, unknown> {
+  /** Unique within one document — the repeater's key. */
+  key: string;
+  /** The entry as markup, e.g. `<meta name="author">`. */
+  label: string;
+  /** What it says, shown after the label and as its tooltip. */
+  value: string;
+}
+
+/** What the card is showing right now. */
+export interface DocHeaderView {
+  /** The region id the card stamps on itself — `pane.<id>/frontmatter`. */
+  region: string;
+  /** `in-column` in Edit, `pinned` in Design. The stage decides; the card only draws it. */
+  placement: "in-column" | "pinned";
+  /** The matched collection's name, or the word `Document` when it belongs to none. */
+  collection: string;
+  /** This page's route. */
+  route: string;
+  /** Whether there is a route to state — a component and a bare entry have none. */
+  hasRoute: boolean;
+  /** Title, Layout and every frontmatter field, in reading order. */
+  rows: DocHeaderRow[];
+  /** `empty` draws the sentence, `list` draws {@link DocHeaderView.rawEntries}. */
+  rawState: "empty" | "list";
+  /** The `$head` entries no structured control owns. */
+  rawEntries: DocHeaderRawEntry[];
+  /** Whether the disclosure is open. Per document, and the flow remembers it. */
+  rawOpen: boolean;
+}
+
+/**
+ * What the reader can do here. Every one of them is given the row's `key`, never its `prop`: the
+ * flow decides what a key commits into, and two rows may legitimately share a name.
+ */
+export interface DocHeaderActions {
+  /** Delete the row's value from the document. */
+  clear: (key: string) => void;
+  /** The reader is typing: commit after a pause, so the canvas follows without a write per key. */
+  editText: (key: string, value: string) => void;
+  /** The reader left the field or pressed Enter: commit now, cancelling any pending write. */
+  commitText: (key: string, value: string) => void;
+  /** A numeric field settled on a value. Arrives as text, because an empty field means empty. */
+  setNumber: (key: string, value: string) => void;
+  /** A checkbox moved. */
+  setBoolean: (key: string, checked: boolean) => void;
+  /** A picker settled on a row. */
+  setChoice: (key: string, value: string) => void;
+  /** Open the OS file picker for a media row and assign what comes back. */
+  upload: (key: string) => void;
+  /** Open the media browser under the button that was pressed. */
+  browse: (key: string, anchor: unknown) => void;
+  /** Run the `document.openSeo` command — the door to Search appearance. */
+  openSeo: () => void;
+  /** Remember that the Raw head tags disclosure was opened or closed. */
+  setRawOpen: (open: boolean) => void;
+}
+
+export interface DocHeaderSurface {
+  /** Bring the standing document up to date. */
+  update: (view: DocHeaderView) => void;
+  /** Whether the document this mounted is still standing in the host it was given. */
+  connected: () => boolean;
+  /** Take the document down. Idempotent. */
+  dispose: () => void;
+}
+
+/** The scope the document reads: the view plus the actions, flat. */
+interface DocHeaderScope extends Record<string, unknown>, DocHeaderView, DocHeaderActions {}
+
+/** Write a whole view into the scope. Assignment only — the mount is never rebuilt for a repaint. */
+function project(scope: DocHeaderScope, view: DocHeaderView): void {
+  scope.region = view.region;
+  scope.placement = view.placement;
+  scope.collection = view.collection;
+  scope.route = view.route;
+  scope.hasRoute = view.hasRoute;
+  scope.rows = view.rows;
+  scope.rawState = view.rawState;
+  scope.rawEntries = view.rawEntries;
+  scope.rawOpen = view.rawOpen;
+}
+
+/**
+ * Mount the card into `host` — the node the stage made for it.
+ *
+ * The host is CLEARED first: the stage hands the card a slot of its own, and whatever was in it
+ * belongs to a document this card is no longer drawing.
+ *
+ * @param {HTMLElement} host The stage's slot for the card.
+ * @param {DocHeaderView} view What the card says to begin with.
+ * @param {DocHeaderActions} actions What each control does. Read once, when the scope is made.
+ * @returns {DocHeaderSurface}
+ */
+export function mountDocHeaderSurface(
+  host: HTMLElement,
+  view: DocHeaderView,
+  actions: DocHeaderActions,
+): DocHeaderSurface {
+  const scope = reactive<DocHeaderScope>({
+    ...actions,
+    collection: "Document",
+    hasRoute: false,
+    placement: "in-column",
+    rawEntries: [],
+    rawOpen: false,
+    rawState: "empty",
+    region: "",
+    route: "",
+    rows: [],
+  }) as DocHeaderScope;
+  project(scope, view);
+
+  host.replaceChildren();
+  let mounted: SurfaceHandle | null = null;
+  let disposed = false;
+  /* Nothing is called on an element here, so the mount is all there is to wait for: `jx-textfield`,
+     `jx-select` and `jx-accordion-item` settle their own templates one `connectedCallback` later
+     without anybody asking them to (specs/studio-ui-guidelines.md §1.1, "await the element"). */
+  void mountSurface("doc-header", scope, host).then((surface) => {
+    if (disposed) {
+      surface.dispose();
+      return;
+    }
+    mounted = surface;
+  });
+
+  return {
+    /* While the mount is in flight the card owns the host only for as long as the host is still the
+       empty one it was handed; once mounted, the question is whether the root is still in it — a
+       stage that redrew took the card's root away without telling anyone. */
+    connected: () =>
+      !disposed &&
+      (mounted === null
+        ? host.childNodes.length === 0
+        : (mounted.root as Node).parentNode === host),
+    dispose() {
+      disposed = true;
+      mounted?.dispose();
+      mounted = null;
+    },
+    update: (next) => project(scope, next),
+  };
+}

package/src/surfaces/empty-state.json

@@ -0,0 +1,152 @@
+{
+  "$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.",
+  "tagName": "div",
+  "attributes": {
+    "part": "empty",
+    "data-compact": "${state.compact ? '' : null}"
+  },
+  "style": {
+    "$description": "What `.empty-state`, `.empty-state--teach`, `.empty-state-message`, `.empty-state-detail`, `.empty-state-actions`, `.empty-state-action` and the `--compact` pair said across `styles/overlays.css` and `styles/panels.css`, keyed on `part`. Neither stylesheet loses its rules: `ui/expression-editor.ts` still renders the lit helper for its own compact state, so this is a copy until that surface converts. Two values did not travel. `.empty-state`'s `font-size: 13px` was a number nothing else in the shell uses and is the kit's `--jx-text-md`; `.empty-state-detail`'s `var(--spectrum-font-size-50, 11px)` resolves only inside `<sp-theme>`, and a document mounted into a Navigator body or a canvas stage is outside it, so it would silently have taken its hard-coded fallback on every paint — it is `--jx-text-sm`, which is the step it was.",
+    "display": "flex",
+    "flexDirection": "column",
+    "alignItems": "center",
+    "gap": "var(--jx-space-3)",
+    "padding": "var(--jx-space-6)",
+    "textAlign": "center",
+    "color": "var(--fg-dim)",
+    "fontSize": "var(--jx-text-md)",
+    "& [part=\"empty-message\"]": {
+      "margin": "0",
+      "maxWidth": "34ch",
+      "lineHeight": "1.5"
+    },
+    "& [part=\"empty-detail\"]": {
+      "$description": "The second sentence: where the region's content comes from. Dimmer than the first, because the first is the one a reader has to take in.",
+      "margin": "0",
+      "maxWidth": "34ch",
+      "fontSize": "var(--jx-text-sm)",
+      "color": "var(--fg-dim)",
+      "opacity": "0.8"
+    },
+    "& [part=\"empty-actions\"]": {
+      "display": "flex",
+      "flexWrap": "wrap",
+      "justifyContent": "center",
+      "gap": "var(--jx-space-3)"
+    },
+    "& [part=\"empty-action\"]": {
+      "flex": "none"
+    },
+    "&[data-compact]": {
+      "$description": "An inline section inside an otherwise populated panel — tighter and left-aligned, because it sits directly above its own add form rather than filling a region on its own.",
+      "alignItems": "flex-start",
+      "gap": "var(--jx-space-2)",
+      "padding": "var(--jx-space-3) var(--jx-space-4)",
+      "textAlign": "left",
+      "fontSize": "var(--jx-text-sm)"
+    },
+    "&[data-compact] [part=\"empty-actions\"]": {
+      "justifyContent": "flex-start"
+    }
+  },
+  "children": [
+    {
+      "tagName": "p",
+      "attributes": {
+        "part": "empty-message"
+      },
+      "textContent": "${state.message}"
+    },
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "empty-detail-slot",
+        "role": "none"
+      },
+      "style": {
+        "display": "contents"
+      },
+      "$switch": {
+        "$ref": "#/state/hasDetail"
+      },
+      "cases": {
+        "true": {
+          "tagName": "p",
+          "attributes": {
+            "part": "empty-detail"
+          },
+          "textContent": "${state.detail}"
+        }
+      }
+    },
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "empty-actions-slot",
+        "role": "none"
+      },
+      "style": {
+        "display": "contents"
+      },
+      "$switch": {
+        "$ref": "#/state/hasActions"
+      },
+      "cases": {
+        "true": {
+          "tagName": "div",
+          "attributes": {
+            "part": "empty-actions"
+          },
+          "children": [
+            {
+              "$prototype": "Array",
+              "items": {
+                "$ref": "#/state/actions"
+              },
+              "key": {
+                "$ref": "$map/item/id"
+              },
+              "map": {
+                "tagName": "jx-button",
+                "attributes": {
+                  "part": "empty-action"
+                },
+                "$props": {
+                  "size": "sm",
+                  "variant": "secondary",
+                  "disabled": {
+                    "$ref": "$map/item/disabled"
+                  }
+                },
+                "onclick": {
+                  "$prototype": "Function",
+                  "body": [
+                    {
+                      "operator": "call",
+                      "target": {
+                        "$ref": "#/state/runAction"
+                      },
+                      "value": [
+                        {
+                          "$ref": "$map/item/id"
+                        }
+                      ]
+                    }
+                  ]
+                },
+                "children": [
+                  {
+                    "tagName": "span",
+                    "textContent": "${$map.item.label}"
+                  }
+                ]
+              }
+            }
+          ]
+        }
+      }
+    }
+  ]
+}

package/src/surfaces/empty-state.ts

@@ -0,0 +1,173 @@
+/// <reference lib="dom" />
+/**
+ * The shared empty state as a mounted document — the seam, and nothing else.
+ *
+ * `empty-state.json` is the markup and the style; `panels/empty-state.ts` is the VOCABULARY (the
+ * copy rules, the shared verbs, `openPageAction`), and it keeps it: this module imports the spec
+ * type rather than restating it, so a region that says "click anything on the canvas to style it"
+ * is still saying the one sentence every equivalent surface says.
+ *
+ * **The seam is a node a lit caller interpolates.** A document CLEARS the host it is given and lit
+ * renders BESIDE foreign nodes, so the two can never share a container — and every caller here is a
+ * lit render root that draws a panel's content OR this instead of it. So the surface owns a
+ * `display: contents` host of its own, exactly as `surfaces/ai-credentials-form.ts` does, and the
+ * caller hands that node to lit as a child value. lit inserts a Node it is given rather than
+ * cloning it, takes it back out when the branch flips to the panel's own markup, and puts the same
+ * one back when it flips again — so the document survives the switch instead of being rebuilt by
+ * it, and no caller has to remember to dispose anything.
+ *
+ * **One surface per OWNER, not one per call.** {@link emptyState} caches by the lit host, because
+ * an empty state is drawn from inside a render function that runs on every tick: a fresh mount per
+ * call would hand lit a new node every time, which is a remount of the document on every repaint of
+ * the region around it. Keyed by the host, the repaint is an assignment.
+ *
+ * @docs studio/interface
+ */
+
+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);
+
+/** One button, as the document draws it: a key, a word, and whether it can act. */
+interface EmptyStateActionRow extends Record<string, unknown> {
+  /** The repeater's key and what a press is addressed with — this action's slot in the list. */
+  id: string;
+  label: string;
+  disabled: boolean;
+}
+
+/**
+ * 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.
+ */
+interface EmptyStateView {
+  message: string;
+  detail: string;
+  hasDetail: boolean;
+  compact: boolean;
+  actions: EmptyStateActionRow[];
+  hasActions: boolean;
+}
+
+/** The scope `empty-state.json` reads. Every field is a value; the document asks no question. */
+interface EmptyStateScope extends Record<string, unknown>, EmptyStateView {
+  runAction: (id: string) => void;
+}
+
+/** A standing empty state: the node a caller interpolates, and the way to change what it says. */
+export interface EmptyStateSurface {
+  /** The element the document lives in — handed to a lit template as a child value. */
+  readonly host: HTMLElement;
+  /** Bring the standing surface up to date. An assignment; the mount is never rebuilt. */
+  update: (spec: EmptyStateSpec) => void;
+  /** Take the document down and give the host back empty. Idempotent. */
+  dispose: () => void;
+}
+
+/**
+ * Mount an empty state into a host of the surface's own.
+ *
+ * @param {EmptyStateSpec} spec What the region says to begin with.
+ * @returns {EmptyStateSurface}
+ */
+export function createEmptyStateSurface(spec: EmptyStateSpec): EmptyStateSurface {
+  const host = document.createElement("div");
+  /* `display: contents` for the reason `surfaces/ai-credentials-form.ts` gives: the callers lay
+     their bodies out themselves — a Navigator body is a scroll column, a canvas stage is a block —
+     and a wrapper box would become the child in the document root's place and take the centring
+     below it with it. */
+  host.style.display = "contents";
+
+  /** The handlers, held apart from the scope so `runAction` never has to be reassigned. */
+  let handlers: (() => void)[] = [];
+  const scope = reactive<EmptyStateScope>({
+    ...project(spec),
+    runAction: (id: string) => {
+      handlers[Number(id)]?.();
+    },
+  }) as EmptyStateScope;
+  handlers = handlersOf(spec);
+
+  let mounted: SurfaceHandle | null = null;
+  let disposed = false;
+  void mountSurface("empty-state", scope, host).then((surface) => {
+    if (disposed) {
+      surface.dispose();
+      return;
+    }
+    mounted = surface;
+  });
+
+  return {
+    dispose() {
+      disposed = true;
+      mounted?.dispose();
+      mounted = null;
+      host.replaceChildren();
+    },
+    host,
+    update(next) {
+      handlers = handlersOf(next);
+      Object.assign(scope, project(next));
+    },
+  };
+}
+
+/** The spec as the document reads it: every branch already decided, nothing left to derive. */
+function project(spec: EmptyStateSpec): EmptyStateView {
+  const actions = spec.actions ?? [];
+  return {
+    actions: actions.map((action, index) => ({
+      disabled: Boolean(action.disabled),
+      id: String(index),
+      label: action.label,
+    })),
+    compact: Boolean(spec.compact),
+    detail: spec.detail ?? "",
+    hasActions: actions.length > 0,
+    /* The detail is drawn when there IS one, which the empty string is not: a caller that passes
+       `detail: ""` means "no second sentence", and a `<p>` with nothing in it is a gap the reader
+       has to account for. */
+    hasDetail: (spec.detail ?? "") !== "",
+    message: spec.message,
+  };
+}
+
+/** The actions' handlers, positionally — the document addresses a press by its row's index. */
+function handlersOf(spec: EmptyStateSpec): (() => void)[] {
+  return (spec.actions ?? []).map((action) => action.run);
+}
+
+/** One standing surface per lit host. */
+const _surfaces = new WeakMap<HTMLElement, EmptyStateSurface>();
+
+/**
+ * The empty state for a lit render root, as a node that root's template interpolates.
+ *
+ * `litRender(hasContent ? content : emptyState(host, spec), host)` — the surface is mounted the
+ * first time the region is empty and ASSIGNED every time after, so flipping between a panel's own
+ * markup and its empty state neither rebuilds the document nor leaves it behind.
+ *
+ * @param {HTMLElement} owner The lit host the region renders into.
+ * @param {EmptyStateSpec} spec What this region says right now.
+ * @returns {HTMLElement} The node to hand lit.
+ */
+export function emptyState(owner: HTMLElement, spec: EmptyStateSpec): HTMLElement {
+  const standing = _surfaces.get(owner);
+  if (standing) {
+    standing.update(spec);
+    return standing.host;
+  }
+  const surface = createEmptyStateSurface(spec);
+  _surfaces.set(owner, surface);
+  return surface.host;
+}