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

package/src/core/hooks/use-consent-telemetry.ts

@@ -0,0 +1,56 @@
+import { useEffect, useRef } from 'react';
+
+import type { ConsentRuntime } from '../types/consent';
+
+import { useThemeHooks } from './use-theme-hooks';
+import { getBaseDataAttributes } from '../utils/telemetry/get-base-data-attributes';
+
+type RealmOwnedRuntime = ConsentRuntime & {
+  mode: 'opt-in' | 'opt-out';
+  configuredMode: 'auto' | 'opt-in' | 'opt-out';
+  region: { source: 'timezone' | 'config' | 'none'; timeZone: string | null };
+};
+
+function isRealmOwned(runtime: ConsentRuntime): runtime is RealmOwnedRuntime {
+  return runtime.region.source !== 'provider';
+}
+
+function getConsentRuntime(): ConsentRuntime | undefined {
+  if (typeof window === 'undefined') return undefined;
+  return (window as Window & { redocly?: { consent?: ConsentRuntime } }).redocly?.consent;
+}
+
+// Sends one consent.changed event per visitor choice in the modes Realm owns.
+export function useConsentTelemetry(): void {
+  const { useTelemetry } = useThemeHooks();
+  const telemetry = useTelemetry();
+  const telemetryRef = useRef(telemetry);
+  telemetryRef.current = telemetry;
+
+  useEffect(() => {
+    const found = getConsentRuntime();
+    const runtime = found && isRealmOwned(found) ? found : null;
+    if (!runtime) return;
+    return runtime.on('change', (state) => {
+      const choice =
+        state.analytics && state.marketing
+          ? 'accept'
+          : !state.analytics && !state.marketing
+            ? 'reject'
+            : 'partial';
+      const { origin, pathname, search, hash } = window.location;
+      const uri = `${origin}${pathname}${search}${hash}`;
+      telemetryRef.current.sendConsentChangedMessage([
+        {
+          ...getBaseDataAttributes('consent', 'consent'),
+          choice,
+          mode: runtime.mode,
+          configuredMode: runtime.configuredMode,
+          regionSource: runtime.region.source,
+          gpc: runtime.gpc,
+        },
+        getBaseDataAttributes(uri, 'page', uri),
+      ]);
+    });
+  }, []);
+}

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-theme-hooks.ts

@@ -19,12 +19,28 @@ const fallbacks = {
   useOtelTelemetry: () => ({ send: () => {} }),
   useBreadcrumbs: () => ({ breadcrumbs: [], siblings: undefined }),
   useBanner: () => ({ banner: undefined, dismissBanner: () => {} }),
+  useConsent: () => ({
+    enabled: false,
+    config: undefined,
+    mode: undefined,
+    state: undefined,
+    decided: false,
+    gpc: false,
+    isDialogOpen: false,
+    openDialog: () => {},
+    closeDialog: () => {},
+    accept: () => {},
+    reject: () => {},
+    save: () => {},
+  }),
   useCodeHighlight: () => ({ highlight: (rawContent: string) => rawContent }),
   useUserMenu: () => ({}),
   usePageData: () => null,
   usePageProps: () => ({}),
   usePageSharedData: () => null,
   useMcpData: () => ({ docs: { enabled: false } }),
+  useSearchFeatures: () => ({}),
+  useNavigationTabs: () => undefined,
 };
 
 export const useThemeHooks = () => {

package/src/core/styles/global.ts

@@ -28,6 +28,7 @@ import { code } from '@redocly/theme/components/CodeBlock/variables';
 import { productPicker } from '@redocly/theme/components/Product/variables';
 import { markdown } from '@redocly/theme/components/Markdown/variables';
 import { banner } from '@redocly/theme/components/Banner/variables';
+import { consent } from '@redocly/theme/components/Consent/variables';
 import { markdownAccordion } from '@redocly/theme/markdoc/components/Accordion/variables';
 import { markdownTabs } from '@redocly/theme/markdoc/components/Tabs/variables';
 import { markdownNumberedList } from '@redocly/theme/markdoc/components/NumberedList/variables';
@@ -48,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';
@@ -1124,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);
@@ -1336,6 +1339,7 @@ export const styles = css<{ palette?: string }>`
     ${badges}
     ${banner}
     ${borders}
+    ${consent}
     ${breadcrumbs}
     ${button}
     ${aiAssistantButton}
@@ -1371,6 +1375,7 @@ export const styles = css<{ palette?: string }>`
     ${productPicker}
     ${responsePanelColors}
     ${search}
+    ${navigationTabs}
     ${select}
     ${sidebar}
     ${sizeAndSpace}
@@ -1411,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/consent.ts

@@ -0,0 +1,51 @@
+import type { ConsentConfig } from '@redocly/config';
+import type { TranslationKey } from './l10n';
+
+export type ConsentCategoryId = 'necessary' | 'analytics' | 'marketing';
+
+export type ConsentCategory = {
+  id: ConsentCategoryId;
+  locked: boolean;
+  titleTranslationKey: TranslationKey;
+  descriptionTranslationKey: TranslationKey;
+  titleDefault: string;
+  descriptionDefault: string;
+};
+
+export type ConsentState = { necessary: true; analytics: boolean; marketing: boolean };
+
+export type ConsentChoice = { analytics?: boolean; marketing?: boolean };
+
+export type ConsentProvider = 'onetrust' | 'cookiebot' | 'trustarc' | 'tcf';
+
+export type ConsentRuntime = {
+  configuredMode: 'auto' | 'opt-in' | 'opt-out' | ConsentProvider;
+  mode: 'opt-in' | 'opt-out' | ConsentProvider;
+  state: ConsentState;
+  decided: boolean;
+  gpc: boolean;
+  dialogOpen: boolean;
+  region: { source: 'timezone' | 'config' | 'none' | 'provider'; timeZone: string | null };
+  accept: () => void;
+  reject: () => void;
+  save: (next: ConsentChoice) => void;
+  open: () => void;
+  close: () => void;
+  reload: () => void;
+  on: (event: 'change' | 'open' | 'close', fn: (state: ConsentState) => void) => () => void;
+};
+
+export type UseConsentResult = {
+  enabled: boolean;
+  config: ConsentConfig | undefined;
+  mode: ConsentRuntime['mode'] | undefined;
+  state: ConsentState | undefined;
+  decided: boolean;
+  gpc: boolean;
+  isDialogOpen: boolean;
+  openDialog: () => void;
+  closeDialog: () => void;
+  accept: () => void;
+  reject: () => void;
+  save: (next: ConsentChoice) => void;
+};

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,
@@ -40,6 +41,7 @@ import type {
 import type { SubmitFeedbackParams } from './feedback';
 import type { TFunction } from './l10n';
 import type { BreadcrumbItem } from './breadcrumb';
+import type { UseConsentResult } from './consent';
 
 import type { AiSearchError } from '../constants/search';
 
@@ -90,6 +92,7 @@ export type ThemeHooks = {
     banner: ResolvedBannerConfig | undefined;
     dismissBanner: (content: string) => void;
   };
+  useConsent: () => UseConsentResult;
   useSearch: (
     product?: string,
     autoSearchDisabled?: boolean,
@@ -117,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;
@@ -154,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

@@ -1,11 +1,13 @@
 export type * from './breadcrumb';
 export type * from './catalog';
+export type * from './consent';
 export type * from './l10n';
 export type * from './mcp';
 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'
@@ -513,7 +516,28 @@ export type TranslationKey =
   | 'diagram.zoomOut'
   | 'diagram.reset'
   | 'diagram.close'
-  | 'diagram.viewer';
+  | 'diagram.viewer'
+  | 'consent.title'
+  | 'consent.message'
+  | 'consent.privacyPolicy'
+  | 'consent.customize'
+  | 'consent.rejectAll'
+  | 'consent.acceptAll'
+  | 'consent.acceptAllCookies'
+  | 'consent.savePreferences'
+  | 'consent.dialog.title'
+  | 'consent.dialog.description'
+  | 'consent.dialog.close'
+  | 'consent.alwaysOn'
+  | 'consent.alwaysOff'
+  | 'consent.gpcNotice'
+  | 'consent.category.necessary.title'
+  | 'consent.category.necessary.description'
+  | 'consent.category.analytics.title'
+  | 'consent.category.analytics.description'
+  | 'consent.category.marketing.title'
+  | 'consent.category.marketing.description'
+  | 'consent.settingsLink';
 
 export type Locale = { code: string; name: string };
 

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/consent-settings-link-placement.ts

@@ -0,0 +1,18 @@
+import type { ConsentConfig, RedoclyConfig } from '@redocly/config';
+
+export type SettingsLinkPlacement = 'footer' | 'none';
+
+export function resolveSettingsLinkPlacement(
+  consent: ConsentConfig | undefined,
+  footer: RedoclyConfig['footer'] | undefined,
+): SettingsLinkPlacement {
+  const choice = consent?.settingsLink ?? 'auto';
+  if (choice !== 'auto') {
+    return choice;
+  }
+  const footerShown =
+    Boolean(footer) &&
+    !footer?.hide &&
+    (Boolean(footer?.copyrightText) || (Array.isArray(footer?.items) && footer.items.length > 0));
+  return footerShown ? 'footer' : 'none';
+}

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';
@@ -49,3 +50,4 @@ export * from './tooltip-placement';
 export * from './telemetry/get-base-data-attributes';
 export * from './telemetry/generate-before-after-context';
 export * from './RenderWithLink';
+export * from './consent-settings-link-placement';

package/src/core/utils/mcp.ts

@@ -39,7 +39,7 @@ export function slugifyMcpServerName(name: string): string {
   return name
     .toLowerCase()
     .replace(/[^a-z0-9_-]+/g, '-')
-    .replace(/^-+|-+$/g, '');
+    .replace(/^-+|(?<!-)-+$/g, '');
 }
 
 export function generateClaudeCodeCommand(config: McpConnectionParams): string {

package/src/core/utils/menu.ts

@@ -3,8 +3,10 @@ import type { Location } from 'react-router';
 
 import type { Locale, TFunction } from '../types/l10n';
 import type { ItemState } from '../types/sidebar';
+import type { NavigationTabRowItem, NavigationTabsState } from '../types/navigation-tabs';
 import { MenuItemType } from '../constants/common';
-import { getPathnameForLocale, withoutPathPrefix, withPathPrefix } from './urls';
+import { addLeadingSlash, getPathnameForLocale, withoutPathPrefix, withPathPrefix } from './urls';
+import { toNavigationTabsConfig } from './navigation-tabs';
 
 const TRANSLATION_KEYS = {
   version: 'mobileMenu.version',
@@ -24,10 +26,7 @@ export const mapNavbarItems = (
         ...(navItem.items && {
           items: mapNavbarItems(navItem.items, defaultLocale, currentLocale, locales, location),
         }),
-        ...('link' in navItem && { link: navItem.link || '/' }),
-        active:
-          'link' in navItem &&
-          isItemActive(navItem, defaultLocale, currentLocale, locales, location),
+        active: isItemActive(navItem, defaultLocale, currentLocale, locales, location),
         hasActiveSubItem: !!navItem.items?.find((item) =>
           isItemActive(item, defaultLocale, currentLocale, locales, location),
         ),
@@ -42,10 +41,12 @@ export const isItemActive = (
   locales: Locale[],
   location: Location,
 ): boolean => {
+  if (!item.link) return false;
+
   const pathHash = location.pathname + location.hash;
   const link = item.languageInsensitive
-    ? item.link || ''
-    : getPathnameForLocale(item.link || '/', defaultLocale, currentLocale, locales);
+    ? item.link
+    : getPathnameForLocale(item.link, defaultLocale, currentLocale, locales);
 
   return pathHash === withPathPrefix(link);
 };
@@ -71,7 +72,7 @@ export const buildLanguagesGroup = (
           locale.code,
           locales,
         );
-        const newUrlWithLanguage = `${newLangPathname}${location.search}${location.hash}`;
+        const newUrlWithLanguage = `${addLeadingSlash(newLangPathname)}${location.search}${location.hash}`;
         return {
           type: 'link',
           label: locale.name || locale.code || '',
@@ -112,8 +113,33 @@ export const buildVersionSection = (
   ];
 };
 
+export const buildNavigationTabsSelect = ({
+  navigationTabs,
+}: {
+  navigationTabs: NavigationTabsState | undefined;
+}): ItemState | undefined => {
+  const tabs = toNavigationTabsConfig({ state: navigationTabs })?.items;
+
+  if (!tabs) {
+    return;
+  }
+
+  const activeTab = tabs.find((tab) => tab.active);
+
+  return {
+    type: MenuItemType.Select,
+    label: activeTab?.label ?? 'Navigation tabs',
+    labelTranslationKey: activeTab ? activeTab.labelTranslationKey : 'navigationTabs.label',
+    items: tabs.map(toNavigationTabOption),
+    active: false,
+    hasActiveSubItem: !!activeTab,
+  };
+};
+
 export function getMenuItemType(item: ItemState): MenuItemType {
-  if (item.type === MenuItemType.Separator) {
+  if (item.type === MenuItemType.Select) {
+    return MenuItemType.Select;
+  } else if (item.type === MenuItemType.Separator) {
     return MenuItemType.Separator;
   } else if (item.menuStyle === 'drilldown') {
     return MenuItemType.DrillDown;
@@ -123,3 +149,22 @@ export function getMenuItemType(item: ItemState): MenuItemType {
     return MenuItemType.Operation;
   } else return MenuItemType.Default;
 }
+
+function toNavigationTabOption(tab: NavigationTabRowItem): ItemState {
+  const landing =
+    tab.type === 'group' ? (tab.items.find((entry) => entry.active) ?? tab.items[0]) : tab;
+
+  return {
+    type: tab.type,
+    label: tab.label,
+    labelTranslationKey: tab.labelTranslationKey,
+    icon: tab.icon,
+    srcSet: tab.srcSet,
+    link: landing?.link,
+    external: landing?.external,
+    target: landing?.target,
+    items: [],
+    active: !!tab.active,
+    hasActiveSubItem: false,
+  };
+}

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

@@ -0,0 +1,99 @@
+import type { ThemeHooks } from '../types/hooks';
+import type {
+  NavigationTab,
+  NavigationTabMenuEntry,
+  NavigationTabItem,
+  NavigationTabRowItem,
+  NavigationTabsConfig,
+  NavigationTabsState,
+} from '../types/navigation-tabs';
+
+import { getBaseDataAttributes } from './telemetry/get-base-data-attributes';
+
+type NavbarItemClickedPayload = Parameters<
+  ReturnType<ThemeHooks['useTelemetry']>['sendNavbarMenuItemClickedMessage']
+>[0];
+
+export function toNavigationTabsConfig({
+  state,
+}: {
+  state: NavigationTabsState | undefined;
+}): NavigationTabsConfig | undefined {
+  const items = toNavigationTabEntries(state).map(
+    (entry): NavigationTabRowItem =>
+      entry.kind === 'menu'
+        ? {
+            type: 'group',
+            label: entry.tab.label,
+            labelTranslationKey: entry.tab.labelTranslationKey,
+            icon: entry.tab.icon,
+            srcSet: entry.tab.srcSet,
+            items: entry.entries.map(({ active, ...link }) => toRowLink(link, active)),
+            active: entry.active,
+          }
+        : toRowLink(entry.link, entry.active),
+  );
+
+  return items.length ? { items } : undefined;
+}
+
+export function getNavbarItemClickedPayload(type: 'link' | 'group'): NavbarItemClickedPayload {
+  return [
+    {
+      ...getBaseDataAttributes<'navbarItem', 'navbar', 'urn:redocly:realm:ui:navbar:navbarItem'>(
+        'navbarItem',
+        'navbar',
+      ),
+      type,
+    },
+  ];
+}
+
+type NavigationTabLink = Omit<NavigationTabMenuEntry, 'tabId'>;
+
+type NavigationTabEntry =
+  | { kind: 'link'; link: NavigationTabLink; active: boolean }
+  | {
+      kind: 'menu';
+      tab: NavigationTab;
+      entries: Array<NavigationTabLink & { active: boolean }>;
+      active: boolean;
+    };
+
+function toNavigationTabEntries(state: NavigationTabsState | undefined): NavigationTabEntry[] {
+  if (!state?.tabs.length) return [];
+
+  return state.tabs.flatMap((tab): NavigationTabEntry[] => {
+    const active = state.activeTab?.tabId === tab.tabId;
+
+    if (tab.menu) {
+      const entries = tab.menu
+        .filter((menuEntry) => !!menuEntry.link)
+        .map(({ tabId, ...link }) => ({
+          ...link,
+          active: active && tabId === state.activeMenuEntry?.tabId,
+        }));
+      return entries.length ? [{ kind: 'menu', tab, entries, active }] : [];
+    }
+
+    if (!tab.link) return [];
+
+    return [
+      {
+        kind: 'link',
+        link: {
+          label: tab.label,
+          labelTranslationKey: tab.labelTranslationKey,
+          link: tab.link,
+          icon: tab.icon,
+          srcSet: tab.srcSet,
+        },
+        active,
+      },
+    ];
+  });
+}
+
+function toRowLink(link: NavigationTabLink, active: boolean): NavigationTabItem {
+  return { type: 'link', ...link, active };
+}

package/src/core/utils/urls.ts

@@ -5,7 +5,9 @@ import { DEFAULT_LOCALE_PLACEHOLDER } from '../constants/common';
 export function combineUrls(baseURL: string, ...relativeURLs: (string | undefined)[]) {
   let res = baseURL;
   for (let relativeURL of relativeURLs) {
-    res = relativeURL ? res.replace(/[/\\]+$/, '') + '/' + relativeURL.replace(/^[/\\]+/, '') : res;
+    res = relativeURL
+      ? res.replace(/(?<![/\\])[/\\]+$/, '') + '/' + relativeURL.replace(/^[/\\]+/, '')
+      : res;
   }
 
   return res;