@promptbook/color 0.105.0-9 → 0.105.0

package/esm/typings/src/book-components/Chat/Chat/ChatMessageItem.d.ts

@@ -2,6 +2,7 @@
 import type { id } from '../../../types/typeAliases';
 import type { ChatMessage } from '../types/ChatMessage';
 import type { ChatParticipant } from '../types/ChatParticipant';
+import { type ParsedCitation } from '../utils/parseCitationsFromContent';
 import type { ChatProps } from './ChatProps';
 /**
  * Props for the `ChatMessageItem` component
@@ -33,11 +34,42 @@ type ChatMessageItemProps = Pick<ChatProps, 'onMessage' | 'participants'> & {
      * Called when the create agent button is pressed for book code blocks.
      */
     onCreateAgent?: (bookContent: string) => void;
+    /**
+     * Optional mapping of technical tool names to human-readable titles.
+     * e.g., { "web_search": "Searching the web..." }
+     */
+    toolTitles?: Record<string, string>;
+    /**
+     * Optional metadata about teammates for team tool calls
+     * Maps tool name to agent information
+     */
+    teammates?: TeammatesMap;
+    /**
+     * Called when a tool call chiplet is clicked.
+     */
+    onToolCallClick?: (toolCall: NonNullable<ChatMessage['toolCalls']>[number]) => void;
+    /**
+     * Called when a source citation chip is clicked.
+     */
+    onCitationClick?: (citation: ParsedCitation) => void;
+};
+/**
+ * Metadata for a teammate agent tool.
+ */
+type TeammateMetadata = {
+    url: string;
+    label?: string;
+    instructions?: string;
+    toolName: string;
 };
+/**
+ * Lookup map of teammate metadata by tool name.
+ */
+type TeammatesMap = Record<string, TeammateMetadata>;
 /**
  * Renders a single chat message item with avatar, content, buttons, and rating.
  *
  * @private internal subcomponent of `<Chat>` component
  */
-export declare const ChatMessageItem: import("react").MemoExoticComponent<({ message, participant, participants, isLastMessage, onMessage, setExpandedMessageId, isExpanded, currentRating, handleRating, mode, isCopyButtonEnabled, isFeedbackEnabled, onCopy, onCreateAgent, }: ChatMessageItemProps) => import("react/jsx-runtime").JSX.Element>;
+export declare const ChatMessageItem: import("react").MemoExoticComponent<(props: ChatMessageItemProps) => import("react/jsx-runtime").JSX.Element>;
 export {};

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

@@ -1,11 +1,26 @@
 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 { string_chat_format_name } from '../save/_common/string_chat_format_name';
 import type { ChatMessage } from '../types/ChatMessage';
 import type { ChatParticipant } from '../types/ChatParticipant';
-import { string_color } from '../../../types/typeAliases';
-import { Color } from '../../../_packages/color.index';
-import { SpeechRecognition } from '../../../types/SpeechRecognition';
+/**
+ * Interface for sound system that can be passed to Chat component
+ * This allows the chat to trigger sounds without tight coupling
+ *
+ * @public exported from `@promptbook/components`
+ */
+export type ChatSoundSystem = {
+    /**
+     * @@@
+     */
+    play(event: string): Promise<void>;
+    isEnabled(): boolean;
+    setEnabled(enabled: boolean): void;
+    toggle(): boolean;
+};
 /**
  * @public exported from `@promptbook/components`
  */
@@ -149,6 +164,26 @@ export type ChatProps = {
      * Keys should match ChatMessage.from values (e.g., 'USER', 'AGENT_{id}', etc.)
      */
     readonly participants?: ReadonlyArray<ChatParticipant>;
+    /**
+     * Optional mapping of technical tool names to human-readable titles.
+     * e.g., { "web_search": "Searching the web..." }
+     */
+    readonly toolTitles?: Record<string, string>;
+    /**
+     * Optional metadata about teammates for team tool calls
+     * Maps tool name to agent information
+     */
+    readonly teammates?: Record<string, {
+        url: string;
+        label?: string;
+        instructions?: string;
+        toolName: string;
+    }>;
+    /**
+     * Optional callback to create a new agent from the template.
+     * If provided, renders the [Create Agent] button for book code blocks.
+     */
+    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
@@ -185,10 +220,56 @@ export type ChatProps = {
      */
     isCopyButtonEnabled?: boolean;
     /**
-     * Optional callback for creating an agent from a book code block.
-     * When provided, "Create Agent" buttons will be shown for book code blocks.
+     * Called when a tool call chiplet is clicked.
      */
-    onCreateAgent?: (bookContent: string) => void;
+    onToolCallClick?: (toolCall: NonNullable<ChatMessage['toolCalls']>[number]) => void;
+    /**
+     * Visual style of the chat component
+     */
+    readonly visual: 'STANDALONE' | 'FULL_PAGE';
+    /**
+     * Optional array of effect configurations for chat animations
+     * When provided, enables visual effects (confetti, hearts, etc.) based on emojis in messages
+     *
+     * Example:
+     * ```typescript
+     * [
+     *   { trigger: '🎉', effectType: 'CONFETTI' },
+     *   { trigger: /❤️|💙|💚/, effectType: 'HEARTS' }
+     * ]
+     * ```
+     */
+    readonly effectConfigs?: ReadonlyArray<{
+        trigger: string | RegExp;
+        effectType: string;
+    }>;
+    /**
+     * Optional sound system for playing chat sounds
+     * When provided, enables sound effects for message events, button clicks, and visual effects
+     *
+     * The sound system should implement the ChatSoundSystem interface:
+     * - play(event: string): Plays a sound for the given event
+     * - isEnabled(): Returns whether sounds are enabled
+     * - setEnabled(enabled: boolean): Enables or disables sounds
+     * - toggle(): Toggles sound on/off and returns the new state
+     *
+     * Supported events:
+     * - 'message_send': When user sends a message
+     * - 'message_receive': When agent sends a message
+     * - 'message_typing': When agent is typing/thinking
+     * - 'button_click': When any button is clicked
+     * - 'effect_confetti': When confetti effect is triggered
+     * - 'effect_hearts': When hearts effect is triggered
+     *
+     * @example
+     * ```typescript
+     * import { createDefaultSoundSystem } from '@/utils/sound/createDefaultSoundSystem';
+     *
+     * const soundSystem = createDefaultSoundSystem();
+     * <Chat soundSystem={soundSystem} ... />
+     * ```
+     */
+    readonly soundSystem?: ChatSoundSystem;
 };
 /**
  * TODO: [☁️] Export component prop types only to `@promptbook/components` (not `@promptbook/types`)

package/esm/typings/src/book-components/Chat/Chat/ChatSoundToggle.d.ts

@@ -0,0 +1,23 @@
+import type { ChatSoundSystem } from './ChatProps';
+/**
+ * Props for the ChatSoundToggle component
+ */
+export type ChatSoundToggleProps = {
+    /**
+     * The sound system instance
+     */
+    soundSystem: ChatSoundSystem;
+    /**
+     * Optional CSS class name
+     */
+    className?: string;
+};
+/**
+ * ChatSoundToggle component
+ *
+ * Renders a toggle button/checkbox to enable/disable chat sounds.
+ * The state is persisted in localStorage via the SoundSystem.
+ *
+ * @public exported from `@promptbook/components`
+ */
+export declare function ChatSoundToggle(props: ChatSoundToggleProps): import("react/jsx-runtime").JSX.Element;

package/esm/typings/src/book-components/Chat/Chat/ClockIcon.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Renders a nice clock icon with a specific time.
+ *
+ * @private internal subcomponent of `<Chat>` component
+ */
+export declare function ClockIcon({ date, size }: {
+    date: Date;
+    size?: number;
+}): import("react/jsx-runtime").JSX.Element;

package/esm/typings/src/book-components/Chat/LlmChat/FriendlyErrorMessage.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Error types for LlmChat component
+ *
+ * This is a minimal type definition for use in the Promptbook Engine component.
+ * The full implementation is in the Agent Server.
+ */
+export type FriendlyErrorMessage = {
+    /**
+     * @@@
+     */
+    title: string;
+    /**
+     * @@@
+     */
+    message: string;
+    /**
+     * @@@
+     */
+    canRetry: boolean;
+};

package/esm/typings/src/book-components/Chat/LlmChat/LlmChatProps.d.ts

@@ -57,4 +57,17 @@ export type LlmChatProps = Omit<ChatProps, 'messages' | 'onMessage' | 'onChange'
      * This is useful for seamless transitions from other pages.
      */
     readonly autoExecuteMessage?: string;
+    /**
+     * Optional mapping of technical tool names to human-readable titles.
+     * e.g., { "web_search": "Searching the web..." }
+     */
+    readonly toolTitles?: Record<string, string>;
+    /**
+     * Optional custom error handler that will be called when an error occurs during chat.
+     * If not provided, errors will be displayed as messages in the chat.
+     *
+     * @param error - The error that occurred
+     * @param retry - Function to retry the last failed message
+     */
+    onError?(error: unknown, retry: () => void): void;
 };

package/esm/typings/src/book-components/Chat/SourceChip/SourceChip.d.ts

@@ -0,0 +1,35 @@
+import type { ParsedCitation } from '../utils/parseCitationsFromContent';
+/**
+ * Props for SourceChip component
+ */
+export type SourceChipProps = {
+    /**
+     * Citation data to display
+     */
+    citation: ParsedCitation;
+    /**
+     * Click handler
+     */
+    onClick?: (citation: ParsedCitation) => void;
+    /**
+     * Additional CSS class name
+     */
+    className?: string;
+};
+/**
+ * SourceChip component - displays a chip with source document information
+ *
+ * This component is used to display RAG source citations in chat messages.
+ * It displays the source document name and citation ID.
+ *
+ * @example
+ * ```tsx
+ * <SourceChip
+ *   citation={{ id: '5:13', source: 'document.pdf' }}
+ *   onClick={(citation) => console.log('clicked', citation)}
+ * />
+ * ```
+ *
+ * @private utility of `ChatMessageItem` component
+ */
+export declare function SourceChip({ citation, onClick, className }: SourceChipProps): import("react/jsx-runtime").JSX.Element;

package/esm/typings/src/book-components/Chat/SourceChip/index.d.ts

@@ -0,0 +1,2 @@
+export { SourceChip } from './SourceChip';
+export type { SourceChipProps } from './SourceChip';

package/esm/typings/src/book-components/Chat/effects/ChatEffectsSystem.d.ts

@@ -0,0 +1,14 @@
+import type { ChatEffectsSystemProps } from './types/ChatEffectsSystemProps';
+/**
+ * ChatEffectsSystem component
+ * Monitors chat messages and triggers visual effects based on emoji content
+ *
+ * This component:
+ * - Tracks which messages have already been processed
+ * - Detects emojis in new agent messages
+ * - Triggers appropriate effects (confetti, hearts, etc.)
+ * - Handles effect lifecycle (creation, completion, cleanup)
+ *
+ * @public exported from `@promptbook/components`
+ */
+export declare function ChatEffectsSystem(props: ChatEffectsSystemProps): import("react/jsx-runtime").JSX.Element;

package/esm/typings/src/book-components/Chat/effects/components/ConfettiEffect.d.ts

@@ -0,0 +1,18 @@
+type ConfettiEffectProps = {
+    /**
+     * Unique identifier for this effect instance
+     */
+    effectId: string;
+    /**
+     * Callback when the effect completes
+     */
+    onComplete?: () => void;
+};
+/**
+ * Confetti effect component
+ * Renders falling confetti particles from the top of the screen
+ *
+ * @public exported from `@promptbook/components`
+ */
+export declare function ConfettiEffect(props: ConfettiEffectProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/esm/typings/src/book-components/Chat/effects/components/HeartsEffect.d.ts

@@ -0,0 +1,18 @@
+type HeartsEffectProps = {
+    /**
+     * Unique identifier for this effect instance
+     */
+    effectId: string;
+    /**
+     * Callback when the effect completes
+     */
+    onComplete?: () => void;
+};
+/**
+ * Hearts effect component
+ * Renders floating hearts that rise from the bottom of the screen
+ *
+ * @public exported from `@promptbook/components`
+ */
+export declare function HeartsEffect(props: HeartsEffectProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/esm/typings/src/book-components/Chat/effects/configs/defaultEffectConfigs.d.ts

@@ -0,0 +1,7 @@
+import type { ChatEffectConfig } from '../types/ChatEffectConfig';
+/**
+ * Default effect configurations for common chat emojis
+ *
+ * @public exported from `@promptbook/components`
+ */
+export declare const defaultEffectConfigs: ReadonlyArray<ChatEffectConfig>;

package/esm/typings/src/book-components/Chat/effects/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Chat effects system exports
+ *
+ * @packageDocumentation
+ */
+export { ChatEffectsSystem } from './ChatEffectsSystem';
+export { ConfettiEffect } from './components/ConfettiEffect';
+export { HeartsEffect } from './components/HeartsEffect';
+export { defaultEffectConfigs } from './configs/defaultEffectConfigs';
+export type { ChatEffect } from './types/ChatEffect';
+export type { ChatEffectConfig } from './types/ChatEffectConfig';
+export type { ChatEffectsSystemProps } from './types/ChatEffectsSystemProps';
+export type { ChatEffectType } from './types/ChatEffectType';
+export { detectEffects } from './utils/detectEffects';
+/**
+ * TODO: !!!!! To rules: Do not create index files that re-ex-port from multiple files, import directly instead or use full register
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ */

package/esm/typings/src/book-components/Chat/effects/types/ChatEffect.d.ts

@@ -0,0 +1,20 @@
+import type { ChatEffectType } from './ChatEffectType';
+/**
+ * Represents a chat effect instance
+ *
+ * @public exported from `@promptbook/components`
+ */
+export type ChatEffect = {
+    /**
+     * Unique identifier for this effect instance
+     */
+    id: string;
+    /**
+     * Type of effect
+     */
+    type: ChatEffectType;
+    /**
+     * Timestamp when the effect was triggered
+     */
+    timestamp: number;
+};

package/esm/typings/src/book-components/Chat/effects/types/ChatEffectConfig.d.ts

@@ -0,0 +1,21 @@
+import type { ChatEffectType } from './ChatEffectType';
+/**
+ * Configuration for a chat effect trigger
+ *
+ * @public exported from `@promptbook/components`
+ */
+export type ChatEffectConfig = {
+    /**
+     * Emoji or pattern that triggers this effect
+     */
+    trigger: string | RegExp;
+    /**
+     * Type of effect to trigger
+     */
+    effectType: ChatEffectType;
+    /**
+     * Whether to match all heart emojis (❤️, 💙, 💚, etc.)
+     * Only relevant for heart effects
+     */
+    matchAllHeartEmojis?: boolean;
+};

package/esm/typings/src/book-components/Chat/effects/types/ChatEffectType.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Types of chat effects that can be triggered
+ *
+ * @public exported from `@promptbook/components`
+ */
+export type ChatEffectType = 'CONFETTI' | 'HEARTS';

package/esm/typings/src/book-components/Chat/effects/types/ChatEffectsSystemProps.d.ts

@@ -0,0 +1,32 @@
+import type { ChatSoundSystem } from '../../Chat/ChatProps';
+import type { ChatMessage } from '../../types/ChatMessage';
+import type { ChatEffectConfig } from './ChatEffectConfig';
+/**
+ * Props for the ChatEffectsSystem component
+ *
+ * @public exported from `@promptbook/components`
+ */
+export type ChatEffectsSystemProps = {
+    /**
+     * Array of chat messages to monitor for effect triggers
+     */
+    messages: ReadonlyArray<ChatMessage>;
+    /**
+     * Array of effect configurations
+     * Defines which emojis/patterns trigger which effects
+     */
+    effectConfigs: ReadonlyArray<ChatEffectConfig>;
+    /**
+     * Optional filter function to determine if a message should trigger effects
+     * By default, only agent messages trigger effects
+     */
+    shouldTriggerEffect?: (message: ChatMessage) => boolean;
+    /**
+     * CSS class name for the effects container
+     */
+    className?: string;
+    /**
+     * Optional sound system to play sounds when effects are triggered
+     */
+    soundSystem?: ChatSoundSystem;
+};

package/esm/typings/src/book-components/Chat/effects/utils/detectEffects.d.ts

@@ -0,0 +1,12 @@
+import type { ChatMessage } from '../../types/ChatMessage';
+import type { ChatEffectConfig } from '../types/ChatEffectConfig';
+import type { ChatEffectType } from '../types/ChatEffectType';
+/**
+ * Detects which effects should be triggered based on message content
+ *
+ * @param message - The chat message to analyze
+ * @param effectConfigs - Array of effect configurations
+ * @returns Array of unique effect types to trigger
+ * @private utility function of Effects system
+ */
+export declare function detectEffects(message: ChatMessage, effectConfigs: ReadonlyArray<ChatEffectConfig>): ChatEffectType[];

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

@@ -1,5 +1,7 @@
 import { Message } from '../../../types/Message';
+import type { ToolCall } from '../../../types/ToolCall';
 import type { id, string_markdown } from '../../../types/typeAliases';
+export type ChatToolCall = ToolCall;
 /**
  * Represents a single message within a chat interface.
  *
@@ -36,12 +38,17 @@ export type ChatMessage = Omit<Message<id>, 'direction' | 'recipients' | 'thread
     /**
      * Optional tool calls made during the execution
      */
-    readonly ongoingToolCalls?: ReadonlyArray<{
-        /**
-         * Name of the tool
-         */
-        readonly name: string;
-    }>;
+    readonly ongoingToolCalls?: ReadonlyArray<ChatToolCall>;
+    /**
+     * Optional tool calls used to produce this message.
+     */
+    readonly toolCalls?: ReadonlyArray<ChatToolCall>;
+    /**
+     * Optional tool calls that have been completed
+     *
+     * @deprecated Use `toolCalls` instead.
+     */
+    readonly completedToolCalls?: ReadonlyArray<ChatToolCall>;
     /**
      * Optional file attachments
      */
@@ -59,6 +66,27 @@ export type ChatMessage = Omit<Message<id>, 'direction' | 'recipients' | 'thread
          */
         url: string;
     }>;
+    /**
+     * Optional source citations/annotations (from RAG systems like OpenAI Assistants)
+     */
+    readonly citations?: ReadonlyArray<{
+        /**
+         * The unique identifier for the citation (e.g., "5:13")
+         */
+        id: string;
+        /**
+         * The source document name (e.g., "document.pdf")
+         */
+        source: string;
+        /**
+         * Optional URL to the source document
+         */
+        url?: string;
+        /**
+         * Optional preview/excerpt from the source
+         */
+        excerpt?: string;
+    }>;
 };
 /**
  * TODO: Make all fields readonly

package/esm/typings/src/book-components/Chat/types/ChatParticipant.d.ts

@@ -31,6 +31,14 @@ export type ChatParticipant = {
      * Agent source for avatar profile
      */
     agentSource?: string_book;
+    /**
+     * Knowledge sources (documents, URLs) used by the agent
+     * Used for resolving document citations when the agent references sources
+     */
+    knowledgeSources?: Array<{
+        url: string;
+        filename: string;
+    }>;
 };
 /**
  * TODO: [🕛] Unite `AgentBasicInformation`, `ChatParticipant`, `LlmExecutionTools` +  `LlmToolsMetadata`

package/esm/typings/src/book-components/Chat/utils/createTeamToolNameFromUrl.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Builds a TEAM tool name from a teammate agent URL.
+ *
+ * @private utility of chat components
+ */
+export declare function createTeamToolNameFromUrl(url: string): string;
+/**
+ * Checks whether a tool name belongs to a TEAM tool.
+ *
+ * @private utility of chat components
+ */
+export declare function isTeamToolName(name: string): boolean;

package/esm/typings/src/book-components/Chat/utils/getToolCallChipletText.d.ts

@@ -0,0 +1,40 @@
+import type { ToolCall } from '../../../types/ToolCall';
+import type { AgentChipData } from '../AgentChip';
+/**
+ * Utility to format tool call information for user-friendly display.
+ */
+/**
+ * Tool call chiplet information including agent data for team tools
+ */
+export type ToolCallChipletInfo = {
+    /**
+     * Display text for the chiplet
+     */
+    text: string;
+    /**
+     * Agent data for team tools (if applicable)
+     */
+    agentData?: AgentChipData;
+};
+/**
+ * Technical to user-friendly tool names and emojis
+ *
+ * @private [🧠] Maybe public?
+ */
+export declare const TOOL_TITLES: Record<string, {
+    title: string;
+    emoji: string;
+}>;
+/**
+ * Gets the user-friendly text for a tool call chiplet.
+ *
+ * @deprecated Use getToolCallChipletInfo instead which returns both text and agent data
+ * @private [🧠] Maybe public?
+ */
+export declare function getToolCallChipletText(toolCall: ToolCall): string;
+/**
+ * Gets the chiplet information including text and agent data (for team tools).
+ *
+ * @private [🧠] Maybe public?
+ */
+export declare function getToolCallChipletInfo(toolCall: ToolCall): ToolCallChipletInfo;

package/esm/typings/src/book-components/Chat/utils/loadAgentProfile.d.ts

@@ -0,0 +1,69 @@
+import type { string_url, string_url_image } from '../../../types/typeAliases';
+/**
+ * Input data for resolving agent profiles.
+ * @private
+ */
+export type AgentProfileInput = {
+    url: string_url;
+    label?: string;
+    imageUrl?: string_url_image;
+    publicUrl?: string_url;
+};
+/**
+ * Resolved agent profile data for UI usage.
+ * @private
+ */
+export type AgentProfileData = {
+    label: string;
+    imageUrl: string_url_image | null;
+};
+/**
+ * Extracts agent name from URL.
+ * @private
+ */
+export declare function extractAgentNameFromUrl(url: string): string;
+/**
+ * Determines whether a label looks like an autogenerated identifier.
+ * @private
+ */
+export declare function isLikelyGeneratedId(label: string): boolean;
+/**
+ * Resolves the initial label for an agent without exposing generated IDs.
+ * @private
+ */
+export declare function resolveInitialAgentLabel(agent: AgentProfileInput): string;
+/**
+ * Picks the best available label from profile data without exposing IDs.
+ * @private
+ */
+export declare function resolvePreferredAgentLabel(candidates: Array<string | undefined>, fallback: string): string;
+/**
+ * Resolves the agents server base URL from the agent URL or provided public URL.
+ * @private
+ */
+export declare function resolveAgentsServerUrl(agentUrl: string, publicUrl?: string_url): string | null;
+/**
+ * Resolves the profile image URL, handling relative URLs when needed.
+ * @private
+ */
+export declare function resolveProfileImageUrl(profileImageUrl: string_url_image | undefined, agentUrl: string_url, publicUrl?: string_url): string_url_image | null;
+/**
+ * Builds a placeholder image URL for the agent when no profile image is available.
+ * @private
+ */
+export declare function resolvePlaceholderImageUrl(agent: AgentProfileInput): string_url_image | null;
+/**
+ * Returns true when a profile fetch would likely improve the label or image.
+ * @private
+ */
+export declare function shouldFetchAgentProfile(agent: AgentProfileInput): boolean;
+/**
+ * Resolves fallback profile data without fetching remote metadata.
+ * @private
+ */
+export declare function resolveAgentProfileFallback(agent: AgentProfileInput): AgentProfileData;
+/**
+ * Loads agent profile data from the agent profile endpoint when needed.
+ * @private
+ */
+export declare function loadAgentProfile(agent: AgentProfileInput): Promise<AgentProfileData>;