@wakastellar/ui 3.3.3 → 3.5.0

package/src/components/editor/waka-collaborative-editor.tsx

@@ -0,0 +1,426 @@
+"use client"
+
+import * as React from "react"
+import { cn } from "../../utils/cn"
+import { Label } from "../label"
+import { Textarea } from "../textarea"
+import { Badge } from "../badge"
+import { Avatar, AvatarFallback } from "../avatar"
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type SlateNode = any
+
+/** Describes a remote user connected to the same document */
+export interface CollaborationUser {
+  /** Unique user ID (e.g., keycloak-id) */
+  id: string
+  /** Display name */
+  name: string
+  /** Cursor color (CSS color value) */
+  color: string
+  /** Optional avatar URL */
+  avatar?: string
+}
+
+/** Provider configuration for Yjs */
+export interface CollaborationProviderConfig {
+  /** Provider type */
+  type: "hocuspocus" | "webrtc"
+  /** Server URL (WebSocket) */
+  url: string
+  /** Room/document name (must be unique per document) */
+  roomName: string
+  /** Additional options */
+  options?: Record<string, unknown>
+}
+
+export interface WakaCollaborativeEditorProps {
+  /** Initial Slate content (used only if the Y.Doc is empty) */
+  value?: SlateNode[]
+  /** Change callback */
+  onChange?: (value: SlateNode[]) => void
+  /** Read-only mode */
+  readOnly?: boolean
+  /** Placeholder */
+  placeholder?: string
+  /** CSS class */
+  className?: string
+  /** Editor CSS class */
+  editorClassName?: string
+  /** Minimum height in px */
+  minHeight?: number
+  /** Label */
+  label?: string
+  /** Description */
+  description?: string
+  /** Error */
+  error?: string
+  /** Unique document ID for the collaboration room */
+  documentId: string
+  /** Current user info for cursor display */
+  currentUser: CollaborationUser
+  /** Collaboration provider configurations */
+  providers: CollaborationProviderConfig[]
+  /**
+   * Maximum number of concurrent participants per room.
+   * Enforced at the WebRTC level. Default: 10.
+   */
+  maxParticipants?: number
+  /** Callback when remote users change. Receives the list of connected users. */
+  onUsersChange?: (users: CollaborationUser[]) => void
+  /** Show the connected users bar at the top */
+  showUsersBar?: boolean
+  /** Extra Plate plugins */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  extraPlugins?: any[]
+  /** Ref to editor instance */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  editorRef?: React.MutableRefObject<any>
+}
+
+// ─── Component ───────────────────────────────────────────────────────────────
+
+/**
+ * WakaCollaborativeEditor -- Real-time collaborative editor using Yjs.
+ *
+ * Wraps Plate.js with `@platejs/yjs` for real-time multi-user editing.
+ * Supports Hocuspocus (WebSocket) and WebRTC providers.
+ * Displays remote cursors with user names and colors.
+ *
+ * Multi-tenant aware: the `documentId` scopes the collaboration room,
+ * and can include tenant prefixes (e.g., `partner-123/spec-456`).
+ *
+ * Requires peer dependencies: `@platejs/yjs`, `yjs`, `y-websocket` or provider libs.
+ *
+ * @example
+ * ```tsx
+ * <WakaCollaborativeEditor
+ *   documentId={`spec-${specId}`}
+ *   currentUser={{ id: user.keycloakId, name: user.name, color: "#3b82f6" }}
+ *   providers={[
+ *     { type: "hocuspocus", url: "wss://collab.wakastart.app", roomName: `spec-${specId}` }
+ *   ]}
+ *   showUsersBar
+ *   value={initialContent}
+ *   onChange={handleChange}
+ * />
+ * ```
+ */
+export const WakaCollaborativeEditor = React.forwardRef<HTMLDivElement, WakaCollaborativeEditorProps>(
+  (
+    {
+      value,
+      onChange,
+      readOnly = false,
+      placeholder = "Editez ensemble en temps reel...",
+      className,
+      editorClassName,
+      minHeight = 400,
+      label,
+      description,
+      error,
+      documentId,
+      currentUser,
+      providers,
+      maxParticipants = 10,
+      onUsersChange,
+      showUsersBar = true,
+      extraPlugins,
+      editorRef,
+    },
+    ref
+  ) => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const [bundle, setBundle] = React.useState<any>(null)
+    const [loadError, setLoadError] = React.useState(false)
+    const [connectedUsers, setConnectedUsers] = React.useState<CollaborationUser[]>([currentUser])
+
+    const configRef = React.useRef({ documentId, currentUser, providers, maxParticipants })
+    configRef.current = { documentId, currentUser, providers, maxParticipants }
+
+    // ── Load Plate + Yjs ──────────────────────────────────────────────────
+    React.useEffect(() => {
+      let cancelled = false
+
+      const load = async () => {
+        try {
+          const cfg = configRef.current
+
+          const [plateReact, basicNodes, tableModule, layoutModule, calloutModule, linkModule, yjsModule] =
+            await Promise.all([
+              import("platejs/react"),
+              import("@platejs/basic-nodes/react"),
+              import("@platejs/table/react"),
+              import("@platejs/layout/react"),
+              import("@platejs/callout/react"),
+              import("@platejs/link/react"),
+              import("@platejs/yjs/react"),
+            ])
+
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const plugins: any[] = [
+            basicNodes.BoldPlugin, basicNodes.ItalicPlugin, basicNodes.UnderlinePlugin,
+            basicNodes.StrikethroughPlugin, basicNodes.CodePlugin, basicNodes.HighlightPlugin,
+            basicNodes.H1Plugin, basicNodes.H2Plugin, basicNodes.H3Plugin,
+            basicNodes.H4Plugin, basicNodes.BlockquotePlugin,
+            tableModule.TablePlugin, tableModule.TableRowPlugin,
+            tableModule.TableCellPlugin, tableModule.TableCellHeaderPlugin,
+            layoutModule.ColumnPlugin, layoutModule.ColumnItemPlugin,
+            calloutModule.CalloutPlugin,
+            linkModule.LinkPlugin.configure({
+              options: { allowedSchemes: ["http", "https", "mailto", "tel"] },
+            }),
+          ]
+
+          // Build Yjs provider configs
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const yjsProviders: any[] = cfg.providers.map((p) => {
+            if (p.type === "hocuspocus") {
+              return {
+                type: "hocuspocus",
+                options: { name: p.roomName, url: p.url, ...p.options },
+              }
+            }
+            return {
+              type: "webrtc",
+              options: {
+                roomName: p.roomName,
+                maxConns: cfg.maxParticipants - 1,
+                signaling: [p.url],
+                ...p.options,
+              },
+            }
+          })
+
+          plugins.push(
+            yjsModule.YjsPlugin.configure({
+              options: {
+                cursors: {
+                  data: {
+                    name: cfg.currentUser.name,
+                    color: cfg.currentUser.color,
+                  },
+                },
+                providers: yjsProviders,
+              },
+            }),
+          )
+
+          if (!cancelled) {
+            setBundle({
+              Plate: plateReact.Plate,
+              PlateContent: plateReact.PlateContent,
+              usePlateEditor: plateReact.usePlateEditor,
+              YjsPlugin: yjsModule.YjsPlugin,
+              plugins,
+            })
+          }
+        } catch (err) {
+          console.error("[WakaCollaborativeEditor] Failed to load:", err)
+          if (!cancelled) setLoadError(true)
+        }
+      }
+
+      load()
+      return () => { cancelled = true }
+    }, [])
+
+    // Notify parent of user changes
+    React.useEffect(() => {
+      onUsersChange?.(connectedUsers)
+    }, [connectedUsers, onUsersChange])
+
+    // ── Render ────────────────────────────────────────────────────────────
+    if (bundle) {
+      return (
+        <CollabEditorInner
+          ref={ref}
+          bundle={bundle}
+          value={value}
+          onChange={onChange}
+          readOnly={readOnly}
+          placeholder={placeholder}
+          className={className}
+          editorClassName={editorClassName}
+          minHeight={minHeight}
+          label={label}
+          description={description}
+          error={error}
+          documentId={documentId}
+          currentUser={currentUser}
+          showUsersBar={showUsersBar}
+          connectedUsers={connectedUsers}
+          setConnectedUsers={setConnectedUsers}
+          extraPlugins={extraPlugins}
+          editorRef={editorRef}
+        />
+      )
+    }
+
+    return (
+      <div ref={ref} className={cn("space-y-1.5", className)}>
+        {label && <Label>{label}</Label>}
+        {description && <p className="text-sm text-muted-foreground">{description}</p>}
+        <div className="relative">
+          <Textarea placeholder={placeholder} disabled style={{ minHeight }} />
+          <div className="absolute inset-0 flex items-center justify-center bg-background/50 rounded-lg">
+            <span className="text-sm text-muted-foreground animate-pulse">
+              {loadError
+                ? "Erreur de chargement (@platejs/yjs requis)"
+                : "Connexion a la session collaborative..."}
+            </span>
+          </div>
+        </div>
+        {error && <p className="text-sm text-destructive">{error}</p>}
+      </div>
+    )
+  }
+)
+
+WakaCollaborativeEditor.displayName = "WakaCollaborativeEditor"
+
+// ─── Inner component ────────────────────────────────────────────────────────
+
+interface CollabEditorInnerProps {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  bundle: any
+  value?: SlateNode[]
+  onChange?: (value: SlateNode[]) => void
+  readOnly?: boolean
+  placeholder?: string
+  className?: string
+  editorClassName?: string
+  minHeight?: number
+  label?: string
+  description?: string
+  error?: string
+  documentId: string
+  currentUser: CollaborationUser
+  showUsersBar?: boolean
+  connectedUsers: CollaborationUser[]
+  setConnectedUsers: React.Dispatch<React.SetStateAction<CollaborationUser[]>>
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  extraPlugins?: any[]
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  editorRef?: React.MutableRefObject<any>
+}
+
+const CollabEditorInner = React.forwardRef<HTMLDivElement, CollabEditorInnerProps>(
+  (
+    {
+      bundle: { Plate, PlateContent, usePlateEditor, YjsPlugin, plugins },
+      value,
+      onChange,
+      readOnly,
+      placeholder,
+      className,
+      editorClassName,
+      minHeight,
+      label,
+      description,
+      error,
+      documentId,
+      showUsersBar,
+      connectedUsers,
+      extraPlugins,
+      editorRef,
+    },
+    ref
+  ) => {
+    const allPlugins = React.useMemo(
+      () => [...plugins, ...(extraPlugins ?? [])],
+      [plugins, extraPlugins]
+    )
+
+    const editor = usePlateEditor(
+      {
+        plugins: allPlugins,
+        skipInitialization: true,
+      },
+      [documentId]
+    )
+
+    // Initialize Yjs document
+    React.useEffect(() => {
+      try {
+        editor.getApi(YjsPlugin).yjs.init({
+          id: documentId,
+          autoSelect: "end",
+          value: value ?? [{ type: "p", children: [{ text: "" }] }],
+        })
+      } catch {
+        // YjsPlugin might not be available
+      }
+
+      return () => {
+        try {
+          editor.getApi(YjsPlugin).yjs.destroy()
+        } catch { /* */ }
+      }
+    }, [editor, documentId, YjsPlugin, value])
+
+    React.useEffect(() => {
+      if (editorRef) editorRef.current = editor
+    }, [editor, editorRef])
+
+    return (
+      <div ref={ref} className={cn("space-y-1.5", className)}>
+        {label && <Label>{label}</Label>}
+        {description && <p className="text-sm text-muted-foreground">{description}</p>}
+
+        <Plate
+          editor={editor}
+          onChange={onChange ? ({ value: v }: { value: SlateNode[] }) => onChange(v) : undefined}
+          readOnly={readOnly}
+        >
+          <div className={cn(
+            "border rounded-lg overflow-hidden",
+            error && "border-destructive",
+          )}>
+            {/* Connected users bar */}
+            {showUsersBar && (
+              <div className="flex items-center gap-2 px-3 py-1.5 border-b bg-muted/30">
+                <span className="text-xs text-muted-foreground">En ligne :</span>
+                <div className="flex items-center -space-x-1.5">
+                  {connectedUsers.map((user) => (
+                    <Avatar key={user.id} className="h-6 w-6 border-2 border-background">
+                      <AvatarFallback
+                        className="text-[10px] text-white font-bold"
+                        style={{ backgroundColor: user.color }}
+                      >
+                        {user.name.slice(0, 2).toUpperCase()}
+                      </AvatarFallback>
+                    </Avatar>
+                  ))}
+                </div>
+                <Badge variant="secondary" className="text-[10px] h-5">
+                  {connectedUsers.length} connecte{connectedUsers.length > 1 ? "s" : ""}
+                </Badge>
+              </div>
+            )}
+
+            {/* Editor content */}
+            <div style={{ minHeight }}>
+              <PlateContent
+                placeholder={placeholder}
+                readOnly={readOnly}
+                className={cn(
+                  "prose prose-sm max-w-none p-4",
+                  "focus-within:outline-none",
+                  "[&_[data-slate-editor]]:outline-none [&_[data-slate-editor]]:min-h-[inherit]",
+                  editorClassName,
+                )}
+              />
+            </div>
+          </div>
+        </Plate>
+
+        {error && <p className="text-sm text-destructive">{error}</p>}
+      </div>
+    )
+  }
+)
+
+CollabEditorInner.displayName = "CollabEditorInner"