@hocuspocus/provider-react 4.0.0-rc.4

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/src/context.ts ADDED
@@ -0,0 +1,18 @@
1
+ import { createContext } from "react";
2
+
3
+ import type {
4
+ HocuspocusContextValue,
5
+ HocuspocusRoomContextValue,
6
+ } from "./types.ts";
7
+
8
+ /**
9
+ * Context for the WebSocket connection shared across rooms
10
+ */
11
+ export const HocuspocusContext =
12
+ createContext<HocuspocusContextValue | null>(null);
13
+
14
+ /**
15
+ * Context for the room/document provider
16
+ */
17
+ export const HocuspocusRoomContext =
18
+ createContext<HocuspocusRoomContextValue | null>(null);
@@ -0,0 +1,5 @@
1
+ export { useHocuspocusAwareness } from "./useHocuspocusAwareness.ts";
2
+ export { useHocuspocusConnectionStatus } from "./useHocuspocusConnectionStatus.ts";
3
+ export { useHocuspocusEvent } from "./useHocuspocusEvent.ts";
4
+ export { useHocuspocusProvider } from "./useHocuspocusProvider.ts";
5
+ export { useHocuspocusSyncStatus } from "./useHocuspocusSyncStatus.ts";
@@ -0,0 +1,89 @@
1
+ import { useCallback, useEffect, useRef, useSyncExternalStore } from "react";
2
+
3
+ import type { CollabUser } from "../types.ts";
4
+ import { useHocuspocusProvider } from "./useHocuspocusProvider.ts";
5
+
6
+ /**
7
+ * Subscribe to the list of connected users in the document.
8
+ *
9
+ * This hook uses the Yjs awareness protocol to track users currently
10
+ * connected to the document.
11
+ *
12
+ * @returns Array of user objects with their awareness state
13
+ *
14
+ * @example
15
+ * ```tsx
16
+ * function UserList() {
17
+ * const users = useHocuspocusAwareness()
18
+ *
19
+ * return (
20
+ * <div className="avatars">
21
+ * {users.map(user => (
22
+ * <div
23
+ * key={user.clientId}
24
+ * style={{ backgroundColor: user.color }}
25
+ * title={user.name}
26
+ * >
27
+ * {user.name?.[0]}
28
+ * </div>
29
+ * ))}
30
+ * </div>
31
+ * )
32
+ * }
33
+ * ```
34
+ */
35
+ export function useHocuspocusAwareness(): CollabUser[] {
36
+ const provider = useHocuspocusProvider();
37
+
38
+ const versionRef = useRef(0);
39
+ const cacheRef = useRef<{ users: CollabUser[]; version: number }>({
40
+ users: [],
41
+ version: -1,
42
+ });
43
+
44
+ // Reset cache when provider changes so we don't serve stale users
45
+ // from a previous provider instance.
46
+ useEffect(() => {
47
+ versionRef.current++;
48
+ cacheRef.current = { users: [], version: -1 };
49
+ }, [provider]);
50
+
51
+ const subscribe = useCallback(
52
+ (onStoreChange: () => void) => {
53
+ const onChange = () => {
54
+ versionRef.current++;
55
+ onStoreChange();
56
+ };
57
+ provider.awareness?.on("change", onChange);
58
+ return () => {
59
+ provider.awareness?.off("change", onChange);
60
+ };
61
+ },
62
+ [provider],
63
+ );
64
+
65
+ const getSnapshot = useCallback(() => {
66
+ const awareness = provider.awareness;
67
+ if (!awareness) {
68
+ return [];
69
+ }
70
+
71
+ // Return cached value if awareness hasn't changed since last snapshot
72
+ if (cacheRef.current.version === versionRef.current) {
73
+ return cacheRef.current.users;
74
+ }
75
+
76
+ const users: CollabUser[] = [];
77
+ awareness.getStates().forEach((state, clientId) => {
78
+ users.push({
79
+ clientId,
80
+ ...state,
81
+ });
82
+ });
83
+
84
+ cacheRef.current = { users, version: versionRef.current };
85
+ return users;
86
+ }, [provider]);
87
+
88
+ return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
89
+ }
@@ -0,0 +1,47 @@
1
+ import { useCallback, useSyncExternalStore } from "react";
2
+
3
+ import type { ConnectionStatus } from "../types.ts";
4
+ import { useHocuspocusProvider } from "./useHocuspocusProvider.ts";
5
+
6
+ /**
7
+ * Subscribe to the connection status of the collaboration provider.
8
+ *
9
+ * This hook uses React's useSyncExternalStore for optimal integration with
10
+ * concurrent rendering features.
11
+ *
12
+ * @returns The current connection status: 'connecting', 'connected', or 'disconnected'
13
+ *
14
+ * @example
15
+ * ```tsx
16
+ * function ConnectionIndicator() {
17
+ * const status = useHocuspocusConnectionStatus()
18
+ *
19
+ * return (
20
+ * <div className={`status-${status}`}>
21
+ * {status === 'connected' ? 'Online' : status === 'connecting' ? 'Connecting...' : 'Offline'}
22
+ * </div>
23
+ * )
24
+ * }
25
+ * ```
26
+ */
27
+ export function useHocuspocusConnectionStatus(): ConnectionStatus {
28
+ const provider = useHocuspocusProvider();
29
+
30
+ const subscribe = useCallback(
31
+ (onStoreChange: () => void) => {
32
+ provider.on("status", onStoreChange);
33
+ return () => {
34
+ provider.off("status", onStoreChange);
35
+ };
36
+ },
37
+ [provider],
38
+ );
39
+
40
+ const getSnapshot = useCallback(
41
+ (): ConnectionStatus =>
42
+ provider.configuration.websocketProvider.status as ConnectionStatus,
43
+ [provider],
44
+ );
45
+
46
+ return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
47
+ }
@@ -0,0 +1,52 @@
1
+ import { useEffect, useRef } from "react";
2
+
3
+ import type { HocuspocusProviderEvents } from "../types.ts";
4
+ import { useHocuspocusProvider } from "./useHocuspocusProvider.ts";
5
+
6
+ /**
7
+ * Subscribe to events from the HocuspocusProvider for the current room.
8
+ *
9
+ * The handler is stored in a ref so the subscription stays stable even if
10
+ * the handler identity changes between renders.
11
+ *
12
+ * Must be used within a HocuspocusRoom component.
13
+ *
14
+ * @param event - The event name to subscribe to
15
+ * @param handler - Callback invoked when the event fires
16
+ *
17
+ * @example
18
+ * ```tsx
19
+ * function AuthGuard() {
20
+ * useHocuspocusEvent('authenticationFailed', (data) => {
21
+ * console.error('Auth failed:', data.reason)
22
+ * redirectToLogin()
23
+ * })
24
+ *
25
+ * useHocuspocusEvent('close', (data) => {
26
+ * console.log('Connection closed', data.event)
27
+ * })
28
+ *
29
+ * return null
30
+ * }
31
+ * ```
32
+ */
33
+ export function useHocuspocusEvent<E extends keyof HocuspocusProviderEvents>(
34
+ event: E,
35
+ handler: HocuspocusProviderEvents[E] extends undefined
36
+ ? () => void
37
+ : (data: HocuspocusProviderEvents[E]) => void,
38
+ ): void {
39
+ const provider = useHocuspocusProvider();
40
+ const handlerRef = useRef(handler);
41
+ handlerRef.current = handler;
42
+
43
+ useEffect(() => {
44
+ const listener = (...args: unknown[]) => {
45
+ (handlerRef.current as (...a: unknown[]) => void)(...args);
46
+ };
47
+ provider.on(event, listener);
48
+ return () => {
49
+ provider.off(event, listener);
50
+ };
51
+ }, [provider, event]);
52
+ }
@@ -0,0 +1,37 @@
1
+ import { useContext } from "react";
2
+
3
+ import { HocuspocusRoomContext } from "../context.ts";
4
+
5
+ /**
6
+ * Access the HocuspocusProvider instance for the current room.
7
+ *
8
+ * Must be used within a HocuspocusRoom component.
9
+ *
10
+ * @returns The HocuspocusProvider instance
11
+ * @throws Error if used outside of HocuspocusRoom
12
+ *
13
+ * @example
14
+ * ```tsx
15
+ * function Editor() {
16
+ * const provider = useHocuspocusProvider()
17
+ *
18
+ * const editor = useEditor({
19
+ * extensions: [
20
+ * Collaboration.configure({ document: provider.document }),
21
+ * CollaborationCursor.configure({ provider }),
22
+ * ],
23
+ * })
24
+ *
25
+ * return <EditorContent editor={editor} />
26
+ * }
27
+ * ```
28
+ */
29
+ export function useHocuspocusProvider() {
30
+ const context = useContext(HocuspocusRoomContext);
31
+
32
+ if (!context) {
33
+ throw new Error("useHocuspocusProvider must be used within a HocuspocusRoom");
34
+ }
35
+
36
+ return context.provider;
37
+ }
@@ -0,0 +1,51 @@
1
+ import { useCallback, useSyncExternalStore } from "react";
2
+
3
+ import type { SyncStatus } from "../types.ts";
4
+ import { useHocuspocusProvider } from "./useHocuspocusProvider.ts";
5
+
6
+ /**
7
+ * Subscribe to the sync status of local changes.
8
+ *
9
+ * This hook indicates whether local changes have been synced with the server.
10
+ *
11
+ * @returns The current sync status: 'synced' or 'syncing'
12
+ *
13
+ * @example
14
+ * ```tsx
15
+ * function SaveIndicator() {
16
+ * const syncStatus = useHocuspocusSyncStatus()
17
+ *
18
+ * return (
19
+ * <div>
20
+ * {syncStatus === 'syncing' ? 'Saving...' : 'All changes saved'}
21
+ * </div>
22
+ * )
23
+ * }
24
+ * ```
25
+ */
26
+ export function useHocuspocusSyncStatus(): SyncStatus {
27
+ const provider = useHocuspocusProvider();
28
+
29
+ const subscribe = useCallback(
30
+ (onStoreChange: () => void) => {
31
+ provider.on("synced", onStoreChange);
32
+ provider.on("unsyncedChanges", onStoreChange);
33
+
34
+ return () => {
35
+ provider.off("synced", onStoreChange);
36
+ provider.off("unsyncedChanges", onStoreChange);
37
+ };
38
+ },
39
+ [provider],
40
+ );
41
+
42
+ const getSnapshot = useCallback((): SyncStatus => {
43
+ // Check if there are unsynced changes
44
+ if (provider.unsyncedChanges > 0) {
45
+ return "syncing";
46
+ }
47
+ return "synced";
48
+ }, [provider]);
49
+
50
+ return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
51
+ }
package/src/index.ts ADDED
@@ -0,0 +1,29 @@
1
+ "use client";
2
+
3
+ // Contexts
4
+ export { HocuspocusContext, HocuspocusRoomContext } from "./context.ts";
5
+
6
+ // Components
7
+ export { HocuspocusProviderWebsocketComponent } from "./HocuspocusProviderWebsocketComponent.tsx";
8
+ export { HocuspocusRoom } from "./HocuspocusRoom.tsx";
9
+
10
+ // Hooks
11
+ export {
12
+ useHocuspocusAwareness,
13
+ useHocuspocusConnectionStatus,
14
+ useHocuspocusEvent,
15
+ useHocuspocusProvider,
16
+ useHocuspocusSyncStatus,
17
+ } from "./hooks/index.ts";
18
+
19
+ // Types
20
+ export type {
21
+ CollabUser,
22
+ ConnectionStatus,
23
+ HocuspocusContextValue,
24
+ HocuspocusProviderEvents,
25
+ HocuspocusProviderWebsocketComponentProps,
26
+ HocuspocusRoomContextValue,
27
+ HocuspocusRoomProps,
28
+ SyncStatus,
29
+ } from "./types.ts";
package/src/types.ts ADDED
@@ -0,0 +1,134 @@
1
+ import type {
2
+ HocuspocusProvider,
3
+ HocuspocusProviderWebsocket,
4
+ onAuthenticatedParameters,
5
+ onAuthenticationFailedParameters,
6
+ onAwarenessChangeParameters,
7
+ onAwarenessUpdateParameters,
8
+ onCloseParameters,
9
+ onDisconnectParameters,
10
+ onMessageParameters,
11
+ onOpenParameters,
12
+ onOutgoingMessageParameters,
13
+ onStatelessParameters,
14
+ onStatusParameters,
15
+ onSyncedParameters,
16
+ onUnsyncedChangesParameters,
17
+ } from "@hocuspocus/provider";
18
+ import type { ReactNode } from "react";
19
+ import type * as Y from "yjs";
20
+
21
+ /**
22
+ * Configuration for HocuspocusProvider component.
23
+ *
24
+ * Provide either a `url` to create a managed WebSocket connection,
25
+ * or a `websocketProvider` instance for full control — but not both.
26
+ */
27
+ export type HocuspocusProviderWebsocketComponentProps = {
28
+ children: ReactNode;
29
+ } & (
30
+ | {
31
+ /**
32
+ * URL of your @hocuspocus/server instance
33
+ */
34
+ url: string;
35
+ websocketProvider?: never;
36
+ }
37
+ | {
38
+ url?: never;
39
+ /**
40
+ * Provide your own websocket instance for full control
41
+ */
42
+ websocketProvider: HocuspocusProviderWebsocket;
43
+ }
44
+ );
45
+
46
+ /**
47
+ * Map of HocuspocusProvider event names to their payload types.
48
+ * Used by `useHocuspocusEvent` and the `HocuspocusRoom` event handler props.
49
+ */
50
+ export interface HocuspocusProviderEvents {
51
+ open: onOpenParameters;
52
+ connect: undefined;
53
+ close: onCloseParameters;
54
+ disconnect: onDisconnectParameters;
55
+ status: onStatusParameters;
56
+ synced: onSyncedParameters;
57
+ unsyncedChanges: onUnsyncedChangesParameters;
58
+ message: onMessageParameters;
59
+ outgoingMessage: onOutgoingMessageParameters;
60
+ stateless: onStatelessParameters;
61
+ authenticated: onAuthenticatedParameters;
62
+ authenticationFailed: onAuthenticationFailedParameters;
63
+ awarenessUpdate: onAwarenessUpdateParameters;
64
+ awarenessChange: onAwarenessChangeParameters;
65
+ destroy: undefined;
66
+ }
67
+
68
+ /**
69
+ * Configuration for HocuspocusRoom component
70
+ */
71
+ export interface HocuspocusRoomProps {
72
+ children: ReactNode;
73
+ /**
74
+ * The document name (required)
75
+ */
76
+ name: string;
77
+ /**
78
+ * Optional: bring your own Y.Doc
79
+ */
80
+ document?: Y.Doc;
81
+ /**
82
+ * JWT token or function that returns a promise resolving to a token
83
+ */
84
+ token?: string | (() => Promise<string>) | (() => string);
85
+
86
+ // Event handlers — all optional, called when the provider emits the corresponding event.
87
+ onOpen?: (data: onOpenParameters) => void;
88
+ onConnect?: () => void;
89
+ onClose?: (data: onCloseParameters) => void;
90
+ onDisconnect?: (data: onDisconnectParameters) => void;
91
+ onStatus?: (data: onStatusParameters) => void;
92
+ onSynced?: (data: onSyncedParameters) => void;
93
+ onUnsyncedChanges?: (data: onUnsyncedChangesParameters) => void;
94
+ onMessage?: (data: onMessageParameters) => void;
95
+ onOutgoingMessage?: (data: onOutgoingMessageParameters) => void;
96
+ onStateless?: (data: onStatelessParameters) => void;
97
+ onAuthenticated?: (data: onAuthenticatedParameters) => void;
98
+ onAuthenticationFailed?: (data: onAuthenticationFailedParameters) => void;
99
+ onAwarenessUpdate?: (data: onAwarenessUpdateParameters) => void;
100
+ onAwarenessChange?: (data: onAwarenessChangeParameters) => void;
101
+ onDestroy?: () => void;
102
+ }
103
+
104
+ /**
105
+ * Context value for the WebSocket provider
106
+ */
107
+ export interface HocuspocusContextValue {
108
+ websocketProvider: HocuspocusProviderWebsocket;
109
+ }
110
+
111
+ /**
112
+ * Context value for the room/document provider
113
+ */
114
+ export interface HocuspocusRoomContextValue {
115
+ provider: HocuspocusProvider;
116
+ }
117
+
118
+ /**
119
+ * Connection status for the collaboration provider
120
+ */
121
+ export type ConnectionStatus = "connecting" | "connected" | "disconnected";
122
+
123
+ /**
124
+ * Sync status indicating whether local changes are synced with server
125
+ */
126
+ export type SyncStatus = "synced" | "syncing";
127
+
128
+ /**
129
+ * User information from awareness
130
+ */
131
+ export interface CollabUser {
132
+ clientId: number;
133
+ [key: string]: unknown;
134
+ }