@hzblj/kara-components 0.6.0 → 0.8.0

package/lib/typescript/atoms/rn-text/rn-text.types.d.ts

@@ -1,9 +1,18 @@
+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'> & {
+/**
+ * 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/lib/typescript/atoms/rn-view/rn-view.types.d.ts

@@ -1,4 +1,5 @@
 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
@@ -14,6 +15,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;
 };
 export type RnViewComponent = (props: RnViewProps) => ReactNode;

package/lib/typescript/atoms/scroll-view/scroll-view.types.d.ts

@@ -7,7 +7,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
@@ -19,7 +21,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;
 };
 export type ScrollViewComponent = (props: ScrollViewProps) => ReactNode;

package/lib/typescript/atoms/segmented-control/segmented-control.d.ts

@@ -1,6 +1 @@
-import type { SegmentedControlComponent } from './segmented-control.types';
-/**
- * `UISegmentedControl` on iOS, Material's single-choice segmented buttons on Android. A new segment plays `selection`
- * on Android, whose buttons play nothing of their own; iOS 26's control already gives its own feedback.
- */
-export declare const SegmentedControl: SegmentedControlComponent;
+export * from './segmented-control.ios';

package/lib/typescript/atoms/segmented-control/segmented-control.ios.d.ts

@@ -0,0 +1,7 @@
+import type { SegmentedControlComponent } 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 declare const SegmentedControl: SegmentedControlComponent;

package/lib/typescript/atoms/segmented-control/segmented-control.types.d.ts

@@ -1,9 +1,22 @@
 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[];
 };
 export type SegmentedControlComponent = (props: SegmentedControlProps) => ReactNode;

package/lib/typescript/atoms/skeleton/skeleton.types.d.ts

@@ -1,9 +1,18 @@
+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/lib/typescript/atoms/slider/slider.types.d.ts

@@ -1,10 +1,17 @@
 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;
 };
 export type SliderComponent = (props: SliderProps) => ReactNode;

package/lib/typescript/atoms/spacer/spacer.types.d.ts

@@ -1,7 +1,10 @@
 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;
 };
 export type SpacerComponent = (props: SpacerProps) => ReactNode;

package/lib/typescript/atoms/surface/surface.types.d.ts

@@ -1,8 +1,15 @@
 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;
 };
 export type SurfaceComponent = (props: SurfaceProps) => ReactNode;

package/lib/typescript/atoms/switch/switch.types.d.ts

@@ -1,8 +1,16 @@
 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;
 };
 export type SwitchComponent = (props: SwitchProps) => ReactNode;

package/lib/typescript/atoms/text/text.types.d.ts

@@ -1,16 +1,33 @@
+import type { ResponsiveSx } from '@hzblj/kara-sx';
 import type { ColorToken, TextVariant } from '@hzblj/kara-theme';
 import type { ReactNode } from 'react';
 export type TextAlign = 'center' | 'left' | 'right';
 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;
 };
 export type TextComponent = (props: TextProps) => ReactNode;

package/lib/typescript/atoms/text-field/text-field.types.d.ts

@@ -1,12 +1,24 @@
 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;
 };
 export type TextFieldComponent = (props: TextFieldProps) => ReactNode;

package/lib/typescript/atoms/v-stack/v-stack.types.d.ts

@@ -2,11 +2,20 @@ import type { ResponsiveSx } from '@hzblj/kara-sx';
 import type { SpaceSize } from '@hzblj/kara-theme';
 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;
 };
 export type VStackComponent = (props: VStackProps) => ReactNode;

package/lib/typescript/atoms/z-stack/z-stack.types.d.ts

@@ -1,10 +1,18 @@
 import type { ResponsiveSx } from '@hzblj/kara-sx';
 import type { ReactNode } from 'react';
 export type ZStackAlign = 'bottom' | 'center' | 'top';
+/** Layers its children on one another — SwiftUI `ZStack` / Compose `Box`. */
 export type ZStackProps = ResponsiveSx & {
+    /** Where the children sit vertically; they are always centred horizontally. `center` by default. */
     align?: ZStackAlign;
+    /** Drawn in order, the last on top. */
     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;
+    /** Test identifier, forwarded to the native view. */
     testID?: string;
 };
 export type ZStackComponent = (props: ZStackProps) => ReactNode;

package/lib/typescript/molecules/collapsible/collapsible.types.d.ts

@@ -1,8 +1,16 @@
 import type { ReactNode } from 'react';
+/**
+ * A row that shows and hides its content: SwiftUI's `DisclosureGroup` on iOS; on Android a pressable row with a
+ * chevron over an animated reveal. A native atom — it renders inside `<Screen>` or `<Island>`.
+ */
 export type CollapsibleProps = {
+    /** Shown while `expanded`. */
     children: ReactNode;
+    /** Whether the content is shown. Update it from `onExpandedChange`. */
     expanded: boolean;
+    /** The row's text. */
     label: string;
+    /** The user pressed the row; it passes the state the row asks for. */
     onExpandedChange: (expanded: boolean) => void;
 };
 export type CollapsibleComponent = (props: CollapsibleProps) => ReactNode;

package/lib/typescript/molecules/empty-state/empty-state.types.d.ts

@@ -5,10 +5,15 @@ import type { IconName } from '../../atoms/icon';
  * `action` takes a `Button` so the state can offer a way out.
  */
 export type EmptyStateProps = {
+    /** Under the text — a `Button`, say. */
     action?: ReactNode;
+    /** A second line under the title, in the secondary colour. */
     description?: string;
+    /** One of the app's icons, large and muted above the title. */
     icon?: IconName;
+    /** Test identifier, forwarded to the native view. */
     testID?: string;
+    /** The headline. */
     title: string;
 };
 export type EmptyStateComponent = (props: EmptyStateProps) => ReactNode;

package/lib/typescript/molecules/label/label.types.d.ts

@@ -6,11 +6,17 @@ import type { IconName } from '../../atoms/icon';
  * header. For a full tappable row with a subtitle and chevron, use `ListItem`.
  */
 export type LabelProps = {
+    /** Colours the icon and the title alike. `content.primary` by default. */
     color?: ColorToken;
+    /** One of the app's icons, before the title. */
     icon: IconName;
+    /** The icon's size. `s20` by default. */
     iconSize?: SpaceSize;
+    /** Test identifier, forwarded to the native view. */
     testID?: string;
+    /** The text beside the icon. */
     title: string;
+    /** The title's text style. `body` by default. */
     variant?: TextVariant;
 };
 export type LabelComponent = (props: LabelProps) => ReactNode;

package/lib/typescript/molecules/labeled-content/labeled-content.types.d.ts

@@ -6,13 +6,19 @@ import type { IconName } from '../../atoms/icon';
  * Pass `children` instead of `value` when the trailing side is a control rather than text.
  */
 export type LabeledContentProps = {
+    /** The trailing side when it is a control, in place of `value`. */
     children?: ReactNode;
+    /** One of the app's icons, before the label, in the secondary colour. */
     icon?: IconName;
+    /** The leading text. */
     label: string;
+    /** Makes the row pressable and adds a chevron on the trailing edge. */
     onPress?: () => void;
     /** Horizontal padding inside the row — inside its press area too, so Android's ripple reaches the card's edges. */
     px?: SpaceSize;
+    /** Test identifier, forwarded to the native view. */
     testID?: string;
+    /** The trailing text, in the secondary colour. Ignored when `children` is given. */
     value?: string;
 };
 export type LabeledContentComponent = (props: LabeledContentProps) => ReactNode;

package/lib/typescript/molecules/link/link.types.d.ts

@@ -3,11 +3,17 @@ import type { ReactNode } from 'react';
 import type { IconName } from '../../atoms/icon';
 /** Opens an external URL in the platform browser or the app that claims the scheme. */
 export type LinkProps = {
+    /** Colours the label and the icon. `content.accent` by default. */
     color?: ColorToken;
+    /** One of the app's icons, before the label. */
     icon?: IconName;
+    /** The link's text. */
     label: string;
+    /** Test identifier, forwarded to the native view. */
     testID?: string;
+    /** Opened through React Native's `Linking` on press. A URL nothing can open fails silently. */
     url: string;
+    /** The label's text style. `body` by default. */
     variant?: TextVariant;
 };
 export type LinkComponent = (props: LinkProps) => ReactNode;

package/lib/typescript/molecules/list-item/list-item.types.d.ts

@@ -1,16 +1,25 @@
 import type { SpaceSize } from '@hzblj/kara-theme';
 import type { ReactNode } from 'react';
 import type { IconName } from '../../atoms/icon';
+/**
+ * A row with an optional icon, a title and subtitle, and a chevron when it can be pressed. A native atom — it renders
+ * inside `<Screen>` or `<Island>`; `RnListItem` is the same row without a host.
+ */
 export type ListItemProps = {
+    /** One of the app's icons, before the title, in the secondary colour. */
     icon?: IconName;
+    /** Makes the row pressable and adds a chevron on the trailing edge. */
     onPress?: () => void;
     /**
      * Horizontal padding inside the row — inside its press area too, so Android's ripple reaches the card's edges. For
      * rows in a card of your own; a `List` insets its rows by itself.
      */
     px?: SpaceSize;
+    /** A second line under the title, smaller and in the secondary colour. */
     subtitle?: string;
+    /** Test identifier, forwarded to the row's view. */
     testID?: string;
+    /** The row's main text. */
     title: string;
 };
 export type ListItemComponent = (props: ListItemProps) => ReactNode;

package/lib/typescript/molecules/navigation-bar/navigation-bar.types.d.ts

@@ -1,6 +1,7 @@
 import type { ReactNode, Ref } from 'react';
 import type { IconName } from '../../atoms/icon';
 type NavigationBarItemBase = {
+    /** Called when the item is pressed. */
     onPress: () => void;
     /**
      * iOS 26: neighbouring items on one side share a glass capsule; this gives the item its own. A close next to
@@ -29,10 +30,15 @@ export type NavigationBarSearchRef = {
 };
 /** A search field in place of the title — iOS only for now; Android keeps the title. */
 export type NavigationBarSearch = {
+    /** Every edit of the field's text. */
     onChangeText: (text: string) => void;
+    /** The field gained or lost focus. */
     onFocusChange?: (focused: boolean) => void;
+    /** Shown while the field is empty. */
     placeholder: string;
+    /** Imperative `clear`. */
     ref?: Ref<NavigationBarSearchRef>;
+    /** Test identifier, forwarded to the native search field. */
     testID?: string;
 };
 export type NavigationBarTitleAlignment = 'center' | 'leading';
@@ -50,7 +56,9 @@ export type NavigationBarProps = {
     leadingItems?: NavigationBarItem[];
     /** Replaces the title with a search field (iOS). */
     search?: NavigationBarSearch;
+    /** Test identifier, forwarded to the native bar. iOS only — Android ignores it. */
     testID?: string;
+    /** The bar's title. */
     title?: string;
     /** `center` by default — iOS's own; `leading` is Material's top app bar. */
     titleAlignment?: NavigationBarTitleAlignment;

package/lib/typescript/molecules/pager/pager.types.d.ts

@@ -10,6 +10,7 @@ import type { ReactNode } from 'react';
  * ceremony would buy nothing.
  */
 export type PagerProps = {
+    /** The pages, one per child, in order. */
     children?: ReactNode;
     /**
      * Page dots. iOS draws SwiftUI's own, over the bottom edge; Compose has no built-in indicator, so
@@ -27,6 +28,7 @@ export type PagerProps = {
      * content down with the swipe, so iOS always stays swipeable.
      */
     scrollEnabled?: boolean;
+    /** Test identifier, forwarded to the native view. */
     testID?: string;
 };
 export type PagerComponent = (props: PagerProps) => ReactNode;

package/lib/typescript/molecules/radio-group/radio-group.types.d.ts

@@ -1,11 +1,21 @@
 import type { ReactNode } from 'react';
+/** One choice of a `RadioGroup`. */
 export type RadioOption = {
+    /** The option's text. */
     label: string;
+    /** Identifies the option to `value` and `onValueChange`, and keys its row — keep it unique. */
     value: string;
 };
+/**
+ * A single choice from a list: rows with a checkmark on the selected one on iOS, Material radio buttons on Android. A
+ * native atom — it renders inside `<Screen>` or `<Island>`.
+ */
 export type RadioGroupProps = {
+    /** The user pressed an option; it passes that option's `value`. */
     onValueChange?: (value: string) => void;
+    /** The choices, top to bottom. */
     options: RadioOption[];
+    /** The selected option's `value`. Update it from `onValueChange`. */
     value: string;
 };
 export type RadioGroupComponent = (props: RadioGroupProps) => ReactNode;

package/lib/typescript/molecules/rn-list-item/rn-list-item.types.d.ts

@@ -2,7 +2,7 @@ import type { ReactNode } from 'react';
 import type { ListItemProps } from '../list-item';
 /**
  * `ListItem`'s row in the React Native tier — plain views, no host. For lists long enough that a native host per row
- * would cost too much to mount (a navigation list, a FlashList of rows), with the platform's own press feedback: a
+ * would cost too much to mount (a navigation list, an `RnFlatList` of rows), with the platform's own press feedback: a
  * ripple across the whole row on Android, a highlight on iOS. In a rounded card, give the card `overflow="hidden"`:
  * Android draws the ripple as the row's foreground, which only a parent's clip keeps inside rounded corners.
  */

package/lib/typescript/molecules/rn-tooltip/rn-tooltip.types.d.ts

@@ -1,7 +1,10 @@
 import type { ReactElement, ReactNode } from 'react';
 export type RnTooltipActionVariant = 'link' | 'primary' | 'secondary';
+/** A button in an `RnTooltip`. */
 export type RnTooltipAction = {
+    /** The button's text. */
     label: string;
+    /** Called on press. The tooltip stays up — turn `visible` off here if the action should close it. */
     onPress: () => void;
     /** `link` by default — an underlined text. `primary`/`secondary` are small filled/outlined buttons. */
     variant?: RnTooltipActionVariant;
@@ -14,6 +17,7 @@ export type RnTooltipDismissReason = 'anchorHidden' | 'outside';
  * Native tier, unlike `Tooltip`, whose anchor is a native view inside a host.
  */
 export type RnTooltipProps = {
+    /** A row of buttons under the text, in order. */
     actions?: RnTooltipAction[];
     /** Which end of the bubble the actions sit at. `end` by default. */
     actionsAlignment?: 'end' | 'start';
@@ -27,11 +31,18 @@ export type RnTooltipProps = {
     };
     /** The anchor — a single React Native view. */
     children: ReactElement;
+    /** The body text, under the title. */
     message?: string;
+    /**
+     * Asks for the tooltip to close, with the reason — turn `visible` off. On Android any touch outside asks, the start
+     * of a scroll included; iOS keeps the tooltip through a scroll.
+     */
     onDismiss: (reason: RnTooltipDismissReason) => void;
     /** The appear animation finished. */
     onShown?: () => void;
+    /** The heading line, above the message. */
     title?: string;
+    /** Shows the tooltip while true. It never hides itself. */
     visible: boolean;
 };
 export type RnTooltipComponent = (props: RnTooltipProps) => ReactNode;

package/lib/typescript/molecules/scroll-edge-container/scroll-edge-container.types.d.ts

@@ -3,8 +3,10 @@ import type { ResponsiveViewSx } from '@hzblj/kara-sx';
 import type { ReactElement, ReactNode } from 'react';
 export type { ScrollEdgeEffect, ScrollEdgeScrollableProps } from '@hzblj/kara-native/swift-ui';
 /**
- * Bars over one React Native scroll view, with the iOS 26 scroll edge effect under them — the system's progressive
- * blur where content scrolls past a bar. The React Native tier: it needs no host.
+ * Bars over one React Native scroll view, with each platform's scroll edge under them — on iOS 26 the system's
+ * progressive blur where content scrolls past a bar; on Android a Material top app bar's behaviour, the bars stacked
+ * around the scroll view and filling with `surface.secondary` once content scrolls under them. The React Native tier:
+ * it needs no host.
  *
  * A screen-level container: wrap the screen's scroll view with it. Mounted inside a cell of a virtualized list on iOS
  * it draws only its bottom bar — the hosted scroll view and the top bar stay blank.
@@ -15,12 +17,15 @@ export type ScrollEdgeContainerProps = ResponsiveViewSx & {
      * content begins below the top bar and scrolls under it. On by default.
      */
     automaticInsets?: boolean;
+    /** Laid over the scroll view's bottom edge on iOS; stacked below it on Android, filled while content continues below. */
     bottomBar?: ReactNode;
     /** Exactly one React Native scroll view — `RnScrollView`, `RnFlatList`, `RnSectionList`. */
     children: ReactElement<ScrollEdgeScrollableProps>;
     /** iOS 26: how hard the edge cuts. `soft` by default. */
     effect?: ScrollEdgeEffect;
+    /** Test identifier, forwarded to the container view. */
     testID?: string;
+    /** Laid over the scroll view's top edge on iOS; stacked above it on Android, filled once content scrolls under it. */
     topBar?: ReactNode;
 };
 export type ScrollEdgeContainerComponent = (props: ScrollEdgeContainerProps) => ReactNode;

package/lib/typescript/molecules/search-bar/search-bar.types.d.ts

@@ -1,8 +1,16 @@
 import type { ReactNode } from 'react';
+/**
+ * A search field drawn the same on both platforms — a rounded box with a magnifier, a `TextInput` and a clear button
+ * while there is text. The React Native tier: it needs no host.
+ */
 export type SearchBarProps = {
+    /** Every edit, and `''` when the clear button is pressed. */
     onChangeText?: (text: string) => void;
+    /** Shown while the field is empty. `Search` by default. */
     placeholder?: string;
+    /** Test identifier, put on the field's container view rather than on the `TextInput`. */
     testID?: string;
+    /** The field's text. Controlled — pass back what `onChangeText` reports. */
     value: string;
 };
 export type SearchBarComponent = (props: SearchBarProps) => ReactNode;

package/lib/typescript/molecules/stepper/stepper.ios.d.ts

@@ -1,2 +1,7 @@
 import type { StepperComponent } from './stepper.types';
+/**
+ * SwiftUI's `Stepper` at the end of a row, the label leading and the value just before the control — the way iOS's own
+ * settings show a stepped value. The value rolls to the next one (`numericText`), up or down with the change, in
+ * monospaced digits so the row does not jump.
+ */
 export declare const Stepper: StepperComponent;

package/lib/typescript/molecules/stepper/stepper.types.d.ts

@@ -1,10 +1,20 @@
 import type { ReactNode } from 'react';
+/**
+ * A number with minus and plus buttons beside a label: SwiftUI's `Stepper` on iOS; on Android the label, the value and
+ * two icon buttons in a row. A native atom — it renders inside `<Screen>` or `<Island>`.
+ */
 export type StepperProps = {
+    /** The leading text. The value is shown too — before the control on iOS, between the buttons on Android. */
     label: string;
+    /** The highest value. When unset, Android has no upper limit and iOS stops at `100`. */
     max?: number;
+    /** The lowest value. When unset, Android has no lower limit and iOS stops at `0`. */
     min?: number;
+    /** A button was pressed; it passes the new value, kept within `min` and `max`. */
     onValueChange: (value: number) => void;
+    /** How much one press adds or takes away. `1` by default. */
     step?: number;
+    /** The current value. Update it from `onValueChange`. iOS's native stepper counts in whole numbers. */
     value: number;
 };
 export type StepperComponent = (props: StepperProps) => ReactNode;

package/lib/typescript/molecules/tooltip/tooltip.types.d.ts

@@ -1,8 +1,20 @@
 import type { ReactNode } from 'react';
+/**
+ * A short text tip on a native view, shown while `visible` — a SwiftUI popover from `children` on iOS, Material's plain
+ * tooltip centred above them on Android. A native atom — it renders inside `<Screen>` or `<Island>`; `RnTooltip`
+ * anchors to a React Native view.
+ */
 export type TooltipProps = {
+    /** The anchor — a native view. */
     children: ReactNode;
+    /** The tip. */
     text: string;
+    /** Shows the tip while true. Controlled: nothing opens it but this — wire a long press to it if you want one. */
     visible: boolean;
+    /**
+     * The user dismissed the tip — turn `visible` off. iOS: a tap outside the popover. Android: any touch outside it, the
+     * start of a scroll included, or the anchor scrolling out of the window.
+     */
     onDismiss: () => void;
 };
 export type TooltipComponent = (props: TooltipProps) => ReactNode;