@hzblj/kara-components 0.6.0 → 0.7.0

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

@@ -11,12 +11,22 @@ export type ButtonStyleName = 'automatic' | 'bordered' | 'borderedProminent' | '
  * whatever the surrounding SwiftUI environment provides.
  */
 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
@@ -24,7 +34,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;
 };
 export type ButtonComponent = (props: ButtonProps) => ReactNode;

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

@@ -1,7 +1,13 @@
 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;
 };
 export type CardComponent = (props: CardProps) => ReactNode;

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

@@ -1,8 +1,13 @@
 import type { ReactNode } from 'react';
+/** Material's `Checkbox` on Android. iOS has none, so there it is a SwiftUI `Toggle` — the same switch as `Switch`. */
 export type CheckboxProps = {
+    /** Dims the control and ignores taps. */
     disabled?: boolean;
+    /** Text beside the control. On Android the whole labelled row toggles it. */
     label?: string;
+    /** Called with the new value when the user toggles it. */
     onValueChange?: (value: boolean) => void;
+    /** Whether it is checked. Controlled — update it from `onValueChange`. */
     value: boolean;
 };
 export type CheckboxComponent = (props: CheckboxProps) => ReactNode;

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

@@ -1,8 +1,13 @@
 import type { ReactNode } from 'react';
+/** A filter pill on a `Pressable`, not a native control — the React Native tier, so it needs no host. */
 export type ChipProps = {
+    /** The text in the pill. */
     label: string;
+    /** Called when the chip is pressed, with the `selection` haptic. */
     onPress?: () => void;
+    /** Draws the chip in the accent colours. Off by default. */
     selected?: boolean;
+    /** Test identifier, forwarded to the view. */
     testID?: string;
 };
 export type ChipComponent = (props: ChipProps) => ReactNode;

package/lib/typescript/atoms/color-picker/color-picker.types.d.ts

@@ -4,9 +4,13 @@ import type { ReactNode } from 'react';
  * renders nothing and says so in dev. Branch on `Platform.OS` if the screen needs a fallback.
  */
 export type ColorPickerProps = {
+    /** Text beside the colour well. */
     label?: string;
+    /** Called with the colour the user picks. */
     onValueChange?: (color: string) => void;
+    /** Lets the user pick an opacity as well. Off by default. */
     supportsOpacity?: boolean;
+    /** Test identifier, forwarded to the native view. */
     testID?: string;
     /** `#RRGGBB` or `#RRGGBBAA`. */
     value: string | null;

package/lib/typescript/atoms/date-picker/date-picker.ios.d.ts

@@ -1,3 +1,8 @@
 import type { DatePickerComponent } from './date-picker.types';
-/** The system's compact date picker, inline: a tap on it opens the calendar popover UIKit owns. */
+/**
+ * The system's compact date picker: the value in a pill, and a tap on it opens the calendar popover UIKit owns. Its own
+ * host, sized to the pill on both axes — a host that took the width it was given would lay the pill out against the
+ * far edge of it, or past its container's — so it drops into a row the way a `Text` does. The label is the caller's,
+ * beside it; the calendar is in the accent.
+ */
 export declare const DatePicker: DatePickerComponent;

package/lib/typescript/atoms/date-picker/date-picker.types.d.ts

@@ -1,11 +1,25 @@
 import type { ReactNode } from 'react';
 export type DatePickerMode = 'date' | 'datetime' | 'time';
+/**
+ * A date or time picker — SwiftUI's compact `DatePicker` on iOS, a field that opens Material's picker dialog on a tap
+ * on Android. The React Native tier: it brings its own host and sizes itself to the value, so it sits in a row beside
+ * its label like a `Text`.
+ */
 export type DatePickerProps = {
+    /** The latest date that can be picked. Android ignores it in `time` mode. */
     max?: Date;
+    /** The earliest date that can be picked. Android ignores it in `time` mode. */
     min?: Date;
+    /**
+     * What it picks. `date` by default. Android has no combined dialog, so there `datetime` picks the date and keeps
+     * `value`'s time of day.
+     */
     mode?: DatePickerMode;
+    /** Called with the new date — on iOS as it changes, on Android when the dialog is confirmed. */
     onValueChange?: (date: Date) => void;
+    /** Test identifier — on the native picker on iOS, on the tappable field on Android. */
     testID?: string;
+    /** The selected date. Controlled — update it from `onValueChange`. */
     value: Date;
 };
 export type DatePickerComponent = (props: DatePickerProps) => ReactNode;

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

@@ -1,7 +1,10 @@
 import type { ColorToken } from '@hzblj/kara-theme';
 import type { ReactNode } from 'react';
+/** A horizontal hairline — SwiftUI `Divider` / Compose `HorizontalDivider`. */
 export type DividerProps = {
+    /** The line's colour. `border.tertiary` by default. */
     color?: ColorToken;
+    /** Test identifier, forwarded to the native view on iOS — Android ignores it. */
     testID?: string;
 };
 export type DividerComponent = (props: DividerProps) => ReactNode;

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

@@ -1,8 +1,15 @@
 import type { ReactNode } from 'react';
 import type { IconName } from '../icon';
+/**
+ * A floating action button — Material's `FloatingActionButton` on Android, a 56pt accent circle (a plain SwiftUI
+ * `Button`) on iOS. It renders inline; pinning it to a corner is up to the screen.
+ */
 export type FabProps = {
+    /** The icon, one of the app's, drawn in `content.on.bg`. */
     name: IconName;
+    /** Called when the button is pressed. */
     onPress?: () => void;
+    /** Test identifier, forwarded to the native view on iOS — Android ignores it. */
     testID?: string;
 };
 export type FabComponent = (props: FabProps) => ReactNode;

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

@@ -11,6 +11,7 @@ export type GlassViewProps = ResponsiveViewSx & {
     children?: ReactNode;
     /** Swells toward the finger on touch, carrying the children with it. Wrap the view in a `Pressable` for the press. */
     interactive?: boolean;
+    /** Test identifier, forwarded to the view. */
     testID?: string;
     /** Tints the material. Unset leaves it clear. */
     tint?: ColorToken;

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

@@ -2,11 +2,17 @@ import type { ResponsiveSx } from '@hzblj/kara-sx';
 import type { SpaceSize } from '@hzblj/kara-theme';
 import type { ReactNode } from 'react';
 export type HStackAlign = 'center' | 'end' | 'start';
+/** A horizontal stack — SwiftUI `HStack` / Compose `Row`. */
 export type HStackProps = ResponsiveSx & {
+    /** How the children line up vertically — `start` is the top, `end` the bottom. `start` by default. */
     align?: HStackAlign;
+    /** Native views, laid out from the leading edge. */
     children?: ReactNode;
+    /** Makes the stack pressable — a tap gesture on iOS, a `clickable` with Material's ripple on Android. */
     onPress?: () => void;
+    /** The gap between children. Unset, SwiftUI puts its default spacing between them and Compose none. */
     spacing?: SpaceSize;
+    /** Test identifier, forwarded to the native view. */
     testID?: string;
 };
 export type HStackComponent = (props: HStackProps) => ReactNode;

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

@@ -15,12 +15,20 @@ type DeclaredIconName = keyof KaraIcons & string;
  * 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;
+/**
+ * One of the app's icons, in a host — SwiftUI `Image` from the asset catalog on iOS, Material's `Icon` with the vector
+ * drawable on Android. `RnIcon` draws the same asset outside one.
+ */
 export type IconProps = {
     /** What a screen reader says. Unset, the icon is decorative and hidden from it. */
     accessibilityLabel?: string;
+    /** The icon's tint. `content.primary` by default. */
     color?: ColorToken;
+    /** Which of the app's icons — a key of `KaraIcons`. */
     name: IconName;
+    /** Its width and height, a spacing token. `s24` by default. */
     size?: SpaceSize;
+    /** Test identifier, forwarded to the native view on iOS — Android ignores it. */
     testID?: string;
 };
 export type IconComponent = (props: IconProps) => ReactNode;

package/lib/typescript/atoms/icon-button/icon-button.types.d.ts

@@ -1,9 +1,14 @@
 import type { ReactNode } from 'react';
 import type { IconName } from '../icon';
+/** A button that is just an icon — a plain SwiftUI `Button` on iOS, Material's `IconButton` on Android. */
 export type IconButtonProps = {
+    /** Draws the icon in `btn.content.disabled` and stops the button responding to presses. */
     disabled?: boolean;
+    /** The icon, one of the app's. */
     name: IconName;
+    /** Called when the button is pressed. */
     onPress?: () => void;
+    /** Test identifier, forwarded to the native view on iOS — Android ignores it. */
     testID?: string;
 };
 export type IconButtonComponent = (props: IconButtonProps) => ReactNode;

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

@@ -10,7 +10,6 @@ export * from './color-picker';
 export * from './date-picker';
 export * from './divider';
 export * from './fab';
-export * from './flash-list';
 export * from './glass-view';
 export * from './h-stack';
 export * from './icon';

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

@@ -1,6 +1,8 @@
 import type { ReactNode } from 'react';
 import type { StyleProp, ViewStyle } from 'react-native';
+/** A host for native atoms in a React Native layout — the SwiftUI / Compose `Host` an `@expo/ui` tree mounts into. */
 export type IslandProps = {
+    /** The native views it hosts. */
     children?: ReactNode;
     /**
      * Sizes the island's height to its native content while the width still comes from the parent, which
@@ -14,7 +16,9 @@ export type IslandProps = {
      * hangs the main thread as soon as the views lay out on screen.
      */
     matchContents?: boolean;
+    /** A React Native style for the host view — its size and placement. It needs a height when `matchContents` is off. */
     style?: StyleProp<ViewStyle>;
+    /** Test identifier, forwarded to the host view on iOS — Android ignores it. */
     testID?: string;
 };
 export type IslandComponent = (props: IslandProps) => ReactNode;

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

@@ -9,12 +9,14 @@ import type { ReactNode } from 'react';
  * the children is one too many: on iOS it becomes an empty row of its own.
  */
 export type ListProps = {
+    /** The rows — native views, one row each. */
     children: ReactNode;
     /**
      * Enables pull-to-refresh. Async on purpose — see `ScrollViewProps.onRefresh`: the spinner runs
      * until the promise settles, so neither platform needs a `refreshing` flag kept in sync by hand.
      */
     onRefresh?: () => Promise<void>;
+    /** Test identifier, forwarded to the native view on iOS — Android ignores it. */
     testID?: string;
 };
 export type ListComponent = (props: ListProps) => ReactNode;

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

@@ -1,13 +1,25 @@
 import type { ReactNode } from 'react';
+/** One choice of a `Picker`. */
 export type PickerOption = {
+    /** What the user reads. */
     label: string;
+    /** What `onValueChange` reports. It also keys the option, so it must be unique. */
     value: string;
 };
+/**
+ * A single choice from a list — a SwiftUI wheel picker on iOS, Material's exposed dropdown on Android. It brings its
+ * own host, so it renders outside `Screen` and `Island` as well.
+ */
 export type PickerProps = {
+    /** Stops the user changing the selection, and dims the picker. */
     disabled?: boolean;
+    /** Called with the chosen option's `value`. */
     onValueChange?: (value: string) => void;
+    /** The choices, in order. */
     options: PickerOption[];
+    /** Android: the dropdown field's test tag. iOS: `@expo/ui`'s wheel picker drops it. */
     testID?: string;
+    /** The selected option's `value`. Controlled: pass back what `onValueChange` reports. */
     value: string;
 };
 export type PickerComponent = (props: PickerProps) => ReactNode;

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

@@ -1,12 +1,20 @@
 import type { ResponsiveViewSx } from '@hzblj/kara-sx';
 import type { ReactNode } from 'react';
 import type { Haptic } from '../../haptics';
+/**
+ * React Native's `Pressable`, styled through `sx` like a `Box`: it springs down to 96% while pressed and takes
+ * touches 8 points past its edges. The React Native tier — it needs no host.
+ */
 export type PressableProps = ResponsiveViewSx & {
+    /** The pressable content. */
     children?: ReactNode;
+    /** Ignores presses — no `onPress`, no haptic, no spring. */
     disabled?: boolean;
     /** Played on press. `true` is a `light` impact; a name picks the haptic, e.g. `selection` for a choice. */
     haptic?: boolean | Haptic;
+    /** Called when the press is released, after the `haptic` plays. */
     onPress?: () => void;
+    /** Test identifier, forwarded to the view. */
     testID?: string;
 };
 export type PressableComponent = (props: PressableProps) => ReactNode;

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

@@ -1,6 +1,12 @@
 import type { ReactNode } from 'react';
+/**
+ * A progress bar or ring, tinted `fill.accent.primary` — SwiftUI `ProgressView` / Compose's
+ * `LinearProgressIndicator` and `CircularProgressIndicator`.
+ */
 export type ProgressProps = {
+    /** A circular indicator instead of a bar. Off by default. */
     circular?: boolean;
+    /** Between `0` and `1`. Leave it unset for an indeterminate indicator. */
     value?: number;
 };
 export type ProgressComponent = (props: ProgressProps) => ReactNode;

package/lib/typescript/atoms/rn-flat-list/rn-flat-list.d.ts

@@ -1,12 +1,9 @@
 import type { RnFlatListProps } from './rn-flat-list.types';
 /**
- * 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 declare const RnFlatList: <TItem>({ content, data, renderItem, ...props }: RnFlatListProps<TItem>) => import("react").JSX.Element;

package/lib/typescript/atoms/rn-flat-list/rn-flat-list.types.d.ts

@@ -2,8 +2,10 @@ import type { ResponsiveViewSx } from '@hzblj/kara-sx';
 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/lib/typescript/atoms/rn-scroll-view/rn-scroll-view.types.d.ts

@@ -11,9 +11,13 @@ import type { ScrollViewAxis } from '../scroll-view';
  * so padding and gap belong there.
  */
 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;
 };
 export type RnScrollViewComponent = (props: RnScrollViewProps) => ReactNode;

package/lib/typescript/atoms/rn-section-list/rn-section-list.d.ts

@@ -1,14 +1,8 @@
 import { type DefaultSectionT } from 'react-native';
 import type { RnSectionListProps } from './rn-section-list.types';
 /**
- * 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.

package/lib/typescript/atoms/rn-section-list/rn-section-list.types.d.ts

@@ -2,8 +2,10 @@ import type { ResponsiveViewSx } from '@hzblj/kara-sx';
 import type { DefaultSectionT, SectionListProps as RNSectionListProps } 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` 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/lib/typescript/atoms/rn-text/rn-text.types.d.ts

@@ -1,9 +1,13 @@
 import type { ColorToken, TextVariant } from '@hzblj/kara-theme';
 import type { ReactNode } from 'react';
 import type { TextProps as RNTextProps } from 'react-native';
+/** React Native's `Text` in a theme typography variant — the React Native tier, for text outside a native host. */
 export type RnTextProps = Omit<RNTextProps, 'style'> & {
+    /** 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,14 @@
 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. */
 export type SkeletonProps = {
+    /** The corner radius. `small` by default. */
     borderRadius?: RadiiSize;
+    /** In points. */
     height: number;
+    /** Test identifier, forwarded to the view. */
     testID?: string;
+    /** In points. Leave it unset and it fills the available width. */
     width?: number;
 };
 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

@@ -3,14 +3,26 @@ import type { ReactNode } from 'react';
 export type TextAlign = 'center' | 'left' | 'right';
 export type TextDecoration = 'none' | 'strikethrough' | 'underline';
 export type TextTransform = 'lowercase' | 'uppercase';
+/** SwiftUI `Text` / Compose `Text` in a theme typography variant — a native atom; outside a host, use `RnText`. */
 export type TextProps = {
+    /**
+     * 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;