@hzblj/kara-components 0.6.0 → 0.7.0

package/lib/typescript/organisms/swipe-actions/swipe-actions.types.d.ts

@@ -1,20 +1,43 @@
+import type { ColorToken } from '@hzblj/kara-theme';
 import type { ReactNode } from 'react';
-export type SwipeActionsEdge = 'leading' | 'trailing';
+import type { IconName } from '../../atoms/icon';
+/** One button a swiped row uncovers. */
+export type SwipeAction = {
+    /** Fills the button with `fill.destructive.primary` unless `tint` says otherwise. */
+    destructive?: boolean;
+    /** One of the app's icons, on the button — a round one on iOS 26, as in Mail, a filled stadium on Android. */
+    icon: IconName;
+    /**
+     * The action's name, written under the button — before iOS 26 a row of the usual height shows the icon alone and
+     * keeps the label for VoiceOver. Actions are keyed by it, so keep labels unique within one row.
+     */
+    label: string;
+    /** Called when the button is pressed. The row closes by itself. */
+    onPress: () => void;
+    /**
+     * The button's fill — `fill.destructive.primary` for a destructive action, `fill.accent.primary` otherwise. The icon
+     * on it is white, so pick a fill that holds white in both appearances.
+     */
+    tint?: ColorToken;
+};
 /**
- * Swipe-to-reveal buttons on a row. iOS only — Compose ships no equivalent, so on Android the
- * row renders exactly as it would without this wrapper and the action buttons are dropped.
- * Degrading that way rather than to `null` keeps the content on screen.
+ * A list row with buttons behind it, uncovered by a swipe — SwiftUI's `swipeActions` on iOS, and on Android, where
+ * Compose has none, kara's own: the row slides on an anchored drag and the buttons show in the strip it leaves. One
+ * row is open at a time on both; a tap on an open row closes it. A native organism — it belongs inside a `List`.
  */
 export type SwipeActionsProps = {
-    children: ReactNode;
-    testID?: string;
-};
-export type SwipeActionsGroupProps = {
-    /** Whether swiping all the way performs the first action in the group. */
+    /**
+     * iOS: a swipe all the way across performs the edge's first action, as in Mail. Android has no full swipe. `true`
+     * by default, as in SwiftUI.
+     */
     allowsFullSwipe?: boolean;
+    /** The row. */
     children: ReactNode;
-    edge?: SwipeActionsEdge;
-};
-export type SwipeActionsComponent = ((props: SwipeActionsProps) => ReactNode) & {
-    Actions: (props: SwipeActionsGroupProps) => ReactNode;
+    /** The buttons at the leading edge, uncovered by a swipe toward the trailing one. The first sits outermost. */
+    leading?: SwipeAction[];
+    /** Test identifier. iOS: on the row. Android: the row is a Compose node, reach it by its content. */
+    testID?: string;
+    /** The buttons at the trailing edge, uncovered by a swipe toward the leading one. The first sits outermost. */
+    trailing?: SwipeAction[];
 };
+export type SwipeActionsComponent = (props: SwipeActionsProps) => ReactNode;

package/lib/typescript/templates/screen/screen.types.d.ts

@@ -1,9 +1,18 @@
 import type { Sx } from '@hzblj/kara-sx';
 import type { ReactNode } from 'react';
+/**
+ * The full-bleed native host a screen starts with — a SwiftUI or Compose `Host` filling its parent, so native atoms
+ * render anywhere inside it. The background runs to the edges; the content keeps clear of the status bar where the
+ * screen covers it (no navigation bar above), on Android as SwiftUI's safe area does on iOS.
+ */
 export type ScreenProps = {
+    /** The screen's colour. `surface.base` by default. */
     bg?: Sx['bg'];
+    /** Laid out in a column that fills the screen. */
     children?: ReactNode;
+    /** Keeps the content where it is when the keyboard opens, instead of avoiding it. Android reads it once, on mount. */
     ignoreKeyboardInset?: boolean;
+    /** Test identifier — on the host view on iOS, on the view around it on Android. */
     testID?: string;
 };
 export type ScreenComponent = (props: ScreenProps) => ReactNode;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hzblj/kara-components",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "The atoms, molecules, organisms and templates of @hzblj/kara-ui — real SwiftUI and Jetpack Compose views through @expo/ui.",
   "author": "Jan Blazej",
   "license": "MIT",
@@ -12,7 +12,7 @@
   "bugs": {
     "url": "https://github.com/hzblj/kara-ui/issues"
   },
-  "homepage": "https://github.com/hzblj/kara-ui/tree/main/packages/components#readme",
+  "homepage": "https://kara.janblazej.dev/docs/components",
   "keywords": [
     "react-native",
     "expo",
@@ -59,15 +59,14 @@
     ]
   },
   "dependencies": {
-    "@hzblj/kara-native": "^0.6.0",
-    "@hzblj/kara-sx": "^0.6.0",
-    "@hzblj/kara-theme": "^0.6.0",
+    "@hzblj/kara-native": "^0.7.0",
+    "@hzblj/kara-sx": "^0.7.0",
+    "@hzblj/kara-theme": "^0.7.0",
     "sf-symbols-typescript": "^2.2.0"
   },
   "peerDependencies": {
     "@expo/ui": "~57.0.0",
     "@lodev09/react-native-true-sheet": ">=3.11.0",
-    "@shopify/flash-list": ">=2.0.0",
     "expo": "~57.0.0",
     "expo-image": "*",
     "react": "*",
@@ -77,7 +76,6 @@
   "devDependencies": {
     "@expo/ui": "~57.0.18",
     "@lodev09/react-native-true-sheet": "3.11.18",
-    "@shopify/flash-list": "^2.3.2",
     "@storybook/react-native": "^10.6.0",
     "@types/react": "~19.2.18",
     "expo": "~57.0.22",

package/src/atoms/avatar/avatar.types.ts

@@ -3,10 +3,15 @@ import type {ImageSourcePropType} from 'react-native'
 
 export type AvatarSize = 'lg' | 'md' | 'sm'
 
+/** A round avatar: the image in `source`, or `initials` without one. The React Native tier — it needs no host. */
 export type AvatarProps = {
+  /** Shown in place of the image when there is no `source`. */
   initials?: string
+  /** The diameter — `sm` is `s24`, `md` `s40`, `lg` `s64`. `md` by default. */
   size?: AvatarSize
+  /** The image, cropped to the circle. */
   source?: ImageSourcePropType
+  /** Test identifier, forwarded to the view. */
   testID?: string
 }
 

package/src/atoms/badge/badge.types.ts

@@ -2,8 +2,11 @@ import type {ReactNode} from 'react'
 
 export type BadgeTone = 'accent' | 'destructive' | 'neutral' | 'success'
 
+/** A small status label in a capsule — a SwiftUI `HStack` in the tone's fill on iOS, Material's `Badge` on Android. */
 export type BadgeProps = {
+  /** The text inside. */
   label: string
+  /** The fill and text colours. `neutral` by default. */
   tone?: BadgeTone
 }
 

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

@@ -22,12 +22,22 @@ export type ButtonStyleName =
  */
 export type ButtonControlSize = 'extraLarge' | 'large' | 'mini' | 'regular' | 'small'
 
+/** 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.
+   */
   buttonStyle?: ButtonStyleName
+  /** 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
+  /** The button's text. */
   label: string
+  /** Called when the button is pressed. */
   onPress?: () => void
+  /** Test identifier, forwarded to the native view. */
   testID?: string
   /**
    * Overrides the variant's own tint. A prominent style takes it as the fill and picks a contrasting
@@ -35,7 +45,9 @@ export type ButtonProps = {
    * 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. */
   variant?: ButtonVariant
+  /** Stretches the button to the full width it is offered. On by default. */
   wide?: boolean
 }
 

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

@@ -1,8 +1,14 @@
 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
+ * the `card` shadow. Any `sx` prop overrides its default.
+ */
 export type CardProps = ResponsiveSx & {
+  /** Native views, stacked vertically from the leading edge. */
   children?: ReactNode
+  /** Test identifier, forwarded to the native view. */
   testID?: string
 }
 

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

@@ -12,6 +12,7 @@ export type GlassViewProps = ResponsiveViewSx & {
   children?: ReactNode
   /** Swells toward the finger on touch, carrying the children with it. Wrap the view in a `Pressable` for the press. */
   interactive?: boolean
+  /** Test identifier, forwarded to the view. */
   testID?: string
   /** Tints the material. Unset leaves it clear. */
   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/index.ts

@@ -10,7 +10,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.types.ts

@@ -1,7 +1,9 @@
 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. */
 export type IslandProps = {
+  /** 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
@@ -15,7 +17,9 @@ export type IslandProps = {
    * hangs the main thread as soon as the views lay out on screen.
    */
   matchContents?: boolean
+  /** A React Native style for the host view — its size and placement. It needs a height when `matchContents` is off. */
   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.types.ts

@@ -3,12 +3,20 @@ import type {ReactNode} from 'react'
 
 import type {Haptic} from '../../haptics'
 
+/**
+ * React Native's `Pressable`, styled through `sx` like a `Box`: it springs down to 96% while pressed and takes
+ * touches 8 points past its edges. 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. */
   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
 }
 

package/src/atoms/rn-flat-list/rn-flat-list.tsx

@@ -7,14 +7,11 @@ import type {RnFlatListProps} from './rn-flat-list.types'
 const NO_SX = {}
 
 /**
- * Flat list built on React Native's own `VirtualizedList` rather than FlashList.
- *
- * FlashList is the default for lists in this codebase and should stay that way for data rows — reach
- * for this only for the case it cannot serve: content that hosts native views. FlashList positions its
- * rows absolutely and recycles their cells, and an `@expo/ui` host survives neither — the hosted view
- * ends up drawn where the layout no longer is. `VirtualizedList` renders its cells in normal flow
- * inside a scroll view, using blank spacers for the range it has not rendered, so a hosted view stays
- * exactly where the layout put it. This is `SectionList`'s reason to exist too, without the sections.
+ * kara's list for React Native content: React Native's own `VirtualizedList`, styled through `sx`. It renders its
+ * cells in normal flow inside a scroll view, with blank spacers for the range it has not rendered, so a row that hosts
+ * native views keeps them where the layout put it. A recycling list (absolutely positioned, reused cells) cannot
+ * promise that — an `@expo/ui` host survives neither, and draws where the layout no longer is — which is why kara
+ * ships none.
  */
 export const RnFlatList = <TItem,>({content, data, renderItem, ...props}: RnFlatListProps<TItem>) => {
   const [style, rest] = useSplitSx(props as Record<string, unknown>)
@@ -23,6 +20,9 @@ export const RnFlatList = <TItem,>({content, data, renderItem, ...props}: RnFlat
   return (
     <RNFlatList<TItem>
       data={data}
+      // Android clips by default, and a host is measured after its first layout — at zero height it counts as
+      // off-screen, is detached, and its native view never comes back.
+      removeClippedSubviews={false}
       renderItem={renderItem}
       {...rest}
       contentContainerStyle={content === undefined ? undefined : contentStyle}

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

@@ -3,9 +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`.
+ * 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. */
     content?: ResponsiveViewSx
   }

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

@@ -13,9 +13,13 @@ import type {ScrollViewAxis} from '../scroll-view'
  */
 export type RnScrollViewProps = ResponsiveViewSx &
   Omit<RNScrollViewProps, 'contentContainerStyle' | 'horizontal' | 'style'> & {
+    /** The scroll direction. `vertical` by default. */
     axis?: ScrollViewAxis
+    /** The scrolling content. */
     children?: ReactNode
+    /** Styles the scrolling content container — padding and gap belong here. */
     content?: ResponsiveViewSx
+    /** Shows the scroll indicators. On by default. */
     showsIndicators?: boolean
   }