@hzblj/kara-components 0.8.0 → 0.10.0

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

@@ -1,5 +1,5 @@
-import {ProgressView} from '@expo/ui/swift-ui'
-import {progressViewStyle, tint} from '@expo/ui/swift-ui/modifiers'
+import {Gauge, ProgressView} from '@expo/ui/swift-ui'
+import {gaugeStyle, progressViewStyle, tint} from '@expo/ui/swift-ui/modifiers'
 import {useAppTheme} from '@hzblj/kara-theme'
 import {useMemo} from 'react'
 
@@ -10,10 +10,19 @@ export const Progress: ProgressComponent = ({circular = false, value}: ProgressP
   useHostGuard('Progress')
   const theme = useAppTheme()
 
+  const ring = circular && value !== undefined
   const modifiers = useMemo(
-    () => [progressViewStyle(circular ? 'circular' : 'linear'), tint(theme.color('fill.accent.primary'))],
-    [circular, theme]
+    () => [
+      ring ? gaugeStyle('circularCapacity') : progressViewStyle(circular ? 'circular' : 'linear'),
+      tint(theme.color('fill.accent.primary')),
+    ],
+    [circular, ring, theme]
   )
 
-  return <ProgressView modifiers={modifiers} value={value ?? null} />
+  // SwiftUI's circular `ProgressView` ignores its value on iOS and spins; a ring that fills is a capacity `Gauge`.
+  return ring ? (
+    <Gauge modifiers={modifiers} value={value} />
+  ) : (
+    <ProgressView modifiers={modifiers} value={value ?? null} />
+  )
 }

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

@@ -1,8 +1,8 @@
 import type {ReactNode} from 'react'
 
 /**
- * A progress bar or ring, tinted `fill.accent.primary` — SwiftUI `ProgressView` / Compose's
- * `LinearProgressIndicator` and `CircularProgressIndicator`.
+ * 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 = {
   /** A circular indicator instead of a bar. Off by default. */

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

package/src/atoms/rn-scroll-view/rn-scroll-view.types.ts

@@ -4,7 +4,7 @@ import type {ScrollViewProps as RNScrollViewProps} from 'react-native'
 import type {ScrollViewAxis} from '../scroll-view'
 
 /**
- * React Native tier scroll container — the sibling of `RnView`/`RnText`. Use it when the
+ * React Native tier scroll container, the sibling of `RnView`/`RnText`. Use it when the
  * subtree is React Native and native atoms are embedded through `Island`. For a screen that
  * is native all the way down, reach for the `ScrollView` atom instead.
  *
@@ -17,7 +17,7 @@ export type RnScrollViewProps = ResponsiveViewSx &
     axis?: ScrollViewAxis
     /** The scrolling content. */
     children?: ReactNode
-    /** Styles the scrolling content container — padding and gap belong here. */
+    /** Styles the scrolling content container; padding and gap belong here. */
     content?: ResponsiveViewSx
     /** Shows the scroll indicators. On by default. */
     showsIndicators?: boolean

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

@@ -3,11 +3,11 @@ import type {DefaultSectionT, SectionListProps as RNSectionListProps} from 'reac
 
 /**
  * Top-level `sx` styles the viewport; `content` styles the scrolling content container, so padding and
- * gap belong there — the same split as `RnScrollView` and `RnFlatList`. `removeClippedSubviews` is off unless
+ * gap belong there (the same split as `RnScrollView` and `RnFlatList`). `removeClippedSubviews` is off unless
  * you turn it on, as in `RnFlatList`: Android's default would leave rows with hosts in them empty.
  */
 export type RnSectionListProps<TItem, TSection = DefaultSectionT> = ResponsiveViewSx &
   Omit<RNSectionListProps<TItem, TSection>, 'contentContainerStyle' | 'style'> & {
-    /** Styles the scrolling content container — padding and gap belong here. */
+    /** Styles the scrolling content container; padding and gap belong here. */
     content?: ResponsiveViewSx
   }

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

@@ -4,8 +4,8 @@ import type {ReactNode} from 'react'
 import type {TextProps as RNTextProps} from 'react-native'
 
 /**
- * React Native's `Text` in a theme typography variant — the React Native tier, for text outside a native host. It takes
- * `Box`'s `sx` surface for its own box — margins, flex, padding, a background — all but `align`, which here aligns the
+ * React Native's `Text` in a theme typography variant: the React Native tier, for text outside a native host. It takes
+ * `Box`'s `sx` surface for its own box (margins, flex, padding, a background), all but `align`, which here aligns the
  * lines.
  */
 export type RnTextProps = Omit<RNTextProps, 'style'> &

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

@@ -1,12 +1,12 @@
 import type {ReactElement, ReactNode} from 'react'
 
-/** Carries a React Native view into a SwiftUI or Compose tree — `@expo/ui`'s `RNHostView` on both platforms. */
+/** Carries a React Native view into a SwiftUI or Compose tree: `@expo/ui`'s `RNHostView` on both platforms. */
 export type RnViewProps = {
   /**
    * A single React Native *view*. It may not contain React Native text: a bare string becomes a
    * `RawText` node, which has no component view, so mounting it across the SwiftUI host boundary
    * fails the `RCTComponentViewFactory` assertion and takes the whole app down. `@expo/ui` states
-   * the rule itself in `ListItem.ios.tsx` — "SwiftUI hosts can't render bare strings" — and wraps
+   * the rule itself in `ListItem.ios.tsx` ("SwiftUI hosts can't render bare strings") and wraps
    * every raw string in a SwiftUI `Text` before it reaches a host. Do the same: use the `Text` atom
    * inside the host, and keep `RnText` outside it.
    */
@@ -16,7 +16,7 @@ export type RnViewProps = {
    * intrinsic size and would otherwise stretch to fill the SwiftUI parent.
    */
   matchContents?: boolean
-  /** Not forwarded on either platform — give the child its own `testID`. */
+  /** Not forwarded on either platform: give the child its own `testID`. */
   testID?: string
 }
 

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

@@ -5,7 +5,7 @@ import type {ReactNode} from 'react'
 export type ScrollViewAxis = 'horizontal' | 'vertical'
 
 /**
- * The `sx` props style the scrolling *content* container, not the viewport — `p` behaves
+ * The `sx` props style the scrolling *content* container, not the viewport: `p` behaves
  * like React Native's `contentContainerStyle` padding and scrolls with the content.
  */
 export type ScrollViewProps = ResponsiveSx & {
@@ -15,13 +15,13 @@ export type ScrollViewProps = ResponsiveSx & {
   children?: ReactNode
   /**
    * Enables pull-to-refresh. Async on purpose: the spinner runs until the promise settles, which is
-   * what SwiftUI's `refreshable` expects and what Compose's controlled indicator is driven from — so
+   * what SwiftUI's `refreshable` expects and what Compose's controlled indicator is driven from, so
    * neither platform needs a separate `refreshing` flag to be kept in sync by the caller.
    *
    * Only a vertical scroll view can be pulled; on a horizontal one both platforms ignore it.
    */
   onRefresh?: () => Promise<void>
-  /** iOS only — Compose exposes no indicator toggle, so Android always shows the native one. */
+  /** iOS only: Compose exposes no indicator toggle, so Android always shows the native one. */
   showsIndicators?: boolean
   /** The space between children. */
   spacing?: SpaceSize

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

@@ -1,7 +1,7 @@
 import type {ReactNode} from 'react'
 
 /**
- * A row of mutually exclusive segments, the selected one in the accent — kara's own `UISegmentedControl` on iOS,
+ * 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.
  */
@@ -9,13 +9,13 @@ 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.
+   * 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. */
+  /** 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

@@ -3,8 +3,8 @@ 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. Sized with the
- * `sx` names: `w`, `h`, `borderRadius`.
+ * A loading placeholder that pulses in `fill.quaternary`. It is a React Native view, so it needs no host. Sized with
+ * the `sx` names: `w`, `h`, `borderRadius`.
  */
 export type SkeletonProps = {
   /** The corner radius. `small` by default. */

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

@@ -1,7 +1,7 @@
 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)`. */
+/** 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

package/src/atoms/surface/surface.ios.tsx

@@ -6,7 +6,8 @@ import type {SurfaceComponent, SurfaceProps} from './surface.types'
 export const Surface: SurfaceComponent = ({children, glass = false, testID, ...sx}: SurfaceProps) => {
   useHostGuard('Surface')
 
-  const modifiers = useSxModifiers({borderRadius: 'large', p: 's16', ...sx})
+  // `surface.primary` unless told otherwise, as Material's `Surface` is on Android — without it a plain one drew nothing.
+  const modifiers = useSxModifiers({bg: 'surface.primary', borderRadius: 'large', p: 's16', ...sx})
   const content = (
     <VStack alignment="leading" modifiers={modifiers} testID={testID}>
       {children}

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

@@ -2,8 +2,8 @@ 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.
+ * A container on `surface.primary`, 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. */

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

@@ -5,7 +5,7 @@ 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
+   * 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

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

@@ -9,7 +9,7 @@ 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`. It takes
+ * SwiftUI `Text` / Compose `Text` in a theme typography variant. A native atom: outside a host, use `RnText`. It takes
  * the native `sx` surface too: padding, a frame (`wide` lines it up by `align`), a background, and the `ios` bucket's
  * `contentTransition`, `animation` and `monospacedDigit` for a number that changes in place.
  */

package/src/atoms/text-field/text-field.android.tsx

@@ -1,6 +1,7 @@
 import {Column, Text as ComposeText, OutlinedTextField, useNativeState} from '@expo/ui/jetpack-compose'
 import {useSxModifiers} from '@hzblj/kara-sx'
 import {useAppTheme} from '@hzblj/kara-theme'
+import {Glyph} from '../../glyph'
 import {useHostGuard} from '../../host-context'
 import type {TextFieldComponent, TextFieldProps} from './text-field.types'
 
@@ -17,12 +18,14 @@ export const TextField: TextFieldComponent = ({
   const theme = useAppTheme()
   const value = useNativeState(defaultValue)
   const modifiers = useSxModifiers({wide: true})
+  const invalid = Boolean(error)
+  const message = typeof error === 'string' && error ? error : undefined
 
   return (
     <Column verticalArrangement={{spacedBy: 4}}>
       {label ? (
         <ComposeText
-          color={theme.colorString(error ? 'content.destructive' : 'content.secondary')}
+          color={theme.colorString(invalid ? 'content.destructive' : 'content.secondary')}
           style={theme.typography.labelMedium}
         >
           {label}
@@ -30,7 +33,7 @@ export const TextField: TextFieldComponent = ({
       ) : null}
       <OutlinedTextField
         enabled={!disabled}
-        isError={error}
+        isError={invalid}
         modifiers={modifiers}
         onValueChange={onChangeText}
         singleLine={!multiline}
@@ -41,7 +44,20 @@ export const TextField: TextFieldComponent = ({
         }}
         value={value}
         visualTransformation={secure ? 'password' : 'none'}
-      />
+      >
+        {invalid ? (
+          <OutlinedTextField.TrailingIcon>
+            <Glyph color="content.destructive" name="error" />
+          </OutlinedTextField.TrailingIcon>
+        ) : null}
+        {message ? (
+          <OutlinedTextField.SupportingText>
+            <ComposeText color={theme.colorString('content.destructive')} style={theme.typography.footnote}>
+              {message}
+            </ComposeText>
+          </OutlinedTextField.SupportingText>
+        ) : null}
+      </OutlinedTextField>
     </Column>
   )
 }

package/src/atoms/text-field/text-field.ios.tsx

@@ -45,7 +45,8 @@ export const TextField: TextFieldComponent = ({
 }: TextFieldProps) => {
   useHostGuard('TextField')
   const text = useNativeState(defaultValue)
-  const tone = TONE[toneOf(disabled, error)]
+  const tone = TONE[toneOf(disabled, Boolean(error))]
+  const message = tone === TONE.error && typeof error === 'string' && error ? error : undefined
 
   const sxModifiers = useSxModifiers({
     bg: tone.bg,
@@ -85,6 +86,11 @@ export const TextField: TextFieldComponent = ({
           text={text}
         />
       )}
+      {message ? (
+        <Text color="content.destructive" variant="footnote">
+          {message}
+        </Text>
+      ) : null}
     </VStack>
   )
 }

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

@@ -1,16 +1,20 @@
 import type {ReactNode} from 'react'
 
 /**
- * An uncontrolled text field with an optional label above it — SwiftUI `TextField` (`SecureField` when `secure`) /
+ * 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. */
+  /** 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
+  /**
+   * Marks the field invalid: a destructive outline and label. A message is shown under the field as well (on Android
+   * as Material's supporting text, beside its error icon), so the error never rests on colour alone; Material's error
+   * colour is a pale red in dark mode. `true` marks it without a message.
+   */
+  error?: boolean | string
   /** Shown above the field, in `labelMedium`. */
   label?: string
   /** Wraps the text and grows the field to fit it. iOS ignores it when `secure`. */

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

@@ -4,7 +4,7 @@ import type {ReactNode} from 'react'
 
 export type VStackAlign = 'center' | 'end' | 'start'
 
-/** Stacks its children top to bottom — SwiftUI `VStack` / Compose `Column`. */
+/** Stacks its children top to bottom: SwiftUI `VStack` / Compose `Column`. */
 export type VStackProps = ResponsiveSx & {
   /** The children's horizontal alignment. `start` by default. */
   align?: VStackAlign

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

@@ -3,7 +3,7 @@ import type {ReactNode} from 'react'
 
 export type ZStackAlign = 'bottom' | 'center' | 'top'
 
-/** Layers its children on one another — SwiftUI `ZStack` / Compose `Box`. */
+/** 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

package/src/glyph/glyph-button.types.ts

@@ -1,7 +1,7 @@
 import type {GlyphName} from '@hzblj/kara-native'
 import type {ReactNode} from 'react'
 
-/** An icon button over one of kara's glyphs — for the controls its own components build (a stepper, a bar). */
+/** An icon button over one of kara's glyphs, for the controls its own components build (a stepper, a bar). */
 export type GlyphButtonProps = {
   accessibilityLabel?: string
   disabled?: boolean

package/src/glyph/glyph.types.ts

@@ -3,7 +3,7 @@ import type {ColorToken, SpaceSize} from '@hzblj/kara-theme'
 import type {ReactNode} from 'react'
 
 /**
- * One of the few glyphs kara's own components draw — a search field's magnifier, a row's chevron. Internal: apps draw
+ * One of the few glyphs kara's own components draw: a search field's magnifier, a row's chevron. Internal: apps draw
  * their own icons with `Icon` / `RnIcon`.
  */
 export type GlyphProps = {

package/src/molecules/collapsible/collapsible.types.ts

@@ -2,7 +2,7 @@ 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>`.
+ * chevron over an animated reveal. A native atom: it renders inside `<Screen>` or `<Island>`.
  */
 export type CollapsibleProps = {
   /** Shown while `expanded`. */

package/src/molecules/empty-state/empty-state.types.ts

@@ -6,7 +6,7 @@ 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. */
+  /** Under the text: a `Button`, say. */
   action?: ReactNode
   /** A second line under the title, in the secondary colour. */
   description?: string

package/src/molecules/label/label.types.ts

@@ -4,7 +4,7 @@ import type {ReactNode} from 'react'
 import type {IconName} from '../../atoms/icon'
 
 /**
- * An inline icon + text pair — the thing you put inside a button, a menu row or a section
+ * An inline icon + text pair: the thing you put inside a button, a menu row or a section
  * header. For a full tappable row with a subtitle and chevron, use `ListItem`.
  */
 export type LabelProps = {

package/src/molecules/labeled-content/labeled-content.types.ts

@@ -3,7 +3,7 @@ import type {ReactNode} from 'react'
 import type {IconName} from '../../atoms/icon'
 
 /**
- * A label on the leading edge and its value on the trailing edge — the settings/detail row.
+ * A label on the leading edge and its value on the trailing edge: the settings/detail row.
  * Pass `children` instead of `value` when the trailing side is a control rather than text.
  */
 export type LabeledContentProps = {
@@ -15,7 +15,7 @@ export type LabeledContentProps = {
   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. */
+  /** Horizontal padding inside the row, and 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