Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
12.3 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';
/**
 * @file CommandPaletteInput.tsx
 * @input Uses React, StyleX, Icon, CommandPaletteContext, DialogContext
 * @output Exports CommandPaletteInput component and props
 * @position Search input for the command palette
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /apps/storybook/stories/CommandPalette.stories.tsx
 * - /apps/storybook/stories/CommandPaletteInput.stories.tsx
 * - /packages/cli/assets/templates/blocks/components/CommandPalette/ (showcase blocks)
 */

import {
  use,
  useCallback,
  useEffect,
  useRef,
  useState,
  type ReactNode,
} from 'react';
import * as stylex from '@stylexjs/stylex';
import {Icon} from '../Icon';
import {Spinner} from '../Spinner';
import {isImeKeyEvent, isRenderable, mergeProps} from '../utils';
import {
  colorVars,
  typeScaleVars,
  spacingVars,
  typographyVars,
} from '../theme/tokens.stylex';
import {useCommandPaletteContext} from './CommandPaletteContext';
import {BusyStartSettleContext} from './busyStartSettle';
import {useDialogContext} from '../Dialog/DialogContext';
import type {BaseProps} from '../BaseProps';
import {themeProps} from '../utils/themeProps';
import {focusOutlineProps} from '../utils/focusOutline.stylex';
import {useInteractionModalityTracking} from '../utils/interactionModality';

import {useMergedRefs} from '../hooks/useMergedRefs';
import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
import {
  registerEnglishFallback,
  useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/CommandPalette/CommandPaletteInput.generated';
import {textEntryTraitAttributes} from '../Field/textEntryTraits';

registerEnglishFallback(english);
const styles = stylex.create({
  wrapper: {
    display: 'flex',
    alignItems: 'center',
    gap: spacingVars['--spacing-2'],
    paddingInline: spacingVars['--spacing-4'],
    paddingBlock: spacingVars['--spacing-3'],
    flexShrink: 0,
  },
  // The icon span needs explicit flex centering to avoid line-height offset
  icon: {
    display: 'flex',
    alignItems: 'center',
    flexShrink: 0,
    color: colorVars['--color-text-secondary'],
  },
  // Groups spinner + endContent on the right with a consistent gap
  end: {
    display: 'flex',
    alignItems: 'center',
    gap: spacingVars['--spacing-1'],
    flexShrink: 0,
  },
  // Delay spinner appearance to avoid flickering on near-instant searches.
  // Uses @starting-style + transition-delay so the spinner only appears
  // if the search is still pending after 150ms.
  spinner: {
    opacity: 1,
    transitionProperty: 'opacity',
    transitionDuration: '1ms',
    transitionDelay: '150ms',
    '@starting-style': {
      opacity: 0,
    },
  },
  input: {
    flex: 1,
    minWidth: 0,
    borderWidth: 0,
    borderStyle: 'none',
    backgroundColor: 'transparent',
    color: colorVars['--color-text-primary'],
    fontFamily: typographyVars['--font-family-body'],
    // The 16px floor is iOS-only: iOS Safari zooms the page when a focused
    // control sits under 16px, and only iOS WebKit implements
    // -webkit-touch-callout to key the coarse-pointer floor to it.
    fontSize: {
      default: typeScaleVars['--text-body-size'],
      '@media (pointer: coarse)': {
        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
      },
    },
    lineHeight: typeScaleVars['--text-body-leading'],
    padding: 0,
    '::placeholder': {
      color: colorVars['--color-text-secondary'],
    },
  },
});

export interface CommandPaletteInputProps extends Omit<
  BaseProps<HTMLInputElement>,
  'onChange'
> {
  /** Ref forwarded to the input element (for focus management). */
  ref?: React.Ref<HTMLInputElement>;

  /**
   * The current search value.
   * When omitted inside CommandPalette, reads from context.
   */
  value?: string;

  /**
   * Called when the search value changes.
   * When omitted inside CommandPalette, writes to context.
   */
  onValueChange?: (value: string) => void;

  /**
   * Placeholder text for the input.
   * @default 'Search…'
   */
  placeholder?: string;

  /**
   * Accessible label for the query field, announced by screen readers. The
   * placeholder is never the field's name.
   * @default 'Search commands'
   */
  label?: string;

  /**
   * Whether to auto-focus the input when mounted.
   * @default true
   */
  hasAutoFocus?: boolean;

  /**
   * Content rendered at the trailing end of the input, after the spinner.
   * Use for clear buttons, keyboard shortcuts, or other trailing actions.
   * The spinner (when busy) appears immediately before this content with a 4px gap.
   */
  endContent?: ReactNode;

  /** Native onChange handler for the input element. */
  onChange?: React.ChangeEventHandler<HTMLInputElement>;
}

/**
 * Search input for the command palette.
 *
 * Renders a search icon and a text input. Auto-focuses when mounted
 * so users can start typing immediately.
 *
 * When used inside CommandPalette, automatically wires to the
 * context for search state and keyboard navigation (via useCombobox).
 * Can also be used standalone with explicit value/onValueChange props.
 *
 * @compositionHint Place as the first child of CommandPalette.
 *
 * @example
 * ```
 * <CommandPalette isOpen={isOpen} onOpenChange={setIsOpen}>
 *   <CommandPaletteInput placeholder="Search commands..." />
 * </CommandPalette>
 * ```
 */
export function CommandPaletteInput({
  value: controlledValue,
  onValueChange,
  placeholder: placeholderFromProps,
  label,
  hasAutoFocus = true,
  endContent,
  onChange,
  onKeyDown,
  onFocus,
  onBlur,
  ref,
  xstyle,
  className,
  style,
  ...props
}: CommandPaletteInputProps) {
  const t = useComponentTranslator();
  const placeholder =
    placeholderFromProps ?? t('@astryx.commandPalette.input.placeholder');
  const ctx = useCommandPaletteContext();
  // Inside CommandPalette the results surface is a listbox only while it holds
  // selectable results; empty and pending states expose no popup.
  const hasListbox = ctx ? ctx.selectableItems.length > 0 : true;
  const dialogContext = useDialogContext();
  const inputRef = useRef<HTMLInputElement>(null);
  // The search Spinner is decorative; the input announces each busy start,
  // including the load on opening or clearing the query. Inside the palette's
  // native modal it does so from a region in the dialog (spec:AST-086 FR8, FR3).
  const settleBusyAnnouncement = useBusyAnnouncement(
    ctx?.isBusy === true,
    t('@astryx.commandPalette.loading'),
    inputRef,
  );
  // Keeps the palette holding this input's settle function, so the palette can
  // drop a busy start not yet announced when a search's outcome is about to be
  // announced (spec:AST-086 FR8).
  const registerSettle = use(BusyStartSettleContext);
  useEffect(() => {
    if (registerSettle == null) {
      return;
    }
    registerSettle(settleBusyAnnouncement);
    return () => registerSettle(null);
  }, [registerSettle, settleBusyAnnouncement]);
  const [isKeyboardFocus, setIsKeyboardFocus] = useState(false);

  // Text-entry controls match :focus-visible after pointer focus in Chromium.
  // Keep the shared selector, but narrow its ring to focus acquired through
  // keyboard navigation so a click or pointer-opened palette stays unringed.
  const {ref: modalityRef, readModality} = useInteractionModalityTracking();
  const handleFocus = useCallback(
    (event: React.FocusEvent<HTMLInputElement>) => {
      setIsKeyboardFocus(readModality() === 'keyboard');
      onFocus?.(event);
    },
    [onFocus, readModality],
  );
  const handleBlur = useCallback(
    (event: React.FocusEvent<HTMLInputElement>) => {
      setIsKeyboardFocus(false);
      onBlur?.(event);
    },
    [onBlur],
  );

  // Use context values as fallback
  const value = controlledValue ?? ctx?.search;
  const handleValueChange = onValueChange ?? ctx?.setSearch;
  const accessibleLabel =
    props['aria-label'] ?? label ?? t('@astryx.commandPalette.input.label');
  const hasEndContent = isRenderable(endContent);
  // A popup attribute the caller passes is caller-owned even while its value
  // is undefined (`aria-expanded={open || undefined}`), so the role stays
  // stable as the caller's popup opens and closes, and a present value is
  // passed through unchanged.
  // `aria-haspopup` counts unless it says there is no popup.
  const callerSets = (key: keyof typeof props) => Object.hasOwn(props, key);
  const callerDeclaresPopup =
    callerSets('aria-haspopup') &&
    props['aria-haspopup'] !== false &&
    props['aria-haspopup'] !== 'false';
  const callerOwnsPopup =
    !ctx &&
    (props.role === 'combobox' ||
      callerSets('aria-expanded') ||
      callerSets('aria-autocomplete') ||
      callerSets('aria-controls') ||
      callerSets('aria-owns') ||
      callerSets('aria-activedescendant') ||
      callerDeclaresPopup);
  const standaloneRole = callerSets('role')
    ? props.role
    : callerOwnsPopup
      ? 'combobox'
      : 'searchbox';

  // When rendered inside an inline dialog, disable auto-focus by default
  // to avoid stealing focus from the surrounding page.
  const effectiveAutoFocus = hasAutoFocus && dialogContext?.isInline !== true;

  // Auto-focus on mount
  useEffect(() => {
    if (effectiveAutoFocus && inputRef.current) {
      requestAnimationFrame(() => {
        inputRef.current?.focus();
      });
    }
  }, [effectiveAutoFocus]);

  // Keyboard navigation — delegates to useCombobox via context
  const handleKeyDown = useCallback(
    (e: React.KeyboardEvent<HTMLInputElement>) => {
      onKeyDown?.(e);
      if (e.defaultPrevented || isImeKeyEvent(e.nativeEvent)) {
        // An in-progress IME composition owns Enter, Escape, and arrows. Let
        // the input method finish or cancel composition without selecting or
        // dismissing palette content.
        return;
      }
      // Delegate to useCombobox's keyboard handler from context
      ctx?.onKeyDown(e);
    },
    [ctx, onKeyDown],
  );

  return (
    <div
      {...mergeProps(
        themeProps('command-palette-input'),
        stylex.props(styles.wrapper, xstyle),
        className,
        style,
      )}>
      <span {...stylex.props(styles.icon)}>
        <Icon icon="search" size="sm" color="inherit" />
      </span>
      <input
        {...props}
        ref={useMergedRefs(ref, inputRef, modalityRef)}
        {...(isKeyboardFocus
          ? focusOutlineProps.focusVisible(styles.input)
          : focusOutlineProps.suppressed(styles.input))}
        type="text"
        // Autocorrect would rewrite names and identifiers.
        {...textEntryTraitAttributes({
          enterKeyHint: 'search',
          hasAutoCorrect: false,
        })}
        role={ctx ? 'combobox' : standaloneRole}
        aria-expanded={
          ctx
            ? ctx.isOpen && hasListbox
            : callerSets('aria-expanded')
              ? props['aria-expanded']
              : callerOwnsPopup || undefined
        }
        aria-autocomplete={
          ctx
            ? 'list'
            : callerSets('aria-autocomplete')
              ? props['aria-autocomplete']
              : callerOwnsPopup
                ? 'list'
                : undefined
        }
        aria-controls={
          ctx ? (hasListbox ? ctx.listId : undefined) : props['aria-controls']
        }
        aria-activedescendant={
          ctx
            ? hasListbox &&
              ctx.highlightedIndex >= 0 &&
              ctx.highlightedIndex < ctx.selectableItems.length
              ? ctx.getItemId(ctx.highlightedIndex)
              : undefined
            : props['aria-activedescendant']
        }
        // Placeholder text is never the field's name (AST-056 AR2).
        aria-label={accessibleLabel}
        placeholder={placeholder}
        value={value}
        data-autofocus={effectiveAutoFocus || undefined}
        onChange={e => {
          handleValueChange?.(e.target.value);
          onChange?.(e);
        }}
        onKeyDown={handleKeyDown}
        onFocus={handleFocus}
        onBlur={handleBlur}
      />
      {(ctx?.isBusy || hasEndContent) && (
        <span {...stylex.props(styles.end)}>
          {ctx?.isBusy && (
            <span {...stylex.props(styles.icon, styles.spinner)}>
              <Spinner size="sm" aria-hidden="true" />
            </span>
          )}
          {hasEndContent && endContent}
        </span>
      )}
    </div>
  );
}

CommandPaletteInput.displayName = 'CommandPaletteInput';