@hocuspocus/provider-react 4.0.0 → 4.1.1
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.
- package/dist/hocuspocus-provider-react.cjs +5 -3
- package/dist/hocuspocus-provider-react.cjs.map +1 -1
- package/dist/hocuspocus-provider-react.esm.js +5 -3
- package/dist/hocuspocus-provider-react.esm.js.map +1 -1
- package/dist/index.d.ts +12 -0
- package/package.json +3 -3
- package/src/HocuspocusRoom.tsx +3 -0
- package/src/types.ts +11 -0
|
@@ -101,7 +101,7 @@ const EVENT_PROP_MAP = {
|
|
|
101
101
|
* </HocuspocusProviderWebsocketComponent>
|
|
102
102
|
* ```
|
|
103
103
|
*/
|
|
104
|
-
function HocuspocusRoom({ children, name, document, token, ...eventHandlers }) {
|
|
104
|
+
function HocuspocusRoom({ children, name, document, token, sessionAwareness, ...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;
|
|
@@ -109,7 +109,8 @@ function HocuspocusRoom({ children, name, document, token, ...eventHandlers }) {
|
|
|
109
109
|
name,
|
|
110
110
|
websocketProvider,
|
|
111
111
|
document,
|
|
112
|
-
token
|
|
112
|
+
token,
|
|
113
|
+
sessionAwareness
|
|
113
114
|
}));
|
|
114
115
|
const destroyTimeoutRef = (0, react.useRef)(null);
|
|
115
116
|
(0, react.useEffect)(() => {
|
|
@@ -119,7 +120,8 @@ function HocuspocusRoom({ children, name, document, token, ...eventHandlers }) {
|
|
|
119
120
|
name,
|
|
120
121
|
websocketProvider,
|
|
121
122
|
document,
|
|
122
|
-
token
|
|
123
|
+
token,
|
|
124
|
+
sessionAwareness
|
|
123
125
|
}));
|
|
124
126
|
}
|
|
125
127
|
}, [
|
|
@@ -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\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}),\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}),\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,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,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,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACnInC,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\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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"}
|
|
@@ -100,7 +100,7 @@ const EVENT_PROP_MAP = {
|
|
|
100
100
|
* </HocuspocusProviderWebsocketComponent>
|
|
101
101
|
* ```
|
|
102
102
|
*/
|
|
103
|
-
function HocuspocusRoom({ children, name, document, token, ...eventHandlers }) {
|
|
103
|
+
function HocuspocusRoom({ children, name, document, token, sessionAwareness, ...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;
|
|
@@ -108,7 +108,8 @@ function HocuspocusRoom({ children, name, document, token, ...eventHandlers }) {
|
|
|
108
108
|
name,
|
|
109
109
|
websocketProvider,
|
|
110
110
|
document,
|
|
111
|
-
token
|
|
111
|
+
token,
|
|
112
|
+
sessionAwareness
|
|
112
113
|
}));
|
|
113
114
|
const destroyTimeoutRef = useRef(null);
|
|
114
115
|
useEffect(() => {
|
|
@@ -118,7 +119,8 @@ function HocuspocusRoom({ children, name, document, token, ...eventHandlers }) {
|
|
|
118
119
|
name,
|
|
119
120
|
websocketProvider,
|
|
120
121
|
document,
|
|
121
|
-
token
|
|
122
|
+
token,
|
|
123
|
+
sessionAwareness
|
|
122
124
|
}));
|
|
123
125
|
}
|
|
124
126
|
}, [
|
|
@@ -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\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}),\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}),\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\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,oBACZ,cAA6C,KAAK;;;;AAKnD,MAAa,wBACZ,cAAiD,KAAK;;;;;;;;;;;;;;;;;;;ACMvD,SAAgB,qCAAqC,EACpD,UACA,KACA,mBAAmB,6BAC0B;CAC7C,MAAM,eAAe,OAA2C,KAAK;CACrE,MAAM,oBAAoB,OAA6C,KAAK;AAM5E,KAAI,CAAC,aAAa,WAAW,CAAC,0BAC7B,cAAa,UAAU,IAAI,4BAA4B,EACjD,KACL,CAAC;CAGH,MAAM,oBACL,6BACC,aAAa;AAGf,iBAAgB;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,eAAe,eACb,EACN,mBACA,GACD,CAAC,kBAAkB,CACnB;AAED,QACC,oBAAC,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,oBAAoB,WAAW,kBAAkB;AAEvD,KAAI,CAAC,kBACJ,OAAM,IAAI,MACT,4EACA;CAGF,MAAM,EAAE,sBAAsB;CAE9B,MAAM,CAAC,UAAU,eAAe,eAE9B,IAAI,mBAAmB;EACtB;EACA;EACA;EACA;EACA;EACA,CAAC,CACH;CAED,MAAM,oBAAoB,OAA6C,KAAK;AAS5E,iBAAgB;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,IAAI,mBAAmB;IACtB;IACA;IACA;IACA;IACA;IACA,CAAC,CACF;;IAGA;EAAC;EAAM;EAAU;EAAO;EAAkB,CAAC;AAG9C,iBAAgB;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,cAAc,OAAO,cAAc;AACzC,aAAY,UAAU;AAEtB,iBAAgB;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,eAAe,eACb,EACN,UACA,GACD,CAAC,SAAS,CACV;AAED,QACC,oBAAC,sBAAsB,UAAvB;EAAgC,OAAO;EACrC;EAC+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACtInC,SAAgB,wBAAwB;CACvC,MAAM,UAAU,WAAW,sBAAsB;AAEjD,KAAI,CAAC,QACJ,OAAM,IAAI,MAAM,6DAA6D;AAG9E,QAAO,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACDhB,SAAgB,yBAAuC;CACtD,MAAM,WAAW,uBAAuB;CAExC,MAAM,aAAa,OAAO,EAAE;CAC5B,MAAM,WAAW,OAAiD;EACjE,OAAO,EAAE;EACT,SAAS;EACT,CAAC;AAIF,iBAAgB;AACf,aAAW;AACX,WAAS,UAAU;GAAE,OAAO,EAAE;GAAE,SAAS;GAAI;IAC3C,CAAC,SAAS,CAAC;CAEd,MAAM,YAAY,aAChB,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,cAAc,kBAAkB;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,QAAO,qBAAqB,WAAW,aAAa,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;AC7DjE,SAAgB,gCAAkD;CACjE,MAAM,WAAW,uBAAuB;CAExC,MAAM,YAAY,aAChB,kBAA8B;AAC9B,WAAS,GAAG,UAAU,cAAc;AACpC,eAAa;AACZ,YAAS,IAAI,UAAU,cAAc;;IAGvC,CAAC,SAAS,CACV;CAED,MAAM,cAAc,kBAElB,SAAS,cAAc,kBAAkB,QAC1C,CAAC,SAAS,CACV;AAED,QAAO,qBAAqB,WAAW,aAAa,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACbjE,SAAgB,mBACf,OACA,SAGO;CACP,MAAM,WAAW,uBAAuB;CACxC,MAAM,aAAa,OAAO,QAAQ;AAClC,YAAW,UAAU;AAErB,iBAAgB;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,YAAY,aAChB,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,cAAc,kBAA8B;AAEjD,MAAI,SAAS,kBAAkB,EAC9B,QAAO;AAER,SAAO;IACL,CAAC,SAAS,CAAC;AAEd,QAAO,qBAAqB,WAAW,aAAa,YAAY"}
|
package/dist/index.d.ts
CHANGED
|
@@ -64,6 +64,17 @@ interface HocuspocusRoomProps {
|
|
|
64
64
|
* JWT token or function that returns a promise resolving to a token
|
|
65
65
|
*/
|
|
66
66
|
token?: string | (() => Promise<string>) | (() => string);
|
|
67
|
+
/**
|
|
68
|
+
* Enable session-aware multiplexing. When true, the provider embeds a unique
|
|
69
|
+
* sessionId in the documentName field of every message, allowing multiple
|
|
70
|
+
* providers with the same document name on a single WebSocket connection.
|
|
71
|
+
*
|
|
72
|
+
* Only set this to `true` when connecting to a v4 server that does
|
|
73
|
+
* support session awareness.
|
|
74
|
+
*
|
|
75
|
+
* Default: false
|
|
76
|
+
*/
|
|
77
|
+
sessionAwareness?: boolean;
|
|
67
78
|
onOpen?: (data: onOpenParameters) => void;
|
|
68
79
|
onConnect?: () => void;
|
|
69
80
|
onClose?: (data: onCloseParameters) => void;
|
|
@@ -167,6 +178,7 @@ declare function HocuspocusRoom({
|
|
|
167
178
|
name,
|
|
168
179
|
document,
|
|
169
180
|
token,
|
|
181
|
+
sessionAwareness,
|
|
170
182
|
...eventHandlers
|
|
171
183
|
}: HocuspocusRoomProps): react.JSX.Element;
|
|
172
184
|
//#endregion
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hocuspocus/provider-react",
|
|
3
|
-
"version": "4.
|
|
3
|
+
"version": "4.1.1",
|
|
4
4
|
"description": "React bindings for Hocuspocus provider",
|
|
5
5
|
"homepage": "https://hocuspocus.dev",
|
|
6
6
|
"keywords": [
|
|
@@ -30,7 +30,7 @@
|
|
|
30
30
|
"dist"
|
|
31
31
|
],
|
|
32
32
|
"peerDependencies": {
|
|
33
|
-
"@hocuspocus/provider": "^4.
|
|
33
|
+
"@hocuspocus/provider": "^4.1.1",
|
|
34
34
|
"react": "^18.0.0 || ^19.0.0",
|
|
35
35
|
"yjs": "^13.6.8"
|
|
36
36
|
},
|
|
@@ -44,5 +44,5 @@
|
|
|
44
44
|
"publishConfig": {
|
|
45
45
|
"access": "public"
|
|
46
46
|
},
|
|
47
|
-
"gitHead": "
|
|
47
|
+
"gitHead": "a07826a1e654edfb89f340fad6fb9492d1c256aa"
|
|
48
48
|
}
|
package/src/HocuspocusRoom.tsx
CHANGED
|
@@ -53,6 +53,7 @@ export function HocuspocusRoom({
|
|
|
53
53
|
name,
|
|
54
54
|
document,
|
|
55
55
|
token,
|
|
56
|
+
sessionAwareness,
|
|
56
57
|
...eventHandlers
|
|
57
58
|
}: HocuspocusRoomProps) {
|
|
58
59
|
const hocuspocusContext = useContext(HocuspocusContext);
|
|
@@ -72,6 +73,7 @@ export function HocuspocusRoom({
|
|
|
72
73
|
websocketProvider,
|
|
73
74
|
document,
|
|
74
75
|
token,
|
|
76
|
+
sessionAwareness,
|
|
75
77
|
}),
|
|
76
78
|
);
|
|
77
79
|
|
|
@@ -100,6 +102,7 @@ export function HocuspocusRoom({
|
|
|
100
102
|
websocketProvider,
|
|
101
103
|
document,
|
|
102
104
|
token,
|
|
105
|
+
sessionAwareness,
|
|
103
106
|
}),
|
|
104
107
|
);
|
|
105
108
|
}
|
package/src/types.ts
CHANGED
|
@@ -82,6 +82,17 @@ export interface HocuspocusRoomProps {
|
|
|
82
82
|
* JWT token or function that returns a promise resolving to a token
|
|
83
83
|
*/
|
|
84
84
|
token?: string | (() => Promise<string>) | (() => string);
|
|
85
|
+
/**
|
|
86
|
+
* Enable session-aware multiplexing. When true, the provider embeds a unique
|
|
87
|
+
* sessionId in the documentName field of every message, allowing multiple
|
|
88
|
+
* providers with the same document name on a single WebSocket connection.
|
|
89
|
+
*
|
|
90
|
+
* Only set this to `true` when connecting to a v4 server that does
|
|
91
|
+
* support session awareness.
|
|
92
|
+
*
|
|
93
|
+
* Default: false
|
|
94
|
+
*/
|
|
95
|
+
sessionAwareness?: boolean;
|
|
85
96
|
|
|
86
97
|
// Event handlers — all optional, called when the provider emits the corresponding event.
|
|
87
98
|
onOpen?: (data: onOpenParameters) => void;
|