@hzblj/kara-components 0.6.0 → 0.7.0

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
 }
 

package/src/atoms/segmented-control/segmented-control.android.tsx

@@ -0,0 +1,79 @@
+import {Host, SegmentedButton, SingleChoiceSegmentedButtonRow, Text} from '@expo/ui/jetpack-compose'
+import {fillMaxWidth, testID as testIdModifier, weight} from '@expo/ui/jetpack-compose/modifiers'
+import {useAppTheme} from '@hzblj/kara-theme'
+import {useCallback, useMemo} from 'react'
+
+import {haptics} from '../../haptics'
+import type {SegmentedControlComponent, SegmentedControlProps} from './segmented-control.types'
+
+const MATCH_HEIGHT_ONLY = {horizontal: false, vertical: true}
+
+/** Every segment the same width, like UIKit's: Material's would size each to its label. */
+const SEGMENT = [weight(1)]
+
+/**
+ * Material's single-choice segmented buttons, the selected one filled with the accent like a checked `Switch`. Its own
+ * host, themed like an `Island`, so it drops into React Native layout the way the iOS control does. Material plays
+ * nothing on a new segment, so this plays `selection`.
+ */
+export const SegmentedControl: SegmentedControlComponent = ({
+  disabled = false,
+  onChange,
+  selectedIndex,
+  testID,
+  values,
+}: SegmentedControlProps) => {
+  const theme = useAppTheme()
+
+  const colors = useMemo(
+    () => ({
+      activeBorderColor: theme.color('fill.accent.primary'),
+      activeContainerColor: theme.color('fill.accent.primary'),
+      activeContentColor: theme.color('content.on.bg'),
+      disabledActiveBorderColor: theme.color('fill.accent.disabled'),
+      disabledActiveContainerColor: theme.color('fill.accent.disabled'),
+      disabledActiveContentColor: theme.color('btn.content.disabled'),
+      disabledInactiveBorderColor: theme.color('border.tertiary'),
+      disabledInactiveContentColor: theme.color('btn.content.disabled'),
+      inactiveBorderColor: theme.color('border.secondary.base'),
+      inactiveContentColor: theme.color('content.primary'),
+    }),
+    [theme]
+  )
+
+  const rowModifiers = useMemo(() => (testID ? [fillMaxWidth(), testIdModifier(testID)] : [fillMaxWidth()]), [testID])
+
+  // Material reports a tap on the segment that is already selected too; iOS does not, and neither does this.
+  const select = useCallback(
+    (index: number) => {
+      if (index === selectedIndex) {
+        return
+      }
+
+      haptics.selection()
+      onChange?.(index, values[index] ?? '')
+    },
+    [onChange, selectedIndex, values]
+  )
+
+  return (
+    <Host colorScheme={theme.dark ? 'dark' : 'light'} matchContents={MATCH_HEIGHT_ONLY} seedColor={theme.materialSeed}>
+      <SingleChoiceSegmentedButtonRow modifiers={rowModifiers}>
+        {values.map((label, index) => (
+          <SegmentedButton
+            colors={colors}
+            enabled={!disabled}
+            key={index}
+            modifiers={SEGMENT}
+            onClick={() => select(index)}
+            selected={index === selectedIndex}
+          >
+            <SegmentedButton.Label>
+              <Text style={theme.typography.subheadlineMedium}>{label}</Text>
+            </SegmentedButton.Label>
+          </SegmentedButton>
+        ))}
+      </SingleChoiceSegmentedButtonRow>
+    </Host>
+  )
+}

package/src/atoms/segmented-control/segmented-control.ios.tsx

@@ -0,0 +1,47 @@
+import {SegmentedControl as NativeSegmentedControl} from '@hzblj/kara-native/swift-ui'
+import {useAppTheme} from '@hzblj/kara-theme'
+import {useCallback, useMemo} from 'react'
+
+import type {SegmentedControlComponent, SegmentedControlProps} from './segmented-control.types'
+
+/**
+ * kara's own `UISegmentedControl`, with the pill in the accent and white text on it — the system control tints only the
+ * pill, and SwiftUI's segmented picker not even that. A plain `UIView` in React Native layout: it needs no host, takes
+ * the width it is given and UIKit's height. UIKit plays the control's own feedback.
+ */
+export const SegmentedControl: SegmentedControlComponent = ({
+  disabled = false,
+  onChange,
+  selectedIndex,
+  testID,
+  values,
+}: SegmentedControlProps) => {
+  const theme = useAppTheme()
+  const face = theme.typography.footnoteMedium
+
+  // The native control speaks in values; a segment's is its index, so two labels may read the same.
+  const options = useMemo(() => values.map((label, index) => ({label, value: String(index)})), [values])
+
+  const onValueChange = useCallback(
+    (value: string) => {
+      const index = Number(value)
+      onChange?.(index, values[index] ?? '')
+    },
+    [onChange, values]
+  )
+
+  return (
+    <NativeSegmentedControl
+      activePillColor={theme.color('fill.accent.primary')}
+      activeTextColor={theme.color('content.on.bg')}
+      disabled={disabled}
+      fontFamily={face.fontFamily}
+      fontSize={face.fontSize}
+      inactiveTextColor={theme.color('content.primary')}
+      onValueChange={onValueChange}
+      options={options}
+      selectedValue={String(selectedIndex)}
+      testID={testID}
+    />
+  )
+}

package/src/atoms/segmented-control/segmented-control.types.ts

@@ -1,10 +1,23 @@
 import type {ReactNode} from 'react'
 
+/**
+ * A row of mutually exclusive segments, the selected one in the accent — kara's own `UISegmentedControl` on iOS,
+ * Material's single-choice segmented buttons on Android. It needs no `Screen` or `Island`: iOS is a plain view, Android
+ * brings its own host. It takes the width it is given; the height is the platform's.
+ */
 export type SegmentedControlProps = {
+  /** Stops the user changing the segment, and dims the control. */
   disabled?: boolean
+  /**
+   * Called with the index and label of the segment the user picked — never for a tap on the one already selected.
+   * Android plays `selection`; iOS's control plays its own feedback.
+   */
   onChange?: (index: number, value: string) => void
+  /** The selected segment. Controlled: pass back what `onChange` reports. */
   selectedIndex: number
+  /** Test identifier, on the whole control — reach a segment by its label. */
   testID?: string
+  /** The segments' labels, in order. */
   values: string[]
 }
 

package/src/atoms/skeleton/skeleton.types.ts

@@ -1,10 +1,15 @@
 import type {RadiiSize} from '@hzblj/kara-theme'
 import type {ReactNode} from 'react'
 
+/** A loading placeholder that pulses in `fill.quaternary` — a React Native view, so it needs no host. */
 export type SkeletonProps = {
+  /** The corner radius. `small` by default. */
   borderRadius?: RadiiSize
+  /** In points. */
   height: number
+  /** Test identifier, forwarded to the view. */
   testID?: string
+  /** In points. Leave it unset and it fills the available width. */
   width?: number
 }
 

package/src/atoms/slider/slider.types.ts

@@ -1,11 +1,18 @@
 import type {ReactNode} from 'react'
 
+/** SwiftUI `Slider` / Compose's Material `Slider`, tinted `fill.accent.primary`. */
 export type SliderProps = {
+  /** Stops the user moving the thumb, and dims the slider. */
   disabled?: boolean
+  /** The upper end. `1` by default. */
   max?: number
+  /** The lower end. `0` by default. */
   min?: number
+  /** Called with the new value as the thumb moves. */
   onValueChange?: (value: number) => void
+  /** The increment between stops; leave it unset for a continuous slider. On Android every stop plays a `tick`. */
   step?: number
+  /** Between `min` and `max`. Controlled: pass back what `onValueChange` reports. */
   value: number
 }
 

package/src/atoms/spacer/spacer.types.ts

@@ -1,8 +1,11 @@
 import type {SpaceSize} from '@hzblj/kara-theme'
 import type {ReactNode} from 'react'
 
+/** Takes up the free space in a stack — SwiftUI `Spacer` / Compose `Spacer` with `weight(1)`. */
 export type SpacerProps = {
+  /** The least room it takes. iOS holds it along the stack's axis; Android as a minimum height only. */
   min?: SpaceSize
+  /** iOS: forwarded to the native view. Android ignores it. */
   testID?: string
 }
 

package/src/atoms/surface/surface.types.ts

@@ -1,9 +1,16 @@
 import type {ResponsiveSx} from '@hzblj/kara-sx'
 import type {ReactNode} from 'react'
 
+/**
+ * A container padded `s16` and rounded `large` unless told otherwise — a SwiftUI `VStack` on iOS, Material's
+ * `Surface` around a `Column` on Android.
+ */
 export type SurfaceProps = ResponsiveSx & {
+  /** Stacked vertically, from the leading edge. */
   children?: ReactNode
+  /** iOS wraps the content in a `GlassEffectContainer`; Android raises it to a tonal elevation of `3`. */
   glass?: boolean
+  /** Test identifier, forwarded to the native view. */
   testID?: string
 }
 

package/src/atoms/switch/switch.android.tsx

@@ -7,6 +7,9 @@ import {haptics} from '../../haptics'
 import {useHostGuard} from '../../host-context'
 import type {SwitchComponent, SwitchProps} from './switch.types'
 
+/** Stands in for a missing handler: Material drops its 48dp touch target without one, and the switch moves. */
+const NOOP = () => undefined
+
 /**
  * Material's switch, tinted with the accent like SwiftUI's toggle. With a label it is a full-width row — label at the
  * start, switch at the end — and the whole row toggles, the way a Material settings row does. A flip plays
@@ -35,7 +38,7 @@ export const Switch: SwitchComponent = ({disabled = false, label, onValueChange,
         checkedTrackColor: theme.color('fill.accent.primary'),
       }}
       enabled={!disabled}
-      onCheckedChange={onValueChange ? toggle : undefined}
+      onCheckedChange={onValueChange ? toggle : NOOP}
       value={value}
     />
   )

package/src/atoms/switch/switch.types.ts

@@ -1,9 +1,17 @@
 import type {ReactNode} from 'react'
 
+/** SwiftUI `Toggle` / Compose `Switch`, tinted `fill.accent.primary`. */
 export type SwitchProps = {
+  /** Stops the user flipping it, and dims it. */
   disabled?: boolean
+  /**
+   * Shown beside the switch. On Android it makes a full-width row — label at the start, switch at the end — that
+   * toggles wherever it is tapped.
+   */
   label?: string
+  /** Called with the new value when the user flips it. On Android a flip plays `toggleOn` / `toggleOff`. */
   onValueChange?: (value: boolean) => void
+  /** Whether it is on. Controlled: pass back what `onValueChange` reports. */
   value: boolean
 }
 

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

@@ -7,14 +7,26 @@ export type TextDecoration = 'none' | 'strikethrough' | 'underline'
 
 export type TextTransform = 'lowercase' | 'uppercase'
 
+/** SwiftUI `Text` / Compose `Text` in a theme typography variant — a native atom; outside a host, use `RnText`. */
 export type TextProps = {
+  /**
+   * How its lines align. iOS reads `left` and `right` as leading and trailing, so they flip in a right-to-left
+   * layout; Android keeps them as they are.
+   */
   align?: TextAlign
+  /** The text. */
   children?: ReactNode
+  /** The text's colour. `content.primary` by default. */
   color?: ColorToken
+  /** An underline or a strikethrough. */
   decoration?: TextDecoration
+  /** The most lines it wraps to. iOS truncates the last with an ellipsis; Android clips it. */
   numberOfLines?: number
+  /** Test identifier, forwarded to the native view. */
   testID?: string
+  /** Upper- or lower-cases the text. Android applies it only when `children` is a plain string. */
   transform?: TextTransform
+  /** The typography variant. `body` by default. */
   variant?: TextVariant
 }
 

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

@@ -1,13 +1,25 @@
 import type {ReactNode} from 'react'
 
+/**
+ * An uncontrolled text field with an optional label above it — SwiftUI `TextField` (`SecureField` when `secure`) /
+ * Compose `OutlinedTextField`.
+ */
 export type TextFieldProps = {
+  /** The text it starts with. Read once, on mount — the field is uncontrolled. */
   defaultValue?: string
+  /** Stops editing and dims the field. On iOS it outranks `error`. */
   disabled?: boolean
+  /** Marks the field invalid: a destructive outline and label. */
   error?: boolean
+  /** Shown above the field, in `labelMedium`. */
   label?: string
+  /** Wraps the text and grows the field to fit it. iOS ignores it when `secure`. */
   multiline?: boolean
+  /** Called with the whole text after every change. */
   onChangeText?: (text: string) => void
+  /** Masks the text, for a password. */
   secure?: boolean
+  /** iOS: forwarded to the native field. Android ignores it. */
   testID?: string
 }
 

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

@@ -4,11 +4,20 @@ import type {ReactNode} from 'react'
 
 export type VStackAlign = 'center' | 'end' | 'start'
 
+/** Stacks its children top to bottom — SwiftUI `VStack` / Compose `Column`. */
 export type VStackProps = ResponsiveSx & {
+  /** The children's horizontal alignment. `start` by default. */
   align?: VStackAlign
+  /** Laid out top to bottom, `spacing` apart. */
   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
+  /** The space between children. */
   spacing?: SpaceSize
+  /** Test identifier, forwarded to the native view. */
   testID?: string
 }
 

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.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.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.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.
  */