@tangle-network/ui 1.0.0

package/src/editor/markdown-document-editor.tsx

@@ -0,0 +1,137 @@
+"use client";
+
+import { type Editor, EditorContent, useEditor } from "@tiptap/react";
+import StarterKit from "@tiptap/starter-kit";
+import { useEffect, useMemo, useRef } from "react";
+import { cn } from "../lib/utils";
+import { EditorToolbar } from "./editor-toolbar";
+import {
+  htmlToMarkdown,
+  markdownToHtml,
+  normalizeMarkdown,
+} from "./markdown-conversion";
+
+export interface MarkdownDocumentEditorProps {
+  value?: string;
+  placeholder?: string;
+  readOnly?: boolean;
+  autoFocus?: boolean;
+  className?: string;
+  contentClassName?: string;
+  onChange?: (markdown: string, editor: Editor) => void;
+  onReady?: (editor: Editor) => void;
+}
+
+export function MarkdownDocumentEditor({
+  value = "",
+  placeholder = "Start writing...",
+  readOnly = false,
+  autoFocus = false,
+  className,
+  contentClassName,
+  onChange,
+  onReady,
+}: MarkdownDocumentEditorProps) {
+  const initialHtml = useMemo(() => markdownToHtml(value), []);
+  const lastAppliedMarkdownRef = useRef(normalizeMarkdown(value));
+
+  const editor = useEditor({
+    extensions: [
+      StarterKit.configure({
+        codeBlock: {
+          HTMLAttributes: {
+            class: "hljs",
+          },
+        },
+      }),
+    ],
+    content: initialHtml,
+    editable: !readOnly,
+    autofocus: autoFocus,
+    editorProps: {
+      attributes: {
+        class: cn(
+          "prose prose-sm sm:prose-base max-w-none focus:outline-none",
+          "prose-headings:text-foreground prose-p:text-foreground prose-li:text-foreground",
+          "prose-strong:text-foreground prose-code:text-foreground prose-pre:text-foreground",
+          contentClassName,
+        ),
+        "data-placeholder": placeholder,
+      },
+    },
+    onUpdate: ({ editor: currentEditor }) => {
+      const nextMarkdown = normalizeMarkdown(htmlToMarkdown(currentEditor.getHTML()));
+      lastAppliedMarkdownRef.current = nextMarkdown;
+      onChange?.(nextMarkdown, currentEditor);
+    },
+    onCreate: ({ editor: currentEditor }) => {
+      onReady?.(currentEditor);
+    },
+  });
+
+  useEffect(() => {
+    if (editor) {
+      editor.setEditable(!readOnly);
+    }
+  }, [editor, readOnly]);
+
+  useEffect(() => {
+    if (!editor) {
+      return;
+    }
+
+    const normalizedValue = normalizeMarkdown(value);
+    if (normalizedValue === lastAppliedMarkdownRef.current) {
+      return;
+    }
+
+    editor.commands.setContent(markdownToHtml(value), { emitUpdate: false });
+    lastAppliedMarkdownRef.current = normalizedValue;
+  }, [editor, value]);
+
+  return (
+    <div
+      className={cn(
+        "flex min-h-[14rem] w-full flex-col overflow-hidden rounded-lg border border-border bg-background",
+        className,
+      )}
+    >
+      <EditorToolbar
+        editor={editor}
+        className="border-border bg-card px-2 py-2"
+      />
+      <div className="min-h-0 flex-1 overflow-auto px-5 py-4">
+        <EditorContent editor={editor} />
+      </div>
+
+      <style>{`
+        .ProseMirror p.is-editor-empty:first-child::before {
+          content: attr(data-placeholder);
+          float: left;
+          color: hsl(var(--muted-foreground));
+          pointer-events: none;
+          height: 0;
+        }
+
+        .ProseMirror pre {
+          background: hsl(var(--muted));
+          border: 1px solid hsl(var(--border));
+          border-radius: 0.75rem;
+          padding: 0.875rem 1rem;
+          overflow-x: auto;
+        }
+
+        .ProseMirror code {
+          background: hsl(var(--muted));
+          border-radius: 0.35rem;
+          padding: 0.12rem 0.3rem;
+        }
+
+        .ProseMirror pre code {
+          background: transparent;
+          padding: 0;
+        }
+      `}</style>
+    </div>
+  );
+}

package/src/editor/tiptap-editor.tsx

@@ -0,0 +1,331 @@
+"use client";
+
+import type { AnyExtension } from "@tiptap/core";
+import Collaboration from "@tiptap/extension-collaboration";
+import CollaborationCaret from "@tiptap/extension-collaboration-caret";
+import { type Editor, EditorContent, useEditor } from "@tiptap/react";
+import StarterKit from "@tiptap/starter-kit";
+import { useEffect, useMemo } from "react";
+import { cn } from "../lib/utils";
+import { type Collaborator, useEditorContext } from "./editor-provider";
+
+/**
+ * Props for TiptapEditor component.
+ */
+export interface TiptapEditorProps {
+  /** Initial content for new documents (markdown string) */
+  initialContent?: string;
+  /** Placeholder text when editor is empty */
+  placeholder?: string;
+  /** Whether the editor is read-only */
+  readOnly?: boolean;
+  /** Whether to auto-focus on mount */
+  autoFocus?: boolean;
+  /** Custom className for the editor wrapper */
+  className?: string;
+  /** Custom className for the editor content area */
+  contentClassName?: string;
+  /** Callback when content changes */
+  onUpdate?: (editor: Editor) => void;
+  /** Callback when selection changes */
+  onSelectionUpdate?: (editor: Editor) => void;
+  /** Callback when editor is ready */
+  onReady?: (editor: Editor) => void;
+}
+
+/**
+ * Cursor colors with contrasting text.
+ */
+const cursorColors: Record<string, { background: string; text: string }> = {
+  "#FF6B6B": { background: "#FF6B6B", text: "#FFFFFF" },
+  "#4ECDC4": { background: "#4ECDC4", text: "#000000" },
+  "#45B7D1": { background: "#45B7D1", text: "#000000" },
+  "#96CEB4": { background: "#96CEB4", text: "#000000" },
+  "#FFEAA7": { background: "#FFEAA7", text: "#000000" },
+  "#DDA0DD": { background: "#DDA0DD", text: "#000000" },
+  "#98D8C8": { background: "#98D8C8", text: "#000000" },
+  "#F7DC6F": { background: "#F7DC6F", text: "#000000" },
+  "#BB8FCE": { background: "#BB8FCE", text: "#000000" },
+  "#85C1E9": { background: "#85C1E9", text: "#000000" },
+};
+
+/**
+ * Get cursor label colors based on user color.
+ */
+function getCursorColors(color: string) {
+  return cursorColors[color] ?? { background: color, text: "#FFFFFF" };
+}
+
+/**
+ * TiptapEditor - Collaborative markdown editor with Y.js sync.
+ * Must be used within an EditorProvider.
+ */
+export function TiptapEditor({
+  initialContent,
+  placeholder = "Start writing...",
+  readOnly = false,
+  autoFocus = false,
+  className,
+  contentClassName,
+  onUpdate,
+  onSelectionUpdate,
+  onReady,
+}: TiptapEditorProps) {
+  const { doc, provider, connectionState } = useEditorContext();
+
+  // Y.js fragment for the editor content
+  const fragment = useMemo(() => doc.getXmlFragment("prosemirror"), [doc]);
+
+  // Configure Tiptap extensions
+  const extensions = useMemo(() => {
+    const baseExtensions: AnyExtension[] = [
+      StarterKit.configure({
+        // Disable history - Y.js handles undo/redo
+        ...({ history: false } as any),
+        // Configure code block for syntax highlighting placeholder
+        codeBlock: {
+          HTMLAttributes: {
+            class: "hljs",
+          },
+        },
+      }),
+      Collaboration.configure({
+        fragment,
+      }),
+    ];
+
+    // Add collaboration cursor if provider is available
+    if (provider?.awareness) {
+      baseExtensions.push(
+        CollaborationCaret.configure({
+          provider,
+          user: provider.awareness.getLocalState()?.user ?? {
+            name: "Anonymous",
+            color: "#808080",
+          },
+          render: (user: { name: string; color: string }) => {
+            const { background, text } = getCursorColors(user.color);
+
+            const cursor = document.createElement("span");
+            cursor.className = "collaboration-cursor";
+            cursor.style.borderColor = background;
+
+            const label = document.createElement("span");
+            label.className = "collaboration-cursor-label";
+            label.style.backgroundColor = background;
+            label.style.color = text;
+            label.textContent = user.name;
+
+            cursor.appendChild(label);
+            return cursor;
+          },
+        }),
+      );
+    }
+
+    return baseExtensions;
+  }, [fragment, provider]);
+
+  // Initialize Tiptap editor
+  const editor = useEditor({
+    extensions,
+    editable: !readOnly,
+    autofocus: autoFocus,
+    editorProps: {
+      attributes: {
+        class: cn(
+          "prose prose-sm sm:prose-base dark:prose-invert max-w-none",
+          "focus:outline-none",
+          contentClassName,
+        ),
+        "data-placeholder": placeholder,
+      },
+    },
+    onUpdate: ({ editor: ed }) => {
+      onUpdate?.(ed);
+    },
+    onSelectionUpdate: ({ editor: ed }) => {
+      onSelectionUpdate?.(ed);
+    },
+    onCreate: ({ editor: ed }) => {
+      onReady?.(ed);
+    },
+  });
+
+  // Update editable state when readOnly changes
+  useEffect(() => {
+    if (editor) {
+      editor.setEditable(!readOnly);
+    }
+  }, [editor, readOnly]);
+
+  // Handle initial content (only for new documents)
+  useEffect(() => {
+    if (
+      editor &&
+      initialContent &&
+      connectionState === "synced" &&
+      editor.isEmpty
+    ) {
+      editor.commands.setContent(initialContent);
+    }
+  }, [editor, initialContent, connectionState]);
+
+  return (
+    <div
+      className={cn(
+        "relative min-h-[200px] w-full rounded-lg border border-border",
+        "bg-background",
+        className,
+      )}
+    >
+      {/* Connection status indicator */}
+      <div className="absolute top-2 right-2 z-10">
+        <ConnectionIndicator state={connectionState} />
+      </div>
+
+      {/* Editor content */}
+      <div className="p-4 pt-10">
+        <EditorContent editor={editor} />
+      </div>
+
+      {/* Placeholder when empty */}
+      <style>{`
+        .ProseMirror p.is-editor-empty:first-child::before {
+          content: attr(data-placeholder);
+          float: left;
+          color: var(--muted-foreground, #999);
+          pointer-events: none;
+          height: 0;
+        }
+
+        .collaboration-cursor {
+          position: relative;
+          border-left: 2px solid;
+          margin-left: -1px;
+          margin-right: -1px;
+          pointer-events: none;
+          word-break: normal;
+        }
+
+        .collaboration-cursor-label {
+          position: absolute;
+          top: -1.4em;
+          left: -1px;
+          font-size: 12px;
+          font-style: normal;
+          font-weight: 600;
+          line-height: normal;
+          padding: 2px 6px;
+          border-radius: 4px 4px 4px 0;
+          white-space: nowrap;
+          user-select: none;
+        }
+
+        .ProseMirror pre {
+          background: var(--muted, #f4f4f5);
+          border-radius: 0.375rem;
+          padding: 0.75rem 1rem;
+          font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
+          font-size: 0.875rem;
+          overflow-x: auto;
+        }
+
+        .dark .ProseMirror pre {
+          background: var(--muted, #27272a);
+        }
+
+        .ProseMirror code {
+          background: var(--muted, #f4f4f5);
+          border-radius: 0.25rem;
+          padding: 0.125rem 0.25rem;
+          font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
+          font-size: 0.875em;
+        }
+
+        .dark .ProseMirror code {
+          background: var(--muted, #27272a);
+        }
+
+        .ProseMirror pre code {
+          background: transparent;
+          padding: 0;
+          font-size: inherit;
+        }
+      `}</style>
+    </div>
+  );
+}
+
+/**
+ * Connection status indicator component.
+ */
+function ConnectionIndicator({
+  state,
+}: {
+  state: "disconnected" | "connecting" | "connected" | "synced";
+}) {
+  const config = {
+    disconnected: {
+      color: "bg-red-500",
+      label: "Disconnected",
+    },
+    connecting: {
+      color: "bg-yellow-500 animate-pulse",
+      label: "Connecting...",
+    },
+    connected: {
+      color: "bg-blue-500",
+      label: "Connected",
+    },
+    synced: {
+      color: "bg-green-500",
+      label: "Synced",
+    },
+  }[state];
+
+  return (
+    <div className="flex items-center gap-1.5 text-muted-foreground text-xs">
+      <span className={cn("h-2 w-2 rounded-full", config.color)} />
+      <span>{config.label}</span>
+    </div>
+  );
+}
+
+/**
+ * Collaborators list component.
+ * Shows active users in the document.
+ */
+export function CollaboratorsList({
+  collaborators,
+  className,
+}: {
+  collaborators: Collaborator[];
+  className?: string;
+}) {
+  if (collaborators.length === 0) {
+    return null;
+  }
+
+  return (
+    <div className={cn("flex items-center gap-1", className)}>
+      {collaborators.slice(0, 5).map((collab) => (
+        <div
+          key={collab.clientId}
+          className="flex h-6 w-6 items-center justify-center rounded-full font-medium text-xs"
+          style={{ backgroundColor: collab.user.color }}
+          title={collab.user.name}
+        >
+          {collab.user.name.charAt(0).toUpperCase()}
+        </div>
+      ))}
+      {collaborators.length > 5 && (
+        <div className="flex h-6 w-6 items-center justify-center rounded-full bg-muted font-medium text-xs">
+          +{collaborators.length - 5}
+        </div>
+      )}
+    </div>
+  );
+}
+
+export { EditorToolbar } from "./editor-toolbar";

package/src/editor/use-editor.ts

@@ -0,0 +1,221 @@
+"use client";
+
+import type { HocuspocusProvider } from "@hocuspocus/provider";
+import { useCallback, useEffect, useState } from "react";
+import { type Collaborator, useEditorContext } from "./editor-provider";
+
+/**
+ * Hook to get the current connection state and helpers.
+ */
+export function useEditorConnection() {
+  const { connectionState, isSynced, connect, disconnect } = useEditorContext();
+
+  const isConnected =
+    connectionState === "connected" || connectionState === "synced";
+  const isConnecting = connectionState === "connecting";
+  const isDisconnected = connectionState === "disconnected";
+
+  return {
+    /** Current connection state string */
+    state: connectionState,
+    /** Whether connected to the server (connected or synced) */
+    isConnected,
+    /** Whether currently attempting to connect */
+    isConnecting,
+    /** Whether disconnected from the server */
+    isDisconnected,
+    /** Whether the document is synced with the server */
+    isSynced,
+    /** Connect to the collaboration server */
+    connect,
+    /** Disconnect from the collaboration server */
+    disconnect,
+  };
+}
+
+/**
+ * Hook to get the list of active collaborators.
+ */
+export function useCollaborators() {
+  const { collaborators } = useEditorContext();
+
+  const count = collaborators.length;
+  const hasOthers = count > 0;
+
+  return {
+    /** List of active collaborators (excluding self) */
+    collaborators,
+    /** Number of other collaborators */
+    count,
+    /** Whether there are other collaborators present */
+    hasOthers,
+  };
+}
+
+/**
+ * Hook to track a specific collaborator's presence.
+ */
+export function useCollaboratorPresence(userId: string): Collaborator | null {
+  const { collaborators } = useEditorContext();
+
+  return collaborators.find((c) => c.user.userId === userId) ?? null;
+}
+
+/**
+ * Hook to sync local state with the Y.Doc.
+ * Useful for persisting editor metadata.
+ */
+export function useYjsState<T>(
+  key: string,
+  initialValue: T,
+): [T, (value: T) => void] {
+  const { doc } = useEditorContext();
+  const [value, setLocalValue] = useState<T>(initialValue);
+
+  // Get or create the metadata map
+  const metaMap = doc.getMap<T>("metadata");
+
+  // Sync from Y.Map on mount and changes
+  useEffect(() => {
+    const updateValue = () => {
+      const stored = metaMap.get(key);
+      if (stored !== undefined) {
+        setLocalValue(stored);
+      }
+    };
+
+    updateValue();
+    metaMap.observe(updateValue);
+
+    return () => {
+      metaMap.unobserve(updateValue);
+    };
+  }, [metaMap, key]);
+
+  // Set value in Y.Map
+  const setValue = useCallback(
+    (newValue: T) => {
+      doc.transact(() => {
+        metaMap.set(key, newValue);
+      });
+    },
+    [doc, metaMap, key],
+  );
+
+  return [value, setValue];
+}
+
+/**
+ * Hook to track document changes.
+ * Returns true if there are unsaved changes since the last save.
+ */
+export function useDocumentChanges(onSave?: () => Promise<void>) {
+  const { doc } = useEditorContext();
+  const [isDirty, setIsDirty] = useState(false);
+  const [isSaving, setIsSaving] = useState(false);
+  const [lastSaved, setLastSaved] = useState<Date | null>(null);
+
+  // Track changes
+  useEffect(() => {
+    const handleUpdate = () => {
+      setIsDirty(true);
+    };
+
+    doc.on("update", handleUpdate);
+
+    return () => {
+      doc.off("update", handleUpdate);
+    };
+  }, [doc]);
+
+  // Save function
+  const save = useCallback(async () => {
+    if (!onSave || isSaving) return;
+
+    setIsSaving(true);
+    try {
+      await onSave();
+      setIsDirty(false);
+      setLastSaved(new Date());
+    } finally {
+      setIsSaving(false);
+    }
+  }, [onSave, isSaving]);
+
+  return {
+    /** Whether there are unsaved changes */
+    isDirty,
+    /** Whether save is in progress */
+    isSaving,
+    /** When the document was last saved */
+    lastSaved,
+    /** Save the document */
+    save,
+  };
+}
+
+/**
+ * Hook to get awareness state for presence features.
+ * Provides lower-level access to the Hocuspocus awareness.
+ */
+export function useAwareness(): {
+  localState: Record<string, unknown>;
+  setLocalState: (state: Record<string, unknown>) => void;
+  setLocalStateField: (field: string, value: unknown) => void;
+  awareness: HocuspocusProvider["awareness"] | undefined;
+} {
+  const { provider } = useEditorContext();
+  const [localState, setLocalStateValue] = useState<Record<string, unknown>>(
+    {},
+  );
+
+  const awareness = provider?.awareness;
+
+  // Sync local state
+  useEffect(() => {
+    if (!awareness) return;
+
+    const updateState = () => {
+      setLocalStateValue(awareness.getLocalState() ?? {});
+    };
+
+    updateState();
+    awareness.on("change", updateState);
+
+    return () => {
+      awareness.off("change", updateState);
+    };
+  }, [awareness]);
+
+  // Set local state
+  const setLocalState = useCallback(
+    (state: Record<string, unknown>) => {
+      if (!awareness) return;
+
+      // Merge with existing state
+      const current = awareness.getLocalState() ?? {};
+      awareness.setLocalState({ ...current, ...state });
+    },
+    [awareness],
+  );
+
+  // Set a single field
+  const setLocalStateField = useCallback(
+    (field: string, value: unknown) => {
+      if (!awareness) return;
+      awareness.setLocalStateField(field, value);
+    },
+    [awareness],
+  );
+
+  return {
+    /** Current local awareness state */
+    localState,
+    /** Set the entire local state (merges with existing) */
+    setLocalState,
+    /** Set a single field in the local state */
+    setLocalStateField,
+    /** The raw awareness instance */
+    awareness,
+  };
+}