@hzblj/kara-components 0.5.0 → 0.7.0

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.android.tsx

@@ -1,9 +1,16 @@
 import {Slider as ComposeSlider} from '@expo/ui/jetpack-compose'
 import {useAppTheme} from '@hzblj/kara-theme'
+import {useCallback, useEffect, useRef} from 'react'
 
+import {haptics} from '../../haptics'
 import {useHostGuard} from '../../host-context'
 import type {SliderComponent, SliderProps} from './slider.types'
 
+/**
+ * Material's slider. `step` is the increment, as SwiftUI takes it; Compose counts the stops between the two ends
+ * instead, so it is converted. A stepped slider ticks at every stop the thumb reaches — Compose's Material slider
+ * plays nothing of its own, where iOS 26's slider already does.
+ */
 export const Slider: SliderComponent = ({
   disabled = false,
   max = 1,
@@ -14,6 +21,30 @@ export const Slider: SliderComponent = ({
 }: SliderProps) => {
   useHostGuard('Slider')
   const theme = useAppTheme()
+  const steps = step ? Math.max(0, Math.round((max - min) / step) - 1) : 0
+
+  // The stop is derived from the value rather than trusting it to arrive snapped, and remembered between events:
+  // Compose reports faster than React re-renders the controlled value.
+  const stopOf = useCallback((at: number) => (step ? Math.round((at - min) / step) : 0), [min, step])
+  const stop = useRef(stopOf(value))
+
+  useEffect(() => {
+    stop.current = stopOf(value)
+  }, [stopOf, value])
+
+  const onChange = useCallback(
+    (next: number) => {
+      const reached = stopOf(next)
+
+      if (steps > 0 && reached !== stop.current) {
+        haptics.tick()
+      }
+
+      stop.current = reached
+      onValueChange?.(next)
+    },
+    [onValueChange, stopOf, steps]
+  )
 
   return (
     <ComposeSlider
@@ -24,8 +55,8 @@ export const Slider: SliderComponent = ({
       enabled={!disabled}
       max={max}
       min={min}
-      onValueChange={onValueChange}
-      steps={step}
+      onValueChange={onChange}
+      steps={steps}
       value={value}
     />
   )

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

@@ -1,21 +1,34 @@
 import {Switch as ComposeSwitch, Row, Text} from '@expo/ui/jetpack-compose'
 import {clickable, fillMaxWidth} from '@expo/ui/jetpack-compose/modifiers'
 import {useAppTheme} from '@hzblj/kara-theme'
-import {useMemo} from 'react'
+import {useCallback, useMemo} from 'react'
 
+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.
+ * start, switch at the end — and the whole row toggles, the way a Material settings row does. A flip plays
+ * `toggleOn`/`toggleOff` — Android 14's constants made for switches — since Compose's Material switch plays nothing
+ * of its own. iOS stays silent, as `UISwitch` does.
  */
 export const Switch: SwitchComponent = ({disabled = false, label, onValueChange, value}: SwitchProps) => {
   useHostGuard('Switch')
   const theme = useAppTheme()
+  const toggle = useCallback(
+    (next: boolean) => {
+      haptics.play(next ? 'toggleOn' : 'toggleOff')
+      onValueChange?.(next)
+    },
+    [onValueChange]
+  )
   const rowModifiers = useMemo(
-    () => (disabled || !onValueChange ? [fillMaxWidth()] : [fillMaxWidth(), clickable(() => onValueChange(!value))]),
-    [disabled, onValueChange, value]
+    () => (disabled || !onValueChange ? [fillMaxWidth()] : [fillMaxWidth(), clickable(() => toggle(!value))]),
+    [disabled, onValueChange, toggle, value]
   )
   const control = (
     <ComposeSwitch
@@ -25,7 +38,7 @@ export const Switch: SwitchComponent = ({disabled = false, label, onValueChange,
         checkedTrackColor: theme.color('fill.accent.primary'),
       }}
       enabled={!disabled}
-      onCheckedChange={onValueChange}
+      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/haptics/haptics.ts

@@ -0,0 +1,68 @@
+import {HAPTICS, type Haptic, playHaptic, prepareHaptic} from '@hzblj/kara-native'
+
+export type {Haptic}
+
+export type HapticOptions = {
+  /** iOS: scales an impact — `soft`, `light`, `medium`, `rigid`, `heavy` — from 0 to 1. Everything else ignores it. */
+  intensity?: number
+}
+
+type HapticShorthands = {readonly [K in Haptic]: (options?: HapticOptions) => void}
+
+let enabled = true
+
+const play = (haptic: Haptic, options?: HapticOptions): void => {
+  if (enabled) {
+    playHaptic(haptic, options?.intensity)
+  }
+}
+
+const prepare = (haptic: Haptic): void => {
+  if (enabled) {
+    prepareHaptic(haptic)
+  }
+}
+
+const shorthands = Object.fromEntries(
+  HAPTICS.map(haptic => [haptic, (options?: HapticOptions) => play(haptic, options)])
+) as HapticShorthands
+
+/**
+ * The platform's own haptic feedback, named for what happened: UIKit's feedback generators on iOS, the system's
+ * `HapticFeedbackConstants` on Android — never a raw vibration. Both follow the user's system haptics setting, and
+ * every call is synchronous, with nothing to await.
+ *
+ * ```ts
+ * haptics.success()                    // a name you know: one function per haptic
+ * haptics.play(haptic)                 // a name that arrives as data
+ * haptics.light({intensity: 0.6})      // impacts scale on iOS
+ * haptics.prepare('selection')         // iOS: warm the Taptic Engine as a gesture begins
+ * haptics.setEnabled(userPreference)   // silences every kara haptic, the components' own too
+ * ```
+ *
+ * - `selection` — a choice changed: a segment, a chip, a picker row.
+ * - `tick` — one step of a continuous gesture: a slider detent, a scrubbed value.
+ * - `toggleOn` / `toggleOff` — a switch flipped.
+ * - `success` / `warning` / `error` — how a task ended. Android has no warning of its own; it plays a rejection.
+ * - `longPress` / `dragStart` — a long press was recognised; an item lifted to be dragged.
+ * - `thresholdActivate` / `thresholdDeactivate` — a gesture crossed its commit point, or went back over it.
+ * - `keyPress` — a key of the app's own keypad.
+ * - `soft`, `light`, `medium`, `rigid`, `heavy` — a collision none of the names above describes.
+ *
+ * On Android the names that came with Android 14's constants fall back to the nearest older feedback, so every name
+ * plays on every version. Haptics are silent in a build without kara's native module.
+ */
+export const haptics = {
+  ...shorthands,
+  /** Whether kara plays haptics — `true` until `setEnabled(false)`. */
+  isEnabled: (): boolean => enabled,
+  play,
+  prepare,
+  /**
+   * Switches every kara haptic on or off, the ones its components play included — for an app's own "Haptics" setting.
+   * Not persisted: call it at start-up with the stored preference. The system setting applies either way.
+   */
+  setEnabled: (value: boolean): void => {
+    enabled = value
+  },
+}

package/src/haptics/index.ts

@@ -0,0 +1,2 @@
+export {type Haptic, type HapticOptions, haptics} from './haptics'
+export {type HapticResolver, useHapticFeedback} from './use-haptic-feedback'

package/src/haptics/use-haptic-feedback.ts

@@ -0,0 +1,36 @@
+import {useEffect, useRef} from 'react'
+
+import {type Haptic, haptics} from './haptics'
+
+/** Picks the haptic for one change of a trigger — or none, to stay silent for that change. */
+export type HapticResolver<T> = (previous: T, next: T) => Haptic | false | null | undefined
+
+/**
+ * Plays a haptic whenever `trigger` changes — never on mount — like SwiftUI's `sensoryFeedback(_:trigger:)`. Give it
+ * a haptic, or a function of the previous and next value that picks one per change. Changes are compared with
+ * `Object.is`, so a trigger is a primitive or a stable reference.
+ *
+ * ```ts
+ * useHapticFeedback(tab, 'selection')
+ * useHapticFeedback(quantity, (before, after) => (after > before ? 'tick' : 'soft'))
+ * useHapticFeedback(payment.status, (_, status) => status === 'paid' ? 'success' : status === 'failed' && 'error')
+ * ```
+ */
+export const useHapticFeedback = <T>(trigger: T, feedback: Haptic | HapticResolver<T>): void => {
+  const previous = useRef(trigger)
+
+  useEffect(() => {
+    const before = previous.current
+
+    if (Object.is(before, trigger)) {
+      return
+    }
+
+    previous.current = trigger
+    const haptic = typeof feedback === 'function' ? feedback(before, trigger) : feedback
+
+    if (haptic) {
+      haptics.play(haptic)
+    }
+  }, [feedback, trigger])
+}

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from './atoms'
+export * from './haptics'
 export * from './molecules'
 export * from './organisms'
 export * from './templates'

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
 }