@jxsuite/studio 2.0.0 → 2.1.0

package/src/content/entry-commands.ts

@@ -0,0 +1,282 @@
+/**
+ * The content-entry verbs: create one, open one as a form, mark one a draft, and choose whether
+ * drafts are listed at all.
+ *
+ * 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
+ * declaration. Two of them are **setters and not toggles** — `content.setDraft {draft}` and
+ * `content.setIncludeDrafts {include}` name the state they reach, because "toggle the draft flag"
+ * run twice by a script leaves the entry exactly where it started and run once against an unknown
+ * default publishes something private.
+ */
+
+import {
+  argsSchema,
+  booleanArg,
+  booleanProperty,
+  enumArg,
+  stringArg,
+  stringProperty,
+} from "../commands/command-args";
+import {
+  defaultContentFormat,
+  formatByName,
+  formatForPath,
+  formatSerialize,
+  loadFormats,
+} from "../format/format-host";
+import { notify } from "../services/notify";
+import { activeTab } from "../workspace/workspace";
+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 { openEntryEditor, setEntryDraft } from "./entry-editor";
+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";
+
+/** Collection names a New Entry can be created in — the `enum` behind `content.newEntry`. */
+function creatableCollections(): string[] {
+  return entryCollections().map((collection) => collection.name);
+}
+
+/**
+ * An enum property whose values are derived WHEN THE SCHEMA IS READ, not when the record is
+ * defined.
+ *
+ * `enumProperty(creatableCollections(), …)` looks identical and is wrong here, and the difference
+ * is invisible in a unit test: a command record is built at module scope —
+ * `commands/app-commands.ts` and `studio.ts` both call {@link contentCommands} before a project is
+ * open — so the array is frozen at `[]`, and `panels/quick-search.ts`'s `paletteArgs` offered an
+ * empty choice list forever after. `run` re-derived the list, which is why the programmatic call
+ * worked and the palette did not: two answers to "which collections exist", one of them a snapshot
+ * of the empty boot state.
+ *
+ * A getter is the whole fix — the palette reads `property.enum` when it opens the prompt, the AI
+ * tool's parameters serialise it when the tool list is built, and `scripts/check-shot-contract.ts`
+ * reads it in a bare Bun process where the honest answer really is "none declared".
+ */
+function derivedEnumProperty(declared: () => readonly string[], description: string): object {
+  return {
+    description,
+    get enum() {
+      return [...declared()];
+    },
+    type: "string",
+  };
+}
+
+/**
+ * The source text a new entry starts as.
+ *
+ * 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) {
+    return JSON.stringify(seed, null, 2);
+  }
+  return formatSerialize(
+    formatName,
+    { ...seed, children: [] },
+    { frontmatter: Object.keys(seed).length > 0, mode: "roundtrip" },
+  );
+}
+
+/**
+ * Create an entry in a collection and open it in its form editor.
+ *
+ * The file goes through `files/files.ts`'s single creation flow — the same name field, the same
+ * "already exists" refusal, the same Problem on failure as the Files tree and the Library — with
+ * two things this caller supplies that a generic "New File" cannot: the collection's **extension**,
+ * so the field asks for a display name and the file is actually matched by the collection it was
+ * created in, and a **body seeded from the schema**, so the entry is valid the moment it exists
+ * instead of being a pile of absent required fields.
+ *
+ * @returns The created path, or null when the author cancelled or the write failed.
+ */
+export async function createEntry(collectionName: string): Promise<string | null> {
+  const collection = entryCollection(collectionName);
+  if (!collection) {
+    notify.error(`No content collection named "${collectionName}" to create an entry in.`, {
+      detail:
+        "A collection needs a `content` entry in project.json whose `source` is a directory. A " +
+        "collection whose source names a single file (a CSV catalogue) has rows, not entry files.",
+      source: "Content",
+    });
+    return null;
+  }
+  await loadFormats().catch(() => {
+    /* An unreachable format registry is not a reason to refuse: `seedText` falls back to the
+       native JSON shape, and the serializer's own failure is reported below with the path. */
+  });
+  let content: string;
+  try {
+    content = await seedText(collection);
+  } catch (error) {
+    notify.error(`Could not prepare a new ${collection.name} entry.`, {
+      detail: errorMessage(error),
+      path: collection.dir,
+      source: "Content",
+    });
+    return null;
+  }
+
+  const { createFileIn } = await import("../files/files");
+  const created = await createFileIn({
+    content,
+    dir: collection.dir,
+    ext: collection.ext,
+    source: "Content",
+    suggestedName: "untitled",
+    title: `New ${collection.name} entry`,
+  });
+  if (created === null) {
+    return null;
+  }
+  // The picker's choices just changed; a cached list would keep offering the old set.
+  invalidateReferenceEntries(collection.name);
+  await openEntryEditor(created);
+  return created;
+}
+
+/** The active tab, when it is a content entry — the subject of the document-level verbs. */
+function activeEntryTab(): Tab | null {
+  const tab = activeTab.value as Tab | null;
+  return tab && collectionOfPath(tab.documentPath) ? 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",
+      aiTool: {
+        description:
+          "Create a content entry in one of the project's collections, seeded from that " +
+          "collection's schema defaults, and open it in the entry form.",
+        name: "new_content_entry",
+      },
+      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."),
+      }),
+      category: "File",
+      id: "content.openEntry",
+      level: "project",
+      menus: ["context/file", "palette"],
+      group: "1_file",
+      requires: "an open project",
+      when: (ctx) => ctx.project.open,
+      aiTool: {
+        description:
+          "Open a content entry as a schema-driven form — its collection's fields, with a picker " +
+          "for every reference to another collection.",
+        name: "open_entry_form",
+      },
+      run: async (_ctx, args) => {
+        await openEntryEditor(stringArg("content.openEntry", args, "path"));
+      },
+      title: "Open Entry Form",
+    },
+    {
+      args: argsSchema({
+        draft: booleanProperty(
+          "True marks the open entry a draft; false marks it published. Written as a `draft` " +
+            "field on the entry.",
+        ),
+      }),
+      category: "Document",
+      id: "content.setDraft",
+      level: "document",
+      menus: ["context/tab", "palette"],
+      group: "3_document",
+      requires: "a content entry open",
+      when: (ctx) => ctx.document.open,
+      enablement: () => activeEntryTab() !== null,
+      undo: "document",
+      aiTool: {
+        description:
+          "Mark the open content entry a draft, or published. Studio filters drafts out of its " +
+          "own lists; the build does not exclude them yet.",
+        name: "set_entry_draft",
+      },
+      run: (_ctx, args) => {
+        const tab = activeEntryTab();
+        if (!tab) {
+          throw new Error("content.setDraft: the active document is not a content entry");
+        }
+        setEntryDraft(tab, booleanArg("content.setDraft", args, "draft"));
+      },
+      title: "Set Draft",
+    },
+    {
+      args: argsSchema({
+        include: booleanProperty("True lists entries marked `draft: true` alongside the rest."),
+      }),
+      category: "View",
+      id: "content.setIncludeDrafts",
+      level: "project",
+      menus: ["palette"],
+      group: "2_view",
+      requires: "an open project",
+      when: (ctx) => ctx.project.open,
+      aiTool: {
+        description: "Choose whether draft entries appear in Studio's content listings.",
+        name: "set_including_drafts",
+      },
+      /*
+       * Set the flag, then repaint what reads it.
+       *
+       * The second half is the wiring, and without it this command sets a value nobody looks at
+       * again: a collection grid holds the rows it loaded once, so an author who asks to see their
+       * drafts watches an unchanged table. `draft-state.ts` cannot do it — it is imported BY the
+       * listings and reaching back into the workspace from there is the cycle. The command can,
+       * because a command is exactly the place where "the state changed" becomes "the app changed".
+       */
+      run: async (_ctx, args) => {
+        setIncludeDrafts(booleanArg("content.setIncludeDrafts", args, "include"));
+        await reloadDraftAwareGrids();
+      },
+      title: "Include Drafts",
+    },
+  ];
+}
+
+/** Register the content-entry verbs. */
+export function registerContentCommands(registry: CommandRegistry): void {
+  registry.registerAll(contentCommands());
+}

package/src/content/entry-editor.ts

@@ -0,0 +1,327 @@
+/// <reference lib="dom" />
+/**
+ * The **Entry editor** — a content entry's fields, as a form, in a pane (§7.4, plan §9.2).
+ *
+ * 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.
+ *
+ * This is one editor over `renderForm`, so every improvement to the engine reaches content entries,
+ * settings and the inspector at once — and the `reference` control in particular arrives here for
+ * free, which is what makes `author: { "$ref": "#/content/authors" }` a picker instead of a text
+ * field you have to type an id into.
+ *
+ * **It is an editor of the same tab, not a second document.** Like `settings/settings-document.ts`,
+ * 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.
+ *
+ * **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
+ * touches `content.frontmatter` directly — reading it unconditionally is what made a JSON entry's
+ * form blank, its valid required fields look absent, and every edit vanish at save time.
+ *
+ * **The mode is registered in all three tables.** `commands/context.ts` holds the one map from mode
+ * to editor kind; a mode missing from it does not fail, it silently answers `"canvas"`, and that is
+ * how ⌘V once inserted an element node into `project.json`. `entry` → `entry` → "Entry" is added to
+ * `EDITOR_KIND_BY_MODE`, `EditorKind` and `EDITOR_KIND_LABELS` in the same change as this file.
+ *
+ * @docs studio/projects/content-types
+ */
+
+import { html, nothing, render as litRender } from "lit-html";
+import { activeRegistry } from "../commands/active-registry";
+import { effect, effectScope } from "../reactivity";
+import { projectState } from "../store";
+import { resolveContextPointer } from "../services/context-resolver";
+import { transactDoc } from "../tabs/transact";
+import { renderForm } from "../ui/schema-form";
+import { paneRegion } from "../ui/regions";
+import { activateTab, workspace } from "../workspace/workspace";
+import { commitEntryFields, entryFields, mutateEntryField } from "./entry-fields";
+import { DRAFT_FIELD, DRAFT_MEANING, hasDraftAxis, isDraftEntry } from "./draft-state";
+import { collectionOfPath, missingRequired } from "./entry-model";
+import type { EntryCollection } from "./entry-model";
+import type { JsonSchema, SchemaFormContext } from "../ui/schema-form";
+import type { Tab } from "../tabs/tab";
+import type { CanvasSurface } from "../canvas/canvas-surface";
+import type { JsonValue } from "../types";
+
+/** The `canvasMode` the entry form draws under. */
+export const ENTRY_MODE = "entry";
+
+/** What an entry tab's mode list becomes when the Entry editor opens it: the form leads. */
+const ENTRY_TAB_MODES = [ENTRY_MODE];
+
+// ─── Mounting ────────────────────────────────────────────────────────────────
+
+interface ActiveEntryPane {
+  /** The pane whose stage this form is drawn on. */
+  paneId: string;
+  tabId: string;
+  wrap: HTMLElement;
+  scope: { stop: () => void; run: <T>(fn: () => T) => T | undefined };
+}
+
+/**
+ * The entry form mounted in each pane, keyed by pane id.
+ *
+ * `entry` is one of the kinds the side pane may host, so this singleton was reachable from two
+ * panes at once the day the grid drew a second cell: pane B's mount stopped pane A's effect scope,
+ * leaving a form on screen that no longer tracked its own frontmatter.
+ */
+const _active = new Map<string, ActiveEntryPane>();
+
+/** The form mounted in a pane, or null. */
+function activeIn(paneId: string): ActiveEntryPane | null {
+  return _active.get(paneId) ?? null;
+}
+
+/** Whether this tab's entry form is already mounted in this pane and still in the document. */
+export function entryPaneMounted(paneId: string, tab: Tab): boolean {
+  const panel = activeIn(paneId);
+  return panel !== null && panel.tabId === tab.id && panel.wrap.isConnected;
+}
+
+/** Tear one pane's entry form down (mode change, tab switch, project close). Idempotent. */
+export function detachEntryPane(paneId: string): void {
+  const panel = _active.get(paneId);
+  if (!panel) {
+    return;
+  }
+  panel.scope.stop();
+  _active.delete(paneId);
+}
+
+// ─── Drafts ──────────────────────────────────────────────────────────────────
+
+/**
+ * Set this entry's draft flag. A setter, never a toggle — the pill, the command and the assistant
+ * all reach the same state whatever it was before.
+ *
+ * `draft: false` is written rather than removed. The absence of the key and the value `false` mean
+ * the same thing to a reader, but only one of them survives a glance at the file, and an author who
+ * has explicitly published something should be able to see that they did.
+ */
+export function setEntryDraft(tab: Tab, draft: boolean): void {
+  transactDoc(tab, (t) => mutateEntryField(t, DRAFT_FIELD, draft as JsonValue));
+}
+
+/**
+ * The draft pill for a tab, or `nothing`.
+ *
+ * Drawn on the pane's tab chip (`panels/tab-strip.ts`) rather than only inside the editor, because
+ * the failure this exists to prevent is publishing something you thought was private — and that
+ * mistake is made while looking at a tab, not while looking at a form. It renders for any entry
+ * whose collection declares the field, so "Published" is as visible as "Draft"; a collection with
+ * no draft workflow shows neither.
+ */
+export function entryDraftPill(tab: Tab) {
+  const collection = collectionOfPath(tab.documentPath);
+  const fields = entryFields(tab);
+  if (!collection || !hasDraftAxis(collection.schema, fields)) {
+    return nothing;
+  }
+  const draft = isDraftEntry(fields);
+  return html`<span
+    class=${draft ? "entry-pill entry-pill--draft" : "entry-pill"}
+    title=${draft ? DRAFT_MEANING : "Not marked a draft."}
+    >${draft ? "Draft" : "Published"}</span
+  >`;
+}
+
+// ─── The form ────────────────────────────────────────────────────────────────
+
+/** The form's host context: enum pointers resolve against this project's configuration. */
+function formContext(tab: Tab): SchemaFormContext {
+  return {
+    fieldKeyPrefix: `entry:${tab.id}`,
+    resolvePointer: (pointer, scope) =>
+      resolveContextPointer(pointer, {
+        projectConfig: (projectState?.projectConfig ?? {}) as Record<string, unknown>,
+        scope,
+      }),
+  };
+}
+
+/**
+ * Required fields this entry does not have.
+ *
+ * Deliberately keyed on ABSENCE, not emptiness. A seeded entry's `title: ""` is present and the
+ * author has not done anything wrong yet, so §7.1 says not to paint it red; a required key that is
+ * missing from the file is a fact about the document, and saying so is the whole reason the form
+ * knows the schema.
+ */
+function absentRequiredErrors(
+  collection: EntryCollection,
+  fields: Record<string, unknown>,
+): Record<string, string> {
+  const errors: Record<string, string> = {};
+  for (const field of missingRequired(collection.schema, fields)) {
+    errors[field] = "Required — this entry does not have one.";
+  }
+  return errors;
+}
+
+/** The header: what this is, and whether it is a draft. */
+function headerTpl(tab: Tab, collection: EntryCollection) {
+  const fields = entryFields(tab);
+  const draftAxis = hasDraftAxis(collection.schema, fields);
+  const draft = isDraftEntry(fields);
+  return html`
+    <div class="entry-editor-header">
+      <h3>${tab.documentPath?.split("/").pop() ?? "Untitled"}</h3>
+      <span class="entry-editor-collection">${collection.name}</span>
+      ${
+        draftAxis
+          ? html`
+              <sp-switch
+                size="s"
+                class="entry-draft-switch"
+                ?checked=${draft}
+                title=${DRAFT_MEANING}
+                @change=${(e: Event) => setEntryDraft(tab, (e.target as HTMLInputElement).checked)}
+                >Draft</sp-switch
+              >
+            `
+          : nothing
+      }
+    </div>
+    ${draft ? html`<p class="entry-editor-note">${DRAFT_MEANING}</p>` : nothing}
+  `;
+}
+
+/**
+ * What the editor says when the document is not an entry.
+ *
+ * The mode is reachable from the palette and from `__jxAutomation` on any tab, so this state is
+ * real and must name the reason and the fix rather than drawing an empty form — "no fields" and
+ * "this file belongs to no collection" are different sentences, and only one of them is true here.
+ */
+function notAnEntryTpl(tab: Tab) {
+  return html`
+    <div class="entry-editor-empty">
+      <p>
+        ${tab.documentPath ?? "This document"} is not an entry of any content collection, so there
+        is no schema to draw a form from.
+      </p>
+      <p class="entry-editor-note">
+        A collection is a <code>content</code> entry in <code>project.json</code> whose
+        <code>source</code> directory contains this file and which declares a <code>schema</code>.
+      </p>
+      <sp-action-button
+        size="s"
+        @click=${() => {
+          void activeRegistry()?.run("settings.open", { section: "content" });
+        }}
+        >Content types…</sp-action-button
+      >
+    </div>
+  `;
+}
+
+/**
+ * Mount the entry form into the pane.
+ *
+ * The same non-iframe-editor pattern as the grid, the Library and Project Settings: this owns its
+ * own effect scope from here, so a field commit repaints the form and nothing else — repainting
+ * through the canvas pipeline would remount the document's iframe on every keystroke.
+ */
+export function renderEntryMode(surface: CanvasSurface, tab: Tab): void {
+  const { paneId, wrap: canvasWrap } = surface;
+  if (entryPaneMounted(paneId, tab)) {
+    return;
+  }
+  detachEntryPane(paneId);
+
+  const scope = effectScope();
+  const panel: ActiveEntryPane = { paneId, scope, tabId: tab.id, wrap: canvasWrap };
+  _active.set(paneId, panel);
+
+  const rerender = () => {
+    if (activeIn(paneId) === panel) {
+      draw();
+    }
+  };
+
+  const draw = () => {
+    const collection = collectionOfPath(tab.documentPath);
+    if (!collection) {
+      litRender(
+        html`<div class="entry-editor" data-jx-region=${paneRegion(paneId, "entry")}>
+          ${notAnEntryTpl(tab)}
+        </div>`,
+        canvasWrap,
+      );
+      return;
+    }
+    const fields = entryFields(tab);
+    litRender(
+      html`
+        <div class="entry-editor" data-jx-region=${paneRegion(paneId, "entry")}>
+          ${headerTpl(tab, collection)}
+          <div class="entry-editor-fields" data-jx-region=${paneRegion(paneId, "entry/fields")}>
+            ${renderForm(collection.schema as JsonSchema, fields, {
+              context: formContext(tab),
+              errors: absentRequiredErrors(collection, fields),
+              onChange: (patch) => commitEntryFields(tab, patch),
+              rerender,
+            })}
+          </div>
+        </div>
+      `,
+      canvasWrap,
+    );
+  };
+
+  scope.run(() => {
+    effect(() => {
+      if (activeIn(paneId) !== panel) {
+        return;
+      }
+      // Everything the form draws from: the entry's own fields, and the schema that types them.
+      // BOTH stores are read, because which one holds the fields is `entry-fields.ts`'s answer,
+      // Never this effect's guess. `tab.doc.document` is also the reference every transaction
+      // Replaces, so it is how an undo reaches the form whichever store the edit was in.
+      void tab.doc.document;
+      void tab.doc.content?.frontmatter;
+      void projectState?.projectConfig?.content;
+      draw();
+    });
+  });
+}
+
+// ─── Opening ─────────────────────────────────────────────────────────────────
+
+/**
+ * Open a content entry in its form editor.
+ *
+ * Reveals the tab the file already has rather than building a second one — same id, same history,
+ * same dirty flag — and only then switches the editor, so an author who was editing the body keeps
+ * their undo stack. Returns null when the file could not be opened at all.
+ */
+export async function openEntryEditor(path: string): Promise<Tab | null> {
+  /* Dynamic: `files/files.ts` reaches the platform, the format registry and the packages layer, and
+     a static edge from here would drag all of it into every importer of the content model. */
+  const { openFileInTab } = await import("../files/files");
+  await openFileInTab(path);
+  for (const [id, tab] of workspace.tabs.entries()) {
+    if (tab.documentPath !== path) {
+      continue;
+    }
+    for (const mode of ENTRY_TAB_MODES) {
+      if (!tab.capabilities.modes.includes(mode)) {
+        tab.capabilities.modes.unshift(mode);
+      }
+    }
+    tab.session.ui.canvasMode = ENTRY_MODE;
+    tab.session.ui.preview = false;
+    activateTab(id);
+    return tab as Tab;
+  }
+  return null;
+}