@realtimexsco/live-chat 1.0.0 → 1.2.0

package/README.md

@@ -1,14 +1,14 @@
 # @realtimexsco/live-chat
 
-> Drop-in real-time chat UI for React — direct messages, group chats, reactions, replies, forwarding, pinned/starred messages, and more. Built on Socket.IO, Zustand, Tailwind CSS v4, and Radix UI.
+> 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.
 
 [![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)
 
-Use the all-in-one `<ChatMain />` for a complete chat app in minutes, or compose
-the individual pieces (`<Chat>`, `<ChannelList>`, `<MessageList>`, …) for full
-control over layout and styling.
+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>`, …).
 
 ---
 
@@ -18,13 +18,19 @@ control over layout and styling.
 - [Requirements](#requirements)
 - [Installation](#installation)
 - [Tailwind CSS v4 setup (required)](#tailwind-css-v4-setup-required)
-- [Quick start — full UI](#quick-start--full-ui)
-- [Composable usage (recommended)](#composable-usage-recommended)
+- [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)
 
 ---
@@ -36,29 +42,32 @@ control over layout and styling.
 - 😀 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)
-- 🧩 **Two integration modes** — all-in-one component or composable building blocks
+- 🧩 **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
 
 ---
 
 ## Requirements
 
-This package relies on the following **peer dependencies** in your app:
-
-| Peer dependency | Version |
-| --------------- | ------- |
-| `react`         | ≥ 17 (19 recommended) |
-| `react-dom`     | ≥ 17 |
-| `zustand`       | ≥ 4 |
-| `tailwindcss`   | **v4** (required) |
+| 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) |
 
 You also need, at runtime:
 
-- **Client ID** — your RealtimeX client/app id
-- **Access token** — JWT for the logged-in user
-- **Logged user details** — `{ _id, name, email }`
-- **API URL** — e.g. `https://your-server.com/api/v1`
-- **Socket URL** — e.g. `https://your-server.com`
+| 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` |
 
 ---
 
@@ -70,200 +79,860 @@ npm install @realtimexsco/live-chat
 npm install react react-dom zustand tailwindcss @tailwindcss/vite
 ```
 
-> Published on the public npm registry — no `.npmrc` or auth token needed.
+Or with pnpm:
+
+```bash
+pnpm add @realtimexsco/live-chat react react-dom zustand tailwindcss @tailwindcss/vite
+```
+
+> Published on the public npm registry — **no `.npmrc` or auth token needed**.
+
+Verify the installed version:
+
+```bash
+cat node_modules/@realtimexsco/live-chat/package.json | grep version
+```
 
 ---
 
 ## Tailwind CSS v4 setup (required)
 
-The package ships Tailwind utility classes, so your app must (1) import the
-package stylesheet and (2) scan the built package output so Tailwind generates
-the classes it uses.
+The package ships Tailwind utility classes, so your app must:
 
-In your global stylesheet (e.g. `src/index.css`):
+1. Import the package stylesheet
+2. Scan the built package output so Tailwind generates the classes it uses
+3. Define `--chat-theme*` CSS variables
+
+### Vite — `src/index.css`
+
+> From `src/index.css`, `@source` uses `../node_modules`.
 
 ```css
 @import "tailwindcss";
 @import "@realtimexsco/live-chat/styles.css";
 
-/* Scan the package dist so Tailwind emits the classes it uses */
 @source "../node_modules/@realtimexsco/live-chat/dist/index.mjs";
 @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);
+  --foreground: oklch(0.145 0 0);
+  --primary: oklch(0.205 0 0);
+  --primary-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.97 0 0);
+  --muted-foreground: oklch(0.556 0 0);
+  --border: oklch(0.922 0 0);
+  --ring: oklch(0.708 0 0);
+  --destructive: oklch(0.577 0.245 27.325);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.145 0 0);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.145 0 0);
+  --accent: oklch(0.97 0 0);
+  --accent-foreground: oklch(0.205 0 0);
+  --secondary: oklch(0.97 0 0);
+  --secondary-foreground: oklch(0.205 0 0);
+  --input: oklch(0.922 0 0);
 
   /* Chat theme — overridden at runtime by the Chat `themeColor` prop */
-  --chat-theme: #3b82f6;
-  --chat-theme-5: #3b82f60d;
-  --chat-theme-10: #3b82f61a;
-  --chat-theme-20: #3b82f633;
-  --chat-theme-40: #3b82f666;
-  --chat-theme-60: #3b82f699;
+  --chat-theme: #6366f1;
+  --chat-theme-5: #6366f10D;
+  --chat-theme-10: #6366f11A;
+  --chat-theme-20: #6366f133;
+  --chat-theme-40: #6366f166;
+  --chat-theme-60: #6366f199;
+}
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-border: var(--border);
+  --color-ring: var(--ring);
+  --color-destructive: var(--destructive);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-input: var(--input);
+  --color-chat-theme: var(--chat-theme);
+  --color-chat-theme-5: var(--chat-theme-5);
+  --color-chat-theme-10: var(--chat-theme-10);
+  --color-chat-theme-20: var(--chat-theme-20);
+  --color-chat-theme-40: var(--chat-theme-40);
+  --color-chat-theme-60: var(--chat-theme-60);
+}
+
+@layer base {
+  html,
+  body,
+  #root {
+    height: 100%;
+  }
+
+  body {
+    @apply bg-background text-foreground;
+  }
 }
 ```
 
-If you use **Vite**, dedupe React/Zustand and pre-bundle the package:
+### Next.js — `src/app/globals.css`
+
+> **Critical:** `globals.css` is in `src/app/`, so `@source` must use `../../node_modules` (NOT `../node_modules`).
+
+```css
+@import "tailwindcss";
+@import "@realtimexsco/live-chat/styles.css";
+
+@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… */
+```
+
+### `@source` path reference
+
+| CSS file location | Correct `@source` |
+| ----------------- | ----------------- |
+| `src/index.css` | `../node_modules/...` |
+| `src/app/globals.css` | `../../node_modules/...` |
+
+Wrong path → Tailwind skips package classes → **old / broken UI**.
+
+### Vite config
 
 ```ts
 // vite.config.ts
+import path from "path";
+import { fileURLToPath } from "url";
 import { defineConfig } from "vite";
 import react from "@vitejs/plugin-react";
 import tailwindcss from "@tailwindcss/vite";
 
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
 export default defineConfig({
   plugins: [react(), tailwindcss()],
-  resolve: { dedupe: ["react", "react-dom", "zustand"] },
-  optimizeDeps: { include: ["@realtimexsco/live-chat", "zustand"] },
+  resolve: {
+    alias: { "@": path.resolve(__dirname, "src") },
+    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
+
+```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)
+
+```js
+// postcss.config.mjs
+const config = {
+  plugins: { "@tailwindcss/postcss": {} },
+};
+export default config;
+```
+
+---
+
+## Configuration
+
+Create a shared config file and replace `YOUR_*` placeholders with real credentials.
+
+**TypeScript** — `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;
+```
+
+**JavaScript** — `src/configs/chat.config.js`:
+
+```js
+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",
+};
+```
+
+| 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
+## Quick start — full UI (`ChatMain`)
 
-The fastest path. `ChatMain` renders the sidebar, chat area, and modals in one
-component.
+The fastest path. `ChatMain` renders the sidebar, chat area, and modals in one component.
 
 ```tsx
 import ChatMain from "@realtimexsco/live-chat";
+import { chatConfig } from "@/configs/chat.config";
+
+export default function App() {
+  return (
+    <div className="chat-page 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>
+  );
+}
+```
+
+Hide sections via the `layout` prop:
+
+```tsx
+<ChatMain
+  {...chatConfig}
+  clientId={chatConfig.clientId}
+  layout={{ input: false }} // read-only chat
+/>
+```
+
+---
+
+## Composable shell (`ChatLayout`)
+
+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.
+
+```tsx
+import { Chat, ChatLayout } from "@realtimexsco/live-chat";
+import { chatConfig } from "@/configs/chat.config";
+import { chatLayoutConfig } from "@/configs/chat.layout.config";
 
 export default function App() {
   return (
-    <ChatMain
-      clientId="YOUR_CLIENT_ID"
-      accessToken="YOUR_JWT_TOKEN"
-      loggedUserDetails={{
-        _id: "USER_ID",
-        name: "John Doe",
-        email: "john@example.com",
-      }}
-      apiUrl="https://your-server.com/api/v1"
-      socketUrl="https://your-server.com"
-      themeColor="#3b82f6"
-    />
+    <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}
+      >
+        <ChatLayout layout={chatLayoutConfig} themeColor={chatConfig.themeColor} />
+      </Chat>
+    </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,
+};
+```
+
+Or re-export the built-in helpers:
+
+```ts
+import {
+  defaultChatLayoutConfig,
+  mergeChatLayoutConfig,
+  type ChatLayoutConfig,
+} from "@realtimexsco/live-chat";
+
+export const chatLayoutConfig = defaultChatLayoutConfig;
+
+export function mergeLayout(layout: ChatLayoutConfig) {
+  return mergeChatLayoutConfig(layout);
+}
+```
+
 ---
 
-## Composable usage (recommended)
+## Custom layout (advanced)
+
+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.
+
+Use `useChatStore` selectors and pass explicit props to each component (the
+package does not auto-wire props when used outside `ChatLayout`).
 
-Build your own layout from the exported pieces for full control over the
-sidebar, routing, and styling.
+**TypeScript** — `src/components/chat/ModularChatLayout.tsx`:
 
 ```tsx
-import { useState, useCallback } from "react";
+"use client"; // required in Next.js
+
+import { useCallback, useEffect, useState } from "react";
 import {
-  Chat,
   Channel,
-  ChannelList,
   ChannelHeader,
-  MessageList,
-  MessageInput,
-  LoggedUserDetails,
+  ChannelList,
   ForwardModal,
-  useChatContext,
+  LoggedUserDetails,
+  MessageInput,
+  MessageList,
   useChatStore,
+  mergeChatLayoutConfig,
+  type ChatLayoutConfig,
 } from "@realtimexsco/live-chat";
+import classNames from "classnames";
+
+type ModularChatLayoutProps = {
+  layout?: ChatLayoutConfig;
+};
+
+const ModularChatLayout = ({ layout }: ModularChatLayoutProps) => {
+  const sections = mergeChatLayoutConfig(layout);
+  const showSidebar =
+    sections.sidebar && (sections.loggedUserDetails || sections.channelList);
+
+  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],
+  );
 
-function MainChatArea() {
-  const { activeChannel } = useChatContext();
-  const { setActiveChannel, error, status } = useChatStore();
-
-  const [search, setSearch] = useState("");
-  const [isMenuOpen, setIsMenuOpen] = useState(false);
-  const [replyToMessage, setReplyToMessage] = useState<any>(null);
-  const [forwardMessage, setForwardMessage] = useState<any>(null);
-
-  // ⚠️ Declare all hooks BEFORE any conditional return (see Troubleshooting)
-  const handleUserSelect = useCallback(
-    (channel: any) => {
+  const handleForwardComplete = useCallback(
+    (channel: Parameters<typeof setActiveChannel>[0]) => {
       setActiveChannel(channel);
-      setIsMenuOpen(false);
-      setReplyToMessage(null);
+      setIsForwardModalOpen(false);
       setForwardMessage(null);
     },
-    [setActiveChannel]
+    [setActiveChannel],
   );
 
-  if (error) return <div>Connection error: {error}</div>;
-  if (status === "connecting" || status === "idle") return <div>Loading chat…</div>;
+  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],
+  );
 
   return (
-    <div className="flex h-screen w-screen overflow-hidden">
-      <aside className="w-[400px] border-r flex flex-col">
-        <LoggedUserDetails
-          searchQuery={search}
-          setSearchQuery={setSearch}
-          isCreateModalOpen={isMenuOpen}
-          setIsCreateModalOpen={setIsMenuOpen}
-          onUserSelect={handleUserSelect}
-        />
-        <ChannelList debouncedSearch={search} onNewChatClick={() => setIsMenuOpen(true)} />
-      </aside>
+    <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>
+        )}
 
-      <main className="flex flex-col flex-1 min-w-0">
-        {/* Channel resolves the conversation, fetches messages, and joins the socket room */}
         <Channel>
-          {activeChannel ? (
-            <>
-              <ChannelHeader />
-              <div className="flex-1 min-h-0">
-                <MessageList
-                  onReply={(msg) => setReplyToMessage(msg)}
-                  onForward={(msg) => setForwardMessage(msg)}
-                />
-              </div>
+          {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
-                replyTo={replyToMessage}
-                onCancelReply={() => setReplyToMessage(null)}
-                onMessageSent={() => setReplyToMessage(null)}
+                activeChannel={activeChannel}
+                conversationId={conversationId}
+                onSendMessage={handleSendMessage}
+                replyTo={replyTo}
+                onCancelReply={() => setReplyTo(null)}
               />
-            </>
-          ) : (
-            <div className="flex h-full items-center justify-center text-gray-400">
-              Select a conversation
             </div>
           )}
         </Channel>
-      </main>
+      </div>
 
-      {forwardMessage && (
+      {sections.forwardModal && (
         <ForwardModal
-          isOpen
-          onClose={() => setForwardMessage(null)}
+          isOpen={isForwardModalOpen}
+          onClose={() => {
+            setIsForwardModalOpen(false);
+            setForwardMessage(null);
+          }}
           message={forwardMessage}
-          onForwardComplete={(channel) => setActiveChannel(channel)}
+          onForwardComplete={handleForwardComplete}
         />
       )}
     </div>
   );
-}
+};
+
+export default ModularChatLayout;
+```
+
+Wrap with `<Chat>`:
+
+```tsx
+import { Chat } from "@realtimexsco/live-chat";
+import ModularChatLayout from "@/components/chat/ModularChatLayout";
+import { chatConfig } from "@/configs/chat.config";
+import { chatLayoutConfig } from "@/configs/chat.layout.config";
 
 export default function App() {
   return (
-    <Chat
-      client={{ id: "YOUR_CLIENT_ID" }}
-      accessToken="YOUR_JWT_TOKEN"
-      loggedUserDetails={{ _id: "USER_ID", name: "John Doe", email: "john@example.com" }}
-      apiUrl="https://your-server.com/api/v1"
-      socketUrl="https://your-server.com"
-      themeColor="#3b82f6"
-      onMessageReceived={(msg) => console.log("Background message:", msg)}
-      onSocketConnected={(id) => console.log("Socket connected:", id)}
-      onSocketError={(err) => console.error("Socket error:", err)}
-    >
-      <MainChatArea />
-    </Chat>
+    <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>
+  );
+}
+```
+
+> **Important:** Declare all hooks (`useState`, `useCallback`, `useEffect`, …) at
+> the **top** of the component, before any conditional `return`.
+
+---
+
+## React (Vite) — complete setup
+
+### Project structure
+
+```
+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
+```
+
+### Create app
+
+```bash
+pnpm create vite my-app --template react
+cd my-app
+```
+
+### `package.json` dependencies
+
+```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"
+  }
+}
+```
+
+### `jsconfig.json`
+
+```json
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": { "@/*": ["src/*"] }
+  },
+  "include": ["src"]
+}
+```
+
+### `src/main.jsx`
+
+```jsx
+import { createRoot } from "react-dom/client";
+import "./index.css";
+import App from "./App.jsx";
+
+createRoot(document.getElementById("root")).render(<App />);
+```
+
+### Run
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Open **http://localhost:3000**
+
+Production:
+
+```bash
+pnpm build
+pnpm preview
+```
+
+### Update package
+
+```bash
+pnpm add @realtimexsco/live-chat@latest
+rm -rf node_modules/.vite dist
+pnpm dev
+```
+
+Hard refresh: **Ctrl + Shift + R**
+
+---
+
+## Next.js (App Router) — complete setup
+
+### Project structure
+
+```
+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
+```
+
+### Create app
+
+```bash
+pnpm create next-app@latest my-chat-app --typescript --tailwind --app --src-dir
+cd my-chat-app
+```
+
+### `package.json` dependencies
+
+```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"
+  }
+}
+```
+
+### `tsconfig.json` path alias
+
+```json
+{
+  "compilerOptions": {
+    "paths": { "@/*": ["./src/*"] }
+  }
+}
+```
+
+### `src/app/layout.tsx`
+
+```tsx
+import type { Metadata } from "next";
+import "./globals.css";
+
+export const metadata: Metadata = {
+  title: "RealtimeX Chat",
+  description: "RealtimeX chat integration with Next.js",
+};
+
+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>
+  );
+}
+```
+
+### `src/app/chat/page.tsx`
+
+```tsx
+"use client";
+
+import { Chat, ChatLayout } from "@realtimexsco/live-chat";
+import { chatConfig } from "@/configs/chat.config";
+import { chatLayoutConfig } from "@/configs/chat.layout.config";
+
+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}
+      >
+        <ChatLayout layout={chatLayoutConfig} themeColor={chatConfig.themeColor} />
+      </Chat>
+    </div>
   );
 }
 ```
 
-> **Important:** Wrap the active chat panel in `<Channel>`. It resolves the
-> conversation id, fetches messages, and emits the correct group/DM socket
-> events. Don't manually emit `group_join` / `group_message_read` yourself.
+> `'use client'` is required — the chat package uses React hooks and Zustand.
+
+### Run
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Open **http://localhost:3000/chat**
+
+Clear cache after CSS or package changes:
+
+```bash
+rm -rf .next
+pnpm dev
+```
+
+### Update package
+
+```bash
+pnpm add @realtimexsco/live-chat@latest
+rm -rf .next
+pnpm dev
+```
 
 ---
 
@@ -335,64 +1004,182 @@ export default function App() {
 
 ---
 
+## Layout customization
+
+Edit your layout config or pass overrides inline:
+
+```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
+};
+```
+
+Examples:
+
+```ts
+{ input: false }        // read-only chat (no composer)
+{ sidebar: false }      // full-width messages (hide sidebar)
+{ forwardModal: false } // hide forward modal
+```
+
+Pass to `ChatMain`, `ChatLayout`, or `ModularChatLayout`:
+
+```tsx
+<ChatLayout layout={{ sidebar: true, input: false }} />
+```
+
+---
+
 ## Exported components & hooks
 
 | Export | Description |
 | ------ | ----------- |
-| `ChatMain` | All-in-one chat UI (default export) |
+| `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 |
-| `MessageInput` | Compose box |
+| `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
+
+```ts
+import {
+  Chat,
+  ChatMain,
+  ChatLayout,
+  Channel,
+  ChannelList,
+  ChannelHeader,
+  MessageList,
+  MessageInput,
+  LoggedUserDetails,
+  ForwardModal,
+  useChatStore,
+  useChatController,
+  getSocketConfig,
+  type ChatLayoutConfig,
+} from "@realtimexsco/live-chat";
+```
 
 ---
 
 ## Theming
 
 Set a single accent color via the `themeColor` prop; it drives the
-`--chat-theme*` CSS variables. Override any of the variables shown in the
-[Tailwind setup](#tailwind-css-v4-setup-required) to customize further, and pass
-`theme="dark"` for dark mode.
+`--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>
+<Chat themeColor="#7c3aed" theme="dark">{/* … */}</Chat>
 ```
 
 ---
 
 ## Troubleshooting
 
-**`Rendered more hooks than during the previous render`**
-Declare all hooks (`useState`, `useCallback`, …) at the **top** of the component,
-before any conditional `return`. Handle loading/error states after the hooks.
+### 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.
 
-**Styles missing / unstyled components**
-1. Confirm the `@source` paths in your CSS point to the package `dist/` files.
-2. Import `@realtimexsco/live-chat/styles.css`.
-3. Restart your dev server after installing or updating the package.
+### Chat loads but messages don't appear
 
-**Chat loads but messages don't appear**
 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)**
+### 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.
 
-**Duplicate React / invalid hook call**
-Add `resolve: { dedupe: ["react", "react-dom", "zustand"] }` to your
-`vite.config.ts`.
+### Duplicate React / invalid hook call
+
+Add `resolve: { dedupe: ["react", "react-dom", "zustand"] }` to `vite.config.ts`.
+
+### `use client` error (Next.js)
+
+Any file importing `Chat`, `useChatStore`, or chat hooks must start with:
+
+```tsx
+"use client";
+```
+
+### 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
+
+### Hydration warnings (Next.js)
+
+Keep chat inside a client component (`chat/page.tsx`). Do not render
+socket-dependent UI in server components.
+
+---
+
+## Checklist
+
+### All projects
+
+- [ ] `@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
+
+### React (Vite)
+
+- [ ] `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
+
+### Next.js
+
+- [ ] `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
 
 ---
 
 ## License
 
-[MIT](https://www.npmjs.com/package/@realtimexsco/live-chat) © RealtimeX
+[MIT](LICENSE) © RealtimeX