@redocly/theme 0.69.0-next.9 → 0.70.0-next.0

package/src/components/Catalog/CatalogEntities.tsx

@@ -1,8 +1,9 @@
-import React, { JSX, useEffect } from 'react';
+import type { JSX } from 'react';
+import React, { useEffect } from 'react';
 
 import type { CatalogEntityConfig } from '@redocly/config';
 
-import { BffCatalogEntity, BffCatalogEntityList } from '@redocly/theme/core/types';
+import type { BffCatalogEntity, BffCatalogEntityList } from '@redocly/theme/core/types';
 import { useThemeHooks, useCatalogEntities } from '@redocly/theme/core/hooks';
 import { getBaseDataAttributes } from '@redocly/theme/core/utils';
 import { ArrowDownIcon } from '@redocly/theme/icons/ArrowDownIcon/ArrowDownIcon';
@@ -88,6 +89,7 @@ export function CatalogEntities(props: CatalogEntitiesProps): JSX.Element {
     (query.isPlaceholderData && entities && entities.length >= LOAD_MORE_THRESHOLD);
 
   useEffect(() => {
+    // oxlint-disable-next-line react-you-might-not-need-an-effect/no-pass-data-to-parent -- the entities query lives in this ejectable component; the fetched total is mirrored up so the portal page header can show the count
     setEntitiesCounter(total || 0);
   }, [total, setEntitiesCounter]);
 

package/src/components/Catalog/CatalogEntitiesEmptyState.tsx

@@ -1,4 +1,5 @@
-import React, { JSX } from 'react';
+import type { JSX } from 'react';
+import React from 'react';
 import styled from 'styled-components';
 
 import type { ListType } from '@redocly/theme/core/types';

package/src/components/Catalog/CatalogEntity/CatalogEntity.tsx

@@ -3,8 +3,12 @@ import styled from 'styled-components';
 import { Route, Routes, useSearchParams } from 'react-router';
 
 import type { CatalogEntityConfig } from '@redocly/config';
-import type { BffCatalogEntity, BffCatalogRelatedEntity } from '@redocly/theme/core/types';
-import type { CatalogEntityPageProps, CatalogEntityProps } from '@redocly/theme/core/types';
+import type {
+  BffCatalogEntity,
+  BffCatalogRelatedEntity,
+  CatalogEntityPageProps,
+  CatalogEntityProps,
+} from '@redocly/theme/core/types';
 
 import { breakpoints } from '@redocly/theme/core/utils';
 import { CatalogPageDescription } from '@redocly/theme/components/Catalog/CatalogPageDescription';

package/src/components/Catalog/CatalogEntity/CatalogEntityGraph/CatalogEntityRelationsGraph.tsx

@@ -1,10 +1,9 @@
-import React, { JSX, useMemo } from 'react';
-import { Background, ColorMode, Controls, ReactFlow } from '@xyflow/react';
+import React, { type JSX, useMemo } from 'react';
+import { type ColorMode, Background, Controls, ReactFlow } from '@xyflow/react';
 import styled from 'styled-components';
 
-import { BffCatalogEntity } from '@redocly/theme/core/types';
-import { useColorSwitcher, useThemeHooks } from '@redocly/theme/core/hooks';
-import { useGraph } from '@redocly/theme/core/hooks';
+import type { BffCatalogEntity } from '@redocly/theme/core/types';
+import { useColorSwitcher, useThemeHooks, useGraph } from '@redocly/theme/core/hooks';
 import { CatalogEntityRelationsNode } from '@redocly/theme/components/Catalog/CatalogEntity/CatalogEntityGraph/CatalogEntityRelationsNode';
 import { CatalogEntityRelationsEdge } from '@redocly/theme/components/Catalog/CatalogEntity/CatalogEntityGraph/CatalogEntityRelationsEdge';
 import { xyflow } from '@redocly/theme/core/styles';

package/src/components/Catalog/CatalogEntity/CatalogEntityHistory/CatalogEntityHistoryButton.tsx

@@ -2,49 +2,70 @@ import React, { useCallback, useEffect, useState } from 'react';
 import styled from 'styled-components';
 
 import { RecentlyViewedIcon } from '@redocly/theme/icons/RecentlyViewedIcon/RecentlyViewedIcon';
-import { CheckmarkOutlineIcon } from '@redocly/theme/icons/CheckmarkOutlineIcon/CheckmarkOutlineIcon';
-import { useThemeHooks } from '@redocly/theme/core/hooks';
+import { RadioCheckButtonIcon } from '@redocly/theme/icons/RadioCheckButtonIcon/RadioCheckButtonIcon';
+import { useThemeHooks, useIsTruncated } from '@redocly/theme/core/hooks';
 import { VERSION_NOT_SPECIFIED } from '@redocly/theme/core/constants';
 import { Tooltip } from '@redocly/theme/components/Tooltip/Tooltip';
-import { useIsTruncated } from '@redocly/theme/core/hooks';
 
 export type CatalogHistoryButtonProps = {
   version: string | null;
+  /** Marks `version` as the group's default, shown as a "(latest)" suffix on the pill. */
+  isDefaultVersion?: boolean;
   className?: string;
 };
 
-export function CatalogEntityHistoryButton({
-  version,
-  className,
-}: CatalogHistoryButtonProps): React.ReactElement {
-  const [label, setLabel] = useState(version === VERSION_NOT_SPECIFIED ? null : version);
+/**
+ * The pill label: the page's version, updated by the overlay's close event
+ * (which appends the revision while an old revision is open), with a
+ * "(latest)" suffix on the plain default-version label.
+ */
+function useVersionPillLabel(version: string | null, isDefaultVersion?: boolean): string | null {
+  const pageLabel = version === VERSION_NOT_SPECIFIED ? null : version;
+  const [label, setLabel] = useState(pageLabel);
+  // Keep the pill in sync when navigation changes the page version.
+  const [lastPageLabel, setLastPageLabel] = useState(pageLabel);
+  if (lastPageLabel !== pageLabel) {
+    setLastPageLabel(pageLabel);
+    setLabel(pageLabel);
+  }
   const { useTranslate } = useThemeHooks();
   const { translate } = useTranslate();
-  const [labelRef, isLabelTruncated] = useIsTruncated<HTMLSpanElement>(label);
+  const latestWord = translate('catalog.history.version.latest', 'latest');
 
   const handleClose = useCallback(
     (e: CustomEvent): void => {
-      setLabel(
-        e.detail.version === VERSION_NOT_SPECIFIED
-          ? e.detail.revision || 'r.1'
-          : `${e.detail.version || version}, ${e.detail.revision || 'r.1'}`,
-      );
+      const closedVersion =
+        e.detail.version === VERSION_NOT_SPECIFIED ? null : e.detail.version || version;
+      setLabel([closedVersion, e.detail.revision].filter(Boolean).join(', ') || null);
     },
     [version],
   );
 
   useEffect(() => {
-    window.addEventListener('portal:sidebar:close-version-history', (e) =>
-      handleClose(e as CustomEvent),
-    );
-
-    return () => {
-      window.removeEventListener('portal:sidebar:close-version-history', (e) =>
-        handleClose(e as CustomEvent),
-      );
-    };
+    const onClose = (e: Event) => handleClose(e as CustomEvent);
+    window.addEventListener('portal:sidebar:close-version-history', onClose);
+    return () => window.removeEventListener('portal:sidebar:close-version-history', onClose);
   }, [handleClose]);
 
+  // A label with a revision, or a version named "latest", stays as-is.
+  return label !== null &&
+    label === pageLabel &&
+    isDefaultVersion &&
+    label.toLowerCase() !== latestWord.toLowerCase()
+    ? `${label} (${latestWord})`
+    : label;
+}
+
+export function CatalogEntityHistoryButton({
+  version,
+  isDefaultVersion,
+  className,
+}: CatalogHistoryButtonProps): React.ReactElement {
+  const { useTranslate } = useThemeHooks();
+  const { translate } = useTranslate();
+  const displayLabel = useVersionPillLabel(version, isDefaultVersion);
+  const [labelRef, isLabelTruncated] = useIsTruncated<HTMLSpanElement>(displayLabel);
+
   const handleClick = (): void => {
     window.dispatchEvent(new CustomEvent('portal:sidebar:open-version-history'));
   };
@@ -54,14 +75,13 @@ export function CatalogEntityHistoryButton({
       className={className}
       data-component-name="Catalog/CatalogHistoryButton"
     >
-      <Separator />
       <HistoryItem onClick={handleClick}>
         <HistoryIcon />
         <HistoryContent>
-          <HistoryText>{translate('catalog.history.button.label', 'Version history')}</HistoryText>
-          {label && (
+          <HistoryText>{translate('catalog.history.button.label', 'Version')}</HistoryText>
+          {displayLabel && (
             <Tooltip
-              tip={label}
+              tip={displayLabel}
               placement="bottom"
               arrowPosition="left"
               disabled={!isLabelTruncated}
@@ -69,13 +89,14 @@ export function CatalogEntityHistoryButton({
               <VersionPillWrapper>
                 <VersionPill>
                   <CheckmarkIcon />
-                  <span ref={labelRef}>{label}</span>
+                  <span ref={labelRef}>{displayLabel}</span>
                 </VersionPill>
               </VersionPillWrapper>
             </Tooltip>
           )}
         </HistoryContent>
       </HistoryItem>
+      <Separator />
     </CatalogHistoryButtonWrapper>
   );
 }
@@ -88,19 +109,19 @@ const Separator = styled.div`
   width: 100%;
   height: 1px;
   background-color: var(--catalog-history-separator-border-color);
-  margin-bottom: var(--catalog-history-separator-margin-bottom);
+  margin: var(--catalog-history-separator-margin);
   flex-shrink: 0;
 `;
 
 const HistoryItem = styled.button`
   all: unset;
+  box-sizing: border-box;
   display: flex;
   align-items: center;
   justify-content: space-between;
   gap: var(--catalog-history-item-gap);
   padding: var(--catalog-history-item-padding);
-  margin-bottom: var(--catalog-history-item-margin-bottom);
-  width: var(--catalog-history-button-item-width);
+  width: 100%;
   border-radius: var(--catalog-history-item-border-radius);
   cursor: pointer;
   transition: background-color 0.2s ease;
@@ -112,13 +133,11 @@ const HistoryItem = styled.button`
 
 const HistoryContent = styled.div`
   display: flex;
-  flex-wrap: wrap;
   align-items: center;
   justify-content: space-between;
   flex: 1;
   gap: var(--catalog-history-item-gap);
   min-width: 0;
-  max-width: var(--catalog-history-content-max-width);
 `;
 
 const HistoryText = styled.span`
@@ -134,19 +153,21 @@ const HistoryText = styled.span`
 const VersionPillWrapper = styled.div`
   flex: 0 1 auto;
   min-width: 0;
-  max-width: var(--catalog-history-content-max-width);
 `;
 
 const HistoryIcon = styled(RecentlyViewedIcon)`
   width: var(--catalog-history-icon-size);
   height: var(--catalog-history-icon-size);
   flex-shrink: 0;
+  margin-right: var(--catalog-history-icon-gap);
 `;
 
 const VersionPill = styled.div`
+  box-sizing: border-box;
   display: flex;
   align-items: center;
   gap: var(--catalog-history-pill-gap);
+  height: var(--catalog-history-pill-height);
   padding: var(--catalog-history-pill-padding-vertical) var(--catalog-history-pill-padding-horizontal);
   border: 1px solid var(--catalog-history-pill-border-color);
   border-radius: var(--catalog-history-pill-border-radius);
@@ -166,7 +187,7 @@ const VersionPill = styled.div`
   }
 `;
 
-const CheckmarkIcon = styled(CheckmarkOutlineIcon)`
+const CheckmarkIcon = styled(RadioCheckButtonIcon)`
   width: var(--catalog-history-pill-icon-size);
   height: var(--catalog-history-pill-icon-size);
   min-width: var(--catalog-history-pill-icon-size);

package/src/components/Catalog/CatalogEntity/CatalogEntityHistory/CatalogEntityHistorySidebar.tsx

@@ -1,4 +1,4 @@
-import React, { useState, useEffect, useCallback, useMemo } from 'react';
+import React, { useState, useEffect, useCallback, useMemo, useRef } from 'react';
 import styled from 'styled-components';
 import { useLocation } from 'react-router';
 
@@ -17,18 +17,67 @@ export type CatalogHistorySidebarProps = {
   className?: string;
 };
 
+/**
+ * Overlay visibility, driven by the button's open event. The overlay stays
+ * open only on the location it was opened at, so navigation closes it; every
+ * close (explicit or by navigation) emits the close event that syncs the
+ * button pill with the given version/revision.
+ */
+function useVersionHistoryOverlay(version: string | null | undefined, revisionLabel?: string) {
+  const location = useLocation();
+  const locationKey = `${location.pathname}${location.search}`;
+  const locationKeyRef = useRef(locationKey);
+  locationKeyRef.current = locationKey;
+  const [openLocation, setOpenLocation] = useState<string | null>(null);
+  const closeEventPending = useRef(false);
+  if (openLocation !== null && openLocation !== locationKey) {
+    closeEventPending.current = true;
+    setOpenLocation(null);
+  }
+
+  useEffect(() => {
+    const open = () => setOpenLocation(locationKeyRef.current);
+    window.addEventListener('portal:sidebar:open-version-history', open);
+    return () => window.removeEventListener('portal:sidebar:open-version-history', open);
+  }, []);
+
+  const emitClose = useCallback(() => {
+    window.dispatchEvent(
+      new CustomEvent('portal:sidebar:close-version-history', {
+        detail: { version, revision: revisionLabel },
+      }),
+    );
+  }, [version, revisionLabel]);
+
+  // Dispatched after the post-navigation render so the close event carries
+  // the freshly navigated-to version/revision.
+  useEffect(() => {
+    if (!closeEventPending.current) return;
+    closeEventPending.current = false;
+    emitClose();
+  }, [openLocation, emitClose]);
+
+  const close = useCallback(() => {
+    emitClose();
+    setOpenLocation(null);
+  }, [emitClose]);
+
+  return { isOpen: openLocation !== null && openLocation === locationKey, close };
+}
+
 export function CatalogEntityHistorySidebar({
   entityKey,
   revision,
   version,
   className,
 }: CatalogHistorySidebarProps): React.ReactElement | null {
-  const [isOpen, setIsOpen] = useState(false);
   const location = useLocation();
   const basePath = location.pathname;
-  const { useTranslate, useFetchCatalogEntityRevisions, useL10nConfig } = useThemeHooks();
+  const { useTranslate, useFetchCatalogEntityRevisions, useL10nConfig, usePageVersions } =
+    useThemeHooks();
   const { translate } = useTranslate();
   const { currentLocale } = useL10nConfig();
+  const { versions: pageVersions } = usePageVersions();
 
   const { items: revisions } = useFetchCatalogEntityRevisions({ entityKey });
 
@@ -50,9 +99,12 @@ export function CatalogEntityHistorySidebar({
       item.revisions?.some((revision) => revision.isActive),
     );
     const activeRevision = itemWithActiveRevision?.revisions?.find((revision) => revision.isActive);
-    return activeRevision?.name;
+    // Show the revision label only while an old revision is open.
+    return activeRevision && !activeRevision.isCurrent ? activeRevision.name : undefined;
   }, [versionHistoryItems]);
 
+  const { isOpen, close } = useVersionHistoryOverlay(version, activeRevisionLabel);
+
   const [expandedVersions, setExpandedVersions] = useState<Set<string>>(new Set());
 
   useEffect(() => {
@@ -61,27 +113,6 @@ export function CatalogEntityHistorySidebar({
     );
   }, [versionHistoryItems]);
 
-  const handleOpenSidebar = useCallback(() => {
-    setIsOpen(true);
-  }, []);
-
-  useEffect(() => {
-    window.addEventListener('portal:sidebar:open-version-history', handleOpenSidebar);
-
-    return () => {
-      window.removeEventListener('portal:sidebar:open-version-history', handleOpenSidebar);
-    };
-  }, [handleOpenSidebar]);
-
-  const handleClose = (): void => {
-    window.dispatchEvent(
-      new CustomEvent('portal:sidebar:close-version-history', {
-        detail: { version, revision: activeRevisionLabel },
-      }),
-    );
-    setIsOpen(false);
-  };
-
   const toggleVersion = (version: string): void => {
     setExpandedVersions((prev) => {
       const newSet = new Set(prev);
@@ -101,18 +132,16 @@ export function CatalogEntityHistorySidebar({
   return (
     <SidebarOverlay className={className} data-component-name="Catalog/CatalogHistorySidebar">
       <SidebarHeader>
-        <HeaderWrapper>
-          <HistoryIcon />
-          <HeaderTitle>{translate('catalog.history.sidebar.title', 'Version history')}</HeaderTitle>
-        </HeaderWrapper>
+        <HistoryIcon />
+        <HeaderTitle>{translate('catalog.history.sidebar.title', 'Version')}</HeaderTitle>
         <CloseButton
-          onClick={handleClose}
+          onClick={close}
           aria-label={translate('catalog.history.sidebar.close', 'Close version history')}
         >
-          <CloseIcon size="20px" color="--catalog-history-sidebar-close-icon-color" />
+          <CloseIcon size="14px" color="--catalog-history-sidebar-close-icon-color" />
         </CloseButton>
       </SidebarHeader>
-
+      <Divider />
       <MenuContainer growContent>
         <VersionList>
           {versionHistoryItems.map((group) => (
@@ -122,6 +151,9 @@ export function CatalogEntityHistorySidebar({
               basePath={basePath}
               isExpanded={expandedVersions.has(group.version)}
               onToggle={toggleVersion}
+              versionLink={
+                pageVersions?.find((pageVersion) => pageVersion.version === group.version)?.link
+              }
             />
           ))}
         </VersionList>
@@ -136,6 +168,7 @@ const SidebarOverlay = styled.div`
   left: 0;
   width: var(--sidebar-width);
   height: calc(100vh - var(--navbar-height) - var(--banner-height));
+  padding: var(--catalog-history-sidebar-padding);
   background-color: var(--catalog-history-sidebar-bg-color);
   border-right: 1px solid var(--catalog-history-sidebar-border-color);
   display: flex;
@@ -144,16 +177,27 @@ const SidebarOverlay = styled.div`
   overflow: hidden;
 `;
 
+// Same row geometry as the history button, so opening the overlay keeps the
+// icon and title in place.
 const SidebarHeader = styled.div`
   display: flex;
   align-items: center;
-  justify-content: space-between;
+  gap: var(--catalog-history-item-gap);
   padding: var(--catalog-history-sidebar-header-padding);
-  border-bottom: 1px solid var(--catalog-history-sidebar-border-color);
+  border-radius: var(--border-radius-lg);
+  flex-shrink: 0;
+`;
+
+const Divider = styled.div`
+  height: 1px;
+  background-color: var(--catalog-history-sidebar-border-color);
+  margin: var(--catalog-history-sidebar-divider-margin);
   flex-shrink: 0;
 `;
 
 const HeaderTitle = styled.h2`
+  flex: 1;
+  min-width: 0;
   margin: 0;
   font-family: var(--catalog-history-sidebar-header-font-family);
   font-size: var(--catalog-history-sidebar-header-font-size);
@@ -182,18 +226,12 @@ const CloseButton = styled.button`
 const VersionList = styled.ul`
   list-style: none;
   margin: 0;
-  padding: var(--catalog-history-sidebar-content-padding);
-  margin-top: var(--catalog-history-sidebar-content-margin-top);
+  padding: 0;
 `;
 
 const HistoryIcon = styled(RecentlyViewedIcon)`
   width: var(--catalog-history-icon-size);
   height: var(--catalog-history-icon-size);
   flex-shrink: 0;
-`;
-
-const HeaderWrapper = styled.div`
-  display: flex;
-  align-items: center;
-  gap: var(--spacing-xs);
+  margin-right: var(--catalog-history-icon-gap);
 `;

package/src/components/Catalog/CatalogEntity/CatalogEntityHistory/CatalogEntityRevisionItem.tsx

@@ -12,16 +12,26 @@ export type CatalogEntityRevisionItemProps = {
   revisionItem: CatalogEntityRevision;
   basePath: string;
   version?: string | null;
+  /** The version's own page URL (from the host's usePageVersions). */
+  versionLink?: string;
 };
 
 export function CatalogEntityRevisionItem({
   revisionItem,
   basePath,
   version,
+  versionLink,
 }: CatalogEntityRevisionItemProps): React.ReactElement {
   const { useTranslate } = useThemeHooks();
   const { translate } = useTranslate();
-  const revisionFilter = buildRevisionUrl(basePath, revisionItem.revisionDate, version) ?? basePath;
+  // The current revision links to the version's live page. Older revisions
+  // add ?revision= to that URL. Hosts without page-version links keep the
+  // legacy ?revision=&version= contract.
+  const base = versionLink ?? basePath;
+  const revisionFilter = revisionItem.isCurrent
+    ? base
+    : (buildRevisionUrl(base, revisionItem.revisionDate, versionLink ? undefined : version) ??
+      base);
   const isActive = revisionItem.isActive ?? false;
 
   return (
@@ -56,12 +66,18 @@ const RevisionItemWrapper = styled(Link)<{ $isActive?: boolean }>`
   padding-left: var(--catalog-history-sidebar-revisions-padding-left);
   border-radius: var(--catalog-history-sidebar-revision-item-border-radius);
   transition: 0.2s ease;
-  text-decoration: none;
   color: inherit;
   cursor: pointer;
   background-color: ${({ $isActive }) =>
     $isActive ? 'var(--catalog-history-sidebar-revision-item-bg-color-active)' : 'transparent'};
 
+  &,
+  &:hover,
+  &:focus,
+  &:visited {
+    text-decoration: none;
+  }
+
   &:hover {
     background-color: ${({ $isActive }) =>
       $isActive