@hzblj/kara-components 0.5.0 → 0.7.0

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

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.types.ts

@@ -17,12 +17,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, where it wants a background. */
   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, where it wants a background. */
   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.types.ts

@@ -1,11 +1,24 @@
 import type {ReactNode} from 'react'
 
+/**
+ * A number with minus and plus buttons beside a label: SwiftUI's `Stepper` on iOS; on Android the label, the value and
+ * two icon buttons in a row. A native atom — it renders inside `<Screen>` or `<Island>`.
+ */
 export type StepperProps = {
+  /**
+   * The leading text. iOS shows only the label, not the value — put the value in it if it should be seen. Android
+   * shows the value between its buttons.
+   */
   label: string
+  /** The highest value. When unset, Android has no upper limit and iOS stops at `100`. */
   max?: number
+  /** The lowest value. When unset, Android has no lower limit and iOS stops at `0`. */
   min?: number
+  /** A button was pressed; it passes the new value, kept within `min` and `max`. */
   onValueChange: (value: number) => void
+  /** How much one press adds or takes away. `1` by default. */
   step?: number
+  /** The current value. Update it from `onValueChange`. iOS's native stepper counts in whole numbers. */
   value: number
 }
 

package/src/molecules/tooltip/tooltip.android.tsx

@@ -1,24 +1,32 @@
-import {Text as ComposeText, TooltipBox} from '@expo/ui/jetpack-compose'
+import {Text as ComposeText} from '@expo/ui/jetpack-compose'
+import {TooltipBox} from '@hzblj/kara-native/jetpack-compose'
 import {useAppTheme} from '@hzblj/kara-theme'
+import {useCallback} from 'react'
 
 import {useHostGuard} from '../../host-context'
 import type {TooltipComponent, TooltipProps} from './tooltip.types'
 
-export const Tooltip: TooltipComponent = ({children, text}: TooltipProps) => {
+/**
+ * Material's plain tooltip in kara's controlled `TooltipBox`: shown while `visible`, centred above the anchor and kept
+ * inside the window. Material's own would open on a long press and hide itself without a word to JS.
+ */
+export const Tooltip: TooltipComponent = ({children, onDismiss, text, visible}: TooltipProps) => {
   useHostGuard('Tooltip')
-
   const theme = useAppTheme()
+  const onDismissRequest = useCallback(() => onDismiss(), [onDismiss])
 
   return (
-    <TooltipBox>
-      <TooltipBox.PlainTooltip
-        containerColor={theme.colorString('surface.high.contrast')}
-        contentColor={theme.colorString('content.on.high.contrast')}
-      >
+    <TooltipBox
+      containerColor={theme.color('surface.high.contrast')}
+      isPresented={visible}
+      onDismissRequest={onDismissRequest}
+      plain
+    >
+      <TooltipBox.Text>
         <ComposeText color={theme.colorString('content.on.high.contrast')} style={theme.typography.footnote}>
           {text}
         </ComposeText>
-      </TooltipBox.PlainTooltip>
+      </TooltipBox.Text>
       {children}
     </TooltipBox>
   )

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

@@ -1,9 +1,21 @@
 import type {ReactNode} from 'react'
 
+/**
+ * A short text tip on a native view, shown while `visible` — a SwiftUI popover from `children` on iOS, Material's plain
+ * tooltip centred above them on Android. A native atom — it renders inside `<Screen>` or `<Island>`; `RnTooltip`
+ * anchors to a React Native view.
+ */
 export type TooltipProps = {
+  /** The anchor — a native view. */
   children: ReactNode
+  /** The tip. */
   text: string
+  /** Shows the tip while true. Controlled: nothing opens it but this — wire a long press to it if you want one. */
   visible: boolean
+  /**
+   * The user dismissed the tip — turn `visible` off. iOS: a tap outside the popover. Android: any touch outside it, the
+   * start of a scroll included, or the anchor scrolling out of the window.
+   */
   onDismiss: () => void
 }
 

package/src/organisms/action-sheet/action-sheet.android.tsx

@@ -1,35 +1,53 @@
-import {Divider} from '../../atoms/divider'
 import {HStack} from '../../atoms/h-stack'
+import {Icon} from '../../atoms/icon'
+import {Island} from '../../atoms/island'
 import {Text} from '../../atoms/text'
 import {VStack} from '../../atoms/v-stack'
 import {useHostGuard} from '../../host-context'
 import {Sheet} from '../sheet'
 import type {ActionSheetComponent, ActionSheetProps} from './action-sheet.types'
 
+/**
+ * Material's bottom-sheet menu: the title, then a full-width row per action, its icon leading. The sheet is the React
+ * Native tier, so the rows — Compose views — sit in an `Island` of their own; rendered straight into the sheet they had
+ * no host and threw.
+ */
 export const ActionSheet: ActionSheetComponent = ({actions, onDismiss, title, visible}: ActionSheetProps) => {
   useHostGuard('ActionSheet')
 
   return (
     <Sheet onDismiss={onDismiss} visible={visible}>
-      <VStack p="s16" spacing="s4" wide>
-        <Text color="content.secondary" variant="labelMedium">
-          {title}
-        </Text>
-        <Divider />
-        {actions.map(action => (
-          <HStack
-            key={action.label}
-            onPress={() => {
-              onDismiss()
-              action.onPress()
-            }}
-            py="s12"
-            wide
-          >
-            <Text color={action.destructive ? 'content.destructive' : 'content.primary'}>{action.label}</Text>
+      <Island>
+        <VStack pb="s16" wide>
+          <HStack px="s24" py="s12" wide>
+            <Text color="content.secondary" variant="labelMedium">
+              {title}
+            </Text>
           </HStack>
-        ))}
-      </VStack>
+          {actions.map(action => {
+            const color = action.destructive ? 'content.destructive' : 'content.primary'
+
+            return (
+              <HStack
+                key={action.label}
+                onPress={() => {
+                  onDismiss()
+                  action.onPress()
+                }}
+                px="s24"
+                py="s16"
+                spacing="s16"
+                wide
+              >
+                {action.icon ? <Icon color={color} name={action.icon} /> : null}
+                <Text color={color} variant="body">
+                  {action.label}
+                </Text>
+              </HStack>
+            )
+          })}
+        </VStack>
+      </Island>
     </Sheet>
   )
 }

package/src/organisms/action-sheet/action-sheet.ios.tsx

@@ -1,8 +1,16 @@
-import {Button, ConfirmationDialog} from '@expo/ui/swift-ui'
+import {Button, ConfirmationDialog, Spacer} from '@expo/ui/swift-ui'
+import {frame} from '@expo/ui/swift-ui/modifiers'
 
 import {useHostGuard} from '../../host-context'
 import type {ActionSheetComponent, ActionSheetProps} from './action-sheet.types'
 
+/**
+ * `@expo/ui` hangs the dialog on its `Trigger` and reads the buttons from its `Actions` slot. Without a trigger it
+ * attaches to an `EmptyView`, which SwiftUI never presents from — a spacer framed to nothing is a real view that takes
+ * no room.
+ */
+const ANCHOR = [frame({height: 0, width: 0})]
+
 export const ActionSheet: ActionSheetComponent = ({actions, onDismiss, title, visible}: ActionSheetProps) => {
   useHostGuard('ActionSheet')
 
@@ -16,14 +24,19 @@ export const ActionSheet: ActionSheetComponent = ({actions, onDismiss, title, vi
       }}
       title={title}
     >
-      {actions.map(action => (
-        <Button
-          key={action.label}
-          label={action.label}
-          onPress={action.onPress}
-          role={action.destructive ? 'destructive' : 'default'}
-        />
-      ))}
+      <ConfirmationDialog.Trigger>
+        <Spacer modifiers={ANCHOR} />
+      </ConfirmationDialog.Trigger>
+      <ConfirmationDialog.Actions>
+        {actions.map(action => (
+          <Button
+            key={action.label}
+            label={action.label}
+            onPress={action.onPress}
+            role={action.destructive ? 'destructive' : 'default'}
+          />
+        ))}
+      </ConfirmationDialog.Actions>
     </ConfirmationDialog>
   )
 }

package/src/organisms/action-sheet/action-sheet.types.ts

@@ -2,10 +2,18 @@ import type {ReactNode} from 'react'
 
 import type {MenuAction} from '../menu'
 
+/**
+ * A list of actions to pick one from: SwiftUI's confirmation dialog on iOS, a `Sheet` of Material rows — icon and label
+ * — under the title on Android. A native atom — it renders inside `<Screen>` or `<Island>`.
+ */
 export type ActionSheetProps = {
+  /** The choices, top to bottom. Picking one closes the sheet. */
   actions: MenuAction[]
+  /** The sheet closed — after a pick too — so turn `visible` off. */
   onDismiss: () => void
+  /** The heading above the actions. Android always shows it; on iOS the system decides, and may hide it. */
   title: string
+  /** Presents the sheet while true. */
   visible: boolean
 }
 

package/src/organisms/alert/alert.ios.tsx

@@ -1,8 +1,15 @@
-import {Button, Alert as SwiftUIAlert, Text as SwiftUIText} from '@expo/ui/swift-ui'
+import {Button, Spacer, Alert as SwiftUIAlert, Text as SwiftUIText} from '@expo/ui/swift-ui'
+import {frame} from '@expo/ui/swift-ui/modifiers'
 
 import {useHostGuard} from '../../host-context'
 import type {AlertComponent, AlertProps} from './alert.types'
 
+/**
+ * `@expo/ui` hangs the alert on its `Alert.Trigger`, and on an `EmptyView` when there is none — which SwiftUI never
+ * presents from, so the alert would not appear at all. A spacer framed to nothing is a real view that takes no room.
+ */
+const ANCHOR = [frame({height: 0, width: 0})]
+
 export const Alert: AlertComponent = ({
   confirmLabel = 'OK',
   destructive = false,
@@ -24,6 +31,9 @@ export const Alert: AlertComponent = ({
       }}
       title={title}
     >
+      <SwiftUIAlert.Trigger>
+        <Spacer modifiers={ANCHOR} />
+      </SwiftUIAlert.Trigger>
       <SwiftUIAlert.Actions>
         <Button label={confirmLabel} onPress={onConfirm ?? onDismiss} role={destructive ? 'destructive' : 'default'} />
         <Button label="Cancel" onPress={onDismiss} role="cancel" />

package/src/organisms/alert/alert.types.ts

@@ -1,12 +1,23 @@
 import type {ReactNode} from 'react'
 
+/**
+ * A modal alert with a confirm button and Cancel: SwiftUI's alert on iOS, Material's `AlertDialog` on Android. A native
+ * atom — it renders inside `<Screen>` or `<Island>`.
+ */
 export type AlertProps = {
+  /** The confirm button's label. `OK` by default. */
   confirmLabel?: string
+  /** Marks the confirm button destructive — the system's destructive role on iOS, the destructive colour on Android. */
   destructive?: boolean
+  /** The body text, under the title. */
   message?: string
+  /** The confirm button was pressed. `onDismiss` follows, as it does for every way the alert closes. */
   onConfirm?: () => void
+  /** The alert closed — either button, or on Android a tap outside or back — so turn `visible` off. */
   onDismiss: () => void
+  /** The alert's heading. */
   title: string
+  /** Shows the alert while true. */
   visible: boolean
 }
 

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

@@ -1,10 +1,10 @@
 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 * 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 {haptics} from '../../haptics'
 import {HostBoundary} from '../../host-context'
 import {splitForRipple} from '../../ripple-clip'
 import type {MenuAction} from '../menu'
@@ -70,7 +70,7 @@ const ContextMenuRoot = ({actions, children, testID, ...props}: ContextMenuProps
   const open = useCallback((event: GestureResponderEvent) => {
     const {pageX, pageY} = event.nativeEvent
 
-    Haptics.performAndroidHapticsAsync(Haptics.AndroidHaptics.Long_Press).catch(() => undefined)
+    haptics.longPress()
     // 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})

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

@@ -10,6 +10,7 @@ import type {MenuAction} from '../menu'
  * needs no `Screen` or `Island`.
  */
 export type ContextMenuProps = ResponsiveViewSx & {
+  /** The menu's actions, top to bottom. */
   actions: MenuAction[]
   /** The trigger, laid out as usual. */
   children: ReactNode
@@ -29,10 +30,13 @@ export type ContextMenuProps = ResponsiveViewSx & {
    * `ZoomTransition.Source`, `pop` otherwise.
    */
   previewTransition?: 'dismiss' | 'pop' | 'zoom'
+  /** Test identifier — on the native view around the trigger on iOS, on the trigger's `Pressable` on Android. */
   testID?: string
 }
 
+/** A region of a `ContextMenu`'s trigger that keeps its own long press — see `ContextMenu.Exclusion`. */
 export type ContextMenuExclusionProps = {
+  /** The region — a button inside the card, say. */
   children: ReactNode
 }
 

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

@@ -9,9 +9,11 @@ import type {MenuAction} from '../menu'
  * of a SwiftUI `Menu`. A native atom — it renders inside `<Screen>` or `<Island>`.
  */
 export type FabMenuProps = {
+  /** The actions the button unfolds into. */
   actions: MenuAction[]
   /** The closed button's icon — one of the app's. A plus by default. */
   icon?: IconName
+  /** Test identifier, forwarded to the SwiftUI `Menu`. iOS only — Android ignores it. */
   testID?: string
 }
 

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

@@ -4,11 +4,15 @@ import {VStack} from '../../atoms/v-stack'
 import {useHostGuard} from '../../host-context'
 import type {FormComponent, FormProps, FormSectionProps} from './form.types'
 
+/**
+ * Inset from its container on every side, as SwiftUI's grouped form is — in a `Screen` the cards would otherwise run
+ * into the screen's edges — and the section titles and footers indented to the cards' content.
+ */
 const FormRoot = ({children, testID}: FormProps) => {
   useHostGuard('Form')
 
   return (
-    <VStack spacing="s16" testID={testID} wide>
+    <VStack p="s16" spacing="s16" testID={testID} wide>
       {children}
     </VStack>
   )
@@ -17,15 +21,19 @@ const FormRoot = ({children, testID}: FormProps) => {
 const FormSection = ({children, footer, title}: FormSectionProps) => (
   <VStack spacing="s4" wide>
     {title ? (
-      <Text color="content.secondary" transform="uppercase" variant="labelMedium">
-        {title}
-      </Text>
+      <VStack px="s16" wide>
+        <Text color="content.secondary" transform="uppercase" variant="labelMedium">
+          {title}
+        </Text>
+      </VStack>
     ) : null}
     <Card wide>{children}</Card>
     {footer ? (
-      <Text color="content.tertiary" variant="footnote">
-        {footer}
-      </Text>
+      <VStack px="s16" wide>
+        <Text color="content.tertiary" variant="footnote">
+          {footer}
+        </Text>
+      </VStack>
     ) : null}
   </VStack>
 )

package/src/organisms/form/form.types.ts

@@ -6,13 +6,19 @@ import type {ReactNode} from 'react'
  * an island that sizes itself to its content it has no height and shows nothing.
  */
 export type FormProps = {
+  /** The form's `Form.Section`s. */
   children: ReactNode
+  /** Test identifier, forwarded to the native view. */
   testID?: string
 }
 
+/** A group of rows in a `Form`: a SwiftUI `Section` on iOS, a `Card` under a heading on Android. */
 export type FormSectionProps = {
+  /** The section's rows. */
   children: ReactNode
+  /** Small print under the section. */
   footer?: string
+  /** The section's heading. */
   title?: string
 }
 

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

@@ -2,15 +2,32 @@ import type {ReactNode} from 'react'
 
 import type {IconName} from '../../atoms/icon'
 
+/** One action of a `Menu`, an `ActionSheet`, a `ContextMenu` or a `FabMenu`. */
 export type MenuAction = {
+  /**
+   * Draws the action in the destructive colour — the system's destructive role on iOS. `FabMenu` ignores it on
+   * Android.
+   */
   destructive?: boolean
+  /**
+   * One of the app's icons, before the label. `ContextMenu` and `FabMenu` show it on both platforms, `Menu` and
+   * `ActionSheet` on Android only.
+   */
   icon?: IconName
+  /** The action's text. Rows are keyed by it, so keep labels unique within one list. */
   label: string
+  /** Called when the action is chosen; the menu closes by itself. */
   onPress: () => void
 }
 
+/**
+ * A text button that opens a list of actions: a SwiftUI `Menu` on iOS, a Material dropdown anchored to it on Android.
+ * A native atom — it renders inside `<Screen>` or `<Island>`.
+ */
 export type MenuProps = {
+  /** The menu's actions, top to bottom. */
   actions: MenuAction[]
+  /** The trigger's text. Android draws it in the accent colour, with a chevron. */
   label: string
 }