@qlover/create-app 0.7.15 → 0.9.0

package/dist/templates/react-app/docs/en/components/chat-message-component.md

@@ -0,0 +1,314 @@
+# ChatMessage Chat Component System
+
+## 📋 Overview
+
+ChatMessage is a complete chat component system that supports real-time conversations, streaming output, error handling, and more. Suitable for AI dialogue, customer service chat, and other scenarios.
+
+## ✨ Core Features
+
+- ✅ **Streaming Output**: Supports character-by-character AI reply display (like ChatGPT)
+- ✅ **Stop Control**: Can stop message generation at any time
+- ✅ **Retry Mechanism**: Failed messages can be retried with one click
+- ✅ **Draft Management**: Automatically saves draft messages being input
+- ✅ **Loading States**: Clear message sending and receiving states
+- ✅ **Error Handling**: Comprehensive error prompts and handling
+- ✅ **Shortcuts**: Ctrl+Enter for quick send
+- ✅ **Internationalization**: Full Chinese/English support
+- ✅ **Responsive Design**: Adapts to different screen sizes
+
+## 📁 File Structure
+
+```
+src/uikit/components/chatMessage/
+├── ChatRoot.tsx              # Root component (assembles all parts)
+├── MessagesList.tsx          # Message list component
+├── MessageItem.tsx           # Single message item component
+├── FocusBar.tsx             # Input bar component
+├── ChatMessageBridge.ts     # Bridge layer (connects UI and logic)
+└── MessageApi.ts            # API layer (mock/real backend)
+
+config/
+├── Identifier/components/component.chatMessage.ts  # i18n identifiers
+├── i18n/chatMessageI18n.ts                        # Component i18n config
+├── Identifier/pages/page.chat.ts                  # Page i18n identifiers
+└── i18n/chatI18n.ts                               # Page i18n config
+
+src/pages/base/
+└── ChatMessagePage.tsx       # Chat page
+```
+
+## 🎯 Core Concepts
+
+### 1. ChatMessageBridge (Bridge Layer)
+
+Bridge connecting UI and data layer, handles:
+- Message sending logic
+- Draft management
+- State control
+- Stop mechanism
+
+### 2. MessageApi (Gateway Layer)
+
+Simulates backend API, supports three modes:
+
+#### Streaming Mode (stream: true)
+```typescript
+{
+  stream: true  // Character-by-character output, stoppable
+}
+```
+
+#### Interruptible Normal Mode
+```typescript
+{
+  stream: false  // One-time return, stoppable
+}
+```
+
+#### Fast Normal Mode
+```typescript
+// No options passed, one-time return, non-stoppable
+```
+
+### 3. ChatMessageStore (State Management)
+
+Manages all message states:
+- `messages` - History message list
+- `draftMessages` - Draft message list
+- `streaming` - Whether streaming output is in progress
+- `disabledSend` - Whether sending is disabled
+
+## 🚀 Usage
+
+### Basic Usage
+
+```typescript
+import { ChatRoot } from '@/uikit/components/chatMessage/ChatRoot';
+
+export default function ChatMessagePage() {
+  return (
+    <div className="h-screen">
+      <ChatRoot />
+    </div>
+  );
+}
+```
+
+### Access Paths
+
+- `/en/chat` - English
+- `/zh/chat` - Chinese
+
+## 🎨 Interface Design
+
+### Message Styles
+
+**User Messages**:
+- Blue background
+- Right-aligned
+- Max width 80%
+- Shows duration
+- Has retry button
+
+**AI Messages**:
+- Light background + border
+- Left-aligned
+- Max width 85%
+- Supports streaming display
+- Shows loading state
+
+### Input Bar
+
+- Auto-adjusts height (2-6 rows)
+- Ctrl+Enter to send
+- Disabled state control
+- Send/Stop button toggle
+
+## 📝 Key APIs
+
+### ChatMessageBridge Methods
+
+```typescript
+interface ChatMessageBridgeInterface<T> {
+  // Send message
+  send(message?: ChatMessage<T>): Promise<ChatMessage<T>>;
+  
+  // Stop sending
+  stop(messageId?: string): boolean;
+  
+  // Stop all
+  stopAll(): void;
+  
+  // Update content
+  onChangeContent(content: T): void;
+  
+  // Get message store
+  getMessageStore(): ChatMessageStore<T>;
+  
+  // Get first draft message
+  getFirstDraftMessage(): ChatMessage<T> | null;
+  
+  // Get sending message
+  getSendingMessage(): ChatMessage<T> | null;
+  
+  // Is send disabled
+  getDisabledSend(): boolean;
+}
+```
+
+### MessageApi Modes
+
+```typescript
+class MessageApi {
+  async sendMessage<M>(
+    message: M,
+    options?: GatewayOptions<M>
+  ): Promise<M>;
+}
+
+interface GatewayOptions<M> {
+  stream?: boolean;           // Whether streaming
+  signal?: AbortSignal;       // Stop signal
+  onConnected?: () => void;   // Connection success
+  onChunk?: (msg: M) => void; // Streaming chunk callback
+  onProgress?: (p: number) => void; // Progress callback
+  onComplete?: (msg: M) => void;    // Completion callback
+  onAborted?: (msg: M) => void;     // Stop callback
+  onError?: (err: any) => void;     // Error callback
+}
+```
+
+## 🔧 Custom Configuration
+
+### 1. Switch Send Mode
+
+```typescript
+// Modify ChatRoot.tsx
+const [bridge] = useState(() => {
+  return new ChatMessageBridge<string>(messagesStore, {
+    gateway: messageApi,
+    logger: logger,
+    senderName: 'ChatSender',
+    gatewayOptions: { 
+      stream: true  // Change to false for normal mode
+    }
+  }).use(new ChatSenderStrategy(SendFailureStrategy.KEEP_FAILED, logger));
+});
+```
+
+### 2. Custom Message Component
+
+```typescript
+<MessagesList 
+  bridge={bridge} 
+  getMessageComponent={(props) => CustomMessageItem}
+/>
+```
+
+### 3. Connect Real API
+
+Modify `MessageApi.ts`:
+
+```typescript
+async sendMessage<M>(message: M, options?: GatewayOptions<M>): Promise<M> {
+  // Replace with real API call
+  const response = await fetch('/api/chat', {
+    method: 'POST',
+    body: JSON.stringify(message),
+    signal: options?.signal
+  });
+  
+  // Handle streaming response
+  if (options?.stream) {
+    const reader = response.body?.getReader();
+    // ... process streaming data
+  }
+  
+  return response.json();
+}
+```
+
+## 💡 Usage Tips
+
+### Test Features
+
+**Normal Messages**:
+```
+Hello
+你好
+Test message
+```
+
+**Trigger Errors**:
+```
+error
+Failed
+test error
+```
+
+**See Streaming Effect**:
+- Send any message
+- Watch character-by-character output
+- Click stop button to test interruption
+
+### Shortcuts
+
+- `Ctrl + Enter` - Send message
+- Auto-save draft while typing
+
+## 🎯 Use Cases
+
+1. **AI Dialogue Apps**: ChatGPT-like dialogue interface
+2. **Customer Service**: Real-time customer service chat
+3. **Q&A Systems**: Q&A interaction
+4. **Code Assistant**: Code generation and explanation
+5. **Teaching Assistant**: Online learning tutoring
+
+## 🔄 Message Flow
+
+```
+User Input → Draft Message
+    ↓
+Click Send/Ctrl+Enter
+    ↓
+Bridge.send()
+    ↓
+MessageSender → MessageApi
+    ↓
+[Streaming Mode]
+  onConnected → onChunk(word-by-word) → onComplete
+  
+[Normal Mode]
+  onConnected → onComplete
+  
+[Error]
+  onError
+  
+[Stop]
+  onAborted
+    ↓
+Update ChatMessageStore
+    ↓
+UI Auto-updates
+```
+
+## 📊 State Management
+
+### Message States
+
+- `DRAFT` - Draft
+- `SENDING` - Sending
+- `SENT` - Sent
+- `FAILED` - Failed
+- `STOPPED` - Stopped
+
+### Message Roles
+
+- `USER` - User message
+- `ASSISTANT` - AI/Assistant message
+- `SYSTEM` - System message
+
+## 🎉 Summary
+
+ChatMessage is a fully-featured, elegantly designed chat component system, ready to use out of the box, supporting streaming output, error handling, state management, and other core features. Can be used directly in production or extended and customized as needed.
+

package/dist/templates/react-app/docs/en/components/chat-message-refactor.md

@@ -0,0 +1,270 @@
+# ChatMessage Refactoring Guide
+
+## Refactoring Overview
+
+Refactored ChatMessage from a standalone page to a reusable component, integrated into MessagePage. Passed the internationalization object `tt` through props to ensure high component reusability.
+
+## Changes
+
+### 1. ChatRoot Component Refactoring
+
+**File:** `src/uikit/components/chatMessage/ChatRoot.tsx`
+
+**Changes:**
+- Removed internal creation of `ChatMessageStore`, `MessageApi`, and `ChatMessageBridge`
+- Changed to accept `bridge` and `tt` (internationalization object) as props
+- Added `ChatRootProps` interface definition
+- Removed internal `useI18nInterface` call
+
+**Before:**
+```typescript
+export function ChatRoot() {
+  const messagesStore = useFactory(ChatMessageStore<string>);
+  const messageApi = useFactory(MessageApi, messagesStore);
+  const [bridge] = useState(() => {
+    return new ChatMessageBridge<string>(messagesStore, {
+      gateway: messageApi,
+      logger: logger,
+      senderName: 'ChatSender',
+      gatewayOptions: { stream: true }
+    }).use(new ChatSenderStrategy(SendFailureStrategy.KEEP_FAILED, logger));
+  });
+  
+  return (
+    <div data-testid="ChatRoot">
+      <MessagesList bridge={bridge} />
+      <FocusBar bridge={bridge} />
+    </div>
+  );
+}
+```
+
+**After:**
+```typescript
+export interface ChatRootProps {
+  bridge: ChatMessageBridge<string>;
+  tt: ChatMessageI18nInterface;
+}
+
+export function ChatRoot({ bridge, tt }: ChatRootProps) {
+  return (
+    <div data-testid="ChatRoot">
+      <MessagesList bridge={bridge} tt={tt} />
+      <FocusBar bridge={bridge} tt={tt} />
+    </div>
+  );
+}
+```
+
+### 2. Integrating ChatRoot into MessagePage
+
+**File:** `src/pages/base/MessagePage.tsx`
+
+**Changes:**
+- Use `useI18nInterface` to get the internationalization object `tt` in MessagePage
+- Create `ChatMessageStore`, `MessageApi`, and `ChatMessageBridge` in MessagePage
+- Pass both `bridge` and `tt` to `ChatRoot` component via props
+- Also integrated the `MessageBaseList` component
+
+**Implementation:**
+```typescript
+import { useFactory } from '@brain-toolkit/react-kit';
+import { chatMessageI18n } from '@config/i18n/chatMessageI18n';
+import {
+  ChatMessageStore,
+  ChatSenderStrategy,
+  SendFailureStrategy
+} from '@qlover/corekit-bridge';
+import { useState } from 'react';
+import { logger } from '@/core/globals';
+import { ChatMessageBridge } from '@/uikit/components/chatMessage/ChatMessageBridge';
+import { ChatRoot } from '@/uikit/components/chatMessage/ChatRoot';
+import { MessageApi } from '@/uikit/components/chatMessage/MessageApi';
+import { MessageBaseList } from '@/uikit/components/MessageBaseList';
+import { useI18nInterface } from '@/uikit/hooks/useI18nInterface';
+
+export default function MessagePage() {
+  const tt = useI18nInterface(chatMessageI18n);
+  const messagesStore = useFactory(ChatMessageStore<string>);
+  const messageApi = useFactory(MessageApi, messagesStore);
+
+  const [bridge] = useState(() => {
+    return new ChatMessageBridge<string>(messagesStore, {
+      gateway: messageApi,
+      logger: logger,
+      senderName: 'ChatSender',
+      gatewayOptions: { stream: true }
+    }).use(new ChatSenderStrategy(SendFailureStrategy.KEEP_FAILED, logger));
+  });
+
+  return (
+    <div
+      data-testid="MessagePage"
+      className="min-h-screen bg-primary py-8 px-4 sm:px-6 lg:px-8"
+    >
+      <MessageBaseList />
+      <ChatRoot bridge={bridge} tt={tt} />
+    </div>
+  );
+}
+```
+
+### 3. Child Component Refactoring (MessagesList, FocusBar, MessageItem)
+
+**Changes:**
+- Removed internal `useI18nInterface` calls from all child components
+- Changed to accept `tt` parameter via props
+- Updated Props interface definitions for each component
+
+**Example - MessagesList:**
+```typescript
+// Before
+export function MessagesList({ bridge, ... }: MessagesListProps) {
+  const tt = useI18nInterface(chatMessageI18n);
+  // ...
+}
+
+// After
+export interface MessagesListProps {
+  bridge: ChatMessageBridgeInterface<T>;
+  tt: ChatMessageI18nInterface;
+  // ...
+}
+
+export function MessagesList({ bridge, tt, ... }: MessagesListProps) {
+  // Use the passed tt directly
+}
+```
+
+### 4. Removed Standalone ChatMessagePage
+
+**Deleted Files:**
+- `src/pages/base/ChatMessagePage.tsx`
+- `config/Identifier/pages/page.chat.ts`
+- `config/i18n/chatI18n.ts`
+
+**Updated Files:**
+- `config/app.router.ts` - Removed `/chat` route configuration
+- `config/Identifier/pages/index.ts` - Removed `page.chat` export
+
+## Advantages of Refactoring
+
+### 1. Improved Component Reusability
+- `ChatRoot` is now a pure presentational component that can be used anywhere
+- Creation and configuration of `bridge` and `tt` are controlled by parent component for better flexibility
+- Parent component can customize internationalization content, supporting different language environments
+
+### 2. Simplified Routing Structure
+- Reduced unnecessary routing layers
+- Directly integrated chat functionality into message page, aligning with business logic
+
+### 3. Better Separation of Concerns
+- `ChatRoot` and its child components focus only on UI presentation
+- Business logic (store, api, bridge) is managed at the page level
+- Internationalization configuration is centrally managed at the page level
+- Easier to test and maintain
+
+### 4. Reduced Boilerplate
+- No need to create a separate page for chat functionality
+- No need to create separate i18n configuration for the page
+- Child components don't need to repeatedly call `useI18nInterface`
+
+### 5. Performance Improvement
+- Reduced number of hook calls (multiple child components share the same `tt` object)
+- Avoided redundant internationalization configuration parsing
+
+## Usage Example
+
+### Basic Usage
+
+If you need to use `ChatRoot` elsewhere:
+
+```typescript
+import { useFactory } from '@brain-toolkit/react-kit';
+import { chatMessageI18n } from '@config/i18n/chatMessageI18n';
+import {
+  ChatMessageStore,
+  ChatSenderStrategy,
+  SendFailureStrategy
+} from '@qlover/corekit-bridge';
+import { useState } from 'react';
+import { logger } from '@/core/globals';
+import { useI18nInterface } from '@/uikit/hooks/useI18nInterface';
+import { ChatMessageBridge } from '@/uikit/components/chatMessage/ChatMessageBridge';
+import { ChatRoot } from '@/uikit/components/chatMessage/ChatRoot';
+import { MessageApi } from '@/uikit/components/chatMessage/MessageApi';
+
+function MyCustomChatPage() {
+  // Get internationalization object
+  const tt = useI18nInterface(chatMessageI18n);
+  
+  const messagesStore = useFactory(ChatMessageStore<string>);
+  const messageApi = useFactory(MessageApi, messagesStore);
+
+  const [bridge] = useState(() => {
+    return new ChatMessageBridge<string>(messagesStore, {
+      gateway: messageApi,
+      logger: logger,
+      senderName: 'MyCustomSender',
+      gatewayOptions: { 
+        stream: true,
+        // Can customize other options
+      }
+    }).use(new ChatSenderStrategy(SendFailureStrategy.KEEP_FAILED, logger));
+  });
+
+  return (
+    <div>
+      <h1>My Custom Chat</h1>
+      <ChatRoot bridge={bridge} tt={tt} />
+    </div>
+  );
+}
+```
+
+### Custom Internationalization
+
+If you need to use custom internationalization configuration:
+
+```typescript
+import { useState } from 'react';
+import type { ChatMessageI18nInterface } from '@config/i18n/chatMessageI18n';
+
+// Custom internationalization object
+const customI18n: ChatMessageI18nInterface = {
+  title: 'custom.chat.title',
+  empty: 'custom.chat.empty',
+  start: 'custom.chat.start',
+  // ... other configurations
+};
+
+function MyCustomChatPage() {
+  const tt = useI18nInterface(customI18n);
+  // ... other logic
+  
+  return <ChatRoot bridge={bridge} tt={tt} />;
+}
+```
+
+## Notes
+
+1. `ChatRoot` component requires two required parameters via props:
+   - `bridge`: `ChatMessageBridge` instance
+   - `tt`: `ChatMessageI18nInterface` internationalization object
+
+2. Creation and configuration of `bridge` should be done in the parent component
+
+3. Ensure `bridge` is created using `useState` to avoid re-initialization
+
+4. Internationalization object `tt` should be obtained using `useI18nInterface` in the parent component, then passed to `ChatRoot`
+
+5. All child components (`MessagesList`, `FocusBar`, `MessageItem`) used by `ChatRoot` receive both `bridge` and `tt` via props
+
+6. All child components no longer call `useI18nInterface` themselves, but use the `tt` passed from the parent component
+
+## Related Documentation
+
+- [ChatMessage Component Documentation](./chat-message-component.md)
+- [MessagePage Simplification Guide](./message-page-简化说明.md)
+- [Development Guide](./development-guide.md)
+