@jxsuite/studio 6.1.2 → 8.0.1

package/src/content/entry-commands.ts

@@ -1,6 +1,11 @@
 /**
- * The content-entry verbs: create one, open one as a form, mark one a draft, and choose whether
- * drafts are listed at all.
+ * The content-entry verbs: open one where it is written, mark one a draft, and choose whether
+ * drafts are listed at all — and {@link createEntry}, the New File tree's route into a collection
+ * folder.
+ *
+ * Creating an entry from anywhere else is Add new's (`file.new { kind: "entry", collection }`,
+ * `create/add-new-flow.ts`), which seeds through {@link entryFormatName} and `entryBody` exactly as
+ * {@link createEntry} does, so both routes write the same bytes.
  *
  * Each is a record in its owning module, so the palette row, the assistant's tool, the automation
  * step and (for the two that declare one) the context-menu item are renderings of the same
@@ -14,8 +19,6 @@ import {
   argsSchema,
   booleanArg,
   booleanProperty,
-  derivedEnumProperty,
-  enumArg,
   stringArg,
   stringProperty,
 } from "../commands/command-args";
@@ -32,48 +35,61 @@ import { serializeJson } from "@jxsuite/schema/json-layout";
 import { invalidateReferenceEntries } from "../ui/form-controls";
 import { reloadDraftAwareGrids } from "../grid/sources/content-source";
 import { setIncludeDrafts } from "./draft-state";
-import { collectionOfPath, entryCollection, entryCollections, seedEntry } from "./entry-model";
+import { collectionOfPath, entryCollection } from "./entry-model";
+import { entryBody } from "../create/add-new";
 import { collectionForDirectory } from "./collection-match";
 import { LOCALE_PLACEHOLDER } from "../canvas/asset-resolve";
-import { openEntryEditor, setEntryDraft } from "./entry-editor";
+import { setEntryDraft } from "./entry-editor";
+import { openEntry } from "./entry-open";
 import { errorMessage } from "@jxsuite/schema/parse";
 import type { EntryCollection } from "./entry-model";
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
 import type { Tab } from "../tabs/tab";
+import type { JxMutableNode } from "@jxsuite/schema/types";
 
-/** Collection names a New Entry can be created in — the `enum` behind `content.newEntry`. */
-function creatableCollections(): string[] {
-  return entryCollections().map((collection) => collection.name);
+/**
+ * The format class that writes a collection's entries, or `null` for native JSON.
+ *
+ * `collectionInfo` derives `.json` exactly when no format class claimed the collection — the
+ * extension and the serializer name come off the same three lookups in the same order — so "the
+ * extension is .json" and "no format can write this" are one condition. Writing JSON into a `.md`
+ * file is therefore not a state a seed can reach.
+ */
+export function entryFormatName(collection: Pick<EntryCollection, "def" | "ext">): string | null {
+  if (collection.ext === ".json") {
+    return null;
+  }
+  return (
+    (collection.def.format ? formatByName(collection.def.format)?.name : undefined) ??
+    formatForPath(`untitled${collection.ext}`)?.name ??
+    defaultContentFormat()?.name ??
+    null
+  );
 }
 
 /**
- * The source text a new entry starts as.
+ * The source text a new entry starts as: `create/add-new.ts`'s `entryBody`, serialized.
  *
  * A `json` collection is serialized here rather than through the format registry, because JSON is
  * the one native collection shape (site-architecture.md §6.2) and has no format class to ask.
- *
- * `collectionInfo` derives `.json` exactly when no format class claimed the collection — the
- * extension and the serializer name come off the same three lookups in the same order — so "the
- * extension is .json" and "no format can write this" are one condition, and the second is not a
- * separate failure to report. Writing JSON into a `.md` file is therefore not a state this can
- * reach.
  */
 async function seedText(collection: EntryCollection): Promise<string> {
-  const seed = seedEntry(collection.schema);
-  const formatName =
-    (collection.def.format ? formatByName(collection.def.format)?.name : undefined) ??
-    formatForPath(`untitled${collection.ext}`)?.name ??
-    defaultContentFormat()?.name;
-  if (collection.ext === ".json" || formatName === undefined) {
+  const body = entryBody({
+    ext: collection.ext,
+    formatName: entryFormatName(collection),
+    schema: collection.schema,
+  });
+  if (body.format === null) {
     // The save serializer with no layout (`@jxsuite/schema/json-layout`): a seed has no source text, and
     // This is what the formatter makes of one, newline included.
-    return serializeJson(seed, null);
+    return serializeJson(body.doc, null);
   }
-  return formatSerialize(
-    formatName,
-    { ...seed, children: [] },
-    { frontmatter: Object.keys(seed).length > 0, mode: "roundtrip" },
-  );
+  /* SAFETY: an entry body is `{ ...seed, children: [] }`, an element-shaped object, which is the
+     document a format's serializer reads. */
+  return formatSerialize(body.format, body.doc as JxMutableNode, {
+    frontmatter: body.frontmatter ?? false,
+    mode: "roundtrip",
+  });
 }
 
 /**
@@ -127,8 +143,8 @@ export async function createEntry(
    * Where the entry lands.
    *
    * A localized collection's `dir` is `content/exhibitions/{locale}` — a path nobody has. Creating
-   * there makes a directory literally named `{locale}`, which is what `content.newEntry` from the
-   * palette and the `new_content_entry` tool have been doing. There is no default locale to pick on
+   * there makes a directory literally named `{locale}`, which is what the palette's New Entry and
+   * the `new_content_entry` tool used to do. There is no default locale to pick on
    * the author's behalf (choosing one silently files the entry under a language), so this refuses
    * and names the gesture that works.
    */
@@ -162,7 +178,7 @@ export async function createEntry(
   }
   // The picker's choices just changed; a cached list would keep offering the old set.
   invalidateReferenceEntries(collection.name);
-  await openEntryEditor(created);
+  await openEntry(created);
   return created;
 }
 
@@ -175,32 +191,6 @@ function activeEntryTab(): Tab | null {
 /** The content-entry command records. */
 export function contentCommands(): AnyCommand[] {
   return [
-    {
-      args: argsSchema({
-        collection: derivedEnumProperty(
-          creatableCollections,
-          "The content collection the entry is created in.",
-        ),
-      }),
-      category: "File",
-      id: "content.newEntry",
-      level: "project",
-      menus: ["palette"],
-      group: "1_file",
-      requires: "a project with a directory-backed content collection",
-      when: (ctx) => ctx.project.open,
-      enablement: () => creatableCollections().length > 0,
-      undo: "project",
-      /* No `aiTool`, by studio-ui-guidelines.md §12.4's second deletion rule: `createEntry` awaits
-         `createFileIn`, which awaits the New File prompt for the name; a cancel resolves with
-         nothing thrown. An optional `name` argument that skips the prompt is the way back in, and
-         is a UX call (issue 273). */
-      run: async (_ctx, args) => {
-        const names = creatableCollections();
-        await createEntry(enumArg("content.newEntry", args, "collection", names));
-      },
-      title: "New Entry",
-    },
     {
       args: argsSchema({
         path: stringProperty("Project-relative path of the entry file to open."),
@@ -213,11 +203,12 @@ export function contentCommands(): AnyCommand[] {
       requires: "an open project",
       when: (ctx) => ctx.project.open,
       /* No `aiTool`, by studio-ui-guidelines.md §12.4's first deletion rule: this opens a surface;
-         the model has `open_document`. */
+         the model has `open_document`. An entry with a body opens on the canvas in its writing
+         editor, inside its template's layout; a JSON entry opens in the form (§22.5). */
       run: async (_ctx, args) => {
-        await openEntryEditor(stringArg("content.openEntry", args, "path"));
+        await openEntry(stringArg("content.openEntry", args, "path"));
       },
-      title: "Open Entry Form",
+      title: "Open Entry",
     },
     {
       args: argsSchema({

package/src/content/entry-editor.ts

@@ -3,11 +3,11 @@
  * The **Entry editor** (site-architecture.md §7.4): a content entry's fields, as a form, in a pane.
  *
  * Until now a markdown entry could be edited two ways and neither was its schema: the canvas edited
- * its BODY, and the Document Header card drew a field list from `panels/frontmatter-fields.ts`'s
- * own type→widget ladder, which is a second implementation of `ui/schema-form.ts` with no reference
- * branch, no validation and no value-source ladder. A JSON entry (`authors/ada.json`) had no field
- * editor at all — it opened as a component tree, so `bio` was a node's property and `links` was a
- * child array.
+ * its BODY, and the Document Header card (since removed) drew a field list from
+ * `panels/frontmatter-fields.ts`'s own type→widget ladder, which is a second implementation of
+ * `ui/schema-form.ts` with no reference branch, no validation and no value-source ladder. A JSON
+ * entry (`authors/ada.json`) had no field editor at all — it opened as a component tree, so `bio`
+ * was a node's property and `links` was a child array.
  *
  * This is one editor over the schema form, so every improvement to the engine reaches content
  * entries, settings and the inspector at once — and the `reference` control in particular arrives
@@ -25,7 +25,7 @@
  * it unshifts its mode onto the tab the file already has, so ⌘S, the dirty flag, the transaction
  * log and undo are the ordinary document verbs. Every field commits through
  * {@link mutateEntryField}, so an edit made here is undone by ⌘Z and replayed by a collaborator
- * exactly as one made in the Document Header card.
+ * exactly as one made in the Inspector's Page tab.
  *
  * **One editor, two storage shapes.** A markdown entry keeps its fields in frontmatter; a JSON
  * entry IS its fields. `content/entry-fields.ts` owns that single question, and this file never
@@ -52,16 +52,21 @@ import { activateTab, workspace } from "../workspace/workspace";
 import { commitEntryFields, entryFields, mutateEntryField } from "./entry-fields";
 import type { EntryFields } from "./entry-fields";
 import { DRAFT_FIELD, DRAFT_MEANING, hasDraftAxis, isDraftEntry } from "./draft-state";
-import { collectionOfPath, missingRequired } from "./entry-model";
+import { collectionOfPath, missingRequired, recordCollectionOfPath } from "./entry-model";
+import { ENTRY_MODE, isRecordTab, recordPlace, showRecord } from "./record-entry";
+import { requestGridReveal } from "../grid/grid-reveal";
+import { titleFieldOf } from "./entry-summaries";
 import type { EntryCollection } from "./entry-model";
 import type { EntryEditorSurfaceHandle, EntryEditorView } from "../surfaces/entry-editor";
 import type { JsonSchema, SchemaFormContext } from "../ui/schema-form";
 import type { Tab } from "../tabs/tab";
 import type { CanvasSurface } from "../canvas/canvas-surface";
-import type { JsonObject } from "@jxsuite/schema/types";
+import type { ContentTypeSchema, JsonObject } from "@jxsuite/schema/types";
+import { isString } from "@jxsuite/schema/guards";
+import { fieldTitle } from "../browse/library-source";
 
-/** The `canvasMode` the entry form draws under. */
-export const ENTRY_MODE = "entry";
+/** The `canvasMode` the entry form draws under (defined with the record a form may be over). */
+export { ENTRY_MODE } from "./record-entry";
 
 /** What an entry tab's mode list becomes when the Entry editor opens it: the form leads. */
 const ENTRY_TAB_MODES = [ENTRY_MODE];
@@ -149,7 +154,7 @@ export interface DraftPill {
  * chip's `status` slot, and `.entry-pill`'s rules in `styles/overlays.css` are dead with it.
  */
 export function entryDraftPill(tab: Tab): DraftPill | null {
-  const collection = collectionOfPath(tab.documentPath);
+  const collection = entryCollectionOf(tab);
   const fields = entryFields(tab);
   if (!collection || !hasDraftAxis(collection.schema, fields)) {
     return null;
@@ -164,8 +169,24 @@ export function entryDraftPill(tab: Tab): DraftPill | null {
 
 // ─── The form ────────────────────────────────────────────────────────────────
 
+/**
+ * The words each field's row is titled with: the schema's own `title` where it states one, else the
+ * key in words (`publishedAt` → "Published at"), the spelling the Content home's columns use. A raw
+ * key is a storage name, and an author reads "Cover", not `cover`.
+ */
+export function fieldLabels(
+  schema: ContentTypeSchema | null | undefined,
+): Record<string, { label: string }> {
+  return Object.fromEntries(
+    Object.entries(schema?.properties ?? {}).map(([name, field]) => [
+      name,
+      { label: isString(field.title) && field.title !== "" ? field.title : fieldTitle(name) },
+    ]),
+  );
+}
+
 /** The form's host context: enum pointers resolve against this project's configuration. */
-function formContext(tab: Tab): SchemaFormContext {
+export function formContext(tab: Tab): SchemaFormContext {
   return {
     fieldKeyPrefix: `entry:${tab.id}`,
     resolvePointer: (pointer, scope) =>
@@ -184,7 +205,7 @@ function formContext(tab: Tab): SchemaFormContext {
  * missing from the file is a fact about the document, and saying so is the whole reason the form
  * knows the schema.
  */
-function absentRequiredErrors(
+export function absentRequiredErrors(
   collection: EntryCollection,
   fields: EntryFields,
 ): Record<string, string> {
@@ -196,6 +217,32 @@ function absentRequiredErrors(
   );
 }
 
+/** The collection an entry tab's form is typed by: its file's, or for a record its file's records'. */
+function entryCollectionOf(tab: Tab): EntryCollection | null {
+  return isRecordTab(tab)
+    ? recordCollectionOfPath(tab.documentPath)
+    : collectionOfPath(tab.documentPath);
+}
+
+/**
+ * The schema with the entry's title field moved to the top: what an entry is called is the first
+ * thing an author looks for, and a schema imported from a CMS lists its properties alphabetically,
+ * which put `title` after forty other fields.
+ */
+export function titleFirst(
+  form: JsonSchema,
+  schema: ContentTypeSchema | null,
+  fields: EntryFields,
+): JsonSchema {
+  const title = titleFieldOf(schema, fields);
+  const properties = form.properties ?? {};
+  const held = title === null ? undefined : properties[title];
+  if (title === null || held === undefined) {
+    return form;
+  }
+  return { ...form, properties: { [title]: held, ...properties } };
+}
+
 /** What the document says when the file belongs to no collection: the reason, then the fix. */
 function emptyLine(tab: Tab): string {
   return `${tab.documentPath ?? "This document"} is not an entry of any content collection, so there is no schema to draw a form from.`;
@@ -214,14 +261,20 @@ function entryView(paneId: string, tab: Tab, collection: EntryCollection | null)
       emptyLine: emptyLine(tab),
       fieldsRegion,
       name: "",
+      nextDisabled: true,
       note: "",
       noteState: "hidden",
+      place: "",
+      previousDisabled: true,
+      recordNav: "hidden",
       region,
       stage: "empty",
     };
   }
   const fields = entryFields(tab);
   const draft = isDraftEntry(fields);
+  const record = isRecordTab(tab);
+  const place = recordPlace(tab);
   return {
     collection: collection.name,
     draft,
@@ -229,14 +282,31 @@ function entryView(paneId: string, tab: Tab, collection: EntryCollection | null)
     draftHint: DRAFT_MEANING,
     emptyLine: "",
     fieldsRegion,
-    name: tab.documentPath?.split("/").pop() ?? "Untitled",
+    // A record is called what the Content home calls it: its title field, else its row.
+    name: record
+      ? recordName(collection, fields, place.index)
+      : (tab.documentPath?.split("/").pop() ?? "Untitled"),
+    nextDisabled: place.next === null,
     note: DRAFT_MEANING,
     noteState: draft ? "shown" : "hidden",
+    place: place.index === -1 ? "" : `${place.index + 1} of ${place.total}`,
+    previousDisabled: place.previous === null,
+    recordNav: record ? "shown" : "hidden",
     region,
     stage: "entry",
   };
 }
 
+/** A record's heading: its title field's text, else its first text, else "Row n". */
+function recordName(collection: EntryCollection, fields: EntryFields, index: number): string {
+  const field = titleFieldOf(collection.schema, fields);
+  const named = field === null ? undefined : fields[field];
+  if (isString(named) && named.trim() !== "") {
+    return named.trim();
+  }
+  return index === -1 ? "Record" : `Row ${index + 1}`;
+}
+
 /**
  * Mount the entry form into the pane.
  *
@@ -289,13 +359,14 @@ export function renderEntryMode(surface: CanvasSurface, tab: Tab): void {
        JSON text, so every value is JSON; a key an editor cleared reads as absent either way. */
     const form = mountSchemaForm(
       `entry:${paneId}`,
-      collection.schema as JsonSchema,
+      titleFirst(collection.schema as JsonSchema, collection.schema, fields),
       fields as JsonObject,
       {
         context: formContext(tab),
         errors: absentRequiredErrors(collection, fields),
         onChange: (patch) => commitEntryFields(tab, patch),
         rerender: redraw,
+        ui: fieldLabels(collection.schema),
       },
     );
     if (form.parentNode !== formHost) {
@@ -304,7 +375,7 @@ export function renderEntryMode(surface: CanvasSurface, tab: Tab): void {
   };
 
   const draw = () => {
-    const collection = collectionOfPath(tab.documentPath);
+    const collection = entryCollectionOf(tab);
     if (!collection) {
       /* The `fields` node goes with the case that held it, so the handle is dropped here rather
          than left pointing at a node the reconciler is about to remove. */
@@ -317,17 +388,37 @@ export function renderEntryMode(surface: CanvasSurface, tab: Tab): void {
   const scope = effectScope();
   const mounted = mountEntryEditorSurface(
     canvasWrap,
-    entryView(paneId, tab, collectionOfPath(tab.documentPath)),
+    entryView(paneId, tab, entryCollectionOf(tab)),
     {
       openContentTypes: () => {
         void activeRegistry()?.run("settings.open", { section: "content" });
       },
+      openGrid: () => {
+        // The grid lands on the row this form was showing (`grid/grid-reveal.ts`).
+        const { index } = recordPlace(tab);
+        if (index !== -1 && tab.documentPath) {
+          requestGridReveal(tab.documentPath, index);
+        }
+        tab.session.ui.canvasMode = "grid";
+      },
       setDraft: (draft) => setEntryDraft(tab, draft),
+      showNext: () => {
+        const { next } = recordPlace(tab);
+        if (next !== null) {
+          showRecord(tab, next);
+        }
+      },
+      showPrevious: () => {
+        const { previous } = recordPlace(tab);
+        if (previous !== null) {
+          showRecord(tab, previous);
+        }
+      },
     },
     {
       fieldsSlot: (host) => {
         formHost = host;
-        paintForm(collectionOfPath(tab.documentPath));
+        paintForm(entryCollectionOf(tab));
       },
     },
   );
@@ -346,6 +437,8 @@ export function renderEntryMode(surface: CanvasSurface, tab: Tab): void {
       void tab.doc.document;
       void tab.doc.content.frontmatter;
       void projectState?.projectConfig?.content;
+      // A record's fields are its grid's rows and pending cells, read through `entryFields`, which
+      // Tracks them. Which record is shown is tracked by `recordOf` the same way.
       draw();
     });
   });

package/src/content/entry-fields.ts

@@ -32,6 +32,7 @@ import { cloneValue } from "@jxsuite/schema/doc-ops";
 import { notePreviewOverlayEdit } from "../preview/preview-overlay";
 import { recordDocOp } from "../tabs/patch-ops";
 import { mutateUpdateFrontmatter, transactDoc } from "../tabs/transact";
+import { commitRecordFields, isRecordTab, recordFields } from "./record-entry";
 import type { JxDocumentValue } from "@jxsuite/schema/types";
 import type { Tab } from "../tabs/tab";
 import type { JsonValue } from "../types";
@@ -64,6 +65,10 @@ function fieldsAreDocument(tab: Tab): boolean {
  * `tab.doc.document` to see which store answered.
  */
 export function entryFields(tab: Tab): EntryFields {
+  // A record of a file-backed collection keeps its fields in a row of its file's grid.
+  if (isRecordTab(tab)) {
+    return recordFields(tab);
+  }
   return fieldsAreDocument(tab) ? tab.doc.document : tab.doc.content.frontmatter;
 }
 
@@ -105,7 +110,9 @@ function mutateDocumentField(tab: Tab, field: string, value?: JsonValue): void {
  * step.
  */
 export function mutateEntryField(tab: Tab, field: string, value?: JsonValue): void {
-  if (fieldsAreDocument(tab)) {
+  if (isRecordTab(tab)) {
+    commitRecordFields(tab, { [field]: value });
+  } else if (fieldsAreDocument(tab)) {
     mutateDocumentField(tab, field, value);
   } else {
     mutateUpdateFrontmatter(tab, field, value);
@@ -119,6 +126,11 @@ export function mutateEntryField(tab: Tab, field: string, value?: JsonValue): vo
  * on the undo stack as several steps — and an author who changed one thing expects one ⌘Z.
  */
 export function commitEntryFields(tab: Tab, patch: Record<string, JsonValue | undefined>): void {
+  // A record's edit is the grid buffer's, whose own undo group is the one ⌘Z reverts.
+  if (isRecordTab(tab)) {
+    commitRecordFields(tab, patch);
+    return;
+  }
   transactDoc(tab, (t) => {
     for (const [field, value] of Object.entries(patch)) {
       mutateEntryField(t, field, value);