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

package/src/core/styles/global.ts

@@ -761,6 +761,7 @@ const apiReferenceDocs = css`
   --schema-property-details-width: 70%;
   --schema-property-details-spacing: var(--spacing-base); // @presenter Spacing
   --schema-fist-property-details-spacing: var(--spacing-sm); // @presenter Spacing
+  --schema-first-property-details-spacing: var(--schema-fist-property-details-spacing, var(--spacing-sm)); // @presenter Spacing
 
   /**
     * @tokens API Reference Schema Icons

package/src/core/templates/Markdown.tsx

@@ -11,7 +11,6 @@ import { TableOfContent } from '@redocly/theme/components/TableOfContent/TableOf
 import { Feedback } from '@redocly/theme/components/Feedback/Feedback';
 import { CodeWalkthroughLayout } from '@redocly/theme/layouts/CodeWalkthroughLayout';
 
-import { IS_BROWSER, onDocumentReady } from '../utils/dom';
 import { extendDetailsBehaviour } from '../utils/details';
 import { useThemeHooks } from '../hooks/use-theme-hooks';
 import { useThemeConfig } from '../hooks/use-theme-config';
@@ -66,19 +65,19 @@ export default function ({ pageProps, children }: React.PropsWithChildren<Markdo
     prevPage,
   };
 
-  if (IS_BROWSER) {
-    onDocumentReady(extendDetailsBehaviour);
-  }
+  React.useEffect(() => {
+    return extendDetailsBehaviour();
+  }, [pathname]);
 
-  const document = <Markdown ref={wrapperRefCb}>{children}</Markdown>;
+  const markdownDocument = <Markdown ref={wrapperRefCb}>{children}</Markdown>;
   const tagList = pageProps.metadata.markdoc.tagList;
   const withCodeWalkthrough = Boolean(
     Array.isArray(tagList) && tagList.includes('code-walkthrough'),
   );
 
   return withCodeWalkthrough ? (
-    <CodeWalkthroughLayout>{document}</CodeWalkthroughLayout>
+    <CodeWalkthroughLayout>{markdownDocument}</CodeWalkthroughLayout>
   ) : (
-    <DocumentationLayout {...documentationLayoutProps}>{document}</DocumentationLayout>
+    <DocumentationLayout {...documentationLayoutProps}>{markdownDocument}</DocumentationLayout>
   );
 }

package/src/core/types/index.ts

@@ -21,3 +21,4 @@ export type * from './open-api-info';
 export type * from './segmented';
 export type * from './tooltip';
 export type * from './toast';
+export type * from './link';

package/src/core/types/link.ts

@@ -0,0 +1,20 @@
+import type { RelativeRoutingType } from 'react-router-dom';
+
+export type LinkProps = {
+  to: string;
+  target?: '_self' | '_blank';
+  external?: boolean;
+  className?: string;
+  style?: React.CSSProperties;
+  innerRef?: React.Ref<HTMLAnchorElement>;
+  languageInsensitive?: boolean;
+  onClick?: () => void;
+  reloadDocument?: boolean;
+  replace?: boolean;
+  state?: unknown;
+  preventScrollReset?: boolean;
+  relative?: RelativeRoutingType;
+  viewTransition?: boolean;
+  [key: string]: unknown;
+  rel?: string;
+};

package/src/core/utils/details.ts

@@ -2,6 +2,10 @@ export function extendDetailsBehaviour() {
   enhanceDetails();
   openDetailsFromHash();
   window.addEventListener('hashchange', openDetailsFromHash);
+
+  return () => {
+    window.removeEventListener('hashchange', openDetailsFromHash);
+  };
 }
 
 function openDetailsAndScroll(detailsElement: Element) {

package/src/core/utils/dom.ts

@@ -1,9 +1 @@
 export const IS_BROWSER = typeof window !== 'undefined' && 'HTMLElement' in window;
-
-export function onDocumentReady(fn: () => unknown) {
-  if (document.readyState === 'loading') {
-    document.addEventListener('DOMContentLoaded', fn as EventListener);
-  } else {
-    fn();
-  }
-}

package/src/core/utils/index.ts

@@ -11,7 +11,6 @@ export * from './urls';
 export * from './js-utils';
 export * from './tags-parser';
 export * from './string';
-export * from './dom';
 export * from './markdoc';
 export * from './attribute-parser';
 export * from './type-guards';

package/src/icons/AiStarsGradientIcon/AiStarsGradientIcon.tsx

@@ -59,9 +59,15 @@ const Icon = (props: AiStarsGradientIconProps) => {
   );
 };
 
-export const AiStarsGradientIcon = styled(Icon).attrs({
-  'data-component-name': 'icons/AiStarsGradientIcon/AiStarsGradientIcon',
-})`
+const iconStyleProps = new Set(['background', 'borderRadius', 'padding', 'margin']);
+
+export const AiStarsGradientIcon = styled(Icon)
+  .withConfig({
+    shouldForwardProp: (prop) => !iconStyleProps.has(prop),
+  })
+  .attrs({
+    'data-component-name': 'icons/AiStarsGradientIcon/AiStarsGradientIcon',
+  })<AiStarsGradientIconProps>`
   height: ${({ size }) => size || '16px'};
   width: ${({ size }) => size || '16px'};
 

package/src/icons/AiStarsIcon/AiStarsIcon.tsx

@@ -29,9 +29,15 @@ const Icon = (props: AiStarsIconProps) => {
   );
 };
 
-export const AiStarsIcon = styled(Icon).attrs({
-  'data-component-name': 'icons/AiStarsIcon/AiStarsIcon',
-})`
+const iconStyleProps = new Set(['background', 'borderRadius', 'padding', 'margin']);
+
+export const AiStarsIcon = styled(Icon)
+  .withConfig({
+    shouldForwardProp: (prop) => !iconStyleProps.has(prop),
+  })
+  .attrs({
+    'data-component-name': 'icons/AiStarsIcon/AiStarsIcon',
+  })<AiStarsIconProps>`
   height: ${({ size }) => size || '16px'};
   width: ${({ size }) => size || '16px'};
 

package/src/icons/MagicWandIcon/MagicWandIcon.tsx

@@ -0,0 +1,26 @@
+import React from 'react';
+import styled from 'styled-components';
+
+import type { IconProps } from '@redocly/theme/icons/types';
+
+import { getCssColorVariable } from '@redocly/theme/core/utils';
+
+const Icon = (props: IconProps) => (
+  <svg viewBox="0 0 12.25 12.2494" fill="none" xmlns="http://www.w3.org/2000/svg" {...props}>
+    <path d="M11.9937 9.62499L4.37501 2.00632C4.20836 1.84719 3.98679 1.7584 3.75636 1.7584C3.52594 1.7584 3.30437 1.84719 3.13772 2.00632L2.00634 3.1377C1.84252 3.30191 1.75051 3.52439 1.75051 3.75634C1.75051 3.9883 1.84252 4.21078 2.00634 4.37499L9.62457 11.9937C9.7888 12.1575 10.0113 12.2494 10.2432 12.2494C10.4752 12.2494 10.6976 12.1575 10.8619 11.9937L11.9937 10.8621C12.0749 10.7808 12.1394 10.6844 12.1834 10.5782C12.2274 10.4721 12.25 10.3583 12.25 10.2434C12.25 10.1285 12.2274 10.0147 12.1834 9.90859C12.1394 9.80244 12.0749 9.70622 11.9937 9.62499ZM2.62501 3.75632L3.75634 2.62499L5.94384 4.81249L4.81221 5.94426L2.62471 3.75676L2.62501 3.75632ZM10.2432 11.375L5.43074 6.56293L6.56251 5.43116L11.375 10.2437L10.2432 11.375Z" />
+    <path d="M0.875027 5.24999L3.56734e-05 6.12498L0.875027 6.99997L1.75002 6.12498L0.875027 5.24999Z" />
+    <path d="M6.12503 8.20979e-06L5.25004 0.875L6.12503 1.74999L7.00002 0.875L6.12503 8.20979e-06Z" />
+    <path d="M0.874992 0L0 0.874992L0.874992 1.74998L1.74998 0.874992L0.874992 0Z" />
+  </svg>
+);
+
+export const MagicWandIcon = styled(Icon).attrs({
+  'data-component-name': 'icons/MagicWandIcon/MagicWandIcon',
+})`
+  path {
+    fill: ${({ color }) => getCssColorVariable(color)};
+  }
+
+  height: ${({ size }) => size || '14px'};
+  width: ${({ size }) => size || '14px'};
+`;

package/src/icons/ReturnKeyIcon/ReturnKeyIcon.tsx

@@ -2,7 +2,7 @@ import styled from 'styled-components';
 
 import { Typography } from '@redocly/theme/components/Typography/Typography';
 
-export const ReturnKeyIcon = styled(Typography).attrs({
+export const ReturnKeyIcon = styled(Typography).attrs<{ 'data-component-name': string }>({
   'data-component-name': 'icons/ReturnKeyIcon/ReturnKeyIcon',
 })`
   margin-left: auto;

package/src/index.ts

@@ -267,6 +267,7 @@ export * from '@redocly/theme/icons/TableBuiltIcon/TableBuiltIcon';
 export * from '@redocly/theme/icons/ValueVariableIcon/ValueVariableIcon';
 export * from '@redocly/theme/icons/InformationIcon/InformationIcon';
 export * from '@redocly/theme/icons/ChevronSortIcon/ChevronSortIcon';
+export * from '@redocly/theme/icons/MagicWandIcon/MagicWandIcon';
 export * from '@redocly/theme/icons/DocumentIcon/DocumentIcon';
 export * from '@redocly/theme/icons/JsonIcon/JsonIcon';
 export * from '@redocly/theme/icons/SubtractIcon/SubtractIcon';

package/src/layouts/DocumentationLayout.tsx

@@ -38,7 +38,7 @@ export function DocumentationLayout({
   return (
     <CodeSnippetProvider>
       <LayoutWrapper data-component-name="Layout/DocumentationLayout" className={className}>
-        <ContentWrapper withToc={!config?.toc?.hide}>
+        <ContentWrapper $withToc={!config?.toc?.hide}>
           <DocumentationLayoutTop config={config} editPage={editPage} lastModified={lastModified} />
           {children}
           <DocumentationLayoutBottom feedback={feedback} nextPage={nextPage} prevPage={prevPage} />
@@ -57,7 +57,7 @@ const LayoutWrapper = styled.div.attrs(({ className }) => ({
   width: 100%;
 `;
 
-const ContentWrapper = styled.section<{ withToc: boolean }>`
+const ContentWrapper = styled.section<{ $withToc: boolean }>`
   --md-content-font-size: var(--font-size-lg);
   --md-content-line-height: var(--line-height-lg);
   --md-table-font-size: var(--md-content-font-size);
@@ -78,6 +78,6 @@ const ContentWrapper = styled.section<{ withToc: boolean }>`
   }
 
   @media screen and (min-width: ${breakpoints.medium}) {
-    width: ${({ withToc }) => (withToc ? `calc(90% - var(--toc-width))` : '90%')};
+    width: ${({ $withToc }) => ($withToc ? `calc(90% - var(--toc-width))` : '90%')};
   }
 `;

package/src/layouts/ThreePanelLayout.tsx

@@ -1,28 +1,41 @@
-import React from 'react';
+import React, { type JSX, type PropsWithChildren } from 'react';
 import styled, { css } from 'styled-components';
 import { LayoutVariant } from '@redocly/config';
 
-import type { JSX } from 'react';
-
 import { breakpoints } from '@redocly/theme/core/utils';
 
-interface LayoutConfig {
-  children: React.ReactNode;
+export type ThreePanelLayoutProps = PropsWithChildren<{
   layout?: LayoutVariant;
   collapsedSidebar?: boolean;
   id?: string;
   className?: string;
-}
+}>;
 
-export function ThreePanelLayout({ children, ...props }: LayoutConfig): JSX.Element {
+export function ThreePanelLayout({
+  layout,
+  collapsedSidebar,
+  children,
+  ...props
+}: ThreePanelLayoutProps): JSX.Element {
   return (
-    <Wrapper data-component-name="Layout/ThreePanelLayout" {...props}>
+    <Wrapper
+      data-component-name="Layout/ThreePanelLayout"
+      {...props}
+      $layout={layout}
+      $collapsedSidebar={collapsedSidebar}
+    >
       {children}
     </Wrapper>
   );
 }
 
-const Wrapper = styled.div<{ collapsedSidebar?: boolean; layout?: LayoutVariant }>`
+export const Wrapper = styled.div.attrs<{
+  'data-component-name': string;
+  $layout: LayoutVariant;
+  $collapsedSidebar: boolean;
+}>({
+  'data-component-name': 'Layout/ThreePanelLayout',
+})<ThreePanelLayoutProps>`
   position: relative;
   display: flex;
   flex-direction: column;
@@ -30,20 +43,20 @@ const Wrapper = styled.div<{ collapsedSidebar?: boolean; layout?: LayoutVariant
   margin: 0 auto;
   width: 100%;
 
-  ${({ layout = LayoutVariant.THREE_PANEL }) => {
+  ${({ $layout = LayoutVariant.THREE_PANEL }) => {
     return css`
-      max-width: ${layout === LayoutVariant.THREE_PANEL ? '100%' : ''};
+      max-width: ${$layout === LayoutVariant.THREE_PANEL ? '100%' : ''};
 
       @media screen and (min-width: ${breakpoints.small}) {
-        max-width: var(--layout-${layout}-small-max-width);
+        max-width: var(--layout-${$layout}-small-max-width);
       }
 
       @media screen and (min-width: ${breakpoints.medium}) {
-        max-width: var(--layout-${layout}-medium-max-width);
+        max-width: var(--layout-${$layout}-medium-max-width);
       }
 
       @media screen and (min-width: ${breakpoints.large}) {
-        max-width: var(--layout-${layout}-large-max-width);
+        max-width: var(--layout-${$layout}-large-max-width);
       }
 
       @media print {

package/src/markdoc/components/CodeWalkthrough/CodeContainer.tsx

@@ -59,7 +59,7 @@ export function CodeContainer({
     <CodeContainerWrapper
       data-component-name="Markdoc/CodeWalkthrough/CodeContainer"
       ref={compRef}
-      hideCodeColors={!isHovered}
+      $hideCodeColors={!isHovered}
       onMouseEnter={() => setIsHovered(true)}
       onMouseLeave={() => setIsHovered(false)}
     >
@@ -69,7 +69,7 @@ export function CodeContainer({
   );
 }
 
-const CodeContainerWrapper = styled.div<{ hideCodeColors?: boolean }>`
+const CodeContainerWrapper = styled.div<{ $hideCodeColors: boolean }>`
   position: relative;
 
   display: flex;
@@ -89,8 +89,8 @@ const CodeContainerWrapper = styled.div<{ hideCodeColors?: boolean }>`
     span.line::before {
       color: var(--code-panel-line-numbering-color);
     }
-    ${({ hideCodeColors }) =>
-      hideCodeColors &&
+    ${({ $hideCodeColors }) =>
+      $hideCodeColors &&
       css`
         .line.greyed-out {
           color: var(--text-color-helper) !important;

package/src/markdoc/components/CodeWalkthrough/CodePanelHeader.tsx

@@ -85,7 +85,7 @@ export function CodePanelHeader({
                     tabRefs.current[i] = el as HTMLButtonElement;
                   }}
                   data-name={path}
-                  active={path === activeTabName}
+                  $active={path === activeTabName}
                   key={i}
                   onClick={() => handleTabSwitch(path)}
                 >
@@ -173,7 +173,7 @@ const ActionBar = styled.div`
   display: flex;
 `;
 
-const Tab = styled.button<{ active: boolean }>`
+const Tab = styled.button<{ $active: boolean }>`
   --icon-width: 16px;
   --icon-height: 16px;
 
@@ -188,8 +188,8 @@ const Tab = styled.button<{ active: boolean }>`
   color: var(--text-color-secondary);
   white-space: nowrap;
   scroll-margin-right: var(--spacing-base);
-  ${({ active }) =>
-    active
+  ${({ $active }) =>
+    $active
       ? css`
           color: var(--text-color-primary);
           background-color: var(--tab-bg-color-filled);

package/src/markdoc/components/CodeWalkthrough/CodePanelPreview.tsx

@@ -18,7 +18,7 @@ export function CodePanelPreview({ children }: PropsWithChildren): JSX.Element {
         {translate('codeWalkthrough.preview', 'Preview')}
         {isOpen ? <ChevronUpIcon /> : <ChevronDownIcon />}
       </PreviewDropdown>
-      <PreviewContentWrapper isOpen={isOpen}>{children}</PreviewContentWrapper>
+      <PreviewContentWrapper $isOpen={isOpen}>{children}</PreviewContentWrapper>
     </CodePanelPreviewWrapper>
   );
 }
@@ -41,8 +41,8 @@ const PreviewDropdown = styled.div`
   cursor: pointer;
 `;
 
-const PreviewContentWrapper = styled.div<{ isOpen: boolean }>`
-  display: ${({ isOpen }) => (isOpen ? 'grid' : 'none')};
+const PreviewContentWrapper = styled.div<{ $isOpen: boolean }>`
+  display: ${({ $isOpen }) => ($isOpen ? 'grid' : 'none')};
   place-items: center;
 
   margin: auto 0;

package/src/markdoc/components/CodeWalkthrough/CodeStep.tsx

@@ -147,7 +147,9 @@ export function CodeStep({
   );
 }
 
-const StepContent = styled.div<{ isActive: boolean }>`
+const StepContent = styled.div.withConfig({
+  shouldForwardProp: (prop) => prop !== 'isActive',
+})<{ isActive: boolean }>`
   margin: var(--spacing-xs) 0px var(--spacing-xs) calc(var(--spacing-unit) * 3.5);
   padding: var(--spacing-md) var(--spacing-lg);
   background: ${({ isActive }) => (isActive ? 'var(--layer-color)' : 'none')};
@@ -163,7 +165,9 @@ const StepHeading = styled.p`
   font-weight: var(--font-weight-semibold);
 `;
 
-export const StepWrapper = styled.div<{ isActive: boolean; scrollMarginTop: number }>`
+export const StepWrapper = styled.div.withConfig({
+  shouldForwardProp: (prop) => !['isActive', 'scrollMarginTop'].includes(prop),
+})<{ isActive: boolean; scrollMarginTop: number; className?: string }>`
   position: relative;
   scroll-margin-top: ${({ scrollMarginTop }) => scrollMarginTop}px;
 

package/src/markdoc/components/Image/Image.tsx

@@ -9,7 +9,7 @@ type MarkdocImageProps = React.PropsWithChildren<ImageProps> & {
 export function Image(props: MarkdocImageProps) {
   const { align, ...rest } = props;
   return align ? (
-    <ImageWrapper align={align}>
+    <ImageWrapper $align={align}>
       <ImageComponent {...rest} />
     </ImageWrapper>
   ) : (
@@ -17,13 +17,13 @@ export function Image(props: MarkdocImageProps) {
   );
 }
 
-const ImageWrapper = styled.div<{ align?: MarkdocImageProps['align'] }>`
-  text-align: ${(props) => props.align || 'initial'};
+const ImageWrapper = styled.div<{ $align?: MarkdocImageProps['align'] }>`
+  text-align: ${(props) => props.$align || 'initial'};
 
   img {
     display: block;
     ${(props) => {
-      switch (props.align) {
+      switch (props.$align) {
         case 'left':
           return 'margin-right: auto; margin-left: 0;';
         case 'right':

package/src/markdoc/components/Tabs/TabItemFragment.tsx

@@ -0,0 +1,15 @@
+import React from 'react';
+
+import type { JSX, PropsWithChildren } from 'react';
+
+// Below props are used by the TabList component to render tab labels
+export type TabItemProps = PropsWithChildren<{
+  label: string;
+  disable?: boolean;
+  onClick?: () => void;
+  icon?: React.ReactNode | string;
+}>;
+
+export function TabItemFragment({ children }: TabItemProps): JSX.Element {
+  return <div>{children}</div>;
+}

package/src/markdoc/components/Tabs/TabList.tsx

@@ -2,9 +2,10 @@ import React, { useState, useRef, useEffect, useCallback } from 'react';
 import styled, { css } from 'styled-components';
 
 import type { JSX } from 'react';
+import type { TabItemProps } from '@redocly/theme/markdoc/components/Tabs/TabItemFragment';
 
 import { Tab } from '@redocly/theme/markdoc/components/Tabs/Tab';
-import { TabItemProps, TabsSize } from '@redocly/theme/markdoc/components/Tabs/Tabs';
+import { TabsSize } from '@redocly/theme/markdoc/components/Tabs/Tabs';
 import { Dropdown } from '@redocly/theme/components/Dropdown/Dropdown';
 import { DropdownMenu } from '@redocly/theme/components/Dropdown/DropdownMenu';
 import { DropdownMenuItem } from '@redocly/theme/components/Dropdown/DropdownMenuItem';
@@ -198,7 +199,7 @@ export function TabList({
 
   return (
     <TabListContainer role="tablist" ref={containerRef}>
-      <HighlightBar size={size} style={highlightStyle}>
+      <HighlightBar $size={size} style={highlightStyle}>
         <div />
       </HighlightBar>
 
@@ -359,7 +360,9 @@ export const TabListContainer = styled.ul`
   }
 `;
 
-export const TabItem = styled.li<{ active?: boolean; size: TabsSize; tabIndex?: number }>`
+export const TabItem = styled.li.withConfig({
+  shouldForwardProp: (prop) => !['active', 'size'].includes(prop),
+})<{ tabIndex?: number; className?: string; active?: boolean; size: TabsSize }>`
   display: inline-flex;
   list-style: none;
   cursor: pointer;
@@ -449,12 +452,12 @@ const FixedPositionDropdown = styled(Dropdown)`
   }
 `;
 
-const HighlightBar = styled.div<{ size: TabsSize }>`
+const HighlightBar = styled.div<{ $size: TabsSize }>`
   position: absolute;
   top: 0;
   bottom: 0;
   border: solid var(--md-tabs-active-tab-border-color);
-  border-width: var(--md-tabs-${({ size }) => size}-active-tab-border-width);
+  border-width: var(--md-tabs-${({ $size }) => $size}-active-tab-border-width);
   transition:
     left 300ms ease-in-out,
     width 300ms ease-in-out;
@@ -465,7 +468,7 @@ const HighlightBar = styled.div<{ size: TabsSize }>`
     width: 100%;
     height: 100%;
     background-color: var(--md-tabs-active-tab-bg-color);
-    border-radius: var(--md-tabs-${({ size }) => size}-active-tab-border-radius);
+    border-radius: var(--md-tabs-${({ $size }) => $size}-active-tab-border-radius);
   }
 `;
 

package/src/markdoc/components/Tabs/Tabs.tsx

@@ -1,26 +1,24 @@
-import React, { useEffect, useRef, useState } from 'react';
+import React, { isValidElement, useEffect, useRef, useState } from 'react';
 import { useInRouterContext } from 'react-router-dom';
 import styled from 'styled-components';
 
-import type { JSX } from 'react';
+import type { JSX, ReactElement, ReactNode } from 'react';
 
 import { useActiveTab } from '@redocly/theme/core/hooks';
+import {
+  TabItemFragment,
+  type TabItemProps,
+} from '@redocly/theme/markdoc/components/Tabs/TabItemFragment';
 import { TabList } from '@redocly/theme/markdoc/components/Tabs/TabList';
 import { getTabId } from '@redocly/theme/core/utils';
 
+export type { TabItemProps } from '@redocly/theme/markdoc/components/Tabs/TabItemFragment';
+
 export enum TabsSize {
   SMALL = 'small',
   MEDIUM = 'medium',
 }
 
-export type TabItemProps = {
-  label: string;
-  disable?: boolean;
-  onClick?: () => void;
-  children: React.ReactNode;
-  icon?: React.ReactNode | string;
-};
-
 type TabsProps = {
   id?: string;
   children: React.ReactElement<TabItemProps>[];
@@ -55,14 +53,17 @@ export function Tabs({
   size,
   initialTab: propInitialTab,
   activeTab: controlledActiveTab,
-}: TabsProps): JSX.Element {
-  const childrenArray = React.Children.toArray(children) as React.ReactElement<TabItemProps>[];
+}: TabsProps): JSX.Element | null {
+  const inRouter = useInRouterContext();
+  const childrenArray = React.Children.toArray(children).filter(isTabItemFragment);
   const containerRef = useRef<HTMLUListElement | null>(null);
 
-  const initialTab = propInitialTab ?? childrenArray[0]?.props.label ?? '';
-  const labelsHash = childrenArray.map((c) => c.props.label).join('|');
+  if (childrenArray.length === 0) {
+    return null;
+  }
 
-  const inRouter = useInRouterContext();
+  const initialTab = propInitialTab ?? childrenArray[0].props.label;
+  const labelsHash = childrenArray.map((c) => c.props.label).join('|');
 
   return (
     <TabsView
@@ -127,6 +128,11 @@ function TabsView({
   );
 }
 
+function isTabItemFragment(node: ReactNode): node is ReactElement<TabItemProps> {
+  if (!isValidElement(node)) return false;
+  return node.type === TabItemFragment;
+}
+
 /**
  * Validates that the active tab exists in children and resets to initial tab if not found.
  * Ensures tab state remains consistent when tab structure changes.

package/src/markdoc/components/default.ts

@@ -4,6 +4,7 @@ export * from '@redocly/theme/markdoc/components/MarkdocExample/MarkdocExample';
 export * from '@redocly/theme/markdoc/components/Heading/Heading';
 export * from '@redocly/theme/markdoc/components/Diagram/Diagram';
 export * from '@redocly/theme/markdoc/components/HtmlBlock/HtmlBlock';
+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';

package/src/markdoc/tags/tab.ts

@@ -7,7 +7,7 @@ export const tab: MarkdocSchemaWrapper = {
       disable: { type: Boolean, default: false },
       icon: { type: String, resolver: 'relativeOrCdnIcon' },
     },
-    render: 'div',
+    render: 'TabItemFragment',
   },
   tagName: 'tab',
 };

package/src/markdoc/tags/tabs.ts

@@ -14,7 +14,7 @@ export const tabs: MarkdocSchemaWrapper = {
         if (isTag(child) && child?.name === 'CodeBlock') {
           const key = child.attributes['data-language'] || 'default';
           const label = child.attributes['data-label'] || key;
-          return new markdoc.Tag('div', { label, key }, [child]);
+          return new markdoc.Tag('TabItemFragment', { label, key }, [child]);
         }
         return child;
       });