snapshot of https://github.com/ueberdosis/hocuspocus.git @ cf3cfa355b4d3bb61c6b6c80071f71783e32470e (2026-09-15)

playground/frontend/app/react-provider/[slug]/ArticleEditor.tsx

@@ -0,0 +1,159 @@
+"use client";
+
+import {
+	HocuspocusProviderWebsocketComponent,
+	HocuspocusRoom,
+} from "@hocuspocus/provider-react";
+import React, { useCallback } from "react";
+import CollaborationStatus from "./CollaborationStatus";
+import CollaborativeEditor from "./CollaborativeEditor";
+import ConnectedUsers from "./ConnectedUsers";
+
+export default function ArticleEditor({ slug }: { slug: string }) {
+	const handleAuthFailed = useCallback(
+		(data: { reason: string }) => {
+			console.error(`[Editor 1] Auth failed for "${slug}":`, data.reason);
+		},
+		[slug],
+	);
+
+	return (
+		<div className="flex flex-col min-h-screen">
+			{/* Header */}
+			<header className="bg-white/80 dark:bg-slate-900/80 backdrop-blur-sm border-b border-slate-200 dark:border-slate-700">
+				<div className="px-8 py-6">
+					<div className="flex items-center justify-between">
+						<div>
+							<h1 className="text-2xl font-bold text-slate-900 dark:text-white">
+								Article #{slug}
+								<span className="ml-3 text-sm font-medium text-purple-600 dark:text-purple-400 bg-purple-100 dark:bg-purple-900/30 px-2 py-1 rounded-full">
+									provider-react
+								</span>
+							</h1>
+							<p className="text-slate-600 dark:text-slate-400 mt-1">
+								Using @hocuspocus/provider-react hooks and components
+							</p>
+						</div>
+					</div>
+				</div>
+			</header>
+
+			{/* Main content */}
+			<main className="flex-1 p-8">
+				<div className="max-w-7xl mx-auto space-y-6">
+					{/* Two independent WebSocket connections, each with its own room */}
+					<div className="grid grid-cols-1 lg:grid-cols-2 gap-6">
+						{/* Editor 1 — event handlers via HocuspocusRoom props */}
+						<HocuspocusProviderWebsocketComponent url="ws://localhost:8000">
+							<HocuspocusRoom
+								name={slug}
+								onAuthenticationFailed={handleAuthFailed}
+								onClose={(data) =>
+									console.log("[Editor 1] Connection closed:", data.event)
+								}
+								onSynced={(data) =>
+									console.log("[Editor 1] Synced:", data.state)
+								}
+							>
+								<div className="space-y-4">
+									<div className="flex items-center justify-between">
+										<h2 className="text-lg font-semibold text-slate-900 dark:text-white">
+											Editor 1
+										</h2>
+										<span className="text-sm text-slate-500 dark:text-slate-400">
+											Event handlers via props
+										</span>
+									</div>
+
+									<CollaborationStatus />
+
+									<ConnectedUsers />
+
+									<div className="bg-white/30 dark:bg-slate-900/30 backdrop-blur-sm rounded-2xl p-6 border border-slate-200 dark:border-slate-700 shadow-xl">
+										<CollaborativeEditor />
+									</div>
+								</div>
+							</HocuspocusRoom>
+						</HocuspocusProviderWebsocketComponent>
+
+						{/* Editor 2 — event handlers via useHocuspocusEvent hook (see CollaborationStatus) */}
+						<HocuspocusProviderWebsocketComponent url="ws://localhost:8000">
+							<HocuspocusRoom name={slug}>
+								<div className="space-y-4">
+									<div className="flex items-center justify-between">
+										<h2 className="text-lg font-semibold text-slate-900 dark:text-white">
+											Editor 2
+										</h2>
+										<span className="text-sm text-slate-500 dark:text-slate-400">
+											Event handlers via hook
+										</span>
+									</div>
+
+									<CollaborationStatus />
+
+									<ConnectedUsers />
+
+									<div className="bg-white/30 dark:bg-slate-900/30 backdrop-blur-sm rounded-2xl p-6 border border-slate-200 dark:border-slate-700 shadow-xl">
+										<CollaborativeEditor />
+									</div>
+								</div>
+							</HocuspocusRoom>
+						</HocuspocusProviderWebsocketComponent>
+					</div>
+
+					{/* Info panel */}
+					<div className="bg-purple-50/50 dark:bg-purple-900/20 backdrop-blur-sm rounded-xl border border-purple-200 dark:border-purple-700 p-6">
+						<div className="flex items-start space-x-3">
+							<div className="flex-shrink-0">
+								<div className="w-8 h-8 bg-purple-100 dark:bg-purple-900/40 rounded-full flex items-center justify-center">
+									<svg
+										className="w-4 h-4 text-purple-600 dark:text-purple-400"
+										fill="none"
+										stroke="currentColor"
+										viewBox="0 0 24 24"
+									>
+										<path
+											strokeLinecap="round"
+											strokeLinejoin="round"
+											strokeWidth={2}
+											d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z"
+										/>
+									</svg>
+								</div>
+							</div>
+							<div>
+								<h3 className="text-sm font-medium text-purple-900 dark:text-purple-100">
+									@hocuspocus/provider-react Demo
+								</h3>
+								<p className="text-sm text-purple-700 dark:text-purple-300 mt-1">
+									This demo uses the new React-specific package. Each editor is
+									wrapped in its own{" "}
+									<code className="bg-purple-200/50 dark:bg-purple-800/50 px-1 rounded">
+										HocuspocusProviderWebsocketComponent
+									</code>{" "}
+									(independent WebSocket) and{" "}
+									<code className="bg-purple-200/50 dark:bg-purple-800/50 px-1 rounded">
+										HocuspocusRoom
+									</code>
+									. Status is read via{" "}
+									<code className="bg-purple-200/50 dark:bg-purple-800/50 px-1 rounded">
+										useHocuspocusConnectionStatus()
+									</code>
+									,{" "}
+									<code className="bg-purple-200/50 dark:bg-purple-800/50 px-1 rounded">
+										useHocuspocusSyncStatus()
+									</code>
+									, and{" "}
+									<code className="bg-purple-200/50 dark:bg-purple-800/50 px-1 rounded">
+										useHocuspocusAwareness()
+									</code>{" "}
+									hooks &mdash; no manual event listeners needed.
+								</p>
+							</div>
+						</div>
+					</div>
+				</div>
+			</main>
+		</div>
+	);
+}

playground/frontend/app/react-provider/[slug]/CollaborationStatus.tsx

@@ -0,0 +1,155 @@
+"use client";
+
+import {
+	useHocuspocusConnectionStatus,
+	useHocuspocusEvent,
+	useHocuspocusProvider,
+	useHocuspocusSyncStatus,
+} from "@hocuspocus/provider-react";
+import { useState } from "react";
+
+const CollaborationStatus = () => {
+	const provider = useHocuspocusProvider();
+	const connectionStatus = useHocuspocusConnectionStatus();
+	const syncStatus = useHocuspocusSyncStatus();
+	const [unsyncedChanges, setUnsyncedChanges] = useState(0);
+
+	// Using the useHocuspocusEvent hook instead of manual provider.on/off
+	useHocuspocusEvent("unsyncedChanges", (data) => {
+		setUnsyncedChanges(data.number);
+	});
+
+	const getStatusColor = (status: string) => {
+		switch (status) {
+			case "connected":
+				return "bg-green-100 text-green-800 dark:bg-green-900/20 dark:text-green-400";
+			case "connecting":
+				return "bg-yellow-100 text-yellow-800 dark:bg-yellow-900/20 dark:text-yellow-400";
+			case "disconnected":
+				return "bg-red-100 text-red-800 dark:bg-red-900/20 dark:text-red-400";
+			default:
+				return "bg-slate-100 text-slate-800 dark:bg-slate-800 dark:text-slate-400";
+		}
+	};
+
+	const UNSYNCED_THRESHOLD = 10;
+
+	return (
+		<div className="bg-white/60 dark:bg-slate-900/60 backdrop-blur-sm rounded-xl border border-slate-200 dark:border-slate-700 p-6">
+			{/* Alert banner when unsynced changes grow — indicates connection issues */}
+			{unsyncedChanges >= UNSYNCED_THRESHOLD && (
+				<div className="mb-4 p-3 bg-red-50 dark:bg-red-900/20 border border-red-200 dark:border-red-800 rounded-lg flex items-center space-x-3">
+					<div className="w-5 h-5 shrink-0 text-red-600 dark:text-red-400">
+						<svg fill="none" stroke="currentColor" viewBox="0 0 24 24">
+							<path
+								strokeLinecap="round"
+								strokeLinejoin="round"
+								strokeWidth={2}
+								d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-2.5L13.732 4c-.77-.833-1.964-.833-2.732 0L4.082 16.5c-.77.833.192 2.5 1.732 2.5z"
+							/>
+						</svg>
+					</div>
+					<div>
+						<p className="text-sm font-medium text-red-800 dark:text-red-200">
+							Connection issue detected
+						</p>
+						<p className="text-xs text-red-600 dark:text-red-400">
+							{unsyncedChanges} changes are waiting to sync. Your edits are
+							saved locally but not yet on the server.
+						</p>
+					</div>
+				</div>
+			)}
+
+			{/* Status indicators */}
+			<div className="flex items-center justify-between mb-6">
+				<h3 className="text-lg font-semibold text-slate-900 dark:text-white">
+					Connection Status
+				</h3>
+				<div className="flex items-center space-x-4">
+					<div className="flex items-center space-x-2">
+						<div
+							className={`w-3 h-3 rounded-full ${connectionStatus === "connected" ? "bg-green-500" : connectionStatus === "connecting" ? "bg-yellow-500" : "bg-red-500"}`}
+						/>
+						<span
+							className={`px-2 py-1 rounded-full text-xs font-medium ${getStatusColor(connectionStatus)}`}
+						>
+							{connectionStatus}
+						</span>
+					</div>
+					<div className="flex items-center space-x-2">
+						<div
+							className={`w-3 h-3 rounded-full ${syncStatus === "synced" ? "bg-green-500" : "bg-orange-500 animate-pulse"}`}
+						/>
+						<span
+							className={`px-2 py-1 rounded-full text-xs font-medium ${syncStatus === "synced" ? "bg-green-100 text-green-800 dark:bg-green-900/20 dark:text-green-400" : "bg-orange-100 text-orange-800 dark:bg-orange-900/20 dark:text-orange-400"}`}
+						>
+							{syncStatus}
+						</span>
+					</div>
+					<div className="flex items-center space-x-2">
+						<div
+							className={`w-3 h-3 rounded-full ${unsyncedChanges >= UNSYNCED_THRESHOLD ? "bg-red-500 animate-pulse" : "bg-orange-500 animate-pulse"}`}
+						/>
+						<span
+							className={`px-2 py-1 rounded-full text-xs font-medium ${unsyncedChanges >= UNSYNCED_THRESHOLD ? "bg-red-100 text-red-800 dark:bg-red-900/20 dark:text-red-400" : "bg-orange-100 text-orange-800 dark:bg-orange-900/20 dark:text-orange-400"}`}
+						>
+							{unsyncedChanges} unsynced
+						</span>
+					</div>
+				</div>
+			</div>
+
+			{/* Control buttons */}
+			<div className="grid grid-cols-2 gap-6">
+				<div className="space-y-3">
+					<h4 className="text-sm font-medium text-slate-700 dark:text-slate-300">
+						WebSocket Controls
+					</h4>
+					<div className="flex space-x-2">
+						<button
+							className="flex-1 px-3 py-2 bg-red-500 hover:bg-red-600 text-white text-sm font-medium rounded-lg transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
+							onClick={() =>
+								provider.configuration.websocketProvider.disconnect()
+							}
+							disabled={connectionStatus === "disconnected"}
+						>
+							Disconnect
+						</button>
+						<button
+							className="flex-1 px-3 py-2 bg-green-500 hover:bg-green-600 text-white text-sm font-medium rounded-lg transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
+							onClick={() =>
+								provider.configuration.websocketProvider.connect()
+							}
+							disabled={connectionStatus === "connected"}
+						>
+							Connect
+						</button>
+					</div>
+				</div>
+
+				<div className="space-y-3">
+					<h4 className="text-sm font-medium text-slate-700 dark:text-slate-300">
+						Provider Controls
+					</h4>
+					<div className="flex space-x-2">
+						<button
+							className="flex-1 px-3 py-2 bg-orange-500 hover:bg-orange-600 text-white text-sm font-medium rounded-lg transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
+							onClick={() => provider.detach()}
+						>
+							Detach
+						</button>
+						<button
+							className="flex-1 px-3 py-2 bg-blue-500 hover:bg-blue-600 text-white text-sm font-medium rounded-lg transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
+							onClick={() => provider.attach()}
+						>
+							Attach
+						</button>
+					</div>
+				</div>
+			</div>
+		</div>
+	);
+};
+
+export default CollaborationStatus;

playground/frontend/app/react-provider/[slug]/CollaborativeEditor.tsx

@@ -0,0 +1,56 @@
+"use client";
+
+import { useHocuspocusProvider } from "@hocuspocus/provider-react";
+import { Collaboration } from "@tiptap/extension-collaboration";
+import { CollaborationCaret } from "@tiptap/extension-collaboration-caret";
+import { EditorContent, useEditor } from "@tiptap/react";
+import { StarterKit } from "@tiptap/starter-kit";
+import { useEffect, useRef } from "react";
+import * as Y from "yjs";
+
+const initialContent = [
+	1, 3, 223, 175, 255, 141, 2, 0, 7, 1, 7, 100, 101, 102, 97, 117, 108, 116, 3,
+	9, 112, 97, 114, 97, 103, 114, 97, 112, 104, 7, 0, 223, 175, 255, 141, 2, 0,
+	6, 4, 0, 223, 175, 255, 141, 2, 1, 17, 72, 101, 108, 108, 111, 32, 87, 111,
+	114, 108, 100, 33, 32, 240, 159, 140, 142, 0,
+];
+
+const CollaborativeEditor = () => {
+	const provider = useHocuspocusProvider();
+	const initializedRef = useRef(false);
+
+	useEffect(() => {
+		if (!initializedRef.current) {
+			Y.applyUpdate(provider.document, Uint8Array.from(initialContent));
+			initializedRef.current = true;
+		}
+	}, [provider.document]);
+
+	const editor = useEditor(
+		{
+			extensions: [
+				StarterKit.configure({
+					undoRedo: false,
+				}),
+				Collaboration.configure({
+					document: provider.document,
+				}),
+				CollaborationCaret.configure({
+					provider,
+				}),
+			],
+			immediatelyRender: false,
+			editorProps: {
+				attributes: {
+					class:
+						"prose prose-lg max-w-none focus:outline-none min-h-[500px] p-8 bg-white/50 dark:bg-slate-900/50 rounded-xl border border-slate-200 dark:border-slate-700 shadow-sm",
+				},
+			},
+		},
+		[provider.document],
+	);
+
+	return <EditorContent editor={editor} />;
+};
+
+export default CollaborativeEditor;

playground/frontend/app/react-provider/[slug]/ConnectedUsers.tsx

@@ -0,0 +1,56 @@
+"use client";
+
+import { useHocuspocusAwareness } from "@hocuspocus/provider-react";
+import { useEffect, useState } from "react";
+
+const colors = [
+	"bg-blue-500",
+	"bg-green-500",
+	"bg-purple-500",
+	"bg-pink-500",
+	"bg-amber-500",
+	"bg-cyan-500",
+	"bg-rose-500",
+	"bg-indigo-500",
+];
+
+const ConnectedUsers = () => {
+	const users = useHocuspocusAwareness();
+	const [mounted, setMounted] = useState(false);
+
+	useEffect(() => {
+		setMounted(true);
+	}, []);
+
+	return (
+		<div className="bg-white/60 dark:bg-slate-900/60 backdrop-blur-sm rounded-xl border border-slate-200 dark:border-slate-700 px-4 py-3">
+			<div className="flex items-center space-x-3">
+				<span className="text-xs font-medium text-slate-500 dark:text-slate-400 uppercase tracking-wider">
+					Users
+				</span>
+				{mounted && (
+					<>
+						<div className="flex -space-x-2">
+							{users.map((user, i) => (
+								<div
+									key={user.clientId}
+									className={`w-7 h-7 rounded-full ${colors[i % colors.length]} border-2 border-white dark:border-slate-900 flex items-center justify-center`}
+									title={`Client ${user.clientId}`}
+								>
+									<span className="text-white text-xs font-bold">
+										{String(user.clientId).slice(-2)}
+									</span>
+								</div>
+							))}
+						</div>
+						<span className="text-xs text-slate-500 dark:text-slate-400">
+							{users.length} connected
+						</span>
+					</>
+				)}
+			</div>
+		</div>
+	);
+};
+
+export default ConnectedUsers;

playground/frontend/app/react-provider/[slug]/page.tsx

@@ -0,0 +1,10 @@
+import ArticleEditor from "./ArticleEditor";
+
+export default async function Page(props: {
+	params: Promise<{ slug: string }>;
+}) {
+	const params = await props.params;
+	const slug = params.slug;
+
+	return <ArticleEditor slug={slug} />;
+}

playground/frontend/app/react-provider/layout.tsx

@@ -0,0 +1,7 @@
+export default function Layout({
+	children,
+}: Readonly<{
+	children: React.ReactNode;
+}>) {
+	return children;
+}