@jackuait/blok 0.23.3 → 0.23.5

package/src/react/useBlok.ts

@@ -43,6 +43,17 @@ export function useBlok(config: UseBlokConfig, deps?: DependencyList): Blok | nu
   // eslint-disable-next-line react-hooks/exhaustive-deps
   const depsToken = useMemo(() => ({}), deps ?? []);
 
+  // Tracks the data the editor currently reflects — set when content is seeded
+  // or rendered (the reactive `data` effect below) AND when the editor emits its
+  // own serialized content via `onSave`. The latter is what makes a controlled
+  // `onSave -> setData -> data` round-trip a no-op: the echoed payload deep-equals
+  // this baseline, so the data effect skips the redundant render() (which would
+  // otherwise reset the caret). Declared here so the `onSave` wrapper below can
+  // update it before the consumer's setState re-runs the data effect.
+  const lastRenderedDataRef = useRef(config.data);
+  const seededEditorRef = useRef<Blok | null>(null);
+  const renderChainRef = useRef<Promise<void>>(Promise.resolve());
+
   // Main lifecycle effect
   useEffect(() => {
     if (typeof window === 'undefined') {
@@ -99,6 +110,35 @@ export function useBlok(config: UseBlokConfig, deps?: DependencyList): Blok | nu
       },
     };
 
+    // Only attach onSave when the consumer opted in: its mere presence makes the
+    // core serialize on every change batch, so an absent prop must stay absent.
+    // The wrapper reads through the ref so the latest callback is always used.
+    if (currentConfig.onSave) {
+      blokConfig.onSave = (...args: Parameters<NonNullable<UseBlokConfig['onSave']>>): void => {
+        // Record the editor's own serialized output as the rendered baseline so a
+        // controlled consumer echoing it straight back into `data` is a no-op —
+        // no redundant render(), no caret reset, no round-trip recursion.
+        lastRenderedDataRef.current = args[0];
+        configRef.current.onSave?.(...args);
+      };
+    }
+
+    // onBeforeRender / onAfterRender are opt-in (absent prop must stay absent so
+    // the core skips them). When present, route through the ref so the latest
+    // callback is always used without recreating the editor.
+    if (currentConfig.onBeforeRender) {
+      blokConfig.onBeforeRender = (
+        ...args: Parameters<NonNullable<UseBlokConfig['onBeforeRender']>>
+      ): ReturnType<NonNullable<UseBlokConfig['onBeforeRender']>> =>
+        configRef.current.onBeforeRender?.(...args) ?? args[0];
+    }
+
+    if (currentConfig.onAfterRender) {
+      blokConfig.onAfterRender = (...args: Parameters<NonNullable<UseBlokConfig['onAfterRender']>>): void => {
+        configRef.current.onAfterRender?.(...args);
+      };
+    }
+
     const blok = new BlokRuntime(blokConfig) as unknown as Blok;
     state.editor = blok;
     setHolder(blok, holder);
@@ -178,13 +218,12 @@ export function useBlok(config: UseBlokConfig, deps?: DependencyList): Blok | nu
   //
   // `data` seeds the editor at construction. Afterwards, changing the prop to
   // new *content* re-renders the editor via the public render() API — no
-  // recreation. Updates are deep-equal–deduped (so a new reference with the
-  // same content is a no-op and won't clobber the caret) and serialized (so
-  // rapid changes can't trigger overlapping render passes).
+  // recreation. Updates are deep-equal–deduped against the editor's current
+  // content baseline (`lastRenderedDataRef`, declared above and also updated by
+  // the `onSave` wrapper) so a new reference with the same content — including
+  // the editor's own serialized output echoed back — is a no-op and won't
+  // clobber the caret. Renders are serialized so rapid changes can't overlap.
   const { data } = config;
-  const lastRenderedDataRef = useRef(config.data);
-  const seededEditorRef = useRef<Blok | null>(null);
-  const renderChainRef = useRef<Promise<void>>(Promise.resolve());
   useEffect(() => {
     if (editor === null || data === undefined) {
       return;

package/types/block-tunes/block-tune.d.ts

@@ -2,6 +2,24 @@ import {API, BlockAPI, ToolConfig} from '../index';
 import { BlockTuneData } from './block-tune-data';
 import { BaseToolConstructable, MenuConfig } from '../tools';
 
+/**
+ * Context passed to a Block Tune's `render()` method, giving the tune a handle
+ * on the popover it is rendered into — so custom tunes can anchor sub-menus or
+ * portals inside Blok's tune popover instead of reaching into the DOM via
+ * `closest('[data-blok-popover]')`.
+ */
+export interface BlockTuneRenderContext {
+  /**
+   * Returns the popover element (`[data-blok-popover]`) the tune is rendered
+   * into, or `null` when accessed before the popover has mounted.
+   *
+   * `render()` itself runs *before* the popover exists, so calling this
+   * synchronously inside `render()` returns `null`. Capture the context and
+   * call this later (e.g. when opening a sub-menu) to get the live element.
+   */
+  getPopoverElement(): HTMLElement | null;
+}
+
 /**
  * Describes BLockTune blueprint
  */
@@ -10,8 +28,10 @@ export interface BlockTune {
    * Returns BlockTune's UI.
    * Should return either MenuConfig (recommended)
    * or an HTMLElement (UI consistency is not guaranteed)
+   *
+   * @param context - render context exposing the host tune popover element
    */
-  render(): HTMLElement | MenuConfig;
+  render(context?: BlockTuneRenderContext): HTMLElement | MenuConfig;
 
   /**
    * Method called on Tool render. Pass Tool content as an argument.

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

@@ -1,6 +1,6 @@
 import type { ThemeMode, ResolvedTheme } from '../api/theme';
 import {ToolConstructable, ToolSettings} from '../tools';
-import {API, LogLevels, OutputData} from '../index';
+import {API, LogLevels, OutputBlockData, OutputData} from '../index';
 import {SanitizerConfig} from './sanitizer-config';
 import {I18nConfig} from './i18n-config';
 import { BlockMutationEvent } from '../events/block';
@@ -136,8 +136,17 @@ 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.
+   * Configures how Blok builds anchor (`<a>`) elements, so consumers can control
+   * the created links instead of post-processing the rendered DOM.
+   *
+   * Applies on every path that produces anchors:
+   * - the interactive **Link inline tool** (links the user creates by hand),
+   * - **render** — anchors coming from stored block HTML when `blocks.render()`
+   *   runs (e.g. saved articles whose `<a>` never went through the inline tool),
+   * - **paste** — `<a>` arriving via the clipboard.
+   *
+   * On the render and paste paths `target`/`rel` are forced and `transformHref`
+   * rewrites the href, exactly as for hand-created links.
    */
   link?: {
     /**
@@ -154,8 +163,13 @@ export interface BlokConfig {
 
     /**
      * 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
+     *
+     * On the inline-tool path it runs after URL validation/normalization, on the
+     * final value. On the render and paste paths it runs against each anchor's
+     * existing href, so it must be idempotent (re-rendering already-transformed
+     * content must not change the result again).
+     *
+     * @param href - the href to transform
      * @returns the href to set on the anchor
      */
     transformHref?: (href: string) => string;
@@ -187,6 +201,49 @@ export interface BlokConfig {
    */
   onChange?(api: API, event: BlockMutationEvent | BlockMutationEvent[]): void;
 
+  /**
+   * Fires with the full serialized {@link OutputData} whenever the content
+   * changes. This is the "output half" of a controlled editor: pair it with the
+   * `data` config (or the React `data` prop) to mirror the editor state into your
+   * own store with a single callback instead of calling `saver.save()` by hand.
+   *
+   * Serialization is debounced through the same change-batching window as
+   * `onChange`, so a burst of edits produces a single `onSave` call. Only
+   * user-driven content changes trigger it — programmatic `render()` does not
+   * (the change observer is disabled during render), so a controlled
+   * `data → render → onSave → setData` round-trip won't recurse.
+   *
+   * @param data - the full serialized output of the editor
+   * @param api - blok.js api
+   */
+  onSave?(data: OutputData, api: API): void;
+
+  /**
+   * Transforms the blocks array just before it is rendered, on every render
+   * (the initial render and every `blocks.render()` call). Use it to run
+   * app-specific data migrations inside Blok instead of pre-processing the
+   * data before handing it to the editor.
+   *
+   * Receives the raw saved blocks (the exact array passed to render, before any
+   * format analysis or hierarchical expansion) and must return the blocks to
+   * render. Returning an empty array renders an empty document; returning blocks
+   * for an empty input injects them.
+   *
+   * @param blocks - the blocks about to be rendered
+   * @returns the blocks to actually render
+   */
+  onBeforeRender?(blocks: OutputBlockData[]): OutputBlockData[];
+
+  /**
+   * Fires after a render completes and the blocks are in the DOM — on the
+   * initial render and on every `blocks.render()` call. Use it for post-render
+   * side effects (scroll restoration, attaching observers, …). Distinct from
+   * `onReady`, which fires once when the editor first becomes ready.
+   *
+   * @param api - blok.js api
+   */
+  onAfterRender?(api: API): void;
+
   /**
    * Defines default toolbar for all tools.
    */

package/types/index.d.ts

@@ -72,7 +72,7 @@ export {
   FilePasteEvent,
   FilePasteEventDetail,
 } from './tools';
-export {BlockTune, BlockTuneConstructable} from './block-tunes';
+export {BlockTune, BlockTuneConstructable, BlockTuneRenderContext} from './block-tunes';
 export {
   BlokConfig,
   SanitizerConfig,