@jxsuite/studio 4.1.0 → 5.1.0

package/src/surfaces/entry-editor.json

@@ -0,0 +1,281 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioEntryEditor",
+  "$description": "The Entry editor (§7.4) — one content entry's fields, in a pane, as a Jx document over the kit. The adapter (`surfaces/entry-editor.ts`) hands in a projection; `content/entry-editor.ts` decides everything in it — which collection the file belongs to, which record its fields live in, which required keys are absent and what a draft flag commits into. The FORM is an island: a schema is `ui/schema-form.ts`'s subject, so this document renders an empty `fields` node and the flow places the element that engine hands back (studio-ui-guidelines.md §9.3, §9.4). That is the whole of the difference between this and the card the lit version drew, and it is why the engine converting in batch 7 is what unblocked this one.",
+  "tagName": "div",
+  "attributes": {
+    "part": "entry",
+    "data-jx-region": "${state.region}"
+  },
+  "style": {
+    "$description": "What `.entry-editor`, `.entry-editor-header`, `.entry-editor-collection`, `.entry-draft-switch`, `.entry-editor-fields`, `.entry-editor-note` and `.entry-editor-empty` said in `styles/overlays.css`, keyed on `part` and re-pointed at the studio token layer. This editor was the only emitter of all seven, so those rules are dead in the stylesheet from here; a central sweep removes them rather than this change, which owns no stylesheet. Every `--spectrum-font-size-*` reference is gone rather than renamed: those names resolve only inside `<sp-theme>`, and a pane editor is mounted outside it, so each would silently have taken its hard-coded fallback.",
+    "height": "100%",
+    "padding": "var(--jx-space-5)",
+    "overflowY": "auto",
+    "background": "var(--bg-panel)",
+    "& [part=\"header\"]": {
+      "display": "flex",
+      "alignItems": "center",
+      "gap": "var(--jx-space-4)",
+      "marginBottom": "var(--jx-space-5)"
+    },
+    "& [part=\"name\"]": {
+      "margin": "0",
+      "fontSize": "var(--jx-text-lg)",
+      "fontWeight": "600",
+      "color": "var(--fg)"
+    },
+    "& [part=\"collection\"]": {
+      "padding": "1px var(--jx-space-3)",
+      "borderRadius": "var(--radius)",
+      "background": "var(--bg)",
+      "color": "var(--fg-dim)",
+      "fontSize": "var(--jx-text-sm)"
+    },
+    "& [part=\"draft\"]": {
+      "$description": "Pushed to the far end of the header rather than placed there: the heading and the collection chip are both content-width, so `margin-left: auto` is what keeps the switch on the right edge whatever the entry is called.",
+      "marginLeft": "auto"
+    },
+    "& [part=\"fields\"]": {
+      "$description": "The schema form's host is `display: contents`, so its rows are the flex items of THIS box — which is why the column lives here and not inside the engine.",
+      "display": "flex",
+      "flexDirection": "column"
+    },
+    "& [part=\"note\"]": {
+      "margin": "0 0 var(--jx-space-4)",
+      "color": "var(--fg-dim)",
+      "fontSize": "var(--jx-text-md)",
+      "lineHeight": "1.5"
+    },
+    "& [part=\"empty\"]": {
+      "display": "flex",
+      "maxWidth": "46ch",
+      "flexDirection": "column",
+      "alignItems": "flex-start",
+      "gap": "var(--jx-space-3)",
+      "color": "var(--fg-dim)",
+      "fontSize": "var(--jx-text-md)",
+      "lineHeight": "1.5"
+    }
+  },
+  "children": [
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "stage-slot",
+        "role": "none"
+      },
+      "style": {
+        "display": "contents"
+      },
+      "$switch": {
+        "$ref": "#/state/stage"
+      },
+      "cases": {
+        "entry": {
+          "tagName": "div",
+          "attributes": {
+            "part": "body",
+            "role": "none"
+          },
+          "style": {
+            "display": "contents"
+          },
+          "children": [
+            {
+              "tagName": "div",
+              "attributes": {
+                "part": "header"
+              },
+              "children": [
+                {
+                  "tagName": "h3",
+                  "attributes": {
+                    "part": "name"
+                  },
+                  "textContent": "${state.name}"
+                },
+                {
+                  "tagName": "span",
+                  "attributes": {
+                    "part": "collection"
+                  },
+                  "textContent": "${state.collection}"
+                },
+                {
+                  "tagName": "div",
+                  "attributes": {
+                    "part": "draft-slot",
+                    "role": "none"
+                  },
+                  "style": {
+                    "display": "contents"
+                  },
+                  "$switch": {
+                    "$ref": "#/state/draftAxis"
+                  },
+                  "cases": {
+                    "shown": {
+                      "$description": "No `label`: the slotted word is on screen and carries the name, so an aria-label would be read twice. The tooltip is `hint`, which is what DRAFT_MEANING has always been.",
+                      "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": "div",
+              "attributes": {
+                "part": "note-slot",
+                "role": "none"
+              },
+              "style": {
+                "display": "contents"
+              },
+              "$switch": {
+                "$ref": "#/state/noteState"
+              },
+              "cases": {
+                "shown": {
+                  "tagName": "p",
+                  "attributes": {
+                    "part": "note"
+                  },
+                  "textContent": "${state.note}"
+                }
+              }
+            },
+            {
+              "$description": "An island: `ui/schema-form.ts` draws this entry's fields into this node, and nothing in this document knows what a schema is.",
+              "tagName": "div",
+              "attributes": {
+                "part": "fields",
+                "data-jx-region": "${state.fieldsRegion}"
+              }
+            }
+          ]
+        },
+        "empty": {
+          "$description": "The mode is reachable from the palette and from `__jxAutomation` on any tab, so this state is real: it names the reason and the fix rather than drawing an empty form.",
+          "tagName": "div",
+          "attributes": {
+            "part": "empty"
+          },
+          "children": [
+            {
+              "tagName": "p",
+              "attributes": {
+                "part": "empty-line"
+              },
+              "textContent": "${state.emptyLine}"
+            },
+            {
+              "tagName": "p",
+              "attributes": {
+                "part": "note"
+              },
+              "children": [
+                {
+                  "tagName": "span",
+                  "textContent": "A collection is a "
+                },
+                {
+                  "tagName": "code",
+                  "textContent": "content"
+                },
+                {
+                  "tagName": "span",
+                  "textContent": " entry in "
+                },
+                {
+                  "tagName": "code",
+                  "textContent": "project.json"
+                },
+                {
+                  "tagName": "span",
+                  "textContent": " whose "
+                },
+                {
+                  "tagName": "code",
+                  "textContent": "source"
+                },
+                {
+                  "tagName": "span",
+                  "textContent": " directory contains this file and which declares a "
+                },
+                {
+                  "tagName": "code",
+                  "textContent": "schema"
+                },
+                {
+                  "tagName": "span",
+                  "textContent": "."
+                }
+              ]
+            },
+            {
+              "tagName": "jx-action-button",
+              "attributes": {
+                "part": "content-types"
+              },
+              "$props": {
+                "label": "Content types",
+                "size": "sm"
+              },
+              "onclick": {
+                "$prototype": "Function",
+                "body": [
+                  {
+                    "operator": "call",
+                    "target": {
+                      "$ref": "#/state/openContentTypes"
+                    },
+                    "value": []
+                  }
+                ]
+              },
+              "children": [
+                {
+                  "tagName": "span",
+                  "textContent": "Content types…"
+                }
+              ]
+            }
+          ]
+        }
+      }
+    }
+  ]
+}

package/src/surfaces/entry-editor.ts

@@ -0,0 +1,191 @@
+/// <reference lib="dom" />
+/**
+ * The Entry editor surface: one content entry's fields, in a pane, as a Jx document over the kit.
+ *
+ * This is the adapter. `content/entry-editor.ts` keeps the editor — which pane holds which tab,
+ * which collection a path belongs to, which record the fields live in, which required keys the
+ * entry does not HAVE, and what the draft switch commits into — and hands this module one
+ * projection whose every field is already a string or a flag. The document draws it and decides
+ * nothing.
+ *
+ * **The form is an ISLAND, and that is the whole shape of this conversion.** A form built from a
+ * JSON Schema is `ui/schema-form.ts`'s surface rather than this one's, and that engine hands back a
+ * host ELEMENT rather than a template. So the document renders an empty `fields` node, announces it
+ * through `onNodeCreated` — the one seam for an island (specs/studio-ui-guidelines.md §9.4) — and
+ * the flow puts the engine's element in it. Nothing here knows what a schema is.
+ *
+ * **Announced, never queried.** The `fields` node lives inside a `$switch` case, so a document that
+ * moves from "this file is in no collection" to "this file is an entry" builds a NEW one; a handle
+ * found once by selector would be detached DOM the moment the discriminant moved. `onNodeCreated`
+ * fires on every creation, including the reconciler's, which is what makes the handle keep up.
+ *
+ * **The card is mounted once per PANE.** `entry` is one of the kinds the side pane may host, so two
+ * stages can each be drawing one: this module 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.
+ *
+ * @docs studio/projects/content-types
+ */
+
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import entryEditorDoc from "./entry-editor.json";
+import type { JxDocument } from "@jxsuite/schema/types";
+import type { SurfaceHandle } from "../ui/surface";
+
+registerSurface("entry-editor", entryEditorDoc as unknown as JxDocument);
+
+/** Everything the document draws, as one value. */
+export interface EntryEditorView {
+  /** The region id stamped on the root — `pane.<id>/entry`. */
+  region: string;
+  /** The region id on the field list — `pane.<id>/entry/fields`. */
+  fieldsRegion: string;
+  /**
+   * Which of the two stages to draw.
+   *
+   * `empty` is not an error state: the mode is reachable from the palette and from `__jxAutomation`
+   * on any tab, so a document that belongs to no collection has to say the reason and the fix.
+   */
+  stage: "entry" | "empty";
+  /** The entry's file name — the heading. */
+  name: string;
+  /** The collection's name, in the chip beside it. */
+  collection: string;
+  /** Whether this collection has a draft workflow at all; with none, neither state is drawn. */
+  draftAxis: "hidden" | "shown";
+  /** Whether the entry is marked a draft. */
+  draft: boolean;
+  /** The switch's tooltip: what a draft IS, in `content/draft-state.ts`'s one sentence. */
+  draftHint: string;
+  /** Whether the sentence under the header is drawn — only while the entry IS a draft. */
+  noteState: "hidden" | "shown";
+  note: string;
+  /** The `empty` stage's first sentence, naming the document it is about. */
+  emptyLine: string;
+}
+
+/** What the reader can do here. Both are decisions the editor owns. */
+export interface EntryEditorActions {
+  /** The draft switch moved. A setter, never a toggle. */
+  setDraft: (draft: boolean) => void;
+  /** Open Project Settings › Content types — the door out of the `empty` stage. */
+  openContentTypes: () => void;
+}
+
+/** The node the document renders empty for somebody else to fill. */
+export interface EntryEditorIslands {
+  /** The schema form's host, whenever the document has just created one. */
+  fieldsSlot: (host: HTMLElement) => void;
+}
+
+export interface EntryEditorSurfaceHandle {
+  /** Resolves with the document's root once it has rendered. */
+  ready: Promise<HTMLElement>;
+  /** Whether what was mounted is still inside the host. */
+  attached: () => boolean;
+  update: (view: EntryEditorView) => void;
+  dispose: () => void;
+}
+
+/** The scope the document reads: the view plus the actions, flat. */
+interface EntryEditorScope extends Record<string, unknown>, EntryEditorView, EntryEditorActions {}
+
+/** Write a whole view into the scope. Assignment only — the mount is never rebuilt for a repaint. */
+function project(scope: EntryEditorScope, view: EntryEditorView): void {
+  scope.region = view.region;
+  scope.fieldsRegion = view.fieldsRegion;
+  scope.stage = view.stage;
+  scope.name = view.name;
+  scope.collection = view.collection;
+  scope.draftAxis = view.draftAxis;
+  scope.draft = view.draft;
+  scope.draftHint = view.draftHint;
+  scope.noteState = view.noteState;
+  scope.note = view.note;
+  scope.emptyLine = view.emptyLine;
+}
+
+/** The `part` a node was authored with, or `""` — the only thing this adapter asks about a node. */
+function partOf(def: unknown): string {
+  const attributes = (def as { attributes?: Record<string, unknown> } | null)?.attributes;
+  const part = attributes?.["part"];
+  return typeof part === "string" ? part : "";
+}
+
+/**
+ * Mount the Entry editor document into `host` — the pane's canvas stage.
+ *
+ * The host is CLEARED first, for the reason `surfaces/media-pane.ts` gives: the stage is handed to
+ * whichever mode owns it whole, and emptying it is what stops two editors stacking when a second
+ * file opens into the same pane before the first mount has settled.
+ *
+ * @param {HTMLElement} host - The pane's canvas stage
+ * @param {EntryEditorView} view - What to draw right now
+ * @param {EntryEditorActions} actions - What each control does
+ * @param {EntryEditorIslands} islands - Where the schema form lands
+ * @returns {EntryEditorSurfaceHandle}
+ */
+export function mountEntryEditorSurface(
+  host: HTMLElement,
+  view: EntryEditorView,
+  actions: EntryEditorActions,
+  islands: EntryEditorIslands,
+): EntryEditorSurfaceHandle {
+  host.replaceChildren();
+  const scope = reactive<EntryEditorScope>({
+    collection: "",
+    draft: false,
+    draftAxis: "hidden",
+    draftHint: "",
+    emptyLine: "",
+    fieldsRegion: "",
+    name: "",
+    note: "",
+    noteState: "hidden",
+    openContentTypes: actions.openContentTypes,
+    region: "",
+    setDraft: actions.setDraft,
+    stage: "empty",
+  }) as EntryEditorScope;
+  project(scope, view);
+
+  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: the island
+     announces itself through `onNodeCreated` as it is created, which is one `connectedCallback`
+     earlier than awaiting the element would be (§1.1, "await the element"). */
+  const ready = mountSurface("entry-editor", scope, host, {
+    onNodeCreated: (element, _path, def) => {
+      if (element instanceof HTMLElement && partOf(def) === "fields") {
+        islands.fieldsSlot(element);
+      }
+    },
+  }).then((surface) => {
+    if (disposed) {
+      surface.dispose();
+      return surface.root as HTMLElement;
+    }
+    mounted = surface;
+    return surface.root as HTMLElement;
+  });
+
+  return {
+    attached: () => {
+      if (disposed) {
+        return false;
+      }
+      const root = mounted?.root;
+      /* A mount still in flight has nothing in the host yet, and answering "no" to that would make
+         the next canvas repaint tear down the mount it is waiting for and start another. */
+      return root === undefined ? true : root instanceof HTMLElement && host.contains(root);
+    },
+    dispose() {
+      disposed = true;
+      mounted?.dispose();
+      mounted = null;
+    },
+    ready,
+    update: (next) => project(scope, next),
+  };
+}