@redocly/theme 0.69.0-next.2 → 0.69.0-next.4

package/lib/components/Badge/Badge.d.ts

@@ -5,5 +5,7 @@ export type BadgeProps = PropsWithChildren<{
     key?: string;
     className?: string;
     icon?: string;
+    /** Inline SVG content for the icon */
+    iconRawContent?: string;
 }>;
-export declare function Badge({ icon, children, deprecated, color, ...props }: BadgeProps): JSX.Element;
+export declare function Badge({ icon, iconRawContent, children, deprecated, color, ...props }: BadgeProps): JSX.Element;

package/lib/components/Badge/Badge.js

@@ -52,9 +52,9 @@ const react_1 = __importDefault(require("react"));
 const styled_components_1 = __importStar(require("styled-components"));
 const GenericIcon_1 = require("../../icons/GenericIcon/GenericIcon");
 function Badge(_a) {
-    var { icon, children, deprecated, color } = _a, props = __rest(_a, ["icon", "children", "deprecated", "color"]);
+    var { icon, iconRawContent, children, deprecated, color } = _a, props = __rest(_a, ["icon", "iconRawContent", "children", "deprecated", "color"]);
     return (react_1.default.createElement(BadgeComponent, Object.assign({}, props, { $color: color, $deprecated: deprecated, "data-component-name": "Badge/Badge" }),
-        icon ? react_1.default.createElement(BadgeIcon, { icon: icon }) : null,
+        icon || iconRawContent ? react_1.default.createElement(BadgeIcon, { icon: icon, rawContent: iconRawContent }) : null,
         children));
 }
 const BadgeComponent = styled_components_1.default.span `
@@ -82,5 +82,10 @@ const BadgeIcon = (0, styled_components_1.default)(GenericIcon_1.GenericIcon) `
   margin-right: var(--spacing-xxs);
   flex-shrink: 0;
   vertical-align: middle;
+
+  /* For inline SVG to align properly */
+  svg {
+    display: block;
+  }
 `;
 //# sourceMappingURL=Badge.js.map

package/lib/core/hooks/use-active-heading.js

@@ -5,16 +5,20 @@ const react_1 = require("react");
 const react_router_1 = require("react-router");
 const utils_1 = require("../utils");
 const constants_1 = require("../constants");
+const TARGET_TOLERANCE = 2;
 function useActiveHeading(contentElement, displayedHeadings) {
     const [heading, setHeading] = (0, react_1.useState)(undefined);
     const [headingElements, setHeadingElements] = (0, react_1.useState)([]);
     const headingElementsRef = (0, react_1.useRef)({});
     const displayedHeadingsRef = (0, react_1.useRef)(displayedHeadings);
     const lockObserver = (0, react_1.useRef)(false);
+    const clickScroll = (0, react_1.useRef)(null);
     const location = (0, react_router_1.useLocation)();
     (0, react_1.useEffect)(() => {
         setHeading(undefined);
         headingElementsRef.current = {};
+        clickScroll.current = null;
+        lockObserver.current = false;
     }, [location.pathname]);
     (0, react_1.useEffect)(() => {
         displayedHeadingsRef.current = displayedHeadings;
@@ -98,13 +102,13 @@ function useActiveHeading(contentElement, displayedHeadings) {
     }, [calculateVirtualPositions]);
     const intersectionCallback = (0, react_1.useCallback)((entries) => {
         var _a, _b, _c;
-        if (lockObserver.current) {
-            return;
-        }
         headingElementsRef.current = entries.reduce((map, entry) => {
             map[entry.target.id] = entry;
             return map;
         }, headingElementsRef.current);
+        if (lockObserver.current) {
+            return;
+        }
         if (isTopOfPage()) {
             const newHeading = ((_a = headingElements[0]) === null || _a === void 0 ? void 0 : _a.id) || undefined;
             setHeading(newHeading);
@@ -145,18 +149,56 @@ function useActiveHeading(contentElement, displayedHeadings) {
         }
         setHeading(visibleHeadings[0].target.id);
     }, [getIndexFromId, headingElements, getTriggerOffset, findActiveHeaderByVirtualPosition]);
+    const releaseClickScroll = (0, react_1.useCallback)(() => {
+        clickScroll.current = null;
+        lockObserver.current = false;
+    }, []);
+    const trackClickScroll = (0, react_1.useCallback)(() => {
+        const clickScrollState = clickScroll.current;
+        if (!clickScrollState) {
+            return;
+        }
+        const { top } = clickScrollState.target.getBoundingClientRect();
+        if (clickScrollState.reached) {
+            if (top >= 0 && top <= getTriggerOffset()) {
+                return;
+            }
+        }
+        else {
+            const distance = Math.abs(top - clickScrollState.scrollMargin);
+            if (distance <= TARGET_TOLERANCE) {
+                clickScrollState.reached = true;
+                return;
+            }
+            if (distance <= clickScrollState.closestDistance + TARGET_TOLERANCE) {
+                clickScrollState.closestDistance = Math.min(clickScrollState.closestDistance, distance);
+                return;
+            }
+        }
+        releaseClickScroll();
+        intersectionCallback([]);
+    }, [releaseClickScroll, intersectionCallback, getTriggerOffset]);
     const handleHeadingClick = (0, react_1.useCallback)((headingId) => {
-        lockObserver.current = true;
+        releaseClickScroll();
         setHeading(headingId);
-        const headingElement = headingElements.find((el) => el.id === headingId);
-        if (headingElement && headingElement.scrollIntoView) {
-            headingElement.scrollIntoView({ behavior: 'smooth', block: 'start' });
-        }
-        setTimeout(() => {
-            headingElementsRef.current = {};
-            lockObserver.current = false;
-        }, 300);
-    }, [headingElements]);
+        const target = document.getElementById(headingId) || headingElements.find((el) => el.id === headingId);
+        if (!(target === null || target === void 0 ? void 0 : target.scrollIntoView)) {
+            return;
+        }
+        target.scrollIntoView({ behavior: 'smooth', block: 'start' });
+        if (!target.getClientRects().length) {
+            return;
+        }
+        const scrollMargin = parseFloat(getComputedStyle(target).scrollMarginTop) || 0;
+        const distance = Math.abs(target.getBoundingClientRect().top - scrollMargin);
+        lockObserver.current = true;
+        clickScroll.current = {
+            target,
+            scrollMargin,
+            closestDistance: distance,
+            reached: distance <= TARGET_TOLERANCE,
+        };
+    }, [headingElements, releaseClickScroll]);
     (0, react_1.useEffect)(() => {
         var _a;
         if (!contentElement) {
@@ -203,8 +245,10 @@ function useActiveHeading(contentElement, displayedHeadings) {
         });
         const handleScroll = () => {
             var _a;
-            if (lockObserver.current)
+            if (clickScroll.current) {
+                trackClickScroll();
                 return;
+            }
             if (isTopOfPage()) {
                 setHeading(((_a = headingElements[0]) === null || _a === void 0 ? void 0 : _a.id) || undefined);
             }
@@ -214,7 +258,7 @@ function useActiveHeading(contentElement, displayedHeadings) {
             observer.disconnect();
             window.removeEventListener('scroll', handleScroll);
         };
-    }, [headingElements, intersectionCallback, getTriggerOffset]);
+    }, [headingElements, intersectionCallback, getTriggerOffset, trackClickScroll]);
     return { heading, handleHeadingClick };
 }
 //# sourceMappingURL=use-active-heading.js.map

package/lib/markdoc/components/Cards/Card.d.ts

@@ -10,7 +10,14 @@ export type CardProps = React.PropsWithChildren<{
     layout?: 'horizontal' | 'vertical' | 'combined';
     variant?: 'filled' | 'outlined' | 'elevated' | 'ghost';
     iconVariant?: 'filled' | 'ghost';
+    iconColor?: string;
     align?: 'start' | 'center' | 'end';
     to?: string;
+    linkIcon?: 'chevron' | 'arrow';
+    cta?: React.ReactNode;
+    badge?: string;
+    badgeColor?: string;
+    badgeIcon?: string;
+    badgeIconRawContent?: string;
 }>;
-export declare function Card({ title, image, icon, iconRawContent, imagePosition, iconPosition, layout, variant, lineClamp, iconVariant, align, to, children, }: CardProps): React.JSX.Element;
+export declare function Card({ title, image, icon, iconRawContent, imagePosition, iconPosition, layout, variant, lineClamp, iconVariant, iconColor, align, to, cta, linkIcon, badge, badgeColor, badgeIcon, badgeIconRawContent, children, }: CardProps): React.JSX.Element;

package/lib/markdoc/components/Cards/Card.js

@@ -7,10 +7,12 @@ exports.Card = Card;
 const react_1 = __importDefault(require("react"));
 const styled_components_1 = __importDefault(require("styled-components"));
 const ChevronRightIcon_1 = require("../../../icons/ChevronRightIcon/ChevronRightIcon");
+const ArrowUpRightIcon_1 = require("../../../icons/ArrowUpRightIcon/ArrowUpRightIcon");
 const CardImage_1 = require("../../../markdoc/components/Cards/CardImage");
 const CardIcon_1 = require("../../../markdoc/components/Cards/CardIcon");
+const CardBadge_1 = require("../../../markdoc/components/Cards/CardBadge");
 const Link_1 = require("../../../components/Link/Link");
-function Card({ title = '', image, icon, iconRawContent, imagePosition = 'start', iconPosition = 'auto', layout = 'vertical', variant = 'filled', lineClamp, iconVariant = 'filled', align = 'start', to, children, }) {
+function Card({ title = '', image, icon, iconRawContent, imagePosition = 'start', iconPosition = 'auto', layout = 'vertical', variant = 'filled', lineClamp, iconVariant = 'filled', iconColor, align = 'start', to, cta, linkIcon, badge, badgeColor, badgeIcon, badgeIconRawContent, children, }) {
     const titleNoSpaces = title === null || title === void 0 ? void 0 : title.replace(/\s+/g, '-').toLowerCase();
     const cardTitleId = `card-title-${titleNoSpaces}`;
     const justifyContent = align === 'center' ? 'center' : align === 'end' ? 'flex-end' : 'flex-start';
@@ -20,12 +22,20 @@ function Card({ title = '', image, icon, iconRawContent, imagePosition = 'start'
         react_1.default.createElement(react_1.default.Fragment, null,
             image ? react_1.default.createElement(CardImage_1.CardImage, { src: image, alt: title, position: imagePosition }) : null,
             react_1.default.createElement(CardContentWrapper, { $layout: layout, $alignItems: alignItems, $textAlign: textAlign, $hasImage: image !== undefined },
-                icon && (react_1.default.createElement(CardIcon_1.CardIcon, { variant: iconVariant, src: icon, rawContent: iconRawContent, position: iconPosition })),
+                icon && (react_1.default.createElement(CardIcon_1.CardIcon, { variant: iconVariant, src: icon, rawContent: iconRawContent, position: iconPosition, color: iconColor })),
                 react_1.default.createElement(ContentWrapper, null,
-                    react_1.default.createElement(Title, { id: cardTitleId, $isCardLink: !!to, $justifyContent: justifyContent },
-                        title,
-                        variant == 'ghost' && !!to && react_1.default.createElement(CardLinkIcon, null)),
-                    react_1.default.createElement(Body, { $lineClamp: lineClamp }, children))))));
+                    react_1.default.createElement(TitleWrapper, { id: cardTitleId, $isCardLink: !!to, $justifyContent: justifyContent },
+                        react_1.default.createElement(Title, null,
+                            title,
+                            !!to && !!linkIcon && (react_1.default.createElement(CardLinkIcon, { as: linkIcon === 'arrow' ? ArrowUpRightIcon_1.ArrowUpRightIcon : undefined }))),
+                        !!badge && (react_1.default.createElement(CardBadge_1.CardBadge, { color: badgeColor, icon: badgeIcon, iconRawContent: badgeIconRawContent }, badge))),
+                    react_1.default.createElement(Body, { $lineClamp: lineClamp }, children),
+                    !!to && !!cta && (react_1.default.createElement(Cta, { $justifyContent: justifyContent },
+                        react_1.default.createElement(CtaText, null,
+                            " ",
+                            cta,
+                            " "),
+                        react_1.default.createElement(CtaIcon, null))))))));
 }
 const CardContentWrapper = styled_components_1.default.div `
   display: flex;
@@ -44,24 +54,26 @@ const ContentWrapper = styled_components_1.default.div `
   gap: var(--card-content-gap);
   width: 100%;
 `;
-const Title = styled_components_1.default.h3 `
-  margin: var(--card-title-margin);
-  font-weight: var(--card-title-font-weight);
+const TitleWrapper = styled_components_1.default.div `
   color: var(--card-title-text-color);
   display: flex;
   align-items: center;
+  flex-wrap: wrap;
+  row-gap: var(--card-title-row-gap);
   justify-content: ${({ $justifyContent }) => $justifyContent};
   width: 100%;
 `;
+const Title = styled_components_1.default.h3 `
+  margin: var(--card-title-margin);
+  font-weight: var(--card-title-font-weight);
+`;
+// The `as` prop selects the icon; the chevron is the default target.
 const CardLinkIcon = (0, styled_components_1.default)(ChevronRightIcon_1.ChevronRightIcon) `
   width: var(--card-link-icon-width);
   height: var(--card-link-icon-height);
-  color: var(--card-link-icon-color);
+  color: var(--icon-color-secondary);
   margin-left: var(--spacing-xxs);
-  opacity: 0;
-  transition:
-    opacity 0.3s,
-    transform 0.3s;
+  margin-top: calc(var(--spacing-xxs) / 2);
 `;
 const Body = styled_components_1.default.div `
   color: var(--card-text-color);
@@ -84,6 +96,26 @@ const Body = styled_components_1.default.div `
     margin-bottom: 0;
   }
 `;
+const Cta = styled_components_1.default.div `
+  display: flex;
+  gap: var(--card-cta-gap);
+  align-items: center;
+  margin-top: var(--card-cta-margin-top);
+  color: var(--card-cta-text-color);
+  font-size: var(--card-cta-font-size);
+  justify-content: ${({ $justifyContent }) => $justifyContent};
+    
+  && > * {
+    cursor: pointer;
+  }  
+`;
+const CtaText = styled_components_1.default.span `
+  font-weight: var(--card-cta-font-weight);
+`;
+const CtaIcon = (0, styled_components_1.default)(ChevronRightIcon_1.ChevronRightIcon) `
+  width: var(--card-cta-icon-width);
+  height: var(--card-cta-icon-height);
+`;
 const CardWrapper = styled_components_1.default.div.attrs(({ $isCardLink, $variant }) => ({
     className: getCardWrapperClass($isCardLink, $variant),
 })) `
@@ -112,6 +144,13 @@ const CardWrapper = styled_components_1.default.div.attrs(({ $isCardLink, $varia
       height: 100%;
       object-fit: cover;
     `}
+  } 
+    
+  &:hover,
+  &:focus-within {
+    ${Cta} {
+      color: var(--card-link-icon-color);
+    }
   }
 
   &.card-link {
@@ -130,8 +169,8 @@ const CardWrapper = styled_components_1.default.div.attrs(({ $isCardLink, $varia
         background-color: var(--card-icon-bg-color-hover);
       }
 
-      svg {
-        opacity: 1;
+      ${CardLinkIcon} {
+        color: var(--card-link-icon-color);
       }
     }
   }

package/lib/markdoc/components/Cards/CardBadge.d.ts

@@ -0,0 +1,9 @@
+import React from 'react';
+export type CardBadgeProps = React.PropsWithChildren<{
+    color?: string;
+    icon?: string;
+    /** Inline SVG content for the icon */
+    iconRawContent?: string;
+    className?: string;
+}>;
+export declare function CardBadge({ color, icon, iconRawContent, className, children }: CardBadgeProps): React.JSX.Element;

package/lib/markdoc/components/Cards/CardBadge.js

@@ -0,0 +1,30 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CardBadge = CardBadge;
+const react_1 = __importDefault(require("react"));
+const styled_components_1 = __importDefault(require("styled-components"));
+const Badge_1 = require("../../../components/Badge/Badge");
+function CardBadge({ color, icon, iconRawContent, className, children }) {
+    // `tag-default` keeps a badge grey when the name is absent or unknown.
+    const classNames = ['tag-default', color && `tag-${color}`, className].filter(Boolean).join(' ');
+    return (react_1.default.createElement(CardBadgeWrapper, { className: classNames, icon: icon, iconRawContent: iconRawContent }, children));
+}
+const CardBadgeWrapper = (0, styled_components_1.default)(Badge_1.Badge) `
+  display: flex;
+  align-items: center;
+  margin: var(--card-badge-margin);
+  padding: var(--card-badge-padding);
+  border-radius: var(--card-badge-border-radius);
+  font-size: var(--card-badge-font-size);
+  font-weight: var(--card-badge-font-weight);
+  line-height: var(--card-badge-line-height);
+  white-space: nowrap;
+  flex-shrink: 0;
+
+  --badge-text-color: var(--tag-color);
+  --badge-bg-color: var(--tag-bg-color);
+`;
+//# sourceMappingURL=CardBadge.js.map

package/lib/markdoc/components/Cards/CardIcon.d.ts

@@ -1,15 +1,16 @@
 import React from 'react';
 export type CardIconProps = {
-    variant?: string;
+    variant?: 'filled' | 'ghost';
     src: string;
     rawContent?: string;
     position?: 'auto' | 'start' | 'center' | 'end';
+    color?: string;
 };
-export declare function CardIcon({ variant, src, rawContent, position }: CardIconProps): React.JSX.Element;
+export declare function CardIcon({ variant, src, rawContent, position, color }: CardIconProps): React.JSX.Element;
 export declare const CardIconWrapper: import("styled-components/dist/types").IStyledComponentBase<"web", import("styled-components").FastOmit<import("styled-components").FastOmit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "$position" | "$variant"> & {
-    $variant?: string;
+    $variant?: 'filled' | 'ghost';
     $position?: string;
 }, never> & Partial<Pick<import("styled-components").FastOmit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "$position" | "$variant"> & {
-    $variant?: string;
+    $variant?: 'filled' | 'ghost';
     $position?: string;
 }, never>>> & string;

package/lib/markdoc/components/Cards/CardIcon.js

@@ -8,14 +8,17 @@ exports.CardIcon = CardIcon;
 const react_1 = __importDefault(require("react"));
 const styled_components_1 = __importDefault(require("styled-components"));
 const GenericIcon_1 = require("../../../icons/GenericIcon/GenericIcon");
-function CardIcon({ variant, src, rawContent, position }) {
-    return (react_1.default.createElement(exports.CardIconWrapper, { $variant: variant, $position: position },
+function CardIcon({ variant, src, rawContent, position, color }) {
+    return (react_1.default.createElement(exports.CardIconWrapper, { className: color && `card-icon-color-${color}`, $variant: variant, $position: position },
         react_1.default.createElement(GenericIcon_1.GenericIcon, { icon: src, rawContent: rawContent })));
 }
 exports.CardIconWrapper = styled_components_1.default.div `
+  --card-icon-bg-color-hover: ${({ $variant }) => $variant === 'ghost' && 'transparent'};
   --icon-width: var(--card-icon-width);
   --icon-height: var(--card-icon-height);
   color: var(--card-icon-color);
+  /* An inline SVG fills from this. */
+  --icon-color: var(--card-icon-color);
 
   display: flex;
   align-self: ${({ $position }) => ($position ? $position : 'auto')};
@@ -24,7 +27,7 @@ exports.CardIconWrapper = styled_components_1.default.div `
   min-height: var(--card-icon-height);
   flex-shrink: 0;
 
-  padding: var(--card-icon-padding);
+  padding: ${({ $variant }) => ($variant === 'ghost' ? 0 : `var(--card-icon-padding)`)};
   border: ${({ $variant }) => $variant !== 'ghost' && `var(--card-icon-border)`};
   border-radius: var(--card-icon-border-radius);
   overflow: hidden;

package/lib/markdoc/components/Cards/variables.dark.js

@@ -23,6 +23,38 @@ exports.cardsDarkMode = (0, styled_components_1.css) `
     --card-box-shadow: 0px 8px 24px -4px #00000014, 0px 6px 12px -6px #0000001F;
     --card-box-shadow-hover: 0px 14px 64px -4px #0000001F, 0px 8px 22px -6px #0000001F;
   }
+
+  .card-icon-color-green {
+    --card-icon-color: var(--color-green-7);
+  }
+
+  .card-icon-color-grey {
+    --card-icon-color: var(--color-warm-grey-8);
+  }
+
+  .card-icon-color-turquoise {
+    --card-icon-color: var(--color-turquoise-6);
+  }
+
+  .card-icon-color-magenta {
+    --card-icon-color: var(--color-magenta-4);
+  }
+
+  .card-icon-color-carrot {
+    --card-icon-color: var(--color-carrot-6);
+  }
+
+  .card-icon-color-grass {
+    --card-icon-color: var(--color-grass-7);
+  }
+
+  .card-icon-color-persian-green {
+    --card-icon-color: var(--color-persian-green-7);
+  }
+
+  .card-icon-color-sky {
+    --card-icon-color: var(--color-sky-6);
+  }
 `;
 /* eslint-enable theme/no-raw-colors-in-styles */
 //# sourceMappingURL=variables.dark.js.map

package/lib/markdoc/components/Cards/variables.js

@@ -23,8 +23,8 @@ exports.cards = (0, styled_components_1.css) `
   --card-border-radius: var(--border-radius-xl);
   --card-border-style: solid;
   --card-link-cursor: pointer;
-  --card-link-icon-width: var(--h3-font-size);
-  --card-link-icon-height: var(--h3-font-size);
+  --card-link-icon-width: 14px;
+  --card-link-icon-height: 14px;
   --card-border-width: 1px;
   --card-image-border-radius: var(--border-radius-md);
   --card-image-aspect-ratio: 16 / 9;
@@ -35,12 +35,26 @@ exports.cards = (0, styled_components_1.css) `
   --card-icon-height: var(--card-icon-size);
   --card-icon-width: var(--card-icon-size);
   --card-icon-gap: var(--spacing-base);
-  --card-title-margin: 0;
+  --card-title-margin: 0 var(--spacing-xs) 0 0;
   --card-title-font-weight: var(--font-weight-semibold);
+  --card-title-row-gap: var(--spacing-xxs);
   --card-content-gap: 4px;
   --card-padding: 16px 20px;
   --card-body-font-size: var(--font-size-base);
   --card-body-line-height: var(--line-height-base);
+  --card-cta-margin-top: var(--spacing-base);
+  --card-cta-gap: var(--spacing-xxs);
+  --card-cta-font-size: var(--font-size-base);
+  --card-cta-font-weight: var(--font-weight-regular);  
+  --card-cta-text-color: var(--text-color-secondary);
+  --card-cta-icon-width: 14px;
+  --card-cta-icon-height: 14px;
+  --card-badge-margin: 0 var(--spacing-xxs) 0 0 ;
+  --card-badge-padding: 0 var(--spacing-xxs);
+  --card-badge-border-radius: var(--border-radius);
+  --card-badge-font-size: var(--font-size-sm);
+  --card-badge-font-weight: var(--font-weight-regular);
+  --card-badge-line-height: var(--line-height-sm);
 
   /**
    * @tokens Card variants
@@ -84,6 +98,64 @@ exports.cards = (0, styled_components_1.css) `
     --card-hover-transition: initial;
   }
 
+  /**
+   * @tokens Card icon colors
+   */
+  .card-icon-color-red {
+    --card-icon-color: var(--color-red-7);
+  }
+
+  .card-icon-color-green {
+    --card-icon-color: var(--color-green-8);
+  }
+
+  .card-icon-color-blue {
+    --card-icon-color: var(--color-blue-7);
+  }
+
+  .card-icon-color-grey {
+    --card-icon-color: var(--text-color-secondary);
+  }
+
+  .card-icon-color-turquoise {
+    --card-icon-color: var(--color-turquoise-8);
+  }
+
+  .card-icon-color-magenta {
+    --card-icon-color: var(--color-magenta-7);
+  }
+
+  .card-icon-color-purple {
+    --card-icon-color: var(--color-purple-7);
+  }
+
+  .card-icon-color-carrot {
+    --card-icon-color: var(--color-carrot-8);
+  }
+
+  .card-icon-color-raspberry {
+    --card-icon-color: var(--color-raspberry-7);
+  }
+
+  .card-icon-color-orange {
+    --card-icon-color: var(--color-orange-7);
+  }
+
+  .card-icon-color-grass {
+    --card-icon-color: var(--color-grass-8);
+  }
+
+  .card-icon-color-persian-green {
+    --card-icon-color: var(--color-persian-green-8);
+  }
+
+  .card-icon-color-sky {
+    --card-icon-color: var(--color-sky-8);
+  }
+
+  .card-icon-color-blueberry {
+    --card-icon-color: var(--color-blueberry-7);
+  }
 `;
-/* eslint-enable theme/no-raw-colors-in-styles */ 
+/* eslint-enable theme/no-raw-colors-in-styles */
 //# sourceMappingURL=variables.js.map

package/lib/markdoc/tags/card.js

@@ -52,7 +52,21 @@ exports.card = {
                 type: String,
                 matches: ['filled', 'ghost'],
             },
+            iconColor: { type: String },
             to: { type: String, resolver: 'link' },
+            linkIcon: {
+                type: String,
+                matches: ['arrow', 'chevron'],
+            },
+            cta: { type: String },
+            badge: { type: String },
+            badgeColor: { type: String },
+            badgeIcon: { type: String, resolver: 'relativeOrCdnIcon' },
+            badgeIconRawContent: {
+                // internal use only
+                type: String,
+                render: true,
+            },
         },
     },
     tagName: 'card',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redocly/theme",
-  "version": "0.69.0-next.2",
+  "version": "0.69.0-next.4",
   "description": "Shared UI components lib",
   "keywords": [
     "theme",
@@ -68,12 +68,12 @@
     "vitest": "4.1.10",
     "vitest-when": "0.6.2",
     "webpack": "5.105.2",
-    "@redocly/realm-asyncapi-sdk": "0.15.0-next.1"
+    "@redocly/realm-asyncapi-sdk": "0.15.0-next.2"
   },
   "dependencies": {
     "@tanstack/react-query": "5.62.3",
     "@tanstack/react-virtual": "3.13.0",
-    "@xyflow/react": "^12.8.2",
+    "@xyflow/react": "12.8.3",
     "copy-to-clipboard": "3.3.3",
     "file-saver": "2.0.5",
     "highlight-words-core": "1.2.2",

package/src/components/Badge/Badge.tsx

@@ -11,9 +11,18 @@ export type BadgeProps = PropsWithChildren<{
   key?: string;
   className?: string;
   icon?: string;
+  /** Inline SVG content for the icon */
+  iconRawContent?: string;
 }>;
 
-export function Badge({ icon, children, deprecated, color, ...props }: BadgeProps): JSX.Element {
+export function Badge({
+  icon,
+  iconRawContent,
+  children,
+  deprecated,
+  color,
+  ...props
+}: BadgeProps): JSX.Element {
   return (
     <BadgeComponent
       {...props}
@@ -21,7 +30,7 @@ export function Badge({ icon, children, deprecated, color, ...props }: BadgeProp
       $deprecated={deprecated}
       data-component-name="Badge/Badge"
     >
-      {icon ? <BadgeIcon icon={icon} /> : null}
+      {icon || iconRawContent ? <BadgeIcon icon={icon} rawContent={iconRawContent} /> : null}
       {children}
     </BadgeComponent>
   );
@@ -54,4 +63,9 @@ const BadgeIcon = styled(GenericIcon)`
   margin-right: var(--spacing-xxs);
   flex-shrink: 0;
   vertical-align: middle;
+
+  /* For inline SVG to align properly */
+  svg {
+    display: block;
+  }
 `;

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

@@ -8,6 +8,15 @@ type HeadingEntry = {
   [key: string]: IntersectionObserverEntry;
 };
 
+type ClickScroll = {
+  target: HTMLElement;
+  scrollMargin: number;
+  closestDistance: number;
+  reached: boolean;
+};
+
+const TARGET_TOLERANCE = 2;
+
 export function useActiveHeading(
   contentElement: HTMLDivElement | null,
   displayedHeadings?: Array<{ id: string; depth: number } | null>,
@@ -17,11 +26,14 @@ export function useActiveHeading(
   const headingElementsRef = useRef<HeadingEntry>({});
   const displayedHeadingsRef = useRef(displayedHeadings);
   const lockObserver = useRef<boolean>(false);
+  const clickScroll = useRef<ClickScroll | null>(null);
   const location = useLocation();
 
   useEffect(() => {
     setHeading(undefined);
     headingElementsRef.current = {};
+    clickScroll.current = null;
+    lockObserver.current = false;
   }, [location.pathname]);
 
   useEffect(() => {
@@ -133,10 +145,6 @@ export function useActiveHeading(
 
   const intersectionCallback = useCallback(
     (entries: IntersectionObserverEntry[]) => {
-      if (lockObserver.current) {
-        return;
-      }
-
       headingElementsRef.current = entries.reduce(
         (map: HeadingEntry, entry: IntersectionObserverEntry) => {
           map[entry.target.id] = entry;
@@ -145,6 +153,10 @@ export function useActiveHeading(
         headingElementsRef.current,
       );
 
+      if (lockObserver.current) {
+        return;
+      }
+
       if (isTopOfPage()) {
         const newHeading = headingElements[0]?.id || undefined;
         setHeading(newHeading);
@@ -202,22 +214,71 @@ export function useActiveHeading(
     [getIndexFromId, headingElements, getTriggerOffset, findActiveHeaderByVirtualPosition],
   );
 
+  const releaseClickScroll = useCallback(() => {
+    clickScroll.current = null;
+    lockObserver.current = false;
+  }, []);
+
+  const trackClickScroll = useCallback(() => {
+    const clickScrollState = clickScroll.current;
+    if (!clickScrollState) {
+      return;
+    }
+
+    const { top } = clickScrollState.target.getBoundingClientRect();
+
+    if (clickScrollState.reached) {
+      if (top >= 0 && top <= getTriggerOffset()) {
+        return;
+      }
+    } else {
+      const distance = Math.abs(top - clickScrollState.scrollMargin);
+
+      if (distance <= TARGET_TOLERANCE) {
+        clickScrollState.reached = true;
+        return;
+      }
+
+      if (distance <= clickScrollState.closestDistance + TARGET_TOLERANCE) {
+        clickScrollState.closestDistance = Math.min(clickScrollState.closestDistance, distance);
+        return;
+      }
+    }
+
+    releaseClickScroll();
+    intersectionCallback([]);
+  }, [releaseClickScroll, intersectionCallback, getTriggerOffset]);
+
   const handleHeadingClick = useCallback(
     (headingId: string) => {
-      lockObserver.current = true;
+      releaseClickScroll();
       setHeading(headingId);
 
-      const headingElement = headingElements.find((el) => el.id === headingId);
-      if (headingElement && headingElement.scrollIntoView) {
-        headingElement.scrollIntoView({ behavior: 'smooth', block: 'start' });
+      const target =
+        document.getElementById(headingId) || headingElements.find((el) => el.id === headingId);
+
+      if (!target?.scrollIntoView) {
+        return;
+      }
+
+      target.scrollIntoView({ behavior: 'smooth', block: 'start' });
+
+      if (!target.getClientRects().length) {
+        return;
       }
 
-      setTimeout(() => {
-        headingElementsRef.current = {};
-        lockObserver.current = false;
-      }, 300);
+      const scrollMargin = parseFloat(getComputedStyle(target).scrollMarginTop) || 0;
+      const distance = Math.abs(target.getBoundingClientRect().top - scrollMargin);
+
+      lockObserver.current = true;
+      clickScroll.current = {
+        target,
+        scrollMargin,
+        closestDistance: distance,
+        reached: distance <= TARGET_TOLERANCE,
+      };
     },
-    [headingElements],
+    [headingElements, releaseClickScroll],
   );
 
   useEffect(() => {
@@ -268,7 +329,10 @@ export function useActiveHeading(
     });
 
     const handleScroll = () => {
-      if (lockObserver.current) return;
+      if (clickScroll.current) {
+        trackClickScroll();
+        return;
+      }
 
       if (isTopOfPage()) {
         setHeading(headingElements[0]?.id || undefined);
@@ -281,7 +345,7 @@ export function useActiveHeading(
       observer.disconnect();
       window.removeEventListener('scroll', handleScroll);
     };
-  }, [headingElements, intersectionCallback, getTriggerOffset]);
+  }, [headingElements, intersectionCallback, getTriggerOffset, trackClickScroll]);
 
   return { heading, handleHeadingClick };
 }

package/src/markdoc/components/Cards/Card.tsx

@@ -2,8 +2,10 @@ import React from 'react';
 import styled from 'styled-components';
 
 import { ChevronRightIcon } from '@redocly/theme/icons/ChevronRightIcon/ChevronRightIcon';
+import { ArrowUpRightIcon } from '@redocly/theme/icons/ArrowUpRightIcon/ArrowUpRightIcon';
 import { CardImage } from '@redocly/theme/markdoc/components/Cards/CardImage';
 import { CardIcon, CardIconWrapper } from '@redocly/theme/markdoc/components/Cards/CardIcon';
+import { CardBadge } from '@redocly/theme/markdoc/components/Cards/CardBadge';
 import { Link } from '@redocly/theme/components/Link/Link';
 
 export type CardProps = React.PropsWithChildren<{
@@ -17,8 +19,15 @@ export type CardProps = React.PropsWithChildren<{
   layout?: 'horizontal' | 'vertical' | 'combined';
   variant?: 'filled' | 'outlined' | 'elevated' | 'ghost';
   iconVariant?: 'filled' | 'ghost';
+  iconColor?: string;
   align?: 'start' | 'center' | 'end';
   to?: string;
+  linkIcon?: 'chevron' | 'arrow';
+  cta?: React.ReactNode;
+  badge?: string;
+  badgeColor?: string;
+  badgeIcon?: string;
+  badgeIconRawContent?: string;
 }>;
 
 export function Card({
@@ -32,8 +41,15 @@ export function Card({
   variant = 'filled',
   lineClamp,
   iconVariant = 'filled',
+  iconColor,
   align = 'start',
   to,
+  cta,
+  linkIcon,
+  badge,
+  badgeColor,
+  badgeIcon,
+  badgeIconRawContent,
   children,
 }: CardProps) {
   const titleNoSpaces = title?.replace(/\s+/g, '-').toLowerCase();
@@ -66,14 +82,30 @@ export function Card({
               src={icon}
               rawContent={iconRawContent}
               position={iconPosition}
+              color={iconColor}
             />
           )}
           <ContentWrapper>
-            <Title id={cardTitleId} $isCardLink={!!to} $justifyContent={justifyContent}>
-              {title}
-              {variant == 'ghost' && !!to && <CardLinkIcon />}
-            </Title>
+            <TitleWrapper id={cardTitleId} $isCardLink={!!to} $justifyContent={justifyContent}>
+              <Title>
+                {title}
+                {!!to && !!linkIcon && (
+                  <CardLinkIcon as={linkIcon === 'arrow' ? ArrowUpRightIcon : undefined} />
+                )}
+              </Title>
+              {!!badge && (
+                <CardBadge color={badgeColor} icon={badgeIcon} iconRawContent={badgeIconRawContent}>
+                  {badge}
+                </CardBadge>
+              )}
+            </TitleWrapper>
             <Body $lineClamp={lineClamp}>{children}</Body>
+            {!!to && !!cta && (
+              <Cta $justifyContent={justifyContent}>
+                <CtaText> {cta} </CtaText>
+                <CtaIcon />
+              </Cta>
+            )}
           </ContentWrapper>
         </CardContentWrapper>
       </>
@@ -105,25 +137,28 @@ const ContentWrapper = styled.div`
   width: 100%;
 `;
 
-const Title = styled.h3<{ $isCardLink: boolean; $justifyContent: string }>`
-  margin: var(--card-title-margin);
-  font-weight: var(--card-title-font-weight);
+const TitleWrapper = styled.div<{ $isCardLink: boolean; $justifyContent: string }>`
   color: var(--card-title-text-color);
   display: flex;
   align-items: center;
+  flex-wrap: wrap;
+  row-gap: var(--card-title-row-gap);
   justify-content: ${({ $justifyContent }) => $justifyContent};
   width: 100%;
 `;
 
+const Title = styled.h3`
+  margin: var(--card-title-margin);
+  font-weight: var(--card-title-font-weight);
+`;
+
+// The `as` prop selects the icon; the chevron is the default target.
 const CardLinkIcon = styled(ChevronRightIcon)`
   width: var(--card-link-icon-width);
   height: var(--card-link-icon-height);
-  color: var(--card-link-icon-color);
+  color: var(--icon-color-secondary);
   margin-left: var(--spacing-xxs);
-  opacity: 0;
-  transition:
-    opacity 0.3s,
-    transform 0.3s;
+  margin-top: calc(var(--spacing-xxs) / 2);
 `;
 
 const Body = styled.div<{ $lineClamp?: number }>`
@@ -149,6 +184,29 @@ const Body = styled.div<{ $lineClamp?: number }>`
   }
 `;
 
+const Cta = styled.div<{ $justifyContent: string }>`
+  display: flex;
+  gap: var(--card-cta-gap);
+  align-items: center;
+  margin-top: var(--card-cta-margin-top);
+  color: var(--card-cta-text-color);
+  font-size: var(--card-cta-font-size);
+  justify-content: ${({ $justifyContent }) => $justifyContent};
+    
+  && > * {
+    cursor: pointer;
+  }  
+`;
+
+const CtaText = styled.span`
+  font-weight: var(--card-cta-font-weight);
+`;
+
+const CtaIcon = styled(ChevronRightIcon)`
+  width: var(--card-cta-icon-width);
+  height: var(--card-cta-icon-height);
+`;
+
 const CardWrapper = styled.div.attrs<{
   $variant: string;
   $isCardLink: boolean;
@@ -185,6 +243,13 @@ const CardWrapper = styled.div.attrs<{
       height: 100%;
       object-fit: cover;
     `}
+  } 
+    
+  &:hover,
+  &:focus-within {
+    ${Cta} {
+      color: var(--card-link-icon-color);
+    }
   }
 
   &.card-link {
@@ -203,8 +268,8 @@ const CardWrapper = styled.div.attrs<{
         background-color: var(--card-icon-bg-color-hover);
       }
 
-      svg {
-        opacity: 1;
+      ${CardLinkIcon} {
+        color: var(--card-link-icon-color);
       }
     }
   }

package/src/markdoc/components/Cards/CardBadge.tsx

@@ -0,0 +1,39 @@
+import React from 'react';
+import styled from 'styled-components';
+
+import { Badge } from '@redocly/theme/components/Badge/Badge';
+
+export type CardBadgeProps = React.PropsWithChildren<{
+  color?: string;
+  icon?: string;
+  /** Inline SVG content for the icon */
+  iconRawContent?: string;
+  className?: string;
+}>;
+
+export function CardBadge({ color, icon, iconRawContent, className, children }: CardBadgeProps) {
+  // `tag-default` keeps a badge grey when the name is absent or unknown.
+  const classNames = ['tag-default', color && `tag-${color}`, className].filter(Boolean).join(' ');
+
+  return (
+    <CardBadgeWrapper className={classNames} icon={icon} iconRawContent={iconRawContent}>
+      {children}
+    </CardBadgeWrapper>
+  );
+}
+
+const CardBadgeWrapper = styled(Badge)`
+  display: flex;
+  align-items: center;
+  margin: var(--card-badge-margin);
+  padding: var(--card-badge-padding);
+  border-radius: var(--card-badge-border-radius);
+  font-size: var(--card-badge-font-size);
+  font-weight: var(--card-badge-font-weight);
+  line-height: var(--card-badge-line-height);
+  white-space: nowrap;
+  flex-shrink: 0;
+
+  --badge-text-color: var(--tag-color);
+  --badge-bg-color: var(--tag-bg-color);
+`;

package/src/markdoc/components/Cards/CardIcon.tsx

@@ -4,24 +4,35 @@ import styled from 'styled-components';
 import { GenericIcon } from '@redocly/theme/icons/GenericIcon/GenericIcon';
 
 export type CardIconProps = {
-  variant?: string;
+  variant?: 'filled' | 'ghost';
   src: string;
   rawContent?: string;
   position?: 'auto' | 'start' | 'center' | 'end';
+  color?: string;
 };
 
-export function CardIcon({ variant, src, rawContent, position }: CardIconProps) {
+export function CardIcon({ variant, src, rawContent, position, color }: CardIconProps) {
   return (
-    <CardIconWrapper $variant={variant} $position={position}>
+    <CardIconWrapper
+      className={color && `card-icon-color-${color}`}
+      $variant={variant}
+      $position={position}
+    >
       <GenericIcon icon={src} rawContent={rawContent} />
     </CardIconWrapper>
   );
 }
 
-export const CardIconWrapper = styled.div<{ $variant?: string; $position?: string }>`
+export const CardIconWrapper = styled.div<{
+  $variant?: 'filled' | 'ghost';
+  $position?: string;
+}>`
+  --card-icon-bg-color-hover: ${({ $variant }) => $variant === 'ghost' && 'transparent'};
   --icon-width: var(--card-icon-width);
   --icon-height: var(--card-icon-height);
   color: var(--card-icon-color);
+  /* An inline SVG fills from this. */
+  --icon-color: var(--card-icon-color);
 
   display: flex;
   align-self: ${({ $position }) => ($position ? $position : 'auto')};
@@ -30,7 +41,7 @@ export const CardIconWrapper = styled.div<{ $variant?: string; $position?: strin
   min-height: var(--card-icon-height);
   flex-shrink: 0;
 
-  padding: var(--card-icon-padding);
+  padding: ${({ $variant }) => ($variant === 'ghost' ? 0 : `var(--card-icon-padding)`)};
   border: ${({ $variant }) => $variant !== 'ghost' && `var(--card-icon-border)`};
   border-radius: var(--card-icon-border-radius);
   overflow: hidden;

package/src/markdoc/components/Cards/variables.dark.ts

@@ -21,5 +21,37 @@ export const cardsDarkMode = css`
     --card-box-shadow: 0px 8px 24px -4px #00000014, 0px 6px 12px -6px #0000001F;
     --card-box-shadow-hover: 0px 14px 64px -4px #0000001F, 0px 8px 22px -6px #0000001F;
   }
+
+  .card-icon-color-green {
+    --card-icon-color: var(--color-green-7);
+  }
+
+  .card-icon-color-grey {
+    --card-icon-color: var(--color-warm-grey-8);
+  }
+
+  .card-icon-color-turquoise {
+    --card-icon-color: var(--color-turquoise-6);
+  }
+
+  .card-icon-color-magenta {
+    --card-icon-color: var(--color-magenta-4);
+  }
+
+  .card-icon-color-carrot {
+    --card-icon-color: var(--color-carrot-6);
+  }
+
+  .card-icon-color-grass {
+    --card-icon-color: var(--color-grass-7);
+  }
+
+  .card-icon-color-persian-green {
+    --card-icon-color: var(--color-persian-green-7);
+  }
+
+  .card-icon-color-sky {
+    --card-icon-color: var(--color-sky-6);
+  }
 `;
 /* eslint-enable theme/no-raw-colors-in-styles */

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

@@ -21,8 +21,8 @@ export const cards = css`
   --card-border-radius: var(--border-radius-xl);
   --card-border-style: solid;
   --card-link-cursor: pointer;
-  --card-link-icon-width: var(--h3-font-size);
-  --card-link-icon-height: var(--h3-font-size);
+  --card-link-icon-width: 14px;
+  --card-link-icon-height: 14px;
   --card-border-width: 1px;
   --card-image-border-radius: var(--border-radius-md);
   --card-image-aspect-ratio: 16 / 9;
@@ -33,12 +33,26 @@ export const cards = css`
   --card-icon-height: var(--card-icon-size);
   --card-icon-width: var(--card-icon-size);
   --card-icon-gap: var(--spacing-base);
-  --card-title-margin: 0;
+  --card-title-margin: 0 var(--spacing-xs) 0 0;
   --card-title-font-weight: var(--font-weight-semibold);
+  --card-title-row-gap: var(--spacing-xxs);
   --card-content-gap: 4px;
   --card-padding: 16px 20px;
   --card-body-font-size: var(--font-size-base);
   --card-body-line-height: var(--line-height-base);
+  --card-cta-margin-top: var(--spacing-base);
+  --card-cta-gap: var(--spacing-xxs);
+  --card-cta-font-size: var(--font-size-base);
+  --card-cta-font-weight: var(--font-weight-regular);  
+  --card-cta-text-color: var(--text-color-secondary);
+  --card-cta-icon-width: 14px;
+  --card-cta-icon-height: 14px;
+  --card-badge-margin: 0 var(--spacing-xxs) 0 0 ;
+  --card-badge-padding: 0 var(--spacing-xxs);
+  --card-badge-border-radius: var(--border-radius);
+  --card-badge-font-size: var(--font-size-sm);
+  --card-badge-font-weight: var(--font-weight-regular);
+  --card-badge-line-height: var(--line-height-sm);
 
   /**
    * @tokens Card variants
@@ -82,5 +96,63 @@ export const cards = css`
     --card-hover-transition: initial;
   }
 
+  /**
+   * @tokens Card icon colors
+   */
+  .card-icon-color-red {
+    --card-icon-color: var(--color-red-7);
+  }
+
+  .card-icon-color-green {
+    --card-icon-color: var(--color-green-8);
+  }
+
+  .card-icon-color-blue {
+    --card-icon-color: var(--color-blue-7);
+  }
+
+  .card-icon-color-grey {
+    --card-icon-color: var(--text-color-secondary);
+  }
+
+  .card-icon-color-turquoise {
+    --card-icon-color: var(--color-turquoise-8);
+  }
+
+  .card-icon-color-magenta {
+    --card-icon-color: var(--color-magenta-7);
+  }
+
+  .card-icon-color-purple {
+    --card-icon-color: var(--color-purple-7);
+  }
+
+  .card-icon-color-carrot {
+    --card-icon-color: var(--color-carrot-8);
+  }
+
+  .card-icon-color-raspberry {
+    --card-icon-color: var(--color-raspberry-7);
+  }
+
+  .card-icon-color-orange {
+    --card-icon-color: var(--color-orange-7);
+  }
+
+  .card-icon-color-grass {
+    --card-icon-color: var(--color-grass-8);
+  }
+
+  .card-icon-color-persian-green {
+    --card-icon-color: var(--color-persian-green-8);
+  }
+
+  .card-icon-color-sky {
+    --card-icon-color: var(--color-sky-8);
+  }
+
+  .card-icon-color-blueberry {
+    --card-icon-color: var(--color-blueberry-7);
+  }
 `;
-/* eslint-enable theme/no-raw-colors-in-styles */
+/* eslint-enable theme/no-raw-colors-in-styles */

package/src/markdoc/tags/card.ts

@@ -52,7 +52,21 @@ export const card: MarkdocSchemaWrapper = {
         type: String,
         matches: ['filled', 'ghost'],
       },
+      iconColor: { type: String },
       to: { type: String, resolver: 'link' },
+      linkIcon: {
+        type: String,
+        matches: ['arrow', 'chevron'],
+      },
+      cta: { type: String },
+      badge: { type: String },
+      badgeColor: { type: String },
+      badgeIcon: { type: String, resolver: 'relativeOrCdnIcon' },
+      badgeIconRawContent: {
+        // internal use only
+        type: String,
+        render: true,
+      },
     },
   },
   tagName: 'card',