@hocuspocus/provider-react 4.3.0 → 4.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -101,7 +101,7 @@ const EVENT_PROP_MAP = {
101
101
  * </HocuspocusProviderWebsocketComponent>
102
102
  * ```
103
103
  */
104
- function HocuspocusRoom({ children, name, document, token, sessionAwareness, ...eventHandlers }) {
104
+ function HocuspocusRoom({ children, name, document, token, sessionAwareness, flushDelay, ...eventHandlers }) {
105
105
  const hocuspocusContext = (0, react.useContext)(HocuspocusContext);
106
106
  if (!hocuspocusContext) throw new Error("HocuspocusRoom must be used within a HocuspocusProviderWebsocketComponent");
107
107
  const { websocketProvider } = hocuspocusContext;
@@ -110,7 +110,8 @@ function HocuspocusRoom({ children, name, document, token, sessionAwareness, ...
110
110
  websocketProvider,
111
111
  document,
112
112
  token,
113
- sessionAwareness
113
+ sessionAwareness,
114
+ flushDelay
114
115
  }));
115
116
  const destroyTimeoutRef = (0, react.useRef)(null);
116
117
  (0, react.useEffect)(() => {
@@ -121,7 +122,8 @@ function HocuspocusRoom({ children, name, document, token, sessionAwareness, ...
121
122
  websocketProvider,
122
123
  document,
123
124
  token,
124
- sessionAwareness
125
+ sessionAwareness,
126
+ flushDelay
125
127
  }));
126
128
  }
127
129
  }, [
@@ -1 +1 @@
1
- {"version":3,"file":"hocuspocus-provider-react.cjs","names":["HocuspocusProviderWebsocket","HocuspocusProvider"],"sources":["../src/context.ts","../src/HocuspocusProviderWebsocketComponent.tsx","../src/HocuspocusRoom.tsx","../src/hooks/useHocuspocusProvider.ts","../src/hooks/useHocuspocusAwareness.ts","../src/hooks/useHocuspocusConnectionStatus.ts","../src/hooks/useHocuspocusEvent.ts","../src/hooks/useHocuspocusSyncStatus.ts"],"sourcesContent":["import { createContext } from \"react\";\n\nimport type {\n\tHocuspocusContextValue,\n\tHocuspocusRoomContextValue,\n} from \"./types.ts\";\n\n/**\n * Context for the WebSocket connection shared across rooms\n */\nexport const HocuspocusContext =\n\tcreateContext<HocuspocusContextValue | null>(null);\n\n/**\n * Context for the room/document provider\n */\nexport const HocuspocusRoomContext =\n\tcreateContext<HocuspocusRoomContextValue | null>(null);\n","\"use client\";\n\nimport { HocuspocusProviderWebsocket } from \"@hocuspocus/provider\";\nimport { useEffect, useMemo, useRef } from \"react\";\n\nimport { HocuspocusContext } from \"./context.ts\";\nimport type { HocuspocusProviderWebsocketComponentProps } from \"./types.ts\";\n\n/**\n * HocuspocusProviderWebsocketComponent manages the WebSocket connection that is shared across all rooms.\n *\n * This component creates a single WebSocket connection that can be used by multiple\n * HocuspocusRoom components, preventing connection overhead when switching between documents.\n *\n * @example\n * ```tsx\n * <HocuspocusProviderWebsocketComponent url=\"ws://localhost:1234\">\n * <HocuspocusRoom name=\"document-1\">\n * <Editor />\n * </HocuspocusRoom>\n * </HocuspocusProviderWebsocketComponent>\n * ```\n */\nexport function HocuspocusProviderWebsocketComponent({\n\tchildren,\n\turl,\n\twebsocketProvider: externalWebsocketProvider,\n}: HocuspocusProviderWebsocketComponentProps) {\n\tconst websocketRef = useRef<HocuspocusProviderWebsocket | null>(null);\n\tconst destroyTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n\n\t// Create WebSocket provider once on mount.\n\t// Safe in StrictMode: useRef persists across double-renders, so the instance\n\t// is created only once. The deferred destruction in the effect below ensures\n\t// the second mount cancels the pending destroy before it fires.\n\tif (!websocketRef.current && !externalWebsocketProvider) {\n\t\twebsocketRef.current = new HocuspocusProviderWebsocket({\n\t\t\turl: url!,\n\t\t});\n\t}\n\n\tconst websocketProvider =\n\t\texternalWebsocketProvider ??\n\t\t(websocketRef.current as HocuspocusProviderWebsocket);\n\n\t// Cleanup on unmount with deferred destruction to handle StrictMode double-mount\n\tuseEffect(() => {\n\t\tif (destroyTimeoutRef.current) {\n\t\t\tclearTimeout(destroyTimeoutRef.current);\n\t\t\tdestroyTimeoutRef.current = null;\n\t\t}\n\n\t\treturn () => {\n\t\t\t// Only destroy if we created the websocket (not externally provided)\n\t\t\tif (!externalWebsocketProvider) {\n\t\t\t\tdestroyTimeoutRef.current = setTimeout(() => {\n\t\t\t\t\tif (websocketRef.current) {\n\t\t\t\t\t\twebsocketRef.current.destroy();\n\t\t\t\t\t\twebsocketRef.current = null;\n\t\t\t\t\t}\n\t\t\t\t}, 0);\n\t\t\t}\n\t\t};\n\t}, [externalWebsocketProvider]);\n\n\tconst contextValue = useMemo(\n\t\t() => ({\n\t\t\twebsocketProvider,\n\t\t}),\n\t\t[websocketProvider],\n\t);\n\n\treturn (\n\t\t<HocuspocusContext.Provider value={contextValue}>\n\t\t\t{children}\n\t\t</HocuspocusContext.Provider>\n\t);\n}\n","\"use client\";\n\nimport { HocuspocusProvider } from \"@hocuspocus/provider\";\nimport { useContext, useEffect, useMemo, useRef, useState } from \"react\";\n\nimport { HocuspocusContext, HocuspocusRoomContext } from \"./context.ts\";\nimport type { HocuspocusProviderEvents, HocuspocusRoomProps } from \"./types.ts\";\n\n/**\n * Mapping from HocuspocusRoom `on*` prop names to provider event names.\n */\nconst EVENT_PROP_MAP: Record<string, keyof HocuspocusProviderEvents> = {\n\tonOpen: \"open\",\n\tonConnect: \"connect\",\n\tonClose: \"close\",\n\tonDisconnect: \"disconnect\",\n\tonStatus: \"status\",\n\tonSynced: \"synced\",\n\tonUnsyncedChanges: \"unsyncedChanges\",\n\tonMessage: \"message\",\n\tonOutgoingMessage: \"outgoingMessage\",\n\tonStateless: \"stateless\",\n\tonAuthenticated: \"authenticated\",\n\tonAuthenticationFailed: \"authenticationFailed\",\n\tonAwarenessUpdate: \"awarenessUpdate\",\n\tonAwarenessChange: \"awarenessChange\",\n\tonDestroy: \"destroy\",\n};\n\n/**\n * HocuspocusRoom manages the connection to a specific document.\n *\n * It uses the shared WebSocket from HocuspocusProviderWebsocketComponent and creates a document-specific\n * provider that connects on mount and disconnects on unmount.\n *\n * This component handles React's StrictMode gracefully by using deferred destruction,\n * preventing unnecessary reconnections during development double-mounts.\n *\n * @example\n * ```tsx\n * <HocuspocusProviderWebsocketComponent url=\"ws://localhost:1234\">\n * <HocuspocusRoom\n * name=\"document-1\"\n * onAuthenticationFailed={(data) => console.error(data.reason)}\n * >\n * <Editor />\n * </HocuspocusRoom>\n * </HocuspocusProviderWebsocketComponent>\n * ```\n */\nexport function HocuspocusRoom({\n\tchildren,\n\tname,\n\tdocument,\n\ttoken,\n\tsessionAwareness,\n\t...eventHandlers\n}: HocuspocusRoomProps) {\n\tconst hocuspocusContext = useContext(HocuspocusContext);\n\n\tif (!hocuspocusContext) {\n\t\tthrow new Error(\n\t\t\t\"HocuspocusRoom must be used within a HocuspocusProviderWebsocketComponent\",\n\t\t);\n\t}\n\n\tconst { websocketProvider } = hocuspocusContext;\n\n\tconst [provider, setProvider] = useState(\n\t\t() =>\n\t\t\tnew HocuspocusProvider({\n\t\t\t\tname,\n\t\t\t\twebsocketProvider,\n\t\t\t\tdocument,\n\t\t\t\ttoken,\n\t\t\t\tsessionAwareness,\n\t\t\t}),\n\t);\n\n\tconst destroyTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n\n\t// Recreate provider when name, document, or token changes.\n\t// Only compare `document`/`token` when the caller actually provided them —\n\t// otherwise the provider's constructor-initialized defaults (auto-created\n\t// Y.Doc, null token) will never match the undefined prop, causing a destroy\n\t// on every render (and in StrictMode, a stray CloseMessage for the current\n\t// doc once the provider is already attached).\n\t// biome-ignore lint/correctness/useExhaustiveDependencies: provider.configuration holds the previous values we compare against — not a reactive dependency\n\tuseEffect(() => {\n\t\tconst shouldRecreate =\n\t\t\tprovider.configuration.name !== name ||\n\t\t\t(document !== undefined &&\n\t\t\t\tprovider.configuration.document !== document) ||\n\t\t\t(token !== undefined && provider.configuration.token !== token) ||\n\t\t\tprovider.configuration.websocketProvider !== websocketProvider;\n\n\t\tif (shouldRecreate) {\n\t\t\tprovider.destroy();\n\t\t\tsetProvider(\n\t\t\t\tnew HocuspocusProvider({\n\t\t\t\t\tname,\n\t\t\t\t\twebsocketProvider,\n\t\t\t\t\tdocument,\n\t\t\t\t\ttoken,\n\t\t\t\t\tsessionAwareness,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\t// eslint-disable-next-line react-hooks/exhaustive-deps\n\t}, [name, document, token, websocketProvider]);\n\n\t// Attach/detach lifecycle with deferred destruction for StrictMode\n\tuseEffect(() => {\n\t\tif (destroyTimeoutRef.current) {\n\t\t\tclearTimeout(destroyTimeoutRef.current);\n\t\t\tdestroyTimeoutRef.current = null;\n\t\t}\n\n\t\tprovider.attach();\n\n\t\treturn () => {\n\t\t\tdestroyTimeoutRef.current = setTimeout(() => {\n\t\t\t\tprovider.destroy();\n\t\t\t}, 0);\n\t\t};\n\t}, [provider]);\n\n\t// Wire up on* event handler props with stable refs\n\tconst handlersRef = useRef(eventHandlers);\n\thandlersRef.current = eventHandlers;\n\n\tuseEffect(() => {\n\t\tconst cleanups: (() => void)[] = [];\n\n\t\tfor (const [propName, eventName] of Object.entries(EVENT_PROP_MAP)) {\n\t\t\tconst listener = (...args: unknown[]) => {\n\t\t\t\tconst handler = handlersRef.current[\n\t\t\t\t\tpropName as keyof typeof handlersRef.current\n\t\t\t\t] as ((...a: unknown[]) => void) | undefined;\n\t\t\t\thandler?.(...args);\n\t\t\t};\n\t\t\tprovider.on(eventName, listener);\n\t\t\tcleanups.push(() => provider.off(eventName, listener));\n\t\t}\n\n\t\treturn () => {\n\t\t\tfor (const cleanup of cleanups) {\n\t\t\t\tcleanup();\n\t\t\t}\n\t\t};\n\t}, [provider]);\n\n\tconst contextValue = useMemo(\n\t\t() => ({\n\t\t\tprovider,\n\t\t}),\n\t\t[provider],\n\t);\n\n\treturn (\n\t\t<HocuspocusRoomContext.Provider value={contextValue}>\n\t\t\t{children}\n\t\t</HocuspocusRoomContext.Provider>\n\t);\n}\n","import { useContext } from \"react\";\n\nimport { HocuspocusRoomContext } from \"../context.ts\";\n\n/**\n * Access the HocuspocusProvider instance for the current room.\n *\n * Must be used within a HocuspocusRoom component.\n *\n * @returns The HocuspocusProvider instance\n * @throws Error if used outside of HocuspocusRoom\n *\n * @example\n * ```tsx\n * function Editor() {\n * const provider = useHocuspocusProvider()\n *\n * const editor = useEditor({\n * extensions: [\n * Collaboration.configure({ document: provider.document }),\n * CollaborationCursor.configure({ provider }),\n * ],\n * })\n *\n * return <EditorContent editor={editor} />\n * }\n * ```\n */\nexport function useHocuspocusProvider() {\n\tconst context = useContext(HocuspocusRoomContext);\n\n\tif (!context) {\n\t\tthrow new Error(\"useHocuspocusProvider must be used within a HocuspocusRoom\");\n\t}\n\n\treturn context.provider;\n}\n","import { useCallback, useEffect, useRef, useSyncExternalStore } from \"react\";\n\nimport type { CollabUser } from \"../types.ts\";\nimport { useHocuspocusProvider } from \"./useHocuspocusProvider.ts\";\n\n/**\n * Subscribe to the list of connected users in the document.\n *\n * This hook uses the Yjs awareness protocol to track users currently\n * connected to the document.\n *\n * @returns Array of user objects with their awareness state\n *\n * @example\n * ```tsx\n * function UserList() {\n * const users = useHocuspocusAwareness()\n *\n * return (\n * <div className=\"avatars\">\n * {users.map(user => (\n * <div\n * key={user.clientId}\n * style={{ backgroundColor: user.color }}\n * title={user.name}\n * >\n * {user.name?.[0]}\n * </div>\n * ))}\n * </div>\n * )\n * }\n * ```\n */\nexport function useHocuspocusAwareness(): CollabUser[] {\n\tconst provider = useHocuspocusProvider();\n\n\tconst versionRef = useRef(0);\n\tconst cacheRef = useRef<{ users: CollabUser[]; version: number }>({\n\t\tusers: [],\n\t\tversion: -1,\n\t});\n\n\t// Reset cache when provider changes so we don't serve stale users\n\t// from a previous provider instance.\n\tuseEffect(() => {\n\t\tversionRef.current++;\n\t\tcacheRef.current = { users: [], version: -1 };\n\t}, [provider]);\n\n\tconst subscribe = useCallback(\n\t\t(onStoreChange: () => void) => {\n\t\t\tconst onChange = () => {\n\t\t\t\tversionRef.current++;\n\t\t\t\tonStoreChange();\n\t\t\t};\n\t\t\tprovider.awareness?.on(\"change\", onChange);\n\t\t\treturn () => {\n\t\t\t\tprovider.awareness?.off(\"change\", onChange);\n\t\t\t};\n\t\t},\n\t\t[provider],\n\t);\n\n\tconst getSnapshot = useCallback(() => {\n\t\tconst awareness = provider.awareness;\n\t\tif (!awareness) {\n\t\t\treturn [];\n\t\t}\n\n\t\t// Return cached value if awareness hasn't changed since last snapshot\n\t\tif (cacheRef.current.version === versionRef.current) {\n\t\t\treturn cacheRef.current.users;\n\t\t}\n\n\t\tconst users: CollabUser[] = [];\n\t\tawareness.getStates().forEach((state, clientId) => {\n\t\t\tusers.push({\n\t\t\t\tclientId,\n\t\t\t\t...state,\n\t\t\t});\n\t\t});\n\n\t\tcacheRef.current = { users, version: versionRef.current };\n\t\treturn users;\n\t}, [provider]);\n\n\treturn useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n","import { useCallback, useSyncExternalStore } from \"react\";\n\nimport type { ConnectionStatus } from \"../types.ts\";\nimport { useHocuspocusProvider } from \"./useHocuspocusProvider.ts\";\n\n/**\n * Subscribe to the connection status of the collaboration provider.\n *\n * This hook uses React's useSyncExternalStore for optimal integration with\n * concurrent rendering features.\n *\n * @returns The current connection status: 'connecting', 'connected', or 'disconnected'\n *\n * @example\n * ```tsx\n * function ConnectionIndicator() {\n * const status = useHocuspocusConnectionStatus()\n *\n * return (\n * <div className={`status-${status}`}>\n * {status === 'connected' ? 'Online' : status === 'connecting' ? 'Connecting...' : 'Offline'}\n * </div>\n * )\n * }\n * ```\n */\nexport function useHocuspocusConnectionStatus(): ConnectionStatus {\n\tconst provider = useHocuspocusProvider();\n\n\tconst subscribe = useCallback(\n\t\t(onStoreChange: () => void) => {\n\t\t\tprovider.on(\"status\", onStoreChange);\n\t\t\treturn () => {\n\t\t\t\tprovider.off(\"status\", onStoreChange);\n\t\t\t};\n\t\t},\n\t\t[provider],\n\t);\n\n\tconst getSnapshot = useCallback(\n\t\t(): ConnectionStatus =>\n\t\t\tprovider.configuration.websocketProvider.status as ConnectionStatus,\n\t\t[provider],\n\t);\n\n\treturn useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n","import { useEffect, useRef } from \"react\";\n\nimport type { HocuspocusProviderEvents } from \"../types.ts\";\nimport { useHocuspocusProvider } from \"./useHocuspocusProvider.ts\";\n\n/**\n * Subscribe to events from the HocuspocusProvider for the current room.\n *\n * The handler is stored in a ref so the subscription stays stable even if\n * the handler identity changes between renders.\n *\n * Must be used within a HocuspocusRoom component.\n *\n * @param event - The event name to subscribe to\n * @param handler - Callback invoked when the event fires\n *\n * @example\n * ```tsx\n * function AuthGuard() {\n * useHocuspocusEvent('authenticationFailed', (data) => {\n * console.error('Auth failed:', data.reason)\n * redirectToLogin()\n * })\n *\n * useHocuspocusEvent('close', (data) => {\n * console.log('Connection closed', data.event)\n * })\n *\n * return null\n * }\n * ```\n */\nexport function useHocuspocusEvent<E extends keyof HocuspocusProviderEvents>(\n\tevent: E,\n\thandler: HocuspocusProviderEvents[E] extends undefined\n\t\t? () => void\n\t\t: (data: HocuspocusProviderEvents[E]) => void,\n): void {\n\tconst provider = useHocuspocusProvider();\n\tconst handlerRef = useRef(handler);\n\thandlerRef.current = handler;\n\n\tuseEffect(() => {\n\t\tconst listener = (...args: unknown[]) => {\n\t\t\t(handlerRef.current as (...a: unknown[]) => void)(...args);\n\t\t};\n\t\tprovider.on(event, listener);\n\t\treturn () => {\n\t\t\tprovider.off(event, listener);\n\t\t};\n\t}, [provider, event]);\n}\n","import { useCallback, useSyncExternalStore } from \"react\";\n\nimport type { SyncStatus } from \"../types.ts\";\nimport { useHocuspocusProvider } from \"./useHocuspocusProvider.ts\";\n\n/**\n * Subscribe to the sync status of local changes.\n *\n * This hook indicates whether local changes have been synced with the server.\n *\n * @returns The current sync status: 'synced' or 'syncing'\n *\n * @example\n * ```tsx\n * function SaveIndicator() {\n * const syncStatus = useHocuspocusSyncStatus()\n *\n * return (\n * <div>\n * {syncStatus === 'syncing' ? 'Saving...' : 'All changes saved'}\n * </div>\n * )\n * }\n * ```\n */\nexport function useHocuspocusSyncStatus(): SyncStatus {\n\tconst provider = useHocuspocusProvider();\n\n\tconst subscribe = useCallback(\n\t\t(onStoreChange: () => void) => {\n\t\t\tprovider.on(\"synced\", onStoreChange);\n\t\t\tprovider.on(\"unsyncedChanges\", onStoreChange);\n\n\t\t\treturn () => {\n\t\t\t\tprovider.off(\"synced\", onStoreChange);\n\t\t\t\tprovider.off(\"unsyncedChanges\", onStoreChange);\n\t\t\t};\n\t\t},\n\t\t[provider],\n\t);\n\n\tconst getSnapshot = useCallback((): SyncStatus => {\n\t\t// Check if there are unsynced changes\n\t\tif (provider.unsyncedChanges > 0) {\n\t\t\treturn \"syncing\";\n\t\t}\n\t\treturn \"synced\";\n\t}, [provider]);\n\n\treturn useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n"],"mappings":";;;;;;;;;;;AAUA,MAAa,6CACiC,KAAK;;;;AAKnD,MAAa,iDACqC,KAAK;;;;;;;;;;;;;;;;;;;ACMvD,SAAgB,qCAAqC,EACpD,UACA,KACA,mBAAmB,6BAC0B;CAC7C,MAAM,iCAA0D,KAAK;CACrE,MAAM,sCAAiE,KAAK;AAM5E,KAAI,CAAC,aAAa,WAAW,CAAC,0BAC7B,cAAa,UAAU,IAAIA,iDAA4B,EACjD,KACL,CAAC;CAGH,MAAM,oBACL,6BACC,aAAa;AAGf,4BAAgB;AACf,MAAI,kBAAkB,SAAS;AAC9B,gBAAa,kBAAkB,QAAQ;AACvC,qBAAkB,UAAU;;AAG7B,eAAa;AAEZ,OAAI,CAAC,0BACJ,mBAAkB,UAAU,iBAAiB;AAC5C,QAAI,aAAa,SAAS;AACzB,kBAAa,QAAQ,SAAS;AAC9B,kBAAa,UAAU;;MAEtB,EAAE;;IAGL,CAAC,0BAA0B,CAAC;CAE/B,MAAM,yCACE,EACN,mBACA,GACD,CAAC,kBAAkB,CACnB;AAED,QACC,2CAAC,kBAAkB,UAAnB;EAA4B,OAAO;EACjC;EAC2B;;;;;;;;AChE/B,MAAM,iBAAiE;CACtE,QAAQ;CACR,WAAW;CACX,SAAS;CACT,cAAc;CACd,UAAU;CACV,UAAU;CACV,mBAAmB;CACnB,WAAW;CACX,mBAAmB;CACnB,aAAa;CACb,iBAAiB;CACjB,wBAAwB;CACxB,mBAAmB;CACnB,mBAAmB;CACnB,WAAW;CACX;;;;;;;;;;;;;;;;;;;;;;AAuBD,SAAgB,eAAe,EAC9B,UACA,MACA,UACA,OACA,kBACA,GAAG,iBACoB;CACvB,MAAM,0CAA+B,kBAAkB;AAEvD,KAAI,CAAC,kBACJ,OAAM,IAAI,MACT,4EACA;CAGF,MAAM,EAAE,sBAAsB;CAE9B,MAAM,CAAC,UAAU,yCAEf,IAAIC,wCAAmB;EACtB;EACA;EACA;EACA;EACA;EACA,CAAC,CACH;CAED,MAAM,sCAAiE,KAAK;AAS5E,4BAAgB;AAQf,MANC,SAAS,cAAc,SAAS,QAC/B,aAAa,UACb,SAAS,cAAc,aAAa,YACpC,UAAU,UAAa,SAAS,cAAc,UAAU,SACzD,SAAS,cAAc,sBAAsB,mBAE1B;AACnB,YAAS,SAAS;AAClB,eACC,IAAIA,wCAAmB;IACtB;IACA;IACA;IACA;IACA;IACA,CAAC,CACF;;IAGA;EAAC;EAAM;EAAU;EAAO;EAAkB,CAAC;AAG9C,4BAAgB;AACf,MAAI,kBAAkB,SAAS;AAC9B,gBAAa,kBAAkB,QAAQ;AACvC,qBAAkB,UAAU;;AAG7B,WAAS,QAAQ;AAEjB,eAAa;AACZ,qBAAkB,UAAU,iBAAiB;AAC5C,aAAS,SAAS;MAChB,EAAE;;IAEJ,CAAC,SAAS,CAAC;CAGd,MAAM,gCAAqB,cAAc;AACzC,aAAY,UAAU;AAEtB,4BAAgB;EACf,MAAM,WAA2B,EAAE;AAEnC,OAAK,MAAM,CAAC,UAAU,cAAc,OAAO,QAAQ,eAAe,EAAE;GACnE,MAAM,YAAY,GAAG,SAAoB;IACxC,MAAM,UAAU,YAAY,QAC3B;AAED,cAAU,GAAG,KAAK;;AAEnB,YAAS,GAAG,WAAW,SAAS;AAChC,YAAS,WAAW,SAAS,IAAI,WAAW,SAAS,CAAC;;AAGvD,eAAa;AACZ,QAAK,MAAM,WAAW,SACrB,UAAS;;IAGT,CAAC,SAAS,CAAC;CAEd,MAAM,yCACE,EACN,UACA,GACD,CAAC,SAAS,CACV;AAED,QACC,2CAAC,sBAAsB,UAAvB;EAAgC,OAAO;EACrC;EAC+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACtInC,SAAgB,wBAAwB;CACvC,MAAM,gCAAqB,sBAAsB;AAEjD,KAAI,CAAC,QACJ,OAAM,IAAI,MAAM,6DAA6D;AAG9E,QAAO,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACDhB,SAAgB,yBAAuC;CACtD,MAAM,WAAW,uBAAuB;CAExC,MAAM,+BAAoB,EAAE;CAC5B,MAAM,6BAA4D;EACjE,OAAO,EAAE;EACT,SAAS;EACT,CAAC;AAIF,4BAAgB;AACf,aAAW;AACX,WAAS,UAAU;GAAE,OAAO,EAAE;GAAE,SAAS;GAAI;IAC3C,CAAC,SAAS,CAAC;CAEd,MAAM,oCACJ,kBAA8B;EAC9B,MAAM,iBAAiB;AACtB,cAAW;AACX,kBAAe;;AAEhB,WAAS,WAAW,GAAG,UAAU,SAAS;AAC1C,eAAa;AACZ,YAAS,WAAW,IAAI,UAAU,SAAS;;IAG7C,CAAC,SAAS,CACV;CAED,MAAM,2CAAgC;EACrC,MAAM,YAAY,SAAS;AAC3B,MAAI,CAAC,UACJ,QAAO,EAAE;AAIV,MAAI,SAAS,QAAQ,YAAY,WAAW,QAC3C,QAAO,SAAS,QAAQ;EAGzB,MAAM,QAAsB,EAAE;AAC9B,YAAU,WAAW,CAAC,SAAS,OAAO,aAAa;AAClD,SAAM,KAAK;IACV;IACA,GAAG;IACH,CAAC;IACD;AAEF,WAAS,UAAU;GAAE;GAAO,SAAS,WAAW;GAAS;AACzD,SAAO;IACL,CAAC,SAAS,CAAC;AAEd,wCAA4B,WAAW,aAAa,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;AC7DjE,SAAgB,gCAAkD;CACjE,MAAM,WAAW,uBAAuB;CAExC,MAAM,oCACJ,kBAA8B;AAC9B,WAAS,GAAG,UAAU,cAAc;AACpC,eAAa;AACZ,YAAS,IAAI,UAAU,cAAc;;IAGvC,CAAC,SAAS,CACV;CAED,MAAM,2CAEJ,SAAS,cAAc,kBAAkB,QAC1C,CAAC,SAAS,CACV;AAED,wCAA4B,WAAW,aAAa,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACbjE,SAAgB,mBACf,OACA,SAGO;CACP,MAAM,WAAW,uBAAuB;CACxC,MAAM,+BAAoB,QAAQ;AAClC,YAAW,UAAU;AAErB,4BAAgB;EACf,MAAM,YAAY,GAAG,SAAoB;AACxC,GAAC,WAAW,QAAsC,GAAG,KAAK;;AAE3D,WAAS,GAAG,OAAO,SAAS;AAC5B,eAAa;AACZ,YAAS,IAAI,OAAO,SAAS;;IAE5B,CAAC,UAAU,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;ACzBtB,SAAgB,0BAAsC;CACrD,MAAM,WAAW,uBAAuB;CAExC,MAAM,oCACJ,kBAA8B;AAC9B,WAAS,GAAG,UAAU,cAAc;AACpC,WAAS,GAAG,mBAAmB,cAAc;AAE7C,eAAa;AACZ,YAAS,IAAI,UAAU,cAAc;AACrC,YAAS,IAAI,mBAAmB,cAAc;;IAGhD,CAAC,SAAS,CACV;CAED,MAAM,2CAA4C;AAEjD,MAAI,SAAS,kBAAkB,EAC9B,QAAO;AAER,SAAO;IACL,CAAC,SAAS,CAAC;AAEd,wCAA4B,WAAW,aAAa,YAAY"}
1
+ {"version":3,"file":"hocuspocus-provider-react.cjs","names":["HocuspocusProviderWebsocket","HocuspocusProvider"],"sources":["../src/context.ts","../src/HocuspocusProviderWebsocketComponent.tsx","../src/HocuspocusRoom.tsx","../src/hooks/useHocuspocusProvider.ts","../src/hooks/useHocuspocusAwareness.ts","../src/hooks/useHocuspocusConnectionStatus.ts","../src/hooks/useHocuspocusEvent.ts","../src/hooks/useHocuspocusSyncStatus.ts"],"sourcesContent":["import { createContext } from \"react\";\n\nimport type {\n\tHocuspocusContextValue,\n\tHocuspocusRoomContextValue,\n} from \"./types.ts\";\n\n/**\n * Context for the WebSocket connection shared across rooms\n */\nexport const HocuspocusContext =\n\tcreateContext<HocuspocusContextValue | null>(null);\n\n/**\n * Context for the room/document provider\n */\nexport const HocuspocusRoomContext =\n\tcreateContext<HocuspocusRoomContextValue | null>(null);\n","\"use client\";\n\nimport { HocuspocusProviderWebsocket } from \"@hocuspocus/provider\";\nimport { useEffect, useMemo, useRef } from \"react\";\n\nimport { HocuspocusContext } from \"./context.ts\";\nimport type { HocuspocusProviderWebsocketComponentProps } from \"./types.ts\";\n\n/**\n * HocuspocusProviderWebsocketComponent manages the WebSocket connection that is shared across all rooms.\n *\n * This component creates a single WebSocket connection that can be used by multiple\n * HocuspocusRoom components, preventing connection overhead when switching between documents.\n *\n * @example\n * ```tsx\n * <HocuspocusProviderWebsocketComponent url=\"ws://localhost:1234\">\n * <HocuspocusRoom name=\"document-1\">\n * <Editor />\n * </HocuspocusRoom>\n * </HocuspocusProviderWebsocketComponent>\n * ```\n */\nexport function HocuspocusProviderWebsocketComponent({\n\tchildren,\n\turl,\n\twebsocketProvider: externalWebsocketProvider,\n}: HocuspocusProviderWebsocketComponentProps) {\n\tconst websocketRef = useRef<HocuspocusProviderWebsocket | null>(null);\n\tconst destroyTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n\n\t// Create WebSocket provider once on mount.\n\t// Safe in StrictMode: useRef persists across double-renders, so the instance\n\t// is created only once. The deferred destruction in the effect below ensures\n\t// the second mount cancels the pending destroy before it fires.\n\tif (!websocketRef.current && !externalWebsocketProvider) {\n\t\twebsocketRef.current = new HocuspocusProviderWebsocket({\n\t\t\turl: url!,\n\t\t});\n\t}\n\n\tconst websocketProvider =\n\t\texternalWebsocketProvider ??\n\t\t(websocketRef.current as HocuspocusProviderWebsocket);\n\n\t// Cleanup on unmount with deferred destruction to handle StrictMode double-mount\n\tuseEffect(() => {\n\t\tif (destroyTimeoutRef.current) {\n\t\t\tclearTimeout(destroyTimeoutRef.current);\n\t\t\tdestroyTimeoutRef.current = null;\n\t\t}\n\n\t\treturn () => {\n\t\t\t// Only destroy if we created the websocket (not externally provided)\n\t\t\tif (!externalWebsocketProvider) {\n\t\t\t\tdestroyTimeoutRef.current = setTimeout(() => {\n\t\t\t\t\tif (websocketRef.current) {\n\t\t\t\t\t\twebsocketRef.current.destroy();\n\t\t\t\t\t\twebsocketRef.current = null;\n\t\t\t\t\t}\n\t\t\t\t}, 0);\n\t\t\t}\n\t\t};\n\t}, [externalWebsocketProvider]);\n\n\tconst contextValue = useMemo(\n\t\t() => ({\n\t\t\twebsocketProvider,\n\t\t}),\n\t\t[websocketProvider],\n\t);\n\n\treturn (\n\t\t<HocuspocusContext.Provider value={contextValue}>\n\t\t\t{children}\n\t\t</HocuspocusContext.Provider>\n\t);\n}\n","\"use client\";\n\nimport { HocuspocusProvider } from \"@hocuspocus/provider\";\nimport { useContext, useEffect, useMemo, useRef, useState } from \"react\";\n\nimport { HocuspocusContext, HocuspocusRoomContext } from \"./context.ts\";\nimport type { HocuspocusProviderEvents, HocuspocusRoomProps } from \"./types.ts\";\n\n/**\n * Mapping from HocuspocusRoom `on*` prop names to provider event names.\n */\nconst EVENT_PROP_MAP: Record<string, keyof HocuspocusProviderEvents> = {\n\tonOpen: \"open\",\n\tonConnect: \"connect\",\n\tonClose: \"close\",\n\tonDisconnect: \"disconnect\",\n\tonStatus: \"status\",\n\tonSynced: \"synced\",\n\tonUnsyncedChanges: \"unsyncedChanges\",\n\tonMessage: \"message\",\n\tonOutgoingMessage: \"outgoingMessage\",\n\tonStateless: \"stateless\",\n\tonAuthenticated: \"authenticated\",\n\tonAuthenticationFailed: \"authenticationFailed\",\n\tonAwarenessUpdate: \"awarenessUpdate\",\n\tonAwarenessChange: \"awarenessChange\",\n\tonDestroy: \"destroy\",\n};\n\n/**\n * HocuspocusRoom manages the connection to a specific document.\n *\n * It uses the shared WebSocket from HocuspocusProviderWebsocketComponent and creates a document-specific\n * provider that connects on mount and disconnects on unmount.\n *\n * This component handles React's StrictMode gracefully by using deferred destruction,\n * preventing unnecessary reconnections during development double-mounts.\n *\n * @example\n * ```tsx\n * <HocuspocusProviderWebsocketComponent url=\"ws://localhost:1234\">\n * <HocuspocusRoom\n * name=\"document-1\"\n * onAuthenticationFailed={(data) => console.error(data.reason)}\n * >\n * <Editor />\n * </HocuspocusRoom>\n * </HocuspocusProviderWebsocketComponent>\n * ```\n */\nexport function HocuspocusRoom({\n\tchildren,\n\tname,\n\tdocument,\n\ttoken,\n\tsessionAwareness,\n\tflushDelay,\n\t...eventHandlers\n}: HocuspocusRoomProps) {\n\tconst hocuspocusContext = useContext(HocuspocusContext);\n\n\tif (!hocuspocusContext) {\n\t\tthrow new Error(\n\t\t\t\"HocuspocusRoom must be used within a HocuspocusProviderWebsocketComponent\",\n\t\t);\n\t}\n\n\tconst { websocketProvider } = hocuspocusContext;\n\n\tconst [provider, setProvider] = useState(\n\t\t() =>\n\t\t\tnew HocuspocusProvider({\n\t\t\t\tname,\n\t\t\t\twebsocketProvider,\n\t\t\t\tdocument,\n\t\t\t\ttoken,\n\t\t\t\tsessionAwareness,\n\t\t\t\tflushDelay,\n\t\t\t}),\n\t);\n\n\tconst destroyTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n\n\t// Recreate provider when name, document, or token changes.\n\t// Only compare `document`/`token` when the caller actually provided them —\n\t// otherwise the provider's constructor-initialized defaults (auto-created\n\t// Y.Doc, null token) will never match the undefined prop, causing a destroy\n\t// on every render (and in StrictMode, a stray CloseMessage for the current\n\t// doc once the provider is already attached).\n\t// biome-ignore lint/correctness/useExhaustiveDependencies: provider.configuration holds the previous values we compare against — not a reactive dependency\n\tuseEffect(() => {\n\t\tconst shouldRecreate =\n\t\t\tprovider.configuration.name !== name ||\n\t\t\t(document !== undefined &&\n\t\t\t\tprovider.configuration.document !== document) ||\n\t\t\t(token !== undefined && provider.configuration.token !== token) ||\n\t\t\tprovider.configuration.websocketProvider !== websocketProvider;\n\n\t\tif (shouldRecreate) {\n\t\t\tprovider.destroy();\n\t\t\tsetProvider(\n\t\t\t\tnew HocuspocusProvider({\n\t\t\t\t\tname,\n\t\t\t\t\twebsocketProvider,\n\t\t\t\t\tdocument,\n\t\t\t\t\ttoken,\n\t\t\t\t\tsessionAwareness,\n\t\t\t\t\tflushDelay,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\t// eslint-disable-next-line react-hooks/exhaustive-deps\n\t}, [name, document, token, websocketProvider]);\n\n\t// Attach/detach lifecycle with deferred destruction for StrictMode\n\tuseEffect(() => {\n\t\tif (destroyTimeoutRef.current) {\n\t\t\tclearTimeout(destroyTimeoutRef.current);\n\t\t\tdestroyTimeoutRef.current = null;\n\t\t}\n\n\t\tprovider.attach();\n\n\t\treturn () => {\n\t\t\tdestroyTimeoutRef.current = setTimeout(() => {\n\t\t\t\tprovider.destroy();\n\t\t\t}, 0);\n\t\t};\n\t}, [provider]);\n\n\t// Wire up on* event handler props with stable refs\n\tconst handlersRef = useRef(eventHandlers);\n\thandlersRef.current = eventHandlers;\n\n\tuseEffect(() => {\n\t\tconst cleanups: (() => void)[] = [];\n\n\t\tfor (const [propName, eventName] of Object.entries(EVENT_PROP_MAP)) {\n\t\t\tconst listener = (...args: unknown[]) => {\n\t\t\t\tconst handler = handlersRef.current[\n\t\t\t\t\tpropName as keyof typeof handlersRef.current\n\t\t\t\t] as ((...a: unknown[]) => void) | undefined;\n\t\t\t\thandler?.(...args);\n\t\t\t};\n\t\t\tprovider.on(eventName, listener);\n\t\t\tcleanups.push(() => provider.off(eventName, listener));\n\t\t}\n\n\t\treturn () => {\n\t\t\tfor (const cleanup of cleanups) {\n\t\t\t\tcleanup();\n\t\t\t}\n\t\t};\n\t}, [provider]);\n\n\tconst contextValue = useMemo(\n\t\t() => ({\n\t\t\tprovider,\n\t\t}),\n\t\t[provider],\n\t);\n\n\treturn (\n\t\t<HocuspocusRoomContext.Provider value={contextValue}>\n\t\t\t{children}\n\t\t</HocuspocusRoomContext.Provider>\n\t);\n}\n","import { useContext } from \"react\";\n\nimport { HocuspocusRoomContext } from \"../context.ts\";\n\n/**\n * Access the HocuspocusProvider instance for the current room.\n *\n * Must be used within a HocuspocusRoom component.\n *\n * @returns The HocuspocusProvider instance\n * @throws Error if used outside of HocuspocusRoom\n *\n * @example\n * ```tsx\n * function Editor() {\n * const provider = useHocuspocusProvider()\n *\n * const editor = useEditor({\n * extensions: [\n * Collaboration.configure({ document: provider.document }),\n * CollaborationCursor.configure({ provider }),\n * ],\n * })\n *\n * return <EditorContent editor={editor} />\n * }\n * ```\n */\nexport function useHocuspocusProvider() {\n\tconst context = useContext(HocuspocusRoomContext);\n\n\tif (!context) {\n\t\tthrow new Error(\"useHocuspocusProvider must be used within a HocuspocusRoom\");\n\t}\n\n\treturn context.provider;\n}\n","import { useCallback, useEffect, useRef, useSyncExternalStore } from \"react\";\n\nimport type { CollabUser } from \"../types.ts\";\nimport { useHocuspocusProvider } from \"./useHocuspocusProvider.ts\";\n\n/**\n * Subscribe to the list of connected users in the document.\n *\n * This hook uses the Yjs awareness protocol to track users currently\n * connected to the document.\n *\n * @returns Array of user objects with their awareness state\n *\n * @example\n * ```tsx\n * function UserList() {\n * const users = useHocuspocusAwareness()\n *\n * return (\n * <div className=\"avatars\">\n * {users.map(user => (\n * <div\n * key={user.clientId}\n * style={{ backgroundColor: user.color }}\n * title={user.name}\n * >\n * {user.name?.[0]}\n * </div>\n * ))}\n * </div>\n * )\n * }\n * ```\n */\nexport function useHocuspocusAwareness(): CollabUser[] {\n\tconst provider = useHocuspocusProvider();\n\n\tconst versionRef = useRef(0);\n\tconst cacheRef = useRef<{ users: CollabUser[]; version: number }>({\n\t\tusers: [],\n\t\tversion: -1,\n\t});\n\n\t// Reset cache when provider changes so we don't serve stale users\n\t// from a previous provider instance.\n\tuseEffect(() => {\n\t\tversionRef.current++;\n\t\tcacheRef.current = { users: [], version: -1 };\n\t}, [provider]);\n\n\tconst subscribe = useCallback(\n\t\t(onStoreChange: () => void) => {\n\t\t\tconst onChange = () => {\n\t\t\t\tversionRef.current++;\n\t\t\t\tonStoreChange();\n\t\t\t};\n\t\t\tprovider.awareness?.on(\"change\", onChange);\n\t\t\treturn () => {\n\t\t\t\tprovider.awareness?.off(\"change\", onChange);\n\t\t\t};\n\t\t},\n\t\t[provider],\n\t);\n\n\tconst getSnapshot = useCallback(() => {\n\t\tconst awareness = provider.awareness;\n\t\tif (!awareness) {\n\t\t\treturn [];\n\t\t}\n\n\t\t// Return cached value if awareness hasn't changed since last snapshot\n\t\tif (cacheRef.current.version === versionRef.current) {\n\t\t\treturn cacheRef.current.users;\n\t\t}\n\n\t\tconst users: CollabUser[] = [];\n\t\tawareness.getStates().forEach((state, clientId) => {\n\t\t\tusers.push({\n\t\t\t\tclientId,\n\t\t\t\t...state,\n\t\t\t});\n\t\t});\n\n\t\tcacheRef.current = { users, version: versionRef.current };\n\t\treturn users;\n\t}, [provider]);\n\n\treturn useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n","import { useCallback, useSyncExternalStore } from \"react\";\n\nimport type { ConnectionStatus } from \"../types.ts\";\nimport { useHocuspocusProvider } from \"./useHocuspocusProvider.ts\";\n\n/**\n * Subscribe to the connection status of the collaboration provider.\n *\n * This hook uses React's useSyncExternalStore for optimal integration with\n * concurrent rendering features.\n *\n * @returns The current connection status: 'connecting', 'connected', or 'disconnected'\n *\n * @example\n * ```tsx\n * function ConnectionIndicator() {\n * const status = useHocuspocusConnectionStatus()\n *\n * return (\n * <div className={`status-${status}`}>\n * {status === 'connected' ? 'Online' : status === 'connecting' ? 'Connecting...' : 'Offline'}\n * </div>\n * )\n * }\n * ```\n */\nexport function useHocuspocusConnectionStatus(): ConnectionStatus {\n\tconst provider = useHocuspocusProvider();\n\n\tconst subscribe = useCallback(\n\t\t(onStoreChange: () => void) => {\n\t\t\tprovider.on(\"status\", onStoreChange);\n\t\t\treturn () => {\n\t\t\t\tprovider.off(\"status\", onStoreChange);\n\t\t\t};\n\t\t},\n\t\t[provider],\n\t);\n\n\tconst getSnapshot = useCallback(\n\t\t(): ConnectionStatus =>\n\t\t\tprovider.configuration.websocketProvider.status as ConnectionStatus,\n\t\t[provider],\n\t);\n\n\treturn useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n","import { useEffect, useRef } from \"react\";\n\nimport type { HocuspocusProviderEvents } from \"../types.ts\";\nimport { useHocuspocusProvider } from \"./useHocuspocusProvider.ts\";\n\n/**\n * Subscribe to events from the HocuspocusProvider for the current room.\n *\n * The handler is stored in a ref so the subscription stays stable even if\n * the handler identity changes between renders.\n *\n * Must be used within a HocuspocusRoom component.\n *\n * @param event - The event name to subscribe to\n * @param handler - Callback invoked when the event fires\n *\n * @example\n * ```tsx\n * function AuthGuard() {\n * useHocuspocusEvent('authenticationFailed', (data) => {\n * console.error('Auth failed:', data.reason)\n * redirectToLogin()\n * })\n *\n * useHocuspocusEvent('close', (data) => {\n * console.log('Connection closed', data.event)\n * })\n *\n * return null\n * }\n * ```\n */\nexport function useHocuspocusEvent<E extends keyof HocuspocusProviderEvents>(\n\tevent: E,\n\thandler: HocuspocusProviderEvents[E] extends undefined\n\t\t? () => void\n\t\t: (data: HocuspocusProviderEvents[E]) => void,\n): void {\n\tconst provider = useHocuspocusProvider();\n\tconst handlerRef = useRef(handler);\n\thandlerRef.current = handler;\n\n\tuseEffect(() => {\n\t\tconst listener = (...args: unknown[]) => {\n\t\t\t(handlerRef.current as (...a: unknown[]) => void)(...args);\n\t\t};\n\t\tprovider.on(event, listener);\n\t\treturn () => {\n\t\t\tprovider.off(event, listener);\n\t\t};\n\t}, [provider, event]);\n}\n","import { useCallback, useSyncExternalStore } from \"react\";\n\nimport type { SyncStatus } from \"../types.ts\";\nimport { useHocuspocusProvider } from \"./useHocuspocusProvider.ts\";\n\n/**\n * Subscribe to the sync status of local changes.\n *\n * This hook indicates whether local changes have been synced with the server.\n *\n * @returns The current sync status: 'synced' or 'syncing'\n *\n * @example\n * ```tsx\n * function SaveIndicator() {\n * const syncStatus = useHocuspocusSyncStatus()\n *\n * return (\n * <div>\n * {syncStatus === 'syncing' ? 'Saving...' : 'All changes saved'}\n * </div>\n * )\n * }\n * ```\n */\nexport function useHocuspocusSyncStatus(): SyncStatus {\n\tconst provider = useHocuspocusProvider();\n\n\tconst subscribe = useCallback(\n\t\t(onStoreChange: () => void) => {\n\t\t\tprovider.on(\"synced\", onStoreChange);\n\t\t\tprovider.on(\"unsyncedChanges\", onStoreChange);\n\n\t\t\treturn () => {\n\t\t\t\tprovider.off(\"synced\", onStoreChange);\n\t\t\t\tprovider.off(\"unsyncedChanges\", onStoreChange);\n\t\t\t};\n\t\t},\n\t\t[provider],\n\t);\n\n\tconst getSnapshot = useCallback((): SyncStatus => {\n\t\t// Check if there are unsynced changes\n\t\tif (provider.unsyncedChanges > 0) {\n\t\t\treturn \"syncing\";\n\t\t}\n\t\treturn \"synced\";\n\t}, [provider]);\n\n\treturn useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n"],"mappings":";;;;;;;;;;;AAUA,MAAa,6CACiC,KAAK;;;;AAKnD,MAAa,iDACqC,KAAK;;;;;;;;;;;;;;;;;;;ACMvD,SAAgB,qCAAqC,EACpD,UACA,KACA,mBAAmB,6BAC0B;CAC7C,MAAM,iCAA0D,KAAK;CACrE,MAAM,sCAAiE,KAAK;AAM5E,KAAI,CAAC,aAAa,WAAW,CAAC,0BAC7B,cAAa,UAAU,IAAIA,iDAA4B,EACjD,KACL,CAAC;CAGH,MAAM,oBACL,6BACC,aAAa;AAGf,4BAAgB;AACf,MAAI,kBAAkB,SAAS;AAC9B,gBAAa,kBAAkB,QAAQ;AACvC,qBAAkB,UAAU;;AAG7B,eAAa;AAEZ,OAAI,CAAC,0BACJ,mBAAkB,UAAU,iBAAiB;AAC5C,QAAI,aAAa,SAAS;AACzB,kBAAa,QAAQ,SAAS;AAC9B,kBAAa,UAAU;;MAEtB,EAAE;;IAGL,CAAC,0BAA0B,CAAC;CAE/B,MAAM,yCACE,EACN,mBACA,GACD,CAAC,kBAAkB,CACnB;AAED,QACC,2CAAC,kBAAkB,UAAnB;EAA4B,OAAO;EACjC;EAC2B;;;;;;;;AChE/B,MAAM,iBAAiE;CACtE,QAAQ;CACR,WAAW;CACX,SAAS;CACT,cAAc;CACd,UAAU;CACV,UAAU;CACV,mBAAmB;CACnB,WAAW;CACX,mBAAmB;CACnB,aAAa;CACb,iBAAiB;CACjB,wBAAwB;CACxB,mBAAmB;CACnB,mBAAmB;CACnB,WAAW;CACX;;;;;;;;;;;;;;;;;;;;;;AAuBD,SAAgB,eAAe,EAC9B,UACA,MACA,UACA,OACA,kBACA,YACA,GAAG,iBACoB;CACvB,MAAM,0CAA+B,kBAAkB;AAEvD,KAAI,CAAC,kBACJ,OAAM,IAAI,MACT,4EACA;CAGF,MAAM,EAAE,sBAAsB;CAE9B,MAAM,CAAC,UAAU,yCAEf,IAAIC,wCAAmB;EACtB;EACA;EACA;EACA;EACA;EACA;EACA,CAAC,CACH;CAED,MAAM,sCAAiE,KAAK;AAS5E,4BAAgB;AAQf,MANC,SAAS,cAAc,SAAS,QAC/B,aAAa,UACb,SAAS,cAAc,aAAa,YACpC,UAAU,UAAa,SAAS,cAAc,UAAU,SACzD,SAAS,cAAc,sBAAsB,mBAE1B;AACnB,YAAS,SAAS;AAClB,eACC,IAAIA,wCAAmB;IACtB;IACA;IACA;IACA;IACA;IACA;IACA,CAAC,CACF;;IAGA;EAAC;EAAM;EAAU;EAAO;EAAkB,CAAC;AAG9C,4BAAgB;AACf,MAAI,kBAAkB,SAAS;AAC9B,gBAAa,kBAAkB,QAAQ;AACvC,qBAAkB,UAAU;;AAG7B,WAAS,QAAQ;AAEjB,eAAa;AACZ,qBAAkB,UAAU,iBAAiB;AAC5C,aAAS,SAAS;MAChB,EAAE;;IAEJ,CAAC,SAAS,CAAC;CAGd,MAAM,gCAAqB,cAAc;AACzC,aAAY,UAAU;AAEtB,4BAAgB;EACf,MAAM,WAA2B,EAAE;AAEnC,OAAK,MAAM,CAAC,UAAU,cAAc,OAAO,QAAQ,eAAe,EAAE;GACnE,MAAM,YAAY,GAAG,SAAoB;IACxC,MAAM,UAAU,YAAY,QAC3B;AAED,cAAU,GAAG,KAAK;;AAEnB,YAAS,GAAG,WAAW,SAAS;AAChC,YAAS,WAAW,SAAS,IAAI,WAAW,SAAS,CAAC;;AAGvD,eAAa;AACZ,QAAK,MAAM,WAAW,SACrB,UAAS;;IAGT,CAAC,SAAS,CAAC;CAEd,MAAM,yCACE,EACN,UACA,GACD,CAAC,SAAS,CACV;AAED,QACC,2CAAC,sBAAsB,UAAvB;EAAgC,OAAO;EACrC;EAC+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACzInC,SAAgB,wBAAwB;CACvC,MAAM,gCAAqB,sBAAsB;AAEjD,KAAI,CAAC,QACJ,OAAM,IAAI,MAAM,6DAA6D;AAG9E,QAAO,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACDhB,SAAgB,yBAAuC;CACtD,MAAM,WAAW,uBAAuB;CAExC,MAAM,+BAAoB,EAAE;CAC5B,MAAM,6BAA4D;EACjE,OAAO,EAAE;EACT,SAAS;EACT,CAAC;AAIF,4BAAgB;AACf,aAAW;AACX,WAAS,UAAU;GAAE,OAAO,EAAE;GAAE,SAAS;GAAI;IAC3C,CAAC,SAAS,CAAC;CAEd,MAAM,oCACJ,kBAA8B;EAC9B,MAAM,iBAAiB;AACtB,cAAW;AACX,kBAAe;;AAEhB,WAAS,WAAW,GAAG,UAAU,SAAS;AAC1C,eAAa;AACZ,YAAS,WAAW,IAAI,UAAU,SAAS;;IAG7C,CAAC,SAAS,CACV;CAED,MAAM,2CAAgC;EACrC,MAAM,YAAY,SAAS;AAC3B,MAAI,CAAC,UACJ,QAAO,EAAE;AAIV,MAAI,SAAS,QAAQ,YAAY,WAAW,QAC3C,QAAO,SAAS,QAAQ;EAGzB,MAAM,QAAsB,EAAE;AAC9B,YAAU,WAAW,CAAC,SAAS,OAAO,aAAa;AAClD,SAAM,KAAK;IACV;IACA,GAAG;IACH,CAAC;IACD;AAEF,WAAS,UAAU;GAAE;GAAO,SAAS,WAAW;GAAS;AACzD,SAAO;IACL,CAAC,SAAS,CAAC;AAEd,wCAA4B,WAAW,aAAa,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;AC7DjE,SAAgB,gCAAkD;CACjE,MAAM,WAAW,uBAAuB;CAExC,MAAM,oCACJ,kBAA8B;AAC9B,WAAS,GAAG,UAAU,cAAc;AACpC,eAAa;AACZ,YAAS,IAAI,UAAU,cAAc;;IAGvC,CAAC,SAAS,CACV;CAED,MAAM,2CAEJ,SAAS,cAAc,kBAAkB,QAC1C,CAAC,SAAS,CACV;AAED,wCAA4B,WAAW,aAAa,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACbjE,SAAgB,mBACf,OACA,SAGO;CACP,MAAM,WAAW,uBAAuB;CACxC,MAAM,+BAAoB,QAAQ;AAClC,YAAW,UAAU;AAErB,4BAAgB;EACf,MAAM,YAAY,GAAG,SAAoB;AACxC,GAAC,WAAW,QAAsC,GAAG,KAAK;;AAE3D,WAAS,GAAG,OAAO,SAAS;AAC5B,eAAa;AACZ,YAAS,IAAI,OAAO,SAAS;;IAE5B,CAAC,UAAU,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;ACzBtB,SAAgB,0BAAsC;CACrD,MAAM,WAAW,uBAAuB;CAExC,MAAM,oCACJ,kBAA8B;AAC9B,WAAS,GAAG,UAAU,cAAc;AACpC,WAAS,GAAG,mBAAmB,cAAc;AAE7C,eAAa;AACZ,YAAS,IAAI,UAAU,cAAc;AACrC,YAAS,IAAI,mBAAmB,cAAc;;IAGhD,CAAC,SAAS,CACV;CAED,MAAM,2CAA4C;AAEjD,MAAI,SAAS,kBAAkB,EAC9B,QAAO;AAER,SAAO;IACL,CAAC,SAAS,CAAC;AAEd,wCAA4B,WAAW,aAAa,YAAY"}
@@ -100,7 +100,7 @@ const EVENT_PROP_MAP = {
100
100
  * </HocuspocusProviderWebsocketComponent>
101
101
  * ```
102
102
  */
103
- function HocuspocusRoom({ children, name, document, token, sessionAwareness, ...eventHandlers }) {
103
+ function HocuspocusRoom({ children, name, document, token, sessionAwareness, flushDelay, ...eventHandlers }) {
104
104
  const hocuspocusContext = useContext(HocuspocusContext);
105
105
  if (!hocuspocusContext) throw new Error("HocuspocusRoom must be used within a HocuspocusProviderWebsocketComponent");
106
106
  const { websocketProvider } = hocuspocusContext;
@@ -109,7 +109,8 @@ function HocuspocusRoom({ children, name, document, token, sessionAwareness, ...
109
109
  websocketProvider,
110
110
  document,
111
111
  token,
112
- sessionAwareness
112
+ sessionAwareness,
113
+ flushDelay
113
114
  }));
114
115
  const destroyTimeoutRef = useRef(null);
115
116
  useEffect(() => {
@@ -120,7 +121,8 @@ function HocuspocusRoom({ children, name, document, token, sessionAwareness, ...
120
121
  websocketProvider,
121
122
  document,
122
123
  token,
123
- sessionAwareness
124
+ sessionAwareness,
125
+ flushDelay
124
126
  }));
125
127
  }
126
128
  }, [
@@ -1 +1 @@
1
- {"version":3,"file":"hocuspocus-provider-react.esm.js","names":[],"sources":["../src/context.ts","../src/HocuspocusProviderWebsocketComponent.tsx","../src/HocuspocusRoom.tsx","../src/hooks/useHocuspocusProvider.ts","../src/hooks/useHocuspocusAwareness.ts","../src/hooks/useHocuspocusConnectionStatus.ts","../src/hooks/useHocuspocusEvent.ts","../src/hooks/useHocuspocusSyncStatus.ts"],"sourcesContent":["import { createContext } from \"react\";\n\nimport type {\n\tHocuspocusContextValue,\n\tHocuspocusRoomContextValue,\n} from \"./types.ts\";\n\n/**\n * Context for the WebSocket connection shared across rooms\n */\nexport const HocuspocusContext =\n\tcreateContext<HocuspocusContextValue | null>(null);\n\n/**\n * Context for the room/document provider\n */\nexport const HocuspocusRoomContext =\n\tcreateContext<HocuspocusRoomContextValue | null>(null);\n","\"use client\";\n\nimport { HocuspocusProviderWebsocket } from \"@hocuspocus/provider\";\nimport { useEffect, useMemo, useRef } from \"react\";\n\nimport { HocuspocusContext } from \"./context.ts\";\nimport type { HocuspocusProviderWebsocketComponentProps } from \"./types.ts\";\n\n/**\n * HocuspocusProviderWebsocketComponent manages the WebSocket connection that is shared across all rooms.\n *\n * This component creates a single WebSocket connection that can be used by multiple\n * HocuspocusRoom components, preventing connection overhead when switching between documents.\n *\n * @example\n * ```tsx\n * <HocuspocusProviderWebsocketComponent url=\"ws://localhost:1234\">\n * <HocuspocusRoom name=\"document-1\">\n * <Editor />\n * </HocuspocusRoom>\n * </HocuspocusProviderWebsocketComponent>\n * ```\n */\nexport function HocuspocusProviderWebsocketComponent({\n\tchildren,\n\turl,\n\twebsocketProvider: externalWebsocketProvider,\n}: HocuspocusProviderWebsocketComponentProps) {\n\tconst websocketRef = useRef<HocuspocusProviderWebsocket | null>(null);\n\tconst destroyTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n\n\t// Create WebSocket provider once on mount.\n\t// Safe in StrictMode: useRef persists across double-renders, so the instance\n\t// is created only once. The deferred destruction in the effect below ensures\n\t// the second mount cancels the pending destroy before it fires.\n\tif (!websocketRef.current && !externalWebsocketProvider) {\n\t\twebsocketRef.current = new HocuspocusProviderWebsocket({\n\t\t\turl: url!,\n\t\t});\n\t}\n\n\tconst websocketProvider =\n\t\texternalWebsocketProvider ??\n\t\t(websocketRef.current as HocuspocusProviderWebsocket);\n\n\t// Cleanup on unmount with deferred destruction to handle StrictMode double-mount\n\tuseEffect(() => {\n\t\tif (destroyTimeoutRef.current) {\n\t\t\tclearTimeout(destroyTimeoutRef.current);\n\t\t\tdestroyTimeoutRef.current = null;\n\t\t}\n\n\t\treturn () => {\n\t\t\t// Only destroy if we created the websocket (not externally provided)\n\t\t\tif (!externalWebsocketProvider) {\n\t\t\t\tdestroyTimeoutRef.current = setTimeout(() => {\n\t\t\t\t\tif (websocketRef.current) {\n\t\t\t\t\t\twebsocketRef.current.destroy();\n\t\t\t\t\t\twebsocketRef.current = null;\n\t\t\t\t\t}\n\t\t\t\t}, 0);\n\t\t\t}\n\t\t};\n\t}, [externalWebsocketProvider]);\n\n\tconst contextValue = useMemo(\n\t\t() => ({\n\t\t\twebsocketProvider,\n\t\t}),\n\t\t[websocketProvider],\n\t);\n\n\treturn (\n\t\t<HocuspocusContext.Provider value={contextValue}>\n\t\t\t{children}\n\t\t</HocuspocusContext.Provider>\n\t);\n}\n","\"use client\";\n\nimport { HocuspocusProvider } from \"@hocuspocus/provider\";\nimport { useContext, useEffect, useMemo, useRef, useState } from \"react\";\n\nimport { HocuspocusContext, HocuspocusRoomContext } from \"./context.ts\";\nimport type { HocuspocusProviderEvents, HocuspocusRoomProps } from \"./types.ts\";\n\n/**\n * Mapping from HocuspocusRoom `on*` prop names to provider event names.\n */\nconst EVENT_PROP_MAP: Record<string, keyof HocuspocusProviderEvents> = {\n\tonOpen: \"open\",\n\tonConnect: \"connect\",\n\tonClose: \"close\",\n\tonDisconnect: \"disconnect\",\n\tonStatus: \"status\",\n\tonSynced: \"synced\",\n\tonUnsyncedChanges: \"unsyncedChanges\",\n\tonMessage: \"message\",\n\tonOutgoingMessage: \"outgoingMessage\",\n\tonStateless: \"stateless\",\n\tonAuthenticated: \"authenticated\",\n\tonAuthenticationFailed: \"authenticationFailed\",\n\tonAwarenessUpdate: \"awarenessUpdate\",\n\tonAwarenessChange: \"awarenessChange\",\n\tonDestroy: \"destroy\",\n};\n\n/**\n * HocuspocusRoom manages the connection to a specific document.\n *\n * It uses the shared WebSocket from HocuspocusProviderWebsocketComponent and creates a document-specific\n * provider that connects on mount and disconnects on unmount.\n *\n * This component handles React's StrictMode gracefully by using deferred destruction,\n * preventing unnecessary reconnections during development double-mounts.\n *\n * @example\n * ```tsx\n * <HocuspocusProviderWebsocketComponent url=\"ws://localhost:1234\">\n * <HocuspocusRoom\n * name=\"document-1\"\n * onAuthenticationFailed={(data) => console.error(data.reason)}\n * >\n * <Editor />\n * </HocuspocusRoom>\n * </HocuspocusProviderWebsocketComponent>\n * ```\n */\nexport function HocuspocusRoom({\n\tchildren,\n\tname,\n\tdocument,\n\ttoken,\n\tsessionAwareness,\n\t...eventHandlers\n}: HocuspocusRoomProps) {\n\tconst hocuspocusContext = useContext(HocuspocusContext);\n\n\tif (!hocuspocusContext) {\n\t\tthrow new Error(\n\t\t\t\"HocuspocusRoom must be used within a HocuspocusProviderWebsocketComponent\",\n\t\t);\n\t}\n\n\tconst { websocketProvider } = hocuspocusContext;\n\n\tconst [provider, setProvider] = useState(\n\t\t() =>\n\t\t\tnew HocuspocusProvider({\n\t\t\t\tname,\n\t\t\t\twebsocketProvider,\n\t\t\t\tdocument,\n\t\t\t\ttoken,\n\t\t\t\tsessionAwareness,\n\t\t\t}),\n\t);\n\n\tconst destroyTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n\n\t// Recreate provider when name, document, or token changes.\n\t// Only compare `document`/`token` when the caller actually provided them —\n\t// otherwise the provider's constructor-initialized defaults (auto-created\n\t// Y.Doc, null token) will never match the undefined prop, causing a destroy\n\t// on every render (and in StrictMode, a stray CloseMessage for the current\n\t// doc once the provider is already attached).\n\t// biome-ignore lint/correctness/useExhaustiveDependencies: provider.configuration holds the previous values we compare against — not a reactive dependency\n\tuseEffect(() => {\n\t\tconst shouldRecreate =\n\t\t\tprovider.configuration.name !== name ||\n\t\t\t(document !== undefined &&\n\t\t\t\tprovider.configuration.document !== document) ||\n\t\t\t(token !== undefined && provider.configuration.token !== token) ||\n\t\t\tprovider.configuration.websocketProvider !== websocketProvider;\n\n\t\tif (shouldRecreate) {\n\t\t\tprovider.destroy();\n\t\t\tsetProvider(\n\t\t\t\tnew HocuspocusProvider({\n\t\t\t\t\tname,\n\t\t\t\t\twebsocketProvider,\n\t\t\t\t\tdocument,\n\t\t\t\t\ttoken,\n\t\t\t\t\tsessionAwareness,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\t// eslint-disable-next-line react-hooks/exhaustive-deps\n\t}, [name, document, token, websocketProvider]);\n\n\t// Attach/detach lifecycle with deferred destruction for StrictMode\n\tuseEffect(() => {\n\t\tif (destroyTimeoutRef.current) {\n\t\t\tclearTimeout(destroyTimeoutRef.current);\n\t\t\tdestroyTimeoutRef.current = null;\n\t\t}\n\n\t\tprovider.attach();\n\n\t\treturn () => {\n\t\t\tdestroyTimeoutRef.current = setTimeout(() => {\n\t\t\t\tprovider.destroy();\n\t\t\t}, 0);\n\t\t};\n\t}, [provider]);\n\n\t// Wire up on* event handler props with stable refs\n\tconst handlersRef = useRef(eventHandlers);\n\thandlersRef.current = eventHandlers;\n\n\tuseEffect(() => {\n\t\tconst cleanups: (() => void)[] = [];\n\n\t\tfor (const [propName, eventName] of Object.entries(EVENT_PROP_MAP)) {\n\t\t\tconst listener = (...args: unknown[]) => {\n\t\t\t\tconst handler = handlersRef.current[\n\t\t\t\t\tpropName as keyof typeof handlersRef.current\n\t\t\t\t] as ((...a: unknown[]) => void) | undefined;\n\t\t\t\thandler?.(...args);\n\t\t\t};\n\t\t\tprovider.on(eventName, listener);\n\t\t\tcleanups.push(() => provider.off(eventName, listener));\n\t\t}\n\n\t\treturn () => {\n\t\t\tfor (const cleanup of cleanups) {\n\t\t\t\tcleanup();\n\t\t\t}\n\t\t};\n\t}, [provider]);\n\n\tconst contextValue = useMemo(\n\t\t() => ({\n\t\t\tprovider,\n\t\t}),\n\t\t[provider],\n\t);\n\n\treturn (\n\t\t<HocuspocusRoomContext.Provider value={contextValue}>\n\t\t\t{children}\n\t\t</HocuspocusRoomContext.Provider>\n\t);\n}\n","import { useContext } from \"react\";\n\nimport { HocuspocusRoomContext } from \"../context.ts\";\n\n/**\n * Access the HocuspocusProvider instance for the current room.\n *\n * Must be used within a HocuspocusRoom component.\n *\n * @returns The HocuspocusProvider instance\n * @throws Error if used outside of HocuspocusRoom\n *\n * @example\n * ```tsx\n * function Editor() {\n * const provider = useHocuspocusProvider()\n *\n * const editor = useEditor({\n * extensions: [\n * Collaboration.configure({ document: provider.document }),\n * CollaborationCursor.configure({ provider }),\n * ],\n * })\n *\n * return <EditorContent editor={editor} />\n * }\n * ```\n */\nexport function useHocuspocusProvider() {\n\tconst context = useContext(HocuspocusRoomContext);\n\n\tif (!context) {\n\t\tthrow new Error(\"useHocuspocusProvider must be used within a HocuspocusRoom\");\n\t}\n\n\treturn context.provider;\n}\n","import { useCallback, useEffect, useRef, useSyncExternalStore } from \"react\";\n\nimport type { CollabUser } from \"../types.ts\";\nimport { useHocuspocusProvider } from \"./useHocuspocusProvider.ts\";\n\n/**\n * Subscribe to the list of connected users in the document.\n *\n * This hook uses the Yjs awareness protocol to track users currently\n * connected to the document.\n *\n * @returns Array of user objects with their awareness state\n *\n * @example\n * ```tsx\n * function UserList() {\n * const users = useHocuspocusAwareness()\n *\n * return (\n * <div className=\"avatars\">\n * {users.map(user => (\n * <div\n * key={user.clientId}\n * style={{ backgroundColor: user.color }}\n * title={user.name}\n * >\n * {user.name?.[0]}\n * </div>\n * ))}\n * </div>\n * )\n * }\n * ```\n */\nexport function useHocuspocusAwareness(): CollabUser[] {\n\tconst provider = useHocuspocusProvider();\n\n\tconst versionRef = useRef(0);\n\tconst cacheRef = useRef<{ users: CollabUser[]; version: number }>({\n\t\tusers: [],\n\t\tversion: -1,\n\t});\n\n\t// Reset cache when provider changes so we don't serve stale users\n\t// from a previous provider instance.\n\tuseEffect(() => {\n\t\tversionRef.current++;\n\t\tcacheRef.current = { users: [], version: -1 };\n\t}, [provider]);\n\n\tconst subscribe = useCallback(\n\t\t(onStoreChange: () => void) => {\n\t\t\tconst onChange = () => {\n\t\t\t\tversionRef.current++;\n\t\t\t\tonStoreChange();\n\t\t\t};\n\t\t\tprovider.awareness?.on(\"change\", onChange);\n\t\t\treturn () => {\n\t\t\t\tprovider.awareness?.off(\"change\", onChange);\n\t\t\t};\n\t\t},\n\t\t[provider],\n\t);\n\n\tconst getSnapshot = useCallback(() => {\n\t\tconst awareness = provider.awareness;\n\t\tif (!awareness) {\n\t\t\treturn [];\n\t\t}\n\n\t\t// Return cached value if awareness hasn't changed since last snapshot\n\t\tif (cacheRef.current.version === versionRef.current) {\n\t\t\treturn cacheRef.current.users;\n\t\t}\n\n\t\tconst users: CollabUser[] = [];\n\t\tawareness.getStates().forEach((state, clientId) => {\n\t\t\tusers.push({\n\t\t\t\tclientId,\n\t\t\t\t...state,\n\t\t\t});\n\t\t});\n\n\t\tcacheRef.current = { users, version: versionRef.current };\n\t\treturn users;\n\t}, [provider]);\n\n\treturn useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n","import { useCallback, useSyncExternalStore } from \"react\";\n\nimport type { ConnectionStatus } from \"../types.ts\";\nimport { useHocuspocusProvider } from \"./useHocuspocusProvider.ts\";\n\n/**\n * Subscribe to the connection status of the collaboration provider.\n *\n * This hook uses React's useSyncExternalStore for optimal integration with\n * concurrent rendering features.\n *\n * @returns The current connection status: 'connecting', 'connected', or 'disconnected'\n *\n * @example\n * ```tsx\n * function ConnectionIndicator() {\n * const status = useHocuspocusConnectionStatus()\n *\n * return (\n * <div className={`status-${status}`}>\n * {status === 'connected' ? 'Online' : status === 'connecting' ? 'Connecting...' : 'Offline'}\n * </div>\n * )\n * }\n * ```\n */\nexport function useHocuspocusConnectionStatus(): ConnectionStatus {\n\tconst provider = useHocuspocusProvider();\n\n\tconst subscribe = useCallback(\n\t\t(onStoreChange: () => void) => {\n\t\t\tprovider.on(\"status\", onStoreChange);\n\t\t\treturn () => {\n\t\t\t\tprovider.off(\"status\", onStoreChange);\n\t\t\t};\n\t\t},\n\t\t[provider],\n\t);\n\n\tconst getSnapshot = useCallback(\n\t\t(): ConnectionStatus =>\n\t\t\tprovider.configuration.websocketProvider.status as ConnectionStatus,\n\t\t[provider],\n\t);\n\n\treturn useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n","import { useEffect, useRef } from \"react\";\n\nimport type { HocuspocusProviderEvents } from \"../types.ts\";\nimport { useHocuspocusProvider } from \"./useHocuspocusProvider.ts\";\n\n/**\n * Subscribe to events from the HocuspocusProvider for the current room.\n *\n * The handler is stored in a ref so the subscription stays stable even if\n * the handler identity changes between renders.\n *\n * Must be used within a HocuspocusRoom component.\n *\n * @param event - The event name to subscribe to\n * @param handler - Callback invoked when the event fires\n *\n * @example\n * ```tsx\n * function AuthGuard() {\n * useHocuspocusEvent('authenticationFailed', (data) => {\n * console.error('Auth failed:', data.reason)\n * redirectToLogin()\n * })\n *\n * useHocuspocusEvent('close', (data) => {\n * console.log('Connection closed', data.event)\n * })\n *\n * return null\n * }\n * ```\n */\nexport function useHocuspocusEvent<E extends keyof HocuspocusProviderEvents>(\n\tevent: E,\n\thandler: HocuspocusProviderEvents[E] extends undefined\n\t\t? () => void\n\t\t: (data: HocuspocusProviderEvents[E]) => void,\n): void {\n\tconst provider = useHocuspocusProvider();\n\tconst handlerRef = useRef(handler);\n\thandlerRef.current = handler;\n\n\tuseEffect(() => {\n\t\tconst listener = (...args: unknown[]) => {\n\t\t\t(handlerRef.current as (...a: unknown[]) => void)(...args);\n\t\t};\n\t\tprovider.on(event, listener);\n\t\treturn () => {\n\t\t\tprovider.off(event, listener);\n\t\t};\n\t}, [provider, event]);\n}\n","import { useCallback, useSyncExternalStore } from \"react\";\n\nimport type { SyncStatus } from \"../types.ts\";\nimport { useHocuspocusProvider } from \"./useHocuspocusProvider.ts\";\n\n/**\n * Subscribe to the sync status of local changes.\n *\n * This hook indicates whether local changes have been synced with the server.\n *\n * @returns The current sync status: 'synced' or 'syncing'\n *\n * @example\n * ```tsx\n * function SaveIndicator() {\n * const syncStatus = useHocuspocusSyncStatus()\n *\n * return (\n * <div>\n * {syncStatus === 'syncing' ? 'Saving...' : 'All changes saved'}\n * </div>\n * )\n * }\n * ```\n */\nexport function useHocuspocusSyncStatus(): SyncStatus {\n\tconst provider = useHocuspocusProvider();\n\n\tconst subscribe = useCallback(\n\t\t(onStoreChange: () => void) => {\n\t\t\tprovider.on(\"synced\", onStoreChange);\n\t\t\tprovider.on(\"unsyncedChanges\", onStoreChange);\n\n\t\t\treturn () => {\n\t\t\t\tprovider.off(\"synced\", onStoreChange);\n\t\t\t\tprovider.off(\"unsyncedChanges\", onStoreChange);\n\t\t\t};\n\t\t},\n\t\t[provider],\n\t);\n\n\tconst getSnapshot = useCallback((): SyncStatus => {\n\t\t// Check if there are unsynced changes\n\t\tif (provider.unsyncedChanges > 0) {\n\t\t\treturn \"syncing\";\n\t\t}\n\t\treturn \"synced\";\n\t}, [provider]);\n\n\treturn useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n"],"mappings":"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"}
1
+ {"version":3,"file":"hocuspocus-provider-react.esm.js","names":[],"sources":["../src/context.ts","../src/HocuspocusProviderWebsocketComponent.tsx","../src/HocuspocusRoom.tsx","../src/hooks/useHocuspocusProvider.ts","../src/hooks/useHocuspocusAwareness.ts","../src/hooks/useHocuspocusConnectionStatus.ts","../src/hooks/useHocuspocusEvent.ts","../src/hooks/useHocuspocusSyncStatus.ts"],"sourcesContent":["import { createContext } from \"react\";\n\nimport type {\n\tHocuspocusContextValue,\n\tHocuspocusRoomContextValue,\n} from \"./types.ts\";\n\n/**\n * Context for the WebSocket connection shared across rooms\n */\nexport const HocuspocusContext =\n\tcreateContext<HocuspocusContextValue | null>(null);\n\n/**\n * Context for the room/document provider\n */\nexport const HocuspocusRoomContext =\n\tcreateContext<HocuspocusRoomContextValue | null>(null);\n","\"use client\";\n\nimport { HocuspocusProviderWebsocket } from \"@hocuspocus/provider\";\nimport { useEffect, useMemo, useRef } from \"react\";\n\nimport { HocuspocusContext } from \"./context.ts\";\nimport type { HocuspocusProviderWebsocketComponentProps } from \"./types.ts\";\n\n/**\n * HocuspocusProviderWebsocketComponent manages the WebSocket connection that is shared across all rooms.\n *\n * This component creates a single WebSocket connection that can be used by multiple\n * HocuspocusRoom components, preventing connection overhead when switching between documents.\n *\n * @example\n * ```tsx\n * <HocuspocusProviderWebsocketComponent url=\"ws://localhost:1234\">\n * <HocuspocusRoom name=\"document-1\">\n * <Editor />\n * </HocuspocusRoom>\n * </HocuspocusProviderWebsocketComponent>\n * ```\n */\nexport function HocuspocusProviderWebsocketComponent({\n\tchildren,\n\turl,\n\twebsocketProvider: externalWebsocketProvider,\n}: HocuspocusProviderWebsocketComponentProps) {\n\tconst websocketRef = useRef<HocuspocusProviderWebsocket | null>(null);\n\tconst destroyTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n\n\t// Create WebSocket provider once on mount.\n\t// Safe in StrictMode: useRef persists across double-renders, so the instance\n\t// is created only once. The deferred destruction in the effect below ensures\n\t// the second mount cancels the pending destroy before it fires.\n\tif (!websocketRef.current && !externalWebsocketProvider) {\n\t\twebsocketRef.current = new HocuspocusProviderWebsocket({\n\t\t\turl: url!,\n\t\t});\n\t}\n\n\tconst websocketProvider =\n\t\texternalWebsocketProvider ??\n\t\t(websocketRef.current as HocuspocusProviderWebsocket);\n\n\t// Cleanup on unmount with deferred destruction to handle StrictMode double-mount\n\tuseEffect(() => {\n\t\tif (destroyTimeoutRef.current) {\n\t\t\tclearTimeout(destroyTimeoutRef.current);\n\t\t\tdestroyTimeoutRef.current = null;\n\t\t}\n\n\t\treturn () => {\n\t\t\t// Only destroy if we created the websocket (not externally provided)\n\t\t\tif (!externalWebsocketProvider) {\n\t\t\t\tdestroyTimeoutRef.current = setTimeout(() => {\n\t\t\t\t\tif (websocketRef.current) {\n\t\t\t\t\t\twebsocketRef.current.destroy();\n\t\t\t\t\t\twebsocketRef.current = null;\n\t\t\t\t\t}\n\t\t\t\t}, 0);\n\t\t\t}\n\t\t};\n\t}, [externalWebsocketProvider]);\n\n\tconst contextValue = useMemo(\n\t\t() => ({\n\t\t\twebsocketProvider,\n\t\t}),\n\t\t[websocketProvider],\n\t);\n\n\treturn (\n\t\t<HocuspocusContext.Provider value={contextValue}>\n\t\t\t{children}\n\t\t</HocuspocusContext.Provider>\n\t);\n}\n","\"use client\";\n\nimport { HocuspocusProvider } from \"@hocuspocus/provider\";\nimport { useContext, useEffect, useMemo, useRef, useState } from \"react\";\n\nimport { HocuspocusContext, HocuspocusRoomContext } from \"./context.ts\";\nimport type { HocuspocusProviderEvents, HocuspocusRoomProps } from \"./types.ts\";\n\n/**\n * Mapping from HocuspocusRoom `on*` prop names to provider event names.\n */\nconst EVENT_PROP_MAP: Record<string, keyof HocuspocusProviderEvents> = {\n\tonOpen: \"open\",\n\tonConnect: \"connect\",\n\tonClose: \"close\",\n\tonDisconnect: \"disconnect\",\n\tonStatus: \"status\",\n\tonSynced: \"synced\",\n\tonUnsyncedChanges: \"unsyncedChanges\",\n\tonMessage: \"message\",\n\tonOutgoingMessage: \"outgoingMessage\",\n\tonStateless: \"stateless\",\n\tonAuthenticated: \"authenticated\",\n\tonAuthenticationFailed: \"authenticationFailed\",\n\tonAwarenessUpdate: \"awarenessUpdate\",\n\tonAwarenessChange: \"awarenessChange\",\n\tonDestroy: \"destroy\",\n};\n\n/**\n * HocuspocusRoom manages the connection to a specific document.\n *\n * It uses the shared WebSocket from HocuspocusProviderWebsocketComponent and creates a document-specific\n * provider that connects on mount and disconnects on unmount.\n *\n * This component handles React's StrictMode gracefully by using deferred destruction,\n * preventing unnecessary reconnections during development double-mounts.\n *\n * @example\n * ```tsx\n * <HocuspocusProviderWebsocketComponent url=\"ws://localhost:1234\">\n * <HocuspocusRoom\n * name=\"document-1\"\n * onAuthenticationFailed={(data) => console.error(data.reason)}\n * >\n * <Editor />\n * </HocuspocusRoom>\n * </HocuspocusProviderWebsocketComponent>\n * ```\n */\nexport function HocuspocusRoom({\n\tchildren,\n\tname,\n\tdocument,\n\ttoken,\n\tsessionAwareness,\n\tflushDelay,\n\t...eventHandlers\n}: HocuspocusRoomProps) {\n\tconst hocuspocusContext = useContext(HocuspocusContext);\n\n\tif (!hocuspocusContext) {\n\t\tthrow new Error(\n\t\t\t\"HocuspocusRoom must be used within a HocuspocusProviderWebsocketComponent\",\n\t\t);\n\t}\n\n\tconst { websocketProvider } = hocuspocusContext;\n\n\tconst [provider, setProvider] = useState(\n\t\t() =>\n\t\t\tnew HocuspocusProvider({\n\t\t\t\tname,\n\t\t\t\twebsocketProvider,\n\t\t\t\tdocument,\n\t\t\t\ttoken,\n\t\t\t\tsessionAwareness,\n\t\t\t\tflushDelay,\n\t\t\t}),\n\t);\n\n\tconst destroyTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n\n\t// Recreate provider when name, document, or token changes.\n\t// Only compare `document`/`token` when the caller actually provided them —\n\t// otherwise the provider's constructor-initialized defaults (auto-created\n\t// Y.Doc, null token) will never match the undefined prop, causing a destroy\n\t// on every render (and in StrictMode, a stray CloseMessage for the current\n\t// doc once the provider is already attached).\n\t// biome-ignore lint/correctness/useExhaustiveDependencies: provider.configuration holds the previous values we compare against — not a reactive dependency\n\tuseEffect(() => {\n\t\tconst shouldRecreate =\n\t\t\tprovider.configuration.name !== name ||\n\t\t\t(document !== undefined &&\n\t\t\t\tprovider.configuration.document !== document) ||\n\t\t\t(token !== undefined && provider.configuration.token !== token) ||\n\t\t\tprovider.configuration.websocketProvider !== websocketProvider;\n\n\t\tif (shouldRecreate) {\n\t\t\tprovider.destroy();\n\t\t\tsetProvider(\n\t\t\t\tnew HocuspocusProvider({\n\t\t\t\t\tname,\n\t\t\t\t\twebsocketProvider,\n\t\t\t\t\tdocument,\n\t\t\t\t\ttoken,\n\t\t\t\t\tsessionAwareness,\n\t\t\t\t\tflushDelay,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\t// eslint-disable-next-line react-hooks/exhaustive-deps\n\t}, [name, document, token, websocketProvider]);\n\n\t// Attach/detach lifecycle with deferred destruction for StrictMode\n\tuseEffect(() => {\n\t\tif (destroyTimeoutRef.current) {\n\t\t\tclearTimeout(destroyTimeoutRef.current);\n\t\t\tdestroyTimeoutRef.current = null;\n\t\t}\n\n\t\tprovider.attach();\n\n\t\treturn () => {\n\t\t\tdestroyTimeoutRef.current = setTimeout(() => {\n\t\t\t\tprovider.destroy();\n\t\t\t}, 0);\n\t\t};\n\t}, [provider]);\n\n\t// Wire up on* event handler props with stable refs\n\tconst handlersRef = useRef(eventHandlers);\n\thandlersRef.current = eventHandlers;\n\n\tuseEffect(() => {\n\t\tconst cleanups: (() => void)[] = [];\n\n\t\tfor (const [propName, eventName] of Object.entries(EVENT_PROP_MAP)) {\n\t\t\tconst listener = (...args: unknown[]) => {\n\t\t\t\tconst handler = handlersRef.current[\n\t\t\t\t\tpropName as keyof typeof handlersRef.current\n\t\t\t\t] as ((...a: unknown[]) => void) | undefined;\n\t\t\t\thandler?.(...args);\n\t\t\t};\n\t\t\tprovider.on(eventName, listener);\n\t\t\tcleanups.push(() => provider.off(eventName, listener));\n\t\t}\n\n\t\treturn () => {\n\t\t\tfor (const cleanup of cleanups) {\n\t\t\t\tcleanup();\n\t\t\t}\n\t\t};\n\t}, [provider]);\n\n\tconst contextValue = useMemo(\n\t\t() => ({\n\t\t\tprovider,\n\t\t}),\n\t\t[provider],\n\t);\n\n\treturn (\n\t\t<HocuspocusRoomContext.Provider value={contextValue}>\n\t\t\t{children}\n\t\t</HocuspocusRoomContext.Provider>\n\t);\n}\n","import { useContext } from \"react\";\n\nimport { HocuspocusRoomContext } from \"../context.ts\";\n\n/**\n * Access the HocuspocusProvider instance for the current room.\n *\n * Must be used within a HocuspocusRoom component.\n *\n * @returns The HocuspocusProvider instance\n * @throws Error if used outside of HocuspocusRoom\n *\n * @example\n * ```tsx\n * function Editor() {\n * const provider = useHocuspocusProvider()\n *\n * const editor = useEditor({\n * extensions: [\n * Collaboration.configure({ document: provider.document }),\n * CollaborationCursor.configure({ provider }),\n * ],\n * })\n *\n * return <EditorContent editor={editor} />\n * }\n * ```\n */\nexport function useHocuspocusProvider() {\n\tconst context = useContext(HocuspocusRoomContext);\n\n\tif (!context) {\n\t\tthrow new Error(\"useHocuspocusProvider must be used within a HocuspocusRoom\");\n\t}\n\n\treturn context.provider;\n}\n","import { useCallback, useEffect, useRef, useSyncExternalStore } from \"react\";\n\nimport type { CollabUser } from \"../types.ts\";\nimport { useHocuspocusProvider } from \"./useHocuspocusProvider.ts\";\n\n/**\n * Subscribe to the list of connected users in the document.\n *\n * This hook uses the Yjs awareness protocol to track users currently\n * connected to the document.\n *\n * @returns Array of user objects with their awareness state\n *\n * @example\n * ```tsx\n * function UserList() {\n * const users = useHocuspocusAwareness()\n *\n * return (\n * <div className=\"avatars\">\n * {users.map(user => (\n * <div\n * key={user.clientId}\n * style={{ backgroundColor: user.color }}\n * title={user.name}\n * >\n * {user.name?.[0]}\n * </div>\n * ))}\n * </div>\n * )\n * }\n * ```\n */\nexport function useHocuspocusAwareness(): CollabUser[] {\n\tconst provider = useHocuspocusProvider();\n\n\tconst versionRef = useRef(0);\n\tconst cacheRef = useRef<{ users: CollabUser[]; version: number }>({\n\t\tusers: [],\n\t\tversion: -1,\n\t});\n\n\t// Reset cache when provider changes so we don't serve stale users\n\t// from a previous provider instance.\n\tuseEffect(() => {\n\t\tversionRef.current++;\n\t\tcacheRef.current = { users: [], version: -1 };\n\t}, [provider]);\n\n\tconst subscribe = useCallback(\n\t\t(onStoreChange: () => void) => {\n\t\t\tconst onChange = () => {\n\t\t\t\tversionRef.current++;\n\t\t\t\tonStoreChange();\n\t\t\t};\n\t\t\tprovider.awareness?.on(\"change\", onChange);\n\t\t\treturn () => {\n\t\t\t\tprovider.awareness?.off(\"change\", onChange);\n\t\t\t};\n\t\t},\n\t\t[provider],\n\t);\n\n\tconst getSnapshot = useCallback(() => {\n\t\tconst awareness = provider.awareness;\n\t\tif (!awareness) {\n\t\t\treturn [];\n\t\t}\n\n\t\t// Return cached value if awareness hasn't changed since last snapshot\n\t\tif (cacheRef.current.version === versionRef.current) {\n\t\t\treturn cacheRef.current.users;\n\t\t}\n\n\t\tconst users: CollabUser[] = [];\n\t\tawareness.getStates().forEach((state, clientId) => {\n\t\t\tusers.push({\n\t\t\t\tclientId,\n\t\t\t\t...state,\n\t\t\t});\n\t\t});\n\n\t\tcacheRef.current = { users, version: versionRef.current };\n\t\treturn users;\n\t}, [provider]);\n\n\treturn useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n","import { useCallback, useSyncExternalStore } from \"react\";\n\nimport type { ConnectionStatus } from \"../types.ts\";\nimport { useHocuspocusProvider } from \"./useHocuspocusProvider.ts\";\n\n/**\n * Subscribe to the connection status of the collaboration provider.\n *\n * This hook uses React's useSyncExternalStore for optimal integration with\n * concurrent rendering features.\n *\n * @returns The current connection status: 'connecting', 'connected', or 'disconnected'\n *\n * @example\n * ```tsx\n * function ConnectionIndicator() {\n * const status = useHocuspocusConnectionStatus()\n *\n * return (\n * <div className={`status-${status}`}>\n * {status === 'connected' ? 'Online' : status === 'connecting' ? 'Connecting...' : 'Offline'}\n * </div>\n * )\n * }\n * ```\n */\nexport function useHocuspocusConnectionStatus(): ConnectionStatus {\n\tconst provider = useHocuspocusProvider();\n\n\tconst subscribe = useCallback(\n\t\t(onStoreChange: () => void) => {\n\t\t\tprovider.on(\"status\", onStoreChange);\n\t\t\treturn () => {\n\t\t\t\tprovider.off(\"status\", onStoreChange);\n\t\t\t};\n\t\t},\n\t\t[provider],\n\t);\n\n\tconst getSnapshot = useCallback(\n\t\t(): ConnectionStatus =>\n\t\t\tprovider.configuration.websocketProvider.status as ConnectionStatus,\n\t\t[provider],\n\t);\n\n\treturn useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n","import { useEffect, useRef } from \"react\";\n\nimport type { HocuspocusProviderEvents } from \"../types.ts\";\nimport { useHocuspocusProvider } from \"./useHocuspocusProvider.ts\";\n\n/**\n * Subscribe to events from the HocuspocusProvider for the current room.\n *\n * The handler is stored in a ref so the subscription stays stable even if\n * the handler identity changes between renders.\n *\n * Must be used within a HocuspocusRoom component.\n *\n * @param event - The event name to subscribe to\n * @param handler - Callback invoked when the event fires\n *\n * @example\n * ```tsx\n * function AuthGuard() {\n * useHocuspocusEvent('authenticationFailed', (data) => {\n * console.error('Auth failed:', data.reason)\n * redirectToLogin()\n * })\n *\n * useHocuspocusEvent('close', (data) => {\n * console.log('Connection closed', data.event)\n * })\n *\n * return null\n * }\n * ```\n */\nexport function useHocuspocusEvent<E extends keyof HocuspocusProviderEvents>(\n\tevent: E,\n\thandler: HocuspocusProviderEvents[E] extends undefined\n\t\t? () => void\n\t\t: (data: HocuspocusProviderEvents[E]) => void,\n): void {\n\tconst provider = useHocuspocusProvider();\n\tconst handlerRef = useRef(handler);\n\thandlerRef.current = handler;\n\n\tuseEffect(() => {\n\t\tconst listener = (...args: unknown[]) => {\n\t\t\t(handlerRef.current as (...a: unknown[]) => void)(...args);\n\t\t};\n\t\tprovider.on(event, listener);\n\t\treturn () => {\n\t\t\tprovider.off(event, listener);\n\t\t};\n\t}, [provider, event]);\n}\n","import { useCallback, useSyncExternalStore } from \"react\";\n\nimport type { SyncStatus } from \"../types.ts\";\nimport { useHocuspocusProvider } from \"./useHocuspocusProvider.ts\";\n\n/**\n * Subscribe to the sync status of local changes.\n *\n * This hook indicates whether local changes have been synced with the server.\n *\n * @returns The current sync status: 'synced' or 'syncing'\n *\n * @example\n * ```tsx\n * function SaveIndicator() {\n * const syncStatus = useHocuspocusSyncStatus()\n *\n * return (\n * <div>\n * {syncStatus === 'syncing' ? 'Saving...' : 'All changes saved'}\n * </div>\n * )\n * }\n * ```\n */\nexport function useHocuspocusSyncStatus(): SyncStatus {\n\tconst provider = useHocuspocusProvider();\n\n\tconst subscribe = useCallback(\n\t\t(onStoreChange: () => void) => {\n\t\t\tprovider.on(\"synced\", onStoreChange);\n\t\t\tprovider.on(\"unsyncedChanges\", onStoreChange);\n\n\t\t\treturn () => {\n\t\t\t\tprovider.off(\"synced\", onStoreChange);\n\t\t\t\tprovider.off(\"unsyncedChanges\", onStoreChange);\n\t\t\t};\n\t\t},\n\t\t[provider],\n\t);\n\n\tconst getSnapshot = useCallback((): SyncStatus => {\n\t\t// Check if there are unsynced changes\n\t\tif (provider.unsyncedChanges > 0) {\n\t\t\treturn \"syncing\";\n\t\t}\n\t\treturn \"synced\";\n\t}, [provider]);\n\n\treturn useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n"],"mappings":"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"}
package/dist/index.d.ts CHANGED
@@ -75,6 +75,15 @@ interface HocuspocusRoomProps {
75
75
  * Default: false
76
76
  */
77
77
  sessionAwareness?: boolean;
78
+ /**
79
+ * Batch outgoing document and awareness updates over a short window (in
80
+ * milliseconds) instead of sending one message per change, to reduce the
81
+ * number of websocket messages during heavy editing. The added latency is
82
+ * capped at `flushDelay`, so keep it small (e.g. 500).
83
+ *
84
+ * Default: false (send every change immediately)
85
+ */
86
+ flushDelay?: false | number;
78
87
  onOpen?: (data: onOpenParameters) => void;
79
88
  onConnect?: () => void;
80
89
  onClose?: (data: onCloseParameters) => void;
@@ -179,6 +188,7 @@ declare function HocuspocusRoom({
179
188
  document,
180
189
  token,
181
190
  sessionAwareness,
191
+ flushDelay,
182
192
  ...eventHandlers
183
193
  }: HocuspocusRoomProps): react.JSX.Element;
184
194
  //#endregion
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hocuspocus/provider-react",
3
- "version": "4.3.0",
3
+ "version": "4.5.0",
4
4
  "description": "React bindings for Hocuspocus provider",
5
5
  "homepage": "https://hocuspocus.dev",
6
6
  "keywords": [
@@ -30,13 +30,13 @@
30
30
  "dist"
31
31
  ],
32
32
  "peerDependencies": {
33
- "@hocuspocus/provider": "^4.3.0",
33
+ "@hocuspocus/provider": "^4.5.0",
34
34
  "react": "^18.0.0 || ^19.0.0",
35
35
  "yjs": "^13.6.8"
36
36
  },
37
37
  "devDependencies": {
38
- "@types/react": "^19.0.0",
39
- "react": "^19.0.0"
38
+ "@types/react": "^19.2.14",
39
+ "react": "^19.2.4"
40
40
  },
41
41
  "repository": {
42
42
  "url": "https://github.com/ueberdosis/hocuspocus"
@@ -44,5 +44,5 @@
44
44
  "publishConfig": {
45
45
  "access": "public"
46
46
  },
47
- "gitHead": "1129ae0a0ec6807e2f3ef2e5884d720bcf1892d7"
47
+ "gitHead": "7827bded7c9181513a3b7c94acbaee0e4059d066"
48
48
  }
@@ -54,6 +54,7 @@ export function HocuspocusRoom({
54
54
  document,
55
55
  token,
56
56
  sessionAwareness,
57
+ flushDelay,
57
58
  ...eventHandlers
58
59
  }: HocuspocusRoomProps) {
59
60
  const hocuspocusContext = useContext(HocuspocusContext);
@@ -74,6 +75,7 @@ export function HocuspocusRoom({
74
75
  document,
75
76
  token,
76
77
  sessionAwareness,
78
+ flushDelay,
77
79
  }),
78
80
  );
79
81
 
@@ -103,6 +105,7 @@ export function HocuspocusRoom({
103
105
  document,
104
106
  token,
105
107
  sessionAwareness,
108
+ flushDelay,
106
109
  }),
107
110
  );
108
111
  }
package/src/types.ts CHANGED
@@ -87,13 +87,23 @@ export interface HocuspocusRoomProps {
87
87
  * sessionId in the documentName field of every message, allowing multiple
88
88
  * providers with the same document name on a single WebSocket connection.
89
89
  *
90
- * Only set this to `true` when connecting to a v4 server that does
90
+ * Only set this to `true` when connecting to a v4 server that does
91
91
  * support session awareness.
92
92
  *
93
93
  * Default: false
94
94
  */
95
95
  sessionAwareness?: boolean;
96
96
 
97
+ /**
98
+ * Batch outgoing document and awareness updates over a short window (in
99
+ * milliseconds) instead of sending one message per change, to reduce the
100
+ * number of websocket messages during heavy editing. The added latency is
101
+ * capped at `flushDelay`, so keep it small (e.g. 500).
102
+ *
103
+ * Default: false (send every change immediately)
104
+ */
105
+ flushDelay?: false | number;
106
+
97
107
  // Event handlers — all optional, called when the provider emits the corresponding event.
98
108
  onOpen?: (data: onOpenParameters) => void;
99
109
  onConnect?: () => void;