@hzblj/kara-components 0.5.0 → 0.7.0

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,10 +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;
-    haptic?: 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,2 +1 @@
-import type { SegmentedControlComponent } from './segmented-control.types';
-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;

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/haptics/haptics.d.ts

@@ -0,0 +1,61 @@
+import { type Haptic } from '@hzblj/kara-native';
+export type { Haptic };
+export type HapticOptions = {
+    /** iOS: scales an impact — `soft`, `light`, `medium`, `rigid`, `heavy` — from 0 to 1. Everything else ignores it. */
+    intensity?: number;
+};
+declare const play: (haptic: Haptic, options?: HapticOptions) => void;
+declare const prepare: (haptic: Haptic) => void;
+/**
+ * The platform's own haptic feedback, named for what happened: UIKit's feedback generators on iOS, the system's
+ * `HapticFeedbackConstants` on Android — never a raw vibration. Both follow the user's system haptics setting, and
+ * every call is synchronous, with nothing to await.
+ *
+ * ```ts
+ * haptics.success()                    // a name you know: one function per haptic
+ * haptics.play(haptic)                 // a name that arrives as data
+ * haptics.light({intensity: 0.6})      // impacts scale on iOS
+ * haptics.prepare('selection')         // iOS: warm the Taptic Engine as a gesture begins
+ * haptics.setEnabled(userPreference)   // silences every kara haptic, the components' own too
+ * ```
+ *
+ * - `selection` — a choice changed: a segment, a chip, a picker row.
+ * - `tick` — one step of a continuous gesture: a slider detent, a scrubbed value.
+ * - `toggleOn` / `toggleOff` — a switch flipped.
+ * - `success` / `warning` / `error` — how a task ended. Android has no warning of its own; it plays a rejection.
+ * - `longPress` / `dragStart` — a long press was recognised; an item lifted to be dragged.
+ * - `thresholdActivate` / `thresholdDeactivate` — a gesture crossed its commit point, or went back over it.
+ * - `keyPress` — a key of the app's own keypad.
+ * - `soft`, `light`, `medium`, `rigid`, `heavy` — a collision none of the names above describes.
+ *
+ * On Android the names that came with Android 14's constants fall back to the nearest older feedback, so every name
+ * plays on every version. Haptics are silent in a build without kara's native module.
+ */
+export declare const haptics: {
+    /** Whether kara plays haptics — `true` until `setEnabled(false)`. */
+    isEnabled: () => boolean;
+    play: typeof play;
+    prepare: typeof prepare;
+    /**
+     * Switches every kara haptic on or off, the ones its components play included — for an app's own "Haptics" setting.
+     * Not persisted: call it at start-up with the stored preference. The system setting applies either way.
+     */
+    setEnabled: (value: boolean) => void;
+    dragStart: (options?: HapticOptions) => void;
+    error: (options?: HapticOptions) => void;
+    heavy: (options?: HapticOptions) => void;
+    keyPress: (options?: HapticOptions) => void;
+    light: (options?: HapticOptions) => void;
+    longPress: (options?: HapticOptions) => void;
+    medium: (options?: HapticOptions) => void;
+    rigid: (options?: HapticOptions) => void;
+    selection: (options?: HapticOptions) => void;
+    soft: (options?: HapticOptions) => void;
+    success: (options?: HapticOptions) => void;
+    thresholdActivate: (options?: HapticOptions) => void;
+    thresholdDeactivate: (options?: HapticOptions) => void;
+    tick: (options?: HapticOptions) => void;
+    toggleOff: (options?: HapticOptions) => void;
+    toggleOn: (options?: HapticOptions) => void;
+    warning: (options?: HapticOptions) => void;
+};

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

@@ -0,0 +1,2 @@
+export { type Haptic, type HapticOptions, haptics } from './haptics';
+export { type HapticResolver, useHapticFeedback } from './use-haptic-feedback';

package/lib/typescript/haptics/use-haptic-feedback.d.ts

@@ -0,0 +1,15 @@
+import { type Haptic } from './haptics';
+/** Picks the haptic for one change of a trigger — or none, to stay silent for that change. */
+export type HapticResolver<T> = (previous: T, next: T) => Haptic | false | null | undefined;
+/**
+ * Plays a haptic whenever `trigger` changes — never on mount — like SwiftUI's `sensoryFeedback(_:trigger:)`. Give it
+ * a haptic, or a function of the previous and next value that picks one per change. Changes are compared with
+ * `Object.is`, so a trigger is a primitive or a stable reference.
+ *
+ * ```ts
+ * useHapticFeedback(tab, 'selection')
+ * useHapticFeedback(quantity, (before, after) => (after > before ? 'tick' : 'soft'))
+ * useHapticFeedback(payment.status, (_, status) => status === 'paid' ? 'success' : status === 'failed' && 'error')
+ * ```
+ */
+export declare const useHapticFeedback: <T>(trigger: T, feedback: Haptic | HapticResolver<T>) => void;

package/lib/typescript/index.d.ts

@@ -1,4 +1,5 @@
 export * from './atoms';
+export * from './haptics';
 export * from './molecules';
 export * from './organisms';
 export * from './templates';

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;