@superdoc-dev/react 1.0.0-canary.2

package/README.md

@@ -0,0 +1,159 @@
+# @superdoc/react
+
+Official React wrapper for [SuperDoc](https://www.superdoc.dev).
+
+## Installation
+
+```bash
+npm install @superdoc/react
+```
+
+> `superdoc` is included as a dependency - no need to install it separately.
+
+## Quick Start
+
+```tsx
+import { SuperDocEditor } from '@superdoc/react';
+import '@superdoc/react/style.css';
+
+function App() {
+  return <SuperDocEditor document={file} />;
+}
+```
+
+## Changing Mode
+
+Just update the `documentMode` prop - the component handles it efficiently (no rebuild):
+
+```tsx
+function App() {
+  const [mode, setMode] = useState<DocumentMode>('editing');
+
+  return (
+    <>
+      <button onClick={() => setMode('viewing')}>View</button>
+      <button onClick={() => setMode('editing')}>Edit</button>
+      <SuperDocEditor document={file} documentMode={mode} />
+    </>
+  );
+}
+```
+
+## Using the Ref
+
+Access SuperDoc methods via `getInstance()`:
+
+```tsx
+import { useRef } from 'react';
+import { SuperDocEditor, SuperDocRef } from '@superdoc/react';
+
+function App() {
+  const ref = useRef<SuperDocRef>(null);
+
+  const handleExport = async () => {
+    await ref.current?.getInstance()?.export({ triggerDownload: true });
+  };
+
+  return (
+    <>
+      <SuperDocEditor ref={ref} document={file} />
+      <button onClick={handleExport}>Export</button>
+    </>
+  );
+}
+```
+
+## Props
+
+All [SuperDoc config options](https://docs.superdoc.dev) are available as props, plus:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `id` | `string` | Custom container ID (auto-generated if not provided) |
+| `renderLoading` | `() => ReactNode` | Loading UI |
+| `hideToolbar` | `boolean` | Hide toolbar (default: false) |
+| `className` | `string` | Wrapper CSS class |
+| `style` | `CSSProperties` | Wrapper inline styles |
+
+### Common Props
+
+```tsx
+<SuperDocEditor
+  document={file}              // File, Blob, URL, or config object
+  documentMode="editing"       // 'editing' | 'viewing' | 'suggesting'
+  role="editor"                // 'editor' | 'viewer' | 'suggester'
+  user={{ name: 'John', email: 'john@example.com' }}
+  onReady={({ superdoc }) => console.log('Ready!')}
+  onEditorCreate={({ editor }) => console.log('Editor created')}
+/>
+```
+
+## Examples
+
+### View-Only Mode
+
+```tsx
+<SuperDocEditor
+  document={file}
+  documentMode="viewing"
+  hideToolbar
+/>
+```
+
+### File Upload
+
+```tsx
+function Editor() {
+  const [file, setFile] = useState<File | null>(null);
+
+  return (
+    <>
+      <input type="file" accept=".docx" onChange={(e) => setFile(e.target.files?.[0] || null)} />
+      {file && <SuperDocEditor document={file} />}
+    </>
+  );
+}
+```
+
+### With Collaboration
+
+```tsx
+<SuperDocEditor
+  document={file}
+  modules={{
+    collaboration: { ydoc, provider },
+  }}
+/>
+```
+
+## Next.js
+
+```tsx
+'use client';
+
+import dynamic from 'next/dynamic';
+
+const SuperDocEditor = dynamic(
+  () => import('@superdoc/react').then((m) => m.SuperDocEditor),
+  { ssr: false }
+);
+```
+
+## TypeScript
+
+```tsx
+import type {
+  SuperDocEditorProps,
+  SuperDocRef,
+  DocumentMode,
+  UserRole,
+  SuperDocUser,
+} from '@superdoc/react';
+```
+
+Types are extracted from the `superdoc` package, ensuring they stay in sync.
+
+## License
+
+AGPL-3.0
+

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const i=require("react/jsx-runtime"),e=require("react");function O(){return`superdoc-${Date.now()}-${Math.random().toString(36).slice(2,9)}`}function A(l,q){const[f,z]=e.useState(!1);e.useEffect(()=>{z(!0)},[]);const{id:T,renderLoading:d,hideToolbar:p=!1,className:_,style:j,onReady:E,onEditorCreate:m,onEditorDestroy:R,onEditorUpdate:S,onContentError:D,onException:g,document:y,user:C,users:I,modules:b,...k}=l,n=l.documentMode??"editing",v=l.role??"editor",s=e.useRef(null),N=e.useRef(null),M=e.useRef(null);if(M.current===null){const r=T??O();M.current={containerId:r,toolbarId:`${r}-toolbar`}}const{containerId:w,toolbarId:P}=M.current,[B,$]=e.useState(!0),o=e.useRef({onReady:E,onEditorCreate:m,onEditorDestroy:R,onEditorUpdate:S,onContentError:D,onException:g});e.useEffect(()=>{o.current={onReady:E,onEditorCreate:m,onEditorDestroy:R,onEditorUpdate:S,onContentError:D,onException:g}},[E,m,R,S,D,g]);const c=e.useRef(null),u=e.useRef(!1),L=e.useRef(n);e.useEffect(()=>{L.current!==n&&(s.current?s.current.setDocumentMode(n):u.current&&(c.current=n)),L.current=n},[n]),e.useImperativeHandle(q,()=>({getInstance:()=>s.current}),[]),e.useEffect(()=>{if(!f)return;$(!0),u.current=!0;let r=!1,a=null;return(async()=>{try{const F=(await import("superdoc")).SuperDoc;if(r)return;const H={...k,selector:`#${CSS.escape(w)}`,...!p&&N.current?{toolbar:`#${CSS.escape(P)}`}:{},documentMode:n,role:v,...y!=null?{document:y}:{},...C?{user:C}:{},...I?{users:I}:{},...b?{modules:b}:{},onReady:t=>{r||($(!1),u.current=!1,c.current&&c.current!==n&&(t.superdoc.setDocumentMode(c.current),c.current=null),o.current.onReady?.(t))},onEditorCreate:t=>{r||o.current.onEditorCreate?.(t)},onEditorDestroy:()=>{r||o.current.onEditorDestroy?.()},onEditorUpdate:t=>{r||o.current.onEditorUpdate?.(t)},onContentError:t=>{r||o.current.onContentError?.(t)},onException:t=>{r||o.current.onException?.(t)}};a=new F(H),s.current=a}catch(x){r||(u.current=!1,console.error("[SuperDocEditor] Failed to initialize SuperDoc:",x),o.current.onException?.({error:x}))}})(),()=>{r=!0,u.current=!1,c.current=null,a&&(a.destroy(),s.current=null)}},[f,y,C,I,b,v,p]);const U=["superdoc-wrapper",_].filter(Boolean).join(" ");return f?i.jsxs("div",{className:U,style:j,children:[!p&&i.jsx("div",{ref:N,id:P,className:"superdoc-toolbar-container"}),i.jsx("div",{id:w,className:"superdoc-editor-container"}),B&&d&&i.jsx("div",{className:"superdoc-loading-container",children:d()})]}):d?i.jsx("div",{className:U,style:j,children:d()}):null}const h=e.forwardRef(A);h.displayName="SuperDocEditor";exports.SuperDocEditor=h;exports.default=h;

package/dist/index.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @superdoc-dev/react - Official React wrapper for SuperDoc
+ * @packageDocumentation
+ */
+
+import { CSSProperties } from 'react';
+import { ForwardRefExoticComponent } from 'react';
+import { ReactNode } from 'react';
+import { RefAttributes } from 'react';
+import { SuperDoc } from 'superdoc';
+
+/** Document mode - extracted from Config.documentMode */
+export declare type DocumentMode = NonNullable<SuperDocConstructorConfig['documentMode']>;
+
+/**
+ * Props managed internally by the React component (not exposed to users).
+ * - selector: managed by component (creates internal container)
+ */
+declare type InternalProps = 'selector';
+
+/**
+ * Props that are required in core but should be optional in React.
+ * - documentMode: defaults to 'editing' if not provided
+ */
+declare type OptionalInReact = 'documentMode';
+
+/**
+ * React-specific props added on top of SuperDocConfig.
+ */
+declare interface ReactProps {
+    /** Optional ID for the editor container. Auto-generated if not provided. */
+    id?: string;
+    /** Render function for loading state */
+    renderLoading?: () => ReactNode;
+    /** Hide the toolbar container. When true, no toolbar is rendered. @default false */
+    hideToolbar?: boolean;
+    /** Additional CSS class name for the wrapper element */
+    className?: string;
+    /** Additional inline styles for the wrapper element */
+    style?: CSSProperties;
+}
+
+/** Full SuperDoc config - extracted from constructor */
+export declare type SuperDocConfig = SuperDocConstructorConfig;
+
+/**
+ * Types for @superdoc/react
+ *
+ * Core types are extracted from the SuperDoc constructor parameter type,
+ * ensuring they stay in sync with the superdoc package.
+ */
+/** SuperDoc constructor config - extracted from superdoc package */
+declare type SuperDocConstructorConfig = ConstructorParameters<typeof SuperDoc>[0];
+
+/**
+ * SuperDocEditor component with forwardRef - Initializes SuperDoc instance and handles cleanup.
+ */
+declare const SuperDocEditor: ForwardRefExoticComponent<SuperDocEditorProps & RefAttributes<SuperDocRef>>;
+export { SuperDocEditor }
+export default SuperDocEditor;
+
+/**
+ * Props for SuperDocEditor component.
+ *
+ * Extends SuperDocConfig (minus internal props) with React-specific additions.
+ * When new props are added to SuperDoc core, they're automatically available here.
+ *
+ * Note: All callback types (onReady, onEditorCreate, etc.) come directly from
+ * SuperDocConfig, ensuring type compatibility with the core package.
+ */
+export declare interface SuperDocEditorProps extends Omit<SuperDocConfig, InternalProps | OptionalInReact>, Partial<Pick<SuperDocConfig, OptionalInReact>>, ReactProps {
+}
+
+/** SuperDoc instance type - from superdoc package */
+export declare type SuperDocInstance = InstanceType<typeof SuperDoc>;
+
+/** Modules configuration - extracted from Config.modules */
+export declare type SuperDocModules = NonNullable<SuperDocConstructorConfig['modules']>;
+
+/**
+ * Ref interface for SuperDocEditor component
+ */
+export declare interface SuperDocRef {
+    /** Get the underlying SuperDoc instance. Returns null if not yet initialized. */
+    getInstance(): SuperDocInstance | null;
+}
+
+/** User object - extracted from Config.user */
+export declare type SuperDocUser = NonNullable<SuperDocConstructorConfig['user']>;
+
+/** User role - extracted from Config.role */
+export declare type UserRole = NonNullable<SuperDocConstructorConfig['role']>;
+
+export { }

package/dist/index.js

@@ -0,0 +1,126 @@
+import { jsx as a, jsxs as J } from "react/jsx-runtime";
+import { forwardRef as K, useState as z, useEffect as l, useRef as o, useImperativeHandle as O } from "react";
+function Q() {
+  return `superdoc-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+}
+function V(f, k) {
+  const [p, B] = z(!1);
+  l(() => {
+    B(!0);
+  }, []);
+  const {
+    // React-specific
+    id: F,
+    renderLoading: u,
+    hideToolbar: m = !1,
+    className: H,
+    style: x,
+    // Callbacks (stored in ref to avoid triggering rebuilds)
+    onReady: E,
+    onEditorCreate: D,
+    onEditorDestroy: S,
+    onEditorUpdate: C,
+    onContentError: y,
+    onException: I,
+    // Key props that trigger rebuild when changed
+    document: R,
+    user: g,
+    users: b,
+    modules: M,
+    // All other props passed through
+    ...T
+  } = f, t = f.documentMode ?? "editing", v = f.role ?? "editor", i = o(null), w = o(null), h = o(null);
+  if (h.current === null) {
+    const e = F ?? Q();
+    h.current = { containerId: e, toolbarId: `${e}-toolbar` };
+  }
+  const { containerId: $, toolbarId: P } = h.current, [q, j] = z(!0), n = o({
+    onReady: E,
+    onEditorCreate: D,
+    onEditorDestroy: S,
+    onEditorUpdate: C,
+    onContentError: y,
+    onException: I
+  });
+  l(() => {
+    n.current = {
+      onReady: E,
+      onEditorCreate: D,
+      onEditorDestroy: S,
+      onEditorUpdate: C,
+      onContentError: y,
+      onException: I
+    };
+  }, [E, D, S, C, y, I]);
+  const c = o(null), s = o(!1), L = o(t);
+  l(() => {
+    L.current !== t && (i.current ? i.current.setDocumentMode(t) : s.current && (c.current = t)), L.current = t;
+  }, [t]), O(
+    k,
+    () => ({
+      getInstance: () => i.current
+    }),
+    []
+  ), l(() => {
+    if (!p) return;
+    j(!0), s.current = !0;
+    let e = !1, d = null;
+    return (async () => {
+      try {
+        const A = (await import("superdoc")).SuperDoc;
+        if (e) return;
+        const G = {
+          ...T,
+          selector: `#${CSS.escape($)}`,
+          // Use internal toolbar container unless hideToolbar is true
+          ...!m && w.current ? { toolbar: `#${CSS.escape(P)}` } : {},
+          documentMode: t,
+          role: v,
+          ...R != null ? { document: R } : {},
+          ...g ? { user: g } : {},
+          ...b ? { users: b } : {},
+          ...M ? { modules: M } : {},
+          // Wire up callbacks with lifecycle guards
+          onReady: (r) => {
+            e || (j(!1), s.current = !1, c.current && c.current !== t && (r.superdoc.setDocumentMode(c.current), c.current = null), n.current.onReady?.(r));
+          },
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          onEditorCreate: (r) => {
+            e || n.current.onEditorCreate?.(r);
+          },
+          onEditorDestroy: () => {
+            e || n.current.onEditorDestroy?.();
+          },
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          onEditorUpdate: (r) => {
+            e || n.current.onEditorUpdate?.(r);
+          },
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          onContentError: (r) => {
+            e || n.current.onContentError?.(r);
+          },
+          onException: (r) => {
+            e || n.current.onException?.(r);
+          }
+        };
+        d = new A(G), i.current = d;
+      } catch (N) {
+        e || (s.current = !1, console.error("[SuperDocEditor] Failed to initialize SuperDoc:", N), n.current.onException?.({ error: N }));
+      }
+    })(), () => {
+      e = !0, s.current = !1, c.current = null, d && (d.destroy(), i.current = null);
+    };
+  }, [p, R, g, b, M, v, m]);
+  const U = ["superdoc-wrapper", H].filter(Boolean).join(" ");
+  return p ? /* @__PURE__ */ J("div", { className: U, style: x, children: [
+    !m && /* @__PURE__ */ a("div", { ref: w, id: P, className: "superdoc-toolbar-container" }),
+    /* @__PURE__ */ a("div", { id: $, className: "superdoc-editor-container" }),
+    q && u && /* @__PURE__ */ a("div", { className: "superdoc-loading-container", children: u() })
+  ] }) : u ? /* @__PURE__ */ a("div", { className: U, style: x, children: u() }) : null;
+}
+const W = K(V);
+W.displayName = "SuperDocEditor";
+export {
+  W as SuperDocEditor,
+  W as default
+};

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@superdoc-dev/react",
+  "version": "1.0.0-canary.2",
+  "description": "Official React wrapper for SuperDoc document editor",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.js"
+    },
+    "./style.css": {
+      "import": "./style.css",
+      "require": "./style.css"
+    }
+  },
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch",
+    "test": "vitest run",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint src --ext .ts,.tsx",
+    "prepublishOnly": "pnpm run build"
+  },
+  "keywords": [
+    "superdoc",
+    "react",
+    "document",
+    "editor",
+    "docx",
+    "word"
+  ],
+  "license": "AGPL-3.0",
+  "dependencies": {
+    "superdoc": "workspace:*"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0",
+    "react-dom": ">=16.8.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "catalog:",
+    "@types/node": "catalog:",
+    "@types/react": "catalog:",
+    "@types/react-dom": "catalog:",
+    "@typescript-eslint/eslint-plugin": "catalog:",
+    "@typescript-eslint/parser": "catalog:",
+    "eslint": "catalog:",
+    "happy-dom": "catalog:",
+    "react": "catalog:",
+    "react-dom": "catalog:",
+    "typescript": "catalog:",
+    "vite": "catalog:",
+    "vite-plugin-dts": "catalog:",
+    "@vitejs/plugin-react": "catalog:",
+    "vitest": "catalog:"
+  },
+  "files": [
+    "dist",
+    "style.css",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/superdoc-dev/superdoc.git",
+    "directory": "packages/react"
+  },
+  "bugs": {
+    "url": "https://github.com/superdoc-dev/superdoc/issues"
+  },
+  "homepage": "https://github.com/superdoc-dev/superdoc/tree/main/packages/react#readme"
+}

package/style.css

@@ -0,0 +1,2 @@
+/* @superdoc/react styles - re-exports superdoc styles */
+@import 'superdoc/style.css';