@poolse/react-native 0.1.1 → 2.0.5

package/dist/index.d.ts

@@ -1,7 +1,80 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
-import { Uuid, Message, AttachmentUploadInput, Conversation, Membership, Attachment } from '@poolse/sdk';
 import * as react from 'react';
-import { ReactElement, ReactNode } from 'react';
+import { ReactNode, ReactElement } from 'react';
+import { Conversation, Uuid, Message, AttachmentUploadInput, Membership, Attachment } from '@poolse/sdk';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+interface InboxUser {
+    /** The user's external_id (the same id you mint JWTs with). */
+    externalId: string;
+    /** Display name shown in the picker row. */
+    name: string;
+    /** Optional avatar URL — falls back to initials if missing. */
+    avatarUrl?: string | null;
+    /** Optional secondary line (email, role, handle…). */
+    subtitle?: string;
+}
+
+interface PoolseInboxProps {
+    /** Header title above the conversation list. Defaults to "Chats". */
+    title?: string;
+    /**
+     * The tenant's user directory. When provided, the inbox shows
+     * "New chat" + "New group" buttons in the header. Omit if you
+     * don't want the built-in picker UI (e.g. you start chats from
+     * elsewhere via the imperative `openDirect()` API).
+     */
+    users?: InboxUser[];
+    /** Display-name resolver for sender labels / chat header titles. */
+    labelFor?: (externalId: string) => string;
+    /** Avatar URL resolver. */
+    avatarFor?: (externalId: string) => string | null;
+    /**
+     * Right-side slot in the header — typical use is a logout / settings
+     * button. Rendered after the New-chat / New-group buttons.
+     */
+    renderRightAction?: () => ReactNode;
+    /**
+     * Custom row renderer for the conversation list. Receives the
+     * conversation + the caller's external_id (resolved via `useMe`)
+     * so you can branch on direct-vs-group display.
+     */
+    renderConversationRow?: (conv: Conversation, callerExternalId: string | null, selected: boolean) => ReactNode;
+    /** Custom empty state when the list is empty. */
+    emptyState?: ReactNode | string;
+    /** Forwarded to `<ConversationView>` — set if you have a nav header above. */
+    keyboardOffset?: number;
+}
+interface PoolseInboxHandle {
+    /** Open a known conversation (e.g. from a deep link / push tap). */
+    open: (conversationId: Uuid) => void;
+    /**
+     * Open (or create) a direct conversation with the given external_id.
+     * The backend dedupes per pair — returns the existing conversation
+     * if one already exists. Use this from a "Message" button on your
+     * user profile screens.
+     */
+    openDirect: (externalId: string) => Promise<void>;
+    /** Open (or create) a group conversation. */
+    openGroup: (name: string, memberExternalIds: string[]) => Promise<void>;
+    /** Open the built-in "new chat" picker programmatically. */
+    promptNewChat: () => void;
+    /** Open the built-in "new group" picker programmatically. */
+    promptNewGroup: () => void;
+    /** Pop back to the conversation list. */
+    close: () => void;
+}
+/**
+ * Drop-in inbox screen: scrollable list of conversations + chat
+ * detail, with an iOS-style slide animation between them. Manages
+ * its own navigation stack (no react-navigation needed). Picker
+ * sheets for "New chat" / "New group" appear when `users` is
+ * provided; otherwise the dev wires those flows themselves and
+ * uses the imperative ref to open conversations.
+ *
+ * For the "Message" button on a user profile screen, hold a ref to
+ * the inbox and call `inboxRef.current?.openDirect(externalId)`.
+ */
+declare const PoolseInbox: react.ForwardRefExoticComponent<PoolseInboxProps & react.RefAttributes<PoolseInboxHandle>>;
 
 interface ConversationViewProps {
     conversationId: Uuid;
@@ -9,6 +82,17 @@ interface ConversationViewProps {
     renderMessage?: (msg: Message, currentUserId: string | null) => ReactElement;
     labelFor?: (externalId: string) => string;
     avatarFor?: (externalId: string) => string | null;
+    /**
+     * Renders the default `<ChatHeader>` at the top of the chat surface.
+     *   * `true` (default)  — auto chat header (other user / group name).
+     *   * `false`           — no header (you supply your own above).
+     *   * `ReactElement`    — custom header node, rendered as-is.
+     */
+    header?: boolean | ReactElement;
+    /** Tap on the header's members icon — typically opens a sheet. */
+    onHeaderMembersPress?: () => void;
+    /** Tap on the header itself — typically opens a conversation profile. */
+    onHeaderPress?: () => void;
     reactions?: boolean;
     mentions?: boolean;
     attachments?: boolean;
@@ -21,10 +105,101 @@ interface ConversationViewProps {
     senderLabels?: 'auto' | 'always' | 'never';
     /** Show avatars to the left of other-side bubbles in group chats. Same semantics. */
     avatars?: 'auto' | 'always' | 'never';
-    /** Fires when auto-mark-read commits — clear sidebar badges via this. */
-    onMarkedRead?: (conversationId: string) => void;
+    /**
+     * Fires when auto-mark-read commits a new server-side read cursor.
+     * Receives the conversation id + the message id that was marked
+     * as the last-read. Wire this to `useConversations().markConversationRead(convId, msgId)`
+     * so the sidebar / list view's unread badge clears immediately
+     * instead of waiting for the next conversations refetch.
+     */
+    onMarkedRead?: (conversationId: string, messageId: string) => void;
+    /**
+     * Fires after every successful message send. Wire to the parent's
+     * `useConversations().refetch()` so the conversation list shows
+     * the fresh `last_message_preview` / `last_message_at` for the
+     * conversation you just sent into. `useConversations` creates
+     * isolated state per call site, so ConversationView can't refresh
+     * a parent hook's state on its own.
+     */
+    onSent?: (conversationId: string) => void;
+    /**
+     * keyboardVerticalOffset passed to the internal KeyboardAvoidingView.
+     * On iOS this MUST equal the distance from the screen top to the
+     * KAV's top (status bar + safe-area-top + any nav header above
+     * the chat). `<PoolseInbox>` computes this for you. Standalone
+     * consumers pass it manually.
+     */
+    keyboardOffset?: number;
+}
+declare function ConversationView({ conversationId, emptyState, renderMessage, labelFor, avatarFor, header, onHeaderMembersPress, onHeaderPress, reactions, mentions, attachments, actions, threads, quotations, readReceipts, maxBodyLength, senderLabels, avatars, onMarkedRead, onSent, keyboardOffset, }: ConversationViewProps): react_jsx_runtime.JSX.Element;
+
+interface ChatHeaderProps {
+    conversationId: Uuid;
+    /**
+     * Override the title resolver — useful when you want to derive the
+     * direct-chat name from your own user directory instead of going
+     * through the SDK's `userResolver`. When omitted, falls back to:
+     *   * direct → the other member's display name (via `useUser`)
+     *   * group  → `conversation.name`
+     */
+    labelFor?: (externalId: string) => string;
+    /** Optional avatar URL resolver for the other party (direct only). */
+    avatarFor?: (externalId: string) => string | null;
+    /** Right-side icon button — typically opens a member-list sheet. */
+    onMembersPress?: () => void;
+    /**
+     * Tap handler for the whole header. Behavior:
+     *   * Direct chat → calls this if provided, otherwise no-op.
+     *   * Group chat  → calls this if provided. If omitted, the header
+     *     opens a built-in group-details sheet showing the member
+     *     roster with live presence.
+     */
+    onPress?: () => void;
+    /**
+     * When provided, renders a back arrow on the LEFT of the header
+     * that calls this handler on tap. Used by `<PoolseInbox>` to
+     * navigate back to the conversation list; safe to wire from your
+     * own navigator too.
+     */
+    onBack?: () => void;
+}
+/**
+ * Top-of-chat header bar.
+ *   * 1:1 direct  → other user's display name + avatar + presence dot.
+ *   * Group       → conversation name + "N members" + group-tile avatar.
+ *
+ * Sits above `<MessageList>` inside `<ConversationView>` by default;
+ * pass `header={false}` to `<ConversationView>` if you mount your own.
+ */
+declare function ChatHeader({ conversationId, labelFor, avatarFor, onMembersPress, onPress, onBack, }: ChatHeaderProps): react_jsx_runtime.JSX.Element;
+
+interface GroupDetailsSheetProps {
+    visible: boolean;
+    onClose: () => void;
+    conversationId: Uuid;
+    /** Resolve external_id → display name. Same shape as MemberList. */
+    labelFor?: (externalId: string) => string;
+    /** Resolve external_id → avatar URL. Same shape as MemberList. */
+    avatarFor?: (externalId: string) => string | null;
+    /**
+     * Predicate for the per-row remove button. Defaults to "never show"
+     * — wire it on the parent for owners/admins. Receives the
+     * Membership row so you can scope to roles or exclude self.
+     */
+    canRemoveMember?: (m: {
+        user_id: string;
+        external_id: string;
+        role: string;
+    }) => boolean;
 }
-declare function ConversationView({ conversationId, emptyState, renderMessage, labelFor, avatarFor, reactions, mentions, attachments, actions, threads, quotations, readReceipts, maxBodyLength, senderLabels, avatars, onMarkedRead, }: ConversationViewProps): react_jsx_runtime.JSX.Element;
+/**
+ * Bottom-sheet (85% of screen) that opens when the user taps the
+ * group chat header. Shows group name + member count at the top,
+ * then a scrollable roster with avatars, display names (resolved
+ * through `labelFor` / `userResolver`), role badges, and live
+ * presence dots (driven by `MemberList` internally).
+ */
+declare function GroupDetailsSheet({ visible, onClose, conversationId, labelFor, avatarFor, canRemoveMember, }: GroupDetailsSheetProps): react_jsx_runtime.JSX.Element;
 
 type BubbleGroupPosition = 'first' | 'middle' | 'last' | 'standalone';
 interface MessageBubbleProps {
@@ -114,6 +289,15 @@ interface MessageComposerProps {
     attachments?: boolean;
     /** Tap on the paperclip — wire to `<AttachmentPicker>` from the same package. */
     onAttachPress?: () => void;
+    /**
+     * Distance from the top of the screen to the top of the
+     * KeyboardAvoidingView — typically the height of any navigation
+     * header sitting above the chat. Pass this when the iOS keyboard
+     * suggestions strip ends up covering the composer (a sign the
+     * computed offset is wrong). Defaults to 0; on Android it's
+     * ignored.
+     */
+    keyboardOffset?: number;
 }
 /**
  * Imperative handle for parents that want to add files to the
@@ -132,19 +316,27 @@ interface MessageActionsProps {
     visible: boolean;
     onClose: () => void;
     isSelf: boolean;
+    /**
+     * Quick-reaction emoji row rendered at the top of the sheet. Tap
+     * one to fire `onPickReaction(emoji)` and immediately close. When
+     * omitted (or `onPickReaction` is omitted) the row is hidden.
+     */
+    emojis?: string[];
+    onPickReaction?: (emoji: string) => void;
     onReply?: () => void;
     onReplyInThread?: () => void;
     onQuote?: () => void;
     onEdit?: () => void;
     onDelete?: () => void;
     onCopy?: () => void;
-    onReact?: () => void;
 }
 /**
- * Long-press action menu — rendered as a modal bottom sheet (RN's
- * native equivalent of the web hover popover).
+ * Long-press action menu — modal bottom sheet. Renders a row of
+ * quick-react emojis at the top (one tap reacts + closes) plus the
+ * action items below. Matches WhatsApp / iMessage's "long-press
+ * shows everything inline" pattern.
  */
-declare function MessageActions({ visible, onClose, isSelf, onReply, onReplyInThread, onQuote, onEdit, onDelete, onCopy, onReact, }: MessageActionsProps): react_jsx_runtime.JSX.Element;
+declare function MessageActions({ visible, onClose, isSelf, emojis, onPickReaction, onReply, onReplyInThread, onQuote, onEdit, onDelete, onCopy, }: MessageActionsProps): react_jsx_runtime.JSX.Element;
 
 interface MessageListProps {
     messages: Message[];
@@ -191,13 +383,21 @@ interface ThreadViewProps {
     conversationId: Uuid;
     rootMessage: Message;
     labelFor?: (externalId: string) => string;
+    avatarFor?: (externalId: string) => string | null;
 }
 /**
- * Modal screen for thread replies. Mirrors the web `<ThreadView>` —
- * root message preview at the top, oldest-first reply list, composer
- * at the bottom.
+ * Bottom-sheet modal for thread replies. Pull the drag handle / header
+ * down to dismiss; tap the backdrop or close button too. The composer
+ * inside the sheet supports attachments (paperclip → picker, shared
+ * upload queue) and the reply rows support reactions, swipe-to-reply,
+ * long-press actions, edit, delete — same surface as ConversationView.
+ *
+ * Keyboard handling: inside a Modal the OS doesn't auto-resize the
+ * sheet's children, so the composer needs its own KeyboardAvoidingView
+ * with `keyboardVerticalOffset` set to the distance between the screen
+ * top and the sheet top (the gutter above the sheet).
  */
-declare function ThreadView({ visible, onClose, conversationId, rootMessage, labelFor, }: ThreadViewProps): react_jsx_runtime.JSX.Element;
+declare function ThreadView({ visible, onClose, conversationId, rootMessage, labelFor, avatarFor, }: ThreadViewProps): react_jsx_runtime.JSX.Element;
 
 interface UserNameProps {
     /** The user's external_id. Pass null to render the fallback. */
@@ -257,9 +457,15 @@ interface AttachmentPreviewProps {
 declare function AttachmentPreview({ attachment, onPress, maxWidth }: AttachmentPreviewProps): react_jsx_runtime.JSX.Element;
 
 /**
- * Horizontal strip of in-flight upload chips with cancel + remove
- * affordances. Reads from `useAttachmentUpload()` so it auto-clears
- * when the composer resets the queue post-send.
+ * Horizontal scrolling preview row of pending / in-flight / ready
+ * uploads. Image attachments render as 64×64 thumbnails sourced from
+ * the original local file URI; file attachments render as a row card
+ * with icon + name + size. A small × overlay on each tile lets the
+ * user drop the upload before send.
+ *
+ * Reads queue state from the shared `<UploadProvider>` (mounted by
+ * `<ConversationView>`), so the composer's "ready attachment ids"
+ * pickup and the strip's display always agree.
  */
 declare function UploadQueueStrip(): react_jsx_runtime.JSX.Element | null;
 
@@ -301,17 +507,16 @@ interface AttachmentPickerProps {
     visible: boolean;
     onClose: () => void;
     /**
-     * Optional adapter that produces an `AttachmentUploadInput` from a
-     * picked RN file. Default reads `uri`/`name`/`type`/`size` and wraps
-     * in a fetch-compatible `Blob`. Override to plug in custom storage
-     * or transcoding.
+     * Optional adapter that produces upload inputs from a picked file.
+     * Override to plug in custom storage / transcoding. Default reads
+     * from `expo-image-picker` / `expo-document-picker`.
      */
     onPickInputs?: (kind: 'image' | 'document') => Promise<{
-        body: Blob | {
+        body: {
             uri: string;
             name: string;
             type: string;
-        } | unknown;
+        } | Blob | unknown;
         contentType: string;
         byteSize: number;
         filename?: string;
@@ -319,16 +524,39 @@ interface AttachmentPickerProps {
 }
 /**
  * Picker sheet wrapping `expo-image-picker` and `expo-document-picker`.
- * Both are OPTIONAL peer dependencies — install only the ones you
- * actually use. If a picker is mounted without its dep installed,
- * the corresponding button is disabled with a tooltip explaining
- * which install command to run.
- *
- * Default implementation dynamically `import()`s the Expo modules
- * at mount; the caller can pass `onPickInputs` to skip Expo entirely.
+ * Both must be installed (`npx expo install expo-image-picker
+ * expo-document-picker`) when this component is mounted — they're
+ * declared as optional peers because consumers who pass
+ * `attachments={false}` to ConversationView never render this file.
  */
 declare function AttachmentPicker({ visible, onClose, onPickInputs }: AttachmentPickerProps): react_jsx_runtime.JSX.Element;
 
+interface ImageMosaicProps {
+    images: Attachment[];
+    /**
+     * Pixel ceiling on the mosaic's width. The mosaic itself fills its
+     * parent (`width: '100%'`) and caps at this value, so it always
+     * fits inside whatever the bubble's actual content area is at
+     * render time — no more hardcoded 280px overflowing on small
+     * screens or inside narrow bubbles.
+     */
+    maxWidth?: number;
+    radius?: number;
+}
+/**
+ * WhatsApp-style multi-image grid for inside the message bubble.
+ * Uses flex-based widths (with `%` and `aspectRatio`) so the layout
+ * scales to whatever the bubble's content area is — no fixed pixel
+ * positioning that can overflow when the bubble is narrower than
+ * the configured max.
+ *
+ *   * n = 1 → single tile, 16:10 aspect.
+ *   * n = 2 → row of 2 squares.
+ *   * n = 3 → 16:9 hero on top + row of 2 squares below.
+ *   * n ≥ 4 → 2×2 grid with "+N more" overlay on the 4th tile.
+ */
+declare function ImageMosaic({ images, maxWidth, radius }: ImageMosaicProps): react_jsx_runtime.JSX.Element | null;
+
 declare const ICONS: {
     readonly attachment: {
         readonly vb: "0 0 24 24";
@@ -669,4 +897,4 @@ declare const defaultDarkTheme: PoolseRNTheme;
  */
 declare function useAppStateLifecycle(): void;
 
-export { AttachmentPicker, type AttachmentPickerProps, AttachmentPreview, type AttachmentPreviewProps, Avatar, type AvatarProps, ConversationList, type ConversationListProps, ConversationView, type ConversationViewProps, EditableMessageBubble, type EditableMessageBubbleProps, type IconName, MemberList, type MemberListProps, MentionInput, type MentionInputProps, MessageActions, type MessageActionsProps, MessageBubble, type MessageBubbleProps, MessageComposer, type MessageComposerProps, MessageList, type MessageListProps, MessageRow, type MessageRowProps, PoolseIcon, type PoolseIconProps, PoolseLogo, type PoolseLogoProps, type PoolseLogoVariant, type PoolseRNTheme, type PoolseRNThemeOverrides, PoolseTheme, type PoolseThemeProps, primitives as Primitives, ReactionPicker, type ReactionPickerProps, ReactionStrip, type ReactionStripProps, type ThemeColors, type ThemeRadii, type ThemeShadows, type ThemeSpacing, type ThemeType, ThreadView, type ThreadViewProps, TypingIndicator, type TypingIndicatorProps, UploadQueueStrip, UserName, type UserNameProps, defaultDarkTheme, defaultLightTheme, useAppStateLifecycle, useDisplayName, usePoolseTheme };
+export { AttachmentPicker, type AttachmentPickerProps, AttachmentPreview, type AttachmentPreviewProps, Avatar, type AvatarProps, ChatHeader, type ChatHeaderProps, ConversationList, type ConversationListProps, ConversationView, type ConversationViewProps, EditableMessageBubble, type EditableMessageBubbleProps, GroupDetailsSheet, type GroupDetailsSheetProps, type IconName, ImageMosaic, type ImageMosaicProps, type InboxUser, MemberList, type MemberListProps, MentionInput, type MentionInputProps, MessageActions, type MessageActionsProps, MessageBubble, type MessageBubbleProps, MessageComposer, type MessageComposerProps, MessageList, type MessageListProps, MessageRow, type MessageRowProps, PoolseIcon, type PoolseIconProps, PoolseInbox, type PoolseInboxHandle, type PoolseInboxProps, PoolseLogo, type PoolseLogoProps, type PoolseLogoVariant, type PoolseRNTheme, type PoolseRNThemeOverrides, PoolseTheme, type PoolseThemeProps, primitives as Primitives, ReactionPicker, type ReactionPickerProps, ReactionStrip, type ReactionStripProps, type ThemeColors, type ThemeRadii, type ThemeShadows, type ThemeSpacing, type ThemeType, ThreadView, type ThreadViewProps, TypingIndicator, type TypingIndicatorProps, UploadQueueStrip, UserName, type UserNameProps, defaultDarkTheme, defaultLightTheme, useAppStateLifecycle, useDisplayName, usePoolseTheme };