@banbox/chat 1.0.11 → 1.0.13

package/README.md

@@ -1,37 +1,72 @@
 # @banbox/chat
 
-Banbox Chat UI package — plug-and-play chat popup for any React or Next.js project.
+> **Current version:** `1.0.12`
+
+Banbox Chat UI package — plug-and-play chat popup for any React or Next.js project.  
+Data-agnostic: bring your own adapter (demo, REST API, or WebSocket).
+
+---
 
 ## Installation
 
 ```bash
-# From GitHub private registry
 npm install @banbox/chat
-
-# Or local development link
-npm install ../banbox-chat
 ```
 
+CSS is **auto-injected** — no manual import needed.
+
+---
+
 ## Requirements
 
 | Peer dep | Version |
-|----------|---------|
-| react | ≥ 18 |
-| react-dom | ≥ 18 |
-| framer-motion | ≥ 10 |
+|---|---|
+| `react` | ≥ 18 |
+| `react-dom` | ≥ 18 |
+| `framer-motion` | ≥ 10 |
+| `lottie-react` | ≥ 2 |
 
 ---
 
 ## Quick Start (Vite / React)
 
-### 1. Wrap your app
+### 1. Create your adapter
+
+```ts
+// src/components/chat/demoData.ts
+import type { ChatAdapter } from "@banbox/chat";
+
+export const createDemoChatAdapter = (): ChatAdapter => ({
+  threads: {
+    list: () => cache.threads,
+    subscribe: (cb) => {
+      socket.on("threads:update", cb);
+      return () => socket.off("threads:update", cb);
+    },
+    pin:      (id, pinned) => api.patch(`/threads/${id}`, { pinned }),
+    delete:   (id)         => api.delete(`/threads/${id}`),
+    markRead: (id)         => api.post(`/threads/${id}/read`),
+  },
+  messages: {
+    list: (tid)       => cache.messages[tid] ?? [],
+    subscribe: (tid, cb) => {
+      socket.on(`messages:${tid}`, cb);
+      return () => socket.off(`messages:${tid}`, cb);
+    },
+    send: (tid, payload) => api.post(`/threads/${tid}/messages`, payload),
+  },
+});
+```
+
+### 2. Mount `ChatRoot` once at the app root
 
 ```tsx
-// main.tsx
+// src/main.tsx
 import { ChatUIProvider, ChatRoot } from "@banbox/chat";
 import { createDemoChatAdapter } from "./components/chat/demoData";
-import "@banbox/chat/dist/index.css"; // if CSS file is emitted
+import { showToast } from "./utils/toast";
 
+// Create adapter once — outside render
 const adapter = createDemoChatAdapter();
 
 createRoot(document.getElementById("root")!).render(
@@ -39,8 +74,17 @@ createRoot(document.getElementById("root")!).render(
     <App />
     <ChatRoot
       adapter={adapter}
+      theme="marketplace"
+
+      // ── Footer toolbar: allow-list per popup ──────────────────────────
+      // Default (when omitted): ["attachment", "emoji", "translate"]
+      // Available keys: "attachment" | "emoji" | "businessCard" | "addressCard" | "translate"
+      inboxFooterActions={["attachment", "emoji", "translate"]}
+      singleFooterActions={["attachment", "emoji", "translate"]}
+      // ─────────────────────────────────────────────────────────────────
+
       uiCallbacks={{
-        showToast: ({ title }) => toast(title),
+        showToast,
         onNavigate: ({ type, id }) => navigate(`/${type}s/${id}`),
       }}
     />
@@ -48,17 +92,30 @@ createRoot(document.getElementById("root")!).render(
 );
 ```
 
-### 2. Open the chat from anywhere
+### 3. Open the chat from anywhere in the app
 
 ```tsx
 import { useChatUI } from "@banbox/chat";
 
-function OrderPage() {
-  const { openSingle } = useChatUI();
+function OrderPage({ orderId }: { orderId: string }) {
+  const { openSingle, openInbox } = useChatUI();
+
   return (
-    <button onClick={() => openSingle({ reference: { kind: "order", id: "ORD-123" } })}>
-      Chat with Buyer
-    </button>
+    <>
+      {/* Open inbox (all conversations) */}
+      <button onClick={() => openInbox()}>Messages</button>
+
+      {/* Open single chat linked to this order */}
+      <button
+        onClick={() =>
+          openSingle({
+            reference: { kind: "order", id: orderId, title: `Order #${orderId}` },
+          })
+        }
+      >
+        Chat with Buyer
+      </button>
+    </>
   );
 }
 ```
@@ -67,27 +124,32 @@ function OrderPage() {
 
 ## Quick Start (Next.js App Router)
 
-### 1. Create a client wrapper component
+### 1. Create a client wrapper
 
 ```tsx
 // components/ChatWrapper.tsx
 "use client";
 import { ChatUIProvider, ChatRoot } from "@banbox/chat";
-import { createDemoChatAdapter } from "@/lib/chat/demoAdapter";
+import { createApiChatAdapter } from "@/lib/chat/apiAdapter";
 
-const adapter = createDemoChatAdapter();
+const adapter = createApiChatAdapter();
 
 export function ChatWrapper({ children }: { children: React.ReactNode }) {
   return (
     <ChatUIProvider>
       {children}
-      <ChatRoot adapter={adapter} />
+      <ChatRoot
+        adapter={adapter}
+        theme="marketplace"
+        inboxFooterActions={["attachment", "emoji", "translate"]}
+        singleFooterActions={["attachment", "emoji", "translate"]}
+      />
     </ChatUIProvider>
   );
 }
 ```
 
-### 2. Add to your root layout
+### 2. Add to root layout
 
 ```tsx
 // app/layout.tsx
@@ -104,104 +166,331 @@ export default function RootLayout({ children }) {
 }
 ```
 
-### 3. Open from any Client Component
-
-```tsx
-"use client";
-import { useChatUI } from "@banbox/chat";
-
-export function ChatButton() {
-  const { openInbox } = useChatUI();
-  return <button onClick={() => openInbox()}>Messages</button>;
-}
-```
-
 ---
 
 ## Tailwind CSS Setup
 
-The package uses Tailwind utility classes. Add the package source to your Tailwind content config so the classes are included in your build:
-
 ```ts
-// tailwind.config.ts  (or vite.config.ts with @tailwindcss/vite)
+// vite.config.ts (or tailwind.config.ts)
 export default {
   content: [
     "./src/**/*.{ts,tsx}",
-    // ↓ Include @banbox/chat source for Tailwind scanning
+    // Include @banbox/chat source for Tailwind class scanning
     "./node_modules/@banbox/chat/src/**/*.{ts,tsx}",
   ],
-}
+};
 ```
 
 ---
 
-## Implementing the ChatAdapter
+## Local Development (Hybrid Mode)
 
-The package is data-agnostic. You implement `ChatAdapter` in your host app:
+The seller / host app automatically detects the local `banbox-chat` folder and uses it during development, while using the published npm package in production builds.
 
 ```ts
-// lib/chat/apiAdapter.ts
-import type { ChatAdapter } from "@banbox/chat";
-
-export const createApiChatAdapter = ({ baseUrl, token }): ChatAdapter => ({
-  threads: {
-    list: () => cache.threads,
-    subscribe: (cb) => {
-      socket.on("threads:update", cb);
-      return () => socket.off("threads:update", cb);
-    },
-    pin: (id, pinned) => api.patch(`/threads/${id}`, { pinned }),
-    delete: (id) => api.delete(`/threads/${id}`),
-    markRead: (id) => api.post(`/threads/${id}/read`),
-  },
-  messages: {
-    list: (tid) => cache.messages[tid] ?? [],
-    subscribe: (tid, cb) => {
-      socket.on(`messages:${tid}`, cb);
-      return () => socket.off(`messages:${tid}`, cb);
-    },
-    send: (tid, payload) => api.post(`/threads/${tid}/messages`, payload),
+// vite.config.ts — hybrid alias (already set up in banbox-seller-react)
+import fs from "fs";
+import path from "path";
+
+const localChatPath = path.resolve(__dirname, "../banbox-chat");
+const useLocalChat = fs.existsSync(localChatPath);
+
+export default defineConfig({
+  resolve: {
+    alias: useLocalChat
+      ? { "@banbox/chat": path.join(localChatPath, "dist/index.js") }
+      : {},
+    dedupe: ["react", "react-dom", "framer-motion", "lottie-react"],
   },
 });
 ```
 
+| Mode | Source |
+|---|---|
+| `npm run dev` (local folder exists) | `../banbox-chat/dist/` |
+| Production build / CI | `node_modules/@banbox/chat` |
+
 ---
 
-## API Reference
+## `ChatRoot` Props
 
-### Components
+```ts
+<ChatRoot
+  adapter={adapter}           // Required — your ChatAdapter implementation
+  theme="marketplace"         // Optional — "marketplace" | "admin" | custom object
+  uiCallbacks={...}           // Optional — toast, navigate, kebab menu
+  inboxFooterActions={[...]}  // Optional — allow-list for InboxPopup toolbar
+  singleFooterActions={[...]} // Optional — allow-list for SinglePopup toolbar
+/>
+```
+
+### `theme` prop
+
+```tsx
+// Named themes
+<ChatRoot theme="marketplace" />   // orange primary (#ff5300)
+<ChatRoot theme="admin" />         // black primary (#1a1a1a)
+
+// Custom theme object
+<ChatRoot theme={{ primary: "#7C3AED", primaryActive: "#6D28D9" }} />
+```
 
-| Component | Description |
-|-----------|-------------|
-| `<ChatRoot adapter uiCallbacks? />` | Main entry point — mounts the chat popup |
-| `<ChatUIProvider>` | Context provider — wrap your app with this |
+### `inboxFooterActions` / `singleFooterActions`
 
-### Hooks
+Controls which toolbar buttons appear in the footer of each popup variant.
 
-| Hook | Description |
-|------|-------------|
-| `useChatUI()` | Open/close chat, select threads |
+| Key | Button | Default |
+|---|---|---|
+| `"attachment"` | 📎 Attach file / image | ✅ Yes |
+| `"emoji"` | 😊 Emoji picker | ✅ Yes |
+| `"translate"` | 🌐 Translation settings | ✅ Yes |
+| `"businessCard"` | 👤 Share business card | ❌ Opt-in |
+| `"addressCard"` | 📍 Share delivery address | ❌ Opt-in |
 
-### `useChatUI()` methods
+```tsx
+// Default (omit the prop — shows attachment, emoji, translate only)
+<ChatRoot adapter={adapter} />
+
+// Add location sharing to SinglePopup only
+<ChatRoot
+  inboxFooterActions={["attachment", "emoji", "translate"]}
+  singleFooterActions={["attachment", "emoji", "translate", "addressCard"]}
+/>
+
+// Full toolbar (all buttons)
+<ChatRoot
+  inboxFooterActions={["attachment", "emoji", "businessCard", "addressCard", "translate"]}
+  singleFooterActions={["attachment", "emoji", "businessCard", "addressCard", "translate"]}
+/>
+```
+
+### `uiCallbacks` prop
 
 ```ts
+uiCallbacks={{
+  // Show a toast from your app's existing toast system
+  showToast: ({ type, title, message }) => toast[type](title),
+
+  // Navigate when user clicks "View Order" / "View Inquiry"
+  onNavigate: ({ type, id }) => navigate(`/${type}s/${id}`),
+
+  // (Optional) Replace the default ⋮ kebab menu with your own component
+  renderKebabMenu: ({ pinned, onPinToggle, onDelete }) => (
+    <MyDropdownMenu pinned={pinned} onPin={onPinToggle} onDelete={onDelete} />
+  ),
+}}
+```
+
+---
+
+## `useChatUI()` Hook
+
+```tsx
 const {
-  openInbox,    // open the inbox (thread list) view
-  openSingle,   // open a single chat view
-  close,        // close the popup
-  selectThread, // switch active thread
-  isOpen,       // boolean
-  variant,      // "inbox" | "single"
+  openInbox,        // () => void — open inbox (all threads)
+  openSingle,       // (opts?) => void — open single chat
+  close,            // () => void — close popup
+  selectThread,     // (id: string | null) => void
+  isOpen,           // boolean
+  variant,          // "inbox" | "single"
+  reference,        // Reference | undefined
+  selectedThreadId, // string | null
 } = useChatUI();
 ```
 
-### `openSingle(opts)` Reference kinds
+### `openInbox(opts?)`
 
 ```ts
-openSingle({ reference: { kind: "order",         id: "ORD-123",      title: "Order Details" } });
-openSingle({ reference: { kind: "inquiry",        id: "INQ-456",      title: "Product Inquiry" } });
-openSingle({ reference: { kind: "quotation",      id: "QUOT-789",     title: "Quotation Request" } });
+// Open inbox with all threads
+openInbox();
+
+// Open inbox pre-filtered to a reference kind
+openInbox({ reference: { kind: "order" } });
+
+// Open inbox with a specific thread pre-selected
+openInbox({ threadId: "t4" });
+```
+
+### `openSingle(opts?)`
+
+```ts
+// Plain single chat
+openSingle();
+
+// Linked to an order — shows "View Order" bar in header
+openSingle({ reference: { kind: "order", id: "ORD-123", title: "Order #123" } });
+
+// Linked to an inquiry
+openSingle({ reference: { kind: "inquiry", id: "INQ-456" } });
+
+// Linked to a quotation
+openSingle({ reference: { kind: "quotation", id: "QUOT-789" } });
+
+// Product inquiry
 openSingle({ reference: { kind: "productInquiry", id: "PI-101" } });
+
+// With metadata for the header (title, subtitle, online status)
+openSingle({
+  reference: {
+    kind: "order",
+    id: "ORD-123",
+    meta: { title: "Emon Hasan", subtitle: "Customer", online: true },
+  },
+});
+```
+
+---
+
+## `ChatAdapter` Interface
+
+Full interface contract:
+
+```ts
+import type { ChatAdapter } from "@banbox/chat";
+
+const adapter: ChatAdapter = {
+  threads: {
+    // Returns current thread list (sync — keep a local cache)
+    list: (reference?) => Thread[],
+
+    // Subscribe to thread changes — returns unsubscribe function
+    subscribe: (cb: () => void) => () => void,
+
+    // Pin / unpin a thread
+    pin: (id: string, pinned: boolean) => Promise<void> | void,
+
+    // Delete a thread
+    delete: (id: string) => Promise<void> | void,
+
+    // Mark thread as read (optional)
+    markRead?: (id: string) => Promise<void> | void,
+  },
+
+  messages: {
+    // Returns messages for a thread (sync — keep a local cache)
+    list: (threadId: string) => Message[],
+
+    // Subscribe to new messages for a thread (optional)
+    subscribe?: (threadId: string, cb: () => void) => () => void,
+
+    // Send a message — handles all payload types
+    send: (threadId: string, payload: SendPayload) => Promise<void> | void,
+  },
+};
+```
+
+### `SendPayload` — all message types
+
+```ts
+// Text message
+{ type: "text"; text: string; replyTo?: MessageRef }
+
+// Voice/audio message
+{ type: "voice"; src?: string; durationSec: number; durationText: string; replyTo?: MessageRef }
+
+// Images and/or files only
+{ type: "attachments"; images: string[]; files: MessageFile[]; replyTo?: MessageRef }
+
+// Text + images/files combined
+{ type: "combined"; text: string; images: string[]; files: MessageFile[]; replyTo?: MessageRef }
+
+// Business card
+{ type: "businessCard"; card: BusinessCard; replyTo?: MessageRef }
+
+// Address / delivery card
+{ type: "addressCard"; card: AddressCard; replyTo?: MessageRef }
+```
+
+### Adding a new message type
+
+1. Add a new variant to `SendPayload` in `banbox-chat/src/types/index.ts`
+2. Handle it in your adapter's `messages.send()` implementation
+3. Optionally add a new UI component in `banbox-chat/src/ui/message-items/`
+
+---
+
+## Domain Types
+
+```ts
+import type {
+  Thread,         // Conversation thread
+  Message,        // A single chat message
+  SendPayload,    // Discriminated union of all sendable message types
+  MessageFile,    // File attachment
+  MessageAudio,   // Audio clip
+  MessageRef,     // Reply-to reference
+  BusinessCard,   // Business card data
+  AddressCard,    // Delivery address data
+  ThreadStatus,   // "seen" | "delivered" | { kind: "new", count: number }
+  Reference,      // Context link: order | inquiry | quotation | productInquiry
+} from "@banbox/chat";
+```
+
+---
+
+## Individual UI Components (Advanced)
+
+Export individual components for custom layouts:
+
+```tsx
+import {
+  ChatFooter,
+  ChatHeader,
+  ChatIdentity,
+  ChatMessageItem,
+  ChatScroll,
+  ChatThreadItem,
+  ChatListHeader,
+  ChatInquiryBar,
+  TypingIndicator,
+  ReplyCard,
+  ChatSpinner,
+  ChatKebabMenu,
+} from "@banbox/chat";
+```
+
+### `ChatFooter` standalone
+
+```tsx
+import { ChatFooter, DEFAULT_FOOTER_ACTIONS } from "@banbox/chat";
+
+<ChatFooter
+  onSend={(payload) => adapter.messages.send(threadId, payload)}
+  onAfterSend={() => setRev(v => v + 1)}
+
+  // Allow-list — only these buttons appear
+  enabledActions={["attachment", "emoji", "translate"]}
+
+  replyTo={replyTo}
+  clearReply={() => setReplyTo(undefined)}
+/>
+```
+
+---
+
+## Translation Support
+
+The translate button (🌐) in the footer opens a Translation Settings modal where users can configure language preferences. To integrate your own translation API, pass `onTranslate` to `ChatMessageItem`:
+
+```tsx
+<ChatMessageItem
+  // ...
+  onTranslate={(originalText) => {
+    // Return translated string or undefined (will keep original if undefined)
+    return myTranslationService.translate(originalText, "bn");
+  }}
+/>
+```
+
+> When `onTranslate` is omitted, the translate button is still visible but acts as a no-op toggle (good for demo mode).
+
+---
+
+## Exported Constants
+
+```ts
+import { DEFAULT_FOOTER_ACTIONS } from "@banbox/chat";
+// → ["attachment", "emoji", "translate"]
 ```
 
 ---
@@ -209,7 +498,33 @@ openSingle({ reference: { kind: "productInquiry", id: "PI-101" } });
 ## Build
 
 ```bash
-npm run build       # compile to dist/
-npm run build:watch # watch mode
-npm run typecheck   # tsc --noEmit
+npm run build        # compile to dist/
+npm run build:watch  # watch mode
+npm run typecheck    # tsc --noEmit
 ```
+
+---
+
+## Changelog
+
+### v1.0.12
+- ♻️ `hiddenActionKeys` → `enabledActions` allow-list in `ChatFooter` (breaking rename in package internals, not host-facing)
+- ✨ `inboxFooterActions` and `singleFooterActions` props on `ChatRoot` — per-popup toolbar control
+- `businessCard` and `addressCard` are now **opt-in** (not shown by default)
+
+### v1.0.11
+- Added `hiddenActionKeys` prop threading through `ChatRoot` → `InboxPopup/SinglePopup` → `ChatFooter`
+
+### v1.0.10
+- 🐛 **Critical:** `SinglePopup` now subscribes to thread list (was fetched once on mount — real-time updates were missing)
+- 🐛 `coalesceThreadId` no longer has hardcoded `"t4"` demo dependency — uses pure reference matching
+- 🐛 `isOnline = true` hardcoded removed from `ChatMessageItem` avatar
+- ✨ `onTranslate` prop on `ChatMessageItem` — replaces internal `toBanglaDemo` hardcoded translator
+- 🐛 `markRead` now fires on **initial popup open**, not only on thread switch
+- ♻️ Shared `utils/theme.ts` — `GRADIENT_BORDER`, `getThemeAttr`, `getThemeVars` extracted from `InboxPopup`/`SinglePopup`
+
+### v1.0.9
+- Initial public release
+- Full adapter pattern, pub/sub threads/messages
+- InboxPopup + SinglePopup
+- All message types: text, voice, images, files, businessCard, addressCard