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

package/src/components/NavigationTabs/NavigationTabMenu.tsx

@@ -0,0 +1,40 @@
+import React from 'react';
+import styled from 'styled-components';
+
+import type { JSX } from 'react';
+import type { NavigationTabItem } from '@redocly/theme/core/types';
+
+import { DropdownMenu } from '@redocly/theme/components/Dropdown/DropdownMenu';
+import { DropdownMenuItem } from '@redocly/theme/components/Dropdown/DropdownMenuItem';
+import { NavigationTabContent } from '@redocly/theme/components/NavigationTabs/NavigationTabContent';
+
+export type NavigationTabMenuProps = {
+  items: NavigationTabItem[];
+  className?: string;
+};
+
+export function NavigationTabMenu({ items, className }: NavigationTabMenuProps): JSX.Element {
+  return (
+    <NavigationTabMenuWrapper
+      data-component-name="NavigationTabs/NavigationTabMenu"
+      className={className}
+    >
+      <DropdownMenu>
+        {items.map((item, index) => (
+          <DropdownMenuItem
+            key={`${item.label}_${index}`}
+            to={item.link}
+            external={item.external}
+            data-translation-key={item.labelTranslationKey}
+            active={item.active}
+            aria-current={item.active ? 'page' : undefined}
+          >
+            <NavigationTabContent item={item} />
+          </DropdownMenuItem>
+        ))}
+      </DropdownMenu>
+    </NavigationTabMenuWrapper>
+  );
+}
+
+const NavigationTabMenuWrapper = styled.div``;

package/src/components/NavigationTabs/NavigationTabs.tsx

@@ -0,0 +1,83 @@
+import React, { useRef } from 'react';
+import styled from 'styled-components';
+
+import type { JSX } from 'react';
+import type { NavigationTabsConfig } from '@redocly/theme/core/types';
+
+import { breakpoints } from '@redocly/theme/core/utils';
+import { useScrollItemIntoView, useThemeHooks } from '@redocly/theme/core/hooks';
+import { NavigationTab } from '@redocly/theme/components/NavigationTabs/NavigationTab';
+
+export type NavigationTabsProps = {
+  config?: NavigationTabsConfig;
+  className?: string;
+};
+
+export function NavigationTabs({ config, className }: NavigationTabsProps): JSX.Element | null {
+  const { useTranslate } = useThemeHooks();
+  const { translate } = useTranslate();
+  const listRef = useRef<HTMLUListElement | null>(null);
+
+  const tabs = config?.items ?? [];
+  const activeIndex = tabs.findIndex((tab) => tab.active);
+
+  useScrollItemIntoView(listRef, activeIndex);
+
+  if (!tabs.length) {
+    return null;
+  }
+
+  return (
+    <NavigationTabsWrapper
+      data-component-name="NavigationTabs/NavigationTabs"
+      className={className}
+      aria-label={translate('navigationTabs.label', 'Navigation tabs')}
+    >
+      <NavigationTabsList ref={listRef}>
+        {tabs.map((tab, index) => (
+          <NavigationTab key={`${tab.label}_${index}`} tab={tab} />
+        ))}
+      </NavigationTabsList>
+    </NavigationTabsWrapper>
+  );
+}
+
+const NavigationTabsWrapper = styled.nav`
+  display: none;
+  box-sizing: border-box;
+  width: 100%;
+  height: var(--navigation-tabs-height);
+  max-width: var(--navbar-container-max-width);
+  padding: var(--navigation-tabs-padding);
+  background: var(--navigation-tabs-bg-color);
+  border-bottom: var(--navigation-tabs-bottom-border);
+  flex-shrink: 0;
+
+  @media screen and (min-width: ${breakpoints.medium}) {
+    display: flex;
+  }
+
+  @media screen and (min-width: ${breakpoints.max}) {
+    max-width: var(--container-max-width);
+    margin-left: auto;
+    margin-right: auto;
+  }
+`;
+
+const NavigationTabsList = styled.ul`
+  list-style: none;
+  margin: 0 0 calc(-1 * var(--navigation-tabs-border-width));
+  padding: 0;
+  display: flex;
+  flex-wrap: nowrap;
+  align-items: stretch;
+  gap: var(--navigation-tabs-gap);
+  min-width: 0;
+  overflow-x: auto;
+  scrollbar-width: none;
+  -ms-overflow-style: none;
+
+  &::-webkit-scrollbar {
+    display: none;
+  }
+`;

package/src/components/NavigationTabs/variables.ts

@@ -0,0 +1,34 @@
+import { css } from 'styled-components';
+
+export const navigationTabs = css`
+  --navigation-tabs-height: 48px; // @presenter Spacing
+  --navigation-tabs-bg-color: transparent; // @presenter Color
+  --navigation-tabs-border-color: var(--border-color-secondary);
+  --navigation-tabs-border-width: 1px;
+  --navigation-tabs-bottom-border: var(--navigation-tabs-border-width) solid var(--navigation-tabs-border-color);
+  --navigation-tabs-padding-vertical: 0;
+  --navigation-tabs-padding-horizontal: var(--spacing-xl);
+  --navigation-tabs-padding: var(--navigation-tabs-padding-vertical) var(--navigation-tabs-padding-horizontal); // @presenter Spacing
+  --navigation-tabs-gap: var(--spacing-base); // @presenter Spacing
+
+  --navigation-tabs-item-padding-vertical: var(--spacing-xxs);
+  --navigation-tabs-item-padding-horizontal: 0;
+  --navigation-tabs-item-padding: var(--navigation-tabs-item-padding-vertical) var(--navigation-tabs-item-padding-horizontal);
+  --navigation-tabs-item-content-gap: var(--spacing-xs);
+  --navigation-tabs-item-font-size: var(--font-size-base);
+  --navigation-tabs-item-line-height: var(--line-height-base);
+  --navigation-tabs-item-font-weight: var(--font-weight-regular);
+  --navigation-tabs-item-font-weight-active: var(--font-weight-medium);
+  --navigation-tabs-item-text-color: var(--navbar-text-color); // @presenter Color
+  --navigation-tabs-item-text-color-hover: var(--text-color-primary); // @presenter Color
+  --navigation-tabs-item-text-color-active: var(--text-color-primary); // @presenter Color
+  --navigation-tabs-item-bottom-border: var(--navigation-tabs-border-width) solid transparent;
+  --navigation-tabs-item-bottom-border-hover: var(--navigation-tabs-border-width) solid var(--border-color-primary);
+  --navigation-tabs-item-bottom-border-active: var(--navigation-tabs-border-width) solid var(--border-color-inverse);
+  --navigation-tabs-item-border-color-focused: var(--button-border-color-focused);
+  --navigation-tabs-item-border-radius: var(--navbar-item-border-radius);
+  --navigation-tabs-item-icon-size: 1.25em; // @presenter Spacing
+  --navigation-tabs-item-external-icon-margin-left: 0;
+  --navigation-tabs-item-label-font-weight-active: var(--navigation-tabs-item-font-weight-active);
+  --navigation-tabs-item-transition: 150ms ease-in-out;
+`;

package/src/components/Product/utils.ts

@@ -2,5 +2,5 @@ export function getProductClassName(productName: string): string {
   return `product-${productName
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '')}`;
+    .replace(/^-+|(?<!-)-+$/g, '')}`;
 }

package/src/components/Search/SearchAiMessage.tsx

@@ -347,7 +347,7 @@ const ResourceTagsWrapper = styled.div`
   gap: var(--search-ai-resource-tags-gap);
 `;
 
-const ResourceTag = styled(Tag)`
+const ResourceTag = styled(Tag).attrs({ textTransform: 'none' })`
   .tag-default {
     --tag-color: var(--search-ai-resource-tag-text-color);
     max-width: 100%;

package/src/components/Search/SearchAiResponse.tsx

@@ -212,6 +212,7 @@ const ResourceTags = styled.div`
 
 const ResourceTag = styled(Tag).attrs({
   className: 'tag-resource',
+  textTransform: 'none',
 })`
   .tag-default {
     --tag-color: --search-ai-resource-tag-text-color;

package/src/components/Search/SearchTrigger.tsx

@@ -31,7 +31,10 @@ export function SearchTrigger({ onClick, className }: SearchTriggerProps): JSX.E
   }
 
   mainShortcutKey = mainShortcutKey?.toUpperCase();
-  const isMac = getUserAgent().includes('Mac');
+  // A page can be cached and served to every platform, so the server renders a hidden
+  // placeholder and the browser picks the label after hydration.
+  const [isMac, setIsMac] = React.useState<boolean | undefined>(undefined);
+  React.useEffect(() => setIsMac(getUserAgent().includes('Mac')), []);
 
   return (
     <SearchTriggerWrapper
@@ -53,7 +56,9 @@ export function SearchTrigger({ onClick, className }: SearchTriggerProps): JSX.E
         <SearchIcon />
         {translate('search.navbar.label', 'Search')}
         {mainShortcutKey === DEFAULT_KEYBOARD_SHORTCUTS ? (
-          <span>{isMac ? '⌘K' : 'Ctrl+K'}</span>
+          <SearchTriggerShortcut $isPending={isMac === undefined}>
+            {isMac ? '⌘K' : 'Ctrl+K'}
+          </SearchTriggerShortcut>
         ) : (
           <span>{mainShortcutKey}</span>
         )}
@@ -80,6 +85,10 @@ const SearchTriggerButton = styled(Button)`
   }
 `;
 
+const SearchTriggerShortcut = styled.span<{ $isPending: boolean }>`
+  visibility: ${({ $isPending }) => ($isPending ? 'hidden' : 'visible')};
+`;
+
 const SearchTriggerInput = styled.div`
   display: none;
   align-items: center;

package/src/components/Sidebar/Sidebar.tsx

@@ -84,8 +84,8 @@ const SidebarContent = styled.aside<{ $opened: boolean; $collapsed?: boolean }>`
   flex-direction: column;
   width: 100%;
   -webkit-font-smoothing: antialiased;
-  top: calc(var(--navbar-height) + var(--banner-height));
-  height: calc(100vh - var(--navbar-height) - var(--banner-height));
+  top: var(--navbar-offset);
+  height: calc(100vh - var(--navbar-offset));
   overflow-x: hidden;
   ${({ $opened }) => `
     display: ${$opened ? 'flex' : 'none'}

package/src/components/TableOfContent/TableOfContent.tsx

@@ -101,8 +101,8 @@ const TableOfContentHeader = styled.div`
 
 const TableOfContentItems = styled.div`
   position: sticky;
-  top: calc(var(--navbar-height) + var(--toc-offset-top));
-  max-height: calc(100vh - var(--navbar-height) - var(--toc-offset-top));
+  top: calc(var(--navbar-stack-height) + var(--toc-offset-top));
+  max-height: calc(100vh - var(--navbar-stack-height) - var(--toc-offset-top));
   overflow-y: auto;
   width: var(--toc-width);
   border-left: solid 1px var(--toc-border-color);

package/src/core/constants/common.ts

@@ -18,6 +18,7 @@ export enum FEEDBACK_TYPES {
 export const DEFAULT_FEEDBACK_TYPE = FEEDBACK_TYPES.SENTIMENT;
 
 export enum MenuItemType {
+  Select = 'select',
   Separator = 'separator',
   DrillDown = 'drilldown',
   Group = 'group',

package/src/core/constants/consent.ts

@@ -0,0 +1,29 @@
+import type { ConsentCategory } from '../types/consent';
+
+export const CONSENT_CATEGORIES: readonly ConsentCategory[] = [
+  {
+    id: 'necessary',
+    locked: true,
+    titleTranslationKey: 'consent.category.necessary.title',
+    descriptionTranslationKey: 'consent.category.necessary.description',
+    titleDefault: 'Necessary',
+    descriptionDefault:
+      'Needed for the site to work: your consent choice, your color mode, and anonymous usage data.',
+  },
+  {
+    id: 'analytics',
+    locked: false,
+    titleTranslationKey: 'consent.category.analytics.title',
+    descriptionTranslationKey: 'consent.category.analytics.description',
+    titleDefault: 'Analytics',
+    descriptionDefault: 'Helps us understand which pages are useful.',
+  },
+  {
+    id: 'marketing',
+    locked: false,
+    titleTranslationKey: 'consent.category.marketing.title',
+    descriptionTranslationKey: 'consent.category.marketing.description',
+    titleDefault: 'Marketing',
+    descriptionDefault: 'Lets us measure which campaigns bring visitors to this site.',
+  },
+];

package/src/core/constants/index.ts

@@ -10,3 +10,4 @@ export * from './mcp';
 export * from './feedback';
 export * from './heading';
 export * from './markdown';
+export * from './consent';

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

@@ -19,12 +19,27 @@ export const useThemeHooks = vi.fn(() => ({
     sendMcpConnectionSnippetCopiedMessage: vi.fn(),
     sendPageActionsButtonClickedMessage: vi.fn(),
     sendColorModeSwitchedMessage: vi.fn(),
+    sendConsentChangedMessage: vi.fn(),
   })),
   useBreadcrumbs: vi.fn().mockReturnValue({ breadcrumbs: [], siblings: undefined }),
   useBanner: vi.fn(() => ({
     banner: undefined,
     dismissBanner: vi.fn(),
   })),
+  useConsent: vi.fn(() => ({
+    enabled: false,
+    config: undefined,
+    mode: undefined,
+    state: undefined,
+    decided: false,
+    gpc: false,
+    isDialogOpen: false,
+    openDialog: vi.fn(),
+    closeDialog: vi.fn(),
+    accept: vi.fn(),
+    reject: vi.fn(),
+    save: vi.fn(),
+  })),
   usePageSharedData: vi.fn().mockReturnValue({}),
   useCatalogClassic: vi.fn(() => ({
     groups: [],
@@ -55,6 +70,7 @@ export const useThemeHooks = vi.fn(() => ({
     items: [],
     isLoading: false,
   })),
+  useSearchFeatures: vi.fn(() => ({ askAi: false })),
   useAiSearch: vi.fn(() => ({
     askQuestion: vi.fn(),
     isGeneratingResponse: false,
@@ -102,6 +118,7 @@ export const useThemeHooks = vi.fn(() => ({
     pushDrilldownState: vi.fn(),
   }),
   useSidebarSiblingsData: vi.fn(),
+  useNavigationTabs: vi.fn(),
   useSubmitFeedback: vi.fn(() => ({
     submitFeedback: vi.fn(),
   })),

package/src/core/hooks/index.ts

@@ -22,6 +22,8 @@ export * from './menu/use-collapse';
 export * from './feedback/use-report-dialog';
 export * from './use-tabs';
 export * from './use-focus-trap';
+export * from './use-consent-dialog';
+export * from './use-consent-telemetry';
 export * from './use-language-picker';
 export * from './use-product-picker';
 export * from './search/use-search-dialog';
@@ -56,3 +58,4 @@ export * from './use-toast-logic';
 export * from './use-banner-telemetry';
 export * from './use-tooltip-fallback-placement';
 export * from './use-anchor-positioning';
+export * from './use-scroll-item-into-view';

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-consent-dialog.ts

@@ -0,0 +1,51 @@
+import { useEffect, useRef, useState } from 'react';
+
+import type { RefObject } from 'react';
+import type { ConsentCategory, ConsentCategoryId, UseConsentResult } from '../types/consent';
+
+import { CONSENT_CATEGORIES } from '../constants/consent';
+import { useFocusTrap } from './use-focus-trap';
+
+export type ConsentDraft = Record<Exclude<ConsentCategoryId, 'necessary'>, boolean>;
+
+export type UseConsentDialogResult = {
+  draft: ConsentDraft;
+  setCategory: (id: keyof ConsentDraft, value: boolean) => void;
+  dialogRef: RefObject<HTMLDivElement | null>;
+  close: () => void;
+  save: () => void;
+  categories: readonly ConsentCategory[];
+};
+
+export function useConsentDialog(consent: UseConsentResult): UseConsentDialogResult {
+  const [draft, setDraft] = useState<ConsentDraft>(() => ({
+    analytics: consent.state?.analytics ?? consent.mode === 'opt-out',
+    marketing: (consent.state?.marketing ?? consent.mode === 'opt-out') && !consent.gpc,
+  }));
+  const dialogRef = useRef<HTMLDivElement | null>(null);
+  const close = consent.closeDialog;
+  const closeRef = useRef(close);
+  closeRef.current = close;
+
+  useEffect(() => {
+    const previous = document.activeElement as HTMLElement | null;
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') closeRef.current();
+    };
+    document.addEventListener('keydown', onKeyDown);
+    return () => {
+      document.removeEventListener('keydown', onKeyDown);
+      previous?.focus?.();
+    };
+  }, []);
+
+  useFocusTrap(dialogRef);
+
+  const setCategory = (id: keyof ConsentDraft, value: boolean) => {
+    setDraft((current) => ({ ...current, [id]: value }));
+  };
+
+  const save = () => consent.save(draft);
+
+  return { draft, setCategory, dialogRef, close, save, categories: CONSENT_CATEGORIES };
+}