@realtimexsco/live-chat 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RealtimeX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,398 @@
+# @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.
+
+[![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.
+
+---
+
+## Table of contents
+
+- [Features](#features)
+- [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)
+- [How it works](#how-it-works)
+- [`Chat` provider props](#chat-provider-props)
+- [Exported components & hooks](#exported-components--hooks)
+- [Theming](#theming)
+- [Troubleshooting](#troubleshooting)
+- [License](#license)
+
+---
+
+## Features
+
+- 💬 **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)
+- 🧩 **Two integration modes** — all-in-one component or composable building blocks
+- 🦾 Ships TypeScript types and ESM + CJS builds
+
+---
+
+## 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) |
+
+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`
+
+---
+
+## Installation
+
+```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
+```
+
+> Published on the public npm registry — no `.npmrc` or auth token needed.
+
+---
+
+## 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.
+
+In your global stylesheet (e.g. `src/index.css`):
+
+```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";
+
+:root {
+  --radius: 0.625rem;
+
+  /* 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;
+}
+```
+
+If you use **Vite**, dedupe React/Zustand and pre-bundle the package:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import tailwindcss from "@tailwindcss/vite";
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  resolve: { dedupe: ["react", "react-dom", "zustand"] },
+  optimizeDeps: { include: ["@realtimexsco/live-chat", "zustand"] },
+});
+```
+
+---
+
+## Quick start — full UI
+
+The fastest path. `ChatMain` renders the sidebar, chat area, and modals in one
+component.
+
+```tsx
+import ChatMain from "@realtimexsco/live-chat";
+
+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"
+    />
+  );
+}
+```
+
+---
+
+## Composable usage (recommended)
+
+Build your own layout from the exported pieces for full control over the
+sidebar, routing, and styling.
+
+```tsx
+import { useState, useCallback } from "react";
+import {
+  Chat,
+  Channel,
+  ChannelList,
+  ChannelHeader,
+  MessageList,
+  MessageInput,
+  LoggedUserDetails,
+  ForwardModal,
+  useChatContext,
+  useChatStore,
+} from "@realtimexsco/live-chat";
+
+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) => {
+      setActiveChannel(channel);
+      setIsMenuOpen(false);
+      setReplyToMessage(null);
+      setForwardMessage(null);
+    },
+    [setActiveChannel]
+  );
+
+  if (error) return <div>Connection error: {error}</div>;
+  if (status === "connecting" || status === "idle") return <div>Loading chat…</div>;
+
+  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>
+
+      <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>
+              <MessageInput
+                replyTo={replyToMessage}
+                onCancelReply={() => setReplyToMessage(null)}
+                onMessageSent={() => setReplyToMessage(null)}
+              />
+            </>
+          ) : (
+            <div className="flex h-full items-center justify-center text-gray-400">
+              Select a conversation
+            </div>
+          )}
+        </Channel>
+      </main>
+
+      {forwardMessage && (
+        <ForwardModal
+          isOpen
+          onClose={() => setForwardMessage(null)}
+          message={forwardMessage}
+          onForwardComplete={(channel) => setActiveChannel(channel)}
+        />
+      )}
+    </div>
+  );
+}
+
+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>
+  );
+}
+```
+
+> **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.
+
+---
+
+## 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.
+
+---
+
+## `Chat` provider props
+
+| 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`
+
+```ts
+{
+  showSidebarAvatar?: boolean;   // default: true
+  sidebarAvatarColor?: string;
+  showChannelDetails?: boolean;  // default: true
+  messageDateFormat?: (date: string) => string;
+}
+```
+
+---
+
+## Exported components & hooks
+
+| Export | Description |
+| ------ | ----------- |
+| `ChatMain` | All-in-one chat UI (default export) |
+| `Chat` | Provider — initializes auth, API, socket, store |
+| `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 |
+| `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) |
+| `socketService` | Low-level socket service |
+| `setChatClientId`, `setChatAccessToken`, `setChatBaseURL` | Manual API config |
+
+---
+
+## 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.
+
+```tsx
+<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.
+
+**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**
+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.
+
+**Duplicate React / invalid hook call**
+Add `resolve: { dedupe: ["react", "react-dom", "zustand"] }` to your
+`vite.config.ts`.
+
+---
+
+## License
+
+[MIT](https://www.npmjs.com/package/@realtimexsco/live-chat) © RealtimeX