@openim/im-composer 1.0.0 → 1.0.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 im-composer
+Copyright (c) 2024 OpenIM
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,8 +1,27 @@
-# @openim/im-composer
+# IM Composer
 
-A React IM composer component with dual mode (plain/rich) supporting @mentions, emoji, attachments, and markdown.
+A dual-mode input editor component for IM (Instant Messaging) applications, built with Tiptap and React.
 
-Built with [Lexical](https://lexical.dev/) editor framework.
+## Features
+
+### Plain Text Mode
+- **@Mention**: Type `@` to trigger member suggestions with async search
+- **File Attachments**: Paste or drag files to attach (with preview)
+- **Quote Messages**: Insert quoted replies that appear above the editor
+- **Atomic Mention Tokens**: Mention tokens cannot be edited - backspace deletes the whole token
+
+### Rich Text Mode
+- **Markdown Shortcuts**: Type `**bold**`, `*italic*`, etc.
+- **Toolbar**: Bold, italic, headings, lists, blockquote, code block, links
+- **Image Upload**: Paste or select images to upload via external handler
+- **Markdown Import/Export**: Programmatically set or get Markdown content
+
+### Common Features
+- **Mode Isolation**: Plain and rich modes maintain completely separate editor states
+- **Configurable Keymap**: Enter/Ctrl+Enter/Cmd+Enter for send
+- **IME Support**: Proper handling of CJK input composition
+- **Draft Support**: Save and restore editor state
+- **i18n Ready**: Customizable locale strings
 
 ## Installation
 
@@ -10,299 +29,291 @@ Built with [Lexical](https://lexical.dev/) editor framework.
 npm install @openim/im-composer
 # or
 pnpm add @openim/im-composer
+# or
+yarn add @openim/im-composer
 ```
 
-**Note:** Requires React 18+ or React 19+ as peer dependencies.
-
 ## Quick Start
 
 ```tsx
-import { IMComposer, IMComposerRef } from '@openim/im-composer';
-import '@openim/im-composer/styles.css';
+import { useRef } from 'react';
+import { IMComposer, type IMComposerRef, type PlainMessagePayload } from '@openim/im-composer';
 
-function Chat() {
+function ChatInput() {
   const composerRef = useRef<IMComposerRef>(null);
 
+  const handleSend = (payload: PlainMessagePayload) => {
+    console.log('Message:', payload.plainText);
+    console.log('Mentions:', payload.mentions);
+    console.log('Attachments:', payload.attachments);
+  };
+
   return (
     <IMComposer
       ref={composerRef}
       mode="plain"
-      placeholder="Type a message..."
-      onSend={(payload) => {
-        console.log('Sent:', payload);
-      }}
+      onSend={handleSend}
+      enableMention={true}
       mentionProvider={async (query) => {
-        // Return list of users matching query
-        return [{ userId: '1', display: 'John', avatarUrl: '...' }];
+        // Return filtered members based on query
+        const response = await fetch(`/api/members?q=${query}`);
+        return response.json();
       }}
+      enableAttachments={true}
+      placeholder="Type a message..."
     />
   );
 }
 ```
 
-## Features
-
-### Plain Text Mode
-- **@Mentions** - Type `@` to search and mention users
-- **Attachments** - Paste or drag files with preview
-- **Quote Messages** - Reply to messages with quote blocks
-- **Emoji** - Full Unicode emoji support
-- **Draft Support** - Save and restore editor state
-
-### Rich Text Mode (Markdown)
-- **Formatting Toolbar** - Bold, italic, strikethrough, code
-- **Headings** - H1, H2, H3
-- **Lists** - Bullet and ordered lists
-- **Code Blocks** - Inline code and code blocks
-- **Block Quotes** - Quote formatting
-- **Links** - Insert and edit links with popup
-- **Images** - Upload and embed images
-
 ## Props
 
-### Basic Props
+### Mode Control
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `mode` | `'plain' \| 'rich'` | - | Controlled mode |
-| `defaultMode` | `'plain' \| 'rich'` | `'plain'` | Default mode (uncontrolled) |
-| `onSend` | `(payload) => void` | - | Callback when user sends message |
-| `placeholder` | `string \| { plain?: string; rich?: string }` | - | Placeholder text |
-| `disabled` | `boolean` | `false` | Disable the editor |
-| `className` | `string` | - | Custom class name |
-| `onChange` | `() => void` | - | Callback on content change |
+| `defaultMode` | `'plain' \| 'rich'` | `'plain'` | Initial mode (uncontrolled) |
 
-### Mention Options (Plain Mode)
+### Plain Mode - Mentions
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `enableMention` | `boolean` | `true` | Enable @mention feature |
-| `mentionProvider` | `(query: string) => Promise<Member[]>` | - | Async function to search members |
+| `mentionProvider` | `(query: string) => Promise<Member[]>` | - | Async search handler |
 | `maxMentions` | `number` | - | Maximum mentions allowed |
-| `renderMentionItem` | `(props) => ReactNode` | - | Custom render for mention dropdown items |
+| `renderMentionItem` | `(props) => ReactNode` | - | Custom mention list item |
 
-### Attachment Options (Plain Mode)
+### Plain Mode - Attachments
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `enableAttachments` | `boolean` | `true` | Enable file attachments |
-| `showAttachmentPreview` | `boolean` | `true` | Show built-in attachment preview bar |
-| `attachmentPreviewPlacement` | `'top' \| 'bottom'` | `'bottom'` | Position of preview bar |
-| `maxAttachments` | `number` | `10` | Maximum attachments allowed |
-| `maxFileSize` | `number` | - | Maximum file size in bytes |
-| `allowedMimeTypes` | `string[]` | - | Allowed MIME types |
-| `onAttachmentLimitExceeded` | `(reason, file) => void` | - | Callback when limit exceeded |
-| `onFilesChange` | `(attachments) => void` | - | Callback when attachments change |
+| `maxAttachments` | `number` | `10` | Maximum attachments |
+| `maxFileSize` | `number` | - | Max file size in bytes |
+| `allowedMimeTypes` | `string[]` | - | Allowed MIME types (supports wildcards) |
+| `attachmentPreviewPlacement` | `'top' \| 'bottom'` | `'bottom'` | Preview bar position |
+| `onAttachmentLimitExceeded` | `(reason, file) => void` | - | Called when limit exceeded |
+| `onFilesChange` | `(attachments) => void` | - | Called when attachments change |
 
-### Rich Mode Options
+### Rich Mode
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `uploadImage` | `(file: File) => Promise<{ url: string; alt?: string }>` | - | Image upload function |
-| `markdownOptions.enabledSyntax` | `MarkdownSyntaxOptions` | All enabled | Enable/disable specific markdown features |
+| `uploadImage` | `(file: File) => Promise<{url, alt?}>` | - | Image upload handler |
 
-### Keymap Options
+### Keymap
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `keymap.send` | `'enter' \| 'ctrlEnter' \| 'cmdEnter'` | `'enter'` | Key to send message |
+| `keymap.send` | `'enter' \| 'ctrlEnter' \| 'cmdEnter'` | `'enter'` | Send key configuration |
 
-### Other Props
+### Common
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `onContextMenu` | `MouseEventHandler` | Right-click handler |
-| `onQuoteRemoved` | `() => void` | Callback when quote is removed |
-| `locale` | `IMComposerLocale` | i18n configuration |
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `placeholder` | `string \| {plain?, rich?}` | - | Placeholder text |
+| `disabled` | `boolean` | `false` | Disable the editor |
+| `className` | `string` | - | Additional CSS class |
+| `locale` | `IMComposerLocale` | - | i18n strings |
+| `onSend` | `(payload) => void` | - | Called on send |
+| `onChange` | `() => void` | - | Called on content change |
+| `onQuoteRemoved` | `() => void` | - | Called when quote is removed |
 
 ## Ref Methods
 
-Access via `useRef<IMComposerRef>()`:
-
 ```tsx
-const composerRef = useRef<IMComposerRef>(null);
-
-// Focus the editor
-composerRef.current?.focus();
-
-// Clear content
-composerRef.current?.clear();
-
-// Export payload without sending
-const payload = composerRef.current?.exportPayload();
-
-// Insert text at cursor
-composerRef.current?.insertText('Hello 👋');
+interface IMComposerRef {
+  focus: () => void;
+  clear: () => void;
+  exportPayload: () => MessagePayload | null;
+
+  // Rich mode
+  importMarkdown: (markdown: string) => void;
+
+  // Attachments (plain mode)
+  getAttachments: () => Attachment[];
+  setAttachments: (attachments: Attachment[]) => void;
+  addFiles: (files: FileList | File[]) => void;
+  removeAttachment: (id: string) => void;
+  clearAttachments: () => void;
+
+  // Quote (plain mode)
+  insertQuote: (title: string, content: string) => void;
+
+  // Mention (plain mode)
+  insertMention: (userId: string, display: string) => void;
+
+  // Draft
+  getDraft: () => ComposerDraft;
+  setDraft: (draft: ComposerDraft) => void;
+
+  // Text
+  setText: (text: string) => void;
+  insertText: (text: string) => void;
+}
 ```
 
-### All Methods
-
-| Method | Description |
-|--------|-------------|
-| `focus()` | Focus the editor |
-| `clear()` | Clear editor content and attachments |
-| `exportPayload()` | Export current payload without sending |
-| `importMarkdown(markdown)` | Import markdown content (rich mode) |
-| `getAttachments()` | Get current attachments (plain mode) |
-| `setAttachments(attachments)` | Set attachments (plain mode) |
-| `addFiles(files)` | Add files to attachments (plain mode) |
-| `removeAttachment(id)` | Remove attachment by ID (plain mode) |
-| `clearAttachments()` | Clear all attachments (plain mode) |
-| `insertQuote(title, content)` | Insert a quote message (plain mode) |
-| `insertMention(userId, display)` | Insert a mention (plain mode) |
-| `getDraft()` | Get draft state for saving |
-| `setDraft(draft)` | Restore draft state |
-| `setText(text, mentions?)` | Set editor content from plain text |
-| `insertText(text)` | Insert text at cursor position |
-
 ## Payload Types
 
-### Plain Text Payload
+### Plain Message Payload
 
 ```typescript
-type PlainMessagePayload = {
+interface PlainMessagePayload {
   type: 'text';
-  plainText: string;        // Text with @mentions as @{display}
-  mentions: MentionInfo[];  // Position info for each mention
+  plainText: string;        // Text with mentions as @userId
+  mentions: MentionInfo[];  // Mention positions (UTF-16 indices)
   attachments: Attachment[];
   quote?: QuoteInfo;
-};
+}
+
+interface MentionInfo {
+  userId: string;
+  display: string;
+  start: number;  // UTF-16 index, inclusive
+  end: number;    // UTF-16 index, exclusive
+}
 ```
 
-### Markdown Payload
+### Markdown Message Payload
 
 ```typescript
-type MarkdownMessagePayload = {
+interface MarkdownMessagePayload {
   type: 'markdown';
-  markdown: string;  // Full markdown content
-};
+  markdown: string;  // Markdown content
+}
 ```
 
-## i18n / Localization
+## Implementing mentionProvider
+
+```typescript
+const mentionProvider = async (query: string): Promise<Member[]> => {
+  const response = await fetch(`/api/members/search?q=${encodeURIComponent(query)}`);
 
-Customize text labels with the `locale` prop:
+  if (!response.ok) {
+    throw new Error('Search failed');
+  }
 
-```tsx
-<IMComposer
-  locale={{
-    linkDialog: {
-      textLabel: '文本',
-      urlLabel: '链接',
-      cancelButton: '取消',
-      insertButton: '插入',
-      saveButton: '保存',
-    },
-    toolbar: {
-      bold: '粗体',
-      italic: '斜体',
-      link: '插入链接',
-      image: '插入图片',
-      // ... more toolbar labels
-    },
-  }}
-/>
+  return response.json();
+};
+
+// Member type
+interface Member {
+  userId: string;
+  display: string;
+  avatarUrl?: string;
+}
 ```
 
-## Draft Support
+The provider is called whenever the user types after `@`. Handle errors gracefully - they will be displayed in the mention list.
 
-Save and restore editor state for drafts:
+## Implementing uploadImage
 
-```tsx
-// Save draft
-const draft = composerRef.current?.getDraft();
-localStorage.setItem('draft', JSON.stringify(draft));
+```typescript
+const uploadImage = async (file: File): Promise<{ url: string; alt?: string }> => {
+  const formData = new FormData();
+  formData.append('file', file);
 
-// Restore draft
-const saved = localStorage.getItem('draft');
-if (saved) {
-  composerRef.current?.setDraft(JSON.parse(saved));
-}
+  const response = await fetch('/api/upload', {
+    method: 'POST',
+    body: formData,
+  });
+
+  if (!response.ok) {
+    throw new Error('Upload failed');
+  }
+
+  const { url } = await response.json();
+  return { url, alt: file.name };
+};
 ```
 
-## Markdown Syntax Control
+While uploading, `exportPayload()` returns `null` and send is disabled.
 
-Enable/disable specific markdown features:
+## Mention Index Calculation
 
-```tsx
-<IMComposer
-  mode="rich"
-  markdownOptions={{
-    enabledSyntax: {
-      heading: true,
-      bold: true,
-      italic: true,
-      strike: true,
-      codeInline: true,
-      codeBlock: true,
-      quote: true,
-      list: true,
-      link: true,
-      image: true,  // Requires uploadImage prop
-    },
-  }}
-/>
+Mention indices use UTF-16 code units (JavaScript string indices) with half-open intervals `[start, end)`:
+
+```typescript
+const plainText = '@alice hello @bob';
+//                 ^     ^      ^   ^
+//                 0     6      13  17
+
+const mentions = [
+  { userId: 'alice', display: 'Alice', start: 0, end: 6 },   // "@alice"
+  { userId: 'bob', display: 'Bob', start: 13, end: 17 },     // "@bob"
+];
+
+// Verify:
+plainText.slice(0, 6);   // "@alice"
+plainText.slice(13, 17); // "@bob"
 ```
 
-## Custom Mention Item Rendering
+## IME Handling
 
-```tsx
-<IMComposer
-  mentionProvider={searchUsers}
-  renderMentionItem={({ member, isSelected }) => (
-    <div className={`mention-item ${isSelected ? 'selected' : ''}`}>
-      <img src={member.avatarUrl} alt="" />
-      <span>{member.display}</span>
-    </div>
-  )}
-/>
-```
+The component properly handles IME (Input Method Editor) input for CJK languages:
+
+- Mention suggestion is **not** triggered during composition
+- Markdown shortcuts are **not** triggered during composition
+- Send key is **not** triggered during composition
+
+This prevents unexpected behavior when typing Chinese, Japanese, or Korean.
 
-## Styling
+## FAQ
 
-Import the default styles:
+### How do I switch between modes programmatically?
+
+Use controlled mode with the `mode` prop:
 
 ```tsx
-import 'im-composer/styles.css';
+const [mode, setMode] = useState<EditorMode>('plain');
+
+<IMComposer mode={mode} />
+<button onClick={() => setMode('rich')}>Switch to Rich</button>
 ```
 
-Customize with CSS variables or override the classes:
+### How do I save and restore drafts?
+
+```tsx
+// Save
+const draft = composerRef.current?.getDraft();
+localStorage.setItem(`draft:${chatId}`, JSON.stringify(draft));
 
-```css
-.im-composer {
-  --im-composer-border-color: #e0e0e0;
-  --im-composer-focus-color: #1890ff;
+// Restore
+const savedDraft = localStorage.getItem(`draft:${chatId}`);
+if (savedDraft) {
+  composerRef.current?.setDraft(JSON.parse(savedDraft));
 }
 ```
 
-## Exported Types
+### Why does exportPayload return null?
 
-```tsx
-import type {
-  IMComposerProps,
-  IMComposerRef,
-  IMComposerLocale,
-  PlainMessagePayload,
-  MarkdownMessagePayload,
-  MessagePayload,
-  Member,
-  MentionInfo,
-  Attachment,
-  QuoteInfo,
-  ComposerMode,
-  UploadImageFn,
-  UploadImageResult,
-  MarkdownSyntaxOptions,
-  SendKey,
-} from 'im-composer';
-```
+`exportPayload()` returns `null` when:
+- The editor is empty (no text and no attachments)
+- Image upload is in progress (rich mode)
 
-## License
+This helps prevent sending empty or incomplete messages.
 
-This package is licensed under the MIT License.
+### How do I customize styles?
 
-## Note on Emoji Rendering
+The component uses CSS Modules internally. You can override styles using the `className` prop and targeting the internal class names with higher specificity.
 
-This package uses CSS font-family declarations for emoji rendering. For consistent emoji display across platforms:
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Start demo
+pnpm dev
+
+# Build package
+pnpm build
+
+# Run tests
+pnpm test
+```
+
+## License
 
-1. Include an emoji font (like Twemoji) in your project
-2. If using Twemoji graphics, ensure proper attribution per CC BY 4.0 license
+MIT