@rgby/collab-vue 1.0.1

package/src/useCollab.ts

@@ -0,0 +1,784 @@
+// @ts-nocheck
+import {
+    inject,
+    provide,
+    ref,
+    reactive,
+    computed,
+    onMounted,
+    onBeforeUnmount,
+    shallowRef,
+    watch,
+    markRaw,
+    nextTick,
+    type InjectionKey,
+    type Ref,
+    type ShallowRef,
+    type ComputedRef
+} from 'vue';
+import * as Y from 'yjs';
+import {
+    CollabClient,
+    CollabProvider,
+    type CollabClientOptions,
+    type CommentEvent,
+    type SessionData
+} from '@rgby/collab-core';
+import type { Editor, EditorOptions } from '@tiptap/core';
+
+// ----------------------------------------------------------------------
+// 1. Setup & Context
+// ----------------------------------------------------------------------
+
+export const CollabClientKey: InjectionKey<CollabClient> = Symbol.for('CollabClient');
+
+export function provideCollabClient(optionsOrInstance: CollabClientOptions | CollabClient) {
+    const client = optionsOrInstance instanceof CollabClient
+        ? optionsOrInstance
+        : new CollabClient(optionsOrInstance);
+
+    provide(CollabClientKey, client);
+    return client;
+}
+
+export function useCollabClient() {
+    const client = inject(CollabClientKey);
+    if (!client) throw new Error('CollabClient not provided. Call provideCollabClient() at the root.');
+    return client;
+}
+
+// ----------------------------------------------------------------------
+// 2. Core: useDocument
+// Manages the Y.Doc and Provider lifecycle
+// ----------------------------------------------------------------------
+
+export interface UseDocumentReturn {
+    doc: ShallowRef<Y.Doc>;
+    provider: ShallowRef<CollabProvider | null>;
+    status: Ref<'disconnected' | 'connecting' | 'connected'>;
+    synced: Ref<boolean>;
+    persistenceReady: Ref<boolean>;
+    undoManager: ShallowRef<Y.UndoManager | null>;
+    connect: () => void;
+    disconnect: () => void;
+    transact: (callback: (txn: Y.Transaction) => void) => void;
+    undo: () => void;
+    redo: () => void;
+    clearLocalData: () => Promise<void>;
+}
+
+export function useDocument(spaceId: string, documentId: string): UseDocumentReturn {
+    const client = useCollabClient();
+
+    // Y.Doc should not be deeply reactive in Vue, so we use shallowRef + markRaw
+    const doc = shallowRef<Y.Doc>(markRaw(new Y.Doc()));
+    const provider = shallowRef<CollabProvider | null>(null);
+    const undoManager = shallowRef<Y.UndoManager | null>(null);
+
+    const status = ref<'disconnected' | 'connecting' | 'connected'>('disconnected');
+    const synced = ref(false);
+    const persistenceReady = ref(false);
+
+    // Track scope for UndoManager to allow filtering (e.g., only undo text, not layout)
+    const trackedTypes = new Set<Y.AbstractType<any>>();
+
+    const connect = async () => {
+        if (provider.value) return;
+
+        const p = await client.getProvider(spaceId, documentId, {
+            document: doc.value
+        });
+
+        // Wait for persistence to load before syncing
+        await p.waitForPersistence();
+        persistenceReady.value = p.isPersistenceReady();
+
+        // Event Listeners
+        const updateStatus = () => { status.value = p.status; };
+        const updateSynced = () => { synced.value = p.synced; };
+
+        p.on('status', updateStatus);
+        p.on('synced', updateSynced);
+        p.on('disconnect', updateStatus);
+
+        provider.value = markRaw(p);
+
+        // Initialize UndoManager
+        // We defer this slightly to allow composables to register their types if needed
+        nextTick(() => {
+            undoManager.value = new Y.UndoManager(
+                trackedTypes.size > 0 ? Array.from(trackedTypes) : doc.value.share.values(),
+                {
+                    doc: doc.value,
+                    captureTransaction: (tr) => tr.origin !== undoManager.value
+                }
+            );
+        });
+    };
+
+    const disconnect = () => {
+        provider.value?.destroy();
+        provider.value = null;
+        undoManager.value?.destroy();
+        undoManager.value = null;
+        status.value = 'disconnected';
+        synced.value = false;
+    };
+
+    onMounted(connect);
+    onBeforeUnmount(() => {
+        disconnect();
+        doc.value.destroy();
+    });
+
+    const transact = (callback: (txn: Y.Transaction) => void) => {
+        doc.value.transact(callback, client);
+    };
+
+    const undo = () => undoManager.value?.undo();
+    const redo = () => undoManager.value?.redo();
+
+    const clearLocalData = async () => {
+        if (provider.value) {
+            await provider.value.clearLocalData();
+        }
+    };
+
+    return {
+        doc,
+        provider,
+        status,
+        synced,
+        persistenceReady,
+        undoManager,
+        connect,
+        disconnect,
+        transact,
+        undo,
+        redo,
+        clearLocalData
+    };
+}
+
+// ----------------------------------------------------------------------
+// 3. Factory: useSyncedMap
+// Reactive wrapper for Y.Map
+// ----------------------------------------------------------------------
+
+export function useSyncedMap<T = any>(doc: ShallowRef<Y.Doc>, mapName: string) {
+    // We use reactive so properties are directly accessible in templates
+    const state = reactive<Record<string, T>>({});
+
+    let _ymap: Y.Map<T> | null = null;
+
+    const init = (newDoc: Y.Doc) => {
+        if (_ymap) _ymap.unobserve(observer);
+
+        _ymap = newDoc.getMap<T>(mapName);
+
+        // Initial Hydration: clear old keys, set new ones
+        for (const key in state) delete state[key];
+        _ymap.forEach((value, key) => {
+            state[key] = value;
+        });
+
+        _ymap.observe(observer);
+    };
+
+    const observer = (event: Y.YMapEvent<T>) => {
+        event.keysChanged.forEach(key => {
+            if (_ymap!.has(key)) {
+                state[key] = _ymap!.get(key)!;
+            } else {
+                delete state[key];
+            }
+        });
+    };
+
+    watch(doc, (newDoc) => { if (newDoc) init(newDoc); }, { immediate: true });
+
+    onBeforeUnmount(() => {
+        if (_ymap) _ymap.unobserve(observer);
+    });
+
+    // Mutators
+    const set = (key: string, value: T) => _ymap?.set(key, value);
+    const remove = (key: string) => _ymap?.delete(key);
+    const clear = () => _ymap?.clear();
+    const get = (key: string) => _ymap?.get(key);
+
+    return {
+        data: state,
+        set,
+        remove,
+        clear,
+        get,
+        yMap: computed(() => _ymap)
+    };
+}
+
+// ----------------------------------------------------------------------
+// 4. Factory: useSyncedArray
+// Reactive wrapper for Y.Array using Deltas for fine-grained DOM updates
+// ----------------------------------------------------------------------
+
+export function useSyncedArray<T = any>(doc: ShallowRef<Y.Doc>, arrayName: string) {
+    const list = ref<T[]>([]) as Ref<T[]>;
+    let _yarray: Y.Array<T> | null = null;
+
+    const init = (newDoc: Y.Doc) => {
+        if (_yarray) _yarray.unobserve(observer);
+        _yarray = newDoc.getArray<T>(arrayName);
+
+        // Initial full copy
+        list.value = _yarray.toArray();
+        _yarray.observe(observer);
+    };
+
+    const observer = (event: Y.YArrayEvent<T>) => {
+        let index = 0;
+        event.delta.forEach((op) => {
+            if (op.retain) {
+                index += op.retain;
+            } else if (op.insert) {
+                const items = op.insert as T[];
+                list.value.splice(index, 0, ...items);
+                index += items.length;
+            } else if (op.delete) {
+                list.value.splice(index, op.delete);
+            }
+        });
+    };
+
+    watch(doc, (newDoc) => { if (newDoc) init(newDoc); }, { immediate: true });
+
+    onBeforeUnmount(() => {
+        if (_yarray) _yarray.unobserve(observer);
+    });
+
+    // Mutators
+    const push = (item: T) => _yarray?.push([item]);
+    const unshift = (item: T) => _yarray?.insert(0, [item]);
+    const insert = (index: number, items: T[]) => _yarray?.insert(index, items);
+    const deleteAt = (index: number, length = 1) => _yarray?.delete(index, length);
+
+    /**
+     * Replaces an item at index. Useful for updating object properties in an array
+     * since Y.Array doesn't track deep object property changes automatically.
+     */
+    const replace = (index: number, item: T) => {
+        if (!_yarray) return;
+        doc.value.transact(() => {
+            _yarray!.delete(index, 1);
+            _yarray!.insert(index, [item]);
+        });
+    };
+
+    return {
+        list,
+        push,
+        unshift,
+        insert,
+        deleteAt,
+        replace,
+        yArray: computed(() => _yarray)
+    };
+}
+
+// ----------------------------------------------------------------------
+// 5. Factory: useSyncedText
+// Reactive wrapper for Y.Text
+// ----------------------------------------------------------------------
+
+export function useSyncedText(doc: ShallowRef<Y.Doc>, textName: string) {
+    const text = ref('');
+    let _ytext: Y.Text | null = null;
+
+    const init = (newDoc: Y.Doc) => {
+        if (_ytext) _ytext.unobserve(observer);
+        _ytext = newDoc.getText(textName);
+        text.value = _ytext.toString();
+        _ytext.observe(observer);
+    };
+
+    const observer = (event: Y.YTextEvent) => {
+        // For strings, we usually just want the current value.
+        // Applying strict deltas to a Javascript string is O(N) anyway.
+        text.value = _ytext!.toString();
+    };
+
+    watch(doc, (newDoc) => { if (newDoc) init(newDoc); }, { immediate: true });
+
+    onBeforeUnmount(() => {
+        if (_ytext) _ytext.unobserve(observer);
+    });
+
+    const insert = (index: number, content: string, attributes?: Record<string, any>) =>
+        _ytext?.insert(index, content, attributes);
+
+    const deleteText = (index: number, length: number) =>
+        _ytext?.delete(index, length);
+
+    const format = (index: number, length: number, attributes: Record<string, any>) =>
+        _ytext?.format(index, length, attributes);
+
+    return {
+        text, // Read-only reactive string
+        insert,
+        delete: deleteText,
+        format,
+        yText: computed(() => _ytext)
+    };
+}
+
+// ----------------------------------------------------------------------
+// 6. Factory: useSyncedXml
+// Exposes Y.XmlFragment (for Tiptap/ProseMirror/Quill)
+// ----------------------------------------------------------------------
+
+export function useSyncedXml(doc: ShallowRef<Y.Doc>, xmlName: string) {
+    const _yxml = shallowRef<Y.XmlFragment | null>(null);
+
+    watch(doc, (newDoc) => {
+        if (newDoc) {
+            _yxml.value = newDoc.getXmlFragment(xmlName);
+        }
+    }, { immediate: true });
+
+    return {
+        yXml: _yxml // Pass this to Tiptap's Collaboration extension
+    };
+}
+
+// ----------------------------------------------------------------------
+// 7. Utility: useAwareness (Presence)
+// ----------------------------------------------------------------------
+
+export interface AwarenessUser {
+    clientId: number;
+    user: {
+        name: string;
+        color: string;
+        avatar?: string;
+    };
+    [key: string]: any;
+}
+
+export function useAwareness(provider: ShallowRef<CollabProvider | null>) {
+    const states = ref<AwarenessUser[]>([]);
+    const currentUser = ref<AwarenessUser | null>(null);
+
+    const update = () => {
+        if (!provider.value) return;
+        const awareness = provider.value.awareness;
+
+        states.value = Array.from(awareness.getStates().entries()).map(([id, state]) => ({
+            clientId: id,
+            ...state
+        })) as AwarenessUser[];
+
+        const local = awareness.getLocalState();
+        if (local) {
+            currentUser.value = { clientId: awareness.clientID, ...local } as AwarenessUser;
+        }
+    };
+
+    watch(provider, (p, oldP) => {
+        if (oldP) oldP.awareness.off('change', update);
+        if (p) {
+            p.awareness.on('change', update);
+            update(); // Initial fetch
+        }
+    }, { immediate: true });
+
+    const setLocalState = (state: Partial<AwarenessUser['user'] | any>) => {
+        if (!provider.value) return;
+        const current = provider.value.awareness.getLocalState() || {};
+        provider.value.awareness.setLocalState({ ...current, ...state });
+    };
+
+    return {
+        states,
+        currentUser,
+        setLocalState
+    };
+}
+
+// ----------------------------------------------------------------------
+// 8. Utility: useLiveComments
+// Hybrid REST + Websocket comments
+// ----------------------------------------------------------------------
+
+export function useLiveComments(
+    provider: ShallowRef<CollabProvider | null>,
+    spaceId: string,
+    documentId: string
+) {
+    const client = useCollabClient();
+    const threads = ref<any[]>([]); // Replace `any` with your CommentThread interface
+    const loading = ref(false);
+
+    const fetchComments = async () => {
+        loading.value = true;
+        try {
+            const res = await client.comments.list(spaceId, documentId);
+            threads.value = res.threads;
+        } catch (e) { console.error(e); }
+        finally { loading.value = false; }
+    };
+
+    watch(provider, (p) => {
+        if (!p) return;
+        // Watch for broadcasted events
+        const cleanup = p.onComment((event: CommentEvent) => {
+            // Simple strategy: refetch on any change from others
+            // (You can implement optimistic updates here for 'create' events)
+            if (['create', 'update', 'delete', 'resolve'].includes(event.action)) {
+                fetchComments();
+            }
+        });
+        fetchComments();
+        return () => cleanup();
+    }, { immediate: true });
+
+    const createComment = async (content: string, anchor?: any, parentId?: string) => {
+        const comment = await client.comments.create(spaceId, documentId, { content, anchor, parentId });
+        provider.value?.sendComment('create', comment);
+        // Optimistic local update
+        if (parentId) {
+            const thread = threads.value.find(t => t.id === parentId);
+            if (thread) thread.replies.push(comment);
+        } else {
+            threads.value.push({ ...comment, replies: [] });
+        }
+    };
+
+    return { threads, loading, createComment, refresh: fetchComments };
+}
+
+// ----------------------------------------------------------------------
+// 9. useAuth Composable
+// Reactive auth state (only works with managed auth mode)
+// ----------------------------------------------------------------------
+
+export interface UseAuthReturn {
+    session: ComputedRef<SessionData | null>;
+    user: ComputedRef<SessionData['user'] | null>;
+    isAuthenticated: ComputedRef<boolean>;
+    login: (email: string, password: string) => Promise<SessionData>;
+    signup: (email: string, password: string, name: string) => Promise<SessionData>;
+    logout: () => Promise<void>;
+}
+
+export function useAuth(providedClient?: CollabClient): UseAuthReturn {
+    const client = providedClient || useCollabClient();
+    const session = ref<SessionData | null>(null);
+
+    // Access private authManager
+    const authManager = (client as any).authManager;
+    if (!authManager) {
+        throw new Error('useAuth() requires CollabClient to be initialized with managed auth mode');
+    }
+
+    // Get initial session immediately
+    session.value = authManager.getSession();
+
+    // Subscribe to auth changes
+    const unsubscribe = authManager.subscribe((newSession: SessionData | null) => {
+        session.value = newSession;
+    });
+
+    onBeforeUnmount(() => {
+        unsubscribe();
+    });
+
+    return {
+        session: computed(() => session.value),
+        user: computed(() => session.value?.user ?? null),
+        isAuthenticated: computed(() => session.value !== null),
+        login: (email: string, password: string) => client.login(email, password),
+        signup: (email: string, password: string, name: string) => client.signup(email, password, name),
+        logout: () => client.logout()
+    };
+}
+
+// ----------------------------------------------------------------------
+// 10. useTiptapEditor Composable
+// Complete TipTap editor setup with Y.js + server extensions
+// ----------------------------------------------------------------------
+
+export interface UseTiptapEditorOptions {
+    spaceId: ComputedRef<string> | Ref<string> | string;
+    documentId: ComputedRef<string> | Ref<string> | string;
+    extensions?: any[];
+    editorOptions?: Partial<EditorOptions>;
+    user?: { name?: string; color?: string };
+    onReady?: (editor: Editor) => void;
+    autoConnect?: boolean;
+}
+
+export interface UseTiptapEditorReturn {
+    editor: ShallowRef<Editor | null>;
+    doc: ShallowRef<Y.Doc>;
+    provider: ShallowRef<CollabProvider | null>;
+    status: Ref<'disconnected' | 'connecting' | 'connected'>;
+    synced: Ref<boolean>;
+    persistenceReady: Ref<boolean>;
+    loading: Ref<boolean>;
+    error: Ref<string>;
+    connect: () => Promise<void>;
+    disconnect: () => void;
+    destroy: () => void;
+    clearLocalData: () => Promise<void>;
+}
+
+export function useTiptapEditor(options: UseTiptapEditorOptions): UseTiptapEditorReturn {
+    const client = useCollabClient();
+
+    // Normalize refs
+    const spaceId = computed(() => {
+        const val = options.spaceId;
+        return typeof val === 'string' ? val : val.value;
+    });
+    const documentId = computed(() => {
+        const val = options.documentId;
+        return typeof val === 'string' ? val : val.value;
+    });
+
+    const editor = shallowRef<Editor | null>(null);
+    const doc = shallowRef<Y.Doc>(markRaw(new Y.Doc()));
+    const provider = shallowRef<CollabProvider | null>(null);
+    const status = ref<'disconnected' | 'connecting' | 'connected'>('disconnected');
+    const synced = ref(false);
+    const persistenceReady = ref(false);
+    const loading = ref(false);
+    const error = ref('');
+
+    // Generate unique tab ID for multi-tab awareness
+    const generateTabId = () => {
+        return `tab-${Math.random().toString(36).substring(2, 9)}-${Date.now()}`;
+    };
+
+    // Random color for cursor
+    const generateColor = () => {
+        const colors = [
+            '#958DF1', '#F98181', '#FBBC88', '#FAF594', '#70CFF8',
+            '#94FADB', '#B9F18D', '#C3E2C2', '#EAECCC', '#AFC8AD'
+        ];
+        return colors[Math.floor(Math.random() * colors.length)];
+    };
+
+    const connect = async () => {
+        if (provider.value) return;
+
+        loading.value = true;
+        error.value = '';
+
+        try {
+            // Dynamically import TipTap extensions first (needed for server extensions)
+            const [
+                tiptapCore,
+                { Collaboration },
+                { CollaborationCursor }
+            ] = await Promise.all([
+                import('@tiptap/core'),
+                import('@tiptap/extension-collaboration'),
+                import('@rgby/collab-core')
+            ]);
+            const { Editor: TiptapEditor } = tiptapCore;
+
+            // Fetch server extensions, providing @tiptap/core for scripts that import it
+            const serverExtensions = await client.getExtensions({
+                '@tiptap/core': tiptapCore
+            });
+
+            // Get provider
+            const p = await client.getProvider(spaceId.value, documentId.value, {
+                document: doc.value
+            });
+
+            // Wait for persistence to load
+            await p.waitForPersistence();
+            persistenceReady.value = p.isPersistenceReady();
+
+            // Event listeners
+            const updateStatus = () => { status.value = p.status; };
+            const updateSynced = () => { synced.value = p.synced; };
+
+            p.on('status', updateStatus);
+            p.on('synced', updateSynced);
+            p.on('disconnect', updateStatus);
+
+            provider.value = markRaw(p);
+
+            // StarterKit is optional - consumer can provide their own extensions
+            let StarterKit: any = null;
+            try {
+                StarterKit = (await import('@tiptap/starter-kit')).default;
+            } catch {
+                // StarterKit not installed - user should provide extensions via options
+            }
+
+            const fragment = doc.value.getXmlFragment('default');
+            const tabId = generateTabId();
+            const userName = options.user?.name ?? 'Anonymous';
+            const userColor = options.user?.color ?? generateColor();
+
+            // Create editor
+            const baseExtensions = StarterKit
+                ? [StarterKit.configure({ undoRedo: false })]
+                : [];
+
+            const editorInstance = new TiptapEditor({
+                extensions: [
+                    ...baseExtensions,
+                    Collaboration.configure({
+                        document: doc.value,
+                        field: 'default'
+                    }),
+                    CollaborationCursor.configure({
+                        provider: provider.value,
+                        user: {
+                            name: userName,
+                            color: userColor,
+                            clientId: tabId
+                        }
+                    }),
+                    ...serverExtensions,
+                    ...(options.extensions ?? [])
+                ],
+                ...options.editorOptions
+            });
+
+            editor.value = markRaw(editorInstance);
+            loading.value = false;
+
+            if (options.onReady) {
+                options.onReady(editorInstance);
+            }
+        } catch (e: any) {
+            error.value = e.message || 'Failed to initialize editor';
+            loading.value = false;
+            console.error('[useTiptapEditor] Error:', e);
+        }
+    };
+
+    const disconnect = () => {
+        provider.value?.destroy();
+        provider.value = null;
+        status.value = 'disconnected';
+        synced.value = false;
+    };
+
+    const destroy = () => {
+        editor.value?.destroy();
+        editor.value = null;
+        disconnect();
+        doc.value.destroy();
+        doc.value = markRaw(new Y.Doc());
+    };
+
+    const clearLocalData = async () => {
+        if (provider.value) {
+            await provider.value.clearLocalData();
+        }
+    };
+
+    // Watch for changes to spaceId/documentId and reconnect
+    watch([spaceId, documentId], async ([newSpaceId, newDocId], [oldSpaceId, oldDocId]) => {
+        if (!newSpaceId || !newDocId) {
+            destroy();
+            return;
+        }
+
+        // If changed, reconnect
+        if (newSpaceId !== oldSpaceId || newDocId !== oldDocId) {
+            destroy();
+            await connect();
+        }
+    });
+
+    // Auto-connect if enabled
+    if (options.autoConnect !== false) {
+        onMounted(async () => {
+            if (spaceId.value && documentId.value) {
+                await connect();
+            }
+        });
+    }
+
+    onBeforeUnmount(() => {
+        destroy();
+    });
+
+    return {
+        editor,
+        doc,
+        provider,
+        status,
+        synced,
+        persistenceReady,
+        loading,
+        error,
+        connect,
+        disconnect,
+        destroy,
+        clearLocalData
+    };
+}
+
+// ----------------------------------------------------------------------
+// 11. Master Composable: useCollaborativeDocument
+// ----------------------------------------------------------------------
+
+export function useCollaborativeDocument(spaceId: string, documentId: string) {
+    // 1. Initialize Connection
+    const {
+        doc, provider, status, synced, undoManager,
+        connect, disconnect, transact, undo, redo
+    } = useDocument(spaceId, documentId);
+
+    // 2. Initialize Utils
+    const awareness = useAwareness(provider);
+    const comments = useLiveComments(provider, spaceId, documentId);
+
+    // 3. Create Factories (closured around 'doc')
+    // We return functions that generate the composables so the user can name them
+    const useMap = <T>(name: string) => useSyncedMap<T>(doc, name);
+    const useArray = <T>(name: string) => useSyncedArray<T>(doc, name);
+    const useText = (name: string) => useSyncedText(doc, name);
+    const useXml = (name: string) => useSyncedXml(doc, name);
+
+    return {
+        // Connection & Core
+        doc,
+        provider,
+        status,
+        synced,
+        connect,
+        disconnect,
+
+        // History
+        undo,
+        redo,
+        transact,
+        canUndo: computed(() => undoManager.value?.undoStack.length ?? 0 > 0),
+        canRedo: computed(() => undoManager.value?.redoStack.length ?? 0 > 0),
+
+        // Presence
+        users: awareness.states,
+        me: awareness.currentUser,
+        updatePresence: awareness.setLocalState,
+
+        // Comments
+        comments: comments.threads,
+        loadingComments: comments.loading,
+        createComment: comments.createComment,
+
+        // Factories
+        useMap,
+        useArray,
+        useText,
+        useXml
+    };
+}