@hzblj/kara-components 0.20.0 → 0.21.0

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

@@ -6,9 +6,9 @@ import {
 } from '@hzblj/kara-native/jetpack-compose'
 import {useAppTheme} from '@hzblj/kara-theme'
 import {useCallback, useState} from 'react'
+import {Glyph} from '../../atoms/glyph'
 import {Icon} from '../../atoms/icon'
-import {Glyph} from '../../glyph'
-import {useHostGuard} from '../../host-context'
+import {useHostGuard} from '../../hooks/host-context'
 import type {MenuAction} from '../menu'
 import type {FabMenuComponent, FabMenuProps} from './fab-menu.types'
 

package/src/organisms/fab-menu/fab-menu.ios.tsx

@@ -1,11 +1,10 @@
 import {Button, Image, Label, Menu} from '@expo/ui/swift-ui'
 import {disabled} from '@expo/ui/swift-ui/modifiers'
 import {iconResourceName} from '@hzblj/expo-native-icons'
-
+import {Glyph} from '../../atoms/glyph'
 import {Icon} from '../../atoms/icon'
 import {VStack} from '../../atoms/v-stack'
-import {Glyph} from '../../glyph'
-import {useHostGuard} from '../../host-context'
+import {useHostGuard} from '../../hooks/host-context'
 import type {FabMenuComponent, FabMenuProps} from './fab-menu.types'
 
 /** Matches `Fab`, so a screen can switch between the two without the button changing shape. */

package/src/organisms/form/form.android.tsx

@@ -1,7 +1,7 @@
 import {Card} from '../../atoms/card'
 import {Text} from '../../atoms/text'
 import {VStack} from '../../atoms/v-stack'
-import {useHostGuard} from '../../host-context'
+import {useHostGuard} from '../../hooks/host-context'
 import type {FormComponent, FormProps, FormSectionProps} from './form.types'
 
 /**

package/src/organisms/form/form.ios.tsx

@@ -1,6 +1,6 @@
 import {Section, Form as SwiftUIForm} from '@expo/ui/swift-ui'
 import {Text} from '../../atoms/text'
-import {useHostGuard} from '../../host-context'
+import {useHostGuard} from '../../hooks/host-context'
 import type {FormComponent, FormProps, FormSectionProps} from './form.types'
 
 const FormRoot = ({children, testID}: FormProps) => {

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

@@ -0,0 +1,7 @@
+import type {ColorToken, Theme} from '@hzblj/kara-theme'
+
+/**
+ * The native stack types header colours as `string`, but they only end up in native styles, which take any
+ * `ColorValue`, including the opaque `PlatformColor` a system token resolves to on iOS.
+ */
+export const headerColor = (theme: Theme, token: ColorToken): string => theme.color(token) as string

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

@@ -0,0 +1,3 @@
+import type {HeaderInsetComponent, HeaderInsetProps} from './header.types'
+
+export const HeaderInset: HeaderInsetComponent = ({children}: HeaderInsetProps) => children

package/src/organisms/header/header-inset.ios.tsx

@@ -0,0 +1,12 @@
+import {SafeAreaView} from 'react-native-screens/experimental'
+
+import type {HeaderInsetComponent, HeaderInsetProps} from './header.types'
+
+const TOP_EDGE = {top: true}
+const INSET_STYLE = {flex: 0}
+
+export const HeaderInset: HeaderInsetComponent = ({children}: HeaderInsetProps) => (
+  <SafeAreaView edges={TOP_EDGE} pointerEvents="box-none" style={INSET_STYLE}>
+    {children}
+  </SafeAreaView>
+)

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

@@ -0,0 +1,168 @@
+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 {HostBoundary} from '../../hooks/host-context'
+import {Menu, type MenuAction} from '../menu'
+import type {
+  HeaderAction,
+  HeaderItemProps,
+  HeaderMenuItem,
+  HeaderNavigationAction,
+  HeaderOptions,
+  HeaderParams,
+} from './header.types'
+import type {HeaderOptionsBuilder} from './header-options.types'
+
+const DEFAULT_LABELS = {back: 'Back', close: 'Close'} as const
+
+const styles = StyleSheet.create({
+  // Material's navigation icon sits 4dp from the edge in a 48dp target; the toolbar insets custom content by 16dp.
+  navigationRow: {alignItems: 'center', flexDirection: 'row', marginStart: -12},
+  row: {alignItems: 'center', flexDirection: 'row'},
+  spinner: {alignItems: 'center', height: 48, justifyContent: 'center', width: 48},
+})
+
+/** 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}>
+      <HostBoundary>{children}</HostBoundary>
+    </Host>
+  )
+}
+
+const toMenuActions = (items: HeaderMenuItem[]): MenuAction[] => {
+  const actions: MenuAction[] = []
+
+  for (const item of items) {
+    if (item.type === 'submenu') {
+      for (const nested of toMenuActions(item.items)) {
+        actions.push(nested)
+      }
+      continue
+    }
+
+    actions.push({
+      destructive: item.destructive,
+      disabled: item.disabled,
+      icon: item.icon,
+      label: item.label,
+      onPress: item.onPress,
+    })
+  }
+
+  return actions
+}
+
+const HeaderActionView = ({action}: {action: HeaderAction}) => {
+  switch (action.type) {
+    case 'back':
+    case 'close': {
+      const label = action.label ?? DEFAULT_LABELS[action.type]
+
+      return (
+        <ActionHost>
+          {action.icon ? (
+            <IconButton accessibilityLabel={label} name={action.icon} onPress={action.onPress} testID={action.testID} />
+          ) : (
+            <GlyphButton accessibilityLabel={label} name={action.type} onPress={action.onPress} />
+          )}
+        </ActionHost>
+      )
+    }
+    case 'icon':
+      if (action.loading) {
+        return (
+          <View style={styles.spinner} testID={action.testID}>
+            <ActivityIndicator accessibilityLabel={action.label} color={action.color ?? 'content.primary'} />
+          </View>
+        )
+      }
+
+      return (
+        <ActionHost>
+          <IconButton
+            accessibilityLabel={action.label}
+            color={action.color}
+            disabled={action.disabled}
+            name={action.icon}
+            onPress={action.onPress}
+            testID={action.testID}
+          />
+        </ActionHost>
+      )
+    case 'text':
+      return (
+        <ActionHost>
+          <Button
+            disabled={action.disabled}
+            label={action.label}
+            onPress={action.onPress}
+            testID={action.testID}
+            variant="plain"
+            wide={false}
+          />
+        </ActionHost>
+      )
+    case 'menu':
+      return (
+        <ActionHost>
+          <Menu
+            accessibilityLabel={action.label}
+            actions={toMenuActions(action.items)}
+            icon={action.icon}
+            testID={action.testID}
+          />
+        </ActionHost>
+      )
+    case 'custom':
+      return action.element
+  }
+}
+
+const renderActions =
+  (actions: HeaderAction[], isLeading: boolean, backHidden: boolean) =>
+  ({canGoBack}: HeaderItemProps) => (
+    <View style={isLeading && (backHidden || !canGoBack) ? styles.navigationRow : styles.row}>
+      {actions.map((action, index) => (
+        <HeaderActionView action={action} key={action.type === 'custom' ? action.key : index} />
+      ))}
+    </View>
+  )
+
+const isClose = (action: HeaderAction): action is HeaderNavigationAction => action.type === 'close'
+
+/** Material's full-screen dialog: with no back to show, the close is the navigation icon at the start. */
+const placeClose = ({backHidden = false, leadingActions, trailingActions}: HeaderParams) => {
+  const close = backHidden && !leadingActions?.length ? trailingActions?.find(isClose) : undefined
+
+  if (!close) {
+    return {leading: leadingActions, trailing: trailingActions}
+  }
+
+  return {leading: [close], trailing: trailingActions?.filter(action => action !== close)}
+}
+
+export const toHeaderOptions: HeaderOptionsBuilder = (params: HeaderParams) => {
+  const backHidden = params.backHidden ?? false
+  const {leading, trailing} = placeClose(params)
+  const options: HeaderOptions = {headerBackVisible: !backHidden}
+
+  if (leading) {
+    options.headerLeft = leading.length > 0 ? renderActions(leading, true, backHidden) : undefined
+  }
+
+  if (trailing) {
+    options.headerRight = trailing.length > 0 ? renderActions(trailing, false, backHidden) : undefined
+  }
+
+  return options
+}

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

@@ -0,0 +1,138 @@
+import {iconResourceName} from '@hzblj/expo-native-icons'
+import {GLYPHS} from '@hzblj/kara-native'
+import type {Theme} from '@hzblj/kara-theme'
+
+import {ActivityIndicator} from '../../atoms/activity-indicator'
+import type {IconName} from '../../atoms/icon'
+import type {
+  HeaderAction,
+  HeaderMenuItem,
+  HeaderOptions,
+  HeaderParams,
+  NativeHeaderItem,
+  NativeHeaderMenuElement,
+} from './header.types'
+import type {HeaderOptionsBuilder} from './header-options.types'
+
+const DEFAULT_LABELS = {back: 'Back', close: 'Close'} as const
+
+/** A zero-width spacing item between two groups is what ends a glass capsule on iOS 26, as the system's headers do. */
+const GROUP_BREAK: NativeHeaderItem = {spacing: 0, type: 'spacing'}
+
+const imageIcon = (icon: IconName) => ({source: {uri: iconResourceName(icon)}, type: 'image'}) as const
+
+const toMenuElement = (item: HeaderMenuItem): NativeHeaderMenuElement => {
+  if (item.type === 'submenu') {
+    return {
+      icon: item.icon ? imageIcon(item.icon) : undefined,
+      inline: item.inline,
+      items: item.items.map(toMenuElement),
+      label: item.label,
+      type: 'submenu',
+    }
+  }
+
+  return {
+    description: item.description,
+    destructive: item.destructive,
+    disabled: item.disabled,
+    icon: item.icon ? imageIcon(item.icon) : undefined,
+    label: item.label,
+    onPress: item.onPress,
+    state: item.checked ? 'on' : undefined,
+    type: 'action',
+  }
+}
+
+const toItem = (action: HeaderAction, theme: Theme): NativeHeaderItem => {
+  switch (action.type) {
+    case 'back':
+    case 'close': {
+      const label = action.label ?? DEFAULT_LABELS[action.type]
+
+      return {
+        accessibilityLabel: label,
+        icon: action.icon ? imageIcon(action.icon) : {name: GLYPHS[action.type].ios, type: 'sfSymbol'},
+        identifier: action.testID,
+        label,
+        onPress: action.onPress,
+        sharesBackground: action.separated ? false : undefined,
+        type: 'button',
+      }
+    }
+    case 'icon':
+      if (action.loading) {
+        return {
+          element: <ActivityIndicator accessibilityLabel={action.label} color="content.primary" />,
+          type: 'custom',
+        }
+      }
+
+      return {
+        accessibilityLabel: action.label,
+        badge: action.badge === undefined ? undefined : {value: action.badge},
+        disabled: action.disabled,
+        icon: imageIcon(action.icon),
+        identifier: action.testID,
+        label: action.label,
+        onPress: action.onPress,
+        selected: action.selected,
+        sharesBackground: action.separated ? false : undefined,
+        tintColor: action.color ? theme.color(action.color) : undefined,
+        type: 'button',
+      }
+    case 'text':
+      return {
+        disabled: action.disabled,
+        identifier: action.testID,
+        label: action.label,
+        onPress: action.onPress,
+        sharesBackground: action.separated ? false : undefined,
+        type: 'button',
+        variant: action.prominent ? 'prominent' : undefined,
+      }
+    case 'menu':
+      return {
+        accessibilityLabel: action.label,
+        icon: imageIcon(action.icon),
+        identifier: action.testID,
+        label: action.label,
+        menu: {items: action.items.map(toMenuElement), title: action.title},
+        sharesBackground: action.separated ? false : undefined,
+        type: 'menu',
+      }
+    case 'custom':
+      return {element: action.element, hidesSharedBackground: action.separated, type: 'custom'}
+  }
+}
+
+const toItems = (actions: HeaderAction[], theme: Theme) => () => {
+  const items: NativeHeaderItem[] = []
+
+  for (const action of actions) {
+    items.push(toItem(action, theme))
+
+    if (action.separated) {
+      items.push(GROUP_BREAK)
+    }
+  }
+
+  return items
+}
+
+export const toHeaderOptions: HeaderOptionsBuilder = (
+  {backHidden = false, leadingActions, trailingActions}: HeaderParams,
+  theme: Theme
+) => {
+  const options: HeaderOptions = {headerBackVisible: !backHidden}
+
+  if (leadingActions) {
+    options.unstable_headerLeftItems = leadingActions.length > 0 ? toItems(leadingActions, theme) : undefined
+  }
+
+  if (trailingActions) {
+    options.unstable_headerRightItems = trailingActions.length > 0 ? toItems(trailingActions, theme) : undefined
+  }
+
+  return options
+}

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

@@ -0,0 +1,6 @@
+import type {Theme} from '@hzblj/kara-theme'
+
+import type {HeaderOptions, HeaderParams} from './header.types'
+
+/** Turns a header's actions into the native-stack options each platform draws them from. */
+export type HeaderOptionsBuilder = (params: HeaderParams, theme: Theme) => HeaderOptions

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

@@ -0,0 +1,4 @@
+import type {HeaderSearchAccessoryComponent} from './header-search-accessory.types'
+
+/** Android's field is a Compose view of kara's own, which takes its glyphs and voice directly (`searchInput`). */
+export const HeaderSearchAccessory: HeaderSearchAccessoryComponent = () => null

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

@@ -0,0 +1,42 @@
+import {iconResourceName} from '@hzblj/expo-native-icons'
+import {NavigationItemSearch} from '@hzblj/kara-native/swift-ui'
+import {useAppTheme} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
+
+import type {IconName} from '../../atoms/icon'
+import {headerColor} from './header-color'
+import type {HeaderSearchAccessoryComponent, HeaderSearchAccessoryProps} from './header-search-accessory.types'
+
+const toImageName = (icon?: IconName) => (icon ? iconResourceName(icon) : undefined)
+
+/**
+ * The header search field's glyphs and voice on iOS: react-native-screens' search bar belongs to the navigation item,
+ * so a layout-less native view in the screen's tree dresses it.
+ */
+export const HeaderSearchAccessory: HeaderSearchAccessoryComponent = ({
+  cancelIcon,
+  clearIcon,
+  voice,
+}: HeaderSearchAccessoryProps) => {
+  const theme = useAppTheme()
+  const color = headerColor(theme, 'content.primary')
+  const nativeVoice = useMemo(
+    () =>
+      voice && {
+        ...voice,
+        clearImageName: toImageName(voice.clearIcon ?? clearIcon),
+        color: voice.color ?? color,
+        microphoneImageName: toImageName(voice.microphoneIcon),
+        stopImageName: toImageName(voice.stopIcon),
+      },
+    [clearIcon, color, voice]
+  )
+
+  return (
+    <NavigationItemSearch
+      cancelImageName={toImageName(cancelIcon)}
+      clearImageName={toImageName(clearIcon)}
+      voice={nativeVoice}
+    />
+  )
+}

package/src/organisms/header/header-search-accessory.types.ts

@@ -0,0 +1,12 @@
+import type {ReactNode} from 'react'
+
+import type {IconName} from '../../atoms/icon'
+import type {SearchFieldVoice} from '../../molecules/navigation-bar/navigation-bar.types'
+
+export type HeaderSearchAccessoryProps = {
+  cancelIcon?: IconName
+  clearIcon?: IconName
+  voice?: SearchFieldVoice
+}
+
+export type HeaderSearchAccessoryComponent = (props: HeaderSearchAccessoryProps) => ReactNode

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

@@ -0,0 +1,89 @@
+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 {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},
+})
+
+const ignoreDetachedView = () => undefined
+
+export const HeaderSearchInput: HeaderSearchInputComponent = ({
+  clearIcon,
+  onChangeText,
+  onFocusChange,
+  placeholder,
+  ref,
+  voice,
+}: HeaderSearchInputProps) => {
+  const theme = useAppTheme()
+  const fieldRef = useRef<SearchFieldRef>(null)
+  const face = theme.typography.body
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      blur: () => {
+        fieldRef.current?.blurField().catch(ignoreDetachedView)
+      },
+      clear: () => {
+        fieldRef.current?.clearQuery().catch(ignoreDetachedView)
+      },
+      setText: (text: string) => {
+        fieldRef.current?.setQuery(text).catch(ignoreDetachedView)
+      },
+    }),
+    []
+  )
+
+  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>
+  )
+}

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

@@ -0,0 +1,7 @@
+import type {HeaderSearchInputComponent} from './header-search-input.types'
+
+/** iOS searches in the navigation bar itself (`headerSearchBarOptions`). */
+export const HeaderSearchInput: HeaderSearchInputComponent = () => null
+
+/** The row's height under the bar. iOS has none. */
+export const HEADER_SEARCH_ROW_HEIGHT = 0

package/src/organisms/header/header-search-input.types.ts

@@ -0,0 +1,21 @@
+import type {ReactNode, Ref} from 'react'
+
+import type {IconName} from '../../atoms/icon'
+import type {SearchFieldVoice} from '../../molecules/navigation-bar/navigation-bar.types'
+
+export type HeaderSearchInputRef = {
+  blur: () => void
+  clear: () => void
+  setText: (text: string) => void
+}
+
+export type HeaderSearchInputProps = {
+  clearIcon?: IconName
+  onChangeText: (text: string) => void
+  onFocusChange: (focused: boolean) => void
+  placeholder: string
+  ref?: Ref<HeaderSearchInputRef>
+  voice?: SearchFieldVoice
+}
+
+export type HeaderSearchInputComponent = (props: HeaderSearchInputProps) => ReactNode

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

@@ -0,0 +1,49 @@
+import {useAppTheme} from '@hzblj/kara-theme'
+import {Platform, Pressable, StyleSheet, View} from 'react-native'
+import Animated, {FadeIn, FadeOut} from 'react-native-reanimated'
+import {SafeAreaView} from 'react-native-screens/experimental'
+
+const SCRIM_OPACITY = 0.7
+const ENTERING = FadeIn.duration(200)
+const EXITING = FadeOut.duration(200)
+const TOP_EDGE = {top: true}
+
+const styles = StyleSheet.create({
+  fill: {flex: 1},
+  layer: {bottom: 0, left: 0, position: 'absolute', right: 0, zIndex: 10},
+})
+
+type HeaderSearchScrimProps = {
+  onPress: () => void
+  topOffset: number
+}
+
+/**
+ * Washes the content out while the search field is focused and empty, as the system's own search does without
+ * dimming the bar; a tap on it ends the search. iOS starts it under the bar, following the bar natively
+ * (react-native-screens' `SafeAreaView`), Android under the search row.
+ */
+export const HeaderSearchScrim = ({onPress, topOffset}: HeaderSearchScrimProps) => {
+  const theme = useAppTheme()
+  const scrim = (
+    <Animated.View
+      entering={ENTERING}
+      exiting={EXITING}
+      style={[styles.fill, {backgroundColor: theme.color('surface.base'), opacity: SCRIM_OPACITY}]}
+    >
+      <Pressable accessible={false} onPress={onPress} style={styles.fill} />
+    </Animated.View>
+  )
+
+  return (
+    <View pointerEvents="box-none" style={[styles.layer, {top: topOffset}]}>
+      {Platform.OS === 'ios' ? (
+        <SafeAreaView edges={TOP_EDGE} pointerEvents="box-none" style={styles.fill}>
+          {scrim}
+        </SafeAreaView>
+      ) : (
+        scrim
+      )}
+    </View>
+  )
+}