@hzblj/kara-components 0.20.1 → 0.22.0

package/src/organisms/header/hero-header-background.types.ts

@@ -0,0 +1,11 @@
+import type {ReactNode} from 'react'
+import type {SharedValue} from 'react-native-reanimated'
+
+export type HeroHeaderBackgroundProps = {
+  /** The bar's height, status bar included. */
+  height: number
+  /** How far the header has faded in: 0 over the hero, 1 revealed. */
+  progress: SharedValue<number>
+}
+
+export type HeroHeaderBackgroundComponent = (props: HeroHeaderBackgroundProps) => ReactNode

package/src/organisms/header/index.ts

@@ -0,0 +1,12 @@
+export * from './header.types'
+export * from './header-inset'
+export * from './header-large-title-fade'
+export {useIsTitleRevealed} from './header-title'
+export * from './sheet-grabber'
+export type {SheetGrabberProps} from './sheet-grabber.types'
+export * from './use-header'
+export * from './use-header-bar-inset'
+export * from './use-header-scroll-to-top'
+export * from './use-header-search'
+export * from './use-hero-header'
+export * from './use-stack-screen-options'

package/src/organisms/header/native-subtitle.android.tsx

@@ -0,0 +1,5 @@
+import type {NativeSubtitleComponent} from './native-subtitle.types'
+
+export const hasNativeSubtitle = false
+
+export const NativeSubtitle: NativeSubtitleComponent = () => null

package/src/organisms/header/native-subtitle.ios.tsx

@@ -0,0 +1,22 @@
+import {isScrollEdgeEffectAvailable} from '@hzblj/kara-native'
+import {NavigationItemSubtitle} from '@hzblj/kara-native/swift-ui'
+import {useAppTheme} from '@hzblj/kara-theme'
+
+import type {NativeSubtitleComponent, NativeSubtitleProps} from './native-subtitle.types'
+
+/** iOS 26 puts a title and its subtitle on the leading side itself (`UINavigationItem.style = .browser`). */
+export const hasNativeSubtitle = isScrollEdgeEffectAvailable()
+
+export const NativeSubtitle: NativeSubtitleComponent = ({subtitle, subtitleHidden}: NativeSubtitleProps) => {
+  const theme = useAppTheme()
+
+  return (
+    <NavigationItemSubtitle
+      color={theme.color('content.secondary')}
+      fontFamily={theme.typography.label.fontFamily}
+      fontSize={theme.typography.label.fontSize}
+      subtitle={subtitle}
+      subtitleHidden={subtitleHidden}
+    />
+  )
+}

package/src/organisms/header/native-subtitle.types.ts

@@ -0,0 +1,8 @@
+import type {ReactNode} from 'react'
+
+export type NativeSubtitleProps = {
+  subtitle: string
+  subtitleHidden: boolean
+}
+
+export type NativeSubtitleComponent = (props: NativeSubtitleProps) => ReactNode

package/src/organisms/header/sheet-grabber.android.tsx

@@ -0,0 +1,4 @@
+import type {SheetGrabberComponent} from './sheet-grabber.types'
+
+/** Android's modal is a full screen with no grabber. */
+export const SheetGrabber: SheetGrabberComponent = () => null

package/src/organisms/header/sheet-grabber.ios.tsx

@@ -0,0 +1,12 @@
+import {SheetGrabber as NativeSheetGrabber} from '@hzblj/kara-native/swift-ui'
+
+import type {SheetGrabberComponent, SheetGrabberProps} from './sheet-grabber.types'
+
+/**
+ * The system grabber of a native-stack screen presented as a sheet (`presentation: 'modal'`), which react-native-screens
+ * gives only `formSheet`. Render it anywhere in the presented content, a nested stack's screens included; it takes no
+ * room. Android draws no grabber on a full-screen modal, and this renders nothing there.
+ */
+export const SheetGrabber: SheetGrabberComponent = ({visible = true}: SheetGrabberProps) => (
+  <NativeSheetGrabber grabberVisible={visible} />
+)

package/src/organisms/header/sheet-grabber.types.ts

@@ -0,0 +1,8 @@
+import type {ReactNode} from 'react'
+
+export type SheetGrabberProps = {
+  /** Shows the grabber. `true` by default. */
+  visible?: boolean
+}
+
+export type SheetGrabberComponent = (props: SheetGrabberProps) => ReactNode

package/src/organisms/header/use-header-bar-inset.android.ts

@@ -0,0 +1 @@
+export const useHeaderBarInset = () => 0

package/src/organisms/header/use-header-bar-inset.ios.ts

@@ -0,0 +1,7 @@
+import {isScrollEdgeEffectAvailable} from '@hzblj/kara-native'
+import {useSafeAreaInsets} from 'react-native-safe-area-context'
+
+/** iOS 26's navigation bar is 54pt, the 44pt row of items plus room for its glass; before it the bar was the row. */
+const BAR_HEIGHT = isScrollEdgeEffectAvailable() ? 54 : 44
+
+export const useHeaderBarInset = () => useSafeAreaInsets().top + BAR_HEIGHT

package/src/organisms/header/use-header-bar-inset.types.ts

@@ -0,0 +1,6 @@
+/**
+ * How far a transparent header reaches into the screen: the status bar plus the bar's own height on iOS, 0 on Android,
+ * where the top app bar sits above the content. Known on the first render, unlike a measured header height, so content
+ * laid out by it never jumps once the bar reports its size.
+ */
+export type UseHeaderBarInset = () => number

package/src/organisms/header/use-header-scroll-to-top.ts

@@ -0,0 +1,48 @@
+import {type RefObject, useMemo} from 'react'
+import {Platform} from 'react-native'
+
+import type {HeaderScrollable, HeaderScrollToTopOptions, HeaderScrollToTopRef} from './header.types'
+import {useHeaderBarInset} from './use-header-bar-inset'
+
+/** The row iOS gives a large title, which the top of a large-title screen includes. */
+const LARGE_TITLE_HEIGHT = 52
+
+const scrollToOffset = (target: HeaderScrollable, offset: number) => {
+  if ('scrollToOffset' in target) {
+    target.scrollToOffset({animated: true, offset})
+    return
+  }
+
+  if ('scrollTo' in target) {
+    target.scrollTo({animated: true, y: offset})
+    return
+  }
+
+  target.getScrollResponder()?.scrollTo({animated: true, y: offset})
+}
+
+/**
+ * A ref for React Navigation's or Expo Router's `useScrollToTop`: pressing the tab again scrolls the list back under a
+ * transparent header, with a large title expanded, where scrolling to 0 would leave the content under the bar and the
+ * title collapsed. `useScrollToTop(useHeaderScrollToTop(listRef, {largeTitle: true}))`.
+ */
+export const useHeaderScrollToTop = (
+  ref: RefObject<HeaderScrollable | null>,
+  {largeTitle = false, topInset = 0}: HeaderScrollToTopOptions = {}
+): HeaderScrollToTopRef => {
+  const barInset = useHeaderBarInset()
+  const offset = Platform.OS === 'ios' ? -(barInset + (largeTitle ? LARGE_TITLE_HEIGHT : 0) + topInset) : 0
+
+  return useMemo(
+    () => ({
+      current: {
+        scrollToTop: () => {
+          if (ref.current) {
+            scrollToOffset(ref.current, offset)
+          }
+        },
+      },
+    }),
+    [offset, ref]
+  )
+}

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

@@ -0,0 +1,138 @@
+import {useAppTheme} from '@hzblj/kara-theme'
+import {useCallback, useMemo, useRef, useState} from 'react'
+import {Platform} from 'react-native'
+import type {SearchBarCommands} from 'react-native-screens'
+
+import type {HeaderSearch, HeaderSearchBarOptions, HeaderSearchParams, HeaderSearchPlacement} from './header.types'
+import {headerColor} from './header-color'
+import {HeaderSearchAccessory} from './header-search-accessory'
+import {HEADER_SEARCH_ROW_HEIGHT, HeaderSearchInput} from './header-search-input'
+import type {HeaderSearchInputRef} from './header-search-input.types'
+import {HeaderSearchScrim} from './header-search-scrim'
+
+/** `integratedButton` hides the title and items while the field is open and keeps it out of the bottom toolbar. */
+const PLACEMENT_OPTIONS: Record<HeaderSearchPlacement, Partial<HeaderSearchBarOptions>> = {
+  integratedButton: {allowToolbarIntegration: false, hideNavigationBar: true},
+  stacked: {hideNavigationBar: false},
+}
+
+/**
+ * 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.
+ *
+ * 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`.
+ */
+export const useHeaderSearch = ({
+  cancelIcon,
+  clearIcon,
+  enabled = true,
+  placeholder = 'Search',
+  placement = 'stacked',
+  voice,
+}: HeaderSearchParams = {}): HeaderSearch => {
+  const theme = useAppTheme()
+  const [query, setQuery] = useState('')
+  const [focused, setFocused] = useState(false)
+  const searchBarRef = useRef<SearchBarCommands | null>(null)
+  const inputRef = useRef<HeaderSearchInputRef>(null)
+  const lastSetText = useRef<string | null>(null)
+  const voiceRef = useRef(voice)
+
+  voiceRef.current = voice
+
+  const cancelVoice = useCallback(() => {
+    if (voiceRef.current?.listening) {
+      voiceRef.current.onCancel?.()
+    }
+  }, [])
+
+  const changeQuery = useCallback(
+    (text: string) => {
+      if (text !== lastSetText.current) {
+        cancelVoice()
+      }
+      setQuery(text)
+    },
+    [cancelVoice]
+  )
+
+  const reset = useCallback(() => {
+    cancelVoice()
+    lastSetText.current = null
+    setQuery('')
+    setFocused(false)
+  }, [cancelVoice])
+
+  const searchBar = useMemo((): HeaderSearchBarOptions | undefined => {
+    if (!enabled || Platform.OS !== 'ios') {
+      return undefined
+    }
+
+    return {
+      ...PLACEMENT_OPTIONS[placement],
+      autoCapitalize: 'none',
+      hideWhenScrolling: false,
+      obscureBackground: false,
+      onBlur: () => setFocused(false),
+      onCancelButtonPress: reset,
+      onChangeText: event => changeQuery(event.nativeEvent.text),
+      onFocus: () => setFocused(true),
+      placeholder,
+      placement,
+      ref: searchBarRef,
+      tintColor: headerColor(theme, 'content.primary'),
+    }
+  }, [changeQuery, enabled, placeholder, placement, reset, theme])
+
+  const searchInput = useMemo(() => {
+    if (!enabled || Platform.OS !== 'android') {
+      return null
+    }
+
+    return (
+      <HeaderSearchInput
+        clearIcon={clearIcon}
+        onChangeText={changeQuery}
+        onFocusChange={setFocused}
+        placeholder={placeholder}
+        ref={inputRef}
+        voice={voice}
+      />
+    )
+  }, [changeQuery, clearIcon, enabled, placeholder, voice])
+
+  const clear = useCallback(() => {
+    reset()
+    searchBarRef.current?.cancelSearch()
+    inputRef.current?.clear()
+    inputRef.current?.blur()
+  }, [reset])
+
+  const setText = useCallback((text: string) => {
+    lastSetText.current = text
+    setQuery(text)
+    searchBarRef.current?.setText(text)
+    inputRef.current?.setText(text)
+  }, [])
+
+  const dimmed = enabled && focused && query.trim().length === 0
+
+  const scrim = useMemo(() => {
+    if (!enabled) {
+      return null
+    }
+
+    return (
+      <>
+        {dimmed ? <HeaderSearchScrim onPress={clear} topOffset={HEADER_SEARCH_ROW_HEIGHT} /> : null}
+        <HeaderSearchAccessory cancelIcon={cancelIcon} clearIcon={clearIcon} voice={voice} />
+      </>
+    )
+  }, [cancelIcon, clear, clearIcon, dimmed, enabled, voice])
+
+  return {clear, query, scrim, searchBar, searchInput, setText}
+}

package/src/organisms/header/use-header.ts

@@ -0,0 +1,67 @@
+import {useAppTheme} from '@hzblj/kara-theme'
+import {useLayoutEffect, useMemo} from 'react'
+
+import type {HeaderContent, HeaderNavigation, HeaderOptions, HeaderOptionsResult, HeaderParams} from './header.types'
+import {toHeaderOptions} from './header-options'
+import {useHeaderTitle} from './header-title'
+
+/**
+ * A screen's header as native-stack options, with what its list needs alongside: the title (centred, leading with a
+ * subtitle, revealed on scroll or large), the actions on both sides (the navigation bar's own items on iOS, Material
+ * buttons on Android) and a search field. Spread `options` into Expo Router's `<Stack.Screen options>` or a React
+ * Navigation screen's `options`. Memoize the action arrays: new arrays build new options on every render.
+ */
+export const useHeaderOptions = ({
+  backHidden,
+  largeTitle,
+  leadingActions,
+  search,
+  subtitle,
+  title,
+  titleHidden = false,
+  titleRevealProgress,
+  trailingActions,
+}: HeaderParams): HeaderOptionsResult => {
+  const theme = useAppTheme()
+  const headerTitle = useHeaderTitle({largeTitle, subtitle, title, titleHidden, titleRevealProgress})
+
+  const actionOptions = useMemo(
+    () => toHeaderOptions({backHidden, leadingActions, trailingActions}, theme),
+    [backHidden, leadingActions, theme, trailingActions]
+  )
+
+  return useMemo(() => {
+    const options: HeaderOptions = {}
+
+    Object.assign(options, headerTitle.options, actionOptions)
+
+    if (search) {
+      options.headerSearchBarOptions = search
+    }
+
+    return {
+      contentInsetAdjustmentBehavior: 'automatic',
+      largeTitle: headerTitle.largeTitle,
+      onScroll: headerTitle.onScroll,
+      options,
+    }
+  }, [actionOptions, headerTitle.largeTitle, headerTitle.onScroll, headerTitle.options, search])
+}
+
+/**
+ * Sets the screen's header through its navigation object, from React Navigation's or Expo Router's `useNavigation()`,
+ * before the screen first paints, and returns what its list needs. What a screen has from the moment it is pushed
+ * belongs in its static `options` too: iOS morphs the bar items between screens only when they exist at the push.
+ */
+export const useHeader = (navigation: HeaderNavigation, params: HeaderParams): HeaderContent => {
+  const {contentInsetAdjustmentBehavior, largeTitle, onScroll, options} = useHeaderOptions(params)
+
+  useLayoutEffect(() => {
+    navigation.setOptions(options)
+  }, [navigation, options])
+
+  return useMemo(
+    () => ({contentInsetAdjustmentBehavior, largeTitle, onScroll}),
+    [contentInsetAdjustmentBehavior, largeTitle, onScroll]
+  )
+}

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

@@ -0,0 +1,222 @@
+import {isScrollEdgeEffectAvailable, isViewControllerBasedStatusBarAppearance} from '@hzblj/kara-native'
+import {useAppTheme} from '@hzblj/kara-theme'
+import {useCallback, useEffect, useLayoutEffect, useMemo, useState} from 'react'
+import {Platform, StatusBar} from 'react-native'
+import {
+  Extrapolation,
+  interpolate,
+  type SharedValue,
+  useAnimatedReaction,
+  useDerivedValue,
+  useSharedValue,
+} from 'react-native-reanimated'
+import {useSafeAreaInsets} from 'react-native-safe-area-context'
+import {scheduleOnRN} from 'react-native-worklets'
+
+import type {
+  HeaderAction,
+  HeaderOptions,
+  HeroHeader,
+  HeroHeaderNavigation,
+  HeroHeaderParams,
+  HeroHeaderStyle,
+} from './header.types'
+import {headerColor} from './header-color'
+import {useIsTitleRevealed} from './header-title'
+import {HeroHeaderBackground} from './hero-header-background'
+import {useHeaderOptions} from './use-header'
+import {useHeaderBarInset} from './use-header-bar-inset'
+import {HERO_HEADER_SCREEN_OPTIONS} from './use-stack-screen-options'
+
+/** The header fades in while 50 to 70 % of the hero's part under the bar scrolls away. */
+const REVEAL_RANGE = [0.5, 0.7] as const
+
+/** Material 3's top app bar. */
+const ANDROID_BAR_HEIGHT = 64
+
+const useHeroBarHeight = () => {
+  const iosBarInset = useHeaderBarInset()
+  const {top} = useSafeAreaInsets()
+
+  return Platform.OS === 'ios' ? iosBarInset : top + ANDROID_BAR_HEIGHT
+}
+
+const useIsOverHero = (progress: SharedValue<number>) => {
+  const [overHero, setOverHero] = useState(() => progress.value === 0)
+
+  useAnimatedReaction(
+    () => progress.value === 0,
+    (isOver, wasOver) => {
+      if (isOver !== wasOver) {
+        scheduleOnRN(setOverHero, isOver)
+      }
+    }
+  )
+
+  return overHero
+}
+
+const useIsScreenFocused = (navigation: HeroHeaderNavigation) => {
+  const [focused, setFocused] = useState(() => navigation.isFocused())
+
+  useEffect(() => {
+    const unsubscribeFocus = navigation.addListener('focus', () => setFocused(true))
+    const unsubscribeBlur = navigation.addListener('blur', () => setFocused(false))
+
+    return () => {
+      unsubscribeFocus()
+      unsubscribeBlur()
+    }
+  }, [navigation])
+
+  return focused
+}
+
+const BAR_STYLES = {dark: 'dark-content', light: 'light-content'} as const satisfies Record<HeroHeaderStyle, string>
+
+/**
+ * The status bar over the hero, for this screen only. With view-controller-based appearance (Info.plist) the native
+ * stack sets it per screen (`statusBarStyle`); otherwise, as in Expo apps and on Android, React Native's `StatusBar`
+ * applies it while the screen is focused and over the hero, and its stack restores the previous style once it is not.
+ */
+const useHeroStatusBar = (navigation: HeroHeaderNavigation, overHero: boolean, overHeroStyle: HeroHeaderStyle) => {
+  const focused = useIsScreenFocused(navigation)
+  const perScreen = isViewControllerBasedStatusBarAppearance()
+
+  useEffect(() => {
+    if (perScreen) {
+      navigation.setOptions({statusBarStyle: overHero ? overHeroStyle : 'auto'})
+    }
+  }, [navigation, overHero, overHeroStyle, perScreen])
+
+  if (perScreen || !focused || !overHero) {
+    return null
+  }
+
+  return <StatusBar animated barStyle={BAR_STYLES[overHeroStyle]} />
+}
+
+const useRevealProgress = (barHeight: number, heroHeight: number, introProgress?: SharedValue<number>) => {
+  const scrollY = useSharedValue(0)
+  const heroUnderBar = heroHeight - barHeight
+  const start = heroUnderBar * REVEAL_RANGE[0]
+  const end = heroUnderBar * REVEAL_RANGE[1]
+
+  const scrollProgress = useDerivedValue(() => {
+    if (end <= start) {
+      return 1
+    }
+
+    return interpolate(scrollY.value, [start, end], [0, 1], Extrapolation.CLAMP)
+  })
+
+  const progress = useDerivedValue(() => Math.max(scrollProgress.value, introProgress?.value ?? 0))
+
+  const onScroll = useCallback(
+    (offsetY: number) => {
+      'worklet'
+      scrollY.value = offsetY
+    },
+    [scrollY]
+  )
+
+  return {onScroll, progress, scrollProgress}
+}
+
+/**
+ * A header over a full-bleed hero: the content runs under a transparent bar, and while 50 to 70 % of the hero's part
+ * under the bar scrolls away the header fades in — the title (and subtitle) in the bar, the bar's background
+ * (`background`: iOS 26's scroll edge effect switched on, the bar's material coming in below iOS 26, the top app bar's
+ * surface on Android), the items' tint and the status bar, light over the hero with `overHeroStyle` `light`. `revealedTrailingActions` join the
+ * bar once the title is shown. Give the screen `HERO_HEADER_SCREEN_OPTIONS` as static options, so its first frame has
+ * no large title, render `background` after the list and call `onScroll` with its offset.
+ */
+export const useHeroHeader = (
+  navigation: HeroHeaderNavigation,
+  {
+    backHidden,
+    heroHeight,
+    introProgress,
+    leadingActions,
+    overHeroStyle = 'light',
+    revealedTrailingActions,
+    subtitle,
+    title,
+    trailingActions,
+  }: HeroHeaderParams
+): HeroHeader => {
+  const theme = useAppTheme()
+  const barHeight = useHeroBarHeight()
+  const {onScroll, progress, scrollProgress} = useRevealProgress(barHeight, heroHeight, introProgress)
+  const titleShown = useIsTitleRevealed(scrollProgress)
+  const overHero = useIsOverHero(progress)
+  const scrolledOverHero = useIsOverHero(scrollProgress)
+  const statusBar = useHeroStatusBar(navigation, overHero, overHeroStyle)
+
+  const visibleTrailingActions = useMemo(() => {
+    if (!titleShown || !revealedTrailingActions) {
+      return trailingActions
+    }
+
+    const actions: HeaderAction[] = []
+
+    for (const action of revealedTrailingActions) {
+      actions.push(action)
+    }
+
+    for (const action of trailingActions ?? []) {
+      actions.push(action)
+    }
+
+    return actions
+  }, [revealedTrailingActions, titleShown, trailingActions])
+
+  const {options} = useHeaderOptions({
+    backHidden,
+    leadingActions,
+    subtitle,
+    title,
+    titleRevealProgress: scrollProgress,
+    trailingActions: visibleTrailingActions,
+  })
+
+  useLayoutEffect(() => {
+    navigation.setOptions(HERO_HEADER_SCREEN_OPTIONS)
+  }, [navigation])
+
+  useLayoutEffect(() => {
+    navigation.setOptions(options)
+  }, [navigation, options])
+
+  useEffect(() => {
+    const light = overHero && overHeroStyle === 'light'
+    const appearance: HeaderOptions = {
+      headerTintColor: headerColor(theme, light ? 'content.on.accent' : 'content.primary'),
+    }
+
+    if (isScrollEdgeEffectAvailable()) {
+      appearance.scrollEdgeEffects = {top: scrolledOverHero ? 'hidden' : 'automatic'}
+    }
+
+    navigation.setOptions(appearance)
+  }, [navigation, overHero, overHeroStyle, scrolledOverHero, theme])
+
+  const background = useMemo(
+    () => (
+      <>
+        <HeroHeaderBackground height={barHeight} progress={progress} />
+        {statusBar}
+      </>
+    ),
+    [barHeight, progress, statusBar]
+  )
+
+  return {
+    background,
+    contentInsetAdjustmentBehavior: 'never',
+    largeTitle: null,
+    onScroll,
+    progress,
+    scrollProgress,
+  }
+}

package/src/organisms/header/use-stack-screen-options.ts

@@ -0,0 +1,66 @@
+import {isScrollEdgeEffectAvailable} from '@hzblj/kara-native'
+import {useAppTheme} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
+import {Platform} from 'react-native'
+
+import type {StackScreenOptions} from './header.types'
+import {headerColor} from './header-color'
+
+/** iOS 26 draws its own scroll edge effect under a transparent bar; older iOS needs the bar's blur instead. */
+const HEADER_BLUR_EFFECT =
+  Platform.OS === 'ios' && !isScrollEdgeEffectAvailable() ? ('systemChromeMaterial' as const) : undefined
+
+/**
+ * A native stack's `screenOptions` in the active theme: the surface behind every screen, a minimal back button, the
+ * title and large title in the theme's `headline` and `headingM`, no hairline under the bar. iOS keeps the bar
+ * transparent so iOS 26 blurs what scrolls under it (older iOS gets the bar's material); Android gets a solid top app
+ * bar in the surface colour.
+ */
+export const useStackScreenOptions = (): StackScreenOptions => {
+  const theme = useAppTheme()
+
+  return useMemo(() => {
+    const content = headerColor(theme, 'content.primary')
+    const surface = headerColor(theme, 'surface.base')
+
+    return {
+      contentStyle: {backgroundColor: surface},
+      headerBackButtonDisplayMode: 'minimal',
+      headerBlurEffect: HEADER_BLUR_EFFECT,
+      headerLargeTitleShadowVisible: false,
+      headerLargeTitleStyle: {
+        color: content,
+        fontFamily: theme.typography.headingM.fontFamily,
+        fontSize: theme.typography.headingM.fontSize,
+      },
+      headerShadowVisible: false,
+      headerStyle: Platform.OS === 'android' ? {backgroundColor: surface} : undefined,
+      headerTintColor: content,
+      headerTitleStyle: {
+        color: content,
+        fontFamily: theme.typography.headline.fontFamily,
+        fontSize: theme.typography.headline.fontSize,
+      },
+      headerTransparent: Platform.OS === 'ios',
+    }
+  }, [theme])
+}
+
+/** A screen with a large title that collapses into the bar as its list scrolls. */
+export const LARGE_TITLE_SCREEN_OPTIONS: StackScreenOptions = {headerLargeTitleEnabled: true, headerShown: true}
+
+/** A screen without the stack's header, for one that draws its own or none. */
+export const HIDDEN_HEADER_SCREEN_OPTIONS: StackScreenOptions = {headerShown: false}
+
+/**
+ * A screen whose content runs under a transparent bar, a full-bleed image above all, for `useHeroHeader`. Static, so the
+ * first frame already has no large title and no bar background over the image.
+ */
+export const HERO_HEADER_SCREEN_OPTIONS: StackScreenOptions = {
+  headerBlurEffect: 'none',
+  headerLargeTitleEnabled: false,
+  headerShown: true,
+  headerStyle: {backgroundColor: 'transparent'},
+  headerTransparent: true,
+  scrollEdgeEffects: {top: 'hidden'},
+}

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

@@ -1,12 +1,12 @@
 import {Text as ComposeText, DropdownMenu, DropdownMenuItem} from '@expo/ui/jetpack-compose'
 import {useAppTheme} from '@hzblj/kara-theme'
 import {type ReactNode, useCallback, useState} from 'react'
+import {Glyph} from '../../atoms/glyph'
 import {HStack} from '../../atoms/h-stack'
 import {Icon} from '../../atoms/icon'
 import {IconButton} from '../../atoms/icon-button'
 import {Text} from '../../atoms/text'
-import {Glyph} from '../../glyph'
-import {useHostGuard} from '../../host-context'
+import {useHostGuard} from '../../hooks/host-context'
 import type {MenuAction, MenuComponent, MenuProps} from './menu.types'
 import {isIconOnly, menuActionColor} from './menu-parts'