@jxsuite/studio 6.1.2 → 8.0.0

package/src/content/entry-inspector.ts

@@ -0,0 +1,225 @@
+/// <reference lib="dom" />
+/**
+ * The Inspector's Entry tab: what the Page tab draws while a collection entry is the focused
+ * document (`specs/studio.md` §6, §22.5; the Content-Entry board's sidebar).
+ *
+ * Four things, in the board's order: the entry's **status** (its draft flag, when the collection
+ * has a draft workflow, `content/draft-state.ts`), its **fields** as the collection's schema types
+ * them (`ui/schema-form.ts` over `content/entry-fields.ts`, the same form and the same transacted
+ * commits as the form-only editor, so ⌘Z undoes a field here exactly as it does there), the **URL**
+ * its collection page publishes it at (`content/collection-pages.ts`), and the **file** it is
+ * stored in, with what that file holds.
+ *
+ * The body is written on the canvas beside it; this tab is the entry's frontmatter (or, for a JSON
+ * entry opened on the canvas by hand, its root). The form-only `entry` editor stays for the entries
+ * the canvas cannot write.
+ *
+ * @docs studio/projects/content-types
+ */
+
+import { effect, effectScope } from "../reactivity";
+import { projectState } from "../store";
+import { runActiveReported } from "../commands/run-reported";
+import { mountSchemaForm } from "../ui/schema-form";
+import { collectionForFile } from "./collection-match";
+import { capitalise, contentCollection } from "./content-collections";
+import {
+  entryLocale,
+  entryUrl,
+  onCollectionPagesRead,
+  peekCollectionPage,
+} from "./collection-pages";
+import { commitEntryFields, entryFields } from "./entry-fields";
+import { DRAFT_MEANING, hasDraftAxis, isDraftEntry } from "./draft-state";
+import { entryCollection } from "./entry-model";
+import {
+  absentRequiredErrors,
+  fieldLabels,
+  formContext,
+  setEntryDraft,
+  titleFirst,
+} from "./entry-editor";
+import { mountEntryInspectorSurface } from "../surfaces/entry-inspector";
+import type { EntryInspectorHandle, EntryInspectorView } from "../surfaces/entry-inspector";
+import type { JsonSchema } from "../ui/schema-form";
+import type { JsonObject } from "@jxsuite/schema/types";
+import type { EffectScope } from "@vue/reactivity";
+import type { Tab } from "../tabs/tab";
+
+/** The region the tab's root carries. */
+export const ENTRY_INSPECTOR_REGION = "inspector/entry";
+
+/** A word with its first letter in capitals. */
+
+/** Whether a tab's document is a collection entry: what titles the Page tab "Entry" (§6). */
+export function isEntryTab(tab: Tab | null): boolean {
+  const match = collectionForFile(tab?.documentPath);
+  return match !== null && !match.fileBacked;
+}
+
+/** What the tab draws for an entry. */
+export function entryInspectorView(tab: Tab): EntryInspectorView {
+  const path = tab.documentPath ?? "";
+  const match = collectionForFile(path);
+  const name = match?.name ?? "";
+  const collection = entryCollection(name);
+  const fields = entryFields(tab);
+  const draftAxis = hasDraftAxis(collection?.schema, fields);
+  const draft = isDraftEntry(fields);
+  const page = name === "" ? null : peekCollectionPage(name, entryLocale(path));
+  const url = page ? entryUrl(page, path, fields) : null;
+  const isJson = path.endsWith(".json");
+  return {
+    draft,
+    draftAxis: draftAxis ? "shown" : "hidden",
+    draftHint: DRAFT_MEANING,
+    fieldsState: collection?.schema ? "form" : "none",
+    kind: capitalise(contentCollection(name)?.item ?? "entry"),
+    path,
+    region: ENTRY_INSPECTOR_REGION,
+    status: draftAxis ? (draft ? "Draft" : "Published") : "",
+    storage: isJson
+      ? ". Its fields are the file itself."
+      : ". Fields are its frontmatter, and the body is its Markdown.",
+    url: url ?? "",
+    urlState: page === undefined ? "loading" : url ? "shown" : page ? "unlisted" : "none",
+  };
+}
+
+// ─── Mounting ────────────────────────────────────────────────────────────────
+
+interface StandingInspector {
+  host: HTMLElement;
+  tabId: string;
+  handle: EntryInspectorHandle;
+  scope: EffectScope;
+  formHost: HTMLElement | null;
+  /**
+   * Repaint this tab, if it is still the one standing: the form's, the pages index's and the
+   * effect's.
+   */
+  redraw: () => void;
+  unlisten: () => void;
+}
+
+let _standing: StandingInspector | null = null;
+
+/** Put the field form into the node the document made for it, or bring it up to date. */
+function paintForm(standing: StandingInspector, tab: Tab): void {
+  const collection = entryCollection(collectionForFile(tab.documentPath)?.name ?? "");
+  if (!standing.formHost || !collection?.schema) {
+    return;
+  }
+  const fields = entryFields(tab);
+  /* SAFETY: `collection.schema` is the collection's JSON Schema, the shape `JsonSchema` names for
+     the form; `fields` is a frontmatter block or a JSON entry's root, both parsed from YAML or JSON
+     text, so every value is JSON. The same reading `entry-editor.ts` makes. */
+  const form = mountSchemaForm(
+    "entry-inspector",
+    titleFirst(collection.schema as JsonSchema, collection.schema, fields),
+    fields as JsonObject,
+    {
+      context: formContext(tab),
+      errors: absentRequiredErrors(collection, fields),
+      onChange: (patch) => commitEntryFields(tab, patch),
+      rerender: standing.redraw,
+      ui: fieldLabels(collection.schema),
+    },
+  );
+  if (form.parentNode !== standing.formHost) {
+    standing.formHost.replaceChildren(form);
+  }
+}
+
+/** Repaint the tab and its form. */
+function draw(standing: StandingInspector, tab: Tab): void {
+  const view = entryInspectorView(tab);
+  if (view.fieldsState === "none") {
+    standing.formHost = null;
+  }
+  standing.handle.update(view);
+  paintForm(standing, tab);
+}
+
+/** Take the tab down. Idempotent. */
+export function unmountEntryInspector(host?: HTMLElement): void {
+  if (!_standing || (host !== undefined && _standing.host !== host)) {
+    return;
+  }
+  _standing.unlisten();
+  _standing.scope.stop();
+  _standing.handle.dispose();
+  _standing = null;
+}
+
+/**
+ * Draw the Entry tab for `tab` into `host`, or bring the one already there up to date.
+ *
+ * Owns its own effect over the entry's fields, like the form-only editor, so a field commit
+ * repaints the tab and nothing else.
+ */
+export function renderEntryInspector(host: HTMLElement, tab: Tab): void {
+  if (
+    _standing &&
+    _standing.host === host &&
+    _standing.tabId === tab.id &&
+    _standing.handle.attached()
+  ) {
+    draw(_standing, tab);
+    return;
+  }
+  unmountEntryInspector();
+  const scope = effectScope();
+  const redraw = (): void => {
+    if (_standing === standing) {
+      draw(standing, tab);
+    }
+  };
+  const standing: StandingInspector = {
+    formHost: null,
+    handle: mountEntryInspectorSurface(
+      host,
+      entryInspectorView(tab),
+      {
+        openFields: () => {
+          const name = collectionForFile(tab.documentPath)?.name;
+          void runActiveReported(
+            "settings.open",
+            name ? { entry: name, section: "content" } : { section: "content" },
+            "Entry",
+          );
+        },
+        /* The command, not a local open(): Search appearance has one definition site, and an
+           entry's search title, description and image are frontmatter it commits into. */
+        openSeo: () => {
+          void runActiveReported("document.openSeo", undefined, "Entry");
+        },
+        setDraft: (draft) => setEntryDraft(tab, draft),
+      },
+      {
+        fieldsSlot: (element) => {
+          if (_standing === standing) {
+            standing.formHost = element;
+            paintForm(standing, tab);
+          }
+        },
+      },
+    ),
+    host,
+    redraw,
+    scope,
+    tabId: tab.id,
+    unlisten: onCollectionPagesRead(redraw),
+  };
+  _standing = standing;
+  scope.run(() => {
+    effect(() => {
+      // Both stores, for the reason `entry-editor.ts` gives: which one holds the fields is
+      // `entry-fields.ts`'s answer, and the document is the reference every transaction replaces.
+      void tab.doc.document;
+      void tab.doc.content.frontmatter;
+      void projectState?.projectConfig?.content;
+      redraw();
+    });
+  });
+}

package/src/content/entry-model.ts

@@ -14,9 +14,9 @@
  *    fill in and "absent" is a validation failure they did not cause.
  * 2. **Where the entry files are** is `collectionInfo`'s answer, imported rather than recomputed.
  *    Three copies of "which collection owns this path, and what extension do its entries carry"
- *    already exist (`utils/studio-utils.ts`'s `findContentTypeSchema`, `grid/sources/content-
- *    source.ts`'s `collectionInfo`, `browse/library-model.ts`'s `contentTypeFor`); this module adds
- *    no fourth and calls the two that are exported.
+ *    existed when this was written (`utils/studio-utils.ts`'s `findContentTypeSchema`,
+ *    `grid/sources/content-source.ts`'s `collectionInfo`, and `browse/library-model.ts`'s
+ *    `contentTypeFor`, since deleted); this module adds no fourth and calls the exported ones.
  *
  * **The draft axis is NOT here.** `content/draft-state.ts` owns what a draft is and whether drafts
  * are listed, because this module imports `content-source.ts` and the grid source must be able to
@@ -99,6 +99,20 @@ export function collectionOfPath(path: string | null): EntryCollection | null {
   return matched ? entryCollection(matched.name) : null;
 }
 
+/**
+ * The collection a file-backed collection's FILE holds the records of (`content/projects.csv`), or
+ * null. {@link entryCollection} refuses one, rightly, for everything that makes a new entry FILE; a
+ * record's form only reads its schema and its name, and `dir` is the file itself.
+ */
+export function recordCollectionOfPath(path: string | null): EntryCollection | null {
+  const matched = findContentTypeSchema(path ?? null, projectState?.projectConfig);
+  const info = matched ? collectionInfo(matched.name) : null;
+  if (!matched || !info) {
+    return null;
+  }
+  return { def: info.def, dir: info.dir, ext: info.ext, name: info.name, schema: matched.schema };
+}
+
 // ─── Seeding a new entry ─────────────────────────────────────────────────────
 
 /** Deep copy of a schema `default`, so two entries seeded from one schema never share an object. */

package/src/content/entry-open.ts

@@ -0,0 +1,80 @@
+/**
+ * Opening a content entry: on the canvas in its writing editor, or in the form when it has no body.
+ *
+ * `specs/studio.md` §22.5: an entry is written on the canvas, inside its template's layout. Opening
+ * one opens the entry's OWN file as an ordinary tab — same id, history and dirty flag as a click in
+ * any file list — in its writing editor (`edit`), which the Content workspace owns (§22.1), so the
+ * Inspector's Entry tab and the writing-mode banner come with it. Every door into an entry goes
+ * through {@link openEntry}: a row in the Content home, an entry in the Collections panel,
+ * `content.openEntry`, and the entry Add new just made.
+ *
+ * The form-only `entry` editor (`content/entry-editor.ts`) stays as the fallback for an entry the
+ * canvas cannot write: a JSON entry IS its fields and has no body, and a file-backed collection's
+ * entries are rows of one file, which open in the grid.
+ *
+ * @docs studio/projects/content-types
+ */
+
+import { activateTab, workspace } from "../workspace/workspace";
+import { collectionForFile } from "./collection-match";
+import { writesEntryOnCanvas } from "./content-collections";
+import { openEntryEditor } from "./entry-editor";
+import type { Tab } from "../tabs/tab";
+
+/** The editor an entry is written in on the canvas. */
+export const WRITING_MODE = "edit";
+
+/** The editors a tab already writes on the canvas in, which an open leaves alone. */
+const CANVAS_MODES: ReadonlySet<string> = new Set(["edit", "design"]);
+
+/**
+ * The open tab for a path, if any (a document tab's id is its path, but a renamed one keeps its
+ * id).
+ */
+function tabFor(path: string): Tab | null {
+  for (const tab of workspace.tabs.values()) {
+    if (tab.documentPath === path) {
+      return tab;
+    }
+  }
+  return null;
+}
+
+/**
+ * Open a content entry where it is written.
+ *
+ * - An entry with a body opens on the canvas in `edit`. A tab already writing it on the canvas
+ *   (`edit` or `design`) keeps its view; a tab showing its form is switched back to writing.
+ * - A JSON entry opens in the form editor.
+ * - Any other file opens as `openFileInTab` would open it.
+ *
+ * @returns The tab, or `null` when the file could not be opened.
+ */
+export async function openEntry(path: string): Promise<Tab | null> {
+  if (!writesEntryOnCanvas(path)) {
+    const match = collectionForFile(path);
+    if (match && !match.fileBacked) {
+      return openEntryEditor(path);
+    }
+    /* Dynamic for the reason `entry-editor.ts` gives: `files/files.ts` reaches the platform, the
+       format registry and the packages layer. */
+    const { openFileInTab } = await import("../files/files");
+    await openFileInTab(path);
+    return tabFor(path);
+  }
+  const { openFileInTab } = await import("../files/files");
+  await openFileInTab(path);
+  const tab = tabFor(path);
+  if (!tab) {
+    return null;
+  }
+  if (
+    !CANVAS_MODES.has(tab.session.ui.canvasMode) &&
+    tab.capabilities.modes.includes(WRITING_MODE)
+  ) {
+    tab.session.ui.canvasMode = WRITING_MODE;
+    tab.session.ui.preview = false;
+  }
+  activateTab(tab.id);
+  return tab;
+}