@saiboniuma/chat-ui 0.1.0

package/README.md

@@ -0,0 +1,52 @@
+# @saiboniuma/chat-ui
+
+> 可插拔聊天 UI 组件库 — Shadow DOM 隔离，插件化消息渲染。
+
+基于 `@saiboniuma/realtime-core` 提供 UI 组件。
+
+## 安装
+
+```bash
+npm install @saiboniuma/chat-ui @saiboniuma/realtime-core
+```
+
+## 快速使用
+
+```typescript
+import { ChatUI } from '@saiboniuma/chat-ui';
+
+const chatUI = new ChatUI({
+  container: document.getElementById('chat-container'),
+  // Shadow DOM 隔离，避免宿主页面样式污染
+});
+chatUI.mount();
+```
+
+## 特性
+
+- **Shadow DOM 隔离**：宿主页面样式不影响聊天 UI
+- **插件化消息渲染**：文本、图片、表情等可扩展
+- **轻量**：原生 DOM 实现，无框架依赖
+
+## 构建
+
+```bash
+npm install
+npm run build      # 输出到 dist/
+npm run type-check # 类型检查
+```
+
+## 依赖
+
+- `@saiboniuma/realtime-core`
+- TypeScript ~5.6.3
+- Vite ^6.2.0
+
+## 发布
+
+```bash
+pnpm build
+pnpm publish --access public   # 发布到 npmjs.com
+```
+
+Registry: `https://registry.npmjs.org/`

package/dist/index.d.ts

@@ -0,0 +1,428 @@
+import { Message } from '@saiboniuma/realtime-core';
+import { RealtimeClient } from '@saiboniuma/realtime-core';
+
+/** 聊天 UI 容器主类 */
+export declare class ChatUI {
+    private host;
+    private shadowRoot;
+    private root;
+    private messageListEl;
+    private inputWrapperEl;
+    private pluginManager;
+    private themeManager;
+    private messageListRenderer;
+    private inputArea;
+    private i18n;
+    private core;
+    private currentUserID;
+    private userInfo;
+    private agentInfo;
+    private agentUserID;
+    private groupId;
+    constructor(container: HTMLElement, options?: ChatUIOptions);
+    /** 绑定 RealtimeClient 核心实例 */
+    bindCore(core: RealtimeClient): void;
+    /** 设置当前用户信息（用于消息渲染） */
+    setUserInfo(userID: string, nickname: string, avatar: string): void;
+    /** 设置客服信息（用于消息渲染） */
+    setAgentInfo(agentUserID: string, nickname: string, avatar: string): void;
+    /** 设置群组 ID（广播模式下消息发送到群组） */
+    setGroupId(groupId: string): void;
+    /** 加载并渲染消息列表 */
+    setMessages(messages: Message[]): void;
+    /** 追加单条消息 */
+    appendMessage(message: Message): void;
+    /** 启用/禁用输入 */
+    setInputEnabled(enabled: boolean): void;
+    /** 滚动到底部 */
+    scrollToBottom(): void;
+    /** 注册插件 */
+    registerPlugin(plugin: ChatUIPlugin): void;
+    /** 注销插件 */
+    unregisterPlugin(pluginName: string): void;
+    /** 切换语言 */
+    setLocale(locale: Locale): void;
+    /** 切换主题 */
+    setTheme(theme: 'light' | 'dark'): void;
+    /** 获取 i18n 实例（供插件使用） */
+    getI18n(): I18n;
+    /** 获取 Shadow Root */
+    getShadowRoot(): ShadowRoot;
+    /** 销毁 */
+    destroy(): void;
+    /** 获取发送者信息 */
+    private getSenderInfo;
+    /** 发送消息回调 */
+    private handleSend;
+    /** 显示加载中覆盖层 */
+    private showLoadingOverlay;
+    /** 显示错误覆盖层 */
+    private showErrorOverlay;
+    /** 隐藏覆盖层 */
+    private hideOverlay;
+}
+
+/** 聊天 UI 配置选项 */
+export declare interface ChatUIOptions {
+    /** 注册的插件列表 */
+    plugins?: ChatUIPlugin[];
+    /** 主题（light/dark） */
+    theme?: 'light' | 'dark';
+    /** 语言 */
+    locale?: string;
+    /** 是否全屏模式 */
+    fullPage?: boolean;
+}
+
+/** 聊天 UI 插件接口 */
+export declare interface ChatUIPlugin {
+    /** 插件名称 */
+    name: string;
+    /** 插件版本 */
+    version: string;
+    /** 安装插件（注册渲染器和工具按钮） */
+    install(context: PluginContext): void;
+    /** 卸载插件 */
+    uninstall?(): void;
+}
+
+/** 清空元素子节点 */
+export declare function clearChildren(el: HTMLElement): void;
+
+/** 创建头像元素（含加载失败 fallback） */
+export declare function createAvatarElement(avatarUrl: string, nickname: string, className?: string): HTMLElement;
+
+/** 创建 DOM 元素并设置属性和 class */
+export declare function createElement<K extends keyof HTMLElementTagNameMap>(tag: K, className?: string, attrs?: Record<string, string>): HTMLElementTagNameMap[K];
+
+/** Emoji 分类 */
+export declare const emojiCategories: {
+    nameKey: string;
+    start: number;
+    end: number;
+}[];
+
+/** 完整 Emoji 列表（112 个） */
+export declare const emojiList: string[];
+
+/** 表情选择器 UI */
+export declare class EmojiPicker {
+    private container;
+    private i18n;
+    private activeCategory;
+    private onSelect;
+    private onClose;
+    private visible;
+    private pickerEl;
+    private gridEl;
+    private categoryBtns;
+    constructor(container: HTMLElement, i18n: I18n, onSelect: (emoji: string) => void, onClose: () => void);
+    /** 显示/隐藏表情面板 */
+    toggle(): void;
+    /** 显示面板 */
+    show(): void;
+    /** 隐藏面板 */
+    hide(): void;
+    /** 是否可见 */
+    isVisible(): boolean;
+    /** 刷新文本（语言切换时） */
+    refreshTexts(): void;
+    /** 构建面板 DOM */
+    private build;
+    /** 渲染当前分类的 Emoji 网格 */
+    private renderGrid;
+    /** 更新分类按钮高亮 */
+    private updateCategoryButtons;
+    /** 销毁 */
+    destroy(): void;
+}
+
+/** 表情插件 */
+export declare class EmojiPlugin implements ChatUIPlugin {
+    name: string;
+    version: string;
+    private picker;
+    install(context: PluginContext): void;
+    uninstall(): void;
+}
+
+export declare const enUS: Record<string, string>;
+
+/** 格式化消息时间 */
+export declare function formatMessageTime(timestamp: number, i18n?: I18n): string;
+
+/** 获取头像显示文本（首字母大写） */
+export declare function getAvatarText(nickname: string): string;
+
+/** 获取发送者信息的回调 */
+declare type GetSenderInfoFn = (message: Message) => SenderInfo;
+
+/** 多语言管理器 */
+export declare class I18n {
+    private currentLocale;
+    private messages;
+    private changeListeners;
+    constructor(locale?: Locale);
+    /** 翻译文本 */
+    t(key: string, params?: Record<string, string | number>): string;
+    /** 获取当前语言 */
+    getLocale(): Locale;
+    /** 切换语言（触发所有监听器刷新 UI） */
+    setLocale(locale: Locale): void;
+    /** 注册语言包（可用于插件扩展） */
+    registerLocale(locale: string, messages: Record<string, string>): void;
+    /** 监听语言切换 */
+    onChange(callback: () => void): void;
+    /** 移除语言切换监听 */
+    offChange(callback: () => void): void;
+    /** 销毁 */
+    destroy(): void;
+}
+
+/** 图片消息插件 */
+export declare class ImagePlugin implements ChatUIPlugin {
+    name: string;
+    version: string;
+    install(context: PluginContext): void;
+}
+
+/** 图片预览（全屏遮罩层） */
+export declare class ImagePreview {
+    private static overlay;
+    /** 显示图片预览 */
+    static show(imageUrl: string, shadowRoot: ShadowRoot): void;
+    /** 关闭图片预览 */
+    static close(shadowRoot: ShadowRoot): void;
+}
+
+/** 图片消息渲染器 */
+export declare class ImageRenderer implements MessageRenderer {
+    contentTypes: 102[];
+    /** 同时匹配自定义图片消息 */
+    canRender(message: Message): boolean;
+    render(message: Message, context: RenderContext): HTMLElement;
+}
+
+/** 输入区域 */
+export declare class InputArea {
+    private wrapper;
+    private inputArea;
+    private inputElement;
+    private sendButton;
+    private toolbarContainer;
+    private pluginManager;
+    private i18n;
+    private shadowRoot;
+    private core;
+    private onSend;
+    private isSending;
+    private isDisabled;
+    private recvID;
+    private groupId;
+    private onAppendMessage;
+    constructor(container: HTMLElement, pluginManager: PluginManager, i18n: I18n, shadowRoot: ShadowRoot, onSend: OnSendFn);
+    /** 设置追加消息回调 */
+    setOnAppendMessage(fn: (message: Message) => void): void;
+    /** 绑定 core 实例 */
+    bindCore(core: RealtimeClient): void;
+    /** 设置接收者 ID */
+    setRecvID(recvID: string): void;
+    /** 设置群组 ID（广播模式） */
+    setGroupId(groupId: string): void;
+    /** 设置启用/禁用状态 */
+    setDisabled(disabled: boolean): void;
+    /** 获取输入框元素 */
+    getInputElement(): HTMLInputElement;
+    /** 刷新工具栏 */
+    refreshToolbar(): void;
+    /** 刷新 UI 文本 */
+    refreshTexts(): void;
+    /** 构建输入区域 DOM */
+    private build;
+    /** 构建工具栏按钮 */
+    private buildToolbar;
+    /** 键盘事件处理 */
+    private handleKeydown;
+    /** 发送消息 */
+    private handleSend;
+    /** 更新工具栏按钮禁用状态 */
+    private updateToolbarButtons;
+    /** 更新发送按钮状态 */
+    private updateSendButton;
+}
+
+/** 输入区工具按钮接口 */
+export declare interface InputTool {
+    /** 工具名称 */
+    name: string;
+    /** 图标（emoji 或 HTML） */
+    icon: string;
+    /** 提示文字 */
+    tooltip: string;
+    /** 排序优先级（越小越靠前） */
+    order?: number;
+    /** 点击回调 */
+    onActivate(context: InputToolContext): void;
+}
+
+/** 输入工具上下文 */
+export declare interface InputToolContext {
+    /** 输入框元素 */
+    inputElement: HTMLInputElement;
+    /** 插入文本到输入框 */
+    insertText(text: string): void;
+    /** 获取当前输入文本 */
+    getInputText(): string;
+    /** 设置输入文本 */
+    setInputText(text: string): void;
+    /** 获取接收者 ID（群聊模式下返回 groupId） */
+    getRecvID(): string;
+    /** 是否群聊模式 */
+    isGroup(): boolean;
+    /** core 实例 */
+    core: RealtimeClient | null;
+    /** 追加消息到聊天列表 */
+    appendMessage(message: Message): void;
+    /** Shadow Root */
+    shadowRoot: ShadowRoot;
+    /** i18n 实例 */
+    i18n: I18n;
+}
+
+/** 检查容器是否接近底部（用于判断是否自动滚动） */
+export declare function isNearBottom(container: HTMLElement, threshold?: number): boolean;
+
+export declare type Locale = 'zh-CN' | 'en-US' | string;
+
+/** 消息列表渲染器 */
+export declare class MessageListRenderer {
+    private container;
+    private pluginManager;
+    private i18n;
+    private shadowRoot;
+    private currentUserID;
+    private getSenderInfo;
+    private messages;
+    private renderedMsgIds;
+    constructor(container: HTMLElement, pluginManager: PluginManager, i18n: I18n, shadowRoot: ShadowRoot, getSenderInfo: GetSenderInfoFn);
+    /** 设置当前用户 ID */
+    setCurrentUserID(userID: string): void;
+    /** 更新消息列表 */
+    updateMessages(messages: Message[]): void;
+    /** 追加单条新消息 */
+    appendMessage(message: Message): void;
+    /** 滚动到底部 */
+    scrollToBottom(): void;
+    /** 完整渲染消息列表 */
+    private render;
+    /** 渲染空状态 */
+    private renderEmptyState;
+    /** 渲染单条消息 */
+    private renderMessageItem;
+    /** 刷新所有消息的 UI 文本（语言切换时调用） */
+    refreshTexts(): void;
+    /** 清空 */
+    clear(): void;
+}
+
+/** 消息渲染器接口 */
+export declare interface MessageRenderer {
+    /** 支持的 contentType 列表 */
+    contentTypes: number[];
+    /** 渲染消息内容，返回 DOM 元素 */
+    render(message: Message, context: RenderContext): HTMLElement;
+    /** 自定义消息匹配器（用于 CustomMessage 子类型判断） */
+    canRender?(message: Message): boolean;
+}
+
+/** 发送回调 */
+declare type OnSendFn = (text: string) => Promise<void>;
+
+/** 插件安装上下文 */
+export declare interface PluginContext {
+    /** 注册消息渲染器 */
+    registerRenderer(renderer: MessageRenderer): void;
+    /** 注册输入工具按钮 */
+    registerInputTool(tool: InputTool): void;
+    /** i18n 实例 */
+    i18n: I18n;
+    /** 注册插件语言包 */
+    registerLocale(locale: string, messages: Record<string, string>): void;
+}
+
+/** 插件管理器 */
+export declare class PluginManager {
+    private renderers;
+    private inputTools;
+    private plugins;
+    private i18n;
+    constructor(i18n: I18n);
+    /** 注册插件 */
+    register(plugin: ChatUIPlugin): void;
+    /** 注销插件 */
+    unregister(pluginName: string): void;
+    /** 根据消息查找合适的渲染器 */
+    getRenderer(message: Message): MessageRenderer | null;
+    /** 获取所有输入工具按钮 */
+    getInputTools(): InputTool[];
+    /** 销毁所有插件 */
+    destroy(): void;
+}
+
+/** 渲染上下文 */
+export declare interface RenderContext {
+    /** 是否是自己发的消息 */
+    isSelf: boolean;
+    /** 当前用户 ID */
+    currentUserID: string;
+    /** i18n 实例 */
+    i18n: I18n;
+    /** Shadow Root（用于插入弹窗等） */
+    shadowRoot: ShadowRoot;
+}
+
+/** 将容器滚动到底部 */
+export declare function scrollToBottom(container: HTMLElement): void;
+
+/** 用户信息（用于渲染消息头像和昵称） */
+export declare interface SenderInfo {
+    nickname: string;
+    avatar: string;
+}
+
+/** 安全设置文本内容 */
+export declare function setTextContent(el: HTMLElement, text: string): void;
+
+/** 文本消息插件 */
+export declare class TextPlugin implements ChatUIPlugin {
+    name: string;
+    version: string;
+    install(context: PluginContext): void;
+}
+
+/** 文本消息渲染器 */
+export declare class TextRenderer implements MessageRenderer {
+    contentTypes: 101[];
+    render(message: Message, context: RenderContext): HTMLElement;
+}
+
+/** 主题管理器 */
+export declare class ThemeManager {
+    private currentTheme;
+    private container;
+    /** 绑定容器元素 */
+    bind(container: HTMLElement): void;
+    /** 设置主题 */
+    setTheme(theme: 'light' | 'dark'): void;
+    /** 获取当前主题 */
+    getTheme(): 'light' | 'dark';
+    /** 应用主题到容器 */
+    private applyTheme;
+}
+
+/** 切换 CSS class */
+export declare function toggleClass(el: HTMLElement, className: string, force?: boolean): void;
+
+export declare const zhCN: Record<string, string>;
+
+export { }