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

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,