@redocly/theme 0.68.0-next.0 → 0.68.0-next.1

package/lib/markdoc/components/default.d.ts

@@ -8,6 +8,8 @@ export * from '../../markdoc/components/Tabs/TabItemFragment';
 export * from '../../markdoc/components/Tabs/Tab';
 export * from '../../markdoc/components/Tabs/TabList';
 export * from '../../markdoc/components/Tabs/Tabs';
+export * from '../../markdoc/components/NumberedList/NumberedItem';
+export * from '../../markdoc/components/NumberedList/NumberedList';
 export * from '../../markdoc/components/CodeBlock/CodeBlock';
 export * from '../../markdoc/components/Cards/Cards';
 export * from '../../markdoc/components/Cards/Card';

package/lib/markdoc/components/default.js

@@ -24,6 +24,8 @@ __exportStar(require("../../markdoc/components/Tabs/TabItemFragment"), exports);
 __exportStar(require("../../markdoc/components/Tabs/Tab"), exports);
 __exportStar(require("../../markdoc/components/Tabs/TabList"), exports);
 __exportStar(require("../../markdoc/components/Tabs/Tabs"), exports);
+__exportStar(require("../../markdoc/components/NumberedList/NumberedItem"), exports);
+__exportStar(require("../../markdoc/components/NumberedList/NumberedList"), exports);
 __exportStar(require("../../markdoc/components/CodeBlock/CodeBlock"), exports);
 __exportStar(require("../../markdoc/components/Cards/Cards"), exports);
 __exportStar(require("../../markdoc/components/Cards/Card"), exports);

package/lib/markdoc/default.js

@@ -53,6 +53,8 @@ const markdoc_example_1 = require("../markdoc/tags/markdoc-example");
 const partial_1 = require("../markdoc/tags/partial");
 const tab_1 = require("../markdoc/tags/tab");
 const tabs_1 = require("../markdoc/tags/tabs");
+const numbered_item_1 = require("../markdoc/tags/numbered-item");
+const numbered_list_1 = require("../markdoc/tags/numbered-list");
 const debug_1 = require("../markdoc/tags/debug");
 const code_snippet_1 = require("../markdoc/tags/code-snippet");
 const inline_svg_1 = require("../markdoc/tags/inline-svg");
@@ -76,6 +78,8 @@ exports.tags = {
     [partial_1.partial.tagName]: partial_1.partial.schema,
     [tab_1.tab.tagName]: tab_1.tab.schema,
     [tabs_1.tabs.tagName]: tabs_1.tabs.schema,
+    [numbered_item_1.numberedItem.tagName]: numbered_item_1.numberedItem.schema,
+    [numbered_list_1.numberedList.tagName]: numbered_list_1.numberedList.schema,
     [code_snippet_1.codeSnippet.tagName]: code_snippet_1.codeSnippet.schema,
     [inline_svg_1.inlineSvg.tagName]: inline_svg_1.inlineSvg.schema,
     [cards_1.cards.tagName]: cards_1.cards.schema,

package/lib/markdoc/tags/numbered-item.d.ts

@@ -0,0 +1,2 @@
+import type { MarkdocSchemaWrapper } from '../../markdoc/tags/types';
+export declare const numberedItem: MarkdocSchemaWrapper;

package/lib/markdoc/tags/numbered-item.js

@@ -0,0 +1,35 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.numberedItem = void 0;
+const markdoc_1 = __importDefault(require("@markdoc/markdoc"));
+const utils_1 = require("../../core/utils");
+const HEADING_TAG_NAME = /^(Heading|h[1-6])$/;
+exports.numberedItem = {
+    schema: {
+        transform(node, config) {
+            const attributes = node.transformAttributes(config);
+            const children = node.transformChildren(config);
+            const [first, ...body] = children;
+            if ((0, utils_1.isTag)(first) && HEADING_TAG_NAME.test(String(first.name))) {
+                const headlineLevel = typeof first.attributes.level === 'number'
+                    ? first.attributes.level
+                    : Number(String(first.name).slice(1)) || undefined;
+                return new markdoc_1.default.Tag('NumberedItem', Object.assign(Object.assign({}, attributes), { headline: first.children, anchorId: first.attributes.id, headlineLevel }), body);
+            }
+            return new markdoc_1.default.Tag('NumberedItem', attributes, children);
+        },
+        attributes: {
+            icon: { type: String, resolver: 'relativeOrCdnIcon' },
+            iconRawContent: {
+                // internal use only
+                type: String,
+                render: true,
+            },
+        },
+    },
+    tagName: 'numbered-item',
+};
+//# sourceMappingURL=numbered-item.js.map

package/lib/markdoc/tags/numbered-list.d.ts

@@ -0,0 +1,2 @@
+import type { MarkdocSchemaWrapper } from '../../markdoc/tags/types';
+export declare const numberedList: MarkdocSchemaWrapper;

package/lib/markdoc/tags/numbered-list.js

@@ -0,0 +1,28 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.numberedList = void 0;
+const markdoc_1 = __importDefault(require("@markdoc/markdoc"));
+const utils_1 = require("../../core/utils");
+exports.numberedList = {
+    schema: {
+        transform(node, config) {
+            const attributes = node.transformAttributes(config);
+            const items = node
+                .transformChildren(config)
+                .filter((child) => (0, utils_1.isTag)(child) && child.name === 'NumberedItem');
+            items.forEach((item, index) => {
+                item.attributes = Object.assign(Object.assign({}, item.attributes), { type: attributes.type, size: attributes.size, index: index + 1, isLast: index === items.length - 1 });
+            });
+            return new markdoc_1.default.Tag('NumberedList', attributes, items);
+        },
+        attributes: {
+            type: { type: String, matches: ['icon', 'number', 'dot'], default: 'number' },
+            size: { type: String, matches: ['small', 'medium'], default: 'medium' },
+        },
+    },
+    tagName: 'numbered-list',
+};
+//# sourceMappingURL=numbered-list.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redocly/theme",
-  "version": "0.68.0-next.0",
+  "version": "0.68.0-next.1",
   "description": "Shared UI components lib",
   "keywords": [
     "theme",

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/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}

package/src/markdoc/components/NumberedList/NumberedItem.tsx

@@ -0,0 +1,274 @@
+import React, { createElement } from 'react';
+import styled, { css } from 'styled-components';
+
+import type { JSX, PropsWithChildren, ReactNode } from 'react';
+
+import { GenericIcon } from '@redocly/theme/icons/GenericIcon/GenericIcon';
+import { LinkIcon } from '@redocly/theme/icons/LinkIcon/LinkIcon';
+
+export const NumberedListType = {
+  ICON: 'icon',
+  NUMBER: 'number',
+  DOT: 'dot',
+} as const;
+
+export type NumberedListType = (typeof NumberedListType)[keyof typeof NumberedListType];
+
+export const NumberedListSize = {
+  SMALL: 'small',
+  MEDIUM: 'medium',
+} as const;
+
+export type NumberedListSize = (typeof NumberedListSize)[keyof typeof NumberedListSize];
+
+export type NumberedItemProps = PropsWithChildren<{
+  headline?: ReactNode;
+  anchorId?: string;
+  headlineLevel?: number;
+  icon?: string | ReactNode;
+  /* Internal use only: raw SVG content resolved for relative `.svg` icons */
+  iconRawContent?: string;
+  className?: string;
+  /* Injected by the parent NumberedList component */
+  type?: NumberedListType;
+  size?: NumberedListSize;
+  index?: number;
+  isLast?: boolean;
+}>;
+
+export function NumberedItem({
+  headline,
+  anchorId,
+  headlineLevel,
+  icon,
+  iconRawContent,
+  className,
+  type = NumberedListType.NUMBER,
+  size = NumberedListSize.MEDIUM,
+  index = 1,
+  isLast = true,
+  children,
+}: NumberedItemProps): JSX.Element {
+  const isDot = type === NumberedListType.DOT;
+  const headlineTextId = anchorId ? `${anchorId}-heading-text` : undefined;
+
+  const marker = (
+    <Marker $type={type} $size={size} data-dot={isDot || undefined}>
+      {type === NumberedListType.ICON && (
+        <MarkerContent className="numbered-item-marker-content">
+          <GenericIcon icon={icon} rawContent={iconRawContent} />
+        </MarkerContent>
+      )}
+      {type === NumberedListType.NUMBER && (
+        <MarkerContent className="numbered-item-marker-content">{index}</MarkerContent>
+      )}
+      {anchorId && (
+        <MarkerLink className="numbered-item-marker-link" $isDot={isDot}>
+          <MarkerLinkIcon
+            aria-hidden="true"
+            focusable="false"
+            color="--md-numbered-list-marker-text-color"
+          />
+        </MarkerLink>
+      )}
+    </Marker>
+  );
+
+  return (
+    <NumberedItemWrapper
+      data-component-name="Markdoc/NumberedList/NumberedItem"
+      className={className}
+      id={anchorId}
+      $size={size}
+      $isDot={isDot}
+    >
+      <MarkerRail>
+        {anchorId ? (
+          <a
+            href={`#${anchorId}`}
+            {...(headline
+              ? { 'aria-labelledby': headlineTextId }
+              : { 'aria-label': 'Link to this item' })}
+          >
+            {marker}
+          </a>
+        ) : (
+          marker
+        )}
+        <Tail data-testid="numbered-item-tail" $isLast={isLast} />
+      </MarkerRail>
+      <NumberedItemContent>
+        {headline &&
+          createElement(
+            NumberedItemHeadline,
+            { as: `h${headlineLevel ?? 3}` as keyof JSX.IntrinsicElements, id: headlineTextId },
+            headline,
+          )}
+        <NumberedItemBody>{children}</NumberedItemBody>
+      </NumberedItemContent>
+    </NumberedItemWrapper>
+  );
+}
+
+const markerSize = css<{ $size?: string }>`
+  ${({ $size }) =>
+    $size === NumberedListSize.SMALL
+      ? css`
+          width: var(--md-numbered-list-marker-small-size);
+          height: var(--md-numbered-list-marker-small-size);
+          --icon-width: var(--md-numbered-list-icon-small-size);
+          --icon-height: var(--md-numbered-list-icon-small-size);
+        `
+      : css`
+          width: var(--md-numbered-list-marker-medium-size);
+          height: var(--md-numbered-list-marker-medium-size);
+          --icon-width: var(--md-numbered-list-icon-medium-size);
+          --icon-height: var(--md-numbered-list-icon-medium-size);
+        `}
+`;
+
+const Marker = styled.span<{ $type: string; $size: string }>`
+  position: relative;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  border-radius: 50%;
+  color: var(--md-numbered-list-marker-text-color);
+  font-size: var(--md-numbered-list-marker-font-size);
+
+  ${({ $type }) =>
+    $type === NumberedListType.DOT
+      ? css`
+          width: var(--md-numbered-list-dot-size);
+          height: var(--md-numbered-list-dot-size);
+          background-color: var(--text-color-primary);
+        `
+      : css`
+          ${markerSize}
+          background-color: var(--md-numbered-list-marker-bg-color);
+        `}
+`;
+
+const MarkerContent = styled.span`
+  display: flex;
+  align-items: center;
+  justify-content: center;
+`;
+
+const MarkerLink = styled.span<{ $isDot?: boolean }>`
+  display: none;
+  align-items: center;
+  justify-content: center;
+
+  svg {
+    width: var(--icon-width, 16px);
+    height: var(--icon-height, 16px);
+  }
+
+  ${({ $isDot }) =>
+    $isDot &&
+    css`
+      position: absolute;
+      inset-inline-end: calc(100% + var(--md-numbered-list-dot-link-gap));
+    `}
+`;
+
+const MarkerLinkIcon = styled(LinkIcon)`
+  path:first-of-type {
+    fill: var(--md-numbered-list-marker-icon-bg-color);
+  }
+`;
+
+const MarkerRail = styled.span`
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  align-self: stretch;
+  flex-shrink: 0;
+
+  a {
+    display: flex;
+    border-radius: 50%;
+    /* Overrides the global markdown link rule a:not([role='button']), which is more specific. */
+    text-decoration: none !important;
+
+    &:hover,
+    &:focus {
+      text-decoration: none !important;
+    }
+  }
+`;
+
+const Tail = styled.span<{ $isLast: boolean }>`
+  flex: 1 0 0;
+  min-height: var(--spacing-xs);
+  width: var(--md-numbered-list-tail-width);
+  background: ${({ $isLast }) =>
+    $isLast
+      ? 'var(--md-numbered-list-tail-fade-gradient)'
+      : 'var(--md-numbered-list-tail-bg-color)'};
+`;
+
+const NumberedItemHeadline = styled.h3`
+  margin: 0;
+  color: var(--md-numbered-list-headline-text-color);
+  font-size: var(--md-numbered-list-headline-font-size);
+  font-weight: var(--md-numbered-list-headline-font-weight);
+  line-height: var(--md-numbered-list-headline-line-height);
+`;
+
+const NumberedItemBody = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: var(--md-numbered-list-body-gap);
+  color: var(--md-numbered-list-body-text-color);
+  font-size: var(--md-numbered-list-body-font-size);
+
+  > p {
+    margin: 0;
+  }
+`;
+
+const NumberedItemContent = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-unit);
+  flex: 1;
+  min-width: 0;
+  padding-bottom: var(--spacing-sm);
+`;
+
+const NumberedItemWrapper = styled.li<{ $size?: string; $isDot?: boolean }>`
+  display: flex;
+  gap: var(--md-numbered-list-gap);
+  align-items: stretch;
+
+  ${({ $isDot }) =>
+    $isDot &&
+    css`
+      ${MarkerRail} {
+        padding-top: var(--md-numbered-list-dot-rail-padding-top);
+      }
+    `}
+
+  &:last-child ${NumberedItemContent} {
+    padding-bottom: 0;
+  }
+
+  &:hover,
+  &:focus-within {
+    ${Marker} {
+      background-color: ${({ $isDot }) =>
+        $isDot ? 'var(--text-color-primary)' : 'var(--md-numbered-list-marker-bg-color-hover)'};
+    }
+
+    a ${Marker}:not([data-dot]) .numbered-item-marker-content {
+      display: none;
+    }
+
+    a ${Marker} .numbered-item-marker-link {
+      display: flex;
+    }
+  }
+`;

package/src/markdoc/components/NumberedList/NumberedList.tsx

@@ -0,0 +1,37 @@
+import React from 'react';
+import styled from 'styled-components';
+
+import type { JSX, PropsWithChildren } from 'react';
+
+export type NumberedListProps = PropsWithChildren<{
+  className?: string;
+}>;
+
+export function NumberedList({ className, children }: NumberedListProps): JSX.Element | null {
+  if (React.Children.count(children) === 0) {
+    return null;
+  }
+
+  return (
+    <NumberedListWrapper
+      data-component-name="Markdoc/NumberedList/NumberedList"
+      className={className}
+    >
+      {children}
+    </NumberedListWrapper>
+  );
+}
+
+const NumberedListWrapper = styled.ol`
+  display: flex;
+  flex-direction: column;
+  margin: var(--md-numbered-list-margin);
+  padding: 0;
+  list-style: none;
+
+  && {
+    & > li:not(:last-child) {
+      margin-bottom: 0;
+    }
+  }
+`;