@promptbook/javascript 0.112.0-31 → 0.112.0-32

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

@@ -24,6 +24,15 @@ export type ChatFeedbackResponse = {
  * @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.
  *
@@ -103,6 +112,257 @@ export type ChatFeedbackTranslations = {
      */
     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 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
@@ -179,6 +439,12 @@ export type ChatProps = {
      * 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
      *
@@ -388,6 +654,21 @@ export type ChatProps = {
      * 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
@@ -407,6 +688,15 @@ export type ChatProps = {
      * Called when a tool call chiplet is clicked.
      */
     onToolCallClick?: (toolCall: NonNullable<ChatMessage['toolCalls']>[number]) => void;
+    /**
+     * 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 'BUBBLE_MODE'
+     */
+    readonly CHAT_VISUAL_MODE?: ChatVisualMode;
     /**
      * Visual style of the chat component
      */

package/umd/src/book-components/Chat/Chat/ChatToolCallModal.d.ts

@@ -25,6 +25,22 @@ export type ChatToolCallModalProps = {
      * Optional cached team agent metadata keyed by TEAM tool name.
      */
     teamAgentProfiles?: Record<string, AgentChipData>;
+    /**
+     * Optional localized labels for the tool call modal UI elements.
+     */
+    chatUiTranslations?: import('./ChatProps').ChatUiTranslations;
+    /**
+     * Optional BCP-47 locale string used to format time labels in the modal.
+     * When omitted the browser/OS default locale is used.
+     */
+    locale?: string;
+    /**
+     * Optional list of tools that were available to the model during the turn that produced this tool call.
+     *
+     * When provided, the advanced view includes an "Available tools" payload section so developers can
+     * inspect what capabilities the model had access to at the exact moment of the request.
+     */
+    availableTools?: ChatMessage['availableTools'];
 };
 /**
  * Modal that renders rich tool call details for chat chiplets.

package/umd/src/book-components/Chat/Chat/renderAdvancedToolCallDetails.d.ts

@@ -14,6 +14,10 @@ type AdvancedToolCallDetailsOptions = {
      * Optional mapping of tool titles.
      */
     toolTitles?: Record<string, string>;
+    /**
+     * Optional list of tools that were available to the model during the turn that produced this tool call.
+     */
+    availableTools?: ChatMessage['availableTools'];
 };
 /**
  * Renders a technical view with raw tool input/output payloads.

package/umd/src/book-components/Chat/Chat/renderToolCallDetails.d.ts

@@ -29,6 +29,15 @@ type ToolCallDetailsOptions = {
      * Requests switching the modal into advanced technical mode.
      */
     onRequestAdvancedView?: () => void;
+    /**
+     * Optional BCP-47 locale string used to format time labels.
+     * When omitted the browser/OS default locale is used.
+     */
+    locale?: string;
+    /**
+     * Optional localized label overrides for the tool call modal UI.
+     */
+    chatUiTranslations?: import('./ChatProps').ChatUiTranslations;
 };
 /**
  * Renders the detail view for a single tool call.

package/umd/src/book-components/Chat/MarkdownContent/MarkdownContent.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import type { string_markdown } from '../../../types/typeAliases';
 type MarkdownContentProps = {
     content: string_markdown;
@@ -9,7 +10,7 @@ type MarkdownContentProps = {
  *
  * @public exported from `@promptbook/components`
  */
-export declare function MarkdownContent(props: MarkdownContentProps): import("react/jsx-runtime").JSX.Element;
+export declare const MarkdownContent: import("react").NamedExoticComponent<MarkdownContentProps>;
 export {};
 /**
  * TODO: !!! Split into multiple files

package/umd/src/book-components/Chat/MarkdownContent/MarkdownContent.test.d.ts

@@ -0,0 +1,2 @@
+/** @jest-environment jsdom */
+export {};

package/umd/src/book-components/Chat/hooks/useChatCompleteNotification.d.ts

@@ -0,0 +1,18 @@
+import type { ChatSoundSystem } from '../Chat/ChatProps';
+import type { ChatMessage } from '../types/ChatMessage';
+/**
+ * Plays the "message received" sound + vibration exactly once when the last
+ * assistant message transitions to a completed / finalized state.
+ *
+ * Notifications are suppressed for:
+ * - Every streaming chunk / intermediate content update
+ * - `message_typing` lifecycle events before the message is finalized
+ * - Re-renders of an already-notified completed message (idempotent)
+ * - User-originated messages
+ *
+ * @param messages - Current list of chat messages
+ * @param soundSystem - Optional sound system instance; no-op when absent
+ *
+ * @private internal hook of `<Chat/>`
+ */
+export declare function useChatCompleteNotification(messages: ReadonlyArray<ChatMessage>, soundSystem: ChatSoundSystem | undefined): void;

package/umd/src/book-components/Chat/hooks/useChatCompleteNotification.test.d.ts

@@ -0,0 +1,2 @@
+/** @jest-environment jsdom */
+export {};

package/umd/src/book-components/Chat/types/ChatMessage.d.ts

@@ -1,6 +1,9 @@
 import { Message } from '../../../types/Message';
+import type { LlmToolDefinition } from '../../../types/LlmToolDefinition';
+import type { ChatModelRequirements } from '../../../types/ModelRequirements';
 import type { ToolCall } from '../../../types/ToolCall';
-import type { id, string_date_iso8601, string_markdown } from '../../../types/typeAliases';
+import type { TODO_object } from '../../../utils/organization/TODO_object';
+import type { id, Parameters, string_date_iso8601, string_markdown, string_prompt, string_title } from '../../../types/typeAliases';
 export type ChatToolCall = ToolCall;
 /**
  * One item in a user-facing progress card shown while assistant response is still running.
@@ -52,6 +55,63 @@ export type ChatProgressCard = {
      */
     readonly isVisible?: boolean;
 };
+/**
+ * Serializable prompt snapshot stored alongside one assistant message for debugging and inspection.
+ */
+type ChatMessagePrompt = {
+    /**
+     * Human-readable label used for the prompt execution.
+     */
+    readonly title: string_title;
+    /**
+     * User-facing chat content submitted into the prompt pipeline.
+     */
+    readonly content: string_prompt;
+    /**
+     * Resolved prompt parameters passed into the agent turn.
+     */
+    readonly parameters: Parameters;
+    /**
+     * Chat-model requirements used when the turn was executed.
+     */
+    readonly modelRequirements: ChatModelRequirements;
+    /**
+     * Prior thread history provided to the prompt.
+     */
+    readonly thread?: ReadonlyArray<ChatMessage>;
+    /**
+     * Attachments submitted with the user turn.
+     */
+    readonly attachments?: ReadonlyArray<{
+        name: string;
+        type: string;
+        url: string;
+    }>;
+    /**
+     * Runtime tools explicitly passed on the chat prompt object.
+     */
+    readonly tools?: ReadonlyArray<LlmToolDefinition>;
+    /**
+     * Full list of tools available to the model for this turn.
+     */
+    readonly availableTools?: ReadonlyArray<LlmToolDefinition>;
+    /**
+     * Tool calls associated with the generated message, duplicated here for raw prompt inspection.
+     */
+    readonly toolCalls?: ReadonlyArray<ChatToolCall>;
+    /**
+     * Completed tool calls associated with the generated message, duplicated here for raw prompt inspection.
+     */
+    readonly completedToolCalls?: ReadonlyArray<ChatToolCall>;
+    /**
+     * Provider-facing prompt text after agent/runtime preparation, when available.
+     */
+    readonly rawPromptContent?: string_prompt;
+    /**
+     * Provider-facing raw request payload, when available.
+     */
+    readonly rawRequest?: TODO_object | null;
+};
 /**
  * Represents a single message within a chat interface.
  *
@@ -165,7 +225,23 @@ export type ChatMessage = Omit<Message<id>, 'direction' | 'recipients' | 'thread
      * Optional structured progress-card payload shown while a response is still in progress.
      */
     readonly progressCard?: ChatProgressCard;
+    /**
+     * Optional list of tools that were available to the model when generating this message.
+     *
+     * This field is populated by the server from the exact tool definitions passed to the LLM
+     * request so developers can inspect what capabilities the model had access to during
+     * each conversation turn.
+     */
+    readonly availableTools?: ReadonlyArray<LlmToolDefinition>;
+    /**
+     * Optional prompt snapshot from which this message was generated.
+     *
+     * Intended for advanced/raw inspection so developers can see the exact chat prompt,
+     * resolved parameters, tool availability, and provider payload associated with one turn.
+     */
+    readonly prompt?: ChatMessagePrompt;
 };
+export {};
 /**
  * TODO: Make all fields readonly
  * TODO: Delete `expectedAnswer` from ChatMessage

package/umd/src/book-components/Chat/utils/formatToolCallDateTime.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Locale-aware date/time labels derived from one tool-call timestamp.
+ *
+ * @private utility of `<Chat/>`
+ */
+type ToolCallDateTimeLabels = {
+    /**
+     * Primary local time label shown in chips and clock panels.
+     */
+    readonly localTimeLabel: string;
+    /**
+     * Local calendar date label shown under the primary time.
+     */
+    readonly localDateLabel: string;
+    /**
+     * Exact local timestamp label used in detail sections.
+     */
+    readonly localDateTimeLabel: string;
+    /**
+     * Relative label such as `in 5 minutes` or `2 minutes ago`.
+     */
+    readonly relativeTimeLabel: string | null;
+};
+/**
+ * Formats one tool-call timestamp into shared locale-aware labels.
+ *
+ * @param date - Timestamp to format.
+ * @param options - Optional locale and relative-time reference point.
+ * @returns Shared labels consumed by tool-call chips and modals.
+ *
+ * @private utility of `<Chat/>`
+ */
+export declare function formatToolCallDateTime(date: Date, options?: {
+    locale?: string;
+    currentDate?: Date;
+}): ToolCallDateTimeLabels;
+export {};

package/umd/src/book-components/Chat/utils/formatToolCallLocalTime.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Formats a Date as a locale-aware short time string (e.g. "5:30 PM" or "17:30").
+ *
+ * @param date - Date to format.
+ * @param locale - Optional BCP-47 locale string (e.g. `"en"`, `"cs"`).
+ *                 When omitted the browser/OS default locale is used.
+ * @returns Formatted time string such as `"5:30 PM"` or `"17:30"`.
+ *
+ * @private utility of `<Chat/>`
+ */
+export declare function formatToolCallLocalTime(date: Date, locale?: string): string;

package/umd/src/book-components/Chat/utils/formatToolCallTranslationTemplate.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Applies `{placeholder}` values to one tool-call translation template.
+ *
+ * @param template - Template from the host application or fallback copy.
+ * @param variables - Placeholder values keyed by variable name.
+ * @returns Formatted string ready for rendering.
+ *
+ * @private utility of `<Chat/>`
+ */
+export declare function formatToolCallTranslationTemplate(template: string, variables: Record<string, string | number>): string;

package/umd/src/book-components/Chat/utils/getChatMessageTimingDisplay.d.ts

@@ -1,3 +1,4 @@
+import 'moment/locale/cs';
 import type { ChatMessage } from '../types/ChatMessage';
 /**
  * Display-ready timestamp values for a chat message.
@@ -21,6 +22,9 @@ export type ChatMessageTimingDisplay = {
 /**
  * Builds display-ready timestamp and duration labels for a chat message.
  *
+ * @param message - Message with optional timestamp metadata.
+ * @param locale - Optional moment locale used for formatting.
+ *
  * @private utility of `<Chat/>` component
  */
-export declare function getChatMessageTimingDisplay(message: ChatMessage): ChatMessageTimingDisplay | null;
+export declare function getChatMessageTimingDisplay(message: ChatMessage, locale?: string): ChatMessageTimingDisplay | null;

package/umd/src/book-components/Chat/utils/getToolCallChipletInfo.d.ts

@@ -15,6 +15,25 @@ export type ToolCallChipletInfo = {
      */
     agentData?: AgentChipData;
 };
+/**
+ * Optional user-facing title overrides for technical tool names.
+ *
+ * @private utility of `<Chat/>`
+ */
+type ToolCallTitleOverrides = Readonly<Record<string, string>>;
+/**
+ * Optional localized labels used for user-facing chip text.
+ *
+ * @private utility of `<Chat/>`
+ */
+type ToolCallChipTranslations = {
+    readonly toolCallTimeChipLabel?: string;
+    readonly toolCallTimeoutChipLabel?: string;
+    readonly toolCallTimeoutChipCancelledLabel?: string;
+    readonly toolCallTimeoutChipInactiveLabel?: string;
+    readonly toolCallTimeoutChipUpdatedLabel?: string;
+    readonly toolCallTimeoutChipFallbackLabel?: string;
+};
 /**
  * Builds display text for a tool call chiplet.
  *
@@ -35,6 +54,12 @@ export declare const TOOL_TITLES: Record<string, {
 /**
  * Gets the chiplet information including text and agent data (for team tools).
  *
+ * @param toolCall - Tool call to build chiplet info for.
+ * @param locale - Optional BCP-47 locale string used to format time labels.
+ * @param titleOverrides - Optional localized titles keyed by tool name.
+ * @param chipTranslations - Optional localized chip templates for time-related tools.
+ *
  * @private [🧠] Maybe public?
  */
-export declare function getToolCallChipletInfo(toolCall: ToolCall): ToolCallChipletInfo;
+export declare function getToolCallChipletInfo(toolCall: ToolCall, locale?: string, titleOverrides?: ToolCallTitleOverrides, chipTranslations?: ToolCallChipTranslations): ToolCallChipletInfo;
+export {};