flikkui 0.2.0-beta.2 → 0.2.0-beta.5

package/dist/hooks/useOptimisticMutation.d.ts

@@ -1,109 +0,0 @@
-/**
- * useOptimisticMutation Hook
- * Provides instant UI updates with automatic rollback on error
- */
-import { OptimisticError } from "../utils/optimisticErrors";
-import { type RetryConfig } from "../utils/retryUtils";
-import { type ActionQueue, type AddActionOptions } from "../utils/actionQueue";
-/**
- * Mutation state
- */
-export type MutationStatus = "idle" | "pending" | "success" | "error";
-/**
- * Options for useOptimisticMutation hook
- */
-export interface OptimisticMutationOptions<TData, TVariables, TContext = unknown> {
-    /**
-     * Called before mutation - return context for rollback
-     * Context is passed to onSuccess, onError, and onSettled
-     */
-    onMutate?: (variables: TVariables) => TContext | Promise<TContext>;
-    /**
-     * Apply optimistic update immediately
-     * Called synchronously before the mutation starts
-     */
-    onOptimisticUpdate?: (variables: TVariables, context: TContext) => void;
-    /**
-     * Called on success - replace optimistic data with real data
-     */
-    onSuccess?: (data: TData, variables: TVariables, context: TContext) => void;
-    /**
-     * Called on error - rollback optimistic update
-     * Use context to restore previous state
-     */
-    onError?: (error: OptimisticError, variables: TVariables, context: TContext) => void;
-    /**
-     * Called after success or error (cleanup)
-     */
-    onSettled?: (data: TData | undefined, error: OptimisticError | null, variables: TVariables, context: TContext) => void;
-    /**
-     * Retry configuration for failed mutations
-     */
-    retry?: RetryConfig;
-    /**
-     * Queue mutation when offline instead of failing immediately
-     */
-    offlineQueue?: boolean;
-    /**
-     * Custom action queue instance (defaults to global queue)
-     */
-    actionQueue?: ActionQueue;
-    /**
-     * Options for queued action (label, description)
-     */
-    queueOptions?: Omit<AddActionOptions, "maxRetries">;
-}
-/**
- * Return value from useOptimisticMutation hook
- */
-export interface OptimisticMutationReturn<TData, TVariables> {
-    /** Trigger the mutation */
-    mutate: (variables: TVariables) => void;
-    /** Trigger the mutation and return a Promise */
-    mutateAsync: (variables: TVariables) => Promise<TData>;
-    /** Response data from the last successful mutation */
-    data: TData | undefined;
-    /** Error from the last failed mutation */
-    error: OptimisticError | null;
-    /** Current mutation status */
-    status: MutationStatus;
-    /** True when no mutation is in progress or completed */
-    isIdle: boolean;
-    /** True when mutation is in progress */
-    isPending: boolean;
-    /** True when showing optimistic data (mutation in progress) */
-    isOptimistic: boolean;
-    /** True when mutation completed successfully */
-    isSuccess: boolean;
-    /** True when mutation failed */
-    isError: boolean;
-    /** True when error occurred and rollback was applied */
-    isRolledBack: boolean;
-    /** True when mutation was queued for offline processing */
-    isQueued: boolean;
-    /** Reset the mutation state */
-    reset: () => void;
-}
-/**
- * Hook for optimistic UI mutations with automatic rollback
- *
- * @example
- * const { mutate, isOptimistic, isPending } = useOptimisticMutation(
- *   async (data) => api.createMessage(data),
- *   {
- *     onOptimisticUpdate: (newMessage) => {
- *       setMessages(prev => [...prev, { ...newMessage, id: 'temp-id', isPending: true }]);
- *     },
- *     onSuccess: (response) => {
- *       setMessages(prev => prev.map(m =>
- *         m.id === 'temp-id' ? { ...response, isPending: false } : m
- *       ));
- *     },
- *     onError: (error) => {
- *       setMessages(prev => prev.filter(m => m.id !== 'temp-id'));
- *       toast.error('Failed to send message');
- *     }
- *   }
- * );
- */
-export declare function useOptimisticMutation<TData, TVariables, TContext = unknown>(mutationFn: (variables: TVariables) => Promise<TData>, options?: OptimisticMutationOptions<TData, TVariables, TContext>): OptimisticMutationReturn<TData, TVariables>;

package/dist/hooks/useOptimisticMutation.js

@@ -1,171 +0,0 @@
-import { useState, useRef, useCallback } from 'react';
-import { normalizeOptimisticError, MutationError } from '../utils/optimisticErrors.js';
-import { shouldRetry, calculateRetryDelay } from '../utils/retryUtils.js';
-import { useNetworkStatus } from './useNetworkStatus.js';
-import { getDefaultQueue } from '../utils/actionQueue.js';
-
-/**
- * useOptimisticMutation Hook
- * Provides instant UI updates with automatic rollback on error
- */
-/**
- * Hook for optimistic UI mutations with automatic rollback
- *
- * @example
- * const { mutate, isOptimistic, isPending } = useOptimisticMutation(
- *   async (data) => api.createMessage(data),
- *   {
- *     onOptimisticUpdate: (newMessage) => {
- *       setMessages(prev => [...prev, { ...newMessage, id: 'temp-id', isPending: true }]);
- *     },
- *     onSuccess: (response) => {
- *       setMessages(prev => prev.map(m =>
- *         m.id === 'temp-id' ? { ...response, isPending: false } : m
- *       ));
- *     },
- *     onError: (error) => {
- *       setMessages(prev => prev.filter(m => m.id !== 'temp-id'));
- *       toast.error('Failed to send message');
- *     }
- *   }
- * );
- */
-function useOptimisticMutation(mutationFn, options = {}) {
-    var _a;
-    const [status, setStatus] = useState("idle");
-    const [data, setData] = useState(undefined);
-    const [error, setError] = useState(null);
-    const [isRolledBack, setIsRolledBack] = useState(false);
-    const [isQueued, setIsQueued] = useState(false);
-    // Track if we're showing optimistic data
-    const isOptimisticRef = useRef(false);
-    const [isOptimistic, setIsOptimistic] = useState(false);
-    // Get network status for offline queueing
-    const { isOnline } = useNetworkStatus();
-    // Get action queue
-    const actionQueue = (_a = options.actionQueue) !== null && _a !== void 0 ? _a : getDefaultQueue();
-    /**
-     * Reset mutation state
-     */
-    const reset = useCallback(() => {
-        setStatus("idle");
-        setData(undefined);
-        setError(null);
-        setIsRolledBack(false);
-        setIsQueued(false);
-        setIsOptimistic(false);
-        isOptimisticRef.current = false;
-    }, []);
-    /**
-     * Execute mutation with retry logic
-     */
-    const executeMutation = useCallback(async (variables, context, attempt = 0) => {
-        try {
-            const result = await mutationFn(variables);
-            return result;
-        }
-        catch (err) {
-            const optimisticError = normalizeOptimisticError(err, {
-                originalData: variables,
-            });
-            // Check if we should retry
-            if (options.retry &&
-                shouldRetry(optimisticError, attempt, options.retry)) {
-                const delay = calculateRetryDelay(attempt, options.retry);
-                await new Promise((resolve) => setTimeout(resolve, delay));
-                return executeMutation(variables, context, attempt + 1);
-            }
-            throw optimisticError;
-        }
-    }, [mutationFn, options.retry]);
-    /**
-     * Core mutation logic
-     */
-    const mutateAsync = useCallback(async (variables) => {
-        var _a, _b, _c, _d, _e, _f;
-        // Handle offline queueing
-        if (!isOnline && options.offlineQueue) {
-            const queueId = actionQueue.add(() => mutationFn(variables), {
-                maxRetries: (_a = options.retry) === null || _a === void 0 ? void 0 : _a.maxAttempts,
-                ...options.queueOptions,
-            });
-            setIsQueued(true);
-            setStatus("pending");
-            // Return a rejected promise with queue info
-            throw new MutationError(`Mutation queued for offline processing (ID: ${queueId})`, true, // Will be retried when online
-            variables);
-        }
-        // Reset previous state
-        setError(null);
-        setIsRolledBack(false);
-        setIsQueued(false);
-        setStatus("pending");
-        // Get context from onMutate
-        let context;
-        try {
-            context = (await ((_b = options.onMutate) === null || _b === void 0 ? void 0 : _b.call(options, variables)));
-        }
-        catch (err) {
-            // onMutate failed - don't proceed
-            const mutateError = normalizeOptimisticError(err);
-            setError(mutateError);
-            setStatus("error");
-            throw mutateError;
-        }
-        // Apply optimistic update
-        if (options.onOptimisticUpdate) {
-            isOptimisticRef.current = true;
-            setIsOptimistic(true);
-            options.onOptimisticUpdate(variables, context);
-        }
-        try {
-            // Execute the mutation
-            const result = await executeMutation(variables, context);
-            // Success - replace optimistic data
-            isOptimisticRef.current = false;
-            setIsOptimistic(false);
-            setData(result);
-            setStatus("success");
-            (_c = options.onSuccess) === null || _c === void 0 ? void 0 : _c.call(options, result, variables, context);
-            (_d = options.onSettled) === null || _d === void 0 ? void 0 : _d.call(options, result, null, variables, context);
-            return result;
-        }
-        catch (err) {
-            // Error - rollback optimistic update
-            const optimisticError = err instanceof MutationError ? err : normalizeOptimisticError(err);
-            isOptimisticRef.current = false;
-            setIsOptimistic(false);
-            setError(optimisticError);
-            setStatus("error");
-            setIsRolledBack(true);
-            (_e = options.onError) === null || _e === void 0 ? void 0 : _e.call(options, optimisticError, variables, context);
-            (_f = options.onSettled) === null || _f === void 0 ? void 0 : _f.call(options, undefined, optimisticError, variables, context);
-            throw optimisticError;
-        }
-    }, [isOnline, options, actionQueue, mutationFn, executeMutation]);
-    /**
-     * Fire-and-forget mutation
-     */
-    const mutate = useCallback((variables) => {
-        mutateAsync(variables).catch(() => {
-            // Error already handled in mutateAsync
-        });
-    }, [mutateAsync]);
-    return {
-        mutate,
-        mutateAsync,
-        data,
-        error,
-        status,
-        isIdle: status === "idle",
-        isPending: status === "pending",
-        isOptimistic,
-        isSuccess: status === "success",
-        isError: status === "error",
-        isRolledBack,
-        isQueued,
-        reset,
-    };
-}
-
-export { useOptimisticMutation };

package/dist/hooks/usePresence.d.ts

@@ -1,88 +0,0 @@
-/**
- * usePresence Hook
- *
- * Custom hook for accessing presence state and controls.
- * Wraps usePresenceContext with additional features like filtering.
- *
- * @example
- * ```tsx
- * function CustomPresenceUI() {
- *   const { users, typingUsers, isConnected, startTyping } = usePresence();
- *
- *   return (
- *     <div>
- *       <h2>{users.length} users online</h2>
- *       {typingUsers.length > 0 && <p>Someone is typing...</p>}
- *     </div>
- *   );
- * }
- * ```
- */
-import { PresenceUser, TypingUser, ConnectionStatus } from "../components/ai/PresenceProvider/PresenceProvider.types";
-/**
- * Options for usePresence hook
- */
-export interface UsePresenceOptions {
-    /** Filter users */
-    filter?: (user: PresenceUser) => boolean;
-}
-/**
- * Return value from usePresence hook
- */
-export interface UsePresenceReturn {
-    /** All users in channel (filtered if filter provided) */
-    users: PresenceUser[];
-    /** All users (unfiltered) */
-    allUsers: 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;
-}
-/**
- * Hook for accessing presence state and controls
- *
- * @param options - Hook options (filtering, etc.)
- * @returns Presence state and control functions
- *
- * @throws Error if used outside PresenceProvider
- *
- * @example
- * ```tsx
- * // Basic usage
- * const { users, isConnected } = usePresence();
- *
- * // With filtering (online users only)
- * const { users } = usePresence({
- *   filter: (user) => user.status === 'online',
- * });
- *
- * // Typing controls
- * const { startTyping, stopTyping } = usePresence();
- * const handleInputChange = () => {
- *   startTyping();
- *   setTimeout(stopTyping, 3000);
- * };
- * ```
- */
-export declare function usePresence(options?: UsePresenceOptions): UsePresenceReturn;

package/dist/utils/presenceUtils.d.ts

@@ -1,66 +0,0 @@
-/**
- * Presence Utilities
- *
- * Helper functions for formatting presence and typing indicators.
- */
-import { PresenceUser, TypingUser } from "../components/ai/PresenceProvider/PresenceProvider.types";
-/**
- * Format typing users into human-readable text
- *
- * @param users - Array of users currently typing
- * @param maxVisible - Maximum users to show by name (default: 3)
- * @returns Formatted text like "Alice is typing..." or "3 people are typing..."
- *
- * @example
- * formatTypingText([{ id: '1', name: 'Alice' }]) // "Alice is typing..."
- * formatTypingText([{ id: '1', name: 'Alice' }, { id: '2', name: 'Bob' }]) // "Alice and Bob are typing..."
- * formatTypingText([...4 users...]) // "Alice, Bob, Charlie, and 1 other are typing..."
- */
-export declare function formatTypingText(users: TypingUser[], maxVisible?: number): string;
-/**
- * Format presence count into human-readable text
- *
- * @param count - Number of users online
- * @returns Formatted text like "5 users online" or "1 user online"
- *
- * @example
- * formatPresenceCount(1) // "1 user online"
- * formatPresenceCount(5) // "5 users online"
- */
-export declare function formatPresenceCount(count: number): string;
-/**
- * Validate presence user data
- * Type guard to ensure object conforms to PresenceUser interface
- *
- * @param user - Unknown object to validate
- * @returns True if valid PresenceUser
- *
- * @example
- * const data = await fetchUserData();
- * if (validatePresenceUser(data)) {
- *   // TypeScript knows data is PresenceUser
- *   console.log(data.name);
- * }
- */
-export declare function validatePresenceUser(user: unknown): user is PresenceUser;
-/**
- * Validate typing user data
- * Type guard to ensure object conforms to TypingUser interface
- *
- * @param user - Unknown object to validate
- * @returns True if valid TypingUser
- */
-export declare function validateTypingUser(user: unknown): user is TypingUser;
-/**
- * Sort presence users by various criteria
- *
- * @param users - Array of users to sort
- * @param sortBy - Sort criteria or custom comparator
- * @returns Sorted array (does not mutate original)
- *
- * @example
- * sortUsers(users, 'name') // Sort alphabetically by name
- * sortUsers(users, 'joinedAt') // Sort by join time (newest first)
- * sortUsers(users, (a, b) => a.metadata.score - b.metadata.score) // Custom sort
- */
-export declare function sortUsers(users: PresenceUser[], sortBy: "name" | "joinedAt" | "status" | ((a: PresenceUser, b: PresenceUser) => number)): PresenceUser[];

package/dist/utils/presenceUtils.js

@@ -1,107 +0,0 @@
-/**
- * Presence Utilities
- *
- * Helper functions for formatting presence and typing indicators.
- */
-/**
- * Format typing users into human-readable text
- *
- * @param users - Array of users currently typing
- * @param maxVisible - Maximum users to show by name (default: 3)
- * @returns Formatted text like "Alice is typing..." or "3 people are typing..."
- *
- * @example
- * formatTypingText([{ id: '1', name: 'Alice' }]) // "Alice is typing..."
- * formatTypingText([{ id: '1', name: 'Alice' }, { id: '2', name: 'Bob' }]) // "Alice and Bob are typing..."
- * formatTypingText([...4 users...]) // "Alice, Bob, Charlie, and 1 other are typing..."
- */
-function formatTypingText(users, maxVisible = 3) {
-    const count = users.length;
-    if (count === 0) {
-        return "";
-    }
-    if (count === 1) {
-        return `${users[0].name} is typing...`;
-    }
-    if (count === 2) {
-        return `${users[0].name} and ${users[1].name} are typing...`;
-    }
-    // 3 or more users
-    if (count <= maxVisible) {
-        const names = users
-            .slice(0, count - 1)
-            .map((u) => u.name)
-            .join(", ");
-        const lastName = users[count - 1].name;
-        return `${names}, and ${lastName} are typing...`;
-    }
-    // More than maxVisible users
-    const visibleNames = users
-        .slice(0, maxVisible)
-        .map((u) => u.name)
-        .join(", ");
-    const remaining = count - maxVisible;
-    return `${visibleNames}, and ${remaining} ${remaining === 1 ? "other" : "others"} are typing...`;
-}
-/**
- * Format presence count into human-readable text
- *
- * @param count - Number of users online
- * @returns Formatted text like "5 users online" or "1 user online"
- *
- * @example
- * formatPresenceCount(1) // "1 user online"
- * formatPresenceCount(5) // "5 users online"
- */
-function formatPresenceCount(count) {
-    if (count === 0) {
-        return "No users online";
-    }
-    if (count === 1) {
-        return "1 user online";
-    }
-    return `${count} users online`;
-}
-/**
- * Sort presence users by various criteria
- *
- * @param users - Array of users to sort
- * @param sortBy - Sort criteria or custom comparator
- * @returns Sorted array (does not mutate original)
- *
- * @example
- * sortUsers(users, 'name') // Sort alphabetically by name
- * sortUsers(users, 'joinedAt') // Sort by join time (newest first)
- * sortUsers(users, (a, b) => a.metadata.score - b.metadata.score) // Custom sort
- */
-function sortUsers(users, sortBy) {
-    const sorted = [...users]; // Don't mutate original
-    if (typeof sortBy === "function") {
-        return sorted.sort(sortBy);
-    }
-    switch (sortBy) {
-        case "name":
-            return sorted.sort((a, b) => a.name.localeCompare(b.name));
-        case "joinedAt":
-            return sorted.sort((a, b) => {
-                var _a, _b, _c, _d;
-                const aTime = (_b = (_a = a.joinedAt) === null || _a === void 0 ? void 0 : _a.getTime()) !== null && _b !== void 0 ? _b : 0;
-                const bTime = (_d = (_c = b.joinedAt) === null || _c === void 0 ? void 0 : _c.getTime()) !== null && _d !== void 0 ? _d : 0;
-                return bTime - aTime; // Newest first
-            });
-        case "status": {
-            // Order: online > busy > away > offline
-            const statusOrder = { online: 0, busy: 1, away: 2, offline: 3 };
-            return sorted.sort((a, b) => {
-                var _a, _b;
-                const aOrder = statusOrder[(_a = a.status) !== null && _a !== void 0 ? _a : "offline"];
-                const bOrder = statusOrder[(_b = b.status) !== null && _b !== void 0 ? _b : "offline"];
-                return aOrder - bOrder;
-            });
-        }
-        default:
-            return sorted;
-    }
-}
-
-export { formatPresenceCount, formatTypingText, sortUsers };