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

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/common.ts

@@ -1 +1,5 @@
+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];

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';

package/src/core/utils/load-and-navigate.ts

@@ -1,5 +1,6 @@
 import type { NavigateFunction, NavigateOptions } from 'react-router-dom';
 
+import { getNavbarElement } from './get-navbar-element';
 import { withLoadProgress } from './with-load-progress';
 
 export type HistoryOrigin = 'pm' | 'browser';
@@ -45,7 +46,11 @@ export async function loadAndNavigate({
     if (hash) {
       const el = document.getElementById(hash.slice(1));
       if (el) {
-        el.scrollIntoView();
+        const navbar = getNavbarElement();
+        const navbarHeight = navbar?.offsetHeight ?? 0;
+        const elementTop = el.getBoundingClientRect().top + window.scrollY;
+        const scrollPosition = elementTop - navbarHeight;
+        window.scrollTo({ top: scrollPosition, behavior: 'smooth' });
       }
     } else {
       window.scrollTo(0, 0);

package/src/core/utils/transform-revisions-to-version-history.ts

@@ -0,0 +1,163 @@
+import type {
+  BffCatalogEntityRevision,
+  CatalogEntityRevision,
+  CatalogEntityVersionHistoryGroup,
+} from '@redocly/theme/core/types';
+
+import { VERSION_NOT_SPECIFIED } from '@redocly/theme/core/constants';
+
+import { toLocalizedShortDate, toLocalizedShortDateTime } from './date';
+
+function compareVersionsDescending(versionA: string, versionB: string): number {
+  return versionB.localeCompare(versionA, undefined, { numeric: true });
+}
+
+function extractGroupComparisonData(group: CatalogEntityVersionHistoryGroup): {
+  version: string;
+  isNotSpecified: boolean;
+  time: number;
+  hasCurrent: boolean;
+} {
+  const version = group.version;
+  const isNotSpecified = version === VERSION_NOT_SPECIFIED;
+
+  // Get version dates (oldest revision date for each group - the version's creation date)
+  // This ensures versions stay in their original order even when new revisions are added
+  const date =
+    group.singleRevisionDate ||
+    (group.revisions && group.revisions.length > 0
+      ? group.revisions[group.revisions.length - 1]?.revisionDate
+      : undefined) ||
+    '';
+  const time = date ? new Date(date).getTime() : 0;
+
+  const hasCurrent = group.hasCurrentRevisionFromBackend ?? false;
+
+  return { version, isNotSpecified, time, hasCurrent };
+}
+
+function compareVersionGroupsDescending(
+  groupA: CatalogEntityVersionHistoryGroup,
+  groupB: CatalogEntityVersionHistoryGroup,
+): number {
+  const {
+    version: versionA,
+    isNotSpecified: isNotSpecifiedA,
+    time: timeA,
+    hasCurrent: hasCurrentA,
+  } = extractGroupComparisonData(groupA);
+  const {
+    version: versionB,
+    isNotSpecified: isNotSpecifiedB,
+    time: timeB,
+    hasCurrent: hasCurrentB,
+  } = extractGroupComparisonData(groupB);
+
+  // First, compare by version date (oldest first, so most recent versions come first)
+  const dateComparison = timeB - timeA;
+  if (dateComparison !== 0) {
+    return dateComparison;
+  }
+
+  // If dates are equal, prioritize the one with isCurrent from backend
+  if (hasCurrentA !== hasCurrentB) {
+    return hasCurrentB ? 1 : -1; // hasCurrentB comes first if true
+  }
+
+  // If both have same isCurrent status, compare by version
+  // If both are unknown or both are real versions, compare by version
+  if (isNotSpecifiedA === isNotSpecifiedB) {
+    return compareVersionsDescending(versionA, versionB);
+  }
+
+  // If one is unknown and one is a real version, unknown comes last
+  return isNotSpecifiedA ? 1 : -1;
+}
+
+export type TransformRevisionsToVersionHistoryParams = {
+  revisions: BffCatalogEntityRevision[];
+  currentRevisionDate?: string;
+  currentVersion?: string | null;
+  locale?: string;
+};
+
+export function transformRevisionsToVersionHistory({
+  revisions,
+  currentRevisionDate,
+  currentVersion,
+  locale = typeof navigator !== 'undefined' ? navigator.language : 'en-US',
+}: TransformRevisionsToVersionHistoryParams): CatalogEntityVersionHistoryGroup[] {
+  const normalizedCurrentVersion = currentVersion === null ? VERSION_NOT_SPECIFIED : currentVersion;
+
+  const versionMap = new Map<string, BffCatalogEntityRevision[]>();
+  revisions.forEach((revision) => {
+    const version = revision.version || VERSION_NOT_SPECIFIED;
+    const versionRevisions = versionMap.get(version) || [];
+    versionRevisions.push(revision);
+    if (!versionMap.has(version)) {
+      versionMap.set(version, versionRevisions);
+    }
+  });
+
+  const versionGroups = Array.from(versionMap.entries()).map(([version, versionRevisions]) => {
+    const sortedRevisions = [...versionRevisions].sort((a, b) => {
+      const dateA = a.revision ? new Date(a.revision).getTime() : 0;
+      const dateB = b.revision ? new Date(b.revision).getTime() : 0;
+      return dateB - dateA;
+    });
+
+    const latestRevision = sortedRevisions[0];
+
+    const versionMatches =
+      normalizedCurrentVersion === undefined || normalizedCurrentVersion === version;
+
+    let isCurrent: boolean;
+    if (currentRevisionDate !== undefined) {
+      // Check if revision matches AND version matches
+      const revisionMatches = sortedRevisions.some((rev) => rev.revision === currentRevisionDate);
+      isCurrent = revisionMatches && versionMatches;
+    } else {
+      // When no revision is specified, use isCurrent flag from the latest revision
+      // but only if version also matches (or no version filter is applied)
+      isCurrent = (latestRevision?.isCurrent ?? false) && versionMatches;
+    }
+
+    // Check if any revision in this version group is the default version
+    const isDefaultVersion = sortedRevisions.some((rev) => rev.isDefaultVersion === true);
+
+    const revisions =
+      sortedRevisions.length > 1
+        ? sortedRevisions.map((rev, index): CatalogEntityRevision => {
+            const revisionMatches = currentRevisionDate
+              ? rev.revision === currentRevisionDate
+              : false;
+            const isActiveRevision = revisionMatches && versionMatches;
+            const isCurrentByDefault =
+              !currentRevisionDate &&
+              normalizedCurrentVersion === undefined &&
+              index === 0 &&
+              isCurrent;
+            return {
+              name: `r.${sortedRevisions.length - index}`,
+              date: toLocalizedShortDateTime(rev.revision, locale),
+              revisionDate: rev.revision,
+              isActive: isActiveRevision || isCurrentByDefault,
+              isCurrent: rev.isCurrent ?? false,
+            };
+          })
+        : undefined;
+
+    return {
+      version,
+      date: toLocalizedShortDate(latestRevision?.revision || null, locale),
+      isCurrent,
+      isExpanded: isCurrent,
+      hasCurrentRevisionFromBackend: latestRevision?.isCurrent ?? false,
+      isDefaultVersion,
+      revisions,
+      singleRevisionDate: sortedRevisions.length === 1 ? sortedRevisions[0]?.revision : undefined,
+    };
+  });
+
+  return versionGroups.sort(compareVersionGroupsDescending);
+}

package/src/icons/NavaidMilitaryIcon/NavaidMilitaryIcon.tsx

@@ -0,0 +1,43 @@
+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) => {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="16"
+      height="16"
+      viewBox="0 0 16 16"
+      fill="none"
+      {...props}
+    >
+      <path
+        d="M8 15C6.61553 15 5.26216 14.5895 4.11101 13.8203C2.95987 13.0511 2.06266 11.9579 1.53285 10.6788C1.00303 9.3997 0.86441 7.99224 1.13451 6.63437C1.4046 5.2765 2.07129 4.02922 3.05026 3.05026C4.02922 2.07129 5.2765 1.4046 6.63437 1.13451C7.99224 0.86441 9.3997 1.00303 10.6788 1.53285C11.9579 2.06266 13.0511 2.95987 13.8203 4.11101C14.5895 5.26216 15 6.61553 15 8C14.9979 9.85588 14.2597 11.6351 12.9474 12.9474C11.6351 14.2597 9.85588 14.9979 8 15ZM8 2C6.81332 2 5.65328 2.3519 4.66658 3.01119C3.67989 3.67047 2.91085 4.60755 2.45673 5.7039C2.0026 6.80026 1.88378 8.00666 2.11529 9.17054C2.3468 10.3344 2.91825 11.4035 3.75736 12.2426C4.59648 13.0818 5.66558 13.6532 6.82946 13.8847C7.99335 14.1162 9.19975 13.9974 10.2961 13.5433C11.3925 13.0892 12.3295 12.3201 12.9888 11.3334C13.6481 10.3467 14 9.18669 14 8C13.9982 6.40926 13.3655 4.88419 12.2406 3.75936C11.1158 2.63454 9.59075 2.00182 8 2Z"
+        fill="#1A1C21"
+      />
+      <path
+        d="M8 12C7.20888 12 6.43552 11.7654 5.77772 11.3259C5.11993 10.8864 4.60724 10.2616 4.30449 9.53074C4.00173 8.79983 3.92252 7.99557 4.07686 7.21964C4.2312 6.44372 4.61217 5.73099 5.17158 5.17158C5.73099 4.61217 6.44372 4.2312 7.21964 4.07686C7.99557 3.92252 8.79983 4.00173 9.53074 4.30449C10.2616 4.60724 10.8864 5.11993 11.3259 5.77772C11.7654 6.43552 12 7.20888 12 8C11.9988 9.0605 11.577 10.0772 10.8271 10.8271C10.0772 11.577 9.0605 11.9988 8 12ZM8 5C7.40666 5 6.82664 5.17595 6.33329 5.50559C5.83994 5.83524 5.45543 6.30377 5.22836 6.85195C5.0013 7.40013 4.94189 8.00333 5.05765 8.58527C5.1734 9.16722 5.45913 9.70177 5.87868 10.1213C6.29824 10.5409 6.83279 10.8266 7.41473 10.9424C7.99668 11.0581 8.59988 10.9987 9.14805 10.7716C9.69623 10.5446 10.1648 10.1601 10.4944 9.66671C10.8241 9.17337 11 8.59335 11 8C10.9991 7.20463 10.6828 6.44208 10.1203 5.87966C9.55793 5.31725 8.79538 5.00089 8 5Z"
+        fill="#1A1C21"
+      />
+      <path
+        d="M8 9C8.55229 9 9 8.55229 9 8C9 7.44772 8.55229 7 8 7C7.44772 7 7 7.44772 7 8C7 8.55229 7.44772 9 8 9Z"
+        fill="#1A1C21"
+      />
+    </svg>
+  );
+};
+
+export const NavaidMilitaryIcon = styled(Icon).attrs(() => ({
+  'data-component-name': 'icons/NavaidMilitaryIcon/NavaidMilitaryIcon',
+}))<IconProps>`
+  path {
+    fill: ${({ color }) => getCssColorVariable(color)};
+  }
+
+  height: ${({ size }) => size || '16px'};
+  width: ${({ size }) => size || '16px'};
+`;

package/src/index.ts

@@ -136,6 +136,8 @@ export * from '@redocly/theme/components/Catalog/CatalogSelector';
 export * from '@redocly/theme/components/Catalog/CatalogSortButton';
 export * from '@redocly/theme/components/Catalog/CatalogTagsWithTooltip';
 export * from '@redocly/theme/components/Catalog/CatalogViewModeToggle';
+export * from '@redocly/theme/components/Catalog/CatalogEntity/CatalogEntityHistory/CatalogEntityHistoryButton';
+export * from '@redocly/theme/components/Catalog/CatalogEntity/CatalogEntityHistory/CatalogEntityHistorySidebar';
 export * from '@redocly/theme/components/Catalog/CatalogEntity/CatalogEntityRelations/CatalogEntityRelations';
 export * from '@redocly/theme/components/Catalog/CatalogEntity/CatalogEntityRelations/CatalogEntityTeamRelations';
 export * from '@redocly/theme/components/Catalog/CatalogEntity/CatalogEntityRelations/CatalogEntityDefaultRelations';