@redocly/theme 0.59.0-rc.2 → 0.60.0-next.0

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

@@ -6,7 +6,7 @@ import type { MenuItemProps } from '../../types/sidebar';
 import { useMenuItemExpanded } from './use-menu-item-expanded';
 import { useCollapse } from './use-collapse';
 import { loadAndNavigate } from '../../utils/load-and-navigate';
-import { withoutPathPrefix } from '../../utils/urls';
+import { withoutPathPrefix, withPathPrefix } from '../../utils/urls';
 
 type NestedMenuProps = MenuItemProps & {
   labelRef?: React.RefObject<HTMLElement | null>;
@@ -78,7 +78,7 @@ export function useNestedMenu({ item, labelRef, nestedMenuRef }: NestedMenuProps
 
     const [firstChild] = item.items;
     if (!isExpanded && item.selectFirstItemOnExpand && firstChild.link) {
-      await loadAndNavigate({ navigate, to: firstChild.link });
+      await loadAndNavigate({ navigate, to: withPathPrefix(firstChild.link) });
     }
     setIsExpanded(!isExpanded);
   }, [item, isExpanded, navigate, location.pathname, setIsExpanded]);

package/src/core/hooks/search/use-feedback-tooltip.ts

@@ -0,0 +1,32 @@
+import { useState } from 'react';
+
+import { useControl } from '../use-control';
+
+type UseFeedbackTooltipReturn = {
+  isOpen: boolean;
+  showTooltip: () => void;
+};
+
+const DEFAULT_TOOLTIP_DURATION = 1500;
+
+export function useFeedbackTooltip(): UseFeedbackTooltipReturn {
+  const [closeTooltipTimeout, setCloseTooltipTimeout] = useState<NodeJS.Timeout | null>(null);
+  const tooltipControl = useControl();
+
+  const showTooltip = () => {
+    tooltipControl.handleOpen();
+    if (closeTooltipTimeout) {
+      clearTimeout(closeTooltipTimeout);
+    }
+    const newCloseTooltipTimeout = setTimeout(() => {
+      tooltipControl.handleClose();
+      setCloseTooltipTimeout(null);
+    }, DEFAULT_TOOLTIP_DURATION);
+    setCloseTooltipTimeout(newCloseTooltipTimeout);
+  };
+
+  return {
+    isOpen: tooltipControl.isOpened,
+    showTooltip,
+  };
+}

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

@@ -0,0 +1,79 @@
+import { useState, useCallback, useMemo } from 'react';
+import debounce from 'lodash.debounce';
+
+import type { MCPOption } from '../types';
+
+import { useThemeHooks } from './use-theme-hooks';
+import { useMCPConfig } from './use-mcp-config';
+import { ClipboardService } from '../utils/clipboard-service';
+
+export type McpButtonOptions = {
+  options?: MCPOption[];
+};
+
+export type McpButtonSettings = {
+  isCopied: boolean;
+  cursorUrl: string;
+  vscodeUrl: string;
+  triggerButtonText: string;
+  visibleOptions: MCPOption[];
+  handleAction: (action: MCPOption) => void;
+};
+
+const COPIED_RESET_TIMEOUT = 1000;
+
+export function useConnectMCPButton({
+  options = ['cursor', 'vscode', 'copy'],
+}: McpButtonOptions = {}): McpButtonSettings {
+  const { useTranslate } = useThemeHooks();
+  const { translate } = useTranslate();
+  const { serverName, serverUrl, cursorUrl, vscodeUrl } = useMCPConfig();
+  const [isCopied, setIsCopied] = useState(false);
+
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const resetCopied = useCallback(
+    debounce(() => setIsCopied(false), COPIED_RESET_TIMEOUT),
+    [],
+  );
+
+  const handleAction = useCallback(
+    (action: MCPOption) => {
+      if (action === 'copy') {
+        const config = {
+          [serverName]: {
+            url: serverUrl,
+            description: 'MCP Server',
+          },
+        };
+        ClipboardService.copyCustom(JSON.stringify(config, null, 2));
+        setIsCopied(true);
+        resetCopied();
+        return;
+      }
+
+      const urlMap: Record<Exclude<MCPOption, 'copy'>, string> = {
+        cursor: cursorUrl,
+        vscode: vscodeUrl,
+      };
+
+      window.open(urlMap[action], '_blank');
+    },
+    [cursorUrl, vscodeUrl, serverUrl, serverName, resetCopied],
+  );
+
+  const triggerButtonText = useMemo(
+    () => translate('page.actions.connectMcp', 'Connect MCP'),
+    [translate],
+  );
+
+  const visibleOptions = useMemo(() => options.filter(Boolean), [options]);
+
+  return {
+    isCopied,
+    cursorUrl,
+    vscodeUrl,
+    triggerButtonText,
+    visibleOptions,
+    handleAction,
+  };
+}

package/src/core/hooks/use-mcp-config.ts

@@ -0,0 +1,43 @@
+import { useMemo } from 'react';
+
+import { useThemeConfig } from './use-theme-config';
+import { IS_BROWSER } from '../utils/dom';
+import { DEFAULT_MCP_SERVER_NAME } from '../constants';
+import { generateMCPDeepLink } from '../utils/mcp';
+
+export type McpConfig = {
+  serverName: string;
+  origin: string;
+  serverUrl: string;
+  cursorUrl: string;
+  vscodeUrl: string;
+  isMcpDisabled: boolean;
+};
+
+export function useMCPConfig(): McpConfig {
+  const themeConfig = useThemeConfig();
+
+  const origin = IS_BROWSER ? window.location.origin : (globalThis as any)['SSR_HOSTNAME'];
+  const serverName = themeConfig.mcp?.docs?.name || DEFAULT_MCP_SERVER_NAME;
+  const serverUrl = `${origin}/mcp`;
+  const isMcpDisabled = themeConfig.mcp?.hide || themeConfig.mcp?.docs?.hide || false;
+
+  const cursorUrl = useMemo(
+    () => generateMCPDeepLink('cursor', { serverName, url: serverUrl }),
+    [serverName, serverUrl],
+  );
+
+  const vscodeUrl = useMemo(
+    () => generateMCPDeepLink('vscode', { serverName, url: serverUrl }),
+    [serverName, serverUrl],
+  );
+
+  return {
+    serverName,
+    origin,
+    serverUrl,
+    cursorUrl,
+    vscodeUrl,
+    isMcpDisabled,
+  };
+}

package/src/core/hooks/use-page-actions.ts

@@ -1,31 +1,40 @@
-import { useMemo } from 'react';
+import { useMemo, useCallback } from 'react';
 
 import type { PageProps, UiAccessibleConfig } from '@redocly/config';
-import type { PageAction } from '../types';
+import type { PageAction, MCPClientType, McpConnectionParams } from '../types';
 
 import { CopyIcon } from '@redocly/theme/icons/CopyIcon/CopyIcon';
 import { ChatGptIcon } from '@redocly/theme/icons/ChatGptIcon/ChatGptIcon';
 import { ClaudeIcon } from '@redocly/theme/icons/ClaudeIcon/ClaudeIcon';
 import { MarkdownFullIcon } from '@redocly/theme/icons/MarkdownFullIcon/MarkdownFullIcon';
+import { VSCodeIcon } from '@redocly/theme/icons/VSCodeIcon/VSCodeIcon';
+import { CursorIcon } from '@redocly/theme/icons/CursorIcon/CursorIcon';
 
 import { useThemeHooks } from './use-theme-hooks';
 import { useThemeConfig } from './use-theme-config';
+import { useMCPConfig } from './use-mcp-config';
 import { ClipboardService } from '../utils/clipboard-service';
 import { IS_BROWSER } from '../utils/dom';
-import { CursorIcon } from '../../icons/CursorIcon/CursorIcon';
+import { generateMCPDeepLink } from '../utils/mcp';
 
-const DEFAULT_ENABLED_ACTIONS = ['copy', 'view', 'chatgpt', 'claude'] as const;
-const CURSOR_URL =
-  'cursor://anysphere.cursor-deeplink/mcp/install?name=$NAME&config=$BASE64_ENCODED_CONFIG';
+const DEFAULT_ENABLED_ACTIONS = [
+  'copy',
+  'view',
+  'chatgpt',
+  'claude',
+  'docs-mcp-cursor',
+  'docs-mcp-vscode',
+] as const;
 
 export type PageActionType =
   | 'copy'
   | 'view'
   | 'chatgpt'
   | 'claude'
+  | 'docs-mcp-cursor'
+  | 'docs-mcp-vscode'
   | 'mcp-cursor'
-  | 'mcp-claude'
-  | 'mcp-json';
+  | 'mcp-vscode';
 
 export function usePageActions(
   pageSlug: string,
@@ -34,12 +43,12 @@ export function usePageActions(
 ): PageAction[] {
   const { useTranslate, usePageData, usePageProps, usePageSharedData } = useThemeHooks();
   const { translate } = useTranslate();
-
   const themeConfig = useThemeConfig();
   const pageProps = usePageProps();
   const openApiSharedData = usePageSharedData<
     { options: { excludeFromSearch: boolean } } | undefined
   >('openAPIDocsStore');
+  const mcpConfig = useMCPConfig();
 
   const shouldHideAllActions = shouldHidePageActions(
     pageProps,
@@ -48,172 +57,154 @@ export function usePageActions(
   );
   const { isPublic } = usePageData() || {};
 
+  const createMCPHandler = useCallback(
+    (clientType: MCPClientType, requiresMcpUrl: boolean = false) =>
+      () => {
+        if (requiresMcpUrl && !mcpUrl) return null;
+        if (!requiresMcpUrl && (mcpUrl || mcpConfig.isMcpDisabled)) return null;
+
+        const config = requiresMcpUrl
+          ? { serverName: mcpConfig.serverName, url: mcpUrl || '' }
+          : { serverName: mcpConfig.serverName, url: mcpConfig.serverUrl || '' };
+
+        return createMCPAction({ clientType, mcpConfig: config, translate });
+      },
+    [mcpUrl, mcpConfig, translate],
+  );
+
   const result: PageAction[] = useMemo(() => {
-    if (shouldHideAllActions && !actions?.length) {
+    if (shouldHideAllActions) {
       return [];
     }
 
     const origin = IS_BROWSER ? window.location.origin : (globalThis as any)['SSR_HOSTNAME'];
-
     const normalizedSlug = pageSlug.startsWith('/') ? pageSlug : '/' + pageSlug;
-
     const mdPageUrl = new URL(
       origin + normalizedSlug + (normalizedSlug === '/' ? 'index.html.md' : '.md'),
     ).toString();
 
-    function getExternalAiPromptLink(baseUrl: string): string {
-      const externalAiPrompt = `Read ${mdPageUrl} and answer questions based on the content.`;
-
-      const url = new URL(baseUrl);
-      url.searchParams.set('q', externalAiPrompt);
-
-      return url.toString();
-    }
-
-    return (themeConfig.navigation?.actions?.items || actions || DEFAULT_ENABLED_ACTIONS)
-      .map((action) => {
-        function generateMCPConfig(isCursor?: boolean): string {
-          const jsonConfig = {
-            'mcp-server': {
-              url: mcpUrl,
-              description: 'MCP Server',
-            },
-          };
-          if (isCursor) {
-            const url = CURSOR_URL.replace('$NAME', 'mcp-server').replace(
-              '$BASE64_ENCODED_CONFIG',
-              btoa(JSON.stringify(jsonConfig['mcp-server'])),
-            );
-            return url;
+    const actionHandlers: Record<PageActionType, () => PageAction | null> = {
+      'docs-mcp-cursor': createMCPHandler('cursor'),
+      'docs-mcp-vscode': createMCPHandler('vscode'),
+      'mcp-cursor': createMCPHandler('cursor', true),
+      'mcp-vscode': createMCPHandler('vscode', true),
+
+      copy: () => ({
+        buttonText: translate('page.actions.copyButtonText', 'Copy'),
+        title: translate('page.actions.copyTitle', 'Copy for LLM'),
+        description: translate('page.actions.copyDescription', 'Copy page as Markdown for LLMs'),
+        iconComponent: CopyIcon,
+        onClick: async () => {
+          try {
+            const result = await fetch(mdPageUrl);
+            if (result.status !== 200) {
+              return;
+            }
+            const text = await result.text();
+            ClipboardService.copyCustom(text);
+          } catch (error) {
+            console.error(error);
           }
-
-          return JSON.stringify(jsonConfig, null, 2);
+        },
+      }),
+
+      view: () => ({
+        buttonText: translate('page.actions.viewAsMdButtonText', 'View as Markdown'),
+        title: translate('page.actions.viewAsMdTitle', 'View as Markdown'),
+        description: translate('page.actions.viewAsMdDescription', 'Open this page as Markdown'),
+        iconComponent: MarkdownFullIcon,
+        link: mdPageUrl,
+      }),
+
+      chatgpt: () => {
+        if (!isPublic) {
+          return null;
         }
-
-        switch (action) {
-          case 'mcp-cursor':
-            if (!mcpUrl) {
-              return null;
-            }
-
-            return {
-              buttonText: translate('page.actions.cursorMcpButtonText', 'Connect to Cursor'),
-              title: translate('page.actions.cursorMcpTitle', 'Connect to Cursor'),
-              description: translate(
-                'page.actions.cursorMcpDescription',
-                'Install MCP server on Cursor',
-              ),
-              iconComponent: CursorIcon,
-              onClick: () => {
-                try {
-                  const url = generateMCPConfig(true);
-                  window.open(url, '_blank');
-                } catch (error) {
-                  console.error(error);
-                }
-              },
-            };
-          case 'mcp-claude':
-            if (!mcpUrl) {
-              return null;
-            }
-
-            return {
-              buttonText: 'Copy Claude configuration',
-              title: 'Copy Claude configuration',
-              description: 'Copy MCP configuration for Claude',
-              iconComponent: ClaudeIcon,
-              onClick: async () => {
-                ClipboardService.copyCustom(`claude mcp add --transport http server ${mcpUrl}`);
-              },
-            };
-          case 'mcp-json':
-            return {
-              buttonText: 'Copy MCP configuration',
-              title: 'Copy MCP JSON configuration',
-              description: 'Copy MCP JSON configuration',
-              iconComponent: CopyIcon,
-              onClick: async () => {
-                ClipboardService.copyCustom(generateMCPConfig());
-              },
-            };
-          case 'copy':
-            return {
-              buttonText: translate('page.actions.copyButtonText', 'Copy'),
-              title: translate('page.actions.copyTitle', 'Copy for LLM'),
-              description: translate(
-                'page.actions.copyDescription',
-                'Copy page as Markdown for LLMs',
-              ),
-              iconComponent: CopyIcon,
-              onClick: async () => {
-                try {
-                  const result = await fetch(mdPageUrl);
-                  if (result.status !== 200) {
-                    throw new Error('Failed to fetch markdown content');
-                  }
-                  const text = await result.text();
-
-                  ClipboardService.copyCustom(text);
-                } catch (error) {
-                  console.error(error);
-                }
-              },
-            };
-          case 'view':
-            return {
-              buttonText: translate('page.actions.viewAsMdButtonText', 'View as Markdown'),
-              title: translate('page.actions.viewAsMdTitle', 'View as Markdown'),
-              description: translate(
-                'page.actions.viewAsMdDescription',
-                'Open this page as Markdown',
-              ),
-              iconComponent: MarkdownFullIcon,
-              link: mdPageUrl,
-            };
-          case 'chatgpt':
-            if (!isPublic) {
-              return null;
-            }
-
-            return {
-              buttonText: translate('page.actions.chatGptButtonText', 'Open in ChatGPT'),
-              title: translate('page.actions.chatGptTitle', 'Open in ChatGPT'),
-              description: translate(
-                'page.actions.chatGptDescription',
-                'Get insights from ChatGPT',
-              ),
-              iconComponent: ChatGptIcon,
-              link: getExternalAiPromptLink('https://chat.openai.com'),
-            };
-          case 'claude':
-            if (!isPublic) {
-              return null;
-            }
-
-            return {
-              buttonText: translate('page.actions.claudeButtonText', 'Open in Claude'),
-              title: translate('page.actions.claudeTitle', 'Open in Claude'),
-              description: translate('page.actions.claudeDescription', 'Get insights from Claude'),
-              iconComponent: ClaudeIcon,
-              link: getExternalAiPromptLink('https://claude.ai/new'),
-            };
+        return {
+          buttonText: translate('page.actions.chatGptButtonText', 'Open in ChatGPT'),
+          title: translate('page.actions.chatGptTitle', 'Open in ChatGPT'),
+          description: translate('page.actions.chatGptDescription', 'Get insights from ChatGPT'),
+          iconComponent: ChatGptIcon,
+          link: getExternalAiPromptLink('https://chat.openai.com', mdPageUrl),
+        };
+      },
+
+      claude: () => {
+        if (!isPublic) {
+          return null;
         }
-      })
-      .filter((action) => action !== null);
+        return {
+          buttonText: translate('page.actions.claudeButtonText', 'Open in Claude'),
+          title: translate('page.actions.claudeTitle', 'Open in Claude'),
+          description: translate('page.actions.claudeDescription', 'Get insights from Claude'),
+          iconComponent: ClaudeIcon,
+          link: getExternalAiPromptLink('https://claude.ai/new', mdPageUrl),
+        };
+      },
+    };
+
+    return (themeConfig.navigation?.actions?.items || actions || DEFAULT_ENABLED_ACTIONS)
+      .map((action) => actionHandlers[action]?.())
+      .filter((action): action is PageAction => action !== null);
   }, [
     shouldHideAllActions,
     pageSlug,
     themeConfig.navigation?.actions?.items,
     actions,
-    mcpUrl,
     translate,
     isPublic,
+    createMCPHandler,
   ]);
 
   return result;
 }
 
+function getExternalAiPromptLink(baseUrl: string, mdPageUrl: string): string {
+  const externalAiPrompt = `Read ${mdPageUrl} and answer questions based on the content.`;
+  const url = new URL(baseUrl);
+  url.searchParams.set('q', externalAiPrompt);
+  return url.toString();
+}
+
+type CreateMCPActionParams = {
+  clientType: MCPClientType;
+  mcpConfig: McpConnectionParams;
+  translate: (key: string, defaultValue: string) => string;
+};
+
+function createMCPAction({ clientType, mcpConfig, translate }: CreateMCPActionParams): PageAction {
+  const url = generateMCPDeepLink(clientType, mcpConfig);
+  const sharedProps = {
+    onClick: () => {
+      window.open(url, '_blank');
+    },
+  };
+
+  if (clientType === 'cursor') {
+    return {
+      ...sharedProps,
+      buttonText: translate('page.actions.connectMcp.cursor', 'Connect to Cursor'),
+      title: translate('page.actions.connectMcp.cursor', 'Connect to Cursor'),
+      description: translate(
+        'page.actions.connectMcp.cursorDescription',
+        'Install MCP server on Cursor',
+      ),
+      iconComponent: CursorIcon,
+    };
+  }
+
+  return {
+    ...sharedProps,
+    buttonText: translate('page.actions.connectMcp.vscode', 'Connect to VS Code'),
+    title: translate('page.actions.connectMcp.vscode', 'Connect to VS Code'),
+    description: translate(
+      'page.actions.connectMcp.vscodeDescription',
+      'Install MCP server on VS Code',
+    ),
+    iconComponent: VSCodeIcon,
+  };
+}
+
 function shouldHidePageActions(
   pageProps: PageProps,
   themeConfig: UiAccessibleConfig,

package/src/core/hooks/use-product-picker.ts

@@ -1,6 +1,7 @@
 import { useNavigate } from 'react-router-dom';
 
 import { useThemeHooks } from './use-theme-hooks';
+import { withPathPrefix } from '../utils';
 
 export function useProductPicker() {
   const { useCurrentProduct, useProducts, useTelemetry, useLoadAndNavigate } = useThemeHooks();
@@ -12,7 +13,7 @@ export function useProductPicker() {
   function setProduct(product: typeof currentProduct) {
     if (!product) return;
     telemetry.sendProductPickedMessage({ product: product.slug });
-    loadAndNavigate({ navigate, to: product.link });
+    loadAndNavigate({ navigate, to: withPathPrefix(product.link) });
   }
   return {
     currentProduct,