@redocly/theme 0.61.0-next.1 → 0.61.0-next.3

package/src/components/ColorModeSwitcher/ColorModeSwitcher.tsx

@@ -2,7 +2,7 @@ import React from 'react';
 
 import type { JSX } from 'react';
 
-import { useMount, useColorSwitcher } from '@redocly/theme/core/hooks';
+import { useColorSwitcher } from '@redocly/theme/core/hooks';
 import { ColorModeIcon } from '@redocly/theme/components/ColorModeSwitcher/ColorModeIcon';
 import { Button } from '@redocly/theme/components/Button/Button';
 
@@ -11,12 +11,7 @@ export type ColorModeSwitcherProps = {
 };
 
 export function ColorModeSwitcher({ className }: ColorModeSwitcherProps): JSX.Element | null {
-  const { isSwitcherHidden, initActiveColorMode, switchColorMode, activeColorMode } =
-    useColorSwitcher();
-
-  useMount(() => {
-    initActiveColorMode();
-  });
+  const { isSwitcherHidden, switchColorMode, activeColorMode } = useColorSwitcher();
 
   if (isSwitcherHidden) {
     return null;

package/src/components/Menu/variables.ts

@@ -40,6 +40,7 @@ export const menu = css`
   --menu-item-padding-vertical: var(--spacing-unit); // @presenter Spacing
   --menu-item-padding-horizontal: var(--spacing-xxs); // @presenter Spacing
   --menu-item-nested-offset: var(--spacing-sm); // @presenter Spacing
+  --menu-header-container-gap: var(--spacing-sm); // @presenter Spacing
 
   /**
    * @tokens Menu item label

package/src/components/Product/utils.ts

@@ -0,0 +1,6 @@
+export function getProductClassName(productName: string): string {
+  return `product-${productName
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')}`;
+}

package/src/components/Tooltip/Tooltip.tsx

@@ -110,6 +110,8 @@ export function TooltipComponent({
       onMouseEnter: handleOpen,
       onMouseLeave: handleClose,
       onClick: handleClose,
+      onFocus: handleOpen,
+      onBlur: handleClose,
     };
 
   return (

package/src/core/constants/catalog.ts

@@ -84,3 +84,5 @@ export enum GraphCustomNodeType {
 export enum GraphCustomEdgeType {
   CatalogEdge = 'catalogEdge',
 }
+
+export const VERSION_NOT_SPECIFIED = 'not_specified_version';

package/src/core/constants/common.ts

@@ -30,3 +30,8 @@ export enum MobileMenuType {
   PRODUCT = 'PRODUCT',
   PAGE = 'PAGE',
 }
+
+export const DEFAULT_COLOR_MODES = {
+  LIGHT: 'light',
+  DARK: 'dark',
+} as const;

package/src/core/hooks/__mocks__/use-theme-hooks.ts

@@ -15,6 +15,7 @@ export const useThemeHooks = vi.fn(() => ({
   useTelemetry: vi.fn(() => ({
     send: vi.fn(),
     sendCodeSnippetReportedMessage: vi.fn(),
+    sendPageActionsButtonClickedMessage: vi.fn(),
   })),
   useBreadcrumbs: vi.fn().mockReturnValue({ breadcrumbs: [], siblings: undefined }),
   useBanner: vi.fn(() => ({

package/src/core/hooks/catalog/use-catalog-entity-details.ts

@@ -1,16 +1,23 @@
 import type { CatalogEntityConfig, EntitiesCatalogConfig } from '@redocly/config';
 import type { BffCatalogEntity } from '@redocly/theme/core/types';
 
-import { getPathPrefix } from '../../utils/urls';
+import { withPathPrefix } from '../../utils/urls';
 
 type Props = {
   catalogConfig: CatalogEntityConfig;
   entitiesCatalogConfig?: EntitiesCatalogConfig;
+  revision?: string | null;
+  version?: string | null;
 };
 
 type BaseEntity = Pick<BffCatalogEntity, 'key' | 'type'>;
 
-export function useCatalogEntityDetails({ catalogConfig, entitiesCatalogConfig }: Props) {
+export function useCatalogEntityDetails({
+  catalogConfig,
+  entitiesCatalogConfig,
+  revision,
+  version,
+}: Props) {
   const getCatalogSpecificConfigByEntityTypeIncluded = (entity: BaseEntity) => {
     if (!entitiesCatalogConfig) {
       return;
@@ -22,14 +29,23 @@ export function useCatalogEntityDetails({ catalogConfig, entitiesCatalogConfig }
   };
 
   const getEntityDetailsLink = (entity: BaseEntity) => {
-    const pathPrefix = getPathPrefix();
     const catalogSpecificConfig = getCatalogSpecificConfigByEntityTypeIncluded(entity);
 
-    if (!catalogSpecificConfig || !entitiesCatalogConfig) {
-      return `${pathPrefix}/catalogs/${catalogConfig.slug}/entities/${entity.key}`;
+    const basePath =
+      !catalogSpecificConfig || !entitiesCatalogConfig
+        ? withPathPrefix(`/catalogs/${catalogConfig.slug}/entities/${entity.key}`)
+        : withPathPrefix(`/catalogs/${catalogSpecificConfig.slug}/entities/${entity.key}`);
+
+    const params = new URLSearchParams();
+    if (revision) {
+      params.set('revision', revision);
+    }
+    if (version !== undefined) {
+      params.set('version', version ?? '');
     }
+    params.set('search', '');
 
-    return `${pathPrefix}/catalogs/${catalogSpecificConfig.slug}/entities/${entity.key}`;
+    return `${basePath}?${params.toString()}`;
   };
 
   return { getEntityDetailsLink };

package/src/core/hooks/index.ts

@@ -48,3 +48,4 @@ export * from './use-connect-mcp-button';
 export * from './catalog/use-catalog-entity-details';
 export * from './catalog/use-catalog-entity-schema';
 export * from './catalog/use-catalog-table-header-cell-actions';
+export * from './use-store';

package/src/core/hooks/search/use-recent-searches.ts

@@ -1,83 +1,56 @@
-import { useCallback, useSyncExternalStore } from 'react';
+import { useCallback } from 'react';
 
+import { createStore, useStore } from '../use-store';
 import { isBrowser } from '../../utils/js-utils';
 
 const RECENT_SEARCHES_KEY = 'recentSearches';
 const RECENT_SEARCHES_LIMIT = 5;
 
-const createRecentSearchesStore = () => {
-  const subscribers = new Set<() => void>();
-  let cachedSnapshot: string[];
-
-  const getSnapshot = (): string[] => {
-    if (!isBrowser()) return [];
-
-    if (cachedSnapshot) return cachedSnapshot;
-
-    try {
-      const stored = localStorage.getItem(RECENT_SEARCHES_KEY);
-      cachedSnapshot = stored ? JSON.parse(stored) : [];
-      return cachedSnapshot;
-    } catch (e) {
-      cachedSnapshot = [];
-      return cachedSnapshot;
-    }
-  };
-
-  const updateItems = (value: string, isAdd: boolean) => {
-    if (!isBrowser()) return;
-
-    const currentItems = getSnapshot();
-    const valueIndex = currentItems.indexOf(value);
-
-    if (valueIndex !== -1) {
-      currentItems.splice(valueIndex, 1);
-    }
-
-    if (isAdd) {
-      currentItems.unshift(value);
-    }
-
-    const limitedItems = currentItems.slice(0, RECENT_SEARCHES_LIMIT);
-
-    localStorage.setItem(RECENT_SEARCHES_KEY, JSON.stringify(limitedItems));
-    cachedSnapshot = limitedItems;
-
-    subscribers.forEach((callback) => callback());
-  };
-
-  const subscribe = (callback: () => void) => {
-    subscribers.add(callback);
-    return () => subscribers.delete(callback);
-  };
-
-  return {
-    getSnapshot,
-    subscribe,
-    updateItems,
-  };
-};
-
-const recentSearchesStore = createRecentSearchesStore();
+const recentSearchesStore = createStore<string[]>({
+  storageKey: RECENT_SEARCHES_KEY,
+});
 
 export const useRecentSearches = (): {
   items: string[];
   addSearchHistoryItem: (value: string) => void;
   removeSearchHistoryItem: (value: string) => void;
 } => {
-  const items = useSyncExternalStore(
-    recentSearchesStore.subscribe,
-    recentSearchesStore.getSnapshot,
-    () => [],
+  const [items, setItems] = useStore<string[]>(recentSearchesStore, []);
+
+  const updateItems = useCallback(
+    (value: string, isAdd: boolean) => {
+      if (!isBrowser()) return;
+
+      const currentItems = [...items];
+      const valueIndex = currentItems.indexOf(value);
+      if (valueIndex !== -1) {
+        currentItems.splice(valueIndex, 1);
+      }
+
+      if (isAdd) {
+        currentItems.unshift(value);
+      }
+
+      const limitedItems = currentItems.slice(0, RECENT_SEARCHES_LIMIT);
+
+      setItems(limitedItems);
+    },
+    [items, setItems],
   );
 
-  const addSearchHistoryItem = useCallback((value: string) => {
-    recentSearchesStore.updateItems(value, true);
-  }, []);
+  const addSearchHistoryItem = useCallback(
+    (value: string) => {
+      updateItems(value, true);
+    },
+    [updateItems],
+  );
 
-  const removeSearchHistoryItem = useCallback((value: string) => {
-    recentSearchesStore.updateItems(value, false);
-  }, []);
+  const removeSearchHistoryItem = useCallback(
+    (value: string) => {
+      updateItems(value, false);
+    },
+    [updateItems],
+  );
 
   return { items, addSearchHistoryItem, removeSearchHistoryItem };
 };

package/src/core/hooks/use-color-switcher.ts

@@ -1,23 +1,38 @@
-import { useState } from 'react';
+import { useMemo } from 'react';
+
+import { useMount } from '@redocly/theme/core/hooks';
 
 import { useThemeConfig } from './use-theme-config';
 import { useThemeHooks } from './use-theme-hooks';
+import { createStore, useStore } from './use-store';
+import { DEFAULT_COLOR_MODES } from '../constants';
+
+const COLOR_MODE_KEY = 'colorSchema';
+const colorModeStore = createStore<string>({
+  storageKey: COLOR_MODE_KEY,
+});
 
 export const useColorSwitcher = () => {
   const themeSettings = useThemeConfig();
   const { useTelemetry } = useThemeHooks();
   const telemetry = useTelemetry();
-  const colorMode = themeSettings.colorMode;
-  const modes = colorMode?.modes || ['light', 'dark'];
-  const defaultColor = modes[0] || 'light';
-  const [activeColorMode, setActiveColorMode] = useState(defaultColor);
+  const themeColorMode = themeSettings.colorMode;
+
+  const modes = useMemo(
+    () => themeColorMode?.modes || [DEFAULT_COLOR_MODES.LIGHT, DEFAULT_COLOR_MODES.DARK],
+    [themeColorMode],
+  );
+
+  const defaultMode = modes[0] || DEFAULT_COLOR_MODES.LIGHT;
 
-  const initActiveColorMode = (): void => {
+  const [activeColorMode, setActiveColorMode] = useStore<string>(colorModeStore, defaultMode);
+
+  useMount(() => {
     const activeMode = Array.from(document.documentElement.classList).find((c) =>
       modes.includes(c),
     );
-    setActiveColorMode(activeMode || defaultColor);
-  };
+    setActiveColorMode(activeMode || defaultMode);
+  });
 
   const switchColorMode = (mode?: string): void => {
     if (mode && !modes.includes(mode)) {
@@ -25,23 +40,22 @@ export const useColorSwitcher = () => {
     }
 
     const activeIndex = modes.indexOf(activeColorMode);
-    // If specific mode is provided, use it, otherwise cycle through modes
     const newMode = mode || (activeIndex < modes.length - 1 ? modes[activeIndex + 1] : modes[0]);
 
-    localStorage.setItem('colorSchema', newMode);
-    document.documentElement.className = `${newMode} notransition`;
+    const root = document.documentElement;
+
+    modes.forEach((mode) => root.classList.remove(mode));
+    root.classList.add(newMode, 'notransition');
 
     window.requestAnimationFrame(() => {
-      document.documentElement.classList.remove('notransition');
+      root.classList.remove('notransition');
     });
     telemetry.sendColorModeSwitchedMessage({ from: activeColorMode, to: newMode });
-
     setActiveColorMode(newMode);
   };
 
   return {
-    isSwitcherHidden: colorMode?.hide,
-    initActiveColorMode,
+    isSwitcherHidden: themeColorMode?.hide,
     switchColorMode,
     activeColorMode,
   };

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

@@ -17,6 +17,14 @@ import { ClipboardService } from '../utils/clipboard-service';
 import { IS_BROWSER } from '../utils/dom';
 import { generateMCPDeepLink } from '../utils/mcp';
 
+function createPageActionResource(pageSlug: string, pageUrl: string) {
+  return {
+    id: pageSlug,
+    object: 'page' as const,
+    uri: pageUrl,
+  };
+}
+
 const DEFAULT_ENABLED_ACTIONS = [
   'copy',
   'view',
@@ -41,10 +49,12 @@ export function usePageActions(
   mcpUrl?: string,
   actions?: PageActionType[],
 ): PageAction[] {
-  const { useTranslate, usePageData, usePageProps, usePageSharedData } = useThemeHooks();
+  const { useTranslate, usePageData, usePageProps, usePageSharedData, useTelemetry } =
+    useThemeHooks();
   const { translate } = useTranslate();
   const themeConfig = useThemeConfig();
   const pageProps = usePageProps();
+  const telemetry = useTelemetry();
   const openApiSharedData = usePageSharedData<
     { options: { excludeFromSearch: boolean } } | undefined
   >('openAPIDocsStore');
@@ -67,9 +77,25 @@ export function usePageActions(
           ? { serverName: mcpConfig.serverName, url: mcpUrl || '' }
           : { serverName: mcpConfig.serverName, url: mcpConfig.serverUrl || '' };
 
-        return createMCPAction({ clientType, mcpConfig: config, translate });
+        const isDocsMcp = !requiresMcpUrl;
+
+        const origin = IS_BROWSER ? window.location.origin : '';
+        const pageUrl = `${origin}${pageSlug}`;
+
+        return createMCPAction({
+          clientType,
+          mcpConfig: config,
+          translate,
+          onClickCallback: isDocsMcp
+            ? () =>
+                telemetry.sendPageActionsButtonClickedMessage({
+                  ...createPageActionResource(pageSlug, pageUrl),
+                  action_type: `docs-mcp-${clientType}` as const,
+                })
+            : undefined,
+        });
       },
-    [mcpUrl, mcpConfig, translate],
+    [mcpUrl, mcpConfig, translate, telemetry, pageSlug],
   );
 
   const result: PageAction[] = useMemo(() => {
@@ -81,13 +107,14 @@ export function usePageActions(
       ? 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 actionHandlers: Record<PageActionType, () => PageAction | null> = {
-      'docs-mcp-cursor': createMCPHandler('cursor'),
-      'docs-mcp-vscode': createMCPHandler('vscode'),
+      'docs-mcp-cursor': createMCPHandler('cursor', false),
+      'docs-mcp-vscode': createMCPHandler('vscode', false),
       'mcp-cursor': createMCPHandler('cursor', true),
       'mcp-vscode': createMCPHandler('vscode', true),
 
@@ -104,6 +131,10 @@ export function usePageActions(
             }
             const text = await result.text();
             ClipboardService.copyCustom(text);
+            telemetry.sendPageActionsButtonClickedMessage({
+              ...createPageActionResource(pageSlug, pageUrl),
+              action_type: 'copy',
+            });
           } catch (error) {
             console.error(error);
           }
@@ -116,6 +147,12 @@ export function usePageActions(
         description: translate('page.actions.viewAsMdDescription', 'Open this page as Markdown'),
         iconComponent: MarkdownFullIcon,
         link: mdPageUrl,
+        onClick: () => {
+          telemetry.sendPageActionsButtonClickedMessage({
+            ...createPageActionResource(pageSlug, pageUrl),
+            action_type: 'view',
+          });
+        },
       }),
 
       chatgpt: () => {
@@ -128,6 +165,12 @@ export function usePageActions(
           description: translate('page.actions.chatGptDescription', 'Get insights from ChatGPT'),
           iconComponent: ChatGptIcon,
           link: getExternalAiPromptLink('https://chat.openai.com', mdPageUrl),
+          onClick: () => {
+            telemetry.sendPageActionsButtonClickedMessage({
+              ...createPageActionResource(pageSlug, pageUrl),
+              action_type: 'chatgpt',
+            });
+          },
         };
       },
 
@@ -141,6 +184,12 @@ export function usePageActions(
           description: translate('page.actions.claudeDescription', 'Get insights from Claude'),
           iconComponent: ClaudeIcon,
           link: getExternalAiPromptLink('https://claude.ai/new', mdPageUrl),
+          onClick: () => {
+            telemetry.sendPageActionsButtonClickedMessage({
+              ...createPageActionResource(pageSlug, pageUrl),
+              action_type: 'claude',
+            });
+          },
         };
       },
     };
@@ -156,6 +205,7 @@ export function usePageActions(
     translate,
     isPublic,
     createMCPHandler,
+    telemetry,
   ]);
 
   return result;
@@ -172,12 +222,19 @@ type CreateMCPActionParams = {
   clientType: MCPClientType;
   mcpConfig: McpConnectionParams;
   translate: (key: string, defaultValue: string) => string;
+  onClickCallback?: () => void;
 };
 
-function createMCPAction({ clientType, mcpConfig, translate }: CreateMCPActionParams): PageAction {
+function createMCPAction({
+  clientType,
+  mcpConfig,
+  translate,
+  onClickCallback,
+}: CreateMCPActionParams): PageAction {
   const url = generateMCPDeepLink(clientType, mcpConfig);
   const sharedProps = {
     onClick: () => {
+      onClickCallback?.();
       window.open(url, '_blank');
     },
   };

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

@@ -1,5 +1,7 @@
 import { useNavigate } from 'react-router-dom';
 
+import { getProductClassName } from '@redocly/theme/components/Product/utils';
+
 import { useThemeHooks } from './use-theme-hooks';
 import { withPathPrefix } from '../utils';
 
@@ -13,6 +15,16 @@ export function useProductPicker() {
   function setProduct(product: typeof currentProduct) {
     if (!product) return;
     telemetry.sendProductPickedMessage({ product: product.slug });
+    if (typeof document === 'undefined') return;
+
+    if (product.name) {
+      const root = document.documentElement;
+      Array.from(root.classList)
+        .filter((c) => c.startsWith('product-'))
+        .forEach((c) => root.classList.remove(c));
+      root.classList.add(getProductClassName(product.name));
+    }
+
     loadAndNavigate({ navigate, to: withPathPrefix(product.link) });
   }
   return {

package/src/core/hooks/use-store.ts

@@ -0,0 +1,95 @@
+import { useSyncExternalStore } from 'react';
+
+import { isBrowser } from '../utils/js-utils';
+
+type Store<T> = {
+  getValue: (defaultValue: T) => T;
+  setValue: (next: T) => void;
+  subscribe: (callback: () => void) => Unsubscribe;
+};
+
+type Unsubscribe = () => void;
+
+type CreateStoreProps<T> = {
+  storageKey: string;
+  storageType?: 'localStorage' | 'sessionStorage';
+  serializer?: {
+    parse: (value: string) => T;
+    serialize: (value: T) => string;
+  };
+};
+
+export function createStore<T>({
+  storageKey,
+  storageType = 'localStorage',
+  serializer = {
+    parse: (value: string) => JSON.parse(value) as T,
+    serialize: (value: T) => JSON.stringify(value),
+  },
+}: CreateStoreProps<T>): Store<T> {
+  const subscribers = new Set<() => void>();
+  let cachedValue: T;
+
+  const shouldSerialize = (value: unknown) => typeof value !== 'string';
+
+  const getValue = (defaultValue: T): T => {
+    if (!isBrowser()) return defaultValue;
+    if (cachedValue !== undefined) return cachedValue;
+
+    const value = window[storageType].getItem(storageKey);
+    if (!value) {
+      cachedValue = defaultValue;
+      return cachedValue;
+    }
+
+    if (!shouldSerialize(defaultValue)) {
+      cachedValue = value as T;
+      return cachedValue;
+    }
+
+    try {
+      cachedValue = JSON.parse(value) as T;
+    } catch {
+      cachedValue = defaultValue;
+    }
+
+    return cachedValue;
+  };
+
+  const setValue = (next: T): void => {
+    if (!isBrowser()) return;
+    try {
+      window[storageType].setItem(
+        storageKey,
+        shouldSerialize(next) ? serializer.serialize(next) : (next as string),
+      );
+      cachedValue = next;
+      subscribers.forEach((callback) => callback());
+    } catch {
+      return;
+    }
+  };
+
+  const subscribe = (callback: () => void): Unsubscribe => {
+    subscribers.add(callback);
+    return () => {
+      subscribers.delete(callback);
+    };
+  };
+
+  return {
+    getValue,
+    setValue,
+    subscribe,
+  };
+}
+
+export function useStore<T>(store: Store<T>, defaultValue: T) {
+  const value = useSyncExternalStore(
+    store.subscribe,
+    () => store.getValue(defaultValue),
+    () => defaultValue,
+  );
+
+  return [value, store.setValue] as const;
+}

package/src/core/hooks/use-telemetry-fallback.ts

@@ -3,6 +3,7 @@
 export const useTelemetryFallback = () => ({
   send: () => {},
   sendPageViewedMessage: () => {},
+  sendPageActionsButtonClickedMessage: () => {},
   sendErrorMessage: () => {},
   sendClientErrorMessage: () => {},
   sendBreadcrumbClickedMessage: () => {},
@@ -63,6 +64,7 @@ export const useTelemetryFallback = () => ({
   sendAsyncapiDocsMessageClickedMessage: () => {},
   sendAsyncapiDocsServerModalOpenedMessage: () => {},
   sendAsyncapiDocsDownloadDefinitionClickedMessage: () => {},
+  sendAsyncapiDocsReferencedInClickedMessage: () => {},
   sendGraphqlDocsViewedMessage: () => {},
   sendGraphqlDocsPerformanceMetricsMessage: () => {},
   sendGraphqlDocsReferencedInLinkClickedMessage: () => {},