@hzblj/kara-components 0.6.0 → 0.8.0

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
   }
 

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

@@ -7,14 +7,8 @@ import type {RnSectionListProps} from './rn-section-list.types'
 const NO_SX = {}
 
 /**
- * Sectioned 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. This
- * exists 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 does not survive either — 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.
+ * `RnFlatList` with sections: React Native's own `VirtualizedList`, cells in normal flow inside a scroll view, so a
+ * row that hosts native views keeps them where the layout put it.
  *
  * Sticky headers default off, unlike React Native, where they are on for vertical lists. A header that
  * detaches and floats over the content is a deliberate effect, not something a list should do unasked.
@@ -30,6 +24,9 @@ export const RnSectionList = <TItem, TSection = DefaultSectionT>({
 
   return (
     <RNSectionList<TItem, TSection>
+      // 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}
       sections={sections}
       {...rest}
       contentContainerStyle={content === undefined ? undefined : contentStyle}

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

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

package/src/atoms/rn-text/rn-text.tsx

@@ -1,5 +1,6 @@
+import {useSplitSx} from '@hzblj/kara-sx'
 import {MAX_FONT_SCALE, useAppTheme} from '@hzblj/kara-theme'
-import {Text as RNText, useWindowDimensions} from 'react-native'
+import {Text as RNText, type TextStyle, useWindowDimensions} from 'react-native'
 
 import type {RnTextComponent, RnTextProps} from './rn-text.types'
 
@@ -10,6 +11,8 @@ export const RnText: RnTextComponent = ({
   ...props
 }: RnTextProps) => {
   const theme = useAppTheme()
+  // A view style, which a text accepts whole — only React Native's types disagree, on `userSelect`'s width.
+  const [sx, rest] = useSplitSx(props) as [TextStyle, Record<string, unknown>]
   const {fontScale} = useWindowDimensions()
   const style = theme.typography[variant]
 
@@ -26,8 +29,8 @@ export const RnText: RnTextComponent = ({
   return (
     <RNText
       maxFontSizeMultiplier={MAX_FONT_SCALE}
-      style={[style, {color: theme.color(color), lineHeight, textAlign: align}]}
-      {...props}
+      style={[style, sx, {color: theme.color(color), lineHeight, textAlign: align}]}
+      {...rest}
     />
   )
 }

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

@@ -1,11 +1,21 @@
+import type {ResponsiveViewSx} from '@hzblj/kara-sx'
 import type {ColorToken, TextVariant} from '@hzblj/kara-theme'
 import type {ReactNode} from 'react'
 import type {TextProps as RNTextProps} from 'react-native'
 
-export type RnTextProps = Omit<RNTextProps, 'style'> & {
-  align?: 'center' | 'left' | 'right'
-  color?: ColorToken
-  variant?: TextVariant
-}
+/**
+ * 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'> &
+  Omit<ResponsiveViewSx, 'align'> & {
+    /** Horizontal alignment, as React Native's `textAlign`. */
+    align?: 'center' | 'left' | 'right'
+    /** The text's colour. `content.primary` by default. */
+    color?: ColorToken
+    /** The typography variant. `body` by default. */
+    variant?: TextVariant
+  }
 
 export type RnTextComponent = (props: RnTextProps) => ReactNode

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

@@ -1,5 +1,6 @@
 import type {ReactElement, ReactNode} from 'react'
 
+/** 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
@@ -15,6 +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`. */
   testID?: string
 }
 

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

@@ -9,7 +9,9 @@ export type ScrollViewAxis = 'horizontal' | 'vertical'
  * like React Native's `contentContainerStyle` padding and scrolls with the content.
  */
 export type ScrollViewProps = ResponsiveSx & {
+  /** The scroll direction. `vertical` by default. */
   axis?: ScrollViewAxis
+  /** Laid out in a stack along `axis`. */
   children?: ReactNode
   /**
    * Enables pull-to-refresh. Async on purpose: the spinner runs until the promise settles, which is
@@ -21,7 +23,9 @@ export type ScrollViewProps = ResponsiveSx & {
   onRefresh?: () => Promise<void>
   /** iOS only — Compose exposes no indicator toggle, so Android always shows the native one. */
   showsIndicators?: boolean
+  /** The space between children. */
   spacing?: SpaceSize
+  /** Test identifier, forwarded to the native view. */
   testID?: string
 }
 

package/src/atoms/segmented-control/segmented-control.android.tsx

@@ -0,0 +1,79 @@
+import {Host, SegmentedButton, SingleChoiceSegmentedButtonRow, Text} from '@expo/ui/jetpack-compose'
+import {fillMaxWidth, testID as testIdModifier, weight} from '@expo/ui/jetpack-compose/modifiers'
+import {useAppTheme} from '@hzblj/kara-theme'
+import {useCallback, useMemo} from 'react'
+
+import {haptics} from '../../haptics'
+import type {SegmentedControlComponent, SegmentedControlProps} from './segmented-control.types'
+
+const MATCH_HEIGHT_ONLY = {horizontal: false, vertical: true}
+
+/** Every segment the same width, like UIKit's: Material's would size each to its label. */
+const SEGMENT = [weight(1)]
+
+/**
+ * Material's single-choice segmented buttons, the selected one filled with the accent like a checked `Switch`. Its own
+ * host, themed like an `Island`, so it drops into React Native layout the way the iOS control does. Material plays
+ * nothing on a new segment, so this plays `selection`.
+ */
+export const SegmentedControl: SegmentedControlComponent = ({
+  disabled = false,
+  onChange,
+  selectedIndex,
+  testID,
+  values,
+}: SegmentedControlProps) => {
+  const theme = useAppTheme()
+
+  const colors = useMemo(
+    () => ({
+      activeBorderColor: theme.color('fill.accent.primary'),
+      activeContainerColor: theme.color('fill.accent.primary'),
+      activeContentColor: theme.color('content.on.bg'),
+      disabledActiveBorderColor: theme.color('fill.accent.disabled'),
+      disabledActiveContainerColor: theme.color('fill.accent.disabled'),
+      disabledActiveContentColor: theme.color('btn.content.disabled'),
+      disabledInactiveBorderColor: theme.color('border.tertiary'),
+      disabledInactiveContentColor: theme.color('btn.content.disabled'),
+      inactiveBorderColor: theme.color('border.secondary.base'),
+      inactiveContentColor: theme.color('content.primary'),
+    }),
+    [theme]
+  )
+
+  const rowModifiers = useMemo(() => (testID ? [fillMaxWidth(), testIdModifier(testID)] : [fillMaxWidth()]), [testID])
+
+  // Material reports a tap on the segment that is already selected too; iOS does not, and neither does this.
+  const select = useCallback(
+    (index: number) => {
+      if (index === selectedIndex) {
+        return
+      }
+
+      haptics.selection()
+      onChange?.(index, values[index] ?? '')
+    },
+    [onChange, selectedIndex, values]
+  )
+
+  return (
+    <Host colorScheme={theme.dark ? 'dark' : 'light'} matchContents={MATCH_HEIGHT_ONLY} seedColor={theme.materialSeed}>
+      <SingleChoiceSegmentedButtonRow modifiers={rowModifiers}>
+        {values.map((label, index) => (
+          <SegmentedButton
+            colors={colors}
+            enabled={!disabled}
+            key={index}
+            modifiers={SEGMENT}
+            onClick={() => select(index)}
+            selected={index === selectedIndex}
+          >
+            <SegmentedButton.Label>
+              <Text style={theme.typography.subheadlineMedium}>{label}</Text>
+            </SegmentedButton.Label>
+          </SegmentedButton>
+        ))}
+      </SingleChoiceSegmentedButtonRow>
+    </Host>
+  )
+}

package/src/atoms/segmented-control/segmented-control.ios.tsx

@@ -0,0 +1,47 @@
+import {SegmentedControl as NativeSegmentedControl} from '@hzblj/kara-native/swift-ui'
+import {useAppTheme} from '@hzblj/kara-theme'
+import {useCallback, useMemo} from 'react'
+
+import type {SegmentedControlComponent, SegmentedControlProps} from './segmented-control.types'
+
+/**
+ * kara's own `UISegmentedControl`, with the pill in the accent and white text on it — the system control tints only the
+ * pill, and SwiftUI's segmented picker not even that. A plain `UIView` in React Native layout: it needs no host, takes
+ * the width it is given and UIKit's height. UIKit plays the control's own feedback.
+ */
+export const SegmentedControl: SegmentedControlComponent = ({
+  disabled = false,
+  onChange,
+  selectedIndex,
+  testID,
+  values,
+}: SegmentedControlProps) => {
+  const theme = useAppTheme()
+  const face = theme.typography.footnoteMedium
+
+  // The native control speaks in values; a segment's is its index, so two labels may read the same.
+  const options = useMemo(() => values.map((label, index) => ({label, value: String(index)})), [values])
+
+  const onValueChange = useCallback(
+    (value: string) => {
+      const index = Number(value)
+      onChange?.(index, values[index] ?? '')
+    },
+    [onChange, values]
+  )
+
+  return (
+    <NativeSegmentedControl
+      activePillColor={theme.color('fill.accent.primary')}
+      activeTextColor={theme.color('content.on.bg')}
+      disabled={disabled}
+      fontFamily={face.fontFamily}
+      fontSize={face.fontSize}
+      inactiveTextColor={theme.color('content.primary')}
+      onValueChange={onValueChange}
+      options={options}
+      selectedValue={String(selectedIndex)}
+      testID={testID}
+    />
+  )
+}

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

@@ -1,10 +1,23 @@
 import type {ReactNode} from 'react'
 
+/**
+ * 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.
+ */
 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.
+   * 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. */
   testID?: string
+  /** The segments' labels, in order. */
   values: string[]
 }
 

package/src/atoms/skeleton/skeleton.tsx

@@ -5,7 +5,7 @@ import {useAnimatedStyle, useSharedValue, withRepeat, withTiming} from 'react-na
 import {ABox} from '../box'
 import type {SkeletonComponent, SkeletonProps} from './skeleton.types'
 
-export const Skeleton: SkeletonComponent = ({borderRadius = 'small', height, testID, width}: SkeletonProps) => {
+export const Skeleton: SkeletonComponent = ({borderRadius = 'small', h, testID, w}: SkeletonProps) => {
   const pulse = useSharedValue<number>(opacity.o40)
 
   useEffect(() => {
@@ -18,11 +18,11 @@ export const Skeleton: SkeletonComponent = ({borderRadius = 'small', height, tes
     <ABox
       bg="fill.quaternary"
       borderRadius={borderRadius}
-      h={height}
+      h={h}
       style={rStyle}
       testID={testID}
-      w={width}
-      wide={width === undefined}
+      w={w}
+      wide={w === undefined}
     />
   )
 }

package/src/atoms/skeleton/skeleton.types.ts

@@ -1,11 +1,20 @@
+import type {SxDimension} from '@hzblj/kara-sx'
 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`.
+ */
 export type SkeletonProps = {
+  /** The corner radius. `small` by default. */
   borderRadius?: RadiiSize
-  height: number
+  /** In points. */
+  h: number
+  /** Test identifier, forwarded to the view. */
   testID?: string
-  width?: number
+  /** In points, or a percentage of the row (`60%` for a line that ends early). Unset, it fills the row. */
+  w?: SxDimension
 }
 
 export type SkeletonComponent = (props: SkeletonProps) => ReactNode

package/src/atoms/slider/slider.types.ts

@@ -1,11 +1,18 @@
 import type {ReactNode} from 'react'
 
+/** SwiftUI `Slider` / Compose's Material `Slider`, tinted `fill.accent.primary`. */
 export type SliderProps = {
+  /** Stops the user moving the thumb, and dims the slider. */
   disabled?: boolean
+  /** The upper end. `1` by default. */
   max?: number
+  /** The lower end. `0` by default. */
   min?: number
+  /** Called with the new value as the thumb moves. */
   onValueChange?: (value: number) => void
+  /** The increment between stops; leave it unset for a continuous slider. On Android every stop plays a `tick`. */
   step?: number
+  /** Between `min` and `max`. Controlled: pass back what `onValueChange` reports. */
   value: number
 }
 

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

@@ -1,8 +1,11 @@
 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)`. */
 export type SpacerProps = {
+  /** The least room it takes. iOS holds it along the stack's axis; Android as a minimum height only. */
   min?: SpaceSize
+  /** iOS: forwarded to the native view. Android ignores it. */
   testID?: string
 }
 

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

@@ -1,9 +1,16 @@
 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.
+ */
 export type SurfaceProps = ResponsiveSx & {
+  /** Stacked vertically, from the leading edge. */
   children?: ReactNode
+  /** iOS wraps the content in a `GlassEffectContainer`; Android raises it to a tonal elevation of `3`. */
   glass?: boolean
+  /** Test identifier, forwarded to the native view. */
   testID?: string
 }
 

package/src/atoms/switch/switch.android.tsx

@@ -7,6 +7,9 @@ import {haptics} from '../../haptics'
 import {useHostGuard} from '../../host-context'
 import type {SwitchComponent, SwitchProps} from './switch.types'
 
+/** Stands in for a missing handler: Material drops its 48dp touch target without one, and the switch moves. */
+const NOOP = () => undefined
+
 /**
  * Material's switch, tinted with the accent like SwiftUI's toggle. With a label it is a full-width row — label at the
  * start, switch at the end — and the whole row toggles, the way a Material settings row does. A flip plays
@@ -35,7 +38,7 @@ export const Switch: SwitchComponent = ({disabled = false, label, onValueChange,
         checkedTrackColor: theme.color('fill.accent.primary'),
       }}
       enabled={!disabled}
-      onCheckedChange={onValueChange ? toggle : undefined}
+      onCheckedChange={onValueChange ? toggle : NOOP}
       value={value}
     />
   )

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

@@ -1,9 +1,17 @@
 import type {ReactNode} from 'react'
 
+/** SwiftUI `Toggle` / Compose `Switch`, tinted `fill.accent.primary`. */
 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
+   * toggles wherever it is tapped.
+   */
   label?: string
+  /** Called with the new value when the user flips it. On Android a flip plays `toggleOn` / `toggleOff`. */
   onValueChange?: (value: boolean) => void
+  /** Whether it is on. Controlled: pass back what `onValueChange` reports. */
   value: boolean
 }
 

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

@@ -1,5 +1,6 @@
 import {Text as ComposeText} 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'
 
@@ -32,11 +33,16 @@ export const Text: TextComponent = ({
   testID,
   transform,
   variant = 'body',
+  ...sx
 }: TextProps) => {
   useHostGuard('Text')
   const theme = useAppTheme()
   const style = theme.typography[variant]
-  const modifiers = useMemo(() => (testID ? [testIdModifier(testID)] : undefined), [testID])
+  const sxModifiers = useSxModifiers(sx)
+  const modifiers = useMemo(
+    () => (testID ? [...sxModifiers, testIdModifier(testID)] : sxModifiers),
+    [sxModifiers, testID]
+  )
 
   return (
     <ComposeText

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

@@ -10,11 +10,12 @@ import {
   underline,
 } from '@expo/ui/swift-ui/modifiers'
 import {scaledFont} from '@hzblj/kara-native/swift-ui'
+import {type FrameAlignment, useSxModifiers} from '@hzblj/kara-sx'
 import {useAppTheme} from '@hzblj/kara-theme'
 import {useMemo} from 'react'
 
 import {useHostGuard} from '../../host-context'
-import type {TextComponent, TextProps} from './text.types'
+import type {TextAlign, TextComponent, TextProps} from './text.types'
 
 const ALIGNMENT = {
   center: 'center',
@@ -22,6 +23,13 @@ const ALIGNMENT = {
   right: 'trailing',
 } as const
 
+/** Where a frame larger than the text — `wide`, `w`, `h` — puts it: on the side its lines align to, centred vertically. */
+const FRAME_ALIGNMENT = {
+  center: 'center',
+  left: 'leading',
+  right: 'trailing',
+} as const satisfies Record<TextAlign, FrameAlignment>
+
 export const Text: TextComponent = ({
   align,
   children,
@@ -31,10 +39,13 @@ export const Text: TextComponent = ({
   testID,
   transform,
   variant = 'body',
+  ...sx
 }: TextProps) => {
   useHostGuard('Text')
   const theme = useAppTheme()
   const style = theme.typography[variant]
+  // After the text's own modifiers: the font and colour belong to the glyphs, the padding and frame to the box around.
+  const sxModifiers = useSxModifiers(sx, FRAME_ALIGNMENT[align ?? 'left'])
 
   const modifiers = useMemo(() => {
     const list: ModifierConfig[] = [
@@ -65,8 +76,8 @@ export const Text: TextComponent = ({
       list.push(lineLimit(numberOfLines))
     }
 
-    return list
-  }, [align, color, decoration, numberOfLines, style, theme, transform])
+    return [...list, ...sxModifiers]
+  }, [align, color, decoration, numberOfLines, style, sxModifiers, theme, transform])
 
   return (
     <SwiftUIText modifiers={modifiers} testID={testID}>

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

@@ -1,3 +1,4 @@
+import type {ResponsiveSx} from '@hzblj/kara-sx'
 import type {ColorToken, TextVariant} from '@hzblj/kara-theme'
 import type {ReactNode} from 'react'
 
@@ -7,14 +8,30 @@ export type TextDecoration = 'none' | 'strikethrough' | 'underline'
 
 export type TextTransform = 'lowercase' | 'uppercase'
 
-export type TextProps = {
+/**
+ * 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.
+ */
+export type TextProps = ResponsiveSx & {
+  /**
+   * How its lines align. iOS reads `left` and `right` as leading and trailing, so they flip in a right-to-left
+   * layout; Android keeps them as they are.
+   */
   align?: TextAlign
+  /** The text. */
   children?: ReactNode
+  /** The text's colour. `content.primary` by default. */
   color?: ColorToken
+  /** An underline or a strikethrough. */
   decoration?: TextDecoration
+  /** The most lines it wraps to. iOS truncates the last with an ellipsis; Android clips it. */
   numberOfLines?: number
+  /** Test identifier, forwarded to the native view. */
   testID?: string
+  /** Upper- or lower-cases the text. Android applies it only when `children` is a plain string. */
   transform?: TextTransform
+  /** The typography variant. `body` by default. */
   variant?: TextVariant
 }
 

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

@@ -1,13 +1,25 @@
 import type {ReactNode} from 'react'
 
+/**
+ * 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. */
   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
+  /** Shown above the field, in `labelMedium`. */
   label?: string
+  /** Wraps the text and grows the field to fit it. iOS ignores it when `secure`. */
   multiline?: boolean
+  /** Called with the whole text after every change. */
   onChangeText?: (text: string) => void
+  /** Masks the text, for a password. */
   secure?: boolean
+  /** iOS: forwarded to the native field. Android ignores it. */
   testID?: string
 }
 

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

@@ -4,11 +4,20 @@ import type {ReactNode} from 'react'
 
 export type VStackAlign = 'center' | 'end' | 'start'
 
+/** Stacks its children top to bottom — SwiftUI `VStack` / Compose `Column`. */
 export type VStackProps = ResponsiveSx & {
+  /** The children's horizontal alignment. `start` by default. */
   align?: VStackAlign
+  /** Laid out top to bottom, `spacing` apart. */
   children?: ReactNode
+  /**
+   * Makes the whole stack pressable. iOS adds a tap gesture with no press feedback; Android a `clickable` whose ripple
+   * fills the stack's shape.
+   */
   onPress?: () => void
+  /** The space between children. */
   spacing?: SpaceSize
+  /** Test identifier, forwarded to the native view. */
   testID?: string
 }