npm - @realtimexsco/live-chat - Versions diffs - 1.2.0 → 1.3.1 - Mend

@realtimexsco/live-chat 1.2.0 → 1.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/README.md CHANGED Viewed

@@ -1,112 +1,200 @@
 # @realtimexsco/live-chat
-> Drop-in real-time chat UI for React and Next.js — direct messages, group chats, reactions, replies, forwarding, pinned/starred messages, and more. Built on Socket.IO, Zustand, Tailwind CSS v4, and Radix UI.
+> Complete real-time chat UI for **React** and **Next.js** — DMs, groups, reactions, replies, forwarding, pins, stars, attachments, search, light/dark theme, locale/timezone, and **full UI customization** (replace the whole chat or any single component).
-[![npm version](https://img.shields.io/npm/v/@realtimexsco/live-chat.svg)](https://www.npmjs.com/package/@realtimexsco/live-chat)
-[![npm downloads](https://img.shields.io/npm/dm/@realtimexsco/live-chat.svg)](https://www.npmjs.com/package/@realtimexsco/live-chat)
-[![license](https://img.shields.io/npm/l/@realtimexsco/live-chat.svg)](https://www.npmjs.com/package/@realtimexsco/live-chat)
+| | |
+|---|---|
+| **Package name** | `@realtimexsco/live-chat` |
+| **Registry** | [npm](https://www.npmjs.com/) (public — no `.npmrc` required) |
+| **Styles entry** | `@realtimexsco/live-chat/styles.css` |
+| **Requires** | React 17+, Tailwind CSS **v4**, Zustand 4+ |
+| **Current version** | `1.1.0` |
-Use the all-in-one `<ChatMain />` for a complete chat app in minutes, drop in
-`<ChatLayout />` for a composable shell with section toggles, or build your own
-layout from the individual pieces (`<Chat>`, `<ChannelList>`, `<MessageList>`, …).
+Socket.IO client, REST API client, Zustand store, Radix UI, emoji picker, and all chat UI are **bundled inside the package**. Your app only installs a few peer dependencies.
 ---
-## Table of contents
+## Start here (5-minute overview)
+1. **Install** the package + peers (`react`, `react-dom`, `zustand`, `tailwindcss` v4).
+2. **Import CSS** — `@import "@realtimexsco/live-chat/styles.css"` and add Tailwind `@source` for the package `dist` files.
+3. **Create** `chat.config.ts` with `clientId`, `accessToken`, `loggedUserDetails`, `apiUrl`, `socketUrl`.
+4. **Render** `<ChatMain {...chatConfig} />` — the package includes a built-in viewport wrapper. For admin templates use `viewportHeight="calc(100dvh - 4rem)"`; for full-page chat use `viewportHeight="screen"`.
+5. **Optional** — pass `components`, `classNames`, or `features` to customize. **Omit any slot → package default is used automatically.**
+```tsx
+// Full page
+<ChatMain {...chatConfig} viewportHeight="screen" />
-- [Features](#features)
-- [Requirements](#requirements)
-- [Installation](#installation)
-- [Tailwind CSS v4 setup (required)](#tailwind-css-v4-setup-required)
-- [Configuration](#configuration)
-- [Quick start — full UI (`ChatMain`)](#quick-start--full-ui-chatmain)
-- [Composable shell (`ChatLayout`)](#composable-shell-chatlayout)
-- [Custom layout (advanced)](#custom-layout-advanced)
-- [React (Vite) — complete setup](#react-vite--complete-setup)
-- [Next.js (App Router) — complete setup](#nextjs-app-router--complete-setup)
-- [How it works](#how-it-works)
-- [`Chat` provider props](#chat-provider-props)
-- [Layout customization](#layout-customization)
-- [Exported components & hooks](#exported-components--hooks)
-- [Theming](#theming)
-- [Troubleshooting](#troubleshooting)
-- [Checklist](#checklist)
-- [License](#license)
+// Admin shell with 4rem header (Elstar, Metronic, etc.)
+<ChatMain {...chatConfig} viewportHeight="calc(100dvh - 4rem)" />
+// Inside your own bounded flex column (parent must have height + min-h-0)
+<div className="flex min-h-0 flex-1 overflow-hidden">
+  <ChatMain {...chatConfig} viewportHeight="full" />
+</div>
+```
+**Do not** pass empty or placeholder components for slots you want to keep default — simply omit those keys from `components`.
 ---
-## Features
+## Table of contents
+1. [Chat features included](#chat-features-included)
+2. [What you install vs what is bundled](#what-you-install-vs-what-is-bundled)
+3. [Backend credentials](#backend-credentials)
+4. [Installation step by step](#installation-step-by-step)
+5. [Tailwind CSS v4 setup (required)](#tailwind-css-v4-setup-required)
+6. [Project config file](#project-config-file)
+7. [Quick start — minimum working chat](#quick-start--minimum-working-chat)
+8. [Complete ChatMain example](#complete-chatmain-example)
+9. [Customization — three ways](#customization--three-ways)
+10. [Default component fallback (important)](#default-component-fallback-important)
+11. [Which slots are wired](#which-slots-are-wired)
+12. [Production integration pattern (admin templates)](#production-integration-pattern-admin-templates)
+13. [Customization examples (Case 1–3)](#customization-examples-case-13)
+14. [Phone & video calling](#phone--video-calling)
+15. [Theme, light/dark, date/time](#theme-lightdark-datetime)
+16. [Layout sections (`layout` prop)](#layout-sections-layout-prop)
+17. [All component slots + examples](#all-component-slots--examples)
+18. [All classNames keys](#all-classnames-keys)
+19. [Wrapping package defaults (`packageDefaultComponents`)](#wrapping-package-defaults-packagedefaultcomponents)
+20. [API query params](#api-query-params)
+21. [ChatMain props reference](#chatmain-props-reference)
+22. [Chat provider (composable mode)](#chat-provider-composable-mode)
+23. [Hooks & store](#hooks--store)
+24. [React (Vite) — full setup](#react-vite--full-setup)
+25. [Next.js — full setup](#nextjs--full-setup)
+26. [Environment variables](#environment-variables)
+27. [Dev proxy (CORS)](#dev-proxy-cors)
+28. [Architecture](#architecture)
+29. [All exports](#all-exports)
+30. [Troubleshooting](#troubleshooting)
+31. [Setup checklist](#setup-checklist)
+32. [Package development (maintainers)](#package-development-maintainers)
+33. [License](#license)
+---
-- 💬 **1-to-1 and group chats** with real-time delivery over Socket.IO
-- ⚡ **Optimistic UI** — messages appear instantly, reconcile on server ack
-- 😀 Reactions, replies, forwarding, pinned, starred & saved messages
-- 🔎 Conversation + message search, attachments, member/admin management
-- 🎨 **Themeable** via a single `themeColor` prop and CSS variables (light/dark)
-- 🧩 **Three integration modes** — all-in-one, composable shell, or fully custom
-- 🦾 Ships TypeScript types and ESM + CJS builds
-- 📦 Published on the **public npm registry** — no private registry or auth token needed
+## Chat features included
+| Feature | Supported |
+|---------|-----------|
+| Direct messages (1-to-1) | Yes |
+| Group chats | Yes |
+| Real-time messages (Socket.IO) | Yes |
+| Optimistic send (instant UI) | Yes |
+| Reactions, replies, forward | Yes |
+| Edit / delete (me / everyone) | Yes |
+| Pin & star messages | Yes |
+| Attachments (images, files) | Yes |
+| In-chat message search | Yes |
+| Typing indicators | Yes |
+| Read receipts (sent / delivered / read) | Yes |
+| New chat / user list modal | Yes |
+| Group members, admins, permissions | Yes |
+| Light / dark mode | Yes |
+| Locale & timezone formatting | Yes |
+| Phone / video call hooks | Yes (you wire WebRTC) |
+| Full UI customization | Yes |
 ---
-## Requirements
+## What you install vs what is bundled
+### You must install (peer dependencies)
+| Package | Version | When | Why |
+|---------|---------|------|-----|
+| `react` | ≥ 17 | Always | UI framework |
+| `react-dom` | ≥ 17 | Always | DOM rendering |
+| `zustand` | ≥ 4 | Always | Chat state store |
+| `tailwindcss` | **v4** | Always | Package uses Tailwind utilities |
+| `@tailwindcss/vite` | v4 | Vite only | Tailwind plugin |
+| `@tailwindcss/postcss` | v4 | Next.js only | Tailwind PostCSS plugin |
+| `next` | ≥ 13 | Next.js only | App Router |
+| `react-hot-toast` | ≥ 2 | Optional | Only if you use `showNotification` helper |
+### Bundled inside the package (do not install separately)
+`axios`, `socket.io-client`, `radix-ui`, `lucide-react`, `emoji-picker-react`, `clsx`, `tailwind-merge`, `class-variance-authority`, and all chat components.
+---
-| Requirement | Version |
-| ----------- | ------- |
-| Node.js | 18+ |
-| React | ≥ 17 (19 recommended) |
-| `react-dom` | ≥ 17 |
-| `zustand` | ≥ 4 |
-| `tailwindcss` | **v4** (required) |
-| Next.js | ≥ 13 App Router (optional — for Next.js projects) |
+## Backend credentials
-You also need, at runtime:
+| Field | Example | Notes |
+|-------|---------|-------|
+| `clientId` | `"6a35339216e46130366cda93"` | RealtimeX tenant / client id |
+| `accessToken` | JWT string | User access token |
+| `loggedUserDetails._id` | `"6a3533c416e46130366cda98"` | **Must match `_id` inside JWT** |
+| `loggedUserDetails.name` | `"chat1"` | Display name |
+| `loggedUserDetails.email` | `"chat1@example.com"` | Used for client-user login |
+| `apiUrl` | `https://realtimex.softwareco.com/api/v1` | REST API — **must end with** `/api/v1` (**required**, pass from your app) |
+| `socketUrl` | `https://realtimex.softwareco.com` | Socket host — **no** `/api/v1`; connects at `/connection`. Optional — derived from `apiUrl` if omitted |
+| `themeColor` | `"#6366f1"` | Brand accent (optional) |
-| Field | Description |
-| ----- | ----------- |
-| **Client ID** | Your RealtimeX client / app id |
-| **Access token** | JWT for the logged-in user |
-| **Logged user details** | `{ _id, name, email }` |
-| **API URL** | REST base ending with `/api/v1`, e.g. `https://your-server.com/api/v1` |
-| **Socket URL** | Base host only (no `/api/v1`), e.g. `https://your-server.com` |
+> **Important:** If `loggedUserDetails._id` does not match the JWT `_id`, messages may appear on the wrong side, contacts may be empty, or session sync can fail. Decode your JWT or use the id returned from the login API.
 ---
-## Installation
+## Installation step by step
+### 1. Install the package and peers
+**npm:**
+```bash
+npm install @realtimexsco/live-chat react react-dom zustand tailwindcss
+```
+**pnpm:**
 ```bash
-npm install @realtimexsco/live-chat
-# install peer dependencies if you don't have them yet
-npm install react react-dom zustand tailwindcss @tailwindcss/vite
+pnpm add @realtimexsco/live-chat react react-dom zustand tailwindcss
 ```
-Or with pnpm:
+### 2. Install Tailwind v4 plugin for your framework
+**Vite:**
 ```bash
-pnpm add @realtimexsco/live-chat react react-dom zustand tailwindcss @tailwindcss/vite
+pnpm add -D @tailwindcss/vite @vitejs/plugin-react vite
 ```
-> Published on the public npm registry — **no `.npmrc` or auth token needed**.
+**Next.js:**
-Verify the installed version:
+```bash
+pnpm add -D @tailwindcss/postcss
+# next is usually already installed
+```
+### 3. Verify install
 ```bash
-cat node_modules/@realtimexsco/live-chat/package.json | grep version
+npm ls @realtimexsco/live-chat
+ls node_modules/@realtimexsco/live-chat/dist/index.d.ts   # TypeScript types must exist
 ```
+### 4. Configure CSS, config file, and chat page (see sections below)
+### 5. Run your app and open the chat route
+No `.npmrc` or private token is required — the package is on the public npm registry.
 ---
 ## Tailwind CSS v4 setup (required)
-The package ships Tailwind utility classes, so your app must:
+The package will look unstyled without these three steps:
-1. Import the package stylesheet
-2. Scan the built package output so Tailwind generates the classes it uses
-3. Define `--chat-theme*` CSS variables
+1. `@import` Tailwind + package `styles.css`
+2. `@source` the package `dist` files so Tailwind scans bundled classes
+3. Define `--chat-theme*` CSS variables in `:root`
 ### Vite — `src/index.css`
-> From `src/index.css`, `@source` uses `../node_modules`.
 ```css
 @import "tailwindcss";
 @import "@realtimexsco/live-chat/styles.css";
@@ -115,11 +203,6 @@ The package ships Tailwind utility classes, so your app must:
 @source "../node_modules/@realtimexsco/live-chat/dist/index.cjs";
 @source "../**/*.{js,jsx,ts,tsx}";
-.chat-page h1,
-.chat-container-root h1 {
-  @apply text-[15px] font-semibold leading-snug text-gray-900;
-}
 :root {
   --radius: 0.625rem;
   --background: oklch(1 0 0);
@@ -141,7 +224,7 @@ The package ships Tailwind utility classes, so your app must:
   --secondary-foreground: oklch(0.205 0 0);
   --input: oklch(0.922 0 0);
-  /* Chat theme — overridden at runtime by the Chat `themeColor` prop */
+  /* Overridden at runtime by ChatMain `themeColor` */
   --chat-theme: #6366f1;
   --chat-theme-5: #6366f10D;
   --chat-theme-10: #6366f11A;
@@ -178,21 +261,14 @@ The package ships Tailwind utility classes, so your app must:
 }
 @layer base {
-  html,
-  body,
-  #root {
-    height: 100%;
-  }
-  body {
-    @apply bg-background text-foreground;
-  }
+  html, body, #root { height: 100%; }
+  body { @apply bg-background text-foreground; }
 }
 ```
 ### Next.js — `src/app/globals.css`
-> **Critical:** `globals.css` is in `src/app/`, so `@source` must use `../../node_modules` (NOT `../node_modules`).
+> `globals.css` is inside `src/app/`, so `@source` uses **`../../node_modules`** (not `../`).
 ```css
 @import "tailwindcss";
@@ -201,22 +277,21 @@ The package ships Tailwind utility classes, so your app must:
 @source "../../node_modules/@realtimexsco/live-chat/dist/index.mjs";
 @source "../../node_modules/@realtimexsco/live-chat/dist/index.cjs";
-/* …same :root, @theme inline, and @layer base blocks as above… */
+/* Copy :root, @theme inline, and @layer base from the Vite example above */
 ```
-### `@source` path reference
+### `@source` path cheat sheet
-| CSS file location | Correct `@source` |
-| ----------------- | ----------------- |
-| `src/index.css` | `../node_modules/...` |
-| `src/app/globals.css` | `../../node_modules/...` |
+| CSS file location | `@source` prefix |
+|-------------------|------------------|
+| `src/index.css` (Vite) | `../node_modules/...` |
+| `src/app/globals.css` (Next.js) | `../../node_modules/...` |
-Wrong path → Tailwind skips package classes → **old / broken UI**.
+Wrong path = broken or unstyled chat UI.
-### Vite config
+### Vite — `vite.config.ts`
 ```ts
-// vite.config.ts
 import path from "path";
 import { fileURLToPath } from "url";
 import { defineConfig } from "vite";
@@ -232,117 +307,79 @@ export default defineConfig({
     dedupe: ["react", "react-dom", "zustand", "socket.io-client", "@realtimexsco/live-chat"],
   },
   optimizeDeps: {
-    // Required: stale .vite/deps cache shows OLD UI after package upgrade
     exclude: ["@realtimexsco/live-chat"],
     include: ["zustand", "socket.io-client"],
   },
-  server: {
-    proxy: {
-      "/chat-api": {
-        target: "http://YOUR_API_HOST",
-        changeOrigin: true,
-        rewrite: (p) => p.replace(/^\/chat-api/, "/api/v1"),
-      },
-    },
-  },
 });
 ```
-### Next.js config
+### Next.js — `next.config.ts`
 ```ts
-// next.config.ts
 import type { NextConfig } from "next";
 const nextConfig: NextConfig = {
   transpilePackages: ["@realtimexsco/live-chat"],
-  async rewrites() {
-    return [
-      {
-        source: "/chat-api/:path*",
-        destination: "http://YOUR_API_HOST/api/v1/:path*",
-      },
-    ];
-  },
 };
 export default nextConfig;
 ```
-`transpilePackages` is required so Next.js compiles the chat package correctly.
-### PostCSS (Next.js)
+### Next.js — `postcss.config.mjs`
 ```js
-// postcss.config.mjs
-const config = {
-  plugins: { "@tailwindcss/postcss": {} },
-};
+const config = { plugins: { "@tailwindcss/postcss": {} } };
 export default config;
 ```
 ---
-## Configuration
-Create a shared config file and replace `YOUR_*` placeholders with real credentials.
+## Project config file
-**TypeScript** — `src/configs/chat.config.ts`:
+Create `src/configs/chat.config.ts`:
 ```ts
-export const chatConfig = {
-  clientId: "YOUR_CLIENT_ID",
-  accessToken: "YOUR_JWT_ACCESS_TOKEN",
-  loggedUserDetails: {
-    _id: "YOUR_USER_ID",
-    name: "Your Name",
-    email: "you@example.com",
-  },
-  apiUrl: "http://YOUR_API_HOST/api/v1",
-  socketUrl: "http://YOUR_API_HOST",
-  themeColor: "#6366f1",
-} as const;
-```
+/** Optional: read _id from JWT so it always matches the token */
+function userIdFromToken(token: string): string | undefined {
+  try {
+    const payload = JSON.parse(
+      atob(token.split(".")[1].replace(/-/g, "+").replace(/_/g, "/"))
+    );
+    return payload._id || payload.id;
+  } catch {
+    return undefined;
+  }
+}
-**JavaScript** — `src/configs/chat.config.js`:
+const accessToken = "YOUR_JWT_ACCESS_TOKEN";
-```js
 export const chatConfig = {
   clientId: "YOUR_CLIENT_ID",
-  accessToken: "YOUR_JWT_ACCESS_TOKEN",
+  accessToken,
   loggedUserDetails: {
-    _id: "YOUR_USER_ID",
+    _id: userIdFromToken(accessToken) ?? "YOUR_USER_ID",
     name: "Your Name",
     email: "you@example.com",
   },
-  apiUrl: "http://YOUR_API_HOST/api/v1",
-  socketUrl: "http://YOUR_API_HOST",
+  apiUrl: "https://realtimex.softwareco.com/api/v1",
+  socketUrl: "https://realtimex.softwareco.com", // optional — auto-derived from apiUrl
   themeColor: "#6366f1",
-};
+} as const;
 ```
-| Field | Description |
-| ----- | ----------- |
-| `clientId` | Chat client ID from backend |
-| `accessToken` | JWT token for authenticated user |
-| `loggedUserDetails._id` | Current user MongoDB / API id |
-| `apiUrl` | REST API base URL ending with `/api/v1` |
-| `socketUrl` | Socket server base URL (no `/api/v1`) |
-| `themeColor` | Primary chat color (hex) |
 ---
-## Quick start — full UI (`ChatMain`)
-The fastest path. `ChatMain` renders the sidebar, chat area, and modals in one component.
+## Quick start — minimum working chat
 ```tsx
+"use client"; // Next.js only — required on any file that imports chat
 import ChatMain from "@realtimexsco/live-chat";
 import { chatConfig } from "@/configs/chat.config";
-export default function App() {
+export default function ChatPage() {
   return (
-    <div className="chat-page h-dvh min-h-0 overflow-hidden">
+    <div className="h-dvh min-h-0 overflow-hidden">
       <ChatMain
         clientId={chatConfig.clientId}
         accessToken={chatConfig.accessToken}
@@ -356,543 +393,993 @@ export default function App() {
 }
 ```
-Hide sections via the `layout` prop:
-```tsx
-<ChatMain
-  {...chatConfig}
-  clientId={chatConfig.clientId}
-  layout={{ input: false }} // read-only chat
-/>
-```
+**Container height is required.** `ChatMain` includes a built-in viewport (`chat-package-viewport`). Set `viewportHeight="screen"` for full page, or `viewportHeight="calc(100dvh - 4rem)"` below a fixed header. Alternatively wrap with `h-dvh min-h-0 overflow-hidden` and use default `viewportHeight="full"`.
 ---
-## Composable shell (`ChatLayout`)
+## Complete ChatMain example
-Recommended when you want control over the page wrapper but not every internal
-detail. `ChatLayout` is shipped inside the package — no need to copy a large
-layout file.
+All common props: theme, locale, layout, customization, calls, alerts.
 ```tsx
-import { Chat, ChatLayout } from "@realtimexsco/live-chat";
+"use client";
+import { useState } from "react";
+import ChatMain, {
+  type ChatColorMode,
+  type ChatComponents,
+  type ChatClassNames,
+  type ChatFeatures,
+  type AvatarSlotProps,
+  defaultChatLayoutConfig,
+} from "@realtimexsco/live-chat";
 import { chatConfig } from "@/configs/chat.config";
-import { chatLayoutConfig } from "@/configs/chat.layout.config";
-export default function App() {
+const MyAvatar = ({ src, name, size }: AvatarSlotProps) => (
+  <img
+    src={src || undefined}
+    alt={name}
+    className={`rounded-full object-cover avatar--${size}`}
+    style={{ width: 36, height: 36 }}
+  />
+);
+const components: ChatComponents = {
+  Avatar: MyAvatar,
+  // ChatLayout: MyFullCustomUI,     // Case 1 — replace entire UI
+  // MessageItem: MyMessageBubble,   // Case 2 — single slot
+};
+const classNames: ChatClassNames = {
+  sidebar: "bg-slate-950",
+  channelHeader: "border-b-2 border-indigo-500",
+  messageBubbleSender: "rounded-3xl shadow-md",
+  messageBubbleReceiver: "rounded-3xl",
+};
+const features: ChatFeatures = {
+  showPhoneCall: true,
+  showVideoCall: true,
+  onPhoneCall: ({ activeChannel, conversationId }) => {
+    console.log("Voice call", activeChannel.name, conversationId);
+  },
+  onVideoCall: ({ activeChannel, conversationId }) => {
+    console.log("Video call", activeChannel.name, conversationId);
+  },
+};
+export default function ChatPage() {
+  const [colorMode, setColorMode] = useState<ChatColorMode>("light");
+  const [error, setError] = useState<string | null>(null);
   return (
-    <div className="chat-page h-dvh min-h-0 overflow-hidden">
-      <Chat
-        client={{ id: chatConfig.clientId }}
+    <div className="h-dvh min-h-0 overflow-hidden">
+      <ChatMain
+        clientId={chatConfig.clientId}
         accessToken={chatConfig.accessToken}
         loggedUserDetails={chatConfig.loggedUserDetails}
         apiUrl={chatConfig.apiUrl}
         socketUrl={chatConfig.socketUrl}
         themeColor={chatConfig.themeColor}
-      >
-        <ChatLayout layout={chatLayoutConfig} themeColor={chatConfig.themeColor} />
-      </Chat>
+        colorMode={colorMode}
+        onColorModeChange={setColorMode}
+        showColorModeToggle={false}
+        locale="en-US"
+        timeZone="Asia/Kolkata"
+        hour12={false}
+        showDateTimeSettings
+        layout={{ ...defaultChatLayoutConfig }}
+        components={components}
+        classNames={classNames}
+        features={features}
+        error={error}
+        onErrorDismiss={() => setError(null)}
+      />
     </div>
   );
 }
 ```
-**Layout config** — `src/configs/chat.layout.config.ts`:
+---
-```ts
-import type { ChatLayoutConfig } from "@realtimexsco/live-chat";
-export const chatLayoutConfig: ChatLayoutConfig = {
-  sidebar: true,
-  loggedUserDetails: true,
-  channelList: true,
-  header: true,
-  messageList: true,
-  input: true,
-  forwardModal: true,
-};
-```
+## Customization — three ways
-Or re-export the built-in helpers:
+You can combine all three.
-```ts
-import {
-  defaultChatLayoutConfig,
-  mergeChatLayoutConfig,
-  type ChatLayoutConfig,
-} from "@realtimexsco/live-chat";
+| Case | Prop | What it does |
+|------|------|--------------|
+| **1** | `components.ChatLayout` | Replace the **entire** chat UI shell |
+| **2** | `components.*` | Replace **one** component (avatar, header, message bubble, drawer, etc.) |
+| **3** | `classNames.*` | Override **Tailwind classes** per region — no new React components |
-export const chatLayoutConfig = defaultChatLayoutConfig;
+Omit any slot or className key → **package default is used automatically**.
-export function mergeLayout(layout: ChatLayoutConfig) {
-  return mergeChatLayoutConfig(layout);
-}
+---
+## Default component fallback (important)
+Customization is **opt-in per slot**. You never need to register every component.
+### How it works internally
+```
+ChatMain components={{ MembersDrawer: MyDrawer }}
+        ↓
+ChatCustomizationProvider merges your config
+        ↓
+At render: resolveComponent("MembersDrawer", PackageMembersDrawer)
+        ↓
+Custom passed?  → use MyDrawer
+Not passed?     → use PackageMembersDrawer (built-in default)
 ```
----
+Rules:
+| You pass | Result |
+|----------|--------|
+| No `components` prop at all | **Full default chat UI** |
+| `components={{ Avatar: MyAvatar }}` | Custom avatar only; **all other slots use defaults** |
+| `components={{ MembersDrawer: undefined }}` | Treated as not passed → **default drawer** |
+| `classNames={{ sidebar: "..." }}` | Your classes **merge on top of** package defaults |
-## Custom layout (advanced)
+### Code pattern inside the package
-For full control, compose the individual pieces. Wrap the active chat panel in
-`<Channel>` — it resolves the conversation id, fetches messages, joins the socket
-room, and marks messages read. **Do not** manually emit `group_join` /
-`group_message_read` yourself.
+Every wired slot follows this pattern:
-Use `useChatStore` selectors and pass explicit props to each component (the
-package does not auto-wire props when used outside `ChatLayout`).
+```tsx
+const MembersDrawerSlot = resolveComponent("MembersDrawer", MembersDrawer);
+return <MembersDrawerSlot isOpen={...} onOpenChange={...} ... />;
+```
+Your custom component receives the **same props** as the package default (`MembersDrawerSlotProps`, etc.). Import the prop type from the package for TypeScript.
+### Wrapping instead of rebuilding
-**TypeScript** — `src/components/chat/ModularChatLayout.tsx`:
+Use `packageDefaultComponents` when you only need to restyle or add a wrapper:
 ```tsx
-"use client"; // required in Next.js
+import { packageDefaultComponents, type MembersDrawerSlotProps } from "@realtimexsco/live-chat";
-import { useCallback, useEffect, useState } from "react";
-import {
-  Channel,
-  ChannelHeader,
-  ChannelList,
-  ForwardModal,
-  LoggedUserDetails,
-  MessageInput,
-  MessageList,
-  useChatStore,
-  mergeChatLayoutConfig,
-  type ChatLayoutConfig,
-} from "@realtimexsco/live-chat";
-import classNames from "classnames";
+const MyMembersDrawer = (props: MembersDrawerSlotProps) => (
+  <div className="my-drawer-shell">
+    <packageDefaultComponents.MembersDrawer! {...props} />
+  </div>
+);
+```
-type ModularChatLayoutProps = {
-  layout?: ChatLayoutConfig;
-};
+---
-const ModularChatLayout = ({ layout }: ModularChatLayoutProps) => {
-  const sections = mergeChatLayoutConfig(layout);
-  const showSidebar =
-    sections.sidebar && (sections.loggedUserDetails || sections.channelList);
+## Which slots are wired
+All slots below are **honored at runtime** when you pass them on `ChatMain` `components` (or `Chat` `uiConfig.components`). Slots not listed as wired may still be typed for future use or require replacing a parent slot (e.g. `ChannelHeader`).
+| Slot | Wired in | Fallback when omitted |
+|------|----------|------------------------|
+| `ChatLayout` | `ChatLayout.tsx` | `DefaultChatLayout` |
+| `LoggedUserDetails` | `DefaultChatLayout` | Package default |
+| `ChannelList` | `DefaultChatLayout` | Package default |
+| `ChannelHeader` | `DefaultChatLayout` | Package default |
+| `MessageList` | `DefaultChatLayout` | Package default |
+| `MessageInput` | `DefaultChatLayout` | Package default |
+| `ForwardModal` | `DefaultChatLayout` | Package default |
+| `ChatPanelAlerts` | `DefaultChatLayout` | Package default |
+| `ChannelListItem` | `ChannelListItem` wrapper | `DefaultChannelListItem` |
+| `Avatar` | `ChatAvatar` | `DefaultChatAvatar` |
+| `HeaderCallActions` | `HeaderCallActions` | Built-in phone/video group |
+| `PhoneCallButton` | `HeaderCallActions` | Built-in button |
+| `VideoCallButton` | `HeaderCallActions` | Built-in button |
+| `HeaderLeftSide` | `ChannelHeaderView` | Package default |
+| `HeaderRightSide` | `ChannelHeaderView` | Package default |
+| `ChatActionModal` | `ChannelHeaderView` | Package default |
+| `ChannelDetailsDrawer` | `ChannelHeaderView` | Package default |
+| `MembersDrawer` | `ChannelHeaderView` | Package default |
+| `AdminsDrawer` | `ChannelHeaderView` | Package default |
+| `PermissionDrawer` | `ChannelHeaderView` | Package default |
+| `AttachmentsDrawer` | `ChannelHeaderView` | Package default |
+| `PinnedMessagesDrawer` | `ChannelHeaderView` | Package default |
+| `StarredMessagesDrawer` | `ChannelHeaderView` | Package default |
+> **Replace entire header:** Pass `components.ChannelHeader` with your own component (use `useChannelHeader` hook for state/handlers). That replaces the full header **and** all drawers inside it.
+### Advanced slots (replace parent component)
+These slots are **typed and exported** but used inside inner components. To customize them, either replace the parent slot or copy the parent and wire your component:
+| Slot | Customize by replacing |
+|------|------------------------|
+| `MessageItem` | `MessageList` (pass your list that renders custom items) |
+| `MessageToolbar`, `MessageStatus`, `MessageAttachments`, `MessageReactions`, `MessageReplySnippet` | `MessageItem` or `MessageList` |
+| `HeaderSearchOverlay` | `HeaderRightSide` or `ChannelHeader` |
+| `ChatThemeToggle`, `ChatDateTimeSettings`, `ChatSocketStatus` | Used inside header/sidebar — replace parent or `ChannelHeader` |
+For most apps, `components` + `classNames` on the [wired slots](#which-slots-are-wired) table is enough without touching advanced slots.
-  const activeChannel = useChatStore((s) => s.activeChannel);
-  const setActiveChannel = useChatStore((s) => s.setActiveChannel);
-  const conversationId = useChatStore((s) => s.activeConversationId);
-  const rateLimitResetAt = useChatStore((s) => s.rateLimitResetAt);
-  const isFetchingMessages = useChatStore((s) => s.isFetchingMessages);
-  const loggedUserDetails = useChatStore((s) => s.loggedUserDetails);
-  const conversationInfos = useChatStore((s) => s.conversationInfos);
-  const messagesByConversation = useChatStore((s) => s.messagesByConversation);
-  const emitDmSend = useChatStore((s) => s.emitDmSend);
-  const emitGroupMessageSend = useChatStore((s) => s.emitGroupMessageSend);
-  const fetchAllUsers = useChatStore((s) => s.fetchAllUsers);
-  const isSessionReady = useChatStore((s) => s.isSessionReady);
-  const accessToken = useChatStore((s) => s.accessToken);
-  const conversationMessages = conversationId
-    ? messagesByConversation[conversationId] || []
-    : [];
-  const [searchQuery, setSearchQuery] = useState("");
-  const [debouncedSearch, setDebouncedSearch] = useState("");
-  const [isCreateModalOpen, setIsCreateModalOpen] = useState(false);
-  const [replyTo, setReplyTo] = useState<Parameters<typeof MessageInput>[0]["replyTo"]>(null);
-  const [forwardMessage, setForwardMessage] = useState<Parameters<typeof ForwardModal>[0]["message"]>(null);
-  const [isForwardModalOpen, setIsForwardModalOpen] = useState(false);
-  useEffect(() => {
-    const timer = setTimeout(() => setDebouncedSearch(searchQuery), 400);
-    return () => clearTimeout(timer);
-  }, [searchQuery]);
-  useEffect(() => {
-    if (isSessionReady && accessToken) fetchAllUsers(true);
-  }, [isSessionReady, accessToken, fetchAllUsers]);
-  useEffect(() => {
-    if (isCreateModalOpen && isSessionReady && accessToken) fetchAllUsers(true);
-  }, [isCreateModalOpen, isSessionReady, accessToken, fetchAllUsers]);
-  const handleChannelSelect = useCallback(
-    (channel: Parameters<typeof setActiveChannel>[0]) => {
-      setActiveChannel(channel);
-      setReplyTo(null);
-    },
-    [setActiveChannel],
-  );
+---
-  const handleForwardComplete = useCallback(
-    (channel: Parameters<typeof setActiveChannel>[0]) => {
-      setActiveChannel(channel);
-      setIsForwardModalOpen(false);
-      setForwardMessage(null);
-    },
-    [setActiveChannel],
-  );
+## Production integration pattern (admin templates)
-  const handleSendMessage = useCallback(
-    (
-      content: string,
-      attachments: Parameters<NonNullable<Parameters<typeof MessageInput>[0]["onSendMessage"]>>[1],
-      replyToMessage?: Parameters<typeof MessageInput>[0]["replyTo"],
-    ) => {
-      if (!activeChannel || !loggedUserDetails) return;
-      const isGroup = !!activeChannel.isGroup;
-      const dmReceiverId = isGroup ? undefined : String(activeChannel.id);
-      const payload = {
-        tempId: `temp-${Date.now()}`,
-        sender: loggedUserDetails._id,
-        receiver: dmReceiverId,
-        content,
-        type: "text",
-        conversationId,
-        replyTo: replyToMessage
-          ? {
-              _id: replyToMessage._id || replyToMessage.id,
-              content: replyToMessage.content,
-              attachments: replyToMessage.attachments || [],
-              sender: {
-                _id: (replyToMessage.sender as { _id?: string })?._id || replyToMessage.sender,
-                name: (replyToMessage.sender as { name?: string })?.name || "",
-              },
-            }
-          : undefined,
-      };
-      if (attachments.length === 0) {
-        if (isGroup) emitGroupMessageSend(payload);
-        else emitDmSend(payload);
-      }
-      setReplyTo(null);
-    },
-    [activeChannel, conversationId, emitDmSend, emitGroupMessageSend, loggedUserDetails],
-  );
+Recommended structure for apps like **Elstar**, **Metronic**, or any admin shell:
-  return (
-    <div className="chat-shell chat-container-root flex h-full w-full overflow-hidden bg-[#f4f5f7] p-3 md:p-4">
-      <div className="relative flex flex-1 overflow-hidden rounded-2xl border border-black/[0.06] bg-white shadow-[0_8px_30px_rgba(15,23,42,0.06)]">
-        {showSidebar && (
-          <aside
-            className={classNames(
-              "flex h-full shrink-0 flex-col border-r border-black/[0.06] bg-white transition-all duration-300 ease-in-out",
-              "w-full md:w-[340px] lg:w-[360px] xl:w-[380px]",
-              activeChannel ? "hidden md:flex" : "flex",
-            )}
-          >
-            {sections.loggedUserDetails && (
-              <LoggedUserDetails
-                onUserSelect={handleChannelSelect}
-                searchQuery={searchQuery}
-                setSearchQuery={setSearchQuery}
-                isCreateModalOpen={isCreateModalOpen}
-                setIsCreateModalOpen={setIsCreateModalOpen}
-              />
-            )}
-            {sections.channelList && (
-              <ChannelList
-                activeChannel={activeChannel}
-                onChannelSelect={handleChannelSelect}
-                onNewChatClick={() => setIsCreateModalOpen(true)}
-                debouncedSearch={debouncedSearch}
-              />
-            )}
-          </aside>
-        )}
-        <Channel>
-          {rateLimitResetAt > Date.now() && (
-            <div className="shrink-0 border-b border-amber-200/80 bg-amber-50 px-4 py-2 text-center text-xs font-medium text-amber-800">
-              Too many requests — please wait before trying again.
-            </div>
-          )}
-          {sections.header && (
-            <div className="shrink-0">
-              <ChannelHeader
-                activeChannel={activeChannel}
-                conversationId={conversationId}
-                onBack={() => setActiveChannel(null)}
-              />
-            </div>
-          )}
-          {sections.messageList && (
-            <div className="relative min-h-0 flex-1 overflow-hidden">
-              <MessageList
-                activeChannel={activeChannel}
-                loggedUserId={loggedUserDetails?._id}
-                conversationMessages={conversationMessages}
-                isLoading={isFetchingMessages}
-                conversationId={conversationId}
-                conversationInfo={
-                  conversationId ? conversationInfos[conversationId] || null : null
-                }
-                onReply={setReplyTo}
-                onForward={(msg) => {
-                  setForwardMessage(msg);
-                  setIsForwardModalOpen(true);
-                }}
-              />
-            </div>
-          )}
-          {sections.input && (
-            <div className="shrink-0 border-t border-black/[0.06] bg-white">
-              <MessageInput
-                activeChannel={activeChannel}
-                conversationId={conversationId}
-                onSendMessage={handleSendMessage}
-                replyTo={replyTo}
-                onCancelReply={() => setReplyTo(null)}
-              />
-            </div>
-          )}
-        </Channel>
-      </div>
+```
+src/
+├── configs/
+│   ├── chat.config.ts              # credentials only
+│   ├── chat.customization.config.ts # components + classNames
+│   └── chat.layout.config.ts       # layout section toggles
+├── components/chat/custom/
+│   ├── ElstarMembersDrawer.tsx     # custom drawer example
+│   ├── ElstarChatAvatar.tsx
+│   └── index.ts
+└── views/Chat.tsx                  # wires ChatMain
+```
-      {sections.forwardModal && (
-        <ForwardModal
-          isOpen={isForwardModalOpen}
-          onClose={() => {
-            setIsForwardModalOpen(false);
-            setForwardMessage(null);
-          }}
-          message={forwardMessage}
-          onForwardComplete={handleForwardComplete}
-        />
-      )}
-    </div>
-  );
+### `chat.config.ts` — credentials only
+```ts
+export const chatConfig = {
+  clientId: "YOUR_CLIENT_ID",
+  accessToken: "YOUR_JWT",
+  loggedUserDetails: { _id: "...", name: "...", email: "..." },
+  apiUrl: "https://api.example.com/api/v1",
+  socketUrl: "https://api.example.com",
+  themeColor: "#6366f1",
+} as const;
+```
+### `chat.customization.config.ts` — UI overrides
+```ts
+import type { ChatClassNames, ChatComponents } from "@realtimexsco/live-chat";
+import {
+  ElstarChatAvatar,
+  ElstarHeaderCallActions,
+  ElstarMembersDrawer,
+  ElstarPhoneCallButton,
+  ElstarVideoCallButton,
+} from "@/components/chat/custom";
+/** Only register slots you want to customize. All others use package defaults. */
+export const chatComponents: ChatComponents = {
+  Avatar: ElstarChatAvatar,
+  HeaderCallActions: ElstarHeaderCallActions,
+  PhoneCallButton: ElstarPhoneCallButton,
+  VideoCallButton: ElstarVideoCallButton,
+  MembersDrawer: ElstarMembersDrawer,
 };
-export default ModularChatLayout;
+export const chatClassNames: ChatClassNames = {
+  shell: "chat-container-root",
+  channelListItemActive: "bg-indigo-50 ring-1 ring-indigo-200",
+  messageBubbleSender: "rounded-2xl shadow-sm",
+  drawer: "z-[60]",
+  drawerContent: "rounded-l-2xl",
+};
 ```
-Wrap with `<Chat>`:
+### `views/Chat.tsx` — single entry
 ```tsx
-import { Chat } from "@realtimexsco/live-chat";
-import ModularChatLayout from "@/components/chat/ModularChatLayout";
+import ChatMain, { type ChatColorMode } from "@realtimexsco/live-chat";
 import { chatConfig } from "@/configs/chat.config";
+import { chatComponents, chatClassNames } from "@/configs/chat.customization.config";
 import { chatLayoutConfig } from "@/configs/chat.layout.config";
-export default function App() {
+export default function ChatPage() {
   return (
-    <div className="chat-page h-dvh min-h-0 overflow-hidden">
-      <Chat
-        client={{ id: chatConfig.clientId }}
-        accessToken={chatConfig.accessToken}
-        loggedUserDetails={chatConfig.loggedUserDetails}
-        apiUrl={chatConfig.apiUrl}
-        socketUrl={chatConfig.socketUrl}
-        themeColor={chatConfig.themeColor}
-        onMessageReceived={(msg) => console.log("Background message:", msg)}
-        onSocketConnected={(id) => console.log("Socket connected:", id)}
-        onSocketError={(err) => console.error("Socket error:", err)}
-      >
-        <ModularChatLayout layout={chatLayoutConfig} />
-      </Chat>
+    <div className="h-dvh min-h-0 overflow-hidden">
+      <ChatMain
+        {...chatConfig}
+        layout={chatLayoutConfig}
+        components={chatComponents}
+        classNames={chatClassNames}
+        showColorModeToggle={false}
+        colorMode="light" // sync with your app theme
+      />
     </div>
   );
 }
 ```
-> **Important:** Declare all hooks (`useState`, `useCallback`, `useEffect`, …) at
-> the **top** of the component, before any conditional `return`.
+### Full custom `MembersDrawer` example
----
+Use the package store inside your drawer — same data/actions as the default drawer:
+```tsx
+import { useState, useMemo } from "react";
+import {
+  useChatStore,
+  type MembersDrawerSlotProps,
+} from "@realtimexsco/live-chat";
+import Drawer from "@/components/ui/Drawer"; // your design system
+const MyMembersDrawer = ({
+  isOpen,
+  onOpenChange,
+  conversationId,
+  conversationInfo,
+}: MembersDrawerSlotProps) => {
+  const allUsers = useChatStore((s) => s.allUsers);
+  const manageGroupMembers = useChatStore((s) => s.manageGroupMembers);
+  const loggedUserDetails = useChatStore((s) => s.loggedUserDetails);
-## React (Vite) — complete setup
+  const participants = conversationInfo?.participants ?? [];
-### Project structure
+  return (
+    <Drawer isOpen={isOpen} onClose={() => onOpenChange(false)} title="Members">
+      {/* Your UI — add/remove members via manageGroupMembers */}
+      <ul>
+        {participants.map((p) => (
+          <li key={typeof p === "string" ? p : p._id}>{typeof p === "string" ? p : p.name}</li>
+        ))}
+      </ul>
+    </Drawer>
+  );
+};
-```
-my-app/
-├── package.json
-├── vite.config.ts
-├── jsconfig.json          # or tsconfig.json
-├── index.html
-└── src/
-    ├── main.jsx
-    ├── App.jsx
-    ├── index.css
-    ├── configs/
-    │   ├── chat.config.js
-    │   └── chat.layout.config.js
-    └── components/
-        └── chat/
-            └── ModularChatLayout.jsx   # optional — or use ChatLayout
+export default MyMembersDrawer;
 ```
-### Create app
+Register it: `components={{ MembersDrawer: MyMembersDrawer }}`. If you **remove** that line, the package default members drawer appears again.
-```bash
-pnpm create vite my-app --template react
-cd my-app
-```
+---
-### `package.json` dependencies
+## Customization examples (Case 1–3)
-```json
-{
-  "dependencies": {
-    "@realtimexsco/live-chat": "^1.0.0",
-    "classnames": "^2.5.1",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7",
-    "zustand": "^5.0.14"
-  },
-  "devDependencies": {
-    "@tailwindcss/vite": "^4.3.1",
-    "@vitejs/plugin-react": "^4.7.0",
-    "tailwindcss": "^4.3.1",
-    "vite": "^6.3.5"
-  }
-}
-```
+### Case 1 — Replace entire chat UI
-### `jsconfig.json`
+```tsx
+import ChatMain, {
+  useChatController,
+  DefaultChatLayout,
+  type ChatLayoutSlotProps,
+} from "@realtimexsco/live-chat";
-```json
-{
-  "compilerOptions": {
-    "baseUrl": ".",
-    "paths": { "@/*": ["src/*"] }
-  },
-  "include": ["src"]
+// Option A: wrap the default layout
+function MyChatShell(props: ChatLayoutSlotProps) {
+  return (
+    <div className="flex h-full flex-col">
+      <header className="shrink-0 border-b px-4 py-2 font-semibold">My App Chat</header>
+      <div className="min-h-0 flex-1">
+        <DefaultChatLayout {...props} shellClassName="rounded-none shadow-none" />
+      </div>
+    </div>
+  );
 }
-```
-### `src/main.jsx`
+// Option B: build from scratch with useChatController()
+function MyFullChatUI(_props: ChatLayoutSlotProps) {
+  const {
+    activeChannel,
+    conversationId,
+    conversationMessages,
+    handleChannelSelect,
+    handleSendMessage,
+    setActiveChannel,
+    state,
+    updateState,
+  } = useChatController();
-```jsx
-import { createRoot } from "react-dom/client";
-import "./index.css";
-import App from "./App.jsx";
+  return (
+    <div className="flex h-full">
+      {/* Your sidebar, header, messages, input — full control */}
+    </div>
+  );
+}
-createRoot(document.getElementById("root")).render(<App />);
+<ChatMain
+  {...chatConfig}
+  clientId={chatConfig.clientId}
+  components={{ ChatLayout: MyChatShell }}
+/>;
 ```
-### Run
+### Case 2 — Replace individual components
-```bash
-pnpm install
-pnpm dev
+```tsx
+<ChatMain
+  {...chatConfig}
+  clientId={chatConfig.clientId}
+  components={{
+    Avatar: MyAvatar,
+    ChannelListItem: MyConversationRow,
+    MessageItem: MyMessageBubble,
+    MessageInput: MyComposer,
+    PhoneCallButton: MyPhoneBtn,
+    MembersDrawer: MyMembersPanel,
+  }}
+/>
 ```
-Open **http://localhost:3000**
-Production:
+### Case 3 — Style with classNames only
-```bash
-pnpm build
-pnpm preview
+```tsx
+<ChatMain
+  {...chatConfig}
+  clientId={chatConfig.clientId}
+  classNames={{
+    channelListItemActive: "bg-indigo-50 ring-1 ring-indigo-200",
+    messageBubbleSender: "rounded-2xl shadow-sm",
+    messageBubbleReceiver: "rounded-2xl bg-white",
+    messageInput: "border-t border-gray-200",
+  }}
+/>
 ```
-### Update package
+---
-```bash
-pnpm add @realtimexsco/live-chat@latest
-rm -rf node_modules/.vite dist
-pnpm dev
-```
+## Phone & video calling
-Hard refresh: **Ctrl + Shift + R**
+Call buttons appear in **DM chats only** (hidden for groups).
----
+### Option A — Keep default buttons, add callbacks
-## Next.js (App Router) — complete setup
+```tsx
+features={{
+  showPhoneCall: true,
+  showVideoCall: true,
+  onPhoneCall: ({ activeChannel, conversationId }) => {
+    yourVoiceSDK.start(activeChannel.id, conversationId);
+  },
+  onVideoCall: ({ activeChannel, conversationId }) => {
+    yourVideoSDK.start(activeChannel.id, conversationId);
+  },
+}}
+```
-### Project structure
+### Option B — Replace the call button group
-```
-my-chat-app/
-├── package.json
-├── next.config.ts
-├── postcss.config.mjs
-├── tsconfig.json
-└── src/
-    ├── app/
-    │   ├── globals.css
-    │   ├── layout.tsx
-    │   ├── page.tsx
-    │   └── chat/
-    │       └── page.tsx
-    ├── configs/
-    │   ├── chat.config.ts
-    │   └── chat.layout.config.ts
-    └── components/
-        └── chat/
-            └── ModularChatLayout.tsx   # optional — or use ChatLayout
+```tsx
+components={{
+  HeaderCallActions: ({ onPhoneCall, onVideoCall, activeChannel }) => (
+    <div className="flex gap-2">
+      <button type="button" onClick={onPhoneCall}>Call {activeChannel.name}</button>
+      <button type="button" onClick={onVideoCall}>Video</button>
+    </div>
+  ),
+}}
 ```
-### Create app
+> Do **not** import `HeaderCallActions` from the package inside your custom `HeaderCallActions` — that causes infinite recursion. Render your own buttons instead.
-```bash
-pnpm create next-app@latest my-chat-app --typescript --tailwind --app --src-dir
-cd my-chat-app
+### Option C — Replace individual buttons
+```tsx
+components={{
+  PhoneCallButton: ({ onPhoneCall, className }) => (
+    <button type="button" className={className} onClick={onPhoneCall}>📞</button>
+  ),
+  VideoCallButton: ({ onVideoCall, className }) => (
+    <button type="button" className={className} onClick={onVideoCall}>📹</button>
+  ),
+}}
 ```
-### `package.json` dependencies
+### Hide calls
-```json
-{
-  "dependencies": {
-    "@realtimexsco/live-chat": "^1.0.0",
-    "classnames": "^2.5.1",
-    "next": "16.2.9",
-    "react": "19.2.4",
-    "react-dom": "19.2.4",
-    "zustand": "^5.0.14"
-  },
-  "devDependencies": {
-    "@tailwindcss/postcss": "^4",
-    "tailwindcss": "^4",
-    "typescript": "^5"
-  }
-}
+```tsx
+features={{ showPhoneCall: false, showVideoCall: false }}
 ```
-### `tsconfig.json` path alias
+---
-```json
-{
-  "compilerOptions": {
-    "paths": { "@/*": ["./src/*"] }
-  }
-}
-```
+## Theme, light/dark, date/time
-### `src/app/layout.tsx`
+### Brand color
 ```tsx
-import type { Metadata } from "next";
-import "./globals.css";
+<ChatMain {...chatConfig} clientId={chatConfig.clientId} themeColor="#7c3aed" />
+```
-export const metadata: Metadata = {
-  title: "RealtimeX Chat",
-  description: "RealtimeX chat integration with Next.js",
-};
+Runtime updates `--chat-theme` CSS variables automatically.
-export default function RootLayout({ children }: { children: React.ReactNode }) {
-  return (
-    <html lang="en" className="h-full antialiased">
-      <body className="min-h-full flex flex-col">{children}</body>
-    </html>
-  );
-}
-```
+### Light / dark mode
+| Pattern | Props |
+|---------|-------|
+| Your app controls theme (e.g. admin template) | `colorMode={mode}` `onColorModeChange={setMode}` `showColorModeToggle={false}` |
+| Chat manages its own theme | `defaultColorMode="light"` (built-in toggle shown) |
+| Start dark | `defaultColorMode="dark"` |
-### `src/app/chat/page.tsx`
+### Date / time
+```tsx
+<ChatMain
+  {...chatConfig}
+  clientId={chatConfig.clientId}
+  locale="en-GB"
+  timeZone="Europe/London"
+  hour12={false}
+  showDateTimeSettings={false}
+  onDateTimePreferencesChange={(prefs) => console.log(prefs)}
+/>
+```
+---
+## Layout sections (`layout` prop)
+Toggle parts of the default UI without writing new components.
+```ts
+import { defaultChatLayoutConfig } from "@realtimexsco/live-chat";
+export const chatLayoutConfig = {
+  ...defaultChatLayoutConfig,
+  // sidebar: true,           // left panel wrapper
+  // loggedUserDetails: true, // profile + new chat button
+  // channelList: true,       // conversation list
+  // header: true,            // channel header bar
+  // messageList: true,       // message bubbles
+  // input: true,             // composer
+  // forwardModal: true,      // forward dialog
+};
+```
+Examples:
+```tsx
+layout={{ input: false }}         // read-only (no composer)
+layout={{ sidebar: false }}        // hide sidebar — messages only
+layout={{ forwardModal: false }}   // disable forward modal
+layout={{ loggedUserDetails: false, channelList: true }}  // list without profile block
+```
+---
+## All component slots + examples
+Pass only the slots you want to override via `components` on `ChatMain` (or `uiConfig` on `Chat`).
+Import prop types from the package for TypeScript, e.g. `AvatarSlotProps`, `MessageItemSlotProps`.
+| Slot | Replaces | Prop type |
+|------|----------|-----------|
+| `ChatLayout` | Entire chat shell | `ChatLayoutSlotProps` |
+| `LoggedUserDetails` | Sidebar profile + new chat | `LoggedUserDetailsSlotProps` |
+| `ChannelList` | Conversation list | `ChannelListSlotProps` |
+| `ChannelListItem` | One conversation row | `ChannelListItemSlotProps` |
+| `ChannelHeader` | Full header bar | `ChannelHeaderSlotProps` |
+| `HeaderLeftSide` | Back, name, pin/star | `HeaderLeftSideSlotProps` |
+| `HeaderRightSide` | Search, menu, settings | `HeaderRightSideSlotProps` |
+| `HeaderCallActions` | Phone + video group | `HeaderCallActionsSlotProps` |
+| `PhoneCallButton` | Voice call button | `PhoneCallButtonSlotProps` |
+| `VideoCallButton` | Video call button | `VideoCallButtonSlotProps` |
+| `HeaderSearchOverlay` | Message search dropdown | `HeaderSearchOverlaySlotProps` |
+| `MessageList` | Scrollable messages area | `ActiveChannelMessagesSlotProps` |
+| `MessageItem` | Single message bubble | `MessageItemSlotProps` |
+| `MessageInput` | Composer | `ChannelMessageBoxSlotProps` |
+| `ForwardModal` | Forward dialog | `ForwardModalSlotProps` |
+| `ChatPanelAlerts` | Error/info banner | `ChatPanelAlertsSlotProps` |
+| `ChatActionModal` | Clear/delete/block confirm | `ChatActionModalSlotProps` |
+| `ChannelDetailsDrawer` | Channel details sheet | `ChannelDetailsDrawerSlotProps` |
+| `MembersDrawer` | Group members sheet | `MembersDrawerSlotProps` |
+| `AdminsDrawer` | Group admins sheet | `AdminsDrawerSlotProps` |
+| `PermissionDrawer` | Permissions sheet | `PermissionDrawerSlotProps` |
+| `AttachmentsDrawer` | Attachments sheet | `AttachmentsDrawerSlotProps` |
+| `PinnedMessagesDrawer` | Pinned messages sheet | `PinnedMessagesDrawerSlotProps` |
+| `StarredMessagesDrawer` | Starred messages sheet | `StarredMessagesDrawerSlotProps` |
+| `Avatar` | Avatar everywhere | `AvatarSlotProps` |
+| `MessageToolbar` | Reply/forward/edit menu | `MessageToolbarSlotProps` |
+| `MessageStatus` | Sent/delivered/read ticks | `MessageStatusSlotProps` |
+| `MessageAttachments` | Files/images in bubble | `MessageAttachmentsSlotProps` |
+| `MessageReactions` | Emoji chips | `MessageReactionsSlotProps` |
+| `MessageReplySnippet` | Quoted reply in bubble | `MessageReplySnippetSlotProps` |
+| `ChatThemeToggle` | Light/dark toggle | `{ className?: string }` |
+| `ChatDateTimeSettings` | Date/time settings button | `Record<string, never>` |
+| `ChatSocketStatus` | Connection indicator | `{ className?: string }` |
+### Code examples for common slots
+**MembersDrawer** (full custom drawer — Elstar-style)
+```tsx
+import { useChatStore, type MembersDrawerSlotProps } from "@realtimexsco/live-chat";
+const MyMembersDrawer = ({
+  isOpen,
+  onOpenChange,
+  conversationId,
+  conversationInfo,
+}: MembersDrawerSlotProps) => {
+  const manageGroupMembers = useChatStore((s) => s.manageGroupMembers);
+  const participants = conversationInfo?.participants ?? [];
+  if (!isOpen) return null;
+  return (
+    <aside className="members-drawer">
+      <header>
+        <h2>Members ({participants.length})</h2>
+        <button type="button" onClick={() => onOpenChange(false)}>Close</button>
+      </header>
+      <ul>
+        {participants.map((p, i) => {
+          const id = typeof p === "string" ? p : p._id;
+          const name = typeof p === "string" ? "User" : p.name;
+          return <li key={`${id}-${i}`}>{name}</li>;
+        })}
+      </ul>
+    </aside>
+  );
+};
+```
+**ChannelDetailsDrawer**
+```tsx
+import type { ChannelDetailsDrawerSlotProps } from "@realtimexsco/live-chat";
+const MyDetailsDrawer = ({ isOpen, onOpenChange, activeChannel, conversationInfo }: ChannelDetailsDrawerSlotProps) => (
+  <dialog open={isOpen} onClose={() => onOpenChange(false)}>
+    <h2>{activeChannel.name}</h2>
+    <p>{conversationInfo?.groupDescription ?? "Direct message"}</p>
+  </dialog>
+);
+```
+**Avatar**
+```tsx
+import type { AvatarSlotProps } from "@realtimexsco/live-chat";
+const MyAvatar = ({ src, name, size = "md", isOnline, showOnline }: AvatarSlotProps) => (
+  <div className="relative">
+    <img src={src || undefined} alt={name} className={`avatar avatar--${size}`} />
+    {showOnline && isOnline && <span className="online-dot" />}
+  </div>
+);
+```
+**MessageItem** (custom bubble)
+```tsx
+import type { MessageItemSlotProps } from "@realtimexsco/live-chat";
+const MyMessageItem = ({ isSender, message, createdAt }: MessageItemSlotProps) => (
+  <div className={isSender ? "text-right" : "text-left"}>
+    <div className={isSender ? "bubble-sent" : "bubble-received"}>{message}</div>
+    <time className="text-xs opacity-60">{createdAt}</time>
+  </div>
+);
+```
+**ChannelListItem**
+```tsx
+import type { ChannelListItemSlotProps } from "@realtimexsco/live-chat";
+const MyRow = ({ channel, isActive, onSelect }: ChannelListItemSlotProps) => (
+  <button
+    type="button"
+    className={isActive ? "row-active" : "row"}
+    onClick={() => onSelect(channel)}
+  >
+    {channel.name}
+    {channel.unreadCount ? ` (${channel.unreadCount})` : ""}
+  </button>
+);
+```
+**MessageInput**
+```tsx
+import type { ChannelMessageBoxSlotProps } from "@realtimexsco/live-chat";
+const MyInput = ({ onSendMessage, replyTo, onCancelReply }: ChannelMessageBoxSlotProps) => {
+  const [text, setText] = useState("");
+  return (
+    <div>
+      {replyTo && <button type="button" onClick={onCancelReply}>Cancel reply</button>}
+      <input value={text} onChange={(e) => setText(e.target.value)} />
+      <button type="button" onClick={() => { onSendMessage?.(text, [], replyTo); setText(""); }}>
+        Send
+      </button>
+    </div>
+  );
+};
+```
+---
+## All classNames keys
+Merged with package defaults — your classes extend styling without replacing components.
+| Key | UI region |
+|-----|-----------|
+| `shell` | Outermost chat wrapper |
+| `mainPanel` | Inner rounded panel |
+| `sidebar` | Left sidebar |
+| `loggedUserDetails` | Profile block at top |
+| `channelList` | Conversation list container |
+| `channelListItem` | Each conversation row |
+| `channelListItemActive` | Selected conversation row |
+| `channelHeader` | Header bar |
+| `headerLeft` | Header left section |
+| `headerRight` | Header right section |
+| `headerCallActions` | Call buttons wrapper |
+| `phoneCallButton` | Phone button |
+| `videoCallButton` | Video button |
+| `messageList` | Messages scroll area |
+| `messageItem` | Message row wrapper |
+| `messageBubble` | Bubble (both sides) |
+| `messageBubbleSender` | Outgoing bubble |
+| `messageBubbleReceiver` | Incoming bubble |
+| `messageInput` | Composer container |
+| `messageInputTextarea` | Textarea element |
+| `avatar` | Avatar wrapper |
+| `avatarFallback` | Initials fallback |
+| `dateDivider` | "Today" / date separator |
+| `emptyState` | No messages placeholder |
+| `forwardModal` | Forward dialog |
+| `chatPanelAlerts` | Error/info alert bar |
+| `drawer` | Drawer overlay/shell |
+| `drawerContent` | Drawer panel body |
+| `searchOverlay` | In-header search results |
+```tsx
+classNames={{
+  shell: "chat-container-root",
+  channelListItemActive: "bg-indigo-50 dark:bg-indigo-500/10",
+  messageBubbleSender: "rounded-2xl shadow-sm",
+  messageBubbleReceiver: "rounded-2xl",
+  drawer: "z-[60]",
+}}
+```
+---
+## Wrapping package defaults (`packageDefaultComponents`)
+The package exports every built-in slot component so you can wrap defaults with your theme instead of rebuilding from scratch.
+```tsx
+import {
+  packageDefaultComponents,
+  type ChatComponents,
+} from "@realtimexsco/live-chat";
+function withTheme<P extends object>(
+  Default: React.ComponentType<P>,
+  className: string
+): React.ComponentType<P> {
+  return (props) => (
+    <div className={className}>
+      <Default {...props} />
+    </div>
+  );
+}
+const components: ChatComponents = {
+  MessageItem: withTheme(packageDefaultComponents.MessageItem!, "my-message"),
+  ChannelListItem: withTheme(packageDefaultComponents.ChannelListItem!, "my-row"),
+  Avatar: MyFullyCustomAvatar, // or use DefaultChatAvatar from package
+};
+```
+Also exported for reference:
+- `packageDefaultComponents` — map of all slot defaults
+- `DefaultChatAvatar` — inner avatar (use when customizing `Avatar` slot)
+- `DefaultChannelListItem` — inner list row (use when customizing `ChannelListItem` slot)
+---
+## API query params
+Pass extra query string params from your app into package HTTP requests. Params are merged in the axios interceptor (built-in params like `limit` / `page` / `conversationId` still win if they conflict).
+**Default behavior:** `queryParams` apply to **all GET APIs** only (`queryParamApis` defaults to `['get']`). Login, create group, and other POST/PATCH calls are **not** affected unless you opt in with `queryParamApis={['all']}`.
+---
+### 1. Default — same params on every GET API
+**When to use:** Your app needs the same filter (e.g. `branchId`) on every list/fetch GET call inside the chat package.
+**Explanation:** You only pass `queryParams`. You do **not** need `queryParamApis` — it defaults to `['get']`, so every GET endpoint below receives these params. POST/PATCH stay clean.
+```tsx
+<ChatMain
+  {...chatConfig}
+  queryParams={{ branchId: "12" }}
+  // queryParamApis default = ['get']
+/>
+```
+**What happens on the network:**
+| Request | Query string |
+|---------|----------------|
+| `GET /user/list` | `?branchId=12` |
+| `GET /conversation/list` | `?limit=20&page=1&branchId=12` |
+| `GET /message/get-all-from-conversation` | `?conversationId=…&limit=…&branchId=12` |
+| `GET …/pinned-messages` | `?conversationId=…&branchId=12` |
+| `POST /user/login/client-user` | *(no extra query params)* |
+**GET APIs covered by default (`CHAT_GET_API_KEYS`):**
+| Key | Endpoint |
+|-----|----------|
+| `users` | `GET /user/list` |
+| `conversations` | `GET /conversation/list` |
+| `conversationInfo` | `GET /conversation/get/information/:id` |
+| `messages` | `GET /message/get-all-from-conversation` |
+| `pinnedMessages` | `GET message/pinned-messages` |
+| `starredMessages` | `GET message/starred-messages` |
+| `searchMessages` | `GET /message/search-messages` |
+| `searchMessagesContext` | `GET /message/searched-message/context` |
+```tsx
+import { CHAT_GET_API_KEYS, CHAT_API_KEYS } from "@realtimexsco/live-chat";
+```
+---
+### 2. Different params per GET API
+**When to use:** Each endpoint needs its own query keys (e.g. conversations need `branchId`, messages need `locale`, users need `orgId`).
+**Explanation:** Use `queryParamsByApi` with named API keys. Only the APIs you list get params — and each can have a different object. You do not need `queryParams` or `queryParamApis` for this pattern.
+```tsx
+<ChatMain
+  {...chatConfig}
+  queryParamsByApi={{
+    conversations: { branchId: "12" },
+    messages: { locale: "en" },
+    users: { orgId: "x" },
+  }}
+/>
+```
+**What happens on the network:**
+| Request | Query string |
+|---------|----------------|
+| `GET /conversation/list` | `?…&branchId=12` |
+| `GET /message/get-all-from-conversation` | `?…&locale=en` |
+| `GET /user/list` | `?orgId=x` |
+| Other GET APIs (not listed) | *(no extra params from this prop)* |
+---
+### 3. Only one GET API
+**When to use:** You want shared-style `queryParams`, but only on a single endpoint (e.g. conversation list), not on messages or users.
+**Explanation:** Pass `queryParams` for the values, and restrict with `queryParamApis={['conversations']}`. Other GET APIs will not receive `branchId`.
+```tsx
+<ChatMain
+  {...chatConfig}
+  queryParams={{ branchId: "12" }}
+  queryParamApis={["conversations"]}
+/>
+```
+**What happens on the network:**
+| Request | Query string |
+|---------|----------------|
+| `GET /conversation/list` | `?limit=20&page=1&branchId=12` |
+| `GET /message/get-all-from-conversation` | *(no `branchId`)* |
+| `GET /user/list` | *(no `branchId`)* |
+You can also target multiple selected GETs:
+```tsx
+<ChatMain
+  {...chatConfig}
+  queryParams={{ orgId: "x" }}
+  queryParamApis={["messages", "users"]}
+/>
+```
+---
+### Bonus: shared + per-API together
+**Explanation:** Shared params apply to the APIs in `queryParamApis`. Per-API params from `queryParamsByApi` merge on top for that endpoint.
+```tsx
+<ChatMain
+  {...chatConfig}
+  queryParams={{ tenant: "abc" }}
+  queryParamApis={["conversations", "messages"]}
+  queryParamsByApi={{
+    conversations: { branchId: "12" },
+    messages: { locale: "en" },
+  }}
+/>
+```
+- conversations → `?tenant=abc&branchId=12`
+- messages → `?tenant=abc&locale=en`
+---
+### `queryParamApis` options
+| Value | Meaning |
+|-------|---------|
+| `['get']` | **Default.** All GET endpoints in the table above |
+| `['all']` | Every `apiClient` request (GET + POST + PATCH) |
+| Specific keys | Only those endpoints (e.g. `['conversations']`) |
+### Imperative helpers
+```tsx
+import {
+  setChatQueryParams,
+  setChatQueryParamApis,
+  setChatQueryParamsByApi,
+} from "@realtimexsco/live-chat";
+setChatQueryParams({ branchId: "12" });
+setChatQueryParamApis(["conversations"]);
+setChatQueryParamsByApi({ messages: { locale: "en" } });
+```
+Socket connection query and S3 presigned uploads are **not** changed by these props.
+---
+## ChatMain props reference
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `clientId` | `string` | — | **Required.** Tenant / client id |
+| `accessToken` | `string` | — | **Required.** JWT access token |
+| `loggedUserDetails` | `object` | — | **Required.** `{ _id, name, email }` — `_id` must match JWT |
+| `apiUrl` | `string` | — | **Required.** REST API ending with `/api/v1` (pass from your env/config) |
+| `socketUrl` | `string` | derived | Optional socket host (no `/api/v1`). Defaults to `apiUrl` without `/api/v1` |
+| `queryParams` | `Record<string, string \| number \| boolean>` | — | Shared query params for selected APIs (see `queryParamApis`) |
+| `queryParamApis` | `ChatApiKey[]` | `['get']` | Which APIs receive `queryParams`. Default = all GET endpoints |
+| `queryParamsByApi` | `ChatQueryParamsByApi` | — | Different query params per API key |
+| `viewportHeight` | `"full" \| "screen" \| string` | `"full"` | Chat root height. Use `"screen"` for full page, or `"calc(100dvh - 4rem)"` below fixed header |
+| `viewportClassName` | `string` | — | Extra classes on the built-in viewport wrapper |
+| `colorMode` | `"light" \| "dark"` | — | Controlled light/dark (use with your app theme) |
+| `defaultColorMode` | `"light" \| "dark"` | `"light"` | Initial mode when uncontrolled |
+| `onColorModeChange` | `(mode) => void` | — | Called when theme changes |
+| `showColorModeToggle` | `boolean` | `true` | Show built-in light/dark toggle |
+| `locale` | `string` | browser | BCP 47 locale, e.g. `"en-US"` |
+| `timeZone` | `string` | browser | IANA timezone, e.g. `"Asia/Kolkata"` |
+| `hour12` | `boolean` | locale | `true` = 12-hour clock |
+| `defaultLocale` | `string` | — | Initial locale when uncontrolled |
+| `defaultTimeZone` | `string` | — | Initial timezone when uncontrolled |
+| `defaultHour12` | `boolean` | — | Initial 12/24h when uncontrolled |
+| `onDateTimePreferencesChange` | `(prefs) => void` | — | User changed date/time settings |
+| `showDateTimeSettings` | `boolean` | `true` | Show in-panel date/time button |
+| `layout` | `ChatLayoutConfig` | all `true` | Toggle UI sections |
+| `components` | `ChatComponents` | — | Replace UI components (Case 1 & 2) |
+| `classNames` | `ChatClassNames` | — | Per-region CSS classes (Case 3) |
+| `features` | `ChatFeatures` | — | Phone/video call flags & callbacks |
+| `uiConfig` | `UIConfig` | — | Advanced: merged with `components` / `classNames` / `features` |
+| `error` | `string \| null` | — | Error message in alert bar |
+| `info` | `string \| null` | — | Info message in alert bar |
+| `onErrorDismiss` | `() => void` | — | Dismiss error |
+| `onInfoDismiss` | `() => void` | — | Dismiss info |
+---
+## Chat provider (composable mode)
+Use `Chat` + `ChatLayout` when you need a custom page wrapper but not a full `ChatMain` replacement.
 ```tsx
 "use client";
-import { Chat, ChatLayout } from "@realtimexsco/live-chat";
+import { Chat, ChatLayout, type ChatComponents } from "@realtimexsco/live-chat";
 import { chatConfig } from "@/configs/chat.config";
-import { chatLayoutConfig } from "@/configs/chat.layout.config";
+const components: ChatComponents = {
+  Avatar: MyAvatar,
+};
 export default function ChatPage() {
   return (
-    <div className="chat-page h-dvh min-h-0 overflow-hidden">
+    <div className="h-dvh min-h-0 overflow-hidden">
       <Chat
         client={{ id: chatConfig.clientId }}
         accessToken={chatConfig.accessToken}
@@ -900,286 +1387,467 @@ export default function ChatPage() {
         apiUrl={chatConfig.apiUrl}
         socketUrl={chatConfig.socketUrl}
         themeColor={chatConfig.themeColor}
+        uiConfig={{
+          components,
+          classNames: { sidebar: "bg-slate-900" },
+          features: {
+            onPhoneCall: (ctx) => console.log("call", ctx),
+          },
+        }}
       >
-        <ChatLayout layout={chatLayoutConfig} themeColor={chatConfig.themeColor} />
+        <ChatLayout themeColor={chatConfig.themeColor} />
       </Chat>
     </div>
   );
 }
 ```
-> `'use client'` is required — the chat package uses React hooks and Zustand.
+### `Chat` provider props
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `client` | `{ id: string }` | Yes | Client id |
+| `accessToken` | `string` | Yes | JWT |
+| `loggedUserDetails` | `object` | Yes | User profile |
+| `apiUrl` | `string` | No | REST base URL |
+| `socketUrl` | `string` | No | Socket host |
+| `queryParams` | `ChatQueryParams` | No | Shared query params (default target: all GET APIs) |
+| `queryParamApis` | `ChatApiKey[]` | No | Which APIs receive `queryParams` (default `['get']`) |
+| `queryParamsByApi` | `ChatQueryParamsByApi` | No | Per-API query params |
+| `themeColor` | `string` | No | Accent color |
+| `uiConfig` | `UIConfig` | No | `components`, `classNames`, `features` |
+| `onMessageReceived` | `(msg) => void` | No | Background message callback |
+| `onSocketConnected` | `(id) => void` | No | Socket connected |
+| `onSocketError` | `(err) => void` | No | Socket error |
+| `children` | `ReactNode` | Yes | Usually `<ChatLayout />` |
-### Run
+---
-```bash
-pnpm install
-pnpm dev
+## Hooks & store
+| Hook / export | Purpose |
+|---------------|---------|
+| `useChatController()` | State + handlers inside custom `ChatLayout` (Case 1) |
+| `useChatStore()` | Zustand store — messages, conversations, socket actions |
+| `useChatCustomization()` | Current `components` / `classNames` inside custom children |
+| `useChatFeatures()` | Phone/video flags and callbacks |
+| `useChatTheme()` | `themeColor`, `isDark`, CSS variables |
+| `useChatLocale()` | Format dates/times with current locale |
+| `useChatAlerts()` | Error/info alert state |
+| `useChatContext()` | Low-level chat provider context |
+```tsx
+import { useChatStore } from "@realtimexsco/live-chat";
+const conversations = useChatStore((s) => s.conversations);
+const emitDmSend = useChatStore((s) => s.emitDmSend);
 ```
-Open **http://localhost:3000/chat**
+---
+## React (Vite) — full setup
-Clear cache after CSS or package changes:
+### 1. Create project
 ```bash
-rm -rf .next
-pnpm dev
+pnpm create vite my-chat-app --template react-ts
+cd my-chat-app
 ```
-### Update package
+### 2. Install
+```bash
+pnpm add @realtimexsco/live-chat react react-dom zustand tailwindcss
+pnpm add -D @tailwindcss/vite @vitejs/plugin-react
+```
+### 3. File structure
+```
+src/
+├── main.tsx
+├── App.tsx
+├── index.css          ← Tailwind + package CSS (see above)
+└── configs/
+    └── chat.config.ts
+```
+### 4. `src/main.tsx`
+```tsx
+import { createRoot } from "react-dom/client";
+import "./index.css";
+import App from "./App";
+createRoot(document.getElementById("root")!).render(<App />);
+```
+### 5. `src/App.tsx`
+```tsx
+import ChatMain from "@realtimexsco/live-chat";
+import { chatConfig } from "./configs/chat.config";
+export default function App() {
+  return (
+    <div className="h-dvh min-h-0 overflow-hidden">
+      <ChatMain
+        clientId={chatConfig.clientId}
+        accessToken={chatConfig.accessToken}
+        loggedUserDetails={chatConfig.loggedUserDetails}
+        apiUrl={chatConfig.apiUrl}
+        socketUrl={chatConfig.socketUrl}
+        themeColor={chatConfig.themeColor}
+      />
+    </div>
+  );
+}
+```
+### 6. Run
 ```bash
-pnpm add @realtimexsco/live-chat@latest
-rm -rf .next
 pnpm dev
 ```
 ---
-## How it works
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│ <Chat>  — provider                                                    │
-│   initializes auth (clientId + accessToken), REST API client,         │
-│   Socket.IO connection, and the Zustand store                         │
-└───────────────┬───────────────────────────────────────────────────────┘
-                │ provides context + store
-        ┌───────┴────────┐
-        ▼                ▼
- <ChannelList>     <Channel>  (wraps the active conversation)
-  lists convos      1. resolves conversationId (DM vs group)
-  click → sets      2. fetches message history via API
-  activeChannel     3. joins the socket room, marks messages read
-        │                │
-        ▼                ▼
-   activeChannel    <MessageList> renders the thread
-   in store         <MessageInput> sends (optimistic UI)
-                         │
-                         ▼
-              Socket events (new / edited / deleted message,
-              reactions, read receipts, forwards) update the
-              Zustand store → React re-renders automatically
-```
-**Lifecycle in short:**
-1. `<Chat>` boots auth, the API client, the socket, and the store.
-2. `<ChannelList>` shows conversations; selecting one calls `setActiveChannel`.
-3. `<Channel>` reacts to the active channel — fetches messages, joins the socket
-   room, and marks them read.
-4. `<MessageInput>` sends a message **optimistically** (it shows immediately),
-   then reconciles with the server acknowledgement.
-5. Incoming socket events mutate the Zustand store, and the UI updates reactively.
+## Next.js — full setup
----
+### 1. Create project
-## `Chat` provider props
+```bash
+pnpm create next-app@latest my-chat-app --typescript --tailwind --app --src-dir
+cd my-chat-app
+```
-| Prop | Type | Required | Description |
-| ---- | ---- | -------- | ----------- |
-| `client` | `{ id: string }` | Yes | RealtimeX client / app id |
-| `accessToken` | `string` | Yes | JWT access token |
-| `loggedUserDetails` | `{ _id, name, email, ... }` | Yes | Current user profile |
-| `apiUrl` | `string` | No | REST API base (default: `http://localhost:5000/api/v1`) |
-| `socketUrl` | `string` | No | Socket server URL (default: `http://localhost:5000`) |
-| `themeColor` | `string` | No | Primary chat accent color (default: `#7494ec`) |
-| `theme` | `"light" \| "dark"` | No | Color scheme |
-| `uiConfig` | `UIConfig` | No | Sidebar / header UI toggles |
-| `onMessageReceived` | `(msg) => void` | No | Fired when a message arrives in a non-active chat |
-| `onSocketConnected` | `(socketId) => void` | No | Socket connected callback |
-| `onSocketError` | `(error) => void` | No | Socket error callback |
-| `children` | `ReactNode` | Yes | Your chat layout |
-### `UIConfig`
+### 2. Install
-```ts
-{
-  showSidebarAvatar?: boolean;   // default: true
-  sidebarAvatarColor?: string;
-  showChannelDetails?: boolean;  // default: true
-  messageDateFormat?: (date: string) => string;
+```bash
+pnpm add @realtimexsco/live-chat zustand
+pnpm add -D @tailwindcss/postcss
+```
+### 3. `src/app/chat/page.tsx`
+```tsx
+"use client";
+import ChatMain from "@realtimexsco/live-chat";
+import { chatConfig } from "@/configs/chat.config";
+export default function ChatPage() {
+  return (
+    <div className="h-dvh min-h-0 overflow-hidden">
+      <ChatMain
+        clientId={chatConfig.clientId}
+        accessToken={chatConfig.accessToken}
+        loggedUserDetails={chatConfig.loggedUserDetails}
+        apiUrl={chatConfig.apiUrl}
+        socketUrl={chatConfig.socketUrl}
+        themeColor={chatConfig.themeColor}
+      />
+    </div>
+  );
 }
 ```
+### 4. Run
+```bash
+pnpm dev
+```
+Open `http://localhost:3000/chat`
 ---
-## Layout customization
+## Environment variables
+Optional — use in `chat.config.ts`:
-Edit your layout config or pass overrides inline:
+```env
+# .env.local (Next.js) or .env (Vite with VITE_ prefix)
+NEXT_PUBLIC_CHAT_CLIENT_ID=your-client-id
+NEXT_PUBLIC_API_V1_BASE_URL=https://realtimex.softwareco.com/api/v1
+NEXT_PUBLIC_SOCKET_URL=https://realtimex.softwareco.com
+```
 ```ts
-export const chatLayoutConfig = {
-  sidebar: true,           // left panel wrapper
-  loggedUserDetails: true, // user profile + new chat button
-  channelList: true,       // conversation list ("Messages")
-  header: true,            // channel header (name, calls, menu)
-  messageList: true,       // message bubbles area
-  input: true,             // message composer
-  forwardModal: true,      // forward message dialog
+export const chatConfig = {
+  clientId: process.env.NEXT_PUBLIC_CHAT_CLIENT_ID ?? "",
+  accessToken: "YOUR_JWT_ACCESS_TOKEN",
+  apiUrl: process.env.NEXT_PUBLIC_API_V1_BASE_URL ?? "",
+  socketUrl:
+    process.env.NEXT_PUBLIC_SOCKET_URL ??
+    (process.env.NEXT_PUBLIC_API_V1_BASE_URL ?? "").replace(/\/api\/v1\/?$/, ""),
+  // ...
 };
 ```
-Examples:
+Vite uses `import.meta.env.VITE_*` instead of `NEXT_PUBLIC_*`.
+---
+## Dev proxy (CORS)
+If the API blocks browser requests during local dev, proxy through your dev server.
+**Vite `vite.config.ts`:**
 ```ts
-{ input: false }        // read-only chat (no composer)
-{ sidebar: false }      // full-width messages (hide sidebar)
-{ forwardModal: false } // hide forward modal
+server: {
+  proxy: {
+    "/chat-api": {
+      target: "https://YOUR_API_HOST",
+      changeOrigin: true,
+      rewrite: (path) => path.replace(/^\/chat-api/, "/api/v1"),
+    },
+  },
+},
 ```
-Pass to `ChatMain`, `ChatLayout`, or `ModularChatLayout`:
+Then set `apiUrl: "/chat-api"` in `chat.config.ts` for local development.
+---
+## Architecture
-```tsx
-<ChatLayout layout={{ sidebar: true, input: false }} />
 ```
+ChatMain
+  ├── ChatThemeProvider        (themeColor, light/dark)
+  ├── ChatLocaleProvider       (locale, timezone, hour12)
+  ├── Chat
+  │     ├── Auth + REST API + Socket.IO + Zustand store
+  │     └── ChatCustomizationProvider   (components, classNames, features)
+  │           └── ChatLayout  (resolveComponent → DefaultChatLayout or custom)
+  │                 ├── Sidebar: LoggedUserDetails + ChannelList
+  │                 └── Main: ChannelHeader + MessageList + MessageInput
+  │                       └── ChannelHeaderView
+  │                             ├── resolveComponent → drawers (Members, Details, …)
+  │                             └── resolveComponent → modals (Clear, Delete, Block)
+  └── ChatAlertsProvider       (error / info banner)
+```
+**Customization flow:**
+1. You pass `components` / `classNames` / `features` on `ChatMain`.
+2. `ChatCustomizationProvider` merges your config (unset slots stay empty).
+3. Each render site calls `resolveComponent(slot, PackageDefault)` — custom wins, else default.
+4. No `components` prop → every slot uses package defaults (full default chat UI).
+**Runtime flow:**
+1. `ChatMain` runs client-user login, sets JWT, connects socket.
+2. User picks a conversation → messages fetch + socket room join.
+3. Send is optimistic — message appears immediately, reconciles on server ack.
+4. Socket events update Zustand → UI re-renders automatically.
 ---
-## Exported components & hooks
-| Export | Description |
-| ------ | ----------- |
-| `ChatMain` (default) | All-in-one chat UI with optional `layout` prop |
-| `Chat` | Provider — initializes auth, API, socket, store |
-| `ChatLayout` | Composable shell — toggle sections via `layout` prop |
-| `Channel` | Active conversation lifecycle (fetch, join, mark-read) |
-| `ChannelList` | Conversation sidebar list |
-| `ChannelHeader` | Chat header with search, details, actions |
-| `MessageList` | Message thread (`ActiveChannelMessages`) |
-| `MessageInput` | Compose box (`ChannelMessageBox`) |
-| `LoggedUserDetails` | User profile + new chat / create group |
-| `ForwardModal` | Forward message modal |
-| `useChatContext` | `{ activeChannel, setActiveChannel, themeColor, uiConfig }` |
-| `useChatStore` | Full Zustand store (messages, socket actions, status, error) |
-| `useChatController` | State + handlers used internally by `ChatLayout` |
-| `ChatLayoutConfig` | Type for layout section toggles |
-| `defaultChatLayoutConfig` | Default layout (all sections enabled) |
-| `mergeChatLayoutConfig` | Merge partial layout with defaults |
-| `socketService` | Low-level socket service |
-| `getSocketConfig` | Socket configuration helper |
-| `setChatClientId`, `setChatAccessToken`, `setChatBaseURL` | Manual API config |
-| `IChannel`, `IMessage`, `IAttachment` | Core TypeScript types |
-| `ISocketConfig` | Socket config type |
-### Import example
+## All exports
 ```ts
-import {
+import ChatMain, {
+  // ── Providers & layout ──
   Chat,
-  ChatMain,
   ChatLayout,
+  DefaultChatLayout,
   Channel,
+  ChatThemeProvider,
+  ChatLocaleProvider,
+  ChatAlertsProvider,
+  ChatCustomizationProvider,
+  // ── UI components (standalone or customization reference) ──
   ChannelList,
   ChannelHeader,
   MessageList,
   MessageInput,
   LoggedUserDetails,
   ForwardModal,
+  MessageItem,
+  ChatAvatar,
+  DefaultChatAvatar,
+  ChannelListItem,
+  DefaultChannelListItem,
+  HeaderCallActions,
+  packageDefaultComponents,
+  // ── Hooks ──
   useChatStore,
   useChatController,
+  useChatContext,
+  useChatCustomization,
+  useChatCustomizationOptional,
+  useChatFeatures,
+  useChatFeaturesOptional,
+  useChatTheme,
+  useChatLocale,
+  useChatAlerts,
+  // ── Layout helpers ──
+  mergeChatLayoutConfig,
+  defaultChatLayoutConfig,
+  mergeChatCustomization,
+  defaultChatClassNames,
+  defaultChatComponents,
+  defaultChatFeatures,
+  // ── API / socket helpers ──
+  setChatClientId,
+  setChatAccessToken,
+  setChatBaseURL,
+  setChatSocketUrl,
+  setChatQueryParams,
+  getChatQueryParams,
+  setChatQueryParamApis,
+  getChatQueryParamApis,
+  setChatQueryParamsByApi,
+  getChatQueryParamsByApi,
+  CHAT_API_KEYS,
+  CHAT_GET_API_KEYS,
+  resolveChatApiKey,
+  socketService,
   getSocketConfig,
+  showNotification,
+  downloadFile,
+  // ── Types ──
+  type ChatApiKey,
+  type ChatGetApiKey,
+  type ChatQueryParams,
+  type ChatQueryParamsByApi,
+  type ChatComponents,
+  type ChatClassNames,
+  type ChatFeatures,
+  type ChatCallContext,
   type ChatLayoutConfig,
+  type ChatColorMode,
+  type ChatCustomizationConfig,
+  type UIConfig,
+  type IChannel,
+  type IMessage,
+  type IAttachment,
+  type AvatarSlotProps,
+  type MessageItemSlotProps,
+  type ChannelHeaderSlotProps,
+  type ChannelListItemSlotProps,
+  type ChatLayoutSlotProps,
+  type HeaderCallActionsSlotProps,
+  type PhoneCallButtonSlotProps,
+  type VideoCallButtonSlotProps,
+  type ActiveChannelMessagesSlotProps,
+  type ChannelMessageBoxSlotProps,
+  type ForwardModalSlotProps,
+  type MembersDrawerSlotProps,
+  // … all *SlotProps types are exported
 } from "@realtimexsco/live-chat";
 ```
----
+**CSS import (not from JS):**
-## Theming
-Set a single accent color via the `themeColor` prop; it drives the
-`--chat-theme*` CSS variables at runtime. Override any of the variables in your
-global CSS to customize further, and pass `theme="dark"` for dark mode.
-```tsx
-<Chat themeColor="#7c3aed" theme="dark">{/* … */}</Chat>
+```css
+@import "@realtimexsco/live-chat/styles.css";
 ```
 ---
 ## Troubleshooting
-### Old or broken UI
-| Cause | Fix |
-| ----- | --- |
-| Wrong `@source` path in CSS | Use `../node_modules` from `src/index.css`, or `../../node_modules` from `src/app/globals.css` |
-| Missing `styles.css` import | `@import "@realtimexsco/live-chat/styles.css"` |
-| Missing `--chat-theme` CSS vars | Copy full CSS block from [Tailwind setup](#tailwind-css-v4-setup-required) |
-| Stale Vite cache | `rm -rf node_modules/.vite && pnpm dev` |
-| Stale Next.js cache | `rm -rf .next && pnpm dev` |
-| Package in `optimizeDeps.include` (Vite) | Use `exclude: ["@realtimexsco/live-chat"]` |
-| Missing `transpilePackages` (Next.js) | Add `transpilePackages: ["@realtimexsco/live-chat"]` in `next.config.ts` |
-### `Rendered more hooks than during the previous render`
-Declare all hooks at the **top** of the component, before any conditional
-`return`. Handle loading / error states after the hooks.
-### Chat loads but messages don't appear
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| Unstyled / broken UI | Missing Tailwind `@source` | Add `@source` to package `dist/index.mjs` and `dist/index.cjs` |
+| No styles at all | Missing `styles.css` import | `@import "@realtimexsco/live-chat/styles.css"` |
+| Wrong `@source` depth | Next.js vs Vite path | Use `../../node_modules` in `src/app/globals.css` |
+| TypeScript: no declaration file | Published tarball missing `dist/index.d.ts` | Reinstall latest version; verify `dist/index.d.ts` exists |
+| Next.js build error | Package not transpiled | `transpilePackages: ["@realtimexsco/live-chat"]` |
+| `use client` error | Server Component import | Add `"use client"` to chat page |
+| Whole page scrolls, not messages | Missing height chain | Set `viewportHeight="screen"` or `viewportHeight="calc(100dvh - 4rem)"` on `<ChatMain />` |
+| Messages don't load | Wrong credentials / CORS | Check `apiUrl`, JWT, proxy in dev |
+| Socket won't connect | Wrong `socketUrl` | No `/api/v1` on socket URL |
+| Duplicate React hooks error | Duplicate React copies | `dedupe: ["react", "react-dom"]` in Vite |
+| Sent message on **left** and **right** | `_id` mismatch or duplicate echo | Ensure `loggedUserDetails._id` matches JWT `_id` |
+| Custom layout has no data | Missing hook | Call `useChatController()` inside custom `ChatLayout` |
+| Custom `MembersDrawer` still shows package UI | Old package version (< 1.1.55) | Upgrade to **1.1.55+** — drawer slots now use `resolveComponent` |
+| Custom drawer works but other slots are default | Expected behavior | Only pass slots you want to override in `components` |
+| Passed `components` but slot unchanged | Slot not wired or parent replaced | See [Which slots are wired](#which-slots-are-wired); use `ChannelHeader` to replace all header drawers |
+| Custom `HeaderCallActions` crashes | Recursive import | Don't import package `HeaderCallActions` inside your slot |
+| Vite stale UI after upgrade | Cached prebundle | `rm -rf node_modules/.vite && pnpm dev` |
+| Rate limit banner | API returned 429 | Wait for cooldown; reduce rapid API calls in dev |
-Ensure `<Channel>` wraps `MessageList` and `MessageInput`. The package keys
-messages by `conversationId` internally — don't key DM messages by user id.
-### Group events firing in DM (or vice versa)
+---
-Always use the composable pattern with `<Channel>`, and don't manually emit
-`group_join` / `group_message_read` outside the package.
+## Setup checklist
+Copy this list when integrating into a new project:
+- [ ] Node.js 18+
+- [ ] `pnpm add @realtimexsco/live-chat react react-dom zustand tailwindcss`
+- [ ] Tailwind v4 plugin installed (`@tailwindcss/vite` or `@tailwindcss/postcss`)
+- [ ] `index.css` / `globals.css` imports `tailwindcss` + `@realtimexsco/live-chat/styles.css`
+- [ ] `@source` points to `dist/index.mjs` and `dist/index.cjs` (correct depth for your CSS path)
+- [ ] `:root` has `--chat-theme` and `--chat-theme-5` … `--chat-theme-60`
+- [ ] `@theme inline` maps `--color-chat-theme*` variables
+- [ ] `chat.config.ts` with real `clientId`, `accessToken`, `apiUrl`, `socketUrl`
+- [ ] `loggedUserDetails._id` matches JWT `_id`
+- [ ] Chat page wrapped in `h-dvh min-h-0 overflow-hidden`
+- [ ] Next.js: `"use client"` on chat page + `transpilePackages`
+- [ ] Vite: `optimizeDeps.exclude` includes `@realtimexsco/live-chat`
+- [ ] Optional: `components` for custom UI (Case 1 / 2)
+- [ ] Optional: `classNames` for theme tweaks (Case 3)
+- [ ] Optional: `features` for phone/video callbacks
+- [ ] Optional: `layout` to hide sections
+- [ ] Optional: `colorMode` synced with your app theme
+- [ ] Verify: `node_modules/@realtimexsco/live-chat/dist/index.d.ts` exists
+- [ ] Use package **≥ 1.1.56** for drawer customization + default fallback fixes
-### Duplicate React / invalid hook call
+---
-Add `resolve: { dedupe: ["react", "react-dom", "zustand"] }` to `vite.config.ts`.
+## Package development (maintainers)
-### `use client` error (Next.js)
+This package is built from the **live-chat-frontend** reference app. Source lives in `src/`; published output is `dist/`.
-Any file importing `Chat`, `useChatStore`, or chat hooks must start with:
+### Sync from frontend
-```tsx
-"use client";
+```bash
+cd chat-ui-package
+pnpm sync    # copies app/chat → src/chat, patches API client & types, fixes imports
+pnpm build   # tsup → dist/
 ```
-### Socket / API errors
-- `apiUrl` must end with `/api/v1`
-- `socketUrl` = base host only (no `/api/v1`)
-- Use a dev proxy (`/chat-api`) or Next.js rewrite if CORS blocks requests
+`scripts/sync-from-frontend.mjs` copies UI from the frontend repo. Protected files (not overwritten):
-### Hydration warnings (Next.js)
+- `src/index.ts`, `ChatMain.tsx`, `ChatContext.tsx`, `DefaultChatLayout.tsx`
+- `src/chat/channel-header/ChannelHeaderView.tsx` (customization wiring)
+- Store/context entrypoints
-Keep chat inside a client component (`chat/page.tsx`). Do not render
-socket-dependent UI in server components.
----
+After UI changes in **live-chat-frontend**, run `pnpm sync` then `pnpm build`, bump version, publish.
-## Checklist
+### Local install in consumer app (e.g. Elstar)
-### All projects
+```bash
+cd chat-ui-package && pnpm pack --pack-destination .
+```
-- [ ] `@realtimexsco/live-chat` installed from npm
-- [ ] Peer deps: `react`, `react-dom`, `zustand`, `tailwindcss` v4
-- [ ] Global CSS imports `tailwindcss` + `@realtimexsco/live-chat/styles.css`
-- [ ] `@source` paths point to package `dist/index.mjs` and `dist/index.cjs`
-- [ ] `--chat-theme*` CSS variables defined in `:root`
-- [ ] `src/configs/chat.config.ts` (or `.js`) — your credentials
-- [ ] Chat wrapped in `h-dvh min-h-0 overflow-hidden` container
+In consumer `package.json`:
-### React (Vite)
+```json
+"@realtimexsco/live-chat": "file:../path/to/realtimexsco-live-chat-1.1.0.tgz"
+```
-- [ ] `vite.config.ts` — `@` alias, dedupe, **exclude** package from `optimizeDeps`
-- [ ] `jsconfig.json` / `tsconfig.json` — `"@/*": ["src/*"]`
-- [ ] `src/main.jsx` imports `index.css`
-- [ ] Clear `node_modules/.vite` after every package upgrade
+Then `pnpm install` in the consumer app.
-### Next.js
+### Version history (customization)
-- [ ] `next.config.ts` — `transpilePackages: ["@realtimexsco/live-chat"]`
-- [ ] `postcss.config.mjs` — `@tailwindcss/postcss`
-- [ ] `globals.css` uses **`../../node_modules`** in `@source`
-- [ ] `src/app/chat/page.tsx` — `'use client'` + `<Chat>` + `<ChatLayout>`
-- [ ] Clear `.next` after every package upgrade
+| Version | Change |
+|---------|--------|
+| **1.1.56** | Hardened default fallback (`resolveComponent` null check); drawer slots use optional customization hook |
+| **1.1.55** | Drawer slots (`MembersDrawer`, `ChannelDetailsDrawer`, etc.) wired through `resolveComponent` |
+| **1.1.53** | UI polish synced from frontend (bubble curves, drawer headers, destructive menu icons) |
 ---
 ## License
-[MIT](LICENSE) © RealtimeX
+[MIT](LICENSE)