@redocly/theme 0.61.1 → 0.62.0-custom.1

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

@@ -16,6 +16,12 @@ import { useMCPConfig } from './use-mcp-config';
 import { ClipboardService } from '../utils/clipboard-service';
 import { IS_BROWSER } from '../utils/dom';
 import { generateMCPDeepLink } from '../utils/mcp';
+import {
+  addTrailingSlash,
+  combineUrls,
+  removeTrailingSlash,
+  withoutPathPrefix,
+} from '../utils/urls';
 
 function createPageActionResource(pageSlug: string, pageUrl: string) {
   return {
@@ -32,6 +38,7 @@ const DEFAULT_ENABLED_ACTIONS = [
   'claude',
   'docs-mcp-cursor',
   'docs-mcp-vscode',
+  'docs-mcp-json',
 ] as const;
 
 export type PageActionType =
@@ -41,6 +48,7 @@ export type PageActionType =
   | 'claude'
   | 'docs-mcp-cursor'
   | 'docs-mcp-vscode'
+  | 'docs-mcp-json'
   | 'mcp-cursor'
   | 'mcp-vscode';
 
@@ -88,10 +96,12 @@ export function usePageActions(
           translate,
           onClickCallback: isDocsMcp
             ? () =>
-                telemetry.sendPageActionsButtonClickedMessage({
-                  ...createPageActionResource(pageSlug, pageUrl),
-                  action_type: `docs-mcp-${clientType}` as const,
-                })
+                telemetry.sendPageActionsButtonClickedMessage([
+                  {
+                    ...createPageActionResource(pageSlug, pageUrl),
+                    action_type: `docs-mcp-${clientType}` as const,
+                  },
+                ])
             : undefined,
         });
       },
@@ -99,18 +109,19 @@ export function usePageActions(
   );
 
   const result: PageAction[] = useMemo(() => {
-    if (shouldHideAllActions) {
+    if (shouldHideAllActions && !actions?.length) {
       return [];
     }
 
     const origin = IS_BROWSER
       ? window.location.origin
       : ((globalThis as { SSR_HOSTNAME?: string })['SSR_HOSTNAME'] ?? '');
-    const normalizedSlug = pageSlug.startsWith('/') ? pageSlug : '/' + pageSlug;
-    const pageUrl = `${origin}${normalizedSlug}`;
-    const mdPageUrl = new URL(
-      origin + normalizedSlug + (normalizedSlug === '/' ? 'index.html.md' : '.md'),
-    ).toString();
+    const pathname = addTrailingSlash(pageSlug);
+    const pageUrl = combineUrls(origin, pathname);
+    const isRoot = withoutPathPrefix(pathname) === '/';
+    const mdPageUrl = isRoot
+      ? combineUrls(origin, pathname, 'index.html.md')
+      : combineUrls(origin, removeTrailingSlash(pathname) + '.md');
 
     const actionHandlers: Record<PageActionType, () => PageAction | null> = {
       'docs-mcp-cursor': createMCPHandler('cursor', false),
@@ -131,10 +142,12 @@ export function usePageActions(
             }
             const text = await result.text();
             ClipboardService.copyCustom(text);
-            telemetry.sendPageActionsButtonClickedMessage({
-              ...createPageActionResource(pageSlug, pageUrl),
-              action_type: 'copy',
-            });
+            telemetry.sendPageActionsButtonClickedMessage([
+              {
+                ...createPageActionResource(pageSlug, pageUrl),
+                action_type: 'copy',
+              },
+            ]);
           } catch (error) {
             console.error(error);
           }
@@ -148,10 +161,12 @@ export function usePageActions(
         iconComponent: MarkdownFullIcon,
         link: mdPageUrl,
         onClick: () => {
-          telemetry.sendPageActionsButtonClickedMessage({
-            ...createPageActionResource(pageSlug, pageUrl),
-            action_type: 'view',
-          });
+          telemetry.sendPageActionsButtonClickedMessage([
+            {
+              ...createPageActionResource(pageSlug, pageUrl),
+              action_type: 'view',
+            },
+          ]);
         },
       }),
 
@@ -159,17 +174,21 @@ export function usePageActions(
         if (!isPublic) {
           return null;
         }
+        const link = getExternalAiPromptLink('https://chat.openai.com', mdPageUrl);
         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),
+          link,
           onClick: () => {
-            telemetry.sendPageActionsButtonClickedMessage({
-              ...createPageActionResource(pageSlug, pageUrl),
-              action_type: 'chatgpt',
-            });
+            telemetry.sendPageActionsButtonClickedMessage([
+              {
+                ...createPageActionResource(pageSlug, pageUrl),
+                action_type: 'chatgpt',
+              },
+            ]);
+            window.location.href = link;
           },
         };
       },
@@ -178,17 +197,43 @@ export function usePageActions(
         if (!isPublic) {
           return null;
         }
+        const link = getExternalAiPromptLink('https://claude.ai/new', mdPageUrl);
         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),
+          link,
           onClick: () => {
-            telemetry.sendPageActionsButtonClickedMessage({
-              ...createPageActionResource(pageSlug, pageUrl),
-              action_type: 'claude',
-            });
+            telemetry.sendPageActionsButtonClickedMessage([
+              {
+                ...createPageActionResource(pageSlug, pageUrl),
+                action_type: 'claude',
+              },
+            ]);
+            window.location.href = link;
+          },
+        };
+      },
+      'docs-mcp-json': () => {
+        return {
+          buttonText: 'Copy MCP configuration',
+          title: 'Copy MCP JSON configuration',
+          description: 'Copy MCP JSON configuration',
+          iconComponent: CopyIcon,
+          onClick: async () => {
+            ClipboardService.copyCustom(
+              JSON.stringify(
+                {
+                  'mcp-server': {
+                    url: mcpUrl,
+                    description: 'MCP Server',
+                  },
+                },
+                null,
+                2,
+              ),
+            );
           },
         };
       },
@@ -205,6 +250,7 @@ export function usePageActions(
     translate,
     isPublic,
     createMCPHandler,
+    mcpUrl,
     telemetry,
   ]);
 
@@ -280,9 +326,10 @@ function shouldHidePageActions(
   }
 
   // Page is excluded from search
+  const isOpenApiPage =
+    pageProps?.metadata?.type === 'openapi' || pageProps?.metadata?.subType === 'openapi-operation';
   const isPageExcludedFromSearch =
-    pageProps?.frontmatter?.excludeFromSearch ||
-    (pageProps?.metadata?.type === 'openapi' && openapiExcludeFromSearch);
+    pageProps?.frontmatter?.excludeFromSearch || (isOpenApiPage && openapiExcludeFromSearch);
 
   if (isPageExcludedFromSearch) {
     return true;

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

@@ -14,7 +14,7 @@ export function useProductPicker() {
   const loadAndNavigate = useLoadAndNavigate();
   function setProduct(product: typeof currentProduct) {
     if (!product) return;
-    telemetry.sendProductPickedMessage({ product: product.slug });
+    telemetry.sendProductPickedMessage([{ object: 'product', product: product.slug }]);
     if (typeof document === 'undefined') return;
 
     if (product.name) {

package/src/core/hooks/use-unique-svg-ids.ts

@@ -0,0 +1,12 @@
+import { useId } from 'react';
+
+/**
+ * Returns a function that appends a per-component-instance suffix to SVG ids.
+ * This prevents collisions when multiple identical SVGs are rendered on the same page,
+ * which can break `url(#...)` references (gradients, clipPath, masks, filters) on reflow.
+ */
+export function useUniqueSvgIds(): (id: string) => string {
+  const reactId = useId();
+  const safeSuffix = reactId.replace(/:/g, '_');
+  return (id: string): string => `${id}-${safeSuffix}`;
+}

package/src/core/openapi/index.ts

@@ -38,3 +38,5 @@ export { SecurityVariablesEnvSuffix } from '../constants/environments';
 export { isUndefined, isString, isNotNull, isObject } from '../utils/type-guards';
 export { ThemeDataContext, type ThemeDataTransferObject } from '../contexts/ThemeDataContext';
 export { SearchSessionProvider, SearchSessionContext } from '../contexts/SearchContext';
+export { useUniqueSvgIds } from '../hooks/use-unique-svg-ids';
+export { trimText } from '../utils/text-trimmer';

package/src/core/styles/dark.ts

@@ -16,6 +16,7 @@ import { pageActionsDarkMode } from '@redocly/theme/components/PageActions/varia
 import { tooltipDarkMode } from '@redocly/theme/components/Tooltip/variables.dark';
 import { bannerDarkMode } from '@redocly/theme/components/Banner/variables.dark';
 import { admonitionDarkMode } from '@redocly/theme/components/Admonition/variables.dark';
+import { svgViewerDarkMode } from '@redocly/theme/components/SvgViewer/variables.dark';
 
 const replayDarkMode = css`
   /**
@@ -45,6 +46,17 @@ const replayDarkMode = css`
   // @tokens End
 `;
 
+const badgesDarkMode = css`
+  /**
+    * @tokens Audience Badge
+    */
+
+  --badge-audience-text-color: var(--text-color-secondary); // @presenter Color
+  --badge-audience-bg-color: var(--color-warm-grey-4); // @presenter Color
+
+  // @tokens End
+`
+
 
 export const darkMode = css`
   /* === Dark Theme Colors  === */
@@ -332,6 +344,8 @@ export const darkMode = css`
   ${tooltipDarkMode}
   ${bannerDarkMode}
   ${admonitionDarkMode}
+  ${svgViewerDarkMode}
+  ${badgesDarkMode}
 
   /**
     * @tokens Dark Theme Scrollbar Config

package/src/core/styles/global.ts

@@ -42,6 +42,7 @@ import { cards } from '@redocly/theme/markdoc/components/Cards/variables';
 import { codeWalkthrough } from '@redocly/theme/markdoc/components/CodeWalkthrough/variables';
 import { skipContent } from '@redocly/theme/components/SkipContent/variables';
 import { pageActions } from '@redocly/theme/components/PageActions/variables';
+import { svgViewer } from '@redocly/theme/components/SvgViewer/variables';
 
 import { darkMode } from './dark';
 
@@ -822,6 +823,13 @@ const badges = css`
   --badge-deprecated-bg-color: var(--color-warning-base); // @presenter Color
   --badge-deprecated-border-radius: var(--border-radius); // @presenter BorderRadius
 
+  /**
+    * @tokens Audience Badge
+    */
+
+  --badge-audience-text-color: var(--text-color-secondary); // @presenter Color
+  --badge-audience-bg-color: var(--color-warm-grey-2); // @presenter Color
+
   // @tokens End
 `;
 
@@ -971,23 +979,41 @@ const pages = css`
     */
 
   --page-403-font-family: var(--font-family-base); // @presenter FontFamily
+  --page-403-margin-vertical: var(--spacing-xl); // @presenter Spacing
+  --page-403-margin-horizontal: calc(var(--spacing-xxl) * 2); // @presenter Spacing
+  --page-403-gap: var(--spacing-lg); // @presenter Spacing
+  --page-403-max-width: 680px; // @presenter Width
+
+  --page-403-status-text-color: var(--text-color-helper); // @presenter Color
+  --page-403-status-font-size: var(--font-size-lg); // @presenter FontSize
+  --page-403-status-font-weight: var(--font-weight-semibold); // @presenter FontWeight
+  --page-403-status-line-height: var(--line-height-lg); // @presenter LineHeight
+
+  --page-403-title-text-color: var(--text-color-primary); // @presenter Color
+  --page-403-title-font-size: 42px; // @presenter FontSize
+  --page-403-title-font-weight: var(--font-weight-bold); // @presenter FontWeight
+  --page-403-title-line-height: 50px; // @presenter LineHeight
+
+  --page-403-description-text-color: var(--text-color-secondary); // @presenter Color
+  --page-403-description-font-size: var(--font-size-xl); // @presenter FontSize
+  --page-403-description-font-weight: var(--font-weight-regular); // @presenter FontWeight
+  --page-403-description-line-height: var(--line-height-xl); // @presenter LineHeight
+
+  // @tokens End
+
+  /**
+    * @tokens 403 Page OIDC Forbidden
+    * @presenter Color
+    */
 
-  --page-403-header-text-color: var(--h1-text-color);
+  --page-403-header-text-color: var(--h1-text-color); // @presenter Color
   --page-403-header-font-size: var(--h1-font-size); // @presenter FontSize
   --page-403-header-font-weight: var(--h1-font-weight); // @presenter FontWeight
   --page-403-header-line-height: var(--h1-line-height); // @presenter LineHeight
   --page-403-header-margin: 0; // @presenter Spacing
-
-  --page-403-description-text-color: var(--text-color-secondary);
-  --page-403-description-font-size: 1.5em; // @presenter FontSize
-  --page-403-description-font-weight: var(--font-weight-regular); // @presenter FontWeight
-  --page-403-description-line-height: 1; // @presenter LineHeight
   --page-403-description-margin: 0; // @presenter Spacing
-
-  --page-403-button-margin: 4em; // @presenter Spacing
-
-  --page-403-oidc-description-font-size: var(--font-size-lg);
-  --page-403-oidc-description-margin: var(--spacing-md) var(--spacing-sm);
+  --page-403-oidc-description-font-size: var(--font-size-lg); // @presenter FontSize
+  --page-403-oidc-description-margin: var(--spacing-md) var(--spacing-sm); // @presenter Spacing
 
   // @tokens End
 
@@ -1085,10 +1111,6 @@ const error = css`
 `;
 
 const modal = css`
-  body:has(.scroll-lock) {
-    overflow: hidden;
-  }
-
   --modal-box-shadow: var(--bg-raised-shadow);
   --modal-bg-color: var(--bg-color);
 `;
@@ -1301,6 +1323,7 @@ export const styles = css`
     ${replay}
     ${skipContent}
     ${pageActions}
+    ${svgViewer}
 
     background-color: var(--bg-color);
     color: var(--text-color-primary);

package/src/core/types/catalog.ts

@@ -154,7 +154,7 @@ export type BffCatalogRelatedEntity = {
   key: string;
   title: string;
   summary?: string | null;
-  readonly source: 'api' | 'file';
+  readonly source: 'remote' | 'file';
   relationRole: 'source' | 'target';
   relationType: EntityRelationType;
   sourceFile?: string | null;

package/src/core/types/hooks.ts

@@ -28,6 +28,8 @@ import type {
   SearchFilterItem,
   SearchFacetQuery,
   AiSearchConversationItem,
+  ToolCallName,
+  ContentSegment,
 } from './search';
 import type { SubmitFeedbackParams } from './feedback';
 import type { TFunction } from './l10n';
@@ -127,6 +129,13 @@ export type ThemeHooks = {
     error: null | AiSearchError;
     conversation: AiSearchConversationItem[];
     setConversation: React.Dispatch<React.SetStateAction<AiSearchConversationItem[]>>;
+    toolCalls: Array<{
+      name: ToolCallName;
+      args: unknown;
+      position: number;
+      result?: { documentCount: number };
+    }>;
+    contentSegments: ContentSegment[];
   };
   useMarkdownText: (text: string) => React.ReactNode;
   useFacetQuery: (field: string) => {
@@ -177,7 +186,26 @@ export type ThemeHooks = {
     | 'startSpan'
     | 'constructCloudEvent'
     | 'sendToOtelService'
-  >;
+  > & {
+    send<TEventType extends AsyncApiRealmUI.EventType>(
+      event: TEventType,
+      data?: AsyncApiRealmUI.EventPayload<TEventType>,
+    ): void;
+    /**
+     * @deprecated This method is deprecated. Use send(event, data) instead.
+     */
+    send<TEventType extends AsyncApiRealmUI.EventType>(
+      params: AsyncApiRealmUI.SendEventParams<TEventType>,
+    ): void;
+  };
+  /**
+   * @deprecated This hook is deprecated. Use `useTelemetry` instead.
+   */
+  useOtelTelemetry: () => {
+    send<TEventType extends AsyncApiRealmUI.EventType>(
+      params: AsyncApiRealmUI.SendEventParams<TEventType>,
+    ): void;
+  };
   useUserTeams: () => string[];
   usePageData: () => PageData | null;
   usePageSharedData: <T = unknown>(dataId: string) => T;

package/src/core/types/l10n.ts

@@ -87,6 +87,7 @@ export type TranslationKey =
   | 'search.ai.newConversation'
   | 'search.ai.backToSearch'
   | 'search.ai.back'
+  | 'search.ai.assistant'
   | 'search.ai.placeholder'
   | 'search.ai.generatingResponse'
   | 'search.ai.followUpQuestion'
@@ -98,6 +99,9 @@ export type TranslationKey =
   | 'search.ai.feedback.title'
   | 'search.ai.feedback.detailsPlaceholder'
   | 'search.ai.feedback.thanks'
+  | 'search.ai.toolResult.found'
+  | 'search.ai.toolResult.found.documents'
+  | 'search.ai.toolCall.searching'
   | 'search.ai.button'
   | 'search.ai.label'
   | 'search.ai.disclaimer'
@@ -116,6 +120,7 @@ export type TranslationKey =
   | 'footer.copyrightText'
   | 'page.homeButton'
   | 'page.forbidden.title'
+  | 'page.forbidden.description'
   | 'page.notFound.title'
   | 'page.notFound.description'
   | 'page.lastUpdated.timeago'
@@ -198,6 +203,7 @@ export type TranslationKey =
   | 'feedback.settings.comment.label'
   | 'feedback.settings.comment.send'
   | 'feedback.settings.comment.cancel'
+  | 'feedback.settings.comment.maxLength'
   | 'feedback.settings.comment.satisfiedLabel'
   | 'feedback.settings.comment.neutralLabel'
   | 'feedback.settings.comment.dissatisfiedLabel'
@@ -412,7 +418,13 @@ export type TranslationKey =
   | 'select.noResults'
   | 'loaders.loading'
   | 'filter.dateRange.from'
-  | 'filter.dateRange.to';
+  | 'filter.dateRange.to'
+  | 'mermaid.openFullscreen'
+  | 'mermaid.zoomIn'
+  | 'mermaid.zoomOut'
+  | 'mermaid.reset'
+  | 'mermaid.close'
+  | 'mermaid.viewer';
 
 export type Locale = { code: string; name: string };
 

package/src/core/types/search.ts

@@ -104,10 +104,29 @@ export type SearchAiMessageResource = {
   title: string;
 };
 
+export type ToolCall = {
+  name: ToolCallName;
+  args: unknown;
+  position: number;
+  result?: { documentCount: number };
+};
+
+export type ContentSegment = { type: 'text'; text: string } | { type: 'tool'; toolCall: ToolCall };
+
 export type AiSearchConversationItem = {
   role: AiSearchConversationRole;
   content: string;
   resources?: SearchAiMessageResource[];
   messageId?: string;
   feedback?: FeedbackType;
+  toolCalls?: ToolCall[];
+  contentSegments?: ContentSegment[];
 };
+
+export enum ToolCallName {
+  SearchDocumentation = 'search_documentation',
+  ListApis = 'list-apis',
+  GetEndpoints = 'get-endpoints',
+  GetSecuritySchemes = 'get-security-schemes',
+  GetFullApiDescription = 'get-full-api-description',
+}

package/src/core/utils/content-segments.ts

@@ -0,0 +1,27 @@
+import type { ToolCall, ContentSegment } from '../types/search';
+
+export function splitContentByToolCalls(
+  content: string | undefined,
+  toolCalls: ToolCall[] | undefined,
+): ContentSegment[] {
+  if (!toolCalls || toolCalls.length === 0) {
+    return [{ type: 'text', text: content || '' }];
+  }
+
+  const segments: ContentSegment[] = [];
+  let lastPos = 0;
+
+  for (const toolCall of toolCalls) {
+    if (content && toolCall.position > lastPos) {
+      segments.push({ type: 'text', text: content.substring(lastPos, toolCall.position) });
+    }
+    segments.push({ type: 'tool', toolCall });
+    lastPos = toolCall.position;
+  }
+
+  if (content && lastPos < content.length) {
+    segments.push({ type: 'text', text: content.substring(lastPos) });
+  }
+
+  return segments;
+}

package/src/core/utils/index.ts

@@ -43,3 +43,4 @@ export * from './get-operation-color';
 export * from './frontmatter-translate';
 export * from './transform-revisions-to-version-history';
 export * from './build-revision-url';
+export * from './content-segments';