@hzblj/kara-components 0.26.2 → 0.27.0

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,114 @@ 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 query = useRef('')
+  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) => {
+      query.current = text
+
+      if (echo.current === text) {
+        echo.current = null
+        return
+      }
+
+      onChangeText?.(text)
+    },
+    [onChangeText]
+  )
+
+  const handleFocusChange = useCallback(
+    (focused: boolean) => {
+      onFocusChange?.(focused)
+
+      if (!focused && query.current === '') {
+        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
+        query.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

package/src/organisms/header/use-header-search.tsx

@@ -19,9 +19,11 @@ const PLACEMENT_OPTIONS: Record<HeaderSearchPlacement, Partial<HeaderSearchBarOp
 /**
  * A search field for a screen's header. iOS: UIKit's search bar stacked under the title, with the title and items kept
  * and nothing dimmed by the system, so a list can filter live, or behind a search button in the bar's corner
- * (`placement`); pass `searchBar` to `useHeader` as `search`. Android: Material's search field with its cancel button,
- * as a row for the screen to put right under the top app bar (`searchInput`). Both report the `query`; `scrim` washes
- * the content out while the field is focused and empty and, on iOS, carries the field's glyphs and voice.
+ * (`placement`); pass `searchBar` to `useHeader` as `search`. Android: `stacked` is Material's search field with its
+ * cancel button, as a row for the screen to put right under the top app bar (`searchInput`); `integratedButton` is the
+ * toolbar's own search, a magnifier in the bar's corner that expands over the title (`searchBar`, as on iOS). Both
+ * report the `query`; `scrim` washes the content out while the field is focused and empty and carries the header
+ * field's glyphs and voice.
  *
  * With `voice` the field has a microphone; the app runs the dictation and writes what it hears with `setText`. Typing
  * over it, or ending the search, calls `voice.onCancel`.
@@ -41,6 +43,7 @@ export const useHeaderSearch = ({
   const inputRef = useRef<HeaderSearchInputRef>(null)
   const lastSetText = useRef<string | null>(null)
   const voiceRef = useRef(voice)
+  const headerField = Platform.OS === 'ios' || placement === 'integratedButton'
 
   voiceRef.current = voice
 
@@ -68,28 +71,33 @@ export const useHeaderSearch = ({
   }, [cancelVoice])
 
   const searchBar = useMemo((): HeaderSearchBarOptions | undefined => {
-    if (!enabled || Platform.OS !== 'ios') {
+    if (!enabled || !headerField) {
       return undefined
     }
 
     return {
       ...PLACEMENT_OPTIONS[placement],
       autoCapitalize: 'none',
+      headerIconColor: headerColor(theme, 'content.primary'),
       hideWhenScrolling: false,
+      hintTextColor: headerColor(theme, 'content.tertiary'),
       obscureBackground: false,
       onBlur: () => setFocused(false),
       onCancelButtonPress: reset,
       onChangeText: event => changeQuery(event.nativeEvent.text),
+      onClose: reset,
       onFocus: () => setFocused(true),
+      onOpen: () => setFocused(true),
       placeholder,
       placement,
       ref: searchBarRef,
+      textColor: Platform.OS === 'android' ? headerColor(theme, 'content.primary') : undefined,
       tintColor: headerColor(theme, 'content.primary'),
     }
-  }, [changeQuery, enabled, placeholder, placement, reset, theme])
+  }, [changeQuery, enabled, headerField, placeholder, placement, reset, theme])
 
   const searchInput = useMemo(() => {
-    if (!enabled || Platform.OS !== 'android') {
+    if (!enabled || headerField) {
       return null
     }
 
@@ -103,7 +111,7 @@ export const useHeaderSearch = ({
         voice={voice}
       />
     )
-  }, [changeQuery, clearIcon, enabled, placeholder, voice])
+  }, [changeQuery, clearIcon, enabled, headerField, placeholder, voice])
 
   const clear = useCallback(() => {
     reset()
@@ -128,11 +136,11 @@ export const useHeaderSearch = ({
 
     return (
       <>
-        {dimmed ? <HeaderSearchScrim onPress={clear} topOffset={HEADER_SEARCH_ROW_HEIGHT} /> : null}
-        <HeaderSearchAccessory cancelIcon={cancelIcon} clearIcon={clearIcon} voice={voice} />
+        {dimmed ? <HeaderSearchScrim onPress={clear} topOffset={headerField ? 0 : HEADER_SEARCH_ROW_HEIGHT} /> : null}
+        {headerField ? <HeaderSearchAccessory cancelIcon={cancelIcon} clearIcon={clearIcon} voice={voice} /> : null}
       </>
     )
-  }, [cancelIcon, clear, clearIcon, dimmed, enabled, voice])
+  }, [cancelIcon, clear, clearIcon, dimmed, enabled, headerField, voice])
 
   return {clear, query, scrim, searchBar, searchInput, setText}
 }

package/src/organisms/sheet/sheet.tsx

@@ -1,5 +1,5 @@
-import {useAppTheme} from '@hzblj/kara-theme'
-import {type DetentChangeEvent, TrueSheet} from '@lodev09/react-native-true-sheet'
+import {useAppTheme, withOpacity} from '@hzblj/kara-theme'
+import {type DetentChangeEvent, type GrabberOptions, TrueSheet} from '@lodev09/react-native-true-sheet'
 import {useCallback, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef} from 'react'
 import {Platform, StyleSheet, View} from 'react-native'
 import type {SheetComponent, SheetDetent, SheetProps} from './sheet.types'
@@ -39,6 +39,22 @@ const SheetRoot = ({
   const theme = useAppTheme()
   const {content, header: headerProps} = useMemo(() => splitSheetChildren(children), [children])
   const sheetHeader = useSheetHeader({header: headerProps, scrollable})
+  const inverted = headerProps?.inverted ?? false
+  /**
+   * Material's drag handle, `onSurfaceVariant` at 40 %, in the app's theme. TrueSheet's own Android grabber picks black
+   * or white by the system's night mode, so an app themed apart from the device drew it in the sheet's own colour.
+   */
+  const grabberOptions = useMemo<GrabberOptions | undefined>(() => {
+    if (Platform.OS !== 'android') {
+      return undefined
+    }
+
+    const color = inverted
+      ? theme.color('content.on.accent:o40')
+      : withOpacity(String(theme.color('content.secondary')), 'o40')
+
+    return {adaptive: false, color}
+  }, [inverted, theme])
   const sheetRef = useRef<TrueSheet>(null)
   const presented = useRef(false)
   /** A dismissal we asked for: `onDismiss` reports the user's, never ours. */
@@ -114,6 +130,7 @@ const SheetRoot = ({
         draggable={draggable}
         footer={footer}
         grabber={grabber}
+        grabberOptions={grabberOptions}
         header={sheetHeader.header}
         headerStyle={sheetHeader.headerStyle}
         onDetentChange={handleDetentChange}