@redocly/theme 0.61.0-next.2 → 0.61.0

package/src/components/Catalog/CatalogTableView/CatalogTableViewRow.tsx

@@ -19,6 +19,8 @@ export type BaseEntity = {
   type: string;
   title: string;
   summary?: string | null;
+  revision?: string | null;
+  version?: string | null;
 };
 
 export type CatalogTableViewRowProps<T extends BaseEntity> = {
@@ -95,14 +97,17 @@ export const CatalogTableViewRow = <T extends BaseEntity>({
   const { getEntityDetailsLink } = useCatalogEntityDetails({
     catalogConfig,
     entitiesCatalogConfig,
+    revision: entity.revision,
+    version: entity.version,
   });
+  const link = getEntityDetailsLink({ key: entity.key, type: entity.type });
 
   return (
     <TableRow
       key={entity.id}
       $columnsWidths={columns.map((column) => column.width || '1fr')}
       $columnsMinWidths={columns.map((column) => column.minWidth || 'auto')}
-      to={getEntityDetailsLink(entity) + '?search='}
+      to={link}
       onClick={() => onRowClick(entity)}
       style={{ color: 'var(--catalog-page-wrapper-text-color)' }}
       data-component-name="Catalog/CatalogTableView/CatalogTableViewRow"

package/src/components/Catalog/variables.ts

@@ -235,6 +235,13 @@ export const catalog = css`
   --catalog-metadata-column-half-gap: var(--spacing-sm);
   --catalog-metadata-heading-size: var(--font-size-md);
 
+  /**
+    * @tokens Catalog show more button
+    */
+  --catalog-show-more-button-gap: 0.5rem;
+  --catalog-show-more-button-color: var(--text-color-primary);
+  --catalog-show-more-button-color-hover: var(--text-color-secondary);
+
   /**
     * @tokens Catalog arrow circle
     */
@@ -427,5 +434,110 @@ export const catalog = css`
   --catalog-entity-relations-edge-label-font-size: 12px;
   --catalog-entity-relations-edge-label-line-height: 1.2;
   // @tokens End
+
+  /**
+    * @tokens Catalog history button
+    */
+  --catalog-history-separator-border-color: var(--border-color-secondary);
+  --catalog-history-separator-margin-bottom: var(--spacing-sm);
+  --catalog-history-item-padding: var(--spacing-xxs);
+  --catalog-history-item-margin-bottom: calc(var(--spacing-xxs) * -1);
+  --catalog-history-item-gap: var(--spacing-xxs);
+  --catalog-history-item-border-radius: var(--menu-item-label-border-radius);
+  --catalog-history-item-bg-color-hover: var(--menu-item-bg-color-hover);
+  --catalog-history-icon-size: 16px;
+  --catalog-history-text-font-family: var(--font-family-base);
+  --catalog-history-text-font-size: var(--font-size-base);
+  --catalog-history-text-font-weight: var(--font-weight-regular);
+  --catalog-history-text-line-height: var(--line-height-base);
+  --catalog-history-text-color: var(--text-color-primary);
+  --catalog-history-pill-gap: var(--spacing-xxs);
+  --catalog-history-pill-padding-vertical: 1px;
+  --catalog-history-pill-padding-horizontal: var(--spacing-xs);
+  --catalog-history-pill-border-color: var(--border-color-primary);
+  --catalog-history-pill-border-radius: 12px;
+  --catalog-history-pill-icon-size: 14px;
+  --catalog-history-pill-icon-color: var(--color-green-8);
+  --catalog-history-pill-font-family: var(--font-family-base);
+  --catalog-history-pill-font-size: var(--font-size-base);
+  --catalog-history-pill-line-height: var(--line-height-base);
+  --catalog-history-pill-text-color: var(--text-color-primary);
+  // @tokens End
+
+  /**
+    * @tokens Catalog history sidebar
+    */
+  --catalog-history-sidebar-width: 320px;
+  --catalog-history-sidebar-bg-color: var(--sidebar-bg-color);
+  --catalog-history-sidebar-border-color: var(--border-color-secondary);
+
+  --catalog-history-sidebar-header-padding: var(--spacing-base) var(--spacing-sm) var(--spacing-base);
+  --catalog-history-sidebar-header-font-family: var(--font-family-base);
+  --catalog-history-sidebar-header-font-size: var(--font-size-base);
+  --catalog-history-sidebar-header-font-weight: var(--font-weight-semibold);
+  --catalog-history-sidebar-header-line-height: var(--line-height-base);
+  --catalog-history-sidebar-header-letter-spacing: 0;
+  --catalog-history-sidebar-header-color: var(--text-color-primary);
+
+  --catalog-history-sidebar-close-button-size: 32px;
+  --catalog-history-sidebar-close-button-border-radius: var(--border-radius-md);
+  --catalog-history-sidebar-close-button-bg-color-hover: var(--color-hover-base);
+  --catalog-history-sidebar-close-icon-color: var(--text-color-primary);
+
+  --catalog-history-sidebar-content-padding: 0 var(--spacing-sm);
+  --catalog-history-sidebar-content-margin-top: calc(var(--spacing-xxs) * -1);
+
+  --catalog-history-sidebar-version-header-padding: var(--spacing-xs) var(--spacing-xxs);
+  --catalog-history-sidebar-version-header-border-radius: var(--border-radius-md);
+  --catalog-history-sidebar-version-header-bg-color-hover: var(--color-hover-base);
+
+  --catalog-history-sidebar-version-icon-size: 32px;
+  --catalog-history-sidebar-version-icon-color: var(--text-color-secondary);
+  --catalog-history-sidebar-version-icon-color-current: var(--color-static-white);
+  --catalog-history-sidebar-version-icon-margin-right: var(--spacing-xs);
+  --catalog-history-sidebar-chevron-icon-color: var(--text-color-secondary);
+  --catalog-history-sidebar-version-info-gap: 2px;
+
+  --catalog-history-sidebar-version-title-font-family: var(--font-family-base);
+  --catalog-history-sidebar-version-title-font-size: var(--font-size-base);
+  --catalog-history-sidebar-version-title-font-weight: var(--font-weight-medium);
+  --catalog-history-sidebar-version-title-line-height: var(--line-height-base);
+  --catalog-history-sidebar-version-title-color: var(--color-warm-grey-7);
+
+  --catalog-history-sidebar-version-date-font-family: var(--font-family-base);
+  --catalog-history-sidebar-version-date-font-size: var(--font-size-sm);
+  --catalog-history-sidebar-version-date-font-weight: var(--font-weight-regular);
+  --catalog-history-sidebar-version-date-line-height: var(--line-height-sm);
+  --catalog-history-sidebar-version-date-color: var(--color-warm-grey-7);
+
+  --catalog-history-sidebar-revisions-padding-left: 40px;
+
+  --catalog-history-sidebar-revision-item-padding: var(--spacing-xs) var(--spacing-sm);
+  --catalog-history-sidebar-revision-item-border-radius: var(--border-radius-md);
+  --catalog-history-sidebar-revision-item-bg-color-hover: var(--bg-color-hover);
+
+  --catalog-history-sidebar-revision-name-font-family: var(--font-family-base);
+  --catalog-history-sidebar-revision-name-font-size: var(--font-size-base);
+  --catalog-history-sidebar-revision-name-font-weight: var(--font-weight-regular);
+  --catalog-history-sidebar-revision-name-line-height: var(--line-height-base);
+  --catalog-history-sidebar-revision-name-color: var(--text-color-primary);
+
+  --catalog-history-sidebar-revision-date-font-family: var(--font-family-base);
+  --catalog-history-sidebar-revision-date-font-size: var(--font-size-sm);
+  --catalog-history-sidebar-revision-date-font-weight: var(--font-weight-regular);
+  --catalog-history-sidebar-revision-date-line-height: var(--line-height-sm);
+  --catalog-history-sidebar-revision-date-color: var(--color-warm-grey-7);
+
+  --catalog-history-sidebar-revision-line-color: var(--border-color-secondary);
+  --catalog-history-sidebar-revision-item-bg-color-active: var(--bg-color-active);
+
+  --catalog-history-sidebar-revisions-limit-message-color: var(--color-warm-grey-6);
+
+  /**
+   * @tokens Catalog history tag border radius
+   */
+  --catalog-history-sidebar-version-tag-border-radius: var(--border-radius-xl);
+  --catalog-history-sidebar-revision-tag-border-radius: var(--border-radius-xl);
+  // @tokens End
 `;
 /* eslint-enable theme/no-raw-colors-in-styles */

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/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/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/use-color-switcher.ts

@@ -1,10 +1,11 @@
 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';
-import { isBrowser } from '../utils/js-utils';
 
 const COLOR_MODE_KEY = 'colorSchema';
 const colorModeStore = createStore<string>({
@@ -21,15 +22,17 @@ export const useColorSwitcher = () => {
     () => themeColorMode?.modes || [DEFAULT_COLOR_MODES.LIGHT, DEFAULT_COLOR_MODES.DARK],
     [themeColorMode],
   );
-  const documentMode = useMemo(() => {
-    if (!isBrowser()) return;
-    return Array.from(document.documentElement.classList).find((c) => modes.includes(c));
-  }, [modes]);
-
-  const [activeColorMode, setActiveColorMode] = useStore<string>(
-    colorModeStore,
-    documentMode ?? modes[0] ?? DEFAULT_COLOR_MODES.LIGHT,
-  );
+
+  const defaultMode = modes[0] || DEFAULT_COLOR_MODES.LIGHT;
+
+  const [activeColorMode, setActiveColorMode] = useStore<string>(colorModeStore, defaultMode);
+
+  useMount(() => {
+    const activeMode = Array.from(document.documentElement.classList).find((c) =>
+      modes.includes(c),
+    );
+    setActiveColorMode(activeMode || defaultMode);
+  });
 
   const switchColorMode = (mode?: string): void => {
     if (mode && !modes.includes(mode)) {

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-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: () => {},

package/src/core/types/catalog.ts

@@ -40,16 +40,6 @@ export type UseCatalogResponse = {
   collapsedSidebar: boolean;
 };
 
-export type UseCatalogFetchCatalogEntities = (
-  params: CatalogApiParams,
-  initialData?: BffCatalogEntityList,
-) => CatalogApiResults<BffCatalogEntity>;
-
-export type UseCatalogFetchCatalogEntitiesRelations = (
-  params: CatalogApiParams & { entityKey: string },
-  initialData?: BffCatalogRelatedEntityList,
-) => CatalogApiResults<BffCatalogRelatedEntity>;
-
 export type UseCatalogSortResponse = {
   sortOption: SortOption | null;
   setSortOption: (option: SortOption | null) => void;
@@ -128,6 +118,7 @@ export type CatalogApiParams = {
   filter?: string;
   sort?: string;
   search?: string;
+  entityVersion?: string | null;
 };
 
 export type UseCatalogEntitiesProps = {
@@ -170,6 +161,7 @@ export type BffCatalogRelatedEntity = {
   /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
   metadata?: Record<string, any>;
   version?: string | null;
+  revision?: string | null;
   readonly createdAt: string | null;
   readonly updatedAt: string | null;
 };
@@ -207,6 +199,7 @@ export type BffCatalogEntity = {
   readonly revision: string;
   readonly isCurrent?: boolean | null;
   readonly isDefaultVersion?: boolean | null;
+  readonly isDeleted?: boolean | null;
   readonly createdAt: string;
   readonly updatedAt: string;
 };
@@ -229,6 +222,41 @@ export type Page = {
   total: number;
 };
 
+export type BffCatalogEntityRevision = {
+  readonly version: string | null;
+  readonly revision: string | null;
+  readonly isCurrent: boolean | null;
+  readonly isDefaultVersion: boolean | null;
+  readonly createdAt: string | null;
+  readonly updatedAt: string | null;
+};
+
+export type BffCatalogEntityRevisionList = BffCatalogList<BffCatalogEntityRevision>;
+
 export type EntityRelationType = (typeof ENTITY_RELATION_TYPES)[number];
 
 export type ListType = 'default' | 'team' | 'api-operation' | 'data-schema';
+
+export type CatalogEntityRevision = {
+  name: string;
+  date: string;
+  revisionDate: string | null;
+  isActive?: boolean;
+  isCurrent?: boolean;
+};
+
+export type CatalogEntityVersionHistoryGroup = {
+  version: string;
+  date: string;
+  isCurrent?: boolean;
+  isExpanded?: boolean;
+  revisions?: CatalogEntityRevision[];
+  singleRevisionDate?: string | null;
+  hasCurrentRevisionFromBackend?: boolean;
+  isDefaultVersion?: boolean;
+};
+
+export type SidebarConnectedEntity = {
+  key: string;
+  version?: string;
+};

package/src/core/types/hooks.ts

@@ -9,6 +9,7 @@ import type {
 import type { ShikiTransformer } from '@shikijs/types';
 import type { Callback, TFunction as TFunc } from 'i18next';
 import type { To, Location, NavigateFunction } from 'react-router-dom';
+import type { UseQueryResult } from '@tanstack/react-query';
 import type { CatalogConfig, ProductUiConfig } from '@redocly/theme/config';
 import type {
   UseCatalogResponse,
@@ -16,8 +17,8 @@ import type {
   UseCatalogSortResponse,
   UseCatalogSearchResponse,
   UseCatalogProps,
-  UseCatalogFetchCatalogEntities,
-  UseCatalogFetchCatalogEntitiesRelations,
+  CatalogApiParams,
+  CatalogApiResults,
 } from './catalog';
 import type { UserMenuData } from './user-menu';
 import type { ItemState } from './sidebar';
@@ -33,6 +34,14 @@ import type { TFunction } from './l10n';
 import type { BreadcrumbItem } from './breadcrumb';
 import type { DrilldownMenuItemDetails } from './sidebar';
 
+import {
+  BffCatalogEntity,
+  BffCatalogEntityList,
+  BffCatalogRelatedEntity,
+  BffCatalogRelatedEntityList,
+  BffCatalogEntityRevision,
+  BffCatalogEntityRevisionList,
+} from './catalog';
 import { AiSearchError } from '../constants/search';
 
 export type ThemeHooks = {
@@ -147,8 +156,18 @@ export type ThemeHooks = {
   useCatalog: (props?: UseCatalogProps) => UseCatalogResponse;
   useCatalogSort: () => UseCatalogSortResponse;
   useCatalogSearch: () => UseCatalogSearchResponse;
-  useFetchCatalogEntities: UseCatalogFetchCatalogEntities;
-  useFetchCatalogEntitiesRelations: UseCatalogFetchCatalogEntitiesRelations;
+  useFetchCatalogEntities: (
+    params: CatalogApiParams,
+    initialData?: BffCatalogEntityList,
+  ) => CatalogApiResults<BffCatalogEntity>;
+  useFetchCatalogEntitiesRelations: (
+    params: CatalogApiParams & { entityKey: string },
+    initialData?: BffCatalogRelatedEntityList,
+  ) => CatalogApiResults<BffCatalogRelatedEntity>;
+  useFetchCatalogEntityRevisions: (params: { entityKey: string; version?: string | null }) => {
+    query: UseQueryResult<BffCatalogEntityRevisionList, Error>;
+    items: BffCatalogEntityRevision[];
+  };
   useCatalogClassic: (config: CatalogConfig) => FilteredCatalog;
   useTelemetry: () => Omit<
     AsyncApiRealmUI.Telemetry,

package/src/core/types/l10n.ts

@@ -170,6 +170,16 @@ export type TranslationKey =
   | 'catalog.links.label'
   | 'catalog.metadata.domains'
   | 'catalog.metadata.owners'
+  | 'catalog.history.button.label'
+  | 'catalog.history.sidebar.title'
+  | 'catalog.history.sidebar.close'
+  | 'catalog.history.version.label'
+  | 'catalog.history.version.notSpecified'
+  | 'catalog.history.version.default'
+  | 'catalog.history.revisions.limitMessage'
+  | 'catalog.history.revision.current'
+  | 'catalog.history.revisions.showLess'
+  | 'catalog.history.revisions.showMore'
   | 'sidebar.menu.backLabel'
   | 'sidebar.menu.backToLabel'
   | 'sidebar.actions.show'

package/src/core/utils/build-revision-url.ts

@@ -0,0 +1,16 @@
+export function buildRevisionUrl(
+  basePath: string,
+  revisionDate: string | null | undefined,
+  version?: string | null,
+): string | undefined {
+  if (!revisionDate) {
+    return undefined;
+  }
+
+  const params = new URLSearchParams();
+  params.set('revision', revisionDate);
+  if (version) {
+    params.set('version', version);
+  }
+  return `${basePath}?${params.toString()}`;
+}

package/src/core/utils/date.ts

@@ -0,0 +1,33 @@
+/**
+ * Formats a date string to localized short date format (e.g., "Dec 12, 2025")
+ * @param dateString - ISO date string or null
+ * @param locale - Locale string (e.g., "en-US")
+ * @returns Formatted date string or empty string if dateString is null
+ */
+export function toLocalizedShortDate(dateString: string | null, locale: string): string {
+  if (!dateString) return '';
+  const date = new Date(dateString);
+  return date.toLocaleDateString(locale, {
+    month: 'short',
+    day: 'numeric',
+    year: 'numeric',
+  });
+}
+
+/**
+ * Formats a date string to localized short date-time format (e.g., "Dec 12, 3:45 PM")
+ * @param dateString - ISO date string or null
+ * @param locale - Locale string (e.g., "en-US")
+ * @returns Formatted date-time string or empty string if dateString is null
+ */
+export function toLocalizedShortDateTime(dateString: string | null, locale: string): string {
+  if (!dateString) return '';
+  const date = new Date(dateString);
+  return date.toLocaleString(locale, {
+    month: 'short',
+    day: 'numeric',
+    hour: 'numeric',
+    minute: '2-digit',
+    hour12: true,
+  });
+}

package/src/core/utils/index.ts

@@ -41,3 +41,5 @@ export * from './Dynamic';
 export * from './tabs';
 export * from './get-operation-color';
 export * from './frontmatter-translate';
+export * from './transform-revisions-to-version-history';
+export * from './build-revision-url';