@redocly/theme 0.67.0 → 0.68.0-next.1

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;
+    }
+  }
+`;

package/src/markdoc/components/NumberedList/variables.ts

@@ -0,0 +1,39 @@
+import { css } from 'styled-components';
+
+export const markdownNumberedList = css`
+  /**
+  *  @tokens Markdown Numbered List
+  */
+
+  --md-numbered-list-margin: var(--spacing-sm) 0; // @presenter Spacing
+  --md-numbered-list-gap: var(--spacing-base); // @presenter Spacing
+
+  --md-numbered-list-marker-bg-color: var(--color-warm-grey-2); // @presenter Color
+  --md-numbered-list-marker-bg-color-hover: var(--color-warm-grey-3); // @presenter Color
+  --md-numbered-list-marker-icon-bg-color: transparent; // @presenter Color
+  --md-numbered-list-marker-text-color: var(--text-color-primary); // @presenter Color
+  --md-numbered-list-marker-font-size: var(--font-size-base); // @presenter FontSize
+
+  --md-numbered-list-marker-medium-size: 28px; // @presenter Spacing
+  --md-numbered-list-icon-medium-size: 16px; // @presenter Spacing
+  --md-numbered-list-tail-width: 1px; // @presenter Spacing
+  --md-numbered-list-marker-small-size: 24px; // @presenter Spacing
+  --md-numbered-list-icon-small-size: 12px; // @presenter Spacing
+  --md-numbered-list-dot-size: 10px; // @presenter Spacing
+  --md-numbered-list-dot-rail-padding-top: 7px; // @presenter Spacing
+  --md-numbered-list-dot-link-gap: 6px; // @presenter Spacing
+
+  --md-numbered-list-tail-bg-color: var(--md-numbered-list-marker-bg-color); // @presenter Color
+  --md-numbered-list-tail-fade-gradient: linear-gradient(to bottom, var(--md-numbered-list-tail-bg-color), transparent); // @presenter Color
+
+  --md-numbered-list-headline-text-color: var(--text-color-primary); // @presenter Color
+  --md-numbered-list-headline-font-size: var(--font-size-base); // @presenter FontSize
+  --md-numbered-list-headline-font-weight: var(--font-weight-medium); // @presenter FontWeight
+  --md-numbered-list-headline-line-height: var(--line-height-base); // @presenter LineHeight
+
+  --md-numbered-list-body-text-color: var(--text-color-secondary); // @presenter Color
+  --md-numbered-list-body-gap: var(--spacing-xs); // @presenter Spacing
+  --md-numbered-list-body-font-size: var(--font-size-base); // @presenter FontSize
+
+  // @tokens End
+`;

package/src/markdoc/components/default.ts

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

package/src/markdoc/default.ts

@@ -14,6 +14,8 @@ import { markdocExample } from '@redocly/theme/markdoc/tags/markdoc-example';
 import { partial } from '@redocly/theme/markdoc/tags/partial';
 import { tab } from '@redocly/theme/markdoc/tags/tab';
 import { tabs } from '@redocly/theme/markdoc/tags/tabs';
+import { numberedItem } from '@redocly/theme/markdoc/tags/numbered-item';
+import { numberedList } from '@redocly/theme/markdoc/tags/numbered-list';
 import { debug } from '@redocly/theme/markdoc/tags/debug';
 import { codeSnippet } from '@redocly/theme/markdoc/tags/code-snippet';
 import { inlineSvg } from '@redocly/theme/markdoc/tags/inline-svg';
@@ -38,6 +40,8 @@ export const tags = {
   [partial.tagName]: partial.schema,
   [tab.tagName]: tab.schema,
   [tabs.tagName]: tabs.schema,
+  [numberedItem.tagName]: numberedItem.schema,
+  [numberedList.tagName]: numberedList.schema,
   [codeSnippet.tagName]: codeSnippet.schema,
   [inlineSvg.tagName]: inlineSvg.schema,
   [cards.tagName]: cards.schema,

package/src/markdoc/tags/numbered-item.ts

@@ -0,0 +1,46 @@
+import markdoc from '@markdoc/markdoc';
+
+import type { MarkdocSchemaWrapper } from '@redocly/theme/markdoc/tags/types';
+
+import { isTag } from '@redocly/theme/core/utils';
+
+const HEADING_TAG_NAME = /^(Heading|h[1-6])$/;
+
+export const numberedItem: MarkdocSchemaWrapper = {
+  schema: {
+    transform(node, config) {
+      const attributes = node.transformAttributes(config);
+      const children = node.transformChildren(config);
+      const [first, ...body] = children;
+
+      if (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.Tag(
+          'NumberedItem',
+          {
+            ...attributes,
+            headline: first.children,
+            anchorId: first.attributes.id,
+            headlineLevel,
+          },
+          body,
+        );
+      }
+
+      return new markdoc.Tag('NumberedItem', attributes, children);
+    },
+    attributes: {
+      icon: { type: String, resolver: 'relativeOrCdnIcon' },
+      iconRawContent: {
+        // internal use only
+        type: String,
+        render: true,
+      },
+    },
+  },
+  tagName: 'numbered-item',
+};

package/src/markdoc/tags/numbered-list.ts

@@ -0,0 +1,34 @@
+import markdoc from '@markdoc/markdoc';
+
+import type { Tag } from '@markdoc/markdoc';
+import type { MarkdocSchemaWrapper } from '@redocly/theme/markdoc/tags/types';
+
+import { isTag } from '@redocly/theme/core/utils';
+
+export const numberedList: MarkdocSchemaWrapper = {
+  schema: {
+    transform(node, config) {
+      const attributes = node.transformAttributes(config);
+      const items = node
+        .transformChildren(config)
+        .filter((child): child is Tag => isTag(child) && child.name === 'NumberedItem');
+
+      items.forEach((item, index) => {
+        item.attributes = {
+          ...item.attributes,
+          type: attributes.type,
+          size: attributes.size,
+          index: index + 1,
+          isLast: index === items.length - 1,
+        };
+      });
+
+      return new markdoc.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',
+};