feat: show remote cursors when in collaboration.

.changeset/odd-radios-smoke.md

@@ -0,0 +1,5 @@
+---
+'@udecode/plate-yjs': patch
+---
+
+Add a small component to show remote cursors.

apps/www/content/docs/collaboration.mdx

@@ -13,6 +13,8 @@ title: Collaboration
 ## Features
 
 - The yjs plugin enables support for collaboration using [slate-yjs](https://docs.slate-yjs.dev/) and [Hocuspocus](https://docs.slate-yjs.dev/walkthroughs/collaboration-hocuspocus).
+- By default remote cursors are rendered slightly faded and become solid on hover.
+- To customize, copy `YjsAboveEditable.tsx` and `Overlay.tsx` into your project and override the `options.render.aboveEditable` option to this plugin.
 
 </PackageInfo>
 
@@ -35,8 +37,8 @@ const editor = createPlateEditor({
     YjsPlugin.configure({
       options: {
         hocuspocusProviderOptions: {
-          url: "https://hocuspocus.test/hocuspocus",
-          name: "test",
+          url: 'https://hocuspocus.test/hocuspocus',
+          name: 'test',
         },
       },
     }),

packages/yjs/package.json

@@ -53,6 +53,8 @@
   "dependencies": {
     "@hocuspocus/provider": "^2.13.5",
     "@slate-yjs/core": "^1.0.2",
+    "@slate-yjs/react": "1.1.0",
+    "@udecode/cn": "workspace:^",
     "yjs": "^13.6.19"
   },
   "devDependencies": {

packages/yjs/src/react/Overlay.tsx

@@ -0,0 +1,123 @@
+// Lifted from slate-yjs https://github.com/BitPhinix/slate-yjs/blob/main/examples/frontend/src/pages/RemoteCursorOverlay/Overlay.tsx
+
+import React, {
+  type CSSProperties,
+  type PropsWithChildren,
+  useRef,
+  useState,
+} from 'react';
+
+import {
+  type CursorOverlayData,
+  useRemoteCursorOverlayPositions,
+} from '@slate-yjs/react';
+
+import { cn } from '@udecode/cn';
+
+export function addAlpha(hexColor: string, opacity: number): string {
+  const normalized = Math.round(Math.min(Math.max(opacity, 0), 1) * 255);
+
+  return hexColor + normalized.toString(16).toUpperCase();
+}
+
+export type CursorData = {
+  color: string;
+  name: string;
+};
+
+type CaretProps = Pick<CursorOverlayData<CursorData>, 'caretPosition' | 'data'>;
+const cursorOpacity = 0.7;
+const hoverOpacity = 1;
+
+function Caret({ caretPosition, data }: CaretProps) {
+  const [isHover, setIsHover] = useState(false);
+
+  const handleMouseEnter = () => {
+    setIsHover(true);
+  };
+  const handleMouseLeave = () => {
+    setIsHover(false);
+  };
+  const caretStyle: CSSProperties = {
+    ...caretPosition,
+    background: data?.color,
+    opacity: cursorOpacity,
+    transition: 'opacity 0.2s',
+  };
+  const caretStyleHover = { ...caretStyle, opacity: hoverOpacity };
+
+  const labelStyle: CSSProperties = {
+    background: data?.color,
+    opacity: cursorOpacity,
+    transform: 'translateY(-100%)',
+    transition: 'opacity 0.2s',
+  };
+  const labelStyleHover = { ...labelStyle, opacity: hoverOpacity };
+
+  return (
+    <div
+      className="absolute w-0.5"
+      style={isHover ? caretStyleHover : caretStyle}
+    >
+      <div
+        className="absolute top-0 whitespace-nowrap rounded rounded-bl-none px-1.5 py-0.5 text-xs text-white"
+        style={isHover ? labelStyleHover : labelStyle}
+        onMouseEnter={handleMouseEnter}
+        onMouseLeave={handleMouseLeave}
+      >
+        {data?.name}
+      </div>
+    </div>
+  );
+}
+
+function RemoteSelection({
+  caretPosition,
+  data,
+  selectionRects,
+}: CursorOverlayData<CursorData>) {
+  if (!data) {
+    return null;
+  }
+
+  const selectionStyle: CSSProperties = {
+    // Add a opacity to the background color
+    backgroundColor: addAlpha(data.color, 0.5),
+  };
+
+  return (
+    <React.Fragment>
+      {selectionRects.map((position, i) => (
+        <div
+          key={i}
+          className="pointer-events-none absolute"
+          style={{ ...selectionStyle, ...position }}
+        ></div>
+      ))}
+      {caretPosition && <Caret caretPosition={caretPosition} data={data} />}
+    </React.Fragment>
+  );
+}
+
+type RemoteCursorsProps = PropsWithChildren<{
+  className?: string;
+}>;
+
+export function RemoteCursorOverlay({
+  children,
+  className,
+}: RemoteCursorsProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [cursors] = useRemoteCursorOverlayPositions<CursorData>({
+    containerRef,
+  });
+
+  return (
+    <div ref={containerRef} className={cn('relative', className)}>
+      {children}
+      {cursors.map((cursor) => (
+        <RemoteSelection key={cursor.clientId} {...cursor} />
+      ))}
+    </div>
+  );
+}

packages/yjs/src/react/YjsAboveEditable.tsx

@@ -4,6 +4,7 @@ import { YjsEditor } from '@slate-yjs/core';
 import { useEditorPlugin } from '@udecode/plate-common/react';
 
 import { type YjsConfig, BaseYjsPlugin } from '../lib/BaseYjsPlugin';
+import { RemoteCursorOverlay } from './Overlay';
 
 export const YjsAboveEditable: React.FC<{
   children: React.ReactNode;
@@ -28,5 +29,5 @@ export const YjsAboveEditable: React.FC<{
 
   if (!isSynced) return null;
 
-  return <>{children}</>;
+  return <RemoteCursorOverlay>{children}</RemoteCursorOverlay>;
 };