@hzblj/kara-components 0.2.1 → 0.4.0

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

@@ -1,28 +1,55 @@
-import {HStack} from '../../atoms/h-stack'
+import {iconResourceName} from '@hzblj/kara-native'
+import {TopAppBar, type TopAppBarItem} from '@hzblj/kara-native/jetpack-compose'
+import {useAppTheme} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
+import {StyleSheet} from 'react-native'
 import {Island} from '../../atoms/island'
-import {Spacer} from '../../atoms/spacer'
-import {Text} from '../../atoms/text'
-import {GlyphButton} from '../../glyph'
-import type {NavigationBarComponent, NavigationBarProps} from './navigation-bar.types'
+import type {NavigationBarComponent, NavigationBarItem, NavigationBarProps} from './navigation-bar.types'
 
-/**
- * Material's top bar shape — navigation icon, start-aligned title, action at the end — built from the atoms in its own
- * island. Compose's icon buttons take no accessibility identifier, so `backTestID`/`closeTestID` are iOS-only.
- */
+/** Material's small top app bar. */
+const BAR_HEIGHT = 64
+
+const styles = StyleSheet.create({
+  bar: {height: BAR_HEIGHT, width: '100%'},
+})
+
+const DEFAULT_LABELS = {back: 'Back', close: 'Close'} as const
+
+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. */
 export const NavigationBar: NavigationBarComponent = ({
-  backLabel = 'Back',
-  closeLabel = 'Close',
-  onBack,
-  onClose,
+  inverted = false,
+  leadingItems,
   testID,
   title,
-}: NavigationBarProps) => (
-  <Island testID={testID}>
-    <HStack align="center" px="s4" spacing="s4" wide>
-      {onBack ? <GlyphButton accessibilityLabel={backLabel} name="back" onPress={onBack} /> : null}
-      {title ? <Text variant="body">{title}</Text> : null}
-      <Spacer />
-      {onClose ? <GlyphButton accessibilityLabel={closeLabel} name="close" onPress={onClose} /> : null}
-    </HStack>
-  </Island>
-)
+  titleAlignment = 'center',
+  titleVisible = true,
+  trailingItems,
+}: NavigationBarProps) => {
+  const theme = useAppTheme()
+  const font = theme.typography.headline
+  const color = theme.color(inverted ? 'content.on.bg' : 'content.primary')
+
+  const nativeLeadingItems = useMemo(() => leadingItems?.map(toNativeItem), [leadingItems])
+  const nativeTrailingItems = useMemo(() => trailingItems?.map(toNativeItem), [trailingItems])
+
+  return (
+    <Island matchContents={false} style={styles.bar} testID={testID}>
+      <TopAppBar
+        fontFamily={font.fontFamily}
+        fontSize={font.fontSize}
+        itemColor={color}
+        leadingItems={nativeLeadingItems}
+        title={title}
+        titleAlignment={titleAlignment}
+        titleColor={color}
+        titleVisible={titleVisible}
+        trailingItems={nativeTrailingItems}
+      />
+    </Island>
+  )
+}

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

@@ -1,33 +1,72 @@
-import {NavigationBar as NativeNavigationBar} from '@hzblj/kara-native/swift-ui'
+import {iconResourceName} from '@hzblj/kara-native'
+import {
+  NavigationBar as NativeNavigationBar,
+  type NavigationBarItem as NativeNavigationBarItem,
+  type NavigationBarRef,
+} from '@hzblj/kara-native/swift-ui'
 import {useAppTheme} from '@hzblj/kara-theme'
+import {useImperativeHandle, useMemo, useRef} from 'react'
 import {StyleSheet} from 'react-native'
-import type {NavigationBarComponent, NavigationBarProps} from './navigation-bar.types'
+import type {NavigationBarComponent, NavigationBarItem, NavigationBarProps} from './navigation-bar.types'
 
-/** UIKit's compact bar height. The bar centres itself vertically in whatever it is given. */
-const BAR_HEIGHT = 44
+/** Fits iOS 26's 44 pt glass items with the bar's own margin; the bar centres itself vertically in it. */
+const BAR_HEIGHT = 56
 
 const styles = StyleSheet.create({
   bar: {height: BAR_HEIGHT, width: '100%'},
 })
 
+const DEFAULT_LABELS = {back: 'Back', close: 'Close'} as const
+
+const toNativeItem = (item: NavigationBarItem): NativeNavigationBarItem =>
+  item.type === 'icon'
+    ? {...item, imageName: iconResourceName(item.icon), type: 'icon'}
+    : {...item, label: item.label ?? DEFAULT_LABELS[item.type]}
+
+const ignoreDetachedView = () => undefined
+
 export const NavigationBar: NavigationBarComponent = ({
-  backLabel = 'Back',
-  closeLabel = 'Close',
-  ...props
+  inverted = false,
+  leadingItems,
+  search,
+  testID,
+  title,
+  titleAlignment = 'center',
+  titleVisible = true,
+  trailingItems,
 }: NavigationBarProps) => {
   const theme = useAppTheme()
-  const title = theme.typography.body
+  const barRef = useRef<NavigationBarRef>(null)
+  const font = theme.typography.headline
+  const color = theme.color(inverted ? 'content.on.bg' : 'content.primary')
+
+  useImperativeHandle(
+    search?.ref,
+    () => ({clear: () => barRef.current?.clearSearchText().catch(ignoreDetachedView)}),
+    []
+  )
+
+  const nativeLeadingItems = useMemo(() => leadingItems?.map(toNativeItem), [leadingItems])
+  const nativeTrailingItems = useMemo(() => trailingItems?.map(toNativeItem), [trailingItems])
 
   return (
     <NativeNavigationBar
-      {...props}
-      backLabel={backLabel}
-      closeLabel={closeLabel}
-      fontFamily={title.fontFamily}
-      fontSize={title.fontSize}
-      itemColor={theme.color('content.primary')}
+      fontFamily={font.fontFamily}
+      fontSize={font.fontSize}
+      itemColor={color}
+      leadingItems={nativeLeadingItems}
+      onSearchFocusChange={search?.onFocusChange}
+      onSearchTextChange={search?.onChangeText}
+      ref={barRef}
+      searchPlaceholder={search?.placeholder}
+      searchTestID={search?.testID}
       style={styles.bar}
-      titleColor={theme.color('content.primary')}
+      testID={testID}
+      title={title}
+      titleAlignment={titleAlignment}
+      titleColor={color}
+      titleVisible={titleVisible}
+      trailingItems={nativeTrailingItems}
     />
   )
 }

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

@@ -1,26 +1,65 @@
-import type {ReactNode} from 'react'
+import type {ReactNode, Ref} from 'react'
+
+import type {IconName} from '../../atoms/icon'
+
+type NavigationBarItemBase = {
+  onPress: () => void
+  /**
+   * iOS 26: neighbouring items on one side share a glass capsule; this gives the item its own. A close next to
+   * actions usually wants it. Material has no grouped capsules, so Android ignores it.
+   */
+  separated?: boolean
+  /** iOS: the item's accessibility identifier; Android: its test tag. */
+  testID?: string
+}
+
+/**
+ * One item of the bar. `back` and `close` are the platform's own — a chevron and the system close item on iOS, the
+ * Material arrow and cross on Android — with `Back` / `Close` as their labels unless given others. `icon` is one of the
+ * app's icons and names itself for VoiceOver and TalkBack.
+ */
+export type NavigationBarItem =
+  | (NavigationBarItemBase & {label?: string; type: 'back' | 'close'})
+  | (NavigationBarItemBase & {icon: IconName; label: string; type: 'icon'})
+
+export type NavigationBarSearchRef = {
+  /** Empties the field and ends editing. */
+  clear: () => void
+}
+
+/** A search field in place of the title — iOS only for now; Android keeps the title. */
+export type NavigationBarSearch = {
+  onChangeText: (text: string) => void
+  onFocusChange?: (focused: boolean) => void
+  placeholder: string
+  ref?: Ref<NavigationBarSearchRef>
+  testID?: string
+}
+
+export type NavigationBarTitleAlignment = 'center' | 'leading'
 
 /**
- * A title with back and close items, for a sheet that is not a navigation screen. On iOS a standalone
- * `UINavigationBar`, so the items press and render exactly like a native-stack header's — on iOS 26 they share the
- * bar's glass instead of swelling as standalone glass buttons do. On Android a Material row of icon buttons. The React
- * Native tier: it needs no host.
+ * A title with items on either side, for a header that is not a navigation screen's — `Sheet.Header` is built on it.
+ * On iOS a standalone `UINavigationBar`, so the items press and render exactly like a native-stack header's: on iOS 26
+ * neighbours share a glass capsule instead of swelling as standalone glass buttons do. On Android Material's top app
+ * bar. Where an item goes is the caller's choice — the bar places nothing by itself, so a close can sit on either side.
+ * The React Native tier: it needs no host.
  */
 export type NavigationBarProps = {
-  /** The back item's accessibility label. `Back` by default. */
-  backLabel?: string
-  /** iOS: the back item's accessibility identifier. */
-  backTestID?: string
-  /** The close item's accessibility label. `Close` by default. */
-  closeLabel?: string
-  /** iOS: the close item's accessibility identifier. */
-  closeTestID?: string
-  /** Shows the back item. */
-  onBack?: () => void
-  /** Shows the close item. */
-  onClose?: () => void
+  /** Light items and title, for a bar laid over an image or a dark hero. */
+  inverted?: boolean
+  /** In screen order, from the leading edge. */
+  leadingItems?: NavigationBarItem[]
+  /** Replaces the title with a search field (iOS). */
+  search?: NavigationBarSearch
   testID?: string
   title?: string
+  /** `center` by default — iOS's own; `leading` is Material's top app bar. */
+  titleAlignment?: NavigationBarTitleAlignment
+  /** Fades the title out and in without moving the items — for a large title that scrolls under the bar. */
+  titleVisible?: boolean
+  /** In screen order, toward the trailing edge. */
+  trailingItems?: NavigationBarItem[]
 }
 
 export type NavigationBarComponent = (props: NavigationBarProps) => ReactNode

package/src/molecules/rn-list-item/index.ts

@@ -0,0 +1,2 @@
+export * from './rn-list-item'
+export * from './rn-list-item.types'

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

@@ -0,0 +1,48 @@
+import {useAppTheme} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
+import {Platform, Pressable, type PressableStateCallbackType} from 'react-native'
+
+import {Box} from '../../atoms/box'
+import {RnIcon} from '../../atoms/rn-icon'
+import {RnText} from '../../atoms/rn-text'
+import {RnGlyph} from '../../glyph'
+import type {RnListItemComponent, RnListItemProps} from './rn-list-item.types'
+
+export const RnListItem: RnListItemComponent = ({icon, onPress, px, subtitle, testID, title}: RnListItemProps) => {
+  const theme = useAppTheme()
+  const pressedColor = theme.color('fill.tertiary')
+
+  const ripple = useMemo(() => ({color: pressedColor}), [pressedColor])
+  const highlight = useMemo(
+    () =>
+      Platform.OS === 'ios'
+        ? ({pressed}: PressableStateCallbackType) => (pressed ? {backgroundColor: pressedColor} : null)
+        : undefined,
+    [pressedColor]
+  )
+
+  const row = (
+    <Box align="center" flexDirection="row" gap="s12" px={px} py="s12">
+      {icon ? <RnIcon color="content.secondary" name={icon} size="s20" /> : null}
+      <Box flex={1} gap="s2">
+        <RnText variant="body">{title}</RnText>
+        {subtitle ? (
+          <RnText color="content.secondary" variant="footnote">
+            {subtitle}
+          </RnText>
+        ) : null}
+      </Box>
+      {onPress ? <RnGlyph color="content.quaternary" name="chevronRight" size="s16" /> : null}
+    </Box>
+  )
+
+  if (!onPress) {
+    return <Box testID={testID}>{row}</Box>
+  }
+
+  return (
+    <Pressable accessibilityRole="button" android_ripple={ripple} onPress={onPress} style={highlight} testID={testID}>
+      {row}
+    </Pressable>
+  )
+}

package/src/molecules/rn-list-item/rn-list-item.types.ts

@@ -0,0 +1,13 @@
+import type {ReactNode} from 'react'
+
+import type {ListItemProps} from '../list-item'
+
+/**
+ * `ListItem`'s row in the React Native tier — plain views, no host. For lists long enough that a native host per row
+ * would cost too much to mount (a navigation list, a FlashList of rows), with the platform's own press feedback: a
+ * ripple across the whole row on Android, a highlight on iOS. In a rounded card, give the card `overflow="hidden"`:
+ * Android draws the ripple as the row's foreground, which only a parent's clip keeps inside rounded corners.
+ */
+export type RnListItemProps = ListItemProps
+
+export type RnListItemComponent = (props: RnListItemProps) => ReactNode

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

@@ -1,17 +1,20 @@
 import {Text as ComposeText, DropdownMenu, DropdownMenuItem, Host} from '@expo/ui/jetpack-compose'
 import {useSx} from '@hzblj/kara-sx'
 import {useAppTheme} from '@hzblj/kara-theme'
-import {useCallback, useState} from 'react'
-import {Pressable, StyleSheet, View} from 'react-native'
+import * as Haptics from 'expo-haptics'
+import {useCallback, useMemo, useRef, useState} from 'react'
+import {type GestureResponderEvent, Pressable, StyleSheet, View} from 'react-native'
+import {Icon} from '../../atoms/icon'
+import {HostBoundary} from '../../host-context'
+import {splitForRipple} from '../../ripple-clip'
 import type {MenuAction} from '../menu'
 import type {ContextMenuComponent, ContextMenuExclusionProps, ContextMenuProps} from './context-menu.types'
 
-/**
- * The menu's anchor: a point at the trigger's bottom start, so the dropdown opens just under it. The host lies outside
- * the touch path — the dropdown is a popup window of its own, which takes its touches regardless.
- */
+type Point = {x: number; y: number}
+
 const styles = StyleSheet.create({
-  anchor: {bottom: 0, height: 1, left: 0, position: 'absolute', width: 1},
+  /** A point under the finger: the dropdown opens from it. The menu is a popup window, so nothing clips it. */
+  anchor: {height: 1, position: 'absolute', width: 1},
 })
 
 type MenuRowProps = {
@@ -22,6 +25,7 @@ type MenuRowProps = {
 /** A row's `onClick` closes over its own action, so memoising it needs a component per row. */
 const MenuRow = ({action, onDismiss}: MenuRowProps) => {
   const theme = useAppTheme()
+  const color = action.destructive ? 'content.destructive' : 'content.primary'
 
   const onClick = useCallback(() => {
     onDismiss()
@@ -31,56 +35,77 @@ const MenuRow = ({action, onDismiss}: MenuRowProps) => {
   return (
     <DropdownMenuItem onClick={onClick}>
       <DropdownMenuItem.Text>
-        <ComposeText
-          color={theme.colorString(action.destructive ? 'content.destructive' : 'content.primary')}
-          style={theme.typography.body}
-        >
+        <ComposeText color={theme.colorString(color)} style={theme.typography.body}>
           {action.label}
         </ComposeText>
       </DropdownMenuItem.Text>
+      {action.icon ? (
+        <DropdownMenuItem.LeadingIcon>
+          <Icon color={color} name={action.icon} size="s20" />
+        </DropdownMenuItem.LeadingIcon>
+      ) : null}
     </DropdownMenuItem>
   )
 }
 
 /**
- * The trigger stays a plain React Native subtree; a long press on it expands a Compose `DropdownMenu` anchored under
- * it. The host behind the menu mounts on the first long press and stays — a list of triggers that are only scrolled
- * past never builds one. `preview` and `onPreviewPress` are iOS-only: Material has no lifted preview.
+ * Android's own take on a context menu, since Material has no lifted preview: a long press ripples the trigger, ticks
+ * the long-press haptic, and opens a Material dropdown where the finger is — the trigger stays highlighted while the
+ * menu is up. The host behind the menu mounts on the first long press and stays, so a list of triggers that are only
+ * scrolled past never builds one. `preview` and `onPreviewPress` are iOS-only.
  */
 const ContextMenuRoot = ({actions, children, testID, ...props}: ContextMenuProps) => {
   const {onPreviewPress: _onPreviewPress, preview: _preview, ...sx} = props
   const theme = useAppTheme()
-  const style = useSx(sx)
-  const [isHostMounted, setIsHostMounted] = useState(false)
+  const resolved = useSx(sx)
+  const trigger = useRef<View>(null)
+  const [anchor, setAnchor] = useState<Point | null>(null)
   const [expanded, setExpanded] = useState(false)
 
-  const open = useCallback(() => {
-    setIsHostMounted(true)
-    setExpanded(true)
+  // 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 highlight = useMemo(() => ({backgroundColor: theme.color('fill.tertiary')}), [theme])
+
+  const open = useCallback((event: GestureResponderEvent) => {
+    const {pageX, pageY} = event.nativeEvent
+
+    Haptics.performAndroidHapticsAsync(Haptics.AndroidHaptics.Long_Press).catch(() => undefined)
+    // The touch in the trigger's own coordinates: `locationX/Y` are relative to whichever child was touched.
+    trigger.current?.measure((_x, _y, _width, _height, left, top) => {
+      setAnchor({x: pageX - left, y: pageY - top})
+      setExpanded(true)
+    })
   }, [])
 
   const dismiss = useCallback(() => setExpanded(false), [])
 
   return (
-    <Pressable onLongPress={open} style={style} testID={testID}>
-      {children}
-      {isHostMounted ? (
-        <Host
-          colorScheme={theme.dark ? 'dark' : 'light'}
-          pointerEvents="none"
-          seedColor={theme.materialSeed}
-          style={styles.anchor}
-        >
-          <DropdownMenu expanded={expanded} onDismissRequest={dismiss}>
-            <DropdownMenu.Items>
-              {actions.map(action => (
-                <MenuRow action={action} key={action.label} onDismiss={dismiss} />
-              ))}
-            </DropdownMenu.Items>
-          </DropdownMenu>
-        </Host>
-      ) : null}
-    </Pressable>
+    <View style={outer}>
+      <Pressable android_ripple={ripple} onLongPress={open} ref={trigger} style={inner} testID={testID}>
+        {/* Under the content, over the trigger's own background: the card tints, its text stays. */}
+        {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}]}
+          >
+            <HostBoundary>
+              <DropdownMenu color={theme.color('surface.primary')} expanded={expanded} onDismissRequest={dismiss}>
+                <DropdownMenu.Items>
+                  {actions.map(action => (
+                    <MenuRow action={action} key={action.label} onDismiss={dismiss} />
+                  ))}
+                </DropdownMenu.Items>
+              </DropdownMenu>
+            </HostBoundary>
+          </Host>
+        ) : null}
+      </Pressable>
+    </View>
   )
 }
 

package/src/organisms/context-menu/context-menu.types.ts

@@ -5,7 +5,8 @@ import type {MenuAction} from '../menu'
 /**
  * A context menu on a React Native subtree — a card in a list, say — opened by a long press. iOS: a
  * `UIContextMenuInteraction`, with an optional React Native `preview` lifted while the menu is open and a callback for
- * a tap on it. Android: a Material dropdown under the subtree. The trigger is ordinary React Native layout, so it
+ * a tap on it. Android, where Material has no lifted preview: a ripple and the long-press haptic, then a Material
+ * dropdown where the finger is, with the trigger highlighted while it is open. The trigger is ordinary React Native layout, so it
  * needs no `Screen` or `Island`.
  */
 export type ContextMenuProps = ResponsiveViewSx & {

package/src/organisms/sheet/index.ts

@@ -1,2 +1,3 @@
 export * from './sheet'
 export * from './sheet.types'
+export {useSheetScroll} from './sheet-scroll'

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

@@ -0,0 +1,6 @@
+import type {SheetHeaderProps} from './sheet.types'
+
+/** A slot, never rendered: `Sheet` reads its props and builds the header into the native sheet's own header area. */
+export const SheetHeader = (_props: SheetHeaderProps): never => {
+  throw new Error('[kara-ui] <Sheet.Header> must be a direct child of <Sheet>.')
+}

package/src/organisms/sheet/sheet-scroll.tsx

@@ -0,0 +1,69 @@
+import {useSx} from '@hzblj/kara-sx'
+import {createContext, useCallback, useContext, useMemo} from 'react'
+import {ScrollView} from 'react-native'
+
+import type {SheetScrollContextValue, SheetScrollHandler, SheetScrollViewProps} from './sheet.types'
+
+export const SheetScrollContext = createContext<SheetScrollContextValue | null>(null)
+
+/**
+ * For a scroll view of your own inside a sheet (a `RnFlatList`, say): pad its content by `topInset`, render
+ * `largeTitle` first, and forward `onScroll` — which is what `<Sheet.ScrollView>` does.
+ */
+export const useSheetScroll = (): SheetScrollContextValue => {
+  const context = useContext(SheetScrollContext)
+
+  if (context === null) {
+    throw new Error('[kara-ui] useSheetScroll and <Sheet.ScrollView> must be used inside <Sheet>.')
+  }
+
+  return context
+}
+
+const NO_SX = {}
+
+/** The sheet's scrolling body: starts below the header on iOS 26, carries a large title, and reports its scroll. */
+export const SheetScrollView = ({
+  children,
+  content,
+  keyboardShouldPersistTaps,
+  onScroll,
+  testID,
+}: SheetScrollViewProps) => {
+  const {largeTitle, onScroll: onSheetScroll, topInset} = useSheetScroll()
+  const contentStyle = useSx(content ?? NO_SX)
+  // The header's room goes on top of the content's own top padding, not in place of it.
+  const containerStyle = useMemo(() => {
+    if (topInset === 0) {
+      return contentStyle
+    }
+
+    const ownTop = typeof contentStyle.paddingTop === 'number' ? contentStyle.paddingTop : 0
+
+    return [contentStyle, {paddingTop: topInset + ownTop}]
+  }, [contentStyle, topInset])
+
+  const handleScroll = useCallback<SheetScrollHandler>(
+    event => {
+      onSheetScroll?.(event)
+      onScroll?.(event)
+    },
+    [onScroll, onSheetScroll]
+  )
+
+  return (
+    <ScrollView
+      contentContainerStyle={containerStyle}
+      contentInsetAdjustmentBehavior="never"
+      keyboardShouldPersistTaps={keyboardShouldPersistTaps}
+      nestedScrollEnabled
+      onScroll={onSheetScroll || onScroll ? handleScroll : undefined}
+      overScrollMode="always"
+      scrollEventThrottle={16}
+      testID={testID}
+    >
+      {largeTitle}
+      {children}
+    </ScrollView>
+  )
+}