@next-buildr/editor 0.0.0-stage → 2.0.1

package/dist/persistence/types.d.ts

@@ -0,0 +1,182 @@
+import type { BuilderDocument, DataContext, DataSchema, Diagnostic, LocaleConfig, MediaAsset } from '@next-buildr/core';
+/** Which document the editor opens: a collection and an id in the host's backend. */
+export interface DocumentRef {
+    readonly collection: string;
+    readonly id: string | number;
+}
+/** Who is editing and what they may do; decided by the host's backend. */
+export interface EditorSession {
+    readonly userId?: string | undefined;
+    readonly canEdit: boolean;
+    readonly canPublish: boolean;
+    /** The languages the content can be written in; one language when the host has no localization. */
+    readonly locales?: LocaleConfig | undefined;
+}
+/** A document as the backend has it (`GET` of docs/payload.md#endpoints). */
+export interface LoadedDocument {
+    readonly title: string;
+    readonly slug?: string | undefined;
+    readonly status: 'draft' | 'published';
+    readonly updatedAt: string;
+    /** Changes with every save; the next save says which one it builds on (`baseRevision`). */
+    readonly revision: number;
+    readonly document: BuilderDocument;
+    /** A viewer's role, or a component newer than this build knows: the document may not be changed. */
+    readonly readOnly?: boolean | undefined;
+    /** What the canvas binds against by default: the entry this document is (`collection:id` for Payload). */
+    readonly contextRef?: string | undefined;
+}
+export interface SaveRequest {
+    readonly document: BuilderDocument;
+    readonly baseRevision: number;
+    /** `true` for a save the editor started on its own, `false` for Ctrl+S; the backend may keep fewer versions of the former. */
+    readonly autosave: boolean;
+}
+/**
+ * What a save came to. A refused save is a value, not a rejection: only what the adapter could not
+ * tell (no network, a 5xx) rejects, and that is the case the editor retries.
+ */
+export type SaveResult = {
+    readonly ok: true;
+    readonly revision: number;
+    readonly updatedAt: string;
+} | {
+    readonly ok: false;
+    readonly kind: 'conflict';
+    readonly currentRevision: number;
+} | {
+    readonly ok: false;
+    readonly kind: 'invalid';
+    readonly diagnostics: readonly Diagnostic[];
+};
+export type PublishResult = {
+    readonly ok: true;
+    readonly revision: number;
+    readonly updatedAt: string;
+} | {
+    readonly ok: false;
+    readonly kind: 'conflict';
+    readonly currentRevision: number;
+} | {
+    readonly ok: false;
+    readonly kind: 'invalid';
+    readonly diagnostics: readonly Diagnostic[];
+};
+/** What `PersistenceController.publish` came to. */
+export type PublishOutcome = {
+    readonly ok: true;
+    readonly revision: number;
+    readonly updatedAt: string;
+} | {
+    readonly ok: false;
+    readonly kind: 'conflict';
+    readonly currentRevision: number;
+} | {
+    readonly ok: false;
+    readonly kind: 'invalid';
+    readonly diagnostics: readonly Diagnostic[];
+}
+/** The document could not be saved first, so there is nothing consistent to publish. */
+ | {
+    readonly ok: false;
+    readonly kind: 'unsaved';
+} | {
+    readonly ok: false;
+    readonly kind: 'network';
+    readonly message: string;
+};
+export interface MediaSearchResult {
+    readonly items: readonly MediaAsset[];
+    readonly nextCursor?: string | undefined;
+}
+/** What the backend has now, without the document (`getRevision`). */
+export interface RevisionInfo {
+    readonly revision: number;
+    readonly updatedAt: string;
+    /** Who made the last save (a name or an email), when the backend records it. */
+    readonly updatedBy?: string | undefined;
+}
+/** What the editor needs from a backend (docs/editor.md#persistence-pb-087); `@next-buildr/payload` implements it. */
+export interface DocumentAdapter {
+    getSession(ref: DocumentRef): Promise<EditorSession>;
+    load(ref: DocumentRef): Promise<LoadedDocument>;
+    /**
+     * The current revision only (cheap): lets the editor notice a save made elsewhere, by an agent or
+     * another tab, before its own save is refused. Optional; without it nothing is polled.
+     */
+    getRevision?(ref: DocumentRef): Promise<RevisionInfo>;
+    save(ref: DocumentRef, request: SaveRequest): Promise<SaveResult>;
+    /**
+     * Renames the page and returns the name the backend kept (it may trim it). The name is not part of
+     * the document, so it is neither versioned nor autosaved. Optional; the editor's title is read-only
+     * without it. A refusal rejects.
+     */
+    rename?(ref: DocumentRef, title: string): Promise<{
+        readonly title: string;
+    }>;
+    publish(ref: DocumentRef, request: {
+        readonly baseRevision: number;
+    }): Promise<PublishResult>;
+    getDataSchema(ref: DocumentRef): Promise<DataSchema>;
+    /** The data the page is shown with; `sampleId` (one of `listSamples`) picks the entry a template is previewed against. */
+    getContext(ref: DocumentRef, options?: {
+        readonly sampleId?: string;
+    }): Promise<DataContext>;
+    listSamples?(ref: DocumentRef): Promise<readonly {
+        readonly id: string;
+        readonly label: string;
+    }[]>;
+    readonly media: {
+        search(query: {
+            readonly text?: string;
+            readonly cursor?: string;
+            readonly mimeTypes?: readonly string[];
+        }): Promise<MediaSearchResult>;
+        /** Adds a file to the library. `alt` is required: an image without alternative text is an accessibility error. */
+        upload?(file: File, alt: string): Promise<MediaAsset>;
+    };
+    /** Where the site shows the page as a visitor would; `draft` asks for the unpublished version. */
+    previewUrl(ref: DocumentRef, options?: {
+        readonly draft?: boolean;
+    }): string;
+    /** The page in the CMS's own admin, when it has one. */
+    cmsUrl?(ref: DocumentRef): string | undefined;
+}
+export type PersistenceStatus = 
+/** The document is the saved one. */
+'clean'
+/** Changed since the last save; a save is scheduled. */
+ | 'dirty' | 'saving'
+/** The last save failed and will be retried (or, for `invalid`, waits for a change). */
+ | 'error'
+/** Somebody else saved in the meantime; the author chooses between reload and overwrite. */
+ | 'conflict';
+export type PersistenceError = {
+    readonly kind: 'network';
+    readonly message: string;
+    readonly attempt: number;
+} | {
+    readonly kind: 'invalid';
+    readonly diagnostics: readonly Diagnostic[];
+};
+export interface PersistenceState {
+    readonly status: PersistenceStatus;
+    /** The revision the next save builds on. */
+    readonly revision: number;
+    readonly lastSavedAt: string | undefined;
+    readonly error: PersistenceError | undefined;
+    /** The revision the backend has now, while `status` is `conflict`. */
+    readonly conflictRevision: number | undefined;
+    /** A newer revision seen on the backend while the local document is unchanged (offer a reload). */
+    readonly external: {
+        readonly revision: number;
+        readonly updatedBy: string | undefined;
+    } | undefined;
+}
+/** The timers the state machine runs on; tests inject their own. */
+export interface Clock {
+    now(): number;
+    setTimeout(handler: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/persistence/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/persistence/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,WAAW,EACX,UAAU,EACV,UAAU,EACV,YAAY,EACZ,UAAU,EACX,MAAM,mBAAmB,CAAC;AAE3B,qFAAqF;AACrF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;CAC9B;AAED,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,mGAAmG;IACnG,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;CAC7C;AAED,6EAA6E;AAC7E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,WAAW,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,2FAA2F;IAC3F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,oGAAoG;IACpG,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACxC,0GAA0G;IAC1G,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1C;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,8HAA8H;IAC9H,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC5E;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;CAAE,GACnF;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE,CAAC;AAElG,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC5E;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;CAAE,GACnF;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE,CAAC;AAElG,oDAAoD;AACpD,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC5E;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;CAAE,GACnF;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE;AAC/F,wFAAwF;GACtF;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAChD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;IACtC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1C;AAED,sEAAsE;AACtE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,gFAAgF;IAChF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC;AAED,sHAAsH;AACtH,MAAM,WAAW,eAAe;IAC9B,UAAU,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACrD,IAAI,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAChD;;;OAGG;IACH,WAAW,CAAC,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACtD,IAAI,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAClE;;;;OAIG;IACH,MAAM,CAAC,CAAC,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC9E,OAAO,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE;QAAE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC9F,aAAa,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACrD,0HAA0H;IAC1H,UAAU,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC7F,WAAW,CAAC,CACV,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,SAAS;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC,CAAC;IACvE,QAAQ,CAAC,KAAK,EAAE;QACd,MAAM,CAAC,KAAK,EAAE;YACZ,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;YACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;YACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;SACxC,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;QAC/B,kHAAkH;QAClH,MAAM,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;KACvD,CAAC;IACF,kGAAkG;IAClG,UAAU,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,MAAM,CAAC;IAC7E,wDAAwD;IACxD,MAAM,CAAC,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,GAAG,SAAS,CAAC;CAC/C;AAED,MAAM,MAAM,iBAAiB;AAC3B,qCAAqC;AACnC,OAAO;AACT,wDAAwD;GACtD,OAAO,GACP,QAAQ;AACV,wFAAwF;GACtF,OAAO;AACT,4FAA4F;GAC1F,UAAU,CAAC;AAEf,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAChF;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE,CAAC;AAE9E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,4CAA4C;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,KAAK,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAC7C,sEAAsE;IACtE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9C,mGAAmG;IACnG,QAAQ,CAAC,QAAQ,EACb;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,GACrE,SAAS,CAAC;CACf;AAED,oEAAoE;AACpE,MAAM,WAAW,KAAK;IACpB,GAAG,IAAI,MAAM,CAAC;IACd,UAAU,CAAC,OAAO,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IACrD,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;CACrC"}

package/dist/persistence/types.js

@@ -0,0 +1 @@
+export {};

package/dist/preview/index.d.ts

@@ -0,0 +1,3 @@
+export { isSafePreviewUrl, type PreviewResult, preparePreview } from './prepare.ts';
+export { PreviewOverlay, type PreviewOverlayProps, type UsePreview, type UsePreviewOptions, usePreview, } from './preview.tsx';
+//# sourceMappingURL=index.d.ts.map

package/dist/preview/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/preview/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,KAAK,aAAa,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACpF,OAAO,EACL,cAAc,EACd,KAAK,mBAAmB,EACxB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,UAAU,GACX,MAAM,eAAe,CAAC"}

package/dist/preview/index.js

@@ -0,0 +1,2 @@
+export { isSafePreviewUrl, preparePreview } from './prepare.js';
+export { PreviewOverlay, usePreview, } from './preview.js';

package/dist/preview/prepare.d.ts

@@ -0,0 +1,16 @@
+import type { DocumentAdapter, DocumentRef, PersistenceController } from '../persistence/index.ts';
+export type PreviewResult = {
+    readonly ok: true;
+    readonly url: string;
+} | {
+    readonly ok: false;
+    readonly reason: 'unsaved' | 'unsafe-url';
+};
+/** Only pages of the site itself or of another web address; never a `javascript:` or `data:` URL. */
+export declare function isSafePreviewUrl(url: string): boolean;
+/**
+ * Makes the preview show the latest changes: saves what is unsaved first, and only then asks the
+ * adapter for the draft URL. A preview of a document that could not be saved would show old work.
+ */
+export declare function preparePreview(controller: Pick<PersistenceController, 'saveNow' | 'state'>, adapter: Pick<DocumentAdapter, 'previewUrl'>, ref: DocumentRef): Promise<PreviewResult>;
+//# sourceMappingURL=prepare.d.ts.map

package/dist/preview/prepare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepare.d.ts","sourceRoot":"","sources":["../../src/preview/prepare.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAEnG,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC3C;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,YAAY,CAAA;CAAE,CAAC;AAEtE,qGAAqG;AACrG,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOrD;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,UAAU,EAAE,IAAI,CAAC,qBAAqB,EAAE,SAAS,GAAG,OAAO,CAAC,EAC5D,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,YAAY,CAAC,EAC5C,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,aAAa,CAAC,CAKxB"}

package/dist/preview/prepare.js

@@ -0,0 +1,21 @@
+/** Only pages of the site itself or of another web address; never a `javascript:` or `data:` URL. */
+export function isSafePreviewUrl(url) {
+    try {
+        const parsed = new URL(url, 'http://localhost');
+        return parsed.protocol === 'http:' || parsed.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Makes the preview show the latest changes: saves what is unsaved first, and only then asks the
+ * adapter for the draft URL. A preview of a document that could not be saved would show old work.
+ */
+export async function preparePreview(controller, adapter, ref) {
+    await controller.saveNow();
+    if (controller.state.getState().status !== 'clean')
+        return { ok: false, reason: 'unsaved' };
+    const url = adapter.previewUrl(ref, { draft: true });
+    return isSafePreviewUrl(url) ? { ok: true, url } : { ok: false, reason: 'unsafe-url' };
+}

package/dist/preview/preview.d.ts

@@ -0,0 +1,27 @@
+import { type ReactNode } from 'react';
+import { type DocumentAdapter, type DocumentRef } from '../persistence/index.ts';
+export interface PreviewOverlayProps {
+    readonly url: string;
+    readonly onExit: () => void;
+}
+/** The page as visitors get it, over the whole editor; Escape or the button leaves it. */
+export declare function PreviewOverlay({ url, onExit }: PreviewOverlayProps): import("react").JSX.Element;
+export interface UsePreviewOptions {
+    readonly adapter: Pick<DocumentAdapter, 'previewUrl'>;
+    readonly docRef: DocumentRef;
+    /** `overlay` (default) shows the page inside the editor, `tab` opens a new browser tab. */
+    readonly target?: 'overlay' | 'tab' | undefined;
+    /** Opens a tab; `window.open` unless a test gives another. */
+    readonly open?: ((url: string) => void) | undefined;
+}
+export interface UsePreview {
+    /** For the toolbar's `onPreview`. */
+    readonly preview: () => void;
+    /** Render this somewhere in the shell. */
+    readonly overlay: ReactNode;
+    /** Why the last attempt failed, as a message for a live region; empty when it did not. */
+    readonly error: string;
+}
+/** Saves, then shows the preview (docs/editor.md#preview). */
+export declare function usePreview(options: UsePreviewOptions): UsePreview;
+//# sourceMappingURL=preview.d.ts.map

package/dist/preview/preview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../src/preview/preview.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAoC,MAAM,OAAO,CAAC;AAEzE,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,WAAW,EAAkB,MAAM,yBAAyB,CAAC;AAIjG,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC;CAC7B;AAED,0FAA0F;AAC1F,wBAAgB,cAAc,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,mBAAmB,+BA0BlE;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,YAAY,CAAC,CAAC;IACtD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,2FAA2F;IAC3F,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,GAAG,KAAK,GAAG,SAAS,CAAC;IAChD,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CACrD;AAED,MAAM,WAAW,UAAU;IACzB,qCAAqC;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;IAC7B,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B,0FAA0F;IAC1F,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,8DAA8D;AAC9D,wBAAgB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,UAAU,CA6BjE"}

package/dist/preview/preview.js

@@ -0,0 +1,51 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useState } from 'react';
+import { useT } from '../messages/index.js';
+import { usePersistence } from '../persistence/index.js';
+import { Button } from '../ui/index.js';
+import { preparePreview } from './prepare.js';
+/** The page as visitors get it, over the whole editor; Escape or the button leaves it. */
+export function PreviewOverlay({ url, onExit }) {
+    const t = useT();
+    useEffect(() => {
+        const onKey = (event) => {
+            if (event.key === 'Escape')
+                onExit();
+        };
+        window.addEventListener('keydown', onKey);
+        return () => window.removeEventListener('keydown', onKey);
+    }, [onExit]);
+    return (_jsxs("div", { className: "bd-preview", role: "dialog", "aria-modal": "true", "aria-label": t('preview.title'), children: [_jsxs("div", { className: "bd-preview-bar", children: [_jsx("span", { children: t('preview.title') }), _jsx(Button, { variant: "primary", onClick: onExit, autoFocus: true, children: t('preview.exit') })] }), _jsx("iframe", { className: "bd-preview-frame", title: t('preview.frame'), src: url, sandbox: "allow-scripts allow-same-origin allow-forms allow-popups", referrerPolicy: "no-referrer" })] }));
+}
+/** Saves, then shows the preview (docs/editor.md#preview). */
+export function usePreview(options) {
+    const { adapter, docRef, target = 'overlay', open } = options;
+    const t = useT();
+    const controller = usePersistence();
+    const [url, setUrl] = useState();
+    const [error, setError] = useState('');
+    const preview = useCallback(() => {
+        setError('');
+        void preparePreview(controller, adapter, docRef).then((result) => {
+            if (!result.ok) {
+                setError(t(result.reason === 'unsaved' ? 'preview.unsaved' : 'preview.unsafe'));
+                return;
+            }
+            if (target === 'tab') {
+                if (open !== undefined)
+                    open(result.url);
+                else
+                    window.open(result.url, '_blank', 'noopener,noreferrer');
+            }
+            else {
+                setUrl(result.url);
+            }
+        });
+    }, [controller, adapter, docRef, target, open, t]);
+    const exit = useCallback(() => setUrl(undefined), []);
+    return {
+        preview,
+        error,
+        overlay: url === undefined ? null : _jsx(PreviewOverlay, { url: url, onExit: exit }),
+    };
+}

package/dist/preview/preview.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=preview.test.d.ts.map

package/dist/preview/preview.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview.test.d.ts","sourceRoot":"","sources":["../../src/preview/preview.test.tsx"],"names":[],"mappings":""}

package/dist/preview/preview.test.js

@@ -0,0 +1,129 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// @vitest-environment jsdom
+import { createRegistryMeta, createSeededIdGenerator, } from '@next-buildr/core';
+import { act } from 'react';
+import { createRoot } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { MessagesProvider } from '../messages/index.js';
+import { createPersistence, PersistenceProvider } from '../persistence/index.js';
+import { createEditorStore, EditorStoreProvider } from '../store/index.js';
+import { ToastProvider } from '../ui/index.js';
+import { isSafePreviewUrl } from './prepare.js';
+import { usePreview } from './preview.js';
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+const item = {
+    type: 'buildr/item',
+    version: 1,
+    label: 'Item',
+    category: 'content',
+    props: {},
+    contentCategories: ['flow'],
+    styles: { groups: [] },
+    runtime: 'shared',
+    slots: { default: {} },
+};
+const page = {
+    ...item,
+    type: 'buildr/page',
+    label: 'Page',
+    capabilities: { root: true },
+};
+const registry = createRegistryMeta({ components: [page, item] });
+const doc = () => ({
+    schemaVersion: 1,
+    root: 'root',
+    nodes: {
+        root: { id: 'root', type: 'buildr/page', slots: { default: ['itemAAAAA1'] } },
+        itemAAAAA1: { id: 'itemAAAAA1', type: 'buildr/item' },
+    },
+    components: { 'buildr/page': 1, 'buildr/item': 1 },
+});
+const ref = { collection: 'pages', id: '1' };
+describe('preview', () => {
+    let container;
+    let root;
+    beforeEach(() => {
+        container = document.createElement('div');
+        document.body.append(container);
+        root = createRoot(container);
+    });
+    afterEach(() => {
+        act(() => root.unmount());
+        document.body.innerHTML = '';
+    });
+    it('accepts web addresses only', () => {
+        expect(isSafePreviewUrl('/blog?draft=1')).toBe(true);
+        expect(isSafePreviewUrl('https://site.test/a')).toBe(true);
+        expect(isSafePreviewUrl('javascript:alert(1)')).toBe(false);
+        expect(isSafePreviewUrl('data:text/html,x')).toBe(false);
+    });
+    function setup(opts) {
+        const order = [];
+        const adapter = {
+            save: async () => {
+                order.push('save');
+                return (await opts.save?.()) ?? { ok: true, revision: 2, updatedAt: 't' };
+            },
+            previewUrl: () => {
+                order.push('url');
+                return opts.url ?? '/preview/1';
+            },
+        };
+        const store = createEditorStore({
+            doc: doc(),
+            registry,
+            generateId: createSeededIdGenerator(2),
+            validationDelayMs: null,
+        });
+        const controller = createPersistence({ store, adapter, ref, revision: 1 });
+        const open = vi.fn((url) => void order.push(`open:${url}`));
+        let api;
+        function Probe() {
+            api = usePreview({ adapter, docRef: ref, target: opts.target, open });
+            return (_jsxs(_Fragment, { children: [api.overlay, _jsx("p", { role: "status", children: api.error })] }));
+        }
+        const mount = () => act(async () => root.render(_jsx(MessagesProvider, { locale: "en", children: _jsx(EditorStoreProvider, { store: store, children: _jsx(ToastProvider, { children: _jsx(PersistenceProvider, { controller: controller, children: _jsx(Probe, {}) }) }) }) })));
+        const edit = () => act(() => {
+            store.dispatch({
+                type: 'node.setAttr',
+                payload: { id: 'itemAAAAA1', key: 'name', value: 'A' },
+            });
+        });
+        return { order, mount, edit, run: () => act(async () => api.preview()) };
+    }
+    it('saves before it asks for the address, then shows the page in an overlay', async () => {
+        const { order, mount, edit, run } = setup({});
+        await mount();
+        edit();
+        await run();
+        expect(order).toEqual(['save', 'url']);
+        const frame = container.ownerDocument.querySelector('iframe');
+        expect(frame.getAttribute('src')).toBe('/preview/1');
+        await act(async () => window.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape' })));
+        expect(document.querySelector('iframe')).toBeNull();
+    });
+    it('opens a tab after the save when asked to', async () => {
+        const { order, mount, edit, run } = setup({ target: 'tab' });
+        await mount();
+        edit();
+        await run();
+        expect(order).toEqual(['save', 'url', 'open:/preview/1']);
+    });
+    it('does not preview old work when the save failed', async () => {
+        const { mount, edit, run } = setup({
+            save: async () => ({ ok: false, kind: 'invalid', diagnostics: [] }),
+        });
+        await mount();
+        edit();
+        await run();
+        expect(document.querySelector('iframe')).toBeNull();
+        expect(container.textContent).toContain('could not be saved');
+    });
+    it('refuses an address that is not a web address', async () => {
+        const { mount, run } = setup({ url: 'javascript:alert(1)' });
+        await mount();
+        await run();
+        expect(document.querySelector('iframe')).toBeNull();
+        expect(container.textContent).toContain('not a web address');
+    });
+});

package/dist/shortcuts/actions.d.ts

@@ -0,0 +1,17 @@
+import type { EditorStore } from '../store/index.ts';
+import type { ShortcutRegistry } from './registry.ts';
+/** What the editor's own shortcuts need from outside: the actions of other modules (PB-085, PB-087). */
+export interface ExternalActions {
+    readonly copy?: () => boolean | undefined;
+    readonly cut?: () => boolean | undefined;
+    readonly paste?: () => boolean | undefined;
+    readonly save?: () => boolean | undefined;
+}
+/**
+ * Binds the shortcuts that act on the store (undo, redo, duplicate, delete, move, select, clear)
+ * and the ones other modules provide. Returns the function that unbinds them all. An action that
+ * cannot run (nothing selected, a locked node the command refuses) returns `false`, so the key is
+ * not swallowed.
+ */
+export declare function bindEditorActions(registry: ShortcutRegistry, store: EditorStore, external?: ExternalActions): () => void;
+//# sourceMappingURL=actions.d.ts.map

package/dist/shortcuts/actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../../src/shortcuts/actions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,wGAAwG;AACxG,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,OAAO,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,OAAO,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,OAAO,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,OAAO,GAAG,SAAS,CAAC;CAC3C;AAyCD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,gBAAgB,EAC1B,KAAK,EAAE,WAAW,EAClB,QAAQ,GAAE,eAAoB,GAC7B,MAAM,IAAI,CAiCZ"}

package/dist/shortcuts/actions.js

@@ -0,0 +1,85 @@
+import { createIndex } from '@next-buildr/core';
+/** The selected nodes that can be acted on: the root is never removed, duplicated or moved. */
+function actionable(store) {
+    const { doc, selectedIds } = store.getState();
+    return selectedIds.filter((id) => id !== doc.root && Object.hasOwn(doc.nodes, id));
+}
+function moveSelected(store, delta) {
+    const ids = actionable(store);
+    const [id] = ids;
+    if (ids.length !== 1 || id === undefined)
+        return false;
+    const { doc } = store.getState();
+    const index = createIndex(doc);
+    const parentId = index.parentOf[id];
+    const slot = index.slotOf[id];
+    const position = index.indexOf[id];
+    if (parentId === undefined || slot === undefined || position === undefined)
+        return false;
+    const siblings = doc.nodes[parentId]?.slots?.[slot] ?? [];
+    const target = position + delta;
+    if (target < 0 || target >= siblings.length)
+        return false;
+    // `index` is a position in the slot as it is now, so moving down passes the neighbour.
+    const result = store.dispatch({
+        type: 'node.move',
+        payload: { ids: [id], parentId, slot, index: delta === -1 ? target : target + 1 },
+    });
+    return result.ok;
+}
+function selectAll(store) {
+    const { doc, anchorId } = store.getState();
+    if (anchorId === null)
+        return false;
+    const index = createIndex(doc);
+    const parentId = index.parentOf[anchorId];
+    const slot = index.slotOf[anchorId];
+    if (parentId === undefined || slot === undefined)
+        return false;
+    const siblings = doc.nodes[parentId]?.slots?.[slot] ?? [];
+    store.setSelection(siblings);
+    return true;
+}
+/**
+ * Binds the shortcuts that act on the store (undo, redo, duplicate, delete, move, select, clear)
+ * and the ones other modules provide. Returns the function that unbinds them all. An action that
+ * cannot run (nothing selected, a locked node the command refuses) returns `false`, so the key is
+ * not swallowed.
+ */
+export function bindEditorActions(registry, store, external = {}) {
+    const stops = [
+        registry.bind('edit.undo', () => store.undo().ok),
+        registry.bind('edit.redo', () => store.redo().ok),
+        registry.bind('edit.duplicate', () => {
+            const ids = actionable(store);
+            return ids.length > 0 && store.dispatch({ type: 'node.duplicate', payload: { ids } }).ok;
+        }),
+        registry.bind('edit.delete', () => {
+            const ids = actionable(store);
+            return ids.length > 0 && store.dispatch({ type: 'node.remove', payload: { ids } }).ok;
+        }),
+        registry.bind('node.moveUp', () => moveSelected(store, -1)),
+        registry.bind('node.moveDown', () => moveSelected(store, 1)),
+        registry.bind('selection.all', () => selectAll(store)),
+        registry.bind('selection.clear', () => {
+            if (store.getState().selectedIds.length === 0)
+                return false;
+            store.clearSelection();
+            return true;
+        }),
+    ];
+    const optional = {
+        'edit.copy': external.copy,
+        'edit.cut': external.cut,
+        'edit.paste': external.paste,
+        'file.save': external.save,
+    };
+    for (const [action, handler] of Object.entries(optional)) {
+        if (handler !== undefined)
+            stops.push(registry.bind(action, handler));
+    }
+    return () => {
+        for (const stop of stops)
+            stop();
+    };
+}

package/dist/shortcuts/index.d.ts

@@ -0,0 +1,11 @@
+export type { ExternalActions } from './actions.ts';
+export { bindEditorActions } from './actions.ts';
+export type { KeyInput, Platform } from './keys.ts';
+export { comboOf, detectPlatform, displayCombo, isTypingTarget, normalizeCombo } from './keys.ts';
+export type { ShortcutDef } from './map.ts';
+export { applyOverrides, DEFAULT_SHORTCUTS } from './map.ts';
+export type { ShortcutHandler, ShortcutRegistry, ShortcutRegistryOptions } from './registry.ts';
+export { createShortcutRegistry } from './registry.ts';
+export type { ShortcutProviderProps } from './shortcuts.tsx';
+export { ShortcutProvider, useForwardedKeys, useOptionalShortcutRegistry, useShortcutHint, useShortcutRegistry, } from './shortcuts.tsx';
+//# sourceMappingURL=index.d.ts.map

package/dist/shortcuts/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/shortcuts/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAClG,YAAY,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7D,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAChG,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACvD,YAAY,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,2BAA2B,EAC3B,eAAe,EACf,mBAAmB,GACpB,MAAM,iBAAiB,CAAC"}

package/dist/shortcuts/index.js

@@ -0,0 +1,5 @@
+export { bindEditorActions } from './actions.js';
+export { comboOf, detectPlatform, displayCombo, isTypingTarget, normalizeCombo } from './keys.js';
+export { applyOverrides, DEFAULT_SHORTCUTS } from './map.js';
+export { createShortcutRegistry } from './registry.js';
+export { ShortcutProvider, useForwardedKeys, useOptionalShortcutRegistry, useShortcutHint, useShortcutRegistry, } from './shortcuts.js';

package/dist/shortcuts/keys.d.ts

@@ -0,0 +1,29 @@
+/** A key press as the editor sees it, from the DOM or forwarded by the canvas (`key:down`). */
+export interface KeyInput {
+    readonly key: string;
+    readonly mods: {
+        readonly shift: boolean;
+        readonly alt: boolean;
+        readonly ctrl: boolean;
+        readonly meta: boolean;
+    };
+}
+/** Which key is the "primary" one: Cmd on a Mac, Ctrl elsewhere. */
+export type Platform = 'mac' | 'other';
+export declare function detectPlatform(navigatorLike?: {
+    readonly platform?: string;
+    readonly userAgent?: string;
+} | undefined): Platform;
+/**
+ * The canonical text of a combination: modifiers in a fixed order (`mod` is Cmd on a Mac and Ctrl
+ * elsewhere), then the key, all lower case — `mod+shift+z`, `alt+arrowup`, `delete`. Two spellings
+ * of one combination give the same text, so a lookup is a plain string comparison.
+ */
+export declare function normalizeCombo(spec: string): string;
+/** The canonical combination of a key press on `platform`. */
+export declare function comboOf(input: KeyInput, platform: Platform): string;
+/** How a combination is shown to the author on `platform` (`⌘⇧Z`, `Ctrl+Shift+Z`). */
+export declare function displayCombo(combo: string, platform: Platform): string;
+/** The keyboard belongs to text here: a field, a select or an editable region. */
+export declare function isTypingTarget(target: EventTarget | null): boolean;
+//# sourceMappingURL=keys.d.ts.map

package/dist/shortcuts/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../src/shortcuts/keys.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE;QACb,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;QACxB,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;QACtB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;QACvB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;KACxB,CAAC;CACH;AAED,oEAAoE;AACpE,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,OAAO,CAAC;AAEvC,wBAAgB,cAAc,CAC5B,aAAa,GACT;IAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3D,SAAoE,GACvE,QAAQ,CAGV;AAcD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAUnD;AAED,8DAA8D;AAC9D,wBAAgB,OAAO,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAWnE;AAkCD,sFAAsF;AACtF,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAMtE;AAED,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,GAAG,OAAO,CAelE"}