@backmatter/next 0.0.21 → 0.0.23

package/src/site-editor.tsx

@@ -0,0 +1,353 @@
+// packages/next/src/site-editor.tsx
+"use client";
+
+import { usePathname, useRouter } from "next/navigation";
+import { startTransition, useEffect, useRef, useState, type CSSProperties, type ReactNode } from "react";
+import { subscribeSiteDoc } from "./site-doc-bridge";
+import { readSiteDoc, sameSiteDoc, type SiteDocRef } from "./site-doc";
+
+function useSiteDoc(): SiteDocRef | null {
+  const pathname = usePathname();
+  const [doc, setDoc] = useState<SiteDocRef | null>(null);
+
+  useEffect(() => {
+    const apply = (next: SiteDocRef | null) => {
+      setDoc((prev) => (sameSiteDoc(prev, next) ? prev : next));
+    };
+    apply(readSiteDoc());
+    const stop = subscribeSiteDoc(apply);
+    const observer = new MutationObserver(() => apply(readSiteDoc()));
+    observer.observe(document.body, {
+      subtree: true,
+      childList: true,
+      attributes: true,
+      attributeFilter: ["data-locale", "data-type", "data-slug", "data-workspace"],
+    });
+    return () => {
+      stop();
+      observer.disconnect();
+    };
+  }, [pathname]);
+
+  return doc;
+}
+
+/** Default route the host mounts `@backmatter/studio` on. */
+export const DEFAULT_STUDIO_PATH = "/backmatter";
+
+/**
+ * The panels are frames of the Studio mounted on this same origin. Same
+ * origin means the site session cookie is first-party and postMessage needs
+ * no foreign origin.
+ */
+function studioBase(studioPath: string): string {
+  if (typeof location === "undefined") return "";
+  return `${location.origin}${studioPath.replace(/\/+$/, "")}`;
+}
+
+export function SiteChrome({
+  branch,
+  tree,
+  exiting,
+  onExit,
+  studioPath = DEFAULT_STUDIO_PATH,
+}: {
+  branch?: string;
+  tree?: string;
+  exiting?: boolean;
+  onExit: () => void;
+  /** Where `@backmatter/studio` is mounted on this site. */
+  studioPath?: string;
+}) {
+  const router = useRouter();
+  const doc = useSiteDoc();
+  const [editorMounted, setEditorMounted] = useState(false);
+  const [editorOpen, setEditorOpen] = useState(false);
+  const [chatMounted, setChatMounted] = useState(false);
+  const [chatOpen, setChatOpen] = useState(false);
+  const [publishOpen, setPublishOpen] = useState(false);
+  const [changeCount, setChangeCount] = useState(0);
+  // Set in an effect so SSR and the first client render agree.
+  const [base, setBase] = useState("");
+  const origin = typeof location === "undefined" ? "" : location.origin;
+  const editorFrame = useRef<HTMLIFrameElement>(null);
+
+  useEffect(() => {
+    setBase(studioBase(studioPath));
+  }, [studioPath]);
+
+  useEffect(() => {
+    function onKey(event: KeyboardEvent) {
+      if (!(event.metaKey || event.ctrlKey) || event.key.toLowerCase() !== "j") return;
+      event.preventDefault();
+      setChatMounted(true);
+      setChatOpen((open) => !open);
+    }
+    document.addEventListener("keydown", onKey, true);
+    return () => document.removeEventListener("keydown", onKey, true);
+  }, []);
+
+  useEffect(() => {
+    function onMessage(event: MessageEvent) {
+      if (event.origin !== origin) return;
+      const data = event.data as {
+        type?: string;
+        changeCount?: number;
+        key?: string;
+        metaKey?: boolean;
+        ctrlKey?: boolean;
+      };
+      if (data?.type === "backmatter:git" && typeof data.changeCount === "number") {
+        setChangeCount(data.changeCount);
+      }
+      if (
+        data?.type === "backmatter:hotkey" &&
+        data.key?.toLowerCase() === "j" &&
+        (data.metaKey || data.ctrlKey)
+      ) {
+        setChatMounted(true);
+        setChatOpen((open) => !open);
+      }
+      if (data?.type === "backmatter:published") {
+        setPublishOpen(false);
+        setChangeCount(0);
+        editorFrame.current?.contentWindow?.postMessage({ type: "backmatter:reload-doc" }, origin);
+        startTransition(() => router.refresh());
+      }
+    }
+    window.addEventListener("message", onMessage);
+    return () => window.removeEventListener("message", onMessage);
+  }, [origin, router]);
+
+  const label = doc ? `${doc.type}/${doc.slug}` : "No document";
+  const editorSrc =
+    doc && base
+      ? `${base}/workspaces/${doc.workspaceId}/docs/${doc.locale}/${doc.type}/${doc.slug}?embed=1`
+      : "";
+
+  function onChatWrote() {
+    editorFrame.current?.contentWindow?.postMessage({ type: "backmatter:reload-doc" }, origin);
+    startTransition(() => router.refresh());
+  }
+
+  return (
+    <>
+      <style>{"body{padding-bottom:36px}"}</style>
+      {editorMounted && doc && editorSrc ? (
+        <iframe
+          ref={editorFrame}
+          title={`Edit ${label}`}
+          src={editorSrc}
+          style={{
+            ...editorStyle,
+            visibility: editorOpen ? "visible" : "hidden",
+            pointerEvents: editorOpen ? "auto" : "none",
+          }}
+        />
+      ) : null}
+      {chatMounted && doc ? (
+        <CmsChat
+          doc={doc}
+          hidden={!chatOpen}
+          onWrote={onChatWrote}
+          onClosed={() => setChatOpen(false)}
+          base={base}
+        />
+      ) : null}
+      {doc && base ? (
+        <iframe
+          title="Publish"
+          src={`${base}/embed/publish/${doc.workspaceId}`}
+          style={{
+            ...publishStyle,
+            visibility: publishOpen ? "visible" : "hidden",
+            pointerEvents: publishOpen ? "auto" : "none",
+          }}
+        />
+      ) : null}
+      <footer aria-label="Backmatter" style={barStyle}>
+        <button
+          type="button"
+          aria-pressed={editorOpen}
+          disabled={!doc}
+          onClick={() => {
+            setEditorMounted(true);
+            setEditorOpen((open) => !open);
+          }}
+          style={docButton}
+        >
+          {label}
+        </button>
+        <BarText>Preview</BarText>
+        {branch ? <BarText>{branch}</BarText> : null}
+        {tree ? <BarText>draft</BarText> : null}
+        <span style={{ flex: 1 }} />
+        <button type="button" aria-pressed={publishOpen} onClick={() => setPublishOpen((open) => !open)} style={barButton}>
+          Publish{changeCount ? ` ${changeCount}` : ""}
+        </button>
+        <button
+          type="button"
+          aria-pressed={chatOpen}
+          onClick={() => {
+            setChatMounted(true);
+            setChatOpen((open) => !open);
+          }}
+          title="Toggle AI chat (⌘J)"
+          style={barButton}
+        >
+          Agent
+        </button>
+        <button type="button" aria-label="Exit preview" disabled={exiting} onClick={onExit} style={barButton}>
+          Exit
+        </button>
+      </footer>
+    </>
+  );
+}
+
+function CmsChat({
+  doc,
+  hidden,
+  onWrote,
+  onClosed,
+  base,
+}: {
+  doc: SiteDocRef;
+  hidden: boolean;
+  onWrote: () => void;
+  onClosed: () => void;
+  /** Studio origin plus base path. */
+  base: string;
+}) {
+  const frame = useRef<HTMLIFrameElement>(null);
+  const onWroteRef = useRef(onWrote);
+  const onClosedRef = useRef(onClosed);
+  const hiddenRef = useRef(hidden);
+  onWroteRef.current = onWrote;
+  onClosedRef.current = onClosed;
+  hiddenRef.current = hidden;
+  const origin = base ? new URL(base).origin : "";
+
+  function openChat() {
+    const frameEl = frame.current;
+    if (!frameEl) return;
+    frameEl.focus();
+    frameEl.contentWindow?.postMessage({ type: "backmatter:chat-open" }, origin);
+  }
+
+  useEffect(() => {
+    if (!hidden) openChat();
+  }, [hidden, origin]);
+
+  useEffect(() => {
+    const focus = { locale: doc.locale, type: doc.type, slug: doc.slug };
+    function postFocus() {
+      frame.current?.contentWindow?.postMessage({ type: "backmatter:focus", doc: focus }, origin);
+    }
+    function onMessage(event: MessageEvent) {
+      if (event.origin !== origin) return;
+      if (event.data?.type === "backmatter:chat-ready") {
+        postFocus();
+        if (!hiddenRef.current) openChat();
+      }
+      if (event.data?.type === "backmatter:doc-changed") onWroteRef.current();
+      if (event.data?.type === "backmatter:chat-closed") onClosedRef.current();
+    }
+    window.addEventListener("message", onMessage);
+    postFocus();
+    return () => window.removeEventListener("message", onMessage);
+  }, [doc.locale, doc.type, doc.slug, origin]);
+
+  if (!base) return null;
+  return (
+    <iframe
+      ref={frame}
+      title="AI chat"
+      src={`${base}/embed/chat/${doc.workspaceId}`}
+      style={{
+        ...chatStyle,
+        visibility: hidden ? "hidden" : "visible",
+        pointerEvents: hidden ? "none" : "auto",
+      }}
+    />
+  );
+}
+
+function BarText({ children }: { children: ReactNode }) {
+  return <span style={mutedStyle}>{children}</span>;
+}
+
+const barStyle: CSSProperties = {
+  position: "fixed",
+  left: 0,
+  right: 0,
+  bottom: 0,
+  zIndex: 2147483000,
+  display: "flex",
+  alignItems: "center",
+  gap: 12,
+  height: 36,
+  padding: "0 12px",
+  paddingBottom: "env(safe-area-inset-bottom, 0px)",
+  boxSizing: "border-box",
+  borderTop: "1px solid #e4e4e7",
+  background: "#f4f4f5",
+  color: "#71717a",
+  font: "12px/1 ui-sans-serif, system-ui, sans-serif",
+};
+
+const barButton: CSSProperties = {
+  border: 0,
+  background: "transparent",
+  color: "#18181b",
+  font: "inherit",
+  cursor: "pointer",
+  padding: "4px 6px",
+};
+
+const docButton: CSSProperties = {
+  ...barButton,
+  fontWeight: 600,
+};
+
+const mutedStyle: CSSProperties = { color: "#71717a", fontSize: 12, margin: 0 };
+
+const editorStyle: CSSProperties = {
+  position: "fixed",
+  left: 0,
+  right: 0,
+  bottom: 36,
+  zIndex: 2147482999,
+  width: "100%",
+  height: "min(78vh, calc(100vh - 48px))",
+  border: 0,
+  borderTop: "1px solid #e4e4e7",
+  background: "#ffffff",
+  boxShadow: "0 -8px 24px rgba(24, 24, 27, 0.08)",
+};
+
+const chatStyle: CSSProperties = {
+  position: "fixed",
+  right: 12,
+  bottom: 48,
+  zIndex: 2147483001,
+  width: "min(440px, calc(100vw - 24px))",
+  height: "min(640px, calc(100vh - 120px))",
+  border: 0,
+  borderRadius: 14,
+  background: "#f4f4f5",
+  boxShadow: "0 16px 48px rgba(0,0,0,0.22), 0 2px 8px rgba(0,0,0,0.08)",
+};
+
+const publishStyle: CSSProperties = {
+  position: "fixed",
+  right: 12,
+  bottom: 48,
+  zIndex: 2147483001,
+  width: "min(420px, calc(100vw - 24px))",
+  height: "min(520px, calc(100vh - 120px))",
+  border: "1px solid #e4e4e7",
+  borderRadius: 8,
+  background: "#ffffff",
+  boxShadow: "0 12px 40px rgba(24, 24, 27, 0.16)",
+};

package/src/source-data.ts

@@ -0,0 +1,42 @@
+// packages/next/src/source-data.ts
+// The one place that decides how an external model's record is obtained for a
+// route: `load(ref)` for a real slug, `sample()` for the template document.
+// Both the catch-all and `renderPreview` call this; `renderLayoutDoc` only
+// receives the result.
+import { isTemplateSlug, type ModelDef, type SourceDef, type SourceRef } from "@backmatter/core";
+
+export type SourceResult = { ok: true; data: unknown } | { ok: false };
+
+/** Source for `model`, or throw when an external model has no `sources/{type}.ts`. */
+export function requireSource(
+  sources: Record<string, SourceDef> | undefined,
+  model: ModelDef,
+): SourceDef | undefined {
+  const source = sources?.[model.type];
+  if (model.external && !source) {
+    throw new Error(
+      `[backmatter] model "${model.type}" is external but sources/${model.type}.ts was not found`,
+    );
+  }
+  return source;
+}
+
+/**
+ * `{ ok: false }` means the outside record does not exist and the route is a 404.
+ * Without a source `data` is `undefined`. On the template slug `data` is the
+ * sample record, or `null` when the source has no `sample`.
+ */
+export async function resolveSourceData(
+  source: SourceDef | undefined,
+  model: ModelDef,
+  ref: SourceRef,
+): Promise<SourceResult> {
+  if (!source) return { ok: true, data: undefined };
+  if (isTemplateSlug(model, ref.slug)) {
+    const sample = source.sample ? await source.sample(ref.locale) : null;
+    return { ok: true, data: sample };
+  }
+  const record = await source.load(ref);
+  if (record === null || record === undefined) return { ok: false };
+  return { ok: true, data: record };
+}

package/src/studio-client.tsx

@@ -0,0 +1,62 @@
+"use client";
+// packages/next/src/studio-client.tsx
+// Loads @backmatter/studio in the browser only. The Studio is a client app
+// (react-router, IndexedDB replica, StyleX output); it has no server render.
+import { useEffect, useState, type ComponentType } from "react";
+import type { StudioDefinition } from "@backmatter/studio/define";
+import "@backmatter/studio/studio.css";
+
+export type StudioMountProps = {
+  workspaceId: string;
+  basePath: string;
+  dashboardUrl: string;
+  version: string;
+  proxyPath: string;
+  previewEntryPath: string;
+  /** CMS API origin for display (Content API URLs); requests use the proxy. */
+  apiUrl?: string;
+  /**
+   * `defineStudio(...)` from a `"use client"` module. The server page passes
+   * the client reference; it resolves to the object here.
+   */
+  studio?: StudioDefinition;
+};
+
+type SiteStudioComponent = ComponentType<StudioMountProps>;
+
+export function StudioMount(props: StudioMountProps) {
+  const [Studio, setStudio] = useState<SiteStudioComponent | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    import("@backmatter/studio")
+      .then((mod) => {
+        if (!cancelled) setStudio(() => mod.SiteStudio as SiteStudioComponent);
+      })
+      .catch((err: unknown) => {
+        if (!cancelled) setError(err instanceof Error ? err.message : "Could not load the Studio");
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  if (error) {
+    return (
+      <div style={fallbackStyle} role="alert">
+        {error}
+      </div>
+    );
+  }
+  if (!Studio) return <div style={fallbackStyle} aria-busy="true" />;
+  return <Studio {...props} />;
+}
+
+const fallbackStyle = {
+  minHeight: "100dvh",
+  display: "grid",
+  placeItems: "center",
+  fontFamily: "ui-sans-serif, system-ui, sans-serif",
+  color: "#71717a",
+} as const;

package/src/studio.tsx

@@ -0,0 +1,144 @@
+// packages/next/src/studio.tsx
+// Mount the Backmatter Studio on a route of the site.
+//
+//   // app/(backmatter)/backmatter/layout.tsx
+//   export { StudioLayout as default } from "@backmatter/next/studio";
+//
+//   // app/(backmatter)/backmatter/[[...path]]/page.tsx
+//   import { createStudioPage } from "@backmatter/next/studio";
+//   import { cms } from "@/.backmatter";
+//   export default createStudioPage(cms);
+//
+// The Studio talks to `/api/backmatter/cms/*` on this origin with the site
+// session cookie. Without a session the page redirects top-level to the
+// dashboard `enter` route, which mints a ticket and returns here.
+import { Suspense, type ReactNode } from "react";
+import {
+  PREVIEW_SESSION_COOKIE,
+  readPreviewSession,
+  resolveDashboardUrl,
+  studioEnterUrl,
+} from "@backmatter/core";
+import type { BackmatterClient } from "@backmatter/core/node/create-backmatter";
+import studioPkg from "@backmatter/studio/package.json";
+import type { StudioDefinition } from "@backmatter/studio/define";
+import { requestUrlFrom } from "./request-url";
+import { StudioMount } from "./studio-client";
+
+export { requestUrlFrom };
+
+export type StudioPageOptions = {
+  /** Where the Studio is mounted. Default `/backmatter`. */
+  basePath?: string;
+  /** Dashboard that holds the login. Default: `resolveDashboardUrl()`. */
+  dashboardUrl?: string;
+  /** Workspace to open. Default: `cms.config.workspaceId`. */
+  workspaceId?: string;
+  /** Same-origin proxy route. Default `/api/backmatter/cms`. */
+  proxyPath?: string;
+  /** Ticket entry route. Default `/api/backmatter/preview`. */
+  previewEntryPath?: string;
+  /**
+   * Site customization: the default export of a `"use client"` module that
+   * calls `defineStudio`. The server only forwards the reference.
+   */
+  studio?: StudioDefinition;
+};
+
+type NextHeaders = {
+  cookies: () => Promise<{ get: (name: string) => { value: string } | undefined }>;
+  headers: () => Promise<{ get: (name: string) => string | null }>;
+};
+
+type NextNavigation = { redirect: (url: string) => never };
+
+async function nextHeaders(): Promise<NextHeaders> {
+  return (await import("next/headers" as string)) as NextHeaders;
+}
+
+async function nextNavigation(): Promise<NextNavigation> {
+  return (await import("next/navigation" as string)) as NextNavigation;
+}
+
+export function studioPathFor(basePath: string, segments: string[] | undefined, search = ""): string {
+  const rest = segments && segments.length > 0 ? `/${segments.map(encodeURIComponent).join("/")}` : "";
+  return `${basePath}${rest}${search}`;
+}
+
+export function createStudioPage(
+  cms: Pick<BackmatterClient, "config">,
+  options: StudioPageOptions = {},
+) {
+  const basePath = (options.basePath ?? "/backmatter").replace(/\/+$/, "") || "/backmatter";
+  const proxyPath = options.proxyPath ?? "/api/backmatter/cms";
+  const previewEntryPath = options.previewEntryPath ?? "/api/backmatter/preview";
+
+  return async function StudioPage(props: {
+    params: Promise<{ path?: string[] }> | { path?: string[] };
+    searchParams?: Promise<Record<string, string | string[] | undefined>> | Record<string, string | string[] | undefined>;
+  }) {
+    const workspaceId = options.workspaceId ?? cms.config.workspaceId;
+    if (!workspaceId) {
+      throw new Error("backmatter: the Studio needs a workspaceId (backmatter.config.ts or BACKMATTER_WORKSPACE_ID)");
+    }
+    const dashboardUrl = resolveDashboardUrl(options.dashboardUrl);
+    const { cookies, headers } = await nextHeaders();
+    const [cookieStore, headerStore] = await Promise.all([cookies(), headers()]);
+
+    const token = cookieStore.get(PREVIEW_SESSION_COOKIE)?.value;
+    const secret = cms.config.previewToken;
+    const claims = token && secret ? await readPreviewSession(secret, token) : null;
+    const valid = claims !== null && claims.workspaceId === workspaceId;
+
+    if (!valid) {
+      const params = await props.params;
+      const search = props.searchParams ? await props.searchParams : {};
+      const qs = new URLSearchParams();
+      for (const [key, value] of Object.entries(search)) {
+        if (typeof value === "string") qs.set(key, value);
+      }
+      const searchText = qs.size > 0 ? `?${qs.toString()}` : "";
+      const returnUrl = requestUrlFrom(
+        (name) => headerStore.get(name),
+        studioPathFor(basePath, params.path, searchText),
+      );
+      const { redirect } = await nextNavigation();
+      redirect(studioEnterUrl(dashboardUrl, { workspaceId, returnUrl }));
+    }
+
+    return (
+      <StudioMount
+        workspaceId={workspaceId}
+        basePath={basePath}
+        dashboardUrl={dashboardUrl}
+        version={studioPkg.version}
+        proxyPath={proxyPath}
+        previewEntryPath={previewEntryPath}
+        apiUrl={cms.config.apiUrl}
+        studio={options.studio}
+      />
+    );
+  };
+}
+
+/**
+ * Root layout for the Studio route group. Its own `<html>` so the site's
+ * layout, fonts and global CSS do not wrap the editor.
+ */
+export function StudioLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <meta name="robots" content="noindex, nofollow" />
+        <script dangerouslySetInnerHTML={{ __html: THEME_BOOT }} />
+      </head>
+      <body style={{ margin: 0 }}>
+        {/* The page reads cookies; with Cache Components that must sit under Suspense. */}
+        <Suspense fallback={null}>{children}</Suspense>
+      </body>
+    </html>
+  );
+}
+
+// Same first-paint theme pick as the dashboard's index.html.
+const THEME_BOOT = `(function(){try{var s=localStorage.getItem("backmatter-theme");var m=s==="light"||s==="dark"?s:"system";var d=m==="dark"||(m!=="light"&&window.matchMedia("(prefers-color-scheme: dark)").matches);document.documentElement.dataset.theme=d?"dark":"light";document.documentElement.style.colorScheme=d?"dark":"light"}catch(e){}})();`;