@tangle-network/sandbox-ui 0.2.0

package/dist/editor.d.ts

@@ -0,0 +1,196 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { HocuspocusProvider } from '@hocuspocus/provider';
+import { ReactNode } from 'react';
+import * as Y from 'yjs';
+import { Editor } from '@tiptap/react';
+
+/**
+ * Connection state for the Hocuspocus provider.
+ */
+type ConnectionState = "disconnected" | "connecting" | "connected" | "synced";
+/**
+ * Collaborator information from awareness.
+ */
+interface Collaborator {
+    clientId: number;
+    user: {
+        name: string;
+        color: string;
+        userId?: string;
+    };
+}
+/**
+ * Editor context value exposed to children.
+ */
+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;
+}
+/**
+ * User information for presence/awareness.
+ */
+interface EditorUser {
+    name: string;
+    color?: string;
+    userId?: string;
+}
+/**
+ * Props for EditorProvider.
+ */
+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;
+    /** 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;
+    /** Children components */
+    children: ReactNode;
+}
+/**
+ * EditorProvider wraps children with Hocuspocus collaboration context.
+ * Manages WebSocket connection, Y.Doc, and awareness state.
+ */
+declare function EditorProvider({ websocketUrl, documentName, token, user, autoConnect, autoReconnect, maxReconnectAttempts, onConnectionChange, onSync, onAuthError, children, }: EditorProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access the editor context.
+ * Must be used within an EditorProvider.
+ */
+declare function useEditorContext(): EditorContextValue;
+
+/**
+ * Props for TiptapEditor component.
+ */
+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;
+}
+/**
+ * TiptapEditor - Collaborative markdown editor with Y.js sync.
+ * Must be used within an EditorProvider.
+ */
+declare function TiptapEditor({ initialContent, placeholder, readOnly, autoFocus, className, contentClassName, onUpdate, onSelectionUpdate, onReady, }: TiptapEditorProps): react_jsx_runtime.JSX.Element;
+/**
+ * Collaborators list component.
+ * Shows active users in the document.
+ */
+declare function CollaboratorsList({ collaborators, className, }: {
+    collaborators: Collaborator[];
+    className?: string;
+}): react_jsx_runtime.JSX.Element | null;
+/**
+ * Editor toolbar component.
+ * Provides basic formatting controls.
+ */
+declare function EditorToolbar({ editor, className, }: {
+    editor: Editor | null;
+    className?: string;
+}): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Hook to get the current connection state and helpers.
+ */
+declare function useEditorConnection(): {
+    /** Current connection state string */
+    state: ConnectionState;
+    /** Whether connected to the server (connected or synced) */
+    isConnected: boolean;
+    /** Whether currently attempting to connect */
+    isConnecting: boolean;
+    /** Whether disconnected from the server */
+    isDisconnected: boolean;
+    /** Whether the document is synced with the server */
+    isSynced: boolean;
+    /** Connect to the collaboration server */
+    connect: () => void;
+    /** Disconnect from the collaboration server */
+    disconnect: () => void;
+};
+/**
+ * Hook to get the list of active collaborators.
+ */
+declare function useCollaborators(): {
+    /** List of active collaborators (excluding self) */
+    collaborators: Collaborator[];
+    /** Number of other collaborators */
+    count: number;
+    /** Whether there are other collaborators present */
+    hasOthers: boolean;
+};
+/**
+ * Hook to track a specific collaborator's presence.
+ */
+declare function useCollaboratorPresence(userId: string): Collaborator | null;
+/**
+ * Hook to sync local state with the Y.Doc.
+ * Useful for persisting editor metadata.
+ */
+declare function useYjsState<T>(key: string, initialValue: T): [T, (value: T) => void];
+/**
+ * Hook to track document changes.
+ * Returns true if there are unsaved changes since the last save.
+ */
+declare function useDocumentChanges(onSave?: () => Promise<void>): {
+    /** Whether there are unsaved changes */
+    isDirty: boolean;
+    /** Whether save is in progress */
+    isSaving: boolean;
+    /** When the document was last saved */
+    lastSaved: Date | null;
+    /** Save the document */
+    save: () => Promise<void>;
+};
+/**
+ * Hook to get awareness state for presence features.
+ * Provides lower-level access to the Hocuspocus awareness.
+ */
+declare function useAwareness(): {
+    localState: Record<string, unknown>;
+    setLocalState: (state: Record<string, unknown>) => void;
+    setLocalStateField: (field: string, value: unknown) => void;
+    awareness: HocuspocusProvider["awareness"] | undefined;
+};
+
+export { type Collaborator, CollaboratorsList, type ConnectionState, type EditorContextValue, EditorProvider, type EditorProviderProps, EditorToolbar, type EditorUser, TiptapEditor, type TiptapEditorProps, useAwareness, useCollaboratorPresence, useCollaborators, useDocumentChanges, useEditorConnection, useEditorContext, useYjsState };