@factorialco/f0-react 4.40.0 → 4.41.0

package/dist/experimental.d.ts

@@ -3702,6 +3702,8 @@ declare const defaultTranslations: {
         readonly noResults: "No chats found";
         readonly backToLatest: "Jump to latest";
         readonly muted: "Muted";
+        readonly mute: "Mute";
+        readonly unmute: "Unmute";
         readonly attachFile: "Attach file";
         readonly addEmoji: "Add emoji";
         readonly recordAudio: "Record audio";
@@ -3728,6 +3730,13 @@ declare const defaultTranslations: {
         readonly twoTyping: "{{first}} and {{second}} are writing…";
         readonly severalTyping: "Several people are writing…";
         readonly deletedMessage: "Message deleted";
+        readonly location: "Location";
+        readonly voiceNote: "Voice note";
+        readonly sendVoiceNote: "Send voice note";
+        readonly sendingVoiceNote: "Sending voice note…";
+        readonly sending: "Sending…";
+        readonly notSent: "Not sent";
+        readonly retry: "Retry";
         readonly moreActions: "Message actions";
         readonly options: "Options";
         readonly pin: "Pin";
@@ -3766,6 +3775,22 @@ declare const defaultTranslations: {
         };
         readonly scrollToBottom: "Scroll to bottom";
         readonly newMessages: "New messages";
+        readonly system: {
+            readonly memberAdded: {
+                readonly one: "{{members}} was added to the group";
+                readonly other: "{{members}} were added to the group";
+            };
+            readonly memberRemoved: {
+                readonly one: "{{members}} was removed from the group";
+                readonly other: "{{members}} were removed from the group";
+            };
+            readonly memberLeft: {
+                readonly one: "{{members}} left the group";
+                readonly other: "{{members}} left the group";
+            };
+            readonly membersWithLast: "{{names}} and {{last}}";
+            readonly membersWithMore: "{{names}} and {{count}} more";
+        };
         readonly unreadCount: {
             readonly one: "{{count}} unread";
             readonly other: "{{count}} unread";
@@ -5020,7 +5045,32 @@ export declare interface F0CardHorizontalProps {
  */
 export declare const F0Chat: (props: F0ChatProps) => ReactNode;
 
-export declare type F0ChatAttachment = F0ChatImageAttachment | F0ChatFileAttachment;
+export declare type F0ChatAttachment = F0ChatImageAttachment | F0ChatFileAttachment | F0ChatLocationAttachment | F0ChatVoiceAttachment;
+
+/**
+ * Per-channel permissions. Everything is optional and defaults to today's
+ * behavior, so hosts only express what their transport restricts (frozen /
+ * read-only channels, moderation roles…):
+ * - `canSend` (default true): false hides the composer entirely.
+ * - `canReact` (default true): false hides the quick-reaction row, the emoji
+ *   pickers and disables toggling existing reaction pills.
+ * - `canUpload` (default: whether `uploadFiles` exists): false disables the
+ *   attach button, drag & drop and voice notes even when `uploadFiles` exists.
+ * - `canEditMessage` (default: own message within {@link F0ChatRuntime.editWindowMs}):
+ *   overrides the edit policy per message. Structural gates still apply (the
+ *   host must provide `editMessage`; deleted messages and voice notes are
+ *   never editable).
+ * - `canDeleteMessage` (default: own message): overrides the delete policy per
+ *   message (e.g. moderators deleting others' messages). Failed local echoes
+ *   are always discardable — they don't exist server-side.
+ */
+export declare type F0ChatCapabilities = {
+    canSend?: boolean;
+    canReact?: boolean;
+    canUpload?: boolean;
+    canEditMessage?: (message: F0ChatMessage) => boolean;
+    canDeleteMessage?: (message: F0ChatMessage) => boolean;
+};
 
 /** The conversation currently shown in the panel (header + behaviour differs by type). */
 export declare type F0ChatChannel = {
@@ -5082,6 +5132,30 @@ export declare type F0ChatFileAttachment = {
     progress?: number;
 };
 
+/**
+ * A host-provided header action (the only built-in one is Search). Pin/mute,
+ * edit-group, leave… are all expressed through this, so each channel can offer
+ * exactly the actions the current user's PERMISSIONS allow — pass different
+ * arrays per channel (or the function form of `headerActions`), and `[]` for a
+ * channel where the user can do nothing but search.
+ */
+export declare type F0ChatHeaderAction = {
+    id: string;
+    /** Already-localized label. For toggles (mute/unmute) the host rebuilds the
+     * array per render with the current label — labels are plain strings. */
+    label: string;
+    icon?: IconType;
+    /** The host decides what happens: call a runtime method (togglePin,
+     * toggleMute), open its own modal, navigate… */
+    onClick: (channel: F0ChatChannel) => void;
+    /** Where the action renders: inside the ellipsis overflow menu (default) or
+     * as its own icon button next to it. Inline requires `icon` — an inline
+     * action without one falls back to the menu. */
+    placement?: "menu" | "inline";
+    /** Restrict the action to a channel type. Omit for both. */
+    channelTypes?: F0ChatChannelType[];
+};
+
 export declare type F0ChatImageAttachment = {
     kind: "image";
     url: string;
@@ -5092,6 +5166,36 @@ export declare type F0ChatImageAttachment = {
     height?: number;
 };
 
+/** Anything that can appear in the transcript, oldest → newest. */
+export declare type F0ChatItem = F0ChatMessage | F0ChatSystemMessage;
+
+/**
+ * Open Graph preview of a URL in the body (WhatsApp-style card above the text).
+ * The host provides scraped metadata — F0 never fetches the URL itself
+ * (factorial → Stream's URL enrichment attachments, `og_scrape_url`).
+ */
+export declare type F0ChatLinkPreview = {
+    /** The link the card opens (the scraped page). */
+    url: string;
+    title?: string;
+    description?: string;
+    /** Preview image (Open Graph `og:image`). */
+    imageUrl?: string;
+};
+
+/**
+ * A shared (static) location. Rendered as a map preview card that opens the
+ * point in Google Maps; the host maps it to its transport's shape (factorial →
+ * a Stream custom attachment `{ type: "location", latitude, longitude }`).
+ */
+export declare type F0ChatLocationAttachment = {
+    kind: "location";
+    latitude: number;
+    longitude: number;
+    /** Optional place label shown under the map. */
+    name?: string;
+};
+
 /**
  * A person mentioned in a message. `id` matches an {@link F0ChatUser.id}; `name`
  * is the display name as it appears in the body (e.g. "Ana García"), used to
@@ -5110,6 +5214,11 @@ export declare type F0ChatMention = {
 };
 
 export declare type F0ChatMessage = {
+    /**
+     * Discriminant against {@link F0ChatSystemMessage}. Optional — an absent
+     * `type` means "message", so existing literals keep compiling.
+     */
+    type?: "message";
     id: string;
     author: F0ChatUser;
     body: string;
@@ -5117,6 +5226,12 @@ export declare type F0ChatMessage = {
     createdAt: string;
     isMine: boolean;
     status?: F0ChatMessageStatus;
+    /**
+     * Why the send failed (host-provided, human-readable — e.g. "Message too
+     * long"). Shown alongside the failed indicator's tooltip so the user knows
+     * whether a retry can help. Only meaningful with `status: "failed"`.
+     */
+    failureReason?: string;
     /**
      * When the message was read (DM read receipt), ISO. Approximated from the
      * counterpart's per-channel last-read pointer — Stream has no per-message
@@ -5125,6 +5240,13 @@ export declare type F0ChatMessage = {
     readAt?: string;
     reactions?: F0ChatReaction[];
     attachments?: F0ChatAttachment[];
+    /**
+     * Preview cards for the URLs in the body (host-scraped metadata only; when
+     * omitted, links render as plain auto-linked text). A single preview shows a
+     * full card with its image; several stack as compact title/host rows
+     * (Slack-style unfurls).
+     */
+    linkPreviews?: F0ChatLinkPreview[];
     replyTo?: F0ChatMessageReply;
     /**
      * People mentioned in this message (groups only). Drives the `@name` chip
@@ -5166,8 +5288,16 @@ export declare type F0ChatMessageReply = {
     attachments?: F0ChatAttachment[];
 };
 
-/** iMessage-style delivery state — only meaningful for messages I sent. */
-export declare type F0ChatMessageStatus = "sending" | "sent" | "read" | "failed";
+/**
+ * iMessage-style delivery state — only meaningful for messages I sent.
+ * `sending` renders a delayed clock beside the bubble (only if the send takes
+ * >500ms, so healthy networks never flash it); `failed` dims the bubble and
+ * shows a tappable critical alert whose menu is reduced to Retry / Delete.
+ * `delivered` (reached the counterpart's device, not read yet) is for backends
+ * that distinguish it — Stream doesn't, so the factorial adapter never emits it
+ * and those messages go straight from `sent` to `read`.
+ */
+export declare type F0ChatMessageStatus = "sending" | "sent" | "delivered" | "read" | "failed";
 
 export declare type F0ChatProps = {
     /** Whether the hosting panel is in fullscreen (controls the header toggle icon). */
@@ -5176,6 +5306,14 @@ export declare type F0ChatProps = {
     onToggleFullscreen?: () => void;
     /** Close the hosting panel. Hidden when omitted. */
     onClose?: () => void;
+    /**
+     * Host-provided header actions (pin, mute, edit group…). Search is the only
+     * built-in one. The function form receives the current channel so each
+     * channel offers exactly what the user's PERMISSIONS allow — return `[]`
+     * where they can do nothing but search. For toggles (mute/unmute) rebuild
+     * the array per render with the current label/icon.
+     */
+    headerActions?: F0ChatHeaderAction[] | ((channel: F0ChatChannel) => F0ChatHeaderAction[]);
 };
 
 /**
@@ -5203,8 +5341,8 @@ export declare type F0ChatRuntime = {
     currentUserId: string;
     channel: F0ChatChannel;
     status: F0ChatStatus;
-    /** Oldest → newest. */
-    messages: F0ChatMessage[];
+    /** Oldest → newest. May interleave system items (membership events). */
+    messages: F0ChatItem[];
     /** Users currently typing (excluding me). */
     typingUsers: F0ChatUser[];
     hasMoreOlder: boolean;
@@ -5223,17 +5361,57 @@ export declare type F0ChatRuntime = {
     unreadCount: number;
     /** Id of the first unread message — where the "new messages" divider goes. */
     firstUnreadId: string | null;
-    sendMessage: (input: F0ChatSendInput) => void;
-    retryMessage: (id: string) => void;
+    /**
+     * Send a message. F0 fires-and-forgets; the OPTIMISTIC LIFECYCLE is the
+     * host's contract (this is what makes any backend feel instant):
+     *
+     * 1. Generate the message id CLIENT-SIDE and synchronously insert a local
+     *    echo into `messages` with `status: "sending"` — the bubble must appear
+     *    in the same render, not after the server acks.
+     * 2. Reconcile by id: when the server echo arrives, replace the local one
+     *    (same id → same bubble, no flicker) and advance `status`.
+     * 3. On failure, flip the echo to `status: "failed"` (optionally with
+     *    `failureReason`) and keep it in `messages` — F0 renders the retry /
+     *    discard affordances.
+     * 4. `retryMessage` re-sends with the SAME id so the server can dedupe when
+     *    the original send actually landed (timeouts lie on bad networks).
+     *
+     * factorial → Stream: `channel.state.addMessageSorted` + client-generated
+     * UUID + id-idempotent `sendMessage`.
+     */
+    sendMessage: (input: F0ChatSendInput) => void | Promise<void>;
+    /**
+     * Re-send a message whose `status` is `"failed"`, reusing the SAME message
+     * id so the transport can dedupe if the original send actually reached the
+     * server (factorial → Stream is idempotent on client-generated message ids).
+     * Flips the message back to `"sending"`.
+     */
+    retryMessage: (id: string) => void | Promise<void>;
     loadOlder: () => void;
-    toggleReaction: (messageId: string, emoji: string) => void;
-    deleteMessage: (id: string) => void;
+    toggleReaction: (messageId: string, emoji: string) => void | Promise<void>;
+    /**
+     * Delete a message that exists server-side (soft delete → tombstone, or hard
+     * delete → removed from `messages`).
+     *
+     * When `deleteFailedMessage` is not provided this is ALSO called for failed
+     * local echoes, and the host must special-case them: discard the local echo
+     * only — no server call, the message doesn't exist server-side (factorial →
+     * `channel.state.removeMessage`). Prefer providing `deleteFailedMessage` so
+     * the two semantics stay explicit.
+     */
+    deleteMessage: (id: string) => void | Promise<void>;
+    /**
+     * Discard a `"failed"` local echo (never delivered — a purely local
+     * operation, no server call). When omitted, F0 falls back to
+     * `deleteMessage`, which then must handle the failed case itself.
+     */
+    deleteFailedMessage?: (id: string) => void | Promise<void>;
     /**
      * Edit an existing message (text, mentions, attachments). Omit to disable
      * editing — the "Edit" action then never shows. factorial →
      * `client.partialUpdateMessage`.
      */
-    editMessage?: (id: string, input: F0ChatEditInput) => void;
+    editMessage?: (id: string, input: F0ChatEditInput) => void | Promise<void>;
     /**
      * How long after sending a message stays editable (ms). The "Edit" action is
      * hidden once a message is older than this. Omit for no limit (editable
@@ -5242,6 +5420,15 @@ export declare type F0ChatRuntime = {
     editWindowMs?: number;
     /** Called as the user types so the runtime can emit typing.start/stop. */
     onInputActivity: () => void;
+    /**
+     * Emit typing.stop immediately — the composer calls it on send, when the
+     * text is cleared and on unmount, so the counterpart's dots drop the very
+     * moment typing actually stopped. Hosts whose transport auto-expires typing
+     * (Stream's `keystroke()` does after a few seconds) can omit it and rely on
+     * the timeout; transports without auto-expiry need it (factorial →
+     * `channel.stopTyping()`).
+     */
+    stopTyping?: () => void | Promise<void>;
     uploadFiles?: (files: File[]) => Promise<F0ChatAttachment[]>;
     /**
      * Max files attachable at once. When a selection/drop would exceed it, the
@@ -5255,7 +5442,24 @@ export declare type F0ChatRuntime = {
      * (the Stream adapter omits it, so the mic button stays hidden there).
      */
     transcribe?: TranscribeFn;
-    markRead?: () => void;
+    /**
+     * Mark the conversation read. `untilMessageId` supports partial reads
+     * ("read up to this message") for backends that track them; F0 currently
+     * always calls it without arguments (read everything), so simple hosts can
+     * ignore the parameter.
+     */
+    markRead?: (untilMessageId?: string) => void | Promise<void>;
+    /**
+     * Per-channel permissions (frozen / read-only channels, moderation…). Omit
+     * for the default policy — see {@link F0ChatCapabilities}.
+     */
+    capabilities?: F0ChatCapabilities;
+    /**
+     * Retry after a load failure — wired to the Retry button in the error state.
+     * Omit to render the error message without an action (previous behavior).
+     * factorial → re-run `channel.watch()`.
+     */
+    reconnect?: () => void | Promise<void>;
     /**
      * Search the conversation's members for the `@`-mention popover, returning
      * matches for `query` (empty string → the full member list). Provide it
@@ -5267,10 +5471,20 @@ export declare type F0ChatRuntime = {
     searchMembers?: (query: string) => Promise<F0ChatUser[]>;
     /**
      * Toggle the conversation's pinned (favourite) state for the current user.
-     * Drives the header "Pin / Unpin" action; omit to hide it. factorial →
+     * Transport capability only — the header no longer auto-renders a Pin
+     * action; the host surfaces one via {@link F0ChatHeaderAction} (`onClick:
+     * () => runtime.togglePin()`) where its permissions allow. factorial →
      * `channel.pin()` / `channel.unpin()`.
      */
-    togglePin?: () => void;
+    togglePin?: () => void | Promise<void>;
+    /**
+     * Toggle the conversation's muted state for the current user. Transport
+     * capability only — the header no longer auto-renders a Mute action; the
+     * host surfaces one via {@link F0ChatHeaderAction} (the header still shows
+     * the `channel.muted` status icon either way). factorial →
+     * `channel.mute()` / `channel.unmute()`.
+     */
+    toggleMute?: () => void | Promise<void>;
     /**
      * Full-text search within this conversation, returning matches oldest→newest.
      * Omit to fall back to a client-side substring search over the loaded
@@ -5304,7 +5518,61 @@ export declare type F0ChatSendInput = {
     mentionedEveryone?: boolean;
 };
 
-export declare type F0ChatStatus = "connecting" | "ready" | "error";
+/**
+ * Conversation lifecycle as the host reports it. `connecting` (first load)
+ * shows the skeleton and `error` the error state (with a Retry button when
+ * {@link F0ChatRuntime.reconnect} is provided). `reconnecting` / `offline` are
+ * for hosts with a live/cached transport: F0 renders the transcript exactly
+ * like `ready` — deliberately NO banner (per-message sending/failed states
+ * already communicate connectivity, WhatsApp-style) — falling back to the
+ * skeleton only when there are no messages to show yet. Hosts with a simple
+ * request/response lifecycle can keep using the original three states.
+ */
+export declare type F0ChatStatus = "connecting" | "ready" | "reconnecting" | "offline" | "error";
+
+/**
+ * Membership / lifecycle events rendered as a centered system row. Closed
+ * union — the host maps unknown transport event kinds to a body-only system
+ * message (the plain-text fallback). Room to grow: "channel.renamed", ….
+ */
+export declare type F0ChatSystemEvent = "member.added" | "member.removed" | "member.left";
+
+/**
+ * A transcript item that is ABOUT the conversation, not from a person: no
+ * author, no isMine, no reactions/replies/status — by construction. Rendered
+ * as a centered row (like the date separator). factorial → a Stream message
+ * with `type: "system"`; `system` comes from its custom fields, `body` from
+ * its free-form `text`.
+ */
+export declare type F0ChatSystemMessage = {
+    type: "system";
+    id: string;
+    /** ISO timestamp — participates in day separators and ordering. */
+    createdAt: string;
+    /** Structured payload → avatar-tag sentence. Omit to render `body` as-is. */
+    system?: F0ChatSystemPayload;
+    /** Plain-text fallback (e.g. GetStream's free-form system `text`), shown
+     * centered when `system` is absent or the event kind is unknown. */
+    body?: string;
+};
+
+/** Structured system payload → rendered as a sentence with inline person tags. */
+export declare type F0ChatSystemPayload = {
+    event: F0ChatSystemEvent;
+    /**
+     * The people the event is about. One message can carry several — the host /
+     * adapter coalesces bursts into one item (Slack-style "Ana, Luis and 2
+     * more") by REPLACING the previous item with an updated `members` array
+     * (same id); coalescing never happens in the view layer.
+     */
+    members: F0ChatUser[];
+    /** How many more people beyond `members` (host truncation) — added to the
+     * "+N" overflow tag on top of the visual max. */
+    remainingCount?: number;
+    /** Who performed the action (the admin who added/removed), when known.
+     * Not rendered today; reserved for "added by X" templates. */
+    actor?: F0ChatUser;
+};
 
 /** A participant in a conversation. */
 export declare type F0ChatUser = {
@@ -5317,6 +5585,20 @@ export declare type F0ChatUser = {
     profileHref?: string;
 };
 
+/**
+ * A voice note: recorded in the composer (mic button) and rendered as an audio
+ * player with playback-speed control. factorial → a Stream attachment
+ * `{ type: "voice_recording", asset_url, duration }`.
+ */
+export declare type F0ChatVoiceAttachment = {
+    kind: "voice";
+    url: string;
+    /** Recording length in seconds (shown before playback starts). */
+    durationSeconds?: number;
+    mimeType?: string;
+    name?: string;
+};
+
 export declare type F0FileAction = {
     icon?: IconType;
     label: string;
@@ -6983,6 +7265,10 @@ declare const internalAvatarSizes: readonly ["xsmall", "small", "medium", "large
 
 declare const internalAvatarTypes: readonly ["base", "rounded"];
 
+export declare const isSystemMessage: (item: F0ChatItem) => item is F0ChatSystemMessage;
+
+export declare const isUserMessage: (item: F0ChatItem) => item is F0ChatMessage;
+
 export declare function Item({ item, counter, isActive, collapsible, isExpanded, onToggleExpanded, sortable, children, onDragOver, onDragLeave, onDrop, canDropInside, currentParentId, justDropped, }: TOCItemProps): JSX_2.Element;
 
 export declare type ItemActionsDefinition<T extends RecordType> = (item: T) => ActionDefinition[] | undefined;