@epicbagel/saas-kit 1.0.0 → 1.2.0

package/dist/primitives/chat.d.ts

@@ -0,0 +1,345 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React$1 from 'react';
+import { ReactNode } from 'react';
+import { MarkdownComponents } from './markdown.js';
+import 'react-markdown';
+import './rich-text.js';
+
+type ChatRole = "user" | "assistant";
+type ChatAttachment = {
+    id: string;
+    name: string;
+    mediaType?: string;
+    size?: number;
+    url?: string;
+    state?: "idle" | "uploading" | "processing" | "error" | "done";
+};
+/** What opening a file on a message does: open it (a preview, a new tab) or download it. */
+type ChatAttachmentAction = "open" | "download";
+type ChatMessage = {
+    /**
+     * Stable for the life of the turn. A user turn under an id the thread hasn't
+     * seen counts as just arrived and is scrolled into view, so when an
+     * optimistic turn is replaced by its stored copy, keep the optimistic id.
+     */
+    id: string;
+    role: ChatRole;
+    /** Controls whether rich content hugs its contents or occupies the transcript width. */
+    width?: "content" | "full";
+    /** When this persisted turn was created. Enables grouped relative-time separators. */
+    createdAt?: string | number | Date;
+    /** Markdown body. Use `content` for custom rich children if you need them. */
+    text?: string;
+    /** Rich children — takes precedence over `text` for rendering. */
+    content?: ReactNode;
+    /** Files that belong to this turn. */
+    attachments?: ReadonlyArray<ChatAttachment>;
+};
+interface ChatThreadProps {
+    messages: ChatMessage[];
+    /** Show a running line (`pendingLabel`) at the end of the thread. */
+    pending?: boolean;
+    /** The running line while a reply is pending. Defaults to "Thinking…". */
+    pendingLabel?: string;
+    /** Accessible name of the scroll-to-latest button. Defaults to "Scroll to latest message". */
+    scrollButtonLabel?: string;
+    /** Shown on a message's file while it is still uploading. Defaults to "Uploading…". */
+    uploadingLabel?: string;
+    /** Max height for the scrollable thread. Defaults to "46vh". */
+    maxHeight?: string;
+    /** `workspace` uses a restrained central transcript with unboxed assistant turns. */
+    appearance?: "bubbles" | "workspace";
+    /** Rich content rendered as the final assistant artifact in the transcript. */
+    footer?: ReactNode;
+    /**
+     * Per-element overrides for Markdown message text (`h1`, `a`, `code`, …),
+     * such as a display treatment for document titles. Messages that pass rich
+     * `content` are unaffected.
+     */
+    markdownComponents?: MarkdownComponents;
+    /**
+     * Makes each file on a message a control: called with the file the reader
+     * picked, to fetch it, start a download or open a preview. Without it a
+     * message's files are listed but inert. Files staged in the composer are
+     * unaffected.
+     */
+    onOpenAttachment?: (attachment: ChatAttachment) => void;
+    /** What opening a message's file does, for its label and icon. Defaults to `"open"`. */
+    attachmentAction?: ChatAttachmentAction;
+    className?: string;
+}
+/**
+ * Scrollable message thread, built on shadcn's headless `MessageScroller`
+ * (streaming-aware auto-scroll, anchored turns) + the `Message`/`Bubble`
+ * primitives. Pass `messages` + `pending`.
+ *
+ * Every row is a `MessageScrollerItem` directly under the content, which is
+ * the one live log (`role="log"`): the scroller measures, anchors and tracks
+ * only its direct children. A user turn that arrives settles near the top with
+ * the end of the previous exchange peeking above it, and a scroll-to-latest
+ * button appears whenever the reader is away from the end. Turns with a
+ * `createdAt` are grouped under relative-time markers ("2 days ago"), and a
+ * pending reply shows as a running trace line, which the log announces as it
+ * appears.
+ */
+declare const ChatThread: React$1.ForwardRefExoticComponent<ChatThreadProps & React$1.RefAttributes<HTMLDivElement>>;
+interface ChatInputProps {
+    value: string;
+    onChange: (next: string) => void;
+    onSend: (text: string, attachments?: ReadonlyArray<ChatAttachment>) => void;
+    pending?: boolean;
+    disabled?: boolean;
+    placeholder?: string;
+    /**
+     * How tall the empty textarea starts: `sm` a single line (3rem), `md` a
+     * couple of lines (4.5rem), `lg` a short paragraph (8rem). It grows with its
+     * text from there, up to 12rem, then scrolls. Defaults to `md`.
+     */
+    size?: "sm" | "md" | "lg";
+    /** Shown on a staged file while it is still uploading. Defaults to "Uploading…". */
+    uploadingLabel?: string;
+    /** Show the inline voice dictation button. Defaults to true. */
+    voice?: boolean;
+    /** Title shown inside the voice overlay. */
+    voiceTitle?: string;
+    /** Language tag for voice dictation. */
+    voiceLang?: string;
+    /**
+     * Label for the submit button. When set, the button renders as a labelled
+     * primary action (`{label} →`) instead of the default icon-only send — use
+     * it to name the outcome, e.g. "Propose 3 times", "Create link", "Send".
+     */
+    submitLabel?: ReactNode;
+    /** Auto-focus the textarea on mount. */
+    autoFocus?: boolean;
+    /** Classes for the composer surface (the bordered input group). */
+    className?: string;
+    /** Imperative ref handle to focus the underlying textarea. */
+    inputRef?: React.RefObject<HTMLTextAreaElement | null>;
+    /** Files currently staged in the composer. */
+    attachments?: ReadonlyArray<ChatAttachment>;
+    /** Enables the `+` action menu and receives files selected by the user. */
+    onFilesSelected?: (files: File[]) => void | Promise<void>;
+    /** Removes a staged attachment. */
+    onRemoveAttachment?: (attachment: ChatAttachment) => void;
+    /** Native file-picker accept list. */
+    accept?: string;
+    /** Whether more than one file may be selected. Defaults to true. */
+    multiple?: boolean;
+    /** Label in the composer action menu. */
+    addFilesLabel?: string;
+    /** Visual density for the complete composer surface. */
+    appearance?: "default" | "spacious";
+    /** Quiet contextual copy between the composer controls. */
+    helperText?: ReactNode;
+    /** Privacy or visibility reassurance rendered below the composer. */
+    privacyNote?: ReactNode;
+}
+/**
+ * Compact text input: a form around one bordered input group, with any
+ * staged files on top, a textarea that grows with its text, then an action
+ * bar (the file menu and voice mic on the left, the submit button on the
+ * right). Always text-first; voice is a secondary affordance. Enter sends;
+ * Shift+Enter newlines, and Enter that commits an IME candidate never sends.
+ *
+ * The submit button is icon-only by default; pass `submitLabel` to name the
+ * outcome ("Propose 3 times", "Create link") — it then renders as a labelled
+ * primary action with a trailing arrow.
+ *
+ * For the "voice-first hero" empty state on mobile, the higher-level `<Chat>`
+ * primitive switches to a different layout (see VoiceHero below) — use
+ * `<Chat>` instead of composing `<ChatInput>` directly if you want
+ * device-aware default modes.
+ */
+declare function ChatInput({ value, onChange, onSend, pending, disabled, placeholder, size, uploadingLabel, voice, voiceTitle, voiceLang, submitLabel, autoFocus, className, inputRef, attachments, onFilesSelected, onRemoveAttachment, accept, multiple, addFilesLabel, appearance, helperText, privacyNote, }: ChatInputProps): react_jsx_runtime.JSX.Element;
+interface ChatProps {
+    /** Conversation messages. */
+    messages: ChatMessage[];
+    /**
+     * Fired when the user submits the input (or commits voice). The composer
+     * clears at once; if the returned promise rejects, Chat puts the text back
+     * so nothing is lost, then hands the rejection to `onSendError`. Reject only
+     * when the turn wasn't stored: a rejection invites the user to send again.
+     */
+    onSend: (text: string, attachments?: ReadonlyArray<ChatAttachment>) => void | Promise<void>;
+    /**
+     * Called with the reason when `onSend` rejects, after the text is back in
+     * the composer. Without it Chat reports the rejection through the global
+     * `reportError` (the console, and any monitoring listening for `error`
+     * events), so a failed send is never silent. Pass it when the app shows the
+     * failure itself, with `error`.
+     */
+    onSendError?: (error: unknown) => void;
+    /** Whether an in-flight request is pending. Disables input and shows a running line (`pendingLabel`). */
+    pending?: boolean;
+    /** The running line while a reply is pending. Defaults to "Thinking…". */
+    pendingLabel?: string;
+    /**
+     * Replaces the empty composer while its first message is in flight. Use for
+     * a deliberate handoff animation instead of leaving a disabled form behind.
+     */
+    emptyPendingContent?: ReactNode;
+    /** Inline error to surface below the input. */
+    error?: string | null;
+    /** Headline shown in the empty state. None by default. */
+    emptyTitle?: ReactNode;
+    /** Subheadline shown under the headline. */
+    emptySubtitle?: ReactNode;
+    /** Optional list of suggested starter prompts. Click → sends. */
+    examplePrompts?: ReadonlyArray<string>;
+    /** Label above the example prompts. Defaults to "Try". */
+    examplePromptsLabel?: string;
+    /**
+     * `chips` (the default) wrap onto as many lines as they need; `row` is one
+     * line that scrolls sideways, for a few short prompts where height is
+     * scarce; `cards` is a two-column grid of wrapping cards for longer prompts.
+     */
+    examplePromptsVariant?: "chips" | "row" | "cards";
+    /**
+     * Render an inline loading state (a running caption over placeholder
+     * suggestions) instead of the prompts. Use while async-fetching
+     * tailored suggestions so the user sees deliberate progress rather
+     * than placeholder copy that then swaps.
+     */
+    examplePromptsLoading?: boolean;
+    /**
+     * Caption shown in the loading state. Pass a single string for static,
+     * an array to rotate through. Defaults to "Loading suggestions…".
+     */
+    examplePromptsLoadingLabel?: string | ReadonlyArray<string>;
+    /** Render the empty state inline rather than as a hero block. */
+    compactEmptyState?: boolean;
+    /**
+     * Force the empty-state input mode. By default, mobile devices get
+     * the voice-first hero and desktop devices get the compact text
+     * input. Pass `"text"` to always start in text mode, or `"voice"` to
+     * always start in voice-first mode.
+     */
+    defaultMode?: "voice" | "text";
+    /** Placeholder text for the empty-state input. */
+    placeholder?: string;
+    /** Placeholder text once the conversation has started. */
+    activePlaceholder?: string;
+    /**
+     * Label for the submit button (empty-state input). When set, the button
+     * names the outcome (`{label} →`) instead of the icon-only send — e.g.
+     * "Propose 3 times". Once the conversation is active the input reverts to
+     * the compact icon send.
+     */
+    submitLabel?: ReactNode;
+    /** Files currently staged in the composer. */
+    attachments?: ReadonlyArray<ChatAttachment>;
+    /** Enables file selection from the composer action menu. */
+    onFilesSelected?: (files: File[]) => void | Promise<void>;
+    /** Removes a staged attachment. */
+    onRemoveAttachment?: (attachment: ChatAttachment) => void;
+    /** Native file-picker accept list. */
+    attachmentAccept?: string;
+    /** Label used for the file action in the composer menu. */
+    addFilesLabel?: string;
+    /** Shown on a file, staged or on a message, while it is still uploading. Defaults to "Uploading…". */
+    uploadingLabel?: string;
+    /** Visual treatment for both empty and active text composers. */
+    composerAppearance?: ChatInputProps["appearance"];
+    /** Quiet contextual copy inside the composer action row. */
+    composerHelperText?: ReactNode;
+    /** Privacy or visibility reassurance below the composer. */
+    composerPrivacyNote?: ReactNode;
+    /** Show a prominent file drop target before the empty-state composer. */
+    emptyFileDropzone?: boolean;
+    /** Primary copy inside the empty-state file drop target. */
+    emptyFileDropzoneLabel?: ReactNode;
+    /** Supporting file type or workflow copy inside the drop target. */
+    emptyFileDropzoneDescription?: ReactNode;
+    /**
+     * Where a dragged file can be dropped. With `onFilesSelected`, a file
+     * dragged over the conversation raises a "Drop to attach" overlay, and a
+     * drop hands every file to `onFilesSelected`, exactly as the composer's
+     * file menu does: same validation, same staged files, same errors.
+     * `"conversation"` (the default) takes drops on the whole Chat, `"page"`
+     * anywhere in the document (its overlay then covers the viewport), and
+     * `false` none. Either way a file dropped where nothing takes it never
+     * opens in the browser.
+     */
+    fileDrop?: "conversation" | "page" | false;
+    /** The drop overlay's label. Defaults to "Drop to attach". */
+    fileDropLabel?: ReactNode;
+    /** A muted line under the overlay's label, such as the accepted types and limits. */
+    fileDropDescription?: ReactNode;
+    /** Enable voice dictation. Defaults to true. */
+    voice?: boolean;
+    /** Title shown inside the voice overlay. */
+    voiceTitle?: string;
+    /** Title shown inside the voice overlay in the active state. */
+    activeVoiceTitle?: string;
+    /** Language tag for voice dictation. */
+    voiceLang?: string;
+    /** Under the mic of the voice-first empty state. Defaults to "Tap to speak". */
+    voiceHeroLabel?: ReactNode;
+    /** The voice-first empty state's switch to the text composer. Defaults to "or type instead". */
+    voiceHeroSwitchLabel?: ReactNode;
+    /** Max height of the message thread once active. Defaults to "46vh". */
+    threadMaxHeight?: string;
+    /** Accessible name of the thread's scroll-to-latest button. Defaults to "Scroll to latest message". */
+    scrollButtonLabel?: string;
+    /** Alignment for the empty chat introduction. */
+    emptyAlign?: "start" | "center";
+    /** Optional visual above the empty chat title. */
+    emptyIcon?: ReactNode;
+    /** Supporting content shown after the empty-state composer. */
+    emptyFooter?: ReactNode;
+    /**
+     * `embedded` (the default) sits in a panel, a card or a drawer.
+     * `application` is embedded on desktop, but on a phone fills the viewport
+     * below a 4rem app header, with the composer docked at the bottom.
+     * `workspace` makes the conversation the whole surface on every screen,
+     * with a centred transcript and a bottom composer.
+     */
+    layout?: "embedded" | "application" | "workspace";
+    /** Rich assistant artifact rendered after the message transcript. */
+    threadFooter?: ReactNode;
+    /**
+     * Per-element overrides for Markdown message text in the thread (`h1`,
+     * `a`, `code`, …), such as a display treatment for document titles.
+     */
+    markdownComponents?: MarkdownComponents;
+    /**
+     * Makes each file on a message a control: called with the file the reader
+     * picked, to fetch it, start a download or open a preview. Without it a
+     * message's files are listed but inert.
+     */
+    onOpenAttachment?: (attachment: ChatAttachment) => void;
+    /** What opening a message's file does, for its label and icon. Defaults to `"open"`. */
+    attachmentAction?: ChatAttachmentAction;
+    className?: string;
+}
+interface ChatHandle {
+    /** Focus the input. */
+    focusInput: () => void;
+    /** Clear the input value. */
+    clearInput: () => void;
+}
+/**
+ * A conversational composer.
+ *
+ * **Empty state** — device-biased:
+ *   - On mobile (`<md` viewport), defaults to a voice-first hero: a big
+ *     tap-to-speak button and a small "or type instead" switcher.
+ *   - On desktop, defaults to a compact text input with the mic as an
+ *     accessory icon.
+ *   - Users can switch modes via the small link.
+ *   - Optional example prompts render as suggestions below the input.
+ *
+ * **Active state** (messages exist) — always the compact text input;
+ * the mic stays as an accessory icon.
+ *
+ * **Files** — with `onFilesSelected`, the composer's menu picks files and a
+ * file dragged anywhere on the conversation can be dropped (`fileDrop`);
+ * both hand the files to `onFilesSelected`, which validates and stages them.
+ *
+ * Stateless w.r.t. the conversation — pass `messages` and handle
+ * `onSend` from the parent. The input text is managed internally.
+ */
+declare const Chat: React$1.ForwardRefExoticComponent<ChatProps & React$1.RefAttributes<ChatHandle>>;
+
+export { Chat, type ChatAttachment, type ChatAttachmentAction, type ChatHandle, ChatInput, type ChatInputProps, type ChatMessage, type ChatProps, type ChatRole, ChatThread, type ChatThreadProps };