@redocly/theme 0.67.0 → 0.68.0-next.1

package/src/components/Buttons/ConnectMCPButton.tsx

@@ -1,10 +1,9 @@
-import React, { useMemo } from 'react';
+import React, { useState, useRef } from 'react';
 import styled from 'styled-components';
 
 import type { JSX } from 'react';
 import type { MCPOption } from '@redocly/theme/core/types';
 
-import { Dropdown } from '@redocly/theme/components/Dropdown/Dropdown';
 import { DropdownMenu } from '@redocly/theme/components/Dropdown/DropdownMenu';
 import { DropdownMenuItem } from '@redocly/theme/components/Dropdown/DropdownMenuItem';
 import { Button } from '@redocly/theme/components/Button/Button';
@@ -12,21 +11,9 @@ import { CursorIcon } from '@redocly/theme/icons/CursorIcon/CursorIcon';
 import { VSCodeIcon } from '@redocly/theme/icons/VSCodeIcon/VSCodeIcon';
 import { CopyIcon } from '@redocly/theme/icons/CopyIcon/CopyIcon';
 import { CheckmarkFilledIcon } from '@redocly/theme/icons/CheckmarkFilledIcon/CheckmarkFilledIcon';
-import { ConnectIcon } from '@redocly/theme/icons/ConnectIcon/ConnectIcon';
-import { useConnectMCPButton } from '@redocly/theme/core/hooks';
-import { useThemeHooks } from '@redocly/theme/core/hooks';
-
-type TriggerButtonProps = {
-  text: string;
-};
-
-const TriggerButton = React.memo(({ text }: TriggerButtonProps): JSX.Element => {
-  return (
-    <StyledButton variant="secondary" icon={<ConnectIcon />}>
-      {text}
-    </StyledButton>
-  );
-});
+import { ChevronDownIcon } from '@redocly/theme/icons/ChevronDownIcon/ChevronDownIcon';
+import { ChevronUpIcon } from '@redocly/theme/icons/ChevronUpIcon/ChevronUpIcon';
+import { useConnectMCPButton, useOutsideClick, useThemeHooks } from '@redocly/theme/core/hooks';
 
 type MenuOption = {
   key: MCPOption;
@@ -74,57 +61,93 @@ export function ConnectMCPButton({
   placement = 'bottom',
   alignment = 'end',
   options = ['cursor', 'vscode', 'copy'],
-}: ConnectMCPButtonProps): JSX.Element {
+}: ConnectMCPButtonProps): JSX.Element | null {
   const { useTranslate } = useThemeHooks();
   const { translate } = useTranslate();
+  const [isOpen, setIsOpen] = useState(false);
+  const wrapperRef = useRef<HTMLDivElement>(null);
 
-  const { isCopied, triggerButtonText, visibleOptions, handleAction } = useConnectMCPButton({
-    options,
-  });
+  const { isCopied, visibleOptions, handleAction } = useConnectMCPButton({ options });
 
-  const menuOptions = useMemo(
-    () => MENU_OPTIONS.filter((option) => visibleOptions.includes(option.key)),
-    [visibleOptions],
-  );
+  useOutsideClick(wrapperRef, () => setIsOpen(false));
+
+  const menuOptions = MENU_OPTIONS.filter((option) => visibleOptions.includes(option.key));
+  const primaryOption = menuOptions[0];
+  const dropdownOptions = menuOptions.slice(1);
+
+  if (!primaryOption) return null;
+
+  const PrimaryIcon = primaryOption.icon;
+  // When copy is the primary action there is no dropdown item to show the copied state, so the
+  // primary button itself must reflect it.
+  const showPrimaryCopied = primaryOption.key === 'copy' && isCopied;
+
+  const handleMenuAction = (key: MCPOption) => {
+    handleAction(key);
+    setIsOpen(false);
+  };
 
   return (
-    <ConnectMCPButtonWrapper data-component-name="Buttons/ConnectMCPButton">
-      <Dropdown
-        trigger={<TriggerButton text={triggerButtonText} />}
-        triggerEvent="hover"
-        placement={placement}
-        alignment={alignment}
-        closeOnClick={false}
-      >
-        <DropdownMenu>
-          {menuOptions.map((option) => {
-            const Icon = option.icon;
-            const showCheckmark = option.key === 'copy' && isCopied;
-
-            return (
-              <DropdownMenuItem key={option.key} onAction={() => handleAction(option.key)}>
-                <MenuItemContent>
-                  <MenuItemIcon>
-                    {showCheckmark ? (
-                      <CheckmarkFilledIcon color="var(--color-success-base)" />
-                    ) : (
-                      <Icon />
-                    )}
-                  </MenuItemIcon>
-                  <MenuItemText>
-                    <MenuItemTitle>
-                      {translate(option.titleTranslationKey, option.titleDefault)}
-                    </MenuItemTitle>
-                    <MenuItemDescription>
-                      {translate(option.descriptionTranslationKey, option.descriptionDefault)}
-                    </MenuItemDescription>
-                  </MenuItemText>
-                </MenuItemContent>
-              </DropdownMenuItem>
-            );
-          })}
-        </DropdownMenu>
-      </Dropdown>
+    <ConnectMCPButtonWrapper ref={wrapperRef} data-component-name="Buttons/ConnectMCPButton">
+      <SplitButtonGroup>
+        <PrimaryButton
+          variant="secondary"
+          icon={
+            showPrimaryCopied ? (
+              <CheckmarkFilledIcon color="var(--color-success-base)" />
+            ) : (
+              <PrimaryIcon />
+            )
+          }
+          onClick={() => handleAction(primaryOption.key)}
+        >
+          {translate(primaryOption.titleTranslationKey, primaryOption.titleDefault)}
+        </PrimaryButton>
+        {dropdownOptions.length > 0 && (
+          <ChevronButton
+            variant="secondary"
+            aria-label={translate('page.actions.connectMcp.moreOptions', 'More options')}
+            aria-expanded={isOpen}
+            aria-haspopup="menu"
+            onClick={() => setIsOpen((prev) => !prev)}
+          >
+            {isOpen ? <ChevronUpIcon /> : <ChevronDownIcon />}
+          </ChevronButton>
+        )}
+      </SplitButtonGroup>
+
+      {isOpen && dropdownOptions.length > 0 && (
+        <DropdownWrapper $placement={placement} $alignment={alignment}>
+          <DropdownMenu>
+            {dropdownOptions.map((option) => {
+              const Icon = option.icon;
+              const showCheckmark = option.key === 'copy' && isCopied;
+
+              return (
+                <DropdownMenuItem key={option.key} onAction={() => handleMenuAction(option.key)}>
+                  <MenuItemContent>
+                    <MenuItemIcon>
+                      {showCheckmark ? (
+                        <CheckmarkFilledIcon color="var(--color-success-base)" />
+                      ) : (
+                        <Icon />
+                      )}
+                    </MenuItemIcon>
+                    <MenuItemText>
+                      <MenuItemTitle>
+                        {translate(option.titleTranslationKey, option.titleDefault)}
+                      </MenuItemTitle>
+                      <MenuItemDescription>
+                        {translate(option.descriptionTranslationKey, option.descriptionDefault)}
+                      </MenuItemDescription>
+                    </MenuItemText>
+                  </MenuItemContent>
+                </DropdownMenuItem>
+              );
+            })}
+          </DropdownMenu>
+        </DropdownWrapper>
+      )}
     </ConnectMCPButtonWrapper>
   );
 }
@@ -134,8 +157,32 @@ const ConnectMCPButtonWrapper = styled.div`
   position: relative;
 `;
 
-const StyledButton = styled(Button)`
+const SplitButtonGroup = styled.div`
+  display: inline-flex;
+  align-items: stretch;
+`;
+
+const PrimaryButton = styled(Button)`
   --button-gap: var(--connect-mcp-button-gap);
+  border-top-right-radius: 0;
+  border-bottom-right-radius: 0;
+`;
+
+const ChevronButton = styled(Button)`
+  border-top-left-radius: 0;
+  border-bottom-left-radius: 0;
+  border-left: none;
+  padding-inline: var(--connect-mcp-button-chevron-padding-inline);
+`;
+
+const DropdownWrapper = styled.div<{ $placement?: string; $alignment?: string }>`
+  position: absolute;
+  top: ${({ $placement }) => ($placement === 'top' ? 'auto' : '100%')};
+  bottom: ${({ $placement }) => ($placement === 'top' ? '100%' : 'auto')};
+  left: ${({ $alignment }) => ($alignment === 'start' ? '0' : 'auto')};
+  right: ${({ $alignment }) => ($alignment === 'end' ? '0' : 'auto')};
+  padding-top: var(--dropdown-menu-padding-top);
+  z-index: var(--dropdown-menu-z-index);
 `;
 
 const MenuItemContent = styled.div`

package/src/components/Buttons/variables.ts

@@ -58,6 +58,9 @@ export const connectMCPButton = css`
   /* Button gap */
   --connect-mcp-button-gap: var(--spacing-xs);
 
+  /* Chevron button */
+  --connect-mcp-button-chevron-padding-inline: var(--spacing-xs);
+
   /* Menu item layout */
   --connect-mcp-button-menu-item-gap: var(--spacing-sm);
   --connect-mcp-button-menu-item-padding-block: var(--spacing-xxs);

package/src/components/Catalog/CatalogEntities.tsx

@@ -3,11 +3,8 @@ import React, { JSX, useEffect } from 'react';
 import type { CatalogEntityConfig } from '@redocly/config';
 
 import { BffCatalogEntity, BffCatalogEntityList } from '@redocly/theme/core/types';
-import {
-  useThemeHooks,
-  useCatalogEntities,
-  useCatalogEntityDetails,
-} from '@redocly/theme/core/hooks';
+import { useThemeHooks, useCatalogEntities } from '@redocly/theme/core/hooks';
+import { getBaseDataAttributes } from '@redocly/theme/core/utils';
 import { ArrowDownIcon } from '@redocly/theme/icons/ArrowDownIcon/ArrowDownIcon';
 import { CatalogCardView } from '@redocly/theme/components/Catalog/CatalogCardView/CatalogCardView';
 import { CatalogTableView } from '@redocly/theme/components/Catalog/CatalogTableView/CatalogTableView';
@@ -45,9 +42,6 @@ export function CatalogEntities(props: CatalogEntitiesProps): JSX.Element {
     isColumnSorted,
   } = props;
 
-  const { getEntityDetailsLink } = useCatalogEntityDetails({
-    catalogConfig,
-  });
   const { useTelemetry, useFetchCatalogEntities } = useThemeHooks();
   const telemetry = useTelemetry();
   const { initialFilter } = useCatalogEntities({
@@ -76,10 +70,12 @@ export function CatalogEntities(props: CatalogEntitiesProps): JSX.Element {
     if (searchQuery) {
       telemetry.sendCatalogEntitiesListSearchResultClickedMessage([
         {
-          id: entity.id,
-          object: 'catalog_entity',
-          uri: getEntityDetailsLink(entity),
+          ...getBaseDataAttributes(
+            'catalogEntitiesListSearchResultId',
+            'catalogEntitiesListSearchResult',
+          ),
           query: searchQuery,
+          entityId: entity.id,
           entityKey: entity.key,
           entityType: entity.type,
         },

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

@@ -8,7 +8,8 @@ import type { BffCatalogEntity, BffCatalogRelatedEntity } from '@redocly/theme/c
 import { CatalogColumn } from '@redocly/theme/components/Catalog/CatalogTableView/CatalogTableView';
 import { CatalogActionsRow } from '@redocly/theme/components/Catalog/CatalogActionsRow';
 import { CatalogEntityRelationsTableContent } from '@redocly/theme/components/Catalog/CatalogEntity/CatalogEntityRelations/CatalogEntityRelationsTableContent';
-import { useCatalogEntityDetails, useThemeHooks } from '@redocly/theme/core/hooks';
+import { useThemeHooks } from '@redocly/theme/core/hooks';
+import { getBaseDataAttributes } from '@redocly/theme/core/utils';
 import { reverseRelationMap } from '@redocly/theme/core/constants';
 
 export type CatalogEntityRelationsTableProps = {
@@ -51,22 +52,20 @@ export function CatalogEntityRelationsTable({
 }: CatalogEntityRelationsTableProps): JSX.Element {
   const { useTelemetry } = useThemeHooks();
   const telemetry = useTelemetry();
-  const { getEntityDetailsLink } = useCatalogEntityDetails({
-    catalogConfig,
-    entitiesCatalogConfig,
-  });
 
   const onRowClick = (relatedEntity: BffCatalogRelatedEntity) => {
     if (searchQuery) {
-      telemetry.sendCatalogEntitiesRelatedEntitiesListSearchResultClickMessage([
+      telemetry.sendCatalogEntitiesRelatedEntitiesListSearchResultClickedMessage([
         {
-          id: relatedEntity.id,
-          object: 'catalog_entity',
-          uri: getEntityDetailsLink(relatedEntity),
+          ...getBaseDataAttributes(
+            'catalogEntitiesRelatedEntitiesListSearchResultId',
+            'catalogEntitiesRelatedEntitiesListSearchResult',
+          ),
           query: searchQuery,
           entityKey: entity.key,
           entityType: entity.type,
           relationType: reverseRelationMap[relatedEntity.relationType],
+          relatedEntityId: relatedEntity.id,
           relatedEntityKey: relatedEntity.key,
           relatedEntityType: relatedEntity.type,
         },

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

@@ -5,8 +5,9 @@ import * as Sampler from 'openapi-sampler';
 import type { CatalogEntityConfig } from '@redocly/config';
 import type { BffCatalogEntity, BffCatalogRelatedEntity } from '@redocly/theme/core/types';
 
-import { useCatalogEntityDetails, useThemeHooks } from '@redocly/theme/core/hooks';
+import { useThemeHooks } from '@redocly/theme/core/hooks';
 import { useCatalogEntitySchema } from '@redocly/theme/core/hooks';
+import { getBaseDataAttributes } from '@redocly/theme/core/utils';
 import { JsonViewer } from '@redocly/theme/components/JsonViewer/JsonViewer';
 import { CopyButton } from '@redocly/theme/components/Buttons/CopyButton';
 
@@ -24,7 +25,6 @@ export type CatalogEntitySchemaProps = {
 export function CatalogEntitySchema({
   entity,
   relatedEntity,
-  catalogConfig,
   RedocSchema,
   StoreProvider,
   GraphqlTypeRenderer,
@@ -35,9 +35,6 @@ export function CatalogEntitySchema({
   const { definition, parsedSchema, rawSchema } = useCatalogEntitySchema({ entity, relatedEntity });
   const isGraphql = entity.metadata?.specType === 'graphql';
   const graphqlSDL = entity?.metadata?.sdl;
-  const { getEntityDetailsLink } = useCatalogEntityDetails({
-    catalogConfig,
-  });
 
   return (
     <MetadataWrapper data-component-name="Catalog/CatalogEntity/CatalogEntitySchema">
@@ -54,9 +51,10 @@ export function CatalogEntitySchema({
             onCopyClick={() =>
               telemetry.sendCatalogEntitiesCopyDataSchemaClickedMessage([
                 {
-                  id: entity.id,
-                  object: 'catalog_entity',
-                  uri: getEntityDetailsLink(entity),
+                  ...getBaseDataAttributes('catalogEntitiesCopyDataSchemaId', 'button'),
+                  entityId: entity.id,
+                  entityKey: entity.key,
+                  entityType: entity.type,
                 },
               ])
             }

package/src/components/Catalog/CatalogFilter/CatalogFilterCheckboxes.tsx

@@ -12,7 +12,7 @@ import { FilterInput } from '@redocly/theme/components/Filter/FilterInput';
 import { useThemeHooks } from '@redocly/theme/core/hooks';
 import { CheckboxIcon } from '@redocly/theme/icons/CheckboxIcon/CheckboxIcon';
 import { CounterTag } from '@redocly/theme/components/Tags/CounterTag';
-import { changeTextCasing } from '@redocly/theme/core/utils';
+import { changeTextCasing, getBaseDataAttributes } from '@redocly/theme/core/utils';
 import { Accordion } from '@redocly/theme/components/Accordion/Accordion';
 
 export type CatalogFilterCheckboxesProps = FilterProps & {
@@ -104,9 +104,7 @@ export function CatalogFilterCheckboxes({
                   filter.toggleOption(value);
                   telemetry.sendCatalogEntitiesFilterCheckboxToggledMessage([
                     {
-                      id: filter.property + '--' + value,
-                      object: 'checkbox',
-                      uri: window.location.href,
+                      ...getBaseDataAttributes('catalogEntitiesFilterCheckboxId', 'checkbox'),
                       category: filter.property,
                       value: value,
                     },

package/src/components/Feedback/Feedback.tsx

@@ -11,6 +11,7 @@ import { Comment } from '@redocly/theme/components/Feedback/Comment';
 import { Mood } from '@redocly/theme/components/Feedback/Mood';
 import { Scale } from '@redocly/theme/components/Feedback/Scale';
 import { DEFAULT_FEEDBACK_TYPE } from '@redocly/theme/core/constants';
+import { getBaseDataAttributes } from '@redocly/theme/core/utils';
 
 const feedbackComponents = {
   rating: Rating,
@@ -58,7 +59,16 @@ export function Feedback(props: FeedbackProps & { path?: string }) {
           settings={settings}
           onSubmit={(values) => {
             submitFeedback({ type, values, path });
-            telemetry.sendFeedbackMessage({ feedbackType: type });
+            telemetry.sendFeedbackMessage([
+              {
+                ...getBaseDataAttributes<
+                  'feedbackFormId',
+                  'feedbackForm',
+                  'urn:redocly:realm:ui:feedbackForm:feedbackFormId'
+                >('feedbackFormId', 'feedbackForm'),
+                feedbackType: type,
+              },
+            ]);
           }}
         />
       </FeedbackWrapper>

package/src/components/Feedback/Reasons.tsx

@@ -16,7 +16,7 @@ export type ReasonsProps = {
 };
 
 export function Reasons({ settings, onChange, className }: ReasonsProps): JSX.Element | null {
-  const { label, component, items = [] } = settings;
+  const { label, component = 'checkbox', items = [] } = settings;
   const [checkedState, setCheckedState] = React.useState(new Array(items.length).fill(false));
   const { useTranslate } = useThemeHooks();
   const { translate } = useTranslate();
@@ -25,8 +25,6 @@ export function Reasons({ settings, onChange, className }: ReasonsProps): JSX.El
     return null;
   }
 
-  const input_type = component || 'checkbox';
-
   const handleOptionChange = (position: number) => {
     const updatedCheckedState =
       component === 'checkbox'
@@ -53,7 +51,7 @@ export function Reasons({ settings, onChange, className }: ReasonsProps): JSX.El
       {items.map((reason, idx) => (
         <OptionWrapper key={reason}>
           <input
-            type={input_type}
+            type={component}
             value={reason}
             checked={checkedState[idx]}
             name="reasons"

package/src/components/Menu/MenuItem.tsx

@@ -10,7 +10,7 @@ import { Link } from '@redocly/theme/components/Link/Link';
 import { ChevronDownIcon } from '@redocly/theme/icons/ChevronDownIcon/ChevronDownIcon';
 import { ChevronRightIcon } from '@redocly/theme/icons/ChevronRightIcon/ChevronRightIcon';
 import { HttpTag } from '@redocly/theme/components/Tags/HttpTag';
-import { MenuItemType } from '@redocly/theme/core/constants';
+import { DEFAULT_LINE_POSITION, MenuItemType } from '@redocly/theme/core/constants';
 import {
   getBaseDataAttributes,
   getMenuItemType,
@@ -178,7 +178,10 @@ export function MenuItem(props: React.PropsWithChildren<MenuItemProps>): JSX.Ele
         </MenuItemNestedWrapper>
       ) : null}
       {item.separatorLine ? (
-        <MenuItemSeparatorLine $depth={depth} $linePosition={item.linePosition} />
+        <MenuItemSeparatorLine
+          $depth={depth}
+          $linePosition={item.linePosition ?? DEFAULT_LINE_POSITION}
+        />
       ) : null}
     </MenuItemWrapper>
   );

package/src/components/Search/SearchAiDialog.tsx

@@ -59,7 +59,7 @@ export function SearchAiDialog({
 
   const conversationEndRef = React.useRef<HTMLDivElement>(null);
 
-  const suggestions = aiAssistant?.suggestions;
+  const suggestions = aiAssistant?.suggestions ?? [];
 
   const placeholder = isGeneratingResponse
     ? translate('search.ai.generatingResponse', 'Generating response...')

package/src/components/Search/SearchAiResponse.tsx

@@ -42,7 +42,7 @@ export function SearchAiResponse(props: SearchAiResponseProps): JSX.Element {
 
   let responseContainer = null;
 
-  const suggestions = aiAssistant?.suggestions;
+  const suggestions = aiAssistant?.suggestions ?? [];
 
   const hasPendingOrReceivedResponse = response || isGeneratingResponse || error;
   if (hasPendingOrReceivedResponse) {

package/src/components/Search/SearchTrigger.tsx

@@ -7,6 +7,7 @@ import { useThemeConfig, useThemeHooks } from '@redocly/theme/core/hooks';
 import { Button } from '@redocly/theme/components/Button/Button';
 import { SearchIcon } from '@redocly/theme/icons/SearchIcon/SearchIcon';
 import { breakpoints, getUserAgent } from '@redocly/theme/core/utils';
+import { DEFAULT_KEYBOARD_SHORTCUTS } from '@redocly/theme/core/constants';
 
 export type SearchTriggerProps = {
   onClick: () => void;
@@ -18,8 +19,7 @@ export function SearchTrigger({ onClick, className }: SearchTriggerProps): JSX.E
   const { useTranslate } = useThemeHooks();
   const { translate } = useTranslate();
 
-  const defaultKeyShortcut = '⌘+K,CTRL+K';
-  const keyShortcuts = themeSettings?.search?.shortcuts ?? [defaultKeyShortcut];
+  const keyShortcuts = themeSettings?.search?.shortcuts ?? [DEFAULT_KEYBOARD_SHORTCUTS];
   let mainShortcutKey: string | null | undefined = null;
 
   if (keyShortcuts) {
@@ -52,7 +52,7 @@ export function SearchTrigger({ onClick, className }: SearchTriggerProps): JSX.E
       >
         <SearchIcon />
         {translate('search.navbar.label', 'Search')}
-        {mainShortcutKey === defaultKeyShortcut ? (
+        {mainShortcutKey === DEFAULT_KEYBOARD_SHORTCUTS ? (
           <span>{isMac ? '⌘K' : 'Ctrl+K'}</span>
         ) : (
           <span>{mainShortcutKey}</span>

package/src/core/constants/common.ts

@@ -35,3 +35,5 @@ export const DEFAULT_COLOR_MODES = {
   LIGHT: 'light',
   DARK: 'dark',
 } as const;
+
+export const DEFAULT_LINE_POSITION = 'top';

package/src/core/constants/search.ts

@@ -46,6 +46,8 @@ export const AI_SEARCH_MAX_MESSAGE_LENGTH = 45000;
 
 export const SEARCH_DEBOUNCE_TIME_MS = 300;
 
+export const DEFAULT_KEYBOARD_SHORTCUTS = '⌘+K,CTRL+K';
+
 export const TOOL_CALL_DISPLAY_TEXT: Partial<
   Record<string, { inProgressText: string; completedText: string }>
 > = {

package/src/core/hooks/search/use-search-dialog.ts

@@ -6,6 +6,7 @@ import { useThemeHooks } from '../use-theme-hooks';
 import { useThemeConfig } from '../use-theme-config';
 import { useSearchSession } from '../../contexts';
 import { getBaseDataAttributes } from '../../utils';
+import { DEFAULT_KEYBOARD_SHORTCUTS } from '../../constants';
 
 export function useSearchDialog() {
   const [isOpen, setIsOpen] = useState(false);
@@ -14,7 +15,7 @@ export function useSearchDialog() {
   const { useTelemetry } = useThemeHooks();
   const telemetry = useTelemetry();
   const { refreshSearchSessionId } = useSearchSession();
-  const keyShortcuts = themeSettings?.search?.shortcuts ?? ['⌘+K,CTRL+K'];
+  const keyShortcuts = themeSettings?.search?.shortcuts ?? [DEFAULT_KEYBOARD_SHORTCUTS];
   const hotKeys = keyShortcuts?.join(',');
 
   useEffect(() => {

package/src/core/hooks/use-active-heading.ts

@@ -64,8 +64,13 @@ export function useActiveHeading(
     const headers = Array.from(allHeaders);
 
     if (displayedHeadingsRef.current && displayedHeadingsRef.current.length > 0) {
-      const displayedIds = displayedHeadingsRef.current.map((h) => h?.id).filter(Boolean);
-      return headers.filter((header) => displayedIds.includes(header.id));
+      // Resolve targets by id so anchors that are not headings (e.g. numbered
+      // list items with a lifted headline) can be scrolled to and tracked.
+      return displayedHeadingsRef.current
+        .map((heading) =>
+          heading?.id ? allContent.querySelector<HTMLElement>(`[id="${heading.id}"]`) : null,
+        )
+        .filter((element): element is HTMLElement => element !== null);
     }
 
     return headers;

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

@@ -8,7 +8,7 @@ export const useTelemetryFallback = () => ({
   sendCatalogEntitiesCopyDataSchemaClickedMessage: () => {},
   sendCatalogEntitiesViewModeChangedMessage: () => {},
   sendCatalogEntitiesRelatedEntitiesListSearchQueryMessage: () => {},
-  sendCatalogEntitiesRelatedEntitiesListSearchResultClickMessage: () => {},
+  sendCatalogEntitiesRelatedEntitiesListSearchResultClickedMessage: () => {},
   sendCatalogEntitiesListSearchQueryMessage: () => {},
   sendCatalogEntitiesListSearchResultClickedMessage: () => {},
   sendRedirectMessage: () => {},

package/src/core/styles/dark.ts

@@ -60,6 +60,17 @@ const badgesDarkMode = css`
   // @tokens End
 `
 
+const numberedListDarkMode = css`
+  /**
+    * @tokens Markdown Numbered List
+    */
+
+  --md-numbered-list-marker-bg-color: var(--color-warm-grey-3); // @presenter Color
+  --md-numbered-list-marker-bg-color-hover: var(--color-warm-grey-4); // @presenter Color
+
+  // @tokens End
+`
+
 
 export const darkMode = css`
   /* === Dark Theme Colors  === */
@@ -352,6 +363,7 @@ export const darkMode = css`
   ${bannerDarkMode}
   ${admonitionDarkMode}
   ${badgesDarkMode}
+  ${numberedListDarkMode}
   ${activeBrandPaletteDark}
   ${codeBlockDarkMode}
   /**

package/src/core/styles/global.ts

@@ -29,6 +29,7 @@ import { productPicker } from '@redocly/theme/components/Product/variables';
 import { markdown } from '@redocly/theme/components/Markdown/variables';
 import { banner } from '@redocly/theme/components/Banner/variables';
 import { markdownTabs } from '@redocly/theme/markdoc/components/Tabs/variables';
+import { markdownNumberedList } from '@redocly/theme/markdoc/components/NumberedList/variables';
 import { diagram } from '@redocly/theme/markdoc/components/Diagram/variables';
 import { lastUpdated } from '@redocly/theme/components/LastUpdated/variables';
 import { logo } from '@redocly/theme/components/Logo/variables';
@@ -1344,6 +1345,7 @@ export const styles = css<{ palette?: string }>`
     ${logo}
     ${markdown}
     ${markdownTabs}
+    ${markdownNumberedList}
     ${diagram}
     ${menu}
     ${mobileMenu}