@rencar-dev/feature-modules-public 1.2.2 → 1.2.3

package/dist/presence/index.d.cts

@@ -16,6 +16,19 @@ type PresenceConfig = {
     url: string;
     transports?: ("websocket" | "polling")[];
 };
+/**
+ * PresenceProvider component props
+ */
+type PresenceProviderProps = {
+    /** Socket server URL */
+    url: string;
+    /** Transport methods (default: ['websocket']) */
+    transports?: ("websocket" | "polling")[];
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+    /** Children components */
+    children: React.ReactNode;
+};
 /**
  * usePresence hook options
  */
@@ -41,19 +54,19 @@ type UsePresenceWatchOptions = {
 /**
  * usePresenceAvatarsState hook options
  */
-type UsePresenceAvatarsStateOptions = {
+type UsePresenceAvatarsStateOptions<T extends PresenceUser = PresenceUser> = {
     /** List of presence users */
-    users: PresenceUser[];
+    users: T[];
     /** Maximum visible avatars (default: 3) */
     maxVisible?: number;
 };
 /**
  * usePresenceAvatarsState return type
  */
-type UsePresenceAvatarsStateReturn = {
-    visibleUsers: PresenceUser[];
+type UsePresenceAvatarsStateReturn<T extends PresenceUser = PresenceUser> = {
+    visibleUsers: T[];
     moreCount: number;
-    hoveredUser: PresenceUser | null;
+    hoveredUser: T | null;
     hoveredIndex: number | null;
     setHoveredIndex: (index: number | null) => void;
     getInitial: (user: PresenceUser) => string;
@@ -62,9 +75,9 @@ type UsePresenceAvatarsStateReturn = {
 /**
  * usePresenceFloatingState hook options
  */
-type UsePresenceFloatingStateOptions = {
+type UsePresenceFloatingStateOptions<T extends PresenceUser = PresenceUser> = {
     /** List of presence users */
-    users: PresenceUser[];
+    users: T[];
     /** Maximum visible avatars (default: 8) */
     maxVisible?: number;
     /** Initial position */
@@ -75,7 +88,7 @@ type UsePresenceFloatingStateOptions = {
 /**
  * usePresenceFloatingState return type
  */
-type UsePresenceFloatingStateReturn = {
+type UsePresenceFloatingStateReturn<T extends PresenceUser = PresenceUser> = {
     containerRef: React.RefObject<HTMLDivElement | null>;
     position: {
         top: number;
@@ -84,20 +97,20 @@ type UsePresenceFloatingStateReturn = {
     isDragging: boolean;
     hasDragged: boolean;
     inlineStyle: React.CSSProperties;
-    visibleUsers: PresenceUser[];
+    visibleUsers: T[];
     moreCount: number;
-    hoveredUser: PresenceUser | null;
+    hoveredUser: T | null;
     tooltipTop: number;
     onMouseDownHeader: (e: React.MouseEvent) => void;
     onTouchStartHeader: (e: React.TouchEvent) => void;
-    onAvatarEnter: (e: React.MouseEvent, user: PresenceUser) => void;
+    onAvatarEnter: (e: React.MouseEvent, user: T) => void;
     onAvatarLeave: () => void;
 };
 /**
  * Render props for individual avatar in PresenceAvatars
  */
-type PresenceAvatarRenderProps = {
-    user: PresenceUser;
+type PresenceAvatarRenderProps<T extends PresenceUser = PresenceUser> = {
+    user: T;
     index: number;
     initial: string;
     isHovered: boolean;
@@ -106,8 +119,8 @@ type PresenceAvatarRenderProps = {
 /**
  * Render props for tooltip in PresenceAvatars
  */
-type PresenceAvatarsTooltipRenderProps = {
-    user: PresenceUser;
+type PresenceAvatarsTooltipRenderProps<T extends PresenceUser = PresenceUser> = {
+    user: T;
     position: {
         top: number;
         left: number;
@@ -116,40 +129,40 @@ type PresenceAvatarsTooltipRenderProps = {
 /**
  * Props for PresenceAvatars component
  */
-type PresenceAvatarsProps = {
+type PresenceAvatarsProps<T extends PresenceUser = PresenceUser> = {
     /** List of presence users */
-    users: PresenceUser[];
+    users: T[];
     /** Maximum visible avatars (default: 3) */
     maxVisible?: number;
     /** Additional CSS class */
     className?: string;
     /** Custom avatar renderer */
-    renderAvatar?: (props: PresenceAvatarRenderProps) => React.ReactNode;
+    renderAvatar?: (props: PresenceAvatarRenderProps<T>) => React.ReactNode;
     /** Custom tooltip renderer */
-    renderTooltip?: (props: PresenceAvatarsTooltipRenderProps) => React.ReactNode;
+    renderTooltip?: (props: PresenceAvatarsTooltipRenderProps<T>) => React.ReactNode;
     /** Custom "more" badge renderer */
     renderMore?: (count: number) => React.ReactNode;
 };
 /**
  * Render props for individual avatar in PresenceFloating
  */
-type PresenceFloatingAvatarRenderProps = {
-    user: PresenceUser;
+type PresenceFloatingAvatarRenderProps<T extends PresenceUser = PresenceUser> = {
+    user: T;
     initial: string;
 };
 /**
  * Render props for tooltip in PresenceFloating
  */
-type PresenceFloatingTooltipRenderProps = {
-    user: PresenceUser;
+type PresenceFloatingTooltipRenderProps<T extends PresenceUser = PresenceUser> = {
+    user: T;
     top: number;
 };
 /**
  * Props for PresenceFloating component
  */
-type PresenceFloatingProps = {
+type PresenceFloatingProps<T extends PresenceUser = PresenceUser> = {
     /** List of presence users */
-    users: PresenceUser[];
+    users: T[];
     /** Maximum visible avatars (default: 8) */
     maxVisible?: number;
     /** Additional CSS class */
@@ -167,9 +180,9 @@ type PresenceFloatingProps = {
     /** More count text formatter (default: (n) => `+${n}명`) */
     moreText?: (count: number) => string;
     /** Custom avatar renderer */
-    renderAvatar?: (props: PresenceFloatingAvatarRenderProps) => React.ReactNode;
+    renderAvatar?: (props: PresenceFloatingAvatarRenderProps<T>) => React.ReactNode;
     /** Custom tooltip renderer */
-    renderTooltip?: (props: PresenceFloatingTooltipRenderProps) => React.ReactNode;
+    renderTooltip?: (props: PresenceFloatingTooltipRenderProps<T>) => React.ReactNode;
 };
 
 /**
@@ -261,7 +274,7 @@ declare function usePresenceWatch(options: UsePresenceWatchOptions): Record<stri
  * );
  * ```
  */
-declare function usePresenceAvatarsState(options: UsePresenceAvatarsStateOptions): UsePresenceAvatarsStateReturn;
+declare function usePresenceAvatarsState<T extends PresenceUser = PresenceUser>(options: UsePresenceAvatarsStateOptions<T>): UsePresenceAvatarsStateReturn<T>;
 
 /**
  * Headless hook for presence floating UI state management
@@ -305,7 +318,7 @@ declare function usePresenceAvatarsState(options: UsePresenceAvatarsStateOptions
  * );
  * ```
  */
-declare function usePresenceFloatingState(options: UsePresenceFloatingStateOptions): UsePresenceFloatingStateReturn;
+declare function usePresenceFloatingState<T extends PresenceUser = PresenceUser>(options: UsePresenceFloatingStateOptions<T>): UsePresenceFloatingStateReturn<T>;
 
 /**
  * PresenceAvatars - Displays a stack of user avatars with hover tooltips
@@ -334,7 +347,7 @@ declare function usePresenceFloatingState(options: UsePresenceFloatingStateOptio
  * />
  * ```
  */
-declare function PresenceAvatars({ users, maxVisible, className, renderAvatar, renderTooltip, renderMore, }: PresenceAvatarsProps): react_jsx_runtime.JSX.Element;
+declare function PresenceAvatars<T extends PresenceUser = PresenceUser>({ users, maxVisible, className, renderAvatar, renderTooltip, renderMore, }: PresenceAvatarsProps<T>): react_jsx_runtime.JSX.Element;
 
 /**
  * PresenceFloating - Draggable floating panel showing presence users
@@ -361,6 +374,67 @@ declare function PresenceAvatars({ users, maxVisible, className, renderAvatar, r
  * />
  * ```
  */
-declare function PresenceFloating({ users, maxVisible, className, style, initialPosition, title, emptyText, moreText, renderAvatar, renderTooltip, }: PresenceFloatingProps): react_jsx_runtime.JSX.Element;
+declare function PresenceFloating<T extends PresenceUser = PresenceUser>({ users, maxVisible, className, style, initialPosition, title, emptyText, moreText, renderAvatar, renderTooltip, }: PresenceFloatingProps<T>): react_jsx_runtime.JSX.Element;
+
+/**
+ * Presence Context value type
+ */
+type PresenceContextValue = {
+    /** Whether the socket is initialized */
+    isInitialized: boolean;
+    /** Current connection status */
+    status: "connecting" | "connected" | "disconnected";
+};
+/**
+ * PresenceProvider - Manages socket initialization lifecycle
+ *
+ * Wrap your app with this provider to automatically initialize
+ * and cleanup the presence socket connection.
+ *
+ * @example
+ * ```tsx
+ * // In your app entry point
+ * import { PresenceProvider } from '@rencar-dev/feature-modules-public';
+ *
+ * function App() {
+ *   return (
+ *     <PresenceProvider url="https://socket.example.com">
+ *       <MyApp />
+ *     </PresenceProvider>
+ *   );
+ * }
+ *
+ * // In child components, hooks work automatically
+ * function MyComponent() {
+ *   const users = usePresence({ roomId: 'room-1', currentUser });
+ *   return <PresenceFloating users={users} />;
+ * }
+ * ```
+ */
+declare function PresenceProvider({ url, transports, debug, children, }: PresenceProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access presence connection status
+ *
+ * @returns Connection status object or null if not inside PresenceProvider
+ *
+ * @example
+ * ```tsx
+ * function StatusIndicator() {
+ *   const presence = usePresenceStatus();
+ *
+ *   if (!presence) {
+ *     return <span>Not initialized</span>;
+ *   }
+ *
+ *   return (
+ *     <span>
+ *       Status: {presence.status}
+ *       {presence.status === 'connecting' && <Spinner />}
+ *     </span>
+ *   );
+ * }
+ * ```
+ */
+declare function usePresenceStatus(): PresenceContextValue | null;
 
-export { type PresenceAvatarRenderProps, PresenceAvatars, type PresenceAvatarsProps, type PresenceAvatarsTooltipRenderProps, type PresenceConfig, PresenceFloating, type PresenceFloatingAvatarRenderProps, type PresenceFloatingProps, type PresenceFloatingTooltipRenderProps, type PresenceUser, type UsePresenceAvatarsStateOptions, type UsePresenceAvatarsStateReturn, type UsePresenceFloatingStateOptions, type UsePresenceFloatingStateReturn, type UsePresenceOptions, type UsePresenceWatchOptions, disconnectPresenceSocket, getPresenceSocket, initPresenceSocket, isPresenceSocketInitialized, usePresence, usePresenceAvatarsState, usePresenceFloatingState, usePresenceWatch };
+export { type PresenceAvatarRenderProps, PresenceAvatars, type PresenceAvatarsProps, type PresenceAvatarsTooltipRenderProps, type PresenceConfig, PresenceFloating, type PresenceFloatingAvatarRenderProps, type PresenceFloatingProps, type PresenceFloatingTooltipRenderProps, PresenceProvider, type PresenceProviderProps, type PresenceUser, type UsePresenceAvatarsStateOptions, type UsePresenceAvatarsStateReturn, type UsePresenceFloatingStateOptions, type UsePresenceFloatingStateReturn, type UsePresenceOptions, type UsePresenceWatchOptions, disconnectPresenceSocket, getPresenceSocket, initPresenceSocket, isPresenceSocketInitialized, usePresence, usePresenceAvatarsState, usePresenceFloatingState, usePresenceStatus, usePresenceWatch };

package/dist/presence/index.d.ts

@@ -16,6 +16,19 @@ type PresenceConfig = {
     url: string;
     transports?: ("websocket" | "polling")[];
 };
+/**
+ * PresenceProvider component props
+ */
+type PresenceProviderProps = {
+    /** Socket server URL */
+    url: string;
+    /** Transport methods (default: ['websocket']) */
+    transports?: ("websocket" | "polling")[];
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+    /** Children components */
+    children: React.ReactNode;
+};
 /**
  * usePresence hook options
  */
@@ -41,19 +54,19 @@ type UsePresenceWatchOptions = {
 /**
  * usePresenceAvatarsState hook options
  */
-type UsePresenceAvatarsStateOptions = {
+type UsePresenceAvatarsStateOptions<T extends PresenceUser = PresenceUser> = {
     /** List of presence users */
-    users: PresenceUser[];
+    users: T[];
     /** Maximum visible avatars (default: 3) */
     maxVisible?: number;
 };
 /**
  * usePresenceAvatarsState return type
  */
-type UsePresenceAvatarsStateReturn = {
-    visibleUsers: PresenceUser[];
+type UsePresenceAvatarsStateReturn<T extends PresenceUser = PresenceUser> = {
+    visibleUsers: T[];
     moreCount: number;
-    hoveredUser: PresenceUser | null;
+    hoveredUser: T | null;
     hoveredIndex: number | null;
     setHoveredIndex: (index: number | null) => void;
     getInitial: (user: PresenceUser) => string;
@@ -62,9 +75,9 @@ type UsePresenceAvatarsStateReturn = {
 /**
  * usePresenceFloatingState hook options
  */
-type UsePresenceFloatingStateOptions = {
+type UsePresenceFloatingStateOptions<T extends PresenceUser = PresenceUser> = {
     /** List of presence users */
-    users: PresenceUser[];
+    users: T[];
     /** Maximum visible avatars (default: 8) */
     maxVisible?: number;
     /** Initial position */
@@ -75,7 +88,7 @@ type UsePresenceFloatingStateOptions = {
 /**
  * usePresenceFloatingState return type
  */
-type UsePresenceFloatingStateReturn = {
+type UsePresenceFloatingStateReturn<T extends PresenceUser = PresenceUser> = {
     containerRef: React.RefObject<HTMLDivElement | null>;
     position: {
         top: number;
@@ -84,20 +97,20 @@ type UsePresenceFloatingStateReturn = {
     isDragging: boolean;
     hasDragged: boolean;
     inlineStyle: React.CSSProperties;
-    visibleUsers: PresenceUser[];
+    visibleUsers: T[];
     moreCount: number;
-    hoveredUser: PresenceUser | null;
+    hoveredUser: T | null;
     tooltipTop: number;
     onMouseDownHeader: (e: React.MouseEvent) => void;
     onTouchStartHeader: (e: React.TouchEvent) => void;
-    onAvatarEnter: (e: React.MouseEvent, user: PresenceUser) => void;
+    onAvatarEnter: (e: React.MouseEvent, user: T) => void;
     onAvatarLeave: () => void;
 };
 /**
  * Render props for individual avatar in PresenceAvatars
  */
-type PresenceAvatarRenderProps = {
-    user: PresenceUser;
+type PresenceAvatarRenderProps<T extends PresenceUser = PresenceUser> = {
+    user: T;
     index: number;
     initial: string;
     isHovered: boolean;
@@ -106,8 +119,8 @@ type PresenceAvatarRenderProps = {
 /**
  * Render props for tooltip in PresenceAvatars
  */
-type PresenceAvatarsTooltipRenderProps = {
-    user: PresenceUser;
+type PresenceAvatarsTooltipRenderProps<T extends PresenceUser = PresenceUser> = {
+    user: T;
     position: {
         top: number;
         left: number;
@@ -116,40 +129,40 @@ type PresenceAvatarsTooltipRenderProps = {
 /**
  * Props for PresenceAvatars component
  */
-type PresenceAvatarsProps = {
+type PresenceAvatarsProps<T extends PresenceUser = PresenceUser> = {
     /** List of presence users */
-    users: PresenceUser[];
+    users: T[];
     /** Maximum visible avatars (default: 3) */
     maxVisible?: number;
     /** Additional CSS class */
     className?: string;
     /** Custom avatar renderer */
-    renderAvatar?: (props: PresenceAvatarRenderProps) => React.ReactNode;
+    renderAvatar?: (props: PresenceAvatarRenderProps<T>) => React.ReactNode;
     /** Custom tooltip renderer */
-    renderTooltip?: (props: PresenceAvatarsTooltipRenderProps) => React.ReactNode;
+    renderTooltip?: (props: PresenceAvatarsTooltipRenderProps<T>) => React.ReactNode;
     /** Custom "more" badge renderer */
     renderMore?: (count: number) => React.ReactNode;
 };
 /**
  * Render props for individual avatar in PresenceFloating
  */
-type PresenceFloatingAvatarRenderProps = {
-    user: PresenceUser;
+type PresenceFloatingAvatarRenderProps<T extends PresenceUser = PresenceUser> = {
+    user: T;
     initial: string;
 };
 /**
  * Render props for tooltip in PresenceFloating
  */
-type PresenceFloatingTooltipRenderProps = {
-    user: PresenceUser;
+type PresenceFloatingTooltipRenderProps<T extends PresenceUser = PresenceUser> = {
+    user: T;
     top: number;
 };
 /**
  * Props for PresenceFloating component
  */
-type PresenceFloatingProps = {
+type PresenceFloatingProps<T extends PresenceUser = PresenceUser> = {
     /** List of presence users */
-    users: PresenceUser[];
+    users: T[];
     /** Maximum visible avatars (default: 8) */
     maxVisible?: number;
     /** Additional CSS class */
@@ -167,9 +180,9 @@ type PresenceFloatingProps = {
     /** More count text formatter (default: (n) => `+${n}명`) */
     moreText?: (count: number) => string;
     /** Custom avatar renderer */
-    renderAvatar?: (props: PresenceFloatingAvatarRenderProps) => React.ReactNode;
+    renderAvatar?: (props: PresenceFloatingAvatarRenderProps<T>) => React.ReactNode;
     /** Custom tooltip renderer */
-    renderTooltip?: (props: PresenceFloatingTooltipRenderProps) => React.ReactNode;
+    renderTooltip?: (props: PresenceFloatingTooltipRenderProps<T>) => React.ReactNode;
 };
 
 /**
@@ -261,7 +274,7 @@ declare function usePresenceWatch(options: UsePresenceWatchOptions): Record<stri
  * );
  * ```
  */
-declare function usePresenceAvatarsState(options: UsePresenceAvatarsStateOptions): UsePresenceAvatarsStateReturn;
+declare function usePresenceAvatarsState<T extends PresenceUser = PresenceUser>(options: UsePresenceAvatarsStateOptions<T>): UsePresenceAvatarsStateReturn<T>;
 
 /**
  * Headless hook for presence floating UI state management
@@ -305,7 +318,7 @@ declare function usePresenceAvatarsState(options: UsePresenceAvatarsStateOptions
  * );
  * ```
  */
-declare function usePresenceFloatingState(options: UsePresenceFloatingStateOptions): UsePresenceFloatingStateReturn;
+declare function usePresenceFloatingState<T extends PresenceUser = PresenceUser>(options: UsePresenceFloatingStateOptions<T>): UsePresenceFloatingStateReturn<T>;
 
 /**
  * PresenceAvatars - Displays a stack of user avatars with hover tooltips
@@ -334,7 +347,7 @@ declare function usePresenceFloatingState(options: UsePresenceFloatingStateOptio
  * />
  * ```
  */
-declare function PresenceAvatars({ users, maxVisible, className, renderAvatar, renderTooltip, renderMore, }: PresenceAvatarsProps): react_jsx_runtime.JSX.Element;
+declare function PresenceAvatars<T extends PresenceUser = PresenceUser>({ users, maxVisible, className, renderAvatar, renderTooltip, renderMore, }: PresenceAvatarsProps<T>): react_jsx_runtime.JSX.Element;
 
 /**
  * PresenceFloating - Draggable floating panel showing presence users
@@ -361,6 +374,67 @@ declare function PresenceAvatars({ users, maxVisible, className, renderAvatar, r
  * />
  * ```
  */
-declare function PresenceFloating({ users, maxVisible, className, style, initialPosition, title, emptyText, moreText, renderAvatar, renderTooltip, }: PresenceFloatingProps): react_jsx_runtime.JSX.Element;
+declare function PresenceFloating<T extends PresenceUser = PresenceUser>({ users, maxVisible, className, style, initialPosition, title, emptyText, moreText, renderAvatar, renderTooltip, }: PresenceFloatingProps<T>): react_jsx_runtime.JSX.Element;
+
+/**
+ * Presence Context value type
+ */
+type PresenceContextValue = {
+    /** Whether the socket is initialized */
+    isInitialized: boolean;
+    /** Current connection status */
+    status: "connecting" | "connected" | "disconnected";
+};
+/**
+ * PresenceProvider - Manages socket initialization lifecycle
+ *
+ * Wrap your app with this provider to automatically initialize
+ * and cleanup the presence socket connection.
+ *
+ * @example
+ * ```tsx
+ * // In your app entry point
+ * import { PresenceProvider } from '@rencar-dev/feature-modules-public';
+ *
+ * function App() {
+ *   return (
+ *     <PresenceProvider url="https://socket.example.com">
+ *       <MyApp />
+ *     </PresenceProvider>
+ *   );
+ * }
+ *
+ * // In child components, hooks work automatically
+ * function MyComponent() {
+ *   const users = usePresence({ roomId: 'room-1', currentUser });
+ *   return <PresenceFloating users={users} />;
+ * }
+ * ```
+ */
+declare function PresenceProvider({ url, transports, debug, children, }: PresenceProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access presence connection status
+ *
+ * @returns Connection status object or null if not inside PresenceProvider
+ *
+ * @example
+ * ```tsx
+ * function StatusIndicator() {
+ *   const presence = usePresenceStatus();
+ *
+ *   if (!presence) {
+ *     return <span>Not initialized</span>;
+ *   }
+ *
+ *   return (
+ *     <span>
+ *       Status: {presence.status}
+ *       {presence.status === 'connecting' && <Spinner />}
+ *     </span>
+ *   );
+ * }
+ * ```
+ */
+declare function usePresenceStatus(): PresenceContextValue | null;
 
-export { type PresenceAvatarRenderProps, PresenceAvatars, type PresenceAvatarsProps, type PresenceAvatarsTooltipRenderProps, type PresenceConfig, PresenceFloating, type PresenceFloatingAvatarRenderProps, type PresenceFloatingProps, type PresenceFloatingTooltipRenderProps, type PresenceUser, type UsePresenceAvatarsStateOptions, type UsePresenceAvatarsStateReturn, type UsePresenceFloatingStateOptions, type UsePresenceFloatingStateReturn, type UsePresenceOptions, type UsePresenceWatchOptions, disconnectPresenceSocket, getPresenceSocket, initPresenceSocket, isPresenceSocketInitialized, usePresence, usePresenceAvatarsState, usePresenceFloatingState, usePresenceWatch };
+export { type PresenceAvatarRenderProps, PresenceAvatars, type PresenceAvatarsProps, type PresenceAvatarsTooltipRenderProps, type PresenceConfig, PresenceFloating, type PresenceFloatingAvatarRenderProps, type PresenceFloatingProps, type PresenceFloatingTooltipRenderProps, PresenceProvider, type PresenceProviderProps, type PresenceUser, type UsePresenceAvatarsStateOptions, type UsePresenceAvatarsStateReturn, type UsePresenceFloatingStateOptions, type UsePresenceFloatingStateReturn, type UsePresenceOptions, type UsePresenceWatchOptions, disconnectPresenceSocket, getPresenceSocket, initPresenceSocket, isPresenceSocketInitialized, usePresence, usePresenceAvatarsState, usePresenceFloatingState, usePresenceStatus, usePresenceWatch };