@backmatter/next 0.0.22 → 0.0.24

package/src/site-pointer.ts

@@ -0,0 +1,199 @@
+// packages/next/src/site-pointer.ts
+// Hit-test a click on the host page and draw the armed pointer outline.
+
+export const POINTER_QUOTE_MAX = 240;
+
+export type PointerGrab = {
+  blockId: string | null;
+  blockType: string | null;
+  blockIndex: number | null;
+  quote: string;
+};
+
+function quoteOf(target: Element): string {
+  return (target.textContent ?? "").replace(/\s+/g, " ").trim().slice(0, POINTER_QUOTE_MAX);
+}
+
+function presentAttr(el: Element, name: string): string | null {
+  const value = el.getAttribute(name);
+  return value ? value : null;
+}
+
+/** Resolve the block marker and visible text under a click. Clicks on the bar are ignored. */
+export function grabAt(target: Element | null, bar: Element | null): PointerGrab | null {
+  if (!target) return null;
+  const doc = target.ownerDocument;
+  if (target === doc.documentElement || target === doc.body) return null;
+  if (bar && (target === bar || bar.contains(target))) return null;
+  if (target.closest("[data-backmatter-pointer]")) return null;
+
+  const marker = target.closest("[data-backmatter-block]");
+  const quote = quoteOf(target);
+  if (!marker) {
+    if (!quote) return null;
+    return { blockId: null, blockType: null, blockIndex: null, quote };
+  }
+  const indexRaw = marker.getAttribute("data-backmatter-index");
+  const blockIndex = indexRaw !== null && /^\d+$/.test(indexRaw) ? Number(indexRaw) : null;
+  return {
+    blockId: presentAttr(marker, "data-backmatter-block"),
+    blockType: presentAttr(marker, "data-backmatter-type"),
+    blockIndex,
+    quote,
+  };
+}
+
+export type SitePointer = {
+  arm: () => void;
+  disarm: () => void;
+  dispose: () => void;
+};
+
+/**
+ * While armed, the page shows a crosshair and an outline. A click reports the
+ * element and does not follow links. Escape disarms. The picker stays armed
+ * after a click so another element can be added.
+ */
+export function installSitePointer(
+  doc: Document,
+  options: {
+    bar: () => Element | null;
+    ignore?: (target: EventTarget | null) => boolean;
+    onGrab: (grab: PointerGrab) => void;
+    onEscape?: () => void;
+  },
+): SitePointer {
+  let armed = false;
+  let current: Element | null = null;
+  let outline: HTMLDivElement | null = null;
+  const root = doc.documentElement;
+
+  function ignored(target: EventTarget | null): boolean {
+    if (!(target instanceof Element)) return true;
+    if (target === root || target === doc.body) return true;
+    if (target.closest("[data-backmatter-pointer]")) return true;
+    const bar = options.bar();
+    if (bar && (target === bar || bar.contains(target))) return true;
+    return options.ignore?.(target) ?? false;
+  }
+
+  function ensureOutline(): HTMLDivElement {
+    if (outline?.isConnected) return outline;
+    outline?.remove();
+    outline = null;
+    const el = doc.createElement("div");
+    el.setAttribute("data-backmatter-pointer", "");
+    el.style.position = "fixed";
+    el.style.pointerEvents = "none";
+    el.style.zIndex = "2147482980";
+    el.style.boxSizing = "border-box";
+    el.style.border = "1.5px solid #18181b";
+    el.style.borderRadius = "4px";
+    el.style.background = "rgba(24, 24, 27, 0.06)";
+    const label = doc.createElement("div");
+    label.setAttribute("data-backmatter-pointer-label", "");
+    label.style.position = "absolute";
+    label.style.left = "0";
+    label.style.top = "0";
+    label.style.maxWidth = "240px";
+    label.style.overflow = "hidden";
+    label.style.textOverflow = "ellipsis";
+    label.style.whiteSpace = "nowrap";
+    label.style.padding = "2px 6px";
+    label.style.borderRadius = "4px";
+    label.style.background = "#18181b";
+    label.style.color = "#ffffff";
+    label.style.font = '11px/1.4 ui-sans-serif, system-ui, sans-serif';
+    label.style.display = "none";
+    el.appendChild(label);
+    doc.body.appendChild(el);
+    outline = el;
+    return el;
+  }
+
+  function place(target: Element | null) {
+    current = target;
+    if (!target) {
+      if (outline) outline.style.display = "none";
+      return;
+    }
+    const el = ensureOutline();
+    const rect = target.getBoundingClientRect();
+    if (rect.width < 1 && rect.height < 1) {
+      el.style.display = "none";
+      return;
+    }
+    el.style.display = "block";
+    el.style.left = `${rect.left}px`;
+    el.style.top = `${rect.top}px`;
+    el.style.width = `${rect.width}px`;
+    el.style.height = `${rect.height}px`;
+    const label = el.firstElementChild as HTMLElement | null;
+    const name = target.closest("[data-backmatter-block]")?.getAttribute("data-backmatter-type") ?? "";
+    if (!label) return;
+    if (!name) {
+      label.textContent = "";
+      label.style.display = "none";
+      return;
+    }
+    label.textContent = name;
+    label.style.display = "block";
+    label.style.transform = rect.top < 28 ? "none" : "translateY(calc(-100% - 4px))";
+  }
+
+  function onMove(event: PointerEvent) {
+    const target = event.target instanceof Element ? event.target : null;
+    place(target && !ignored(target) ? target : null);
+  }
+
+  function onScroll() {
+    if (current && !ignored(current)) place(current);
+    else place(null);
+  }
+
+  function onClick(event: MouseEvent) {
+    if (!armed || ignored(event.target)) return;
+    event.preventDefault();
+    event.stopPropagation();
+    const target = event.target instanceof Element ? event.target : null;
+    const grab = grabAt(target, options.bar());
+    if (grab) options.onGrab(grab);
+  }
+
+  function onKey(event: KeyboardEvent) {
+    if (!armed || event.key !== "Escape") return;
+    event.preventDefault();
+    event.stopPropagation();
+    disarm();
+    options.onEscape?.();
+  }
+
+  function arm() {
+    if (armed) return;
+    armed = true;
+    root.classList.add("backmatter-pointing");
+    doc.addEventListener("pointermove", onMove, true);
+    doc.addEventListener("scroll", onScroll, true);
+    doc.addEventListener("click", onClick, true);
+    doc.addEventListener("keydown", onKey, true);
+  }
+
+  function disarm() {
+    if (!armed) return;
+    armed = false;
+    current = null;
+    root.classList.remove("backmatter-pointing");
+    doc.removeEventListener("pointermove", onMove, true);
+    doc.removeEventListener("scroll", onScroll, true);
+    doc.removeEventListener("click", onClick, true);
+    doc.removeEventListener("keydown", onKey, true);
+    outline?.remove();
+    outline = null;
+  }
+
+  return {
+    arm,
+    disarm,
+    dispose: disarm,
+  };
+}

package/src/studio-client.tsx

@@ -0,0 +1,80 @@
+"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>;
+
+const fallbackStyle = {
+  minHeight: "100dvh",
+  display: "grid",
+  placeItems: "center",
+  fontFamily: "ui-sans-serif, system-ui, sans-serif",
+  color: "#71717a",
+} as const;
+
+const SESSION_EXPIRED_MESSAGE = "backmatter:session-expired";
+
+/**
+ * Rendered instead of redirecting to the dashboard. A frame tells the parent
+ * to drop the bar. The top window goes to `enterUrl` to sign in.
+ */
+export function StudioSignedOut({ enterUrl }: { enterUrl: string }) {
+  useEffect(() => {
+    const framed = Boolean(window.top && window.top !== window);
+    if (framed) {
+      window.parent.postMessage({ type: SESSION_EXPIRED_MESSAGE }, window.location.origin);
+      return;
+    }
+    window.location.assign(enterUrl);
+  }, [enterUrl]);
+  return <div style={fallbackStyle} aria-busy="true" />;
+}
+
+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} />;
+}

package/src/studio.tsx

@@ -0,0 +1,157 @@
+// 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, a frame tells the parent page and a
+// top-level visit goes to the dashboard `enter` route.
+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, StudioSignedOut } 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 }>;
+};
+
+async function nextHeaders(): Promise<NextHeaders> {
+  return (await import("next/headers" as string)) as NextHeaders;
+}
+
+export function studioPathFor(basePath: string, segments: string[] | undefined, search = ""): string {
+  const rest = segments && segments.length > 0 ? `/${segments.map(encodeURIComponent).join("/")}` : "";
+  return `${basePath}${rest}${search}`;
+}
+
+type StudioPageProps = {
+  params: Promise<{ path?: string[] }> | { path?: string[] };
+  searchParams?:
+    | Promise<Record<string, string | string[] | undefined>>
+    | Record<string, string | string[] | undefined>;
+};
+
+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";
+
+  function requireWorkspaceId(): string {
+    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)");
+    }
+    return workspaceId;
+  }
+
+  // Cookie and header reads stay in this child. The page returns Suspense
+  // first so Cache Components can prerender the route shell.
+  async function StudioSession(props: StudioPageProps & { workspaceId: string }) {
+    const { workspaceId } = props;
+    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),
+      );
+      return <StudioSignedOut enterUrl={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}
+      />
+    );
+  }
+
+  return function StudioPage(props: StudioPageProps) {
+    const workspaceId = requireWorkspaceId();
+    return (
+      <Suspense fallback={null}>
+        <StudioSession {...props} workspaceId={workspaceId} />
+      </Suspense>
+    );
+  };
+}
+
+/**
+ * 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 suspends on the session. This boundary keeps the document shell outside that hole. */}
+        <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){}})();`;