Skip to content

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

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

'use client';

/**
 * @file ComplexSelector.tsx
 * @input Uses React, StyleX, Field, Icon slots, Layer positioning, and usePopover
 * @output Exports a rich-selector shell with exact token-sized input, secondary, and ghost triggers, plus an imperative open/close handle
 * @position Core implementation; consumed by index.ts
 *
 * SYNC: When modified, update:
 * - /packages/core/src/ComplexSelector/ComplexSelector.doc.mjs
 * - /packages/core/src/ComplexSelector/ComplexSelector.test.tsx
 * - /packages/core/src/ComplexSelector/index.ts
 * - /apps/storybook/stories/ComplexSelector.stories.tsx
 * - /packages/cli/assets/templates/blocks/components/ComplexSelector/ (showcase blocks)
 */

import React, {
  useCallback,
  useId,
  useImperativeHandle,
  useInsertionEffect,
  useOptimistic,
  useRef,
  useTransition,
  type ReactNode,
} from 'react';
import * as stylex from '@stylexjs/stylex';
import type {StyleXStyles} from '@stylexjs/stylex';
import {
  useFieldInputStyling,
  type FieldInputBaseProps,
  type FieldPartStyleProps,
} from '../Field/fieldParts';
import {useDevWarning} from '../hooks/useDevWarning';
import {mergeRefs} from '../utils/mergeRefs';
import {isFocusLost} from '../utils/focusReturn';
import {useMergedRefs} from '../hooks/useMergedRefs';
import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
import {Field, inputWrapperStyles} from '../Field';
import {Icon, renderIconSlot, type IconType} from '../Icon';
import {Spinner} from '../Spinner';
import {layerAnimations} from '../Layer/layerAnimations.stylex';
import type {LayerAlignment, LayerPlacement} from '../Layer/useLayer';
import {usePopover} from '../Popover/usePopover';
import {useResolvedRequired} from '../hooks/useResolvedRequired';
import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
import {
  colorVars,
  durationVars,
  easeVars,
  fontWeightVars,
  radiusVars,
  sizeVars,
  spacingVars,
  typographyVars,
  typeScaleVars,
} from '../theme/tokens.stylex';
import {focusOutlineStyles} from '../utils/focusOutline.stylex';
import {isRenderable, mergeProps} from '../utils';
import {composeEventHandlers} from '../utils/composeEventHandlers';
import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
import {usePressFeedback} from '../hooks/usePressFeedback';
import type {SizeValue} from '../utils/types';
import {themeProps} from '../utils/themeProps';
import {layerViewportInset} from '../Layer/layerViewportInset.stylex';
import type {FieldStatusPlacement} from '../Field/fieldStatusPlacement';
import {
  registerEnglishFallback,
  useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/ComplexSelector/ComplexSelector.generated';

registerEnglishFallback(english);

// The popup content's own block-size cap; the viewport cap is the layer
// runtime's.
const CONTENT_BLOCK_CAP = '480px';

const styles = stylex.create({
  // The status glyph or info-tip keeps its size when the trigger text is long.
  statusTip: {
    display: 'inline-flex',
    alignItems: 'center',
    flexShrink: 0,
  },
  triggerContainer: {
    position: 'relative',
    display: 'flex',
    alignItems: 'center',
    justifyContent: 'space-between',
    gap: spacingVars['--spacing-2'],
    width: '100%',
    paddingBlock: spacingVars['--spacing-2'],
    paddingInline: spacingVars['--spacing-3'],
    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-label-size'],
      '@media (pointer: coarse)': {
        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-label-size']})`,
      },
    },
    lineHeight: typeScaleVars['--text-label-leading'],
    color: colorVars['--color-text-primary'],
    cursor: {
      default: 'pointer',
      ':is(:disabled,[aria-disabled="true"])': 'default',
    },
  },
  trigger: {
    display: 'flex',
    alignItems: 'center',
    justifyContent: 'space-between',
    gap: spacingVars['--spacing-2'],
    flexGrow: 1,
    flexShrink: 1,
    flexBasis: 0,
    minWidth: 0,
    padding: 0,
    margin: 0,
    borderWidth: 0,
    borderStyle: 'none',
    backgroundColor: 'transparent',
    fontFamily: 'inherit',
    fontSize: 'inherit',
    lineHeight: 'inherit',
    color: 'inherit',
    cursor: {
      default: 'pointer',
      ':is(:disabled,[aria-disabled="true"])': 'default',
    },
    outline: 'none',
    borderRadius: radiusVars['--radius-element'],
  },
  triggerText: {
    flexGrow: 1,
    minWidth: 0,
    overflow: 'hidden',
    textOverflow: 'ellipsis',
    whiteSpace: 'nowrap',
    textAlign: 'start',
  },
  placeholder: {
    color: colorVars['--color-text-secondary'],
  },
  triggerGhost: {
    width: 'auto',
    borderWidth: 0,
    backgroundColor: 'transparent',
    boxShadow: {
      default: 'none',
      ':hover:not(:focus-within):where(:not(:disabled,[aria-disabled="true"]))':
        {
          '@media (hover: hover)': 'none',
        },
      ':focus-within': 'none',
    },
    fontWeight: fontWeightVars['--font-weight-medium'],
    transitionProperty:
      'background-image, background-color, color, opacity, transform',
    transform: {
      default: 'scale(1)',
      // A mouse press; under a coarse pointer the touch press model writes
      // `data-astryx-press` instead (see interactionOverlay.stylex.ts).
      ':active': {
        default: 'scale(0.98)',
        '@media (pointer: coarse)': 'scale(1)',
      },
      '[data-astryx-press="on"]': 'scale(0.98)',
    },
  },
  // Keep the input-family width contract while reusing ghost's borderless paint
  // and the neutral resting fill used by secondary buttons.
  triggerSecondary: {
    borderWidth: 0,
    backgroundColor: colorVars['--color-neutral'],
    boxShadow: {
      default: 'none',
      ':hover:not(:focus-within):where(:not(:disabled,[aria-disabled="true"]))':
        {
          '@media (hover: hover)': 'none',
        },
      ':focus-within': 'none',
    },
    fontWeight: fontWeightVars['--font-weight-medium'],
    transitionProperty:
      'background-image, background-color, color, opacity, transform',
    transform: {
      default: 'scale(1)',
      ':active': {
        default: 'scale(0.98)',
        '@media (pointer: coarse)': 'scale(1)',
      },
      '[data-astryx-press="on"]': 'scale(0.98)',
    },
  },
  triggerGhostDisabled: {
    backgroundImage: 'none',
    transform: {
      default: 'none',
      ':active': 'none',
      '[data-astryx-press="on"]': 'none',
    },
  },
  // Only what Icon does not already provide: `sm` gives the 16px box and
  // `color="secondary"` the color, but the glyph still must not shrink inside
  // the flex trigger.
  triggerIcon: {
    flexShrink: 0,
  },
  // Rotation lives on the chevron glyph itself (passed through `xstyle`), not
  // on the layout wrapper above, so the icon's
  // `complex-selector-indicator-icon` theme target and the open/closed
  // transform sit on one element — a theme can restyle the mark and its
  // rotation through a single selector. The wrapper keeps only layout.
  triggerIconRotation: {
    transitionProperty: 'transform',
    // Under reduced motion the chevron turns at once: an in-place state
    // change moves nothing (design:reduced-motion DR1–DR3).
    transitionDuration: {
      default: durationVars['--duration-fast'],
      '@media (prefers-reduced-motion: reduce)': '0s',
    },
    transitionTimingFunction: easeVars['--ease-standard'],
    transformOrigin: 'center',
  },
  triggerIconOpen: {
    transform: 'rotate(180deg)',
  },
  popover: {
    minWidth: 'anchor-size(width)',
  },
  content: {
    boxSizing: 'border-box',
    // The content's own cap, under the layer runtime's viewport cap: the
    // viewport minus its gutters and any bar the app declares through
    // LayerProvider's `inset` (spec:AST-059 FR2, FR6), so the last rows never
    // paint under that bar.
    maxHeight: stylex.firstThatWorks(
      `min(${CONTENT_BLOCK_CAP}, ${layerViewportInset.maxBlockSize})`,
      `min(${CONTENT_BLOCK_CAP}, ${layerViewportInset.maxBlockSizeFallback})`,
    ),
    overflow: 'auto',
    padding: spacingVars['--spacing-3'],
  },
  sm: {
    height: sizeVars['--size-element-sm'],
  },
  md: {
    height: sizeVars['--size-element-md'],
  },
  lg: {
    height: sizeVars['--size-element-lg'],
  },
  disabled: {
    cursor: 'default',
  },
});

export type ComplexSelectorVariant = 'input' | 'secondary' | 'ghost';

export type ComplexSelectorSize = 'sm' | 'md' | 'lg';

const RENDER_TRIGGER_PARTS_MESSAGE =
  '`container*` and `control*` styling props have no effect with `renderTrigger`: ' +
  'no Field box or control box renders. Style the control you render instead.';

/**
 * Props the `renderTrigger` render prop hands to the control the caller
 * renders.
 * Spread them onto that control: it becomes the popup's anchor, the element
 * focus returns to, and the control that announces the popup's state.
 */
export interface ComplexSelectorRenderTriggerProps extends Omit<
  FieldInputBaseProps,
  | keyof FieldPartStyleProps
  | 'id'
  | 'onClick'
  | 'onKeyDown'
  | 'role'
  | 'aria-label'
  | 'aria-haspopup'
  | 'aria-expanded'
  | 'aria-controls'
  | 'aria-busy'
  | 'aria-required'
  | 'aria-disabled'
> {
  /**
   * Attaches the control as the popup's anchor and focus-return target, and
   * forwards it to the selector's own `ref`.
   */
  ref: (element: HTMLElement | null) => void;
  /** The id the field would have given its own button. */
  id: string;
  onClick: (event: React.MouseEvent<HTMLElement>) => void;
  /** ArrowDown opens the popup, as it does on the built-in button. */
  onKeyDown: (event: React.KeyboardEvent<HTMLElement>) => void;
  'aria-haspopup': 'dialog';
  'aria-expanded': boolean;
  'aria-controls': string;
  'aria-busy': boolean | undefined;
  /**
   * The control is the selector's field: a combobox whose popup is a dialog,
   * as on the built-in trigger.
   */
  role: 'combobox';
  /**
   * The field's `label`, unless the selector was given `aria-label` or
   * `aria-labelledby`: a combobox takes no name from its content, so the
   * label names the control as it names the built-in trigger.
   */
  'aria-label': string | undefined;
  /** `'true'` when the field is required. */
  'aria-required': 'true' | undefined;
  /**
   * `'true'` when the selector is disabled. The control keeps its tab stop
   * and the popup does not open (`spec:AST-085`).
   */
  'aria-disabled': 'true' | undefined;
}

export interface ComplexSelectorRenderState {
  /** Whether the selector surface is open. */
  isOpen: boolean;
  /** Whether changeAction/isLoading is pending. */
  isBusy: boolean;
  /** ID of the trigger button. */
  triggerId: string;
  /** ID of the popup content container. */
  contentId: string;
}

/**
 * Imperative control surface for ComplexSelector, accessed via the `handleRef`
 * prop. Methods drive the same popover machinery as the built-in trigger, so
 * they respect focus restoration, light dismiss, and Escape. Prefer these
 * callbacks over mirroring open state in the parent — the selector owns its
 * visibility, and imperative calls avoid the focus-management pitfalls of
 * syncing an external `isOpen` prop. Pair with `onOpenChange` to observe every
 * open and close, including the ones the selector performs itself.
 */
export interface ComplexSelectorHandle {
  /** Open the selector surface. No-op when disabled or already open. */
  open(): void;
  /**
   * Close the selector surface. Focus returns to the trigger only when it
   * would otherwise be lost; a caller-rendered trigger always gets it back.
   */
  close(): void;
  /** Toggle the selector surface open or closed. */
  toggle(): void;
  /** Whether the selector surface is currently open. Reads live state. */
  isOpen(): boolean;
}

export interface ComplexSelectorStatus {
  type: 'warning' | 'error' | 'success';
  message?: string;
}

export interface ComplexSelectorProps<Value> extends Omit<
  FieldInputBaseProps,
  'children' | 'onChange'
> {
  /** Label text for accessibility and the field label. */
  label: string;
  /**
   * Ref to the trigger: the button that opens the popup and carries the
   * accessible name — or, with `renderTrigger`, the caller's control.
   */
  ref?: React.Ref<HTMLElement>;
  /**
   * Click handler on the trigger. It runs before the popup opens; call
   * `preventDefault()` to keep the popup closed. A press elsewhere in the
   * control box goes through the trigger, so it reaches this handler too.
   * With `renderTrigger` it lands on the caller's control and runs after the
   * built-in toggle, which it cannot cancel.
   */
  onClick?: React.MouseEventHandler<HTMLElement>;
  /**
   * Key handler on the trigger. It runs after the built-in handling and
   * receives every key, including the ArrowDown that opens the popup. With
   * `renderTrigger` it lands on the caller's control, runs after the built-in
   * handling, and is skipped for keys that handling cancels.
   */
  onKeyDown?: React.KeyboardEventHandler<HTMLElement>;
  /** Current controlled value. */
  value: Value;
  /** Called when custom content commits a new value. */
  onChange?: (value: Value) => void;
  /** Optional async action after onChange; drives optimistic UI. */
  changeAction?: (value: Value) => void | Promise<void>;
  /** Custom selector surface content rendered inside a dialog popover. */
  children: (
    value: Value,
    onChange: (value: Value) => void,
    close: () => void,
    state: ComplexSelectorRenderState,
  ) => ReactNode;
  /** Label/content shown in the closed trigger. */
  triggerLabel?: ReactNode;
  /** Placeholder shown when triggerLabel is omitted. */
  placeholder?: ReactNode;
  /** Whether to visually hide the field label. */
  isLabelHidden?: boolean;
  /** Helper text displayed below the label. */
  description?: string;
  /** Marks the field optional. */
  isOptional?: boolean;
  /** Marks the field required. */
  isRequired?: boolean;
  /** Blocks opening and value commits, including from an already-open popup. */
  isDisabled?: boolean;
  /** Shows loading state on the trigger. */
  isLoading?: boolean;
  /** Validation status. */
  status?: ComplexSelectorStatus;
  /**
   * How the status message is placed relative to the input.
   * - 'attached': message overlaps directly below the input (bordered treatment; detached when variant is secondary or ghost)
   * - 'detached': message floats below as a separate element with spacing
   * - 'tooltip': no message box; the status icon becomes a focusable info-tip button that reveals the message on hover, keyboard focus, or tap
   * @default 'attached' for input selectors; 'detached' for secondary and ghost selectors
   */
  statusVariant?: FieldStatusPlacement;
  /** Tooltip text displayed next to the label. */
  labelTooltip?: string;
  /** Trigger and field size. */
  size?: ComplexSelectorSize;
  /**
   * Visual trigger style. Secondary matches secondary buttons; ghost matches
   * ghost buttons.
   */
  variant?: ComplexSelectorVariant;
  /** Icon displayed at the start of the trigger. */
  startIcon?: ReactNode | IconType;
  /** Width of the field. */
  width?: SizeValue;
  /** Popup placement. */
  placement?: LayerPlacement;
  /** Popup alignment along the placement axis. */
  alignment?: LayerAlignment;
  /**
   * Imperative handle for programmatic open/close control. Exposes open,
   * close, toggle, and the isOpen query. Use this instead of mirroring open
   * state in the parent — the selector owns its visibility.
   */
  handleRef?: React.Ref<ComplexSelectorHandle>;
  /**
   * Render the control the popup hangs off — a glyph in a list row, a chip,
   * an icon button — instead of the selector's own field and button. Spread
   * the given props onto it; the popup is then anchored to that control and
   * still labelled by `label`. The field chrome (`Field`, status, spinner,
   * chevron) is not rendered; the caller owns the opener. Pair with
   * `handleRef` to open the popup from a keystroke elsewhere.
   *
   * Hover and pressed paint stay yours. The open state reaches your control
   * as `aria-expanded` on the given props, so style it from the rendered
   * attribute. A pressed look keyed to `:active` is not a substitute:
   * `:active` does not behave the same under a coarse pointer, which is why
   * menu rows drop coarse-pointer `:active` paint entirely.
   *
   * @example
   * ```
   * <ComplexSelector
   *   label="Assignee"
   *   renderTrigger={props => <IconButton icon="user" label="Assign" {...props} />}
   * />
   * ```
   *
   * @example
   * ```
   * // Styling the open state from the rendered attribute:
   * // .my-trigger[aria-expanded='true'] { background: var(--color-overlay-pressed); }
   * ```
   */
  renderTrigger?: (props: ComplexSelectorRenderTriggerProps) => ReactNode;
  /**
   * Called whenever the selector surface opens or closes, however it happened
   * — the trigger, the keyboard, a light dismiss, Escape, content that calls
   * `close()`, or the imperative handle. Pair it with `handleRef` to drive the
   * surface from outside without mirroring its state.
   */
  onOpenChange?: (isOpen: boolean) => void;
  /** StyleX styles for the popup content container. */
  contentXstyle?: StyleXStyles;
  /** Test ID for the trigger button. */
  'data-testid'?: string;
}

/** Keeps a click from reaching the control box's open-the-popup handler. */
function stopPropagation(event: React.MouseEvent) {
  event.stopPropagation();
}

/**
 * A selector shell for rich, custom selection surfaces.
 *
 * ComplexSelector owns the field, trigger, popover, focus restore, and async
 * change action flow. Consumers provide the dialog content as a render function,
 * using the supplied `value`, `onChange`, and `close` helpers to compose the
 * right accessible structure for the custom selector.
 *
 * @example
 * ```
 * <ComplexSelector
 *   label="Fruit"
 *   value={value}
 *   onChange={setValue}
 *   triggerLabel={`${value.fruit} ${value.ripeness}`}>
 *   {(value, onChange, close) => (
 *     <FruitGrid
 *       value={value}
 *       onChange={nextValue => {
 *         onChange(nextValue);
 *         close();
 *       }}
 *     />
 *   )}
 * </ComplexSelector>
 * ```
 */
export function ComplexSelector<Value>({
  label,
  value,
  onChange,
  changeAction,
  children,
  triggerLabel,
  placeholder: placeholderFromProps,
  isLabelHidden = false,
  description,
  isOptional = false,
  isRequired = false,
  isDisabled = false,
  isLoading = false,
  status,
  statusVariant = 'attached',
  labelTooltip,
  size = 'md',
  variant = 'input',
  startIcon,
  width,
  placement = 'below',
  alignment = 'start',
  handleRef,
  renderTrigger,
  onOpenChange,
  contentXstyle,
  containerXstyle,
  containerClassName,
  containerStyle,
  controlXstyle,
  controlClassName,
  controlStyle,
  ref,
  id,
  onClick: onClickProp,
  onKeyDown: onKeyDownProp,
  'aria-describedby': ariaDescribedByProp,
  ...restProps
}: ComplexSelectorProps<Value>) {
  const {rest, container} = useFieldInputStyling('ComplexSelector', restProps, {
    containerXstyle,
    containerClassName,
    containerStyle,
  });
  useDevWarning(
    'ComplexSelector',
    RENDER_TRIGGER_PARTS_MESSAGE,
    renderTrigger != null &&
      (containerXstyle != null ||
        containerClassName != null ||
        containerStyle != null ||
        controlXstyle != null ||
        controlClassName != null ||
        controlStyle != null),
  );
  const t = useComponentTranslator();
  const pressable = usePressFeedback();
  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
  const placeholder = placeholderFromProps ?? t('@astryx.selector.placeholder');
  const effectiveStatusVariant =
    variant !== 'input' && statusVariant === 'attached'
      ? 'detached'
      : statusVariant;

  const generatedTriggerId = useId();
  // A caller's `id` lands on the trigger, so the label wiring must use it.
  const triggerId = id ?? generatedTriggerId;
  const labelId = useId();
  const contentId = useId();
  const descriptionId = useId();
  const statusMessageId = useId();
  // With `tooltip` placement, Field renders no message box. The info-tip
  // holds the message and describes the trigger.
  const isTooltipStatus = effectiveStatusVariant === 'tooltip';
  const {statusIcon: statusTip, describedBy: statusTipDescribedBy} =
    useInputStatusIcon({
      status,
      statusVariant: effectiveStatusVariant,
      size: 'sm',
    });
  const ariaDescribedBy =
    [
      description ? descriptionId : null,
      isTooltipStatus
        ? statusTipDescribedBy
        : status?.message
          ? statusMessageId
          : null,
    ]
      .filter((id): id is string => id != null)
      .join(' ') || undefined;

  const triggerRef = useRef<HTMLElement>(null);
  const triggerButtonRef = useMergedRefs<HTMLElement>(triggerRef, ref);

  const [isPending, startTransition] = useTransition();
  const [optimisticValue, setOptimisticValue] = useOptimistic(value);
  const isBusy = isLoading || isPending;
  // The busy Spinner is decorative; this control announces its busy start
  // (spec:AST-086 FR8).
  useBusyAnnouncement(isBusy, t('@astryx.spinner.loading'), triggerRef);

  const handlePopoverShow = useCallback(() => {
    onOpenChange?.(true);
  }, [onOpenChange]);

  // The popup's content element, read when it closes.
  const popupContentRef = useRef<HTMLElement | null>(null);
  const hasCallerTrigger = renderTrigger != null;
  const handlePopoverHide = useCallback(() => {
    const trigger = triggerRef.current;
    // A press that moved focus to another control keeps it there. A caller's
    // control always gets focus back. Focus moves before the callback, so a
    // consumer that moves it from the callback wins.
    if (
      hasCallerTrigger ||
      isFocusLost(popupContentRef.current, trigger?.ownerDocument)
    ) {
      trigger?.focus();
    }
    onOpenChange?.(false);
  }, [hasCallerTrigger, onOpenChange]);

  const popover = usePopover({
    dialogLabel: label,
    hasCloseButton: false,
    hasAutoFocus: true,
    surfaceTarget: 'complex-selector-popup',
    onShow: handlePopoverShow,
    onHide: handlePopoverHide,
    // The entrance runs on the surface: an anchored layer lays out again on
    // each frame its own style animates.
    xstyle: layerAnimations[placement],
  });
  popupContentRef.current = popover.contentRef.current;

  const isOpen = popover.isOpen;

  const handleTriggerClick = useCallback(() => {
    if (isDisabled) {
      return;
    }
    if (popover.isOpen) {
      popover.hide();
    } else {
      popover.show();
    }
  }, [isDisabled, popover]);

  const close = useCallback(() => {
    popover.hide();
  }, [popover]);

  const handleTriggerKeyDown = useCallback(
    (event: React.KeyboardEvent<HTMLElement>) => {
      if (event.key === 'ArrowDown' && !isOpen && !isDisabled) {
        event.preventDefault();
        popover.show();
      }
    },
    [isDisabled, isOpen, popover],
  );

  // A caller `onClick` runs first and can cancel opening with
  // `preventDefault()`, as it always could. It now lands on the trigger, so
  // the trigger composes it; a press elsewhere in the control box (padding,
  // start icon, chevron) opens the popup directly.
  const handleTriggerButtonClick = composeEventHandlers(
    onClickProp,
    handleTriggerClick,
  );
  // A caller `onKeyDown` sees every key, including the ArrowDown the trigger
  // has already used to open the popup.
  const handleTriggerButtonKeyDown = (
    event: React.KeyboardEvent<HTMLElement>,
  ) => {
    handleTriggerKeyDown(event);
    // A disabled trigger keeps its tab stop but invokes no callback
    // (`spec:AST-085` FR2).
    if (!isDisabled) {
      onKeyDownProp?.(event);
    }
  };
  // A press on a disabled control reaches no handler, the component's or an
  // ancestor's, as with a natively disabled button (`spec:AST-085` FR2).
  const swallowDisabledPress = (event: React.MouseEvent<HTMLElement>) => {
    event.preventDefault();
    event.stopPropagation();
  };
  const handleControlBoxClick = useCallback(
    (event: React.MouseEvent<HTMLDivElement>) => {
      if (isDisabled) {
        event.stopPropagation();
        return;
      }
      if (triggerRef.current?.contains(event.target as Node)) {
        return;
      }
      // Route the press through the trigger so it behaves exactly like a
      // press on the trigger itself, caller `onClick` included.
      triggerRef.current?.click();
    },
    [isDisabled],
  );

  useImperativeHandle(
    handleRef,
    () => ({
      open: () => {
        if (!isDisabled) {
          popover.show();
        }
      },
      close: () => popover.hide(),
      toggle: () => {
        if (isDisabled) {
          return;
        }
        if (popover.isOpen) {
          popover.hide();
        } else {
          popover.show();
        }
      },
      isOpen: () => popover.isOpen,
    }),
    [isDisabled, popover],
  );

  // The helper reads the selector's availability when it runs, not the
  // render it came from: content may keep a helper from an earlier render
  // (after an await, say) across a change either way. The insertion effect
  // runs before any layout effect of the content, so a commit from the
  // content's own layout effect in the render that changes it sees the new
  // availability too.
  const isDisabledRef = useRef(isDisabled);
  useInsertionEffect(() => {
    isDisabledRef.current = isDisabled;
  }, [isDisabled]);

  const commitValue = useCallback(
    (nextValue: Value) => {
      // Caller-owned popup controls may remain mounted after disablement.
      // Guard the supplied commit boundary, not just the trigger.
      if (isDisabledRef.current) {
        return;
      }
      onChange?.(nextValue);
      if (changeAction) {
        startTransition(async () => {
          setOptimisticValue(nextValue);
          await changeAction(nextValue);
        });
      }
    },
    [changeAction, onChange, setOptimisticValue, startTransition],
  );

  const triggerContent = triggerLabel ?? placeholder;

  const startIconSlot = renderIconSlot(startIcon, {
    size: 'sm',
    color: 'secondary',
  });

  const content = (
    <div id={contentId} {...stylex.props(styles.content, contentXstyle)}>
      {children(optimisticValue, commitValue, close, {
        isOpen,
        isBusy,
        triggerId,
        contentId,
      })}
    </div>
  );

  const popup = popover.render(content, {
    placement,
    alignment,
    offset: spacingVars['--spacing-1'],
    xstyle: styles.popover,
  });

  if (renderTrigger != null) {
    // Anchor-only mode: the caller renders the opener and spreads these props
    // on it. No Field, no status, no chevron — the caller owns the control;
    // the selector owns the popup, its anchor, and focus return.
    const triggerProps: ComplexSelectorRenderTriggerProps = {
      // Base props reach the caller's control, the primary semantic control
      // in this mode; the selector's own wiring below wins over them.
      ...rest,
      'aria-describedby': ariaDescribedByProp,
      ref: mergeRefs<HTMLElement>(el => {
        popover.triggerRef(el);
        triggerRef.current = el;
      }, ref),
      id: triggerId,
      // This path never forwarded caller handlers before, so the newly
      // forwarded ones compose component first and cannot cancel opening.
      // A disabled control keeps its tab stop but invokes no callback
      // (`spec:AST-085` FR2), as on the built-in trigger.
      onClick: isDisabled
        ? swallowDisabledPress
        : composeEventHandlers(handleTriggerClick, onClickProp),
      onKeyDown: isDisabled
        ? handleTriggerKeyDown
        : composeEventHandlers(handleTriggerKeyDown, onKeyDownProp),
      // The caller's control is the field, so it carries the field's role
      // and state as the built-in trigger does.
      role: 'combobox',
      // A combobox takes no name from its content, so the field's label
      // names the control, as it names the built-in trigger and the popup.
      // A name passed to the selector wins.
      'aria-label':
        rest['aria-label'] ??
        (rest['aria-labelledby'] != null ? undefined : label),
      'aria-haspopup': 'dialog',
      'aria-expanded': isOpen,
      'aria-controls': contentId,
      'aria-busy': isBusy || undefined,
      'aria-required': isEffectivelyRequired ? 'true' : undefined,
      'aria-disabled': isDisabled ? 'true' : undefined,
    };
    return (
      <>
        {renderTrigger(triggerProps)}
        {popup}
      </>
    );
  }

  const selectorContent = (
    <>
      <div
        ref={popover.triggerRef}
        {...pressable}
        onClick={handleControlBoxClick}
        {...mergeProps(
          themeProps('complex-selector', {
            variant,
            size,
            status: status?.type ?? null,
          }),
          stylex.props(
            inputWrapperStyles.base,
            styles.triggerContainer,
            styles[size],
            // The ring belongs to the wrapper (the focusable `<button>` sits
            // inside it), but it must still be a KEYBOARD ring: `:focus-within`
            // matched a mouse click on the trigger and drew the outline for
            // pointer users too. It keys off the trigger alone, so the status
            // info-tip beside it rings itself and the box does not ring too
            // (architecture:interaction-modality INV3).
            focusOutlineStyles.focusWithinCombobox,
            variant === 'secondary' && styles.triggerSecondary,
            variant === 'ghost' && styles.triggerGhost,
            variant !== 'input' && interactionOverlayStyles.backgroundImage,
            isDisabled && inputWrapperStyles.disabled,
            variant !== 'input' && isDisabled && styles.triggerGhostDisabled,
            isDisabled && styles.disabled,
            triggerLabel == null && styles.placeholder,
            controlXstyle,
          ),
          controlClassName,
          controlStyle,
        )}>
        {isRenderable(startIconSlot) && startIconSlot}
        <button
          {...rest}
          ref={triggerButtonRef}
          id={triggerId}
          type="button"
          // The trigger is the field's control: a combobox whose popup is a
          // dialog, so required and disabled state are valid on it.
          role="combobox"
          aria-haspopup="dialog"
          aria-expanded={isOpen}
          aria-controls={contentId}
          // A caller's description is kept alongside the field's own.
          aria-describedby={
            [ariaDescribedByProp, ariaDescribedBy].filter(Boolean).join(' ') ||
            undefined
          }
          // The field's label names the trigger unless the selector was
          // given a name: a caller's `aria-label` or `aria-labelledby`
          // replaces it (family:input-fields FR10), as on `renderTrigger`.
          aria-labelledby={
            rest['aria-labelledby'] ??
            (rest['aria-label'] != null ? undefined : labelId)
          }
          aria-required={isEffectivelyRequired ? 'true' : undefined}
          aria-invalid={status?.type === 'error' ? 'true' : undefined}
          aria-busy={isBusy || undefined}
          // A disabled trigger keeps its tab stop and says so through
          // aria-disabled (`spec:AST-085` FR1). Its press runs neither the
          // caller's handler nor the toggle (FR2).
          aria-disabled={isDisabled ? 'true' : undefined}
          onClick={isDisabled ? swallowDisabledPress : handleTriggerButtonClick}
          onKeyDown={handleTriggerButtonKeyDown}
          {...stylex.props(styles.trigger)}>
          <span {...stylex.props(styles.triggerText)}>{triggerContent}</span>
        </button>
        {isBusy && <Spinner size="sm" aria-hidden="true" />}
        {isRenderable(statusTip) &&
          (isTooltipStatus ? (
            // The info-tip is its own control: a press on it, or on its
            // message bubble (portaled, so outside this span in the DOM but
            // inside it in React), shows the message without opening the
            // popup.
            <span onClick={stopPropagation} {...stylex.props(styles.statusTip)}>
              {statusTip}
            </span>
          ) : (
            // The plain icon is part of the field: a press on it opens the
            // popup, as a press on the trigger does.
            <span {...stylex.props(styles.statusTip)}>{statusTip}</span>
          ))}
        {/* A status icon or info-tip takes the chevron's place, as in
            Selector. */}
        {!isRenderable(statusTip) && (
          <Icon
            icon="chevronDown"
            size="sm"
            color="secondary"
            // No wrapper: Icon's own span already provides the 16px box (`sm`)
            // and the secondary icon color the wrapper used to set, so the glyph
            // IS the trigger's icon element — one node carrying the box, the
            // color, the rotation, and the theme target.
            xstyle={[
              styles.triggerIcon,
              styles.triggerIconRotation,
              isOpen && styles.triggerIconOpen,
            ]}
            {...themeProps('complex-selector-indicator-icon', {
              state: isOpen ? 'expanded' : 'collapsed',
            })}
          />
        )}
      </div>

      {popup}
    </>
  );

  return (
    <Field
      label={label}
      isLabelHidden={isLabelHidden}
      description={description}
      inputID={triggerId}
      descriptionID={description ? descriptionId : undefined}
      labelID={labelId}
      isOptional={isOptional}
      isRequired={isRequired}
      isDisabled={isDisabled}
      status={
        status
          ? {
              type: status.type,
              message: status.message,
              messageID: status.message ? statusMessageId : undefined,
            }
          : undefined
      }
      statusVariant={effectiveStatusVariant}
      labelTooltip={labelTooltip}
      width={width}
      {...container}>
      {selectorContent}
    </Field>
  );
}

ComplexSelector.displayName = 'ComplexSelector';