@jackuait/blok 0.23.0 → 0.23.1

package/dist/full.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require(`./chunks/blok-D4WXeg3t.cjs`),t=require(`./chunks/constants-BbCnmzAr.cjs`),n=require(`./chunks/objectSpread2-iNkE6aJh.cjs`),r=require(`./chunks/tools-tG5_UaWz.cjs`);var i={paragraph:{class:r.k,inlineToolbar:!0,config:{preserveBlank:!0}},header:{class:r.O,inlineToolbar:!0},list:{class:r.D,inlineToolbar:!0}},a=n.t(n.t({},i),{},{bold:{class:r.l},italic:{class:r.c},marker:{class:r.o},underline:{class:r.a},strikethrough:{class:r.i},link:{class:r.s}});exports.Blok=e.t,exports.Bold=r.l,exports.DATA_ATTR=t.ja,exports.Header=r.O,exports.Italic=r.c,exports.Link=r.s,exports.List=r.D,exports.Marker=r.o,exports.Paragraph=r.k,exports.Strikethrough=r.i,exports.Toggle=r.T,exports.Underline=r.a,exports.allTools=a,exports.defaultBlockTools=r.t,exports.defaultInlineTools=r.n,exports.defaultTools=i,exports.version=e.n;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require(`./chunks/blok-Ci1zCOUg.cjs`),t=require(`./chunks/constants-Bkncy0y5.cjs`),n=require(`./chunks/objectSpread2-iNkE6aJh.cjs`),r=require(`./chunks/tools-DlOZpcVU.cjs`);var i={paragraph:{class:r.k,inlineToolbar:!0,config:{preserveBlank:!0}},header:{class:r.O,inlineToolbar:!0},list:{class:r.D,inlineToolbar:!0}},a=n.t(n.t({},i),{},{bold:{class:r.l},italic:{class:r.c},marker:{class:r.o},underline:{class:r.a},strikethrough:{class:r.i},link:{class:r.s}});exports.Blok=e.t,exports.Bold=r.l,exports.DATA_ATTR=t.ja,exports.Header=r.O,exports.Italic=r.c,exports.Link=r.s,exports.List=r.D,exports.Marker=r.o,exports.Paragraph=r.k,exports.Strikethrough=r.i,exports.Toggle=r.T,exports.Underline=r.a,exports.allTools=a,exports.defaultBlockTools=r.t,exports.defaultInlineTools=r.n,exports.defaultTools=i,exports.version=e.n;

package/dist/full.mjs

@@ -1,7 +1,7 @@
-import { n as e, t } from "./chunks/blok-BmckXjmW.mjs";
-import { ja as n } from "./chunks/constants-tXKHkDAG.mjs";
+import { n as e, t } from "./chunks/blok-BPeM6wKv.mjs";
+import { ja as n } from "./chunks/constants-DR3sya6U.mjs";
 import { t as r } from "./chunks/objectSpread2-jlBcdYeb.mjs";
-import { D as i, O as a, T as o, a as s, c, i as l, k as u, l as d, n as f, o as p, s as m, t as h } from "./chunks/tools-oXMAa9zD.mjs";
+import { D as i, O as a, T as o, a as s, c, i as l, k as u, l as d, n as f, o as p, s as m, t as h } from "./chunks/tools-B72rczVw.mjs";
 //#region src/full.ts
 var g = {
 	paragraph: {

package/dist/react.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`}),require(`./chunks/chunk-BL1yB9zm.cjs`);const e=require(`./chunks/blok-D4WXeg3t.cjs`),t=require(`./chunks/objectSpread2-iNkE6aJh.cjs`);let n=require(`react`),r=require(`react/jsx-runtime`);var i=new WeakMap;function a(e,t){i.set(e,t)}function o(e){return i.get(e)}function s(e){i.delete(e)}function c(r,i){let[o,c]=(0,n.useState)(null),u=(0,n.useRef)(r);u.current=r;let d=(0,n.useRef)({editor:null,holder:null,destroyTimeout:null,isDestroyed:!1,depsToken:null}),f=(0,n.useMemo)(()=>({}),i==null?[]:i);(0,n.useEffect)(()=>{if(typeof window>`u`)return;let n=d.current;if(n.destroyTimeout!==null&&(clearTimeout(n.destroyTimeout),n.destroyTimeout=null),n.editor!==null&&!n.isDestroyed&&n.depsToken===f)return c(n.editor),()=>{l(n,c)};if(n.editor!==null&&!n.isDestroyed){s(n.editor);try{n.editor.destroy()}catch(e){}n.editor=null,n.holder=null,n.isDestroyed=!0,c(null)}let r=document.createElement(`div`);n.holder=r,n.isDestroyed=!1,n.depsToken=f;let i=u.current,o=new e.t(t.t(t.t({},i),{},{holder:r,onReady:()=>{var e,t;(e=(t=u.current).onReady)==null||e.call(t)},onChange:(...e)=>{var t,n;(t=(n=u.current).onChange)==null||t.call(n,...e)}}));return n.editor=o,a(o,r),o.isReady.then(()=>{n.editor===o&&!n.isDestroyed&&c(o)}).catch(()=>{if(n.editor===o&&!n.isDestroyed){s(o);try{o.destroy()}catch(e){}n.editor=null,n.holder=null,n.isDestroyed=!0,c(null)}}),()=>{l(n,c)}},[f]);let{readOnly:p}=r;(0,n.useEffect)(()=>{o!==null&&o.readOnly.set(p==null?!1:p)},[o,p]);let{autofocus:m}=r;(0,n.useEffect)(()=>{o===null||!m||o.focus()},[o,m]);let{theme:h}=r;(0,n.useEffect)(()=>{o===null||h===void 0||o.theme.set(h)},[o,h]);let{width:g}=r;return(0,n.useEffect)(()=>{o===null||g===void 0||o.width.set(g)},[o,g]),o}function l(e,t){e.destroyTimeout=setTimeout(()=>{if(e.editor!==null){s(e.editor);try{e.editor.destroy()}catch(e){}e.editor=null,e.holder=null,e.isDestroyed=!0,e.destroyTimeout=null,t(null)}},0)}var u=[`editor`],d=(0,n.forwardRef)(function(i,a){let{editor:s}=i,c=e.i(i,u),l=(0,n.useRef)(null);return(0,n.useEffect)(()=>{if(s===null||l.current===null)return;let e=o(s);if(e!==void 0)return l.current.appendChild(e),()=>{e.remove()}},[s]),(0,r.jsx)(`div`,t.t({ref:e=>{if(l.current=e,typeof a==`function`)a(e);else if(a!=null){let t=a;t.current=e}}},c))}),f=[`deps`,`className`,`onReady`,`data-testid`],p=(0,n.forwardRef)(function(t,i){let{deps:a,className:o,onReady:s,"data-testid":l}=t,u=c(e.i(t,f),a);(0,n.useImperativeHandle)(i,()=>u,[u]);let p=(0,n.useRef)(s);return p.current=s,(0,n.useEffect)(()=>{if(u!==null){var e;(e=p.current)==null||e.call(p,u)}},[u]),(0,r.jsx)(d,{editor:u,className:o,"data-testid":l})});exports.BlokContent=d,exports.BlokEditor=p,exports.useBlok=c;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`}),require(`./chunks/chunk-BL1yB9zm.cjs`);const e=require(`./chunks/blok-Ci1zCOUg.cjs`),t=require(`./chunks/objectSpread2-iNkE6aJh.cjs`);let n=require(`react`),r=require(`react/jsx-runtime`);var i=new WeakMap;function a(e,t){i.set(e,t)}function o(e){return i.get(e)}function s(e){i.delete(e)}function c(r,i){let[o,c]=(0,n.useState)(null),u=(0,n.useRef)(r);u.current=r;let d=(0,n.useRef)({editor:null,holder:null,destroyTimeout:null,isDestroyed:!1,depsToken:null}),f=(0,n.useMemo)(()=>({}),i==null?[]:i);(0,n.useEffect)(()=>{if(typeof window>`u`)return;let n=d.current;if(n.destroyTimeout!==null&&(clearTimeout(n.destroyTimeout),n.destroyTimeout=null),n.editor!==null&&!n.isDestroyed&&n.depsToken===f)return c(n.editor),()=>{l(n,c)};if(n.editor!==null&&!n.isDestroyed){s(n.editor);try{n.editor.destroy()}catch(e){}n.editor=null,n.holder=null,n.isDestroyed=!0,c(null)}let r=document.createElement(`div`);n.holder=r,n.isDestroyed=!1,n.depsToken=f;let i=u.current,o=new e.t(t.t(t.t({},i),{},{holder:r,onReady:()=>{var e,t;(e=(t=u.current).onReady)==null||e.call(t)},onChange:(...e)=>{var t,n;(t=(n=u.current).onChange)==null||t.call(n,...e)}}));return n.editor=o,a(o,r),o.isReady.then(()=>{n.editor===o&&!n.isDestroyed&&c(o)}).catch(()=>{if(n.editor===o&&!n.isDestroyed){s(o);try{o.destroy()}catch(e){}n.editor=null,n.holder=null,n.isDestroyed=!0,c(null)}}),()=>{l(n,c)}},[f]);let{readOnly:p}=r;(0,n.useEffect)(()=>{o!==null&&o.readOnly.set(p==null?!1:p)},[o,p]);let{autofocus:m}=r;(0,n.useEffect)(()=>{o===null||!m||o.focus()},[o,m]);let{theme:h}=r;(0,n.useEffect)(()=>{o===null||h===void 0||o.theme.set(h)},[o,h]);let{width:g}=r;(0,n.useEffect)(()=>{o===null||g===void 0||o.width.set(g)},[o,g]);let{placeholder:_}=r;return(0,n.useEffect)(()=>{o===null||_===void 0||o.placeholder.set(_)},[o,_]),o}function l(e,t){e.destroyTimeout=setTimeout(()=>{if(e.editor!==null){s(e.editor);try{e.editor.destroy()}catch(e){}e.editor=null,e.holder=null,e.isDestroyed=!0,e.destroyTimeout=null,t(null)}},0)}var u=[`editor`],d=(0,n.forwardRef)(function(i,a){let{editor:s}=i,c=e.i(i,u),l=(0,n.useRef)(null);return(0,n.useEffect)(()=>{if(s===null||l.current===null)return;let e=o(s);if(e!==void 0)return l.current.appendChild(e),()=>{e.remove()}},[s]),(0,r.jsx)(`div`,t.t({ref:e=>{if(l.current=e,typeof a==`function`)a(e);else if(a!=null){let t=a;t.current=e}}},c))}),f=`autofocus.defaultBlock.dataModel.placeholder.sanitizer.hideToolbar.maxHistoryLength.historyDebounceTime.newGroupDelay.globalUndoRedo.tools.data.minHeight.logLevel.readOnly.i18n.linkPaste.onReady.onChange.inlineToolbar.tunes.style.theme.onThemeChange.scrollToBlock.user.resolveUser.notifierPosition.notifier.width`.split(`.`),p=[`deps`,`onReady`],m=new Set(f),h=(0,n.forwardRef)(function(i,a){let{deps:o,onReady:s}=i,l=e.i(i,p),u={},f={};for(let e of Object.keys(l)){let t=l[e];m.has(e)?u[e]=t:f[e]=t}let h=c(u,o);(0,n.useImperativeHandle)(a,()=>h,[h]);let g=(0,n.useRef)(s);return g.current=s,(0,n.useEffect)(()=>{if(h!==null){var e;(e=g.current)==null||e.call(g,h)}},[h]),(0,r.jsx)(d,t.t({editor:h},f))});exports.BlokContent=d,exports.BlokEditor=h,exports.useBlok=c;

package/dist/react.mjs

@@ -1,4 +1,4 @@
-import { i as e, t } from "./chunks/blok-BmckXjmW.mjs";
+import { i as e, t } from "./chunks/blok-BPeM6wKv.mjs";
 import { t as n } from "./chunks/objectSpread2-jlBcdYeb.mjs";
 import { forwardRef as r, useEffect as i, useImperativeHandle as a, useMemo as o, useRef as s, useState as c } from "react";
 import { jsx as l } from "react/jsx-runtime";
@@ -78,9 +78,13 @@ function m(e, r) {
 		a === null || v === void 0 || a.theme.set(v);
 	}, [a, v]);
 	let { width: y } = e;
-	return i(() => {
+	i(() => {
 		a === null || y === void 0 || a.width.set(y);
-	}, [a, y]), a;
+	}, [a, y]);
+	let { placeholder: b } = e;
+	return i(() => {
+		a === null || b === void 0 || a.placeholder.set(b);
+	}, [a, b]), a;
 }
 function h(e, t) {
 	e.destroyTimeout = setTimeout(() => {
@@ -110,25 +114,21 @@ var g = ["editor"], _ = r(function(t, r) {
 			t.current = e;
 		}
 	} }, o));
-}), v = [
-	"deps",
-	"className",
-	"onReady",
-	"data-testid"
-], y = r(function(t, n) {
-	let { deps: r, className: o, onReady: c, "data-testid": u } = t, d = m(e(t, v), r);
-	a(n, () => d, [d]);
-	let f = s(c);
-	return f.current = c, i(() => {
-		if (d !== null) {
+}), v = /* @__PURE__ */ "autofocus.defaultBlock.dataModel.placeholder.sanitizer.hideToolbar.maxHistoryLength.historyDebounceTime.newGroupDelay.globalUndoRedo.tools.data.minHeight.logLevel.readOnly.i18n.linkPaste.onReady.onChange.inlineToolbar.tunes.style.theme.onThemeChange.scrollToBlock.user.resolveUser.notifierPosition.notifier.width".split("."), y = ["deps", "onReady"], b = new Set(v), x = r(function(t, r) {
+	let { deps: o, onReady: c } = t, u = e(t, y), d = {}, f = {};
+	for (let e of Object.keys(u)) {
+		let t = u[e];
+		b.has(e) ? d[e] = t : f[e] = t;
+	}
+	let p = m(d, o);
+	a(r, () => p, [p]);
+	let h = s(c);
+	return h.current = c, i(() => {
+		if (p !== null) {
 			var e;
-			(e = f.current) == null || e.call(f, d);
+			(e = h.current) == null || e.call(h, p);
 		}
-	}, [d]), /* @__PURE__ */ l(_, {
-		editor: d,
-		className: o,
-		"data-testid": u
-	});
+	}, [p]), /* @__PURE__ */ l(_, n({ editor: p }, f));
 });
 //#endregion
-export { _ as BlokContent, y as BlokEditor, m as useBlok };
+export { _ as BlokContent, x as BlokEditor, m as useBlok };

package/dist/tools.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require(`./chunks/constants-BbCnmzAr.cjs`),t=require(`./chunks/tools-tG5_UaWz.cjs`);exports.Audio=t.g,exports.Bold=t.l,exports.Bookmark=t.u,exports.Callout=t.w,exports.Code=t.y,exports.Column=t.p,exports.ColumnList=t.m,exports.Columns=t.f,exports.Convert=e.m,exports.Database=t.C,exports.DatabaseRow=t.S,exports.Divider=t.x,exports.Embed=t.d,exports.File=t._,exports.Header=t.O,exports.Image=t.v,exports.InlineCode=t.r,exports.Italic=t.c,exports.Link=t.s,exports.List=t.D,exports.Marker=t.o,exports.Paragraph=t.k,exports.Quote=t.b,exports.Strikethrough=t.i,exports.Table=t.E,exports.Toggle=t.T,exports.Underline=t.a,exports.Video=t.h,exports.defaultBlockTools=t.t,exports.defaultInlineTools=t.n;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require(`./chunks/constants-Bkncy0y5.cjs`),t=require(`./chunks/tools-DlOZpcVU.cjs`);exports.Audio=t.g,exports.Bold=t.l,exports.Bookmark=t.u,exports.Callout=t.w,exports.Code=t.y,exports.Column=t.p,exports.ColumnList=t.m,exports.Columns=t.f,exports.Convert=e.m,exports.Database=t.C,exports.DatabaseRow=t.S,exports.Divider=t.x,exports.Embed=t.d,exports.File=t._,exports.Header=t.O,exports.Image=t.v,exports.InlineCode=t.r,exports.Italic=t.c,exports.Link=t.s,exports.List=t.D,exports.Marker=t.o,exports.Paragraph=t.k,exports.Quote=t.b,exports.Strikethrough=t.i,exports.Table=t.E,exports.Toggle=t.T,exports.Underline=t.a,exports.Video=t.h,exports.defaultBlockTools=t.t,exports.defaultInlineTools=t.n;

package/dist/tools.mjs

@@ -1,3 +1,3 @@
-import { m as e } from "./chunks/constants-tXKHkDAG.mjs";
-import { C as t, D as n, E as r, O as i, S as a, T as o, _ as s, a as c, b as l, c as u, d, f, g as p, h as m, i as h, k as g, l as _, m as v, n as y, o as b, p as x, r as S, s as C, t as w, u as T, v as E, w as D, x as O, y as k } from "./chunks/tools-oXMAa9zD.mjs";
+import { m as e } from "./chunks/constants-DR3sya6U.mjs";
+import { C as t, D as n, E as r, O as i, S as a, T as o, _ as s, a as c, b as l, c as u, d, f, g as p, h as m, i as h, k as g, l as _, m as v, n as y, o as b, p as x, r as S, s as C, t as w, u as T, v as E, w as D, x as O, y as k } from "./chunks/tools-B72rczVw.mjs";
 export { p as Audio, _ as Bold, T as Bookmark, D as Callout, k as Code, x as Column, v as ColumnList, f as Columns, e as Convert, t as Database, a as DatabaseRow, O as Divider, d as Embed, s as File, i as Header, E as Image, S as InlineCode, u as Italic, C as Link, n as List, b as Marker, g as Paragraph, l as Quote, h as Strikethrough, r as Table, o as Toggle, c as Underline, m as Video, w as defaultBlockTools, y as defaultInlineTools };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jackuait/blok",
-  "version": "0.23.0",
+  "version": "0.23.1",
   "description": "Blok — headless, highly extensible rich text editor built for developers who need to implement a block-based editing experience (similar to Notion) without building it from scratch",
   "module": "dist/blok.mjs",
   "main": "./dist/blok.cjs",

package/src/blok.ts

@@ -175,6 +175,39 @@ class Blok {
       toggle: (): void => applyWidthMode(readWidthMode() === 'full' ? 'narrow' : 'full'),
     };
 
+    /**
+     * Placeholder API — exposed immediately (mirrors theme/width) so host apps
+     * can call instance.placeholder.set(...) before isReady without a silent
+     * no-op. The value is buffered and replayed once BlockManager is ready.
+     */
+    const placeholderBuffer = { pending: null as string | false | null };
+
+    const getBlockManager = (): BlokModules['BlockManager'] | undefined =>
+      (blok.moduleInstances as Partial<BlokModules>).BlockManager;
+
+    const applyPlaceholder = (value: string | false): void => {
+      placeholderBuffer.pending = value;
+
+      const bm = getBlockManager();
+
+      if (bm !== undefined) {
+        bm.setPlaceholder(value);
+      }
+    };
+
+    (this as Record<string, unknown>).placeholder = {
+      get: (): string | false => {
+        if (placeholderBuffer.pending !== null) {
+          return placeholderBuffer.pending;
+        }
+
+        const cfg = this.initialConfiguration;
+
+        return isObject(cfg) ? ((cfg as BlokConfig).placeholder ?? false) : false;
+      },
+      set: (value: string | false): void => applyPlaceholder(value),
+    };
+
     /**
      * We need to export isReady promise in the constructor
      * as it can be used before other API methods are exported
@@ -247,6 +280,16 @@ class Blok {
         widthBuffer.pendingMode = null;
       }
 
+      // Apply any placeholder buffered before isReady resolved.
+      if (placeholderBuffer.pending !== null) {
+        const bm = (blok.moduleInstances as Partial<BlokModules>).BlockManager;
+
+        if (bm !== undefined) {
+          bm.setPlaceholder(placeholderBuffer.pending);
+        }
+        placeholderBuffer.pending = null;
+      }
+
       // Scroll to the block referenced by the URL hash, if present.
       // isReady resolves only after all blocks are in the DOM (requestIdleCallback fence in Renderer),
       // so no extra polling is needed even on slow connections.

package/src/components/block/index.ts

@@ -610,6 +610,19 @@ export class Block extends EventsDispatcher<BlockEvents> {
     }
   }
 
+  /**
+   * Update the block's placeholder in place (reactive editor.placeholder API).
+   * Delegates to the tool instance if it implements `setPlaceholder`. No-op otherwise.
+   * @param value - new placeholder text, or false to clear it
+   */
+  public setPlaceholder(value: string | false): void {
+    const tool = this.toolInstance as unknown as { setPlaceholder?: (v: string | false) => void };
+
+    if (typeof tool.setPlaceholder === 'function') {
+      tool.setPlaceholder(value);
+    }
+  }
+
   /**
    * Tool could specify several entries to be displayed at the Toolbox (for example, "Heading 1", "Heading 2", "Heading 3")
    * This method returns the entry that is related to the Block (depended on the Block data)

package/src/components/modules/blockManager/blockManager.ts

@@ -153,6 +153,25 @@ export class BlockManager extends Module {
     return this.repository.blocks;
   }
 
+  /**
+   * Apply a new editor-level placeholder to existing blocks and future ones.
+   * Backs the reactive `editor.placeholder` API: mutates the shared config,
+   * updates the default tool adapter (so blocks created afterward use it), and
+   * sweeps existing blocks for an in-place update.
+   * @param value - new placeholder text, or false to clear it
+   */
+  public setPlaceholder(value: string | false): void {
+    this.config.placeholder = value;
+
+    const defaultToolName = this.config.defaultBlock ?? 'paragraph';
+
+    this.Blok.Tools.blockTools.get(defaultToolName)?.setDefaultPlaceholder(value);
+
+    for (const block of this.blocks) {
+      block.setPlaceholder(value);
+    }
+  }
+
   /**
    * Check if each Block is empty
    * @returns {boolean}

package/src/components/tools/base.ts

@@ -191,6 +191,15 @@ export abstract class BaseToolAdapter<Type extends ToolType = ToolType, ToolClas
     this.defaultPlaceholder = defaultPlaceholder;
   }
 
+  /**
+   * Update the editor-level default placeholder. Used by the reactive
+   * `editor.placeholder` API so blocks created AFTER the change use the new value.
+   * @param value - new default placeholder, or false to disable it
+   */
+  public setDefaultPlaceholder(value: string | false): void {
+    this.defaultPlaceholder = value;
+  }
+
   /**
    * Returns Tool user configuration.
    * Extracts tool-specific options from flat config and merges with nested config.

package/src/react/BlokEditor.tsx

@@ -1,26 +1,35 @@
-import { forwardRef, useImperativeHandle, useEffect, useRef, type DependencyList } from 'react';
+import {
+  forwardRef,
+  useImperativeHandle,
+  useEffect,
+  useRef,
+  type DependencyList,
+  type HTMLAttributes,
+} from 'react';
 import { useBlok } from './useBlok';
 import { BlokContent } from './BlokContent';
+import { USE_BLOK_CONFIG_KEYS } from './config-keys';
 import type { Blok } from '@/types';
 import type { UseBlokConfig } from './types';
 
 /**
  * Props for the all-in-one BlokEditor component.
  * Accepts every useBlok config prop (except `onReady`, re-typed below to receive
- * the ready instance), plus container `className`/`data-testid` and an optional
- * `deps` list. When any value in `deps` changes, the editor is destroyed and
- * recreated (use this when `tools` or other structural config changes).
+ * the ready instance) AND every standard HTML div attribute, which is forwarded
+ * to the editor container element (mirrors `BlokContent`). `style` and `onChange`
+ * keep their editor-config meaning (they collide with div attributes of the same
+ * name), so the container is styled via `className` rather than an inline `style`.
  *
  * `data` is uncontrolled (seed-only): it sets the INITIAL content. After mount the
  * editor owns the document — passing a new `data` reference does NOT reload it.
  * Read content via `onChange` or the ref (`ref.current.save()`); replace it
  * imperatively via `ref.current.render(newData)`.
  */
-export interface BlokEditorProps extends Omit<UseBlokConfig, 'onReady'> {
+export interface BlokEditorProps
+  extends Omit<UseBlokConfig, 'onReady'>,
+    Omit<HTMLAttributes<HTMLDivElement>, 'style' | 'onChange'> {
   /** When any value changes, the editor is destroyed and recreated. */
   deps?: DependencyList;
-  /** Class name applied to the editor container element. */
-  className?: string;
   /** Test id forwarded to the editor container element (via data-testid). */
   'data-testid'?: string;
   /**
@@ -30,6 +39,9 @@ export interface BlokEditorProps extends Omit<UseBlokConfig, 'onReady'> {
   onReady?: (editor: Blok) => void;
 }
 
+/** Fast membership test for partitioning props into editor config vs. div attributes. */
+const CONFIG_KEY_SET = new Set<string>(USE_BLOK_CONFIG_KEYS);
+
 /**
  * The recommended way to embed Blok in React. Internally wires `useBlok` and
  * `BlokContent`, and forwards a ref to the live `Blok` instance.
@@ -37,12 +49,25 @@ export interface BlokEditorProps extends Omit<UseBlokConfig, 'onReady'> {
  * @example
  * ```tsx
  * const ref = useRef<Blok | null>(null);
- * <BlokEditor ref={ref} tools={tools} data={data} theme={theme} onReady={(e) => e.focus()} />;
+ * <BlokEditor ref={ref} id="editor" tools={tools} data={data} theme={theme} onReady={(e) => e.focus()} />;
  * ```
  */
 export const BlokEditor = forwardRef<Blok | null, BlokEditorProps>(
-  function BlokEditor({ deps, className, onReady, 'data-testid': dataTestId, ...config }, ref) {
-    const editor = useBlok(config, deps);
+  function BlokEditor({ deps, onReady, ...rest }, ref) {
+    const config: Record<string, unknown> = {};
+    const divProps: Record<string, unknown> = {};
+
+    for (const key of Object.keys(rest)) {
+      const value = (rest as Record<string, unknown>)[key];
+
+      if (CONFIG_KEY_SET.has(key)) {
+        config[key] = value;
+      } else {
+        divProps[key] = value;
+      }
+    }
+
+    const editor = useBlok(config as UseBlokConfig, deps);
 
     useImperativeHandle<Blok | null, Blok | null>(ref, () => editor, [editor]);
 
@@ -58,6 +83,6 @@ export const BlokEditor = forwardRef<Blok | null, BlokEditorProps>(
       }
     }, [editor]);
 
-    return <BlokContent editor={editor} className={className} data-testid={dataTestId} />;
+    return <BlokContent editor={editor} {...(divProps as HTMLAttributes<HTMLDivElement>)} />;
   }
 );

package/src/react/config-keys.ts

@@ -0,0 +1,51 @@
+import type { UseBlokConfig } from './types';
+
+/**
+ * Keys that belong to the editor config (consumed by `useBlok`). Any prop on
+ * `BlokEditor` whose key is NOT in this set is treated as a container div
+ * attribute and spread onto the underlying element (mirrors `BlokContent`).
+ *
+ * Keep in sync with `UseBlokConfig`. The two compile-time guards below fail the
+ * `yarn lint:types` typecheck if this list drifts.
+ */
+export const USE_BLOK_CONFIG_KEYS = [
+  'autofocus',
+  'defaultBlock',
+  'dataModel',
+  'placeholder',
+  'sanitizer',
+  'hideToolbar',
+  'maxHistoryLength',
+  'historyDebounceTime',
+  'newGroupDelay',
+  'globalUndoRedo',
+  'tools',
+  'data',
+  'minHeight',
+  'logLevel',
+  'readOnly',
+  'i18n',
+  'linkPaste',
+  'onReady',
+  'onChange',
+  'inlineToolbar',
+  'tunes',
+  'style',
+  'theme',
+  'onThemeChange',
+  'scrollToBlock',
+  'user',
+  'resolveUser',
+  'notifierPosition',
+  'notifier',
+  'width',
+] as const satisfies readonly (keyof UseBlokConfig)[];
+
+/**
+ * Compile error if a `UseBlokConfig` key is missing from the list above.
+ * (`satisfies` only proves each entry is a valid key; this proves coverage.)
+ */
+type _MissingConfigKey = Exclude<keyof UseBlokConfig, (typeof USE_BLOK_CONFIG_KEYS)[number]>;
+const _exhaustive: _MissingConfigKey extends never ? true : never = true;
+
+void _exhaustive;

package/src/react/types.ts

@@ -10,6 +10,7 @@ import type { BlokConfig, Blok, EditorWidth } from '@/types';
  * - `autofocus` — calls `editor.focus()` when changed to true
  * - `theme` — calls `editor.theme.set(value)`
  * - `width` — calls `editor.width.set(value)`
+ * - `placeholder` — calls `editor.placeholder.set(value)`
  */
 export interface UseBlokConfig extends Omit<BlokConfig, 'holder'> {
   /** Editor content width mode. Synced reactively after mount via `editor.width.set()`. */

package/src/react/useBlok.ts

@@ -164,6 +164,15 @@ export function useBlok(config: UseBlokConfig, deps?: DependencyList): Blok | nu
     editor.width.set(width);
   }, [editor, width]);
 
+  // Reactive: placeholder
+  const { placeholder } = config;
+  useEffect(() => {
+    if (editor === null || placeholder === undefined) {
+      return;
+    }
+    editor.placeholder.set(placeholder);
+  }, [editor, placeholder]);
+
   return editor;
 }
 

package/src/tools/paragraph/index.ts

@@ -321,6 +321,26 @@ export class Paragraph implements BlockTool {
     }
   }
 
+  /**
+   * Update the block's placeholder text in place (reactive editor.placeholder API).
+   * Updates internal state always; writes the live attribute only when editable
+   * and rendered. A read-only block picks up the new text on the next edit toggle.
+   *
+   * @param value - new placeholder text, or false to clear it
+   */
+  public setPlaceholder(value: string | false): void {
+    this._placeholder = value === false ? '' : value;
+
+    if (!this._element || this.readOnly) {
+      return;
+    }
+
+    this._element.setAttribute(
+      'data-blok-placeholder-active',
+      value === false ? '' : this.api.i18n.t(this._placeholder)
+    );
+  }
+
   /**
    * Method that specified how to merge two Text blocks.
    * Called by Editor by backspace at the beginning of the Block

package/types/api/index.d.ts

@@ -19,3 +19,4 @@ export * from './tools';
 
 export * from './theme';
 export * from './width';
+export * from './placeholder';

package/types/api/placeholder.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Describes Blok's placeholder API for controlling the editor-level placeholder
+ * (the hint shown on the empty default block) at runtime.
+ */
+export interface Placeholder {
+  /**
+   * Returns the current editor placeholder.
+   * @returns the placeholder text, or `false` when disabled.
+   */
+  get(): string | false;
+
+  /**
+   * Sets the editor placeholder. Updates existing blocks in place and applies to
+   * blocks created afterward. Pass `false` to clear it.
+   * @param value - new placeholder text, or false to disable it
+   */
+  set(value: string | false): void;
+}

package/types/index.d.ts

@@ -33,6 +33,7 @@ import {
   ThemeMode,
   ResolvedTheme,
   Width,
+  Placeholder,
 } from './api';
 
 import { OutputData } from './data-formats';
@@ -129,6 +130,7 @@ export {
   ResolvedTheme,
   Width,
   EditorWidth,
+  Placeholder,
 } from './api';
 export {
   BlockMutationType,
@@ -228,6 +230,8 @@ export interface PendingBlok {
   theme: Theme;
   /** Width API, exposed immediately after construction. */
   width: Width;
+  /** Placeholder API, exposed immediately after construction. */
+  placeholder: Placeholder;
 }
 
 /**
@@ -249,6 +253,7 @@ export class Blok {
   public readOnly: ReadOnly;
   public theme: Theme;
   public width: Width;
+  public placeholder: Placeholder;
   constructor(configuration?: BlokConfig|string);
 
   /**

package/types/react.d.ts

@@ -11,6 +11,7 @@ import type React from 'react';
  * - `autofocus` — calls `editor.focus()` when changed to true
  * - `theme` — calls `editor.theme.set(value)`
  * - `width` — calls `editor.width.set(value)`
+ * - `placeholder` — calls `editor.placeholder.set(value)`
  *
  * All other config is consumed once at editor creation.
  */
@@ -64,14 +65,15 @@ export declare const BlokContent: React.ForwardRefExoticComponent<BlokContentPro
 
 /**
  * Props for the BlokEditor component — all useBlok config (except `onReady`,
- * re-typed to receive the ready instance) plus container `className`/`data-testid`
- * and an optional `deps` list that forces recreation when changed.
+ * re-typed to receive the ready instance) plus every standard HTML div attribute
+ * (forwarded to the container, like `BlokContent`) and an optional `deps` list
+ * that forces recreation when changed. `style`/`onChange` keep editor-config meaning.
  */
-export interface BlokEditorProps extends Omit<UseBlokConfig, 'onReady'> {
+export interface BlokEditorProps
+  extends Omit<UseBlokConfig, 'onReady'>,
+    Omit<React.HTMLAttributes<HTMLDivElement>, 'style' | 'onChange'> {
   /** When any value changes, the editor is destroyed and recreated. */
   deps?: React.DependencyList;
-  /** Class name applied to the editor container element. */
-  className?: string;
   /** Test id forwarded to the editor container element (via data-testid). */
   'data-testid'?: string;
   /** Called once the editor is ready, with the live Blok instance (ref is also committed). */