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

package/src/core/styles/global.ts

@@ -1330,83 +1330,88 @@ const replay = css`
 `;
 
 
+/** The light theme tokens without a selector, for a host that sets them on one element. */
+export const tokens = css`
+  ${accordion}
+  ${admonition}
+  ${apiReferenceDocs}
+  ${apiReferencePanels}
+  ${badges}
+  ${banner}
+  ${borders}
+  ${consent}
+  ${breadcrumbs}
+  ${button}
+  ${aiAssistantButton}
+  ${cards}
+  ${catalog}
+  ${catalogClassic}
+  ${code}
+  ${codeWalkthrough}
+  ${docsDropdown}
+  ${dropdown}
+  ${error}
+  ${filter}
+  ${footer}
+  ${headingsTypography}
+  ${httpTag}
+  ${image}
+  ${inputs}
+  ${languagePicker}
+  ${lastUpdated}
+  ${links}
+  ${loadProgressBar}
+  ${logo}
+  ${markdown}
+  ${markdownAccordion}
+  ${markdownTabs}
+  ${markdownNumberedList}
+  ${diagram}
+  ${menu}
+  ${mobileMenu}
+  ${modal}
+  ${navbar}
+  ${pages}
+  ${productPicker}
+  ${responsePanelColors}
+  ${search}
+  ${navigationTabs}
+  ${select}
+  ${sidebar}
+  ${sizeAndSpace}
+  ${tag}
+  ${themeColors}
+  ${activeBrandPaletteLight}
+  ${tile}
+  ${toc}
+  ${tooltip}
+  ${typography}
+  ${userMenu}
+  ${versionPicker}
+  ${zIndexDepth}
+  ${scorecardColors}
+  ${statusCode}
+  ${tab}
+  ${icon}
+  ${tree}
+  ${segmented}
+  ${switcher}
+  ${checkbox}
+  ${feedback}
+  ${scorecard}
+  ${datePicker}
+  ${replay}
+  ${skipContent}
+  ${pageActions}
+  ${svgViewer}
+  ${toast}
+  ${pageNavigation}
+
+`;
+
 export const styles = css<{ palette?: string }>`
   :root {
-    ${accordion}
-    ${admonition}
-    ${apiReferenceDocs}
-    ${apiReferencePanels}
-    ${badges}
-    ${banner}
-    ${borders}
-    ${consent}
-    ${breadcrumbs}
-    ${button}
-    ${aiAssistantButton}
-    ${cards}
-    ${catalog}
-    ${catalogClassic}
-    ${code}
-    ${codeWalkthrough}
-    ${docsDropdown}
-    ${dropdown}
-    ${error}
-    ${filter}
-    ${footer}
-    ${headingsTypography}
-    ${httpTag}
-    ${image}
-    ${inputs}
-    ${languagePicker}
-    ${lastUpdated}
-    ${links}
-    ${loadProgressBar}
-    ${logo}
-    ${markdown}
-    ${markdownAccordion}
-    ${markdownTabs}
-    ${markdownNumberedList}
-    ${diagram}
-    ${menu}
-    ${mobileMenu}
-    ${modal}
-    ${navbar}
-    ${pages}
-    ${productPicker}
-    ${responsePanelColors}
-    ${search}
-    ${navigationTabs}
-    ${select}
-    ${sidebar}
-    ${sizeAndSpace}
-    ${tag}
-    ${themeColors}
-    ${activeBrandPaletteLight}
-    ${tile}
-    ${toc}
-    ${tooltip}
-    ${typography}
-    ${userMenu}
-    ${versionPicker}
-    ${zIndexDepth}
-    ${scorecardColors}
-    ${statusCode}
-    ${tab}
-    ${icon}
-    ${tree}
-    ${segmented}
-    ${switcher}
-    ${checkbox}
-    ${feedback}
-    ${scorecard}
-    ${datePicker}
-    ${replay}
-    ${skipContent}
-    ${pageActions}
-    ${svgViewer}
-    ${toast}
-    ${pageNavigation}
-
+    ${tokens}
     background-color: var(--bg-color);
     color: var(--text-color-primary);
     font-family: var(--font-family-base);

package/src/core/styles/index.ts

@@ -1,3 +1,4 @@
 export * from './global';
 export * from './dark';
-export { xyflow } from './xyflow';
+export { xyflow } from './xyflow';
+export { searchAiAppearAnimation } from './search-ai-appear';

package/src/core/styles/search-ai-appear.ts

@@ -0,0 +1,16 @@
+import { css, keyframes } from 'styled-components';
+
+const appear = keyframes`
+  from {
+    opacity: 0;
+    transform: translateY(4px);
+  }
+`;
+
+export const searchAiAppearAnimation = css`
+  animation: ${appear} var(--search-ai-activity-fade-duration) ease-out;
+
+  @media (prefers-reduced-motion: reduce) {
+    animation: none;
+  }
+`;

package/src/core/types/dropdown.ts

@@ -0,0 +1 @@
+export type DropdownAlignment = 'start' | 'end';

package/src/core/types/index.ts

@@ -25,3 +25,4 @@ export type * from './tooltip';
 export type * from './toast';
 export type * from './link';
 export type * from './button-group';
+export type * from './dropdown';

package/src/core/types/l10n.ts

@@ -113,7 +113,7 @@ export type TranslationKey =
   | 'search.ai.feedback.thanks'
   | 'search.ai.toolCall.executed'
   | 'search.ai.toolCall.executing'
-  | 'search.ai.toolCall.withArgs'
+  | 'search.ai.toolCall.usedTools'
   | 'search.ai.button'
   | 'search.ai.label'
   | 'search.ai.disclaimer'

package/src/core/types/mcp.ts

@@ -1,6 +1,8 @@
+import type { MCP_OPTIONS } from '../constants/mcp';
+
 export type MCPClientType = 'cursor' | 'vscode';
 
-export type MCPOption = 'cursor' | 'vscode' | 'claude-code' | 'codex' | 'copy';
+export type MCPOption = (typeof MCP_OPTIONS)[number];
 
 export type McpConnectionParams = {
   serverName: string;

package/src/core/types/search.ts

@@ -117,6 +117,27 @@ export type ToolCall = {
 
 export type ContentSegment = { type: 'text'; text: string } | { type: 'tool'; toolCall: ToolCall };
 
+export type GroupedContentSegment =
+  | { type: 'text'; text: string }
+  /** `isActive`: the assistant still works on this group, with nothing written after it yet. */
+  | { type: 'tools'; toolCalls: ToolCall[]; isActive: boolean };
+
+export type SearchAiActivityKind = 'thinking' | 'search' | 'code' | 'support';
+
+export type SearchAiActivityStatus = {
+  label: string;
+  detail?: string;
+  kind: SearchAiActivityKind;
+  isRunning: boolean;
+};
+
+export type SearchAiActivityStep = {
+  id: string;
+  label: string;
+  kind: SearchAiActivityKind;
+  isRunning: boolean;
+};
+
 export type AiSearchConversationItem = {
   role: AiSearchConversationRole;
   content: string;

package/src/core/utils/assign-ref.ts

@@ -0,0 +1,9 @@
+import type { Ref } from 'react';
+
+export function assignRef<T>(ref: Ref<T> | undefined, value: T): void {
+  if (typeof ref === 'function') {
+    ref(value);
+  } else if (ref) {
+    ref.current = value;
+  }
+}

package/src/core/utils/content-segments.ts

@@ -1,5 +1,13 @@
-import type { ToolCall, ContentSegment } from '../types/search';
+import type { ToolCall, ContentSegment, GroupedContentSegment } from '../types/search';
 
+const SENTENCE_END_MARKS = '.!?:;';
+const CLOSING_MARKS = `"')]*_\``;
+const CODE_FENCE = /^[ \t]*(```|~~~)/gm;
+
+/**
+ * Splits an answer at its tool calls. A call made in the middle of a sentence or a code block is
+ * placed at the end of that paragraph, so the sentence reads as one piece.
+ */
 export function splitContentByToolCalls(
   content: string | undefined,
   toolCalls: ToolCall[] | undefined,
@@ -8,20 +16,104 @@ export function splitContentByToolCalls(
     return [{ type: 'text', text: content || '' }];
   }
 
+  const text = content ?? '';
+  const fences = Array.from(text.matchAll(CODE_FENCE), (match) => match.index);
   const segments: ContentSegment[] = [];
   let lastPos = 0;
 
   for (const toolCall of toolCalls) {
-    if (content && toolCall.position > lastPos) {
-      segments.push({ type: 'text', text: content.substring(lastPos, toolCall.position) });
+    const position = Math.max(lastPos, getBlockBoundary(text, toolCall.position, fences));
+    if (position > lastPos) {
+      segments.push({ type: 'text', text: text.substring(lastPos, position) });
     }
     segments.push({ type: 'tool', toolCall });
-    lastPos = toolCall.position;
+    lastPos = position;
   }
 
-  if (content && lastPos < content.length) {
-    segments.push({ type: 'text', text: content.substring(lastPos) });
+  if (lastPos < text.length) {
+    segments.push({ type: 'text', text: text.substring(lastPos) });
   }
 
   return segments;
 }
+
+function getBlockBoundary(content: string, position: number, fences: number[]): number {
+  if (position <= 0 || position >= content.length) {
+    return position;
+  }
+  const isInsideCodeFence = (index: number) => {
+    let count = 0;
+    while (count < fences.length && fences[count] < index) count++;
+    return count % 2 === 1;
+  };
+  if (!isInsideCodeFence(position) && endsBlockOrSentence(content, position)) {
+    return position;
+  }
+  for (
+    let boundary = content.indexOf('\n\n', position);
+    boundary !== -1;
+    boundary = content.indexOf('\n\n', boundary + 2)
+  ) {
+    if (!isInsideCodeFence(boundary)) {
+      return boundary;
+    }
+  }
+  return content.length;
+}
+
+function endsBlockOrSentence(content: string, position: number): boolean {
+  let index = position - 1;
+  while (index >= 0 && /\s/.test(content[index])) {
+    if (content[index] === '\n') return true;
+    index--;
+  }
+  while (index >= 0 && CLOSING_MARKS.includes(content[index])) index--;
+  return index >= 0 && SENTENCE_END_MARKS.includes(content[index]);
+}
+
+/**
+ * Groups consecutive tool calls and drops text that is only whitespace. While the answer is
+ * generated, an answer with nothing to show yet is one empty active group (the thinking status),
+ * and the last group is active until text that is not whitespace follows it.
+ */
+export function groupToolCallSegments(
+  segments: ContentSegment[],
+  isGenerating?: boolean,
+): GroupedContentSegment[] {
+  const grouped: GroupedContentSegment[] = [];
+  let text = '';
+
+  for (const segment of segments) {
+    if (segment.type === 'text') {
+      text += segment.text;
+      if (segment.text.trim()) {
+        grouped.push(segment);
+      }
+      continue;
+    }
+    const previous = grouped.at(-1);
+    if (previous?.type === 'tools') {
+      previous.toolCalls.push(segment.toolCall);
+    } else {
+      grouped.push({ type: 'tools', toolCalls: [segment.toolCall], isActive: false });
+    }
+  }
+
+  if (!isGenerating) {
+    return grouped;
+  }
+  const last = grouped.at(-1);
+  if (last?.type === 'tools') {
+    last.isActive = !text.slice(last.toolCalls.at(-1)?.position ?? 0).trim();
+  } else if (grouped.length === 0) {
+    return [{ type: 'tools', toolCalls: [], isActive: true }];
+  }
+  return grouped;
+}
+
+export function hasToolCallsAndText(segments: ContentSegment[]): boolean {
+  return (
+    segments.some((segment) => segment.type === 'tool') &&
+    segments.some((segment) => segment.type === 'text' && segment.text.trim().length > 0)
+  );
+}

package/src/core/utils/dropdown.ts

@@ -0,0 +1,14 @@
+import type { DropdownAlignment } from '../types/dropdown';
+
+export function fitDropdownAlignment(
+  anchor: DOMRect,
+  menuWidth: number,
+  alignment: DropdownAlignment = 'start',
+): DropdownAlignment {
+  const fits: Record<DropdownAlignment, boolean> = {
+    start: anchor.left + menuWidth <= window.innerWidth,
+    end: anchor.right - menuWidth >= 0,
+  };
+  const other: DropdownAlignment = alignment === 'end' ? 'start' : 'end';
+  return fits[alignment] || !fits[other] ? alignment : other;
+}

package/src/core/utils/index.ts

@@ -51,3 +51,5 @@ export * from './telemetry/get-base-data-attributes';
 export * from './telemetry/generate-before-after-context';
 export * from './RenderWithLink';
 export * from './consent-settings-link-placement';
+export * from './assign-ref';
+export * from './dropdown';

package/src/core/utils/mcp.ts

@@ -1,4 +1,10 @@
-import type { MCPClientType, McpConnectionParams } from '../types';
+import type { MCPClientType, McpConnectionParams, MCPOption } from '../types';
+
+import { MCP_OPTIONS } from '../constants/mcp';
+
+export function isMCPOption(value: unknown): value is MCPOption {
+  return (MCP_OPTIONS as readonly unknown[]).includes(value);
+}
 
 function generateCursorMCPDeepLink(config: McpConnectionParams): string {
   const cursorConfig = {

package/src/core/utils/search-ai-activity.ts

@@ -0,0 +1,110 @@
+import type { TFunction } from '../types/l10n';
+
+import {
+  ToolCallName,
+  type SearchAiActivityStatus,
+  type SearchAiActivityStep,
+  type ToolCall,
+  type SearchAiActivityKind,
+} from '../types/search';
+import { TOOL_CALL_DISPLAY_TEXT } from '../constants/search';
+import { isObject } from './type-guards';
+
+export function getSearchAiActivityStatus(
+  toolCalls: ToolCall[],
+  isActive: boolean,
+  runningToolCall: ToolCall | undefined,
+  translate: TFunction,
+): SearchAiActivityStatus {
+  const latestToolCall = toolCalls.at(-1);
+  if (!latestToolCall) {
+    return {
+      label: translate('search.ai.thinkingText', 'Thinking...'),
+      kind: 'thinking',
+      isRunning: true,
+    };
+  }
+
+  if (isActive || toolCalls.length === 1) {
+    const toolCall = runningToolCall ?? latestToolCall;
+    return {
+      ...getToolCallLabel(toolCall, !isActive, translate),
+      kind: getSearchAiActivityKind(toolCall.name),
+      isRunning: isActive,
+    };
+  }
+
+  const isSameTool = toolCalls.every((toolCall) => toolCall.name === latestToolCall.name);
+  const sharedText = isSameTool
+    ? TOOL_CALL_DISPLAY_TEXT[latestToolCall.name]?.completedText
+    : undefined;
+  return {
+    label: sharedText ?? translate('search.ai.toolCall.usedTools', 'Used tools'),
+    kind: isSameTool ? getSearchAiActivityKind(latestToolCall.name) : 'code',
+    isRunning: false,
+  };
+}
+
+export function getSearchAiActivityStep(
+  toolCall: ToolCall,
+  isRunning: boolean,
+  translate: TFunction,
+): SearchAiActivityStep {
+  const detail = getToolCallDetail(toolCall);
+  const kind = getSearchAiActivityKind(toolCall.name);
+
+  if (toolCall.name === ToolCallName.SearchDocumentation && detail) {
+    return { id: toolCall.id, label: `“${detail}”`, kind, isRunning };
+  }
+  const { label } = getToolCallLabel(toolCall, !isRunning, translate);
+  return { id: toolCall.id, label: detail ? label : stripEllipsis(label), kind, isRunning };
+}
+
+function getToolCallLabel(
+  toolCall: ToolCall,
+  isCompleted: boolean,
+  translate: TFunction,
+): { label: string; detail?: string } {
+  const detail = getToolCallDetail(toolCall);
+  if (toolCall.name === ToolCallName.Execute && detail) {
+    return { label: detail };
+  }
+  const builtInText = TOOL_CALL_DISPLAY_TEXT[toolCall.name];
+  if (builtInText) {
+    const text = isCompleted ? builtInText.completedText : builtInText.inProgressText;
+    return detail ? { label: stripEllipsis(text), detail } : { label: text };
+  }
+  const prefix = isCompleted
+    ? translate('search.ai.toolCall.executed', 'Executed')
+    : translate('search.ai.toolCall.executing', 'Executing');
+  return { label: `${prefix} ${toolCall.name}` };
+}
+
+function getSearchAiActivityKind(name: string): SearchAiActivityKind {
+  if (name === ToolCallName.SearchDocumentation) return 'search';
+  if (name === ToolCallName.ContactSupport) return 'support';
+  return 'code';
+}
+
+function getToolCallDetail(toolCall: ToolCall): string | undefined {
+  switch (toolCall.name) {
+    case ToolCallName.SearchDocumentation:
+      return getStringArg(toolCall.args, 'query');
+    case ToolCallName.Execute:
+      return getStringArg(toolCall.args, 'description');
+    default:
+      return undefined;
+  }
+}
+
+function getStringArg(args: unknown, name: string): string | undefined {
+  if (!isObject(args) || !(name in args)) {
+    return undefined;
+  }
+  const value: unknown = Reflect.get(args, name);
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function stripEllipsis(text: string): string {
+  return text.replace(/(\.{3}|…)$/, '');
+}

package/src/markdoc/tags/connect-mcp.ts

@@ -1,6 +1,7 @@
 import type { MarkdocSchemaWrapper } from '@redocly/theme/markdoc/tags/types';
 
-import { DEFAULT_MCP_OPTIONS } from '@redocly/theme/core/constants';
+import { DEFAULT_MCP_OPTIONS, MCP_OPTIONS } from '@redocly/theme/core/constants';
+import { isMCPOption } from '@redocly/theme/core/utils';
 
 export const connectMcp: MarkdocSchemaWrapper = {
   schema: {
@@ -19,6 +20,20 @@ export const connectMcp: MarkdocSchemaWrapper = {
       options: {
         type: Array,
         default: DEFAULT_MCP_OPTIONS,
+        validate(value) {
+          if (!Array.isArray(value)) return [];
+
+          const unknownOptions = value.filter((option) => !isMCPOption(option));
+          if (unknownOptions.length === 0) return [];
+
+          return [
+            {
+              id: 'invalid-connect-mcp-options',
+              level: 'error',
+              message: `Invalid connect-mcp options: ${unknownOptions.join(', ')}. Must be one of: ${MCP_OPTIONS.join(', ')}`,
+            },
+          ];
+        },
       },
     },
     selfClosing: true,