@redocly/theme 0.70.0-next.5 → 0.70.0-next.6

package/src/components/Search/SearchAiDialog.tsx

@@ -119,6 +119,10 @@ export function SearchAiDialog({
 
     // oxlint-disable-next-line react-you-might-not-need-an-effect/no-pass-data-to-parent -- merges the streamed assistant response into the lifted conversation state as chunks arrive
     setConversation((prev) => {
+      // A reset can land between this effect's render and its update.
+      if (prev.length === 0) {
+        return prev;
+      }
       const lastMessage = prev[prev.length - 1];
       const content: string = response || '';
 
@@ -214,9 +218,6 @@ export function SearchAiDialog({
             messageId={item.messageId}
             feedback={item.feedback}
             onFeedbackChange={handleFeedbackChange}
-            toolCalls={
-              item.toolCalls || (index === conversation.length - 1 ? toolCalls : undefined)
-            }
             contentSegments={item.contentSegments}
           />
         ))}

package/src/components/Search/SearchAiMessage.tsx

@@ -6,9 +6,9 @@ import {
   type SearchAiMessageResource,
   type ToolCall,
   type ContentSegment,
-  ToolCallName,
 } from '@redocly/theme/core/types';
-import { TOOL_CALL_DISPLAY_TEXT, AiSearchConversationRole } from '@redocly/theme/core/constants';
+import { AiSearchConversationRole } from '@redocly/theme/core/constants';
+import { groupToolCallSegments, hasToolCallsAndText } from '@redocly/theme/core/utils';
 import { Link } from '@redocly/theme/components/Link/Link';
 import { Tag } from '@redocly/theme/components/Tag/Tag';
 import { useThemeHooks } from '@redocly/theme/core/hooks';
@@ -18,43 +18,14 @@ import { AiStarsIcon } from '@redocly/theme/icons/AiStarsIcon/AiStarsIcon';
 import { CheckmarkOutlineIcon } from '@redocly/theme/icons/CheckmarkOutlineIcon/CheckmarkOutlineIcon';
 import { SearchAiActionButtons } from '@redocly/theme/components/Search/SearchAiActionButtons';
 import { SearchAiNegativeFeedbackForm } from '@redocly/theme/components/Search/SearchAiNegativeFeedbackForm';
+import { SearchAiActivity } from '@redocly/theme/components/Search/SearchAiActivity';
+import { searchAiAppearAnimation } from '@redocly/theme/core/styles';
 
 function MarkdownSegment({ text }: { text: string }): JSX.Element {
   const { useMarkdownText } = useThemeHooks();
   const markdown = useMarkdownText(text);
   return <ResponseText as="div" children={markdown} data-testid="response-text" />;
 }
-// The codemode `execute` tool passes a human-readable `description` of what its code
-// does; show that instead of a generic "Executing execute..." label.
-function getExecuteDescription(args: unknown): string | undefined {
-  if (args && typeof args === 'object' && 'description' in args) {
-    const { description } = args as { description?: unknown };
-    if (typeof description === 'string' && description.trim().length > 0) {
-      return description.trim();
-    }
-  }
-  return undefined;
-}
-
-function getToolCallDisplayText(toolCall: ToolCall): {
-  inProgressText: string;
-  completedText: string;
-} {
-  if (toolCall.name === ToolCallName.Execute) {
-    const description = getExecuteDescription(toolCall.args);
-    if (description) {
-      return { inProgressText: description, completedText: description };
-    }
-  }
-
-  return (
-    TOOL_CALL_DISPLAY_TEXT[toolCall.name] ?? {
-      inProgressText: `Executing ${toolCall.name}...`,
-      completedText: `${toolCall.name} executed`,
-    }
-  );
-}
-
 export type SearchAiMessageProps = {
   role: AiSearchConversationRole;
   content: string;
@@ -64,6 +35,7 @@ export type SearchAiMessageProps = {
   messageId?: string;
   feedback?: FeedbackType;
   onFeedbackChange: (messageId: string, feedback: FeedbackType | undefined) => void;
+  /** @deprecated Not used; the message reads its tool calls from `contentSegments`. */
   toolCalls?: ToolCall[];
   contentSegments?: ContentSegment[];
 };
@@ -77,7 +49,6 @@ function SearchAiMessageComponent({
   messageId,
   feedback,
   onFeedbackChange,
-  toolCalls = [],
   contentSegments = [{ type: 'text' as const, text: content }],
 }: SearchAiMessageProps): JSX.Element {
   const { useTranslate, useTelemetry } = useThemeHooks();
@@ -90,7 +61,8 @@ function SearchAiMessageComponent({
 
   const showSuccessMessage = feedbackSent && feedback;
 
-  const isLoading = isThinking && content.length === 0 && toolCalls.length === 0;
+  const groupedSegments = groupToolCallSegments(contentSegments, isThinking);
+  const isFullWidth = hasToolCallsAndText(contentSegments);
 
   const sendFeedbackTelemetry = (feedbackValue: FeedbackType, dislikeReason?: string) => {
     if (!messageId) return;
@@ -143,29 +115,18 @@ function SearchAiMessageComponent({
           margin="0 var(--spacing-xs) 0 0"
         />
       )}
-      <MessageContentWrapper>
+      <MessageContentWrapper $isFullWidth={isFullWidth}>
         {role === AiSearchConversationRole.ASSISTANT ? (
           <>
-            <MessageWrapper $role={role}>
-              {contentSegments.map((segment, index) => {
-                if (segment.type === 'tool') {
-                  const toolCallCompleted = Boolean(segment.toolCall.result);
-
-                  const { inProgressText, completedText } = getToolCallDisplayText(
-                    segment.toolCall,
-                  );
-
-                  const toolCallDisplayText = toolCallCompleted ? completedText : inProgressText;
-
+            <MessageWrapper $role={role} $isFullWidth={isFullWidth}>
+              {groupedSegments.map((segment, index) => {
+                if (segment.type === 'tools') {
                   return (
-                    <ToolCallsInfoWrapper key={`tool-${index}`} data-testid="tool-calls-info">
-                      <ToolCallInfoItem>
-                        <DocumentIcon size="14px" color="--search-ai-text-color" />
-                        <ToolCallText $isSearching={!toolCallCompleted}>
-                          {toolCallDisplayText}
-                        </ToolCallText>
-                      </ToolCallInfoItem>
-                    </ToolCallsInfoWrapper>
+                    <ToolCallsActivity
+                      key={`tools-${index}`}
+                      toolCalls={segment.toolCalls}
+                      isActive={segment.isActive}
+                    />
                   );
                 }
 
@@ -193,14 +154,7 @@ function SearchAiMessageComponent({
                   </ResourcesWrapper>
                 </>
               )}
-              {isLoading && (
-                <ThinkingDotsWrapper data-testid="thinking-dots-wrapper">
-                  <ThinkingDot />
-                  <ThinkingDot />
-                  <ThinkingDot />
-                </ThinkingDotsWrapper>
-              )}
-              {content.length > 0 && (
+              {!isThinking && content.length > 0 && (
                 <FeedbackWrapper>
                   <SearchAiActionButtons
                     content={content}
@@ -261,7 +215,6 @@ export const SearchAiMessage = memo(SearchAiMessageComponent, (prevProps, nextPr
     prevProps.feedback === nextProps.feedback &&
     prevProps.onFeedbackChange === nextProps.onFeedbackChange &&
     areResourcesEqual(prevProps.resources, nextProps.resources) &&
-    prevProps.toolCalls?.length === nextProps.toolCalls?.length &&
     prevProps.contentSegments === nextProps.contentSegments
   );
 });
@@ -275,9 +228,10 @@ const SearchAiMessageWrapper = styled.div<{ $role: string }>`
     $role === AiSearchConversationRole.USER ? 'flex-end' : 'flex-start'};
 `;
 
-const MessageContentWrapper = styled.div`
+const MessageContentWrapper = styled.div<{ $isFullWidth: boolean }>`
   display: flex;
   flex-direction: column;
+  flex-grow: ${({ $isFullWidth }) => ($isFullWidth ? 1 : 0)};
   gap: var(--spacing-sm);
   max-width: 80%;
   min-width: 0;
@@ -300,13 +254,13 @@ const ResponseText = styled(Markdown)`
   }
 `;
 
-const MessageWrapper = styled.div<{ $role: string }>`
+const MessageWrapper = styled.div<{ $role: string; $isFullWidth?: boolean }>`
   padding: ${({ $role }) =>
     $role === AiSearchConversationRole.USER
       ? 'var(--spacing-sm)'
       : 'var(--spacing-sm) var(--spacing-sm) var(--spacing-xs) var(--spacing-sm)'};
   border-radius: var(--border-radius-xl);
-  width: fit-content;
+  width: ${({ $isFullWidth }) => ($isFullWidth ? 'auto' : 'fit-content')};
   max-width: 100%;
   word-wrap: break-word;
   white-space: pre-wrap;
@@ -327,12 +281,14 @@ const ResourcesWrapper = styled.div`
   display: flex;
   flex-direction: column;
   margin: 0;
+  ${searchAiAppearAnimation}
 `;
 const FeedbackWrapper = styled.div`
   display: flex;
   flex-direction: row;
   gap: var(--search-ai-feedback-gap);
   margin-top: var(--spacing-sm);
+  ${searchAiAppearAnimation}
 `;
 
 const ResourcesTitle = styled.div`
@@ -367,43 +323,6 @@ const ResourceTag = styled(Tag).attrs({ textTransform: 'none' })`
   }
 `;
 
-const ThinkingDotsWrapper = styled.div`
-  display: flex;
-  gap: var(--search-ai-thinking-dots-gap);
-  padding: var(--search-ai-thinking-dots-padding);
-`;
-
-const ThinkingDot = styled.div`
-  width: var(--search-ai-thinking-dot-size);
-  height: var(--search-ai-thinking-dot-size);
-  border-radius: 50%;
-  background: var(--search-ai-thinking-dot-color);
-  animation: bounce 1.4s infinite ease-in-out;
-
-  &:nth-child(1) {
-    animation-delay: -0.32s;
-  }
-  &:nth-child(2) {
-    animation-delay: -0.16s;
-  }
-  &:nth-child(3) {
-    animation-delay: 0s;
-  }
-
-  @keyframes bounce {
-    0%,
-    80%,
-    100% {
-      opacity: 0.2;
-      transform: scale(0.8);
-    }
-    40% {
-      opacity: 1;
-      transform: scale(1);
-    }
-  }
-`;
-
 const SuccessMessageWrapper = styled.div`
   max-width: fit-content;
   display: flex;
@@ -420,37 +339,10 @@ const SuccessMessageText = styled.div`
   color: var(--color-success-darker);
 `;
 
-const ToolCallsInfoWrapper = styled.div`
-  display: flex;
-  flex-direction: column;
-  gap: var(--spacing-xxs);
+const ToolCallsActivity = styled(SearchAiActivity)`
   margin: 0 0 var(--spacing-sm) 0;
-  font-size: var(--font-size-xs);
-  color: var(--search-ai-text-color);
-  opacity: 0.6;
-`;
-
-const ToolCallInfoItem = styled.div`
-  display: flex;
-  align-items: center;
-  gap: var(--spacing-xxs);
-`;
-
-const ToolCallText = styled.span<{ $isSearching?: boolean }>`
-  font-weight: var(--font-weight-regular);
 
-  ${({ $isSearching }) =>
-    $isSearching &&
-    `
-    animation: pulse 1.5s ease-in-out infinite;
-    
-    @keyframes pulse {
-      0%, 100% {
-        opacity: 1;
-      }
-      50% {
-        opacity: 0.4;
-      }
-    }
-  `}
+  &:last-child {
+    margin-bottom: var(--spacing-xxs);
+  }
 `;

package/src/components/Search/SearchItem.tsx

@@ -9,7 +9,7 @@ import { Link } from '@redocly/theme/components/Link/Link';
 import { Image } from '@redocly/theme/components/Image/Image';
 import { searchHighlight } from '@redocly/theme/components/Search/SearchHighlight';
 import { Badge } from '@redocly/theme/components/Badge/Badge';
-import { trimText, getOperationColor } from '@redocly/theme/core/utils';
+import { assignRef, trimText, getOperationColor } from '@redocly/theme/core/utils';
 import { ReturnKeyIcon } from '@redocly/theme/icons/ReturnKeyIcon/ReturnKeyIcon';
 import { useThemeHooks } from '@redocly/theme/core/hooks';
 
@@ -61,14 +61,7 @@ export function SearchItem({
       tabIndex={0}
       innerRef={(el: HTMLAnchorElement) => {
         ref.current = el;
-
-        if (!innerRef) return;
-
-        if (typeof innerRef === 'function') {
-          innerRef(el);
-        } else {
-          innerRef.current = el;
-        }
+        assignRef(innerRef, el);
       }}
       data-component-name="Search/SearchItem"
     >

package/src/components/Search/variables.ts

@@ -199,8 +199,21 @@ export const search = css`
   --search-ai-suggestions-title-font-weight: var(--font-weight-light);
   --search-ai-suggestions-text-color: var(--text-color-description);
 
-  --search-ai-thinking-dots-gap: 4px;
-  --search-ai-thinking-dots-padding: 4px 0;
+  --search-ai-activity-font-size: var(--font-size-base);
+  --search-ai-activity-line-height: var(--line-height-sm);
+  --search-ai-activity-count-font-size: var(--font-size-sm);
+  --search-ai-activity-count-bg-color: var(--border-color-secondary);
+  --search-ai-activity-text-color: var(--text-color-description);
+  --search-ai-activity-text-color-hover: var(--text-color-primary);
+  --search-ai-activity-detail-color: var(--text-color-secondary);
+  --search-ai-activity-shimmer-color: var(--text-color-primary);
+  --search-ai-activity-rail-color: var(--border-color-primary);
+  --search-ai-activity-icon-size: 14px;
+  --search-ai-activity-fade-duration: 200ms;
+  --search-ai-activity-expand-duration: 250ms;
+  --search-ai-activity-shimmer-duration: 2s;
+  --search-ai-activity-easing: cubic-bezier(0.32, 0.72, 0, 1);
+
   --search-ai-thinking-dot-size: 6px;
   --search-ai-thinking-dot-color: var(--search-ai-gradient);
 

package/src/components/Select/SelectInput.tsx

@@ -6,6 +6,7 @@ import type { SelectOption } from '@redocly/theme/core/types';
 import { Tag } from '@redocly/theme/components/Tag/Tag';
 import { CloseIcon } from '@redocly/theme/icons/CloseIcon/CloseIcon';
 import { Button } from '@redocly/theme/components/Button/Button';
+import { assignRef } from '@redocly/theme/core/utils';
 
 type SelectInputProps<T> = {
   id?: string;
@@ -125,14 +126,7 @@ export function SelectInput<T>(props: SelectInputProps<T>): React.ReactNode {
         if (!input) return;
 
         inputRef.current = input;
-
-        if (!forwardedInputRef) return;
-
-        if (typeof forwardedInputRef === 'function') {
-          forwardedInputRef(input);
-        } else {
-          forwardedInputRef.current = input;
-        }
+        assignRef(forwardedInputRef, input);
       }}
       $width={multiple ? (!searchValue && selectedOptions.length ? '10px' : 'auto') : '100%'}
       tabIndex={0}

package/src/components/SplitButton/SplitButton.tsx

@@ -1,4 +1,4 @@
-import React from 'react';
+import React, { useRef } from 'react';
 import styled from 'styled-components';
 
 import type { ComponentProps, JSX } from 'react';
@@ -45,9 +45,14 @@ export function SplitButton(props: SplitButtonProps): JSX.Element {
   } = props;
 
   const hasMenu = typeof children === 'function' || React.Children.toArray(children).length > 0;
+  const wrapperRef = useRef<HTMLDivElement>(null);
 
   return (
-    <SplitButtonWrapper data-component-name="SplitButton/SplitButton" className={className}>
+    <SplitButtonWrapper
+      data-component-name="SplitButton/SplitButton"
+      className={className}
+      ref={wrapperRef}
+    >
       <ButtonGroup variant={variant} size={size}>
         {button}
         {hasMenu ? (
@@ -56,6 +61,7 @@ export function SplitButton(props: SplitButtonProps): JSX.Element {
             placement={placement}
             alignment={alignment}
             portalled={portalled}
+            alignmentAnchorRef={wrapperRef}
             withArrow
             onOpen={onOpen}
             onClose={onClose}

package/src/core/constants/mcp.ts

@@ -1,15 +1,9 @@
-import type { MCPOption } from '../types/mcp';
-
 export const DEFAULT_MCP_SERVER_NAME = 'mcp-server';
 
 export const MCP_ROUTE = '/mcp';
 
 export const PUBLIC_MCP_ROUTE = '/mcp-public';
 
-export const DEFAULT_MCP_OPTIONS: MCPOption[] = [
-  'cursor',
-  'vscode',
-  'claude-code',
-  'codex',
-  'copy',
-];
+export const MCP_OPTIONS = ['cursor', 'vscode', 'claude-code', 'codex', 'copy'] as const;
+
+export const DEFAULT_MCP_OPTIONS = [...MCP_OPTIONS];

package/src/core/constants/search.ts

@@ -53,7 +53,7 @@ export const TOOL_CALL_DISPLAY_TEXT: Partial<
 > = {
   [ToolCallName.SearchDocumentation]: {
     inProgressText: 'Searching documentation...',
-    completedText: 'Search completed',
+    completedText: 'Searched the documentation',
   },
   [ToolCallName.ListApis]: {
     inProgressText: 'Browsing APIs...',
@@ -75,6 +75,10 @@ export const TOOL_CALL_DISPLAY_TEXT: Partial<
     inProgressText: 'Reading API description...',
     completedText: 'Read API description',
   },
+  [ToolCallName.Execute]: {
+    inProgressText: 'Running code...',
+    completedText: 'Ran code',
+  },
   [ToolCallName.DescribeTools]: {
     inProgressText: 'Discovering available tools...',
     completedText: 'Discovered available tools',

package/src/core/hooks/__mocks__/index.ts

@@ -23,6 +23,7 @@ export * from '../menu/use-mobile-menu-levels';
 export * from '../feedback/use-report-dialog';
 export * from '../use-product-picker';
 export * from '../search/use-search-dialog';
+export * from '../search/use-search-ai-activity';
 export * from '../use-language-picker';
 export * from './use-element-size';
 export * from './use-time-ago';

package/src/core/hooks/index.ts

@@ -30,6 +30,7 @@ export * from './use-product-picker';
 export * from './search/use-search-dialog';
 export * from './search/use-search-filter';
 export * from './search/use-feedback-tooltip';
+export * from './search/use-search-ai-activity';
 export * from './use-controlled-state';
 export * from './use-codeblock-tabs-controls';
 export * from './code-walkthrough/use-code-walkthrough';

package/src/core/hooks/menu/use-collapse.ts

@@ -207,5 +207,5 @@ export function useEvent<T extends (...args: any[]) => any>(callback?: T): T {
     ref.current = callback;
   });
 
-  return useCallback(((...args: Parameters<T>) => ref.current?.(...args)) as T, []);
+  return useCallback((...args: Parameters<T>) => ref.current?.(...args), []) as T;
 }

package/src/core/hooks/search/use-search-ai-activity.ts

@@ -0,0 +1,31 @@
+import type { SearchAiActivityStatus, SearchAiActivityStep, ToolCall } from '../../types/search';
+
+import { useThemeHooks } from '../use-theme-hooks';
+import { getSearchAiActivityStatus, getSearchAiActivityStep } from '../../utils/search-ai-activity';
+
+type UseSearchAiActivityParams = {
+  toolCalls: ToolCall[];
+  isActive: boolean;
+};
+
+type UseSearchAiActivityReturn = {
+  status: SearchAiActivityStatus;
+  steps: SearchAiActivityStep[];
+};
+
+export function useSearchAiActivity({
+  toolCalls,
+  isActive,
+}: UseSearchAiActivityParams): UseSearchAiActivityReturn {
+  const { useTranslate } = useThemeHooks();
+  const { translate } = useTranslate();
+
+  const runningToolCall = isActive ? toolCalls.find((toolCall) => !toolCall.result) : undefined;
+
+  return {
+    status: getSearchAiActivityStatus(toolCalls, isActive, runningToolCall, translate),
+    steps: toolCalls.map((toolCall) =>
+      getSearchAiActivityStep(toolCall, isActive && !toolCall.result, translate),
+    ),
+  };
+}

package/src/core/hooks/use-connect-mcp-button.ts

@@ -7,7 +7,7 @@ import { useThemeHooks } from './use-theme-hooks';
 import { useMCPConfig } from './use-mcp-config';
 import { ClipboardService } from '../utils/clipboard-service';
 import { DEFAULT_MCP_OPTIONS } from '../constants/mcp';
-import { generateClaudeCodeCommand, generateCodexCommand } from '../utils/mcp';
+import { generateClaudeCodeCommand, generateCodexCommand, isMCPOption } from '../utils/mcp';
 import { getBaseDataAttributes } from '../utils/telemetry/get-base-data-attributes';
 
 export type McpButtonOptions = {
@@ -80,7 +80,12 @@ export function useConnectMCPButton({
     [translate],
   );
 
-  const visibleOptions = useMemo(() => options.filter(Boolean), [options]);
+  // Markdoc reports attribute errors but still renders the tag, so `options` can be any value.
+  const visibleOptions = useMemo(
+    () =>
+      Array.isArray(options) ? [...new Set(options.filter(isMCPOption))] : [...DEFAULT_MCP_OPTIONS],
+    [options],
+  );
 
   return {
     copiedOption,

package/src/core/hooks/use-full-height.ts

@@ -3,9 +3,9 @@ import throttle from 'lodash.throttle';
 
 import type { RefObject } from 'react';
 
-export function useFullHeight(element: RefObject<HTMLElement | null>): void {
+export function useFullHeight(elementRef: RefObject<HTMLElement | null>): void {
   const handler = useCallback(() => {
-    if (!element.current) {
+    if (!elementRef.current) {
       return;
     }
 
@@ -14,19 +14,19 @@ export function useFullHeight(element: RefObject<HTMLElement | null>): void {
       return;
     }
 
-    const elementTop = element.current.getBoundingClientRect().top;
+    const elementTop = elementRef.current.getBoundingClientRect().top;
     const footerOffset = footer.offsetTop - window.scrollY - elementTop;
     if (footerOffset > window.innerHeight) {
-      element.current.style.maxHeight = `${window.innerHeight - elementTop}px`;
+      elementRef.current.style.maxHeight = `${window.innerHeight - elementTop}px`;
     } else {
-      element.current.style.maxHeight = `${footerOffset}px`;
+      elementRef.current.style.maxHeight = `${footerOffset}px`;
     }
-  }, [element]);
+  }, [elementRef]);
 
   const throttledHandler = useMemo(() => throttle(handler, 150), [handler]);
 
   useEffect(() => {
-    if (typeof window === 'undefined' || !element.current) {
+    if (typeof window === 'undefined' || !elementRef.current) {
       return () => {
         // nope
       };
@@ -45,5 +45,5 @@ export function useFullHeight(element: RefObject<HTMLElement | null>): void {
       window.removeEventListener('scroll', throttledHandler);
       window.removeEventListener('resize', throttledHandler);
     };
-  }, [throttledHandler, element, handler]);
+  }, [throttledHandler, elementRef, handler]);
 }