@react-navigation/elements 2.0.3 → 2.1.0

package/src/Header/HeaderSearchBar.tsx

@@ -17,11 +17,11 @@ import closeIcon from '../assets/close-icon.png';
 import searchIcon from '../assets/search-icon.png';
 import { PlatformPressable } from '../PlatformPressable';
 import { Text } from '../Text';
-import type { HeaderOptions } from '../types';
+import type { HeaderSearchBarOptions, HeaderSearchBarRef } from '../types';
 import { HeaderButton } from './HeaderButton';
 import { HeaderIcon } from './HeaderIcon';
 
-type Props = HeaderOptions['headerSearchBarOptions'] & {
+type Props = Omit<HeaderSearchBarOptions, 'ref'> & {
   visible: boolean;
   onClose: () => void;
   style?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
@@ -34,17 +34,20 @@ const INPUT_TYPE_TO_MODE = {
   email: 'email',
 } as const;
 
-export function HeaderSearchBar({
-  visible,
-  inputType,
-  autoFocus = true,
-  placeholder = 'Search',
-  cancelButtonText = 'Cancel',
-  onChangeText,
-  onClose,
-  style,
-  ...rest
-}: Props) {
+function HeaderSearchBarInternal(
+  {
+    visible,
+    inputType,
+    autoFocus = true,
+    placeholder = 'Search',
+    cancelButtonText = 'Cancel',
+    onChangeText,
+    onClose,
+    style,
+    ...rest
+  }: Props,
+  ref: React.ForwardedRef<HeaderSearchBarRef>
+) {
   const navigation = useNavigation();
   const { dark, colors, fonts } = useTheme();
   const [value, setValue] = React.useState('');
@@ -98,22 +101,46 @@ export function HeaderSearchBar({
     });
   }, [clearVisibleAnim, hasText]);
 
-  const onClear = React.useCallback(() => {
+  const clearText = React.useCallback(() => {
     inputRef.current?.clear();
     inputRef.current?.focus();
     setValue('');
+  }, []);
+
+  const onClear = React.useCallback(() => {
+    clearText();
     // FIXME: figure out how to create a SyntheticEvent
     // @ts-expect-error: we don't have the native event here
     onChangeText?.({ nativeEvent: { text: '' } });
-  }, [onChangeText]);
+  }, [clearText, onChangeText]);
+
+  const cancelSearch = React.useCallback(() => {
+    onClear();
+    onClose();
+  }, [onClear, onClose]);
 
   React.useEffect(
-    () =>
-      navigation?.addListener('blur', () => {
-        onClear();
-        onClose();
-      }),
-    [navigation, onClear, onClose]
+    () => navigation?.addListener('blur', cancelSearch),
+    [cancelSearch, navigation]
+  );
+
+  React.useImperativeHandle(
+    ref,
+    () => ({
+      focus: () => {
+        inputRef.current?.focus();
+      },
+      blur: () => {
+        inputRef.current?.blur();
+      },
+      setText: (text: string) => {
+        inputRef.current?.setNativeProps({ text });
+        setValue(text);
+      },
+      clearText,
+      cancelSearch,
+    }),
+    [cancelSearch, clearText]
   );
 
   if (!visible && !rendered) {
@@ -189,13 +216,7 @@ export function HeaderSearchBar({
         </HeaderButton>
       ) : null}
       {Platform.OS === 'ios' ? (
-        <PlatformPressable
-          onPress={() => {
-            onClear();
-            onClose();
-          }}
-          style={styles.cancelButton}
-        >
+        <PlatformPressable onPress={cancelSearch} style={styles.cancelButton}>
           <Text
             style={[
               fonts.regular,
@@ -281,3 +302,5 @@ const styles = StyleSheet.create({
     },
   }),
 });
+
+export const HeaderSearchBar = React.forwardRef(HeaderSearchBarInternal);

package/src/types.tsx

@@ -11,7 +11,26 @@ export type HeaderBackButtonDisplayMode = 'default' | 'generic' | 'minimal';
 
 export type Layout = { width: number; height: number };
 
-type HeaderSearchBarOptions = {
+export type HeaderSearchBarRef = {
+  focus: () => void;
+  blur: () => void;
+  setText: (text: string) => void;
+  clearText: () => void;
+  cancelSearch: () => void;
+};
+
+export type HeaderSearchBarOptions = {
+  /**
+   * Ref to imperatively update the search bar.
+   *
+   * Supported operations:
+   * - `focus` - focuses the search bar
+   * - `blur` - removes focus from the search bar
+   * - `setText` - sets the search bar's content to given value
+   * - `clearText` - removes any text present in the search bar input field
+   * - `cancelSearch` - cancel the search and close the search bar
+   */
+  ref?: React.Ref<HeaderSearchBarRef>;
   /**
    * The auto-capitalization behavior
    */
@@ -273,8 +292,14 @@ export type HeaderBackButtonProps = Omit<HeaderButtonProps, 'children'> & {
    */
   truncatedLabel?: string;
   /**
-   * Whether the label text is visible.
-   * Defaults to `true` on iOS and `false` on Android.
+   * How the back button displays icon and title.
+   *
+   * Supported values:
+   * - "default" - Displays one of the following depending on the available space: previous screen's title, truncated title (e.g. 'Back') or no title (only icon).
+   * - "generic" – Displays one of the following depending on the available space: truncated title (e.g. 'Back') or no title (only icon).
+   * - "minimal" – Always displays only the icon without a title.
+   *
+   * Defaults to "default" on iOS, and "minimal" on other platforms.
    */
   displayMode?: HeaderBackButtonDisplayMode;
   /**