@promptbook/documents 0.111.0-7 → 0.112.0-100

package/esm/src/book-components/Chat/Chat/ChatProps.d.ts

@@ -1,11 +1,14 @@
 import type { CSSProperties, ReactNode } from 'react';
 import type { Promisable } from 'type-fest';
-import { Color } from '../../../_packages/color.index';
-import { SpeechRecognition } from '../../../types/SpeechRecognition';
-import { string_color } from '../../../types/typeAliases';
+import type { SpeechRecognition } from '../../../types/SpeechRecognition';
+import type { string_href } from '../../../types/string_href';
+import type { string_color } from '../../../types/string_person_fullname';
+import { Color } from '../../../utils/color/Color';
+import type { AgentChipData } from '../AgentChip/AgentChip';
 import type { string_chat_format_name } from '../save/_common/string_chat_format_name';
 import type { ChatMessage } from '../types/ChatMessage';
 import type { ChatParticipant } from '../types/ChatParticipant';
+import type { ChatSaveFormatHandlerMap } from '../save/_common/ChatSaveFormatHandler';
 /**
  * Response data returned by the optional `onFeedback` handler.
  *
@@ -17,6 +20,371 @@ export type ChatFeedbackResponse = {
      */
     readonly message?: string;
 };
+/**
+ * Visual mode for post-response feedback actions.
+ *
+ * @public exported from `@promptbook/components`
+ */
+export type ChatFeedbackMode = 'off' | 'stars' | 'report_issue';
+/**
+ * Visual presentation mode used for chat messages.
+ *
+ * - `BUBBLE_MODE`: user and agent messages render as bubbles.
+ * - `ARTICLE_MODE`: user messages stay as bubbles; agent messages render as seamless article blocks.
+ *
+ * @public exported from `@promptbook/components`
+ */
+export type ChatVisualMode = 'BUBBLE_MODE' | 'ARTICLE_MODE';
+/**
+ * Optional text overrides for feedback UI copy.
+ *
+ * @public exported from `@promptbook/components`
+ */
+export type ChatFeedbackTranslations = {
+    /**
+     * Tooltip shown on the report-issue quick action button.
+     */
+    readonly reportIssueButtonTitle?: string;
+    /**
+     * Accessible label shown on the report-issue quick action button.
+     */
+    readonly reportIssueButtonAriaLabel?: string;
+    /**
+     * Modal heading shown when user reports an issue.
+     */
+    readonly reportIssueModalTitle?: string;
+    /**
+     * Modal heading shown when user rates a response with stars.
+     */
+    readonly rateResponseModalTitle?: string;
+    /**
+     * Label shown above the original user question preview.
+     */
+    readonly userQuestionLabel?: string;
+    /**
+     * Label for expected-answer field in report-issue mode.
+     */
+    readonly reportIssueExpectedAnswerLabel?: string;
+    /**
+     * Label for expected-answer field in stars mode.
+     */
+    readonly expectedAnswerLabel?: string;
+    /**
+     * Placeholder for expected-answer input.
+     */
+    readonly expectedAnswerPlaceholder?: string;
+    /**
+     * Label for free-form issue details in report-issue mode.
+     */
+    readonly reportIssueDetailsLabel?: string;
+    /**
+     * Label for free-form note input in stars mode.
+     */
+    readonly noteLabel?: string;
+    /**
+     * Placeholder for free-form issue details input.
+     */
+    readonly reportIssueDetailsPlaceholder?: string;
+    /**
+     * Placeholder for free-form note input.
+     */
+    readonly notePlaceholder?: string;
+    /**
+     * Cancel button label shown in the feedback modal.
+     */
+    readonly cancelLabel?: string;
+    /**
+     * Submit button label shown in report-issue mode.
+     */
+    readonly reportIssueSubmitLabel?: string;
+    /**
+     * Submit button label shown in stars mode.
+     */
+    readonly submitLabel?: string;
+    /**
+     * Toast message shown when generic feedback is stored.
+     */
+    readonly feedbackSuccessMessage?: string;
+    /**
+     * Toast message shown when issue report is stored.
+     */
+    readonly reportIssueSuccessMessage?: string;
+    /**
+     * Toast message shown when feedback storage fails.
+     */
+    readonly feedbackErrorMessage?: string;
+};
+/**
+ * Optional text overrides for general Chat UI strings such as button labels, lifecycle
+ * state badges, tool call modal controls, and the default input placeholder.
+ *
+ * @public exported from `@promptbook/components`
+ */
+export type ChatUiTranslations = {
+    /**
+     * Default placeholder shown in the message input when no custom placeholder is provided.
+     * @default "Write a message..."
+     */
+    readonly inputPlaceholder?: string;
+    /**
+     * Label shown above quoted reply previews in both composer and reply bubbles.
+     * @default "Replying to"
+     */
+    readonly replyingToLabel?: string;
+    /**
+     * Visible label for the explicit reply action on one message.
+     * @default "Reply"
+     */
+    readonly replyActionLabel?: string;
+    /**
+     * Accessible title for the explicit reply action on one message.
+     * @default "Reply to this message"
+     */
+    readonly replyActionTitle?: string;
+    /**
+     * Accessible label for the composer button that cancels reply mode.
+     * @default "Cancel reply"
+     */
+    readonly cancelReplyLabel?: string;
+    /**
+     * Label for the "Save" button in the chat actions bar.
+     * @default "Save"
+     */
+    readonly saveButtonLabel?: string;
+    /**
+     * Label for the "New chat" button in the chat actions bar.
+     * @default "New chat"
+     */
+    readonly newChatButtonLabel?: string;
+    /**
+     * Lifecycle badge label for messages being sent by the user.
+     * @default "Sending"
+     */
+    readonly lifecycleSending?: string;
+    /**
+     * Lifecycle badge label for queued messages.
+     * @default "Queued"
+     */
+    readonly lifecycleQueued?: string;
+    /**
+     * Lifecycle badge label for running messages.
+     * @default "Running"
+     */
+    readonly lifecycleRunning?: string;
+    /**
+     * Lifecycle badge label for failed messages.
+     * @default "Failed"
+     */
+    readonly lifecycleFailed?: string;
+    /**
+     * Lifecycle badge label for cancelled messages.
+     * @default "Cancelled"
+     */
+    readonly lifecycleCancelled?: string;
+    /**
+     * Lifecycle badge label for completed messages.
+     * @default "Completed"
+     */
+    readonly lifecycleCompleted?: string;
+    /**
+     * Accessible label for the tool call details modal dialog.
+     * @default "Tool call details"
+     */
+    readonly toolCallModalTitle?: string;
+    /**
+     * Accessible label for the close button in the tool call details modal.
+     * @default "Close tool call details"
+     */
+    readonly toolCallModalCloseLabel?: string;
+    /**
+     * Label for the "Copy" button in the tool call details modal footer.
+     * @default "Copy"
+     */
+    readonly toolCallModalCopyLabel?: string;
+    /**
+     * Label for the "Save" button in the tool call details modal footer.
+     * @default "Save"
+     */
+    readonly toolCallModalSaveLabel?: string;
+    /**
+     * Label for switching to the advanced view in the tool call details modal.
+     * @default "Advanced"
+     */
+    readonly toolCallModalAdvancedLabel?: string;
+    /**
+     * Label for switching back to the simple view in the tool call details modal.
+     * @default "Simple"
+     */
+    readonly toolCallModalSimpleLabel?: string;
+    /**
+     * Title shown when a timeout has been successfully scheduled.
+     * @default "Timeout scheduled"
+     */
+    readonly toolCallTimeoutTitle?: string;
+    /**
+     * Title shown when a timeout has been cancelled.
+     * @default "Timeout cancelled"
+     */
+    readonly toolCallTimeoutCancelledTitle?: string;
+    /**
+     * Title shown when a timeout status update is received.
+     * @default "Timeout update"
+     */
+    readonly toolCallTimeoutUpdateTitle?: string;
+    /**
+     * Label for the "Cancel" quick-action button inside the timeout modal.
+     * @default "Cancel"
+     */
+    readonly toolCallTimeoutCancelButton?: string;
+    /**
+     * Label for the "Snooze" quick-action button inside the timeout modal.
+     * @default "Snooze"
+     */
+    readonly toolCallTimeoutSnoozeButton?: string;
+    /**
+     * Label for the "View advanced" quick-action button inside the timeout modal.
+     * @default "View advanced"
+     */
+    readonly toolCallTimeoutViewAdvancedButton?: string;
+    /**
+     * Message shown in the timeout modal when presentation data is still loading.
+     * @default "Timeout details are still loading."
+     */
+    readonly toolCallTimeoutLoadingMessage?: string;
+    /**
+     * Message shown in the timeout modal when the scheduled time is unavailable.
+     * @default "Scheduled time is unavailable."
+     */
+    readonly toolCallTimeoutUnavailableMessage?: string;
+    /**
+     * Label prefix for the due date line in the timeout modal (e.g. "Date: 1/1/2025").
+     * @default "Date:"
+     */
+    readonly toolCallTimeoutDateLabel?: string;
+    /**
+     * Label prefix for the message line in the timeout modal.
+     * @default "Message:"
+     */
+    readonly toolCallTimeoutMessageLabel?: string;
+    /**
+     * Label prefix for the timezone line in the timeout modal.
+     * @default "Timezone:"
+     */
+    readonly toolCallTimeoutTimezoneLabel?: string;
+    /**
+     * Template used for timeout chips, for example `"Timeout: {time}"`.
+     * @default "Timeout: {time}"
+     */
+    readonly toolCallTimeoutChipLabel?: string;
+    /**
+     * Chip text used when a timeout has been cancelled.
+     * @default "Timeout cancelled"
+     */
+    readonly toolCallTimeoutChipCancelledLabel?: string;
+    /**
+     * Chip text used when a timeout is already inactive.
+     * @default "Timeout inactive"
+     */
+    readonly toolCallTimeoutChipInactiveLabel?: string;
+    /**
+     * Chip text used when a timeout status update is received.
+     * @default "Timeout update"
+     */
+    readonly toolCallTimeoutChipUpdatedLabel?: string;
+    /**
+     * Chip text used when no specific timeout time is available yet.
+     * @default "Timeout scheduled"
+     */
+    readonly toolCallTimeoutChipFallbackLabel?: string;
+    /**
+     * Primary timeout summary template shown in the modal, for example `"Scheduled for {time}."`.
+     * @default "Scheduled for {time}."
+     */
+    readonly toolCallTimeoutPrimaryScheduledLabel?: string;
+    /**
+     * Secondary timeout summary template shown in the modal, for example `"Will retry in {duration}."`.
+     * @default "Will retry in {duration}."
+     */
+    readonly toolCallTimeoutSecondaryDurationLabel?: string;
+    /**
+     * Primary timeout summary shown after cancellation.
+     * @default "The timeout has been cancelled."
+     */
+    readonly toolCallTimeoutPrimaryCancelledLabel?: string;
+    /**
+     * Primary timeout summary shown when the timeout is already inactive.
+     * @default "This timeout was already inactive."
+     */
+    readonly toolCallTimeoutPrimaryInactiveLabel?: string;
+    /**
+     * Primary timeout summary shown for generic timeout updates.
+     * @default "The timeout status has been updated."
+     */
+    readonly toolCallTimeoutPrimaryUpdatedLabel?: string;
+    /**
+     * Primary timeout summary shown when only limited data is available.
+     * @default "The timeout has been scheduled."
+     */
+    readonly toolCallTimeoutPrimaryFallbackLabel?: string;
+    /**
+     * Accessible label for the timeout quick-action button group.
+     * @default "Timeout quick actions"
+     */
+    readonly toolCallTimeoutActionGroupLabel?: string;
+    /**
+     * Accessible label for the "Cancel" timeout quick action.
+     * @default "Cancel timeout"
+     */
+    readonly toolCallTimeoutCancelAriaLabel?: string;
+    /**
+     * Accessible label for the "Snooze" timeout quick action.
+     * @default "Snooze timeout"
+     */
+    readonly toolCallTimeoutSnoozeAriaLabel?: string;
+    /**
+     * Accessible label for the "View advanced" timeout quick action.
+     * @default "View advanced timeout details"
+     */
+    readonly toolCallTimeoutViewAdvancedAriaLabel?: string;
+    /**
+     * Header title shown in the time-check modal.
+     * @default "Time at call"
+     */
+    readonly toolCallTimeTitle?: string;
+    /**
+     * Shown in the time modal when the time value is unknown.
+     * @default "Unknown time"
+     */
+    readonly toolCallTimeUnknown?: string;
+    /**
+     * Label prefix for the exact timestamp line in the time modal.
+     * @default "Timestamp of call:"
+     */
+    readonly toolCallTimeTimestampLabel?: string;
+    /**
+     * Template used for the time chip, for example `"Time: {time}"`.
+     * @default "{time}"
+     */
+    readonly toolCallTimeChipLabel?: string;
+    /**
+     * Template shown under the time clock panel for relative context.
+     * @default "Called {relative}"
+     */
+    readonly toolCallTimeRelativeLabel?: string;
+};
+/**
+ * Optional text overrides for localized timing metadata rendered next to message timestamps.
+ *
+ * @public exported from `@promptbook/components`
+ */
+export type ChatTimingTranslations = {
+    /**
+     * Template used for assistant response duration metadata.
+     *
+     * The `{duration}` placeholder is replaced with the compact duration label.
+     */
+    readonly answerDurationLabel?: string;
+};
 /**
  * Interface for sound system that can be passed to Chat component
  * This allows the chat to trigger sounds without tight coupling
@@ -43,6 +411,22 @@ export type ChatSoundSystem = {
     vibrate?(event: string): void;
 };
 /**
+ * Supported primary Enter-key behaviors for the chat composer.
+ *
+ * @private internal helper of `<Chat/>`
+ */
+type ChatEnterBehavior = 'SEND' | 'NEWLINE';
+/**
+ * Async resolver used when the host app wants to decide Enter behavior lazily.
+ *
+ * Returning `null` / `undefined` keeps the current composer text unchanged.
+ *
+ * @private internal helper of `<Chat/>`
+ */
+type ChatEnterBehaviorResolver = () => Promisable<ChatEnterBehavior | null | undefined>;
+/**
+ * Props for chat.
+ *
  * @public exported from `@promptbook/components`
  */
 export type ChatProps = {
@@ -71,7 +455,40 @@ export type ChatProps = {
      * - When set, the send textarea and button will be shown
      * - When undefined, the chat has no input and is read-only showing only the messages
      */
-    onMessage?(messageContent: string): Promisable<void>;
+    onMessage?(messageContent: string, attachments?: Array<{
+        name: string;
+        type: string;
+        url: string;
+    }>, replyingToMessage?: ChatMessage | null): Promisable<void>;
+    /**
+     * Called when user clicks a quick action button parsed from message markdown.
+     *
+     * The callback is responsible for running the browser-side action and may reject
+     * to keep the button available for another attempt.
+     */
+    onActionButton?(code: string): Promisable<void>;
+    /**
+     * Called when user clicks a quick message button parsed from message markdown.
+     *
+     * When not provided, quick message buttons fall back to `onMessage`.
+     */
+    onQuickMessageButton?(messageContent: string): Promisable<void>;
+    /**
+     * Optional callback fired when the user starts replying to one existing message.
+     */
+    onReplyToMessage?(message: ChatMessage): void;
+    /**
+     * Optional callback fired when the user cancels the currently composed reply.
+     */
+    onCancelReply?(): void;
+    /**
+     * Optional callback that determines whether one message can be replied to.
+     */
+    canReplyToMessage?(message: ChatMessage): boolean;
+    /**
+     * Optional message currently being quoted by the composer.
+     */
+    readonly replyingToMessage?: ChatMessage | null;
     /**
      * Optional callback
      *
@@ -79,6 +496,20 @@ export type ChatProps = {
      * - When undefined, no reset button will be shown
      */
     onReset?(): Promisable<void>;
+    /**
+     * Controls whether the reset button asks for native browser confirmation before calling `onReset`.
+     *
+     * @default true
+     */
+    readonly resetRequiresConfirmation?: boolean;
+    /**
+     * Optional navigation target for the action-bar "New chat" control.
+     *
+     * When provided, the control is rendered as a plain link instead of invoking `onReset`.
+     * This allows host applications to rely on browser-native navigation affordances such as
+     * right-click "Open in new tab/window".
+     */
+    readonly newChatButtonHref?: string_href;
     /**
      * Determines whether the voice recognition button is rendered
      */
@@ -100,6 +531,11 @@ export type ChatProps = {
      * @default true
      */
     readonly isSpeechPlaybackEnabled?: boolean;
+    /**
+     * Optional ElevenLabs voice ID that should be used when reading messages aloud.
+     * When not provided, the server uses the default configured voice.
+     */
+    readonly elevenLabsVoiceId?: string;
     /**
      * Optional placeholder message for the textarea
      *
@@ -110,6 +546,24 @@ export type ChatProps = {
      * Optional preset message in chat
      */
     readonly defaultMessage?: string;
+    /**
+     * Determines which action the plain `Enter` key triggers in the composer.
+     *
+     * `Ctrl+Enter` automatically performs the inverse action.
+     * `Shift+Enter` always inserts a new line.
+     *
+     * @default 'SEND'
+     */
+    readonly enterBehavior?: ChatEnterBehavior;
+    /**
+     * Optional async hook used when `enterBehavior` is not known yet.
+     *
+     * It is invoked after the user presses plain `Enter` and can resolve to the
+     * preferred behavior without coupling `<Chat/>` to any specific persistence UI.
+     *
+     * Returning `null` / `undefined` leaves the text unchanged.
+     */
+    readonly resolveEnterBehavior?: ChatEnterBehaviorResolver;
     /**
      * List of tasks that are currently in progress that should be displayed
      */
@@ -176,6 +630,11 @@ export type ChatProps = {
      * @default * All supported formats (see `string_chat_format_name` type)
      */
     readonly saveFormats?: Array<string_chat_format_name>;
+    /**
+     * Optional host-provided handlers that replace the default browser download flow
+     * for selected save formats.
+     */
+    readonly saveFormatHandlers?: ChatSaveFormatHandlerMap;
     /**
      * Is the writing textarea automatically focused?
      *
@@ -213,6 +672,10 @@ export type ChatProps = {
         instructions?: string;
         toolName: string;
     }>;
+    /**
+     * Optional cached agent metadata keyed by TEAM tool names to improve chip rendering.
+     */
+    readonly teamAgentProfiles?: Record<string, AgentChipData>;
     /**
      * Optional callback to create a new agent from the template.
      * If provided, renders the [Create Agent] button for book code blocks.
@@ -220,11 +683,11 @@ export type ChatProps = {
     onCreateAgent?: (bookContent: string) => void;
     /**
      * Optional callback for handling user feedback on messages
-     * When provided, star rating buttons (1-5 stars) will be displayed next to each message
+     * When provided, message feedback actions are displayed according to `feedbackMode`.
      *
      * @param feedback - Object containing the feedback data
      * @param feedback.message - The message being rated
-     * @param feedback.rating - Star rating from 1 to 5
+     * @param feedback.rating - Numeric feedback rating value
      * @param feedback.textRating - Optional text feedback/note from user
      * @param feedback.chatThread - Complete chat thread as string
      * @param feedback.expectedAnswer - Optional expected answer provided by user
@@ -238,6 +701,31 @@ export type ChatProps = {
         expectedAnswer: string | null;
         url: string;
     }): Promisable<void>;
+    /**
+     * Selects which feedback action UI is shown on assistant responses.
+     *
+     * @default 'stars'
+     */
+    readonly feedbackMode?: ChatFeedbackMode;
+    /**
+     * Optional localized feedback labels for buttons, modal copy, and status toasts.
+     */
+    readonly feedbackTranslations?: ChatFeedbackTranslations;
+    /**
+     * Optional localized labels used by timestamp metadata shown under messages.
+     */
+    readonly timingTranslations?: ChatTimingTranslations;
+    /**
+     * Optional localized labels for general Chat UI elements such as button labels,
+     * lifecycle state badges, tool call modal strings, and the default input placeholder.
+     */
+    readonly chatUiTranslations?: ChatUiTranslations;
+    /**
+     * Optional moment locale used when formatting message timestamps.
+     *
+     * When omitted, the current global moment locale is used.
+     */
+    readonly chatLocale?: string;
     /**
      * Optional callback for handling file uploads
      * When provided, enables file upload functionality via drag-and-drop and file button
@@ -258,9 +746,27 @@ export type ChatProps = {
      */
     onToolCallClick?: (toolCall: NonNullable<ChatMessage['toolCalls']>[number]) => void;
     /**
-     * Visual style of the chat component
+     * Visual presentation mode for chat messages.
+     *
+     * - `BUBBLE_MODE`: keeps the default bubble appearance for all messages.
+     * - `ARTICLE_MODE`: keeps user bubbles while rendering assistant replies as borderless article blocks.
+     *
+     * @default 'ARTICLE_MODE'
+     */
+    readonly visualMode?: ChatVisualMode;
+    /**
+     * Resolved visual theme used for chat surfaces, modals, and embedded Monaco viewers.
+     *
+     * Host applications should pass the final light/dark theme here instead of leaving
+     * `<Chat/>` to infer anything from the document.
+     *
+     * @default 'LIGHT'
      */
-    readonly visual: 'STANDALONE' | 'FULL_PAGE';
+    readonly theme?: 'LIGHT' | 'DARK';
+    /**
+     * Layout of the chat component
+     */
+    readonly layout: 'STANDALONE' | 'FULL_PAGE';
     /**
      * Optional array of effect configurations for chat animations
      * When provided, enables visual effects (confetti, hearts, etc.) based on emojis in messages
@@ -305,6 +811,4 @@ export type ChatProps = {
      */
     readonly soundSystem?: ChatSoundSystem;
 };
-/**
- * TODO: [☁️] Export component prop types only to `@promptbook/components` (not `@promptbook/types`)
- */
+export {};

package/esm/src/book-components/Chat/Chat/ChatRatingModal.d.ts

@@ -1,5 +1,6 @@
-import type { id } from '../../../types/typeAliases';
+import type { id } from '../../../types/string_token';
 import type { ChatMessage } from '../types/ChatMessage';
+import type { ChatFeedbackMode, ChatProps } from './ChatProps';
 /**
  * Props for the rating modal used in Chat.
  *
@@ -13,6 +14,14 @@ export type ChatRatingModalProps = {
     hoveredRating: number;
     messageRatings: Map<id, number>;
     textRating: string;
+    /**
+     * Chooses which feedback flow the modal should render.
+     */
+    feedbackMode: ChatFeedbackMode;
+    /**
+     * Optional localized labels used by feedback controls.
+     */
+    feedbackTranslations?: ChatProps['feedbackTranslations'];
     mode: 'LIGHT' | 'DARK';
     isMobile: boolean;
     onClose: () => void;

package/esm/src/book-components/Chat/Chat/ChatReplyPreview.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Props for one faded quoted-message preview rendered inside the chat UI.
+ *
+ * @private component of `<Chat/>`
+ */
+export type ChatReplyPreviewProps = {
+    readonly label: string;
+    readonly senderLabel: string;
+    readonly previewText: string;
+    readonly className?: string;
+    readonly dismissLabel?: string;
+    readonly onDismiss?: () => void;
+};
+/**
+ * Renders the common faded preview used for reply bubbles and composer reply mode.
+ *
+ * @private component of `<Chat/>`
+ */
+export declare function ChatReplyPreview(props: ChatReplyPreviewProps): import("react/jsx-runtime").JSX.Element;

package/esm/src/book-components/Chat/Chat/ChatSelfLearningSummary.d.ts

@@ -19,6 +19,3 @@ export type SelfLearningSummaryData = {
  * @private component of `<Chat/>`
  */
 export declare function buildSelfLearningSummary(toolCall: NonNullable<ChatMessage['toolCalls']>[number], resultRaw: TODO_any): SelfLearningSummaryData;
-/**
- * Note: [💞] Ignore a discrepancy between file name and entity name, BUT maybe rename to `buildSelfLearningSummary`
- */