flikkui 0.1.0-beta.8 → 0.2.0-beta.1

package/dist/components/ai/PresenceIndicator/PresenceIndicator.types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * PresenceIndicator Type Definitions
+ *
+ * Defines props and interfaces for the PresenceIndicator component.
+ */
+import React from 'react';
+import { PresenceUser } from '../PresenceProvider/PresenceProvider.types';
+import { AvatarSize } from '../../core/Avatar/Avatar.types';
+import { AvatarGroupSpacing } from '../../core/AvatarGroup/AvatarGroup.types';
+/**
+ * Sort criteria for presence users
+ */
+export type PresenceSort = 'joinedAt' | 'name' | 'status' | ((a: PresenceUser, b: PresenceUser) => number);
+/**
+ * PresenceIndicator component props
+ */
+export interface PresenceIndicatorProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Maximum users to display before showing overflow (default: 5) */
+    max?: number;
+    /** Avatar size (default: 'md') */
+    size?: AvatarSize;
+    /** Spacing between avatars (default: 'normal') */
+    spacing?: AvatarGroupSpacing;
+    /** Show user count label (default: false) */
+    showCount?: boolean;
+    /** Custom count format function */
+    countFormat?: (count: number) => string;
+    /** Filter which users to show */
+    filter?: (user: PresenceUser) => boolean;
+    /** Sort users by criteria (default: 'joinedAt') */
+    sortBy?: PresenceSort;
+    /** Custom avatar renderer */
+    renderAvatar?: (user: PresenceUser) => React.ReactNode;
+    /** Enable animations (default: true) */
+    shouldAnimate?: boolean;
+    /** Custom overflow indicator */
+    overflowIndicator?: (overflowCount: number) => React.ReactNode;
+    /** ARIA label for the group */
+    ariaLabel?: string;
+    /** Theme overrides */
+    theme?: PresenceIndicatorTheme;
+}
+/**
+ * Theme configuration for PresenceIndicator
+ */
+export interface PresenceIndicatorTheme {
+    /** Base container style */
+    baseStyle?: string;
+    /** Count label style */
+    countStyle?: string;
+    /** Size-specific gaps */
+    sizes?: Partial<Record<AvatarSize, string>>;
+}

package/dist/components/ai/PresenceIndicator/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * PresenceIndicator - Visual display of active users
+ *
+ * @module collaboration/PresenceIndicator
+ */
+export { PresenceIndicator } from './PresenceIndicator';
+export { presenceIndicatorTheme } from './PresenceIndicator.theme';
+export type { PresenceIndicatorProps, PresenceIndicatorTheme, PresenceSort, } from './PresenceIndicator.types';

package/dist/components/ai/PresenceProvider/PresenceContext.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Presence Context
+ *
+ * Provides presence state to child components via React Context.
+ * Follow the same pattern as Tabs and other compound components.
+ */
+import { PresenceContextValue } from './PresenceProvider.types';
+/**
+ * Context for sharing presence state between provider and child components
+ */
+export declare const PresenceContext: import("react").Context<PresenceContextValue | null>;
+/**
+ * Hook to consume PresenceContext
+ *
+ * @throws Error if used outside PresenceProvider
+ * @returns Presence context value
+ *
+ * @example
+ * function MyComponent() {
+ *   const { users, typingUsers, isConnected } = usePresenceContext();
+ *   return <div>{users.length} users online</div>;
+ * }
+ */
+export declare const usePresenceContext: () => PresenceContextValue;

package/dist/components/ai/PresenceProvider/PresenceContext.js

@@ -0,0 +1,34 @@
+import { createContext, useContext } from 'react';
+
+/**
+ * Presence Context
+ *
+ * Provides presence state to child components via React Context.
+ * Follow the same pattern as Tabs and other compound components.
+ */
+/**
+ * Context for sharing presence state between provider and child components
+ */
+const PresenceContext = createContext(null);
+/**
+ * Hook to consume PresenceContext
+ *
+ * @throws Error if used outside PresenceProvider
+ * @returns Presence context value
+ *
+ * @example
+ * function MyComponent() {
+ *   const { users, typingUsers, isConnected } = usePresenceContext();
+ *   return <div>{users.length} users online</div>;
+ * }
+ */
+const usePresenceContext = () => {
+    const context = useContext(PresenceContext);
+    if (!context) {
+        throw new Error('Presence components must be used within a PresenceProvider. ' +
+            'Wrap your component tree with <PresenceProvider>.');
+    }
+    return context;
+};
+
+export { PresenceContext, usePresenceContext };

package/dist/components/ai/PresenceProvider/PresenceProvider.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Presence Provider Component
+ *
+ * Root provider that manages real-time presence state via adapter pattern.
+ * Provides presence context to child components.
+ *
+ * Features:
+ * - Backend-agnostic adapter pattern
+ * - Network-aware reconnection
+ * - Typing state management with debouncing
+ * - Auto-cleanup on unmount
+ */
+import React from 'react';
+import { PresenceProviderProps } from './PresenceProvider.types';
+/**
+ * PresenceProvider - Real-time collaboration provider
+ *
+ * @example
+ * ```tsx
+ * const adapter = new MockPresenceAdapter();
+ * const currentUser = { id: '1', name: 'John Doe', status: 'online' };
+ *
+ * <PresenceProvider channel="chat-room-123" currentUser={currentUser} adapter={adapter}>
+ *   <PresenceIndicator />
+ *   <ChatInterface>
+ *     <MessageHistory />
+ *     <EditingIndicator />
+ *   </ChatInterface>
+ * </PresenceProvider>
+ * ```
+ */
+export declare const PresenceProvider: React.ForwardRefExoticComponent<PresenceProviderProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/ai/PresenceProvider/PresenceProvider.js

@@ -0,0 +1,321 @@
+import React__default, { useState, useRef, useCallback, useMemo, useEffect } from 'react';
+import { PresenceContext } from './PresenceContext.js';
+import { useNetworkStatus } from '../../../hooks/useNetworkStatus.js';
+import { debounce } from '../../../utils/debounce.js';
+
+/**
+ * Presence Provider Component
+ *
+ * Root provider that manages real-time presence state via adapter pattern.
+ * Provides presence context to child components.
+ *
+ * Features:
+ * - Backend-agnostic adapter pattern
+ * - Network-aware reconnection
+ * - Typing state management with debouncing
+ * - Auto-cleanup on unmount
+ */
+/**
+ * PresenceProvider - Real-time collaboration provider
+ *
+ * @example
+ * ```tsx
+ * const adapter = new MockPresenceAdapter();
+ * const currentUser = { id: '1', name: 'John Doe', status: 'online' };
+ *
+ * <PresenceProvider channel="chat-room-123" currentUser={currentUser} adapter={adapter}>
+ *   <PresenceIndicator />
+ *   <ChatInterface>
+ *     <MessageHistory />
+ *     <EditingIndicator />
+ *   </ChatInterface>
+ * </PresenceProvider>
+ * ```
+ */
+const PresenceProvider = React__default.forwardRef(({ channel, currentUser, adapter, autoConnect = true, typingDebounce = 300, typingTimeout = 3000, autoReconnect = true, onPresenceChange, onConnectionChange, onError, children, className, ...props }, ref) => {
+    // ===== State =====
+    const [users, setUsers] = useState([]);
+    const [typingUsers, setTypingUsers] = useState([]);
+    const [connectionStatus, setConnectionStatus] = useState('disconnected');
+    const [error, setError] = useState(null);
+    // ===== Refs =====
+    const typingTimeoutRef = useRef(undefined);
+    const isConnectingRef = useRef(false);
+    const hasConnectedOnceRef = useRef(false);
+    // ===== Network status =====
+    const { isOnline, wasOffline } = useNetworkStatus();
+    // ===== Derived state =====
+    const isConnected = connectionStatus === 'connected';
+    const isConnecting = connectionStatus === 'connecting';
+    // ===== Connection management =====
+    /**
+     * Connect to presence channel
+     */
+    const connect = useCallback(async () => {
+        // Use ref to check if already connecting to avoid dependency on connectionStatus
+        if (isConnectingRef.current) {
+            return;
+        }
+        isConnectingRef.current = true;
+        setConnectionStatus('connecting');
+        setError(null);
+        try {
+            await adapter.connect({
+                channel,
+                currentUser,
+                typingDebounce,
+                typingTimeout,
+            });
+            hasConnectedOnceRef.current = true;
+            setConnectionStatus('connected');
+            if (process.env.NODE_ENV !== 'production') {
+                console.log('[PresenceProvider]: Connected to channel:', channel);
+            }
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error('Connection failed');
+            setError(error);
+            setConnectionStatus('disconnected');
+            onError === null || onError === void 0 ? void 0 : onError(error);
+            if (process.env.NODE_ENV !== 'production') {
+                console.error('[PresenceProvider]: Connection error:', error);
+            }
+            // Attempt reconnection if enabled
+            if (autoReconnect && hasConnectedOnceRef.current) {
+                if (process.env.NODE_ENV !== 'production') {
+                    console.log('[PresenceProvider]: Scheduling reconnection...');
+                }
+                setTimeout(() => {
+                    if (isOnline) {
+                        connect();
+                    }
+                }, 3000);
+            }
+        }
+        finally {
+            isConnectingRef.current = false;
+        }
+    }, [
+        adapter,
+        channel,
+        currentUser,
+        typingDebounce,
+        typingTimeout,
+        autoReconnect,
+        isOnline,
+        onError,
+    ]);
+    /**
+     * Disconnect from channel
+     */
+    const disconnect = useCallback(async () => {
+        try {
+            await adapter.disconnect();
+            setConnectionStatus('disconnected');
+            setUsers([]);
+            setTypingUsers([]);
+            setError(null);
+            if (process.env.NODE_ENV !== 'production') {
+                console.log('[PresenceProvider]: Disconnected from channel');
+            }
+        }
+        catch (err) {
+            if (process.env.NODE_ENV !== 'production') {
+                console.error('[PresenceProvider]: Disconnect error:', err);
+            }
+        }
+    }, [adapter]);
+    // ===== Typing management =====
+    /**
+     * Start typing indicator (not debounced - debouncing is handled internally)
+     */
+    const startTypingInternal = useCallback(() => {
+        if (connectionStatus !== 'connected')
+            return;
+        adapter.sendTypingStart();
+        // Clear existing timeout
+        if (typingTimeoutRef.current) {
+            clearTimeout(typingTimeoutRef.current);
+        }
+        // Auto-stop after timeout
+        typingTimeoutRef.current = setTimeout(() => {
+            stopTyping();
+        }, typingTimeout);
+    }, [adapter, connectionStatus, typingTimeout]);
+    /**
+     * Start typing indicator (debounced)
+     */
+    const startTyping = useMemo(() => debounce(startTypingInternal, typingDebounce), [startTypingInternal, typingDebounce]);
+    /**
+     * Stop typing indicator
+     */
+    const stopTyping = useCallback(() => {
+        if (connectionStatus !== 'connected')
+            return;
+        adapter.sendTypingStop();
+        // Clear timeout
+        if (typingTimeoutRef.current) {
+            clearTimeout(typingTimeoutRef.current);
+        }
+    }, [adapter, connectionStatus]);
+    /**
+     * Update current user metadata
+     */
+    const updateUser = useCallback((updates) => {
+        if (connectionStatus !== 'connected')
+            return;
+        adapter.updateUserMetadata(updates);
+    }, [adapter, connectionStatus]);
+    /**
+     * Send custom event
+     */
+    const sendEvent = useCallback((event, data) => {
+        if (connectionStatus !== 'connected')
+            return;
+        adapter.sendCustomEvent(event, data);
+    }, [adapter, connectionStatus]);
+    // ===== Effects =====
+    /**
+     * Subscribe to adapter events
+     */
+    useEffect(() => {
+        // Subscribe to presence changes
+        const unsubscribePresence = adapter.onPresenceChange((newUsers) => {
+            setUsers(newUsers);
+            // Notify callback
+            if (onPresenceChange && newUsers.length > users.length) {
+                // User joined
+                const newUser = newUsers.find(u => !users.find(existing => existing.id === u.id));
+                if (newUser) {
+                    const event = { type: 'user-joined', user: newUser };
+                    onPresenceChange(event);
+                }
+            }
+            else if (onPresenceChange && newUsers.length < users.length) {
+                // User left
+                const leftUser = users.find(u => !newUsers.find(existing => existing.id === u.id));
+                if (leftUser) {
+                    const event = { type: 'user-left', userId: leftUser.id };
+                    onPresenceChange(event);
+                }
+            }
+        });
+        // Subscribe to typing changes
+        const unsubscribeTyping = adapter.onTypingChange((newTypingUsers) => {
+            setTypingUsers(newTypingUsers);
+            // Notify callback
+            if (onPresenceChange) {
+                const startedTyping = newTypingUsers.find(u => !typingUsers.find(existing => existing.id === u.id));
+                const stoppedTyping = typingUsers.find(u => !newTypingUsers.find(existing => existing.id === u.id));
+                if (startedTyping) {
+                    const event = {
+                        type: 'typing-started',
+                        userId: startedTyping.id,
+                        userName: startedTyping.name,
+                    };
+                    onPresenceChange(event);
+                }
+                if (stoppedTyping) {
+                    const event = {
+                        type: 'typing-stopped',
+                        userId: stoppedTyping.id,
+                    };
+                    onPresenceChange(event);
+                }
+            }
+        });
+        // Subscribe to connection changes
+        const unsubscribeConnection = adapter.onConnectionChange((status) => {
+            setConnectionStatus(status);
+            onConnectionChange === null || onConnectionChange === void 0 ? void 0 : onConnectionChange(status);
+            if (status === 'connected' && onPresenceChange) {
+                const event = { type: 'reconnected' };
+                onPresenceChange(event);
+            }
+            else if (status === 'connecting' && onPresenceChange) {
+                const event = { type: 'reconnecting' };
+                onPresenceChange(event);
+            }
+        });
+        // Subscribe to errors
+        const unsubscribeError = adapter.onError((err) => {
+            setError(err);
+            onError === null || onError === void 0 ? void 0 : onError(err);
+            if (onPresenceChange) {
+                const event = { type: 'connection-error', error: err };
+                onPresenceChange(event);
+            }
+        });
+        // Cleanup
+        return () => {
+            unsubscribePresence();
+            unsubscribeTyping();
+            unsubscribeConnection();
+            unsubscribeError();
+        };
+    }, [adapter, users, typingUsers, onPresenceChange, onConnectionChange, onError]);
+    /**
+     * Auto-connect on mount
+     */
+    useEffect(() => {
+        if (autoConnect) {
+            connect();
+        }
+        // Cleanup on unmount
+        return () => {
+            disconnect();
+            // Clear typing timeout
+            if (typingTimeoutRef.current) {
+                clearTimeout(typingTimeoutRef.current);
+            }
+        };
+    }, [autoConnect, connect, disconnect]);
+    /**
+     * Handle network recovery
+     */
+    useEffect(() => {
+        if (wasOffline && isOnline && autoReconnect && hasConnectedOnceRef.current) {
+            if (process.env.NODE_ENV !== 'production') {
+                console.log('[PresenceProvider]: Network recovered, reconnecting...');
+            }
+            connect();
+        }
+    }, [wasOffline, isOnline, autoReconnect, connect]);
+    // ===== Context value =====
+    const contextValue = useMemo(() => ({
+        users,
+        typingUsers,
+        currentUser,
+        connectionStatus,
+        isConnected,
+        isConnecting,
+        error,
+        connect,
+        disconnect,
+        startTyping,
+        stopTyping,
+        updateUser,
+        sendEvent,
+    }), [
+        users,
+        typingUsers,
+        currentUser,
+        connectionStatus,
+        isConnected,
+        isConnecting,
+        error,
+        connect,
+        disconnect,
+        startTyping,
+        stopTyping,
+        updateUser,
+        sendEvent,
+    ]);
+    // ===== Render =====
+    return (React__default.createElement(PresenceContext.Provider, { value: contextValue },
+        React__default.createElement("div", { ref: ref, className: className, "data-channel": channel, "data-connected": isConnected, "data-user-count": users.length, "data-typing-count": typingUsers.length, ...props }, children)));
+});
+// Set display name for dev tools
+PresenceProvider.displayName = 'PresenceProvider';
+
+export { PresenceProvider };

package/dist/components/ai/PresenceProvider/PresenceProvider.types.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Real-Time Collaboration - Core Type Definitions
+ *
+ * Defines the foundational types for the presence system including
+ * users, typing states, events, and provider configuration.
+ */
+import React from 'react';
+import { PresenceAdapter } from './adapters/PresenceAdapter';
+/**
+ * User presence data structure
+ * Represents a user's current state in the collaboration channel
+ */
+export interface PresenceUser {
+    /** Unique user identifier */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Avatar image URL (optional) */
+    avatar?: string;
+    /** User status indicator */
+    status?: 'online' | 'offline' | 'busy' | 'away';
+    /** Custom metadata (JSON serializable) */
+    metadata?: Record<string, unknown>;
+    /** Timestamp when user joined the channel */
+    joinedAt?: Date;
+    /** Last activity timestamp */
+    lastSeenAt?: Date;
+}
+/**
+ * Typing state for a user
+ * Tracks when a user is actively typing
+ */
+export interface TypingUser {
+    /** User ID */
+    id: string;
+    /** User name for display */
+    name: string;
+    /** Avatar URL (optional) */
+    avatar?: string;
+    /** Timestamp when typing started */
+    startedAt: Date;
+}
+/**
+ * Connection status states
+ */
+export type ConnectionStatus = 'connected' | 'disconnected' | 'connecting';
+/**
+ * Presence event types
+ * Union type representing all possible presence-related events
+ */
+export type PresenceEvent = {
+    type: 'user-joined';
+    user: PresenceUser;
+} | {
+    type: 'user-left';
+    userId: string;
+} | {
+    type: 'user-updated';
+    user: PresenceUser;
+} | {
+    type: 'typing-started';
+    userId: string;
+    userName: string;
+} | {
+    type: 'typing-stopped';
+    userId: string;
+} | {
+    type: 'connection-error';
+    error: Error;
+} | {
+    type: 'reconnecting';
+} | {
+    type: 'reconnected';
+};
+/**
+ * Context value provided to child components
+ * Shared state accessible via usePresenceContext hook
+ */
+export interface PresenceContextValue {
+    /** All users currently in the channel */
+    users: PresenceUser[];
+    /** Users currently typing */
+    typingUsers: TypingUser[];
+    /** Current user data */
+    currentUser: PresenceUser;
+    /** Current connection status */
+    connectionStatus: ConnectionStatus;
+    /** Is actively connected */
+    isConnected: boolean;
+    /** Is connecting or reconnecting */
+    isConnecting: boolean;
+    /** Connection error (if any) */
+    error: Error | null;
+    /** Manually connect to channel */
+    connect: () => Promise<void>;
+    /** Manually disconnect from channel */
+    disconnect: () => Promise<void>;
+    /** Start typing indicator */
+    startTyping: () => void;
+    /** Stop typing indicator */
+    stopTyping: () => void;
+    /** Update current user metadata */
+    updateUser: (updates: Partial<PresenceUser>) => void;
+    /** Send custom presence event */
+    sendEvent: (event: string, data?: unknown) => void;
+}
+/**
+ * PresenceProvider component props
+ */
+export interface PresenceProviderProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onError'> {
+    /** Unique channel/room identifier */
+    channel: string;
+    /** Current user data */
+    currentUser: PresenceUser;
+    /** Backend adapter instance */
+    adapter: PresenceAdapter;
+    /** Auto-connect on mount (default: true) */
+    autoConnect?: boolean;
+    /** Debounce delay for typing events in milliseconds (default: 300) */
+    typingDebounce?: number;
+    /** Auto stop typing after inactivity in milliseconds (default: 3000) */
+    typingTimeout?: number;
+    /** Enable automatic reconnection (default: true) */
+    autoReconnect?: boolean;
+    /** Callback when presence event occurs */
+    onPresenceChange?: (event: PresenceEvent) => void;
+    /** Callback when connection status changes */
+    onConnectionChange?: (status: ConnectionStatus) => void;
+    /** Callback when error occurs */
+    onError?: (error: Error) => void;
+    /** Children components */
+    children?: React.ReactNode;
+}
+/**
+ * Theme overrides for PresenceProvider
+ * Currently unused but kept for future styling needs
+ */
+export interface PresenceProviderTheme {
+    baseStyle?: string;
+}