@hzblj/kara-components 0.26.2 → 0.27.1

package/src/molecules/navigation-bar/bar-search-field.tsx

@@ -0,0 +1,94 @@
+import {iconResourceName} from '@hzblj/expo-native-icons'
+import {SearchField, type SearchFieldRef} from '@hzblj/kara-native/jetpack-compose'
+import {useAppTheme} from '@hzblj/kara-theme'
+import {type ReactNode, type Ref, useMemo} from 'react'
+import {StyleSheet, View} from 'react-native'
+import type {IconName} from '../../atoms/icon'
+import {ComposeHost} from '../../hooks/compose-host'
+import type {SearchFieldVoice} from './navigation-bar.types'
+
+/** Material's search field is 56dp; a row adds 8dp above it and 12dp below, under a top app bar. */
+const FIELD_HEIGHT = 56
+
+/** A search row's height under a bar, for what is laid out below it. */
+export const BAR_SEARCH_ROW_HEIGHT = 8 + FIELD_HEIGHT + 12
+
+const styles = StyleSheet.create({
+  field: {height: FIELD_HEIGHT},
+  row: {paddingBottom: 12, paddingHorizontal: 16, paddingTop: 8},
+})
+
+export type BarSearchFieldProps = {
+  /** Focuses the field and shows the keyboard as soon as it is composed. */
+  autoFocus?: boolean
+  /** The text button beside a focused field that empties and blurs it. `Cancel` by default. */
+  cancelLabel?: string
+  clearIcon?: IconName
+  onChangeText: (text: string) => void
+  onFocusChange?: (focused: boolean, hasText: boolean) => void
+  placeholder: string
+  ref?: Ref<SearchFieldRef>
+  testID?: string
+  voice?: SearchFieldVoice
+}
+
+/**
+ * The search field kara draws on Android, in a header row or inside a bar: Material's input field in the theme's
+ * colours and body face, with the app's icons and the voice. A Compose view, so the caller brings the host. Import it
+ * only from `.android` files.
+ */
+export const BarSearchField = ({
+  autoFocus,
+  cancelLabel = 'Cancel',
+  clearIcon,
+  onChangeText,
+  onFocusChange,
+  placeholder,
+  ref,
+  testID,
+  voice,
+}: BarSearchFieldProps) => {
+  const theme = useAppTheme()
+  const face = theme.typography.body
+
+  const nativeVoice = useMemo(
+    () =>
+      voice && {
+        ...voice,
+        microphoneIconName: voice.microphoneIcon ? iconResourceName(voice.microphoneIcon) : undefined,
+        stopIconName: voice.stopIcon ? iconResourceName(voice.stopIcon) : undefined,
+      },
+    [voice]
+  )
+  const fieldClearIcon = voice?.clearIcon ?? clearIcon
+
+  return (
+    <SearchField
+      autoFocus={autoFocus}
+      cancelLabel={cancelLabel}
+      clearIconName={fieldClearIcon ? iconResourceName(fieldClearIcon) : undefined}
+      clearLabel={voice?.clearLabel ?? 'Clear'}
+      containerColor={theme.color('fill.quaternary')}
+      fontFamily={face.fontFamily}
+      fontSize={face.fontSize}
+      iconColor={theme.color('content.secondary')}
+      onFocusChange={onFocusChange}
+      onQueryChange={onChangeText}
+      placeholder={placeholder}
+      placeholderColor={theme.color('content.tertiary')}
+      ref={ref}
+      testID={testID}
+      textColor={theme.color('content.primary')}
+      voice={nativeVoice}
+    />
+  )
+}
+
+/** A search field's own row under a bar, in its own host. */
+export const BarSearchRow = ({children}: {children: ReactNode}) => (
+  <View style={styles.row}>
+    <ComposeHost ignoreSafeAreaKeyboardInsets style={styles.field}>
+      {children}
+    </ComposeHost>
+  </View>
+)

package/src/molecules/navigation-bar/navigation-bar.android.tsx

@@ -1,24 +1,36 @@
 import {iconResourceName} from '@hzblj/expo-native-icons'
-import {TopAppBar, type TopAppBarItem} from '@hzblj/kara-native/jetpack-compose'
+import {GLYPHS} from '@hzblj/kara-native'
+import {type SearchFieldRef, TopAppBar, type TopAppBarItem} from '@hzblj/kara-native/jetpack-compose'
 import {useAppTheme} from '@hzblj/kara-theme'
-import {useMemo} from 'react'
+import {useCallback, useImperativeHandle, useMemo, useRef, useState} from 'react'
+
 import {Island} from '../../atoms/island'
+import {BarSearchField, BarSearchRow} from './bar-search-field'
 import type {NavigationBarComponent, NavigationBarItem, NavigationBarProps} from './navigation-bar.types'
 
 /** Material's small top app bar. */
 const BAR_HEIGHT = 64
 
-const DEFAULT_LABELS = {back: 'Back', close: 'Close'} as const
+const DEFAULT_LABELS = {back: 'Back', close: 'Close', search: 'Search'} as const
+
+const NO_ITEMS: NavigationBarItem[] = []
+
+const ignoreDetachedView = () => undefined
 
 const toNativeItem = ({onPress, testID, ...item}: NavigationBarItem): TopAppBarItem =>
   item.type === 'icon'
     ? {iconName: iconResourceName(item.icon), label: item.label, onPress, testID, type: 'icon'}
     : {label: item.label ?? DEFAULT_LABELS[item.type], onPress, testID, type: item.type}
 
-/** Material's top app bar in its own host. `search` is iOS-only for now, and `separated` has no Material counterpart. */
+/**
+ * Material's top app bar in its own host. `search` is a field in a row under the bar (`stacked`), or a search item
+ * that grows into the field over the bar (`integratedButton`) and collapses back once the field is cancelled, cleared
+ * or left empty. `separated` has no Material counterpart.
+ */
 export const NavigationBar: NavigationBarComponent = ({
   inverted = false,
   leadingItems,
+  search,
   testID,
   title,
   titleAlignment = 'center',
@@ -29,22 +41,110 @@ export const NavigationBar: NavigationBarComponent = ({
   const font = theme.typography.headline
   const color = theme.color(inverted ? 'content.on.accent' : 'content.primary')
 
-  const nativeLeadingItems = useMemo(() => leadingItems?.map(toNativeItem), [leadingItems])
-  const nativeTrailingItems = useMemo(() => trailingItems?.map(toNativeItem), [trailingItems])
+  const fieldRef = useRef<SearchFieldRef>(null)
+  const echo = useRef<string | null>(null)
+  const [searchActive, setSearchActive] = useState(false)
+
+  const integrated = search?.placement === 'integratedButton'
+  const buttonPlacement = search?.buttonPlacement ?? 'trailing'
+  const onChangeText = search?.onChangeText
+  const onFocusChange = search?.onFocusChange
+
+  const searchItem = useMemo<TopAppBarItem | undefined>(
+    () =>
+      integrated
+        ? {
+            iconName: search?.buttonIcon ? iconResourceName(search.buttonIcon) : GLYPHS.search.android,
+            label: search?.buttonLabel ?? DEFAULT_LABELS.search,
+            onPress: () => setSearchActive(true),
+            type: 'icon',
+          }
+        : undefined,
+    [integrated, search?.buttonIcon, search?.buttonLabel]
+  )
+
+  const nativeLeadingItems = useMemo(() => {
+    const items = (leadingItems ?? NO_ITEMS).map(toNativeItem)
+    return searchItem && buttonPlacement === 'leading' ? [...items, searchItem] : items
+  }, [buttonPlacement, leadingItems, searchItem])
+
+  const nativeTrailingItems = useMemo(() => {
+    const items = (trailingItems ?? NO_ITEMS).map(toNativeItem)
+    return searchItem && buttonPlacement === 'trailing' ? [searchItem, ...items] : items
+  }, [buttonPlacement, searchItem, trailingItems])
+
+  const handleChangeText = useCallback(
+    (text: string) => {
+      if (echo.current === text) {
+        echo.current = null
+        return
+      }
+
+      onChangeText?.(text)
+    },
+    [onChangeText]
+  )
+
+  const handleFocusChange = useCallback(
+    (focused: boolean, hasText: boolean) => {
+      onFocusChange?.(focused)
+
+      if (!focused && !hasText) {
+        setSearchActive(false)
+      }
+    },
+    [onFocusChange]
+  )
+
+  useImperativeHandle(
+    search?.ref,
+    () => ({
+      clear: () => {
+        fieldRef.current?.clearQuery().catch(ignoreDetachedView)
+        fieldRef.current?.blurField().catch(ignoreDetachedView)
+        setSearchActive(false)
+      },
+      setText: (text: string) => {
+        echo.current = text
+        fieldRef.current?.setQuery(text).catch(ignoreDetachedView)
+      },
+    }),
+    []
+  )
+
+  const field = search ? (
+    <BarSearchField
+      autoFocus={integrated}
+      cancelLabel={search.cancelLabel}
+      clearIcon={search.clearIcon}
+      onChangeText={handleChangeText}
+      onFocusChange={handleFocusChange}
+      placeholder={search.placeholder}
+      ref={fieldRef}
+      testID={search.testID}
+      voice={search.voice}
+    />
+  ) : null
 
   return (
-    <Island h={BAR_HEIGHT} matchContents={false} testID={testID} w="100%">
-      <TopAppBar
-        fontFamily={font.fontFamily}
-        fontSize={font.fontSize}
-        itemColor={color}
-        leadingItems={nativeLeadingItems}
-        title={title}
-        titleAlignment={titleAlignment}
-        titleColor={color}
-        titleVisible={titleVisible}
-        trailingItems={nativeTrailingItems}
-      />
-    </Island>
+    <>
+      <Island h={BAR_HEIGHT} matchContents={false} testID={testID} w="100%">
+        <TopAppBar
+          fontFamily={font.fontFamily}
+          fontSize={font.fontSize}
+          itemColor={color}
+          leadingItems={nativeLeadingItems}
+          searchActive={integrated && searchActive}
+          title={title}
+          titleAlignment={titleAlignment}
+          titleColor={color}
+          titleVisible={titleVisible}
+          trailingItems={nativeTrailingItems}
+        >
+          {integrated ? <TopAppBar.Search>{field}</TopAppBar.Search> : null}
+        </TopAppBar>
+      </Island>
+      {search && !integrated ? <BarSearchRow>{field}</BarSearchRow> : null}
+    </>
   )
 }

package/src/molecules/navigation-bar/navigation-bar.types.ts

@@ -72,20 +72,22 @@ export type NavigationBarSearchRef = {
 }
 
 /**
- * Where the search field goes on iOS, as a native-stack header places its search: `stacked` in a row of its own under
- * the title, `integratedButton` as a search item beside the trailing items that turns the bar into the field.
+ * Where the search field goes, as a native-stack header places its search: `stacked` in a row of its own under the
+ * title, `integratedButton` as a search item that turns the bar into the field.
  */
 export type NavigationBarSearchPlacement = 'integratedButton' | 'stacked'
 
 /**
  * Where `integratedButton` puts its search button: beside the trailing items, or after the leading ones. On iOS 26 the
- * button grows into the field and the cancel splits off its end, the way the system's own search does.
+ * button grows into the field and the cancel splits off its end, the way the system's own search does; on Android the
+ * field grows over the bar from its trailing edge.
  */
 export type NavigationBarSearchButtonPlacement = 'leading' | 'trailing'
 
 /**
- * A search field in the bar. iOS only for now; Android keeps the title. A focused field gets a cancel item that
- * empties it and ends the search, a bar item like the others.
+ * A search field in the bar. A focused field gets a cancel that empties it and ends the search: a bar item on iOS,
+ * Material's text button beside the field on Android. An `integratedButton` search closes again once the field is
+ * cancelled, cleared or left empty.
  */
 export type NavigationBarSearch = {
   /** `integratedButton`: the search item's icon, one of the app's icons; the system magnifying glass unset. */
@@ -130,7 +132,7 @@ export type NavigationBarProps = {
   inverted?: boolean
   /** In screen order, from the leading edge. */
   leadingItems?: NavigationBarItem[]
-  /** A search field (iOS): under the title, or behind a search item beside the trailing items. */
+  /** A search field: under the title, or behind a search item that turns the bar into the field. */
   search?: NavigationBarSearch
   /** Test identifier, forwarded to the native bar. iOS only; Android ignores it. */
   testID?: string

package/src/molecules/rn-list-item/rn-list-item.tsx

@@ -22,8 +22,9 @@ export const RnListItem: RnListItemComponent = ({
   // One element for a screen reader, as `ListItem` is: a button when it can be pressed.
   const a11y = accessibilityProps({accessible: true, ...accessibility}, onPress ? 'button' : undefined)
   const pressedColor = theme.color('fill.tertiary')
+  const rippleColor = theme.color('fill.ripple')
 
-  const ripple = useMemo(() => ({color: pressedColor}), [pressedColor])
+  const ripple = useMemo(() => ({color: rippleColor}), [rippleColor])
   const highlight = useMemo(
     () =>
       Platform.OS === 'ios'

package/src/molecules/rn-tooltip/rn-tooltip.android.tsx

@@ -1,8 +1,9 @@
-import {Text as ComposeText, Host, RNHostView, Row, TextButton} from '@expo/ui/jetpack-compose'
+import {Text as ComposeText, RNHostView, Row, TextButton} from '@expo/ui/jetpack-compose'
 
 import {TooltipBox} from '@hzblj/kara-native/jetpack-compose'
 import {useAppTheme} from '@hzblj/kara-theme'
 import {Button} from '../../atoms/button'
+import {ComposeHost} from '../../hooks/compose-host'
 import {HostBoundary} from '../../hooks/host-context'
 import type {RnTooltipAction, RnTooltipComponent, RnTooltipProps} from './rn-tooltip.types'
 
@@ -53,7 +54,7 @@ export const RnTooltip: RnTooltipComponent = ({
   const theme = useAppTheme()
 
   return (
-    <Host colorScheme={theme.dark ? 'dark' : 'light'} matchContents seedColor={theme.materialSeed}>
+    <ComposeHost matchContents>
       <HostBoundary>
         <TooltipBox
           actionsAlignment={actionsAlignment}
@@ -90,6 +91,6 @@ export const RnTooltip: RnTooltipComponent = ({
           <RNHostView matchContents>{children}</RNHostView>
         </TooltipBox>
       </HostBoundary>
-    </Host>
+    </ComposeHost>
   )
 }

package/src/organisms/context-menu/context-menu.android.tsx

@@ -1,10 +1,11 @@
-import {Text as ComposeText, DropdownMenu, DropdownMenuItem, Host} from '@expo/ui/jetpack-compose'
+import {Text as ComposeText, DropdownMenu, DropdownMenuItem} from '@expo/ui/jetpack-compose'
 import {haptics} from '@hzblj/expo-rich-haptics'
 import {useSx} from '@hzblj/kara-sx'
 import {useAppTheme} from '@hzblj/kara-theme'
 import {useCallback, useMemo, useRef, useState} from 'react'
 import {type GestureResponderEvent, Pressable, StyleSheet, View} from 'react-native'
 import {Icon} from '../../atoms/icon'
+import {ComposeHost} from '../../hooks/compose-host'
 import {HostBoundary} from '../../hooks/host-context'
 import {splitForRipple} from '../../utils/ripple-clip'
 import type {MenuAction} from '../menu'
@@ -73,7 +74,7 @@ const ContextMenuRoot = ({actions, children, testID, ...props}: ContextMenuProps
 
   // The shape clips on an outer view, so the ripple and the highlight follow the trigger's rounded corners.
   const {inner, outer} = useMemo(() => splitForRipple(resolved), [resolved])
-  const ripple = useMemo(() => ({color: theme.color('fill.tertiary')}), [theme])
+  const ripple = useMemo(() => ({color: theme.color('fill.ripple')}), [theme])
   const highlight = useMemo(() => ({backgroundColor: theme.color('fill.tertiary')}), [theme])
 
   const open = useCallback((event: GestureResponderEvent) => {
@@ -96,12 +97,7 @@ const ContextMenuRoot = ({actions, children, testID, ...props}: ContextMenuProps
         {expanded ? <View pointerEvents="none" style={[StyleSheet.absoluteFill, highlight]} /> : null}
         {children}
         {anchor ? (
-          <Host
-            colorScheme={theme.dark ? 'dark' : 'light'}
-            pointerEvents="none"
-            seedColor={theme.materialSeed}
-            style={[styles.anchor, {left: anchor.x, top: anchor.y}]}
-          >
+          <ComposeHost pointerEvents="none" style={[styles.anchor, {left: anchor.x, top: anchor.y}]}>
             <HostBoundary>
               <DropdownMenu color={theme.color('surface.primary')} expanded={expanded} onDismissRequest={dismiss}>
                 <DropdownMenu.Items>
@@ -111,7 +107,7 @@ const ContextMenuRoot = ({actions, children, testID, ...props}: ContextMenuProps
                 </DropdownMenu.Items>
               </DropdownMenu>
             </HostBoundary>
-          </Host>
+          </ComposeHost>
         ) : null}
       </Pressable>
     </View>

package/src/organisms/header/header-options.android.tsx

@@ -1,12 +1,10 @@
-import {Host} from '@expo/ui/jetpack-compose'
-import {useAppTheme} from '@hzblj/kara-theme'
 import type {ReactNode} from 'react'
 import {StyleSheet, View} from 'react-native'
-
 import {ActivityIndicator} from '../../atoms/activity-indicator'
 import {Button} from '../../atoms/button'
 import {GlyphButton} from '../../atoms/glyph'
 import {IconButton} from '../../atoms/icon-button'
+import {ComposeHost} from '../../hooks/compose-host'
 import {HostBoundary} from '../../hooks/host-context'
 import {Menu, type MenuAction} from '../menu'
 import type {
@@ -30,12 +28,10 @@ const styles = StyleSheet.create({
 
 /** A host sized to its button both ways: the toolbar gives custom content no width to fill. */
 const ActionHost = ({children}: {children: ReactNode}) => {
-  const theme = useAppTheme()
-
   return (
-    <Host colorScheme={theme.dark ? 'dark' : 'light'} matchContents seedColor={theme.materialSeed}>
+    <ComposeHost matchContents>
       <HostBoundary>{children}</HostBoundary>
-    </Host>
+    </ComposeHost>
   )
 }
 

package/src/organisms/header/header-search-accessory.android.tsx

@@ -1,4 +1,38 @@
-import type {HeaderSearchAccessoryComponent} from './header-search-accessory.types'
+import {iconResourceName} from '@hzblj/expo-native-icons'
+import {NavigationItemSearch} from '@hzblj/kara-native/jetpack-compose'
+import {useAppTheme} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
 
-/** Android's field is a Compose view of kara's own, which takes its glyphs and voice directly (`searchInput`). */
-export const HeaderSearchAccessory: HeaderSearchAccessoryComponent = () => null
+import {headerColor} from './header-color'
+import type {HeaderSearchAccessoryComponent, HeaderSearchAccessoryProps} from './header-search-accessory.types'
+
+/**
+ * The toolbar search's glyphs and voice on Android (`integratedButton`): react-native-screens' `SearchView` belongs to
+ * the toolbar, so a zero-size native view in the screen's tree puts the microphone into its field and gives its X the
+ * bar's ripple and the app's clear glyph. The toolbar has no cancel glyph; back closes the search.
+ */
+export const HeaderSearchAccessory: HeaderSearchAccessoryComponent = ({
+  clearIcon,
+  voice,
+}: HeaderSearchAccessoryProps) => {
+  const theme = useAppTheme()
+  const nativeVoice = useMemo(
+    () =>
+      voice && {
+        ...voice,
+        microphoneIconName: voice.microphoneIcon ? iconResourceName(voice.microphoneIcon) : undefined,
+        stopIconName: voice.stopIcon ? iconResourceName(voice.stopIcon) : undefined,
+      },
+    [voice]
+  )
+  const fieldClearIcon = voice?.clearIcon ?? clearIcon
+
+  return (
+    <NavigationItemSearch
+      clearIconName={fieldClearIcon ? iconResourceName(fieldClearIcon) : undefined}
+      iconColor={voice?.color ?? headerColor(theme, 'content.primary')}
+      rippleColor={theme.color('fill.ripple')}
+      voice={nativeVoice}
+    />
+  )
+}

package/src/organisms/header/header-search-input.android.tsx

@@ -1,22 +1,11 @@
-import {Host} from '@expo/ui/jetpack-compose'
-import {iconResourceName} from '@hzblj/expo-native-icons'
-import {SearchField, type SearchFieldRef} from '@hzblj/kara-native/jetpack-compose'
-import {useAppTheme} from '@hzblj/kara-theme'
-import {useImperativeHandle, useMemo, useRef} from 'react'
-import {StyleSheet, View} from 'react-native'
+import type {SearchFieldRef} from '@hzblj/kara-native/jetpack-compose'
+import {useImperativeHandle, useRef} from 'react'
 
+import {BAR_SEARCH_ROW_HEIGHT, BarSearchField, BarSearchRow} from '../../molecules/navigation-bar/bar-search-field'
 import type {HeaderSearchInputComponent, HeaderSearchInputProps} from './header-search-input.types'
 
-/** Material's search field is 56dp; the row adds 8dp above it and 12dp below, under the top app bar. */
-const FIELD_HEIGHT = 56
-
 /** The row's height under the bar, for what is laid out below it (the scrim starts there). */
-export const HEADER_SEARCH_ROW_HEIGHT = 8 + FIELD_HEIGHT + 12
-
-const styles = StyleSheet.create({
-  field: {height: FIELD_HEIGHT},
-  row: {paddingBottom: 12, paddingHorizontal: 16, paddingTop: 8},
-})
+export const HEADER_SEARCH_ROW_HEIGHT = BAR_SEARCH_ROW_HEIGHT
 
 const ignoreDetachedView = () => undefined
 
@@ -28,9 +17,7 @@ export const HeaderSearchInput: HeaderSearchInputComponent = ({
   ref,
   voice,
 }: HeaderSearchInputProps) => {
-  const theme = useAppTheme()
   const fieldRef = useRef<SearchFieldRef>(null)
-  const face = theme.typography.body
 
   useImperativeHandle(
     ref,
@@ -48,42 +35,16 @@ export const HeaderSearchInput: HeaderSearchInputComponent = ({
     []
   )
 
-  const nativeVoice = useMemo(
-    () =>
-      voice && {
-        ...voice,
-        microphoneIconName: voice.microphoneIcon ? iconResourceName(voice.microphoneIcon) : undefined,
-        stopIconName: voice.stopIcon ? iconResourceName(voice.stopIcon) : undefined,
-      },
-    [voice]
-  )
-  const fieldClearIcon = voice?.clearIcon ?? clearIcon
-
   return (
-    <View style={styles.row}>
-      <Host
-        colorScheme={theme.dark ? 'dark' : 'light'}
-        ignoreSafeAreaKeyboardInsets
-        seedColor={theme.materialSeed}
-        style={styles.field}
-      >
-        <SearchField
-          cancelLabel="Cancel"
-          clearIconName={fieldClearIcon ? iconResourceName(fieldClearIcon) : undefined}
-          clearLabel={voice?.clearLabel ?? 'Clear'}
-          containerColor={theme.color('fill.quaternary')}
-          fontFamily={face.fontFamily}
-          fontSize={face.fontSize}
-          iconColor={theme.color('content.secondary')}
-          onFocusChange={onFocusChange}
-          onQueryChange={onChangeText}
-          placeholder={placeholder}
-          placeholderColor={theme.color('content.tertiary')}
-          ref={fieldRef}
-          textColor={theme.color('content.primary')}
-          voice={nativeVoice}
-        />
-      </Host>
-    </View>
+    <BarSearchRow>
+      <BarSearchField
+        clearIcon={clearIcon}
+        onChangeText={onChangeText}
+        onFocusChange={onFocusChange}
+        placeholder={placeholder}
+        ref={fieldRef}
+        voice={voice}
+      />
+    </BarSearchRow>
   )
 }

package/src/organisms/header/header.types.ts

@@ -278,23 +278,33 @@ export type HeaderOptionsResult = HeaderContent & {
 export type HeaderSearchBarOptions = {
   allowToolbarIntegration?: boolean
   autoCapitalize?: 'characters' | 'none' | 'sentences' | 'words'
+  /** Android: the toolbar search's magnifier and X. */
+  headerIconColor?: string
   hideNavigationBar?: boolean
   hideWhenScrolling?: boolean
+  /** Android: the placeholder's colour. */
+  hintTextColor?: string
   obscureBackground?: boolean
   onBlur?: () => void
   onCancelButtonPress?: () => void
   onChangeText?: (event: {nativeEvent: {text: string}}) => void
+  /** Android: the toolbar search closed (back, or the X on an empty field). */
+  onClose?: () => void
   onFocus?: () => void
+  /** Android: the toolbar search opened. */
+  onOpen?: () => void
   placeholder?: string
   placement?: 'automatic' | 'inline' | 'integrated' | 'integratedButton' | 'integratedCentered' | 'stacked'
   ref?: RefObject<SearchBarCommands | null>
+  /** Android: the typed text. */
+  textColor?: string
   tintColor?: string
 }
 
 /**
- * Where the search goes on iOS: `stacked` in a row under the title (title and items kept); `integratedButton` as a
- * search button in the bar's trailing corner that opens the field in the bar, the title and items hidden meanwhile.
- * The integrated field's close is the system's: iOS gives it no other glyph.
+ * Where the search goes: `stacked` in a row under the title (title and items kept); `integratedButton` as a search
+ * button in the bar's trailing corner that opens the field in the bar, the title and items hidden meanwhile. On iOS the
+ * integrated field's close is the system's, which takes no other glyph; on Android back closes it.
  */
 export type HeaderSearchPlacement = 'integratedButton' | 'stacked'
 
@@ -307,16 +317,16 @@ export type HeaderSearchParams = {
   enabled?: boolean
   /** Shown while the field is empty. `Search` by default. */
   placeholder?: string
-  /** iOS: `stacked` by default. Android always puts its field in a row under the bar. */
+  /** `stacked` by default. */
   placement?: HeaderSearchPlacement
   /** A microphone in the field: see `SearchFieldVoice`. Write what it hears with `setText`. */
   voice?: SearchFieldVoice
 }
 
 /**
- * A header's search: what to give `useHeader` (`searchBar`, iOS), the row Android puts under its bar (`searchInput`),
- * the scrim that washes the content out while the field is focused and empty (render it last, over the content), and
- * the query to filter by.
+ * A header's search: what to give `useHeader` (`searchBar`), the row Android puts under its bar for `stacked`
+ * (`searchInput`), the scrim that washes the content out while the field is focused and empty (render it last, over
+ * the content), and the query to filter by.
  */
 export type HeaderSearch = {
   /** Empties the field and ends the search. */
@@ -324,13 +334,13 @@ export type HeaderSearch = {
   /** The field's text. */
   query: string
   /**
-   * Over the content while the field is focused and empty; a tap on it ends the search. On iOS it also carries the
+   * Over the content while the field is focused and empty; a tap on it ends the search. It also carries the header
    * field's glyphs and voice, which have to sit in the screen's tree. Render it last.
    */
   scrim: ReactElement | null
-  /** Android: the Material search field, a row to put right under the bar. `null` on iOS. */
+  /** Android, `stacked`: the Material search field, a row to put right under the bar. `null` otherwise. */
   searchInput: ReactElement | null
-  /** iOS: `search` for `useHeader`. `undefined` on Android. */
+  /** `search` for `useHeader`: always on iOS, for `integratedButton` on Android. `undefined` otherwise. */
   searchBar: HeaderSearchBarOptions | undefined
   /** Puts text into the field and the query, the way dictation fills it in. */
   setText: (text: string) => void