@superdoc-dev/react 1.10.0-next.9 → 1.11.0-next.1

package/README.md

@@ -49,6 +49,25 @@ function App() {
 }
 ```
 
+## File prop component
+
+When an agent needs to create a React wrapper around a DOCX `File`, use this shape:
+
+```tsx
+import { SuperDocEditor } from '@superdoc-dev/react';
+import '@superdoc-dev/react/style.css';
+
+export function ContractEditor({ file }: { file: File }) {
+  return (
+    <SuperDocEditor
+      document={file}
+      documentMode="editing"
+      onReady={({ superdoc }) => console.log('Ready', superdoc)}
+    />
+  );
+}
+```
+
 ## Changing Mode
 
 Just update the `documentMode` prop - the component handles it efficiently (no rebuild):
@@ -209,4 +228,3 @@ Types are extracted from the `superdoc` package, ensuring they stay in sync.
 ## License
 
 AGPL-3.0
-

package/dist/index.cjs

@@ -1 +1 @@
-Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:`Module`}});var e=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,i=Object.getPrototypeOf,a=Object.prototype.hasOwnProperty,o=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=r(i),l=0,u=c.length,d;l<u;l++)d=c[l],!a.call(e,d)&&d!==o&&t(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=n(i,d))||s.enumerable});return e},s=(n,r,a)=>(a=n==null?{}:e(i(n)),o(r||!n||!n.__esModule?t(a,`default`,{value:n,enumerable:!0}):a,n));let c=require(`react`);c=s(c);let l=require(`react/jsx-runtime`);function u(){let e=c.useRef(null);return e.current===null&&(e.current=`-${Date.now()}-${Math.random().toString(36).slice(2,9)}`),e.current}var d=c.useId;const f=typeof d==`function`?d:u;function p(e){let t=c.useRef(e),n=c.useRef(e);return t.current!==e&&(m(n.current,e)||(n.current=e),t.current=e),n.current}function m(e,t){if(e===t)return!0;if(e==null||t==null)return e===t;try{return JSON.stringify(e)===JSON.stringify(t)}catch{return!1}}function h(e,t){let[n,r]=(0,c.useState)(!1),{id:i,renderLoading:a,hideToolbar:o=!1,contained:s=!1,className:u,style:d,onReady:m,onEditorCreate:h,onEditorDestroy:g,onEditorUpdate:_,onTransaction:v,onContentError:y,onException:b,document:x,user:S,users:C,modules:w,...T}=e,E=e.documentMode??`editing`,D=e.role??`editor`,O=p(S),k=p(C),A=(0,c.useRef)(null),j=(0,c.useRef)(null),M=f(),N=i??`superdoc${M}`,P=N,F=`${N}-toolbar`,[I,L]=(0,c.useState)(!0),R=(0,c.useRef)({onReady:m,onEditorCreate:h,onEditorDestroy:g,onEditorUpdate:_,onTransaction:v,onContentError:y,onException:b});(0,c.useEffect)(()=>{R.current={onReady:m,onEditorCreate:h,onEditorDestroy:g,onEditorUpdate:_,onTransaction:v,onContentError:y,onException:b}},[m,h,g,_,v,y,b]);let z=(0,c.useRef)(null),B=(0,c.useRef)(!1),V=(0,c.useRef)(E);(0,c.useEffect)(()=>{V.current!==E&&(A.current?A.current.setDocumentMode(E):B.current&&(z.current=E)),V.current=E},[E]),(0,c.useImperativeHandle)(t,()=>({getInstance:()=>A.current}),[]),(0,c.useEffect)(()=>{L(!0),r(!1),B.current=!0;let e=!1,t=null;return(async()=>{try{let n=(await import(`superdoc`)).SuperDoc;if(e)return;t=new n({...T,selector:`#${CSS.escape(P)}`,...!o&&j.current?{toolbar:`#${CSS.escape(F)}`}:{},documentMode:E,role:D,contained:s,...x==null?{}:{document:x},...O?{user:O}:{},...k?{users:k}:{},...w?{modules:w}:{},onReady:t=>{e||(L(!1),B.current=!1,z.current&&z.current!==E&&(t.superdoc.setDocumentMode(z.current),z.current=null),R.current.onReady?.(t))},onEditorCreate:t=>{e||R.current.onEditorCreate?.(t)},onEditorDestroy:()=>{e||R.current.onEditorDestroy?.()},onEditorUpdate:t=>{e||R.current.onEditorUpdate?.(t)},onTransaction:t=>{e||R.current.onTransaction?.(t)},onContentError:t=>{e||R.current.onContentError?.(t)},onException:t=>{e||R.current.onException?.(t)}}),A.current=t}catch(t){e||(B.current=!1,L(!1),r(!0),console.error(`[SuperDocEditor] Failed to initialize SuperDoc:`,t),R.current.onException?.({error:t}))}})(),()=>{B.current=!1,z.current=null,t&&(t.destroy(),A.current=null),e=!0}},[x,O,k,w,D,o,s,P,F]);let H=[`superdoc-wrapper`,u].filter(Boolean).join(` `),U=I?{display:`none`}:void 0;return(0,l.jsxs)(`div`,{className:H,style:{...d,...s&&{display:`flex`,flexDirection:`column`}},children:[!o&&(0,l.jsx)(`div`,{ref:j,id:F,className:`superdoc-toolbar-container`,style:U}),(0,l.jsx)(`div`,{id:P,className:`superdoc-editor-container`,style:{...U,...s&&{flex:1,minHeight:0}}}),I&&!n&&a&&(0,l.jsx)(`div`,{className:`superdoc-loading-container`,children:a()}),n&&(0,l.jsx)(`div`,{className:`superdoc-error-container`,children:`Failed to load editor. Check console for details.`})]})}const g=(0,c.forwardRef)(h);g.displayName=`SuperDocEditor`;var _=g;exports.SuperDocEditor=g,exports.default=_;
+Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:`Module`}});var e=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,i=Object.getPrototypeOf,a=Object.prototype.hasOwnProperty,o=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=r(i),l=0,u=c.length,d;l<u;l++)d=c[l],!a.call(e,d)&&d!==o&&t(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=n(i,d))||s.enumerable});return e},s=(n,r,a)=>(a=n==null?{}:e(i(n)),o(r||!n||!n.__esModule?t(a,`default`,{value:n,enumerable:!0}):a,n));let c=require(`react`);c=s(c);let l=require(`react/jsx-runtime`);function u(){let e=c.useRef(null);return e.current===null&&(e.current=`-${Date.now()}-${Math.random().toString(36).slice(2,9)}`),e.current}var d=c.useId;const f=typeof d==`function`?d:u;function p(e){let t=c.useRef(e),n=c.useRef(e);return t.current!==e&&(m(n.current,e)||(n.current=e),t.current=e),n.current}function m(e,t){if(e===t)return!0;if(e==null||t==null)return e===t;try{return JSON.stringify(e)===JSON.stringify(t)}catch{return!1}}function h(e,t){let[n,r]=(0,c.useState)(!1),{id:i,renderLoading:a,hideToolbar:o=!1,contained:s=!1,className:u,style:d,onReady:m,onEditorCreate:h,onEditorDestroy:g,onEditorUpdate:_,onTransaction:v,onContentError:y,onException:b,onZoomChange:x,onViewportChange:S,document:C,user:w,users:T,modules:E,...D}=e,O=e.documentMode??`editing`,k=e.role??`editor`,A=p(w),j=p(T),M=(0,c.useRef)(null),N=(0,c.useRef)(null),P=f(),F=i??`superdoc${P}`,I=F,L=`${F}-toolbar`,[R,z]=(0,c.useState)(!0),B=(0,c.useRef)({onReady:m,onEditorCreate:h,onEditorDestroy:g,onEditorUpdate:_,onTransaction:v,onContentError:y,onException:b,onZoomChange:x,onViewportChange:S});(0,c.useEffect)(()=>{B.current={onReady:m,onEditorCreate:h,onEditorDestroy:g,onEditorUpdate:_,onTransaction:v,onContentError:y,onException:b,onZoomChange:x,onViewportChange:S}},[m,h,g,_,v,y,b,x,S]);let V=(0,c.useRef)(null),H=(0,c.useRef)(!1),U=(0,c.useRef)(O);(0,c.useEffect)(()=>{U.current!==O&&(M.current?M.current.setDocumentMode(O):H.current&&(V.current=O)),U.current=O},[O]),(0,c.useImperativeHandle)(t,()=>({getInstance:()=>M.current}),[]),(0,c.useEffect)(()=>{z(!0),r(!1),H.current=!0;let e=!1,t=null;return(async()=>{try{let n=(await import(`superdoc`)).SuperDoc;if(e)return;t=new n({...D,selector:`#${CSS.escape(I)}`,...!o&&N.current?{toolbar:`#${CSS.escape(L)}`}:{},documentMode:O,role:k,contained:s,...C==null?{}:{document:C},...A?{user:A}:{},...j?{users:j}:{},...E?{modules:E}:{},onReady:t=>{e||(z(!1),H.current=!1,V.current&&V.current!==O&&(t.superdoc.setDocumentMode(V.current),V.current=null),B.current.onReady?.(t))},onEditorCreate:t=>{e||B.current.onEditorCreate?.(t)},onEditorDestroy:()=>{e||B.current.onEditorDestroy?.()},onEditorUpdate:t=>{e||B.current.onEditorUpdate?.(t)},onTransaction:t=>{e||B.current.onTransaction?.(t)},onContentError:t=>{e||B.current.onContentError?.(t)},onException:t=>{e||B.current.onException?.(t)},onZoomChange:t=>{e||B.current.onZoomChange?.(t)},onViewportChange:t=>{e||B.current.onViewportChange?.(t)}}),M.current=t}catch(t){e||(H.current=!1,z(!1),r(!0),console.error(`[SuperDocEditor] Failed to initialize SuperDoc:`,t),B.current.onException?.({error:t}))}})(),()=>{H.current=!1,V.current=null,t&&(t.destroy(),M.current=null),e=!0}},[C,A,j,E,k,o,s,I,L]);let W=[`superdoc-wrapper`,u].filter(Boolean).join(` `),G=R?{display:`none`}:void 0;return(0,l.jsxs)(`div`,{className:W,style:{...d,...s&&{display:`flex`,flexDirection:`column`}},children:[!o&&(0,l.jsx)(`div`,{ref:N,id:L,className:`superdoc-toolbar-container`,style:G}),(0,l.jsx)(`div`,{id:I,className:`superdoc-editor-container`,style:{...G,...s&&{flex:1,minHeight:0}}}),R&&!n&&a&&(0,l.jsx)(`div`,{className:`superdoc-loading-container`,children:a()}),n&&(0,l.jsx)(`div`,{className:`superdoc-error-container`,children:`Failed to load editor. Check console for details.`})]})}const g=(0,c.forwardRef)(h);g.displayName=`SuperDocEditor`;var _=g;exports.SuperDocEditor=g,exports.default=_;

package/dist/index.d.ts

@@ -26,6 +26,10 @@ export declare interface CallbackProps {
     onContentError?: (event: SuperDocContentErrorEvent) => void;
     /** Callback when an exception is thrown */
     onException?: (event: SuperDocExceptionEvent) => void;
+    /** Callback when the zoom level changes (setZoom, toolbar, or fit-width mode) */
+    onZoomChange?: (event: SuperDocZoomChangeEvent) => void;
+    /** Callback when the implied fit changes (rounded fit zoom or base page width); see the core viewport-change event */
+    onViewportChange?: (event: SuperDocViewportChangeEvent) => void;
 }
 
 /** Document mode - extracted from Config.documentMode */
@@ -40,7 +44,7 @@ export declare type EditorSurface = 'body' | 'header' | 'footer';
  * Callback props that are explicitly typed in CallbackProps.
  * These are excluded from SuperDocConfig to avoid type conflicts.
  */
-declare type ExplicitCallbackProps = 'onReady' | 'onEditorCreate' | 'onEditorDestroy' | 'onEditorUpdate' | 'onTransaction' | 'onContentError' | 'onException';
+declare type ExplicitCallbackProps = 'onReady' | 'onEditorCreate' | 'onEditorDestroy' | 'onEditorUpdate' | 'onTransaction' | 'onContentError' | 'onException' | 'onZoomChange' | 'onViewportChange';
 
 /**
  * Props managed internally by the React component (not exposed to users).
@@ -181,6 +185,20 @@ export declare interface SuperDocTransactionEvent {
 /** User object - extracted from Config.user */
 export declare type SuperDocUser = NonNullable<SuperDocConstructorConfig['user']>;
 
+/**
+ * Event passed to onViewportChange callback. Re-derived from the core
+ * `Config.onViewportChange` parameter so the React wrapper cannot
+ * drift from the core contract.
+ */
+export declare type SuperDocViewportChangeEvent = Parameters<NonNullable<SuperDocConfig['onViewportChange']>>[0];
+
+/**
+ * Event passed to onZoomChange callback. Re-derived from the core
+ * `Config.onZoomChange` parameter so the React wrapper cannot drift
+ * from the core contract.
+ */
+export declare type SuperDocZoomChangeEvent = Parameters<NonNullable<SuperDocConfig['onZoomChange']>>[0];
+
 /** User role - extracted from Config.role */
 export declare type UserRole = NonNullable<SuperDocConstructorConfig['role']>;
 

package/dist/index.js

@@ -21,24 +21,28 @@ function shallowJsonEqual(e, s) {
 	}
 }
 function SuperDocEditorInner(e, s) {
-	let [u, d] = useState(!1), { id: f, renderLoading: p, hideToolbar: m = !1, contained: h = !1, className: g, style: _, onReady: v, onEditorCreate: y, onEditorDestroy: b, onEditorUpdate: x, onTransaction: S, onContentError: C, onException: w, document: T, user: E, users: D, modules: O, ...k } = e, A = e.documentMode ?? "editing", j = e.role ?? "editor", M = useMemoByValue(E), N = useMemoByValue(D), P = useRef(null), F = useRef(null), I = useStableId(), L = f ?? `superdoc${I}`, R = L, z = `${L}-toolbar`, [B, V] = useState(!0), H = useRef({
+	let [u, d] = useState(!1), { id: f, renderLoading: p, hideToolbar: m = !1, contained: h = !1, className: g, style: _, onReady: v, onEditorCreate: y, onEditorDestroy: b, onEditorUpdate: x, onTransaction: S, onContentError: C, onException: w, onZoomChange: T, onViewportChange: E, document: D, user: O, users: k, modules: A, ...j } = e, M = e.documentMode ?? "editing", N = e.role ?? "editor", P = useMemoByValue(O), F = useMemoByValue(k), I = useRef(null), L = useRef(null), R = useStableId(), z = f ?? `superdoc${R}`, B = z, V = `${z}-toolbar`, [H, U] = useState(!0), W = useRef({
 		onReady: v,
 		onEditorCreate: y,
 		onEditorDestroy: b,
 		onEditorUpdate: x,
 		onTransaction: S,
 		onContentError: C,
-		onException: w
+		onException: w,
+		onZoomChange: T,
+		onViewportChange: E
 	});
 	useEffect(() => {
-		H.current = {
+		W.current = {
 			onReady: v,
 			onEditorCreate: y,
 			onEditorDestroy: b,
 			onEditorUpdate: x,
 			onTransaction: S,
 			onContentError: C,
-			onException: w
+			onException: w,
+			onZoomChange: T,
+			onViewportChange: E
 		};
 	}, [
 		v,
@@ -47,71 +51,79 @@ function SuperDocEditorInner(e, s) {
 		x,
 		S,
 		C,
-		w
+		w,
+		T,
+		E
 	]);
-	let U = useRef(null), W = useRef(!1), G = useRef(A);
+	let G = useRef(null), K = useRef(!1), q = useRef(M);
 	useEffect(() => {
-		G.current !== A && (P.current ? P.current.setDocumentMode(A) : W.current && (U.current = A)), G.current = A;
-	}, [A]), useImperativeHandle(s, () => ({ getInstance: () => P.current }), []), useEffect(() => {
-		V(!0), d(!1), W.current = !0;
+		q.current !== M && (I.current ? I.current.setDocumentMode(M) : K.current && (G.current = M)), q.current = M;
+	}, [M]), useImperativeHandle(s, () => ({ getInstance: () => I.current }), []), useEffect(() => {
+		U(!0), d(!1), K.current = !0;
 		let e = !1, s = null;
 		return (async () => {
 			try {
 				let c = (await import("superdoc")).SuperDoc;
 				if (e) return;
 				s = new c({
-					...k,
-					selector: `#${CSS.escape(R)}`,
-					...!m && F.current ? { toolbar: `#${CSS.escape(z)}` } : {},
-					documentMode: A,
-					role: j,
+					...j,
+					selector: `#${CSS.escape(B)}`,
+					...!m && L.current ? { toolbar: `#${CSS.escape(V)}` } : {},
+					documentMode: M,
+					role: N,
 					contained: h,
-					...T == null ? {} : { document: T },
-					...M ? { user: M } : {},
-					...N ? { users: N } : {},
-					...O ? { modules: O } : {},
+					...D == null ? {} : { document: D },
+					...P ? { user: P } : {},
+					...F ? { users: F } : {},
+					...A ? { modules: A } : {},
 					onReady: (s) => {
-						e || (V(!1), W.current = !1, U.current && U.current !== A && (s.superdoc.setDocumentMode(U.current), U.current = null), H.current.onReady?.(s));
+						e || (U(!1), K.current = !1, G.current && G.current !== M && (s.superdoc.setDocumentMode(G.current), G.current = null), W.current.onReady?.(s));
 					},
 					onEditorCreate: (s) => {
-						e || H.current.onEditorCreate?.(s);
+						e || W.current.onEditorCreate?.(s);
 					},
 					onEditorDestroy: () => {
-						e || H.current.onEditorDestroy?.();
+						e || W.current.onEditorDestroy?.();
 					},
 					onEditorUpdate: (s) => {
-						e || H.current.onEditorUpdate?.(s);
+						e || W.current.onEditorUpdate?.(s);
 					},
 					onTransaction: (s) => {
-						e || H.current.onTransaction?.(s);
+						e || W.current.onTransaction?.(s);
 					},
 					onContentError: (s) => {
-						e || H.current.onContentError?.(s);
+						e || W.current.onContentError?.(s);
 					},
 					onException: (s) => {
-						e || H.current.onException?.(s);
+						e || W.current.onException?.(s);
+					},
+					onZoomChange: (s) => {
+						e || W.current.onZoomChange?.(s);
+					},
+					onViewportChange: (s) => {
+						e || W.current.onViewportChange?.(s);
 					}
-				}), P.current = s;
+				}), I.current = s;
 			} catch (s) {
-				e || (W.current = !1, V(!1), d(!0), console.error("[SuperDocEditor] Failed to initialize SuperDoc:", s), H.current.onException?.({ error: s }));
+				e || (K.current = !1, U(!1), d(!0), console.error("[SuperDocEditor] Failed to initialize SuperDoc:", s), W.current.onException?.({ error: s }));
 			}
 		})(), () => {
-			W.current = !1, U.current = null, s && (s.destroy(), P.current = null), e = !0;
+			K.current = !1, G.current = null, s && (s.destroy(), I.current = null), e = !0;
 		};
 	}, [
-		T,
-		M,
+		D,
+		P,
+		F,
+		A,
 		N,
-		O,
-		j,
 		m,
 		h,
-		R,
-		z
+		B,
+		V
 	]);
-	let K = ["superdoc-wrapper", g].filter(Boolean).join(" "), q = B ? { display: "none" } : void 0;
+	let J = ["superdoc-wrapper", g].filter(Boolean).join(" "), Y = H ? { display: "none" } : void 0;
 	return /* @__PURE__ */ jsxs("div", {
-		className: K,
+		className: J,
 		style: {
 			..._,
 			...h && {
@@ -121,23 +133,23 @@ function SuperDocEditorInner(e, s) {
 		},
 		children: [
 			!m && /* @__PURE__ */ jsx("div", {
-				ref: F,
-				id: z,
+				ref: L,
+				id: V,
 				className: "superdoc-toolbar-container",
-				style: q
+				style: Y
 			}),
 			/* @__PURE__ */ jsx("div", {
-				id: R,
+				id: B,
 				className: "superdoc-editor-container",
 				style: {
-					...q,
+					...Y,
 					...h && {
 						flex: 1,
 						minHeight: 0
 					}
 				}
 			}),
-			B && !u && p && /* @__PURE__ */ jsx("div", {
+			H && !u && p && /* @__PURE__ */ jsx("div", {
 				className: "superdoc-loading-container",
 				children: p()
 			}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdoc-dev/react",
-  "version": "1.10.0-next.9",
+  "version": "1.11.0-next.1",
   "description": "Official React wrapper for the SuperDoc document editor",
   "type": "module",
   "main": "./dist/index.cjs",