@convokitapp/react-ui 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,316 @@
+import { Message, Conversation as Conversation$1, MessageMedia, RealtimeSubscription, ReadEvent, TypingEvent, ConvoKitClient } from '@convokitapp/sdk';
+import * as react from 'react';
+import { CSSProperties, HTMLAttributes, ReactNode, RefObject, TextareaHTMLAttributes, PropsWithChildren } from 'react';
+
+interface ConvoKitUiClient {
+    readonly currentUserId: string;
+    getConversations(options: {
+        limit: number;
+        offset: number;
+        archived: boolean;
+    }): Promise<Conversation$1[]>;
+    getConversation(conversationId: string): Promise<Conversation$1>;
+    getMessages(options: {
+        conversationId: string;
+        limit: number;
+        offset: number;
+    }): Promise<Message[]>;
+    sendMessage(input: {
+        conversationId: string;
+        text?: string;
+        media?: MessageMedia[];
+    }): Promise<Message>;
+    markConversationRead(conversationId: string): Promise<void>;
+    sendTyping(input: {
+        conversationId: string;
+        isTyping: boolean;
+    }): Promise<void>;
+    onMessage(conversationId: string, handler: (message: Message) => void, onError?: (error: Error) => void): RealtimeSubscription;
+    onReadReceipt(conversationId: string, handler: (event: ReadEvent) => void, onError?: (error: Error) => void): RealtimeSubscription;
+    onTyping(conversationId: string, handler: (event: TypingEvent) => void, onError?: (error: Error) => void): RealtimeSubscription;
+}
+interface ConversationFilter {
+    query?: string;
+    archived?: boolean;
+    participantIds?: ReadonlySet<string> | readonly string[];
+    requireAllParticipants?: boolean;
+    predicate?: (conversation: Conversation$1) => boolean;
+    comparator?: (left: Conversation$1, right: Conversation$1) => number;
+}
+interface ConversationPageRequest {
+    limit: number;
+    offset: number;
+    filter: ConversationFilter;
+}
+type ConversationPageLoader = (request: ConversationPageRequest) => Promise<Conversation$1[]>;
+interface ConversationListState {
+    conversations: Conversation$1[];
+    filter: ConversationFilter;
+    isInitialLoading: boolean;
+    isLoadingMore: boolean;
+    hasMore: boolean;
+    hasLoaded: boolean;
+    error: unknown;
+}
+interface ConversationState {
+    conversation: Conversation$1 | null;
+    messages: Message[];
+    typingUserIds: ReadonlySet<string>;
+    readAtByUserId: ReadonlyMap<string, Date>;
+    isInitialLoading: boolean;
+    isLoadingOlder: boolean;
+    isSending: boolean;
+    hasOlderMessages: boolean;
+    hasLoaded: boolean;
+    error: unknown;
+    currentUserId: string;
+    readerIdsFor(message: Message): ReadonlySet<string>;
+}
+type ConvoKitUiDensity = 'comfortable' | 'compact';
+type ConvoKitUiPart = 'root' | 'list' | 'listItem' | 'avatar' | 'header' | 'messages' | 'message' | 'incomingMessage' | 'outgoingMessage' | 'media' | 'receipt' | 'typing' | 'composer' | 'input' | 'button' | 'empty' | 'loading' | 'error';
+interface ConvoKitAppearanceProps {
+    classNames?: Partial<Record<ConvoKitUiPart, string>>;
+    styles?: Partial<Record<ConvoKitUiPart, CSSProperties>>;
+    density?: ConvoKitUiDensity;
+    unstyled?: boolean;
+}
+interface ConversationItemRenderProps {
+    conversation: Conversation$1;
+    index: number;
+    selected: boolean;
+    onSelect: () => void;
+}
+interface MessageRenderProps {
+    message: Message;
+    chronologicalIndex: number;
+    isCurrentUser: boolean;
+    sender: Conversation$1['participants'][number] | undefined;
+    readerIds: ReadonlySet<string>;
+}
+interface MediaRenderProps {
+    media: MessageMedia;
+    message: Message;
+    isCurrentUser: boolean;
+    onOpen?: () => void;
+}
+interface ComposerRenderProps {
+    value: string;
+    setValue: (value: string) => void;
+    isSending: boolean;
+    send: () => void;
+    addAttachment?: () => void;
+}
+interface TypingRenderProps {
+    userIds: ReadonlySet<string>;
+    displayNameForUser: (userId: string) => string;
+}
+interface ReadReceiptRenderProps {
+    message: Message;
+    readerIds: ReadonlySet<string>;
+}
+interface ErrorRenderProps {
+    error: unknown;
+    retry?: () => void;
+}
+interface BaseViewProps extends ConvoKitAppearanceProps, Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'style'> {
+    style?: CSSProperties;
+}
+interface ScrollOptions {
+    scrollRef?: RefObject<HTMLDivElement | null>;
+    paginationThreshold?: number;
+}
+type StateRenderer = () => ReactNode;
+type ErrorRenderer = (props: ErrorRenderProps) => ReactNode;
+
+/** Adapts a connected `@convokitapp/sdk` client to the replaceable UI boundary. */
+declare function createConvoKitUiClient(client: ConvoKitClient): ConvoKitUiClient;
+
+interface ConvoKitAvatarProps extends HTMLAttributes<HTMLSpanElement> {
+    name: string;
+    src?: string | null;
+}
+/** Accessible avatar built on Radix Avatar. */
+declare function ConvoKitAvatar({ name, src, className, ...props }: ConvoKitAvatarProps): react.JSX.Element;
+
+interface UseConversationOptions {
+    client: ConvoKitUiClient;
+    conversationId: string;
+    messagePageSize?: number;
+    markReadOnLoad?: boolean;
+    markReadOnReceive?: boolean;
+    typingTimeoutMs?: number;
+    autoLoad?: boolean;
+}
+interface ConversationController extends ConversationState {
+    loadInitial(): Promise<void>;
+    refresh(): Promise<void>;
+    loadOlderMessages(): Promise<void>;
+    sendMessage(input: {
+        text?: string;
+        media?: MessageMedia[];
+    }): Promise<Message | null>;
+    markRead(): Promise<void>;
+    updateTyping(isTyping: boolean): Promise<void>;
+}
+/** Owns one conversation's history, realtime state, sending, and read positions. */
+declare function useConversation({ client, conversationId, messagePageSize, markReadOnLoad, markReadOnReceive, typingTimeoutMs, autoLoad, }: UseConversationOptions): ConversationController;
+
+interface MessageListViewProps extends BaseViewProps, ScrollOptions {
+    conversation: Conversation$1;
+    messages: readonly Message[];
+    currentUserId: string;
+    readAtByUserId?: ReadonlyMap<string, Date>;
+    readersResolver?: (message: Message) => ReadonlySet<string>;
+    onLoadOlder?: () => void | Promise<void>;
+    hasOlderMessages?: boolean;
+    isLoadingOlder?: boolean;
+    error?: unknown;
+    renderMessage?: (props: MessageRenderProps) => ReactNode;
+    renderMedia?: (props: MediaRenderProps) => ReactNode;
+    renderReadReceipt?: (props: ReadReceiptRenderProps) => ReactNode;
+    onAttachmentClick?: (media: MessageMedia, message: Message) => void;
+    renderEmpty?: StateRenderer;
+    renderLoadingOlder?: StateRenderer;
+    renderError?: ErrorRenderer;
+    reverse?: boolean;
+    stickToBottom?: boolean;
+    formatTime?: (date: Date) => string;
+    imageLoading?: 'eager' | 'lazy';
+}
+/** Controlled message history with read receipts, structured media, and older-page loading. */
+declare function MessageListView({ conversation, messages, currentUserId, readAtByUserId, readersResolver, onLoadOlder, hasOlderMessages, isLoadingOlder, error, renderMessage, renderMedia, renderReadReceipt, onAttachmentClick, renderEmpty, renderLoadingOlder, renderError, scrollRef, paginationThreshold, reverse, stickToBottom, formatTime, imageLoading, className, style, classNames, styles, density, unstyled, onScroll, ...rootProps }: MessageListViewProps): react.JSX.Element;
+
+interface ConversationViewProps extends BaseViewProps {
+    conversation: Conversation$1;
+    messages: readonly Message[];
+    currentUserId: string;
+    onSendMessage: (text: string) => boolean | void | Promise<boolean | void>;
+    typingUserIds?: ReadonlySet<string>;
+    readAtByUserId?: ReadonlyMap<string, Date>;
+    readersResolver?: (message: Message) => ReadonlySet<string>;
+    onBack?: () => void;
+    onRefresh?: () => void | Promise<void>;
+    onLoadOlder?: () => void | Promise<void>;
+    onTypingChange?: (isTyping: boolean) => void | Promise<void>;
+    onAddAttachment?: () => void;
+    onAttachmentClick?: (media: MessageMedia, message: Message) => void;
+    isInitialLoading?: boolean;
+    isLoadingOlder?: boolean;
+    isSending?: boolean;
+    hasOlderMessages?: boolean;
+    error?: unknown;
+    messageError?: unknown;
+    renderHeader?: (props: {
+        conversation: Conversation$1;
+        onBack?: () => void;
+        onRefresh?: () => void | Promise<void>;
+    }) => ReactNode;
+    renderMessage?: (props: MessageRenderProps) => ReactNode;
+    renderMedia?: (props: MediaRenderProps) => ReactNode;
+    renderReadReceipt?: (props: ReadReceiptRenderProps) => ReactNode;
+    renderComposer?: (props: ComposerRenderProps) => ReactNode;
+    renderTypingIndicator?: (props: TypingRenderProps) => ReactNode;
+    renderEmpty?: StateRenderer;
+    renderLoading?: StateRenderer;
+    renderError?: ErrorRenderer;
+    renderLoadingOlder?: StateRenderer;
+    renderMessageError?: ErrorRenderer;
+    displayNameForUser?: (userId: string) => string | null | undefined;
+    reverseMessages?: boolean;
+    stickToBottom?: boolean;
+    paginationThreshold?: number;
+    formatTime?: MessageListViewProps['formatTime'];
+    imageLoading?: MessageListViewProps['imageLoading'];
+    composerPlaceholder?: string;
+    composerAriaLabel?: string;
+    composerProps?: Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'value' | 'defaultValue' | 'onChange' | 'disabled'>;
+    draft?: string;
+    defaultDraft?: string;
+    onDraftChange?: (value: string) => void;
+}
+/** Controlled, complete selected-conversation surface. */
+declare function ConversationView({ conversation, messages, currentUserId, onSendMessage, typingUserIds, readAtByUserId, readersResolver, onBack, onRefresh, onLoadOlder, onTypingChange, onAddAttachment, onAttachmentClick, isInitialLoading, isLoadingOlder, isSending, hasOlderMessages, error, messageError, renderHeader, renderMessage, renderMedia, renderReadReceipt, renderComposer, renderTypingIndicator, renderEmpty, renderLoading, renderError, renderLoadingOlder, renderMessageError, displayNameForUser, reverseMessages, stickToBottom, paginationThreshold, formatTime, imageLoading, composerPlaceholder, composerAriaLabel, composerProps, draft: controlledDraft, defaultDraft, onDraftChange, className, classNames, styles, density, unstyled, ...rootProps }: ConversationViewProps): react.JSX.Element;
+interface ConversationProps extends Omit<ConversationViewProps, 'conversation' | 'messages' | 'currentUserId' | 'onSendMessage' | 'typingUserIds' | 'readAtByUserId' | 'onRefresh' | 'onLoadOlder' | 'onTypingChange' | 'isInitialLoading' | 'isLoadingOlder' | 'isSending' | 'hasOlderMessages' | 'error'>, UseConversationOptions {
+    renderLoading?: StateRenderer;
+    onControllerChange?: (controller: ConversationController) => void;
+}
+/** Plug-and-play SDK-backed UI for one conversation. */
+declare function Conversation({ client, conversationId, messagePageSize, markReadOnLoad, markReadOnReceive, typingTimeoutMs, autoLoad, renderLoading, onControllerChange, ...viewProps }: ConversationProps): react.JSX.Element;
+declare function defaultReadersResolver(readAtByUserId: ReadonlyMap<string, Date>): (message: Message) => ReadonlySet<string>;
+
+interface UseConversationListOptions {
+    client: ConvoKitUiClient;
+    pageLoader?: ConversationPageLoader;
+    initialFilter?: ConversationFilter;
+    pageSize?: number;
+    autoLoad?: boolean;
+}
+interface ConversationListController extends ConversationListState {
+    loadInitial(): Promise<void>;
+    refresh(): Promise<void>;
+    loadMore(): Promise<void>;
+    setFilter(filter: ConversationFilter): Promise<void>;
+    setQuery(query: string): Promise<void>;
+}
+/** Loads, de-duplicates, filters, and paginates conversations. */
+declare function useConversationList({ client, pageLoader, initialFilter, pageSize, autoLoad, }: UseConversationListOptions): ConversationListController;
+
+interface ConversationListViewProps extends BaseViewProps, ScrollOptions {
+    conversations: readonly Conversation$1[];
+    onConversationSelect: (conversation: Conversation$1) => void;
+    selectedConversationId?: string;
+    onRefresh?: () => void | Promise<void>;
+    onLoadMore?: () => void | Promise<void>;
+    isInitialLoading?: boolean;
+    isLoadingMore?: boolean;
+    hasMore?: boolean;
+    error?: unknown;
+    renderConversationItem?: (props: ConversationItemRenderProps) => ReactNode;
+    renderSeparator?: (index: number) => ReactNode;
+    renderEmpty?: StateRenderer;
+    renderInitialLoading?: StateRenderer;
+    renderError?: ErrorRenderer;
+    renderLoadMore?: StateRenderer;
+    ariaLabel?: string;
+}
+/** Controlled conversation list. It can be used with any state-management layer. */
+declare function ConversationListView({ conversations, onConversationSelect, selectedConversationId, onRefresh, onLoadMore, isInitialLoading, isLoadingMore, hasMore, error, renderConversationItem, renderSeparator, renderEmpty, renderInitialLoading, renderError, renderLoadMore, scrollRef, paginationThreshold, ariaLabel, className, style, classNames, styles, density, unstyled, onScroll, ...rootProps }: ConversationListViewProps): react.JSX.Element;
+interface ConversationListProps extends Omit<ConversationListViewProps, 'conversations' | 'onRefresh' | 'onLoadMore' | 'isInitialLoading' | 'isLoadingMore' | 'hasMore' | 'error'>, UseConversationListOptions {
+    onControllerChange?: (controller: ConversationListController) => void;
+}
+/** Plug-and-play SDK-backed conversation list. */
+declare function ConversationList({ client, pageLoader, initialFilter, pageSize, autoLoad, onControllerChange, ...viewProps }: ConversationListProps): react.JSX.Element;
+
+interface ConvoKitTheme {
+    background: string;
+    surface: string;
+    primary: string;
+    text: string;
+    mutedText: string;
+    border: string;
+    error: string;
+    incomingBubble: string;
+    outgoingBubble: string;
+    outgoingText: string;
+    radius: string;
+    avatarSize: string;
+    fontFamily: string;
+}
+declare const defaultConvoKitTheme: ConvoKitTheme;
+interface ConvoKitThemeProviderProps extends PropsWithChildren {
+    theme?: Partial<ConvoKitTheme>;
+    className?: string;
+    style?: CSSProperties;
+}
+/** Supplies theme tokens as CSS variables. Nest providers to override a subtree. */
+declare function ConvoKitThemeProvider({ children, theme, className, style, }: ConvoKitThemeProviderProps): react.JSX.Element;
+declare function useConvoKitTheme(): ConvoKitTheme;
+
+declare function matchesConversation(conversation: Conversation$1, filter: ConversationFilter): boolean;
+declare function applyConversationFilter(conversations: readonly Conversation$1[], filter: ConversationFilter): Conversation$1[];
+declare function mergeConversations(current: readonly Conversation$1[], incoming: readonly Conversation$1[]): Conversation$1[];
+declare function mergeMessages(current: readonly Message[], incoming: readonly Message[]): Message[];
+declare function readerIdsFor(message: Message, readAtByUserId: ReadonlyMap<string, Date>): ReadonlySet<string>;
+declare function formatFileSize(size: number | undefined): string | null;
+
+export { type BaseViewProps, type ComposerRenderProps, Conversation, type ConversationController, type ConversationFilter, type ConversationItemRenderProps, ConversationList, type ConversationListController, type ConversationListProps, type ConversationListState, ConversationListView, type ConversationListViewProps, type ConversationPageLoader, type ConversationPageRequest, type ConversationProps, type ConversationState, ConversationView, type ConversationViewProps, type ConvoKitAppearanceProps, ConvoKitAvatar, type ConvoKitAvatarProps, type ConvoKitTheme, ConvoKitThemeProvider, type ConvoKitThemeProviderProps, type ConvoKitUiClient, type ConvoKitUiDensity, type ConvoKitUiPart, type ErrorRenderProps, type ErrorRenderer, type MediaRenderProps, MessageListView, type MessageListViewProps, type MessageRenderProps, type ReadReceiptRenderProps, type ScrollOptions, type StateRenderer, type TypingRenderProps, type UseConversationListOptions, type UseConversationOptions, applyConversationFilter, createConvoKitUiClient, defaultConvoKitTheme, defaultReadersResolver, formatFileSize, matchesConversation, mergeConversations, mergeMessages, readerIdsFor, useConversation, useConversationList, useConvoKitTheme };

package/dist/index.d.ts

@@ -0,0 +1,316 @@
+import { Message, Conversation as Conversation$1, MessageMedia, RealtimeSubscription, ReadEvent, TypingEvent, ConvoKitClient } from '@convokitapp/sdk';
+import * as react from 'react';
+import { CSSProperties, HTMLAttributes, ReactNode, RefObject, TextareaHTMLAttributes, PropsWithChildren } from 'react';
+
+interface ConvoKitUiClient {
+    readonly currentUserId: string;
+    getConversations(options: {
+        limit: number;
+        offset: number;
+        archived: boolean;
+    }): Promise<Conversation$1[]>;
+    getConversation(conversationId: string): Promise<Conversation$1>;
+    getMessages(options: {
+        conversationId: string;
+        limit: number;
+        offset: number;
+    }): Promise<Message[]>;
+    sendMessage(input: {
+        conversationId: string;
+        text?: string;
+        media?: MessageMedia[];
+    }): Promise<Message>;
+    markConversationRead(conversationId: string): Promise<void>;
+    sendTyping(input: {
+        conversationId: string;
+        isTyping: boolean;
+    }): Promise<void>;
+    onMessage(conversationId: string, handler: (message: Message) => void, onError?: (error: Error) => void): RealtimeSubscription;
+    onReadReceipt(conversationId: string, handler: (event: ReadEvent) => void, onError?: (error: Error) => void): RealtimeSubscription;
+    onTyping(conversationId: string, handler: (event: TypingEvent) => void, onError?: (error: Error) => void): RealtimeSubscription;
+}
+interface ConversationFilter {
+    query?: string;
+    archived?: boolean;
+    participantIds?: ReadonlySet<string> | readonly string[];
+    requireAllParticipants?: boolean;
+    predicate?: (conversation: Conversation$1) => boolean;
+    comparator?: (left: Conversation$1, right: Conversation$1) => number;
+}
+interface ConversationPageRequest {
+    limit: number;
+    offset: number;
+    filter: ConversationFilter;
+}
+type ConversationPageLoader = (request: ConversationPageRequest) => Promise<Conversation$1[]>;
+interface ConversationListState {
+    conversations: Conversation$1[];
+    filter: ConversationFilter;
+    isInitialLoading: boolean;
+    isLoadingMore: boolean;
+    hasMore: boolean;
+    hasLoaded: boolean;
+    error: unknown;
+}
+interface ConversationState {
+    conversation: Conversation$1 | null;
+    messages: Message[];
+    typingUserIds: ReadonlySet<string>;
+    readAtByUserId: ReadonlyMap<string, Date>;
+    isInitialLoading: boolean;
+    isLoadingOlder: boolean;
+    isSending: boolean;
+    hasOlderMessages: boolean;
+    hasLoaded: boolean;
+    error: unknown;
+    currentUserId: string;
+    readerIdsFor(message: Message): ReadonlySet<string>;
+}
+type ConvoKitUiDensity = 'comfortable' | 'compact';
+type ConvoKitUiPart = 'root' | 'list' | 'listItem' | 'avatar' | 'header' | 'messages' | 'message' | 'incomingMessage' | 'outgoingMessage' | 'media' | 'receipt' | 'typing' | 'composer' | 'input' | 'button' | 'empty' | 'loading' | 'error';
+interface ConvoKitAppearanceProps {
+    classNames?: Partial<Record<ConvoKitUiPart, string>>;
+    styles?: Partial<Record<ConvoKitUiPart, CSSProperties>>;
+    density?: ConvoKitUiDensity;
+    unstyled?: boolean;
+}
+interface ConversationItemRenderProps {
+    conversation: Conversation$1;
+    index: number;
+    selected: boolean;
+    onSelect: () => void;
+}
+interface MessageRenderProps {
+    message: Message;
+    chronologicalIndex: number;
+    isCurrentUser: boolean;
+    sender: Conversation$1['participants'][number] | undefined;
+    readerIds: ReadonlySet<string>;
+}
+interface MediaRenderProps {
+    media: MessageMedia;
+    message: Message;
+    isCurrentUser: boolean;
+    onOpen?: () => void;
+}
+interface ComposerRenderProps {
+    value: string;
+    setValue: (value: string) => void;
+    isSending: boolean;
+    send: () => void;
+    addAttachment?: () => void;
+}
+interface TypingRenderProps {
+    userIds: ReadonlySet<string>;
+    displayNameForUser: (userId: string) => string;
+}
+interface ReadReceiptRenderProps {
+    message: Message;
+    readerIds: ReadonlySet<string>;
+}
+interface ErrorRenderProps {
+    error: unknown;
+    retry?: () => void;
+}
+interface BaseViewProps extends ConvoKitAppearanceProps, Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'style'> {
+    style?: CSSProperties;
+}
+interface ScrollOptions {
+    scrollRef?: RefObject<HTMLDivElement | null>;
+    paginationThreshold?: number;
+}
+type StateRenderer = () => ReactNode;
+type ErrorRenderer = (props: ErrorRenderProps) => ReactNode;
+
+/** Adapts a connected `@convokitapp/sdk` client to the replaceable UI boundary. */
+declare function createConvoKitUiClient(client: ConvoKitClient): ConvoKitUiClient;
+
+interface ConvoKitAvatarProps extends HTMLAttributes<HTMLSpanElement> {
+    name: string;
+    src?: string | null;
+}
+/** Accessible avatar built on Radix Avatar. */
+declare function ConvoKitAvatar({ name, src, className, ...props }: ConvoKitAvatarProps): react.JSX.Element;
+
+interface UseConversationOptions {
+    client: ConvoKitUiClient;
+    conversationId: string;
+    messagePageSize?: number;
+    markReadOnLoad?: boolean;
+    markReadOnReceive?: boolean;
+    typingTimeoutMs?: number;
+    autoLoad?: boolean;
+}
+interface ConversationController extends ConversationState {
+    loadInitial(): Promise<void>;
+    refresh(): Promise<void>;
+    loadOlderMessages(): Promise<void>;
+    sendMessage(input: {
+        text?: string;
+        media?: MessageMedia[];
+    }): Promise<Message | null>;
+    markRead(): Promise<void>;
+    updateTyping(isTyping: boolean): Promise<void>;
+}
+/** Owns one conversation's history, realtime state, sending, and read positions. */
+declare function useConversation({ client, conversationId, messagePageSize, markReadOnLoad, markReadOnReceive, typingTimeoutMs, autoLoad, }: UseConversationOptions): ConversationController;
+
+interface MessageListViewProps extends BaseViewProps, ScrollOptions {
+    conversation: Conversation$1;
+    messages: readonly Message[];
+    currentUserId: string;
+    readAtByUserId?: ReadonlyMap<string, Date>;
+    readersResolver?: (message: Message) => ReadonlySet<string>;
+    onLoadOlder?: () => void | Promise<void>;
+    hasOlderMessages?: boolean;
+    isLoadingOlder?: boolean;
+    error?: unknown;
+    renderMessage?: (props: MessageRenderProps) => ReactNode;
+    renderMedia?: (props: MediaRenderProps) => ReactNode;
+    renderReadReceipt?: (props: ReadReceiptRenderProps) => ReactNode;
+    onAttachmentClick?: (media: MessageMedia, message: Message) => void;
+    renderEmpty?: StateRenderer;
+    renderLoadingOlder?: StateRenderer;
+    renderError?: ErrorRenderer;
+    reverse?: boolean;
+    stickToBottom?: boolean;
+    formatTime?: (date: Date) => string;
+    imageLoading?: 'eager' | 'lazy';
+}
+/** Controlled message history with read receipts, structured media, and older-page loading. */
+declare function MessageListView({ conversation, messages, currentUserId, readAtByUserId, readersResolver, onLoadOlder, hasOlderMessages, isLoadingOlder, error, renderMessage, renderMedia, renderReadReceipt, onAttachmentClick, renderEmpty, renderLoadingOlder, renderError, scrollRef, paginationThreshold, reverse, stickToBottom, formatTime, imageLoading, className, style, classNames, styles, density, unstyled, onScroll, ...rootProps }: MessageListViewProps): react.JSX.Element;
+
+interface ConversationViewProps extends BaseViewProps {
+    conversation: Conversation$1;
+    messages: readonly Message[];
+    currentUserId: string;
+    onSendMessage: (text: string) => boolean | void | Promise<boolean | void>;
+    typingUserIds?: ReadonlySet<string>;
+    readAtByUserId?: ReadonlyMap<string, Date>;
+    readersResolver?: (message: Message) => ReadonlySet<string>;
+    onBack?: () => void;
+    onRefresh?: () => void | Promise<void>;
+    onLoadOlder?: () => void | Promise<void>;
+    onTypingChange?: (isTyping: boolean) => void | Promise<void>;
+    onAddAttachment?: () => void;
+    onAttachmentClick?: (media: MessageMedia, message: Message) => void;
+    isInitialLoading?: boolean;
+    isLoadingOlder?: boolean;
+    isSending?: boolean;
+    hasOlderMessages?: boolean;
+    error?: unknown;
+    messageError?: unknown;
+    renderHeader?: (props: {
+        conversation: Conversation$1;
+        onBack?: () => void;
+        onRefresh?: () => void | Promise<void>;
+    }) => ReactNode;
+    renderMessage?: (props: MessageRenderProps) => ReactNode;
+    renderMedia?: (props: MediaRenderProps) => ReactNode;
+    renderReadReceipt?: (props: ReadReceiptRenderProps) => ReactNode;
+    renderComposer?: (props: ComposerRenderProps) => ReactNode;
+    renderTypingIndicator?: (props: TypingRenderProps) => ReactNode;
+    renderEmpty?: StateRenderer;
+    renderLoading?: StateRenderer;
+    renderError?: ErrorRenderer;
+    renderLoadingOlder?: StateRenderer;
+    renderMessageError?: ErrorRenderer;
+    displayNameForUser?: (userId: string) => string | null | undefined;
+    reverseMessages?: boolean;
+    stickToBottom?: boolean;
+    paginationThreshold?: number;
+    formatTime?: MessageListViewProps['formatTime'];
+    imageLoading?: MessageListViewProps['imageLoading'];
+    composerPlaceholder?: string;
+    composerAriaLabel?: string;
+    composerProps?: Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'value' | 'defaultValue' | 'onChange' | 'disabled'>;
+    draft?: string;
+    defaultDraft?: string;
+    onDraftChange?: (value: string) => void;
+}
+/** Controlled, complete selected-conversation surface. */
+declare function ConversationView({ conversation, messages, currentUserId, onSendMessage, typingUserIds, readAtByUserId, readersResolver, onBack, onRefresh, onLoadOlder, onTypingChange, onAddAttachment, onAttachmentClick, isInitialLoading, isLoadingOlder, isSending, hasOlderMessages, error, messageError, renderHeader, renderMessage, renderMedia, renderReadReceipt, renderComposer, renderTypingIndicator, renderEmpty, renderLoading, renderError, renderLoadingOlder, renderMessageError, displayNameForUser, reverseMessages, stickToBottom, paginationThreshold, formatTime, imageLoading, composerPlaceholder, composerAriaLabel, composerProps, draft: controlledDraft, defaultDraft, onDraftChange, className, classNames, styles, density, unstyled, ...rootProps }: ConversationViewProps): react.JSX.Element;
+interface ConversationProps extends Omit<ConversationViewProps, 'conversation' | 'messages' | 'currentUserId' | 'onSendMessage' | 'typingUserIds' | 'readAtByUserId' | 'onRefresh' | 'onLoadOlder' | 'onTypingChange' | 'isInitialLoading' | 'isLoadingOlder' | 'isSending' | 'hasOlderMessages' | 'error'>, UseConversationOptions {
+    renderLoading?: StateRenderer;
+    onControllerChange?: (controller: ConversationController) => void;
+}
+/** Plug-and-play SDK-backed UI for one conversation. */
+declare function Conversation({ client, conversationId, messagePageSize, markReadOnLoad, markReadOnReceive, typingTimeoutMs, autoLoad, renderLoading, onControllerChange, ...viewProps }: ConversationProps): react.JSX.Element;
+declare function defaultReadersResolver(readAtByUserId: ReadonlyMap<string, Date>): (message: Message) => ReadonlySet<string>;
+
+interface UseConversationListOptions {
+    client: ConvoKitUiClient;
+    pageLoader?: ConversationPageLoader;
+    initialFilter?: ConversationFilter;
+    pageSize?: number;
+    autoLoad?: boolean;
+}
+interface ConversationListController extends ConversationListState {
+    loadInitial(): Promise<void>;
+    refresh(): Promise<void>;
+    loadMore(): Promise<void>;
+    setFilter(filter: ConversationFilter): Promise<void>;
+    setQuery(query: string): Promise<void>;
+}
+/** Loads, de-duplicates, filters, and paginates conversations. */
+declare function useConversationList({ client, pageLoader, initialFilter, pageSize, autoLoad, }: UseConversationListOptions): ConversationListController;
+
+interface ConversationListViewProps extends BaseViewProps, ScrollOptions {
+    conversations: readonly Conversation$1[];
+    onConversationSelect: (conversation: Conversation$1) => void;
+    selectedConversationId?: string;
+    onRefresh?: () => void | Promise<void>;
+    onLoadMore?: () => void | Promise<void>;
+    isInitialLoading?: boolean;
+    isLoadingMore?: boolean;
+    hasMore?: boolean;
+    error?: unknown;
+    renderConversationItem?: (props: ConversationItemRenderProps) => ReactNode;
+    renderSeparator?: (index: number) => ReactNode;
+    renderEmpty?: StateRenderer;
+    renderInitialLoading?: StateRenderer;
+    renderError?: ErrorRenderer;
+    renderLoadMore?: StateRenderer;
+    ariaLabel?: string;
+}
+/** Controlled conversation list. It can be used with any state-management layer. */
+declare function ConversationListView({ conversations, onConversationSelect, selectedConversationId, onRefresh, onLoadMore, isInitialLoading, isLoadingMore, hasMore, error, renderConversationItem, renderSeparator, renderEmpty, renderInitialLoading, renderError, renderLoadMore, scrollRef, paginationThreshold, ariaLabel, className, style, classNames, styles, density, unstyled, onScroll, ...rootProps }: ConversationListViewProps): react.JSX.Element;
+interface ConversationListProps extends Omit<ConversationListViewProps, 'conversations' | 'onRefresh' | 'onLoadMore' | 'isInitialLoading' | 'isLoadingMore' | 'hasMore' | 'error'>, UseConversationListOptions {
+    onControllerChange?: (controller: ConversationListController) => void;
+}
+/** Plug-and-play SDK-backed conversation list. */
+declare function ConversationList({ client, pageLoader, initialFilter, pageSize, autoLoad, onControllerChange, ...viewProps }: ConversationListProps): react.JSX.Element;
+
+interface ConvoKitTheme {
+    background: string;
+    surface: string;
+    primary: string;
+    text: string;
+    mutedText: string;
+    border: string;
+    error: string;
+    incomingBubble: string;
+    outgoingBubble: string;
+    outgoingText: string;
+    radius: string;
+    avatarSize: string;
+    fontFamily: string;
+}
+declare const defaultConvoKitTheme: ConvoKitTheme;
+interface ConvoKitThemeProviderProps extends PropsWithChildren {
+    theme?: Partial<ConvoKitTheme>;
+    className?: string;
+    style?: CSSProperties;
+}
+/** Supplies theme tokens as CSS variables. Nest providers to override a subtree. */
+declare function ConvoKitThemeProvider({ children, theme, className, style, }: ConvoKitThemeProviderProps): react.JSX.Element;
+declare function useConvoKitTheme(): ConvoKitTheme;
+
+declare function matchesConversation(conversation: Conversation$1, filter: ConversationFilter): boolean;
+declare function applyConversationFilter(conversations: readonly Conversation$1[], filter: ConversationFilter): Conversation$1[];
+declare function mergeConversations(current: readonly Conversation$1[], incoming: readonly Conversation$1[]): Conversation$1[];
+declare function mergeMessages(current: readonly Message[], incoming: readonly Message[]): Message[];
+declare function readerIdsFor(message: Message, readAtByUserId: ReadonlyMap<string, Date>): ReadonlySet<string>;
+declare function formatFileSize(size: number | undefined): string | null;
+
+export { type BaseViewProps, type ComposerRenderProps, Conversation, type ConversationController, type ConversationFilter, type ConversationItemRenderProps, ConversationList, type ConversationListController, type ConversationListProps, type ConversationListState, ConversationListView, type ConversationListViewProps, type ConversationPageLoader, type ConversationPageRequest, type ConversationProps, type ConversationState, ConversationView, type ConversationViewProps, type ConvoKitAppearanceProps, ConvoKitAvatar, type ConvoKitAvatarProps, type ConvoKitTheme, ConvoKitThemeProvider, type ConvoKitThemeProviderProps, type ConvoKitUiClient, type ConvoKitUiDensity, type ConvoKitUiPart, type ErrorRenderProps, type ErrorRenderer, type MediaRenderProps, MessageListView, type MessageListViewProps, type MessageRenderProps, type ReadReceiptRenderProps, type ScrollOptions, type StateRenderer, type TypingRenderProps, type UseConversationListOptions, type UseConversationOptions, applyConversationFilter, createConvoKitUiClient, defaultConvoKitTheme, defaultReadersResolver, formatFileSize, matchesConversation, mergeConversations, mergeMessages, readerIdsFor, useConversation, useConversationList, useConvoKitTheme };