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

package/src/components/MCP/McpConnectionTabs.tsx

@@ -0,0 +1,285 @@
+import React, { useEffect, useState } from 'react';
+import styled from 'styled-components';
+
+import type { JSX, ReactNode } from 'react';
+import type { TFunction } from '@redocly/theme/core/types';
+import type { AsyncApiRealmUI } from '@redocly/realm-asyncapi-sdk';
+import type { CodeBlockControlsProps } from '@redocly/theme/components/CodeBlock/CodeBlockControls';
+
+import { useMCPConfig, useThemeHooks } from '@redocly/theme/core/hooks';
+import {
+  generateClaudeCodeCommand,
+  generateClaudeDesktopConfig,
+  generateCodexCommand,
+  generateMcpInstallPrompt,
+  getBaseDataAttributes,
+} from '@redocly/theme/core/utils';
+import { CodeBlock } from '@redocly/theme/components/CodeBlock/CodeBlock';
+import { ClaudeIcon } from '@redocly/theme/icons/ClaudeIcon/ClaudeIcon';
+import { ChatGptIcon } from '@redocly/theme/icons/ChatGptIcon/ChatGptIcon';
+import { Tabs, TabsSize } from '@redocly/theme/markdoc/components/Tabs/Tabs';
+import { TabItemFragment } from '@redocly/theme/markdoc/components/Tabs/TabItemFragment';
+import { NumberedList } from '@redocly/theme/markdoc/components/NumberedList/NumberedList';
+import { NumberedItem } from '@redocly/theme/markdoc/components/NumberedList/NumberedItem';
+
+export type McpConnectionTab = 'claude' | 'chatgpt' | 'json';
+
+export type McpConnectionTabsProps = {
+  options?: McpConnectionTab[];
+  className?: string;
+};
+
+const DEFAULT_TAB_OPTIONS: McpConnectionTab[] = ['claude', 'chatgpt', 'json'];
+
+const TAB_LABELS: Record<
+  McpConnectionTab,
+  { translationKey: string; defaultLabel: string; icon?: React.ComponentType }
+> = {
+  claude: {
+    translationKey: 'page.mcpNotAllowed.tabs.claude',
+    defaultLabel: 'Claude',
+    icon: ClaudeIcon,
+  },
+  chatgpt: {
+    translationKey: 'page.mcpNotAllowed.tabs.chatgpt',
+    defaultLabel: 'ChatGPT',
+    icon: ChatGptIcon,
+  },
+  json: { translationKey: 'page.mcpNotAllowed.tabs.json', defaultLabel: 'JSON' },
+};
+
+type TabClient = { headline: string; content: ReactNode };
+
+type SnippetId =
+  AsyncApiRealmUI.EventPayload<'com.redocly.mcpConnectionSnippet.copied'>[0]['snippet'];
+
+type SnippetHeader = (client: McpConnectionTab, snippet: SnippetId) => CodeBlockControlsProps;
+
+export function McpConnectionTabs({
+  options = DEFAULT_TAB_OPTIONS,
+  className,
+}: McpConnectionTabsProps): JSX.Element | null {
+  const { useTranslate, useTelemetry } = useThemeHooks();
+  const { translate } = useTranslate();
+  const telemetry = useTelemetry();
+  const { serverName, serverUrl, isMcpDisabled } = useMCPConfig();
+  // The SSR markup of error pages is cached with the build-time origin, so the
+  // tabs remount after hydration to pick up the real browser origin.
+  const [hydrated, setHydrated] = useState(false);
+
+  useEffect(() => setHydrated(true), []);
+
+  if (isMcpDisabled) {
+    return null;
+  }
+
+  const connection = { serverName, url: serverUrl };
+
+  const snippetHeader: SnippetHeader = (client, snippet) => ({
+    controls: {
+      copy: {
+        onClick: () =>
+          telemetry.sendMcpConnectionSnippetCopiedMessage([
+            { ...getBaseDataAttributes('mcpConnectionSnippet', 'button'), client, snippet },
+          ]),
+      },
+      // The report control is docs feedback, not useful on the connection page.
+      report: { hidden: true },
+    },
+  });
+
+  return (
+    <McpConnectionTabsWrapper
+      key={hydrated ? 'client' : 'ssr'}
+      data-component-name="MCP/McpConnectionTabs"
+      data-testid="mcp-connection-tabs"
+      className={className}
+    >
+      <Tabs size={TabsSize.SMALL}>
+        {options.map((option) => {
+          const { translationKey, defaultLabel, icon: TabIcon } = TAB_LABELS[option];
+
+          return (
+            <TabItemFragment
+              key={option}
+              label={translate(translationKey, defaultLabel)}
+              icon={TabIcon ? <TabIcon /> : undefined}
+            >
+              {renderTabContent(option, connection, translate, snippetHeader)}
+            </TabItemFragment>
+          );
+        })}
+      </Tabs>
+    </McpConnectionTabsWrapper>
+  );
+}
+
+function renderTabContent(
+  option: McpConnectionTab,
+  connection: { serverName: string; url: string },
+  translate: TFunction,
+  snippetHeader: SnippetHeader,
+): ReactNode {
+  const terminalHint = (
+    <TabHint>
+      {translate('page.mcpNotAllowed.snippets.terminal.hint', 'Run this command in your terminal:')}
+    </TabHint>
+  );
+
+  const urlBlock = (
+    <CodeBlock lang="text" source={connection.url} header={snippetHeader(option, 'chatgpt-app')} />
+  );
+
+  const assistantPromptClient: TabClient = {
+    headline: translate('page.mcpNotAllowed.snippets.prompt.headline', 'Prompt'),
+    content: (
+      <>
+        <TabHint>
+          {translate(
+            'page.mcpNotAllowed.snippets.prompt.hint',
+            'Or paste this prompt into the chat to have it add the server for you:',
+          )}
+        </TabHint>
+        <CodeBlock
+          lang="text"
+          source={generateMcpInstallPrompt(connection)}
+          header={snippetHeader(option, 'prompt')}
+          wrapContents
+        />
+      </>
+    ),
+  };
+
+  switch (option) {
+    case 'claude':
+      return renderClientList([
+        {
+          headline: translate('page.mcpNotAllowed.snippets.claudeCode.headline', 'Claude Code'),
+          content: (
+            <>
+              {terminalHint}
+              <CodeBlock
+                lang="shell"
+                source={generateClaudeCodeCommand(connection)}
+                header={snippetHeader(option, 'claude-code')}
+                wrapContents
+              />
+            </>
+          ),
+        },
+        {
+          headline: translate(
+            'page.mcpNotAllowed.snippets.claudeDesktop.headline',
+            'Claude Desktop',
+          ),
+          content: (
+            <>
+              <TabHint>
+                {translate(
+                  'page.mcpNotAllowed.snippets.claudeDesktop.instruction',
+                  'In Claude Desktop, open Settings → Developer → Edit Config, add this to the configuration file, and restart Claude Desktop:',
+                )}
+              </TabHint>
+              <CodeBlock
+                lang="json"
+                source={generateClaudeDesktopConfig(connection)}
+                header={snippetHeader(option, 'claude-desktop')}
+              />
+            </>
+          ),
+        },
+      ]);
+    case 'chatgpt':
+      return renderClientList([
+        {
+          headline: translate('page.mcpNotAllowed.snippets.codexCli.headline', 'Codex CLI'),
+          content: (
+            <>
+              {terminalHint}
+              <CodeBlock
+                lang="shell"
+                source={generateCodexCommand(connection)}
+                header={snippetHeader(option, 'codex')}
+                wrapContents
+              />
+            </>
+          ),
+        },
+        {
+          headline: translate(
+            'page.mcpNotAllowed.snippets.chatgptApp.headline',
+            'ChatGPT desktop app',
+          ),
+          content: (
+            <>
+              <TabHint>
+                {translate(
+                  'page.mcpNotAllowed.snippets.chatgptApp.instruction',
+                  'In the ChatGPT desktop app, go to Settings → Plugins → MCPs and add a server with the "Streamable HTTP" type and this URL (restart the app afterwards):',
+                )}
+              </TabHint>
+              {urlBlock}
+            </>
+          ),
+        },
+        assistantPromptClient,
+      ]);
+    case 'json':
+      return (
+        <>
+          <TabHint>
+            {translate(
+              'page.mcpNotAllowed.snippets.json.hint',
+              'Add this server entry to your MCP client configuration file:',
+            )}
+          </TabHint>
+          <CodeBlock
+            lang="json"
+            source={JSON.stringify(
+              { [connection.serverName]: { url: connection.url, description: 'MCP Server' } },
+              null,
+              2,
+            )}
+            header={snippetHeader(option, 'json')}
+          />
+        </>
+      );
+  }
+}
+
+function renderClientList(clients: TabClient[]): ReactNode {
+  return (
+    <NumberedList>
+      {clients.map((client, index) => (
+        <NumberedItem
+          key={index}
+          type="dot"
+          size="small"
+          headline={client.headline}
+          index={index + 1}
+          isLast={index === clients.length - 1}
+        >
+          {client.content}
+        </NumberedItem>
+      ))}
+    </NumberedList>
+  );
+}
+
+const McpConnectionTabsWrapper = styled.div`
+  --md-numbered-list-margin: 0 0 var(--spacing-sm);
+
+  font-size: var(--page-mcp-405-snippets-font-size);
+  line-height: var(--page-mcp-405-snippets-line-height);
+  text-align: left;
+
+  /* The copy control floats over the code, so wrapped lines need room to clear it. */
+  pre[data-testid='source-code'] {
+    padding-right: var(--page-mcp-405-snippets-code-padding-right);
+  }
+`;
+
+const TabHint = styled.p`
+  margin: 0 0 var(--spacing-xs);
+  color: var(--page-mcp-405-snippets-hint-text-color);
+`;

package/src/components/Markdown/styles/base-table.ts

@@ -45,6 +45,14 @@ export const markdownBaseTableCss = css`
       background-color: var(--md-table-header-bg-color);
     }
 
+    /* hide the header row when every cell is empty; one labelled cell keeps it visible */
+    thead:has(th:empty) {
+      display: none;
+    }
+    thead:has(th:not(:empty)) {
+      display: table-header-group;
+    }
+
     tr {
       background-color: var(--md-table-stripe-bg-color);
     }

package/src/components/Markdown/variables.ts

@@ -40,7 +40,7 @@ export const markdown = css`
   --md-table-line-height: var(--line-height-md); // @presenter FontSize
   --md-table-margin-vertical: 20px; // @presenter Spacing
   --md-table-bg-color: transparent; // @presenter Color
-  --md-table-border-radius: var(--border-radius);
+  --md-table-border-radius: var(--border-radius-xl);
 
   --md-table-border-width: 1px;
   --md-table-header-bg-color: var(--layer-color);

package/src/components/Menu/MenuItem.tsx

@@ -122,8 +122,8 @@ function MenuItemImpl(props: React.PropsWithChildren<MenuItemProps>): JSX.Elemen
       onClick={handleOnClick}
       onKeyDown={handleExpandOnEnter}
       ref={labelRef}
-      role={item.link ? 'none' : 'link'}
-      tabIndex={!item.link ? 0 : undefined}
+      role={item.link || isSeparator ? 'none' : 'link'}
+      tabIndex={!item.link && !isSeparator ? 0 : undefined}
       data-testid="menu-item-label"
       data-active={item.active}
     >

package/src/components/Menu/variables.ts

@@ -56,7 +56,7 @@ export const menu = css`
   --menu-item-label-margin: var(--menu-item-label-margin-vertical) var(--menu-item-label-margin-horizontal);
   --menu-item-label-padding: var(--menu-item-padding-vertical) var(--menu-item-padding-horizontal);
   --menu-item-label-gap: var(--spacing-xxs);
-  --menu-item-label-border-radius: 6px;
+  --menu-item-label-border-radius: var(--border-radius-lg);
   --menu-item-label-chevron-size: 12px;
   --menu-item-label-chevron-offset: calc(var(--menu-item-label-gap) + var(--menu-item-label-chevron-size));
 

package/src/components/Navbar/variables.ts

@@ -27,7 +27,7 @@ export const navbar = css`
 
   --navbar-item-line-height: var(--line-height-base);
   --navbar-item-bg-color-active: var(--bg-color-active);
-  --navbar-item-border-radius: var(--border-radius);
+  --navbar-item-border-radius: var(--border-radius-lg);
   --navbar-item-bottom-border: none;
 
   --navbar-item-text-color-hover: var(--text-color-primary);

package/src/components/PageActions/PageActions.tsx

@@ -7,13 +7,12 @@ import type { PageAction } from '@redocly/theme/core/types';
 import { PageActionsMenuItem } from '@redocly/theme/components/PageActions/PageActionsMenuItem';
 import { DropdownMenuItem } from '@redocly/theme/components/Dropdown/DropdownMenuItem';
 import { Link } from '@redocly/theme/components/Link/Link';
-import { ButtonGroup } from '@redocly/theme/components/Button/ButtonGroup';
 import { Button } from '@redocly/theme/components/Button/Button';
-import { Dropdown } from '@redocly/theme/components/Dropdown/Dropdown';
+import { SplitButton } from '@redocly/theme/components/SplitButton/SplitButton';
 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 { PageActionType, usePageActions } from '@redocly/theme/core/hooks';
+import { PageActionType, usePageActions, useThemeHooks } from '@redocly/theme/core/hooks';
 
 type ActionState = 'idle' | 'processing' | 'done';
 
@@ -28,6 +27,8 @@ const ACTION_DONE_DISPLAY_DURATION = 1000;
 export function PageActions(props: PageActionProps): JSX.Element | null {
   const { pageSlug, mcpUrl } = props;
 
+  const { useTranslate } = useThemeHooks();
+  const { translate } = useTranslate();
   const actions = usePageActions(pageSlug || '/', mcpUrl, props.actions);
 
   const [actionState, setActionState] = useState<ActionState>('idle');
@@ -73,27 +74,25 @@ export function PageActions(props: PageActionProps): JSX.Element | null {
 
   return (
     <PageActionsWrapper data-component-name="PageActions/PageActions">
-      <ButtonGroup variant="outlined" size="medium">
-        <Button
-          icon={renderIcon(buttonAction, actionState)}
-          to={'link' in buttonAction ? buttonAction.link : undefined}
-          external
-          onClick={() => handleActionClick(buttonAction)}
-        >
-          {buttonAction.buttonText}
-        </Button>
-        {actions.length > 1 ? (
-          <Dropdown
-            withArrow
-            portalled
-            trigger={<Button aria-label="More actions" />}
-            placement="bottom"
-            alignment="end"
+      <SplitButton
+        portalled
+        variant="outlined"
+        size="medium"
+        toggleAriaLabel={translate('page.actions.moreActions', 'More actions')}
+        button={
+          <Button
+            variant="outlined"
+            icon={renderIcon(buttonAction, actionState)}
+            to={'link' in buttonAction ? buttonAction.link : undefined}
+            external
+            onClick={() => handleActionClick(buttonAction)}
           >
-            <StyledDropdownMenu>{menuItems}</StyledDropdownMenu>
-          </Dropdown>
-        ) : null}
-      </ButtonGroup>
+            {buttonAction.buttonText}
+          </Button>
+        }
+      >
+        {actions.length > 1 ? <StyledDropdownMenu>{menuItems}</StyledDropdownMenu> : null}
+      </SplitButton>
     </PageActionsWrapper>
   );
 }

package/src/components/PageActions/PageActionsMenuItem.tsx

@@ -1,73 +1,59 @@
 import React from 'react';
 import styled from 'styled-components';
 
+import type { JSX } from 'react';
 import type { PageAction } from '@redocly/theme/core/types';
 
+import { DropdownMenuItemContent } from '@redocly/theme/components/Dropdown/DropdownMenuItemContent';
 import { LaunchIcon } from '@redocly/theme/icons/LaunchIcon/LaunchIcon';
 
-type PageActionsMenuItemProps = {
+export type PageActionsMenuItemProps = {
   pageAction: PageAction;
+  className?: string;
 };
 
-export function PageActionsMenuItem(props: PageActionsMenuItemProps) {
-  const { pageAction } = props;
+export function PageActionsMenuItem(props: PageActionsMenuItemProps): JSX.Element {
+  const { pageAction, className } = props;
 
   return (
-    <MenuItemWrapper data-component-name="PageActions/PageActionsMenuItem">
-      <IconWrapper>
-        <pageAction.iconComponent />
-      </IconWrapper>
-      <ContentWrapper>
-        <Title>
-          {pageAction.title}
-          {'link' in pageAction ? (
-            <LaunchIcon color="var(--page-actions-menu-item-title-icon-color)" size="14px" />
-          ) : null}
-        </Title>
-        <Description>{pageAction.description}</Description>
-      </ContentWrapper>
+    <MenuItemWrapper data-component-name="PageActions/PageActionsMenuItem" className={className}>
+      <DropdownMenuItemContent
+        icon={<pageAction.iconComponent />}
+        title={
+          <>
+            {pageAction.title}
+            {'link' in pageAction ? (
+              <LaunchIcon color="var(--page-actions-menu-item-title-icon-color)" size="14px" />
+            ) : null}
+          </>
+        }
+        description={pageAction.description}
+      />
     </MenuItemWrapper>
   );
 }
 
 const MenuItemWrapper = styled.div`
-  padding: var(--page-actions-menu-item-padding);
-  display: flex;
-  flex-direction: row;
-  align-items: center;
-  gap: var(--page-actions-menu-item-gap);
-`;
-
-const IconWrapper = styled.div`
-  color: var(--page-actions-menu-item-icon-color);
-  border: 1px solid var(--page-actions-menu-item-icon-border-color);
-  border-radius: var(--page-actions-menu-item-icon-border-radius);
-  width: var(--page-actions-menu-item-icon-wrapper-size);
-  height: var(--page-actions-menu-item-icon-wrapper-size);
-  display: flex;
-  align-items: center;
-  justify-content: center;
-`;
-
-const ContentWrapper = styled.div`
-  display: flex;
-  flex-direction: column;
-  gap: var(--page-actions-menu-item-text-gap);
-`;
-
-const Title = styled.div`
-  font-weight: var(--page-actions-menu-item-title-font-weight);
-  font-size: var(--page-actions-menu-item-title-font-size);
-  line-height: var(--page-actions-menu-item-title-line-height);
-  color: var(--page-actions-menu-item-title-color);
-  display: flex;
-  align-items: center;
-  gap: var(--page-actions-menu-item-title-icon-gap);
-`;
-
-const Description = styled.div`
-  font-weight: var(--page-actions-menu-item-description-font-weight);
-  font-size: var(--page-actions-menu-item-description-font-size);
-  line-height: var(--page-actions-menu-item-description-line-height);
-  color: var(--page-actions-menu-item-description-color);
+  --dropdown-menu-item-content-gap: var(--page-actions-menu-item-gap);
+  --dropdown-menu-item-content-padding: var(--page-actions-menu-item-padding);
+  --dropdown-menu-item-content-icon-size: var(--page-actions-menu-item-icon-wrapper-size);
+  --dropdown-menu-item-content-icon-color: var(--page-actions-menu-item-icon-color);
+  --dropdown-menu-item-content-icon-border: 1px solid var(--page-actions-menu-item-icon-border-color);
+  --dropdown-menu-item-content-icon-border-radius: var(--page-actions-menu-item-icon-border-radius);
+  --dropdown-menu-item-content-text-gap: var(--page-actions-menu-item-text-gap);
+  --dropdown-menu-item-content-title-icon-gap: var(--page-actions-menu-item-title-icon-gap);
+  --dropdown-menu-item-content-title-font-weight: var(--page-actions-menu-item-title-font-weight);
+  --dropdown-menu-item-content-title-font-size: var(--page-actions-menu-item-title-font-size);
+  --dropdown-menu-item-content-title-line-height: var(--page-actions-menu-item-title-line-height);
+  --dropdown-menu-item-content-title-color: var(--page-actions-menu-item-title-color);
+  --dropdown-menu-item-content-description-font-weight: var(
+    --page-actions-menu-item-description-font-weight
+  );
+  --dropdown-menu-item-content-description-font-size: var(
+    --page-actions-menu-item-description-font-size
+  );
+  --dropdown-menu-item-content-description-line-height: var(
+    --page-actions-menu-item-description-line-height
+  );
+  --dropdown-menu-item-content-description-color: var(--page-actions-menu-item-description-color);
 `;

package/src/components/Panel/Panel.tsx

@@ -1,4 +1,4 @@
-import React, { useEffect, useState } from 'react';
+import React, { useState } from 'react';
 import styled from 'styled-components';
 
 import type { BaseSyntheticEvent, PropsWithChildren, ReactNode, JSX } from 'react';
@@ -34,6 +34,12 @@ export function Panel({
 }: PropsWithChildren<PanelProps>): JSX.Element {
   const [isExpanded, setExpanded] = useState(expanded);
   const [animate, setAnimate] = useState(false);
+  const [prevExpanded, setPrevExpanded] = useState(expanded);
+
+  if (prevExpanded !== expanded) {
+    setPrevExpanded(expanded);
+    setExpanded(expanded);
+  }
 
   const toggle = ({ target }: BaseSyntheticEvent): void => {
     if (target instanceof HTMLAnchorElement || !isExpandable) return;
@@ -42,8 +48,6 @@ export function Panel({
     onToggle?.(!isExpanded);
   };
 
-  useEffect(() => setExpanded(expanded), [expanded]);
-
   return (
     <PanelWrapper
       className={className}

package/src/components/Panel/variables.ts

@@ -178,7 +178,7 @@ export const apiReferencePanels = css`
   * @tokens Panel common
   */
 
-  --panel-border-radius: var(--border-radius); // @presenter BorderRadius
+  --panel-border-radius: var(--border-radius-xl); // @presenter BorderRadius
   --panel-border: 1px solid var(--border-color-secondary); // @presenter Border
 
   --panel-line-height: var(--line-height-base); // @presenter LineHeight

package/src/components/Product/variables.ts

@@ -25,7 +25,7 @@ export const productPicker = css`
   --product-picker-dropdown-item-padding-vertical: var(--dropdown-menu-item-padding-vertical); // @presenter Spacing
   --product-picker-dropdown-item-separator-padding-top: var(--dropdown-menu-item-separator-padding-top ); // @presenter Spacing
   --product-picker-dropdown-item-separator-padding-bottom: var(--dropdown-menu-item-separator-padding-bottom ); // @presenter Spacing
-  --product-picker-dropdown-item-border-radius: var(--dropdown-menu-item-border-radius ); // @presenter BorderRadius
+  --product-picker-dropdown-item-border-radius: var(--dropdown-menu-item-border-radius); // @presenter BorderRadius
   --product-picker-dropdown-item-bg-color-active: var(--dropdown-menu-item-bg-color-active); // @presenter Color
   --product-picker-dropdown-item-bg-color-hover: var(--dropdown-menu-item-bg-color-hover); // @presenter Color
   --product-picker-dropdown-item-bg-color-disabled: var(--dropdown-menu-item-bg-color-disabled); // @presenter Color
@@ -36,4 +36,5 @@ export const productPicker = css`
   --product-picker-dropdown-item-color-hover: var(--dropdown-menu-item-color-hover);
   --product-picker-dropdown-item-border-color-focused: var(--dropdown-menu-item-border-color-focused);
 
+  // @tokens End
 `;

package/src/components/ReplayGate/ReplayGate.tsx

@@ -10,6 +10,9 @@ export type ReplayGateProps = {
   // The current OpenAPI description's id (from x-metadata), when known. Lets a custom
   // ReplayGate vary behavior per API in a multi-API catalog.
   apiId?: string;
+  // Closes the whole Replay overlay. A gate that denies access calls this instead of
+  // rendering `children`, so a dismissed gate doesn't leave Replay reachable.
+  onClose: () => void;
   children: React.ReactNode;
 };