@hzblj/kara-components 0.5.0 → 0.7.0

package/src/atoms/checkbox/checkbox.android.tsx

@@ -6,9 +6,13 @@ import {useMemo} from 'react'
 import {useHostGuard} from '../../host-context'
 import type {CheckboxComponent, CheckboxProps} from './checkbox.types'
 
+/** Stands in for a missing handler: Material drops its 48dp touch target without one, and the box moves. */
+const NOOP = () => undefined
+
 /**
- * Material's checkbox, tinted with the accent. With a label it is a full-width row that toggles as a whole; the gap is
- * explicit because a checkbox without a handler drops Material's 48dp touch target, and with it the space around it.
+ * Material's checkbox, tinted with the accent. With a label it is a full-width row that toggles as a whole. It always
+ * gets a handler, so a disabled or read-only box keeps the touch target an enabled one has, and lines up with it;
+ * `enabled` is what stops the input.
  */
 export const Checkbox: CheckboxComponent = ({disabled = false, label, onValueChange, value}: CheckboxProps) => {
   useHostGuard('Checkbox')
@@ -21,7 +25,7 @@ export const Checkbox: CheckboxComponent = ({disabled = false, label, onValueCha
     <ComposeCheckbox
       colors={{checkedColor: theme.color('fill.accent.primary'), checkmarkColor: theme.color('content.on.bg')}}
       enabled={!disabled}
-      onCheckedChange={onValueChange}
+      onCheckedChange={onValueChange ?? NOOP}
       value={value}
     />
   )

package/src/atoms/checkbox/checkbox.types.ts

@@ -1,9 +1,14 @@
 import type {ReactNode} from 'react'
 
+/** Material's `Checkbox` on Android. iOS has none, so there it is a SwiftUI `Toggle` — the same switch as `Switch`. */
 export type CheckboxProps = {
+  /** Dims the control and ignores taps. */
   disabled?: boolean
+  /** Text beside the control. On Android the whole labelled row toggles it. */
   label?: string
+  /** Called with the new value when the user toggles it. */
   onValueChange?: (value: boolean) => void
+  /** Whether it is checked. Controlled — update it from `onValueChange`. */
   value: boolean
 }
 

package/src/atoms/chip/chip.tsx

@@ -9,7 +9,7 @@ export const Chip: ChipComponent = ({label, onPress, selected = false, testID}:
     borderColor={selected ? 'border.accent' : 'border.tertiary'}
     borderRadius="full"
     borderWidth={1}
-    haptic
+    haptic="selection"
     justify="center"
     onPress={onPress}
     px="s12"

package/src/atoms/chip/chip.types.ts

@@ -1,9 +1,14 @@
 import type {ReactNode} from 'react'
 
+/** A filter pill on a `Pressable`, not a native control — the React Native tier, so it needs no host. */
 export type ChipProps = {
+  /** The text in the pill. */
   label: string
+  /** Called when the chip is pressed, with the `selection` haptic. */
   onPress?: () => void
+  /** Draws the chip in the accent colours. Off by default. */
   selected?: boolean
+  /** Test identifier, forwarded to the view. */
   testID?: string
 }
 

package/src/atoms/color-picker/color-picker.types.ts

@@ -5,9 +5,13 @@ import type {ReactNode} from 'react'
  * renders nothing and says so in dev. Branch on `Platform.OS` if the screen needs a fallback.
  */
 export type ColorPickerProps = {
+  /** Text beside the colour well. */
   label?: string
+  /** Called with the colour the user picks. */
   onValueChange?: (color: string) => void
+  /** Lets the user pick an opacity as well. Off by default. */
   supportsOpacity?: boolean
+  /** Test identifier, forwarded to the native view. */
   testID?: string
   /** `#RRGGBB` or `#RRGGBBAA`. */
   value: string | null

package/src/atoms/date-picker/date-picker.ios.tsx

@@ -1,9 +1,22 @@
-import {DateTimePicker} from '@expo/ui/community/datetime-picker'
-import {useCallback} from 'react'
+import {Host, DatePicker as SwiftUIDatePicker} from '@expo/ui/swift-ui'
+import {datePickerStyle, labelsHidden, tint} from '@expo/ui/swift-ui/modifiers'
+import {useAppTheme} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
 
-import type {DatePickerComponent, DatePickerProps} from './date-picker.types'
+import type {DatePickerComponent, DatePickerMode, DatePickerProps} from './date-picker.types'
 
-/** The system's compact date picker, inline: a tap on it opens the calendar popover UIKit owns. */
+const COMPONENTS = {
+  date: ['date'],
+  datetime: ['date', 'hourAndMinute'],
+  time: ['hourAndMinute'],
+} as const satisfies Record<DatePickerMode, ('date' | 'hourAndMinute')[]>
+
+/**
+ * The system's compact date picker: the value in a pill, and a tap on it opens the calendar popover UIKit owns. Its own
+ * host, sized to the pill on both axes — a host that took the width it was given would lay the pill out against the
+ * far edge of it, or past its container's — so it drops into a row the way a `Text` does. The label is the caller's,
+ * beside it; the calendar is in the accent.
+ */
 export const DatePicker: DatePickerComponent = ({
   max,
   min,
@@ -12,16 +25,23 @@ export const DatePicker: DatePickerComponent = ({
   testID,
   value,
 }: DatePickerProps) => {
-  const onChange = useCallback((_event: unknown, date: Date) => onValueChange?.(date), [onValueChange])
+  const theme = useAppTheme()
+
+  const modifiers = useMemo(
+    () => [datePickerStyle('compact'), labelsHidden(), tint(theme.color('fill.accent.primary'))],
+    [theme]
+  )
 
   return (
-    <DateTimePicker
-      maximumDate={max}
-      minimumDate={min}
-      mode={mode}
-      onValueChange={onChange}
-      testID={testID}
-      value={value}
-    />
+    <Host colorScheme={theme.dark ? 'dark' : 'light'} matchContents>
+      <SwiftUIDatePicker
+        displayedComponents={[...COMPONENTS[mode]]}
+        modifiers={modifiers}
+        onDateChange={onValueChange}
+        range={min || max ? {end: max, start: min} : undefined}
+        selection={value}
+        testID={testID}
+      />
+    </Host>
   )
 }

package/src/atoms/date-picker/date-picker.types.ts

@@ -2,12 +2,26 @@ import type {ReactNode} from 'react'
 
 export type DatePickerMode = 'date' | 'datetime' | 'time'
 
+/**
+ * A date or time picker — SwiftUI's compact `DatePicker` on iOS, a field that opens Material's picker dialog on a tap
+ * on Android. The React Native tier: it brings its own host and sizes itself to the value, so it sits in a row beside
+ * its label like a `Text`.
+ */
 export type DatePickerProps = {
+  /** The latest date that can be picked. Android ignores it in `time` mode. */
   max?: Date
+  /** The earliest date that can be picked. Android ignores it in `time` mode. */
   min?: Date
+  /**
+   * What it picks. `date` by default. Android has no combined dialog, so there `datetime` picks the date and keeps
+   * `value`'s time of day.
+   */
   mode?: DatePickerMode
+  /** Called with the new date — on iOS as it changes, on Android when the dialog is confirmed. */
   onValueChange?: (date: Date) => void
+  /** Test identifier — on the native picker on iOS, on the tappable field on Android. */
   testID?: string
+  /** The selected date. Controlled — update it from `onValueChange`. */
   value: Date
 }
 

package/src/atoms/divider/divider.types.ts

@@ -1,8 +1,11 @@
 import type {ColorToken} from '@hzblj/kara-theme'
 import type {ReactNode} from 'react'
 
+/** A horizontal hairline — SwiftUI `Divider` / Compose `HorizontalDivider`. */
 export type DividerProps = {
+  /** The line's colour. `border.tertiary` by default. */
   color?: ColorToken
+  /** Test identifier, forwarded to the native view on iOS — Android ignores it. */
   testID?: string
 }
 

package/src/atoms/fab/fab.types.ts

@@ -2,9 +2,16 @@ import type {ReactNode} from 'react'
 
 import type {IconName} from '../icon'
 
+/**
+ * A floating action button — Material's `FloatingActionButton` on Android, a 56pt accent circle (a plain SwiftUI
+ * `Button`) on iOS. It renders inline; pinning it to a corner is up to the screen.
+ */
 export type FabProps = {
+  /** The icon, one of the app's, drawn in `content.on.bg`. */
   name: IconName
+  /** Called when the button is pressed. */
   onPress?: () => void
+  /** Test identifier, forwarded to the native view on iOS — Android ignores it. */
   testID?: string
 }
 

package/src/atoms/glass-view/glass-view.types.ts

@@ -12,6 +12,7 @@ export type GlassViewProps = ResponsiveViewSx & {
   children?: ReactNode
   /** Swells toward the finger on touch, carrying the children with it. Wrap the view in a `Pressable` for the press. */
   interactive?: boolean
+  /** Test identifier, forwarded to the view. */
   testID?: string
   /** Tints the material. Unset leaves it clear. */
   tint?: ColorToken

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

@@ -4,11 +4,17 @@ import type {ReactNode} from 'react'
 
 export type HStackAlign = 'center' | 'end' | 'start'
 
+/** A horizontal stack — SwiftUI `HStack` / Compose `Row`. */
 export type HStackProps = ResponsiveSx & {
+  /** How the children line up vertically — `start` is the top, `end` the bottom. `start` by default. */
   align?: HStackAlign
+  /** Native views, laid out from the leading edge. */
   children?: ReactNode
+  /** Makes the stack pressable — a tap gesture on iOS, a `clickable` with Material's ripple on Android. */
   onPress?: () => void
+  /** The gap between children. Unset, SwiftUI puts its default spacing between them and Compose none. */
   spacing?: SpaceSize
+  /** Test identifier, forwarded to the native view. */
   testID?: string
 }
 

package/src/atoms/icon/icon.types.ts

@@ -18,12 +18,20 @@ type DeclaredIconName = keyof KaraIcons & string
  */
 export type IconName = [DeclaredIconName] extends [never] ? string : DeclaredIconName
 
+/**
+ * One of the app's icons, in a host — SwiftUI `Image` from the asset catalog on iOS, Material's `Icon` with the vector
+ * drawable on Android. `RnIcon` draws the same asset outside one.
+ */
 export type IconProps = {
   /** What a screen reader says. Unset, the icon is decorative and hidden from it. */
   accessibilityLabel?: string
+  /** The icon's tint. `content.primary` by default. */
   color?: ColorToken
+  /** Which of the app's icons — a key of `KaraIcons`. */
   name: IconName
+  /** Its width and height, a spacing token. `s24` by default. */
   size?: SpaceSize
+  /** Test identifier, forwarded to the native view on iOS — Android ignores it. */
   testID?: string
 }
 

package/src/atoms/icon-button/icon-button.types.ts

@@ -2,10 +2,15 @@ import type {ReactNode} from 'react'
 
 import type {IconName} from '../icon'
 
+/** A button that is just an icon — a plain SwiftUI `Button` on iOS, Material's `IconButton` on Android. */
 export type IconButtonProps = {
+  /** Draws the icon in `btn.content.disabled` and stops the button responding to presses. */
   disabled?: boolean
+  /** The icon, one of the app's. */
   name: IconName
+  /** Called when the button is pressed. */
   onPress?: () => void
+  /** Test identifier, forwarded to the native view on iOS — Android ignores it. */
   testID?: string
 }
 

package/src/atoms/index.ts

@@ -10,7 +10,6 @@ export * from './color-picker'
 export * from './date-picker'
 export * from './divider'
 export * from './fab'
-export * from './flash-list'
 export * from './glass-view'
 export * from './h-stack'
 export * from './icon'

package/src/atoms/island/island.types.ts

@@ -1,7 +1,9 @@
 import type {ReactNode} from 'react'
 import type {StyleProp, ViewStyle} from 'react-native'
 
+/** A host for native atoms in a React Native layout — the SwiftUI / Compose `Host` an `@expo/ui` tree mounts into. */
 export type IslandProps = {
+  /** The native views it hosts. */
   children?: ReactNode
   /**
    * Sizes the island's height to its native content while the width still comes from the parent, which
@@ -15,7 +17,9 @@ export type IslandProps = {
    * hangs the main thread as soon as the views lay out on screen.
    */
   matchContents?: boolean
+  /** A React Native style for the host view — its size and placement. It needs a height when `matchContents` is off. */
   style?: StyleProp<ViewStyle>
+  /** Test identifier, forwarded to the host view on iOS — Android ignores it. */
   testID?: string
 }
 

package/src/atoms/list/list.types.ts

@@ -10,12 +10,14 @@ import type {ReactNode} from 'react'
  * the children is one too many: on iOS it becomes an empty row of its own.
  */
 export type ListProps = {
+  /** The rows — native views, one row each. */
   children: ReactNode
   /**
    * Enables pull-to-refresh. Async on purpose — see `ScrollViewProps.onRefresh`: the spinner runs
    * until the promise settles, so neither platform needs a `refreshing` flag kept in sync by hand.
    */
   onRefresh?: () => Promise<void>
+  /** Test identifier, forwarded to the native view on iOS — Android ignores it. */
   testID?: string
 }
 

package/src/atoms/picker/picker.types.ts

@@ -1,15 +1,27 @@
 import type {ReactNode} from 'react'
 
+/** One choice of a `Picker`. */
 export type PickerOption = {
+  /** What the user reads. */
   label: string
+  /** What `onValueChange` reports. It also keys the option, so it must be unique. */
   value: string
 }
 
+/**
+ * A single choice from a list — a SwiftUI wheel picker on iOS, Material's exposed dropdown on Android. It brings its
+ * own host, so it renders outside `Screen` and `Island` as well.
+ */
 export type PickerProps = {
+  /** Stops the user changing the selection, and dims the picker. */
   disabled?: boolean
+  /** Called with the chosen option's `value`. */
   onValueChange?: (value: string) => void
+  /** The choices, in order. */
   options: PickerOption[]
+  /** Android: the dropdown field's test tag. iOS: `@expo/ui`'s wheel picker drops it. */
   testID?: string
+  /** The selected option's `value`. Controlled: pass back what `onValueChange` reports. */
   value: string
 }
 

package/src/atoms/pressable/pressable.tsx

@@ -1,8 +1,9 @@
 import {useSplitSx} from '@hzblj/kara-sx'
-import * as Haptics from 'expo-haptics'
 import {useCallback} from 'react'
 import {Pressable as RNPressable} from 'react-native'
 import Animated, {useAnimatedStyle, useSharedValue, withSpring} from 'react-native-reanimated'
+
+import {haptics} from '../../haptics'
 import type {PressableComponent, PressableProps} from './pressable.types'
 
 const SPRING = {damping: 20, stiffness: 400}
@@ -19,24 +20,30 @@ export const Pressable: PressableComponent = ({
 }: PressableProps) => {
   const [resolved, rest] = useSplitSx(props)
   const scale = useSharedValue(1)
+  const feedback = haptic === true ? 'light' : haptic || undefined
 
   const rStyle = useAnimatedStyle(() => ({transform: [{scale: scale.value}]}), [])
 
+  // The finger is down: the Taptic Engine has until the release to wake, so the haptic lands with the press.
   const onPressIn = useCallback(() => {
     scale.value = withSpring(0.96, SPRING)
-  }, [scale])
+
+    if (feedback) {
+      haptics.prepare(feedback)
+    }
+  }, [feedback, scale])
 
   const onPressOut = useCallback(() => {
     scale.value = withSpring(1, SPRING)
   }, [scale])
 
   const onPressWithHaptic = useCallback(() => {
-    if (haptic) {
-      Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light).catch(() => undefined)
+    if (feedback) {
+      haptics.play(feedback)
     }
 
     onPress?.()
-  }, [haptic, onPress])
+  }, [feedback, onPress])
 
   return (
     <AnimatedPressable

package/src/atoms/pressable/pressable.types.ts

@@ -1,11 +1,22 @@
 import type {ResponsiveViewSx} from '@hzblj/kara-sx'
 import type {ReactNode} from 'react'
 
+import type {Haptic} from '../../haptics'
+
+/**
+ * React Native's `Pressable`, styled through `sx` like a `Box`: it springs down to 96% while pressed and takes
+ * touches 8 points past its edges. The React Native tier — it needs no host.
+ */
 export type PressableProps = ResponsiveViewSx & {
+  /** The pressable content. */
   children?: ReactNode
+  /** Ignores presses — no `onPress`, no haptic, no spring. */
   disabled?: boolean
-  haptic?: boolean
+  /** Played on press. `true` is a `light` impact; a name picks the haptic, e.g. `selection` for a choice. */
+  haptic?: boolean | Haptic
+  /** Called when the press is released, after the `haptic` plays. */
   onPress?: () => void
+  /** Test identifier, forwarded to the view. */
   testID?: string
 }
 

package/src/atoms/progress/progress.types.ts

@@ -1,7 +1,13 @@
 import type {ReactNode} from 'react'
 
+/**
+ * A progress bar or ring, tinted `fill.accent.primary` — SwiftUI `ProgressView` / Compose's
+ * `LinearProgressIndicator` and `CircularProgressIndicator`.
+ */
 export type ProgressProps = {
+  /** A circular indicator instead of a bar. Off by default. */
   circular?: boolean
+  /** Between `0` and `1`. Leave it unset for an indeterminate indicator. */
   value?: number
 }
 

package/src/atoms/rn-flat-list/rn-flat-list.tsx

@@ -7,14 +7,11 @@ import type {RnFlatListProps} from './rn-flat-list.types'
 const NO_SX = {}
 
 /**
- * Flat list built on React Native's own `VirtualizedList` rather than FlashList.
- *
- * FlashList is the default for lists in this codebase and should stay that way for data rows — reach
- * for this only for the case it cannot serve: content that hosts native views. FlashList positions its
- * rows absolutely and recycles their cells, and an `@expo/ui` host survives neither — the hosted view
- * ends up drawn where the layout no longer is. `VirtualizedList` renders its cells in normal flow
- * inside a scroll view, using blank spacers for the range it has not rendered, so a hosted view stays
- * exactly where the layout put it. This is `SectionList`'s reason to exist too, without the sections.
+ * kara's list for React Native content: React Native's own `VirtualizedList`, styled through `sx`. It renders its
+ * cells in normal flow inside a scroll view, with blank spacers for the range it has not rendered, so a row that hosts
+ * native views keeps them where the layout put it. A recycling list (absolutely positioned, reused cells) cannot
+ * promise that — an `@expo/ui` host survives neither, and draws where the layout no longer is — which is why kara
+ * ships none.
  */
 export const RnFlatList = <TItem,>({content, data, renderItem, ...props}: RnFlatListProps<TItem>) => {
   const [style, rest] = useSplitSx(props as Record<string, unknown>)
@@ -23,6 +20,9 @@ export const RnFlatList = <TItem,>({content, data, renderItem, ...props}: RnFlat
   return (
     <RNFlatList<TItem>
       data={data}
+      // Android clips by default, and a host is measured after its first layout — at zero height it counts as
+      // off-screen, is detached, and its native view never comes back.
+      removeClippedSubviews={false}
       renderItem={renderItem}
       {...rest}
       contentContainerStyle={content === undefined ? undefined : contentStyle}

package/src/atoms/rn-flat-list/rn-flat-list.types.ts

@@ -3,9 +3,11 @@ import type {FlatListProps as RNFlatListProps} from 'react-native'
 
 /**
  * Top-level `sx` styles the viewport; `content` styles the scrolling content container, so padding and
- * gap belong there — the same split as `RnScrollView`.
+ * gap belong there — the same split as `RnScrollView`. `removeClippedSubviews` is off unless you turn it on:
+ * Android's default would detach a row's host before it has measured itself, and the row would stay empty.
  */
 export type RnFlatListProps<TItem> = ResponsiveViewSx &
   Omit<RNFlatListProps<TItem>, 'contentContainerStyle' | 'style'> & {
+    /** Styles the scrolling content container — padding and gap belong here. */
     content?: ResponsiveViewSx
   }

package/src/atoms/rn-scroll-view/rn-scroll-view.types.ts

@@ -13,9 +13,13 @@ import type {ScrollViewAxis} from '../scroll-view'
  */
 export type RnScrollViewProps = ResponsiveViewSx &
   Omit<RNScrollViewProps, 'contentContainerStyle' | 'horizontal' | 'style'> & {
+    /** The scroll direction. `vertical` by default. */
     axis?: ScrollViewAxis
+    /** The scrolling content. */
     children?: ReactNode
+    /** Styles the scrolling content container — padding and gap belong here. */
     content?: ResponsiveViewSx
+    /** Shows the scroll indicators. On by default. */
     showsIndicators?: boolean
   }
 

package/src/atoms/rn-section-list/rn-section-list.tsx

@@ -7,14 +7,8 @@ import type {RnSectionListProps} from './rn-section-list.types'
 const NO_SX = {}
 
 /**
- * Sectioned list built on React Native's own `VirtualizedList` rather than FlashList.
- *
- * FlashList is the default for lists in this codebase and should stay that way for data rows. This
- * exists for the case it cannot serve: content that hosts native views. FlashList positions its rows
- * absolutely and recycles their cells, and an `@expo/ui` host does not survive either — the hosted
- * view ends up drawn where the layout no longer is. `VirtualizedList` renders its cells in normal flow
- * inside a scroll view, using blank spacers for the range it has not rendered, so a hosted view stays
- * exactly where the layout put it.
+ * `RnFlatList` with sections: React Native's own `VirtualizedList`, cells in normal flow inside a scroll view, so a
+ * row that hosts native views keeps them where the layout put it.
  *
  * Sticky headers default off, unlike React Native, where they are on for vertical lists. A header that
  * detaches and floats over the content is a deliberate effect, not something a list should do unasked.
@@ -30,6 +24,9 @@ export const RnSectionList = <TItem, TSection = DefaultSectionT>({
 
   return (
     <RNSectionList<TItem, TSection>
+      // Android clips by default, and a host is measured after its first layout — at zero height it counts as
+      // off-screen, is detached, and its native view never comes back.
+      removeClippedSubviews={false}
       sections={sections}
       {...rest}
       contentContainerStyle={content === undefined ? undefined : contentStyle}

package/src/atoms/rn-section-list/rn-section-list.types.ts

@@ -3,9 +3,11 @@ import type {DefaultSectionT, SectionListProps as RNSectionListProps} from 'reac
 
 /**
  * Top-level `sx` styles the viewport; `content` styles the scrolling content container, so padding and
- * gap belong there — the same split as `RnScrollView` and `RnFlatList`.
+ * gap belong there — the same split as `RnScrollView` and `RnFlatList`. `removeClippedSubviews` is off unless
+ * you turn it on, as in `RnFlatList`: Android's default would leave rows with hosts in them empty.
  */
 export type RnSectionListProps<TItem, TSection = DefaultSectionT> = ResponsiveViewSx &
   Omit<RNSectionListProps<TItem, TSection>, 'contentContainerStyle' | 'style'> & {
+    /** Styles the scrolling content container — padding and gap belong here. */
     content?: ResponsiveViewSx
   }

package/src/atoms/rn-text/rn-text.types.ts

@@ -2,9 +2,13 @@ import type {ColorToken, TextVariant} from '@hzblj/kara-theme'
 import type {ReactNode} from 'react'
 import type {TextProps as RNTextProps} from 'react-native'
 
+/** React Native's `Text` in a theme typography variant — the React Native tier, for text outside a native host. */
 export type RnTextProps = Omit<RNTextProps, 'style'> & {
+  /** Horizontal alignment, as React Native's `textAlign`. */
   align?: 'center' | 'left' | 'right'
+  /** The text's colour. `content.primary` by default. */
   color?: ColorToken
+  /** The typography variant. `body` by default. */
   variant?: TextVariant
 }
 

package/src/atoms/rn-view/rn-view.types.ts

@@ -1,5 +1,6 @@
 import type {ReactElement, ReactNode} from 'react'
 
+/** Carries a React Native view into a SwiftUI or Compose tree — `@expo/ui`'s `RNHostView` on both platforms. */
 export type RnViewProps = {
   /**
    * A single React Native *view*. It may not contain React Native text: a bare string becomes a
@@ -15,6 +16,7 @@ export type RnViewProps = {
    * intrinsic size and would otherwise stretch to fill the SwiftUI parent.
    */
   matchContents?: boolean
+  /** Not forwarded on either platform — give the child its own `testID`. */
   testID?: string
 }
 

package/src/atoms/scroll-view/scroll-view.types.ts

@@ -9,7 +9,9 @@ export type ScrollViewAxis = 'horizontal' | 'vertical'
  * like React Native's `contentContainerStyle` padding and scrolls with the content.
  */
 export type ScrollViewProps = ResponsiveSx & {
+  /** The scroll direction. `vertical` by default. */
   axis?: ScrollViewAxis
+  /** Laid out in a stack along `axis`. */
   children?: ReactNode
   /**
    * Enables pull-to-refresh. Async on purpose: the spinner runs until the promise settles, which is
@@ -21,7 +23,9 @@ export type ScrollViewProps = ResponsiveSx & {
   onRefresh?: () => Promise<void>
   /** iOS only — Compose exposes no indicator toggle, so Android always shows the native one. */
   showsIndicators?: boolean
+  /** The space between children. */
   spacing?: SpaceSize
+  /** Test identifier, forwarded to the native view. */
   testID?: string
 }