@namphuongtechnologi/np-chat-ui

Đây là package dùng để nhúng chat vào app React khác.

Có UI đầy đủ (sidebar phòng, cửa sổ tin, panel phải) — copy vài bước là chạy.

| Package | Việc của nó | |---------|-------------| | np-chat-ui (package này) | UI + ChatApp | | np-chat-react | Provider + hooks (cài kèm) | | np-chat-core | Dependency nội bộ — không import trực tiếp khi nhúng |

Cài đặt

pnpm add @namphuongtechnologi/np-chat-ui @namphuongtechnologi/np-chat-react @namphuongtechnologi/np-chat-core
pnpm add axios @tanstack/react-query

(npm cũng được: npm i ...)

• Cài cùng version cho cả 3 package @namphuongtechnologi/np-chat-*
• Peer: react >= 18, react-dom >= 18

Nhúng vào app host (copy-paste)

1. Import CSS (một lần, ở entry)

import '@namphuongtechnologi/np-chat-ui/styles.css';

2. Trang chat

Library không tạo axios. Truyền axios instance đã có auth của app:

import { ChatQueryProvider, ChatProvider } from '@namphuongtechnologi/np-chat-react';
import { ChatApp } from '@namphuongtechnologi/np-chat-ui';
import '@namphuongtechnologi/np-chat-ui/styles.css';

// apiClient = axios của app host (baseURL + interceptor Authorization sẵn)
export function ChatPage() {
  return (
    <ChatQueryProvider>
      <ChatProvider
        config={{
          axios: apiClient,
          currentUser: {
            id: user.id,
            name: user.displayName,
            acsId: user.acsCommunicationId,
            avatarUrl: user.avatarUrl,
          },
          locale: 'vi',
          onError: (err) => console.error('[NP-Chat]', err),
        }}
      >
        {/* Cha phải có chiều cao rõ — ChatApp đã gắn class np-chat-root */}
        <div style={{ height: 'calc(100vh - 64px)' }}>
          <ChatApp layout="full" />
        </div>
      </ChatProvider>
    </ChatQueryProvider>
  );
}

Thứ tự bắt buộc:

ChatQueryProvider → ChatProvider → ChatApp

3. Route (host quyết path)

<Route path="/chats" element={<ChatPage />} />

Library tự sync ?roomId= — không cần bridge useSearchParams.

Layout

<ChatApp layout="full" />                           {/* sidebar + chat + panel */}
<ChatApp layout="embedded" showRightPanel={false} /> {/* chỉ cửa sổ chat */}

ChatConfig

| Field | Bắt buộc | Mô tả | |-------|----------|--------| | axios | Có | Axios instance host (auth do host) | | currentUser.id | Có | User id backend | | currentUser.name | Có | Tên hiển thị | | currentUser.acsId | Khuyến nghị | Cần cho realtime ACS | | locale | Không | 'vi' | 'en' | | onError | Không | Callback lỗi | | onRoomChange | Không | Callback đổi phòng |

Host vs library

| Host làm | Library lo | |----------|------------| | Axios + auth interceptor | REST chat + ACS | | currentUser sau login | Sync ?roomId= | | Route /chats + menu | UI (ChatApp) | | Import styles.css | CSS prefix npc-, scope .np-chat-root |

Checklist

• [ ] 3 package cùng version + import styles.css
• [ ] Axios có baseURL + Authorization
• [ ] currentUser.id / name đúng; có acsId nếu cần realtime
• [ ] Wrapper có chiều cao (100% / calc(100vh - header))
• [ ] Mở phòng → gửi tin → realtime OK

Lỗi thường gặp

| Triệu chứng | Kiểm tra | |-------------|----------| | 401 | Interceptor token trên axios host | | Sidebar trống | Token / chưa login | | Không realtime | Thiếu acsId hoặc join room không trả ACS token | | CSS vỡ / trắng | Thiếu styles.css hoặc thiếu chiều cao wrapper | | Peer TypeScript | Cài react, axios, @tanstack/react-query |

Tự build UI (không dùng ChatApp)

Dùng @namphuongtechnologi/np-chat-react (hooks). Chỉ import @namphuongtechnologi/np-chat-core khi cần domain / metadata thuần TS.