Sidepanel.tsx

import { DocSearch, useDocSearch } from '@docsearch/core';
import type { DocSearchCallbacks, DocSearchRef, DocSearchTheme, SidepanelShortcuts } from '@docsearch/core';
import type { JSX } from 'react';
import React from 'react';
import { createPortal } from 'react-dom';

import type { AgentStudioSearchParameters, AskAiSearchParameters } from './DocSearch';
import type { SidepanelButtonProps, SidepanelProps as SidepanelPanelProps } from './Sidepanel/index';
import { SidepanelButton, Sidepanel } from './Sidepanel/index';

export type { DocSearchRef, DocSearchCallbacks } from '@docsearch/core';

export type SidepanelSearchParameters =
  | {
      /**
       * **Experimental:** Whether to use Agent Studio as the chat backend.
       *
       * This is an experimental feature and its API may change without notice in future releases.
       * Use with caution in production environments.
       *
       * @default false
       */
      agentStudio?: never;
      /**
       * The search parameters to use for the ask AI feature.
       *
       * **NOTE**: If using `agentStudio = true`, the `searchParameters` object is
       * keyed by the index name.
       */
      searchParameters?: AskAiSearchParameters;
    }
  | {
      agentStudio: false;
      searchParameters?: AskAiSearchParameters;
    }
  | {
      agentStudio: true;
      /**
       * The search parameters to use for the ask AI feature.
       * Keyed by the index name.
       *
       * @example
       * {
       *   "INDEX_NAME": { distinct: false }
       * }
       */
      searchParameters?: AgentStudioSearchParameters;
    };

export type DocSearchSidepanelProps = DocSearchCallbacks & {
  /**
   * The assistant ID to use for the ask AI feature.
   */
  assistantId: string;
  /**
   * Public api key with search permissions for the index.
   */
  apiKey: string;
  /**
   * Algolia application id used by the search client.
   */
  appId: string;
  /**
   * The index name to use for the ask AI feature. Your assistant will search this index for relevant documents.
   */
  indexName: string;
  /**
   * Configuration for keyboard shortcuts. Allows enabling/disabling specific shortcuts.
   *
   * @default `{ 'Ctrl/Cmd+I': true }`
   */
  keyboardShortcuts?: SidepanelShortcuts;
  /**
   * Theme overrides applied to the Sidepanel button and panel.
   *
   * @default 'light'
   */
  theme?: DocSearchTheme;
  /**
   * Props specific to the Sidepanel button.
   */
  button?: Omit<SidepanelButtonProps, 'keyboardShortcuts'>;
  /**
   * Props specific to the Sidepanel panel.
   */
  panel?: Omit<SidepanelPanelProps, 'keyboardShortcuts'>;
};

type SidepanelProps = DocSearchSidepanelProps & SidepanelSearchParameters;

function DocSearchSidepanelComponent(
  { keyboardShortcuts, theme, onReady, onOpen, onClose, onSidepanelOpen, onSidepanelClose, ...props }: SidepanelProps,
  ref: React.ForwardedRef<DocSearchRef>,
): JSX.Element {
  return (
    <DocSearch
      keyboardShortcuts={keyboardShortcuts}
      theme={theme}
      ref={ref}
      onReady={onReady}
      onOpen={onOpen}
      onClose={onClose}
      onSidepanelOpen={onSidepanelOpen}
      onSidepanelClose={onSidepanelClose}
    >
      <DocSearchSidepanelComp {...props} />
    </DocSearch>
  );
}

export const DocSearchSidepanel = React.forwardRef(DocSearchSidepanelComponent);

function DocSearchSidepanelComp({
  button: buttonProps = {},
  panel: { portalContainer, ...panelProps } = {},
  ...rootProps
}: DocSearchSidepanelProps): JSX.Element {
  const {
    docsearchState,
    setDocsearchState,
    keyboardShortcuts,
    registerView,
    initialAskAiMessage,
    clearInitialAskAiMessage,
  } = useDocSearch();

  const toggleSidepanelState = React.useCallback(() => {
    setDocsearchState(docsearchState === 'sidepanel' ? 'ready' : 'sidepanel');
  }, [docsearchState, setDocsearchState]);

  const handleClose = (): void => {
    clearInitialAskAiMessage();
    setDocsearchState('ready');
  };

  const handleOpen = (): void => {
    setDocsearchState('sidepanel');
  };

  const containerElement = React.useMemo(() => portalContainer ?? document.body, [portalContainer]);

  React.useEffect(() => {
    registerView('sidepanel');
  }, [registerView]);

  const ButtonComp = React.useMemo(
    () => <SidepanelButton keyboardShortcuts={keyboardShortcuts} onClick={toggleSidepanelState} {...buttonProps} />,
    [keyboardShortcuts, toggleSidepanelState, buttonProps],
  );

  return (
    <>
      {buttonProps.variant === 'inline' ? ButtonComp : createPortal(ButtonComp, containerElement)}
      {createPortal(
        <Sidepanel
          initialMessage={initialAskAiMessage}
          isOpen={docsearchState === 'sidepanel'}
          onClose={handleClose}
          onOpen={handleOpen}
          {...rootProps}
          {...panelProps}
          keyboardShortcuts={keyboardShortcuts}
        />,
        containerElement,
      )}
    </>
  );
}

export * from './Sidepanel/index';