@jxsuite/studio 6.1.1 → 8.0.0

package/src/surfaces/entry-inspector.json

@@ -0,0 +1,371 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioEntryInspector",
+  "$description": "The Inspector's Entry tab (specs/studio.md §6, §22.5): one collection entry's own settings while it is written on the canvas, the Content-Entry board's sidebar. Its status (draft or published), its fields as the collection's schema types them, the URL its collection page publishes it at, and the file it is stored in. `content/entry-inspector.ts` keeps every decision; the field form is an island it fills, `ui/schema-form.ts`'s, the same form the form-only entry editor draws.",
+  "tagName": "div",
+  "attributes": {
+    "part": "entry",
+    "data-jx-region": "${state.region}"
+  },
+  "style": {
+    "$description": "A column of sections, each a small uppercase heading over its rows, like the Page tab beside it.",
+    "display": "flex",
+    "flexDirection": "column",
+    "gap": "var(--jx-space-4)",
+    "padding": "var(--jx-space-3)",
+    "fontFamily": "var(--jx-font-sans)",
+    "fontSize": "var(--jx-text-md)",
+    "color": "var(--fg)",
+    "& [part=\"section\"]": {
+      "display": "flex",
+      "flexDirection": "column",
+      "gap": "var(--jx-space-2)"
+    },
+    "& [part=\"section-title\"]": {
+      "margin": "0",
+      "fontSize": "var(--jx-text-sm)",
+      "fontWeight": "700",
+      "letterSpacing": "0.06em",
+      "textTransform": "uppercase",
+      "color": "var(--fg-dim)"
+    },
+    "& [part=\"head\"]": {
+      "display": "flex",
+      "alignItems": "baseline",
+      "justifyContent": "space-between",
+      "gap": "var(--jx-space-2)"
+    },
+    "& [part=\"kind\"]": {
+      "fontWeight": "600"
+    },
+    "& [part=\"status\"]": {
+      "fontSize": "var(--jx-text-sm)",
+      "color": "var(--fg-dim)"
+    },
+    "& [part=\"status\"][data-draft=\"true\"]": {
+      "color": "var(--warning)"
+    },
+    "& [part=\"note\"]": {
+      "margin": "0",
+      "fontSize": "var(--jx-text-sm)",
+      "lineHeight": "1.5",
+      "color": "var(--fg-dim)"
+    },
+    "& [part=\"url\"]": {
+      "fontFamily": "var(--font-mono)",
+      "fontSize": "var(--jx-text-sm)",
+      "wordBreak": "break-all"
+    },
+    "& [part=\"path\"]": {
+      "fontFamily": "var(--font-mono)",
+      "fontSize": "var(--jx-text-sm)",
+      "color": "var(--fg)",
+      "wordBreak": "break-all"
+    },
+    "& [part=\"fields-head\"]": {
+      "display": "flex",
+      "alignItems": "center",
+      "justifyContent": "space-between"
+    }
+  },
+  "children": [
+    {
+      "tagName": "section",
+      "attributes": {
+        "part": "section",
+        "aria-labelledby": "entry-inspector-entry"
+      },
+      "children": [
+        {
+          "tagName": "div",
+          "attributes": {
+            "part": "head"
+          },
+          "children": [
+            {
+              "tagName": "h3",
+              "attributes": {
+                "part": "section-title",
+                "id": "entry-inspector-entry"
+              },
+              "textContent": "Entry"
+            },
+            {
+              "tagName": "span",
+              "attributes": {
+                "part": "status",
+                "data-draft": "${state.draft ? 'true' : 'false'}"
+              },
+              "textContent": "${state.status}"
+            }
+          ]
+        },
+        {
+          "tagName": "span",
+          "attributes": {
+            "part": "kind"
+          },
+          "textContent": "${state.kind}"
+        },
+        {
+          "tagName": "div",
+          "attributes": {
+            "part": "draft-slot",
+            "role": "none"
+          },
+          "style": {
+            "display": "contents"
+          },
+          "$switch": {
+            "$ref": "#/state/draftAxis"
+          },
+          "cases": {
+            "shown": {
+              "$description": "The entry's draft state, the one field every collection with a draft workflow shares (site-architecture.md §7.6). A setter: the switch names the state it reaches.",
+              "tagName": "jx-switch",
+              "attributes": {
+                "part": "draft"
+              },
+              "$props": {
+                "checked": {
+                  "$ref": "#/state/draft"
+                },
+                "hint": "${state.draftHint}",
+                "size": "sm"
+              },
+              "onchange": {
+                "$prototype": "Function",
+                "body": [
+                  {
+                    "operator": "call",
+                    "target": {
+                      "$ref": "#/state/setDraft"
+                    },
+                    "value": [
+                      {
+                        "$ref": "event#/target/checked"
+                      }
+                    ]
+                  }
+                ]
+              },
+              "children": [
+                {
+                  "tagName": "span",
+                  "textContent": "Draft"
+                }
+              ]
+            }
+          }
+        }
+      ]
+    },
+    {
+      "tagName": "section",
+      "attributes": {
+        "part": "section",
+        "aria-labelledby": "entry-inspector-fields"
+      },
+      "children": [
+        {
+          "tagName": "div",
+          "attributes": {
+            "part": "fields-head"
+          },
+          "children": [
+            {
+              "tagName": "h3",
+              "attributes": {
+                "part": "section-title",
+                "id": "entry-inspector-fields"
+              },
+              "textContent": "Fields"
+            },
+            {
+              "tagName": "jx-action-button",
+              "attributes": {
+                "part": "edit-fields"
+              },
+              "$props": {
+                "size": "sm",
+                "quiet": true,
+                "hint": "Edit this collection's fields in Project Settings",
+                "haspopup": "dialog"
+              },
+              "onclick": {
+                "$prototype": "Function",
+                "body": [
+                  {
+                    "operator": "call",
+                    "target": {
+                      "$ref": "#/state/openFields"
+                    },
+                    "value": []
+                  }
+                ]
+              },
+              "children": [
+                {
+                  "tagName": "span",
+                  "textContent": "Edit"
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "tagName": "div",
+          "attributes": {
+            "part": "fields-slot",
+            "role": "none"
+          },
+          "style": {
+            "display": "contents"
+          },
+          "$switch": {
+            "$ref": "#/state/fieldsState"
+          },
+          "cases": {
+            "form": {
+              "tagName": "div",
+              "attributes": {
+                "part": "fields"
+              }
+            },
+            "none": {
+              "tagName": "p",
+              "attributes": {
+                "part": "note"
+              },
+              "textContent": "This collection declares no fields. Edit adds some in Project Settings."
+            }
+          }
+        }
+      ]
+    },
+    {
+      "tagName": "section",
+      "attributes": {
+        "part": "section",
+        "aria-labelledby": "entry-inspector-page"
+      },
+      "children": [
+        {
+          "tagName": "div",
+          "attributes": {
+            "part": "fields-head"
+          },
+          "children": [
+            {
+              "tagName": "h3",
+              "attributes": {
+                "part": "section-title",
+                "id": "entry-inspector-page"
+              },
+              "textContent": "Page"
+            },
+            {
+              "$description": "The door to Search appearance, the same `document.openSeo` the Page tab's button runs: an entry's search title, description and social image are its frontmatter too (studio.md §4.2).",
+              "tagName": "jx-action-button",
+              "attributes": {
+                "part": "seo-button"
+              },
+              "$props": {
+                "size": "sm",
+                "quiet": true,
+                "label": "Search appearance",
+                "hint": "Preview how this entry appears in search and when shared",
+                "haspopup": "dialog"
+              },
+              "onclick": {
+                "$prototype": "Function",
+                "body": [
+                  {
+                    "operator": "call",
+                    "target": {
+                      "$ref": "#/state/openSeo"
+                    },
+                    "value": []
+                  }
+                ]
+              },
+              "children": [
+                {
+                  "tagName": "span",
+                  "textContent": "Search appearance…"
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "tagName": "div",
+          "attributes": {
+            "part": "url-slot",
+            "role": "none"
+          },
+          "style": {
+            "display": "contents"
+          },
+          "$switch": {
+            "$ref": "#/state/urlState"
+          },
+          "cases": {
+            "shown": {
+              "tagName": "code",
+              "attributes": {
+                "part": "url"
+              },
+              "textContent": "${state.url}"
+            },
+            "none": {
+              "tagName": "p",
+              "attributes": {
+                "part": "note"
+              },
+              "textContent": "Entries of this collection have no page of their own."
+            },
+            "unlisted": {
+              "$description": "The collection has a page, but the page lists the ids it publishes (`$paths.values`) and this entry is not one of them: naming a URL the build never writes would be a link to nothing.",
+              "tagName": "p",
+              "attributes": {
+                "part": "note"
+              },
+              "textContent": "Not published: this collection's page lists the entries it publishes, and this is not one of them."
+            },
+            "loading": {
+              "tagName": "p",
+              "attributes": {
+                "part": "note"
+              },
+              "textContent": "Finding the page this entry is published at…"
+            }
+          }
+        },
+        {
+          "tagName": "p",
+          "attributes": {
+            "part": "note"
+          },
+          "children": [
+            {
+              "tagName": "span",
+              "textContent": "Stored as "
+            },
+            {
+              "tagName": "code",
+              "attributes": {
+                "part": "path"
+              },
+              "textContent": "${state.path}"
+            },
+            {
+              "tagName": "span",
+              "textContent": "${state.storage}"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/src/surfaces/entry-inspector.ts

@@ -0,0 +1,143 @@
+/// <reference lib="dom" />
+/**
+ * The Inspector's Entry tab surface: one collection entry's status, fields, page URL and file
+ * (`specs/studio.md` §6, §22.5).
+ *
+ * This is the adapter. `content/entry-inspector.ts` decides everything and hands this module one
+ * projection; the field form is an island the document renders empty (`part="fields"`) and the flow
+ * fills through `onNodeCreated`, because `ui/schema-form.ts` hands back a host element.
+ *
+ * @docs studio/projects/content-types
+ */
+
+import { isString } from "@jxsuite/schema/guards";
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import entryInspectorDoc from "./entry-inspector.json";
+import type { JxElement } from "@jxsuite/schema/types";
+import type { SurfaceHandle } from "../ui/surface";
+
+registerSurface("entry-inspector", entryInspectorDoc);
+
+/** Everything the document draws. Every field is a value. */
+export interface EntryInspectorView {
+  /** The region id stamped on the root. */
+  region: string;
+  /** What the entry is, said in the singular: "Post". */
+  kind: string;
+  /** "Draft", "Published", or "" for a collection with no draft workflow. */
+  status: string;
+  /** Whether the collection has a draft workflow at all. */
+  draftAxis: "hidden" | "shown";
+  draft: boolean;
+  draftHint: string;
+  /** `form` draws the field form's host; `none` says the collection declares no fields. */
+  fieldsState: "form" | "none";
+  /**
+   * `shown` draws the URL; `none` says the collection has no page; `unlisted` that its page lists
+   * the entries it publishes and this is not one; `loading` while the pages are read.
+   */
+  urlState: "shown" | "none" | "unlisted" | "loading";
+  url: string;
+  /** The file the entry is stored in. */
+  path: string;
+  /** What the file holds: ". Fields are its frontmatter, and the body is its Markdown." */
+  storage: string;
+}
+
+/** What the tab's controls do. */
+export interface EntryInspectorActions {
+  /** The draft switch moved. A setter, never a toggle. */
+  setDraft: (draft: boolean) => void;
+  /** **Edit** opens Project Settings › Content types on this collection. */
+  openFields: () => void;
+  /** **Search appearance…** runs `document.openSeo` over this entry, as the Page tab's does. */
+  openSeo: () => void;
+}
+
+/** The node the document renders empty for the flow to fill. */
+export interface EntryInspectorIslands {
+  /** The field form's host, whenever the document has just created one. */
+  fieldsSlot: (host: HTMLElement) => void;
+}
+
+export interface EntryInspectorHandle {
+  readonly ready: Promise<unknown>;
+  /** Whether what was mounted is still inside the host. */
+  attached: () => boolean;
+  update: (view: EntryInspectorView) => void;
+  dispose: () => void;
+}
+
+interface EntryInspectorScope extends EntryInspectorView, EntryInspectorActions {}
+
+/** Write a view into the scope, field by field. */
+function project(scope: EntryInspectorScope, view: EntryInspectorView): void {
+  scope.region = view.region;
+  scope.kind = view.kind;
+  scope.status = view.status;
+  scope.draftAxis = view.draftAxis;
+  scope.draft = view.draft;
+  scope.draftHint = view.draftHint;
+  scope.fieldsState = view.fieldsState;
+  scope.urlState = view.urlState;
+  scope.url = view.url;
+  scope.path = view.path;
+  scope.storage = view.storage;
+}
+
+/** The `part` a node was authored with, or `""`. */
+function partOf(def: JxElement | string): string {
+  const part = isString(def) ? undefined : def.attributes?.["part"];
+  return isString(part) ? part : "";
+}
+
+/**
+ * Mount the Entry tab into `host`, the Inspector's Page body.
+ *
+ * @param host The body host.
+ * @param view What to draw.
+ * @param actions What the controls do.
+ * @param islands Where the field form goes.
+ */
+export function mountEntryInspectorSurface(
+  host: HTMLElement,
+  view: EntryInspectorView,
+  actions: EntryInspectorActions,
+  islands: EntryInspectorIslands,
+): EntryInspectorHandle {
+  host.replaceChildren();
+  const scope: EntryInspectorScope = reactive<EntryInspectorScope>({ ...view, ...actions });
+  let mounted: SurfaceHandle | null = null;
+  let disposed = false;
+  const ready = mountSurface("entry-inspector", scope, host, {
+    onNodeCreated: (element, _path, def) => {
+      if (!disposed && element instanceof HTMLElement && partOf(def) === "fields") {
+        islands.fieldsSlot(element);
+      }
+    },
+  }).then((surface) => {
+    if (disposed) {
+      surface.dispose();
+    } else {
+      mounted = surface;
+    }
+    return surface;
+  });
+  return {
+    attached: () => {
+      if (disposed) {
+        return false;
+      }
+      const root = mounted?.root;
+      return root === undefined ? true : host.contains(root);
+    },
+    dispose() {
+      disposed = true;
+      mounted?.dispose();
+      mounted = null;
+    },
+    ready,
+    update: (next) => project(scope, next),
+  };
+}

package/src/surfaces/expression-editor.ts

@@ -31,26 +31,12 @@
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import expressionEditorDoc from "./expression-editor.json";
-import type { JxDocument } from "@jxsuite/schema/types";
-import type { SurfaceHandle } from "../ui/surface";
+import type { SurfaceHandle, SurfaceOption, SurfaceOptionGroup } from "../ui/surface";
 
-registerSurface("expression-editor", expressionEditorDoc as unknown as JxDocument);
-
-/** A closed list of choices, in the shape the kit's select reads. */
-export interface ExprOption {
-  value: string;
-  label: string;
-}
-
-/** A delimited run of choices — the kit's own `optgroup`, which draws both halves of the rule. */
-export interface ExprSelectGroup {
-  id: string;
-  label: string;
-  rows: ExprOption[];
-}
+registerSurface("expression-editor", expressionEditorDoc);
 
 /** One chip of the pipeline, as the document draws it. */
-export interface ExprChipView extends Record<string, unknown> {
+export interface ExprChipView {
   /** The joined node path: the repeater's key, and what a click reports back to the flow. */
   key: string;
   label: string;
@@ -83,7 +69,7 @@ export type ExprLead = "none" | "arg" | "case" | "default";
  * Every field is a string, a flag or a list: the document asks no question about an expression, and
  * there is no branch in it that the walk has not already taken.
  */
-export interface ExprRowView extends Record<string, unknown> {
+export interface ExprRowView {
   /**
    * Unique within one editor, and the repeater's key. It is the node's own path plus the slot it
    * fills, so a row that survives an edit keeps its node — which is what stops a keystroke in one
@@ -111,19 +97,19 @@ export interface ExprRowView extends Record<string, unknown> {
   /** The accessible name of the row's icon-only control. */
   title: string;
   /** An `operator` row's grouped operator list. */
-  groups: ExprSelectGroup[];
+  groups: SurfaceOptionGroup[];
   /** An `operator` row offers the catalog beside its picker; a nested one does not. */
   catalog: boolean;
   /** Which rung an `operand` row shows. */
   source: ExprSource;
   /** The rungs on offer. Empty means the slot admits one shape, so there is nothing to choose. */
-  sourceOptions: ExprOption[];
+  sourceOptions: SurfaceOption[];
   /** Whether the rung picker is drawn at all — `sourceOptions` non-empty, said as a flag. */
   chooser: boolean;
   /** `string`, `number`, `boolean` or `null` — what the literal type picker holds. */
   literalType: string;
   /** The literal types on offer. A separate list from {@link sourceOptions}: two questions. */
-  typeOptions: ExprOption[];
+  typeOptions: SurfaceOption[];
   /** Which literal control follows the type picker: `text`, `number`, `bool` or `null`. */
   literal: string;
   /** What a text literal, a number literal or a ref picker holds. */
@@ -131,9 +117,9 @@ export interface ExprRowView extends Record<string, unknown> {
   /** What a boolean literal holds. */
   checked: boolean;
   /** The signals this slot may bind to. */
-  refOptions: ExprOption[];
+  refOptions: SurfaceOption[];
   /** The event refs, as their own named run. Empty where the position admits none. */
-  refGroups: ExprSelectGroup[];
+  refGroups: SurfaceOptionGroup[];
   /** Which leading cell the row carries. */
   lead: ExprLead;
   /** An arg's positional name, or the `default` case's word. */
@@ -181,7 +167,7 @@ export interface ExpressionActions {
   pickChip: (key: string) => void;
 }
 
-interface ExpressionScope extends Record<string, unknown>, ExpressionActions {
+interface ExpressionScope extends ExpressionActions {
   rows: ExprRowView[];
 }
 
@@ -225,7 +211,7 @@ export function renderExpressionEditorSurface(
   }
   takeDown(host, existing);
   host.textContent = "";
-  const scope = reactive({ ...actions, rows }) as ExpressionScope;
+  const scope: ExpressionScope = reactive<ExpressionScope>({ ...actions, rows });
   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

package/src/surfaces/files-panel.ts

@@ -37,14 +37,15 @@
  * @docs studio/interface
  */
 
+import { isNonNullObject, isString } from "@jxsuite/schema/guards";
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import filesPanelDoc from "./files-panel.json";
-import type { JxDocument, JxElement } from "@jxsuite/schema/types";
+import type { JxElement } from "@jxsuite/schema/types";
 import type { JxScope } from "@jxsuite/runtime/types";
 import type { SurfaceHandle } from "../ui/surface";
 
-registerSurface("files-panel", filesPanelDoc as unknown as JxDocument);
+registerSurface("files-panel", filesPanelDoc);
 
 /**
  * One row the tree draws, with every field already a string.
@@ -170,7 +171,7 @@ export interface FilesPanelSurfaceHandle {
 }
 
 /** The scope the document reads: the projection, plus everything a control can ask for. */
-interface FilesPanelScope extends Record<string, unknown>, FilesPanelValues, FilesPanelActions {}
+interface FilesPanelScope extends FilesPanelValues, FilesPanelActions {}
 
 /** Write a projection into the scope. Assignment by assignment, so an unchanged field is inert. */
 function project(scope: FilesPanelScope, values: FilesPanelValues): void {
@@ -214,15 +215,28 @@ export function emptyFilesPanelValues(): FilesPanelValues {
 
 /** The `part` a node's definition carries, or `""` for a text node or an unmarked element. */
 function partOf(def: JxElement | string): string {
-  const part = typeof def === "string" ? undefined : def.attributes?.["part"];
-  return typeof part === "string" ? part : "";
+  const part = isString(def) ? undefined : def.attributes?.["part"];
+  return isString(part) ? part : "";
 }
 
-/** The mapped row a node was rendered inside, or null when it was not in one. */
-function mappedRow(state: JxScope | undefined): FileRowView | null {
-  const map = state?.["$map"] as { item?: unknown } | undefined;
-  const item = map?.item as FileRowView | undefined;
-  return typeof item?.path === "string" ? item : null;
+/**
+ * The path and type of the mapped row a node was rendered inside, or null when it was not in one.
+ * The only mapped array in `files-panel.json` is `#/state/rows`, which `project()` fills from
+ * `FilesPanelValues.rows: FileRowView[]`, so a row's item carries both as strings.
+ */
+function mappedRow(state: JxScope | undefined): Pick<FileRowView, "path" | "type"> | null {
+  const map = state?.["$map"];
+  const item = isNonNullObject(map) && "item" in map ? map.item : undefined;
+  if (
+    !isNonNullObject(item) ||
+    !("path" in item) ||
+    !isString(item.path) ||
+    !("type" in item) ||
+    !isString(item.type)
+  ) {
+    return null;
+  }
+  return { path: item.path, type: item.type };
 }
 
 /**
@@ -237,10 +251,10 @@ export function mountFilesPanelSurface(
   values: FilesPanelValues,
   actions: FilesPanelActions,
 ): FilesPanelSurfaceHandle {
-  const scope = reactive<FilesPanelScope>({
+  const scope: FilesPanelScope = reactive<FilesPanelScope>({
     ...emptyFilesPanelValues(),
     ...actions,
-  }) as FilesPanelScope;
+  });
   project(scope, values);
 
   let mounted: SurfaceHandle | null = null;
@@ -286,8 +300,7 @@ export function mountFilesPanelSurface(
        answer is simply whether this handle is still wanted — answering no would start a second
        mount racing the first. Once mounted, the question is whether the root is still where it was
        put: a Navigator that painted another panel cleared this document out from under it. */
-    connected: () =>
-      !disposed && (mounted === null || (mounted.root as Node).parentNode === container),
+    connected: () => !disposed && (mounted === null || mounted.root.parentNode === container),
     dispose() {
       disposed = true;
       mounted?.dispose();