@hzblj/kara-components 0.9.0 → 0.11.0

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

@@ -3,7 +3,7 @@ import type { ReactNode } from 'react';
 import type { ScrollViewProps as RNScrollViewProps } from 'react-native';
 import type { ScrollViewAxis } from '../scroll-view';
 /**
- * React Native tier scroll container — the sibling of `RnView`/`RnText`. Use it when the
+ * React Native tier scroll container, the sibling of `RnView`/`RnText`. Use it when the
  * subtree is React Native and native atoms are embedded through `Island`. For a screen that
  * is native all the way down, reach for the `ScrollView` atom instead.
  *
@@ -15,7 +15,7 @@ export type RnScrollViewProps = ResponsiveViewSx & Omit<RNScrollViewProps, 'cont
     axis?: ScrollViewAxis;
     /** The scrolling content. */
     children?: ReactNode;
-    /** Styles the scrolling content container — padding and gap belong here. */
+    /** Styles the scrolling content container; padding and gap belong here. */
     content?: ResponsiveViewSx;
     /** Shows the scroll indicators. On by default. */
     showsIndicators?: boolean;

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

@@ -2,10 +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`. `removeClippedSubviews` is off unless
+ * 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. */
+    /** Styles the scrolling content container; padding and gap belong here. */
     content?: ResponsiveViewSx;
 };

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

@@ -3,8 +3,8 @@ 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. It takes
- * `Box`'s `sx` surface for its own box — margins, flex, padding, a background — all but `align`, which here aligns the
+ * 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'> & {

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

@@ -1,11 +1,11 @@
 import type { ReactElement, ReactNode } from 'react';
-/** Carries a React Native view into a SwiftUI or Compose tree — `@expo/ui`'s `RNHostView` on both platforms. */
+/** 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
      * `RawText` node, which has no component view, so mounting it across the SwiftUI host boundary
      * fails the `RCTComponentViewFactory` assertion and takes the whole app down. `@expo/ui` states
-     * the rule itself in `ListItem.ios.tsx` — "SwiftUI hosts can't render bare strings" — and wraps
+     * the rule itself in `ListItem.ios.tsx` ("SwiftUI hosts can't render bare strings") and wraps
      * every raw string in a SwiftUI `Text` before it reaches a host. Do the same: use the `Text` atom
      * inside the host, and keep `RnText` outside it.
      */
@@ -15,7 +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`. */
+    /** 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

@@ -3,7 +3,7 @@ import type { SpaceSize } from '@hzblj/kara-theme';
 import type { ReactNode } from 'react';
 export type ScrollViewAxis = 'horizontal' | 'vertical';
 /**
- * The `sx` props style the scrolling *content* container, not the viewport — `p` behaves
+ * The `sx` props style the scrolling *content* container, not the viewport: `p` behaves
  * like React Native's `contentContainerStyle` padding and scrolls with the content.
  */
 export type ScrollViewProps = ResponsiveSx & {
@@ -13,13 +13,13 @@ export type ScrollViewProps = ResponsiveSx & {
     children?: ReactNode;
     /**
      * Enables pull-to-refresh. Async on purpose: the spinner runs until the promise settles, which is
-     * what SwiftUI's `refreshable` expects and what Compose's controlled indicator is driven from — so
+     * what SwiftUI's `refreshable` expects and what Compose's controlled indicator is driven from, so
      * neither platform needs a separate `refreshing` flag to be kept in sync by the caller.
      *
      * Only a vertical scroll view can be pulled; on a horizontal one both platforms ignore it.
      */
     onRefresh?: () => Promise<void>;
-    /** iOS only — Compose exposes no indicator toggle, so Android always shows the native one. */
+    /** iOS only: Compose exposes no indicator toggle, so Android always shows the native one. */
     showsIndicators?: boolean;
     /** The space between children. */
     spacing?: SpaceSize;

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

@@ -1,6 +1,6 @@
 import type { ReactNode } from 'react';
 /**
- * A row of mutually exclusive segments, the selected one in the accent — kara's own `UISegmentedControl` on iOS,
+ * 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.
  */
@@ -8,13 +8,13 @@ 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.
+     * 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. */
+    /** Test identifier, on the whole control. Reach a segment by its label. */
     testID?: string;
     /** The segments' labels, in order. */
     values: string[];

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

@@ -2,7 +2,8 @@ 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
+ * A loading placeholder that pulses in `fill.quaternary`, and holds still with motion reduced. Hidden from screen
+ * readers: what is loading is for the screen to say. It is a React Native view, so it needs no host. Sized with the
  * `sx` names: `w`, `h`, `borderRadius`.
  */
 export type SkeletonProps = {

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

@@ -1,6 +1,6 @@
 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)`. */
+/** 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;

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

@@ -1,10 +1,10 @@
-import type { ResponsiveSx } from '@hzblj/kara-sx';
+import type { AccessibilityProps, ResponsiveSx } from '@hzblj/kara-sx';
 import type { ReactNode } from 'react';
 /**
- * A container on `surface.primary`, padded `s16` and rounded `large` unless told otherwise — a SwiftUI `VStack` on
+ * A container on `surface.primary`, 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 & {
+export type SurfaceProps = ResponsiveSx & AccessibilityProps & {
     /** Stacked vertically, from the leading edge. */
     children?: ReactNode;
     /** iOS wraps the content in a `GlassEffectContainer`; Android raises it to a tonal elevation of `3`. */

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

@@ -4,7 +4,7 @@ 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
+     * 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;

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

@@ -1,15 +1,15 @@
-import type { ResponsiveSx } from '@hzblj/kara-sx';
+import type { AccessibilityProps, 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';
 /**
- * SwiftUI `Text` / Compose `Text` in a theme typography variant — a native atom; outside a host, use `RnText`. It takes
+ * 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 & {
+export type TextProps = ResponsiveSx & AccessibilityProps & {
     /**
      * 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.

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

@@ -1,16 +1,16 @@
 import type { ReactNode } from 'react';
 /**
- * An uncontrolled text field with an optional label above it — SwiftUI `TextField` (`SecureField` when `secure`) /
+ * 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. */
+    /** 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. A message is shown under the field as well — on Android
-     * as Material's supporting text, beside its error icon — so the error never rests on colour alone; Material's error
+     * Marks the field invalid: a destructive outline and label. A message is shown under the field as well (on Android
+     * as Material's supporting text, beside its error icon), so the error never rests on colour alone; Material's error
      * colour is a pale red in dark mode. `true` marks it without a message.
      */
     error?: boolean | string;

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

@@ -1,16 +1,16 @@
-import type { ResponsiveSx } from '@hzblj/kara-sx';
+import type { AccessibilityProps, 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 & {
+/** Stacks its children top to bottom: SwiftUI `VStack` / Compose `Column`. */
+export type VStackProps = ResponsiveSx & AccessibilityProps & {
     /** 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.
+     * fills the stack's shape. Screen readers then read the stack as one button.
      */
     onPress?: () => void;
     /** The space between children. */

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

@@ -1,15 +1,15 @@
-import type { ResponsiveSx } from '@hzblj/kara-sx';
+import type { AccessibilityProps, 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 & {
+/** Layers its children on one another: SwiftUI `ZStack` / Compose `Box`. */
+export type ZStackProps = ResponsiveSx & AccessibilityProps & {
     /** 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.
+     * fills the stack's shape. Screen readers then read the stack as one button.
      */
     onPress?: () => void;
     /** Test identifier, forwarded to the native view. */

package/lib/typescript/glyph/glyph-button.types.d.ts

@@ -1,6 +1,6 @@
 import type { GlyphName } from '@hzblj/kara-native';
 import type { ReactNode } from 'react';
-/** An icon button over one of kara's glyphs — for the controls its own components build (a stepper, a bar). */
+/** An icon button over one of kara's glyphs, for the controls its own components build (a stepper, a bar). */
 export type GlyphButtonProps = {
     accessibilityLabel?: string;
     disabled?: boolean;

package/lib/typescript/glyph/glyph.types.d.ts

@@ -2,10 +2,12 @@ import type { GlyphName } from '@hzblj/kara-native';
 import type { ColorToken, SpaceSize } from '@hzblj/kara-theme';
 import type { ReactNode } from 'react';
 /**
- * One of the few glyphs kara's own components draw — a search field's magnifier, a row's chevron. Internal: apps draw
+ * One of the few glyphs kara's own components draw: a search field's magnifier, a row's chevron. Internal: apps draw
  * their own icons with `Icon` / `RnIcon`.
  */
 export type GlyphProps = {
+    /** What a screen reader says. Unset, the glyph is decorative and hidden from it. */
+    accessibilityLabel?: string;
     color?: ColorToken;
     name: GlyphName;
     size?: SpaceSize;

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

@@ -1,7 +1,7 @@
 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>`.
+ * chevron over an animated reveal. A native atom: it renders inside `<Screen>` or `<Island>`.
  */
 export type CollapsibleProps = {
     /** Shown while `expanded`. */

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

@@ -5,7 +5,7 @@ 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. */
+    /** Under the text: a `Button`, say. */
     action?: ReactNode;
     /** A second line under the title, in the secondary colour. */
     description?: string;

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

@@ -2,7 +2,7 @@ import type { ColorToken, SpaceSize, TextVariant } from '@hzblj/kara-theme';
 import type { ReactNode } from 'react';
 import type { IconName } from '../../atoms/icon';
 /**
- * An inline icon + text pair — the thing you put inside a button, a menu row or a section
+ * An inline icon + text pair: the thing you put inside a button, a menu row or a section
  * header. For a full tappable row with a subtitle and chevron, use `ListItem`.
  */
 export type LabelProps = {

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

@@ -1,11 +1,13 @@
+import type { AccessibilityProps } from '@hzblj/kara-sx';
 import type { SpaceSize } from '@hzblj/kara-theme';
 import type { ReactNode } from 'react';
 import type { IconName } from '../../atoms/icon';
 /**
- * A label on the leading edge and its value on the trailing edge — the settings/detail row.
- * Pass `children` instead of `value` when the trailing side is a control rather than text.
+ * A label on the leading edge and its value on the trailing edge: the settings/detail row.
+ * Pass `children` instead of `value` when the trailing side is a control rather than text. With a `value`, screen
+ * readers read the row as one element ("Version, 2.4"); with a control, the control stays its own.
  */
-export type LabeledContentProps = {
+export type LabeledContentProps = AccessibilityProps & {
     /** 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. */
@@ -14,7 +16,7 @@ export type LabeledContentProps = {
     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. */
+    /** Horizontal padding inside the row, and 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;

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

@@ -1,8 +1,9 @@
+import type { AccessibilityProps } from '@hzblj/kara-sx';
 import type { ColorToken, TextVariant } from '@hzblj/kara-theme';
 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 = {
+export type LinkProps = AccessibilityProps & {
     /** Colours the label and the icon. `content.accent` by default. */
     color?: ColorToken;
     /** One of the app's icons, before the label. */

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

@@ -1,17 +1,19 @@
+import type { AccessibilityProps } from '@hzblj/kara-sx';
 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.
+ * A row with an optional icon, a title and subtitle, and a chevron when it can be pressed. Screen readers read it as one
+ * element (a button when it is pressable). A native atom: it renders inside `<Screen>` or `<Island>`; `RnListItem` is
+ * the same row without a host.
  */
-export type ListItemProps = {
+export type ListItemProps = AccessibilityProps & {
     /** 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
+     * Horizontal padding inside the row, and 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;

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

@@ -12,8 +12,8 @@ type NavigationBarItemBase = {
     testID?: string;
 };
 /**
- * One item of the bar. `back` and `close` are the platform's own — a chevron and the system close item on iOS, the
- * Material arrow and cross on Android — with `Back` / `Close` as their labels unless given others. `icon` is one of the
+ * One item of the bar. `back` and `close` are the platform's own (a chevron and the system close item on iOS, the
+ * Material arrow and cross on Android), with `Back` / `Close` as their labels unless given others. `icon` is one of the
  * app's icons and names itself for VoiceOver and TalkBack.
  */
 export type NavigationBarItem = (NavigationBarItemBase & {
@@ -28,7 +28,7 @@ export type NavigationBarSearchRef = {
     /** Empties the field and ends editing. */
     clear: () => void;
 };
-/** A search field in place of the title — iOS only for now; Android keeps the title. */
+/** 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;
@@ -43,10 +43,10 @@ export type NavigationBarSearch = {
 };
 export type NavigationBarTitleAlignment = 'center' | 'leading';
 /**
- * A title with items on either side, for a header that is not a navigation screen's — `Sheet.Header` is built on it.
+ * A title with items on either side, for a header that is not a navigation screen's. `Sheet.Header` is built on it.
  * On iOS a standalone `UINavigationBar`, so the items press and render exactly like a native-stack header's: on iOS 26
  * neighbours share a glass capsule instead of swelling as standalone glass buttons do. On Android Material's top app
- * bar. Where an item goes is the caller's choice — the bar places nothing by itself, so a close can sit on either side.
+ * bar. Where an item goes is the caller's choice: the bar places nothing by itself, so a close can sit on either side.
  * The React Native tier: it needs no host.
  */
 export type NavigationBarProps = {
@@ -56,13 +56,13 @@ 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. */
+    /** 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. */
+    /** `center` (iOS's own) by default; `leading` is Material's top app bar. */
     titleAlignment?: NavigationBarTitleAlignment;
-    /** Fades the title out and in without moving the items — for a large title that scrolls under the bar. */
+    /** Fades the title out and in without moving the items, for a large title that scrolls under the bar. */
     titleVisible?: boolean;
     /** In screen order, toward the trailing edge. */
     trailingItems?: NavigationBarItem[];

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

@@ -4,7 +4,7 @@ import type { ReactNode } from 'react';
  * A swipeable, snapping pager: SwiftUI's `TabView` in its page style, Compose's `HorizontalPager`.
  *
  * Pages are addressed by their index rather than by a name, because Compose's pager is index-native
- * and SwiftUI's tab values are strings — synthesising the string from the child's position is
+ * and SwiftUI's tab values are strings; synthesising the string from the child's position is
  * lossless, whereas inventing indices for named tabs on Compose would not be. Children are therefore
  * plain nodes with no `Pager.Page` part to wrap them in: a page carries no props of its own, so the
  * ceremony would buy nothing.
@@ -21,7 +21,7 @@ export type PagerProps = {
     onPageChange?: (page: number) => void;
     /** Zero-based. Controlled when passed; otherwise the pager just starts at 0 and owns its position. */
     page?: number;
-    /** Android only — a SwiftUI page-style `TabView` has no gap between pages. */
+    /** Android only: a SwiftUI page-style `TabView` has no gap between pages. */
     pageSpacing?: SpaceSize;
     /**
      * Android only. SwiftUI can only disable a `TabView` as a whole, which would take the pages'

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

@@ -3,12 +3,12 @@ import type { ReactNode } from 'react';
 export type RadioOption = {
     /** The option's text. */
     label: string;
-    /** Identifies the option to `value` and `onValueChange`, and keys its row — keep it unique. */
+    /** 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>`.
+ * native atom: it renders inside `<Screen>` or `<Island>`.
  */
 export type RadioGroupProps = {
     /** The user pressed an option; it passes that option's `value`. */

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

@@ -1,7 +1,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
+ * `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, 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

@@ -4,15 +4,15 @@ export type RnTooltipActionVariant = 'link' | 'primary' | 'secondary';
 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. */
+    /** 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. */
+    /** `link` by default, an underlined text. `primary`/`secondary` are small filled/outlined buttons. */
     variant?: RnTooltipActionVariant;
 };
 /** `outside`: a touch outside the bubble. `anchorHidden`: the anchor's centre left the visible area. */
 export type RnTooltipDismissReason = 'anchorHidden' | 'outside';
 /**
- * A rich tooltip — title, message, actions — anchored below a React Native view, and drawn above every sibling.
+ * A rich tooltip (title, message, actions) anchored below a React Native view, and drawn above every sibling.
  * Controlled: it never hides itself. `onDismiss` reports why it should, and the caller turns `visible` off. The React
  * Native tier, unlike `Tooltip`, whose anchor is a native view inside a host.
  */
@@ -22,19 +22,19 @@ export type RnTooltipProps = {
     /** Which end of the bubble the actions sit at. `end` by default. */
     actionsAlignment?: 'end' | 'start';
     /**
-     * Insets from the window's top and bottom that the anchor's centre must stay inside — a header or a tab bar over the
-     * content. Past them the tooltip asks to be dismissed with `anchorHidden`.
+     * Insets from the window's top and bottom that the anchor's centre must stay inside (a header or a tab bar over the
+     * content). Past them the tooltip asks to be dismissed with `anchorHidden`.
      */
     boundaryInsets?: {
         bottom?: number;
         top?: number;
     };
-    /** The anchor — a single React Native view. */
+    /** 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
+     * 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;

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

@@ -3,13 +3,13 @@ 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 each platform's scroll edge under them — on iOS 26 the system's
+ * 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.
+ * it draws only its bottom bar; the hosted scroll view and the top bar stay blank.
  */
 export type ScrollEdgeContainerProps = ResponsiveViewSx & {
     /**
@@ -19,7 +19,7 @@ export type ScrollEdgeContainerProps = ResponsiveViewSx & {
     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`. */
+    /** Exactly one React Native scroll view: `RnScrollView`, `RnFlatList`, `RnSectionList`. */
     children: ReactElement<ScrollEdgeScrollableProps>;
     /** iOS 26: how hard the edge cuts. `soft` by default. */
     effect?: ScrollEdgeEffect;

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

@@ -1,6 +1,6 @@
 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
+ * 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 = {
@@ -10,7 +10,7 @@ export type SearchBarProps = {
     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. */
+    /** 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

@@ -2,6 +2,6 @@ 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.
+ * monospaced digits so the row does not jump. With motion reduced it cross-fades instead.
  */
 export declare const Stepper: StepperComponent;

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

@@ -1,10 +1,10 @@
 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>`.
+ * 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. */
+    /** 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;

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

@@ -1,19 +1,19 @@
 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`
+ * 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. */
+    /** 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. */
+    /** 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.
+     * The user dismissed the tip, so 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;
 };

package/lib/typescript/motion.d.ts

@@ -0,0 +1,8 @@
+import { type DurationSize, type EasingName } from '@hzblj/kara-theme';
+import { type WithTimingConfig } from 'react-native-reanimated';
+/**
+ * A Reanimated timing from the motion tokens, `smoothOut` unless told otherwise. `ReduceMotion.Never`, because a
+ * component has applied `useReducedMotion` before it animates: what is left (a fade, a dim) is meant to run, and
+ * Reanimated's own check reads the setting once at launch and never hears of `KaraProvider reduceMotion`.
+ */
+export declare const timing: (size: DurationSize, curve?: EasingName) => WithTimingConfig;