@redocly/theme 0.59.0-next.10 → 0.59.0-next.12

package/src/components/Buttons/ConnectMCPButton.tsx

@@ -0,0 +1,180 @@
+import React, { useMemo } from 'react';
+import styled from 'styled-components';
+
+import type { JSX } from 'react';
+import type { MCPOption } from '@redocly/theme/core/types';
+
+import { Dropdown } from '@redocly/theme/components/Dropdown/Dropdown';
+import { DropdownMenu } from '@redocly/theme/components/Dropdown/DropdownMenu';
+import { DropdownMenuItem } from '@redocly/theme/components/Dropdown/DropdownMenuItem';
+import { Button } from '@redocly/theme/components/Button/Button';
+import { CursorIcon } from '@redocly/theme/icons/CursorIcon/CursorIcon';
+import { VSCodeIcon } from '@redocly/theme/icons/VSCodeIcon/VSCodeIcon';
+import { CopyIcon } from '@redocly/theme/icons/CopyIcon/CopyIcon';
+import { CheckmarkFilledIcon } from '@redocly/theme/icons/CheckmarkFilledIcon/CheckmarkFilledIcon';
+import { ConnectIcon } from '@redocly/theme/icons/ConnectIcon/ConnectIcon';
+import { useConnectMCPButton } from '@redocly/theme/core/hooks/use-connect-mcp-button';
+import { useThemeHooks } from '@redocly/theme/core/hooks';
+
+type TriggerButtonProps = {
+  text: string;
+};
+
+const TriggerButton = React.memo(({ text }: TriggerButtonProps): JSX.Element => {
+  return (
+    <StyledButton variant="secondary" icon={<ConnectIcon />}>
+      {text}
+    </StyledButton>
+  );
+});
+
+type MenuOption = {
+  key: MCPOption;
+  icon: React.ComponentType;
+  titleTranslationKey: string;
+  titleDefault: string;
+  descriptionTranslationKey: string;
+  descriptionDefault: string;
+};
+
+const MENU_OPTIONS: MenuOption[] = [
+  {
+    key: 'cursor',
+    icon: CursorIcon,
+    titleTranslationKey: 'page.actions.connectMcp.cursor',
+    titleDefault: 'Connect to Cursor',
+    descriptionTranslationKey: 'page.actions.connectMcp.cursorDescription',
+    descriptionDefault: 'Install MCP server on Cursor',
+  },
+  {
+    key: 'vscode',
+    icon: VSCodeIcon,
+    titleTranslationKey: 'page.actions.connectMcp.vscode',
+    titleDefault: 'Connect to VS Code',
+    descriptionTranslationKey: 'page.actions.connectMcp.vscodeDescription',
+    descriptionDefault: 'Install MCP server on VS Code',
+  },
+  {
+    key: 'copy',
+    icon: CopyIcon,
+    titleTranslationKey: 'page.actions.connectMcp.copyConfig',
+    titleDefault: 'Copy MCP Configuration',
+    descriptionTranslationKey: 'page.actions.connectMcp.copyConfigDescription',
+    descriptionDefault: 'Copy MCP JSON Configuration',
+  },
+];
+
+export type ConnectMCPButtonProps = {
+  placement?: 'top' | 'bottom';
+  alignment?: 'start' | 'end';
+  options?: MCPOption[];
+};
+
+export function ConnectMCPButton({
+  placement = 'bottom',
+  alignment = 'end',
+  options = ['cursor', 'vscode', 'copy'],
+}: ConnectMCPButtonProps): JSX.Element {
+  const { useTranslate } = useThemeHooks();
+  const { translate } = useTranslate();
+
+  const { isCopied, triggerButtonText, visibleOptions, handleAction } = useConnectMCPButton({
+    options,
+  });
+
+  const menuOptions = useMemo(
+    () => MENU_OPTIONS.filter((option) => visibleOptions.includes(option.key)),
+    [visibleOptions],
+  );
+
+  return (
+    <ConnectMCPButtonWrapper data-component-name="Buttons/ConnectMCPButton">
+      <Dropdown
+        trigger={<TriggerButton text={triggerButtonText} />}
+        triggerEvent="hover"
+        placement={placement}
+        alignment={alignment}
+        closeOnClick={false}
+      >
+        <DropdownMenu>
+          {menuOptions.map((option) => {
+            const Icon = option.icon;
+            const showCheckmark = option.key === 'copy' && isCopied;
+
+            return (
+              <DropdownMenuItem key={option.key} onAction={() => handleAction(option.key)}>
+                <MenuItemContent>
+                  <MenuItemIcon>
+                    {showCheckmark ? (
+                      <CheckmarkFilledIcon color="var(--color-success-base)" />
+                    ) : (
+                      <Icon />
+                    )}
+                  </MenuItemIcon>
+                  <MenuItemText>
+                    <MenuItemTitle>
+                      {translate(option.titleTranslationKey, option.titleDefault)}
+                    </MenuItemTitle>
+                    <MenuItemDescription>
+                      {translate(option.descriptionTranslationKey, option.descriptionDefault)}
+                    </MenuItemDescription>
+                  </MenuItemText>
+                </MenuItemContent>
+              </DropdownMenuItem>
+            );
+          })}
+        </DropdownMenu>
+      </Dropdown>
+    </ConnectMCPButtonWrapper>
+  );
+}
+
+const ConnectMCPButtonWrapper = styled.div`
+  display: inline-block;
+  position: relative;
+`;
+
+const StyledButton = styled(Button)`
+  --button-gap: var(--connect-mcp-button-gap);
+`;
+
+const MenuItemContent = styled.div`
+  display: flex;
+  align-items: center;
+  gap: var(--connect-mcp-button-menu-item-gap);
+  padding: var(--connect-mcp-button-menu-item-padding-block)
+    var(--connect-mcp-button-menu-item-padding-inline);
+`;
+
+const MenuItemIcon = styled.div`
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--connect-mcp-button-menu-item-icon-size);
+  height: var(--connect-mcp-button-menu-item-icon-size);
+  flex-shrink: 0;
+  border: var(--connect-mcp-button-menu-item-icon-border);
+  border-radius: var(--connect-mcp-button-menu-item-icon-border-radius);
+  color: var(--connect-mcp-button-menu-item-icon-color);
+`;
+
+const MenuItemText = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: var(--connect-mcp-button-menu-item-text-gap);
+  flex: 1;
+`;
+
+const MenuItemTitle = styled.div`
+  font-size: var(--connect-mcp-button-menu-item-title-font-size);
+  font-weight: var(--connect-mcp-button-menu-item-title-font-weight);
+  line-height: var(--connect-mcp-button-menu-item-title-line-height);
+  color: var(--connect-mcp-button-menu-item-title-color);
+`;
+
+const MenuItemDescription = styled.div`
+  font-size: var(--connect-mcp-button-menu-item-description-font-size);
+  font-weight: var(--connect-mcp-button-menu-item-description-font-weight);
+  line-height: var(--connect-mcp-button-menu-item-description-line-height);
+  color: var(--connect-mcp-button-menu-item-description-color);
+`;

package/src/components/Buttons/variables.ts

@@ -46,3 +46,44 @@ export const aiAssistantButton = css`
   /* Transition */
   --ai-assistant-button-transition: box-shadow 0.3s ease, transform 0.2s ease;
 `;
+
+export const connectMCPButton = css`
+  /**
+   * @tokens Connect MCP Button
+   * @presenter Color
+   */
+
+  /* Button gap */
+  --connect-mcp-button-gap: var(--spacing-xs);
+
+  /* Menu item layout */
+  --connect-mcp-button-menu-item-gap: var(--spacing-sm);
+  --connect-mcp-button-menu-item-padding-block: var(--spacing-xxs);
+  --connect-mcp-button-menu-item-padding-inline: 0;
+
+  /* Menu item icon */
+  --connect-mcp-button-menu-item-icon-size: 32px;
+  --connect-mcp-button-menu-item-icon-border-color: var(--border-color-secondary);
+  --connect-mcp-button-menu-item-icon-border-style: solid;
+  --connect-mcp-button-menu-item-icon-border-width: 1px;
+  --connect-mcp-button-menu-item-icon-border: var(--connect-mcp-button-menu-item-icon-border-width)
+    var(--connect-mcp-button-menu-item-icon-border-style)
+    var(--connect-mcp-button-menu-item-icon-border-color);
+  --connect-mcp-button-menu-item-icon-border-radius: var(--border-radius);
+  --connect-mcp-button-menu-item-icon-color: var(--icon-color-secondary);
+
+  /* Menu item text */
+  --connect-mcp-button-menu-item-text-gap: var(--spacing-xxs);
+
+  /* Menu item title */
+  --connect-mcp-button-menu-item-title-font-size: var(--font-size-base);
+  --connect-mcp-button-menu-item-title-font-weight: var(--font-weight-regular);
+  --connect-mcp-button-menu-item-title-line-height: var(--line-height-base);
+  --connect-mcp-button-menu-item-title-color: var(--text-color-secondary);
+
+  /* Menu item description */
+  --connect-mcp-button-menu-item-description-font-size: var(--font-size-sm);
+  --connect-mcp-button-menu-item-description-font-weight: var(--font-weight-regular);
+  --connect-mcp-button-menu-item-description-line-height: var(--line-height-sm);
+  --connect-mcp-button-menu-item-description-color: var(--text-color-description);
+`;

package/src/components/PageActions/PageActions.tsx

@@ -77,7 +77,7 @@ export function PageActions(props: PageActionProps): JSX.Element | null {
         </Button>
         {actions.length > 1 ? (
           <Dropdown withArrow trigger={<Button />} placement="bottom" alignment="end">
-            <DropdownMenu items={menuItems} />
+            <StyledDropdownMenu items={menuItems} />
           </Dropdown>
         ) : null}
       </ButtonGroup>
@@ -110,3 +110,7 @@ const LinkMenuItem = styled(Link)`
   text-decoration: none;
   --link-decoration-hover: none;
 `;
+
+const StyledDropdownMenu = styled(DropdownMenu)`
+  --dropdown-menu-max-height: var(--page-actions-dropdown-max-height);
+`;

package/src/components/PageActions/variables.ts

@@ -7,6 +7,8 @@ export const pageActions = css`
   --page-actions-button-text-color: var(--text-color-secondary);
   --page-actions-button-padding: 5px 14px 5px var(--spacing-sm);
 
+  --page-actions-dropdown-max-height: fit-content;
+
   --page-actions-menu-item-padding: 3px 0;
   --page-actions-menu-item-gap: var(--spacing-xs);
   --page-actions-menu-item-icon-color: var(--icon-color-secondary);

package/src/components/Segmented/Segmented.tsx

@@ -2,18 +2,10 @@ import React, { forwardRef } from 'react';
 import styled, { css } from 'styled-components';
 
 import type { ForwardedRef, ReactElement } from 'react';
-import type { SelectOption } from '@redocly/theme/core/types/select';
+import type { SegmentedProps } from '@redocly/theme/core/types/segmented';
 
 import { typedMemo } from '@redocly/theme/core/hoc/typedMemo';
 
-export type SegmentedProps<T> = {
-  options: SelectOption<T>[];
-  value: T;
-  onChange: ({ label, value }: SelectOption<T>) => void;
-  className?: string;
-  size?: 'regular' | 'small';
-};
-
 function SegmentedComponent<T>(
   { options, onChange, value, className = '', size = 'regular' }: SegmentedProps<T>,
   ref?: ForwardedRef<HTMLDivElement>,
@@ -25,17 +17,20 @@ function SegmentedComponent<T>(
       className={`tag-grey ${size} ${className}`}
       role="tablist"
     >
-      {options.map((opt) => (
-        <SegmentedItem
-          key={opt.label}
-          role="tab"
-          title={opt.label}
-          onClick={() => onChange(opt)}
-          $isActive={value == opt.value}
-          $size={size}
-        >
-          {opt.label}
-        </SegmentedItem>
+      {options.map((opt, index) => (
+        <React.Fragment key={index}>
+          {opt.divider}
+          <SegmentedItem
+            key={opt.label}
+            role="tab"
+            title={opt.label}
+            onClick={() => onChange(opt)}
+            $isActive={value == opt.value}
+            $size={size}
+          >
+            {opt.element || opt.label}
+          </SegmentedItem>
+        </React.Fragment>
       ))}
     </SegmentedGroup>
   );

package/src/core/constants/index.ts

@@ -4,3 +4,4 @@ export * from './code-walkthrough';
 export * from './search';
 export * from './catalog';
 export * from './breadcrumb';
+export * from './mcp';

package/src/core/constants/mcp.ts

@@ -0,0 +1 @@
+export const DEFAULT_MCP_SERVER_NAME = 'mcp-server';

package/src/core/hooks/index.ts

@@ -43,3 +43,5 @@ export * from './use-active-page-version';
 export * from './use-page-versions';
 export * from './use-user-teams';
 export * from './use-page-actions';
+export * from './use-mcp-config';
+export * from './use-connect-mcp-button';

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,
+  };
+}