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

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;
@@ -125,14 +126,7 @@ 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}

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/contexts/PortalContainerContext.tsx

@@ -0,0 +1,4 @@
+import { createContext } from 'react';
+
+/** Where theme portals mount; set it inside a shadow root (the AI assistant web component), else `document.body`. */
+export const PortalContainerContext = createContext<HTMLElement | null>(null);

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

@@ -23,6 +23,8 @@ 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 '../search/use-persisted-quick-filter';
 export * from '../use-language-picker';
 export * from './use-element-size';
 export * from './use-time-ago';

package/src/core/hooks/index.ts

@@ -30,6 +30,8 @@ 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 './search/use-persisted-quick-filter';
 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-persisted-quick-filter.ts

@@ -0,0 +1,125 @@
+import { useEffect, useRef, useState } from 'react';
+
+import type { Dispatch, SetStateAction } from 'react';
+import type { SearchFacet, SearchFilterItem } from '../../types/search';
+
+import { createStore, useStore } from '../use-store';
+
+type StoredQuickFilter = Pick<SearchFilterItem, 'field' | 'values'>;
+
+const quickFilterStore = createStore<StoredQuickFilter | null>({
+  storageKey: 'searchQuickFilter',
+  storageType: 'sessionStorage',
+});
+
+const findQuickFilter = (filter: SearchFilterItem[]) => filter.find((item) => item.isQuickFilter);
+
+const withQuickFilter = (filter: SearchFilterItem[], quickFilter: StoredQuickFilter) => [
+  ...filter.filter((item) => !item.isQuickFilter),
+  ...(quickFilter.values.length ? [{ ...quickFilter, isQuickFilter: true }] : []),
+];
+
+const groupFacetValues = (facets: SearchFacet[], field: string) => {
+  const facet = facets.find((item) => item.field === field);
+  const values = facet?.values ?? [];
+  return {
+    present: facet !== undefined,
+    values: values.map((item) => (typeof item === 'string' ? item : item.value)),
+    counted: values.some((item) => typeof item !== 'string' && item.isCounterVisible),
+  };
+};
+
+const isRestorable = (
+  stored: StoredQuickFilter | null,
+  groupField: string,
+): stored is StoredQuickFilter =>
+  !!stored &&
+  stored.field === groupField &&
+  Array.isArray(stored.values) &&
+  stored.values.length > 0 &&
+  stored.values.every((value) => typeof value === 'string');
+
+type UsePersistedQuickFilterOptions = {
+  filter: SearchFilterItem[];
+  setFilter: Dispatch<SetStateAction<SearchFilterItem[]>>;
+  facets: SearchFacet[];
+  groupField: string;
+  query: string;
+  isSearchLoading: boolean;
+  searchError: string | null;
+  enabled?: boolean;
+};
+
+/**
+ * Remembers the quick filter on `groupField` for the browser tab and restores it on mount unless
+ * one is already selected. Restored values are dropped once known not to exist: absent from the
+ * full value list, or from the `groupField` facet left by the first search that finishes without
+ * error on an empty query (the restored value is that search's filter, so a value without
+ * documents is not counted). Does nothing while `enabled` is false.
+ */
+export function usePersistedQuickFilter({
+  filter,
+  setFilter,
+  facets,
+  groupField,
+  query,
+  isSearchLoading,
+  searchError,
+  enabled = true,
+}: UsePersistedQuickFilterOptions): void {
+  const [stored, setStored] = useStore(quickFilterStore, null);
+  const [initial] = useState(() =>
+    enabled && isRestorable(stored, groupField) && !findQuickFilter(filter) ? stored.values : null,
+  );
+  const phaseRef = useRef<'restoring' | 'validating' | 'done'>(initial ? 'restoring' : 'done');
+  const searchedRef = useRef(false);
+
+  useEffect(() => {
+    if (!initial) return;
+    // oxlint-disable-next-line react-you-might-not-need-an-effect/no-pass-data-to-parent -- the filter state belongs to the product's `useSearch` and starts empty on every mount
+    setFilter((current) => withQuickFilter(current, { field: groupField, values: initial }));
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- applies only to the initial state
+  }, []);
+
+  useEffect(() => {
+    if (!enabled) return;
+    const quickFilter = findQuickFilter(filter);
+    // The commit that starts the restore still sees the empty initial filter.
+    if (phaseRef.current === 'restoring') {
+      if (!quickFilter) return;
+      phaseRef.current = 'validating';
+    }
+    if (phaseRef.current === 'validating' && initial) {
+      if (isSearchLoading) searchedRef.current = true;
+      const settled = searchedRef.current && !isSearchLoading && !searchError && !query.trim();
+      const { present, values: known, counted } = groupFacetValues(facets, groupField);
+      if ((known.length && !counted) || (settled && present)) {
+        phaseRef.current = 'done';
+        const values = quickFilter?.values.filter(
+          (value) => known.includes(value) || !initial.includes(value),
+        );
+        if (quickFilter && values && values.length !== quickFilter.values.length) {
+          // oxlint-disable-next-line react-you-might-not-need-an-effect/no-pass-data-to-parent -- the facets arrive after the restore
+          setFilter((current) => withQuickFilter(current, { field: groupField, values }));
+          return;
+        }
+      }
+    }
+    const next = quickFilter ? { field: quickFilter.field, values: quickFilter.values } : null;
+    if (JSON.stringify(next) !== JSON.stringify(stored)) {
+      setStored(next);
+    }
+  }, [
+    enabled,
+    filter,
+    facets,
+    groupField,
+    query,
+    isSearchLoading,
+    searchError,
+    initial,
+    stored,
+    setFilter,
+    setStored,
+  ]);
+}

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/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'
@@ -124,6 +124,9 @@ export type TranslationKey =
   | 'search.ai.error.header.forbidden'
   | 'search.ai.error.header.unauthorized'
   | 'search.ai.feedback.more'
+  | 'search.ai.actions.copy'
+  | 'search.ai.actions.like'
+  | 'search.ai.actions.dislike'
   | 'search.searchItem.deprecated'
   | 'search.searchItem.enum'
   | 'search.searchItem.example'

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;

package/src/core/types/search.ts

@@ -117,6 +117,27 @@ export type ToolCall = {
 
 export type ContentSegment = { type: 'text'; text: string } | { type: 'tool'; toolCall: ToolCall };
 
+export type GroupedContentSegment =
+  | { type: 'text'; text: string }
+  /** `isActive`: the assistant still works on this group, with nothing written after it yet. */
+  | { type: 'tools'; toolCalls: ToolCall[]; isActive: boolean };
+
+export type SearchAiActivityKind = 'thinking' | 'search' | 'code' | 'support';
+
+export type SearchAiActivityStatus = {
+  label: string;
+  detail?: string;
+  kind: SearchAiActivityKind;
+  isRunning: boolean;
+};
+
+export type SearchAiActivityStep = {
+  id: string;
+  label: string;
+  kind: SearchAiActivityKind;
+  isRunning: boolean;
+};
+
 export type AiSearchConversationItem = {
   role: AiSearchConversationRole;
   content: string;

package/src/core/utils/assign-ref.ts

@@ -0,0 +1,9 @@
+import type { Ref } from 'react';
+
+export function assignRef<T>(ref: Ref<T> | undefined, value: T): void {
+  if (typeof ref === 'function') {
+    ref(value);
+  } else if (ref) {
+    ref.current = value;
+  }
+}