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

package/src/components/Segmented/Segmented.tsx

@@ -5,34 +5,43 @@ import type { ForwardedRef, ReactElement } from 'react';
 import type { SegmentedProps } from '@redocly/theme/core/types';
 
 import { typedMemo } from '@redocly/theme/core/hoc/typed-memo';
+import { useTabList } from '@redocly/theme/core/hooks';
 
 function SegmentedComponent<T>(
   { options, onChange, value, className = '', size = 'regular' }: SegmentedProps<T>,
   ref?: ForwardedRef<HTMLDivElement>,
 ): ReactElement {
+  const { tabListProps, getTabProps } = useTabList({
+    count: options.length,
+    activeIndex: options.findIndex((opt) => value == opt.value),
+    onChange: (index) => onChange(options[index]),
+  });
+
   return (
     <SegmentedGroup
       ref={ref}
       data-component-name="Segmented/Segmented"
       className={`tag-grey ${size} ${className}`}
-      role="tablist"
+      {...tabListProps}
       $size={size}
     >
-      {options.map((opt, index) => (
-        <React.Fragment key={index}>
-          {opt.divider}
-          <SegmentedItem
-            key={opt.label}
-            role="tab"
-            title={opt.label}
-            onClick={() => onChange(opt)}
-            $isActive={value == opt.value}
-            $size={size}
-          >
-            {opt.element || opt.label}
-          </SegmentedItem>
-        </React.Fragment>
-      ))}
+      {options.map((opt, index) => {
+        const { 'aria-controls': _noPanel, ...tabProps } = getTabProps(index);
+        return (
+          <React.Fragment key={index}>
+            {opt.divider}
+            <SegmentedItem
+              key={opt.label}
+              {...tabProps}
+              title={opt.label}
+              $isActive={value == opt.value}
+              $size={size}
+            >
+              {opt.element || opt.label}
+            </SegmentedItem>
+          </React.Fragment>
+        );
+      })}
     </SegmentedGroup>
   );
 }

package/src/components/Select/Select.tsx

@@ -63,6 +63,7 @@ export function Select<T>(props: SelectProps<T>): JSX.Element {
   const [filteredOptions, setFilteredOptions] = useState<SelectOption<T>[]>(options);
   const [stickyInputValue, setStickyInputValue] = useState<string>(placeholder || '');
   const inputId = useId();
+  const listboxId = `${inputId}-listbox`;
 
   useOutsideClick(selectRef, () => {
     setDropdownActive(false);
@@ -189,7 +190,8 @@ export function Select<T>(props: SelectProps<T>): JSX.Element {
     return (
       <SelectInput
         id={inputId}
-        listboxId={inputId}
+        listboxId={listboxId}
+        expanded={dropdownActive}
         selectedOptions={selectedOptions}
         searchValue={searchValue}
         placeholder={placeholder}
@@ -223,10 +225,14 @@ export function Select<T>(props: SelectProps<T>): JSX.Element {
           setDropdownActive(!dropdownActive);
         }
       }}
-      tabIndex={0}
-      aria-haspopup="listbox"
-      aria-expanded={dropdownActive}
-      aria-label="Select option"
+      tabIndex={searchable ? undefined : 0}
+      {...(!searchable && {
+        role: 'combobox',
+        'aria-haspopup': 'listbox' as const,
+        'aria-expanded': dropdownActive,
+        'aria-controls': listboxId,
+        'aria-label': 'Select option',
+      })}
       onFocus={(e) => {
         if (e.target === selectRef.current) {
           selectInputRef.current?.focus();
@@ -245,7 +251,7 @@ export function Select<T>(props: SelectProps<T>): JSX.Element {
         alignment={alignment}
         active={!renderInput ? dropdownActive : undefined}
       >
-        <SelectDropdownMenu role="listbox" footer={footer}>
+        <SelectDropdownMenu id={listboxId} role="listbox" footer={footer}>
           {filteredOptions.length === 0 ? (
             <DropdownMenuItem disabled>
               {translate('select.noResults', 'No results')}

package/src/components/Select/SelectInput.tsx

@@ -6,6 +6,7 @@ import type { SelectOption } from '@redocly/theme/core/types';
 import { Tag } from '@redocly/theme/components/Tag/Tag';
 import { CloseIcon } from '@redocly/theme/icons/CloseIcon/CloseIcon';
 import { Button } from '@redocly/theme/components/Button/Button';
+import { assignRef } from '@redocly/theme/core/utils';
 
 type SelectInputProps<T> = {
   id?: string;
@@ -22,6 +23,7 @@ type SelectInputProps<T> = {
   placeholder?: string;
   multiple?: boolean;
   searchable?: boolean;
+  expanded?: boolean;
   clearable?: boolean;
   inputRef?: React.ForwardedRef<HTMLInputElement>;
   /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
@@ -48,6 +50,7 @@ export function SelectInput<T>(props: SelectInputProps<T>): React.ReactNode {
     stickyValue,
     multiple,
     searchable,
+    expanded,
     clearable,
     clearHandler,
     searchHandler,
@@ -123,17 +126,15 @@ export function SelectInput<T>(props: SelectInputProps<T>): React.ReactNode {
         if (!input) return;
 
         inputRef.current = input;
-
-        if (!forwardedInputRef) return;
-
-        if (typeof forwardedInputRef === 'function') {
-          forwardedInputRef(input);
-        } else {
-          forwardedInputRef.current = input;
-        }
+        assignRef(forwardedInputRef, input);
       }}
       $width={multiple ? (!searchValue && selectedOptions.length ? '10px' : 'auto') : '100%'}
       tabIndex={0}
+      role="combobox"
+      aria-expanded={!!expanded}
+      aria-controls={listboxId}
+      aria-autocomplete="list"
+      aria-label="Select option"
       onFocus={(e) => {
         e.stopPropagation();
       }}
@@ -156,16 +157,7 @@ export function SelectInput<T>(props: SelectInputProps<T>): React.ReactNode {
   );
 
   return (
-    <SelectInputWrapper
-      id={id}
-      onFocus={onFocusHandler}
-      onClick={onClickHandler}
-      role="button"
-      aria-haspopup="listbox"
-      aria-controls={listboxId}
-      aria-owns={listboxId}
-      aria-label="Select option"
-    >
+    <SelectInputWrapper id={id} onFocus={onFocusHandler} onClick={onClickHandler}>
       {!onlyIcon && (
         <>
           <SelectInputValue>

package/src/components/SplitButton/SplitButton.tsx

@@ -1,4 +1,4 @@
-import React from 'react';
+import React, { useRef } from 'react';
 import styled from 'styled-components';
 
 import type { ComponentProps, JSX } from 'react';
@@ -45,9 +45,14 @@ export function SplitButton(props: SplitButtonProps): JSX.Element {
   } = props;
 
   const hasMenu = typeof children === 'function' || React.Children.toArray(children).length > 0;
+  const wrapperRef = useRef<HTMLDivElement>(null);
 
   return (
-    <SplitButtonWrapper data-component-name="SplitButton/SplitButton" className={className}>
+    <SplitButtonWrapper
+      data-component-name="SplitButton/SplitButton"
+      className={className}
+      ref={wrapperRef}
+    >
       <ButtonGroup variant={variant} size={size}>
         {button}
         {hasMenu ? (
@@ -56,6 +61,7 @@ export function SplitButton(props: SplitButtonProps): JSX.Element {
             placement={placement}
             alignment={alignment}
             portalled={portalled}
+            alignmentAnchorRef={wrapperRef}
             withArrow
             onOpen={onOpen}
             onClose={onClose}

package/src/core/constants/mcp.ts

@@ -1,15 +1,9 @@
-import type { MCPOption } from '../types/mcp';
-
 export const DEFAULT_MCP_SERVER_NAME = 'mcp-server';
 
 export const MCP_ROUTE = '/mcp';
 
 export const PUBLIC_MCP_ROUTE = '/mcp-public';
 
-export const DEFAULT_MCP_OPTIONS: MCPOption[] = [
-  'cursor',
-  'vscode',
-  'claude-code',
-  'codex',
-  'copy',
-];
+export const MCP_OPTIONS = ['cursor', 'vscode', 'claude-code', 'codex', 'copy'] as const;
+
+export const DEFAULT_MCP_OPTIONS = [...MCP_OPTIONS];

package/src/core/constants/search.ts

@@ -53,7 +53,7 @@ export const TOOL_CALL_DISPLAY_TEXT: Partial<
 > = {
   [ToolCallName.SearchDocumentation]: {
     inProgressText: 'Searching documentation...',
-    completedText: 'Search completed',
+    completedText: 'Searched the documentation',
   },
   [ToolCallName.ListApis]: {
     inProgressText: 'Browsing APIs...',
@@ -75,6 +75,10 @@ export const TOOL_CALL_DISPLAY_TEXT: Partial<
     inProgressText: 'Reading API description...',
     completedText: 'Read API description',
   },
+  [ToolCallName.Execute]: {
+    inProgressText: 'Running code...',
+    completedText: 'Ran code',
+  },
   [ToolCallName.DescribeTools]: {
     inProgressText: 'Discovering available tools...',
     completedText: 'Discovered available tools',

package/src/core/hooks/__mocks__/index.ts

@@ -23,6 +23,7 @@ export * from '../menu/use-mobile-menu-levels';
 export * from '../feedback/use-report-dialog';
 export * from '../use-product-picker';
 export * from '../search/use-search-dialog';
+export * from '../search/use-search-ai-activity';
 export * from '../use-language-picker';
 export * from './use-element-size';
 export * from './use-time-ago';

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

@@ -20,6 +20,7 @@ export const useThemeHooks = vi.fn(() => ({
     sendPageActionsButtonClickedMessage: vi.fn(),
     sendColorModeSwitchedMessage: vi.fn(),
     sendConsentChangedMessage: vi.fn(),
+    sendFilterCheckboxToggledMessage: vi.fn(),
   })),
   useBreadcrumbs: vi.fn().mockReturnValue({ breadcrumbs: [], siblings: undefined }),
   useBanner: vi.fn(() => ({

package/src/core/hooks/index.ts

@@ -21,6 +21,7 @@ export * from './menu/use-mobile-menu-levels';
 export * from './menu/use-collapse';
 export * from './feedback/use-report-dialog';
 export * from './use-tabs';
+export * from './use-tab-list';
 export * from './use-focus-trap';
 export * from './use-consent-dialog';
 export * from './use-consent-telemetry';
@@ -29,6 +30,7 @@ export * from './use-product-picker';
 export * from './search/use-search-dialog';
 export * from './search/use-search-filter';
 export * from './search/use-feedback-tooltip';
+export * from './search/use-search-ai-activity';
 export * from './use-controlled-state';
 export * from './use-codeblock-tabs-controls';
 export * from './code-walkthrough/use-code-walkthrough';

package/src/core/hooks/menu/use-collapse.ts

@@ -207,5 +207,5 @@ export function useEvent<T extends (...args: any[]) => any>(callback?: T): T {
     ref.current = callback;
   });
 
-  return useCallback(((...args: Parameters<T>) => ref.current?.(...args)) as T, []);
+  return useCallback((...args: Parameters<T>) => ref.current?.(...args), []) as T;
 }

package/src/core/hooks/search/use-search-ai-activity.ts

@@ -0,0 +1,31 @@
+import type { SearchAiActivityStatus, SearchAiActivityStep, ToolCall } from '../../types/search';
+
+import { useThemeHooks } from '../use-theme-hooks';
+import { getSearchAiActivityStatus, getSearchAiActivityStep } from '../../utils/search-ai-activity';
+
+type UseSearchAiActivityParams = {
+  toolCalls: ToolCall[];
+  isActive: boolean;
+};
+
+type UseSearchAiActivityReturn = {
+  status: SearchAiActivityStatus;
+  steps: SearchAiActivityStep[];
+};
+
+export function useSearchAiActivity({
+  toolCalls,
+  isActive,
+}: UseSearchAiActivityParams): UseSearchAiActivityReturn {
+  const { useTranslate } = useThemeHooks();
+  const { translate } = useTranslate();
+
+  const runningToolCall = isActive ? toolCalls.find((toolCall) => !toolCall.result) : undefined;
+
+  return {
+    status: getSearchAiActivityStatus(toolCalls, isActive, runningToolCall, translate),
+    steps: toolCalls.map((toolCall) =>
+      getSearchAiActivityStep(toolCall, isActive && !toolCall.result, translate),
+    ),
+  };
+}

package/src/core/hooks/use-connect-mcp-button.ts

@@ -7,7 +7,7 @@ import { useThemeHooks } from './use-theme-hooks';
 import { useMCPConfig } from './use-mcp-config';
 import { ClipboardService } from '../utils/clipboard-service';
 import { DEFAULT_MCP_OPTIONS } from '../constants/mcp';
-import { generateClaudeCodeCommand, generateCodexCommand } from '../utils/mcp';
+import { generateClaudeCodeCommand, generateCodexCommand, isMCPOption } from '../utils/mcp';
 import { getBaseDataAttributes } from '../utils/telemetry/get-base-data-attributes';
 
 export type McpButtonOptions = {
@@ -80,7 +80,12 @@ export function useConnectMCPButton({
     [translate],
   );
 
-  const visibleOptions = useMemo(() => options.filter(Boolean), [options]);
+  // Markdoc reports attribute errors but still renders the tag, so `options` can be any value.
+  const visibleOptions = useMemo(
+    () =>
+      Array.isArray(options) ? [...new Set(options.filter(isMCPOption))] : [...DEFAULT_MCP_OPTIONS],
+    [options],
+  );
 
   return {
     copiedOption,

package/src/core/hooks/use-full-height.ts

@@ -3,9 +3,9 @@ import throttle from 'lodash.throttle';
 
 import type { RefObject } from 'react';
 
-export function useFullHeight(element: RefObject<HTMLElement | null>): void {
+export function useFullHeight(elementRef: RefObject<HTMLElement | null>): void {
   const handler = useCallback(() => {
-    if (!element.current) {
+    if (!elementRef.current) {
       return;
     }
 
@@ -14,19 +14,19 @@ export function useFullHeight(element: RefObject<HTMLElement | null>): void {
       return;
     }
 
-    const elementTop = element.current.getBoundingClientRect().top;
+    const elementTop = elementRef.current.getBoundingClientRect().top;
     const footerOffset = footer.offsetTop - window.scrollY - elementTop;
     if (footerOffset > window.innerHeight) {
-      element.current.style.maxHeight = `${window.innerHeight - elementTop}px`;
+      elementRef.current.style.maxHeight = `${window.innerHeight - elementTop}px`;
     } else {
-      element.current.style.maxHeight = `${footerOffset}px`;
+      elementRef.current.style.maxHeight = `${footerOffset}px`;
     }
-  }, [element]);
+  }, [elementRef]);
 
   const throttledHandler = useMemo(() => throttle(handler, 150), [handler]);
 
   useEffect(() => {
-    if (typeof window === 'undefined' || !element.current) {
+    if (typeof window === 'undefined' || !elementRef.current) {
       return () => {
         // nope
       };
@@ -45,5 +45,5 @@ export function useFullHeight(element: RefObject<HTMLElement | null>): void {
       window.removeEventListener('scroll', throttledHandler);
       window.removeEventListener('resize', throttledHandler);
     };
-  }, [throttledHandler, element, handler]);
+  }, [throttledHandler, elementRef, handler]);
 }

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/styles/global.ts

@@ -1330,83 +1330,88 @@ const replay = css`
 `;
 
 
+/** The light theme tokens without a selector, for a host that sets them on one element. */
+export const tokens = css`
+  ${accordion}
+  ${admonition}
+  ${apiReferenceDocs}
+  ${apiReferencePanels}
+  ${badges}
+  ${banner}
+  ${borders}
+  ${consent}
+  ${breadcrumbs}
+  ${button}
+  ${aiAssistantButton}
+  ${cards}
+  ${catalog}
+  ${catalogClassic}
+  ${code}
+  ${codeWalkthrough}
+  ${docsDropdown}
+  ${dropdown}
+  ${error}
+  ${filter}
+  ${footer}
+  ${headingsTypography}
+  ${httpTag}
+  ${image}
+  ${inputs}
+  ${languagePicker}
+  ${lastUpdated}
+  ${links}
+  ${loadProgressBar}
+  ${logo}
+  ${markdown}
+  ${markdownAccordion}
+  ${markdownTabs}
+  ${markdownNumberedList}
+  ${diagram}
+  ${menu}
+  ${mobileMenu}
+  ${modal}
+  ${navbar}
+  ${pages}
+  ${productPicker}
+  ${responsePanelColors}
+  ${search}
+  ${navigationTabs}
+  ${select}
+  ${sidebar}
+  ${sizeAndSpace}
+  ${tag}
+  ${themeColors}
+  ${activeBrandPaletteLight}
+  ${tile}
+  ${toc}
+  ${tooltip}
+  ${typography}
+  ${userMenu}
+  ${versionPicker}
+  ${zIndexDepth}
+  ${scorecardColors}
+  ${statusCode}
+  ${tab}
+  ${icon}
+  ${tree}
+  ${segmented}
+  ${switcher}
+  ${checkbox}
+  ${feedback}
+  ${scorecard}
+  ${datePicker}
+  ${replay}
+  ${skipContent}
+  ${pageActions}
+  ${svgViewer}
+  ${toast}
+  ${pageNavigation}
+
+`;
+
 export const styles = css<{ palette?: string }>`
   :root {
-    ${accordion}
-    ${admonition}
-    ${apiReferenceDocs}
-    ${apiReferencePanels}
-    ${badges}
-    ${banner}
-    ${borders}
-    ${consent}
-    ${breadcrumbs}
-    ${button}
-    ${aiAssistantButton}
-    ${cards}
-    ${catalog}
-    ${catalogClassic}
-    ${code}
-    ${codeWalkthrough}
-    ${docsDropdown}
-    ${dropdown}
-    ${error}
-    ${filter}
-    ${footer}
-    ${headingsTypography}
-    ${httpTag}
-    ${image}
-    ${inputs}
-    ${languagePicker}
-    ${lastUpdated}
-    ${links}
-    ${loadProgressBar}
-    ${logo}
-    ${markdown}
-    ${markdownAccordion}
-    ${markdownTabs}
-    ${markdownNumberedList}
-    ${diagram}
-    ${menu}
-    ${mobileMenu}
-    ${modal}
-    ${navbar}
-    ${pages}
-    ${productPicker}
-    ${responsePanelColors}
-    ${search}
-    ${navigationTabs}
-    ${select}
-    ${sidebar}
-    ${sizeAndSpace}
-    ${tag}
-    ${themeColors}
-    ${activeBrandPaletteLight}
-    ${tile}
-    ${toc}
-    ${tooltip}
-    ${typography}
-    ${userMenu}
-    ${versionPicker}
-    ${zIndexDepth}
-    ${scorecardColors}
-    ${statusCode}
-    ${tab}
-    ${icon}
-    ${tree}
-    ${segmented}
-    ${switcher}
-    ${checkbox}
-    ${feedback}
-    ${scorecard}
-    ${datePicker}
-    ${replay}
-    ${skipContent}
-    ${pageActions}
-    ${svgViewer}
-    ${toast}
-    ${pageNavigation}
-
+    ${tokens}
     background-color: var(--bg-color);
     color: var(--text-color-primary);
     font-family: var(--font-family-base);

package/src/core/styles/index.ts

@@ -1,3 +1,4 @@
 export * from './global';
 export * from './dark';
-export { xyflow } from './xyflow';
+export { xyflow } from './xyflow';
+export { searchAiAppearAnimation } from './search-ai-appear';

package/src/core/styles/search-ai-appear.ts

@@ -0,0 +1,16 @@
+import { css, keyframes } from 'styled-components';
+
+const appear = keyframes`
+  from {
+    opacity: 0;
+    transform: translateY(4px);
+  }
+`;
+
+export const searchAiAppearAnimation = css`
+  animation: ${appear} var(--search-ai-activity-fade-duration) ease-out;
+
+  @media (prefers-reduced-motion: reduce) {
+    animation: none;
+  }
+`;

package/src/core/types/dropdown.ts

@@ -0,0 +1 @@
+export type DropdownAlignment = 'start' | 'end';

package/src/core/types/index.ts

@@ -25,3 +25,4 @@ export type * from './tooltip';
 export type * from './toast';
 export type * from './link';
 export type * from './button-group';
+export type * from './dropdown';

package/src/core/types/l10n.ts

@@ -113,7 +113,7 @@ export type TranslationKey =
   | 'search.ai.feedback.thanks'
   | 'search.ai.toolCall.executed'
   | 'search.ai.toolCall.executing'
-  | 'search.ai.toolCall.withArgs'
+  | 'search.ai.toolCall.usedTools'
   | 'search.ai.button'
   | 'search.ai.label'
   | 'search.ai.disclaimer'

package/src/core/types/mcp.ts

@@ -1,6 +1,8 @@
+import type { MCP_OPTIONS } from '../constants/mcp';
+
 export type MCPClientType = 'cursor' | 'vscode';
 
-export type MCPOption = 'cursor' | 'vscode' | 'claude-code' | 'codex' | 'copy';
+export type MCPOption = (typeof MCP_OPTIONS)[number];
 
 export type McpConnectionParams = {
   serverName: string;