simple-support-chat 0.2.0 → 0.3.0

package/dist/client/index.d.cts

@@ -31,6 +31,36 @@ interface ChatBubbleProps {
     user?: ChatUser;
     /** URL to poll for team replies (e.g., '/api/support/replies'). Enables bidirectional chat. */
     repliesUrl?: string;
+    /**
+     * Controlled mode: when provided, overrides internal open/close state.
+     * The chat panel is open when `isOpen` is true, closed when false.
+     * Use together with `onOpenChange` to control the panel externally.
+     *
+     * When not provided, ChatBubble manages its own open/close state (uncontrolled mode).
+     *
+     * Note: `show` controls visibility of the floating button, `isOpen` controls the panel state.
+     * Both can be used together (e.g., `show={false}` + `isOpen={true}` = no bubble button but panel is open).
+     */
+    isOpen?: boolean;
+    /**
+     * Callback fired when the user attempts to change the open/close state.
+     * Called when the user clicks the bubble button, close button, or presses Escape.
+     * In controlled mode, you must update your state in response to this callback.
+     * In uncontrolled mode, this is called as a notification after the state changes internally.
+     */
+    onOpenChange?: (isOpen: boolean) => void;
+    /**
+     * Color for the unread badge on the floating bubble button.
+     * Only visible when there are unread replies and the chat is closed.
+     * Default: '#eab308' (yellow).
+     */
+    badgeColor?: string;
+    /**
+     * Number of unread replies to display on the badge.
+     * When provided, a circular badge is shown on the floating bubble button.
+     * Typically driven by the `useUnreadCount` hook.
+     */
+    unreadCount?: number;
 }
 /** A single chat message */
 interface ChatMessage {
@@ -90,7 +120,7 @@ interface AnonymousContext {
  * <ChatBubble apiUrl="/api/support" />
  * ```
  */
-declare function ChatBubble({ apiUrl, position, color, title, placeholder, show, user, repliesUrl, }: ChatBubbleProps): react_jsx_runtime.JSX.Element;
+declare function ChatBubble({ apiUrl, position, color, title, placeholder, show, user, repliesUrl, isOpen: isOpenProp, onOpenChange, badgeColor, unreadCount, }: ChatBubbleProps): react_jsx_runtime.JSX.Element;
 
 /**
  * SupportChatModal -- modal-based support chat.
@@ -168,9 +198,56 @@ interface ChatEngineState {
  */
 declare function useChatEngine({ apiUrl, user, repliesUrl, isOpen, }: ChatEngineOptions): ChatEngineState;
 
+/** Options for the useUnreadCount hook */
+interface UnreadCountOptions {
+    /** URL to poll for team replies (e.g., '/api/support/replies') */
+    repliesUrl: string;
+    /** Authenticated user info (optional). When provided, user.id is used as sessionId. */
+    user?: ChatUser;
+    /** Whether the chat panel is currently open. Polling pauses when true. */
+    isOpen: boolean;
+}
+/** Return value from useUnreadCount */
+interface UnreadCountState {
+    /** Number of unread reply messages */
+    unreadCount: number;
+    /** Convenience boolean: true when unreadCount > 0 */
+    hasUnread: boolean;
+    /** Pre-fetched reply messages ready to display instantly when chat opens */
+    pendingReplies: ChatMessage[];
+    /** Reset unreadCount to 0 and clear pendingReplies */
+    markAsRead: () => void;
+}
+/**
+ * Hook that tracks unread reply count in the background via polling.
+ *
+ * Polls the replies endpoint every 4 seconds when `isOpen` is false.
+ * Stops background polling when `isOpen` is true (useChatEngine handles it at that point).
+ * Pre-fetches reply messages so they appear instantly when the chat opens.
+ *
+ * Can be used independently of ChatBubble -- any component can call useUnreadCount
+ * to build custom unread UX.
+ *
+ * @example
+ * ```tsx
+ * const { unreadCount, hasUnread, pendingReplies, markAsRead } = useUnreadCount({
+ *   repliesUrl: '/api/support/replies',
+ *   user: currentUser,
+ *   isOpen: false,
+ * });
+ *
+ * return (
+ *   <button onClick={openChat}>
+ *     Support {hasUnread && <span className="badge">{unreadCount}</span>}
+ *   </button>
+ * );
+ * ```
+ */
+declare function useUnreadCount({ repliesUrl, user, isOpen, }: UnreadCountOptions): UnreadCountState;
+
 /** Get or create a persistent session ID from localStorage */
 declare function getSessionId(): string;
 /** Collect anonymous browser context */
 declare function collectAnonymousContext(): AnonymousContext;
 
-export { type AnonymousContext, type BubblePosition, ChatBubble, type ChatBubbleProps, type ChatEngineOptions, type ChatEngineState, type ChatMessage, type ChatUser, SupportChatModal, type SupportChatModalProps, type SupportChatState, collectAnonymousContext, getSessionId, useChatEngine, useSupportChat };
+export { type AnonymousContext, type BubblePosition, ChatBubble, type ChatBubbleProps, type ChatEngineOptions, type ChatEngineState, type ChatMessage, type ChatUser, SupportChatModal, type SupportChatModalProps, type SupportChatState, type UnreadCountOptions, type UnreadCountState, collectAnonymousContext, getSessionId, useChatEngine, useSupportChat, useUnreadCount };

package/dist/client/index.d.ts

@@ -31,6 +31,36 @@ interface ChatBubbleProps {
     user?: ChatUser;
     /** URL to poll for team replies (e.g., '/api/support/replies'). Enables bidirectional chat. */
     repliesUrl?: string;
+    /**
+     * Controlled mode: when provided, overrides internal open/close state.
+     * The chat panel is open when `isOpen` is true, closed when false.
+     * Use together with `onOpenChange` to control the panel externally.
+     *
+     * When not provided, ChatBubble manages its own open/close state (uncontrolled mode).
+     *
+     * Note: `show` controls visibility of the floating button, `isOpen` controls the panel state.
+     * Both can be used together (e.g., `show={false}` + `isOpen={true}` = no bubble button but panel is open).
+     */
+    isOpen?: boolean;
+    /**
+     * Callback fired when the user attempts to change the open/close state.
+     * Called when the user clicks the bubble button, close button, or presses Escape.
+     * In controlled mode, you must update your state in response to this callback.
+     * In uncontrolled mode, this is called as a notification after the state changes internally.
+     */
+    onOpenChange?: (isOpen: boolean) => void;
+    /**
+     * Color for the unread badge on the floating bubble button.
+     * Only visible when there are unread replies and the chat is closed.
+     * Default: '#eab308' (yellow).
+     */
+    badgeColor?: string;
+    /**
+     * Number of unread replies to display on the badge.
+     * When provided, a circular badge is shown on the floating bubble button.
+     * Typically driven by the `useUnreadCount` hook.
+     */
+    unreadCount?: number;
 }
 /** A single chat message */
 interface ChatMessage {
@@ -90,7 +120,7 @@ interface AnonymousContext {
  * <ChatBubble apiUrl="/api/support" />
  * ```
  */
-declare function ChatBubble({ apiUrl, position, color, title, placeholder, show, user, repliesUrl, }: ChatBubbleProps): react_jsx_runtime.JSX.Element;
+declare function ChatBubble({ apiUrl, position, color, title, placeholder, show, user, repliesUrl, isOpen: isOpenProp, onOpenChange, badgeColor, unreadCount, }: ChatBubbleProps): react_jsx_runtime.JSX.Element;
 
 /**
  * SupportChatModal -- modal-based support chat.
@@ -168,9 +198,56 @@ interface ChatEngineState {
  */
 declare function useChatEngine({ apiUrl, user, repliesUrl, isOpen, }: ChatEngineOptions): ChatEngineState;
 
+/** Options for the useUnreadCount hook */
+interface UnreadCountOptions {
+    /** URL to poll for team replies (e.g., '/api/support/replies') */
+    repliesUrl: string;
+    /** Authenticated user info (optional). When provided, user.id is used as sessionId. */
+    user?: ChatUser;
+    /** Whether the chat panel is currently open. Polling pauses when true. */
+    isOpen: boolean;
+}
+/** Return value from useUnreadCount */
+interface UnreadCountState {
+    /** Number of unread reply messages */
+    unreadCount: number;
+    /** Convenience boolean: true when unreadCount > 0 */
+    hasUnread: boolean;
+    /** Pre-fetched reply messages ready to display instantly when chat opens */
+    pendingReplies: ChatMessage[];
+    /** Reset unreadCount to 0 and clear pendingReplies */
+    markAsRead: () => void;
+}
+/**
+ * Hook that tracks unread reply count in the background via polling.
+ *
+ * Polls the replies endpoint every 4 seconds when `isOpen` is false.
+ * Stops background polling when `isOpen` is true (useChatEngine handles it at that point).
+ * Pre-fetches reply messages so they appear instantly when the chat opens.
+ *
+ * Can be used independently of ChatBubble -- any component can call useUnreadCount
+ * to build custom unread UX.
+ *
+ * @example
+ * ```tsx
+ * const { unreadCount, hasUnread, pendingReplies, markAsRead } = useUnreadCount({
+ *   repliesUrl: '/api/support/replies',
+ *   user: currentUser,
+ *   isOpen: false,
+ * });
+ *
+ * return (
+ *   <button onClick={openChat}>
+ *     Support {hasUnread && <span className="badge">{unreadCount}</span>}
+ *   </button>
+ * );
+ * ```
+ */
+declare function useUnreadCount({ repliesUrl, user, isOpen, }: UnreadCountOptions): UnreadCountState;
+
 /** Get or create a persistent session ID from localStorage */
 declare function getSessionId(): string;
 /** Collect anonymous browser context */
 declare function collectAnonymousContext(): AnonymousContext;
 
-export { type AnonymousContext, type BubblePosition, ChatBubble, type ChatBubbleProps, type ChatEngineOptions, type ChatEngineState, type ChatMessage, type ChatUser, SupportChatModal, type SupportChatModalProps, type SupportChatState, collectAnonymousContext, getSessionId, useChatEngine, useSupportChat };
+export { type AnonymousContext, type BubblePosition, ChatBubble, type ChatBubbleProps, type ChatEngineOptions, type ChatEngineState, type ChatMessage, type ChatUser, SupportChatModal, type SupportChatModalProps, type SupportChatState, type UnreadCountOptions, type UnreadCountState, collectAnonymousContext, getSessionId, useChatEngine, useSupportChat, useUnreadCount };

package/dist/client/index.js

@@ -215,6 +215,10 @@ function injectKeyframes() {
       from { opacity: 1; transform: translateY(0) scale(1); }
       to   { opacity: 0; transform: translateY(12px) scale(0.96); }
     }
+    @keyframes sc-badge-scale-in {
+      from { transform: scale(0); }
+      to   { transform: scale(1); }
+    }
   `;
   document.head.appendChild(style);
 }
@@ -226,9 +230,27 @@ function ChatBubble({
   placeholder = "Type a message...",
   show = true,
   user,
-  repliesUrl
+  repliesUrl,
+  isOpen: isOpenProp,
+  onOpenChange,
+  badgeColor = "#eab308",
+  unreadCount = 0
 }) {
-  const [isOpen, setIsOpen] = useState(false);
+  const isControlled = isOpenProp !== void 0;
+  const [isOpenInternal, setIsOpenInternal] = useState(false);
+  const isOpen = isControlled ? isOpenProp : isOpenInternal;
+  const setIsOpen = useCallback(
+    (valueOrUpdater) => {
+      const newValue = typeof valueOrUpdater === "function" ? valueOrUpdater(isOpen) : valueOrUpdater;
+      if (isControlled) {
+        onOpenChange?.(newValue);
+      } else {
+        setIsOpenInternal(newValue);
+        onOpenChange?.(newValue);
+      }
+    },
+    [isControlled, isOpen, onOpenChange]
+  );
   const colorScheme = useColorScheme();
   const theme = useMemo(() => getThemeTokens(colorScheme), [colorScheme]);
   const { messages, input, setInput, sending, sendMessage, handleKeyDown } = useChatEngine({ apiUrl, user, repliesUrl, isOpen });
@@ -290,8 +312,8 @@ function ChatBubble({
     };
     document.addEventListener("keydown", handleTrapKeyDown);
     return () => document.removeEventListener("keydown", handleTrapKeyDown);
-  }, [panelState]);
-  const toggle = useCallback(() => setIsOpen((o) => !o), []);
+  }, [panelState, setIsOpen]);
+  const toggle = useCallback(() => setIsOpen((o) => !o), [setIsOpen]);
   const positionStyles = {
     position: "fixed",
     zIndex: 99999,
@@ -324,7 +346,7 @@ function ChatBubble({
             }
           }
         ` }),
-    show && /* @__PURE__ */ jsx(
+    show && /* @__PURE__ */ jsxs(
       "button",
       {
         onClick: toggle,
@@ -343,7 +365,8 @@ function ChatBubble({
           alignItems: "center",
           justifyContent: "center",
           boxShadow: "0 4px 12px rgba(0,0,0,0.15)",
-          transition: "transform 0.2s ease, box-shadow 0.2s ease"
+          transition: "transform 0.2s ease, box-shadow 0.2s ease",
+          overflow: "visible"
         },
         onMouseEnter: (e) => {
           e.currentTarget.style.transform = "scale(1.1)";
@@ -353,21 +376,50 @@ function ChatBubble({
           e.currentTarget.style.transform = "scale(1)";
           e.currentTarget.style.boxShadow = "0 4px 12px rgba(0,0,0,0.15)";
         },
-        children: /* @__PURE__ */ jsx(
-          "svg",
-          {
-            width: "24",
-            height: "24",
-            viewBox: "0 0 24 24",
-            fill: "none",
-            stroke: "white",
-            strokeWidth: "2",
-            strokeLinecap: "round",
-            strokeLinejoin: "round",
-            "aria-hidden": "true",
-            children: isOpen ? /* @__PURE__ */ jsx("path", { d: "M18 6L6 18M6 6l12 12" }) : /* @__PURE__ */ jsx("path", { d: "M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z" })
-          }
-        )
+        children: [
+          /* @__PURE__ */ jsx(
+            "svg",
+            {
+              width: "24",
+              height: "24",
+              viewBox: "0 0 24 24",
+              fill: "none",
+              stroke: "white",
+              strokeWidth: "2",
+              strokeLinecap: "round",
+              strokeLinejoin: "round",
+              "aria-hidden": "true",
+              children: isOpen ? /* @__PURE__ */ jsx("path", { d: "M18 6L6 18M6 6l12 12" }) : /* @__PURE__ */ jsx("path", { d: "M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z" })
+            }
+          ),
+          !isOpen && unreadCount > 0 && /* @__PURE__ */ jsx(
+            "span",
+            {
+              "data-testid": "unread-badge",
+              "aria-label": `${unreadCount > 9 ? "9+" : unreadCount} unread messages`,
+              style: {
+                position: "absolute",
+                top: "-4px",
+                right: "-4px",
+                minWidth: "20px",
+                height: "20px",
+                borderRadius: "10px",
+                backgroundColor: badgeColor,
+                color: "#fff",
+                fontSize: "11px",
+                fontWeight: 700,
+                display: "flex",
+                alignItems: "center",
+                justifyContent: "center",
+                padding: "0 5px",
+                lineHeight: 1,
+                boxShadow: "0 2px 4px rgba(0,0,0,0.2)",
+                animation: "sc-badge-scale-in 0.2s ease-out forwards"
+              },
+              children: unreadCount > 9 ? "9+" : unreadCount
+            }
+          )
+        ]
       }
     ),
     showPanel && /* @__PURE__ */ jsxs(
@@ -856,7 +908,76 @@ function useSupportChat() {
   const toggle = useCallback(() => setIsOpen((prev) => !prev), []);
   return { open, close, toggle, isOpen };
 }
+var POLL_INTERVAL2 = 4e3;
+function useUnreadCount({
+  repliesUrl,
+  user,
+  isOpen
+}) {
+  const [pendingReplies, setPendingReplies] = useState([]);
+  const lastReplyTimestampRef = useRef(null);
+  const knownReplyIdsRef = useRef(/* @__PURE__ */ new Set());
+  const prevIsOpenRef = useRef(isOpen);
+  useEffect(() => {
+    if (isOpen && !prevIsOpenRef.current) {
+      setPendingReplies([]);
+      knownReplyIdsRef.current.clear();
+      lastReplyTimestampRef.current = null;
+    }
+    prevIsOpenRef.current = isOpen;
+  }, [isOpen]);
+  const markAsRead = useCallback(() => {
+    setPendingReplies([]);
+    knownReplyIdsRef.current.clear();
+    lastReplyTimestampRef.current = null;
+  }, []);
+  useEffect(() => {
+    if (!repliesUrl || isOpen) return;
+    const sessionId = user?.id ?? getSessionId();
+    const fetchReplies = async () => {
+      try {
+        const params = new URLSearchParams({ sessionId });
+        if (lastReplyTimestampRef.current) {
+          params.set("since", lastReplyTimestampRef.current);
+        }
+        const response = await fetch(`${repliesUrl}?${params.toString()}`);
+        if (!response.ok) return;
+        const data = await response.json();
+        if (data.replies.length === 0) return;
+        const newReplies = data.replies.filter(
+          (r) => !knownReplyIdsRef.current.has(r.id)
+        );
+        if (newReplies.length === 0) return;
+        for (const r of newReplies) {
+          knownReplyIdsRef.current.add(r.id);
+        }
+        const latestTimestamp = newReplies.reduce((latest, r) => {
+          return r.timestamp > latest ? r.timestamp : latest;
+        }, lastReplyTimestampRef.current ?? "");
+        lastReplyTimestampRef.current = latestTimestamp;
+        const replyMessages = newReplies.map((r) => ({
+          id: r.id,
+          text: r.text,
+          sender: "received",
+          timestamp: new Date(r.timestamp).getTime()
+        }));
+        setPendingReplies((prev) => [...prev, ...replyMessages]);
+      } catch {
+      }
+    };
+    void fetchReplies();
+    const intervalId = setInterval(() => void fetchReplies(), POLL_INTERVAL2);
+    return () => clearInterval(intervalId);
+  }, [repliesUrl, isOpen, user]);
+  const unreadCount = pendingReplies.length;
+  return {
+    unreadCount,
+    hasUnread: unreadCount > 0,
+    pendingReplies,
+    markAsRead
+  };
+}
 
-export { ChatBubble, SupportChatModal, collectAnonymousContext, getSessionId, useChatEngine, useSupportChat };
+export { ChatBubble, SupportChatModal, collectAnonymousContext, getSessionId, useChatEngine, useSupportChat, useUnreadCount };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map