@blinkk/root-cms 3.0.6 → 3.1.1

package/README.md

@@ -92,3 +92,80 @@ This is convenient for granting access to a whole workspace, but be aware:
   that grants access to anyone with a Google account.
 - Prefer explicit per-email grants for `ADMIN` and `EDITOR`; reserve the
   wildcard for `CONTRIBUTOR` or `VIEWER` if you use it at all.
+
+# Embedding the CMS (`@blinkk/root-cms/browser-client`)
+
+`@blinkk/root-cms/browser-client` is a dependency-free, framework-agnostic
+browser library for embedding Root CMS into another site. It wraps the
+underlying iframe/postMessage wiring behind a typed API, so the wire protocol
+can evolve without breaking your integration.
+
+For pop-up/iframe embedding (the doc editor and Root AI), the embedding page's
+origin must be allowlisted in the CMS plugin config:
+
+```ts
+// root.config.ts
+cmsPlugin({
+  // ...
+  allowedIframeOrigins: ['https://app.example.com'],
+});
+```
+
+## Headless doc editor (pop-up or iframe)
+
+Opens `/cms/embed/content/<collection>/<slug>`, a minimal version of the doc
+editor with explicit (non-auto) saving. In `popup` mode, call from a user
+gesture (e.g. a click handler) to avoid pop-up blockers. Closing the editor
+discards unsaved changes.
+
+```ts
+import {RootCMSBrowserClient} from '@blinkk/root-cms/browser-client';
+
+const root = new RootCMSBrowserClient({cmsOrigin: 'https://cms.example.com'});
+
+const editor = root.openEditor('Pages/about', {
+  mode: 'popup', // or 'iframe' (pass `container`)
+  deeplink: 'hero.title', // optional: field to scroll to on load
+});
+editor.on('ready', () => console.log('editor loaded'));
+editor.on('saved', () => location.reload());
+editor.on('published', () => editor.closeAndReload());
+editor.on('close', () => console.log('editor closed'));
+editor.focusField('hero.image'); // scroll the editor to a field
+editor.reload();
+editor.close(); // or editor.closeAndReload()
+```
+
+## Headless Root AI (pop-up or iframe)
+
+Opens `/cms/embed/ai`, the compact Root AI chat, optionally with a doc as
+context:
+
+```ts
+const ai = root.openRootAI({docId: 'Pages/about', mode: 'popup'});
+ai.on('ready', () => console.log('chat loaded'));
+ai.close();
+```
+
+## Field focus from the in-CMS preview pane ("click to edit")
+
+When your site is rendered inside the CMS preview pane, use a
+`PreviewConnection` to focus editor fields from the page and to highlight page
+nodes when the editor requests it. The preview pane is same-origin with the
+CMS, so no config is needed and the connection is inert when the page is not
+embedded:
+
+```ts
+import {RootCMSBrowserClient} from '@blinkk/root-cms/browser-client';
+
+const preview = RootCMSBrowserClient.connectPreview();
+if (preview.isEmbedded) {
+  // "Click to edit": focus the field in the doc editor.
+  el.addEventListener('click', () => preview.focusField('hero.title'));
+  // Highlight page nodes when the editor hovers/focuses a field.
+  preview.on('highlight', ({deepKey, scroll}) => {
+    clearHighlights();
+    if (deepKey) highlightNode(deepKey, {scroll});
+  });
+}
+```

package/dist/app.js

@@ -1,9 +1,10 @@
 import {
   getServerVersion,
   serializeAiConfig
-} from "./chunk-7L5OI5ES.js";
-import "./chunk-RXWDB3K4.js";
-import "./chunk-N4K6ICFR.js";
+} from "./chunk-GXV4UQ6Z.js";
+import "./chunk-4VZTYUQ7.js";
+import "./chunk-AFBSITEO.js";
+import "./chunk-J72JK4KR.js";
 import {
   getCollectionSchema,
   getProjectSchemas
@@ -150,7 +151,8 @@ async function renderApp(req, res, options) {
       hasExport: isFunction(t.onExport)
     })),
     defaultOneOfVariant: cmsConfig.defaultOneOfVariant || "dropdown",
-    excludeLocalesFromTranslations: cmsConfig.excludeLocalesFromTranslations || []
+    excludeLocalesFromTranslations: cmsConfig.excludeLocalesFromTranslations || [],
+    allowedIframeOrigins: cmsConfig.allowedIframeOrigins || []
   };
   const projectName = cmsConfig.name || cmsConfig.id || "";
   const title = getCmsTitle(projectName, cmsConfig.minimalBranding);

package/dist/browser-client/browser-client.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Browser client for embedding Root CMS into another site, exported as
+ * `@blinkk/root-cms/browser-client`. Framework-agnostic and dependency-free.
+ *
+ * Covers three scenarios:
+ * - Opening the headless doc editor in a pop-up or iframe
+ *   ({@link RootCMSBrowserClient.openEditor}).
+ * - Opening the headless Root AI chat in a pop-up or iframe
+ *   ({@link RootCMSBrowserClient.openRootAI}).
+ * - Communicating with the doc editor from a site rendered inside the in-CMS
+ *   preview pane ({@link RootCMSBrowserClient.connectPreview}).
+ *
+ * The first two require the embedding page's origin to be listed in the
+ * `allowedIframeOrigins` option of the CMS plugin config.
+ */
+import { EmbedWindow, EmbedWindowEvents } from './embed-window.js';
+export { SaveState } from '../shared/embed-protocol.js';
+export type { HighlightNodeMessage, RootEmbedMessage, ScrollToDeeplinkMessage, } from '../shared/embed-protocol.js';
+export type { EmbedWindowEvents } from './embed-window.js';
+export interface RootCMSBrowserClientOptions {
+    /** Origin of the Root CMS server, e.g. `https://cms.example.com`. */
+    cmsOrigin: string;
+}
+export interface OpenEditorOptions {
+    /** How to open the editor. Defaults to `popup`. */
+    mode?: 'popup' | 'iframe';
+    /** Container the iframe is appended to. Required when mode is `iframe`. */
+    container?: HTMLElement;
+    /** Deep key of a field to scroll to on load, e.g. `hero.title`. */
+    deeplink?: string;
+    /** Pop-up window width. Defaults to 480. */
+    width?: number;
+    /** Pop-up window height. Defaults to 720. */
+    height?: number;
+}
+export interface OpenRootAIOptions extends Omit<OpenEditorOptions, 'deeplink'> {
+    /** Doc to provide as context to the AI chat, e.g. `Pages/about`. */
+    docId?: string;
+}
+/** Events emitted by {@link EmbeddedEditor}. */
+export type EditorEvents = EmbedWindowEvents;
+/** Events emitted by {@link EmbeddedAI}. */
+export type AIEvents = Pick<EmbedWindowEvents, 'ready' | 'error' | 'close'>;
+/** Event emitted when the doc editor requests a field highlight. */
+export interface PreviewHighlightEvent {
+    /** Deep key of the field to highlight, or `null` to clear highlights. */
+    deepKey: string | null;
+    /** Whether to scroll the highlighted node into view. */
+    scroll: boolean;
+}
+/**
+ * Handle to a headless doc editor opened via {@link RootCMSBrowserClient.openEditor}.
+ *
+ * Note: the embedded editor does not autosave; closing it discards any
+ * unsaved changes.
+ */
+export declare class EmbeddedEditor {
+    /** The doc being edited, e.g. `Pages/about`. */
+    readonly docId: string;
+    private embedWindow;
+    constructor(docId: string, embedWindow: EmbedWindow);
+    /** The iframe element (iframe mode only). */
+    get element(): HTMLIFrameElement | null;
+    /** The pop-up window (popup mode only). */
+    get window(): Window | null;
+    /** Subscribes to an editor event. Returns an unsubscribe function. */
+    on<K extends keyof EditorEvents>(type: K, cb: (payload: EditorEvents[K]) => void): () => void;
+    /** Scrolls the editor to (focuses) a field, e.g. `hero.title`. */
+    focusField(deepKey: string): void;
+    /** Reloads the embedded editor. */
+    reload(): void;
+    /** Closes the embedded editor, discarding any unsaved changes. */
+    close(): void;
+    /** Closes the embedded editor and reloads the host page. */
+    closeAndReload(): void;
+}
+/** Handle to a headless Root AI chat opened via {@link RootCMSBrowserClient.openRootAI}. */
+export declare class EmbeddedAI {
+    private embedWindow;
+    constructor(embedWindow: EmbedWindow);
+    /** The iframe element (iframe mode only). */
+    get element(): HTMLIFrameElement | null;
+    /** The pop-up window (popup mode only). */
+    get window(): Window | null;
+    /** Subscribes to an event. Returns an unsubscribe function. */
+    on<K extends keyof AIEvents>(type: K, cb: (payload: AIEvents[K]) => void): () => void;
+    /** Reloads the embedded chat (starts a fresh chat). */
+    reload(): void;
+    /** Closes the embedded chat. */
+    close(): void;
+    /** Closes the embedded chat and reloads the host page. */
+    closeAndReload(): void;
+}
+/**
+ * Channel between a site rendered inside the in-CMS preview pane and the doc
+ * editor that frames it. The preview iframe is same-origin with the CMS, so
+ * no configuration is needed. Safe to construct unconditionally: outside the
+ * preview pane the connection is inert (`isEmbedded` is false).
+ */
+export declare class PreviewConnection {
+    /** Whether this page is rendered inside the in-CMS preview pane. */
+    readonly isEmbedded: boolean;
+    private emitter;
+    constructor();
+    /**
+     * Requests that the doc editor scroll to (focus) a field, e.g.
+     * `hero.title`. Used to implement "click to edit".
+     */
+    focusField(deepKey: string): void;
+    /**
+     * Subscribes to field highlight requests from the doc editor (sent when the
+     * user hovers/focuses a field). Returns an unsubscribe function.
+     */
+    on(type: 'highlight', cb: (event: PreviewHighlightEvent) => void): () => void;
+    /** Removes the message listener and all subscriptions. */
+    disconnect(): void;
+    private onMessage;
+}
+/** Client for embedding Root CMS into another site. */
+export declare class RootCMSBrowserClient {
+    /** Normalized origin of the Root CMS server. */
+    readonly cmsOrigin: string;
+    constructor(options: RootCMSBrowserClientOptions);
+    /**
+     * Opens the headless doc editor for a doc (e.g. `Pages/about`) in a pop-up
+     * or iframe. In popup mode, call from a user gesture (e.g. a click handler)
+     * to avoid pop-up blockers.
+     *
+     * The slug portion of the docId is normalized the same way the CMS
+     * normalizes slugs, so a URL-like path also works, e.g. `Pages/about/foo`
+     * -> `Pages/about--foo`.
+     */
+    openEditor(docId: string, options?: OpenEditorOptions): EmbeddedEditor;
+    /**
+     * Opens the headless Root AI chat in a pop-up or iframe, optionally with a
+     * doc as context. In popup mode, call from a user gesture (e.g. a click
+     * handler) to avoid pop-up blockers.
+     */
+    openRootAI(options?: OpenRootAIOptions): EmbeddedAI;
+    /**
+     * Connects to the doc editor from a site rendered inside the in-CMS preview
+     * pane, enabling "click to edit" ({@link PreviewConnection.focusField}) and
+     * field highlighting (`on('highlight', ...)`).
+     */
+    static connectPreview(): PreviewConnection;
+    /** Returns whether this page is rendered inside the in-CMS preview pane. */
+    static isInPreviewIframe(): boolean;
+}

package/dist/browser-client/embed-window.d.ts

@@ -0,0 +1,66 @@
+import { SaveState } from '../shared/embed-protocol.js';
+/** Events emitted by an embedded CMS window (iframe or pop-up). */
+export interface EmbedWindowEvents {
+    /** The embedded page finished loading. */
+    ready: {
+        docId?: string;
+    };
+    /** The doc was saved. */
+    saved: {
+        docId?: string;
+        saveState?: SaveState;
+    };
+    /** The doc was published. */
+    published: {
+        docId?: string;
+        publishedAt?: number;
+    };
+    /** An error occurred (e.g. the pop-up was blocked). */
+    error: {
+        error?: string;
+    };
+    /** The embedded window was closed (via `close()` or by the user). */
+    close: void;
+}
+export interface EmbedWindowOptions {
+    /** How to open the embedded page. Defaults to `popup`. */
+    mode?: 'popup' | 'iframe';
+    /** Container the iframe is appended to. Required when mode is `iframe`. */
+    container?: HTMLElement;
+    /** Pop-up window width. Defaults to 480. */
+    width?: number;
+    /** Pop-up window height. Defaults to 720. */
+    height?: number;
+}
+/**
+ * Internal plumbing shared by the embedded doc editor and Root AI handles.
+ * Owns the iframe-or-popup lifecycle: opening, message routing (with origin
+ * and source validation), outbound message buffering until `ready`, reload,
+ * and close detection.
+ */
+export declare class EmbedWindow {
+    /** The iframe element (iframe mode only). */
+    readonly element: HTMLIFrameElement | null;
+    /** The pop-up window (popup mode only). */
+    readonly window: Window | null;
+    private url;
+    private cmsOrigin;
+    private emitter;
+    private ready;
+    private closed;
+    private outbox;
+    private pollTimer;
+    constructor(url: string, cmsOrigin: string, options?: EmbedWindowOptions);
+    on<K extends keyof EmbedWindowEvents>(type: K, cb: (payload: EmbedWindowEvents[K]) => void): () => void;
+    /**
+     * Posts a message to the embedded window, targeted at the CMS origin.
+     * Messages are buffered until the embedded page signals `ready`.
+     */
+    post(message: unknown): void;
+    /** Reloads the embedded page. */
+    reload(): void;
+    /** Closes the embedded window. Safe to call multiple times. */
+    close(): void;
+    private contentWindow;
+    private onMessage;
+}

package/dist/browser-client/emitter.d.ts

@@ -0,0 +1,11 @@
+type Listener<T> = (payload: T) => void;
+/** Minimal typed event emitter. */
+export declare class Emitter<Events extends Record<string, any>> {
+    private listeners;
+    /** Subscribes to an event. Returns an unsubscribe function. */
+    on<K extends keyof Events>(type: K, cb: Listener<Events[K]>): () => void;
+    off<K extends keyof Events>(type: K, cb: Listener<Events[K]>): void;
+    emit<K extends keyof Events>(type: K, payload: Events[K]): void;
+    removeAll(): void;
+}
+export {};