@datalayer/agent-runtimes 1.3.28 → 1.3.29

package/lib/chat/ChatFloating.d.ts

@@ -12,6 +12,8 @@
  * @module chat/ChatFloating
  */
 import React from 'react';
+import { type AssistantCharacter } from './assistant/characters';
+import type { AssistantCharacterData } from './assistant/formats/types';
 import type { ChatCommonProps, ChatViewMode } from '../types';
 /**
  * ChatFloating props — extends ChatCommonProps with floating/popup-specific configuration.
@@ -67,10 +69,18 @@ export interface ChatFloatingProps extends ChatCommonProps {
      * - 'floating': Full-height floating panel (pinned to right edge with offset)
      * - 'floating-small': Standard floating popup
      * - 'floating-draggable': The popup with a handle, movable about the viewport
+     * - 'assistant': A character on the page that speaks in a balloon (LOOP T-21)
      * - 'panel': Full-height side panel (right edge, no floating offset)
      * @default 'floating'
      */
-    defaultViewMode?: 'floating' | 'floating-small' | 'floating-draggable' | 'panel';
+    defaultViewMode?: 'floating' | 'floating-small' | 'floating-draggable' | 'assistant' | 'panel';
+    /**
+     * The character of the floating assistant: one Datalayer ships, by id
+     * (`ASSISTANT_CHARACTERS`, LOOP T-25), or one a person loaded from a file
+     * they hold the rights to (`readClippyCharacter`, `readAcsCharacter`, T-26).
+     * @default 'paperclip'
+     */
+    assistantCharacter?: string | AssistantCharacter | AssistantCharacterData;
     /**
      * Callback when the user switches view mode via the header toggle.
      * The parent component receives the new ChatViewMode value.
@@ -99,5 +109,5 @@ export interface ChatFloatingProps extends ChatCommonProps {
  * ChatFloating component
  * A floating chat window built on ChatBase
  */
-export declare function ChatFloating({ endpoint, protocol: protocolProp, useStore: useStoreMode, title, description, position, defaultOpen, width, height, showHeader, showButton, showNewChatButton, showClearButton, showSettingsButton, enableKeyboardShortcuts, toggleShortcut, showPoweredBy, promptVariant, mentionableAgents, poweredByProps, clickOutsideToClose, escapeToClose, className, onSettingsClick, onNewChat, onOpen, onClose, onStateUpdate, children, brandIcon, buttonIcon, buttonTooltip, brandColor, buttonGlow, offset, animationDuration, renderToolResult, frontendTools, initialState: _initialState, suggestions, submitOnSuggestionClick, hideMessagesAfterToolUI, defaultViewMode, onViewModeChange, sidebarMountPoint, showPanelBackdrop, availableModels, showModelSelector, showToolsMenu, showSkillsMenu, showTokenUsage, showContextRing, themeVariant, colorMode, runtimeId, historyEndpoint, authToken, historyAuthToken, pendingPrompt, showInformation, onInformationClick, onToolCallStart, onToolCallComplete, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, panelProps, launching, launchingMessage, }: ChatFloatingProps): React.JSX.Element;
+export declare function ChatFloating({ endpoint, protocol: protocolProp, useStore: useStoreMode, title, description, position, defaultOpen, width, height, showHeader, showButton, showNewChatButton, showClearButton, showSettingsButton, enableKeyboardShortcuts, toggleShortcut, showPoweredBy, promptVariant, mentionableAgents, poweredByProps, clickOutsideToClose, escapeToClose, className, onSettingsClick, onNewChat, onOpen, onClose, onStateUpdate, children, brandIcon, buttonIcon, buttonTooltip, brandColor, buttonGlow, offset, animationDuration, renderToolResult, frontendTools, initialState: _initialState, suggestions, submitOnSuggestionClick, hideMessagesAfterToolUI, defaultViewMode, onViewModeChange, sidebarMountPoint, showPanelBackdrop, availableModels, showModelSelector, showToolsMenu, showSkillsMenu, showTokenUsage, showContextRing, themeVariant, colorMode, runtimeId, historyEndpoint, authToken, historyAuthToken, pendingPrompt, showInformation, onInformationClick, onToolCallStart, onToolCallComplete, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, panelProps, launching, launchingMessage, assistantCharacter, }: ChatFloatingProps): React.JSX.Element;
 export default ChatFloating;

package/lib/chat/ChatFloating.js

@@ -26,6 +26,11 @@ import { ChatBase } from './base/ChatBase';
 import { ButtonGlow } from './display/ButtonGlow';
 import { useViewportDrag } from './useViewportDrag';
 import { disabledChatViewModes, resolveMountPoint } from './viewModes';
+import { AssistantStage } from './assistant/AssistantStage';
+import { SpeechBalloon } from './assistant/SpeechBalloon';
+import { DEFAULT_ASSISTANT_CHARACTER, } from './assistant/characters';
+import { assistantStateOf, latestSaying, newestIsAnswer, keepAway, keptAway, } from './assistant/state';
+import { presenceState, presenceToolOf, } from './presence/presenceStatus';
 import { useChatOpen, useChatMessages, useChatStore, } from '../stores/chatStore';
 import { useChatKeyboardShortcuts, getShortcutDisplay, } from '@datalayer/core/lib/hooks';
 /**
@@ -47,7 +52,7 @@ function useIsMobile(breakpoint = 640) {
  * ChatFloating component
  * A floating chat window built on ChatBase
  */
-export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useStoreMode = true, title = 'Chat', description = 'Start a conversation with the AI agent.', position = 'bottom-right', defaultOpen = false, width = 400, height = 550, showHeader = true, showButton = true, showNewChatButton = true, showClearButton = true, showSettingsButton = false, enableKeyboardShortcuts = true, toggleShortcut = '/', showPoweredBy = true, promptVariant, mentionableAgents, poweredByProps, clickOutsideToClose = false, escapeToClose = true, className, onSettingsClick, onNewChat, onOpen, onClose, onStateUpdate, children, brandIcon, buttonIcon, buttonTooltip = 'Chat with AI', brandColor, buttonGlow = true, offset = 20, animationDuration = 200, renderToolResult, frontendTools, initialState: _initialState, suggestions, submitOnSuggestionClick = true, hideMessagesAfterToolUI = false, defaultViewMode = 'floating', onViewModeChange, sidebarMountPoint = null, showPanelBackdrop = false, availableModels, showModelSelector = false, showToolsMenu = false, showSkillsMenu = false, showTokenUsage = true, showContextRing = false, themeVariant, colorMode, runtimeId, historyEndpoint, authToken, historyAuthToken, pendingPrompt, showInformation = false, onInformationClick, onToolCallStart, onToolCallComplete, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, panelProps, launching = false, launchingMessage, }) {
+export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useStoreMode = true, title = 'Chat', description = 'Start a conversation with the AI agent.', position = 'bottom-right', defaultOpen = false, width = 400, height = 550, showHeader = true, showButton = true, showNewChatButton = true, showClearButton = true, showSettingsButton = false, enableKeyboardShortcuts = true, toggleShortcut = '/', showPoweredBy = true, promptVariant, mentionableAgents, poweredByProps, clickOutsideToClose = false, escapeToClose = true, className, onSettingsClick, onNewChat, onOpen, onClose, onStateUpdate, children, brandIcon, buttonIcon, buttonTooltip = 'Chat with AI', brandColor, buttonGlow = true, offset = 20, animationDuration = 200, renderToolResult, frontendTools, initialState: _initialState, suggestions, submitOnSuggestionClick = true, hideMessagesAfterToolUI = false, defaultViewMode = 'floating', onViewModeChange, sidebarMountPoint = null, showPanelBackdrop = false, availableModels, showModelSelector = false, showToolsMenu = false, showSkillsMenu = false, showTokenUsage = true, showContextRing = false, themeVariant, colorMode, runtimeId, historyEndpoint, authToken, historyAuthToken, pendingPrompt, showInformation = false, onInformationClick, onToolCallStart, onToolCallComplete, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, panelProps, launching = false, launchingMessage, assistantCharacter = DEFAULT_ASSISTANT_CHARACTER, }) {
     // Store-based state
     const storeIsOpen = useChatOpen();
     const storeMessages = useChatMessages();
@@ -96,6 +101,88 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
             resetDrag();
         }
     }, [viewMode, resetDrag]);
+    /*
+     * The floating assistant (LOOP T-21, T-22, T-27): a character that acts out
+     * the presence of what answers — read here from the chat's own loading and
+     * items — greets when it arrives, says goodbye when sent away, and is
+     * dragged about by itself, the conversation following it.
+     */
+    const ASSISTANT_SIZE = 88;
+    const assistantMode = viewMode === 'assistant' && !isMobile;
+    const [chatBusy, setChatBusy] = useState(false);
+    const [chatTool, setChatTool] = useState({
+        open: false,
+        pendingApproval: false,
+    });
+    const [answering, setAnswering] = useState(false);
+    const [arriving, setArriving] = useState(false);
+    const [leaving, setLeaving] = useState(false);
+    const [assistantAway, setAssistantAway] = useState(keptAway);
+    const assistantShown = assistantMode && assistantAway === 'none';
+    const callAssistantBack = useCallback(() => {
+        keepAway('none');
+        setAssistantAway('none');
+    }, []);
+    /* The agent's newest words, said in the balloon until heard (T-23). */
+    const [saying, setSaying] = useState();
+    const [heardId, setHeardId] = useState();
+    const [freshSaying, setFreshSaying] = useState(false);
+    useEffect(() => {
+        if (!saying || isOpen) {
+            return;
+        }
+        setFreshSaying(true);
+        const timer = setTimeout(() => setFreshSaying(false), 12000);
+        return () => clearTimeout(timer);
+    }, [saying?.id, saying?.text, isOpen]);
+    useEffect(() => {
+        if (isOpen && saying) {
+            setHeardId(saying.id);
+        }
+    }, [isOpen, saying]);
+    const stageRef = useRef(null);
+    const stageDrag = useViewportDrag(stageRef);
+    useEffect(() => {
+        if (!assistantShown) {
+            return;
+        }
+        setArriving(true);
+        const timer = setTimeout(() => setArriving(false), 1800);
+        return () => clearTimeout(timer);
+    }, [assistantShown]);
+    const assistantState = assistantStateOf(presenceState(chatBusy, chatTool), {
+        arriving,
+        leaving,
+        speaking: answering,
+    });
+    const unheard = !!saying && saying.id !== heardId;
+    const assistantBalloon = assistantState === 'waiting'
+        ? { text: 'Waiting for you — open the conversation to answer.' }
+        : unheard && saying
+            ? { text: saying.text, more: saying.more }
+            : { text: description };
+    const balloonInsists = assistantState === 'greeting' ||
+        assistantState === 'waiting' ||
+        (unheard && (assistantState === 'speaking' || freshSaying));
+    const panelOnLoadingChange = panelProps?.onLoadingChange;
+    const panelOnDisplayItemsChange = panelProps?.onDisplayItemsChange;
+    const handleLoadingChange = useCallback((loading) => {
+        setChatBusy(loading);
+        panelOnLoadingChange?.(loading);
+    }, [panelOnLoadingChange]);
+    const handleDisplayItemsChange = useCallback((items) => {
+        const tool = presenceToolOf(items);
+        setChatTool(previous => previous.open === tool.open &&
+            previous.pendingApproval === tool.pendingApproval
+            ? previous
+            : tool);
+        setAnswering(newestIsAnswer(items));
+        const said = latestSaying(items);
+        setSaying(previous => previous?.id === said?.id && previous?.text === said?.text
+            ? previous
+            : said);
+        panelOnDisplayItemsChange?.(items);
+    }, [panelOnDisplayItemsChange]);
     // Handle view mode changes from the header segmented toggle
     const handleChatViewModeChange = useCallback((mode) => {
         if (mode === 'sidebar' && sidebarDisabled) {
@@ -115,12 +202,16 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
             setFocusTrigger(prev => prev + 1);
         }
         else {
-            // The floating modes stay within ChatFloating
+            // The floating modes stay within ChatFloating; picking the assistant
+            // calls it back, however long it was sent away for (T-27).
+            if (mode === 'assistant') {
+                callAssistantBack();
+            }
             setViewMode(mode);
             setFocusTrigger(prev => prev + 1);
             onViewModeChange?.(mode);
         }
-    }, [onViewModeChange, sidebarDisabled]);
+    }, [onViewModeChange, sidebarDisabled, callAssistantBack]);
     // Detect whether the chat is mounted inside a parent that is intentionally
     // configured for docked side panels (Notebook example lays the chat out as a
     // flex sibling). Those hosts dock the panel in-flow. Plain content pages
@@ -272,6 +363,42 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
         // Reset animating after duration
         setTimeout(() => setIsAnimating(false), animationDuration);
     }, [isOpen, setIsOpen, onOpen, onClose, animationDuration]);
+    /*
+     * The assistant sent away (T-27): goodbye first, then the popup's round
+     * button in its place — which calls it back when it went for the page, and
+     * opens the chat when it went for the session or for good.
+     */
+    const dismissAssistant = useCallback((away) => {
+        if (isOpen) {
+            handleToggle();
+        }
+        keepAway(away);
+        setLeaving(true);
+        setTimeout(() => {
+            setLeaving(false);
+            setAssistantAway(away);
+        }, 600);
+    }, [isOpen, handleToggle]);
+    /*
+     * The conversation as the assistant's balloon: above the character, its
+     * right edge on the character's, and never off the screen.
+     */
+    const balloonPlace = () => {
+        const widthPx = typeof width === 'number' ? width : 400;
+        const heightPx = typeof height === 'number' ? height : 550;
+        if (stageDrag.position) {
+            return {
+                left: Math.max(8, stageDrag.position.left + ASSISTANT_SIZE - widthPx),
+                top: Math.max(8, stageDrag.position.top - heightPx - 16),
+                right: 'auto',
+                bottom: 'auto',
+            };
+        }
+        const corner = getPositionStyles();
+        return position.startsWith('bottom')
+            ? { ...corner, bottom: offset + ASSISTANT_SIZE + 16 }
+            : { ...corner, top: offset + ASSISTANT_SIZE + 16 };
+    };
     // Handle new chat
     const handleNewChat = useCallback(() => {
         if (useStoreMode) {
@@ -437,6 +564,11 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
                     }
                     : getPositionStyles()
                 : {}),
+            ...(assistantShown
+                ? balloonPlace()
+                : assistantMode && !isMobile
+                    ? getPositionStyles()
+                    : {}),
             ...(viewMode === 'panel' && !isMobile
                 ? {
                     ...(panelInFlow || dockedInMount
@@ -468,7 +600,8 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
                         ? `${popupWidth}px`
                         : popupWidth
                     : (viewMode === 'floating-small' ||
-                        viewMode === 'floating-draggable') &&
+                        viewMode === 'floating-draggable' ||
+                        viewMode === 'assistant') &&
                         !isMobile
                         ? typeof popupWidth === 'number'
                             ? `${popupWidth}px`
@@ -487,7 +620,8 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
                 : viewMode === 'floating' && !isMobile
                     ? '100%'
                     : (viewMode === 'floating-small' ||
-                        viewMode === 'floating-draggable') &&
+                        viewMode === 'floating-draggable' ||
+                        viewMode === 'assistant') &&
                         !isMobile
                         ? typeof popupHeight === 'number'
                             ? `${popupHeight}px`
@@ -502,7 +636,11 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
             bg: 'canvas.default',
             border: '1px solid',
             borderColor: 'border.default',
-            borderRadius: viewMode === 'panel' || isMobile ? 0 : '12px',
+            borderRadius: viewMode === 'panel' || isMobile
+                ? 0
+                : assistantMode
+                    ? 'var(--theme-radius-bubble, 16px)'
+                    : '12px',
             boxShadow: viewMode === 'panel' ? 'shadow.none' : 'shadow.extra-large',
             overflow: 'hidden',
             transform: viewMode === 'panel'
@@ -550,30 +688,56 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
                     ...poweredByProps,
                 }, renderToolResult: renderToolResult, description: description, onStateUpdate: onStateUpdate, onNewChat: onNewChat, suggestions: suggestions, submitOnSuggestionClick: submitOnSuggestionClick, hideMessagesAfterToolUI: hideMessagesAfterToolUI, avatarConfig: {
                     showAvatars: true,
-                }, placeholder: "Type a message...", backgroundColor: "canvas.subtle", frontendTools: frontendTools, showModelSelector: showModelSelector, availableModels: availableModels, showToolsMenu: showToolsMenu, showSkillsMenu: showSkillsMenu, showTokenUsage: showTokenUsage, showContextRing: showContextRing, runtimeId: runtimeId, historyEndpoint: historyEndpoint, historyAuthToken: historyAuthToken, pendingPrompt: pendingPrompt, showInformation: showInformation, onInformationClick: onInformationClick, onToolCallStart: onToolCallStart, onToolCallComplete: onToolCallComplete, showToolApprovalBanner: showToolApprovalBanner, pendingApprovals: pendingApprovals, onApproveApproval: onApproveApproval, onRejectApproval: onRejectApproval, ...panelProps, children: children })] }));
-    return (_jsxs(_Fragment, { children: [showButton && !isOpen && (_jsx(Box, { sx: {
+                }, placeholder: "Type a message...", backgroundColor: "canvas.subtle", frontendTools: frontendTools, showModelSelector: showModelSelector, availableModels: availableModels, showToolsMenu: showToolsMenu, showSkillsMenu: showSkillsMenu, showTokenUsage: showTokenUsage, showContextRing: showContextRing, runtimeId: runtimeId, historyEndpoint: historyEndpoint, historyAuthToken: historyAuthToken, pendingPrompt: pendingPrompt, showInformation: showInformation, onInformationClick: onInformationClick, onToolCallStart: onToolCallStart, onToolCallComplete: onToolCallComplete, showToolApprovalBanner: showToolApprovalBanner, pendingApprovals: pendingApprovals, onApproveApproval: onApproveApproval, onRejectApproval: onRejectApproval, ...panelProps, onLoadingChange: handleLoadingChange, onDisplayItemsChange: handleDisplayItemsChange, children: children })] }));
+    /*
+     * The floating popup's button. Words not yet heard make it blink for the
+     * person's attention, until the chat is opened; hovered, they show in a
+     * balloon above it in place of the tooltip.
+     */
+    const chatButton = (_jsx(IconButton, { icon: buttonIcon ? buttonIcon : CommentDiscussionIcon, "aria-label": buttonTooltip, onClick: assistantMode && assistantAway === 'page'
+            ? callAssistantBack
+            : handleToggle, size: "large", sx: {
+            width: 56,
+            height: 56,
+            borderRadius: '50%',
+            bg: brandColor || 'accent.emphasis',
+            color: 'fg.onEmphasis',
+            boxShadow: 'shadow.large',
+            transition: 'transform 0.2s ease, box-shadow 0.2s ease',
+            transform: isHovered ? 'scale(1.1)' : 'scale(1)',
+            // Words not yet heard: the circle blinks for the person's
+            // attention, and stops once the chat is opened.
+            ...(unheard
+                ? {
+                    animation: 'chatFloatingBlink 1.1s ease-in-out infinite',
+                    '@keyframes chatFloatingBlink': {
+                        '0%, 100%': {
+                            filter: 'brightness(1)',
+                            boxShadow: '0 0 0 0 rgba(0,0,0,0)',
+                        },
+                        '50%': {
+                            filter: 'brightness(1.25)',
+                            boxShadow: '0 0 0 6px var(--bgColor-accent-muted, rgba(84,174,255,0.4))',
+                        },
+                    },
+                    '@media (prefers-reduced-motion: reduce)': { animation: 'none' },
+                }
+                : {}),
+            '&:hover': {
+                bg: brandColor || 'accent.emphasis',
+                boxShadow: 'shadow.extra-large',
+            },
+        } }));
+    return (_jsxs(_Fragment, { children: [assistantShown && (_jsx(AssistantStage, { character: assistantCharacter, state: assistantState, size: ASSISTANT_SIZE, place: stageDrag.position
+                    ? { left: stageDrag.position.left, top: stageDrag.position.top }
+                    : getPositionStyles(), stageRef: stageRef, onDragStart: stageDrag.onHandlePointerDown, open: isOpen, onToggle: handleToggle, balloon: assistantBalloon, insist: balloonInsists, onDismiss: dismissAssistant })), showButton && !isOpen && !assistantShown && (_jsx(Box, { sx: {
                     ...getPositionStyles(),
                 }, children: _jsxs(Box, { sx: {
                         position: 'relative',
                         display: 'inline-flex',
                         // The glow's halos go behind the button, not behind the page.
                         isolation: 'isolate',
-                    }, onMouseEnter: () => setIsHovered(true), onMouseLeave: () => setIsHovered(false), children: [buttonGlow && _jsx(ButtonGlow, { color: brandColor }), _jsx(Tooltip, { text: `${buttonTooltip}${shortcutHint ? ` (${shortcutHint})` : ''}`, direction: position.includes('right') ? 'w' : 'e', children: _jsx(IconButton, { icon: buttonIcon
-                                    ? buttonIcon
-                                    : CommentDiscussionIcon, "aria-label": buttonTooltip, onClick: handleToggle, size: "large", sx: {
-                                    width: 56,
-                                    height: 56,
-                                    borderRadius: '50%',
-                                    bg: brandColor || 'accent.emphasis',
-                                    color: 'fg.onEmphasis',
-                                    boxShadow: 'shadow.large',
-                                    transition: 'transform 0.2s ease, box-shadow 0.2s ease',
-                                    transform: isHovered ? 'scale(1.1)' : 'scale(1)',
-                                    '&:hover': {
-                                        bg: brandColor || 'accent.emphasis',
-                                        boxShadow: 'shadow.extra-large',
-                                    },
-                                } }) }), messages.length > 0 && (_jsx(Box, { sx: {
+                    }, onMouseEnter: () => setIsHovered(true), onMouseLeave: () => setIsHovered(false), children: [buttonGlow && _jsx(ButtonGlow, { color: brandColor }), isHovered && saying ? (_jsx(SpeechBalloon, { text: saying.text, more: saying.more, onOpen: handleToggle, above: 64, side: position.startsWith('bottom') ? 'above' : 'below', align: position.includes('right') ? 'right' : 'left', tailAt: 28 })) : null, saying ? (chatButton) : (_jsx(Tooltip, { text: `${buttonTooltip}${shortcutHint ? ` (${shortcutHint})` : ''}`, direction: position.includes('right') ? 'w' : 'e', children: chatButton })), messages.length > 0 && (_jsx(Box, { sx: {
                                 position: 'absolute',
                                 top: 0,
                                 right: 0,
@@ -589,7 +753,7 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
                                 fontSize: 0,
                                 fontWeight: 'bold',
                                 pointerEvents: 'none',
-                            }, children: _jsx(Text, { sx: { fontSize: 0 }, children: messages.length > 99 ? '99+' : messages.length }) })), messages.length > 0 && (_jsx(Box, { sx: {
+                            }, children: _jsx(Text, { sx: { fontSize: 0 }, children: messages.length > 99 ? '99+' : messages.length }) })), unheard && (_jsx(Box, { sx: {
                                 position: 'absolute',
                                 top: 0,
                                 left: 0,
@@ -610,6 +774,13 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
                                         opacity: 0,
                                     },
                                 },
+                                // Still, as a ring held around the button, for a reader
+                                // who asks the system for reduced motion (T-28).
+                                '@media (prefers-reduced-motion: reduce)': {
+                                    animation: 'none',
+                                    transform: 'scale(1.15)',
+                                    opacity: 0.6,
+                                },
                             } }))] }) })), isMobile && isOpen && (_jsx(Box, { sx: {
                     position: 'fixed',
                     top: 0,

package/lib/chat/assistant/AssistantStage.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The floating assistant on the page (LOOP T-21, T-22, T-27): a character in
+ * a corner, acting out what the application is doing, with a balloon that
+ * says a word while the conversation is closed. Clicked, it opens the
+ * conversation; dragged, it moves, and the conversation follows; sent away,
+ * it says goodbye and leaves a small way back.
+ *
+ * Its motions are one set for every character, by the parts each drawing
+ * names (`assistant-body`, `-pupils`, `-lids`, `-mouth`), and nothing moves
+ * for a reader who asks the system for reduced motion.
+ *
+ * @module chat/assistant/AssistantStage
+ */
+import type { JSX, RefObject } from 'react';
+import { type AssistantCharacter } from './characters';
+import type { AssistantCharacterData } from './formats/types';
+import type { AssistantAway, AssistantState } from './state';
+/**
+ * Where the balloon goes so that it stays inside the window (T-23): toward
+ * the middle of the page from whichever half the character stands in, and
+ * below it when it stands too near the top.
+ */
+export declare function balloonSide(place: {
+    left?: unknown;
+    top?: unknown;
+    right?: unknown;
+    bottom?: unknown;
+}, viewport?: {
+    width: number;
+    height: number;
+}): {
+    side: 'above' | 'below';
+    align: 'left' | 'right';
+};
+export interface AssistantStageProps {
+    /** The character: one Datalayer ships, by id (T-25), or one loaded from a file (T-26). */
+    character: string | AssistantCharacter | AssistantCharacterData;
+    /** What it acts out (T-22). */
+    state: AssistantState;
+    /** Its size, in pixels. */
+    size?: number;
+    /** Where it sits once moved, or the corner it starts in. */
+    place: {
+        left: number;
+        top: number;
+    } | React.CSSProperties;
+    /** The element the drag measures. */
+    stageRef: RefObject<HTMLDivElement | null>;
+    /** Starts a drag. */
+    onDragStart: (event: React.PointerEvent<HTMLElement>) => void;
+    /** The conversation is open: the balloon above is the chat itself. */
+    open: boolean;
+    /** Open or close the conversation. */
+    onToggle: () => void;
+    /**
+     * What the balloon says while the conversation is closed: the agent's
+     * newest words, as the Office Assistant said them (T-23), or a welcome.
+     * `more` adds *Open the conversation* for the rest.
+     */
+    balloon?: {
+        text: string;
+        more?: boolean;
+    };
+    /** Show the balloon without being hovered: something new to say. */
+    insist?: boolean;
+    /** Send it away (T-27): for the page, for the session, or for good. */
+    onDismiss: (away: AssistantAway) => void;
+}
+export declare function AssistantStage({ character, state, size, place, stageRef, onDragStart, open, onToggle, balloon, insist, onDismiss, }: AssistantStageProps): JSX.Element;
+export default AssistantStage;

package/lib/chat/assistant/AssistantStage.js

@@ -0,0 +1,192 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useRef, useState } from 'react';
+import { ActionList, ActionMenu, IconButton } from '@primer/react';
+import { Box } from '@datalayer/primer-addons';
+import { XIcon } from '@primer/octicons-react';
+import { assistantCharacter } from './characters';
+import { SpeechBalloon } from './SpeechBalloon';
+import { SpriteCharacter } from './SpriteCharacter';
+/** The motions, by the state the stage is in. */
+const MOTIONS = {
+    '@keyframes assistantFloat': {
+        '0%, 100%': { transform: 'translateY(0)' },
+        '50%': { transform: 'translateY(-3px)' },
+    },
+    '@keyframes assistantBlink': {
+        '0%, 94%, 100%': { transform: 'scaleY(0)' },
+        '97%': { transform: 'scaleY(1)' },
+    },
+    '@keyframes assistantTilt': {
+        '0%, 100%': { transform: 'rotate(-5deg)' },
+        '50%': { transform: 'rotate(-8deg) translateY(-2px)' },
+    },
+    '@keyframes assistantWork': {
+        '0%, 100%': { transform: 'rotate(-3deg) translateY(0)' },
+        '50%': { transform: 'rotate(3deg) translateY(-4px)' },
+    },
+    '@keyframes assistantAttention': {
+        '0%, 100%': { transform: 'scale(1) rotate(0)' },
+        '20%': { transform: 'scale(1.08) rotate(-6deg)' },
+        '40%': { transform: 'scale(1.08) rotate(6deg)' },
+        '60%': { transform: 'scale(1)' },
+    },
+    '@keyframes assistantHop': {
+        '0%, 100%': { transform: 'translateY(0)' },
+        '30%': { transform: 'translateY(-14px)' },
+        '55%': { transform: 'translateY(0)' },
+        '75%': { transform: 'translateY(-6px)' },
+    },
+    '@keyframes assistantTalk': {
+        '0%, 100%': { transform: 'scaleY(1)' },
+        '50%': { transform: 'scaleY(2.2)' },
+    },
+    '@keyframes assistantLeave': {
+        from: { transform: 'scale(1)', opacity: 1 },
+        to: { transform: 'scale(0.2) translateY(20px)', opacity: 0 },
+    },
+};
+const BODY = '& .assistant-body';
+/** How long it may be sent away for, in the menu's words (T-27). */
+const AWAY_CHOICES = [
+    { away: 'page', label: 'Hide for now' },
+    { away: 'session', label: 'Hide for this session' },
+    { away: 'always', label: 'Don\u2019t show again' },
+];
+/** Room the balloon needs above the character before it goes below. */
+const BALLOON_ROOM = 200;
+/**
+ * Where the balloon goes so that it stays inside the window (T-23): toward
+ * the middle of the page from whichever half the character stands in, and
+ * below it when it stands too near the top.
+ */
+export function balloonSide(place, viewport = {
+    width: typeof window === 'undefined' ? 1280 : window.innerWidth,
+    height: typeof window === 'undefined' ? 800 : window.innerHeight,
+}) {
+    const left = typeof place.left === 'number' ? place.left : undefined;
+    const top = typeof place.top === 'number' ? place.top : undefined;
+    const align = left !== undefined
+        ? left < viewport.width / 2
+            ? 'left'
+            : 'right'
+        : place.left !== undefined && place.right === undefined
+            ? 'left'
+            : 'right';
+    const side = top !== undefined
+        ? top < BALLOON_ROOM
+            ? 'below'
+            : 'above'
+        : place.top !== undefined && place.bottom === undefined
+            ? 'below'
+            : 'above';
+    return { side, align };
+}
+export function AssistantStage({ character, state, size = 88, place, stageRef, onDragStart, open, onToggle, balloon, insist = false, onDismiss, }) {
+    // A shipped one by id, a drawing contributed by a plugin (T-24), or a
+    // character read from a file (T-26).
+    const shipped = typeof character === 'string'
+        ? assistantCharacter(character)
+        : 'Drawing' in character
+            ? character
+            : undefined;
+    const name = shipped
+        ? shipped.name
+        : character.name;
+    const [hovered, setHovered] = useState(false);
+    const [menuOpen, setMenuOpen] = useState(false);
+    // Where the press began: a press that moves is a drag, not a click.
+    const pressedAt = useRef(null);
+    const showBalloon = !open && !!balloon && (hovered || insist);
+    return (_jsxs(Box, { ref: stageRef, "data-assistant-state": state, sx: {
+            position: 'fixed',
+            zIndex: 1002,
+            ...place,
+            width: size,
+            height: size,
+            ...MOTIONS,
+            '& .assistant-lids ellipse': {
+                transformBox: 'fill-box',
+                transformOrigin: 'top',
+                transform: 'scaleY(0)',
+                animation: 'assistantBlink 5.2s ease-in-out infinite',
+            },
+            [BODY]: {
+                transformBox: 'fill-box',
+                transformOrigin: '50% 100%',
+            },
+            '& .assistant-pupils': {
+                transition: 'transform var(--theme-motion-status, 120ms) var(--theme-motion-easing, ease)',
+            },
+            '& .assistant-mouth': {
+                transformBox: 'fill-box',
+                transformOrigin: 'center',
+            },
+            '&[data-assistant-state="idle"] .assistant-body': {
+                animation: 'assistantFloat 3.2s ease-in-out infinite',
+            },
+            '&[data-assistant-state="thinking"] .assistant-body': {
+                animation: 'assistantTilt 2.4s ease-in-out infinite',
+            },
+            '&[data-assistant-state="thinking"] .assistant-pupils': {
+                transform: 'translate(-1px, -3px)',
+            },
+            '&[data-assistant-state="working"] .assistant-body': {
+                animation: 'assistantWork 0.7s ease-in-out infinite',
+            },
+            '&[data-assistant-state="working"] .assistant-pupils': {
+                transform: 'translate(2px, 2px)',
+            },
+            '&[data-assistant-state="waiting"] .assistant-body': {
+                animation: 'assistantAttention 1.4s ease-in-out infinite',
+            },
+            '&[data-assistant-state="greeting"] .assistant-body': {
+                animation: 'assistantHop 0.9s ease-out 2',
+            },
+            '&[data-assistant-state="speaking"] .assistant-mouth': {
+                animation: 'assistantTalk 0.24s ease-in-out infinite',
+            },
+            '&[data-assistant-state="speaking"] .assistant-body': {
+                animation: 'assistantFloat 1.6s ease-in-out infinite',
+            },
+            '&[data-assistant-state="goodbye"] .assistant-body': {
+                animation: 'assistantLeave 0.6s ease-in forwards',
+            },
+            // One still frame per state for a reader who asks for no motion.
+            '@media (prefers-reduced-motion: reduce)': {
+                '& *': { animation: 'none !important' },
+            },
+        }, onMouseEnter: () => setHovered(true), onMouseLeave: () => setHovered(false), children: [showBalloon && balloon && (_jsx(SpeechBalloon, { text: balloon.text, more: balloon.more, onOpen: onToggle, above: size + 8, side: balloonSide(place).side, align: balloonSide(place).align, tailAt: size / 2 })), _jsx(Box, { as: "button", type: "button", "aria-label": open ? `Close the conversation with ${name}` : `Talk to ${name}`, "aria-expanded": open, onPointerDown: (event) => {
+                    pressedAt.current = { x: event.clientX, y: event.clientY };
+                    onDragStart(event);
+                }, onClick: (event) => {
+                    const from = pressedAt.current;
+                    pressedAt.current = null;
+                    if (from &&
+                        Math.hypot(event.clientX - from.x, event.clientY - from.y) > 4) {
+                        return;
+                    }
+                    onToggle();
+                }, sx: {
+                    display: 'block',
+                    width: size,
+                    height: size,
+                    p: 0,
+                    border: 0,
+                    bg: 'transparent',
+                    cursor: 'grab',
+                    touchAction: 'none',
+                    filter: 'drop-shadow(0 6px 10px rgba(0, 0, 0, 0.18))',
+                    '&:active': { cursor: 'grabbing' },
+                    '&:focus-visible': {
+                        outline: '2px solid',
+                        outlineColor: 'var(--focus-outlineColor, var(--fgColor-accent))',
+                        outlineOffset: 2,
+                        borderRadius: '50%',
+                    },
+                }, children: shipped ? (_jsx(shipped.Drawing, { size: size })) : (_jsx(SpriteCharacter, { character: character, state: state, size: size })) }), (hovered || menuOpen) && state !== 'goodbye' && (_jsx(Box, { sx: { position: 'absolute', top: -6, right: -6 }, children: _jsxs(ActionMenu, { open: menuOpen, onOpenChange: setMenuOpen, children: [_jsx(ActionMenu.Anchor, { children: _jsx(IconButton, { icon: XIcon, "aria-label": `Send ${name} away`, size: "small", variant: "invisible", "data-assistant-dismiss": "", sx: {
+                                    bg: 'canvas.default',
+                                    borderRadius: '50%',
+                                    boxShadow: 'shadow.small',
+                                } }) }), _jsx(ActionMenu.Overlay, { width: "auto", children: _jsx(ActionList, { children: AWAY_CHOICES.map(choice => (_jsx(ActionList.Item, { "data-assistant-away": choice.away, onSelect: () => onDismiss(choice.away), children: choice.label }, choice.away))) }) })] }) }))] }));
+}
+export default AssistantStage;

package/lib/chat/assistant/SpeechBalloon.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A speech balloon over something that stands for the agent — the floating
+ * assistant's character, or the floating popup's button while the chat is
+ * closed: the agent's newest words, as the Office Assistant said them
+ * (LOOP T-23), with *Open the conversation* when there is more.
+ *
+ * @module chat/assistant/SpeechBalloon
+ */
+import type { JSX } from 'react';
+export interface SpeechBalloonProps {
+    text: string;
+    /** There is more than the balloon holds. */
+    more?: boolean;
+    /** Opens the conversation. */
+    onOpen: () => void;
+    /** How far from what it stands over, in pixels: above it, or below. */
+    above: number;
+    /** Above what speaks (the default), or below it when it sits at the top. */
+    side?: 'above' | 'below';
+    /** Which edge it is aligned to, toward the page's inside. */
+    align: 'left' | 'right';
+    /** Where the tail points, from that edge, in pixels. */
+    tailAt: number;
+}
+export declare function SpeechBalloon({ text, more, onOpen, above, side, align, tailAt, }: SpeechBalloonProps): JSX.Element;
+export default SpeechBalloon;