@banbox/chat 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,556 @@
+import * as React$1 from 'react';
+import React__default from 'react';
+import { ClassValue } from 'clsx';
+
+/**
+ * Thread status — controls the status badge/icon in the thread list.
+ * "seen"      — blue double tick
+ * "delivered" — grey double tick
+ * "new"       — unread count badge
+ */
+type ThreadStatus = {
+    kind: "seen";
+} | {
+    kind: "delivered";
+} | {
+    kind: "new";
+    count: number;
+};
+/**
+ * A contextual reference attached to a chat session.
+ * Allows the host app to link a chat to an order, inquiry, or quotation.
+ */
+type Reference = {
+    kind: "quotation" | "order" | "inquiry" | "productInquiry";
+    id?: string;
+    /** Human-readable label shown in the chat header (e.g. "Quotation Request", "Order #123") */
+    title?: string;
+    /** Arbitrary metadata the host app wants to attach (e.g. product name, amount) */
+    meta?: Record<string, string | number | boolean>;
+};
+/**
+ * A conversation thread shown in the thread list.
+ */
+type Thread = {
+    id: string;
+    title: string;
+    subTitle?: string;
+    avatarText?: string;
+    avatarSrc?: string;
+    online?: boolean;
+    /** True if the contact has a "verified seller" badge */
+    badge?: boolean;
+    pinned?: boolean;
+    /** Unread message count */
+    unread?: number;
+    /** Preview of the last message */
+    last?: string;
+    /** Timestamp of the last message */
+    time?: string;
+    /** For linking to an order */
+    orderId?: string;
+    /** For linking to an inquiry */
+    inquiryId?: string;
+    status?: ThreadStatus;
+    /** Contextual references attached when opening from a specific order/inquiry */
+    references?: Reference[];
+};
+/** A file attachment in a message */
+type MessageFile = {
+    name: string;
+    sizeMB: number;
+    ext: string;
+    href?: string;
+    downloadName?: string;
+};
+/** An audio clip attachment in a message */
+type MessageAudio = {
+    src?: string;
+    duration?: string;
+};
+/** A reference to a message being replied to */
+type MessageRef$1 = {
+    id: string;
+    author: string | {
+        name: string;
+    };
+    time?: string;
+    text?: string;
+    images?: string[];
+    files?: MessageFile[];
+    audio?: MessageAudio;
+};
+/** Business card shared in a message */
+type BusinessCard$1 = {
+    avatarSrc?: string;
+    name: string;
+    country?: string;
+    flag?: string;
+    company?: string;
+    email?: string;
+    phone?: string;
+    [key: string]: string | undefined;
+};
+/** Address card shared in a message */
+type AddressCard$1 = {
+    name?: string;
+    label?: string;
+    businessName?: string;
+    mobileNumber?: string;
+    country?: string;
+    district?: string | null;
+    policeStation?: string | null;
+    state?: string | null;
+    city?: string | null;
+    postalCode?: string;
+    addressLine?: string;
+    landMark?: string | null;
+    [key: string]: string | null | undefined;
+};
+/**
+ * A single chat message.
+ */
+type Message = {
+    id: string;
+    author: string | {
+        name: string;
+    };
+    time?: string;
+    /** Primary text content */
+    text?: string;
+    /** Alias for text (legacy compat) */
+    content?: string;
+    images?: string[];
+    files?: MessageFile[];
+    audio?: MessageAudio;
+    businessCard?: BusinessCard$1 | Record<string, string>;
+    addressCard?: AddressCard$1 | Record<string, string>;
+    replyTo?: MessageRef$1;
+    avatarSrc?: string;
+};
+/**
+ * The unified send payload — all message types in one discriminated union.
+ * ChatFooter produces one of these; the adapter's messages.send() consumes it.
+ *
+ * To add a new message type:
+ *   1. Add a new variant here
+ *   2. Handle it in the adapter's send() implementation
+ */
+type SendPayload = {
+    type: "text";
+    text: string;
+    replyTo?: MessageRef$1;
+} | {
+    type: "voice";
+    src?: string;
+    durationSec: number;
+    durationText: string;
+    replyTo?: MessageRef$1;
+} | {
+    type: "attachments";
+    images: string[];
+    files: MessageFile[];
+    replyTo?: MessageRef$1;
+} | {
+    type: "businessCard";
+    card: BusinessCard$1;
+    replyTo?: MessageRef$1;
+} | {
+    type: "addressCard";
+    card: AddressCard$1;
+    replyTo?: MessageRef$1;
+} | {
+    type: "combined";
+    text: string;
+    images: string[];
+    files: MessageFile[];
+    replyTo?: MessageRef$1;
+};
+
+/** Options for the kebab menu (⋮) rendered by the host app */
+type KebabMenuOpts = {
+    pinned: boolean;
+    onPinToggle: () => void;
+    onDelete: () => void;
+};
+/** Options for a toast notification triggered by the package */
+type ToastOpts = {
+    type?: "success" | "error" | "info" | "warning";
+    title: string;
+    message?: string;
+};
+/**
+ * The unified data adapter.
+ *
+ * Implement this interface in your host app and pass it to <ChatRoot adapter={...} />.
+ *
+ * ### Demo implementation (local state):
+ * ```ts
+ * const adapter: ChatAdapter = {
+ *   threads: { list: getThreads, subscribe: subscribeThreads, pin, delete: deleteThread },
+ *   messages: { list: getMessages, send: handleSend },
+ * };
+ * ```
+ *
+ * ### Real API implementation:
+ * ```ts
+ * const adapter: ChatAdapter = {
+ *   threads: {
+ *     list: (ref) => cachedThreads,           // from polling/socket
+ *     subscribe: (cb) => socket.on("threads", cb),
+ *     pin: (id, p) => api.patch(`/threads/${id}`, { pinned: p }),
+ *     delete: (id) => api.delete(`/threads/${id}`),
+ *   },
+ *   messages: {
+ *     list: (tid) => cachedMessages[tid] ?? [],
+ *     subscribe: (tid, cb) => socket.on(`messages:${tid}`, cb),
+ *     send: (tid, payload) => api.post(`/threads/${tid}/messages`, payload),
+ *   },
+ * };
+ * ```
+ */
+interface ChatAdapter {
+    threads: {
+        /**
+         * Returns the current list of threads.
+         * Called synchronously; keep a local cache if using async data.
+         */
+        list: (reference?: Reference) => Thread[];
+        /**
+         * Subscribe to thread list changes.
+         * Call the callback whenever threads change (new msg, pin, delete, etc.)
+         * Returns an unsubscribe function.
+         *
+         * For WebSocket: `(cb) => socket.on("threads:update", cb)`
+         */
+        subscribe: (cb: () => void) => () => void;
+        /**
+         * Pin or unpin a thread.
+         * @param id Thread ID
+         * @param pinned True to pin, false to unpin
+         */
+        pin: (id: string, pinned: boolean) => Promise<void> | void;
+        /**
+         * Delete a thread permanently.
+         */
+        delete: (id: string) => Promise<void> | void;
+        /**
+         * Mark a thread as read (optional).
+         * Called when the user opens a thread.
+         */
+        markRead?: (id: string) => Promise<void> | void;
+    };
+    messages: {
+        /**
+         * Returns the current messages for a thread.
+         * Called synchronously; keep a local cache if using async data.
+         */
+        list: (threadId: string) => Message[];
+        /**
+         * Subscribe to message changes for a specific thread.
+         * Returns an unsubscribe function.
+         *
+         * For WebSocket: `(tid, cb) => socket.on(`messages:${tid}`, cb)`
+         * For demo: optional (UI re-renders via onAfterSend)
+         */
+        subscribe?: (threadId: string, cb: () => void) => () => void;
+        /**
+         * Send a message.
+         * The payload is a discriminated union covering all message types.
+         * Mutate your local cache + emit to server here.
+         */
+        send: (threadId: string, payload: SendPayload) => Promise<void> | void;
+    };
+}
+/**
+ * UI-level callbacks — side-effects that the host app controls.
+ *
+ * These are NOT data operations; they are UI actions that the package
+ * delegates back to the host app (so the package stays decoupled from
+ * the host app's routing, notification, and menu systems).
+ */
+interface ChatUICallbacks {
+    /**
+     * Show a toast notification.
+     * Use your app's existing toast system (react-toastify, sonner, etc.)
+     */
+    showToast?: (opts: ToastOpts) => void;
+    /**
+     * Navigate to an order or inquiry page.
+     * Called when the user clicks "View Order" / "View Inquiry" in the chat.
+     */
+    onNavigate?: (route: {
+        type: "order" | "inquiry";
+        id: string;
+    }) => void;
+    /**
+     * Render the kebab (⋮) menu in the chat header.
+     * Return your app's custom dropdown component here.
+     */
+    renderKebabMenu?: (opts: KebabMenuOpts) => React__default.ReactNode;
+}
+
+type ChatRootProps = {
+    /**
+     * The unified data adapter — provides all threads, messages, and send logic.
+     *
+     * Implement this in your host app:
+     * ```ts
+     * const adapter = createDemoChatAdapter();  // or createApiChatAdapter(...)
+     * ```
+     */
+    adapter: ChatAdapter;
+    /**
+     * Optional UI callbacks — controls toast notifications, navigation,
+     * and the kebab (⋮) menu renderer.
+     *
+     * These delegate UI side-effects back to the host app so the package
+     * stays decoupled from the host's routing and notification systems.
+     */
+    uiCallbacks?: ChatUICallbacks;
+};
+declare function ChatRoot({ adapter, uiCallbacks }: ChatRootProps): React$1.ReactPortal | null;
+
+declare function ChatUIProvider({ children }: {
+    children: React__default.ReactNode;
+}): React__default.JSX.Element;
+
+type ChatVariant = "inbox" | "single";
+type ChatUIState = {
+    isOpen: boolean;
+    variant: ChatVariant;
+    reference?: Reference;
+    selectedThreadId?: string | null;
+    openInbox: (opts?: {
+        reference?: Reference;
+        threadId?: string;
+    }) => void;
+    openSingle: (opts?: {
+        reference?: Reference;
+    }) => void;
+    close: () => void;
+    selectThread: (id: string | null) => void;
+};
+declare const ChatUIContext: React$1.Context<ChatUIState | null>;
+declare function useChatUI(): ChatUIState;
+
+type FooterAction = {
+    key: "attachment" | "emoji" | "businessCard" | "addressCard" | "translate" | string;
+    title: string;
+    icon: React__default.ReactNode;
+    onClick?: () => void;
+};
+type Props$8 = {
+    variant?: "single" | "group";
+    /**
+     * Called when the user sends any type of message.
+     * The adapter (host app) handles storage and server communication.
+     */
+    onSend: (payload: SendPayload) => void;
+    /** Called after send completes — triggers parent re-render / scroll */
+    onAfterSend?: () => void;
+    actions?: FooterAction[];
+    className?: string;
+    maxRows?: number;
+    /** The message being replied to */
+    replyTo?: MessageRef$1;
+    clearReply?: () => void;
+};
+declare const ChatFooter: React__default.FC<Props$8>;
+
+type Props$7 = {
+    left: React__default.ReactNode;
+    right?: React__default.ReactNode;
+    below?: React__default.ReactNode;
+    className?: string;
+};
+declare function ChatHeader({ left, right, below, className }: Props$7): React__default.JSX.Element;
+
+type SubtitleVariant = "live" | "muted";
+type BaseProps = {
+    title: string;
+    subtitle?: string;
+    subtitleVariant?: SubtitleVariant;
+    online?: boolean;
+    verified?: boolean;
+    /** Circle size in px (default 46) */
+    size?: number;
+    className?: string;
+};
+type AvatarVariant = BaseProps & {
+    variant: "avatar";
+    src: string;
+};
+type InitialVariant = BaseProps & {
+    variant: "initial";
+    initial: string;
+    initialSrc?: string;
+    bg?: string;
+    textClassName?: string;
+};
+type LogoVariant = BaseProps & {
+    variant: "logo";
+    src: string;
+    ringColor?: string;
+};
+type ChatIdentityProps = AvatarVariant | InitialVariant | LogoVariant;
+declare const ChatIdentity: (props: ChatIdentityProps) => React$1.JSX.Element;
+
+type MessageRef = {
+    id: string;
+    author: string | {
+        name: string;
+    };
+    time?: string;
+    text?: string;
+    images?: string[];
+    files?: ChatFile[];
+    audio?: ChatAudio;
+};
+type BusinessCard = {
+    avatarSrc: string;
+    name: string;
+    country: string;
+    flag?: string;
+    company: string;
+    email: string;
+    phone: string;
+};
+type AddressCard = {
+    name: string;
+    label?: "Home" | "Office";
+    businessName?: string;
+    mobileNumber: string;
+    country: string;
+    district?: string | null;
+    policeStation?: string | null;
+    state?: string | null;
+    city?: string | null;
+    postalCode?: string;
+    addressLine: string;
+    landMark?: string | null;
+};
+
+type ChatAudio = {
+    src?: string;
+    duration?: string;
+};
+type ChatFile = {
+    name: string;
+    sizeMB: number;
+    ext: string;
+    href?: string;
+    downloadName?: string;
+};
+type ChatMessageItemProps = {
+    id: string;
+    mine?: boolean;
+    time: string;
+    authorInitial?: string;
+    avatarBg?: string;
+    text?: string;
+    businessCard?: BusinessCard;
+    addressCard?: AddressCard;
+    images?: string[];
+    files?: ChatFile[];
+    audio?: ChatAudio;
+    replyTo?: MessageRef;
+    showStatus?: boolean;
+    status?: string;
+    className?: string;
+    onReply?: () => void;
+    onTranslate?: () => void;
+    initialSrc?: string;
+};
+declare const ChatMessageItem: ({ id, mine, time, authorInitial, avatarBg, text, businessCard, addressCard, images, files, audio, replyTo, showStatus, status, className, onReply, onTranslate, initialSrc, }: ChatMessageItemProps) => React$1.JSX.Element;
+
+type Props$6 = {
+    top?: React__default.ReactNode;
+    children: React__default.ReactNode;
+    className?: string;
+    /** set true if you want short threads anchored at the bottom */
+    bottomAlignWhenShort?: boolean;
+    /** when this value changes, we auto-scroll to the bottom */
+    scrollKey?: string | number;
+};
+declare const ChatScroll: React__default.FC<Props$6>;
+
+type ChatThreadStatus = {
+    kind: "seen";
+} | {
+    kind: "delivered";
+} | {
+    kind: "new";
+    count: number;
+};
+type Props$5 = {
+    active?: boolean;
+    pinned?: boolean;
+    online?: boolean;
+    verified?: boolean;
+    title: string;
+    preview: string;
+    time: string;
+    status: ChatThreadStatus;
+    avatarText: string;
+    avatarSrc?: string;
+    size?: number;
+    avatarBg?: string;
+    className?: string;
+    onClick?: () => void;
+};
+declare const ChatThreadItem: ({ active, pinned, online, verified, title, preview, time, status, avatarText, avatarSrc, avatarBg, className, onClick, }: Props$5) => React$1.JSX.Element;
+
+type Props$4 = {
+    className?: string;
+    onClose?: () => void;
+    onSearchChange?: (value: string) => void;
+};
+declare const ChatListHeader: ({ className, onClose, onSearchChange }: Props$4) => React$1.JSX.Element;
+
+type Props$3 = {
+    id?: string;
+    onView?: () => void;
+    className?: string;
+    label?: string;
+    buttonLabel?: string;
+};
+declare const ChatInquiryBar: React__default.FC<Props$3>;
+
+type Props$2 = {
+    /** Pixel box for the animation area */
+    size?: number;
+    loop?: boolean;
+    autoplay?: boolean;
+    className?: string;
+    ariaLabel?: string;
+    /** Avatar size in px */
+    avatarSize?: number;
+};
+declare const TypingIndicator: React__default.FC<Props$2>;
+
+type Props$1 = {
+    refMsg: MessageRef;
+    onClose?: () => void;
+    compact?: boolean;
+    className?: string;
+    jumpOnClick?: boolean;
+};
+declare const ReplyCard: React__default.FC<Props$1>;
+
+type Props = {
+    className?: string;
+    /** Size in px (default 32) */
+    size?: number;
+};
+declare const ChatSpinner: React__default.FC<Props>;
+
+declare function cn(...inputs: ClassValue[]): string;
+
+interface PortalProps {
+    children: React.ReactNode;
+    containerId?: string;
+}
+declare function Portal({ children, containerId }: PortalProps): React$1.ReactPortal | null;
+
+export { type AddressCard$1 as AddressCard, type BusinessCard$1 as BusinessCard, type ChatAdapter, ChatFooter, ChatHeader, ChatIdentity, ChatInquiryBar, ChatListHeader, ChatMessageItem, ChatRoot, type ChatRootProps, ChatScroll, ChatSpinner, ChatThreadItem, type ChatThreadStatus, type ChatUICallbacks, ChatUIContext, ChatUIProvider, type ChatUIState, type ChatVariant, type KebabMenuOpts, type Message, type MessageAudio, type MessageFile, type MessageRef$1 as MessageRef, Portal, type Reference, ReplyCard, type SendPayload, type Thread, type ThreadStatus, type ToastOpts, TypingIndicator, cn, useChatUI };