@b10cks/client 1.10.0 → 1.12.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,10 +86,14 @@ 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. */
@@ -286,6 +292,7 @@ export declare type B10cksLink = {
     anchor?: string;
     target?: '_self' | '_blank' | '_parent' | '_top';
     rel?: string;
+    params?: B10cksLinkParams;
 } | {
     type: 'email';
     email: string;
@@ -298,7 +305,7 @@ export declare type B10cksLink = {
     url: string;
     title: string;
     content: string;
-    params?: string;
+    params?: B10cksLinkParams;
     anchor?: string;
     target?: '_self' | '_blank' | '_parent' | '_top';
 } | {
@@ -306,6 +313,9 @@ export declare type B10cksLink = {
     id: string;
 };
 
+/** Query params stored on a link: a key/value map (CMS format) or a raw query string. */
+export declare type B10cksLinkParams = Record<string, string> | string;
+
 export declare interface B10cksLinkResolved {
     href: string;
     target: string;
@@ -317,6 +327,47 @@ 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 }`.
+ *
+ * `v-editable` (Vue) and `B10cksComponent` (React) set the id already. Spread this onto the
+ * root element of blocks rendered without them. Block ids are ULIDs and can start with a
+ * digit, so look them up with `getElementById` (or `CSS.escape` for `querySelector`).
+ */
+export declare function blockAnchorAttrs(block: {
+    id?: string | null;
+} | null | undefined): {
+    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.
@@ -346,12 +397,27 @@ 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 adds HIDDEN_BLOCKS and the `hide` and `show` block
+ * actions.
+ */
+export declare const BRIDGE_PROTOCOL = 2;
+
 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.
  *
@@ -364,8 +430,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;
 };
@@ -416,10 +486,11 @@ export declare type EditableFieldMode = 'inline' | 'select';
 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;
 
@@ -432,9 +503,13 @@ export declare type EventPayloadMap = {
     HOVER_UPDATE: SelectUpdateEvent;
     FIELD_UPDATE: FieldUpdateEvent;
     FIELD_SELECT: FieldSelectEvent;
+    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' | 'BLOCK_LABELS' | 'HIDDEN_BLOCKS' | 'BLOCK_ACTION' | 'BLOCK_MOVE';
 
 export declare type FetchClient = (input: URL | string | RequestInfo, init?: RequestInit) => Promise<unknown>;
 
@@ -482,6 +557,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;
@@ -847,6 +930,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. */
@@ -857,6 +942,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;
@@ -864,6 +954,10 @@ 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;
+    /** 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;
@@ -899,7 +993,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;
 }
 
@@ -930,8 +1028,9 @@ export declare function renderSitemapXml(entries: IBSitemapEntry[], siteUrl?: st
  * Resolves a B10cksLink value to a plain { href, target } object.
  *
  * - `'email'` links produce a `mailto:` href with optional subject/body/cc/bcc query params.
- * - `'url'` and `'internal'` links use the stored `url` field; an `anchor` is appended as a
- *   hash fragment when present.
+ * - `'url'` and `'internal'` links use the stored `url` field, then append `params` as a query
+ *   string and `anchor` as a `#fragment` (`/page?x=1#01kh…`). An href that already carries a
+ *   fragment keeps it.
  * - `'asset'` links cannot be resolved to a URL without the asset record — returns `undefined`.
  * - Locale prefixing and router integration are intentionally left to the caller.
  */
@@ -942,8 +1041,9 @@ export declare type RootBlock<T> = T & {
     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>;
@@ -1053,6 +1153,7 @@ export declare namespace types {
         IBSpace,
         IBRedirect,
         IBContentQueryParams,
+        B10cksLinkParams,
         B10cksLink,
         B10cksAssetA11y,
         B10cksAssetThumbnail,