@b10cks/client 1.11.0 → 2.0.0

package/dist/index.d.ts

@@ -57,10 +57,12 @@ declare type ApiQueryParams = Omit<IBBaseQueryParams, 'token'> & Record<string,
 declare type ApiResourceResponse<T> = IBResponse<T> | T;
 
 /**
- * Wire a DOM element as a selectable block: click selects it in the editor,
- * and editor-driven select/hover toggle outline classes. Honors the configured
- * scroll offset and only scrolls when the element isn't already in view.
- * Returns a cleanup function. No-op outside preview mode.
+ * Wire a DOM element as a selectable block. A click selects it in the editor
+ * and never reaches links or buttons inside it. Only the innermost editable
+ * under the pointer or matching the editor's selection is highlighted, with a
+ * label. Toggles `b10cks-selected`, `b10cks-hover`, and `b10cks-hidden` (while
+ * the editor hides the block) on the element. Returns a
+ * cleanup function. No-op outside preview mode.
  */
 export declare function attachEditable(el: HTMLElement, options: AttachEditableOptions): () => void;
 
@@ -84,16 +86,52 @@ export declare interface AttachEditableFieldOptions {
      * targets a complex value.
      */
     mode?: EditableFieldMode;
+    /** Label for `select` mode. Defaults to the field name. */
+    label?: string;
 }
 
 export declare interface AttachEditableOptions {
     id: string;
+    /** Shown on the selection and hover label. A slug like `hero_section` reads as `Hero section`. */
+    label?: string;
     onSelectChange?: (selected: boolean) => void;
     onHoverChange?: (hovered: boolean) => void;
     /** Scroll the element into view when it becomes selected. Default true. */
     scrollOnSelect?: boolean;
 }
 
+/**
+ * Make a rendered rich text field editable in place in the preview. A click
+ * selects the field in the editor, which answers with the field's settings
+ * when the user may edit it; the element then turns into a Tiptap editor with
+ * the CMS schema. Edits stream to the editor as FIELD_UPDATE, and changes made
+ * in the editor arrive through {@link RichTextFieldHandle.update} without
+ * moving the caret. Escape returns to block selection.
+ *
+ * Without the editor's go-ahead (older editors, read-only users) the field
+ * behaves like `attachEditableField` in `select` mode. No-op outside preview
+ * mode, where Tiptap is never loaded.
+ */
+export declare function attachRichTextField(el: HTMLElement, options: AttachRichTextFieldOptions): RichTextFieldHandle;
+
+export declare interface AttachRichTextFieldOptions {
+    /** Id of the block the field belongs to. */
+    id: string;
+    /** Path to the field within the block. */
+    path: FieldPath;
+    /** The field's document, as rendered into the element. */
+    document: RichTextDocument | null | undefined;
+    /** Shown on the field's highlight. Defaults to the field name. */
+    label?: string;
+    /** The options the element was rendered with, so links and placeholders look the same while editing. */
+    render?: RichTextHtmlOptions;
+    /**
+     * Editing started or stopped. While it runs the editor owns the element's
+     * content, so keep rendering the HTML you rendered before it started.
+     */
+    onEditingChange?: (editing: boolean) => void;
+}
+
 export declare interface B10cksApiClientOptions {
     baseUrl: string;
     token: string;
@@ -321,6 +359,19 @@ export declare interface B10cksLinkResolved {
  */
 export declare function bindPreviewStore<T>(store: PreviewStore<T>): () => void;
 
+/** `hide` and `show` set the block's visibility and do nothing when it already is. */
+export declare type BlockAction = 'move-up' | 'move-down' | 'duplicate' | 'delete' | 'insert-before' | 'insert-after' | 'hide' | 'show';
+
+/**
+ * Ask the editor to run a structural action on a block. The editor validates
+ * it, applies it, and answers with CONTENT_UPDATE (and SELECT_UPDATE where the
+ * selection moves). `insert-*` opens the editor's block picker.
+ */
+export declare type BlockActionEvent = {
+    itemId: string;
+    action: BlockAction;
+};
+
 /**
  * Attributes that make a block addressable as a link anchor: `{ id: block.id }`.
  *
@@ -334,6 +385,21 @@ export declare function blockAnchorAttrs(block: {
     id?: string;
 };
 
+/** Display names of the space's blocks, keyed by block slug. */
+export declare type BlockLabelsEvent = {
+    labels: Record<string, string>;
+};
+
+/**
+ * Drag and drop: move block `itemId` before or after block `targetId`. The
+ * editor rejects moves its schema doesn't allow and answers like BLOCK_ACTION.
+ */
+export declare type BlockMoveEvent = {
+    itemId: string;
+    targetId: string;
+    position: 'before' | 'after';
+};
+
 /**
  * Renders a trail as a schema.org `BreadcrumbList`, ready to be serialized into
  * an `application/ld+json` script tag.
@@ -363,12 +429,28 @@ export declare interface BreadcrumbListJsonLd {
     itemListElement: BreadcrumbListItem[];
 }
 
+/**
+ * Bridge protocol version, sent with the ready announcement. Previews that
+ * announce without a payload (protocol 0) understand CONTENT_UPDATE,
+ * SELECT_UPDATE, HOVER_UPDATE, and CONTENT_PATCH relative to the root only, so
+ * the editor must not send them block-relative patches or labels. Protocol 1
+ * adds those and the block actions, protocol 2 HIDDEN_BLOCKS and the `hide`
+ * and `show` block actions, protocol 3 FIELD_CONFIG for in-place rich text
+ * editing.
+ */
+export declare const BRIDGE_PROTOCOL = 3;
+
 export declare type BridgeEvent = {
     type: EventType;
     payload: EventPayloadMap[EventType];
     b10cksId?: string;
 };
 
+/** Payload of the ready announcement. */
+export declare type BridgeReadyPayload = {
+    protocol: number;
+};
+
 /**
  * Combines a b10cks `full_slug` and `language_iso` into a rooted, locale-prefixed path.
  *
@@ -381,8 +463,12 @@ export declare interface CollectionFetchOptions {
     allPages?: boolean;
 }
 
-/** Granular update: replace the value at `path` within the content tree. */
+/**
+ * Granular update: replace the value at `path`. With `itemId`, `path` is
+ * relative to that block; without it, relative to the content tree's root.
+ */
 export declare type ContentPatchEvent = {
+    itemId?: string;
     path: FieldPath;
     value: unknown;
 };
@@ -430,13 +516,17 @@ export declare type DateFilter = string | {
 
 export declare type EditableFieldMode = 'inline' | 'select';
 
+/** The field a rich text component renders, for its `editable` prop. */
+export declare type EditableRichTextField = Pick<AttachRichTextFieldOptions, 'id' | 'path' | 'label'>;
+
 export declare type Endpoint = 'blocks' | `blocks/${string}` | `breadcrumbs/${string}` | 'contents' | `contents/${string}` | `datasources/${string}/entries` | 'datasources' | 'redirects' | 'search' | 'sitemap' | `sitemaps/${string}` | 'spaces/me';
 
 /**
- * Inject the preview outline styles once. Selected/hovered blocks get an
- * outline; `.b10cks-preview` carries a `scroll-margin-top` so scroll-into-view
- * clears a fixed app header. Set the offset via {@link setPreviewScrollOffset}
- * or the `--b10cks-scroll-offset` CSS variable.
+ * Inject the preview styles once: `.b10cks-preview` carries a
+ * `scroll-margin-top` so scroll-into-view clears a fixed app header. Set the
+ * offset via {@link setPreviewScrollOffset} or the `--b10cks-scroll-offset`
+ * CSS variable. Blocks the editor hides carry `b10cks-hidden` and are dimmed.
+ * Selection and hover are drawn in a separate overlay layer.
  */
 export declare function ensurePreviewStyles(): void;
 
@@ -449,12 +539,28 @@ export declare type EventPayloadMap = {
     HOVER_UPDATE: SelectUpdateEvent;
     FIELD_UPDATE: FieldUpdateEvent;
     FIELD_SELECT: FieldSelectEvent;
+    FIELD_CONFIG: FieldConfigEvent;
+    BLOCK_LABELS: BlockLabelsEvent;
+    HIDDEN_BLOCKS: HiddenBlocksEvent;
+    BLOCK_ACTION: BlockActionEvent;
+    BLOCK_MOVE: BlockMoveEvent;
 };
 
-export declare type EventType = 'CONTENT_UPDATE' | 'CONTENT_PATCH' | 'SELECT_UPDATE' | 'HOVER_UPDATE' | 'FIELD_UPDATE' | 'FIELD_SELECT';
+export declare type EventType = 'CONTENT_UPDATE' | 'CONTENT_PATCH' | 'SELECT_UPDATE' | 'HOVER_UPDATE' | 'FIELD_UPDATE' | 'FIELD_SELECT' | 'FIELD_CONFIG' | 'BLOCK_LABELS' | 'HIDDEN_BLOCKS' | 'BLOCK_ACTION' | 'BLOCK_MOVE';
 
 export declare type FetchClient = (input: URL | string | RequestInfo, init?: RequestInit) => Promise<unknown>;
 
+/**
+ * The editor's answer to FIELD_SELECT for a rich text field the user may edit:
+ * the preview can edit it in place, with the field's settings. Not sent for
+ * read-only users or other field types. Protocol 3.
+ */
+export declare type FieldConfigEvent = {
+    itemId: string;
+    path: FieldPath;
+    richtext: RichTextFieldConfig;
+};
+
 /** Addresses a field within a block, supporting nested objects and arrays. */
 export declare type FieldPath = (string | number)[];
 
@@ -499,6 +605,14 @@ export declare interface GetConfigOptions extends Omit<IBContentQueryParams, 'to
     bypassCache?: boolean;
 }
 
+/**
+ * Ids of every block in the edited content, at any depth, that is hidden.
+ * Sent whenever that set changes. Protocol 2.
+ */
+export declare type HiddenBlocksEvent = {
+    ids: string[];
+};
+
 export declare interface IBBaseQueryParams extends IBPaginationParams, IBSortParams {
     vid?: string;
     version?: string;
@@ -864,6 +978,8 @@ export declare function normalizePathSegment(value: string | null | undefined):
 export declare class PreviewBridge {
     private static instance;
     private readonly listeners;
+    /** Last payload received per event type, for consumers that attach late. */
+    private readonly received;
     private initialized;
     private allowedOrigins;
     /** Origin of the editor, captured from the first trusted message. */
@@ -874,6 +990,11 @@ export declare class PreviewBridge {
     destroy(): void;
     isInPreviewMode(): boolean;
     on<T extends EventType>(eventType: T, callback: EventCallback<EventPayloadMap[T]>): () => void;
+    /**
+     * The last payload the editor sent for `eventType`. The editor replays state
+     * right after the ready announcement, often before components mount.
+     */
+    latest<T extends EventType>(eventType: T): EventPayloadMap[T] | undefined;
     selectItem(selectedItem: string): void;
     /** Deep-select a nested field (e.g. a rich text field) in the editor. */
     selectField(itemId: string, path: FieldPath): void;
@@ -881,6 +1002,16 @@ export declare class PreviewBridge {
     updateField(itemId: string, field: string, value: string): void;
     /** Stream an inline edit back to the editor, addressed by path. */
     updateFieldAt(itemId: string, path: FieldPath, value: unknown): void;
+    /**
+     * Apply a patch to the preview's own content, as if the editor had sent it.
+     * For edits made in the preview itself, which the editor doesn't echo back,
+     * so a content store rendering the page stays current.
+     */
+    patchLocal(patch: ContentPatchEvent): void;
+    /** Ask the editor to move, duplicate, delete, hide, show, or insert next to a block. */
+    blockAction(itemId: string, action: BlockAction): void;
+    /** Ask the editor to move a block before or after another block. */
+    moveBlock(itemId: string, targetId: string, position: BlockMoveEvent['position']): void;
     private post;
     private handleMessage;
     private isOriginTrusted;
@@ -916,7 +1047,11 @@ export declare class PreviewStore<T = Record<string, unknown>> {
      * Unknown ids are ignored and do not notify subscribers.
      */
     applyContentUpdate(update: Record<string, unknown>): void;
-    patch(path: FieldPath, value: unknown): void;
+    /**
+     * Replace the value at `path`. With `itemId`, `path` is relative to that
+     * block (the root when its id matches). Unknown ids are ignored.
+     */
+    patch(path: FieldPath, value: unknown, itemId?: string): void;
     private emit;
 }
 
@@ -955,13 +1090,104 @@ export declare function renderSitemapXml(entries: IBSitemapEntry[], siteUrl?: st
  */
 export declare function resolveB10cksLink(link: B10cksLink | undefined | null): B10cksLinkResolved | undefined;
 
+declare interface RichTextDocument {
+    type: string
+    content?: RichTextDocument[]
+    text?: string
+    marks?: RichTextMark[]
+    attrs?: Record<string, unknown>
+}
+
+/** Features a rich text field can switch off in the CMS field settings. */
+declare type RichTextFeature =
+| 'bold'
+| 'italic'
+| 'underline'
+| 'strike'
+| 'code'
+| 'heading'
+| 'bulletList'
+| 'orderedList'
+| 'blockquote'
+| 'codeBlock'
+| 'horizontalRule'
+| 'link'
+| 'internalLink'
+| 'table'
+
+/** How a rich text field is configured in the CMS. */
+declare interface RichTextFieldConfig {
+    /** A feature is on unless set to `false`, like in the CMS. */
+    features?: Partial<Record<RichTextFeature, boolean>>
+    /** Block formats the toolbar offers, in order. */
+    headingLevels?: RichTextHeadingLevel[]
+}
+
+export declare interface RichTextFieldHandle {
+    /** Pass the field's latest document whenever it changes. */
+    update: (document: RichTextDocument | null | undefined) => void;
+    destroy: () => void;
+}
+
+declare type RichTextHeadingLevel = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p'
+
+declare interface RichTextHtmlOptions {
+    internalLinkHandler?: RichTextInternalLinkHandler
+    placeholderHandler?: RichTextPlaceholderHandler
+    /**
+     * URL schemes (without the trailing colon) permitted in link `href` and
+     * image `src` attributes. URLs with any other scheme are replaced with `'#'`
+     * to prevent script-injecting URLs (e.g. `javascript:`) stored in CMS
+     * content from executing. Relative URLs are always allowed.
+     *
+     * Defaults to {@link DEFAULT_ALLOWED_SCHEMES}. To additionally allow
+     * `javascript:` URLs, pass
+     * `[...DEFAULT_ALLOWED_SCHEMES, 'javascript']`.
+     */
+    allowedSchemes?: string[]
+}
+
+declare interface RichTextInternalLinkAttrs {
+    url?: string | null
+    href?: string | null
+    title?: string | null
+    target?: string | null
+    rel?: string | null
+    anchor?: string | null
+    content?: string | null
+    cached_url?: string | null
+    linktype?: string | null
+    uuid?: string | null
+    id?: string | null
+    [key: string]: unknown
+}
+
+declare type RichTextInternalLinkHandler = (
+attrs: RichTextInternalLinkAttrs
+) => string | null | undefined
+
+declare interface RichTextMark {
+    type: string
+    attrs?: Record<string, unknown>
+}
+
+/**
+ * Resolves a placeholder token to its real value.
+ * Receives the token's `key` (e.g. `"companyName"`) and `label` (the display
+ * hint shown in the editor, e.g. `"{companyName}"`).
+ * Return the replacement string, or null/undefined to leave the token as-is
+ * (rendered as a `<span data-type="placeholder-token">` for client-side use).
+ */
+declare type RichTextPlaceholderHandler = (key: string, label: string) => string | null | undefined
+
 export declare type RootBlock<T> = T & {
     id: string;
     block: string;
 };
 
+/** `selectedItem` is null when the editor clears the selection or hover. */
 export declare type SelectUpdateEvent = {
-    selectedItem: string;
+    selectedItem: string | null;
 };
 
 export declare function serializeFilter(filter: Record<string, unknown>): Record<string, string>;