@redocly/theme 0.69.0-next.0 → 0.69.0-next.10

package/src/core/types/catalog.ts

@@ -212,10 +212,8 @@ export type BffCatalogEntityList = BffCatalogList<BffCatalogEntity>;
 export type BffCatalogRelatedEntityList = BffCatalogList<BffCatalogRelatedEntity>;
 
 export type Page = {
-  endCursor: string | null;
-  startCursor: string | null;
-  hasNextPage: boolean;
-  hasPrevPage: boolean;
+  nextPage: string | null;
+  previousPage: string | null;
   limit: number;
   total: number;
 };

package/src/core/types/common.ts

@@ -1,5 +1,8 @@
+import type React from 'react';
 import { DEFAULT_COLOR_MODES } from '../constants';
 
 export type Plural<T extends string> = `${T}s`;
 
 export type ColorMode = (typeof DEFAULT_COLOR_MODES)[keyof typeof DEFAULT_COLOR_MODES];
+
+export type RenderableChildren<Context> = React.ReactNode | ((context: Context) => React.ReactNode);

package/src/core/types/hooks.ts

@@ -143,6 +143,7 @@ export type ThemeHooks = {
     docs: {
       enabled: boolean;
       name?: string;
+      publicEndpoint?: boolean;
     };
   };
   useSidebarItems: (activeVersion?: Version | null) => {

package/src/core/types/index.ts

@@ -22,3 +22,4 @@ export type * from './segmented';
 export type * from './tooltip';
 export type * from './toast';
 export type * from './link';
+export type * from './button-group';

package/src/core/types/l10n.ts

@@ -134,8 +134,28 @@ export type TranslationKey =
   | 'page.forbidden.description'
   | 'page.notFound.title'
   | 'page.notFound.description'
+  | 'page.apiNotFound.title'
+  | 'page.apiNotFound.description'
+  | 'page.apiNotFound.hint'
+  | 'page.apiNotFound.backButton'
   | 'page.mcpNotAllowed.title'
   | 'page.mcpNotAllowed.description'
+  | 'page.mcpNotAllowed.publicNote'
+  | 'page.mcpNotAllowed.publicEndpointHint'
+  | 'page.mcpNotAllowed.mainEndpointHint'
+  | 'page.mcpNotAllowed.snippets.terminal.hint'
+  | 'page.mcpNotAllowed.snippets.claudeCode.headline'
+  | 'page.mcpNotAllowed.snippets.claudeDesktop.headline'
+  | 'page.mcpNotAllowed.snippets.claudeDesktop.instruction'
+  | 'page.mcpNotAllowed.snippets.chatgptApp.headline'
+  | 'page.mcpNotAllowed.snippets.chatgptApp.instruction'
+  | 'page.mcpNotAllowed.snippets.codexCli.headline'
+  | 'page.mcpNotAllowed.snippets.prompt.headline'
+  | 'page.mcpNotAllowed.snippets.prompt.hint'
+  | 'page.mcpNotAllowed.snippets.json.hint'
+  | 'page.mcpNotAllowed.tabs.claude'
+  | 'page.mcpNotAllowed.tabs.chatgpt'
+  | 'page.mcpNotAllowed.tabs.json'
   | 'page.lastUpdated.timeago'
   | 'page.lastUpdated.on'
   | 'catalog.filters.placeholder'
@@ -271,8 +291,14 @@ export type TranslationKey =
   | 'page.actions.connectMcp.cursorDescription'
   | 'page.actions.connectMcp.vscode'
   | 'page.actions.connectMcp.vscodeDescription'
+  | 'page.actions.connectMcp.claudeCode'
+  | 'page.actions.connectMcp.claudeCodeDescription'
+  | 'page.actions.connectMcp.codex'
+  | 'page.actions.connectMcp.codexDescription'
   | 'page.actions.connectMcp.copyConfig'
   | 'page.actions.connectMcp.copyConfigDescription'
+  | 'page.actions.connectMcp.moreOptions'
+  | 'page.actions.moreActions'
   | 'openapi.download.description.title'
   | 'openapi.info.title'
   | 'openapi.info.contact.url'
@@ -280,6 +306,7 @@ export type TranslationKey =
   | 'openapi.info.license'
   | 'openapi.info.termsOfService'
   | 'openapi.info.metadata.title'
+  | 'graphql.info.metadata.title'
   | 'openapi.key'
   | 'openapi.value'
   | 'openapi.enum'
@@ -369,6 +396,8 @@ export type TranslationKey =
   | 'openapi.mcp.inputExample'
   | 'openapi.mcp.outputSchema'
   | 'openapi.mcp.outputExample'
+  | 'openapi.mcp.exampleTitle'
+  | 'openapi.mcp.argumentsExample'
   | 'asyncapi.download.description.title'
   | 'asyncapi.info.title'
   | 'asyncapi.info.contact.url'
@@ -449,7 +478,6 @@ export type TranslationKey =
   | 'graphql.sample'
   | 'graphql.referenced'
   | 'graphql.content.fragment'
-  | 'button.copy.tooltipText'
   | 'button.download.tooltipText'
   | 'button.externalLink.tooltipText'
   | 'button.email.tooltipText'

package/src/core/types/mcp.ts

@@ -1,6 +1,6 @@
 export type MCPClientType = 'cursor' | 'vscode';
 
-export type MCPOption = 'cursor' | 'vscode' | 'copy';
+export type MCPOption = 'cursor' | 'vscode' | 'claude-code' | 'codex' | 'copy';
 
 export type McpConnectionParams = {
   serverName: string;

package/src/core/utils/RenderWithLink.tsx

@@ -0,0 +1,19 @@
+import React from 'react';
+
+import type { JSX } from 'react';
+
+// Splits a translated sentence on <link>...</link> markers and renders the
+// marked phrase as an anchor, so each locale keeps its own word order.
+export function renderWithLink(text: string, href: string): JSX.Element {
+  const [before, label, after] = text.split(/<link>|<\/link>/);
+  if (label === undefined) {
+    return <>{text}</>;
+  }
+  return (
+    <>
+      {before}
+      <a href={href}>{label}</a>
+      {after}
+    </>
+  );
+}

package/src/core/utils/index.ts

@@ -48,3 +48,4 @@ export * from './get-auto-dismiss-duration';
 export * from './tooltip-placement';
 export * from './telemetry/get-base-data-attributes';
 export * from './telemetry/generate-before-after-context';
+export * from './RenderWithLink';

package/src/core/utils/mcp.ts

@@ -32,3 +32,42 @@ export function generateMCPDeepLink(
       return generateCursorMCPDeepLink(config);
   }
 }
+
+// Server names can contain spaces (e.g. "Docs MCP server") which break bare CLI
+// arguments, so commands use a slugified form while JSON configs keep the raw name.
+export function slugifyMcpServerName(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+// Claude Desktop's config file only launches stdio commands, so remote servers
+// connect through the mcp-remote bridge.
+export function generateClaudeDesktopConfig(config: McpConnectionParams): string {
+  return JSON.stringify(
+    {
+      mcpServers: {
+        [slugifyMcpServerName(config.serverName)]: {
+          command: 'npx',
+          args: ['-y', 'mcp-remote', config.url],
+        },
+      },
+    },
+    null,
+    2,
+  );
+}
+
+export function generateClaudeCodeCommand(config: McpConnectionParams): string {
+  return `claude mcp add --transport http ${slugifyMcpServerName(config.serverName)} ${config.url}`;
+}
+
+export function generateCodexCommand(config: McpConnectionParams): string {
+  return `codex mcp add ${slugifyMcpServerName(config.serverName)} --url ${config.url}`;
+}
+
+// Pasted into an AI assistant (Claude Code, Codex) so it installs the server itself.
+export function generateMcpInstallPrompt(config: McpConnectionParams): string {
+  return `Add the MCP server "${slugifyMcpServerName(config.serverName)}" with URL ${config.url} (streamable HTTP transport) to my MCP configuration, then verify it is connected.`;
+}

package/src/icons/CodexIcon/CodexIcon.tsx

@@ -0,0 +1,23 @@
+import React from 'react';
+import styled from 'styled-components';
+
+import type { IconProps } from '@redocly/theme/icons/types';
+
+import { getCssColorVariable } from '@redocly/theme/core/utils';
+
+const Icon = (props: IconProps) => (
+  <svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg" {...props}>
+    <path d="M22.2819 9.8211a5.9847 5.9847 0 0 0-.5157-4.9108 6.0462 6.0462 0 0 0-6.5098-2.9A6.0651 6.0651 0 0 0 4.9807 4.1818a5.9847 5.9847 0 0 0-3.9977 2.9 6.0462 6.0462 0 0 0 .7427 7.0966 5.98 5.98 0 0 0 .511 4.9107 6.051 6.051 0 0 0 6.5146 2.9001A5.9847 5.9847 0 0 0 13.2599 24a6.0557 6.0557 0 0 0 5.7718-4.2058 5.9894 5.9894 0 0 0 3.9977-2.9001 6.0557 6.0557 0 0 0-.7475-7.073zm-9.022 12.6081a4.4755 4.4755 0 0 1-2.8764-1.0408l.1419-.0804 4.7783-2.7582a.7948.7948 0 0 0 .3927-.6813v-6.7369l2.02 1.1686a.071.071 0 0 1 .038.052v5.5826a4.504 4.504 0 0 1-4.4945 4.4944zm-9.6607-4.1254a4.4708 4.4708 0 0 1-.5346-3.0137l.142.0852 4.783 2.7582a.7712.7712 0 0 0 .7806 0l5.8428-3.3685v2.3324a.0804.0804 0 0 1-.0332.0615L9.74 19.9502a4.4992 4.4992 0 0 1-6.1408-1.6464zM2.3408 7.8956a4.485 4.485 0 0 1 2.3655-1.9728V11.6a.7664.7664 0 0 0 .3879.6765l5.8144 3.3543-2.0201 1.1685a.0757.0757 0 0 1-.071 0l-4.8303-2.7865A4.504 4.504 0 0 1 2.3408 7.8956zm16.5963 3.8558L13.1038 8.364 15.1192 7.2a.0757.0757 0 0 1 .071 0l4.8303 2.7913a4.4944 4.4944 0 0 1-.6765 8.1042v-5.6772a.79.79 0 0 0-.407-.667zm2.0107-3.0231l-.142-.0852-4.7735-2.7818a.7759.7759 0 0 0-.7854 0L9.409 9.2297V6.8974a.0662.0662 0 0 1 .0284-.0615l4.8303-2.7866a4.4992 4.4992 0 0 1 6.6802 4.66zM8.3065 12.863l-2.02-1.1638a.0804.0804 0 0 1-.038-.0567V6.0742a4.4992 4.4992 0 0 1 7.3757-3.4537l-.142.0805L8.704 5.459a.7948.7948 0 0 0-.3927.6813zm1.0976-2.3654l2.602-1.4998 2.6069 1.4998v2.9994l-2.5974 1.4997-2.6067-1.4997z" />
+  </svg>
+);
+
+export const CodexIcon = styled(Icon).attrs({
+  'data-component-name': 'icons/CodexIcon/CodexIcon',
+})`
+  path {
+    fill: ${({ color }) => getCssColorVariable(color)};
+  }
+
+  height: ${({ size }) => size || '16px'};
+  width: ${({ size }) => size || '16px'};
+`;

package/src/icons/LinkIcon/LinkIcon.tsx

@@ -15,7 +15,7 @@ const Icon = (props: IconProps) => (
     {...props}
   >
     <path
-      d="M0 4C0 1.79086 1.79086 0 4 0H16C18.2091 0 20 1.79086 20 4V16C20 18.2091 18.2091 20 16 20H4C1.79086 20 0 18.2091 0 16V4Z"
+      d="M0 6C0 2.68629 2.68629 0 6 0H14C17.3137 0 20 2.68629 20 6V14C20 17.3137 17.3137 20 14 20H6C2.68629 20 0 17.3137 0 14V6Z"
       fill="var(--layer-color)"
     />
     <path

package/src/index.ts

@@ -15,6 +15,8 @@ export * from '@redocly/theme/components/Badge/Badge';
 export * from '@redocly/theme/components/Dropdown/Dropdown';
 export * from '@redocly/theme/components/Dropdown/DropdownMenu';
 export * from '@redocly/theme/components/Dropdown/DropdownMenuItem';
+export * from '@redocly/theme/components/Dropdown/DropdownMenuItemContent';
+export * from '@redocly/theme/components/SplitButton/SplitButton';
 export * from '@redocly/theme/components/Loaders/Loading';
 export * from '@redocly/theme/components/LoadMore/LoadMore';
 export * from '@redocly/theme/components/Link/Link';

package/src/layouts/McpNotAllowed.tsx

@@ -3,28 +3,61 @@ import styled from 'styled-components';
 
 import type { JSX } from 'react';
 
-import { useThemeHooks } from '@redocly/theme/core/hooks';
+import { useThemeHooks, useMCPConfig } from '@redocly/theme/core/hooks';
+import { renderWithLink } from '@redocly/theme/core/utils';
 import { ConnectMCPButton } from '@redocly/theme/components/Buttons/ConnectMCPButton';
+import { McpConnectionTabs } from '@redocly/theme/components/MCP/McpConnectionTabs';
 
 export default function McpNotAllowed(): JSX.Element {
   const { useTranslate } = useThemeHooks();
   const { translate } = useTranslate();
+  const { isPublicEndpointPage, alternateServerUrl } = useMCPConfig();
 
   return (
     <NotAllowedWrapper data-component-name="layouts/McpNotAllowed">
-      <StatusText>405</StatusText>
       <Title data-translation-key="page.mcpNotAllowed.title">
-        {translate('page.mcpNotAllowed.title', 'Method not allowed')}
+        {translate('page.mcpNotAllowed.title', 'Connect to the MCP server')}
       </Title>
       <Description data-translation-key="page.mcpNotAllowed.description">
         {translate(
           'page.mcpNotAllowed.description',
-          'To use this MCP server, register it in your MCP Client (for example: VS Code, Cursor, or Claude Code).',
+          'To use this MCP server, register it in your MCP client (for example: VS Code, Cursor, or Claude Code).',
         )}
       </Description>
+      {isPublicEndpointPage && (
+        <Description data-translation-key="page.mcpNotAllowed.publicNote">
+          {translate(
+            'page.mcpNotAllowed.publicNote',
+            'This endpoint serves publicly available content only and requires no login.',
+          )}
+        </Description>
+      )}
+      {isPublicEndpointPage && alternateServerUrl && (
+        <Description data-translation-key="page.mcpNotAllowed.mainEndpointHint">
+          {renderWithLink(
+            translate(
+              'page.mcpNotAllowed.mainEndpointHint',
+              'To access content available to your account, use the <link>main MCP endpoint</link>.',
+            ),
+            alternateServerUrl,
+          )}
+        </Description>
+      )}
+      {!isPublicEndpointPage && alternateServerUrl && (
+        <Description data-translation-key="page.mcpNotAllowed.publicEndpointHint">
+          {renderWithLink(
+            translate(
+              'page.mcpNotAllowed.publicEndpointHint',
+              'To connect anonymously without an account, use the <link>public endpoint</link>.',
+            ),
+            alternateServerUrl,
+          )}
+        </Description>
+      )}
       <ButtonWrapper>
         <ConnectMCPButton alignment="start" />
       </ButtonWrapper>
+      <McpConnectionTabs />
     </NotAllowedWrapper>
   );
 }
@@ -44,13 +77,6 @@ const NotAllowedWrapper = styled.div`
   }
 `;
 
-const StatusText = styled.div`
-  color: var(--page-mcp-405-status-text-color);
-  font-size: var(--page-mcp-405-status-font-size);
-  line-height: var(--page-mcp-405-status-line-height);
-  font-weight: var(--page-mcp-405-status-font-weight);
-`;
-
 const Title = styled.div`
   font-size: var(--page-mcp-405-title-font-size);
   line-height: var(--page-mcp-405-title-line-height);

package/src/markdoc/components/Accordion/Accordion.tsx

@@ -0,0 +1,128 @@
+import React from 'react';
+import styled, { keyframes } from 'styled-components';
+
+import type { JSX, PropsWithChildren } from 'react';
+
+import { ChevronRightIcon } from '@redocly/theme/icons/ChevronRightIcon/ChevronRightIcon';
+import { ACCORDION_COMPONENT_NAME } from '@redocly/theme/core/constants';
+
+export type AccordionProps = {
+  title: string;
+  expanded?: boolean;
+  className?: string;
+  'data-source'?: string;
+  'data-hash'?: string;
+};
+
+export function Accordion({
+  title,
+  expanded = false,
+  className,
+  children,
+  'data-source': dataSource,
+  'data-hash': dataHash,
+}: PropsWithChildren<AccordionProps>): JSX.Element {
+  return (
+    <AccordionWrapper
+      className={className}
+      open={expanded}
+      data-component-name={ACCORDION_COMPONENT_NAME}
+      data-source={dataSource}
+      data-hash={dataHash}
+    >
+      <AccordionSummary>
+        <ChevronRightIcon
+          color="--md-accordion-chevron-icon-color"
+          size="var(--md-accordion-chevron-icon-size)"
+        />
+        {title}
+      </AccordionSummary>
+      <AccordionBody>{children}</AccordionBody>
+    </AccordionWrapper>
+  );
+}
+
+const AccordionWrapper = styled.details`
+  margin: var(--md-accordion-margin);
+  border: var(--md-accordion-border);
+  border-radius: var(--md-accordion-border-radius);
+  font-family: var(--md-accordion-font-family);
+  overflow: hidden;
+
+  &[open] > summary svg {
+    transform: rotate(90deg);
+  }
+`;
+
+const AccordionSummary = styled.summary`
+  display: flex;
+  align-items: center;
+  gap: var(--md-accordion-gap);
+  cursor: pointer;
+  list-style: none;
+
+  background-color: var(--md-accordion-header-bg-color);
+  color: var(--md-accordion-header-text-color);
+  font-weight: var(--md-accordion-header-font-weight);
+  font-size: var(--md-accordion-header-font-size);
+  line-height: var(--md-accordion-header-line-height);
+  padding: var(--md-accordion-header-padding);
+
+  &::-webkit-details-marker {
+    display: none;
+  }
+
+  &:hover {
+    background-color: var(--md-accordion-header-bg-color-hover);
+  }
+
+  &:focus-visible {
+    outline: none;
+    position: relative;
+
+    &::after {
+      content: '';
+      position: absolute;
+      inset: 2px;
+      border: 1px solid var(--button-border-color-focused);
+      border-radius: calc(var(--md-accordion-border-radius) - 2px);
+      pointer-events: none;
+    }
+  }
+
+  svg {
+    flex-shrink: 0;
+    transition: transform 0.15s ease-out;
+  }
+`;
+
+const showAccordionBody = keyframes`
+  0% {
+    opacity: 0;
+    transform: translateY(-5px);
+  }
+  100% {
+    opacity: 1;
+    transform: translateY(0);
+  }
+`;
+
+const AccordionBody = styled.div`
+  padding: var(--md-accordion-body-padding);
+  background-color: var(--md-accordion-body-bg-color);
+  color: var(--md-accordion-body-text-color);
+  font-size: var(--md-accordion-body-font-size);
+  line-height: var(--md-accordion-body-line-height);
+
+  details[open] > & {
+    animation: ${showAccordionBody} 0.15s ease-out;
+  }
+
+  > :first-child {
+    margin-top: 0;
+  }
+
+  > :last-child {
+    margin-bottom: 0;
+  }
+`;

package/src/markdoc/components/Accordion/AccordionGroup.tsx

@@ -0,0 +1,41 @@
+import React from 'react';
+import styled from 'styled-components';
+
+import type { JSX, PropsWithChildren } from 'react';
+
+import { ACCORDION_GROUP_COMPONENT_NAME, ACCORDION_SELECTOR } from '@redocly/theme/core/constants';
+
+export type AccordionGroupProps = {
+  className?: string;
+};
+
+export function AccordionGroup({
+  className,
+  children,
+}: PropsWithChildren<AccordionGroupProps>): JSX.Element {
+  return (
+    <AccordionGroupWrapper
+      className={className}
+      data-component-name={ACCORDION_GROUP_COMPONENT_NAME}
+    >
+      {children}
+    </AccordionGroupWrapper>
+  );
+}
+
+const AccordionGroupWrapper = styled.div`
+  margin: var(--md-accordion-group-margin);
+  border: var(--md-accordion-group-border);
+  border-radius: var(--md-accordion-group-border-radius);
+  overflow: hidden;
+
+  & > ${ACCORDION_SELECTOR} {
+    margin: 0;
+    border: none;
+    border-radius: 0;
+  }
+
+  & > ${ACCORDION_SELECTOR} + ${ACCORDION_SELECTOR} {
+    border-top: var(--md-accordion-group-divider);
+  }
+`;

package/src/markdoc/components/Accordion/variables.ts

@@ -0,0 +1,37 @@
+import { css } from 'styled-components';
+
+export const markdownAccordion = css`
+  /**
+  *  @tokens Markdown Accordion
+  */
+
+  --md-accordion-group-margin: var(--spacing-base) 0; // @presenter Spacing
+  --md-accordion-group-border: 1px solid var(--border-color-secondary); // @presenter Border
+  --md-accordion-group-border-radius: var(--border-radius-xl); // @presenter BorderRadius
+  --md-accordion-group-divider: 1px solid var(--border-color-secondary); // @presenter Border
+
+  --md-accordion-margin: var(--spacing-base) 0; // @presenter Spacing
+  --md-accordion-border: 1px solid var(--border-color-secondary); // @presenter Border
+  --md-accordion-border-radius: var(--border-radius-xl); // @presenter BorderRadius
+  --md-accordion-gap: var(--spacing-xs); // @presenter Spacing
+  --md-accordion-font-family: var(--font-family-base); // @presenter FontFamily
+
+  --md-accordion-chevron-icon-color: var(--text-color-primary); // @presenter Color
+  --md-accordion-chevron-icon-size: 16px;
+
+  --md-accordion-header-bg-color: var(--layer-color); // @presenter Color
+  --md-accordion-header-bg-color-hover: var(--layer-color-hover); // @presenter Color
+  --md-accordion-header-text-color: var(--text-color-primary); // @presenter Color
+  --md-accordion-header-font-weight: var(--font-weight-semibold); // @presenter FontWeight
+  --md-accordion-header-line-height: var(--line-height-lg); // @presenter LineHeight
+  --md-accordion-header-font-size: var(--font-size-lg); // @presenter FontSize
+  --md-accordion-header-padding: var(--spacing-sm) var(--spacing-md); // @presenter Spacing
+
+  --md-accordion-body-bg-color: var(--bg-color); // @presenter Color
+  --md-accordion-body-text-color: var(--text-color-primary); // @presenter Color
+  --md-accordion-body-font-size: var(--font-size-base); // @presenter FontSize
+  --md-accordion-body-line-height: var(--line-height-base); // @presenter LineHeight
+  --md-accordion-body-padding: var(--spacing-sm) var(--spacing-md) var(--spacing-md); // @presenter Spacing
+
+  // @tokens End
+`;