@hzblj/kara-components 0.6.0 → 0.8.0

package/src/atoms/z-stack/z-stack.types.ts

@@ -3,10 +3,18 @@ import type {ReactNode} from 'react'
 
 export type ZStackAlign = 'bottom' | 'center' | 'top'
 
+/** Layers its children on one another — SwiftUI `ZStack` / Compose `Box`. */
 export type ZStackProps = ResponsiveSx & {
+  /** Where the children sit vertically; they are always centred horizontally. `center` by default. */
   align?: ZStackAlign
+  /** Drawn in order, the last on top. */
   children?: ReactNode
+  /**
+   * Makes the whole stack pressable. iOS adds a tap gesture with no press feedback; Android a `clickable` whose ripple
+   * fills the stack's shape.
+   */
   onPress?: () => void
+  /** Test identifier, forwarded to the native view. */
   testID?: string
 }
 

package/src/molecules/collapsible/collapsible.android.tsx

@@ -1,25 +1,65 @@
-import {AnimatedVisibility, Column, Text as ComposeText, Row} from '@expo/ui/jetpack-compose'
-import {clickable} from '@expo/ui/jetpack-compose/modifiers'
-import {useAppTheme} from '@hzblj/kara-theme'
+import {
+  AnimatedVisibility,
+  Box,
+  Column,
+  Text as ComposeText,
+  EnterTransition,
+  ExitTransition,
+  Row,
+} from '@expo/ui/jetpack-compose'
+import {
+  animated,
+  clickable,
+  defaultMinSize,
+  fillMaxWidth,
+  graphicsLayer,
+  tween,
+} from '@expo/ui/jetpack-compose/modifiers'
+import {duration, useAppTheme} from '@hzblj/kara-theme'
 import {useMemo} from 'react'
 import {Glyph} from '../../glyph'
 import {useHostGuard} from '../../host-context'
 import type {CollapsibleComponent, CollapsibleProps} from './collapsible.types'
 
+/** Material's standard easing, at the length a disclosure takes. */
+const TURN = tween({durationMillis: duration.d200, easing: 'fastOutSlowIn'})
+
+/** Down from the row, fading in — Compose's default grows from a corner, sideways as well as down. */
+const ENTER = EnterTransition.expandVertically().plus(EnterTransition.fadeIn())
+const EXIT = ExitTransition.shrinkVertically().plus(ExitTransition.fadeOut())
+
+const WIDE = [fillMaxWidth()]
+
+/** Material's least touch target. */
+const ROW_HEIGHT = 48
+
+/**
+ * A pressable row and an animated reveal: the content expands down from the row, and the chevron turns a quarter
+ * toward it, as a Material disclosure does — it used to jump between two glyphs. The row spans its parent, the chevron
+ * at the far end, and is never shorter than a touch target.
+ */
 export const Collapsible: CollapsibleComponent = ({children, expanded, label, onExpandedChange}: CollapsibleProps) => {
   useHostGuard('Collapsible')
   const theme = useAppTheme()
-  const modifiers = useMemo(() => [clickable(() => onExpandedChange(!expanded))], [expanded, onExpandedChange])
+  const modifiers = useMemo(
+    () => [fillMaxWidth(), defaultMinSize({minHeight: ROW_HEIGHT}), clickable(() => onExpandedChange(!expanded))],
+    [expanded, onExpandedChange]
+  )
+  const turn = useMemo(() => [graphicsLayer({rotationZ: animated(expanded ? 90 : 0, TURN)})], [expanded])
 
   return (
-    <Column>
+    <Column modifiers={WIDE}>
       <Row horizontalArrangement="spaceBetween" modifiers={modifiers} verticalAlignment="center">
         <ComposeText color={theme.colorString('content.primary')} style={theme.typography.body}>
           {label}
         </ComposeText>
-        <Glyph name={expanded ? 'chevronDown' : 'chevronRight'} size="s20" />
+        <Box modifiers={turn}>
+          <Glyph name="chevronRight" size="s20" />
+        </Box>
       </Row>
-      <AnimatedVisibility visible={expanded}>{children}</AnimatedVisibility>
+      <AnimatedVisibility enterTransition={ENTER} exitTransition={EXIT} visible={expanded}>
+        {children}
+      </AnimatedVisibility>
     </Column>
   )
 }

package/src/molecules/collapsible/collapsible.types.ts

@@ -1,9 +1,17 @@
 import type {ReactNode} from 'react'
 
+/**
+ * A row that shows and hides its content: SwiftUI's `DisclosureGroup` on iOS; on Android a pressable row with a
+ * chevron over an animated reveal. A native atom — it renders inside `<Screen>` or `<Island>`.
+ */
 export type CollapsibleProps = {
+  /** Shown while `expanded`. */
   children: ReactNode
+  /** Whether the content is shown. Update it from `onExpandedChange`. */
   expanded: boolean
+  /** The row's text. */
   label: string
+  /** The user pressed the row; it passes the state the row asks for. */
   onExpandedChange: (expanded: boolean) => void
 }
 

package/src/molecules/empty-state/empty-state.types.ts

@@ -6,10 +6,15 @@ import type {IconName} from '../../atoms/icon'
  * `action` takes a `Button` so the state can offer a way out.
  */
 export type EmptyStateProps = {
+  /** Under the text — a `Button`, say. */
   action?: ReactNode
+  /** A second line under the title, in the secondary colour. */
   description?: string
+  /** One of the app's icons, large and muted above the title. */
   icon?: IconName
+  /** Test identifier, forwarded to the native view. */
   testID?: string
+  /** The headline. */
   title: string
 }
 

package/src/molecules/label/label.types.ts

@@ -8,11 +8,17 @@ import type {IconName} from '../../atoms/icon'
  * header. For a full tappable row with a subtitle and chevron, use `ListItem`.
  */
 export type LabelProps = {
+  /** Colours the icon and the title alike. `content.primary` by default. */
   color?: ColorToken
+  /** One of the app's icons, before the title. */
   icon: IconName
+  /** The icon's size. `s20` by default. */
   iconSize?: SpaceSize
+  /** Test identifier, forwarded to the native view. */
   testID?: string
+  /** The text beside the icon. */
   title: string
+  /** The title's text style. `body` by default. */
   variant?: TextVariant
 }
 

package/src/molecules/labeled-content/labeled-content.types.ts

@@ -7,13 +7,19 @@ import type {IconName} from '../../atoms/icon'
  * Pass `children` instead of `value` when the trailing side is a control rather than text.
  */
 export type LabeledContentProps = {
+  /** The trailing side when it is a control, in place of `value`. */
   children?: ReactNode
+  /** One of the app's icons, before the label, in the secondary colour. */
   icon?: IconName
+  /** The leading text. */
   label: string
+  /** Makes the row pressable and adds a chevron on the trailing edge. */
   onPress?: () => void
   /** Horizontal padding inside the row — inside its press area too, so Android's ripple reaches the card's edges. */
   px?: SpaceSize
+  /** Test identifier, forwarded to the native view. */
   testID?: string
+  /** The trailing text, in the secondary colour. Ignored when `children` is given. */
   value?: string
 }
 

package/src/molecules/link/link.types.ts

@@ -5,11 +5,17 @@ import type {IconName} from '../../atoms/icon'
 
 /** Opens an external URL in the platform browser or the app that claims the scheme. */
 export type LinkProps = {
+  /** Colours the label and the icon. `content.accent` by default. */
   color?: ColorToken
+  /** One of the app's icons, before the label. */
   icon?: IconName
+  /** The link's text. */
   label: string
+  /** Test identifier, forwarded to the native view. */
   testID?: string
+  /** Opened through React Native's `Linking` on press. A URL nothing can open fails silently. */
   url: string
+  /** The label's text style. `body` by default. */
   variant?: TextVariant
 }
 

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

@@ -3,16 +3,25 @@ import type {ReactNode} from 'react'
 
 import type {IconName} from '../../atoms/icon'
 
+/**
+ * A row with an optional icon, a title and subtitle, and a chevron when it can be pressed. A native atom — it renders
+ * inside `<Screen>` or `<Island>`; `RnListItem` is the same row without a host.
+ */
 export type ListItemProps = {
+  /** One of the app's icons, before the title, in the secondary colour. */
   icon?: IconName
+  /** Makes the row pressable and adds a chevron on the trailing edge. */
   onPress?: () => void
   /**
    * Horizontal padding inside the row — inside its press area too, so Android's ripple reaches the card's edges. For
    * rows in a card of your own; a `List` insets its rows by itself.
    */
   px?: SpaceSize
+  /** A second line under the title, smaller and in the secondary colour. */
   subtitle?: string
+  /** Test identifier, forwarded to the row's view. */
   testID?: string
+  /** The row's main text. */
   title: string
 }
 

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

@@ -2,17 +2,12 @@ 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 type {NavigationBarComponent, NavigationBarItem, NavigationBarProps} from './navigation-bar.types'
 
 /** 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 =>
@@ -38,7 +33,7 @@ export const NavigationBar: NavigationBarComponent = ({
   const nativeTrailingItems = useMemo(() => trailingItems?.map(toNativeItem), [trailingItems])
 
   return (
-    <Island matchContents={false} style={styles.bar} testID={testID}>
+    <Island h={BAR_HEIGHT} matchContents={false} testID={testID} w="100%">
       <TopAppBar
         fontFamily={font.fontFamily}
         fontSize={font.fontSize}

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

@@ -3,6 +3,7 @@ import type {ReactNode, Ref} from 'react'
 import type {IconName} from '../../atoms/icon'
 
 type NavigationBarItemBase = {
+  /** Called when the item is pressed. */
   onPress: () => void
   /**
    * iOS 26: neighbouring items on one side share a glass capsule; this gives the item its own. A close next to
@@ -29,10 +30,15 @@ export type NavigationBarSearchRef = {
 
 /** A search field in place of the title — iOS only for now; Android keeps the title. */
 export type NavigationBarSearch = {
+  /** Every edit of the field's text. */
   onChangeText: (text: string) => void
+  /** The field gained or lost focus. */
   onFocusChange?: (focused: boolean) => void
+  /** Shown while the field is empty. */
   placeholder: string
+  /** Imperative `clear`. */
   ref?: Ref<NavigationBarSearchRef>
+  /** Test identifier, forwarded to the native search field. */
   testID?: string
 }
 
@@ -52,7 +58,9 @@ export type NavigationBarProps = {
   leadingItems?: NavigationBarItem[]
   /** Replaces the title with a search field (iOS). */
   search?: NavigationBarSearch
+  /** Test identifier, forwarded to the native bar. iOS only — Android ignores it. */
   testID?: string
+  /** The bar's title. */
   title?: string
   /** `center` by default — iOS's own; `leading` is Material's top app bar. */
   titleAlignment?: NavigationBarTitleAlignment

package/src/molecules/pager/pager.android.tsx

@@ -4,15 +4,17 @@ import {spacing} from '@hzblj/kara-theme'
 import {Children, useCallback, useEffect, useMemo, useRef, useState} from 'react'
 
 import {HStack} from '../../atoms/h-stack'
+import {Spacer} from '../../atoms/spacer'
 import {VStack} from '../../atoms/v-stack'
 import {useHostGuard} from '../../host-context'
 import type {PagerComponent, PagerProps} from './pager.types'
 
 const DOT_SIZE = 6
 
-/** Compose ships no page indicator, so the dots are composed out of atoms. */
+/** Compose ships no page indicator, so the dots are composed out of atoms — centred between two spacers. */
 const PagerDots = ({count, current}: {count: number; current: number}) => (
   <HStack align="center" py="s12" spacing="s6" wide>
+    <Spacer />
     {Array.from({length: count}, (_, index) => (
       <VStack
         bg={index === current ? 'content.primary' : 'fill.tertiary'}
@@ -22,6 +24,7 @@ const PagerDots = ({count, current}: {count: number; current: number}) => (
         w={DOT_SIZE}
       />
     ))}
+    <Spacer />
   </HStack>
 )
 

package/src/molecules/pager/pager.types.ts

@@ -11,6 +11,7 @@ import type {ReactNode} from 'react'
  * ceremony would buy nothing.
  */
 export type PagerProps = {
+  /** The pages, one per child, in order. */
   children?: ReactNode
   /**
    * Page dots. iOS draws SwiftUI's own, over the bottom edge; Compose has no built-in indicator, so
@@ -28,6 +29,7 @@ export type PagerProps = {
    * content down with the swipe, so iOS always stays swipeable.
    */
   scrollEnabled?: boolean
+  /** Test identifier, forwarded to the native view. */
   testID?: string
 }
 

package/src/molecules/radio-group/radio-group.types.ts

@@ -1,13 +1,23 @@
 import type {ReactNode} from 'react'
 
+/** One choice of a `RadioGroup`. */
 export type RadioOption = {
+  /** The option's text. */
   label: string
+  /** Identifies the option to `value` and `onValueChange`, and keys its row — keep it unique. */
   value: string
 }
 
+/**
+ * A single choice from a list: rows with a checkmark on the selected one on iOS, Material radio buttons on Android. A
+ * native atom — it renders inside `<Screen>` or `<Island>`.
+ */
 export type RadioGroupProps = {
+  /** The user pressed an option; it passes that option's `value`. */
   onValueChange?: (value: string) => void
+  /** The choices, top to bottom. */
   options: RadioOption[]
+  /** The selected option's `value`. Update it from `onValueChange`. */
   value: string
 }
 

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

@@ -4,7 +4,7 @@ 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
+ * would cost too much to mount (a navigation list, an `RnFlatList` 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.
  */

package/src/molecules/rn-tooltip/rn-tooltip.types.ts

@@ -2,8 +2,11 @@ import type {ReactElement, ReactNode} from 'react'
 
 export type RnTooltipActionVariant = 'link' | 'primary' | 'secondary'
 
+/** A button in an `RnTooltip`. */
 export type RnTooltipAction = {
+  /** The button's text. */
   label: string
+  /** Called on press. The tooltip stays up — turn `visible` off here if the action should close it. */
   onPress: () => void
   /** `link` by default — an underlined text. `primary`/`secondary` are small filled/outlined buttons. */
   variant?: RnTooltipActionVariant
@@ -18,6 +21,7 @@ export type RnTooltipDismissReason = 'anchorHidden' | 'outside'
  * Native tier, unlike `Tooltip`, whose anchor is a native view inside a host.
  */
 export type RnTooltipProps = {
+  /** A row of buttons under the text, in order. */
   actions?: RnTooltipAction[]
   /** Which end of the bubble the actions sit at. `end` by default. */
   actionsAlignment?: 'end' | 'start'
@@ -28,11 +32,18 @@ export type RnTooltipProps = {
   boundaryInsets?: {bottom?: number; top?: number}
   /** The anchor — a single React Native view. */
   children: ReactElement
+  /** The body text, under the title. */
   message?: string
+  /**
+   * Asks for the tooltip to close, with the reason — turn `visible` off. On Android any touch outside asks, the start
+   * of a scroll included; iOS keeps the tooltip through a scroll.
+   */
   onDismiss: (reason: RnTooltipDismissReason) => void
   /** The appear animation finished. */
   onShown?: () => void
+  /** The heading line, above the message. */
   title?: string
+  /** Shows the tooltip while true. It never hides itself. */
   visible: boolean
 }
 

package/src/molecules/scroll-edge-container/scroll-edge-container.android.tsx

@@ -1,9 +1,49 @@
-import {Box} from '../../atoms/box'
+import {duration, opacity} from '@hzblj/kara-theme'
+import {cloneElement, type ReactNode, useCallback, useRef} from 'react'
+import type {LayoutChangeEvent, NativeScrollEvent, NativeSyntheticEvent} from 'react-native'
+import {type SharedValue, useAnimatedStyle, useSharedValue, withTiming} from 'react-native-reanimated'
+
+import {ABox, Box} from '../../atoms/box'
 import type {ScrollEdgeContainerComponent, ScrollEdgeContainerProps} from './scroll-edge-container.types'
 
+/** Less than a pixel scrolled is not scrolled — a fling settles a fraction away from the edge. */
+const EDGE_SLOP = 0.5
+
+const FILL = {duration: duration.d200}
+
+type Bar = {children: ReactNode; filled: SharedValue<number>}
+
+/** A bar, and behind it the container colour it fills with — faded in and out, not switched. */
+const EdgeBar = ({children, filled}: Bar) => {
+  const fill = useAnimatedStyle(() => ({opacity: filled.value}), [])
+
+  if (!children) {
+    return null
+  }
+
+  return (
+    <Box>
+      <ABox
+        bg="surface.secondary"
+        bottom={0}
+        left={0}
+        pointerEvents="none"
+        position="absolute"
+        right={0}
+        style={fill}
+        top={0}
+      />
+      {children}
+    </Box>
+  )
+}
+
 /**
- * Android has no scroll edge effect, and a React Native scroll view there has no `contentInset` to slide content under
- * a bar with — so the bars stack above and below the scroll view instead of over it. Give them a background.
+ * Material's take on the scroll edge: a React Native scroll view has no `contentInset` to slide content under a bar on
+ * Android, so the bars stack above and below it, and do what a Material top app bar does on scroll — transparent at
+ * rest, filled with `surface.secondary` (the scrolled container colour, `surfaceContainer`) once content has scrolled
+ * under it. The bottom bar mirrors it: filled while there is more content below. The scroll view keeps its own
+ * `onScroll`, `onLayout` and `onContentSizeChange`.
  */
 export const ScrollEdgeContainer: ScrollEdgeContainerComponent = ({
   automaticInsets: _automaticInsets,
@@ -13,10 +53,63 @@ export const ScrollEdgeContainer: ScrollEdgeContainerComponent = ({
   testID,
   topBar,
   ...sx
-}: ScrollEdgeContainerProps) => (
-  <Box {...sx} testID={testID}>
-    {topBar}
-    <Box flex={1}>{children}</Box>
-    {bottomBar}
-  </Box>
-)
+}: ScrollEdgeContainerProps) => {
+  const topFilled = useSharedValue<number>(opacity.o0)
+  const bottomFilled = useSharedValue<number>(opacity.o0)
+  const metrics = useRef({content: 0, offset: 0, viewport: 0})
+  const state = useRef({bottom: false, top: false})
+  const {flex, onContentSizeChange, onLayout, onScroll, scrollEventThrottle} = children.props as {
+    flex?: number
+    onContentSizeChange?: (width: number, height: number) => void
+    onLayout?: (event: LayoutChangeEvent) => void
+    onScroll?: (event: NativeSyntheticEvent<NativeScrollEvent>) => void
+    scrollEventThrottle?: number
+  }
+
+  // Only a change of state animates; a scroll event restating the same one would restart the fade.
+  const update = useCallback(() => {
+    const {content, offset, viewport} = metrics.current
+    const top = offset > EDGE_SLOP
+    const bottom = viewport > 0 && offset + viewport < content - EDGE_SLOP
+
+    if (top !== state.current.top) {
+      state.current.top = top
+      topFilled.value = withTiming(top ? opacity.o100 : opacity.o0, FILL)
+    }
+
+    if (bottom !== state.current.bottom) {
+      state.current.bottom = bottom
+      bottomFilled.value = withTiming(bottom ? opacity.o100 : opacity.o0, FILL)
+    }
+  }, [bottomFilled, topFilled])
+
+  // `flex` so the scroll view takes the room between the bars — left to its content, it grew to the content's height,
+  // ran under the bottom bar and had nothing to scroll.
+  const scrollable = cloneElement(children, {
+    flex: flex ?? 1,
+    onContentSizeChange: (width: number, height: number) => {
+      metrics.current.content = height
+      update()
+      onContentSizeChange?.(width, height)
+    },
+    onLayout: (event: LayoutChangeEvent) => {
+      metrics.current.viewport = event.nativeEvent.layout.height
+      update()
+      onLayout?.(event)
+    },
+    onScroll: (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      metrics.current.offset = event.nativeEvent.contentOffset.y
+      update()
+      onScroll?.(event)
+    },
+    scrollEventThrottle: scrollEventThrottle ?? 16,
+  } as Partial<typeof children.props>)
+
+  return (
+    <Box {...sx} testID={testID}>
+      <EdgeBar filled={topFilled}>{topBar}</EdgeBar>
+      <Box flex={1}>{scrollable}</Box>
+      <EdgeBar filled={bottomFilled}>{bottomBar}</EdgeBar>
+    </Box>
+  )
+}

package/src/molecules/scroll-edge-container/scroll-edge-container.types.ts

@@ -5,8 +5,10 @@ import type {ReactElement, ReactNode} from 'react'
 export type {ScrollEdgeEffect, ScrollEdgeScrollableProps} from '@hzblj/kara-native/swift-ui'
 
 /**
- * Bars over one React Native scroll view, with the iOS 26 scroll edge effect under them — the system's progressive
- * blur where content scrolls past a bar. The React Native tier: it needs no host.
+ * Bars over one React Native scroll view, with each platform's scroll edge under them — on iOS 26 the system's
+ * progressive blur where content scrolls past a bar; on Android a Material top app bar's behaviour, the bars stacked
+ * around the scroll view and filling with `surface.secondary` once content scrolls under them. The React Native tier:
+ * it needs no host.
  *
  * A screen-level container: wrap the screen's scroll view with it. Mounted inside a cell of a virtualized list on iOS
  * it draws only its bottom bar — the hosted scroll view and the top bar stay blank.
@@ -17,12 +19,15 @@ export type ScrollEdgeContainerProps = ResponsiveViewSx & {
    * content begins below the top bar and scrolls under it. On by default.
    */
   automaticInsets?: boolean
+  /** Laid over the scroll view's bottom edge on iOS; stacked below it on Android, filled while content continues below. */
   bottomBar?: ReactNode
   /** Exactly one React Native scroll view — `RnScrollView`, `RnFlatList`, `RnSectionList`. */
   children: ReactElement<ScrollEdgeScrollableProps>
   /** iOS 26: how hard the edge cuts. `soft` by default. */
   effect?: ScrollEdgeEffect
+  /** Test identifier, forwarded to the container view. */
   testID?: string
+  /** Laid over the scroll view's top edge on iOS; stacked above it on Android, filled once content scrolls under it. */
   topBar?: ReactNode
 }
 

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

@@ -1,5 +1,5 @@
 import {useAppTheme} from '@hzblj/kara-theme'
-import {TextInput} from 'react-native'
+import {Platform, TextInput} from 'react-native'
 
 import {Box} from '../../atoms/box'
 import {Pressable} from '../../atoms/pressable'
@@ -13,6 +13,13 @@ export const SearchBar: SearchBarComponent = ({
   value,
 }: SearchBarProps) => {
   const theme = useAppTheme()
+  const {lineHeight, ...face} = theme.typography.body
+  /**
+   * A single-line `UITextField` sets its text against the bottom of a line taller than the font, so the variant's
+   * `lineHeight` pushed the text below the magnifier beside it. iOS takes the face without it, in a field as tall as
+   * the line would have been; Android centres the line and keeps it.
+   */
+  const text = Platform.OS === 'ios' ? {...face, height: lineHeight} : theme.typography.body
 
   return (
     <Box
@@ -31,7 +38,7 @@ export const SearchBar: SearchBarComponent = ({
         onChangeText={onChangeText}
         placeholder={placeholder}
         placeholderTextColor={theme.color('content.quaternary')}
-        style={[theme.typography.body, {color: theme.color('content.primary'), flex: 1, padding: 0}]}
+        style={[text, {color: theme.color('content.primary'), flex: 1, padding: 0}]}
         value={value}
       />
       {value.length > 0 ? (

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

@@ -1,9 +1,17 @@
 import type {ReactNode} from 'react'
 
+/**
+ * A search field drawn the same on both platforms — a rounded box with a magnifier, a `TextInput` and a clear button
+ * while there is text. The React Native tier: it needs no host.
+ */
 export type SearchBarProps = {
+  /** Every edit, and `''` when the clear button is pressed. */
   onChangeText?: (text: string) => void
+  /** Shown while the field is empty. `Search` by default. */
   placeholder?: string
+  /** Test identifier, put on the field's container view rather than on the `TextInput`. */
   testID?: string
+  /** The field's text. Controlled — pass back what `onChangeText` reports. */
   value: string
 }
 

package/src/molecules/stepper/stepper.ios.tsx

@@ -1,10 +1,46 @@
 import {Stepper as SwiftUIStepper} from '@expo/ui/swift-ui'
+import {labelsHidden} from '@expo/ui/swift-ui/modifiers'
+import {useRef} from 'react'
 
+import {HStack} from '../../atoms/h-stack'
+import {Spacer} from '../../atoms/spacer'
+import {Text} from '../../atoms/text'
 import {useHostGuard} from '../../host-context'
 import type {StepperComponent, StepperProps} from './stepper.types'
 
+/** The label stays VoiceOver's, on the control; on screen it is the row's own text. */
+const LABEL_HIDDEN = [labelsHidden()]
+
+/**
+ * SwiftUI's `Stepper` at the end of a row, the label leading and the value just before the control — the way iOS's own
+ * settings show a stepped value. The value rolls to the next one (`numericText`), up or down with the change, in
+ * monospaced digits so the row does not jump.
+ */
 export const Stepper: StepperComponent = ({label, max, min, onValueChange, step = 1, value}: StepperProps) => {
   useHostGuard('Stepper')
+  const previous = useRef(value)
+  const countsDown = value < previous.current
+  previous.current = value
 
-  return <SwiftUIStepper label={label} max={max} min={min} onValueChange={onValueChange} step={step} value={value} />
+  return (
+    <HStack align="center" spacing="s12" wide>
+      <Text>{label}</Text>
+      <Spacer />
+      <Text
+        color="content.secondary"
+        ios={{animation: {value}, contentTransition: {countsDown, type: 'numericText'}, monospacedDigit: true}}
+      >
+        {String(value)}
+      </Text>
+      <SwiftUIStepper
+        label={label}
+        max={max}
+        min={min}
+        modifiers={LABEL_HIDDEN}
+        onValueChange={onValueChange}
+        step={step}
+        value={value}
+      />
+    </HStack>
+  )
 }