@hzblj/kara-components 0.1.0 → 0.2.1

package/lib/typescript/organisms/fab-menu/fab-menu.types.d.ts

@@ -8,7 +8,7 @@ import type { MenuAction } from '../menu';
  */
 export type FabMenuProps = {
     actions: MenuAction[];
-    /** The closed button's icon. `add` by default. */
+    /** The closed button's icon — one of the app's. A plus by default. */
     icon?: IconName;
     testID?: string;
 };

package/lib/typescript/organisms/form/form.types.d.ts

@@ -1,4 +1,9 @@
 import type { ReactNode } from 'react';
+/**
+ * A settings form — SwiftUI `Form` with its grouped sections, Material cards on Android. On iOS it scrolls like a
+ * `List`, so it needs a height from outside: a `Screen`, or an `Island` with `matchContents={false}` and a height. In
+ * an island that sizes itself to its content it has no height and shows nothing.
+ */
 export type FormProps = {
     children: ReactNode;
     testID?: string;

package/lib/typescript/organisms/index.d.ts

@@ -4,7 +4,6 @@ export * from './context-menu';
 export * from './fab-menu';
 export * from './form';
 export * from './menu';
-export * from './rn-context-menu';
 export * from './sheet';
 export * from './snackbar';
 export * from './swipe-actions';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hzblj/kara-components",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "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",
@@ -59,14 +59,13 @@
     ]
   },
   "dependencies": {
-    "@hzblj/kara-native": "^0.1.0",
-    "@hzblj/kara-sx": "^0.1.0",
-    "@hzblj/kara-theme": "^0.1.0",
+    "@hzblj/kara-native": "^0.2.1",
+    "@hzblj/kara-sx": "^0.2.1",
+    "@hzblj/kara-theme": "^0.2.1",
     "sf-symbols-typescript": "^2.2.0"
   },
   "peerDependencies": {
     "@expo/ui": "~57.0.0",
-    "@expo/vector-icons": "*",
     "@shopify/flash-list": ">=2.0.0",
     "expo": "~57.0.0",
     "expo-haptics": "*",
@@ -77,7 +76,6 @@
   },
   "devDependencies": {
     "@expo/ui": "~57.0.18",
-    "@expo/vector-icons": "^15.1.1",
     "@shopify/flash-list": "^2.3.2",
     "@storybook/react-native": "^10.6.0",
     "@types/react": "~19.2.18",

package/src/atoms/badge/badge.android.tsx

@@ -1,9 +1,10 @@
-import {Badge as ComposeBadge} from '@expo/ui/jetpack-compose'
+import {Badge as ComposeBadge, Text as ComposeText} from '@expo/ui/jetpack-compose'
 import {useAppTheme} from '@hzblj/kara-theme'
 import {useHostGuard} from '../../host-context'
 import type {BadgeComponent, BadgeProps} from './badge.types'
 import {BADGE_TOKENS} from './badge-tokens'
 
+/** Material's badge. Its content is a Compose `Text` — `@expo/ui`'s badge takes composable content, not a string. */
 export const Badge: BadgeComponent = ({label, tone = 'neutral'}: BadgeProps) => {
   useHostGuard('Badge')
   const theme = useAppTheme()
@@ -11,7 +12,9 @@ export const Badge: BadgeComponent = ({label, tone = 'neutral'}: BadgeProps) =>
 
   return (
     <ComposeBadge containerColor={theme.color(tokens.fill)} contentColor={theme.color(tokens.content)}>
-      {label}
+      <ComposeText color={theme.colorString(tokens.content)} style={theme.typography.captionMedium}>
+        {label}
+      </ComposeText>
     </ComposeBadge>
   )
 }

package/src/atoms/button/button-tokens.ts

@@ -33,3 +33,52 @@ export const buttonTokens = (variant: ButtonVariant, disabled: boolean, theme: T
 
   return {content: 'btn.content.disabled', fill: disabledFill[variant], shadow: tokens.shadow} as const
 }
+
+/** Relative luminance of a `#rrggbb` colour (any alpha ignored); `undefined` for anything else. */
+const luminance = (color: unknown): number | undefined => {
+  const hex = typeof color === 'string' ? /^#([0-9a-f]{6})/i.exec(color)?.[1] : undefined
+
+  if (!hex) {
+    return undefined
+  }
+
+  const [r, g, b] = [0, 2, 4].map(i => {
+    const channel = Number.parseInt(hex.slice(i, i + 2), 16) / 255
+
+    return channel <= 0.04045 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4
+  })
+
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b
+}
+
+/**
+ * The hex behind a token in the current appearance. Android resolves an adaptive entry to one; iOS hands the platform
+ * a dynamic colour instead, so there the authored entry is read and its branch picked. A system colour has none.
+ */
+const currentHex = (token: ColorToken, theme: Theme): unknown => {
+  const resolved = theme.color(token)
+
+  if (typeof resolved === 'string') {
+    return resolved
+  }
+
+  const entry = token
+    .split(':')[0]
+    .split('.')
+    .reduce<unknown>((node, key) => (node as Record<string, unknown> | undefined)?.[key], theme)
+
+  if (entry && typeof entry === 'object' && 'adaptive' in entry) {
+    const {dark, light} = (entry as {adaptive: {dark: string; light: string}}).adaptive
+
+    return theme.dark ? dark : light
+  }
+
+  return entry
+}
+
+/**
+ * The label for a button filled with an arbitrary `tint`: the on-accent white over a strong colour, the primary
+ * content colour over a pale one (`fill.accent.base`) — the light container tokens pair with it in both appearances.
+ */
+export const contentOnTint = (tint: ColorToken, theme: Theme): ColorToken =>
+  (luminance(currentHex(tint, theme)) ?? 0) > 0.4 ? 'content.primary' : 'content.on.bg'

package/src/atoms/button/button.android.tsx

@@ -1,36 +1,70 @@
-import {Button as ComposeButton} from '@expo/ui/jetpack-compose'
+import {Button as ComposeButton, Text as ComposeText, OutlinedButton} from '@expo/ui/jetpack-compose'
+import {testID as testIdModifier} from '@expo/ui/jetpack-compose/modifiers'
 import {useSxModifiers} from '@hzblj/kara-sx'
 import {useAppTheme} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
 import {useHostGuard} from '../../host-context'
 import type {ButtonComponent, ButtonProps} from './button.types'
-import {buttonTokens} from './button-tokens'
+import {buttonTokens, contentOnTint} from './button-tokens'
 
+/**
+ * Material's filled button, in its own stadium shape. No `borderRadius` or `shadow` from the tokens: those shape the
+ * SwiftUI button's glossy ring, and laid over a Compose button they clip and outline a rounded rectangle around the
+ * pill Material draws. The label is a Compose `Text` — `@expo/ui`'s button takes composable content, not a string.
+ *
+ * Material has no glass, so `glass` is its outlined button — and a `tint` makes any variant a filled button in that
+ * colour, as a prominent style does on iOS. `buttonStyle` and `controlSize` are SwiftUI's alone.
+ */
 export const Button: ButtonComponent = ({
   disabled = false,
   label,
   onPress,
   testID,
+  tint,
   variant = 'accent',
   wide = true,
 }: ButtonProps) => {
   useHostGuard('Button')
   const theme = useAppTheme()
   const tokens = buttonTokens(variant, disabled, theme)
-  const modifiers = useSxModifiers({borderRadius: 'medium', shadow: tokens.shadow, wide})
+  const sxModifiers = useSxModifiers({wide})
+  const modifiers = useMemo(
+    () => (testID ? [...sxModifiers, testIdModifier(testID)] : sxModifiers),
+    [sxModifiers, testID]
+  )
+  const style = theme.typography.body
+  const outlined = variant === 'glass' && !tint
+  const fill = tint && !disabled ? tint : tokens.fill
+  const content = tint && !disabled ? contentOnTint(tint, theme) : tokens.content
+  const MaterialButton = outlined ? OutlinedButton : ComposeButton
 
   return (
-    <ComposeButton
-      colors={{
-        containerColor: theme.color(tokens.fill),
-        contentColor: theme.color(tokens.content),
-        disabledContainerColor: theme.color(tokens.fill),
-        disabledContentColor: theme.color(tokens.content),
-      }}
+    <MaterialButton
+      colors={
+        outlined
+          ? {contentColor: theme.color(content), disabledContentColor: theme.color(content)}
+          : {
+              containerColor: theme.color(fill),
+              contentColor: theme.color(content),
+              disabledContainerColor: theme.color(fill),
+              disabledContentColor: theme.color(content),
+            }
+      }
       enabled={!disabled}
       modifiers={modifiers}
       onClick={onPress}
     >
-      {label}
-    </ComposeButton>
+      <ComposeText
+        color={theme.colorString(content)}
+        style={{
+          fontFamily: style.fontFamily,
+          fontSize: style.fontSize,
+          fontWeight: style.fontWeight,
+          lineHeight: style.lineHeight,
+        }}
+      >
+        {label}
+      </ComposeText>
+    </MaterialButton>
   )
 }

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

@@ -12,7 +12,7 @@ import {useHostGuard} from '../../host-context'
 import {Text} from '../text'
 import {VStack} from '../v-stack'
 import type {ButtonComponent, ButtonProps, ButtonStyleName, ButtonVariant} from './button.types'
-import {buttonTokens} from './button-tokens'
+import {buttonTokens, contentOnTint} from './button-tokens'
 
 const STYLE_BY_VARIANT = {
   accent: 'borderedProminent',
@@ -55,6 +55,9 @@ export const Button: ButtonComponent = ({
    * button its height — without it a tinted glass button comes out shorter than every other variant.
    */
   const glassTint = style === 'glass' && resolvedTint ? theme.color(resolvedTint) : undefined
+  const filled = Boolean(glassTint) || style === 'borderedProminent' || style === 'glassProminent'
+  // A prominent style — and tinted glass — is coloured by the tint, so a caller's own tint picks the label on it.
+  const content = tint && filled && !disabled ? contentOnTint(tint, theme) : tokens.content
 
   const modifiers = useMemo(() => {
     const list = [buttonStyleModifier(glassTint ? 'plain' : style), controlSizeModifier(controlSize)]
@@ -77,7 +80,7 @@ export const Button: ButtonComponent = ({
   return (
     <SwiftUIButton modifiers={modifiers} onPress={onPress} testID={testID}>
       <VStack align="center" py={glassTint ? 's16' : undefined} wide={wide}>
-        <Text color={tokens.content} variant="body">
+        <Text color={content} variant="body">
           {label}
         </Text>
       </VStack>

package/src/atoms/checkbox/checkbox.android.tsx

@@ -1,22 +1,39 @@
 import {Checkbox as ComposeCheckbox, Row, Text} from '@expo/ui/jetpack-compose'
-import {useAppTheme} from '@hzblj/kara-theme'
+import {clickable, fillMaxWidth} from '@expo/ui/jetpack-compose/modifiers'
+import {spacing, useAppTheme} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
 
 import {useHostGuard} from '../../host-context'
 import type {CheckboxComponent, CheckboxProps} from './checkbox.types'
 
+/**
+ * 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.
+ */
 export const Checkbox: CheckboxComponent = ({disabled = false, label, onValueChange, value}: CheckboxProps) => {
   useHostGuard('Checkbox')
   const theme = useAppTheme()
-  const control = <ComposeCheckbox enabled={!disabled} onCheckedChange={onValueChange} value={value} />
+  const rowModifiers = useMemo(
+    () => (disabled || !onValueChange ? [fillMaxWidth()] : [fillMaxWidth(), clickable(() => onValueChange(!value))]),
+    [disabled, onValueChange, value]
+  )
+  const control = (
+    <ComposeCheckbox
+      colors={{checkedColor: theme.color('fill.accent.primary'), checkmarkColor: theme.color('content.on.bg')}}
+      enabled={!disabled}
+      onCheckedChange={onValueChange}
+      value={value}
+    />
+  )
 
   if (!label) {
     return control
   }
 
   return (
-    <Row verticalAlignment="center">
+    <Row horizontalArrangement={{spacedBy: spacing.s8}} modifiers={rowModifiers} verticalAlignment="center">
       {control}
-      <Text color={theme.colorString('content.primary')} style={theme.typography.body}>
+      <Text color={theme.colorString(disabled ? 'content.tertiary' : 'content.primary')} style={theme.typography.body}>
         {label}
       </Text>
     </Row>

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

@@ -0,0 +1,74 @@
+import {DateTimePicker} from '@expo/ui/community/datetime-picker'
+import {useAppTheme} from '@hzblj/kara-theme'
+import {useCallback, useState} from 'react'
+
+import {Pressable} from '../pressable'
+import {RnText} from '../rn-text'
+import type {DatePickerComponent, DatePickerMode, DatePickerProps} from './date-picker.types'
+
+const formatted = (value: Date, mode: DatePickerMode): string => {
+  if (mode === 'time') {
+    return value.toLocaleTimeString(undefined, {hour: '2-digit', minute: '2-digit'})
+  }
+
+  const date = value.toLocaleDateString(undefined, {day: 'numeric', month: 'short', year: 'numeric'})
+
+  return mode === 'datetime'
+    ? `${date} ${value.toLocaleTimeString(undefined, {hour: '2-digit', minute: '2-digit'})}`
+    : date
+}
+
+/**
+ * The value as a field that opens Material's date picker dialog on a tap. Android's picker *is* a dialog — mounted, it
+ * opens — so it is mounted only while open, and unmounted on confirm or dismiss, as the component asks its caller to.
+ */
+export const DatePicker: DatePickerComponent = ({
+  max,
+  min,
+  mode = 'date',
+  onValueChange,
+  testID,
+  value,
+}: DatePickerProps) => {
+  const theme = useAppTheme()
+  const [open, setOpen] = useState(false)
+
+  const show = useCallback(() => setOpen(true), [])
+  const hide = useCallback(() => setOpen(false), [])
+
+  const onChange = useCallback(
+    (_event: unknown, date: Date) => {
+      setOpen(false)
+      onValueChange?.(date)
+    },
+    [onValueChange]
+  )
+
+  return (
+    <>
+      <Pressable
+        alignSelf="flex-start"
+        bg="fill.tertiary"
+        borderRadius="medium"
+        onPress={show}
+        px="s12"
+        py="s8"
+        testID={testID}
+      >
+        <RnText variant="body">{formatted(value, mode)}</RnText>
+      </Pressable>
+      {open ? (
+        <DateTimePicker
+          accentColor={theme.colorString('fill.accent.primary')}
+          maximumDate={max}
+          minimumDate={min}
+          mode={mode}
+          onDismiss={hide}
+          onValueChange={onChange}
+          presentation="dialog"
+          value={value}
+        />
+      ) : null}
+    </>
+  )
+}

package/src/atoms/date-picker/date-picker.ios.tsx

@@ -0,0 +1,27 @@
+import {DateTimePicker} from '@expo/ui/community/datetime-picker'
+import {useCallback} from 'react'
+
+import type {DatePickerComponent, DatePickerProps} from './date-picker.types'
+
+/** The system's compact date picker, inline: a tap on it opens the calendar popover UIKit owns. */
+export const DatePicker: DatePickerComponent = ({
+  max,
+  min,
+  mode = 'date',
+  onValueChange,
+  testID,
+  value,
+}: DatePickerProps) => {
+  const onChange = useCallback((_event: unknown, date: Date) => onValueChange?.(date), [onValueChange])
+
+  return (
+    <DateTimePicker
+      maximumDate={max}
+      minimumDate={min}
+      mode={mode}
+      onValueChange={onChange}
+      testID={testID}
+      value={value}
+    />
+  )
+}

package/src/atoms/fab/fab.android.tsx

@@ -12,7 +12,10 @@ export const Fab: FabComponent = ({name, onPress}: FabProps) => {
 
   return (
     <FloatingActionButton containerColor={theme.color('fill.accent.primary')} onClick={onPress}>
-      <Icon color="content.on.bg" name={name} />
+      {/* `@expo/ui`'s FAB is slot-based: content outside `.Icon` is not composed at all. */}
+      <FloatingActionButton.Icon>
+        <Icon color="content.on.bg" name={name} />
+      </FloatingActionButton.Icon>
     </FloatingActionButton>
   )
 }

package/src/atoms/glass-view/glass-fallback.tsx

@@ -1,9 +1,12 @@
 import {Box} from '../box'
 import type {GlassViewProps} from './glass-view.types'
 
-/** The capsule drawn where there is no Liquid Glass to draw. */
+/**
+ * The capsule drawn where there is no Liquid Glass to draw: the glass buttons' own translucent fill, so whatever sits
+ * on the glass — usually content meant for a colourful backdrop — stays readable, the way it would on real glass.
+ */
 export const GlassFallback = ({children, interactive: _interactive, tint, ...props}: GlassViewProps) => (
-  <Box borderRadius="full" {...props} bg={tint ?? 'fill.tertiary'}>
+  <Box borderRadius="full" {...props} bg={tint ?? 'btn.bg.glass.base'}>
     {children}
   </Box>
 )

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

@@ -5,7 +5,7 @@ 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 `fill.tertiary` when there is none.
+ * capsule of `tint` instead, or of the glass buttons' translucent fill (`btn.bg.glass.base`) when there is none.
  */
 export type GlassViewProps = ResponsiveViewSx & {
   /** React Native views. Give them `pointerEvents="none"` when `interactive`, so the press reaches the `Pressable`. */

package/src/atoms/icon/icon.android.tsx

@@ -1,17 +1,21 @@
-import MaterialIcons from '@expo/vector-icons/MaterialIcons'
+import {iconResourceName} from '@hzblj/kara-native'
+import {DrawableIcon} from '@hzblj/kara-native/jetpack-compose'
 import {spacing, useAppTheme} from '@hzblj/kara-theme'
+
 import {useHostGuard} from '../../host-context'
-import {RnView} from '../rn-view'
 import type {IconComponent, IconProps} from './icon.types'
-import {MATERIAL_ICONS} from './icon-names'
 
-export const Icon: IconComponent = ({color = 'content.primary', name, size = 's24', testID}: IconProps) => {
+/** The app's icon as the vector drawable the config plugin generated from the SVG, drawn by Material's `Icon`. */
+export const Icon: IconComponent = ({accessibilityLabel, color = 'content.primary', name, size = 's24'}: IconProps) => {
   useHostGuard('Icon')
   const theme = useAppTheme()
 
   return (
-    <RnView>
-      <MaterialIcons color={theme.color(color)} name={MATERIAL_ICONS[name]} size={spacing[size]} testID={testID} />
-    </RnView>
+    <DrawableIcon
+      accessibilityLabel={accessibilityLabel}
+      iconColor={theme.color(color)}
+      iconSize={spacing[size]}
+      resourceName={iconResourceName(name)}
+    />
   )
 }

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

@@ -1,15 +1,35 @@
 import {Image} from '@expo/ui/swift-ui'
+import {accessibilityHidden, frame, accessibilityLabel as labelModifier, resizable} from '@expo/ui/swift-ui/modifiers'
+import {iconResourceName} from '@hzblj/kara-native'
 import {spacing, useAppTheme} from '@hzblj/kara-theme'
-import type {SFSymbol} from 'sf-symbols-typescript'
+import {useMemo} from 'react'
+
 import {useHostGuard} from '../../host-context'
 import type {IconComponent, IconProps} from './icon.types'
-import {SF_SYMBOLS} from './icon-names'
 
-export const Icon: IconComponent = ({color = 'content.primary', name, size = 's24', testID}: IconProps) => {
+/**
+ * The app's icon from its asset catalog — the template image set the config plugin generated from the SVG, vector data
+ * kept, so `resizable()` scales it crisply to the token size and the platform tints it.
+ */
+export const Icon: IconComponent = ({
+  accessibilityLabel,
+  color = 'content.primary',
+  name,
+  size = 's24',
+  testID,
+}: IconProps) => {
   useHostGuard('Icon')
   const theme = useAppTheme()
+  const side = spacing[size]
 
-  return (
-    <Image color={theme.color(color)} size={spacing[size]} systemName={SF_SYMBOLS[name] as SFSymbol} testID={testID} />
+  const modifiers = useMemo(
+    () => [
+      resizable(),
+      frame({height: side, width: side}),
+      accessibilityLabel ? labelModifier(accessibilityLabel) : accessibilityHidden(true),
+    ],
+    [accessibilityLabel, side]
   )
+
+  return <Image assetName={iconResourceName(name)} color={theme.color(color)} modifiers={modifiers} testID={testID} />
 }

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

@@ -1,32 +1,26 @@
 import type {ColorToken, SpaceSize} from '@hzblj/kara-theme'
 import type {ReactNode} from 'react'
 
-export type IconName =
-  | 'add'
-  | 'arrowLeft'
-  | 'arrowRight'
-  | 'calendar'
-  | 'check'
-  | 'chevronDown'
-  | 'chevronRight'
-  | 'close'
-  | 'error'
-  | 'grid'
-  | 'heart'
-  | 'home'
-  | 'info'
-  | 'lock'
-  | 'more'
-  | 'notification'
-  | 'search'
-  | 'settings'
-  | 'share'
-  | 'star'
-  | 'trash'
-  | 'user'
-  | 'warning'
+declare global {
+  /**
+   * The app's icon names, one key per SVG in its icon folder. Written by the config plugin
+   * (`plugins: [['@hzblj/kara-ui', {icons: {source: './assets/icons'}}]]`) into `kara-icons.d.ts`, or by
+   * `npx kara-icons`. Empty until then. Global, so the declaration reaches it without resolving any kara package.
+   */
+  interface KaraIcons {}
+}
+
+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
+ * 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
 
 export type IconProps = {
+  /** What a screen reader says. Unset, the icon is decorative and hidden from it. */
+  accessibilityLabel?: string
   color?: ColorToken
   name: IconName
   size?: SpaceSize

package/src/atoms/icon/index.ts

@@ -1,3 +1,2 @@
 export * from './icon'
 export * from './icon.types'
-export * from './icon-names'

package/src/atoms/index.ts

@@ -7,7 +7,6 @@ export * from './card'
 export * from './checkbox'
 export * from './chip'
 export * from './color-picker'
-export * from './countdown'
 export * from './date-picker'
 export * from './divider'
 export * from './fab'
@@ -23,6 +22,7 @@ export * from './picker'
 export * from './pressable'
 export * from './progress'
 export * from './rn-flat-list'
+export * from './rn-icon'
 export * from './rn-scroll-view'
 export * from './rn-section-list'
 export * from './rn-text'

package/src/atoms/list/list.android.tsx

@@ -1,15 +1,26 @@
 import {LazyColumn, PullToRefreshBox} from '@expo/ui/jetpack-compose'
 import {useSxModifiers} from '@hzblj/kara-sx'
+import {Children, Fragment, isValidElement} from 'react'
 import {useHostGuard} from '../../host-context'
 import {useRefreshState} from '../../use-refresh-state'
+import {Divider} from '../divider'
 import type {ListComponent, ListProps} from './list.types'
 
+/** A divider between rows, the separator SwiftUI's `List` draws on its own — so rows are written the same for both. */
+const withSeparators = (children: ListProps['children']) =>
+  Children.toArray(children).map((child, index) => (
+    <Fragment key={isValidElement(child) && child.key !== null ? child.key : index}>
+      {index > 0 ? <Divider /> : null}
+      {child}
+    </Fragment>
+  ))
+
 export const List: ListComponent = ({children, onRefresh}: ListProps) => {
   useHostGuard('List')
   const modifiers = useSxModifiers({wide: true})
   const {isRefreshing, refresh} = useRefreshState(onRefresh)
 
-  const column = <LazyColumn modifiers={modifiers}>{children}</LazyColumn>
+  const column = <LazyColumn modifiers={modifiers}>{withSeparators(children)}</LazyColumn>
 
   if (!onRefresh) {
     return column

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

@@ -1,5 +1,14 @@
 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 `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
+ * the children is one too many: on iOS it becomes an empty row of its own.
+ */
 export type ListProps = {
   children: ReactNode
   /**