@jxsuite/studio 2.0.0 → 2.1.0

package/src/content/entry-fields.ts

@@ -0,0 +1,116 @@
+/**
+ * **Where a content entry's fields live**, and the one mutation that writes them.
+ *
+ * A collection has two storage shapes and exactly one editor, so the question "what record am I
+ * editing?" has to be answered once, here, rather than assumed at every read site.
+ *
+ * - A **markdown** entry (or any file a format class parsed) is a frontmatter block plus a body. Its
+ *   fields are `tab.doc.content.frontmatter`; `tab.doc.document` is the prose.
+ * - A **JSON** entry (site-architecture.md §6.2's native collection shape) has no frontmatter block
+ *   to split off. `files/files.ts` parses it straight into `tab.doc.document`, and
+ *   `files/file-ops.ts` writes that object back as the whole file. Its fields ARE the document.
+ *
+ * The Entry editor read `content.frontmatter` unconditionally. For a JSON entry that record is `{}`
+ * — so the form drew blank rows for an entry full of data, `absentRequiredErrors` accused a valid
+ * entry of missing its required fields, and every keystroke was committed to a record that
+ * `serializeDocument` never writes: the edit marked the tab dirty, survived undo, and was discarded
+ * by ⌘S under a "Saved" toast. Three symptoms, one wrong assumption about storage.
+ *
+ * **The discriminator is the serializer's own ladder, not a guess about the extension.**
+ * `serializeDocument` writes `JSON.stringify(tab.doc.document)` for exactly one kind of tab: no
+ * format class claimed it (`sourceFormat === null`) and it is not a content-mode document. Those
+ * are the two reads {@link fieldsAreDocument} makes, so "which record does the form edit" and
+ * "which record does save write" cannot drift apart — and if a project ever registers a format
+ * class for `.json`, both answers move together to frontmatter.
+ *
+ * Both shapes mutate with the same semantics — `undefined`, `null` and `""` remove the key, every
+ * other value is written — so an author cannot tell from the form's behaviour which one they are
+ * editing. That is the point.
+ */
+
+import { cloneValue } from "@jxsuite/collab/ops";
+import { recordDocOp } from "../tabs/patch-ops";
+import { mutateUpdateFrontmatter, transactDoc } from "../tabs/transact";
+import type { Tab } from "../tabs/tab";
+import type { JsonValue } from "../types";
+
+/**
+ * Whether this tab's entry fields are the document itself rather than a frontmatter block.
+ *
+ * Mirrors `files/file-ops.ts`'s `serializeDocument` fall-through: a tab with no serializing format
+ * and no content mode round-trips as raw JSON, so anything not in `tab.doc.document` is not saved.
+ *
+ * Deliberately NOT exported. The answer is only ever useful as the record it selects, and a second
+ * caller branching on it would be the beginning of the fork this module exists to prevent —
+ * {@link entryFields} and {@link mutateEntryField} are the whole interface.
+ */
+function fieldsAreDocument(tab: Tab): boolean {
+  return tab.doc.sourceFormat == null && tab.doc.mode !== "content";
+}
+
+/**
+ * The record this entry's fields live in — the one the form draws, validates and repaints from.
+ *
+ * Returned live, not copied: the caller reads it during a render that is already tracking the
+ * reactive tab, and a copy would break that. It is also the identity a caller can compare against
+ * `tab.doc.document` to see which store answered.
+ */
+export function entryFields(tab: Tab): Record<string, unknown> {
+  return fieldsAreDocument(tab)
+    ? (tab.doc.document as unknown as Record<string, unknown>)
+    : (tab.doc.content?.frontmatter ?? {});
+}
+
+/**
+ * Set one document-root key, recording the forward/inverse pair history and the collab bridge
+ * replay from. The same shape `mutateUpdateFrontmatter` records for a frontmatter key, against the
+ * other store — a JSON entry's field change is a genuine document op, so unlike a frontmatter op it
+ * also reaches a co-editor.
+ *
+ * No canvas patch op: a JSON entry has no rendered node for the key, and an unrecorded patch batch
+ * is already the "not surgically patchable, fall back" signal `transactDoc` reads.
+ */
+function mutateDocumentField(tab: Tab, field: string, value?: JsonValue): void {
+  const doc = tab.doc.document as unknown as Record<string, unknown>;
+  const before = Object.hasOwn(doc, field) ? cloneValue(doc[field]) : undefined;
+  const deletes = value === undefined || value === null || value === "";
+  if (deletes) {
+    delete doc[field];
+  } else {
+    doc[field] = value;
+  }
+  const after = deletes ? undefined : cloneValue(value);
+  recordDocOp({
+    forward: { key: field, op: "set-key", path: [], value: after },
+    inverse: { key: field, op: "set-key", path: [], value: before },
+  });
+  tab.doc.dirty = true;
+}
+
+/**
+ * Set one entry field, in whichever record this entry keeps its fields in.
+ *
+ * A mutation, not a transaction: callers wrap it in `transactDoc` so a multi-key change is one undo
+ * step.
+ */
+export function mutateEntryField(tab: Tab, field: string, value?: JsonValue): void {
+  if (fieldsAreDocument(tab)) {
+    mutateDocumentField(tab, field, value);
+  } else {
+    mutateUpdateFrontmatter(tab, field, value);
+  }
+}
+
+/**
+ * Commit a form patch onto this entry's fields, in ONE transaction.
+ *
+ * `renderForm` emits single-key patches today, but committing per key would put a multi-key patch
+ * 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, unknown>): void {
+  transactDoc(tab, (t) => {
+    for (const [field, value] of Object.entries(patch)) {
+      mutateEntryField(t, field, value as JsonValue);
+    }
+  });
+}

package/src/content/entry-model.ts

@@ -0,0 +1,175 @@
+/**
+ * The content-entry model — which collection an entry belongs to, and what a NEW one contains. Pure
+ * over its inputs (the project config it reads, the schema it is handed), so the seeding rules can
+ * be asserted without a DOM, a platform or a tab.
+ *
+ * **Two facts this module exists to stop being restated.**
+ *
+ * 1. **A new entry is seeded, not blank.** `library-pane.ts`'s collection branch created the file
+ *    through the shared creation flow with no extension and no body, so a new `blog` entry landed
+ *    as `content/blog/untitled` — no `.md`, therefore matched by no format, therefore not an entry
+ *    of the collection it was created in, and its required fields were absent rather than empty.
+ *    {@link seedEntry} answers with the schema's own defaults, and every REQUIRED property that
+ *    declares none gets a typed empty, because "present and blank" is a valid entry the author can
+ *    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.
+ *
+ * **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
+ * ask what a draft is — the reverse edge would be a cycle, and `import/no-cycle` is an error here.
+ */
+
+import { collectionInfo } from "../grid/sources/content-source";
+import { projectState } from "../store";
+import { findContentTypeSchema } from "../utils/studio-utils";
+import type { ContentSectionEntry } from "../types";
+import type { ContentTypeSchema, ContentTypeSchemaField } from "@jxsuite/schema/types";
+
+// ─── Collections ─────────────────────────────────────────────────────────────
+
+/** One content collection, as the entry surfaces need it. */
+export interface EntryCollection {
+  name: string;
+  /** Source directory, project-relative and without a trailing slash. */
+  dir: string;
+  /** The extension a new entry of this collection is written with (`.md`, `.json`, …). */
+  ext: string;
+  schema: ContentTypeSchema | null;
+  def: ContentSectionEntry;
+}
+
+/** Every content type the project declares, in declaration order. */
+export function collectionNames(): string[] {
+  return Object.keys((projectState?.projectConfig?.content ?? {}) as Record<string, unknown>);
+}
+
+/**
+ * The collection named `name`, or null when the project declares no such directory-backed type.
+ *
+ * A collection whose `source` names a FILE (a CSV catalogue) has no per-entry files, so it has no
+ * entry editor and no New Entry — `collectionInfo` still answers for it, and this rejects it here
+ * rather than letting a caller compose `products/catalog.csv/untitled.csv`.
+ */
+export function entryCollection(name: string): EntryCollection | null {
+  const info = collectionInfo(name);
+  if (!info) {
+    return null;
+  }
+  if (/\.[a-z\d]+$/i.test(info.dir)) {
+    return null;
+  }
+  return {
+    def: info.def,
+    dir: info.dir,
+    ext: info.ext,
+    name: info.name,
+    schema: info.def.schema ?? null,
+  };
+}
+
+/** The collections a New Entry can be created in — directory-backed types only. */
+export function entryCollections(): EntryCollection[] {
+  return collectionNames()
+    .map((name) => entryCollection(name))
+    .filter((collection): collection is EntryCollection => collection !== null);
+}
+
+/**
+ * The collection a document path belongs to, or null.
+ *
+ * Delegates to `findContentTypeSchema`, which is the matcher the frontmatter surfaces already use —
+ * including its Windows backslash normalisation and its file-source (CSV) branch. A path that
+ * matches a type with no `schema` is NOT a match there, and that is the right answer here too: an
+ * entry editor over a collection that declares no shape has no form to draw.
+ */
+export function collectionOfPath(path: string | null): EntryCollection | null {
+  const matched = findContentTypeSchema(path ?? null, projectState?.projectConfig);
+  return matched ? entryCollection(matched.name) : null;
+}
+
+// ─── Seeding a new entry ─────────────────────────────────────────────────────
+
+/** Deep copy of a schema `default`, so two entries seeded from one schema never share an object. */
+function cloneDefault(value: unknown): unknown {
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+  // oxlint-disable-next-line unicorn/prefer-structured-clone
+  return JSON.parse(JSON.stringify(value)) as unknown;
+}
+
+/**
+ * The empty value of a declared type — what a REQUIRED property with no `default` is seeded with.
+ *
+ * A reference (`$ref` to another collection) seeds as `""`: it is required, so the key must exist,
+ * and picking an arbitrary entry of the target collection on the author's behalf would be inventing
+ * a relationship they never stated.
+ */
+function emptyForField(field: ContentTypeSchemaField): unknown {
+  if (typeof field.$ref === "string") {
+    return "";
+  }
+  switch (field.type) {
+    case "boolean": {
+      return false;
+    }
+    case "integer":
+    case "number": {
+      return 0;
+    }
+    case "array": {
+      return [];
+    }
+    case "object": {
+      return seedEntry(field as ContentTypeSchema);
+    }
+    default: {
+      return "";
+    }
+  }
+}
+
+/**
+ * The frontmatter a new entry of this schema starts life with.
+ *
+ * Two rules, and nothing else:
+ *
+ * - A property that declares a `default` gets it (cloned);
+ * - A property listed in `required` that declares no default gets its type's empty value.
+ *
+ * An optional property with no default is **omitted**. Seeding every declared field would write the
+ * author's file full of keys they never asked for, and "the schema mentions it" is not a reason for
+ * it to exist on disk — the form still draws a row for it, because the form draws the SCHEMA.
+ */
+export function seedEntry(schema: ContentTypeSchema | null | undefined): Record<string, unknown> {
+  const properties = schema?.properties;
+  if (!properties) {
+    return {};
+  }
+  const required = new Set(Array.isArray(schema?.required) ? schema.required : []);
+  const seed: Record<string, unknown> = {};
+  for (const [name, field] of Object.entries(properties)) {
+    if (field.default !== undefined) {
+      seed[name] = cloneDefault(field.default);
+    } else if (required.has(name)) {
+      seed[name] = emptyForField(field);
+    }
+  }
+  return seed;
+}
+
+/**
+ * Required properties this record leaves absent — what a caller checks before claiming an entry is
+ * valid. `seedEntry`'s whole promise is that this is empty for a freshly seeded entry.
+ */
+export function missingRequired(
+  schema: ContentTypeSchema | null | undefined,
+  value: Record<string, unknown>,
+): string[] {
+  const required = Array.isArray(schema?.required) ? schema.required : [];
+  return required.filter((name) => value[name] === undefined);
+}

package/src/editor/canvas-context-menu.ts

@@ -2,9 +2,13 @@
 /**
  * Parent-realm adapter for canvas right-clicks: the iframe suppresses the browser menu and posts
  * `contextMenu` with the nearest element path + iframe-viewport coords; the host converts to
- * parent-viewport coords and calls this handler, which shows the Jx element context menu (copy /
- * paste / insert before/after / convert / delete…). Replaces the legacy panel-events canvas
- * contextmenu handler that died with the in-parent <div> canvas.
+ * parent-viewport coords and calls this handler, which shows the Jx element context menu. Replaces
+ * the legacy panel-events canvas contextmenu handler that died with the in-parent <div> canvas.
+ *
+ * The canvas menu IS the `context/element` placement — this adapter contributes coordinates and the
+ * component-navigation hook, and never a list of verbs. Which rows appear, what they are called,
+ * whether they are enabled and what chord they teach all come from the registry
+ * (`context-menu.ts`).
  */
 
 import { dismissContextMenu, showContextMenu } from "./context-menu";
@@ -14,12 +18,14 @@ import type { CanvasContextMenuHandler } from "../canvas/iframe-host";
 import type { JxPath } from "../state";
 
 /**
- * Build the handler with its studio-owned dependency (component navigation), mirroring the other
- * host DI factories.
+ * Build the handler.
+ *
+ * It took a `navigateToComponent` dep, threaded into the menu as a per-target `onEditComponent`
+ * hook. "Edit Component" is `panels/block-action-bar.ts`'s record now and navigates through the
+ * same function this host was handing over, so the dep became a second way to say one thing — and a
+ * component right-clicked from a host that forgot to pass it showed neither Edit nor Convert.
  */
-export function makeCanvasContextMenuHandler(deps: {
-  navigateToComponent: (path: string) => void | Promise<void>;
-}): CanvasContextMenuHandler {
+export function makeCanvasContextMenuHandler(): CanvasContextMenuHandler {
   return {
     dismiss: () => dismissContextMenu(),
     show: ({ path, clientX, clientY }) => {
@@ -32,9 +38,9 @@ export function makeCanvasContextMenuHandler(deps: {
       // ShowContextMenu reads only preventDefault/clientX/clientY from the event, so a synthetic
       // MouseEvent carries the converted coords safely.
       const evt = new MouseEvent("contextmenu", { clientX, clientY });
-      showContextMenu(evt, bubbled, {
-        onEditComponent: (p) => void deps.navigateToComponent(p),
-      });
+      // No `onEditComponent` hook: "Edit Component" is `block-action-bar.ts`'s record now, and it
+      // Navigates through the same `navigateToComponent` this host was handing over.
+      showContextMenu(evt, bubbled);
     },
   };
 }

package/src/editor/canvas-slash-bridge.ts

@@ -14,8 +14,15 @@ import type { CanvasSlashHandler } from "../canvas/iframe-host";
 export const canvasSlashHandler: CanvasSlashHandler = {
   dismiss: () => dismissSlashMenu(),
   nav: (key) => handleSlashMenuKey(key),
-  // No filter input: the author keeps typing in the iframe contenteditable and the engine re-posts
-  // SlashShow with the updated filter.
-  show: ({ rect, filter, onSelect, onDismiss }) =>
-    showSlashMenuAtRect(rect, filter, { onDismiss, onSelect }),
+  /* The filter field appears only when the frame asks for it, and only the frame knows why the menu
+     opened. Typing "/" needs none — the author keeps typing into the iframe's contenteditable and
+     the engine re-posts `slashShow` with the updated filter. A menu opened BY NAME
+     (`insert.openSlashMenu`) has no "/…" run to type into, so without the field the only way past
+     fifteen blocks is scrolling. */
+  show: ({ rect, filter, showFilter, onSelect, onDismiss }) =>
+    showSlashMenuAtRect(rect, filter, {
+      onDismiss,
+      onSelect,
+      ...(showFilter === true ? { showFilter: true } : {}),
+    }),
 };