@jackuait/blok 0.22.0 → 0.23.1

package/dist/full.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require(`./chunks/blok-Blnd71Ww.cjs`),t=require(`./chunks/constants-BIqDMhRj.cjs`),n=require(`./chunks/objectSpread2-iNkE6aJh.cjs`),r=require(`./chunks/tools-DTjC0C5o.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-S6c68iVJ.mjs";
-import { ja as n } from "./chunks/constants-BvxJIgSQ.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-B89FUeNz.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-Blnd71Ww.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;return(0,n.useEffect)(()=>{o===null||!m||o.focus()},[o,m]),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))});exports.BlokContent=d,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,83 +1,95 @@
-import { i as e, t } from "./chunks/blok-S6c68iVJ.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, useMemo as a, useRef as o, useState as s } from "react";
-import { jsx as c } from "react/jsx-runtime";
+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";
 //#region src/react/holder-map.ts
-var l = /* @__PURE__ */ new WeakMap();
-function u(e, t) {
-	l.set(e, t);
-}
-function d(e) {
-	return l.get(e);
+var u = /* @__PURE__ */ new WeakMap();
+function d(e, t) {
+	u.set(e, t);
 }
 function f(e) {
-	l.delete(e);
+	return u.get(e);
+}
+function p(e) {
+	u.delete(e);
 }
 //#endregion
 //#region src/react/useBlok.ts
-function p(e, r) {
-	let [c, l] = s(null), d = o(e);
-	d.current = e;
-	let p = o({
+function m(e, r) {
+	let [a, l] = c(null), u = s(e);
+	u.current = e;
+	let f = s({
 		editor: null,
 		holder: null,
 		destroyTimeout: null,
 		isDestroyed: !1,
 		depsToken: null
-	}), h = a(() => ({}), r == null ? [] : r);
+	}), m = o(() => ({}), r == null ? [] : r);
 	i(() => {
 		if (typeof window > "u") return;
-		let e = p.current;
-		if (e.destroyTimeout !== null && (clearTimeout(e.destroyTimeout), e.destroyTimeout = null), e.editor !== null && !e.isDestroyed && e.depsToken === h) return l(e.editor), () => {
-			m(e, l);
+		let e = f.current;
+		if (e.destroyTimeout !== null && (clearTimeout(e.destroyTimeout), e.destroyTimeout = null), e.editor !== null && !e.isDestroyed && e.depsToken === m) return l(e.editor), () => {
+			h(e, l);
 		};
 		if (e.editor !== null && !e.isDestroyed) {
-			f(e.editor);
+			p(e.editor);
 			try {
 				e.editor.destroy();
 			} catch (e) {}
 			e.editor = null, e.holder = null, e.isDestroyed = !0, l(null);
 		}
 		let r = document.createElement("div");
-		e.holder = r, e.isDestroyed = !1, e.depsToken = h;
-		let i = d.current, a = new t(n(n({}, i), {}, {
+		e.holder = r, e.isDestroyed = !1, e.depsToken = m;
+		let i = u.current, a = new t(n(n({}, i), {}, {
 			holder: r,
 			onReady: () => {
 				var e, t;
-				(e = (t = d.current).onReady) == null || e.call(t);
+				(e = (t = u.current).onReady) == null || e.call(t);
 			},
 			onChange: (...e) => {
 				var t, n;
-				(t = (n = d.current).onChange) == null || t.call(n, ...e);
+				(t = (n = u.current).onChange) == null || t.call(n, ...e);
 			}
 		}));
-		return e.editor = a, u(a, r), a.isReady.then(() => {
+		return e.editor = a, d(a, r), a.isReady.then(() => {
 			e.editor === a && !e.isDestroyed && l(a);
 		}).catch(() => {
 			if (e.editor === a && !e.isDestroyed) {
-				f(a);
+				p(a);
 				try {
 					a.destroy();
 				} catch (e) {}
 				e.editor = null, e.holder = null, e.isDestroyed = !0, l(null);
 			}
 		}), () => {
-			m(e, l);
+			h(e, l);
 		};
-	}, [h]);
+	}, [m]);
 	let { readOnly: g } = e;
 	i(() => {
-		c !== null && c.readOnly.set(g == null ? !1 : g);
-	}, [c, g]);
+		a !== null && a.readOnly.set(g == null ? !1 : g);
+	}, [a, g]);
 	let { autofocus: _ } = e;
+	i(() => {
+		a === null || !_ || a.focus();
+	}, [a, _]);
+	let { theme: v } = e;
+	i(() => {
+		a === null || v === void 0 || a.theme.set(v);
+	}, [a, v]);
+	let { width: y } = e;
+	i(() => {
+		a === null || y === void 0 || a.width.set(y);
+	}, [a, y]);
+	let { placeholder: b } = e;
 	return i(() => {
-		c === null || !_ || c.focus();
-	}, [c, _]), c;
+		a === null || b === void 0 || a.placeholder.set(b);
+	}, [a, b]), a;
 }
-function m(e, t) {
+function h(e, t) {
 	e.destroyTimeout = setTimeout(() => {
 		if (e.editor !== null) {
-			f(e.editor);
+			p(e.editor);
 			try {
 				e.editor.destroy();
 			} catch (e) {}
@@ -87,21 +99,36 @@ function m(e, t) {
 }
 //#endregion
 //#region src/react/BlokContent.tsx
-var h = ["editor"], g = r(function(t, r) {
-	let { editor: a } = t, s = e(t, h), l = o(null);
+var g = ["editor"], _ = r(function(t, r) {
+	let { editor: a } = t, o = e(t, g), c = s(null);
 	return i(() => {
-		if (a === null || l.current === null) return;
-		let e = d(a);
-		if (e !== void 0) return l.current.appendChild(e), () => {
+		if (a === null || c.current === null) return;
+		let e = f(a);
+		if (e !== void 0) return c.current.appendChild(e), () => {
 			e.remove();
 		};
-	}, [a]), /* @__PURE__ */ c("div", n({ ref: (e) => {
-		if (l.current = e, typeof r == "function") r(e);
+	}, [a]), /* @__PURE__ */ l("div", n({ ref: (e) => {
+		if (c.current = e, typeof r == "function") r(e);
 		else if (r != null) {
 			let t = r;
 			t.current = e;
 		}
-	} }, s));
+	} }, o));
+}), 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 = h.current) == null || e.call(h, p);
+		}
+	}, [p]), /* @__PURE__ */ l(_, n({ editor: p }, f));
 });
 //#endregion
-export { g as BlokContent, p 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-BIqDMhRj.cjs`),t=require(`./chunks/tools-DTjC0C5o.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-BvxJIgSQ.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-B89FUeNz.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.22.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

@@ -0,0 +1,88 @@
+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) 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'>,
+    Omit<HTMLAttributes<HTMLDivElement>, 'style' | 'onChange'> {
+  /** When any value changes, the editor is destroyed and recreated. */
+  deps?: DependencyList;
+  /** 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. Fires after the
+   * forwarded ref is committed, so `ref.current` is also populated at this point.
+   */
+  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.
+ *
+ * @example
+ * ```tsx
+ * const ref = useRef<Blok | null>(null);
+ * <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, 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]);
+
+    // Own onReady here instead of forwarding it to the core config: the core
+    // onReady fires before useImperativeHandle commits the ref. This passive
+    // effect runs AFTER the commit, so both the instance argument and ref.current
+    // are reliably populated.
+    const onReadyRef = useRef(onReady);
+    onReadyRef.current = onReady;
+    useEffect(() => {
+      if (editor !== null) {
+        onReadyRef.current?.(editor);
+      }
+    }, [editor]);
+
+    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/index.ts

@@ -1,3 +1,5 @@
 export { useBlok } from './useBlok';
 export { BlokContent } from './BlokContent';
+export { BlokEditor } from './BlokEditor';
 export type { UseBlokConfig, BlokContentProps } from './types';
+export type { BlokEditorProps } from './BlokEditor';

package/src/react/types.ts

@@ -1,10 +1,21 @@
-import type { BlokConfig, Blok } from '@/types';
+import type { BlokConfig, Blok, EditorWidth } from '@/types';
 
 /**
  * Configuration for useBlok hook.
- * Same as BlokConfig but without `holder` — the holder is managed by BlokContent.
+ * Same as BlokConfig but without `holder` (managed by BlokContent), plus a
+ * React-only reactive `width` prop.
+ *
+ * Reactive props (sync after mount without recreation):
+ * - `readOnly` — calls `editor.readOnly.set(value)`
+ * - `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'> {}
+export interface UseBlokConfig extends Omit<BlokConfig, 'holder'> {
+  /** Editor content width mode. Synced reactively after mount via `editor.width.set()`. */
+  width?: EditorWidth;
+}
 
 /**
  * Props for the BlokContent component.

package/src/react/useBlok.ts

@@ -146,6 +146,33 @@ export function useBlok(config: UseBlokConfig, deps?: DependencyList): Blok | nu
     editor.focus();
   }, [editor, autofocus]);
 
+  // Reactive: theme
+  const { theme } = config;
+  useEffect(() => {
+    if (editor === null || theme === undefined) {
+      return;
+    }
+    editor.theme.set(theme);
+  }, [editor, theme]);
+
+  // Reactive: width
+  const { width } = config;
+  useEffect(() => {
+    if (editor === null || width === undefined) {
+      return;
+    }
+    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);
 
   /**