@hzblj/kara-components 0.6.0 → 0.8.0

package/lib/typescript/organisms/action-sheet/action-sheet.types.d.ts

@@ -1,9 +1,17 @@
 import type { ReactNode } from 'react';
 import type { MenuAction } from '../menu';
+/**
+ * A list of actions to pick one from: SwiftUI's confirmation dialog on iOS, a `Sheet` of Material rows — icon and label
+ * — under the title on Android. A native atom — it renders inside `<Screen>` or `<Island>`.
+ */
 export type ActionSheetProps = {
+    /** The choices, top to bottom. Picking one closes the sheet. */
     actions: MenuAction[];
+    /** The sheet closed — after a pick too — so turn `visible` off. */
     onDismiss: () => void;
+    /** The heading above the actions. Android always shows it; on iOS the system decides, and may hide it. */
     title: string;
+    /** Presents the sheet while true. */
     visible: boolean;
 };
 export type ActionSheetComponent = (props: ActionSheetProps) => ReactNode;

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

@@ -1,11 +1,22 @@
 import type { ReactNode } from 'react';
+/**
+ * A modal alert with a confirm button and Cancel: SwiftUI's alert on iOS, Material's `AlertDialog` on Android. A native
+ * atom — it renders inside `<Screen>` or `<Island>`.
+ */
 export type AlertProps = {
+    /** The confirm button's label. `OK` by default. */
     confirmLabel?: string;
+    /** Marks the confirm button destructive — the system's destructive role on iOS, the destructive colour on Android. */
     destructive?: boolean;
+    /** The body text, under the title. */
     message?: string;
+    /** The confirm button was pressed. `onDismiss` follows, as it does for every way the alert closes. */
     onConfirm?: () => void;
+    /** The alert closed — either button, or on Android a tap outside or back — so turn `visible` off. */
     onDismiss: () => void;
+    /** The alert's heading. */
     title: string;
+    /** Shows the alert while true. */
     visible: boolean;
 };
 export type AlertComponent = (props: AlertProps) => ReactNode;

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

@@ -9,6 +9,7 @@ import type { MenuAction } from '../menu';
  * needs no `Screen` or `Island`.
  */
 export type ContextMenuProps = ResponsiveViewSx & {
+    /** The menu's actions, top to bottom. */
     actions: MenuAction[];
     /** The trigger, laid out as usual. */
     children: ReactNode;
@@ -28,9 +29,12 @@ export type ContextMenuProps = ResponsiveViewSx & {
      * `ZoomTransition.Source`, `pop` otherwise.
      */
     previewTransition?: 'dismiss' | 'pop' | 'zoom';
+    /** Test identifier — on the native view around the trigger on iOS, on the trigger's `Pressable` on Android. */
     testID?: string;
 };
+/** A region of a `ContextMenu`'s trigger that keeps its own long press — see `ContextMenu.Exclusion`. */
 export type ContextMenuExclusionProps = {
+    /** The region — a button inside the card, say. */
     children: ReactNode;
 };
 export type ContextMenuComponent = ((props: ContextMenuProps) => ReactNode) & {

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

@@ -7,9 +7,11 @@ import type { MenuAction } from '../menu';
  * of a SwiftUI `Menu`. A native atom — it renders inside `<Screen>` or `<Island>`.
  */
 export type FabMenuProps = {
+    /** The actions the button unfolds into. */
     actions: MenuAction[];
     /** The closed button's icon — one of the app's. A plus by default. */
     icon?: IconName;
+    /** Test identifier, forwarded to the SwiftUI `Menu`. iOS only — Android ignores it. */
     testID?: string;
 };
 export type FabMenuComponent = (props: FabMenuProps) => ReactNode;

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

@@ -5,12 +5,18 @@ import type { ReactNode } from 'react';
  * an island that sizes itself to its content it has no height and shows nothing.
  */
 export type FormProps = {
+    /** The form's `Form.Section`s. */
     children: ReactNode;
+    /** Test identifier, forwarded to the native view. */
     testID?: string;
 };
+/** A group of rows in a `Form`: a SwiftUI `Section` on iOS, a `Card` under a heading on Android. */
 export type FormSectionProps = {
+    /** The section's rows. */
     children: ReactNode;
+    /** Small print under the section. */
     footer?: string;
+    /** The section's heading. */
     title?: string;
 };
 export type FormComponent = ((props: FormProps) => ReactNode) & {

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

@@ -1,13 +1,30 @@
 import type { ReactNode } from 'react';
 import type { IconName } from '../../atoms/icon';
+/** One action of a `Menu`, an `ActionSheet`, a `ContextMenu` or a `FabMenu`. */
 export type MenuAction = {
+    /**
+     * Draws the action in the destructive colour — the system's destructive role on iOS. `FabMenu` ignores it on
+     * Android.
+     */
     destructive?: boolean;
+    /**
+     * One of the app's icons, before the label. `ContextMenu` and `FabMenu` show it on both platforms, `Menu` and
+     * `ActionSheet` on Android only.
+     */
     icon?: IconName;
+    /** The action's text. Rows are keyed by it, so keep labels unique within one list. */
     label: string;
+    /** Called when the action is chosen; the menu closes by itself. */
     onPress: () => void;
 };
+/**
+ * A text button that opens a list of actions: a SwiftUI `Menu` on iOS, a Material dropdown anchored to it on Android.
+ * A native atom — it renders inside `<Screen>` or `<Island>`.
+ */
 export type MenuProps = {
+    /** The menu's actions, top to bottom. */
     actions: MenuAction[];
+    /** The trigger's text. Android draws it in the accent colour, with a chevron. */
     label: string;
 };
 export type MenuComponent = (props: MenuProps) => ReactNode;

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

@@ -24,13 +24,16 @@ export type SheetHeaderProps = {
     leadingItems?: NavigationBarItem[];
     /** A search field in place of the title (iOS). */
     search?: NavigationBarSearch;
+    /** The title — in the bar, or above the content with a `large` `titleStyle`. */
     title?: string;
     /** `center` by default. */
     titleStyle?: SheetTitleStyle;
     /** In screen order, toward the trailing edge — the close item, by convention. */
     trailingItems?: NavigationBarItem[];
 };
+/** Imperative control of a `Sheet`, through its `ref`. */
 export type SheetRef = {
+    /** Dismisses it without calling `onDismiss`, which reports the user's dismissals only. */
     dismiss: () => Promise<void>;
     /** Presents at a detent — the first by default. */
     present: (detentIndex?: number) => Promise<void>;
@@ -45,6 +48,7 @@ export type SheetRef = {
 export type SheetProps = {
     /** The sheet's colour. `surface.primary` by default. */
     bg?: ColorToken;
+    /** The content. A `<Sheet.Header>` among the direct children becomes the native header instead. */
     children: ReactNode;
     /** Where the sheet can rest, smallest first. `['auto']` — fit the content — by default. */
     detents?: SheetDetent[];
@@ -60,29 +64,44 @@ export type SheetProps = {
     grabber?: boolean;
     /** The user dismissed it — `visible` going false does not call this. */
     onDismiss: () => void;
+    /** The sheet moved to another detent — its index in `detents`. */
     onDetentChange?: (detentIndex: number) => void;
+    /** The sheet finished presenting. */
     onPresent?: () => void;
+    /** `present`, `dismiss` and `resize`, for driving the sheet imperatively. */
     ref?: Ref<SheetRef>;
     /**
      * The content is a scroll view (`<Sheet.ScrollView>`) the sheet drives: dragging past its top resizes the sheet,
      * and a header scrolls with the iOS 26 edge effect. Off by default — set it with a scrolling body.
      */
     scrollable?: boolean;
+    /** Test identifier, forwarded to the native sheet. */
     testID?: string;
+    /** Presents the sheet while true; going false dismisses it. */
     visible: boolean;
 };
 export type SheetScrollHandler = (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
 /** What a scroll view inside a sheet needs: the room the header takes, the large title, the scroll listener. */
 export type SheetScrollContextValue = {
+    /** Render it first in the content. `null` unless the header's `titleStyle` is `large`. */
     largeTitle: ReactNode;
+    /** Forward the scroll view's scroll events to it — it tracks the large title. Unset when there is none. */
     onScroll?: SheetScrollHandler;
+    /** The room an overlaid header takes, to add to the content's top padding. `0` where the header sits above it. */
     topInset: number;
 };
+/**
+ * The body of a `scrollable` sheet: its content starts below an overlaid header, it carries a large title, and it
+ * reports its scroll to the sheet.
+ */
 export type SheetScrollViewProps = Pick<ScrollViewProps, 'keyboardShouldPersistTaps'> & {
+    /** The scrolling content, after the large title if there is one. */
     children: ReactNode;
     /** Styles the scrolling content — padding and gap belong here, as with `RnScrollView`. */
     content?: ResponsiveViewSx;
+    /** Called on every scroll event, after the sheet's own listener. */
     onScroll?: SheetScrollHandler;
+    /** Test identifier, forwarded to the scroll view. */
     testID?: string;
 };
 export type SheetComponent = ((props: SheetProps) => ReactNode) & {

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

@@ -1,8 +1,16 @@
 import type { ReactNode } from 'react';
+/**
+ * A short message laid over the bottom of its parent, with an optional action. The React Native tier, drawn the same on
+ * both platforms: it needs no host, and it never hides itself.
+ */
 export type SnackbarProps = {
+    /** The action button's text, on the trailing side. No button without it. */
     actionLabel?: string;
+    /** The message. */
     message: string;
+    /** The action was pressed. The snackbar stays up — turn `visible` off to hide it. */
     onAction?: () => void;
+    /** Shows the snackbar while true, fading it in and out. It sets no timer of its own. */
     visible: boolean;
 };
 export type SnackbarComponent = (props: SnackbarProps) => ReactNode;

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.8.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://www.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.8.0",
+    "@hzblj/kara-sx": "^0.8.0",
+    "@hzblj/kara-theme": "^0.8.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/activity-indicator/activity-indicator.android.tsx

@@ -0,0 +1,32 @@
+import {Host, LoadingIndicator} from '@expo/ui/jetpack-compose'
+import {fillMaxSize, testID as testIdModifier} from '@expo/ui/jetpack-compose/modifiers'
+import {useAppTheme} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
+import {StyleSheet} from 'react-native'
+
+import type {ActivityIndicatorComponent, ActivityIndicatorProps} from './activity-indicator.types'
+
+/** Material's 48dp for a screen; half of it in a row, about where React Native's small spinner sat. */
+const styles = StyleSheet.create({
+  large: {height: 48, width: 48},
+  small: {height: 24, width: 24},
+})
+
+/**
+ * Material 3's expressive `LoadingIndicator` in a host of its own, sized here rather than measured, so it renders
+ * anywhere and takes its place in the first frame.
+ */
+export const ActivityIndicator: ActivityIndicatorComponent = ({
+  color = 'fill.accent.primary',
+  size = 'small',
+  testID,
+}: ActivityIndicatorProps) => {
+  const theme = useAppTheme()
+  const modifiers = useMemo(() => (testID ? [fillMaxSize(), testIdModifier(testID)] : [fillMaxSize()]), [testID])
+
+  return (
+    <Host colorScheme={theme.dark ? 'dark' : 'light'} seedColor={theme.materialSeed} style={styles[size]}>
+      <LoadingIndicator color={theme.color(color)} modifiers={modifiers} />
+    </Host>
+  )
+}

package/src/atoms/activity-indicator/activity-indicator.ios.tsx

@@ -0,0 +1,15 @@
+import {useAppTheme} from '@hzblj/kara-theme'
+import {ActivityIndicator as RNActivityIndicator} from 'react-native'
+
+import type {ActivityIndicatorComponent, ActivityIndicatorProps} from './activity-indicator.types'
+
+/** React Native's spinner, which on iOS is UIKit's own `UIActivityIndicatorView`. */
+export const ActivityIndicator: ActivityIndicatorComponent = ({
+  color = 'fill.accent.primary',
+  size = 'small',
+  testID,
+}: ActivityIndicatorProps) => {
+  const theme = useAppTheme()
+
+  return <RNActivityIndicator color={theme.color(color)} size={size} testID={testID} />
+}

package/src/atoms/activity-indicator/activity-indicator.types.ts

@@ -0,0 +1,20 @@
+import type {ColorToken} from '@hzblj/kara-theme'
+import type {ReactNode} from 'react'
+
+export type ActivityIndicatorSize = 'large' | 'small'
+
+/**
+ * That something is loading, for as long as it takes — UIKit's spinner on iOS, Material 3's expressive
+ * `LoadingIndicator` on Android, its shapes morphing as it turns. A React Native view on iOS and a host of its own on
+ * Android, so it renders anywhere. For how far along something is, use `Progress`.
+ */
+export type ActivityIndicatorProps = {
+  /** Its colour. `fill.accent.primary` by default. */
+  color?: ColorToken
+  /** `small` sits in a row or a button, `large` holds a screen that is loading. `small` by default. */
+  size?: ActivityIndicatorSize
+  /** Test identifier, forwarded to the view. */
+  testID?: string
+}
+
+export type ActivityIndicatorComponent = (props: ActivityIndicatorProps) => ReactNode

package/src/atoms/activity-indicator/index.ts

@@ -1 +1,2 @@
 export * from './activity-indicator'
+export * from './activity-indicator.types'

package/src/atoms/avatar/avatar.tsx

@@ -32,7 +32,7 @@ export const Avatar: AvatarComponent = ({initials, size = 'md', source, testID}:
       w={diameter}
     >
       {source ? (
-        <Image source={source} style={{height: diameter, width: diameter}} />
+        <Image h={diameter} source={source} w={diameter} />
       ) : (
         <RnText color="content.secondary" variant={VARIANT[size]}>
           {initials ?? ''}

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/blur-view/blur-view.android.tsx

@@ -0,0 +1,68 @@
+import {BackdropBlurView} from '@hzblj/kara-native/jetpack-compose'
+import {useSx} from '@hzblj/kara-sx'
+import {type ColorToken, type OpacitySize, useAppTheme, withOpacity} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
+import {StyleSheet} from 'react-native'
+
+import type {BlurMaterial, BlurViewComponent, BlurViewProps} from './blur-view.types'
+
+type MaterialSpec = {
+  /** dp. */
+  blur: number
+  /** A Material tonal surface — the thicker the material, the higher the container. */
+  fill: ColorToken
+  /**
+   * How much of the surface covers the blur, light and dark. A dark material covers more, as iOS's do: a dark surface
+   * over a bright backdrop otherwise leaves light content on light colour.
+   */
+  opacity: {dark: OpacitySize; light: OpacitySize}
+  /** iOS's materials lift the colour of what they blur; a plain blur greys it into mud. */
+  saturation: number
+}
+
+const MATERIALS: Record<BlurMaterial, MaterialSpec> = {
+  regular: {blur: 28, fill: 'surface.secondary', opacity: {dark: 'o75', light: 'o60'}, saturation: 1.6},
+  thick: {blur: 30, fill: 'surface.secondary', opacity: {dark: 'o85', light: 'o80'}, saturation: 1.4},
+  thin: {blur: 24, fill: 'surface.primary', opacity: {dark: 'o60', light: 'o40'}, saturation: 1.7},
+  ultraThick: {blur: 32, fill: 'fill.quaternary', opacity: {dark: 'o90', light: 'o90'}, saturation: 1.2},
+  ultraThin: {blur: 20, fill: 'surface.base', opacity: {dark: 'o50', light: 'o25'}, saturation: 1.8},
+}
+
+/**
+ * The materials in Android's terms: kara's `BackdropBlurView` — what lies behind, blurred and saturated — under a
+ * Material tonal surface that gets higher and more opaque as the material thickens. Pinned to the appearance the app
+ * is not in, the surface is Material's inverse one. `vibrancy` has no Android counterpart and is left out.
+ */
+export const BlurView: BlurViewComponent = ({
+  appearance,
+  children,
+  material = 'regular',
+  testID,
+  vibrancy: _vibrancy,
+  ...sx
+}: BlurViewProps) => {
+  const theme = useAppTheme()
+  const resolved = useSx(sx)
+  const spec = MATERIALS[material]
+  const inverted = appearance !== undefined && (appearance === 'dark') !== theme.dark
+  const dark = appearance ? appearance === 'dark' : theme.dark
+  const base = String(theme.color(inverted ? 'surface.high.contrast' : spec.fill))
+  const {cornerRadius, style} = useMemo(() => {
+    const {borderRadius, ...rest} = StyleSheet.flatten(resolved) ?? {}
+    return {cornerRadius: typeof borderRadius === 'number' ? borderRadius : 0, style: rest}
+  }, [resolved])
+
+  return (
+    <BackdropBlurView
+      blurRadius={spec.blur}
+      cornerRadius={cornerRadius}
+      fallbackTint={withOpacity(base, 'o95')}
+      glassTint={withOpacity(base, spec.opacity[dark ? 'dark' : 'light'])}
+      saturation={spec.saturation}
+      style={style}
+      testID={testID}
+    >
+      {children}
+    </BackdropBlurView>
+  )
+}

package/src/atoms/blur-view/blur-view.ios.tsx

@@ -0,0 +1,37 @@
+import {BlurView as NativeBlurView} from '@hzblj/kara-native/swift-ui'
+import {useSx} from '@hzblj/kara-sx'
+import {useAppTheme} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
+import {StyleSheet} from 'react-native'
+
+import type {BlurViewComponent, BlurViewProps} from './blur-view.types'
+
+/** `borderRadius` is the material's shape, so it goes to the effect view — the one that clips — not the layout box. */
+export const BlurView: BlurViewComponent = ({
+  appearance,
+  children,
+  material = 'regular',
+  testID,
+  vibrancy,
+  ...sx
+}: BlurViewProps) => {
+  const theme = useAppTheme()
+  const resolved = useSx(sx)
+  const {cornerRadius, style} = useMemo(() => {
+    const {borderRadius, ...rest} = StyleSheet.flatten(resolved) ?? {}
+    return {cornerRadius: typeof borderRadius === 'number' ? borderRadius : 0, style: rest}
+  }, [resolved])
+
+  return (
+    <NativeBlurView
+      colorScheme={appearance ?? (theme.dark ? 'dark' : 'light')}
+      cornerRadius={cornerRadius}
+      material={material}
+      style={style}
+      testID={testID}
+      vibrancy={vibrancy}
+    >
+      {children}
+    </NativeBlurView>
+  )
+}

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

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

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

@@ -0,0 +1,2 @@
+export * from './blur-view'
+export * from './blur-view.types'

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
 }