@hzblj/kara-components 0.9.0 → 0.10.0

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

@@ -5,16 +5,16 @@ import type {ReactNode} from 'react'
 export type {BlurMaterial, BlurVibrancy} from '@hzblj/kara-native/swift-ui'
 
 /**
- * One of the system's materials behind React Native content — what sheets, bars, menus and HUDs are made of, in
+ * One of the system's materials (what sheets, bars, menus and HUDs are made of) behind React Native content, in
  * SwiftUI's five thicknesses. iOS: UIKit's `system*Material` blur, with optional vibrancy for the content. Android:
- * what lies behind, blurred and saturated (Android 12+), under a Material tonal surface as thick as the material —
- * `surface` at `ultraThin` up to `surfaceContainerHighest` at `ultraThick`; below Android 12 the surface alone. The
+ * what lies behind, blurred and saturated (Android 12+), under a Material tonal surface as thick as the material
+ * (`surface` at `ultraThin` up to `surfaceContainerHighest` at `ultraThick`); below Android 12 the surface alone. The
  * React Native tier: it needs no host, so it suits a list cell. Shape it with `borderRadius`; it clips its children.
  */
 export type BlurViewProps = ResponsiveViewSx & {
   /**
-   * Pins the material to light or dark whatever the app's appearance — a dark HUD over a light screen. Unset, it follows
-   * the app theme. Android draws the opposite appearance with Material's inverse surface.
+   * Pins the material to light or dark whatever the app's appearance (a dark HUD over a light screen). Unset, it
+   * follows the app theme. Android draws the opposite appearance with Material's inverse surface.
    */
   appearance?: 'dark' | 'light'
   /** React Native content, over the material. */
@@ -24,7 +24,7 @@ export type BlurViewProps = ResponsiveViewSx & {
   /** Test identifier, forwarded to the view. */
   testID?: string
   /**
-   * iOS: draws the children vibrant at this level, the way iOS draws its own labels and fills on a material — their
+   * iOS: draws the children vibrant at this level, the way iOS draws its own labels and fills on a material. Their
    * colour becomes the material's vibrant one and their alpha the mask. Android has no vibrancy: the children keep
    * their colours there.
    */

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

@@ -4,7 +4,7 @@ import type {ReactNode} from 'react'
 export type ButtonVariant = 'accent' | 'destructive' | 'glass' | 'secondary'
 
 /**
- * SwiftUI `ButtonStyle`. iOS only — Compose has no equivalent, so Android ignores it and keeps
+ * SwiftUI `ButtonStyle`. iOS only: Compose has no equivalent, so Android ignores it and keeps
  * rendering the variant's tokens.
  */
 export type ButtonStyleName =
@@ -17,19 +17,19 @@ export type ButtonStyleName =
   | 'plain'
 
 /**
- * SwiftUI `ControlSize`. iOS only, and it has no `automatic` member — leave it unset to inherit
+ * SwiftUI `ControlSize`. iOS only, and it has no `automatic` member: leave it unset to inherit
  * whatever the surrounding SwiftUI environment provides.
  */
 export type ButtonControlSize = 'extraLarge' | 'large' | 'mini' | 'regular' | 'small'
 
-/** A text button — SwiftUI `Button` on iOS, Material's filled button (outlined for `glass`) on Android. */
+/** A text button: SwiftUI `Button` on iOS, Material's filled button (outlined for `glass`) on Android. */
 export type ButtonProps = {
   /**
-   * Replaces the style the variant picks — `borderedProminent` for `accent` and `destructive`, `bordered` for
-   * `secondary`, `glass` for `glass`. iOS only — Android ignores it.
+   * Replaces the style the variant picks: `borderedProminent` for `accent` and `destructive`, `bordered` for
+   * `secondary`, `glass` for `glass`. iOS only. Android ignores it.
    */
   buttonStyle?: ButtonStyleName
-  /** SwiftUI's control size. `large` by default. iOS only — Android ignores it. */
+  /** SwiftUI's control size. `large` by default. iOS only. Android ignores it. */
   controlSize?: ButtonControlSize
   /** Draws the button in its disabled colours and stops it responding to presses. */
   disabled?: boolean
@@ -42,7 +42,7 @@ export type ButtonProps = {
   /**
    * Overrides the variant's own tint. A prominent style takes it as the fill and picks a contrasting
    * label. `glass` has to reach the material through `glassEffect` instead, so tinting one costs it
-   * the stock `.glass` style — see the iOS implementation.
+   * the stock `.glass` style (see the iOS implementation).
    */
   tint?: ColorToken
   /** The look. `accent` by default. Material has no glass, so on Android `glass` is an outlined button. */

package/src/atoms/card/card.types.ts

@@ -2,7 +2,7 @@ import type {ResponsiveSx} from '@hzblj/kara-sx'
 import type {ReactNode} from 'react'
 
 /**
- * A raised container — SwiftUI `VStack` / Compose `Column` on `surface.primary`, with a large radius, `s16` padding and
+ * A raised container: SwiftUI `VStack` / Compose `Column` on `surface.primary`, with a large radius, `s16` padding and
  * the `card` shadow. Any `sx` prop overrides its default.
  */
 export type CardProps = ResponsiveSx & {

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

@@ -1,6 +1,6 @@
 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`. */
+/** 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
@@ -8,7 +8,7 @@ export type CheckboxProps = {
   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`. */
+  /** Whether it is checked. Controlled: update it from `onValueChange`. */
   value: boolean
 }
 

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

@@ -1,6 +1,6 @@
 import type {ReactNode} from 'react'
 
-/** A filter pill on a `Pressable`, not a native control — the React Native tier, so it needs no host. */
+/** A filter pill on a `Pressable`, not a native control. It belongs to the React Native tier, so it needs no host. */
 export type ChipProps = {
   /** The text in the pill. */
   label: string

package/src/atoms/color-picker/color-picker.android.tsx

@@ -1,9 +1,29 @@
-import {warnUnsupported} from '../../platform-support'
-import type {ColorPickerComponent} from './color-picker.types'
+import {ColorWell} from '@hzblj/kara-native/jetpack-compose'
 
-/** Compose has no colour picker, and there is nothing sane to degrade a colour wheel into. */
-export const ColorPicker: ColorPickerComponent = () => {
-  warnUnsupported('ColorPicker', 'Android')
+import {useHostGuard} from '../../host-context'
+import {HStack} from '../h-stack'
+import {Spacer} from '../spacer'
+import {Text} from '../text'
+import type {ColorPickerComponent, ColorPickerProps} from './color-picker.types'
 
-  return null
+/**
+ * The row SwiftUI's `ColorPicker` lays out on iOS, the label leading and the well trailing, around kara's own Compose
+ * well: Compose ships no colour picker, so the sheet behind it draws the iOS picker's grid, spectrum and sliders.
+ */
+export const ColorPicker: ColorPickerComponent = ({
+  label,
+  onValueChange,
+  supportsOpacity = false,
+  testID,
+  value,
+}: ColorPickerProps) => {
+  useHostGuard('ColorPicker')
+
+  return (
+    <HStack align="center" spacing="s12" testID={testID} wide>
+      {label ? <Text>{label}</Text> : null}
+      <Spacer />
+      <ColorWell onValueChange={onValueChange} supportsOpacity={supportsOpacity} title={label} value={value} />
+    </HStack>
+  )
 }

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

@@ -1,11 +1,12 @@
 import type {ReactNode} from 'react'
 
 /**
- * The system colour picker. iOS only — Compose ships no equivalent, so on Android this
- * renders nothing and says so in dev. Branch on `Platform.OS` if the screen needs a fallback.
+ * A row with a label and a colour well that opens a picker: SwiftUI's `ColorPicker` on iOS. Compose ships none, so on
+ * Android it is kara's own, in the same shape: a well with a rainbow ring, and a sheet with a grid of swatches, a
+ * spectrum and RGB sliders.
  */
 export type ColorPickerProps = {
-  /** Text beside the colour well. */
+  /** Text beside the colour well, and the Android sheet's title. */
   label?: string
   /** Called with the colour the user picks. */
   onValueChange?: (color: string) => void

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

@@ -3,7 +3,7 @@ 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
+ * 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`.
  */
@@ -17,11 +17,11 @@ export type DatePickerProps = {
    * `value`'s time of day.
    */
   mode?: DatePickerMode
-  /** Called with the new date — on iOS as it changes, on Android when the dialog is confirmed. */
+  /** 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. */
+  /** Test identifier, on the native picker on iOS and on the tappable field on Android. */
   testID?: string
-  /** The selected date. Controlled — update it from `onValueChange`. */
+  /** The selected date. Controlled: update it from `onValueChange`. */
   value: Date
 }
 

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

@@ -1,11 +1,11 @@
 import type {ColorToken} from '@hzblj/kara-theme'
 import type {ReactNode} from 'react'
 
-/** A horizontal hairline — SwiftUI `Divider` / Compose `HorizontalDivider`. */
+/** 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. */
+  /** Test identifier, forwarded to the native view on iOS. Android ignores it. */
   testID?: string
 }
 

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

@@ -3,7 +3,7 @@ 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
+ * 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 = {
@@ -11,7 +11,7 @@ export type FabProps = {
   name: IconName
   /** Called when the button is pressed. */
   onPress?: () => void
-  /** Test identifier, forwarded to the native view on iOS — Android ignores it. */
+  /** Test identifier, forwarded to the native view on iOS. Android ignores it. */
   testID?: string
 }
 

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

@@ -3,13 +3,13 @@ import type {ColorToken} from '@hzblj/kara-theme'
 import type {ReactNode} from 'react'
 
 /**
- * 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.
+ * Glass around a React Native subtree, shaped as a capsule. It belongs to the React Native tier, so it needs no host.
+ * iOS 26: Liquid Glass. Android: frosted glass, made of 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.
+ * 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`. */

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

@@ -4,13 +4,13 @@ import type {ReactNode} from 'react'
 
 export type HStackAlign = 'center' | 'end' | 'start'
 
-/** A horizontal stack — SwiftUI `HStack` / Compose `Row`. */
+/** 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. */
+  /** 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. */
+  /** 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

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

@@ -13,13 +13,13 @@ declare global {
 type DeclaredIconName = keyof KaraIcons & string
 
 /**
- * One of the app's icons. Once the plugin has written `kara-icons.d.ts` only those names type-check — an icon removed
+ * One of the app's icons. Once the plugin has written `kara-icons.d.ts` only those names type-check: an icon removed
  * from the folder fails at every call site. Before that, any string, so a project can adopt icons gradually.
  */
 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
+ * 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 = {
@@ -27,11 +27,11 @@ export type IconProps = {
   accessibilityLabel?: string
   /** The icon's tint. `content.primary` by default. */
   color?: ColorToken
-  /** Which of the app's icons — a key of `KaraIcons`. */
+  /** 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. */
+  /** Test identifier, forwarded to the native view on iOS. Android ignores it. */
   testID?: string
 }
 

package/src/atoms/icon-button/icon-button.ios.tsx

@@ -1,11 +1,18 @@
 import {Button} from '@expo/ui/swift-ui'
-import {buttonStyle, disabled as disabledModifier} from '@expo/ui/swift-ui/modifiers'
+import {buttonStyle, contentShape, disabled as disabledModifier, shapes} from '@expo/ui/swift-ui/modifiers'
 import {useMemo} from 'react'
 
 import {useHostGuard} from '../../host-context'
 import {Icon} from '../icon'
+import {ZStack} from '../z-stack'
 import type {IconButtonComponent, IconButtonProps} from './icon-button.types'
 
+/** Apple's least tap target. Android's `IconButton` is Material's 48dp; this is the same idea in points. */
+const TARGET = 44
+
+/** The whole square takes the tap, not only the glyph's own pixels. */
+const WHOLE_TARGET = {modifiers: [contentShape(shapes.circle())]}
+
 export const IconButton: IconButtonComponent = ({disabled = false, name, onPress, testID}: IconButtonProps) => {
   useHostGuard('IconButton')
 
@@ -21,7 +28,10 @@ export const IconButton: IconButtonComponent = ({disabled = false, name, onPress
 
   return (
     <Button modifiers={modifiers} onPress={onPress} testID={testID}>
-      <Icon color={disabled ? 'btn.content.disabled' : 'content.primary'} name={name} />
+      <ZStack h={TARGET} ios={WHOLE_TARGET} w={TARGET}>
+        {/* SwiftUI dims a disabled button's label itself; a disabled colour on top of that dimmed it twice. */}
+        <Icon color="content.primary" name={name} />
+      </ZStack>
     </Button>
   )
 }

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

@@ -2,15 +2,19 @@ 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. */
+/**
+ * A button that is just an icon: a plain SwiftUI `Button` on iOS, Material's `IconButton` on Android. The icon sits
+ * centred in a tap target the size each platform asks for, 44pt on iOS and 48dp on Android, so a row of them spaces
+ * itself the same way on both.
+ */
 export type IconButtonProps = {
-  /** Draws the icon in `btn.content.disabled` and stops the button responding to presses. */
+  /** Dims the icon (iOS's own disabled look, `btn.content.disabled` on Android) and stops the button responding. */
   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. */
+  /** Test identifier, forwarded to the native view on iOS. Android ignores it. */
   testID?: string
 }
 

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

@@ -3,7 +3,7 @@ import type {ReactNode} from 'react'
 import type {StyleProp, ViewStyle} from 'react-native'
 
 /**
- * A host for native atoms in a React Native layout — the SwiftUI / Compose `Host` an `@expo/ui` tree mounts into. It
+ * 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 & {
@@ -15,15 +15,15 @@ export type IslandProps = ResponsiveViewSx & {
    * 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 height, `h` — 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. */
+  /** 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. */
+  /** Test identifier, forwarded to the host view on iOS. Android ignores it. */
   testID?: string
 }
 

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

@@ -1,23 +1,23 @@
 import type {ReactNode} from 'react'
 
 /**
- * A scrolling list — SwiftUI `List`, Compose `LazyColumn`. It has no height of its own, so it needs one from outside:
+ * A scrolling list: SwiftUI `List`, Compose `LazyColumn`. It has no height of its own, so it needs one from outside:
  * a `Screen`, or an `Island` with `matchContents={false}` and a height. In an island that sizes itself to its content
  * Compose measures it against an infinite height and throws ("Vertically scrollable component was measured with an
  * infinity maximum height"); SwiftUI shows nothing. For a handful of rows that should not scroll, use a `VStack`.
  *
- * Rows are separated for you — SwiftUI's own separators, a `Divider` between rows on Android — so a `Divider` among
+ * Rows are separated for you (SwiftUI's own separators, a `Divider` between rows on Android), so a `Divider` among
  * 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. */
+  /** The rows: native views, one row each. */
   children: ReactNode
   /**
-   * Enables pull-to-refresh. Async on purpose — see `ScrollViewProps.onRefresh`: the spinner runs
+   * 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. */
+  /** Test identifier, forwarded to the native view on iOS. Android ignores it. */
   testID?: string
 }
 

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

@@ -9,7 +9,7 @@ export type PickerOption = {
 }
 
 /**
- * A single choice from a list — a SwiftUI wheel picker on iOS, Material's exposed dropdown on Android. It brings its
+ * 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 = {

package/src/atoms/pressable/pressable.tsx

@@ -1,8 +1,8 @@
 import {useSplitSx} from '@hzblj/kara-sx'
-import {useAppTheme, withOpacity} from '@hzblj/kara-theme'
+import {duration, opacity, 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 {Platform, Pressable as RNPressable, type ViewStyle} from 'react-native'
+import Animated, {useAnimatedStyle, useSharedValue, withSpring, withTiming} from 'react-native-reanimated'
 
 import {haptics} from '../../haptics'
 import {splitForRipple} from '../../ripple-clip'
@@ -10,6 +10,12 @@ import type {PressableComponent, PressableProps} from './pressable.types'
 
 const SPRING = {damping: 20, stiffness: 400}
 
+/** A dim comes in quickly and leaves a little slower, as UIKit's own highlight does. */
+const DIM_IN = {duration: duration.d100}
+const DIM_OUT = {duration: duration.d200}
+
+const PLATFORM_EFFECT = Platform.OS === 'ios' ? 'scale' : 'none'
+
 const AnimatedPressable = Animated.createAnimatedComponent(RNPressable)
 
 export const Pressable: PressableComponent = ({
@@ -17,24 +23,38 @@ export const Pressable: PressableComponent = ({
   disabled = false,
   haptic = false,
   onPress,
+  pressEffect = PLATFORM_EFFECT,
+  pressedOpacity = 'o60',
+  pressedScale = 0.96,
+  ripple: withRipple = true,
   testID,
   ...props
 }: PressableProps) => {
   const [resolved, rest] = useSplitSx(props)
-  const scale = useSharedValue(1)
+  // 0 at rest, 1 held: one value drives whichever effect is picked, so a change of effect needs no second animation.
+  const pressed = useSharedValue(0)
   const feedback = haptic === true ? 'light' : haptic || undefined
+  const dimmed = opacity[pressedOpacity]
 
   const theme = useAppTheme()
   const isAndroid = Platform.OS === 'android'
 
-  const rStyle = useAnimatedStyle(() => ({transform: [{scale: scale.value}]}), [])
+  const rStyle = useAnimatedStyle(() => {
+    if (pressEffect === 'scale') {
+      return {transform: [{scale: 1 - (1 - pressedScale) * pressed.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.
+    return pressEffect === 'opacity' ? {opacity: 1 - (1 - dimmed) * pressed.value} : {}
+  }, [dimmed, pressEffect, pressedScale])
+
+  // 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`). The effect, when there is one, moves that outer view, ripple and all.
   const ripple = useMemo(
     () =>
-      isAndroid ? {color: withOpacity(String(theme.color('content.primary')), 'o10'), foreground: true} : undefined,
-    [isAndroid, theme]
+      isAndroid && withRipple
+        ? {color: withOpacity(String(theme.color('content.primary')), 'o10'), foreground: true}
+        : undefined,
+    [isAndroid, theme, withRipple]
   )
   const androidStyle = useMemo(
     () => (isAndroid ? splitForRipple(resolved as ViewStyle) : undefined),
@@ -43,20 +63,20 @@ export const Pressable: PressableComponent = ({
 
   // The finger is down: the Taptic Engine has until the release to wake, so the haptic lands with the press.
   const onPressIn = useCallback(() => {
-    if (!isAndroid) {
-      scale.value = withSpring(0.96, SPRING)
+    if (pressEffect === 'scale') {
+      pressed.value = withSpring(1, SPRING)
+    } else if (pressEffect === 'opacity') {
+      pressed.value = withTiming(1, DIM_IN)
     }
 
     if (feedback) {
       haptics.prepare(feedback)
     }
-  }, [feedback, isAndroid, scale])
+  }, [feedback, pressEffect, pressed])
 
   const onPressOut = useCallback(() => {
-    if (!isAndroid) {
-      scale.value = withSpring(1, SPRING)
-    }
-  }, [isAndroid, scale])
+    pressed.value = pressEffect === 'scale' ? withSpring(0, SPRING) : withTiming(0, DIM_OUT)
+  }, [pressEffect, pressed])
 
   const onPressWithHaptic = useCallback(() => {
     if (feedback) {
@@ -68,20 +88,21 @@ export const Pressable: PressableComponent = ({
 
   if (androidStyle) {
     return (
-      <View style={androidStyle.outer}>
+      <Animated.View style={[androidStyle.outer, rStyle]}>
         <RNPressable
           android_ripple={ripple}
           disabled={disabled}
           hitSlop={8}
           onPress={onPressWithHaptic}
           onPressIn={onPressIn}
+          onPressOut={onPressOut}
           style={androidStyle.inner}
           testID={testID}
           {...rest}
         >
           {children}
         </RNPressable>
-      </View>
+      </Animated.View>
     )
   }
 

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

@@ -1,23 +1,40 @@
 import type {ResponsiveViewSx} from '@hzblj/kara-sx'
+import type {OpacitySize} from '@hzblj/kara-theme'
 import type {ReactNode} from 'react'
 
 import type {Haptic} from '../../haptics'
 
+/** How the content answers a press: it springs down, it dims, or it stays still. */
+export type PressEffect = 'none' | 'opacity' | 'scale'
+
 /**
- * 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.
+ * React Native's `Pressable`, styled through `sx` like a `Box`, taking touches 8 points past its edges. Each platform
+ * presses its own way by default: iOS springs the content down to 96%, Android draws Material's ripple over it,
+ * clipped to the pressable's shape. `pressEffect` picks the same answer on both, and Android keeps its ripple on top
+ * unless `ripple` is off. 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. */
+  /** Ignores presses: no `onPress`, no haptic, no press effect 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
+  /**
+   * How the content answers while it is held. `scale` springs it down to `pressedScale`, `opacity` dims it to
+   * `pressedOpacity`, `none` leaves it still. `scale` on iOS and `none` on Android by default, where the ripple is the
+   * press.
+   */
+  pressEffect?: PressEffect
+  /** What `opacity` dims to, an opacity token. `o60` by default. */
+  pressedOpacity?: OpacitySize
+  /** What `scale` springs down to. `0.96` by default. */
+  pressedScale?: number
+  /** Android's ripple: Material's pressed state layer over the content, clipped to the shape. On by default. iOS has none. */
+  ripple?: boolean
   /** Test identifier, forwarded to the view. */
   testID?: string
 }

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

@@ -1,7 +1,7 @@
 import type {ReactNode} from 'react'
 
 /**
- * A progress bar or ring, tinted `fill.accent.primary` — SwiftUI `ProgressView` (a capacity `Gauge` for a ring with a
+ * A progress bar or ring, tinted `fill.accent.primary`: SwiftUI `ProgressView` (a capacity `Gauge` for a ring with a
  * value, which `ProgressView` cannot draw on iOS) / Compose's `LinearProgressIndicator` and `CircularProgressIndicator`.
  */
 export type ProgressProps = {

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

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

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

@@ -2,7 +2,7 @@ import type {ReactNode} from 'react'
 
 import type {IconProps} from '../icon'
 
-/** The same contract as `Icon`, for the React Native tier — anywhere, no `Screen` or `Island` needed. */
+/** The same contract as `Icon`, for the React Native tier: anywhere, no `Screen` or `Island` needed. */
 export type RnIconProps = IconProps
 
 export type RnIconComponent = (props: RnIconProps) => ReactNode