@object-ui/collaboration 2.0.0

package/dist/usePresence.js

@@ -0,0 +1,174 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { useState, useEffect, useCallback, useRef, useMemo } from 'react';
+/** Deterministic color assignment based on user ID */
+function userIdToColor(userId) {
+    const colors = [
+        '#e74c3c', '#3498db', '#2ecc71', '#f39c12', '#9b59b6',
+        '#1abc9c', '#e67e22', '#2980b9', '#27ae60', '#8e44ad',
+        '#d35400', '#c0392b', '#16a085', '#f1c40f', '#7f8c8d',
+    ];
+    let hash = 0;
+    for (let i = 0; i < userId.length; i++) {
+        hash = ((hash << 5) - hash + userId.charCodeAt(i)) | 0;
+    }
+    return colors[Math.abs(hash) % colors.length];
+}
+/**
+ * Hook for live cursors and presence tracking.
+ *
+ * Tracks cursor position with throttled updates, detects idle/away status
+ * through activity monitoring, and manages a set of remote users.
+ *
+ * @param sendPresence - Callback to broadcast presence updates to other users
+ * @param config - Presence configuration
+ */
+export function usePresence(sendPresence, config) {
+    const { user, throttleMs = 50, idleTimeout = 60000, awayTimeout = 300000, } = config;
+    const color = useMemo(() => userIdToColor(user.id), [user.id]);
+    const [remoteUsers, setRemoteUsers] = useState(new Map());
+    const [currentUser, setCurrentUser] = useState(() => ({
+        userId: user.id,
+        userName: user.name,
+        avatar: user.avatar,
+        color,
+        status: 'active',
+        lastActivity: new Date().toISOString(),
+    }));
+    const lastSendRef = useRef(0);
+    const activityTimerRef = useRef(null);
+    const awayTimerRef = useRef(null);
+    const currentUserRef = useRef(currentUser);
+    currentUserRef.current = currentUser;
+    const sendPresenceRef = useRef(sendPresence);
+    sendPresenceRef.current = sendPresence;
+    const throttledSend = useCallback((updated) => {
+        const now = Date.now();
+        if (now - lastSendRef.current >= throttleMs) {
+            lastSendRef.current = now;
+            sendPresenceRef.current(updated);
+        }
+    }, [throttleMs]);
+    const resetActivityTimers = useCallback(() => {
+        if (activityTimerRef.current !== null)
+            clearTimeout(activityTimerRef.current);
+        if (awayTimerRef.current !== null)
+            clearTimeout(awayTimerRef.current);
+        const now = new Date().toISOString();
+        setCurrentUser(prev => {
+            if (prev.status !== 'active' || prev.lastActivity !== now) {
+                const updated = { ...prev, status: 'active', lastActivity: now };
+                throttledSend(updated);
+                return updated;
+            }
+            return prev;
+        });
+        activityTimerRef.current = setTimeout(() => {
+            setCurrentUser(prev => {
+                const updated = { ...prev, status: 'idle', lastActivity: new Date().toISOString() };
+                sendPresenceRef.current(updated);
+                return updated;
+            });
+            awayTimerRef.current = setTimeout(() => {
+                setCurrentUser(prev => {
+                    const updated = { ...prev, status: 'away', lastActivity: new Date().toISOString() };
+                    sendPresenceRef.current(updated);
+                    return updated;
+                });
+            }, awayTimeout - idleTimeout);
+        }, idleTimeout);
+    }, [idleTimeout, awayTimeout, throttledSend]);
+    // Listen for user activity (mouse, keyboard, touch)
+    useEffect(() => {
+        if (typeof window === 'undefined')
+            return;
+        const handleActivity = () => resetActivityTimers();
+        const events = ['mousemove', 'keydown', 'touchstart', 'scroll', 'click'];
+        events.forEach(event => window.addEventListener(event, handleActivity, { passive: true }));
+        resetActivityTimers();
+        return () => {
+            events.forEach(event => window.removeEventListener(event, handleActivity));
+            if (activityTimerRef.current !== null)
+                clearTimeout(activityTimerRef.current);
+            if (awayTimerRef.current !== null)
+                clearTimeout(awayTimerRef.current);
+        };
+    }, [resetActivityTimers]);
+    const updateCursor = useCallback((position) => {
+        setCurrentUser(prev => {
+            const updated = {
+                ...prev,
+                cursor: position,
+                lastActivity: new Date().toISOString(),
+                status: 'active',
+            };
+            throttledSend(updated);
+            return updated;
+        });
+    }, [throttledSend]);
+    const updateSelection = useCallback((selection) => {
+        setCurrentUser(prev => {
+            const updated = {
+                ...prev,
+                selection,
+                lastActivity: new Date().toISOString(),
+                status: 'active',
+            };
+            throttledSend(updated);
+            return updated;
+        });
+    }, [throttledSend]);
+    // Keep currentUser in sync with config changes
+    useEffect(() => {
+        setCurrentUser(prev => ({
+            ...prev,
+            userId: user.id,
+            userName: user.name,
+            avatar: user.avatar,
+            color,
+        }));
+    }, [user.id, user.name, user.avatar, color]);
+    const users = useMemo(() => Array.from(remoteUsers.values()), [remoteUsers]);
+    return {
+        users,
+        userCount: users.length + 1,
+        updateCursor,
+        updateSelection,
+        currentUser,
+    };
+}
+/**
+ * Update remote user presence. Call this when receiving presence data
+ * from other users via the realtime channel.
+ *
+ * @returns A function to update or remove a remote user from the presence set.
+ */
+export function createPresenceUpdater() {
+    const users = new Map();
+    const listeners = new Set();
+    const notify = () => {
+        listeners.forEach(cb => cb(new Map(users)));
+    };
+    return {
+        updateUser(user) {
+            users.set(user.userId, user);
+            notify();
+        },
+        removeUser(userId) {
+            users.delete(userId);
+            notify();
+        },
+        getUsers() {
+            return Array.from(users.values());
+        },
+        onUsersChange(callback) {
+            listeners.add(callback);
+            return () => { listeners.delete(callback); };
+        },
+    };
+}

package/dist/useRealtimeSubscription.d.ts

@@ -0,0 +1,59 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/** WebSocket connection configuration */
+export interface RealtimeConfig {
+    /** WebSocket URL */
+    url?: string;
+    /** Room/channel to subscribe to */
+    channel: string;
+    /** Auto-reconnect on disconnect */
+    autoReconnect?: boolean;
+    /** Reconnect interval in ms */
+    reconnectInterval?: number;
+    /** Max reconnect attempts */
+    maxReconnectAttempts?: number;
+    /** Auth token for WebSocket */
+    authToken?: string;
+}
+export type ConnectionState = 'connecting' | 'connected' | 'disconnected' | 'reconnecting' | 'error';
+export interface RealtimeMessage<T = unknown> {
+    type: string;
+    channel: string;
+    data: T;
+    sender?: string;
+    timestamp: string;
+}
+export interface RealtimeResult<T = unknown> {
+    /** Current connection state */
+    connectionState: ConnectionState;
+    /** Whether connected */
+    isConnected: boolean;
+    /** Last received message */
+    lastMessage: RealtimeMessage<T> | null;
+    /** All messages received since subscription */
+    messages: RealtimeMessage<T>[];
+    /** Send a message to the channel */
+    send: (type: string, data: T) => void;
+    /** Subscribe to specific message types */
+    subscribe: (type: string, handler: (data: T) => void) => () => void;
+    /** Disconnect from the channel */
+    disconnect: () => void;
+    /** Reconnect to the channel */
+    reconnect: () => void;
+    /** Error if any */
+    error: Error | null;
+}
+/**
+ * Hook for real-time data subscriptions via WebSocket.
+ * Aligned with @objectstack/client realtime API.
+ *
+ * Provides automatic reconnection with exponential backoff,
+ * message buffering, and typed message subscriptions.
+ */
+export declare function useRealtimeSubscription<T = unknown>(config: RealtimeConfig): RealtimeResult<T>;
+//# sourceMappingURL=useRealtimeSubscription.d.ts.map

package/dist/useRealtimeSubscription.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRealtimeSubscription.d.ts","sourceRoot":"","sources":["../src/useRealtimeSubscription.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,yCAAyC;AACzC,MAAM,WAAW,cAAc;IAC7B,oBAAoB;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,mCAAmC;IACnC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,+BAA+B;IAC/B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,6BAA6B;IAC7B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,+BAA+B;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,WAAW,GAAG,cAAc,GAAG,cAAc,GAAG,OAAO,CAAC;AAErG,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,OAAO;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,CAAC,CAAC;IACR,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO;IACzC,+BAA+B;IAC/B,eAAe,EAAE,eAAe,CAAC;IACjC,wBAAwB;IACxB,WAAW,EAAE,OAAO,CAAC;IACrB,4BAA4B;IAC5B,WAAW,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACvC,+CAA+C;IAC/C,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/B,oCAAoC;IACpC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;IACtC,0CAA0C;IAC1C,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;IACpE,kCAAkC;IAClC,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,+BAA+B;IAC/B,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,mBAAmB;IACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,cAAc,GAAG,cAAc,CAAC,CAAC,CAAC,CA0O9F"}

package/dist/useRealtimeSubscription.js

@@ -0,0 +1,224 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { useState, useEffect, useCallback, useRef } from 'react';
+/**
+ * Hook for real-time data subscriptions via WebSocket.
+ * Aligned with @objectstack/client realtime API.
+ *
+ * Provides automatic reconnection with exponential backoff,
+ * message buffering, and typed message subscriptions.
+ */
+export function useRealtimeSubscription(config) {
+    const { url, channel, autoReconnect = true, reconnectInterval = 1000, maxReconnectAttempts = 10, authToken, } = config;
+    const [connectionState, setConnectionState] = useState('disconnected');
+    const [lastMessage, setLastMessage] = useState(null);
+    const [messages, setMessages] = useState([]);
+    const [error, setError] = useState(null);
+    const wsRef = useRef(null);
+    const reconnectAttemptsRef = useRef(0);
+    const reconnectTimerRef = useRef(null);
+    const handlersRef = useRef(new Map());
+    const sendBufferRef = useRef([]);
+    const mountedRef = useRef(true);
+    const intentionalCloseRef = useRef(false);
+    const clearReconnectTimer = useCallback(() => {
+        if (reconnectTimerRef.current !== null) {
+            clearTimeout(reconnectTimerRef.current);
+            reconnectTimerRef.current = null;
+        }
+    }, []);
+    const flushSendBuffer = useCallback((ws) => {
+        while (sendBufferRef.current.length > 0) {
+            const msg = sendBufferRef.current.shift();
+            const payload = {
+                type: msg.type,
+                channel,
+                data: msg.data,
+                timestamp: new Date().toISOString(),
+            };
+            ws.send(JSON.stringify(payload));
+        }
+    }, [channel]);
+    const connect = useCallback(() => {
+        if (typeof WebSocket === 'undefined') {
+            setError(new Error('WebSocket is not available in this environment'));
+            setConnectionState('error');
+            return;
+        }
+        if (!url) {
+            setError(new Error('WebSocket URL is required'));
+            setConnectionState('error');
+            return;
+        }
+        // Validate WebSocket URL protocol (only ws: or wss: allowed)
+        try {
+            const parsed = new URL(url);
+            if (parsed.protocol !== 'ws:' && parsed.protocol !== 'wss:') {
+                setError(new Error('WebSocket URL must use ws: or wss: protocol'));
+                setConnectionState('error');
+                return;
+            }
+        }
+        catch {
+            setError(new Error('Invalid WebSocket URL'));
+            setConnectionState('error');
+            return;
+        }
+        // Close existing connection
+        if (wsRef.current) {
+            intentionalCloseRef.current = true;
+            wsRef.current.close();
+            wsRef.current = null;
+        }
+        intentionalCloseRef.current = false;
+        setConnectionState('connecting');
+        setError(null);
+        const wsUrl = authToken ? `${url}?token=${encodeURIComponent(authToken)}&channel=${encodeURIComponent(channel)}` : `${url}?channel=${encodeURIComponent(channel)}`;
+        let ws;
+        try {
+            ws = new WebSocket(wsUrl);
+        }
+        catch (err) {
+            if (!mountedRef.current)
+                return;
+            const connectError = err instanceof Error ? err : new Error('Failed to create WebSocket connection');
+            setError(connectError);
+            setConnectionState('error');
+            return;
+        }
+        wsRef.current = ws;
+        ws.onopen = () => {
+            if (!mountedRef.current)
+                return;
+            setConnectionState('connected');
+            setError(null);
+            reconnectAttemptsRef.current = 0;
+            flushSendBuffer(ws);
+        };
+        ws.onmessage = (event) => {
+            if (!mountedRef.current)
+                return;
+            try {
+                const message = JSON.parse(String(event.data));
+                if (message.channel !== channel)
+                    return;
+                setLastMessage(message);
+                setMessages(prev => [...prev, message]);
+                // Notify type-specific handlers
+                const typeHandlers = handlersRef.current.get(message.type);
+                if (typeHandlers) {
+                    typeHandlers.forEach(handler => handler(message.data));
+                }
+            }
+            catch {
+                // Ignore unparseable messages
+            }
+        };
+        ws.onerror = () => {
+            if (!mountedRef.current)
+                return;
+            setError(new Error('WebSocket connection error'));
+            setConnectionState('error');
+        };
+        ws.onclose = () => {
+            if (!mountedRef.current)
+                return;
+            wsRef.current = null;
+            if (intentionalCloseRef.current) {
+                setConnectionState('disconnected');
+                return;
+            }
+            if (autoReconnect && reconnectAttemptsRef.current < maxReconnectAttempts) {
+                setConnectionState('reconnecting');
+                const backoff = Math.min(reconnectInterval * Math.pow(2, reconnectAttemptsRef.current), 30000);
+                reconnectAttemptsRef.current += 1;
+                reconnectTimerRef.current = setTimeout(() => {
+                    if (mountedRef.current) {
+                        connect();
+                    }
+                }, backoff);
+            }
+            else {
+                setConnectionState('disconnected');
+            }
+        };
+    }, [url, channel, authToken, autoReconnect, reconnectInterval, maxReconnectAttempts, flushSendBuffer]);
+    const disconnect = useCallback(() => {
+        clearReconnectTimer();
+        intentionalCloseRef.current = true;
+        reconnectAttemptsRef.current = 0;
+        if (wsRef.current) {
+            wsRef.current.close();
+            wsRef.current = null;
+        }
+        setConnectionState('disconnected');
+    }, [clearReconnectTimer]);
+    const reconnectFn = useCallback(() => {
+        clearReconnectTimer();
+        reconnectAttemptsRef.current = 0;
+        connect();
+    }, [connect, clearReconnectTimer]);
+    const send = useCallback((type, data) => {
+        const ws = wsRef.current;
+        if (ws && ws.readyState === WebSocket.OPEN) {
+            const payload = {
+                type,
+                channel,
+                data,
+                timestamp: new Date().toISOString(),
+            };
+            ws.send(JSON.stringify(payload));
+        }
+        else {
+            // Buffer message for when connection is restored
+            sendBufferRef.current.push({ type, data });
+        }
+    }, [channel]);
+    const subscribe = useCallback((type, handler) => {
+        if (!handlersRef.current.has(type)) {
+            handlersRef.current.set(type, new Set());
+        }
+        handlersRef.current.get(type).add(handler);
+        return () => {
+            const handlers = handlersRef.current.get(type);
+            if (handlers) {
+                handlers.delete(handler);
+                if (handlers.size === 0) {
+                    handlersRef.current.delete(type);
+                }
+            }
+        };
+    }, []);
+    // Connect on mount, disconnect on unmount
+    useEffect(() => {
+        mountedRef.current = true;
+        if (url) {
+            connect();
+        }
+        return () => {
+            mountedRef.current = false;
+            clearReconnectTimer();
+            intentionalCloseRef.current = true;
+            if (wsRef.current) {
+                wsRef.current.close();
+                wsRef.current = null;
+            }
+        };
+    }, [url, channel, authToken]); // eslint-disable-line react-hooks/exhaustive-deps
+    return {
+        connectionState,
+        isConnected: connectionState === 'connected',
+        lastMessage,
+        messages,
+        send,
+        subscribe,
+        disconnect,
+        reconnect: reconnectFn,
+        error,
+    };
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@object-ui/collaboration",
+  "version": "2.0.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "Real-time collaboration for Object UI with presence tracking, live cursors, conflict resolution, and comment threads.",
+  "homepage": "https://www.objectui.org",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/objectstack-ai/objectui.git",
+    "directory": "packages/collaboration"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "dependencies": {
+    "@object-ui/types": "2.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.13",
+    "react": "^19.1.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint ."
+  }
+}