@hzblj/kara-components 0.6.0 → 0.8.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.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.android.tsx

@@ -1,5 +1,43 @@
-import {GlassFallback} from './glass-fallback'
+import {BackdropBlurView} from '@hzblj/kara-native/jetpack-compose'
+import {useSx} from '@hzblj/kara-sx'
+import {radii, useAppTheme, withOpacity} from '@hzblj/kara-theme'
+
 import type {GlassViewComponent, GlassViewProps} from './glass-view.types'
 
-/** Android has no Liquid Glass, so this is always the fallback capsule. */
-export const GlassView: GlassViewComponent = (props: GlassViewProps) => <GlassFallback {...props} />
+/** dp. Strong enough that a photo behind reads as colour and light, not as detail. */
+const BLUR_RADIUS = 16
+
+/**
+ * Frosted glass, Android's way: what lies behind the capsule, blurred (Android 12+), under a tonal Material surface
+ * and a light hairline — the blurred surfaces Android 16 gives its own system UI, not a copy of iOS's lens. Without a
+ * tint it is the surface colour, translucent, so the content keeps its usual colours on it; a tint fills it with that
+ * colour instead. Below Android 12, with nothing to blur, the same colours are drawn near-opaque. Android has no swell,
+ * so `interactive` changes nothing here — the `Pressable` around it gives the press its feedback.
+ */
+export const GlassView: GlassViewComponent = ({
+  children,
+  interactive: _interactive,
+  testID,
+  tint,
+  ...sx
+}: GlassViewProps) => {
+  const theme = useAppTheme()
+  const style = useSx(sx)
+  const base = String(theme.color(tint ?? 'surface.primary'))
+
+  return (
+    <BackdropBlurView
+      blurRadius={BLUR_RADIUS}
+      cornerRadius={radii.full}
+      fallbackTint={withOpacity(base, 'o95')}
+      glassTint={withOpacity(base, tint ? 'o85' : 'o50')}
+      hairlineColor={withOpacity(String(theme.color('content.on.bg')), theme.dark ? 'o20' : 'o60')}
+      hairlineWidth={1}
+      saturation={1.6}
+      style={style}
+      testID={testID}
+    >
+      {children}
+    </BackdropBlurView>
+  )
+}

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

@@ -3,17 +3,25 @@ import type {ColorToken} from '@hzblj/kara-theme'
 import type {ReactNode} from 'react'
 
 /**
- * iOS 26 Liquid Glass around a React Native subtree, shaped as a capsule — the React Native tier, so it needs no host
- * and costs next to nothing in a list cell. Where there is no Liquid Glass (Android, and iOS before 26) it draws a
- * capsule of `tint` instead, or of the glass buttons' translucent fill (`btn.bg.glass.base`) when there is none.
+ * Glass around a React Native subtree, shaped as a capsule — the React Native tier, so it needs no host. iOS 26:
+ * Liquid Glass. Android: frosted glass — what lies behind, blurred on Android 12+, under a translucent tonal surface
+ * (or `tint`) and a hairline. iOS before 26 has no Liquid Glass and draws a capsule of `tint` instead, or of the glass
+ * buttons' translucent fill (`btn.bg.glass.base`) when there is none.
+ *
+ * On Android each glass re-records what lies behind it before every frame: a few buttons cost nothing, but keep it out
+ * of the cells of a long list — a plain `tint` reads as well there.
  */
 export type GlassViewProps = ResponsiveViewSx & {
   /** React Native views. Give them `pointerEvents="none"` when `interactive`, so the press reaches the `Pressable`. */
   children?: ReactNode
-  /** Swells toward the finger on touch, carrying the children with it. Wrap the view in a `Pressable` for the press. */
+  /**
+   * iOS 26: swells toward the finger on touch, carrying the children with it. Android has no swell: wrap the view in a
+   * `Pressable` with `borderRadius="full"`, whose ripple then keeps to the capsule. The press is always the `Pressable`'s.
+   */
   interactive?: boolean
+  /** Test identifier, forwarded to the view. */
   testID?: string
-  /** Tints the material. Unset leaves it clear. */
+  /** Tints the material. Unset leaves it clear on iOS, and the translucent surface colour on Android. */
   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/image/image.tsx

@@ -1,15 +1,14 @@
+import {sx} from '@hzblj/kara-sx'
 import {duration} from '@hzblj/kara-theme'
-import {Image as ExpoImage, ImageProps} from 'expo-image'
-import {FC} from 'react'
+import {Image as ExpoImage, type ImageProps as ExpoImageProps} from 'expo-image'
+import type {Ref} from 'react'
 
-const Image: FC<ImageProps> = props => (
-  <ExpoImage
-    transition={{
-      duration: duration.d100,
-      timing: 'linear',
-    }}
-    {...props}
-  />
-)
+const FADE = {duration: duration.d100, timing: 'linear'} as const
 
-export {Image}
+const FadingImage = (props: ExpoImageProps & {ref?: Ref<ExpoImage>}) => <ExpoImage transition={FADE} {...props} />
+
+/**
+ * `expo-image` with the `sx` props, the way `Box` is a `View` with them, and the design system's 100 ms linear fade
+ * already applied, so a loaded image never pops in. An explicit `transition` wins, and so does an explicit `style`.
+ */
+export const Image = sx(FadingImage)

package/src/atoms/image/image.types.ts

@@ -0,0 +1,6 @@
+import type {ComponentProps} from 'react'
+
+import type {Image} from './image'
+
+/** Derived from the component itself, so it cannot drift from what `sx(Image)` actually accepts. */
+export type ImageProps = ComponentProps<typeof Image>

package/src/atoms/image/index.ts

@@ -1 +1,2 @@
 export * from './image'
+export * from './image.types'

package/src/atoms/index.ts

@@ -1,6 +1,7 @@
 export * from './activity-indicator'
 export * from './avatar'
 export * from './badge'
+export * from './blur-view'
 export * from './box'
 export * from './button'
 export * from './card'
@@ -10,7 +11,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.android.tsx

@@ -1,4 +1,5 @@
 import {Host} from '@expo/ui/jetpack-compose'
+import {useSx} from '@hzblj/kara-sx'
 import {useAppTheme} from '@hzblj/kara-theme'
 
 import {HostBoundary} from '../../host-context'
@@ -8,15 +9,22 @@ const MATCH_HEIGHT_ONLY = {horizontal: false, vertical: true}
 
 const MATCH_NEITHER = {horizontal: false, vertical: false}
 
-export const Island: IslandComponent = ({children, matchContents = true, style}: IslandProps) => {
+export const Island: IslandComponent = ({
+  children,
+  matchContents = true,
+  style,
+  testID: _testID,
+  ...sx
+}: IslandProps) => {
   const theme = useAppTheme()
+  const resolved = useSx(sx)
 
   return (
     <Host
       colorScheme={theme.dark ? 'dark' : 'light'}
       matchContents={matchContents ? MATCH_HEIGHT_ONLY : MATCH_NEITHER}
       seedColor={theme.materialSeed}
-      style={style}
+      style={style ? [resolved, style] : resolved}
     >
       <HostBoundary>{children}</HostBoundary>
     </Host>

package/src/atoms/island/island.ios.tsx

@@ -1,5 +1,6 @@
 import {Host} from '@expo/ui/swift-ui'
 import {dynamicTypeSize} from '@expo/ui/swift-ui/modifiers'
+import {useSx} from '@hzblj/kara-sx'
 import {MAX_DYNAMIC_TYPE_SIZE, useAppTheme} from '@hzblj/kara-theme'
 
 import {HostBoundary} from '../../host-context'
@@ -11,8 +12,9 @@ const MATCH_HEIGHT_ONLY = {horizontal: false, vertical: true}
 
 const MATCH_NEITHER = {horizontal: false, vertical: false}
 
-export const Island: IslandComponent = ({children, matchContents = true, style, testID}: IslandProps) => {
+export const Island: IslandComponent = ({children, matchContents = true, style, testID, ...sx}: IslandProps) => {
   const theme = useAppTheme()
+  const resolved = useSx(sx)
 
   return (
     <Host
@@ -20,7 +22,7 @@ export const Island: IslandComponent = ({children, matchContents = true, style,
       matchContents={matchContents ? MATCH_HEIGHT_ONLY : MATCH_NEITHER}
       modifiers={DYNAMIC_TYPE_CAP}
       seedColor={theme.materialSeed}
-      style={style}
+      style={style ? [resolved, style] : resolved}
       testID={testID}
     >
       <HostBoundary>{children}</HostBoundary>

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

@@ -1,7 +1,13 @@
+import type {ResponsiveViewSx} from '@hzblj/kara-sx'
 import type {ReactNode} from 'react'
 import type {StyleProp, ViewStyle} from 'react-native'
 
-export type IslandProps = {
+/**
+ * A host for native atoms in a React Native layout — the SwiftUI / Compose `Host` an `@expo/ui` tree mounts into. It
+ * sits in that layout like a `Box`, and takes `Box`'s `sx` props for it: `h`, `flex`, margins.
+ */
+export type IslandProps = ResponsiveViewSx & {
+  /** 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
@@ -9,13 +15,15 @@ export type IslandProps = {
    * width maps to `fixedSize(horizontal: true)`, so the native side ignores the proposed width and
    * resolves a `wide` stack's ideal width as unbounded.
    *
-   * Turn it off — and give the island an explicit size via `style` — when the subtree contains an
+   * Turn it off — and give the island an explicit height, `h` — when the subtree contains an
    * `RnView`: that host drives its SwiftUI frame from the child's Yoga-laid-out bounds while this one
    * writes its measured size back into the Yoga style, and the two together spin a layout loop that
    * hangs the main thread as soon as the views lay out on screen.
    */
   matchContents?: boolean
+  /** A React Native style for the host view, merged over the `sx` props — for what they cannot say. */
   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,9 +1,11 @@
 import {useSplitSx} from '@hzblj/kara-sx'
-import {useCallback} from 'react'
-import {Pressable as RNPressable} from 'react-native'
+import {useAppTheme, withOpacity} from '@hzblj/kara-theme'
+import {useCallback, useMemo} from 'react'
+import {Platform, Pressable as RNPressable, View, type ViewStyle} from 'react-native'
 import Animated, {useAnimatedStyle, useSharedValue, withSpring} from 'react-native-reanimated'
 
 import {haptics} from '../../haptics'
+import {splitForRipple} from '../../ripple-clip'
 import type {PressableComponent, PressableProps} from './pressable.types'
 
 const SPRING = {damping: 20, stiffness: 400}
@@ -22,20 +24,39 @@ export const Pressable: PressableComponent = ({
   const scale = useSharedValue(1)
   const feedback = haptic === true ? 'light' : haptic || undefined
 
+  const theme = useAppTheme()
+  const isAndroid = Platform.OS === 'android'
+
   const rStyle = useAnimatedStyle(() => ({transform: [{scale: scale.value}]}), [])
 
+  // Android's press is Material's: a ripple over the content — the pressed state layer, `onSurface` at 10 % — clipped to
+  // the shape by an outer view (`splitForRipple`), and nothing moves. iOS springs down.
+  const ripple = useMemo(
+    () =>
+      isAndroid ? {color: withOpacity(String(theme.color('content.primary')), 'o10'), foreground: true} : undefined,
+    [isAndroid, theme]
+  )
+  const androidStyle = useMemo(
+    () => (isAndroid ? splitForRipple(resolved as ViewStyle) : undefined),
+    [isAndroid, resolved]
+  )
+
   // 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)
+    if (!isAndroid) {
+      scale.value = withSpring(0.96, SPRING)
+    }
 
     if (feedback) {
       haptics.prepare(feedback)
     }
-  }, [feedback, scale])
+  }, [feedback, isAndroid, scale])
 
   const onPressOut = useCallback(() => {
-    scale.value = withSpring(1, SPRING)
-  }, [scale])
+    if (!isAndroid) {
+      scale.value = withSpring(1, SPRING)
+    }
+  }, [isAndroid, scale])
 
   const onPressWithHaptic = useCallback(() => {
     if (feedback) {
@@ -45,6 +66,25 @@ export const Pressable: PressableComponent = ({
     onPress?.()
   }, [feedback, onPress])
 
+  if (androidStyle) {
+    return (
+      <View style={androidStyle.outer}>
+        <RNPressable
+          android_ripple={ripple}
+          disabled={disabled}
+          hitSlop={8}
+          onPress={onPressWithHaptic}
+          onPressIn={onPressIn}
+          style={androidStyle.inner}
+          testID={testID}
+          {...rest}
+        >
+          {children}
+        </RNPressable>
+      </View>
+    )
+  }
+
   return (
     <AnimatedPressable
       disabled={disabled}

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

@@ -3,12 +3,22 @@ import type {ReactNode} from 'react'
 
 import type {Haptic} from '../../haptics'
 
+/**
+ * React Native's `Pressable`, styled through `sx` like a `Box`, taking touches 8 points past its edges. The press is
+ * each platform's own: iOS springs it down to 96%; Android draws Material's ripple over the content, clipped to the
+ * pressable's shape — give it the `borderRadius` of what it wraps (`full` around a `GlassView`). 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 or ripple. */
   disabled?: 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
 }