@openim/im-composer 1.0.0 → 1.0.2

package/dist/index.d.mts

@@ -0,0 +1,617 @@
+import * as React$1 from 'react';
+import React__default, { MouseEventHandler, ReactNode } from 'react';
+import { Editor, useEditor } from '@tiptap/react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { Editor as Editor$1 } from '@tiptap/core';
+
+/**
+ * Represents a file attachment in plain mode
+ */
+interface Attachment {
+    /** Unique identifier generated by the component */
+    id: string;
+    /** Original File object */
+    file: File;
+    /** File name */
+    name: string;
+    /** File size in bytes */
+    size: number;
+    /** MIME type */
+    mime: string;
+    /** File last modified timestamp */
+    lastModified?: number;
+    /** Preview URL for images (objectURL) */
+    previewUrl?: string;
+}
+/**
+ * Information about a mention in the message
+ */
+interface MentionInfo {
+    /** User ID */
+    userId: string;
+    /** Display name */
+    display: string;
+    /** Start index in plainText (UTF-16, inclusive) */
+    start: number;
+    /** End index in plainText (UTF-16, exclusive) */
+    end: number;
+}
+/**
+ * Member data for mention suggestions
+ */
+interface Member {
+    /** Unique user identifier */
+    userId: string;
+    /** Display name shown in the editor */
+    display: string;
+    /** Optional avatar URL */
+    avatarUrl?: string;
+}
+/**
+ * Quoted message information
+ */
+interface QuoteInfo {
+    /** Quote title, e.g., "Reply to Alice:" */
+    title: string;
+    /** Quoted content */
+    content: string;
+}
+/**
+ * Result from image upload handler
+ */
+interface UploadImageResult {
+    /** URL of the uploaded image */
+    url: string;
+    /** Optional alt text */
+    alt?: string;
+}
+/**
+ * Progress callback for image upload
+ */
+interface UploadProgressEvent {
+    /** Upload progress percentage (0-100) */
+    progress: number;
+}
+/**
+ * Image upload function type with optional progress callback
+ */
+type UploadImageFn = (file: File, onProgress?: (event: UploadProgressEvent) => void) => Promise<UploadImageResult>;
+/**
+ * Payload for plain text mode messages
+ */
+interface PlainMessagePayload {
+    type: 'text';
+    /** Plain text with mentions as @userId */
+    plainText: string;
+    /** List of mentions with their positions */
+    mentions: MentionInfo[];
+    /** List of attached files */
+    attachments: Attachment[];
+    /** Quoted message (if any) */
+    quote?: QuoteInfo;
+}
+/**
+ * Payload for rich text mode messages (Markdown)
+ */
+interface MarkdownMessagePayload {
+    type: 'markdown';
+    /** Markdown content */
+    markdown: string;
+}
+/**
+ * Union type for all message payloads
+ */
+type MessagePayload = PlainMessagePayload | MarkdownMessagePayload;
+/**
+ * Draft state for saving/restoring editor content
+ */
+interface ComposerDraft {
+    /** Editor mode */
+    mode?: EditorMode;
+    /** Serialized editor state (JSON string from getJSON) - deprecated, use json */
+    editorState?: string;
+    /** Editor JSON content */
+    json?: Record<string, unknown>;
+    /** Attachments (plain mode only) */
+    attachments?: Attachment[];
+    /** Quick restore text for plain mode */
+    text?: string;
+    /** Quote information (plain mode only) */
+    quote?: QuoteInfo;
+}
+/**
+ * Locale strings for internationalization
+ */
+interface IMComposerLocale {
+    /** Placeholder text for plain mode */
+    placeholderPlain?: string;
+    /** Placeholder text for rich mode */
+    placeholderRich?: string;
+    /** No results found in mention list */
+    mentionNoResults?: string;
+    /** Loading text for mention list */
+    mentionLoading?: string;
+    /** Error text for mention list */
+    mentionError?: string;
+    /** Remove attachment button label */
+    removeAttachment?: string;
+    /** Remove quote button label */
+    removeQuote?: string;
+    /** Upload failed message */
+    uploadFailed?: string;
+    /** Uploading text */
+    uploading?: string;
+    /** Undo button */
+    undo?: string;
+    /** Redo button */
+    redo?: string;
+    /** Heading dropdown */
+    heading?: string;
+    /** Heading 1 */
+    heading1?: string;
+    /** Heading 2 */
+    heading2?: string;
+    /** Heading 3 */
+    heading3?: string;
+    /** Heading 4 */
+    heading4?: string;
+    /** Paragraph */
+    paragraph?: string;
+    /** List dropdown */
+    list?: string;
+    /** Bullet list */
+    bulletList?: string;
+    /** Ordered list */
+    orderedList?: string;
+    /** Task list */
+    taskList?: string;
+    /** Blockquote button */
+    blockquote?: string;
+    /** Code block button */
+    codeBlock?: string;
+    /** Bold button */
+    bold?: string;
+    /** Italic button */
+    italic?: string;
+    /** Strikethrough button */
+    strike?: string;
+    /** Inline code button */
+    code?: string;
+    /** Underline button */
+    underline?: string;
+    /** Highlight button */
+    highlight?: string;
+    /** Remove highlight */
+    removeHighlight?: string;
+    /** Link button */
+    link?: string;
+    /** Link input placeholder */
+    linkPlaceholder?: string;
+    /** Apply link */
+    applyLink?: string;
+    /** Open link */
+    openLink?: string;
+    /** Remove link */
+    removeLink?: string;
+    /** Superscript button */
+    superscript?: string;
+    /** Subscript button */
+    subscript?: string;
+    /** Align left button */
+    alignLeft?: string;
+    /** Align center button */
+    alignCenter?: string;
+    /** Align right button */
+    alignRight?: string;
+    /** Align justify button */
+    alignJustify?: string;
+    /** Insert image button */
+    insertImage?: string;
+    /** Upload image */
+    uploadImage?: string;
+    /** Click to upload */
+    clickToUpload?: string;
+    /** Or drag and drop */
+    orDragAndDrop?: string;
+    /** Maximum files */
+    maxFiles?: string;
+    /** Clear all */
+    clearAll?: string;
+}
+/**
+ * Default English locale
+ */
+declare const defaultLocale: IMComposerLocale;
+/**
+ * Send keymap configuration
+ */
+type SendKeymap = 'enter' | 'ctrlEnter' | 'cmdEnter';
+/**
+ * Editor mode
+ */
+type EditorMode = 'plain' | 'rich';
+/**
+ * Attachment limit exceeded reason
+ */
+type AttachmentLimitReason = 'count' | 'size' | 'mime';
+/**
+ * Main component props
+ */
+interface IMComposerProps {
+    /** Controlled mode */
+    mode?: EditorMode;
+    /** Default mode for uncontrolled usage */
+    defaultMode?: EditorMode;
+    /** Called when user triggers send action */
+    onSend?: (payload: PlainMessagePayload | MarkdownMessagePayload) => void;
+    /** Called when editor content changes */
+    onChange?: () => void;
+    /** Context menu handler */
+    onContextMenu?: MouseEventHandler<HTMLDivElement>;
+    /** Called when quote is removed */
+    onQuoteRemoved?: () => void;
+    /** Enable @mention feature */
+    enableMention?: boolean;
+    /** Async provider for mention suggestions */
+    mentionProvider?: (query: string) => Promise<Member[]>;
+    /** Maximum number of mentions allowed */
+    maxMentions?: number;
+    /** Custom render function for mention list items */
+    renderMentionItem?: (props: {
+        member: Member;
+        isSelected: boolean;
+    }) => ReactNode;
+    /** Mention list placement relative to cursor: 'top' or 'bottom' */
+    mentionPlacement?: 'top' | 'bottom';
+    /** Enable file attachments */
+    enableAttachments?: boolean;
+    /** Attachment preview bar placement */
+    attachmentPreviewPlacement?: 'top' | 'bottom';
+    /** Maximum number of attachments */
+    maxAttachments?: number;
+    /** Allowed MIME types (supports wildcards like "image/*") */
+    allowedMimeTypes?: string[];
+    /** Maximum file size in bytes */
+    maxFileSize?: number;
+    /** Called when attachment limit is exceeded */
+    onAttachmentLimitExceeded?: (reason: AttachmentLimitReason, file: File) => void;
+    /** Called when attachments change */
+    onFilesChange?: (attachments: Attachment[]) => void;
+    /** Show attachment preview bar */
+    showAttachmentPreview?: boolean;
+    /** Markdown options */
+    markdownOptions?: {
+        enabledSyntax?: string[];
+    };
+    /** Image upload handler with optional progress callback */
+    uploadImage?: UploadImageFn;
+    /** Keymap configuration */
+    keymap?: {
+        send?: SendKeymap;
+    };
+    /** Placeholder text (string or per-mode object) */
+    placeholder?: string | {
+        plain?: string;
+        rich?: string;
+    };
+    /** Disable the editor */
+    disabled?: boolean;
+    /** Additional CSS class */
+    className?: string;
+    /** Locale strings */
+    locale?: IMComposerLocale;
+}
+/**
+ * Methods exposed via ref
+ */
+interface IMComposerRef {
+    /** Focus the editor */
+    focus: () => void;
+    /** Clear the editor content */
+    clear: () => void;
+    /** Export current content as payload. Returns null if empty or uploading */
+    exportPayload: () => PlainMessagePayload | MarkdownMessagePayload | null;
+    /** Import markdown content (rich mode only) */
+    importMarkdown: (markdown: string) => void;
+    /** Get current attachments */
+    getAttachments: () => Attachment[];
+    /** Set attachments */
+    setAttachments: (attachments: Attachment[]) => void;
+    /** Add files to attachments */
+    addFiles: (files: FileList | File[]) => void;
+    /** Remove a specific attachment by ID */
+    removeAttachment: (id: string) => void;
+    /** Clear all attachments */
+    clearAttachments: () => void;
+    /** Insert or replace a quote */
+    insertQuote: (title: string, content: string) => void;
+    /** Programmatically insert a mention */
+    insertMention: (userId: string, display: string) => void;
+    /** Get current draft state */
+    getDraft: () => ComposerDraft;
+    /** Restore from draft state */
+    setDraft: (draft: ComposerDraft) => void;
+    /** Set text content (with optional mentions for plain mode) */
+    setText: (text: string, mentions?: Member[]) => void;
+    /** Insert text at cursor */
+    insertText: (text: string) => void;
+}
+/**
+ * @internal Mention suggestion state
+ */
+interface MentionSuggestionState {
+    active: boolean;
+    query: string;
+    items: Member[];
+    selectedIndex: number;
+    loading: boolean;
+    error: boolean;
+    /** Command to insert a mention (replaces @ trigger) */
+    command: ((member: {
+        userId: string;
+        display: string;
+    }) => void) | null;
+}
+
+/**
+ * IM Composer component supporting plain text and rich text modes.
+ */
+declare const IMComposer: React__default.ForwardRefExoticComponent<IMComposerProps & React__default.RefAttributes<IMComposerRef>>;
+
+interface RichEditorProps {
+    placeholder?: string;
+    disabled?: boolean;
+    uploadImage?: UploadImageFn;
+    onUploadingChange?: (count: number) => void;
+    onSend?: () => void;
+    onChange?: () => void;
+    sendKeymap?: 'enter' | 'ctrlEnter' | 'cmdEnter';
+}
+interface RichEditorRef {
+    editor: Editor | null;
+    focus: () => void;
+    clear: () => void;
+    exportPayload: () => MarkdownMessagePayload | null;
+    importMarkdown: (markdown: string) => void;
+    getDraft: () => ComposerDraft;
+    setDraft: (draft: ComposerDraft) => void;
+    setText: (text: string) => void;
+    insertText: (text: string) => void;
+    isUploading: () => boolean;
+}
+declare const RichEditor: React$1.ForwardRefExoticComponent<RichEditorProps & React$1.RefAttributes<RichEditorRef>>;
+
+declare function LocaleProvider({ locale, children, }: {
+    locale?: IMComposerLocale;
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function useLocale(): IMComposerLocale;
+
+interface MentionListProps {
+    /** List of member suggestions */
+    items: Member[];
+    /** Currently selected index */
+    selectedIndex: number;
+    /** Loading state */
+    loading: boolean;
+    /** Error state */
+    error: boolean;
+    /** Called when item is clicked */
+    onSelect: (member: Member) => void;
+    /** Called when mouse enters an item */
+    onHover: (index: number) => void;
+    /** Custom render function */
+    renderItem?: (props: {
+        member: Member;
+        isSelected: boolean;
+    }) => React__default.ReactNode;
+    /** Locale strings */
+    locale?: {
+        noResults?: string;
+        loading?: string;
+        error?: string;
+    };
+}
+/**
+ * Mention suggestion list component.
+ */
+declare function MentionList({ items, selectedIndex, loading, error, onSelect, onHover, renderItem, locale, }: MentionListProps): react_jsx_runtime.JSX.Element | null;
+
+interface AttachmentPreviewProps {
+    /** List of attachments */
+    attachments: Attachment[];
+    /** Called when remove button is clicked */
+    onRemove: (id: string) => void;
+    /** Placement position */
+    placement?: 'top' | 'bottom';
+    /** Remove button label */
+    removeLabel?: string;
+}
+/**
+ * Attachment preview bar component.
+ */
+declare function AttachmentPreview({ attachments, onRemove, placement, removeLabel, }: AttachmentPreviewProps): react_jsx_runtime.JSX.Element | null;
+
+interface QuoteBarProps {
+    /** Quote information */
+    quote: QuoteInfo;
+    /** Called when remove button is clicked */
+    onRemove: () => void;
+    /** Remove button label */
+    removeLabel?: string;
+}
+/**
+ * Quote message bar component.
+ */
+declare function QuoteBar({ quote, onRemove, removeLabel }: QuoteBarProps): react_jsx_runtime.JSX.Element;
+
+interface UseAttachmentsOptions {
+    /** Maximum number of attachments */
+    maxAttachments?: number;
+    /** Maximum file size in bytes */
+    maxFileSize?: number;
+    /** Allowed MIME types */
+    allowedMimeTypes?: string[];
+    /** Called when limit is exceeded */
+    onLimitExceeded?: (reason: AttachmentLimitReason, file: File) => void;
+    /** Called when attachments change */
+    onChange?: (attachments: Attachment[]) => void;
+}
+interface UseAttachmentsReturn {
+    /** Current attachments */
+    attachments: Attachment[];
+    /** Add files to attachments */
+    addFiles: (files: FileList | File[]) => void;
+    /** Remove attachment by ID */
+    removeAttachment: (id: string) => void;
+    /** Clear all attachments */
+    clearAttachments: () => void;
+    /** Set attachments directly */
+    setAttachments: (attachments: Attachment[]) => void;
+    /** Get current attachments */
+    getAttachments: () => Attachment[];
+}
+/**
+ * Hook for managing file attachments with proper objectURL lifecycle.
+ */
+declare function useAttachments(options?: UseAttachmentsOptions): UseAttachmentsReturn;
+
+interface UsePlainEditorOptions {
+    /** Placeholder text */
+    placeholder?: string;
+    /** Keymap for send */
+    sendKeymap?: SendKeymap;
+    /** Called when send is triggered */
+    onSend?: () => void;
+    /** Enable mention */
+    enableMention?: boolean;
+    /** Mention provider */
+    mentionProvider?: (query: string) => Promise<Member[]>;
+    /** Max mentions */
+    maxMentions?: number;
+    /** Called when mention state changes */
+    onMentionStateChange?: (state: MentionSuggestionState) => void;
+    /** Called when files are pasted */
+    onPasteFiles?: (files: File[]) => void;
+    /** Get current uploading state */
+    isUploading?: () => boolean;
+    /** Disabled state */
+    disabled?: boolean;
+    /** Called on content change */
+    onChange?: () => void;
+    /** Called when quote is removed */
+    onQuoteRemoved?: () => void;
+}
+interface UsePlainEditorReturn {
+    /** Tiptap editor instance */
+    editor: ReturnType<typeof useEditor>;
+    /** Check if composing (IME) */
+    isComposing: () => boolean;
+    /** Check if mention list is open */
+    isMentionListOpen: () => boolean;
+    /** Export payload */
+    exportPayload: (attachments: Attachment[]) => PlainMessagePayload | null;
+    /** Get draft */
+    getDraft: (attachments: Attachment[]) => ComposerDraft;
+    /** Set draft */
+    setDraft: (draft: ComposerDraft) => void;
+    /** Insert mention programmatically */
+    insertMention: (userId: string, display: string) => void;
+    /** Insert quote */
+    insertQuote: (title: string, content: string) => void;
+    /** Remove quote */
+    removeQuote: () => void;
+    /** Get current quote */
+    getQuote: () => QuoteInfo | undefined;
+    /** Set text content */
+    setText: (text: string) => void;
+    /** Insert text at cursor */
+    insertText: (text: string) => void;
+    /** Clear editor */
+    clear: () => void;
+    /** Focus editor */
+    focus: () => void;
+}
+/**
+ * Hook for managing plain text editor.
+ */
+declare function usePlainEditor(options?: UsePlainEditorOptions): UsePlainEditorReturn;
+
+/**
+ * Extract plain text and mention information from the editor.
+ * Mention tokens are output as @{userId} followed by a space.
+ *
+ * @param editor Tiptap editor instance
+ * @returns Object containing plainText and mentions array with UTF-16 indices
+ */
+declare function extractPlainTextWithMentions(editor: Editor$1): {
+    plainText: string;
+    mentions: MentionInfo[];
+};
+/**
+ * Check if mention indices are valid and aligned with the plainText.
+ */
+declare function validateMentionIndices(plainText: string, mentions: MentionInfo[]): boolean;
+/**
+ * Create a mention info object with calculated indices.
+ */
+declare function createMentionInfo(userId: string, display: string, startIndex: number): MentionInfo;
+
+/**
+ * Create an Attachment object from a File.
+ */
+declare function createAttachment(file: File): Attachment;
+/**
+ * Revoke object URL for an attachment.
+ */
+declare function revokeAttachmentUrl(attachment: Attachment): void;
+/**
+ * Revoke all object URLs for a list of attachments.
+ */
+declare function revokeAllAttachmentUrls(attachments: Attachment[]): void;
+/**
+ * Validate a file against attachment constraints.
+ * Returns the reason for rejection, or null if valid.
+ */
+declare function validateFile(file: File, currentCount: number, options: {
+    maxAttachments?: number;
+    maxFileSize?: number;
+    allowedMimeTypes?: string[];
+}): AttachmentLimitReason | null;
+/**
+ * Format file size for display.
+ */
+declare function formatFileSize(bytes: number): string;
+
+/**
+ * Markdown serializer for Tiptap editor content.
+ * Converts the editor document to Markdown string.
+ */
+declare function editorToMarkdown(editor: Editor$1): string;
+/**
+ * Parse Markdown to Tiptap-compatible JSON content.
+ * This is a simplified parser for the Markdown subset we support.
+ */
+declare function markdownToEditorContent(markdown: string): any;
+
+/**
+ * Check if a URL has an allowed protocol for links.
+ */
+declare function isAllowedLinkProtocol(url: string): boolean;
+/**
+ * Check if a URL has an allowed protocol for images.
+ */
+declare function isAllowedImageProtocol(url: string): boolean;
+/**
+ * Sanitize a URL for links.
+ * - Adds https:// if no protocol is present
+ * - Returns null if protocol is not allowed (including javascript:, vbscript:, etc.)
+ */
+declare function sanitizeLinkUrl(url: string): string | null;
+/**
+ * Sanitize a URL for images.
+ * Returns null if protocol is not allowed.
+ */
+declare function sanitizeImageUrl(url: string): string | null;
+
+export { type Attachment, type AttachmentLimitReason, AttachmentPreview, type AttachmentPreviewProps, type ComposerDraft, type EditorMode, IMComposer, type IMComposerLocale, type IMComposerProps, type IMComposerRef, LocaleProvider, type MarkdownMessagePayload, type Member, type MentionInfo, MentionList, type MentionListProps, type MessagePayload, type PlainMessagePayload, QuoteBar, type QuoteBarProps, type QuoteInfo, RichEditor, type RichEditorProps, type RichEditorRef, type SendKeymap, type UploadImageFn, type UploadImageResult, type UploadProgressEvent, type UseAttachmentsOptions, type UseAttachmentsReturn, type UsePlainEditorOptions, type UsePlainEditorReturn, createAttachment, createMentionInfo, defaultLocale, editorToMarkdown, extractPlainTextWithMentions, formatFileSize, isAllowedImageProtocol, isAllowedLinkProtocol, markdownToEditorContent, revokeAllAttachmentUrls, revokeAttachmentUrl, sanitizeImageUrl, sanitizeLinkUrl, useAttachments, useLocale, usePlainEditor, validateFile, validateMentionIndices };