@tangle-network/ui 1.0.0

package/src/editor/editor-provider.tsx

@@ -0,0 +1,428 @@
+"use client";
+
+import { HocuspocusProvider } from "@hocuspocus/provider";
+import {
+  createContext,
+  type ReactNode,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import * as Y from "yjs";
+
+/**
+ * Connection state for the Hocuspocus provider.
+ */
+export type ConnectionState =
+  | "disconnected"
+  | "connecting"
+  | "connected"
+  | "synced";
+
+/**
+ * Collaborator information from awareness.
+ */
+export interface Collaborator {
+  clientId: number;
+  user: {
+    name: string;
+    color: string;
+    userId?: string;
+  };
+}
+
+/**
+ * Editor context value exposed to children.
+ */
+export interface EditorContextValue {
+  /** The Y.Doc instance for collaboration */
+  doc: Y.Doc;
+  /** The Hocuspocus provider instance */
+  provider: HocuspocusProvider | null;
+  /** Current connection state */
+  connectionState: ConnectionState;
+  /** List of active collaborators */
+  collaborators: Collaborator[];
+  /** Whether the document is synced with the server */
+  isSynced: boolean;
+  /** Connect to the collaboration server */
+  connect: () => void;
+  /** Disconnect from the collaboration server */
+  disconnect: () => void;
+}
+
+const EditorContext = createContext<EditorContextValue | null>(null);
+
+/**
+ * User information for presence/awareness.
+ */
+export interface EditorUser {
+  name: string;
+  color?: string;
+  userId?: string;
+}
+
+export interface EditorTokenRefreshResult {
+  token: string;
+  expiresAt?: number;
+}
+
+/**
+ * Props for EditorProvider.
+ */
+export interface EditorProviderProps {
+  /** WebSocket URL for the Hocuspocus server */
+  websocketUrl: string;
+  /** Document name (e.g., "doc:my-document") */
+  documentName: string;
+  /** JWT token for authentication */
+  token: string;
+  /** Unix timestamp (seconds) when the current token expires */
+  tokenExpiresAt?: number;
+  /** Current user information for awareness */
+  user: EditorUser;
+  /** Auto-connect on mount (default: true) */
+  autoConnect?: boolean;
+  /** Reconnect on disconnect (default: true) */
+  autoReconnect?: boolean;
+  /** Max reconnect attempts (default: 5) */
+  maxReconnectAttempts?: number;
+  /** Callback when connection state changes */
+  onConnectionChange?: (state: ConnectionState) => void;
+  /** Callback when sync completes */
+  onSync?: () => void;
+  /** Callback on authentication error */
+  onAuthError?: (error: Error) => void;
+  /** Optional token refresh callback used before reconnect/auth retry */
+  onRefreshToken?: () => Promise<EditorTokenRefreshResult | string>;
+  /** Children components */
+  children: ReactNode;
+}
+
+/**
+ * Generate a random color for user presence.
+ */
+function generateUserColor(): string {
+  const colors = [
+    "#FF6B6B", // Red
+    "#4ECDC4", // Teal
+    "#45B7D1", // Blue
+    "#96CEB4", // Green
+    "#FFEAA7", // Yellow
+    "#DDA0DD", // Plum
+    "#98D8C8", // Mint
+    "#F7DC6F", // Gold
+    "#BB8FCE", // Purple
+    "#85C1E9", // Sky
+  ];
+  return colors[Math.floor(Math.random() * colors.length)];
+}
+
+/**
+ * EditorProvider wraps children with Hocuspocus collaboration context.
+ * Manages WebSocket connection, Y.Doc, and awareness state.
+ */
+export function EditorProvider({
+  websocketUrl,
+  documentName,
+  token,
+  tokenExpiresAt,
+  user,
+  autoConnect = true,
+  autoReconnect = true,
+  maxReconnectAttempts = 5,
+  onConnectionChange,
+  onSync,
+  onAuthError,
+  onRefreshToken,
+  children,
+}: EditorProviderProps) {
+  const [connectionState, setConnectionState] =
+    useState<ConnectionState>("disconnected");
+  const [collaborators, setCollaborators] = useState<Collaborator[]>([]);
+  const [isSynced, setIsSynced] = useState(false);
+
+  // Use refs to avoid recreating provider on every render
+  const docRef = useRef<Y.Doc | null>(null);
+  const providerRef = useRef<HocuspocusProvider | null>(null);
+  const reconnectAttemptsRef = useRef(0);
+  const tokenRef = useRef(token);
+  const tokenExpiryRef = useRef<number | undefined>(tokenExpiresAt);
+  const refreshPromiseRef = useRef<Promise<string | null> | null>(null);
+  const refreshTimerRef = useRef<number | null>(null);
+
+  tokenRef.current = token;
+  tokenExpiryRef.current = tokenExpiresAt;
+
+  // Initialize Y.Doc once
+  if (!docRef.current) {
+    docRef.current = new Y.Doc();
+  }
+  const doc = docRef.current;
+
+  // User color (generate once per session)
+  const userColor = useMemo(
+    () => user.color ?? generateUserColor(),
+    [user.color],
+  );
+
+  // Update connection state and notify callback
+  const updateConnectionState = useCallback(
+    (state: ConnectionState) => {
+      setConnectionState(state);
+      onConnectionChange?.(state);
+    },
+    [onConnectionChange],
+  );
+
+  // Update collaborators from awareness
+  const updateCollaborators = useCallback(
+    (awareness: HocuspocusProvider["awareness"]) => {
+      if (!awareness) return;
+
+      const states = awareness.getStates();
+      const collabs: Collaborator[] = [];
+
+      states.forEach((state: Record<string, unknown>, clientId: number) => {
+        // Skip our own client
+        if (clientId === awareness.clientID) return;
+
+        if (state.user) {
+          collabs.push({
+            clientId,
+            user: state.user as Collaborator["user"],
+          });
+        }
+      });
+
+      setCollaborators(collabs);
+    },
+    [],
+  );
+
+  const clearRefreshTimer = useCallback(() => {
+    if (refreshTimerRef.current != null) {
+      window.clearTimeout(refreshTimerRef.current);
+      refreshTimerRef.current = null;
+    }
+  }, []);
+
+  const refreshToken = useCallback(async (): Promise<string | null> => {
+    if (!onRefreshToken) {
+      return null;
+    }
+
+    if (refreshPromiseRef.current) {
+      return refreshPromiseRef.current;
+    }
+
+    const refreshPromise = (async () => {
+      const next = await onRefreshToken();
+      const resolvedToken = typeof next === "string" ? next : next.token;
+      const resolvedExpiry =
+        typeof next === "string" ? undefined : next.expiresAt;
+
+      tokenRef.current = resolvedToken;
+      tokenExpiryRef.current = resolvedExpiry;
+      return resolvedToken;
+    })()
+      .catch((error) => {
+        onAuthError?.(
+          error instanceof Error ? error : new Error(String(error)),
+        );
+        return null;
+      })
+      .finally(() => {
+        refreshPromiseRef.current = null;
+      });
+
+    refreshPromiseRef.current = refreshPromise;
+    return refreshPromise;
+  }, [onAuthError, onRefreshToken]);
+
+  const scheduleTokenRefresh = useCallback(() => {
+    clearRefreshTimer();
+
+    if (
+      !tokenExpiryRef.current ||
+      !onRefreshToken ||
+      typeof window === "undefined"
+    ) {
+      return;
+    }
+
+    const refreshAtMs = tokenExpiryRef.current * 1000 - 60_000;
+    const delay = refreshAtMs - Date.now();
+
+    if (delay <= 0) {
+      void refreshToken();
+      return;
+    }
+
+    refreshTimerRef.current = window.setTimeout(() => {
+      void refreshToken();
+    }, delay);
+  }, [clearRefreshTimer, onRefreshToken, refreshToken]);
+
+  // Connect to the collaboration server
+  const connect = useCallback(() => {
+    if (providerRef.current) {
+      providerRef.current.connect();
+      return;
+    }
+
+    updateConnectionState("connecting");
+
+    const provider = new HocuspocusProvider({
+      url: websocketUrl,
+      name: documentName,
+      document: doc,
+      token: async () => tokenRef.current,
+      connect: true,
+
+      onConnect: () => {
+        reconnectAttemptsRef.current = 0;
+        updateConnectionState("connected");
+        scheduleTokenRefresh();
+      },
+
+      onSynced: () => {
+        setIsSynced(true);
+        updateConnectionState("synced");
+        onSync?.();
+      },
+
+      onDisconnect: () => {
+        updateConnectionState("disconnected");
+        setIsSynced(false);
+        clearRefreshTimer();
+
+        // Auto-reconnect logic
+        if (
+          autoReconnect &&
+          reconnectAttemptsRef.current < maxReconnectAttempts
+        ) {
+          reconnectAttemptsRef.current += 1;
+          const delay = Math.min(
+            1000 * 2 ** reconnectAttemptsRef.current,
+            30000,
+          );
+          setTimeout(() => {
+            if (providerRef.current && !(providerRef.current as any).isConnected) {
+              providerRef.current.connect();
+            }
+          }, delay);
+        }
+      },
+
+      onAuthenticationFailed: ({ reason }: { reason?: string }) => {
+        const error = new Error(reason ?? "Authentication failed");
+        updateConnectionState("disconnected");
+        clearRefreshTimer();
+
+        if (onRefreshToken) {
+          void refreshToken().then((nextToken) => {
+            if (nextToken && providerRef.current) {
+              providerRef.current.connect();
+              return;
+            }
+
+            onAuthError?.(error);
+          });
+          return;
+        }
+
+        onAuthError?.(error);
+      },
+
+      onAwarenessUpdate: () => {
+        updateCollaborators(provider.awareness);
+      },
+    });
+
+    // Set local user awareness
+    provider.awareness?.setLocalStateField("user", {
+      name: user.name,
+      color: userColor,
+      userId: user.userId,
+    });
+
+    providerRef.current = provider;
+  }, [
+    websocketUrl,
+    documentName,
+    doc,
+    user.name,
+    user.userId,
+    userColor,
+    autoReconnect,
+    maxReconnectAttempts,
+    clearRefreshTimer,
+    updateConnectionState,
+    updateCollaborators,
+    onSync,
+    onAuthError,
+    onRefreshToken,
+    refreshToken,
+    scheduleTokenRefresh,
+  ]);
+
+  // Disconnect from the collaboration server
+  const disconnect = useCallback(() => {
+    if (providerRef.current) {
+      providerRef.current.disconnect();
+      updateConnectionState("disconnected");
+    }
+  }, [updateConnectionState]);
+
+  // Auto-connect on mount
+  useEffect(() => {
+    if (autoConnect) {
+      connect();
+    }
+
+    return () => {
+      // Cleanup on unmount
+      clearRefreshTimer();
+      if (providerRef.current) {
+        providerRef.current.destroy();
+        providerRef.current = null;
+      }
+    };
+  }, [autoConnect, clearRefreshTimer, connect]);
+
+  // Context value
+  const contextValue = useMemo<EditorContextValue>(
+    () => ({
+      doc,
+      provider: providerRef.current,
+      connectionState,
+      collaborators,
+      isSynced,
+      connect,
+      disconnect,
+    }),
+    [doc, connectionState, collaborators, isSynced, connect, disconnect],
+  );
+
+  return (
+    <EditorContext.Provider value={contextValue}>
+      {children}
+    </EditorContext.Provider>
+  );
+}
+
+/**
+ * Hook to access the editor context.
+ * Must be used within an EditorProvider.
+ */
+export function useEditorContext(): EditorContextValue {
+  const context = useContext(EditorContext);
+  if (!context) {
+    throw new Error("useEditorContext must be used within an EditorProvider");
+  }
+  return context;
+}

package/src/editor/editor-toolbar.tsx

@@ -0,0 +1,130 @@
+"use client";
+
+import { type Editor } from "@tiptap/react";
+import { cn } from "../lib/utils";
+
+/**
+ * Editor toolbar component.
+ * Provides basic formatting controls.
+ */
+export function EditorToolbar({
+  editor,
+  className,
+}: {
+  editor: Editor | null;
+  className?: string;
+}) {
+  if (!editor) {
+    return null;
+  }
+
+  const buttons = [
+    {
+      id: "bold",
+      label: "Bold",
+      action: () => editor.chain().focus().toggleBold().run(),
+      isActive: editor.isActive("bold"),
+      shortcut: "Ctrl+B",
+    },
+    {
+      id: "italic",
+      label: "Italic",
+      action: () => editor.chain().focus().toggleItalic().run(),
+      isActive: editor.isActive("italic"),
+      shortcut: "Ctrl+I",
+    },
+    {
+      id: "strike",
+      label: "Strike",
+      action: () => editor.chain().focus().toggleStrike().run(),
+      isActive: editor.isActive("strike"),
+      shortcut: "Ctrl+Shift+X",
+    },
+    {
+      id: "code",
+      label: "Code",
+      action: () => editor.chain().focus().toggleCode().run(),
+      isActive: editor.isActive("code"),
+      shortcut: "Ctrl+E",
+    },
+    { id: "sep-1", type: "separator" as const },
+    {
+      id: "h1",
+      label: "H1",
+      action: () => editor.chain().focus().toggleHeading({ level: 1 }).run(),
+      isActive: editor.isActive("heading", { level: 1 }),
+    },
+    {
+      id: "h2",
+      label: "H2",
+      action: () => editor.chain().focus().toggleHeading({ level: 2 }).run(),
+      isActive: editor.isActive("heading", { level: 2 }),
+    },
+    {
+      id: "h3",
+      label: "H3",
+      action: () => editor.chain().focus().toggleHeading({ level: 3 }).run(),
+      isActive: editor.isActive("heading", { level: 3 }),
+    },
+    { id: "sep-2", type: "separator" as const },
+    {
+      id: "bullet-list",
+      label: "Bullet List",
+      action: () => editor.chain().focus().toggleBulletList().run(),
+      isActive: editor.isActive("bulletList"),
+    },
+    {
+      id: "ordered-list",
+      label: "Ordered List",
+      action: () => editor.chain().focus().toggleOrderedList().run(),
+      isActive: editor.isActive("orderedList"),
+    },
+    {
+      id: "code-block",
+      label: "Code Block",
+      action: () => editor.chain().focus().toggleCodeBlock().run(),
+      isActive: editor.isActive("codeBlock"),
+    },
+    {
+      id: "blockquote",
+      label: "Blockquote",
+      action: () => editor.chain().focus().toggleBlockquote().run(),
+      isActive: editor.isActive("blockquote"),
+    },
+  ];
+
+  return (
+    <div
+      className={cn(
+        "flex items-center gap-1 border-border border-b bg-card p-2",
+        className,
+      )}
+    >
+      {buttons.map((button) => {
+        if ("type" in button && button.type === "separator") {
+          return <div key={button.id} className="mx-1 h-6 w-px bg-border" />;
+        }
+
+        return (
+          <button
+            key={button.id}
+            onClick={button.action}
+            type="button"
+            title={
+              "shortcut" in button
+                ? `${button.label} (${button.shortcut})`
+                : button.label
+            }
+            className={cn(
+              "rounded px-2 py-1 font-medium text-xs transition-colors",
+              "hover:bg-accent hover:text-accent-foreground",
+              button.isActive && "bg-accent text-accent-foreground",
+            )}
+          >
+            {button.label}
+          </button>
+        );
+      })}
+    </div>
+  );
+}

package/src/editor/index.ts

@@ -0,0 +1,31 @@
+export {
+  EditorProvider,
+  useEditorContext,
+  type EditorProviderProps,
+  type EditorContextValue,
+  type EditorTokenRefreshResult,
+  type EditorUser,
+  type ConnectionState,
+  type Collaborator,
+} from "./editor-provider";
+export {
+  TiptapEditor,
+  CollaboratorsList,
+  EditorToolbar,
+  type TiptapEditorProps,
+} from "./tiptap-editor";
+export {
+  DocumentEditorPane,
+  type DocumentEditorPaneProps,
+  type DocumentEditorMode,
+  type DocumentEditorBackend,
+  type DocumentEditorPaneCollaborationConfig,
+} from "./document-editor-pane";
+export {
+  useEditorConnection,
+  useCollaborators,
+  useCollaboratorPresence,
+  useYjsState,
+  useDocumentChanges,
+  useAwareness,
+} from "./use-editor";

package/src/editor/markdown-conversion.ts

@@ -0,0 +1,21 @@
+import { marked } from "marked";
+import TurndownService from "turndown";
+
+const turndown = new TurndownService({
+  bulletListMarker: "-",
+  codeBlockStyle: "fenced",
+  emDelimiter: "*",
+  headingStyle: "atx",
+});
+
+export function markdownToHtml(markdown: string) {
+  return String(marked.parse(markdown, { async: false, gfm: true }));
+}
+
+export function htmlToMarkdown(html: string) {
+  return turndown.turndown(html);
+}
+
+export function normalizeMarkdown(markdown: string) {
+  return markdown.replace(/\r\n/g, "\n").trimEnd();
+}