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

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/Dynamic.tsx

@@ -5,60 +5,86 @@ interface DynamicOptions<TProps extends Record<string, unknown>> {
   loading?: React.ComponentType<TProps>;
 }
 
+/**
+ * A component from `dynamic()`. After `preload()` resolves, the component renders without a
+ * loading state. On the server, `preload()` does not load a client-only component (`ssr: false`).
+ */
+export type DynamicComponent<TProps> = React.ComponentType<TProps> & {
+  preload(): Promise<void>;
+};
+
 export function dynamic<TProps extends Record<string, unknown>>(
   factory: () => Promise<
     React.ComponentType<TProps> | { default: React.ComponentType<TProps> } | Record<string, unknown>
   >,
   { ssr = true, loading }: DynamicOptions<TProps> = {},
-): React.ComponentType<TProps> {
-  const Component = React.lazy(() =>
-    factory().then((mod) => {
-      // Case 1: factory() => import('./SomeModule') - direct import
-      // Case 2: factory() => import('./SomeModule').then(mod => mod.default) - extract default
-      if (typeof mod === 'function') {
-        return { default: mod };
-      }
-
-      // Case 3: factory() => import('./SomeModule').then(mod => ({ default: mod.default })) - manual wrap
-      // Case 4: factory() => import('./SomeModule').then(mod => ({ default: mod.Named })) - manual wrap named
-      if (mod && typeof mod === 'object' && 'default' in mod) {
-        const defaultExport = mod.default;
-
-        // Handle both function components and React component objects (e.g., memo/forwardRef)
-        if (typeof defaultExport === 'function') {
-          return { default: defaultExport as React.ComponentType<TProps> };
+): DynamicComponent<TProps> {
+  let loaded: React.ComponentType<TProps> | undefined;
+  let pending: Promise<{ default: React.ComponentType<TProps> }> | undefined;
+
+  const load = () =>
+    (pending ??= factory()
+      .then((mod) => {
+        // Case 1: factory() => import('./SomeModule') - direct import
+        // Case 2: factory() => import('./SomeModule').then(mod => mod.default) - extract default
+        if (typeof mod === 'function') {
+          return { default: mod };
         }
 
-        if (defaultExport && typeof defaultExport === 'object' && '$$typeof' in defaultExport) {
-          return { default: defaultExport as React.ComponentType<TProps> };
+        // Case 3: factory() => import('./SomeModule').then(mod => ({ default: mod.default })) - manual wrap
+        // Case 4: factory() => import('./SomeModule').then(mod => ({ default: mod.Named })) - manual wrap named
+        if (mod && typeof mod === 'object' && 'default' in mod) {
+          const defaultExport = mod.default;
+
+          // Handle both function components and React component objects (e.g., memo/forwardRef)
+          if (typeof defaultExport === 'function') {
+            return { default: defaultExport as React.ComponentType<TProps> };
+          }
+
+          if (defaultExport && typeof defaultExport === 'object' && '$$typeof' in defaultExport) {
+            return { default: defaultExport as React.ComponentType<TProps> };
+          }
         }
-      }
 
-      // Case 5: factory() => import('./SomeModule').then(mod => mod.Named) - find named export
-      if (mod && typeof mod === 'object') {
-        const modObj = mod as Record<string, unknown>;
+        // Case 5: factory() => import('./SomeModule').then(mod => mod.Named) - find named export
+        if (mod && typeof mod === 'object') {
+          const modObj = mod as Record<string, unknown>;
 
-        for (const key in modObj) {
-          const value = modObj[key];
+          for (const key in modObj) {
+            const value = modObj[key];
 
-          if (typeof value === 'function') {
-            return { default: value as React.ComponentType<TProps> };
-          }
+            if (typeof value === 'function') {
+              return { default: value as React.ComponentType<TProps> };
+            }
 
-          if (value && typeof value === 'object' && '$$typeof' in value) {
-            return { default: value as React.ComponentType<TProps> };
+            if (value && typeof value === 'object' && '$$typeof' in value) {
+              return { default: value as React.ComponentType<TProps> };
+            }
           }
         }
-      }
 
-      throw new Error('Dynamic import did not return a valid React component');
-    }),
-  );
+        throw new Error('Dynamic import did not return a valid React component');
+      })
+      .then(
+        (module) => {
+          loaded = module.default;
+          return module;
+        },
+        (error: unknown) => {
+          // A failed load is not kept, so the next preload tries again.
+          pending = undefined;
+          throw error;
+        },
+      ));
+
+  const LazyComponent = React.lazy(load);
 
   const LoadingComponent: React.ComponentType<TProps> = loading || (() => null);
 
-  return (props: TProps) => {
+  const DynamicComponent = (props: TProps) => {
     const [hasMounted, setHasMounted] = React.useState(false);
+    // Fixed per instance: a change of the element type would remount the component.
+    const [Component] = React.useState(() => loaded ?? LazyComponent);
 
     React.useEffect(() => {
       setHasMounted(true);
@@ -82,4 +108,10 @@ export function dynamic<TProps extends Record<string, unknown>>(
       </React.Suspense>
     );
   };
+
+  return Object.assign(DynamicComponent, {
+    async preload() {
+      if (ssr || typeof window !== 'undefined') await load();
+    },
+  });
 }

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/icons/CheckboxIcon/CheckboxIcon.tsx

@@ -11,6 +11,7 @@ const Icon = ({
   checked?: boolean;
   onClick?: () => void;
 }) => (
+  // oxlint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-static-element-interactions -- the control that renders the icon handles the keyboard
   <span className={className} onClick={onClick}>
     {checked ? (
       <svg

package/src/icons/ChevronSortIcon/ChevronSortIcon.tsx

@@ -6,6 +6,7 @@ import type { IconProps } from '@redocly/theme/icons/types';
 import { getCssColorVariable } from '@redocly/theme/core/utils';
 
 const Icon = ({ className, onClick }: IconProps & { onClick?: () => void }) => (
+  // oxlint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-static-element-interactions -- the control that renders the icon handles the keyboard
   <svg
     className={className}
     onClick={onClick}

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,