@b10cks/client 1.12.0 → 2.0.1

package/dist/index.d.ts

@@ -81,9 +81,9 @@ export declare interface AttachEditableFieldOptions {
      * `inline` makes the element contenteditable and streams plain-text edits
      * back to the editor — suitable for simple string fields only. `select`
      * instead deep-selects the field so the editor opens its own editor, which
-     * is the right choice for rich text and other complex types. Default
-     * `inline`, or `select` automatically when no `field` is given but a `path`
-     * targets a complex value.
+     * is the right choice for rich text and other complex types. Defaults to
+     * `select` for path-only fields and fields wrapping interactive children;
+     * other flat fields default to `inline`.
      */
     mode?: EditableFieldMode;
     /** Label for `select` mode. Defaults to the field name. */
@@ -100,6 +100,38 @@ export declare interface AttachEditableOptions {
     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;
@@ -402,10 +434,11 @@ export declare interface BreadcrumbListJsonLd {
  * 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 adds HIDDEN_BLOCKS and the `hide` and `show` block
- * actions.
+ * 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 = 2;
+export declare const BRIDGE_PROTOCOL = 3;
 
 export declare type BridgeEvent = {
     type: EventType;
@@ -483,6 +516,9 @@ 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';
 
 /**
@@ -503,16 +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' | 'BLOCK_LABELS' | 'HIDDEN_BLOCKS' | 'BLOCK_ACTION' | 'BLOCK_MOVE';
+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)[];
 
@@ -954,6 +1002,12 @@ 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. */
@@ -1036,6 +1090,96 @@ 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;