@redocly/theme 0.70.0-next.1 → 0.70.0-next.11

package/src/core/types/navigation-tabs.ts

@@ -0,0 +1,54 @@
+export type NavigationTabMenuEntry = {
+  tabId: string;
+  label: string;
+  labelTranslationKey?: string;
+  link: string;
+  icon?: string;
+  srcSet?: string;
+  external?: boolean;
+  target?: '_self' | '_blank';
+};
+
+export type NavigationTab = {
+  tabId: string;
+  label: string;
+  labelTranslationKey?: string;
+  link?: string;
+  icon?: string;
+  srcSet?: string;
+  menu?: NavigationTabMenuEntry[];
+};
+
+export type NavigationTabsState = {
+  tabs: NavigationTab[];
+  activeTab?: NavigationTab;
+  activeMenuEntry?: NavigationTabMenuEntry;
+};
+
+export type NavigationTabItem = {
+  type: 'link';
+  label: string;
+  labelTranslationKey?: string;
+  link: string;
+  icon?: string;
+  srcSet?: string;
+  external?: boolean;
+  target?: '_self' | '_blank';
+  active?: boolean;
+};
+
+type NavigationTabGroupItem = {
+  type: 'group';
+  label: string;
+  labelTranslationKey?: string;
+  icon?: string;
+  srcSet?: string;
+  items: NavigationTabItem[];
+  active?: boolean;
+};
+
+export type NavigationTabRowItem = NavigationTabItem | NavigationTabGroupItem;
+
+export type NavigationTabsConfig = {
+  items: NavigationTabRowItem[];
+};

package/src/core/types/prompt.ts

@@ -0,0 +1,11 @@
+import type { AI_PROMPT_TARGETS } from '../constants/prompt';
+import type { TranslationKey } from './l10n';
+
+export type AiPromptTarget = (typeof AI_PROMPT_TARGETS)[keyof typeof AI_PROMPT_TARGETS];
+
+export type AiPromptActionOption = {
+  titleTranslationKey: TranslationKey;
+  titleDefault: string;
+  descriptionTranslationKey: TranslationKey;
+  descriptionDefault: string;
+};

package/src/core/types/search.ts

@@ -45,6 +45,8 @@ export type ParameterHighlight = {
   description: string;
   place: string;
   path: string[];
+  enum?: string;
+  example?: string;
 };
 
 export type SearchItemData = {
@@ -115,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/consent-settings-link-placement.ts

@@ -0,0 +1,18 @@
+import type { ConsentConfig, RedoclyConfig } from '@redocly/config';
+
+export type SettingsLinkPlacement = 'footer' | 'none';
+
+export function resolveSettingsLinkPlacement(
+  consent: ConsentConfig | undefined,
+  footer: RedoclyConfig['footer'] | undefined,
+): SettingsLinkPlacement {
+  const choice = consent?.settingsLink ?? 'auto';
+  if (choice !== 'auto') {
+    return choice;
+  }
+  const footerShown =
+    Boolean(footer) &&
+    !footer?.hide &&
+    (Boolean(footer?.copyrightText) || (Array.isArray(footer?.items) && footer.items.length > 0));
+  return footerShown ? 'footer' : 'none';
+}

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/download-code-walkthrough.ts

@@ -1,6 +1,6 @@
 import { saveAs } from 'file-saver';
 
-import type { CodeWalkthroughFile } from '@redocly/config';
+import type { CodeWalkthroughFile } from '@redocly/theme/core/types';
 
 import { removeLeadingSlash } from './urls';
 import { findClosestCommonDirectory } from './find-closest-common-directory';

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/get-ai-prompt-link.ts

@@ -0,0 +1,30 @@
+import type { AiPromptTarget } from '../types/prompt';
+
+type AiPromptEndpoint = { baseUrl: string; queryParam: string };
+
+const AI_PROMPT_ENDPOINTS: Record<AiPromptTarget, AiPromptEndpoint> = {
+  chatgpt: { baseUrl: 'https://chat.openai.com', queryParam: 'q' },
+  claude: { baseUrl: 'https://claude.ai/new', queryParam: 'q' },
+  // Encoding: https://cursor.com/docs/integrations/deeplinks
+  cursor: { baseUrl: 'https://cursor.com/link/prompt', queryParam: 'text' },
+};
+
+/**
+ * Builds a link that opens an AI tool with the prompt prefilled.
+ *
+ * @param target - The AI tool to open.
+ * @param prompt - The plain-text prompt to prefill.
+ * @returns The absolute URL with the encoded prompt in the query string.
+ *
+ * @example
+ * ```ts
+ * getAiPromptLink('claude', 'Summarize this page');
+ * // 'https://claude.ai/new?q=Summarize+this+page'
+ * ```
+ */
+export function getAiPromptLink(target: AiPromptTarget, prompt: string): string {
+  const { baseUrl, queryParam } = AI_PROMPT_ENDPOINTS[target];
+  const url = new URL(baseUrl);
+  url.searchParams.set(queryParam, prompt);
+  return url.toString();
+}

package/src/core/utils/get-code-walkthrough-file-text.ts

@@ -1,4 +1,4 @@
-import type { CodeWalkthroughFile, CodeWalkthroughNode } from '@redocly/config';
+import type { CodeWalkthroughFile, CodeWalkthroughNode } from '@redocly/theme/core/types';
 
 import { matchCodeWalkthroughConditions } from './match-code-walkthrough-conditions';
 import { replaceInputsWithValue } from './replace-inputs-with-value';

package/src/core/utils/index.ts

@@ -17,6 +17,7 @@ export * from './type-guards';
 export * from './dom';
 export * from './toc';
 export * from './menu';
+export * from './navigation-tabs';
 export * from './load-and-navigate';
 export * from './get-scorecard-color-variable';
 export * from './change-text-casing';
@@ -49,3 +50,7 @@ export * from './tooltip-placement';
 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';
+export * from './get-ai-prompt-link';

package/src/core/utils/match-code-walkthrough-conditions.ts

@@ -1,4 +1,4 @@
-import type { CodeWalkthroughConditionsObject } from '@redocly/config';
+import type { CodeWalkthroughConditionsObject } from '@redocly/theme/core/types';
 
 import { isObject } from './type-guards';
 

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 = {
@@ -19,6 +25,12 @@ function generateVSCodeMCPDeepLink(config: McpConnectionParams): string {
   return `vscode:mcp/install?${encodedConfig}`;
 }
 
+function generateClaudeConnectorLink(config: McpConnectionParams): string {
+  const connectorName = encodeURIComponent(config.serverName);
+  const connectorUrl = encodeURIComponent(config.url);
+  return `https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=${connectorName}&connectorUrl=${connectorUrl}`;
+}
+
 export function generateMCPDeepLink(
   clientType: MCPClientType,
   config: McpConnectionParams,
@@ -28,8 +40,8 @@ export function generateMCPDeepLink(
       return generateCursorMCPDeepLink(config);
     case 'vscode':
       return generateVSCodeMCPDeepLink(config);
-    default:
-      return generateCursorMCPDeepLink(config);
+    case 'claude':
+      return generateClaudeConnectorLink(config);
   }
 }
 
@@ -39,7 +51,7 @@ export function slugifyMcpServerName(name: string): string {
   return name
     .toLowerCase()
     .replace(/[^a-z0-9_-]+/g, '-')
-    .replace(/^-+|-+$/g, '');
+    .replace(/^-+|(?<!-)-+$/g, '');
 }
 
 export function generateClaudeCodeCommand(config: McpConnectionParams): string {

package/src/core/utils/menu.ts

@@ -3,8 +3,10 @@ import type { Location } from 'react-router';
 
 import type { Locale, TFunction } from '../types/l10n';
 import type { ItemState } from '../types/sidebar';
+import type { NavigationTabRowItem, NavigationTabsState } from '../types/navigation-tabs';
 import { MenuItemType } from '../constants/common';
-import { getPathnameForLocale, withoutPathPrefix, withPathPrefix } from './urls';
+import { addLeadingSlash, getPathnameForLocale, withoutPathPrefix, withPathPrefix } from './urls';
+import { toNavigationTabsConfig } from './navigation-tabs';
 
 const TRANSLATION_KEYS = {
   version: 'mobileMenu.version',
@@ -24,10 +26,7 @@ export const mapNavbarItems = (
         ...(navItem.items && {
           items: mapNavbarItems(navItem.items, defaultLocale, currentLocale, locales, location),
         }),
-        ...('link' in navItem && { link: navItem.link || '/' }),
-        active:
-          'link' in navItem &&
-          isItemActive(navItem, defaultLocale, currentLocale, locales, location),
+        active: isItemActive(navItem, defaultLocale, currentLocale, locales, location),
         hasActiveSubItem: !!navItem.items?.find((item) =>
           isItemActive(item, defaultLocale, currentLocale, locales, location),
         ),
@@ -42,10 +41,12 @@ export const isItemActive = (
   locales: Locale[],
   location: Location,
 ): boolean => {
+  if (!item.link) return false;
+
   const pathHash = location.pathname + location.hash;
   const link = item.languageInsensitive
-    ? item.link || ''
-    : getPathnameForLocale(item.link || '/', defaultLocale, currentLocale, locales);
+    ? item.link
+    : getPathnameForLocale(item.link, defaultLocale, currentLocale, locales);
 
   return pathHash === withPathPrefix(link);
 };
@@ -71,7 +72,7 @@ export const buildLanguagesGroup = (
           locale.code,
           locales,
         );
-        const newUrlWithLanguage = `${newLangPathname}${location.search}${location.hash}`;
+        const newUrlWithLanguage = `${addLeadingSlash(newLangPathname)}${location.search}${location.hash}`;
         return {
           type: 'link',
           label: locale.name || locale.code || '',
@@ -112,8 +113,33 @@ export const buildVersionSection = (
   ];
 };
 
+export const buildNavigationTabsSelect = ({
+  navigationTabs,
+}: {
+  navigationTabs: NavigationTabsState | undefined;
+}): ItemState | undefined => {
+  const tabs = toNavigationTabsConfig({ state: navigationTabs })?.items;
+
+  if (!tabs) {
+    return;
+  }
+
+  const activeTab = tabs.find((tab) => tab.active);
+
+  return {
+    type: MenuItemType.Select,
+    label: activeTab?.label ?? 'Navigation tabs',
+    labelTranslationKey: activeTab ? activeTab.labelTranslationKey : 'navigationTabs.label',
+    items: tabs.map(toNavigationTabOption),
+    active: false,
+    hasActiveSubItem: !!activeTab,
+  };
+};
+
 export function getMenuItemType(item: ItemState): MenuItemType {
-  if (item.type === MenuItemType.Separator) {
+  if (item.type === MenuItemType.Select) {
+    return MenuItemType.Select;
+  } else if (item.type === MenuItemType.Separator) {
     return MenuItemType.Separator;
   } else if (item.menuStyle === 'drilldown') {
     return MenuItemType.DrillDown;
@@ -123,3 +149,22 @@ export function getMenuItemType(item: ItemState): MenuItemType {
     return MenuItemType.Operation;
   } else return MenuItemType.Default;
 }
+
+function toNavigationTabOption(tab: NavigationTabRowItem): ItemState {
+  const landing =
+    tab.type === 'group' ? (tab.items.find((entry) => entry.active) ?? tab.items[0]) : tab;
+
+  return {
+    type: tab.type,
+    label: tab.label,
+    labelTranslationKey: tab.labelTranslationKey,
+    icon: tab.icon,
+    srcSet: tab.srcSet,
+    link: landing?.link,
+    external: landing?.external,
+    target: landing?.target,
+    items: [],
+    active: !!tab.active,
+    hasActiveSubItem: false,
+  };
+}