@jxsuite/studio 6.1.1 → 8.0.0

package/src/content/content-collections.ts

@@ -0,0 +1,270 @@
+/**
+ * The collections the Content workspace lists: a built-in **Pages** collection, then every
+ * collection `project.json` declares, in declaration order (`specs/studio.md` §9.1.2, §22.5).
+ *
+ * One answer to "which collection is this file in", and it is `content/collection-match.ts`'s. A
+ * routed file under `pages/` is a page; any other file is in the collection `collectionForFile`
+ * names, or in none. The Library this replaces had a third matcher (`contentTypeFor`, a source
+ * prefix test) and folder categories beside it, and the two disagreed about the same entry; both
+ * are gone, and nothing here guesses from a folder name.
+ *
+ * Pure over the open project's configuration: no DOM, no platform, so the commands that name a
+ * collection can build their `enum` in a bare Bun process.
+ *
+ * @docs studio/projects/browse
+ */
+
+import { isRoutedPageFile } from "@jxsuite/site/routes";
+import { projectState } from "../store";
+import { MEDIA_EXTENSIONS, extensionOf } from "../files/media-types";
+import { collectionForFile } from "./collection-match";
+import type { ContentSectionEntry } from "../types";
+import type { ContentTypeSchema } from "@jxsuite/schema/types";
+
+/**
+ * Collection names whose singular is the word itself. The suffix rules below would make `news` a
+ * `new`, `series` a `sery` and `species` a `specy`, and the result is visible copy ("New new").
+ */
+const INVARIANT_NOUNS = new Set(["data", "media", "metadata", "news", "series", "species"]);
+
+/**
+ * Collections named for the WHOLE rather than its parts: a `menu` holds dishes, a `gallery`
+ * pictures. Their item is "<name> item", the noun English already uses ("menu item", "catalog
+ * item"); "New menu" would promise a second menu.
+ */
+const COLLECTIVE_NOUNS = new Set([
+  "archive",
+  "catalog",
+  "catalogue",
+  "collection",
+  "directory",
+  "faq",
+  "gallery",
+  "inventory",
+  "library",
+  "menu",
+  "portfolio",
+  "showcase",
+]);
+
+/**
+ * A storage name in words, as a person reads it: `project_tag` → "project tag", `service-type` →
+ * "service type", `docsNav` → "docs nav". Lower case; {@link capitalise} makes a heading of it.
+ */
+export function humanName(name: string): string {
+  return name
+    .replaceAll(/[_-]+/g, " ")
+    .replaceAll(/([a-z\d])([A-Z])/g, "$1 $2")
+    .trim()
+    .replaceAll(/\s+/g, " ")
+    .toLowerCase();
+}
+
+/** A collection's item, said in the singular: `recipes` → `recipe`, `stories` → `story`. */
+export function itemNoun(collection: string): string {
+  // Only the last word is a noun to singularise: `post_tags` is a "post tag".
+  // A one-word name keeps its own spelling (`News`); a compound one is said in lower-case words.
+  const words = /[_-]|[a-z\d][A-Z]/.test(collection) ? humanName(collection) : collection;
+  const at = words.lastIndexOf(" ");
+  const last = words.slice(at + 1);
+  if (COLLECTIVE_NOUNS.has(last.toLowerCase())) {
+    return `${words} item`;
+  }
+  return `${words.slice(0, at + 1)}${singular(last)}`;
+}
+
+/** One word in the singular. */
+function singular(collection: string): string {
+  if (INVARIANT_NOUNS.has(collection.toLowerCase())) {
+    return collection;
+  }
+  if (/[^aeiou]ies$/.test(collection)) {
+    return `${collection.slice(0, -3)}y`;
+  }
+  // `classes` → `class`, `boxes` → `box`, `matches` → `match`: the plural added `es`.
+  if (/(?:ss|x|ch|sh|z)es$/.test(collection)) {
+    return collection.slice(0, -2);
+  }
+  // `status`, `campus`, `analysis`, `glass` are already singular.
+  if (/(?:us|is|ss)$/.test(collection)) {
+    return collection;
+  }
+  if (collection.endsWith("s")) {
+    return collection.slice(0, -1);
+  }
+  return collection;
+}
+
+/** A word with its first letter in capitals: `posts` → `Posts`. */
+export function capitalise(word: string): string {
+  return word.charAt(0).toUpperCase() + word.slice(1);
+}
+
+/**
+ * A template or page file's display name, from its file name: `./layouts/post.json` → `Post`,
+ * `./layouts/blog-post.json` → `Blog Post`. The one spelling every surface that names a template
+ * uses, so the header line, the writing banner and the layout picker never disagree.
+ */
+export function templateDisplayName(path: string): string {
+  const base = path.replaceAll("\\", "/").split("/").pop() ?? path;
+  return base
+    .replace(/\.[^.]+$/, "")
+    .replaceAll(/[-_]+/g, " ")
+    .replaceAll(/\b\w/g, (c: string) => c.toUpperCase());
+}
+
+/** The key of the built-in collection every site has: the routed files under `pages/`. */
+export const PAGES_COLLECTION = "pages";
+
+/** One collection, as the Content workspace names it. */
+export interface ContentCollection {
+  /** `pages`, or the collection's name in `project.json`. The value every command names. */
+  key: string;
+  /** What the heading says: "Pages", or the collection's name capitalised. */
+  title: string;
+  /** One of its items, in the singular and lower case: "page", "post", "story". */
+  item: string;
+  /** `pages` for the built-in collection, `collection` for a declared one. */
+  kind: "pages" | "collection";
+  /** True for a collection whose `source` is one file (a CSV catalogue): its entries are rows. */
+  fileBacked: boolean;
+}
+
+/** The declared collections, name → entry, in declaration order. */
+function contentSection(): Record<string, ContentSectionEntry> {
+  /* SAFETY: `content` is the parser extension's section, collection name → entry object; this
+     module reads only the optional `source`, and only to ask whether it names one file. */
+  return (projectState?.projectConfig?.content ?? {}) as Record<string, ContentSectionEntry>;
+}
+
+/** Whether a `source` names a single file rather than a directory. */
+function namesFile(source: string | undefined): boolean {
+  return source !== undefined && /\.[\da-z]+$/i.test(source.replace(/\/+$/, ""));
+}
+
+/** The built-in Pages collection. */
+const PAGES: ContentCollection = {
+  fileBacked: false,
+  item: "page",
+  key: PAGES_COLLECTION,
+  kind: "pages",
+  title: "Pages",
+};
+
+/** Every collection the Content workspace lists: Pages first, then the declared ones. */
+export function contentCollections(): ContentCollection[] {
+  const declared = Object.entries(contentSection()).map(([name, def]): ContentCollection => ({
+    fileBacked: namesFile(def.source),
+    item: itemNoun(name),
+    key: name,
+    kind: "collection",
+    // In words, as the Table names a field: `project_tag` is "Project tag", not "Project_tag".
+    title: capitalise(humanName(name)),
+  }));
+  return [PAGES, ...declared];
+}
+
+/** Every collection key, for a command's `enum`: `pages` first, then the declared names. */
+export function contentCollectionKeys(): string[] {
+  return contentCollections().map((collection) => collection.key);
+}
+
+/**
+ * The project-relative file a file-backed collection's entries are rows of (`./content/p.csv` →
+ * `content/p.csv`), or `null` for a collection whose source is a directory, or none at all.
+ */
+export function collectionSourceFile(key: string): string | null {
+  const source = contentSection()[key]?.source;
+  return source !== undefined && namesFile(source) ? source.replace(/^\.\//, "") : null;
+}
+
+/** The schema a collection declares, file-backed or not, or `null` for none. */
+export function declaredCollectionSchema(key: string): ContentTypeSchema | null {
+  return contentSection()[key]?.schema ?? null;
+}
+
+/** The collection with this key, or `null` when the project declares none by that name. */
+export function contentCollection(key: string): ContentCollection | null {
+  return contentCollections().find((collection) => collection.key === key) ?? null;
+}
+
+/**
+ * The collection a file is in, or `null`.
+ *
+ * Media files are in none: an image beside an entry is the entry's asset, which the Media workspace
+ * lists. A file under `pages/` is a page; any other is `collectionForFile`'s answer.
+ */
+export function collectionKeyOfPath(path: string | null | undefined): string | null {
+  if (!path) {
+    return null;
+  }
+  const normalized = path.replaceAll("\\", "/").replace(/^\.\//, "");
+  if (MEDIA_EXTENSIONS.has(extensionOf(normalized))) {
+    return null;
+  }
+  if (normalized.startsWith("pages/")) {
+    // An underscore-prefixed file or folder is a page directory's private part, not a route.
+    return isRoutedPageFile(normalized) ? PAGES_COLLECTION : null;
+  }
+  return collectionForFile(normalized)?.name ?? null;
+}
+
+/**
+ * Whether an entry is written on the canvas rather than in the form editor.
+ *
+ * An entry with a body (a Markdown file, or any format with prose) is written on the canvas inside
+ * its template's layout (§22.5). A JSON entry IS its fields, with no body to write, and a
+ * file-backed collection's entries are rows: both keep the form-only `entry` editor.
+ */
+export function writesEntryOnCanvas(path: string | null | undefined): boolean {
+  if (!path) {
+    return false;
+  }
+  const match = collectionForFile(path);
+  if (!match || match.fileBacked) {
+    return false;
+  }
+  const ext = extensionOf(path);
+  return ext !== ".json" && ext !== ".csv";
+}
+
+/** Which of the Content workspace's three derived caches a batch of file events can make wrong. */
+export interface ContentCacheDrops {
+  /** The scan the collections are filtered from: only the file SET, so adds, removes and renames. */
+  scan: boolean;
+  /** The pages that say where each collection is published: any write under `pages/`. */
+  pages: boolean;
+  /** The titles and statuses the Collections panel lists: any write to a collection's entry. */
+  entries: boolean;
+}
+
+/**
+ * Which Content caches a file-event batch drops.
+ *
+ * A plain content `change` cannot change which files exist, so it leaves the scan alone; that is
+ * every save, Studio's own echoes included, and dropping the scan on each one blanked the
+ * Collections panel and re-walked the project after every keystroke-and-save. It can still change a
+ * template page's `$paths` (the index) and an entry's title or status (the summaries), so those are
+ * dropped by path.
+ *
+ * @param paths The project-relative paths the batch touched, or `undefined` after a gap, when any
+ *   path may have changed.
+ * @param structural Whether the batch added, removed or renamed anything.
+ */
+export function contentCacheDrops(
+  paths: readonly string[] | undefined,
+  structural: boolean,
+): ContentCacheDrops {
+  if (paths === undefined || structural) {
+    return { entries: true, pages: true, scan: true };
+  }
+  const normalized = paths.map((path) => path.replaceAll("\\", "/").replace(/^\.\//, ""));
+  return {
+    entries: normalized.some((path) => {
+      const key = collectionKeyOfPath(path);
+      return key !== null && key !== PAGES_COLLECTION;
+    }),
+    pages: normalized.some((path) => path.startsWith("pages/")),
+    scan: false,
+  };
+}

package/src/content/draft-state.ts

@@ -20,6 +20,7 @@
 
 import { reactive } from "../reactivity";
 import type { ContentTypeSchema } from "@jxsuite/schema/types";
+import type { EntryFields } from "./entry-fields";
 
 /** The conventional frontmatter boolean that marks an entry a draft (site-architecture.md §7.6). */
 export const DRAFT_FIELD = "draft";
@@ -44,7 +45,7 @@ export const DRAFT_MEANING =
  * Takes the entry's FIELDS, whichever record they live in — `content/entry-fields.ts` answers that,
  * because a JSON collection's entry has no frontmatter and its `draft` key is on the document.
  */
-export function isDraftEntry(fields: Record<string, unknown> | null | undefined): boolean {
+export function isDraftEntry(fields: EntryFields | null | undefined): boolean {
   return fields?.[DRAFT_FIELD] === true;
 }
 
@@ -63,7 +64,7 @@ export function schemaDeclaresDraft(schema: ContentTypeSchema | null | undefined
  */
 export function hasDraftAxis(
   schema: ContentTypeSchema | null | undefined,
-  fields?: Record<string, unknown> | null,
+  fields?: EntryFields | null,
 ): boolean {
   return schemaDeclaresDraft(schema) || isDraftEntry(fields);
 }
@@ -100,7 +101,7 @@ export function setIncludeDrafts(include: boolean): void {
  */
 export function applyDraftFilter<T>(
   items: readonly T[],
-  fieldsOf: (item: T) => Record<string, unknown> | null | undefined,
+  fieldsOf: (item: T) => EntryFields | null | undefined,
   includeDrafts: boolean,
 ): readonly T[] {
   return includeDrafts ? items : items.filter((item) => !isDraftEntry(fieldsOf(item)));

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,47 +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 { LOCALE_PLACEHOLDER, collectionForDirectory } from "./collection-match";
-import { openEntryEditor, setEntryDraft } from "./entry-editor";
+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 { 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",
+  });
 }
 
 /**
@@ -126,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.
    */
@@ -161,45 +178,19 @@ 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;
 }
 
 /** 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;
+  const tab = activeTab.value;
   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",
-      /* 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."),
@@ -212,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({