Skip to content

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

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

'use client';

/**
 * @file PanelSearchInput.tsx
 * @input Uses React, StyleX, Icon, InputClearButton, theme tokens
 * @output Exports PanelSearchInput — the search row that sits at the top of a
 *   dropdown panel
 * @position Shared internal primitive; used by Selector and MultiSelector
 *
 * A dropdown panel is already a bordered, elevated surface. Nesting a bordered
 * TextInput inside it draws a second box within that box, so the field reads as
 * a control dropped into the menu rather than part of it. This row is the
 * seamless alternative — magnifier, borderless input, clear button — separated
 * from the options by a divider the panel owns.
 *
 * The field is shaped like the option rows under it rather than like a form
 * input: same inset from the panel edge, same `--radius-element` corners, same
 * height. The focus ring is drawn on that rounded box, so focus reads as "this
 * row of the panel" — the same visual language as an item's highlight — instead
 * of ringing the whole panel header. It appears for keyboard focus only; see
 * `fieldKeyboardFocus` for why `:focus-visible` alone does not mean that.
 *
 *   ┌─ panel ──────────────────┐
 *   │ ┌──────────────────────┐ │  ← field: rounded, inset, item-sized
 *   │ │ ⌕  Search…         ✕ │ │
 *   │ └──────────────────────┘ │
 *   ├──────────────────────────┤  ← divider (full-bleed)
 *   │ ┌──────────────────────┐ │
 *   │ │ Apple                │ │  ← option row: same box
 *
 * The clear button is the shared `InputClearButton`, so the affordance and its
 * ghost-button behavior match every other input's clear. It renders AFTER the
 * input in DOM order: the selector components' Tab handling depends on that
 * order to keep the popup open while focus moves onto it.
 *
 * Not exported from the package: it is an implementation detail of the panels
 * that use it, not public API.
 */

import {useCallback, useState, type Ref} from 'react';
import * as stylex from '@stylexjs/stylex';
import type {StyleXStyles} from '@stylexjs/stylex';
import {Icon} from '../Icon/Icon';
import {InputClearButton} from './InputClearButton';
import {mergeProps} from '../utils/mergeProps';
import {useInteractionModalityTracking} from '../utils/interactionModality';
import {useMergedRefs} from '../hooks/useMergedRefs';
import {
  colorVars,
  durationVars,
  easeVars,
  radiusVars,
  spacingVars,
  typeScaleVars,
  typographyVars,
} from '../theme/tokens.stylex';
import type {BaseProps} from '../BaseProps';
import {textEntryTraitAttributes} from './textEntryTraits';
import {inputWrapperStyles} from './inputStyles.stylex';

const styles = stylex.create({
  // Gutter only. Matches the option list's own padding so the field below
  // lines up with the option rows rather than with the panel edge.
  wrapper: {
    paddingBlock: spacingVars['--spacing-1'],
    paddingInline: spacingVars['--spacing-1'],
  },
  // The field proper — the same box an option row draws: `--radius-element`
  // corners and, at md, a 6/8 padding pair that lands it on the option row's
  // 32px height. Focus rings THIS, not the full-width row.
  field: {
    boxSizing: 'border-box',
    display: 'flex',
    alignItems: 'center',
    gap: spacingVars['--spacing-2'],
    width: '100%',
    paddingBlock: spacingVars['--spacing-1-5'],
    paddingInline: spacingVars['--spacing-2'],
    borderRadius: radiusVars['--radius-element'],
    transitionProperty: 'box-shadow',
    transitionDuration: {
      default: durationVars['--duration-fast'],
      '@media (prefers-reduced-motion: reduce)': '0s',
    },
    transitionTimingFunction: easeVars['--ease-standard'],
  },
  // The focus ring, applied only while focus was taken by keyboard (see
  // `isKeyboardFocus`). `:has(input:focus-visible)` stays the CSS condition —
  // the browser's heuristic still decides, this only narrows it — and rings
  // the field rather than the bare <input> so the magnifier and the clear
  // button sit inside it, and so tabbing ONTO the clear button does not
  // re-ring the field.
  //
  // Inset, not the shared 3px-offset outline: the field is inset 4-5px from
  // the panel edge, so an outline at that offset would land on the panel's own
  // border and the divider. Measured, not guessed.
  fieldKeyboardFocus: {
    boxShadow: {
      default: 'none',
      ':has(input:focus-visible)': `inset 0 0 0 2px ${colorVars['--color-accent']}`,
    },
  },
  // The icon span needs explicit flex centering to avoid a line-height offset.
  icon: {
    display: 'flex',
    alignItems: 'center',
    flexShrink: 0,
  },
  input: {
    flexGrow: 1,
    flexShrink: 1,
    minWidth: 0,
    padding: 0,
    margin: 0,
    borderWidth: 0,
    borderStyle: 'none',
    backgroundColor: 'transparent',
    color: colorVars['--color-text-primary'],
    fontFamily: typographyVars['--font-family-body'],
    // Matches the option rows below it, so the query reads as the first line of
    // the list. The floor keeps iOS from zooming on focus — keyed to iOS
    // alone, since only iOS WebKit implements -webkit-touch-callout.
    fontSize: {
      default: typeScaleVars['--text-label-size'],
      '@media (pointer: coarse)': {
        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-label-size']})`,
      },
    },
    lineHeight: typeScaleVars['--text-label-leading'],
    // The field draws the focus ring (see `field`), so the bare input must not
    // draw a second one inside it.
    outline: 'none',
    '::placeholder': {
      color: colorVars['--color-text-secondary'],
    },
  },
});

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

  /**
   * Accessible name for the input. Rendered as `aria-label`: the panel has no
   * visible label for the field, and a placeholder is not a reliable name.
   */
  label: string;

  /** Accessible name for the clear (✕) button, e.g. `Clear Search options`. */
  clearLabel: string;

  /** Placeholder text shown while the query is empty. */
  placeholder?: string;

  /** The current query. */
  value: string;

  /** Called with the next query on every keystroke and on clear. */
  onValueChange: (value: string) => void;

  /** Key handler for the input itself. */
  onKeyDown?: React.KeyboardEventHandler<HTMLInputElement>;

  /** Focus handler for the input; runs after the ring's own bookkeeping. */
  onFocus?: React.FocusEventHandler<HTMLInputElement>;

  /** Blur handler for the input; runs after the ring's own bookkeeping. */
  onBlur?: React.FocusEventHandler<HTMLInputElement>;

  /**
   * Key handler for the row. Events from the input are handled by `onKeyDown`;
   * this one exists for keys pressed on the clear button, which has no other
   * handler of its own.
   */
  onContainerKeyDown?: React.KeyboardEventHandler<HTMLDivElement>;

  /**
   * Styles for the field box itself (the rounded row that draws the focus
   * ring), as opposed to `xstyle`, which lands on the outer gutter. A panel
   * whose rows are taller than a dropdown's — a touch sheet — uses it to grow
   * the field to the same height as its rows.
   */
  fieldXstyle?: StyleXStyles;
  /**
   * Draw the field as the shared input box — the input border, accent while
   * focused, surface and radius — instead of the borderless panel row. A
   * touch sheet is a full-width surface, not a bordered panel, so its field
   * reads as a form input.
   * @default false
   */
  hasInputBox?: boolean;
}

/**
 * Search row for the top of a dropdown panel: magnifier, borderless input, and
 * a clear button once a query is typed, in a rounded box shaped like the
 * option rows beneath it.
 *
 * `className`/`style`/`xstyle` apply to the outer row (use them to match the
 * option list's inline padding); every other prop (`role`, `aria-*`, `id`, …)
 * passes through to the `<input>`, so the caller owns the combobox wiring.
 */
export function PanelSearchInput({
  ref,
  label,
  clearLabel,
  placeholder,
  value,
  onValueChange,
  onKeyDown,
  onFocus,
  onBlur,
  onContainerKeyDown,
  fieldXstyle,
  hasInputBox = false,
  xstyle,
  className,
  style,
  ...props
}: PanelSearchInputProps) {
  // `:focus-visible` matches a text input focused by POINTER as well (CSS
  // Selectors 4, verified in Chromium), so it cannot express "keyboard focus"
  // by itself. Gate it on how the user last interacted; the CSS condition
  // stays `:focus-visible`, this only narrows it.
  const [isKeyboardFocus, setIsKeyboardFocus] = useState(false);

  const {ref: modalityRef, readModality} = useInteractionModalityTracking();
  const mergedInputRef = useMergedRefs(ref, modalityRef);

  const handleFocus = useCallback(
    (e: React.FocusEvent<HTMLInputElement>) => {
      setIsKeyboardFocus(readModality() === 'keyboard');
      onFocus?.(e);
    },
    [onFocus, readModality],
  );

  const handleBlur = useCallback(
    (e: React.FocusEvent<HTMLInputElement>) => {
      setIsKeyboardFocus(false);
      onBlur?.(e);
    },
    [onBlur],
  );

  const handleClear = useCallback(
    (e?: React.MouseEvent<HTMLButtonElement>) => {
      onValueChange('');
      // Clearing puts the caret back where the user was typing, matching
      // TextInput's built-in clear, and it does so inside the tap: iOS raises
      // the software keyboard only for a focus made while the browser is
      // still dispatching the person's tap, and a UIKit search field's clear
      // button makes the field first responder, keyboard and all (measured on
      // iOS 26.2). A frame later the focus came with no keyboard. When the
      // input already has focus, the clear button's pressed state never takes
      // it, so this is a no-op and the keyboard stays where it is.
      // `preventScroll` keeps a pointer tap from scrolling the page.
      if (typeof ref === 'object' && ref?.current) {
        ref.current.focus(
          e == null || e.detail === 0 ? undefined : {preventScroll: true},
        );
      }
    },
    [onValueChange, ref],
  );

  return (
    <div
      onKeyDown={onContainerKeyDown}
      {...mergeProps(stylex.props(styles.wrapper, xstyle), className, style)}>
      <div
        data-keyboard-focus={isKeyboardFocus ? 'true' : undefined}
        {...stylex.props(
          styles.field,
          isKeyboardFocus && styles.fieldKeyboardFocus,
          hasInputBox && inputWrapperStyles.base,
          hasInputBox && inputWrapperStyles.textField,
          fieldXstyle,
        )}>
        <Icon icon="search" size="sm" color="secondary" xstyle={styles.icon} />
        <input
          ref={mergedInputRef}
          type="text"
          // Autocorrect would rewrite names and identifiers.
          {...textEntryTraitAttributes({
            enterKeyHint: 'search',
            hasAutoCorrect: false,
          })}
          aria-label={label}
          placeholder={placeholder}
          value={value}
          onChange={e => onValueChange(e.target.value)}
          onKeyDown={onKeyDown}
          onFocus={handleFocus}
          onBlur={handleBlur}
          {...stylex.props(styles.input)}
          {...props}
        />
        {value !== '' && (
          <InputClearButton label={clearLabel} onClick={handleClear} />
        )}
      </div>
    </div>
  );
}

PanelSearchInput.displayName = 'PanelSearchInput';