@jxsuite/studio 6.1.1 → 8.0.0

package/src/content/writing-banner.ts

@@ -0,0 +1,177 @@
+/// <reference lib="dom" />
+/**
+ * The writing-mode banner: what the canvas says while a collection entry is written inside its
+ * template's layout (`specs/studio.md` §22.5).
+ *
+ * "Writing mode: text and media are editable, the layout is locked", with **Edit the <item>
+ * template in Design**. The template it opens is the collection's template PAGE when the project
+ * has one (the page whose `$paths.contentType` names the collection,
+ * `content/collection-pages.ts`), because that is the page that decides what an entry looks like on
+ * the site; with no such page it is the layout the entry is drawn in. Opening either activates it,
+ * and activating a page or a layout enters Design (§22.1).
+ *
+ * One banner per pane, mounted into the host the canvas stage draws above Edit's column
+ * (`surfaces/canvas-stage.json`'s `writing-banner`); `canvas/canvas-render.ts` hands the host over
+ * and repaints it. It is the one band Edit draws over a document: an ordinary page opens at the top
+ * with nothing above it (studio.md §4.2).
+ *
+ * @docs studio/projects/content-types
+ */
+
+import { isString } from "@jxsuite/schema/guards";
+import { paneRegion } from "../ui/regions";
+import { workspace } from "../workspace/workspace";
+import { collectionForFile } from "./collection-match";
+import { contentCollection, templateDisplayName } from "./content-collections";
+import {
+  entryLayoutPath,
+  entryLocale,
+  onCollectionPagesRead,
+  peekCollectionPage,
+} from "./collection-pages";
+import { mountWritingBannerSurface } from "../surfaces/writing-banner";
+import type { Tab } from "../tabs/tab";
+import type { WritingBannerHandle, WritingBannerView } from "../surfaces/writing-banner";
+
+/** The sentence the banner always says. */
+export const WRITING_MODE_TEXT = "Writing mode: text and media are editable, the layout is locked";
+
+/** Where the banner's button goes, and what it is called. `null` when there is nothing to open. */
+export interface BannerTarget {
+  path: string;
+  /** The button's text, as `WritingBannerView.actionLabel` draws it. */
+  actionLabel: string;
+}
+
+/**
+ * What an entry's banner opens: its collection's page, else the layout it is drawn in.
+ *
+ * Each label names the file it opens. The collection's page is called what the Content home's
+ * header line calls it ("Design the post page"), so the two surfaces that reach it agree; a layout
+ * is a template everywhere in Studio, and is called one by its own name.
+ */
+export function bannerTarget(tab: Tab): BannerTarget | null {
+  const match = collectionForFile(tab.documentPath);
+  if (!match) {
+    return null;
+  }
+  const item = contentCollection(match.name)?.item ?? "entry";
+  const page = peekCollectionPage(match.name, entryLocale(tab.documentPath));
+  if (page) {
+    return { actionLabel: `Design the ${item} page`, path: page.path };
+  }
+  const own = tab.doc.document.$layout ?? tab.doc.content.frontmatter.$layout;
+  const layout = entryLayoutPath(isString(own) || own === false ? own : undefined, page ?? null);
+  if (!layout) {
+    return null;
+  }
+  return {
+    actionLabel: `Edit the ${templateDisplayName(layout)} template in Design`,
+    path: layout.replace(/^\.\//, ""),
+  };
+}
+
+/** What the banner over `tab` in `paneId` draws. */
+export function writingBannerView(paneId: string, tab: Tab): WritingBannerView {
+  const target = bannerTarget(tab);
+  return {
+    actionLabel: target?.actionLabel ?? "",
+    actionState: target ? "shown" : "hidden",
+    region: paneRegion(paneId, "writing-banner"),
+    text: WRITING_MODE_TEXT,
+  };
+}
+
+// ─── Mounting ────────────────────────────────────────────────────────────────
+
+interface StandingBanner {
+  host: HTMLElement;
+  handle: WritingBannerHandle;
+  /** The tab the banner was last drawn for: what its button opens the template of. */
+  tabId: string | null;
+}
+
+const _banners = new Map<string, StandingBanner>();
+let _unlisten: (() => void) | null = null;
+
+/** Open the template of the entry a pane's banner is over. */
+async function openTemplate(paneId: string): Promise<void> {
+  const tabId = _banners.get(paneId)?.tabId;
+  const tab = tabId ? workspace.tabs.get(tabId) : undefined;
+  const target = tab ? bannerTarget(tab) : null;
+  if (!target) {
+    return;
+  }
+  const { openFileInTab } = await import("../files/files");
+  await openFileInTab(target.path);
+}
+
+/** Repaint every banner: the collection pages it names its button from have just been read. */
+function repaintAll(): void {
+  for (const [paneId, banner] of _banners) {
+    const tab = banner.tabId ? workspace.tabs.get(banner.tabId) : undefined;
+    if (tab) {
+      banner.handle.update(writingBannerView(paneId, tab));
+    }
+  }
+}
+
+/**
+ * Take a pane's banner host, or let it go (`null`).
+ *
+ * The stage announces the host when it draws the `writing` or `banner` lead; the same host comes
+ * back on every repaint that keeps that lead, so a second announcement of it changes nothing.
+ */
+export function attachWritingBanner(paneId: string, host: HTMLElement | null): void {
+  const held = _banners.get(paneId);
+  if (held?.host === host) {
+    return;
+  }
+  if (held) {
+    held.handle.dispose();
+    _banners.delete(paneId);
+  }
+  if (!host) {
+    return;
+  }
+  _unlisten ??= onCollectionPagesRead(repaintAll);
+  const handle = mountWritingBannerSurface(
+    host,
+    {
+      actionLabel: "",
+      actionState: "hidden",
+      region: paneRegion(paneId, "writing-banner"),
+      text: WRITING_MODE_TEXT,
+    },
+    {
+      openTemplate: () => {
+        void openTemplate(paneId);
+      },
+    },
+  );
+  _banners.set(paneId, { handle, host, tabId: null });
+}
+
+/** Draw a pane's banner for the entry it is over. A pane with no banner host is left alone. */
+export function renderWritingBanner(paneId: string, tab: Tab): void {
+  const banner = _banners.get(paneId);
+  if (!banner) {
+    return;
+  }
+  banner.tabId = tab.id;
+  banner.handle.update(writingBannerView(paneId, tab));
+}
+
+/** Take a pane's banner down (its lead went away, or the pane did). Idempotent. */
+export function detachWritingBanner(paneId: string): void {
+  attachWritingBanner(paneId, null);
+}
+
+/** Take every banner down — tests. */
+export function resetWritingBanners(): void {
+  for (const paneId of _banners.keys()) {
+    detachWritingBanner(paneId);
+  }
+  _unlisten?.();
+  _unlisten = null;
+}

package/src/create/add-new-commands.ts

@@ -0,0 +1,185 @@
+/**
+ * `file.new`: Add new, as a command record (`specs/studio.md` §9.1.1).
+ *
+ * One record, four doors: the palette, the Command Bar's overflow, the chords, and the assistant.
+ * The Site panel's **+** and the Content home's **New** run it too, so there is one way in and
+ * every surface is a rendering of it.
+ *
+ * **Two behaviours, chosen by the arguments.** With a `name`, it creates — kind, name and options
+ * through `deriveCreation`, refused by throwing the sentence the dialog would print, written by the
+ * flow's one write path — and opens nothing modal. Without one, it OPENS the dialog on the kind
+ * asked for and returns at once, never awaiting it: a `run` that waits on a person is the second
+ * deletion rule of `studio-ui-guidelines.md` §12.4, and returning is what keeps this record a tool.
+ * The model is told as much in the description, and the report says which of the two happened.
+ *
+ * **The chords.** `⌘N` where the host owns it — the desktop app — and `⌘⌥N` everywhere, because a
+ * browser keeps `⌘N` for a new window and never delivers it to the page.
+ *
+ * DOM-free at import: the flow is loaded on the first run, so `commands/app-commands.ts` can list
+ * this record in a bare Bun process.
+ *
+ * @docs studio/projects/pages-layouts-components
+ */
+
+import {
+  argsSchema,
+  derivedEnumProperty,
+  enumArg,
+  enumProperty,
+  optionalStringArg,
+  stringProperty,
+} from "../commands/command-args";
+import { entryCollections } from "../content/entry-model";
+import { CREATION_KINDS } from "./add-new";
+import type { CreationKind } from "./add-new";
+import type { AddNewRequest, AddNewResult } from "./add-new-flow";
+import type { CommandArgValues } from "../commands/command-args";
+import type { AiToolReport, AnyCommand, CommandRegistry } from "../commands/registry";
+
+/** The id, which the Site panel and the Content home run. */
+export const FILE_NEW = "file.new";
+
+/** What one run did: a creation, or the dialog it opened instead. */
+interface LastRun {
+  created: AddNewResult | null;
+  opened: CreationKind | null;
+}
+
+/** The last run, for `report`, which reads module state rather than an injected dep. */
+let _lastRun: LastRun = { created: null, opened: null };
+
+/** The arguments as a request, each one read with the reader its schema names. */
+function requestOf(args: CommandArgValues): AddNewRequest {
+  const request: AddNewRequest = {};
+  if (args.kind !== undefined) {
+    request.kind = enumArg(FILE_NEW, args, "kind", CREATION_KINDS);
+  }
+  const name = optionalStringArg(FILE_NEW, args, "name");
+  if (name !== undefined) {
+    request.name = name;
+  }
+  const collection = optionalStringArg(FILE_NEW, args, "collection");
+  if (collection !== undefined) {
+    request.collection = collection;
+  }
+  const locale = optionalStringArg(FILE_NEW, args, "locale");
+  if (locale !== undefined) {
+    request.locale = locale;
+  }
+  const template = optionalStringArg(FILE_NEW, args, "template");
+  if (template !== undefined) {
+    request.template = template;
+  }
+  return request;
+}
+
+/** The sentence the model reads after a run. */
+function reportFor(): AiToolReport {
+  const { created, opened } = _lastRun;
+  if (created) {
+    return { summary: describe(created), wrote: created.wrote };
+  }
+  return {
+    summary:
+      `Opened Add new on ${opened ?? "page"} for the person; nothing is created until they ` +
+      "confirm. Pass a name to create without the dialog.",
+    wrote: [],
+  };
+}
+
+/** One sentence naming what a creation made. */
+export function describe(result: AddNewResult): string {
+  switch (result.kind) {
+    case "page": {
+      return `Created the page ${result.path}${result.route ? `, which opens at ${result.route}` : ""}, and opened it in Design.`;
+    }
+    case "component": {
+      return `Created <${result.tag ?? ""}> in ${result.path}; it is listed under Components in the Site panel and open in Design.`;
+    }
+    case "template": {
+      return `Created the template ${result.path} and opened it in Design.`;
+    }
+    case "entry": {
+      return `Created the entry ${result.path} and opened it.`;
+    }
+    case "collection": {
+      return `Created the ${result.path.replace(/^content\//, "")} collection, writing ${result.wrote.join(", ")}.`;
+    }
+    default: {
+      return `Uploaded ${result.wrote.length === 1 ? "1 file" : `${result.wrote.length} files`} to public/media/.`;
+    }
+  }
+}
+
+/** The `file.new` record. */
+export function addNewCommands(): AnyCommand[] {
+  return [
+    {
+      aiTool: {
+        description:
+          "Create a page, collection, template, component or collection entry, the way Add new does: " +
+          "pass kind and name and it is written and opened, with the path derived from the name " +
+          "(pages/<slug>.json, layouts/<slug>.json, components/<tag>.json, a content/<name>/ " +
+          "collection). Without a name it only opens the Add new dialog for the person.",
+        name: "add_new",
+        report: () => reportFor(),
+      },
+      args: argsSchema(
+        {
+          collection: derivedEnumProperty(
+            () => entryCollections().map((collection) => collection.name),
+            "For an entry: the content collection it is created in.",
+          ),
+          kind: enumProperty(
+            CREATION_KINDS,
+            "What to create: page, collection, template, component, media (an upload) or entry.",
+          ),
+          locale: stringProperty(
+            "For a page or an entry of a localized collection: the language it is written in, one " +
+              "of the project's i18n locales such as fr-CA. A page in another language is saved in " +
+              "that language's folder and opens under its URL prefix.",
+          ),
+          name: stringProperty(
+            "The name. A page's URL, a template's file and a component's tag are derived from it. " +
+              "Omit it to open the Add new dialog instead of creating.",
+          ),
+          template: stringProperty(
+            "The template to start from: a layout such as base or layouts/base.json, article for a " +
+              "Markdown page, or blank for none. A collection uses it for its own page; a template " +
+              "is wrapped in it.",
+          ),
+        },
+        [],
+      ),
+      category: "File",
+      group: "1_file",
+      icon: "plus",
+      id: FILE_NEW,
+      keybinding: ["mod+n", "mod+alt+n"],
+      level: "project",
+      menus: ["commandbar/overflow", "palette"],
+      requires: "an open project",
+      run: async (_ctx, args) => {
+        const request = requestOf(args);
+        const flow = await import("./add-new-flow");
+        if (request.name !== undefined) {
+          _lastRun = { created: null, opened: null };
+          const created = await flow.createDirect({ ...request, name: request.name });
+          _lastRun = { created, opened: null };
+          return;
+        }
+        _lastRun = { created: null, opened: request.kind ?? "page" };
+        // Opened, never awaited: the dialog belongs to the person (studio-ui-guidelines.md §12.4).
+        void flow.openAddNew(request);
+      },
+      title: "Add New…",
+      undo: "none",
+      when: (ctx) => ctx.project.open,
+    },
+  ];
+}
+
+/** Register `file.new`. */
+export function registerAddNewCommands(registry: CommandRegistry): void {
+  registry.registerAll(addNewCommands());
+}