@jackuait/blok 0.23.1 → 0.23.3

package/types/configs/blok-config.d.ts

@@ -59,6 +59,17 @@ export interface BlokConfig {
    */
   sanitizer?: SanitizerConfig;
 
+  /**
+   * Transform or clean the raw clipboard HTML before Blok processes it.
+   * Runs on the unmodified `text/html` payload, before any Blok preprocessing
+   * or sanitization, so you no longer need a capture-phase paste interceptor.
+   *
+   * @param html - the raw `text/html` clipboard string
+   * @returns the transformed HTML to feed into the rest of the paste pipeline,
+   *          or `null` to skip the HTML paste path (paste falls through to plain text).
+   */
+  onBeforePaste?: (html: string) => string | null;
+
   /**
    * If true, toolbar won't be shown
    */
@@ -124,6 +135,32 @@ export interface BlokConfig {
    */
   i18n?: I18nConfig;
 
+  /**
+   * Configures how the Link inline tool builds anchor elements, so consumers can
+   * control the created `<a>` instead of post-processing the rendered DOM.
+   */
+  link?: {
+    /**
+     * `target` attribute applied to created anchors.
+     * @default '_blank'
+     */
+    target?: string;
+
+    /**
+     * `rel` attribute applied to created anchors.
+     * @default 'nofollow'
+     */
+    rel?: string;
+
+    /**
+     * Transforms the href just before it is assigned to the anchor.
+     * Runs after URL validation/normalization, on the final value.
+     * @param href - the validated, protocol-normalized href
+     * @returns the href to set on the anchor
+     */
+    transformHref?: (href: string) => string;
+  };
+
   /**
    * Notion-style link-paste behavior. Pasting a URL always opens a small menu
    * (Plain link / Bookmark / Embed) instead of auto-inserting a block.

package/types/events/editor-events.ts

@@ -0,0 +1,41 @@
+/**
+ * Public payloads and name map for editor lifecycle events observable via
+ * `blok.events.on(...)`.
+ *
+ * These complement the mutation events delivered through the `onChange`
+ * config callback ({@link ./block}). Use together with the exported event-name
+ * constants `BlockRendered` (`'block:rendered'`) and `BlocksRendered`
+ * (`'blocks:rendered'`).
+ */
+
+/**
+ * Payload for the `block:rendered` event.
+ */
+export interface BlockRenderedPayload {
+  /**
+   * Id of the block that has just been rendered into the DOM.
+   * Use `blok.blocks.getById(blockId)` to access it.
+   */
+  blockId: string;
+}
+
+/**
+ * Payload for the `blocks:rendered` event.
+ */
+export interface BlocksRenderedPayload {
+  /**
+   * Number of top-level blocks rendered in the completed batch.
+   */
+  count: number;
+}
+
+/**
+ * Map of editor lifecycle event name -> payload.
+ *
+ * Subscribers get fully typed payloads for these well-known events while the
+ * `Events` API still accepts arbitrary string event names for custom events.
+ */
+export interface BlokEditorEventMap {
+  'block:rendered': BlockRenderedPayload;
+  'blocks:rendered': BlocksRenderedPayload;
+}

package/types/index.d.ts

@@ -42,6 +42,7 @@ import { BlockAddedMutationType, BlockAddedEvent } from './events/block/BlockAdd
 import { BlockChangedMutationType, BlockChangedEvent } from './events/block/BlockChanged';
 import { BlockMovedMutationType, BlockMovedEvent } from './events/block/BlockMoved';
 import { BlockRemovedMutationType, BlockRemovedEvent } from './events/block/BlockRemoved';
+import { BlokEditorEventMap, BlockRenderedPayload, BlocksRenderedPayload } from './events/editor-events';
 
 /**
  * Interfaces used for development
@@ -144,6 +145,9 @@ export {
   BlockMovedEvent,
   BlockChangedMutationType,
   BlockChangedEvent,
+  BlokEditorEventMap,
+  BlockRenderedPayload,
+  BlocksRenderedPayload,
 }
 
 /**
@@ -170,7 +174,7 @@ export interface API {
   ui: Ui;
   theme: Theme;
   /** Read-only view of selected editor configuration. */
-  config: Readonly<Pick<BlokConfig, 'linkPaste'>>;
+  config: Readonly<Pick<BlokConfig, 'linkPaste' | 'link'>>;
   rectangleSelection: {
     cancelActiveSelection: () => void;
     isRectActivated: () => boolean;

package/types/react.d.ts

@@ -12,6 +12,8 @@ import type React from 'react';
  * - `theme` — calls `editor.theme.set(value)`
  * - `width` — calls `editor.width.set(value)`
  * - `placeholder` — calls `editor.placeholder.set(value)`
+ * - `data` — re-renders via `editor.render(value)` when the content changes
+ *   (deep-equal–deduped and serialized; seeds the initial content at creation)
  *
  * All other config is consumed once at editor creation.
  */
@@ -34,7 +36,7 @@ export interface BlokContentProps extends React.HTMLAttributes<HTMLDivElement> {
  * React hook that creates and manages a Blok editor instance.
  *
  * @param config - Editor configuration (all BlokConfig props except `holder`)
- * @param deps - Optional dependency array. When any dep changes, the editor is destroyed and recreated.
+ * @param deps - Optional dependency array. When any dep changes, the editor is destroyed and recreated. Keep each value referentially stable (primitives or useMemo-stable objects) so the editor isn't recreated every render.
  * @returns The Blok editor instance, or null during SSR / before initialization.
  *
  * @example
@@ -72,7 +74,11 @@ export declare const BlokContent: React.ForwardRefExoticComponent<BlokContentPro
 export interface BlokEditorProps
   extends Omit<UseBlokConfig, 'onReady'>,
     Omit<React.HTMLAttributes<HTMLDivElement>, 'style' | 'onChange'> {
-  /** When any value changes, the editor is destroyed and recreated. */
+  /**
+   * When any value changes, the editor is destroyed and recreated. Keep each
+   * value referentially stable (primitives or useMemo-stable objects) — a dep
+   * whose identity changes every render recreates the editor each time.
+   */
   deps?: React.DependencyList;
   /** Test id forwarded to the editor container element (via data-testid). */
   'data-testid'?: string;
@@ -84,6 +90,11 @@ export interface BlokEditorProps
  * The recommended all-in-one React component. Wires useBlok + BlokContent and
  * forwards a ref to the live Blok instance (null before the editor is ready).
  *
+ * Don't wrap this component in `styled()` or any HOC that reserves the `theme`
+ * prop — styled-components claims `theme` for its own `ThemeProvider`, so it
+ * never reaches the editor and theme sync silently breaks. Render it directly
+ * and style the container via `className`.
+ *
  * @example
  * ```tsx
  * const ref = useRef<Blok | null>(null);