tempest-react-sdk 0.33.2 → 0.34.0

package/dist/tempest-react-sdk.d.ts

@@ -158,6 +158,307 @@ export declare interface AccordionProps {
     className?: string;
 }
 
+/**
+ * A conversation with a model: role-based turns, Markdown answers, a reasoning
+ * block, a streaming caret, per-turn actions and a composer that turns into a stop
+ * button while a turn is generating.
+ *
+ * This is the shape ChatGPT, Claude and DeepSeek converged on, and it is a different
+ * component from {@link Chat}, not a variant of it. A human thread is addressed by
+ * author and cares about delivery state; a model transcript is addressed by role,
+ * has no delivery state at all, and needs three things a human thread never does —
+ * partial output, reasoning separate from the answer, and re-asking.
+ *
+ * Presentational and controlled, like the rest of the SDK: it takes a list and emits
+ * intent (`onSend`, `onStop`, `onRegenerate`, `onEditSubmit`, `onFeedback`). The
+ * transport stays with the app, because "how do I stream from my backend" has a
+ * different answer per provider — the SDK's `createEventStream` covers SSE, `fetch`
+ * with a `ReadableStream` covers the rest, and either way the app owns the
+ * `AbortController` it hands to `onStop`.
+ *
+ * @example
+ * <AIChat
+ *     messages={turns}
+ *     pending={pending}
+ *     onSend={(text) => ask(text)}
+ *     onStop={() => controller.current?.abort()}
+ *     onRegenerate={(turn) => reask(turn)}
+ *     onFeedback={(turn, vote) => track("answer_rated", { id: turn.id, vote })}
+ *     suggestions={["Resuma o último relatório", "Quais pedidos atrasaram?"]}
+ * />
+ */
+export declare function AIChat({ messages, onSend, onStop, onRegenerate, onEditSubmit, onFeedback, onRetry, pending, suggestions, renderAvatar, renderContent, votes, header, emptyState, showSystem, defaultReasoningOpen, showLineNumbers, locale, placeholder, composerActions, composerFooter, composerDisabled, maxRows, onSendError, className, ...rest }: AIChatProps): JSX.Element;
+
+/** A file carried by a turn — an upload on the way in, a document on the way out. */
+export declare interface AIChatAttachment {
+    /** Stable identity. Used as the React key. */
+    id: string;
+    /** Name shown in the chip. */
+    name: string;
+    /** Size in bytes. Formatted for display when given. */
+    size?: number;
+    /** Image URL. When set the attachment renders as a thumbnail instead of a chip. */
+    url?: string;
+    /** MIME type. Used as the chip's secondary label when there is no size. */
+    mimeType?: string;
+}
+
+/**
+ * The prompt field of a conversation with a model: a textarea that grows with its
+ * content, sends on `Enter`, keeps `Shift+Enter` for a newline, and turns into a
+ * stop button while a turn is streaming.
+ *
+ * Uncontrolled on purpose. A draft changes on every keystroke, and lifting that into
+ * app state re-renders the whole transcript per character — with a streaming answer
+ * above, that is the one place where "controlled by default" costs something
+ * visible. Apps that need the draft (a persisted composer, a slash-command menu)
+ * read it from `onChange` or drive it through the ref.
+ *
+ * @example
+ * <AIChatComposer
+ *     generating={generating}
+ *     onSend={(text) => ask(text)}
+ *     onStop={() => controller.abort()}
+ *     footer={<small>Claude Opus 5 · pode errar</small>}
+ * />
+ */
+export declare const AIChatComposer: ForwardRefExoticComponent<AIChatComposerProps & RefAttributes<AIChatComposerHandle>>;
+
+/** Imperative handle, so a thread can focus or refill the field. */
+export declare interface AIChatComposerHandle {
+    focus: () => void;
+    /** Replace the draft — used to put a prompt back in the field. */
+    setValue: (text: string) => void;
+}
+
+export declare interface AIChatComposerProps extends Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, OverriddenDomProps_5> {
+    /** Called with the trimmed prompt. The field clears only when this does not throw. */
+    onSend: (text: string) => void | Promise<void>;
+    /**
+     * Abort the turn in flight.
+     *
+     * When given together with `generating`, the send button becomes a stop button
+     * and `Escape` aborts too.
+     */
+    onStop?: () => void;
+    /** A turn is being generated. Replaces send with stop and refuses to send. */
+    generating?: boolean;
+    /** Locale for the placeholder and the button labels. Default `"pt-BR"`. */
+    locale?: "pt-BR" | "en";
+    /** Left of the send button — an attach control, a model picker, a tool toggle. */
+    actions?: ReactNode;
+    /** Under the field — a token count, the model name, a disclaimer. */
+    footer?: ReactNode;
+    /** Largest height the field grows to, in lines. Default 8. */
+    maxRows?: number;
+    /**
+     * Called when `onSend` rejects. The draft is kept either way.
+     *
+     * Without it the rejection is swallowed after the draft is preserved: re-throwing
+     * out of a DOM event handler surfaces as an unhandled promise rejection, which is
+     * console noise for the developer and nothing the user can act on. The visible
+     * signal is the prompt still sitting in the field; wire this to a toast to say why.
+     */
+    onError?: (error: unknown) => void;
+}
+
+/** One turn of a conversation with a model. */
+export declare interface AIChatMessage {
+    /** Stable identity. Used as the React key and by every callback. */
+    id: string;
+    role: AIChatRole;
+    /**
+     * The text of the turn.
+     *
+     * An assistant turn is rendered as Markdown; a user turn is rendered as plain
+     * text with newlines preserved. That asymmetry is deliberate: a model emits
+     * Markdown by contract, while a person typing `2 * 3 * 4` did not mean to open
+     * an emphasis span.
+     */
+    content: string;
+    /**
+     * Reasoning the model exposed before answering — extended thinking, a
+     * chain-of-thought trace.
+     *
+     * Rendered in its own collapsible block above the answer, so a long trace never
+     * pushes the answer off screen.
+     */
+    reasoning?: string;
+    /**
+     * The turn is still arriving.
+     *
+     * Shows the caret, marks the block `aria-busy`, and hides the action row —
+     * copying or rating half an answer is never what somebody meant to do.
+     */
+    streaming?: boolean;
+    /** Generation failed. Shown under whatever streamed, with the retry control. */
+    error?: string;
+    /** Epoch milliseconds. */
+    createdAt?: number;
+    /** Model that produced the turn. Shown in the meta row of an assistant turn. */
+    model?: string;
+    attachments?: readonly AIChatAttachment[];
+    /** Anything the app wants to carry through to its own renderers. */
+    data?: Record<string, unknown>;
+}
+
+export declare interface AIChatProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_4> {
+    /** The transcript, **oldest first**. Never reordered by the component. */
+    messages: readonly AIChatMessage[];
+    /** Renders the composer when given. Receives the trimmed prompt. */
+    onSend?: (text: string) => void | Promise<void>;
+    /** Abort the turn in flight. Shows the stop button while generating. */
+    onStop?: () => void;
+    /** Ask again for the newest assistant turn. */
+    onRegenerate?: (message: AIChatMessage) => void;
+    /** Re-submit an edited user turn. The app decides what to drop after it. */
+    onEditSubmit?: (message: AIChatMessage, text: string) => void | Promise<void>;
+    /** Rating on an assistant turn. */
+    onFeedback?: (message: AIChatMessage, vote: AIChatVote) => void;
+    /** Retry a turn that carries an `error`. */
+    onRetry?: (message: AIChatMessage) => void;
+    /**
+     * The request is out and nothing has arrived yet.
+     *
+     * Distinct from a turn with `streaming: true`: apps that only push a message
+     * once the first token lands need somewhere to say "we asked", and without it the
+     * screen is frozen for however long the model takes to start.
+     */
+    pending?: boolean;
+    /** Prompts offered on an empty transcript. Clicking one sends it. */
+    suggestions?: readonly string[];
+    /** Avatar for a turn — an `<Avatar>`, an `<Icon>`, a logo. */
+    renderAvatar?: (message: AIChatMessage) => ReactNode;
+    /** Render a body yourself — a tool-call card, a chart, a citation list. */
+    renderContent?: (message: AIChatMessage) => ReactNode;
+    /** Ratings to show as pressed, by message id. Omit to keep them local. */
+    votes?: Readonly<Record<string, AIChatVote>>;
+    /** Rendered above the transcript, inside the panel. */
+    header?: ReactNode;
+    /** Shown when there are no turns and no suggestions. */
+    emptyState?: ReactNode;
+    /** Show `"system"` turns. Default `false`. */
+    showSystem?: boolean;
+    /** Reasoning blocks start expanded. Default `false`. */
+    defaultReasoningOpen?: boolean;
+    /** Show line numbers in fenced code. Default `false`. */
+    showLineNumbers?: boolean;
+    /** Locale for labels. Default `"pt-BR"`. */
+    locale?: "pt-BR" | "en";
+    /** Placeholder for the composer. */
+    placeholder?: string;
+    /** Extra controls inside the composer, before the send button. */
+    composerActions?: ReactNode;
+    /** Under the composer field — token count, model name, a disclaimer. */
+    composerFooter?: ReactNode;
+    /** Disable the composer — no credits, conversation archived, offline. */
+    composerDisabled?: boolean;
+    /** Largest height the composer grows to, in lines. Default 8. */
+    maxRows?: number;
+    /**
+     * Called when `onSend` **or** `onEditSubmit` rejects. The draft stays in the field
+     * either way.
+     */
+    onSendError?: (error: unknown) => void;
+}
+
+/** Who produced a turn. */
+export declare type AIChatRole = "user" | "assistant" | "system";
+
+/** Labels the conversation needs, per locale. */
+export declare interface AIChatStrings {
+    thread: string;
+    empty: string;
+    emptyHint: string;
+    placeholder: string;
+    send: string;
+    stop: string;
+    regenerate: string;
+    copy: string;
+    copied: string;
+    edit: string;
+    save: string;
+    cancel: string;
+    editing: string;
+    good: string;
+    bad: string;
+    reasoning: string;
+    thinking: string;
+    generating: string;
+    done: string;
+    stopped: string;
+    you: string;
+    assistant: string;
+    system: string;
+    retry: string;
+    jumpToLatest: string;
+    attachment: string;
+    turnActions: string;
+}
+
+/** Locale strings for the conversation. */
+export declare function aiChatStrings(locale: "pt-BR" | "en"): AIChatStrings;
+
+/**
+ * One turn of a conversation with a model.
+ *
+ * Exported for apps that build their own transcript layout (a split view, a diff of
+ * two answers) but still want the SDK's turn: Markdown body, reasoning block,
+ * attachments, streaming caret, error state and the action row.
+ *
+ * @example
+ * <AIChatTurn message={turn} canRegenerate onRegenerate={(m) => reask(m)} />
+ */
+export declare function AIChatTurn({ message, locale, canRegenerate, onRegenerate, onFeedback, onEditSubmit, onEditError, onRetry, renderAvatar, renderContent, vote, defaultReasoningOpen, showLineNumbers, }: AIChatTurnProps): JSX.Element;
+
+export declare interface AIChatTurnProps {
+    /** The turn to render. */
+    message: AIChatMessage;
+    /** Locale for the labels. Default `"pt-BR"`. */
+    locale?: "pt-BR" | "en";
+    /**
+     * Offer the regenerate control.
+     *
+     * Only the newest assistant turn should get it — re-asking an older one throws
+     * away every turn after it, which is a different operation and needs its own
+     * confirmation.
+     */
+    canRegenerate?: boolean;
+    onRegenerate?: (message: AIChatMessage) => void;
+    onFeedback?: (message: AIChatMessage, vote: AIChatVote) => void;
+    /** Enables the edit control on a user turn. Receives the edited prompt. */
+    onEditSubmit?: (message: AIChatMessage, text: string) => void | Promise<void>;
+    /**
+     * Called when `onEditSubmit` rejects. The editor stays open with the draft either
+     * way.
+     *
+     * Without it the rejection is swallowed after the draft is preserved: re-throwing
+     * out of a click handler surfaces as an unhandled promise rejection, which is
+     * console noise for the developer and nothing the user can act on.
+     */
+    onEditError?: (error: unknown) => void;
+    /** Enables the retry control on a turn that carries an `error`. */
+    onRetry?: (message: AIChatMessage) => void;
+    renderAvatar?: (message: AIChatMessage) => ReactNode;
+    /** Render the body yourself — a tool-call card, a chart, a citation list. */
+    renderContent?: (message: AIChatMessage) => ReactNode;
+    /**
+     * Rating to show as pressed.
+     *
+     * Pass it to keep votes in app state (persisted across a reload); leave it out
+     * and the pressed state is kept locally, which is enough for a fire-and-forget
+     * `onFeedback`.
+     */
+    vote?: AIChatVote;
+    /** Reasoning blocks start expanded. Default `false`. */
+    defaultReasoningOpen?: boolean;
+    /** Show line numbers in fenced code. Default `false`. */
+    showLineNumbers?: boolean;
+}
+
+/** Rating an app can collect on an assistant turn. */
+export declare type AIChatVote = "up" | "down";
+
 /**
  * Inline alert / notice with tone (info/success/warning/danger) and appearance
  * (soft/solid/outline). Accepts optional `icon`, `title`, `description` and
@@ -2456,10 +2757,36 @@ export declare interface CreateWebSocketOptions<T> {
     /**
      * Ping interval (ms). When set, the client sends `pingPayload` periodically
      * to keep the socket alive. Default: 0 (disabled).
+     *
+     * Leave it off against a `tempest-fastapi-sdk` server: that server pings on
+     * its own and answers a client-sent `{"type":"ping"}` with nothing, while a
+     * strict handler rejects the unknown frame. What it needs from the client
+     * is the `pong` reply, which `respondToPing` sends for you.
      */
     pingInterval?: number;
     /** Payload sent on each ping. Default: `JSON.stringify({ type: "ping" })`. */
     pingPayload?: string | Blob | BufferSource;
+    /**
+     * Reply to a server `{"type":"ping"}` with `pongPayload`. Default: true.
+     *
+     * `tempest-fastapi-sdk` closes a socket with code `4408` when no `pong`
+     * arrives within `WS_HEARTBEAT_TIMEOUT_SECONDS`, so a client that stays
+     * silent is dropped once per timeout. The ping is still forwarded to
+     * `onMessage` — the reply is sent before your handler runs.
+     */
+    respondToPing?: boolean;
+    /** Payload sent in reply to a server ping. Default: `JSON.stringify({ type: "pong" })`. */
+    pongPayload?: string | Blob | BufferSource;
+    /**
+     * Buffer payloads sent while the socket is not open and flush them on the
+     * next `open`. Default: false — `send()` returns false and drops.
+     *
+     * Without it, an action fired during reconnect backoff vanishes and the UI
+     * cannot tell "never sent" from "sent and ignored".
+     */
+    queueWhileClosed?: boolean;
+    /** Cap on buffered payloads when `queueWhileClosed` is on. Default: 100. */
+    maxQueuedMessages?: number;
     /** Parse incoming frames. Default: JSON with raw-string fallback. */
     parser?: (raw: string) => T;
     onOpen?: (event: Event) => void;
@@ -3316,7 +3643,7 @@ export declare interface Filter {
  */
 export declare function FilterBar({ fields, value, onChange, locale, actions, className, ...rest }: FilterBarProps): JSX.Element;
 
-export declare interface FilterBarProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_7> {
+export declare interface FilterBarProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_9> {
     /** Fields the user may filter by. */
     fields: readonly FilterField[];
     /** Applied filters. Controlled. */
@@ -4459,6 +4786,9 @@ export declare function isDefined<T>(value: T | null | undefined): value is T;
  */
 export declare function isEmpty(value: unknown): boolean;
 
+/** Whether any turn in the thread is still streaming. */
+export declare function isGenerating(messages: readonly AIChatMessage[]): boolean;
+
 /**
  * Detects iOS / iPadOS Safari, including modern iPads that report `MacIntel`
  * plus multi-touch instead of an `iPad` user agent.
@@ -4695,6 +5025,15 @@ export declare interface LabelProps extends LabelHTMLAttributes<HTMLLabelElement
     required?: boolean;
 }
 
+/**
+ * Id of the newest assistant turn, or `null` when there is none.
+ *
+ * Only that turn gets the regenerate control: re-asking an older one would throw
+ * away every turn after it, which is a different operation ("branch here") and
+ * needs its own confirmation.
+ */
+export declare function lastAssistantId(messages: readonly AIChatMessage[]): string | null;
+
 /**
  * Conflict-resolution helpers for the `applyRemote` callback of
  * {@link createOfflineSync}. Each takes the current local record (or
@@ -5024,7 +5363,7 @@ export declare type MarkdownInline = {
     type: "break";
 };
 
-export declare interface MarkdownProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_6> {
+export declare interface MarkdownProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_8> {
     /** The Markdown source. */
     source: string;
     /**
@@ -5062,7 +5401,7 @@ export declare interface MarkdownProps extends Omit<HTMLAttributes<HTMLDivElemen
  */
 export declare function Masonry<T>({ items, children, itemKey, columns, gap, className, style, ...rest }: MasonryProps<T>): JSX.Element;
 
-export declare interface MasonryProps<T> extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_5> {
+export declare interface MasonryProps<T> extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_7> {
     /** What to lay out. */
     items: readonly T[];
     /** Render one card. */
@@ -6021,16 +6360,22 @@ declare type OverriddenDomProps_2 = "children" | "onSubmit";
 declare type OverriddenDomProps_3 = "onSubmit" | "value" | "defaultValue" | "rows";
 
 /** DOM attributes this component redefines. */
-declare type OverriddenDomProps_4 = "children" | "onChange" | "defaultValue";
+declare type OverriddenDomProps_4 = "children" | "onSubmit";
+
+/** DOM attributes the composer redefines. */
+declare type OverriddenDomProps_5 = "onSubmit" | "value" | "defaultValue" | "rows";
+
+/** DOM attributes this component redefines. */
+declare type OverriddenDomProps_6 = "children" | "onChange" | "defaultValue";
 
 /** DOM attributes this component redefines. */
-declare type OverriddenDomProps_5 = "children";
+declare type OverriddenDomProps_7 = "children";
 
 /** DOM attributes this component redefines. */
-declare type OverriddenDomProps_6 = "children";
+declare type OverriddenDomProps_8 = "children";
 
 /** DOM attributes this component redefines. */
-declare type OverriddenDomProps_7 = "children" | "onChange";
+declare type OverriddenDomProps_9 = "children" | "onChange";
 
 /**
  * Page wrapper with header + (optional) toolbar + content + footer. Pairs
@@ -7026,6 +7371,9 @@ export declare interface RoleAccessControlConfig {
     role?: string | string[];
 }
 
+/** Role label used in the turn header and by screen readers. */
+export declare function roleLabel(role: AIChatRole, strings: AIChatStrings): string;
+
 export { Route }
 
 /**
@@ -8188,6 +8536,21 @@ export declare type TagSize = "sm" | "md" | "lg";
 
 export declare type TagVariant = "neutral" | "primary" | "success" | "warning" | "danger" | "info";
 
+/**
+ * A value that changes whenever the tail of the thread grows.
+ *
+ * The scroll effect cannot depend on the `messages` array alone. Streaming appends
+ * to the **last** turn, and an app that mutates that object in place — or that
+ * re-renders from a store holding the same array identity — would keep the same
+ * dependency while the text grows, so the view would stop following the answer.
+ * Length of the array, identity of the tail and length of its text together cover
+ * both shapes.
+ *
+ * @param messages - The thread, oldest first.
+ * @returns An opaque signature; compare with `===`.
+ */
+export declare function tailSignature(messages: readonly AIChatMessage[]): string;
+
 export declare interface TelemetryAdapter {
     /** Optional. Called when the provider mounts. */
     init?: () => void | Promise<void>;
@@ -8872,7 +9235,7 @@ export declare interface TransferItem {
     data?: Record<string, unknown>;
 }
 
-export declare interface TransferProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_4> {
+export declare interface TransferProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_6> {
     /** The whole catalogue. Both panes are derived from it. */
     items: readonly TransferItem[];
     /** Ids on the target side. Controlled. */
@@ -9021,6 +9384,15 @@ export declare interface TruncateTextProps extends HTMLAttributes<HTMLDivElement
     children: ReactNode;
 }
 
+/**
+ * Clock label for a turn — the time, not a relative phrase.
+ *
+ * A transcript is read top to bottom in one sitting, so "há 2 minutos" on every turn
+ * is noise that also has to be re-rendered on a timer. The wall clock is stable and
+ * enough to answer the only question anyone asks of it ("was this today?").
+ */
+export declare function turnTime(timestamp: number, locale?: "pt-BR" | "en"): string;
+
 /** Sentence for the typing indicator, or `null` when nobody is typing. */
 export declare function typingLabel(names: readonly string[], locale?: "pt-BR" | "en"): string | null;
 
@@ -10782,6 +11154,17 @@ export { useWatch }
 /**
  * React hook around {@link createWebSocket}. Manages the connection lifecycle
  * for the host component and tears it down on unmount.
+ *
+ * Every callback is read through a ref, so `onOpen` / `onMessage` / `onClose` /
+ * `onError` always run the latest closure — an inline arrow function is fine
+ * and never reopens the socket. Connection-shaping options (`protocols`,
+ * `maxRetries`, `initialBackoff`, `maxBackoff`, `pingInterval`,
+ * `queueWhileClosed`) are baked into the connection, so changing one reopens
+ * it with the new value rather than being silently ignored.
+ *
+ * @param url - Full ws:// or wss:// URL.
+ * @param options - Connection configuration and callbacks.
+ * @returns Status, last frame, and the `send` / `reconnect` controls.
  */
 export declare function useWebSocket<T = unknown>(url: string, options?: UseWebSocketOptions<T>): UseWebSocketResult<T>;
 
@@ -10792,7 +11175,15 @@ export declare interface UseWebSocketOptions<T> extends Omit<CreateWebSocketOpti
 
 export declare interface UseWebSocketResult<T> {
     status: WebSocketStatus;
-    /** Last decoded frame received. */
+    /**
+     * Last decoded frame received.
+     *
+     * A snapshot, not a stream: two frames arriving in the same tick collapse
+     * into a single render and only the later one is ever visible. One server
+     * action often emits several frames in a row, so anything that must see
+     * every message has to use `onMessage`, which fires once per frame. Read
+     * `lastMessage` for "what is the current state" rendering only.
+     */
     lastMessage: WebSocketMessage<T> | null;
     /** Send a payload through the active connection. Returns false when not open. */
     send: (payload: string | Blob | BufferSource) => boolean;
@@ -10995,6 +11386,21 @@ export declare interface VirtualTableSort<T> {
 
 export declare type VirtualTableSortDirection = "asc" | "desc";
 
+/**
+ * Turns to render, in order.
+ *
+ * System turns are dropped unless asked for: a system prompt is configuration, and
+ * an app that shows it by default leaks its own instructions into the transcript.
+ *
+ * @param params.messages - The thread, oldest first. Never reordered.
+ * @param params.showSystem - Keep `"system"` turns. Default `false`.
+ * @returns The visible turns, in the given order.
+ */
+export declare function visibleTurns({ messages, showSystem, }: {
+    messages: readonly AIChatMessage[];
+    showSystem?: boolean;
+}): AIChatMessage[];
+
 /**
  * Render content that is hidden visually but remains available to screen
  * readers — the standard "sr-only" pattern. Useful for accessible labels on