@redocly/theme 0.70.0-next.3 → 0.70.0-next.5

package/src/core/hooks/menu/use-mobile-menu-items.ts

@@ -1,21 +1,36 @@
+import { useMemo } from 'react';
 import { useLocation } from 'react-router';
 
-import type { ResolvedNavItem } from '@redocly/config';
+import type { ResolvedNavItem, Version } from '@redocly/config';
 
 import { useThemeHooks } from '../use-theme-hooks';
 import { useThemeConfig } from '../use-theme-config';
 import { MobileMenuType } from '../../constants/common';
-import { buildLanguagesGroup, buildVersionSection, mapNavbarItems } from '../../utils/menu';
+import {
+  buildLanguagesGroup,
+  buildNavigationTabsSelect,
+  buildVersionSection,
+  mapNavbarItems,
+} from '../../utils/menu';
 
 const MENU_SEPARATOR: ResolvedNavItem = {
   type: 'separator',
   separatorLine: true,
 };
 
+const NO_VERSIONS: Version[] = [];
+const NO_NAV_ITEMS: ResolvedNavItem[] = [];
+
 export const useMobileMenuItems = (menuType: MobileMenuType) => {
-  const { useTranslate, useL10nConfig, useCurrentProduct, usePageVersions, useSidebarItems } =
-    useThemeHooks();
-  const { versions = [] } = usePageVersions() || {};
+  const {
+    useTranslate,
+    useL10nConfig,
+    useCurrentProduct,
+    usePageVersions,
+    useSidebarItems,
+    useNavigationTabs,
+  } = useThemeHooks();
+  const versions = usePageVersions()?.versions ?? NO_VERSIONS;
   const { defaultLocale, currentLocale, locales } = useL10nConfig();
   const { translate } = useTranslate();
   const activeVersion = versions.find((version) => version.active);
@@ -25,6 +40,7 @@ export const useMobileMenuItems = (menuType: MobileMenuType) => {
     popDrilldownState,
     backLink,
   } = useSidebarItems(activeVersion);
+  const navigationTabs = useNavigationTabs();
   const location = useLocation();
 
   const currentProduct = useCurrentProduct();
@@ -33,74 +49,93 @@ export const useMobileMenuItems = (menuType: MobileMenuType) => {
   const productThemeConfig = useThemeConfig();
   const baseThemeConfig = useThemeConfig(false);
 
-  const baseNavItems = (baseThemeConfig.navbar?.items || []) as ResolvedNavItem[];
+  const baseNavItems = (baseThemeConfig.navbar?.items ?? NO_NAV_ITEMS) as ResolvedNavItem[];
   const productNavItems = (
-    hasProductNavbarOverride ? productThemeConfig.navbar?.items || [] : []
+    hasProductNavbarOverride ? (productThemeConfig.navbar?.items ?? NO_NAV_ITEMS) : NO_NAV_ITEMS
   ) as ResolvedNavItem[];
-
-  const menuItems: ResolvedNavItem[] = [];
-
-  if (menuType === MobileMenuType.PAGE) {
-    if (activeVersion) {
-      // eslint-disable-next-line no-warning-comments
-      // TODO: consider to refactor
-      const versionsSection = buildVersionSection(translate, versions, activeVersion);
-      menuItems.push(...versionsSection);
-    }
-    if (menuItems.length && sidebarItems.length) {
-      menuItems.push(MENU_SEPARATOR);
-    }
-    menuItems.push(...(sidebarItems as ResolvedNavItem[]));
-  } else if (menuType === MobileMenuType.PRODUCT) {
-    menuItems.push(...productNavItems);
-
-    if (menuItems.length && baseNavItems.length) {
-      menuItems.push(MENU_SEPARATOR);
-    }
-
-    if (baseNavItems.length) {
-      menuItems.push(...baseNavItems);
-    }
-  } else if (menuType === MobileMenuType.MAIN_MENU) {
-    const productMenuItems: ResolvedNavItem[] = Object.values(baseThemeConfig.products || {}).map(
-      (product) => ({
+  const products = baseThemeConfig.products;
+
+  const items = useMemo(() => {
+    const menuItems: ResolvedNavItem[] = [];
+    const navigationTabsSelect =
+      menuType === MobileMenuType.PAGE ? buildNavigationTabsSelect({ navigationTabs }) : undefined;
+
+    if (menuType === MobileMenuType.PAGE) {
+      if (activeVersion) {
+        menuItems.push(...buildVersionSection(translate, versions, activeVersion));
+      }
+      if (menuItems.length && sidebarItems.length) {
+        menuItems.push(MENU_SEPARATOR);
+      }
+      menuItems.push(...(sidebarItems as ResolvedNavItem[]));
+    } else if (menuType === MobileMenuType.PRODUCT) {
+      menuItems.push(...productNavItems);
+
+      if (menuItems.length && baseNavItems.length) {
+        menuItems.push(MENU_SEPARATOR);
+      }
+
+      if (baseNavItems.length) {
+        menuItems.push(...baseNavItems);
+      }
+    } else if (menuType === MobileMenuType.MAIN_MENU) {
+      const productMenuItems: ResolvedNavItem[] = Object.values(products || {}).map((product) => ({
         label: product.name,
         link: product.link,
         icon: product.icon,
         type: 'link',
-      }),
-    );
+      }));
+
+      if (productMenuItems.length) {
+        menuItems.push({
+          type: 'separator',
+          label: translate('mobileMenu.products', 'Products'),
+        });
 
-    if (productMenuItems.length) {
-      menuItems.push({
-        type: 'separator',
-        label: translate('mobileMenu.products', 'Products'),
-      });
+        menuItems.push(...productMenuItems);
+      }
 
-      menuItems.push(...productMenuItems);
+      if (menuItems.length && baseNavItems.length) {
+        menuItems.push(MENU_SEPARATOR);
+      }
+
+      if (baseNavItems.length) {
+        menuItems.push(...baseNavItems);
+      }
     }
 
-    if (menuItems.length && baseNavItems.length) {
+    const languagesMenu = buildLanguagesGroup(locales, defaultLocale, currentLocale);
+
+    if (menuItems.length && languagesMenu) {
       menuItems.push(MENU_SEPARATOR);
     }
 
-    if (baseNavItems.length) {
-      menuItems.push(...baseNavItems);
+    if (languagesMenu) {
+      menuItems.push(languagesMenu);
     }
-  }
-
-  const languagesMenu = buildLanguagesGroup(locales, defaultLocale, currentLocale);
-
-  if (menuItems.length && languagesMenu) {
-    menuItems.push(MENU_SEPARATOR);
-  }
 
-  if (languagesMenu) {
-    menuItems.push(languagesMenu);
-  }
+    return [
+      ...(navigationTabsSelect ? [navigationTabsSelect] : []),
+      ...mapNavbarItems(menuItems, defaultLocale, currentLocale, locales, location),
+    ];
+  }, [
+    menuType,
+    navigationTabs,
+    activeVersion,
+    versions,
+    sidebarItems,
+    productNavItems,
+    baseNavItems,
+    products,
+    translate,
+    locales,
+    defaultLocale,
+    currentLocale,
+    location,
+  ]);
 
   return {
-    items: mapNavbarItems(menuItems, defaultLocale, currentLocale, locales, location),
+    items,
     popDrilldownState,
     pushDrilldownState,
     backLink,

package/src/core/hooks/menu/use-mobile-menu-levels.ts

@@ -8,27 +8,35 @@ import { useThemeConfig } from '../use-theme-config';
 import { MobileMenuType } from '../../constants/common';
 
 export const useMobileMenuLevels = () => {
-  const { useTranslate, useCurrentProduct, usePageVersions, useSidebarItems } = useThemeHooks();
+  const { useTranslate, useCurrentProduct, usePageVersions, useSidebarItems, useNavigationTabs } =
+    useThemeHooks();
   const { versions = [] } = usePageVersions() || {};
   const activeVersion = versions.find((version) => version?.active);
   const { currentItems: sidebarItems } = useSidebarItems(activeVersion);
+  const navigationTabs = useNavigationTabs();
   const { translate } = useTranslate();
   const currentProduct = useCurrentProduct();
   const productThemeConfig = useThemeConfig();
+  const baseThemeConfig = useThemeConfig(false);
   const location = useLocation();
 
   const hasProductNavbarOverride = currentProduct?.configOverride?.navbar;
   const productNavItems = (
     hasProductNavbarOverride ? productThemeConfig.navbar?.items || [] : []
   ) as ResolvedNavItem[];
+  const hasMainMenuItems =
+    Object.values(baseThemeConfig.products || {}).length > 0 ||
+    (baseThemeConfig.navbar?.items || []).length > 0;
 
   const menuLevels = useMemo(() => {
-    const menuLevels = [
-      {
+    const menuLevels: Array<{ label: string; type: MobileMenuType }> = [];
+
+    if (hasMainMenuItems) {
+      menuLevels.push({
         label: translate('mobileMenu.mainMenu', 'Main menu'),
         type: MobileMenuType.MAIN_MENU,
-      },
-    ];
+      });
+    }
 
     if (currentProduct && productNavItems.length) {
       menuLevels.push({
@@ -37,7 +45,7 @@ export const useMobileMenuLevels = () => {
       });
     }
 
-    if (sidebarItems.length || activeVersion) {
+    if (sidebarItems.length || activeVersion || navigationTabs?.tabs.length) {
       menuLevels.push({
         label: translate('mobileMenu.previous', 'Previous'),
         type: MobileMenuType.PAGE,

package/src/core/hooks/use-scroll-item-into-view.ts

@@ -0,0 +1,18 @@
+import { useEffect } from 'react';
+
+import type { RefObject } from 'react';
+
+export function useScrollItemIntoView(
+  listRef: RefObject<HTMLElement | null>,
+  activeIndex: number,
+): void {
+  useEffect(() => {
+    const list = listRef.current;
+    const activeItem = activeIndex === -1 ? undefined : list?.children[activeIndex];
+    if (!list || !activeItem) return;
+
+    const listRect = list.getBoundingClientRect();
+    const itemRect = activeItem.getBoundingClientRect();
+    list.scrollLeft += itemRect.left - listRect.left - (listRect.width - itemRect.width) / 2;
+  }, [listRef, activeIndex]);
+}

package/src/core/hooks/use-tab-list.ts

@@ -0,0 +1,63 @@
+import { useCallback, useId, useRef } from 'react';
+
+import type { KeyboardEvent } from 'react';
+
+type UseTabListProps = {
+  count: number;
+  activeIndex: number;
+  onChange: (index: number) => void;
+};
+
+/**
+ * Props for a WAI-ARIA tab list with automatic activation: only the active tab is a tab stop,
+ * and Left/Right/Home/End select and focus another tab.
+ */
+export function useTabList({ count, activeIndex, onChange }: UseTabListProps) {
+  const idPrefix = useId();
+  const focusableIndex = activeIndex >= 0 ? activeIndex : 0;
+  const tabRefs = useRef<(HTMLElement | null)[]>([]);
+
+  const select = useCallback(
+    (index: number) => {
+      onChange(index);
+      tabRefs.current[index]?.focus();
+    },
+    [onChange],
+  );
+
+  const onKeyDown = useCallback(
+    (event: KeyboardEvent, index: number) => {
+      const target = (<Record<string, number>>{
+        ArrowRight: (index + 1) % count,
+        ArrowLeft: (index - 1 + count) % count,
+        Home: 0,
+        End: count - 1,
+      })[event.key];
+      if (target === undefined) return;
+      event.preventDefault();
+      select(target);
+    },
+    [count, select],
+  );
+
+  const getTabProps = (index: number) => ({
+    id: `${idPrefix}-tab-${index}`,
+    role: 'tab',
+    'aria-selected': index === activeIndex,
+    'aria-controls': `${idPrefix}-panel-${index}`,
+    tabIndex: index === focusableIndex ? 0 : -1,
+    ref: (element: HTMLElement | null) => {
+      tabRefs.current[index] = element;
+    },
+    onClick: () => select(index),
+    onKeyDown: (event: KeyboardEvent) => onKeyDown(event, index),
+  });
+
+  const getTabPanelProps = (index: number) => ({
+    id: `${idPrefix}-panel-${index}`,
+    role: 'tabpanel',
+    'aria-labelledby': `${idPrefix}-tab-${index}`,
+  });
+
+  return { tabListProps: { role: 'tablist' }, getTabProps, getTabPanelProps };
+}

package/src/core/hooks/use-theme-hooks.ts

@@ -39,6 +39,8 @@ const fallbacks = {
   usePageProps: () => ({}),
   usePageSharedData: () => null,
   useMcpData: () => ({ docs: { enabled: false } }),
+  useSearchFeatures: () => ({}),
+  useNavigationTabs: () => undefined,
 };
 
 export const useThemeHooks = () => {

package/src/core/styles/global.ts

@@ -49,6 +49,8 @@ import { pageActions } from '@redocly/theme/components/PageActions/variables';
 import { svgViewer } from '@redocly/theme/components/SvgViewer/variables';
 import { toast } from '@redocly/theme/components/Toast/variables';
 import { pageNavigation } from '@redocly/theme/components/PageNavigation/variables';
+import { navigationTabs } from '@redocly/theme/components/NavigationTabs/variables';
+import { breakpoints } from '@redocly/theme/core/utils';
 
 import { activeBrandPaletteLight } from './palette';
 import { darkMode } from './dark';
@@ -1125,8 +1127,8 @@ const error = css`
   --detailed-error-overlay-z-index: var(--z-index-raised);
 
   --detailed-error-modal-width: calc(100% - var(--spacing-lg) * 2);
-  --detailed-error-modal-height: calc(100vh - var(--navbar-height) - var(--spacing-lg) * 2);
-  --detailed-error-modal-top: calc(var(--spacing-lg) + var(--navbar-height));
+  --detailed-error-modal-height: calc(100vh - var(--navbar-stack-height) - var(--spacing-lg) * 2);
+  --detailed-error-modal-top: calc(var(--spacing-lg) + var(--navbar-stack-height));
   --detailed-error-modal-border-radius: var(--border-radius-md);
   --detailed-error-modal-bg-color: var(--bg-color-raised);
   --detailed-error-modal-color: var(--text-color-primary);
@@ -1373,6 +1375,7 @@ export const styles = css<{ palette?: string }>`
     ${productPicker}
     ${responsePanelColors}
     ${search}
+    ${navigationTabs}
     ${select}
     ${sidebar}
     ${sizeAndSpace}
@@ -1413,6 +1416,13 @@ export const styles = css<{ palette?: string }>`
     ${darkMode};
   }
 
+  @media screen and (min-width: ${breakpoints.medium}) {
+    :root:has([data-component-name='NavigationTabs/NavigationTabs']) {
+      --navbar-stack-height: calc(var(--navbar-height) + var(--navigation-tabs-height, 48px));
+      --navbar-row-bottom-border-color: transparent;
+    }
+  }
+
   :root.notransition * {
     transition: none !important;
   }

package/src/core/types/hooks.ts

@@ -28,6 +28,7 @@ import type {
 } from './catalog';
 import type { UserMenuData } from './user-menu';
 import type { ItemState, DrilldownMenuItemDetails } from './sidebar';
+import type { NavigationTabsState } from './navigation-tabs';
 import type {
   SearchItemData,
   SearchFacet,
@@ -119,6 +120,9 @@ export type ThemeHooks = {
     askAi?: boolean;
     retrySearch: () => Promise<void>;
   };
+  useSearchFeatures: () => {
+    askAi?: boolean;
+  };
   useAiSearch: (options?: { filter?: SearchFilterItem[]; product?: string }) => {
     askQuestion: (question: string, history?: AiSearchConversationItem[]) => void;
     isGeneratingResponse: boolean;
@@ -156,6 +160,7 @@ export type ThemeHooks = {
     pushDrilldownState: (drilldownDetails: DrilldownMenuItemDetails) => void;
     backLink?: { slug?: string; label?: string };
   };
+  useNavigationTabs: () => NavigationTabsState | undefined;
   useSidebarSiblingsData: () =>
     | {
         prevPage?: ResolvedNavItemWithLink;

package/src/core/types/index.ts

@@ -7,6 +7,7 @@ export type * from './feedback';
 export type * from './hooks';
 export type * from './markdown';
 export type * from './navbar';
+export type * from './navigation-tabs';
 export * from './search';
 export type * from './select';
 export type * from './sidebar';

package/src/core/types/l10n.ts

@@ -222,6 +222,7 @@ export type TranslationKey =
   | 'catalog.history.revision.current'
   | 'catalog.history.revisions.showLess'
   | 'catalog.history.revisions.showMore'
+  | 'navigationTabs.label'
   | 'sidebar.menu.backLabel'
   | 'sidebar.menu.backToLabel'
   | 'sidebar.actions.show'
@@ -271,6 +272,7 @@ export type TranslationKey =
   | 'mobileMenu.previous'
   | 'mobileMenu.products'
   | 'mobileMenu.version'
+  | 'navbar.label'
   | 'navbar.products'
   | 'page.nextButton'
   | 'page.previousButton'
@@ -360,6 +362,7 @@ export type TranslationKey =
   | 'openapi.hideExample'
   | 'openapi.showExample'
   | 'openapi.expandAll'
+  | 'openapi.deepLink.tooltip'
   | 'openapi.collapseAll'
   | 'openapi.viewSecurityDetails'
   | 'openapi.noResponseExample'

package/src/core/types/navigation-tabs.ts

@@ -0,0 +1,54 @@
+export type NavigationTabMenuEntry = {
+  tabId: string;
+  label: string;
+  labelTranslationKey?: string;
+  link: string;
+  icon?: string;
+  srcSet?: string;
+  external?: boolean;
+  target?: '_self' | '_blank';
+};
+
+export type NavigationTab = {
+  tabId: string;
+  label: string;
+  labelTranslationKey?: string;
+  link?: string;
+  icon?: string;
+  srcSet?: string;
+  menu?: NavigationTabMenuEntry[];
+};
+
+export type NavigationTabsState = {
+  tabs: NavigationTab[];
+  activeTab?: NavigationTab;
+  activeMenuEntry?: NavigationTabMenuEntry;
+};
+
+export type NavigationTabItem = {
+  type: 'link';
+  label: string;
+  labelTranslationKey?: string;
+  link: string;
+  icon?: string;
+  srcSet?: string;
+  external?: boolean;
+  target?: '_self' | '_blank';
+  active?: boolean;
+};
+
+type NavigationTabGroupItem = {
+  type: 'group';
+  label: string;
+  labelTranslationKey?: string;
+  icon?: string;
+  srcSet?: string;
+  items: NavigationTabItem[];
+  active?: boolean;
+};
+
+export type NavigationTabRowItem = NavigationTabItem | NavigationTabGroupItem;
+
+export type NavigationTabsConfig = {
+  items: NavigationTabRowItem[];
+};

package/src/core/utils/Dynamic.tsx

@@ -5,60 +5,86 @@ interface DynamicOptions<TProps extends Record<string, unknown>> {
   loading?: React.ComponentType<TProps>;
 }
 
+/**
+ * A component from `dynamic()`. After `preload()` resolves, the component renders without a
+ * loading state. On the server, `preload()` does not load a client-only component (`ssr: false`).
+ */
+export type DynamicComponent<TProps> = React.ComponentType<TProps> & {
+  preload(): Promise<void>;
+};
+
 export function dynamic<TProps extends Record<string, unknown>>(
   factory: () => Promise<
     React.ComponentType<TProps> | { default: React.ComponentType<TProps> } | Record<string, unknown>
   >,
   { ssr = true, loading }: DynamicOptions<TProps> = {},
-): React.ComponentType<TProps> {
-  const Component = React.lazy(() =>
-    factory().then((mod) => {
-      // Case 1: factory() => import('./SomeModule') - direct import
-      // Case 2: factory() => import('./SomeModule').then(mod => mod.default) - extract default
-      if (typeof mod === 'function') {
-        return { default: mod };
-      }
-
-      // Case 3: factory() => import('./SomeModule').then(mod => ({ default: mod.default })) - manual wrap
-      // Case 4: factory() => import('./SomeModule').then(mod => ({ default: mod.Named })) - manual wrap named
-      if (mod && typeof mod === 'object' && 'default' in mod) {
-        const defaultExport = mod.default;
-
-        // Handle both function components and React component objects (e.g., memo/forwardRef)
-        if (typeof defaultExport === 'function') {
-          return { default: defaultExport as React.ComponentType<TProps> };
+): DynamicComponent<TProps> {
+  let loaded: React.ComponentType<TProps> | undefined;
+  let pending: Promise<{ default: React.ComponentType<TProps> }> | undefined;
+
+  const load = () =>
+    (pending ??= factory()
+      .then((mod) => {
+        // Case 1: factory() => import('./SomeModule') - direct import
+        // Case 2: factory() => import('./SomeModule').then(mod => mod.default) - extract default
+        if (typeof mod === 'function') {
+          return { default: mod };
         }
 
-        if (defaultExport && typeof defaultExport === 'object' && '$$typeof' in defaultExport) {
-          return { default: defaultExport as React.ComponentType<TProps> };
+        // Case 3: factory() => import('./SomeModule').then(mod => ({ default: mod.default })) - manual wrap
+        // Case 4: factory() => import('./SomeModule').then(mod => ({ default: mod.Named })) - manual wrap named
+        if (mod && typeof mod === 'object' && 'default' in mod) {
+          const defaultExport = mod.default;
+
+          // Handle both function components and React component objects (e.g., memo/forwardRef)
+          if (typeof defaultExport === 'function') {
+            return { default: defaultExport as React.ComponentType<TProps> };
+          }
+
+          if (defaultExport && typeof defaultExport === 'object' && '$$typeof' in defaultExport) {
+            return { default: defaultExport as React.ComponentType<TProps> };
+          }
         }
-      }
 
-      // Case 5: factory() => import('./SomeModule').then(mod => mod.Named) - find named export
-      if (mod && typeof mod === 'object') {
-        const modObj = mod as Record<string, unknown>;
+        // Case 5: factory() => import('./SomeModule').then(mod => mod.Named) - find named export
+        if (mod && typeof mod === 'object') {
+          const modObj = mod as Record<string, unknown>;
 
-        for (const key in modObj) {
-          const value = modObj[key];
+          for (const key in modObj) {
+            const value = modObj[key];
 
-          if (typeof value === 'function') {
-            return { default: value as React.ComponentType<TProps> };
-          }
+            if (typeof value === 'function') {
+              return { default: value as React.ComponentType<TProps> };
+            }
 
-          if (value && typeof value === 'object' && '$$typeof' in value) {
-            return { default: value as React.ComponentType<TProps> };
+            if (value && typeof value === 'object' && '$$typeof' in value) {
+              return { default: value as React.ComponentType<TProps> };
+            }
           }
         }
-      }
 
-      throw new Error('Dynamic import did not return a valid React component');
-    }),
-  );
+        throw new Error('Dynamic import did not return a valid React component');
+      })
+      .then(
+        (module) => {
+          loaded = module.default;
+          return module;
+        },
+        (error: unknown) => {
+          // A failed load is not kept, so the next preload tries again.
+          pending = undefined;
+          throw error;
+        },
+      ));
+
+  const LazyComponent = React.lazy(load);
 
   const LoadingComponent: React.ComponentType<TProps> = loading || (() => null);
 
-  return (props: TProps) => {
+  const DynamicComponent = (props: TProps) => {
     const [hasMounted, setHasMounted] = React.useState(false);
+    // Fixed per instance: a change of the element type would remount the component.
+    const [Component] = React.useState(() => loaded ?? LazyComponent);
 
     React.useEffect(() => {
       setHasMounted(true);
@@ -82,4 +108,10 @@ export function dynamic<TProps extends Record<string, unknown>>(
       </React.Suspense>
     );
   };
+
+  return Object.assign(DynamicComponent, {
+    async preload() {
+      if (ssr || typeof window !== 'undefined') await load();
+    },
+  });
 }

package/src/core/utils/index.ts

@@ -17,6 +17,7 @@ export * from './type-guards';
 export * from './dom';
 export * from './toc';
 export * from './menu';
+export * from './navigation-tabs';
 export * from './load-and-navigate';
 export * from './get-scorecard-color-variable';
 export * from './change-text-casing';