@composy/chat-core 0.0.1

package/README.md

@@ -0,0 +1,123 @@
+# @composy/chat-core
+
+Framework-agnostic chat runtime for LDesign. It renders message lists, bubbles, input, mentions, toolbar actions, voice input hooks, upload/drop callbacks, message status, streaming text, and light/dark/auto themes without depending on a UI framework.
+
+## Features
+
+- Text, image, file, system, custom, revoked, and streaming messages.
+- Mention engine with keyboard navigation, name/id filtering, and mention parsing.
+- Toolbar callbacks for image upload, file upload, paste, drop, and browser speech recognition.
+- Input helpers: `enterToSend`, `clearInputOnSend`, `maxInputLength`, `setInputContent`, `clearInput`, and `onInputChange`.
+- Runtime APIs for message CRUD, streaming append/finish, scroll control, loading-more state, and message lookup.
+- All generated classes use the `ldesign-` prefix. The default class prefix is `ldesign-chat`.
+- Component CSS variables use `--ldesign-chat-*` and map to shared `packages/color` `--color-*` variables plus `packages/size` `--size-*` variables.
+
+## Install
+
+```bash
+pnpm add @composy/chat-core
+```
+
+Load the global LDesign color and size variable styles before mounting chat UI:
+
+```ts
+import '@composy/color-core/styles.css';
+import '@composy/size-core/styles.css';
+```
+
+## Usage
+
+```ts
+import { createChat } from '@composy/chat-core';
+
+const chat = createChat({
+  container: '#chat',
+  currentUserId: 'u1',
+  theme: 'auto',
+  enableMention: true,
+  mentionMembers: [
+    { id: 'u2', name: 'Alice' },
+  ],
+  onSend(content, mentions) {
+    console.log(content, mentions);
+  },
+});
+
+chat.addMessage({
+  id: 'm1',
+  type: 'text',
+  direction: 'incoming',
+  sender: { id: 'u2', nickname: 'Alice' },
+  content: 'Hello',
+  timestamp: Date.now(),
+});
+```
+
+## Public API
+
+```ts
+chat.addMessage(message);
+chat.prependMessages(messages);
+chat.updateMessage(id, updates);
+chat.removeMessage(id);
+chat.setMessages(messages);
+chat.clearMessages();
+chat.getMessages();
+chat.getMessage(id);
+
+chat.appendMessageContent(id, chunk);
+chat.finishStreaming(id);
+
+chat.scrollToBottom(true);
+chat.isAtBottom();
+chat.setLoadingMore(false);
+
+chat.setTheme('dark');
+chat.setMentionMembers(members);
+
+chat.focusInput();
+chat.setInputContent('hello');
+chat.getInputContent();
+chat.clearInput();
+
+chat.on('message-retry', (message) => {});
+chat.destroy();
+```
+
+## Styling Contract
+
+The renderer normalizes `classPrefix`. If no prefix is passed, generated classes start with `ldesign-chat-*`. If a custom prefix does not start with `ldesign-`, it is normalized to `ldesign-${prefix}`.
+
+Key classes:
+
+- `ldesign-chat-container`
+- `ldesign-chat-message-list`
+- `ldesign-chat-message-row`
+- `ldesign-chat-bubble`
+- `ldesign-chat-input-area`
+- `ldesign-chat-toolbar`
+- `ldesign-chat-mention-panel`
+
+The injected stylesheet defines component variables such as:
+
+- `--ldesign-chat-bg-primary`
+- `--ldesign-chat-text-primary`
+- `--ldesign-chat-border-primary`
+- `--ldesign-chat-avatar-size`
+- `--ldesign-chat-radius-md`
+- `--ldesign-chat-transition-fast`
+
+Defaults are references to `--color-*` and `--size-*` tokens, so consumers can theme chat by loading or overriding the shared token styles.
+
+## Build
+
+```bash
+pnpm --dir libraries/chat/packages/core type-check
+pnpm --dir libraries/chat/packages/core build
+```
+
+The build generates `dist`, `es`, `esm`, and `lib`. `postbuild` verifies required outputs and creates `dist/index.min.js`.
+
+## License
+
+MIT