@redocly/theme 0.58.0-next.9 → 0.58.0

package/src/components/JsonViewer/JsonViewer.tsx

@@ -12,11 +12,11 @@ export type PanelType = 'request' | 'responses' | 'request-samples' | 'response-
 
 export type JsonProps = {
   title?: CodeBlockControlsProps['title'];
+  controls?: CodeBlockControlsProps['controls'];
   data: any;
   className?: string;
   expandLevel: number;
   startLineNumber?: number;
-  hideHeader?: boolean;
   onCopyClick?: () => void;
   onPanelToggle?: (isExpanded: boolean, panelType?: PanelType) => void;
 };
@@ -28,7 +28,7 @@ function JsonComponent({
   onCopyClick,
   onPanelToggle,
   title,
-  hideHeader,
+  controls = {},
 }: JsonProps): JSX.Element {
   const showFoldingButtons =
     data && Object.values(data).some((value) => typeof value === 'object' && value !== null);
@@ -53,6 +53,8 @@ function JsonComponent({
 
   const source = JSON.stringify(data, null, 2);
 
+  const hasHeader = title || controls;
+
   return (
     <JsonViewerWrap
       data-testid="json-viewer"
@@ -61,17 +63,22 @@ function JsonComponent({
     >
       <CodeBlock
         header={
-          hideHeader
-            ? undefined
-            : {
+          hasHeader
+            ? {
                 title,
                 className: 'code-block-header',
-                controls: {
-                  copy: { data, onClick: onCopyClick, handleOutside: true },
-                  expand: showFoldingButtons ? { onClick: expandAll } : undefined,
-                  collapse: showFoldingButtons ? { onClick: collapseAll } : undefined,
+                controls: controls && {
+                  ...controls,
+                  copy: { ...controls.copy, data, onClick: onCopyClick, handleOutside: true },
+                  expand: showFoldingButtons
+                    ? { ...controls.expand, onClick: expandAll }
+                    : undefined,
+                  collapse: showFoldingButtons
+                    ? { ...controls.collapse, onClick: collapseAll }
+                    : undefined,
                 },
               }
+            : undefined
         }
         source={source}
       >

package/src/components/PageActions/PageActions.tsx

@@ -13,20 +13,22 @@ import { Dropdown } from '@redocly/theme/components/Dropdown/Dropdown';
 import { DropdownMenu } from '@redocly/theme/components/Dropdown/DropdownMenu';
 import { Spinner } from '@redocly/theme/icons/Spinner/Spinner';
 import { CheckmarkFilledIcon } from '@redocly/theme/icons/CheckmarkFilledIcon/CheckmarkFilledIcon';
-import { usePageActions } from '@redocly/theme/core/hooks';
+import { PageActionType, usePageActions } from '@redocly/theme/core/hooks';
 
 type ActionState = 'idle' | 'processing' | 'done';
 
 type PageActionProps = {
-  pageSlug: string;
+  pageSlug?: string;
+  mcpUrl?: string;
+  actions?: PageActionType[];
 };
 
 const ACTION_DONE_DISPLAY_DURATION = 1000;
 
 export function PageActions(props: PageActionProps): JSX.Element | null {
-  const { pageSlug } = props;
+  const { pageSlug, mcpUrl } = props;
 
-  const actions = usePageActions(pageSlug || '/');
+  const actions = usePageActions(pageSlug || '/', mcpUrl, props.actions);
 
   const [actionState, setActionState] = useState<ActionState>('idle');
 

package/src/core/constants/catalog.ts

@@ -38,6 +38,8 @@ export const reverseRelationMap: Record<EntityRelationType, EntityRelationType>
   memberOf: 'hasMember',
   triggers: 'triggeredBy',
   triggeredBy: 'triggers',
+  returns: 'returnedBy',
+  returnedBy: 'returns',
 } as const;
 
 export const relationTypeMap: Record<EntityRelationType, string> = {
@@ -66,6 +68,8 @@ export const relationTypeMap: Record<EntityRelationType, string> = {
   memberOf: 'Member of',
   triggers: 'Triggers',
   triggeredBy: 'Triggered by',
+  returns: 'Returns',
+  returnedBy: 'Returned by',
 };
 
 export enum GraphHandleType {

package/src/core/contexts/CodeSnippetContext.tsx

@@ -1,31 +1,67 @@
-import { createContext, useContext, useState } from 'react';
+import React, { createContext, useContext, useCallback, useMemo } from 'react';
 
-export type CodeSnippetContextType = {
-  activeSnippetName: string;
-  setActiveSnippetName: (name: string) => void;
-};
+import { useLocalState } from '../hooks/use-local-state';
 
 export const CODE_GROUP_SNIPPET_NAME_KEY = 'redocly:codeGroupSnippetName';
 
+type CodeSnippetContextType = {
+  activeSnippets: Record<string, string>;
+  setActiveSnippet: (groupId: string, snippetId: string) => void;
+};
+
 export const CodeSnippetContext = createContext<CodeSnippetContextType | null>(null);
 
-export function useActiveCodeSnippetName(
-  mode: 'tabs' | 'dropdown',
-): [string, (name: string) => void] {
+export function CodeSnippetProvider({ children }: { children: React.ReactNode }) {
+  const [activeSnippets, setActiveSnippets] = useLocalState<Record<string, string>>(
+    CODE_GROUP_SNIPPET_NAME_KEY,
+    {},
+  );
+
+  const setActiveSnippet = useCallback(
+    (groupId: string, snippetId: string) => {
+      setActiveSnippets({ ...activeSnippets, [groupId]: snippetId });
+    },
+    [activeSnippets, setActiveSnippets],
+  );
+
+  const contextValue = { activeSnippets, setActiveSnippet };
+
+  return <CodeSnippetContext.Provider value={contextValue}>{children}</CodeSnippetContext.Provider>;
+}
+
+export const useCodeSnippetContext = (): CodeSnippetContextType => {
   const context = useContext(CodeSnippetContext);
+
   if (!context) {
     throw new Error('useCodeSnippetContext must be used within a CodeSnippetContext');
   }
 
-  const [activeSnippetName, setActiveSnippetName] = useState(
-    mode === 'tabs' ? '' : context.activeSnippetName,
+  return context;
+};
+
+export const useActiveCodeSnippetId = (
+  groupId?: string,
+  availableSnippets?: { id: string }[],
+): [string, (id: string) => void] => {
+  const { activeSnippets, setActiveSnippet } = useCodeSnippetContext();
+
+  const storedSnippetId = groupId ? activeSnippets[groupId] || '' : '';
+
+  const activeId = useMemo(() => {
+    if (!availableSnippets?.length) return storedSnippetId;
+
+    const found = storedSnippetId && availableSnippets.find((s) => s.id === storedSnippetId);
+    return found ? storedSnippetId : availableSnippets[0]?.id || '';
+  }, [storedSnippetId, availableSnippets]);
+
+  const setActiveSnippetId = useCallback(
+    (id: string) => {
+      if (groupId) {
+        setActiveSnippet(groupId, id);
+      }
+    },
+    [groupId, setActiveSnippet],
   );
 
-  if (mode === 'tabs') {
-    // use non-synced state for tabs mode
-    return [activeSnippetName, setActiveSnippetName];
-  } else {
-    // use global synced state for dropdown mode
-    return [context.activeSnippetName, context.setActiveSnippetName];
-  }
-}
+  return [activeId, setActiveSnippetId];
+};

package/src/core/hooks/use-codeblock-tabs-controls.ts

@@ -1,9 +1,9 @@
 import { useEffect, useState, useCallback, useMemo } from 'react';
 
-import type { CodeBlockTabItems } from '../../components/CodeBlock/CodeBlock';
+import type { CodeBlockItems } from '../../components/CodeBlock/CodeBlock';
 
 type CodeBlockTabsProps = {
-  tabs: CodeBlockTabItems;
+  tabs: CodeBlockItems;
   containerRef: React.RefObject<HTMLDivElement | null>;
   tabRefs: React.RefObject<HTMLButtonElement[]>;
 };

package/src/core/hooks/use-local-state.ts

@@ -1,30 +1,39 @@
-import { useState, useEffect } from 'react';
+import { useState, useEffect, useCallback } from 'react';
+
+import { isBrowser } from '../utils/js-utils';
+
+function getStoredValue<T>(key: string, fallback: T): T {
+  if (!isBrowser()) return fallback;
 
-function getInitialValue<T>(key: string, initialValue: T): T {
-  if (typeof window === 'undefined') {
-    return initialValue;
-  }
   try {
     const savedValue = localStorage.getItem(key);
-    if (savedValue) {
-      return JSON.parse(savedValue) as T;
-    }
-  } catch (error) {
-    console.error(`Error reading from localStorage for key "${key}":`, error);
+    return savedValue ? (JSON.parse(savedValue) as T) : fallback;
+  } catch {
+    return fallback;
   }
-  return initialValue;
 }
 
 export function useLocalState<T>(key: string, initialValue: T): [T, (value: T) => void] {
-  const [value, setValue] = useState<T>(() => getInitialValue(key, initialValue));
+  const [value, setValue] = useState<T>(initialValue);
 
+  // Load stored value from localStorage after component mounts
+  // This ensures SSR compatibility: server and client both start with initialValue,
+  // then client loads the actual stored value without hydration mismatch
   useEffect(() => {
-    try {
-      localStorage.setItem(key, JSON.stringify(value));
-    } catch (error) {
-      console.error(`Error writing to localStorage for key "${key}":`, error);
-    }
-  }, [key, value]);
+    if (!isBrowser()) return;
+    setValue(getStoredValue(key, initialValue));
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key]);
+
+  const handleSetValue = useCallback(
+    (newValue: T) => {
+      setValue(newValue);
+      if (isBrowser()) {
+        localStorage.setItem(key, JSON.stringify(newValue));
+      }
+    },
+    [key],
+  );
 
-  return [value, setValue] as const;
+  return [value, handleSetValue] as const;
 }

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

@@ -12,10 +12,19 @@ import { useThemeHooks } from './use-theme-hooks';
 import { useThemeConfig } from './use-theme-config';
 import { ClipboardService } from '../utils/clipboard-service';
 import { IS_BROWSER } from '../utils/dom';
+import { CursorIcon } from '../../icons/CursorIcon/CursorIcon';
 
 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';
 
-export function usePageActions(pageSlug: string): PageAction[] {
+export type PageActionType = 'copy' | 'view' | 'chatgpt' | 'claude' | 'mcp-cursor';
+
+export function usePageActions(
+  pageSlug: string,
+  mcpUrl?: string,
+  actions?: PageActionType[],
+): PageAction[] {
   const { useTranslate, usePageData, usePageProps, usePageSharedData } = useThemeHooks();
   const { translate } = useTranslate();
 
@@ -32,7 +41,7 @@ export function usePageActions(pageSlug: string): PageAction[] {
   );
   const { isPublic } = usePageData() || {};
 
-  const actions: PageAction[] = useMemo(() => {
+  const result: PageAction[] = useMemo(() => {
     if (shouldHideAllActions) {
       return [];
     }
@@ -54,9 +63,49 @@ export function usePageActions(pageSlug: string): PageAction[] {
       return url.toString();
     }
 
-    return (themeConfig.navigation?.actions?.items || DEFAULT_ENABLED_ACTIONS)
+    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;
+          }
+
+          return JSON.stringify(jsonConfig, null, 2);
+        }
+
         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 'copy':
             return {
               buttonText: translate('page.actions.copyButtonText', 'Copy'),
@@ -121,9 +170,17 @@ export function usePageActions(pageSlug: string): PageAction[] {
         }
       })
       .filter((action) => action !== null);
-  }, [themeConfig, translate, pageSlug, isPublic, shouldHideAllActions]);
-
-  return actions;
+  }, [
+    shouldHideAllActions,
+    pageSlug,
+    themeConfig.navigation?.actions?.items,
+    actions,
+    mcpUrl,
+    translate,
+    isPublic,
+  ]);
+
+  return result;
 }
 
 function shouldHidePageActions(

package/src/core/openapi/index.ts

@@ -17,6 +17,7 @@ export {
   addTrailingSlash,
   withPathPrefix,
 } from '../utils/urls';
+export { capitalize } from '../utils/string';
 export { typedMemo } from '../hoc/typedMemo';
 export { useMount } from '../hooks/use-mount';
 export { GlobalStyle } from '../styles/global';

package/src/core/types/l10n.ts

@@ -206,6 +206,9 @@ export type TranslationKey =
   | 'page.actions.claudeTitle'
   | 'page.actions.claudeButtonText'
   | 'page.actions.claudeDescription'
+  | 'page.actions.cursorMcpButtonText'
+  | 'page.actions.cursorMcpTitle'
+  | 'page.actions.cursorMcpDescription'
   | 'openapi.download.description.title'
   | 'openapi.info.title'
   | 'openapi.info.contact.url'
@@ -283,6 +286,16 @@ export type TranslationKey =
   | 'openapi.schemaCatalogLink.title'
   | 'openapi.schemaCatalogLink.copyButtonTooltip'
   | 'openapi.schemaCatalogLink.copiedTooltip'
+  | 'openapi.mcp.title'
+  | 'openapi.mcp.endpoint'
+  | 'openapi.mcp.tools'
+  | 'openapi.mcp.protocolVersion'
+  | 'openapi.mcp.capabilities'
+  | 'openapi.mcp.experimentalCapabilities'
+  | 'openapi.mcp.inputSchema'
+  | 'openapi.mcp.inputExample'
+  | 'openapi.mcp.outputSchema'
+  | 'openapi.mcp.outputExample'
   | 'asyncapi.download.description.title'
   | 'asyncapi.info.title'
   | 'graphql.queries'

package/src/core/types/open-api-server.ts

@@ -1,6 +1,7 @@
 export type OpenAPIServer = {
   url: string;
   description?: string;
+  name?: string;
   variables?: Record<
     string,
     {

package/src/icons/CursorIcon/CursorIcon.tsx

@@ -0,0 +1,35 @@
+import React from 'react';
+import styled from 'styled-components';
+
+import type { IconProps } from '@redocly/theme/icons/types';
+
+const Icon = (props: IconProps) => (
+  <svg
+    width="16"
+    height="16"
+    viewBox="0 0 16 16"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path d="M7.99956 15V8.0001L2 11.4999L7.99956 15Z" fill="#939393" />
+    <path d="M14 4.49979L7.99956 15V8.0001L14 4.49979Z" fill="#E3E3E3" />
+    <path d="M2 4.49979H14L7.99956 8.0001L2 4.49979Z" fill="white" />
+    <path d="M8.00025 1V4.49995L14 4.49979L8.00025 1Z" fill="#444444" />
+    <path
+      d="M2 4.49979L8.00025 4.49995V1L2 4.49979ZM13.9999 11.4998L10.9999 9.74987L7.99956 15L13.9999 11.4998Z"
+      fill="#939393"
+    />
+    <path
+      d="M14 4.49979L10.9999 9.74987L13.9999 11.4998L14 4.49979ZM7.99956 8.0001L2 11.4999V4.49979L7.99956 8.0001Z"
+      fill="#444444"
+    />
+  </svg>
+);
+
+export const CursorIcon = styled(Icon).attrs(() => ({
+  'data-component-name': 'icons/CursorIcon/CursorIcon',
+}))<IconProps>`
+  height: ${({ size }) => size || '16px'};
+  width: ${({ size }) => size || '16px'};
+`;

package/src/layouts/DocumentationLayout.tsx

@@ -9,12 +9,7 @@ import { breakpoints } from '@redocly/theme/core/utils';
 import { PageNavigation } from '@redocly/theme/components/PageNavigation/PageNavigation';
 import { LastUpdated } from '@redocly/theme/components/LastUpdated/LastUpdated';
 import { Breadcrumbs as ThemeBreadcrumbs } from '@redocly/theme/components/Breadcrumbs/Breadcrumbs';
-
-import {
-  CodeSnippetContext,
-  CODE_GROUP_SNIPPET_NAME_KEY,
-} from '../core/contexts/CodeSnippetContext';
-import { useLocalState } from '../core/hooks/use-local-state';
+import { CodeSnippetProvider } from '@redocly/theme/core/contexts/CodeSnippetContext';
 
 type DocumentationLayoutProps = {
   tableOfContent: React.ReactNode;
@@ -44,10 +39,8 @@ export function DocumentationLayout({
   const { editPage: themeEditPage } = config || {};
   const mergedConf = editPage ? { ...themeEditPage, ...editPage } : undefined;
 
-  const [activeSnippetName, setActiveSnippetName] = useLocalState(CODE_GROUP_SNIPPET_NAME_KEY, '');
-
   return (
-    <CodeSnippetContext.Provider value={{ activeSnippetName, setActiveSnippetName }}>
+    <CodeSnippetProvider>
       <LayoutWrapper data-component-name="Layout/DocumentationLayout" className={className}>
         <ContentWrapper withToc={!config?.toc?.hide}>
           <Breadcrumbs />
@@ -61,7 +54,7 @@ export function DocumentationLayout({
         </ContentWrapper>
         {tableOfContent}
       </LayoutWrapper>
-    </CodeSnippetContext.Provider>
+    </CodeSnippetProvider>
   );
 }
 

package/src/markdoc/components/CodeGroup/CodeGroup.tsx

@@ -5,65 +5,55 @@ import {
   type CodeBlockProps,
 } from '@redocly/theme/components/CodeBlock/CodeBlock';
 import { langToName } from '@redocly/theme/core/utils';
-import { useActiveCodeSnippetName } from '@redocly/theme/core/contexts';
+import { useActiveCodeSnippetId } from '@redocly/theme/core/contexts';
+
+type SnippetData = {
+  name: string;
+  languageName: string;
+  lang: string;
+  props: CodeBlockProps;
+  id: string;
+};
 
 export function CodeGroup(props: React.PropsWithChildren<{ mode?: 'tabs' | 'dropdown' }>) {
   const mode = props.mode || 'tabs';
   const isTabsMode = mode === 'tabs';
 
   const rawSnippets = React.useMemo(
-    () =>
-      React.Children.toArray(props.children).map((child, idx) => {
-        const childProps = child as React.ReactElement<CodeBlockProps>;
-        return {
-          name: getTabName(childProps.props, idx),
-          languageName: langToName(childProps.props.lang || 'Default'),
-          lang: childProps.props.lang || '',
-          props: childProps.props,
-        };
-      }),
+    () => parseSnippetsFromChildren(props.children),
     [props.children],
   );
 
-  const [activeSnippetName, setActiveSnippetName] = useActiveCodeSnippetName(mode);
-
-  const snippets: Record<string, CodeBlockProps> = React.useMemo(
-    () =>
-      Object.fromEntries(
-        rawSnippets.map((snippet) => {
-          const getItemName = (snippet: (typeof rawSnippets)[number]) =>
-            isTabsMode ? snippet?.name : snippet?.languageName || '';
-
-          const name = getItemName(snippet);
-
-          const items = rawSnippets.map((item) => ({
-            name: getItemName(item),
-            lang: item.lang,
-          }));
-          const itemsProps = {
-            items,
-            onChange: (name: string | string[]) => {
-              setActiveSnippetName(name as string);
-            },
-            value: activeSnippetName || getItemName(rawSnippets[0]),
-          };
-          const snippetProps = {
-            ...snippet.props,
-            header: {
-              ...snippet.props.header,
-              title: isTabsMode ? undefined : snippet.name,
-            },
-            ...(isTabsMode ? { tabs: itemsProps } : { dropdown: itemsProps }),
-          };
-
-          return [name, snippetProps];
-        }),
-      ),
-    [rawSnippets, activeSnippetName, isTabsMode, setActiveSnippetName],
-  );
+  const groupId = React.useMemo(() => generateGroupId(rawSnippets, mode), [rawSnippets, mode]);
+
+  const [activeSnippetId, setActiveSnippetId] = useActiveCodeSnippetId(groupId, rawSnippets);
+
+  const snippets = React.useMemo(() => {
+    const items = createItemsFromSnippets(rawSnippets, isTabsMode);
 
-  const firstName = Object.keys(snippets)[0];
-  const activeSnippet = snippets[activeSnippetName] || snippets[firstName];
+    const itemsProps = {
+      items,
+      onChange: (id: string | string[]) => setActiveSnippetId(id as string),
+      value: activeSnippetId,
+    };
+
+    return Object.fromEntries(
+      rawSnippets.map((snippet: SnippetData) => {
+        const snippetProps = {
+          ...snippet.props,
+          header: {
+            ...snippet.props.header,
+            title: isTabsMode ? undefined : snippet.name,
+          },
+          ...(isTabsMode ? { tabs: itemsProps } : { dropdown: itemsProps }),
+        };
+
+        return [snippet.id, snippetProps];
+      }),
+    );
+  }, [rawSnippets, activeSnippetId, isTabsMode, setActiveSnippetId]);
+
+  const activeSnippet = snippets[activeSnippetId];
   if (!activeSnippet) {
     return null;
   }
@@ -71,8 +61,47 @@ export function CodeGroup(props: React.PropsWithChildren<{ mode?: 'tabs' | 'drop
   return <CodeBlockComponent {...activeSnippet} />;
 }
 
+function generateContentHash(content: string): number {
+  let hash = 0;
+  for (let i = 0; i < content.length; i++) {
+    hash = content.charCodeAt(i) + ((hash << 5) - hash);
+  }
+  return Math.abs(hash);
+}
+
+// Generate unique group ID for CodeGroup instance
+// Examples: "dropdown-8901234", "tabs-1234567"
+function generateGroupId(rawSnippets: SnippetData[], mode: string): string {
+  const content = rawSnippets.map((s) => s.id + (s.props.source || '')).join('|') + `|${mode}`;
+  const hash = generateContentHash(content);
+
+  return `${mode}-${hash}`;
+}
+
 function getTabName(props: CodeBlockProps, idx: number): string {
-  return String(
-    props.header?.title || props.file || langToName(props.lang || '') || 'Tab ' + String(idx + 1),
-  );
+  const fallbackName = `Tab ${idx + 1}`;
+  return String(props.header?.title || props.file || langToName(props.lang || '') || fallbackName);
+}
+
+function parseSnippetsFromChildren(children: React.ReactNode): SnippetData[] {
+  return React.Children.toArray(children).map((child, idx) => {
+    const childProps = child as React.ReactElement<CodeBlockProps>;
+    const props = childProps.props;
+
+    return {
+      name: getTabName(props, idx),
+      languageName: String(langToName(props.lang || 'Default') || ''),
+      lang: props.lang || '',
+      props,
+      id: `${props.lang || ''}-${idx}`,
+    };
+  });
+}
+
+function createItemsFromSnippets(snippets: SnippetData[], isTabsMode: boolean) {
+  return snippets.map((snippet) => ({
+    name: isTabsMode ? snippet.name : snippet.languageName || '',
+    lang: snippet.lang,
+    id: snippet.id,
+  }));
 }

package/src/markdoc/components/Tabs/TabList.tsx

@@ -104,6 +104,7 @@ export function TabList({
                     key={`more-${tabId}`}
                     active={activeTab === label}
                     onAction={() => {
+                      childrenArray[index].props.onClick?.();
                       onTabClick(index);
                     }}
                     disabled={childrenArray[index].props.disable}