@rencar-dev/feature-modules-public 0.0.7

package/dist/presence/index.d.cts

@@ -0,0 +1,231 @@
+import { Socket } from 'socket.io-client';
+
+/**
+ * Presence User Type
+ */
+type PresenceUser = {
+    userId: string;
+    name: string;
+    [key: string]: unknown;
+};
+/**
+ * Socket configuration
+ */
+type PresenceConfig = {
+    url: string;
+    transports?: ("websocket" | "polling")[];
+};
+/**
+ * usePresence hook options
+ */
+type UsePresenceOptions = {
+    /** Room identifier to join */
+    roomId: string;
+    /** Current user info to broadcast */
+    currentUser: PresenceUser;
+    /** Enable/disable the hook (default: true) */
+    enabled?: boolean;
+    /** Heartbeat interval in ms (default: 10 minutes) */
+    heartbeatInterval?: number;
+};
+/**
+ * usePresenceWatch hook options
+ */
+type UsePresenceWatchOptions = {
+    /** Room IDs to watch */
+    roomIds: string[];
+    /** Enable/disable the hook (default: true) */
+    enabled?: boolean;
+};
+/**
+ * usePresenceAvatarsState hook options
+ */
+type UsePresenceAvatarsStateOptions = {
+    /** List of presence users */
+    users: PresenceUser[];
+    /** Maximum visible avatars (default: 3) */
+    maxVisible?: number;
+};
+/**
+ * usePresenceAvatarsState return type
+ */
+type UsePresenceAvatarsStateReturn = {
+    visibleUsers: PresenceUser[];
+    moreCount: number;
+    hoveredUser: PresenceUser | null;
+    hoveredIndex: number | null;
+    setHoveredIndex: (index: number | null) => void;
+    getInitial: (user: PresenceUser) => string;
+    getZIndex: (index: number, isHovered: boolean) => number;
+};
+/**
+ * usePresenceFloatingState hook options
+ */
+type UsePresenceFloatingStateOptions = {
+    /** List of presence users */
+    users: PresenceUser[];
+    /** Maximum visible avatars (default: 8) */
+    maxVisible?: number;
+    /** Initial position */
+    initialPosition?: {
+        top: number;
+    };
+};
+/**
+ * usePresenceFloatingState return type
+ */
+type UsePresenceFloatingStateReturn = {
+    containerRef: React.RefObject<HTMLDivElement | null>;
+    position: {
+        top: number;
+        left: number;
+    };
+    isDragging: boolean;
+    hasDragged: boolean;
+    inlineStyle: React.CSSProperties;
+    visibleUsers: PresenceUser[];
+    moreCount: number;
+    hoveredUser: PresenceUser | null;
+    tooltipTop: number;
+    onMouseDownHeader: (e: React.MouseEvent) => void;
+    onTouchStartHeader: (e: React.TouchEvent) => void;
+    onAvatarEnter: (e: React.MouseEvent, user: PresenceUser) => void;
+    onAvatarLeave: () => void;
+};
+
+/**
+ * Initialize the presence socket with configuration
+ * Must be called before using any presence hooks
+ */
+declare function initPresenceSocket(presenceConfig: PresenceConfig): void;
+/**
+ * Get the shared socket instance
+ * @throws Error if socket is not initialized
+ */
+declare function getPresenceSocket(): Socket;
+/**
+ * Disconnect and cleanup the socket connection
+ */
+declare function disconnectPresenceSocket(): void;
+/**
+ * Check if socket is initialized
+ */
+declare function isPresenceSocketInitialized(): boolean;
+
+/**
+ * Hook to join a presence room and track users in that room
+ *
+ * @param options - Configuration options
+ * @returns Array of users currently in the room
+ *
+ * @example
+ * ```tsx
+ * const users = usePresence({
+ *   roomId: 'my-app:page-123',
+ *   currentUser: { userId: '1', name: 'John' },
+ * });
+ * ```
+ */
+declare function usePresence(options: UsePresenceOptions): PresenceUser[];
+
+/**
+ * Hook to watch multiple rooms without joining them
+ * (read-only observation, current user is not added to the rooms)
+ *
+ * @param options - Configuration options
+ * @returns Map of roomId to array of users in that room
+ *
+ * @example
+ * ```tsx
+ * const roomsUsers = usePresenceWatch({
+ *   roomIds: ['room-1', 'room-2', 'room-3'],
+ * });
+ * // roomsUsers = { 'room-1': [...], 'room-2': [...], ... }
+ * ```
+ */
+declare function usePresenceWatch(options: UsePresenceWatchOptions): Record<string, PresenceUser[]>;
+
+/**
+ * Headless hook for presence avatars UI state management
+ *
+ * This hook provides all the state and logic needed to build
+ * a presence avatars component without any styling.
+ *
+ * @param options - Configuration options
+ * @returns State and handlers for building presence avatars UI
+ *
+ * @example
+ * ```tsx
+ * const {
+ *   visibleUsers,
+ *   moreCount,
+ *   hoveredUser,
+ *   setHoveredIndex,
+ *   getInitial,
+ *   getZIndex,
+ * } = usePresenceAvatarsState({ users, maxVisible: 3 });
+ *
+ * return (
+ *   <div>
+ *     {visibleUsers.map((user, idx) => (
+ *       <span
+ *         key={user.userId}
+ *         style={{ zIndex: getZIndex(idx, hoveredUser?.userId === user.userId) }}
+ *         onMouseEnter={() => setHoveredIndex(idx)}
+ *         onMouseLeave={() => setHoveredIndex(null)}
+ *       >
+ *         {getInitial(user)}
+ *       </span>
+ *     ))}
+ *     {moreCount > 0 && <span>+{moreCount}</span>}
+ *   </div>
+ * );
+ * ```
+ */
+declare function usePresenceAvatarsState(options: UsePresenceAvatarsStateOptions): UsePresenceAvatarsStateReturn;
+
+/**
+ * Headless hook for presence floating UI state management
+ *
+ * This hook provides all the state and logic needed to build
+ * a draggable floating presence panel without any styling.
+ *
+ * @param options - Configuration options
+ * @returns State and handlers for building floating presence UI
+ *
+ * @example
+ * ```tsx
+ * const {
+ *   containerRef,
+ *   inlineStyle,
+ *   isDragging,
+ *   visibleUsers,
+ *   moreCount,
+ *   hoveredUser,
+ *   tooltipTop,
+ *   onMouseDownHeader,
+ *   onAvatarEnter,
+ *   onAvatarLeave,
+ * } = usePresenceFloatingState({ users, maxVisible: 8 });
+ *
+ * return (
+ *   <div ref={containerRef} style={inlineStyle} onMouseDown={onMouseDownHeader}>
+ *     <div className="header">열람중 {users.length}</div>
+ *     <div className="body">
+ *       {visibleUsers.map((user) => (
+ *         <span
+ *           key={user.userId}
+ *           onMouseEnter={(e) => onAvatarEnter(e, user)}
+ *           onMouseLeave={onAvatarLeave}
+ *         >
+ *           {user.name}
+ *         </span>
+ *       ))}
+ *     </div>
+ *   </div>
+ * );
+ * ```
+ */
+declare function usePresenceFloatingState(options: UsePresenceFloatingStateOptions): UsePresenceFloatingStateReturn;
+
+export { type PresenceConfig, type PresenceUser, type UsePresenceAvatarsStateOptions, type UsePresenceAvatarsStateReturn, type UsePresenceFloatingStateOptions, type UsePresenceFloatingStateReturn, type UsePresenceOptions, type UsePresenceWatchOptions, disconnectPresenceSocket, getPresenceSocket, initPresenceSocket, isPresenceSocketInitialized, usePresence, usePresenceAvatarsState, usePresenceFloatingState, usePresenceWatch };

package/dist/presence/index.d.ts

@@ -0,0 +1,231 @@
+import { Socket } from 'socket.io-client';
+
+/**
+ * Presence User Type
+ */
+type PresenceUser = {
+    userId: string;
+    name: string;
+    [key: string]: unknown;
+};
+/**
+ * Socket configuration
+ */
+type PresenceConfig = {
+    url: string;
+    transports?: ("websocket" | "polling")[];
+};
+/**
+ * usePresence hook options
+ */
+type UsePresenceOptions = {
+    /** Room identifier to join */
+    roomId: string;
+    /** Current user info to broadcast */
+    currentUser: PresenceUser;
+    /** Enable/disable the hook (default: true) */
+    enabled?: boolean;
+    /** Heartbeat interval in ms (default: 10 minutes) */
+    heartbeatInterval?: number;
+};
+/**
+ * usePresenceWatch hook options
+ */
+type UsePresenceWatchOptions = {
+    /** Room IDs to watch */
+    roomIds: string[];
+    /** Enable/disable the hook (default: true) */
+    enabled?: boolean;
+};
+/**
+ * usePresenceAvatarsState hook options
+ */
+type UsePresenceAvatarsStateOptions = {
+    /** List of presence users */
+    users: PresenceUser[];
+    /** Maximum visible avatars (default: 3) */
+    maxVisible?: number;
+};
+/**
+ * usePresenceAvatarsState return type
+ */
+type UsePresenceAvatarsStateReturn = {
+    visibleUsers: PresenceUser[];
+    moreCount: number;
+    hoveredUser: PresenceUser | null;
+    hoveredIndex: number | null;
+    setHoveredIndex: (index: number | null) => void;
+    getInitial: (user: PresenceUser) => string;
+    getZIndex: (index: number, isHovered: boolean) => number;
+};
+/**
+ * usePresenceFloatingState hook options
+ */
+type UsePresenceFloatingStateOptions = {
+    /** List of presence users */
+    users: PresenceUser[];
+    /** Maximum visible avatars (default: 8) */
+    maxVisible?: number;
+    /** Initial position */
+    initialPosition?: {
+        top: number;
+    };
+};
+/**
+ * usePresenceFloatingState return type
+ */
+type UsePresenceFloatingStateReturn = {
+    containerRef: React.RefObject<HTMLDivElement | null>;
+    position: {
+        top: number;
+        left: number;
+    };
+    isDragging: boolean;
+    hasDragged: boolean;
+    inlineStyle: React.CSSProperties;
+    visibleUsers: PresenceUser[];
+    moreCount: number;
+    hoveredUser: PresenceUser | null;
+    tooltipTop: number;
+    onMouseDownHeader: (e: React.MouseEvent) => void;
+    onTouchStartHeader: (e: React.TouchEvent) => void;
+    onAvatarEnter: (e: React.MouseEvent, user: PresenceUser) => void;
+    onAvatarLeave: () => void;
+};
+
+/**
+ * Initialize the presence socket with configuration
+ * Must be called before using any presence hooks
+ */
+declare function initPresenceSocket(presenceConfig: PresenceConfig): void;
+/**
+ * Get the shared socket instance
+ * @throws Error if socket is not initialized
+ */
+declare function getPresenceSocket(): Socket;
+/**
+ * Disconnect and cleanup the socket connection
+ */
+declare function disconnectPresenceSocket(): void;
+/**
+ * Check if socket is initialized
+ */
+declare function isPresenceSocketInitialized(): boolean;
+
+/**
+ * Hook to join a presence room and track users in that room
+ *
+ * @param options - Configuration options
+ * @returns Array of users currently in the room
+ *
+ * @example
+ * ```tsx
+ * const users = usePresence({
+ *   roomId: 'my-app:page-123',
+ *   currentUser: { userId: '1', name: 'John' },
+ * });
+ * ```
+ */
+declare function usePresence(options: UsePresenceOptions): PresenceUser[];
+
+/**
+ * Hook to watch multiple rooms without joining them
+ * (read-only observation, current user is not added to the rooms)
+ *
+ * @param options - Configuration options
+ * @returns Map of roomId to array of users in that room
+ *
+ * @example
+ * ```tsx
+ * const roomsUsers = usePresenceWatch({
+ *   roomIds: ['room-1', 'room-2', 'room-3'],
+ * });
+ * // roomsUsers = { 'room-1': [...], 'room-2': [...], ... }
+ * ```
+ */
+declare function usePresenceWatch(options: UsePresenceWatchOptions): Record<string, PresenceUser[]>;
+
+/**
+ * Headless hook for presence avatars UI state management
+ *
+ * This hook provides all the state and logic needed to build
+ * a presence avatars component without any styling.
+ *
+ * @param options - Configuration options
+ * @returns State and handlers for building presence avatars UI
+ *
+ * @example
+ * ```tsx
+ * const {
+ *   visibleUsers,
+ *   moreCount,
+ *   hoveredUser,
+ *   setHoveredIndex,
+ *   getInitial,
+ *   getZIndex,
+ * } = usePresenceAvatarsState({ users, maxVisible: 3 });
+ *
+ * return (
+ *   <div>
+ *     {visibleUsers.map((user, idx) => (
+ *       <span
+ *         key={user.userId}
+ *         style={{ zIndex: getZIndex(idx, hoveredUser?.userId === user.userId) }}
+ *         onMouseEnter={() => setHoveredIndex(idx)}
+ *         onMouseLeave={() => setHoveredIndex(null)}
+ *       >
+ *         {getInitial(user)}
+ *       </span>
+ *     ))}
+ *     {moreCount > 0 && <span>+{moreCount}</span>}
+ *   </div>
+ * );
+ * ```
+ */
+declare function usePresenceAvatarsState(options: UsePresenceAvatarsStateOptions): UsePresenceAvatarsStateReturn;
+
+/**
+ * Headless hook for presence floating UI state management
+ *
+ * This hook provides all the state and logic needed to build
+ * a draggable floating presence panel without any styling.
+ *
+ * @param options - Configuration options
+ * @returns State and handlers for building floating presence UI
+ *
+ * @example
+ * ```tsx
+ * const {
+ *   containerRef,
+ *   inlineStyle,
+ *   isDragging,
+ *   visibleUsers,
+ *   moreCount,
+ *   hoveredUser,
+ *   tooltipTop,
+ *   onMouseDownHeader,
+ *   onAvatarEnter,
+ *   onAvatarLeave,
+ * } = usePresenceFloatingState({ users, maxVisible: 8 });
+ *
+ * return (
+ *   <div ref={containerRef} style={inlineStyle} onMouseDown={onMouseDownHeader}>
+ *     <div className="header">열람중 {users.length}</div>
+ *     <div className="body">
+ *       {visibleUsers.map((user) => (
+ *         <span
+ *           key={user.userId}
+ *           onMouseEnter={(e) => onAvatarEnter(e, user)}
+ *           onMouseLeave={onAvatarLeave}
+ *         >
+ *           {user.name}
+ *         </span>
+ *       ))}
+ *     </div>
+ *   </div>
+ * );
+ * ```
+ */
+declare function usePresenceFloatingState(options: UsePresenceFloatingStateOptions): UsePresenceFloatingStateReturn;
+
+export { type PresenceConfig, type PresenceUser, type UsePresenceAvatarsStateOptions, type UsePresenceAvatarsStateReturn, type UsePresenceFloatingStateOptions, type UsePresenceFloatingStateReturn, type UsePresenceOptions, type UsePresenceWatchOptions, disconnectPresenceSocket, getPresenceSocket, initPresenceSocket, isPresenceSocketInitialized, usePresence, usePresenceAvatarsState, usePresenceFloatingState, usePresenceWatch };