@hzblj/kara-components 0.16.0 → 0.18.0

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

@@ -4,6 +4,8 @@ export type BadgeTone = 'accent' | 'destructive' | 'neutral' | 'success';
 export type BadgeProps = {
     /** The text inside. */
     label: string;
+    /** Test identifier, forwarded to the native view. */
+    testID?: string;
     /** The fill and text colours. `neutral` by default. */
     tone?: BadgeTone;
 };

package/lib/typescript/atoms/button/button-tokens.d.ts

@@ -12,14 +12,18 @@ export declare const buttonTokens: (variant: ButtonVariant, disabled: boolean, t
     readonly content: 'content.primary';
     readonly fill: 'btn.bg.glass.base';
     readonly shadow: 'btn.glass';
+} | {
+    readonly content: 'content.accent';
+    readonly fill: undefined;
+    readonly shadow: undefined;
 } | {
     readonly content: 'content.primary';
     readonly fill: 'btn.bg.secondary.base';
     readonly shadow: 'btn.secondary';
 } | {
     readonly content: 'btn.content.disabled';
-    readonly fill: "btn.bg.glass.disabled" | "btn.bg.secondary.disabled" | "fill.accent.disabled" | "fill.destructive.disabled";
-    readonly shadow: "btn.accent" | "btn.destructive" | "btn.glass" | "btn.secondary";
+    readonly fill: "btn.bg.glass.disabled" | "btn.bg.secondary.disabled" | "fill.accent.disabled" | "fill.destructive.disabled" | undefined;
+    readonly shadow: "btn.accent" | "btn.destructive" | "btn.glass" | "btn.secondary" | undefined;
 };
 /**
  * The label for a button filled with an arbitrary `tint`: the on-accent white over a strong colour, the primary

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

@@ -1,6 +1,7 @@
 import type { ColorToken } from '@hzblj/kara-theme';
 import type { ReactNode } from 'react';
-export type ButtonVariant = 'accent' | 'destructive' | 'glass' | 'secondary';
+import type { IconName } from '../icon';
+export type ButtonVariant = 'accent' | 'destructive' | 'glass' | 'plain' | 'secondary';
 /**
  * SwiftUI `ButtonStyle`. iOS only: Compose has no equivalent, so Android ignores it and keeps
  * rendering the variant's tokens.
@@ -11,19 +12,28 @@ 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. */
+/**
+ * A text button: SwiftUI `Button` on iOS, Material's filled button on Android (outlined for `glass`, a `TextButton`
+ * for `plain`).
+ */
 export type ButtonProps = {
     /** What pressing it does, when the label alone does not say. See `AccessibilityProps`. */
     accessibilityHint?: string;
     /**
      * Replaces the style the variant picks: `borderedProminent` for `accent` and `destructive`, `bordered` for
-     * `secondary`, `glass` for `glass`. iOS only. Android ignores it.
+     * `secondary`, `glass` for `glass`, `borderless` for `plain`. 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;
+    /**
+     * One of the app's icons, before the label and in the label's colour. iOS sets the two as a SwiftUI `Label`; Android
+     * puts the icon in the button's content row, as Material's buttons with an icon do. Screen readers read the label
+     * only.
+     */
+    icon?: IconName;
     /** The button's text. */
     label: string;
     /** Called when the button is pressed. */
@@ -33,10 +43,14 @@ export type ButtonProps = {
     /**
      * Overrides the variant's own tint. A prominent style takes it as the fill and picks a contrasting
      * label. `glass` has to reach the material through `glassEffect` instead, so tinting one costs it
-     * the stock `.glass` style (see the iOS implementation).
+     * the stock `.glass` style (see the iOS implementation). `plain` has no fill, so there it colours the label.
      */
     tint?: ColorToken;
-    /** The look. `accent` by default. Material has no glass, so on Android `glass` is an outlined button. */
+    /**
+     * The look. `accent` by default. Material has no glass, so on Android `glass` is an outlined button. `plain` is a
+     * text button in the accent, with no fill or border, for a lesser action beside a prominent one ("Skip", "Forgot
+     * password?"): SwiftUI's `borderless` style, Material's `TextButton`.
+     */
     variant?: ButtonVariant;
     /** Stretches the button to the full width it is offered. On by default. */
     wide?: boolean;

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

@@ -7,6 +7,8 @@ export type CheckboxProps = {
     label?: string;
     /** Called with the new value when the user toggles it. */
     onValueChange?: (value: boolean) => void;
+    /** Test identifier, forwarded to the native control (on Android the box itself, not the labelled row). */
+    testID?: string;
     /** Whether it is checked. Controlled: update it from `onValueChange`. */
     value: boolean;
 };

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

@@ -5,6 +5,8 @@ import type { ReactNode } from 'react';
  * spectrum and RGB sliders.
  */
 export type ColorPickerProps = {
+    /** Stops the user picking a colour, and dims the label and the well. */
+    disabled?: boolean;
     /** Text beside the colour well, and the Android sheet's title. */
     label?: string;
     /** Called with the colour the user picks. */

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

@@ -1,9 +1,9 @@
 import type { DatePickerComponent } from './date-picker.types';
 /**
- * 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. Inside a `Screen` or `Island` it renders into that host instead (see
- * `useInsideHost`).
+ * The system's date picker, in the accent. `compact` by default: the value in a pill, and a tap on it opens the
+ * calendar popover UIKit owns. `graphical` is that calendar in place, `wheel` the value on wheels. Its own host, sized
+ * to the picker 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.
+ * Inside a `Screen` or `Island` it renders into that host instead (see `useInsideHost`).
  */
 export declare const DatePicker: DatePickerComponent;

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

@@ -1,23 +1,46 @@
 import type { ReactNode } from 'react';
 export type DatePickerMode = 'date' | 'datetime' | 'time';
+/** How SwiftUI shows the picker: a pill that opens the calendar, the calendar in place, or wheels. */
+export type DatePickerStyleName = 'compact' | 'graphical' | 'wheel';
 /**
- * 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`. Inside a `Screen` or `Island` it joins that host instead, beside a native `Text` label.
+ * A date or time picker: SwiftUI's `DatePicker` on iOS (a pill by default, a calendar or wheels with
+ * `datePickerStyle`), a field that opens Material's picker dialog on a tap on Android, or Material's calendar in place
+ * with `datePickerStyle="graphical"`. 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`. Inside a `Screen` or `Island` it joins that host instead, beside a
+ * native `Text` label.
  */
 export type DatePickerProps = {
+    /**
+     * SwiftUI's date picker style. `compact` by default: the value in a pill, which opens the calendar in a popover.
+     * `graphical` is the calendar in place, a month at a time, with the time under it in `datetime` mode: what a screen
+     * built around picking a day wants. `wheel` puts the value on wheels. Android shows Material's calendar in place for
+     * `graphical` in `date` and `datetime` modes (without its title and headline); otherwise it keeps its field and
+     * dialog, since Material has no wheel.
+     */
+    datePickerStyle?: DatePickerStyleName;
+    /**
+     * Stops the user changing the date, and dims the picker. Material's calendar has no disabled state of its own, so a
+     * `graphical` picker on Android is dimmed and offers only the selected day.
+     */
+    disabled?: boolean;
     /** 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.
+     * What it picks. `date` by default. Android has no combined dialog or calendar, 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. */
+    /**
+     * Called with the new date: on iOS as it changes, on Android when the dialog is confirmed or a day in the calendar
+     * is tapped.
+     */
     onValueChange?: (date: Date) => void;
-    /** Test identifier, on the native picker on iOS and on the tappable field on Android. */
+    /**
+     * Test identifier, on the native picker on iOS and on Android's calendar, and on the tappable field elsewhere on
+     * Android.
+     */
     testID?: string;
     /** The selected date. Controlled: update it from `onValueChange`. */
     value: Date;

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

@@ -1,2 +1,6 @@
 import type { DividerComponent } from './divider.types';
+/**
+ * SwiftUI's divider, which turns with its stack: vertical in an `HStack`, horizontal anywhere else. So `axis`, which
+ * Android needs to pick its divider, has nothing to do here.
+ */
 export declare const Divider: DividerComponent;

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

@@ -1,10 +1,21 @@
 import type { ColorToken } from '@hzblj/kara-theme';
 import type { ReactNode } from 'react';
-/** A horizontal hairline: SwiftUI `Divider` / Compose `HorizontalDivider`. */
+/** Which way the line runs. */
+export type DividerAxis = 'horizontal' | 'vertical';
+/**
+ * A hairline between views: SwiftUI `Divider` / Compose `HorizontalDivider`, or `VerticalDivider` with
+ * `axis="vertical"`.
+ */
 export type DividerProps = {
+    /**
+     * Which way the line runs. `horizontal` by default: across a `VStack`. `vertical` stands it up between the children
+     * of an `HStack`, as tall as the stack, so give the stack a height (`h`). iOS ignores it: SwiftUI's divider turns by
+     * itself, vertical in an `HStack` and horizontal anywhere else. Set it anyway, so Android draws the same.
+     */
+    axis?: DividerAxis;
     /** The line's colour. `border.tertiary` by default. */
     color?: ColorToken;
-    /** Test identifier, forwarded to the native view on iOS. Android ignores it. */
+    /** Test identifier, forwarded to the native view. */
     testID?: string;
 };
 export type DividerComponent = (props: DividerProps) => ReactNode;

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

@@ -1,22 +1,39 @@
 import type { ReactNode } from 'react';
 import type { IconName } from '../icon';
+/** Material's three floating action buttons: 40, 56 and 96 across. */
+export type FabSize = 'large' | 'regular' | 'small';
 /**
- * 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.
+ * A floating action button: Material's `FloatingActionButton` on Android, an accent circle (a plain SwiftUI `Button`)
+ * on iOS. With a `label` it is the extended one, the icon and the text side by side: Material's
+ * `ExtendedFloatingActionButton`, an accent capsule on iOS. It renders inline; pinning it to a corner is up to the
+ * screen.
  */
 export type FabProps = {
     /**
      * What VoiceOver and TalkBack say for the button, since an icon has no words of its own: "Share", "Add to
-     * favourites". Required for that reason.
+     * favourites". Required for that reason. With a `label` it is still what they say, in place of the label, so give
+     * it the label's words (or words that start with them), and Voice Control finds the button by what it shows.
      */
     accessibilityLabel: string;
     /** What pressing it does, when the label alone does not say. See `AccessibilityProps`. */
     accessibilityHint?: string;
+    /**
+     * Text beside the icon, which makes it an extended FAB: "Compose", "New post". For a screen whose main action needs
+     * its words. Material's `ExtendedFloatingActionButton` on Android; on iOS the same accent, 56pt tall, as a capsule.
+     */
+    label?: string;
     /** The icon, one of the app's, drawn in `content.on.accent`. */
     name: IconName;
     /** Called when the button is pressed. */
     onPress?: () => void;
-    /** Test identifier, forwarded to the native view on iOS. Android ignores it. */
+    /**
+     * `regular` by default, 56 across. `small` is 40, for a secondary action beside a regular one; `large` is 96, with a
+     * 36 icon, for a screen built around one action. Material's `SmallFloatingActionButton` and
+     * `LargeFloatingActionButton` on Android, the same sizes of circle on iOS. A FAB with a `label` has one size and
+     * ignores it.
+     */
+    size?: FabSize;
+    /** Test identifier, forwarded to the native view. */
     testID?: string;
 };
 export type FabComponent = (props: FabProps) => ReactNode;

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

@@ -1,9 +1,15 @@
+import type { ColorToken } from '@hzblj/kara-theme';
 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. The icon sits
- * centred in a tap target the size each platform asks for, 44pt on iOS and 48dp on Android, so a row of them spaces
- * itself the same way on both.
+ * How much the button stands out: just the icon (`plain`), on a fill in the accent (`filled`), on a muted fill
+ * (`tonal`), in a ring (`outlined`) or on Liquid Glass (`glass`).
+ */
+export type IconButtonVariant = 'filled' | 'glass' | 'outlined' | 'plain' | 'tonal';
+/**
+ * A button that is just an icon: a SwiftUI `Button` on iOS, one of Material's icon buttons on Android. A `plain` one
+ * sits centred in a tap target the size each platform asks for, 44pt on iOS and 48dp on Android, so a row of them
+ * spaces itself the same way on both; the other variants draw a circle around the icon.
  */
 export type IconButtonProps = {
     /**
@@ -13,13 +19,26 @@ export type IconButtonProps = {
     accessibilityLabel: string;
     /** What pressing it does, when the label alone does not say. See `AccessibilityProps`. */
     accessibilityHint?: string;
+    /**
+     * The icon's colour, `content.primary` by default. On `filled` it is the fill instead (`fill.accent.primary` by
+     * default) and the icon picks a colour that reads on it, as a `Button`'s `tint` does on a prominent style. On iOS a
+     * `tonal` button's circle takes a pale shade of it too.
+     */
+    color?: ColorToken;
     /** Dims the icon (iOS's own disabled look, `btn.content.disabled` on Android) and stops the button responding. */
     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. */
+    /** Test identifier, forwarded to the native view. */
     testID?: string;
+    /**
+     * The look. `plain` by default. iOS draws the others as SwiftUI button styles in a circle: `borderedProminent` for
+     * `filled`, `bordered` for `tonal`, `glass` for `glass` (`bordered` below iOS 26), and `outlined` as a plain button
+     * in a hairline ring. Android draws Material's `IconButton`, `FilledIconButton`, `FilledTonalIconButton` and
+     * `OutlinedIconButton`; Material has no glass, so there `glass` is the tonal one.
+     */
+    variant?: IconButtonVariant;
 };
 export type IconButtonComponent = (props: IconButtonProps) => ReactNode;

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

@@ -1,4 +1,6 @@
 import type { ReactNode } from 'react';
+/** How the rows are laid out: in a rounded card inset from the edges, or edge to edge. */
+export type ListVariant = 'insetGrouped' | 'plain';
 /**
  * A scrolling list: SwiftUI `List`, Compose `LazyColumn`. It has no height of its own, so it needs one from outside:
  * a `Screen`, or an `Island` with `matchContents={false}` and a height. In an island that sizes itself to its content
@@ -16,7 +18,19 @@ export type ListProps = {
      * 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. */
+    /**
+     * Draws a line between rows. On by default. Off, iOS hides SwiftUI's row separators and Android draws no `Divider`,
+     * for rows that carry their own spacing (cards, media).
+     */
+    separators?: boolean;
+    /** Test identifier, forwarded to the native view. */
     testID?: string;
+    /**
+     * The layout. Each platform's own list by default: `insetGrouped` on iOS, `plain` on Android. `insetGrouped` sets
+     * the rows in a rounded card inset from the edges (SwiftUI's `insetGrouped` list style; on Android a `Card` inside the
+     * column, the way `Form` draws its sections). `plain` runs the rows edge to edge (SwiftUI's `plain` style; Android's
+     * column as it is).
+     */
+    variant?: ListVariant;
 };
 export type ListComponent = (props: ListProps) => ReactNode;

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

@@ -1,7 +1,9 @@
 import type { PickerComponent } from './picker.types';
 /**
- * A SwiftUI wheel. On its own it is `@expo/ui`'s community picker, which brings a host of its own. Inside a `Screen` or
- * `Island` it is the same wheel rendered into that host instead (see `useInsideHost`): a host nested in the island's
- * stack is given no height there, and the wheel spills over the views around it.
+ * A SwiftUI picker: a wheel, or with `pickerStyle="menu"` a button with the selection that opens the options as a
+ * menu, in the accent. On its own the wheel is `@expo/ui`'s community picker, which brings a host of its own, and the
+ * menu sits in a host sized to its button on both axes, as the date picker's pill does, so it drops into a row the way
+ * a `Text` does. Inside a `Screen` or `Island` either renders into that host instead (see `useInsideHost`): a host
+ * nested in the island's stack is given no height there, and the wheel spills over the views around it.
  */
 export declare const Picker: PickerComponent;

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

@@ -6,10 +6,12 @@ export type PickerOption = {
     /** What `onValueChange` reports. It also keys the option, so it must be unique. */
     value: string;
 };
+/** How SwiftUI shows the picker: a wheel, or a button that opens the options as a menu. */
+export type PickerStyleName = 'menu' | 'wheel';
 /**
- * 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. Inside one it renders into that host instead, so it
- * can share a stack with other native views.
+ * A single choice from a list: a SwiftUI picker on iOS (a wheel, or a menu with `pickerStyle`), Material's exposed
+ * dropdown on Android. It brings its own host, so it renders outside `Screen` and `Island` as well. Inside one it
+ * renders into that host instead, so it can share a stack with other native views.
  */
 export type PickerProps = {
     /** Stops the user changing the selection, and dims the picker. */
@@ -18,6 +20,12 @@ export type PickerProps = {
     onValueChange?: (value: string) => void;
     /** The choices, in order. */
     options: PickerOption[];
+    /**
+     * SwiftUI's picker style. `wheel` by default: the options on a wheel, always in view. `menu` is a button with the
+     * selection, in the accent, that opens the options as a menu: what a screen with more than one picker, or a picker
+     * in a row, wants. iOS only. Android ignores it: its exposed dropdown is a menu already.
+     */
+    pickerStyle?: PickerStyleName;
     /**
      * Android: the dropdown field's test tag. iOS: the wheel's, inside a `Screen` or `Island` only; on its own,
      * `@expo/ui`'s wheel picker drops it.

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

@@ -1,13 +1,24 @@
+import type { ColorToken } from '@hzblj/kara-theme';
 import type { ReactNode } from 'react';
 /**
- * A progress bar or ring, tinted `fill.accent.primary`: SwiftUI `ProgressView` (a capacity `Gauge` for a ring with a
- * value, which `ProgressView` cannot draw on iOS) / Compose's `LinearProgressIndicator` and `CircularProgressIndicator`.
+ * A progress bar or ring, tinted `fill.accent.primary` unless `color` names another: SwiftUI `ProgressView` (a capacity
+ * `Gauge` for a ring with a value, which `ProgressView` cannot draw on iOS) / Compose's `LinearProgressIndicator` and
+ * `CircularProgressIndicator`.
  */
 export type ProgressProps = {
     /** What is in progress, for VoiceOver and TalkBack: "Uploading". They read how far along it is themselves. */
     accessibilityLabel?: string;
     /** A circular indicator instead of a bar. Off by default. */
     circular?: boolean;
+    /**
+     * Its colour: `fill.destructive.primary` for storage nearly full, `fill.success.primary` for a goal reached.
+     * `fill.accent.primary` by default. iOS tints the bar or ring with it. Android draws the indicator in it and, for any
+     * colour but the accent, the track in the same colour faded (Material's own track stays under the accent, and an
+     * indeterminate ring has none).
+     */
+    color?: ColorToken;
+    /** Test identifier, forwarded to the native view. */
+    testID?: string;
     /** Between `0` and `1`. Leave it unset for an indeterminate indicator. */
     value?: number;
 };

package/lib/typescript/atoms/slider/slider.ios.d.ts

@@ -1,2 +1,6 @@
 import type { SliderComponent } from './slider.types';
+/**
+ * SwiftUI's slider. `onValueChangeEnd` is its `onEditingChanged(false)`, with the last value the drag reported: the
+ * controlled `value` can still be a render behind when the finger lifts.
+ */
 export declare const Slider: SliderComponent;

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

@@ -9,8 +9,15 @@ export type SliderProps = {
     min?: number;
     /** Called with the new value as the thumb moves. */
     onValueChange?: (value: number) => void;
+    /**
+     * Called once with the final value when the user lets go of the slider: where a seek or a volume commits, rather
+     * than at every step of the drag.
+     */
+    onValueChangeEnd?: (value: number) => void;
     /** The increment between stops; leave it unset for a continuous slider. On Android every stop plays a `tick`. */
     step?: number;
+    /** Test identifier, forwarded to the native view. */
+    testID?: string;
     /** Between `min` and `max`. Controlled: pass back what `onValueChange` reports. */
     value: number;
 };

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

@@ -10,6 +10,8 @@ export type SwitchProps = {
     label?: string;
     /** Called with the new value when the user flips it. On Android a flip plays `toggleOn` / `toggleOff`. */
     onValueChange?: (value: boolean) => void;
+    /** Test identifier, forwarded to the native switch (on Android the switch itself, not the labelled row). */
+    testID?: string;
     /** Whether it is on. Controlled: pass back what `onValueChange` reports. */
     value: boolean;
 };

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

@@ -5,6 +5,8 @@ export type TextSpan = {
     color?: ColorToken;
     text: string;
 };
+/** The string and number children, joined: the text of a `Text` without spans, however JSX split it. */
+export declare const textOf: (children: ReactNode) => string;
 /**
  * The children as runs when any of them is a nested `Text` (`type`, the platform's own component), `null` when they
  * are only text. A span keeps its `color`; anything else it sets is the outer text's.

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

@@ -4,6 +4,8 @@ import type { ReactNode } from 'react';
 export type TextAlign = 'center' | 'left' | 'right';
 export type TextDecoration = 'none' | 'strikethrough' | 'underline';
 export type TextTransform = 'lowercase' | 'uppercase';
+/** Where the ellipsis goes in a text cut short: its start, its middle or its end. */
+export type TextTruncation = 'head' | 'middle' | 'tail';
 /**
  * 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
@@ -29,7 +31,7 @@ export type TextProps = ResponsiveSx & AccessibilityProps & {
     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. */
+    /** The most lines it wraps to. A text cut short ends with an ellipsis, where `truncation` puts it. */
     numberOfLines?: number;
     /**
      * Sets it in the theme's fixed-width face, at the variant's size and weight: the app's `fonts.mono`, else Menlo on
@@ -46,6 +48,12 @@ export type TextProps = ResponsiveSx & AccessibilityProps & {
     testID?: string;
     /** Upper- or lower-cases the text. Android applies it only when `children` is a plain string. */
     transform?: TextTransform;
+    /**
+     * Where the ellipsis goes in a text cut short. `tail` by default: the end of the last line. `head` keeps the end of
+     * the text and `middle` both of its ends, for a file name, a path or an address. Android puts it at the head or in
+     * the middle of a single line only (`numberOfLines={1}`), as Compose does; a longer text there ends at the tail.
+     */
+    truncation?: TextTruncation;
     /** The typography variant. `body` by default. */
     variant?: TextVariant;
 };

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

@@ -0,0 +1,7 @@
+import type { TextFieldAutoCapitalize, TextFieldKeyboard } from './text-field.types';
+/** The capitalisation asked for, else `none` for an address; `undefined` leaves the platform's own. */
+export declare const capitalizationFor: (keyboard: TextFieldKeyboard, autoCapitalize: TextFieldAutoCapitalize | undefined) => TextFieldAutoCapitalize | undefined;
+/** Autocorrection as asked for, else on for everything but an address. */
+export declare const autoCorrectFor: (keyboard: TextFieldKeyboard, autoCorrect: boolean | undefined) => boolean;
+/** A no-op for a ref call that lands after the native view has gone. */
+export declare const ignoreDetachedView: () => undefined;

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

@@ -1,9 +1,50 @@
-import type { ReactNode } from 'react';
+import type { ReactNode, Ref } from 'react';
+/** The keyboard a field brings up. */
+export type TextFieldKeyboard = 'decimal' | 'default' | 'email' | 'number' | 'phone' | 'url';
+/** When the keyboard turns Shift on by itself. */
+export type TextFieldAutoCapitalize = 'characters' | 'none' | 'sentences' | 'words';
+/** What the return key says. */
+export type TextFieldSubmitLabel = 'done' | 'go' | 'next' | 'search' | 'send';
+/**
+ * What a field holds, so the system can offer to fill it in: an account's email or password, a new strong password,
+ * the code from a text message, the user's own name, phone number or address.
+ */
+export type TextFieldContentType = 'addressCity' | 'countryName' | 'creditCardNumber' | 'emailAddress' | 'familyName' | 'fullStreetAddress' | 'givenName' | 'name' | 'newPassword' | 'oneTimeCode' | 'password' | 'postalCode' | 'streetAddressLine1' | 'streetAddressLine2' | 'telephoneNumber' | 'username';
+/** Drives a `TextField` from code, as when `onSubmit` moves on to the next field. */
+export type TextFieldRef = {
+    /** Ends editing: the field gives up focus and the keyboard goes down. */
+    blur: () => void;
+    /** Empties the field and calls `onChangeText` with `''`. */
+    clear: () => void;
+    /** Starts editing: the field takes focus and brings up the keyboard. */
+    focus: () => void;
+};
 /**
  * An uncontrolled text field with an optional label above it: SwiftUI `TextField` (`SecureField` when `secure`) /
- * Compose `OutlinedTextField`.
+ * Compose `OutlinedTextField`. `keyboard`, `autoCapitalize`, `autoCorrect` and `contentType` fit it to the text it
+ * takes; `submitLabel`, `onSubmit` and `ref` chain fields so the return key moves on to the next.
  */
 export type TextFieldProps = {
+    /**
+     * When the keyboard turns Shift on by itself: never (`none`), at the start of `sentences`, of `words`, or for all
+     * `characters`. Unset, it is `none` for the `email` and `url` keyboards, and otherwise each platform's own:
+     * `sentences` on iOS, `none` on Android.
+     */
+    autoCapitalize?: TextFieldAutoCapitalize;
+    /**
+     * Lets the keyboard correct words as they are typed and suggest the next. On unless the keyboard is `email` or
+     * `url`, where a correction would only break an address. A `secure` field never corrects.
+     */
+    autoCorrect?: boolean;
+    /** Takes focus, and brings up the keyboard, as soon as the field appears. Off by default. */
+    autoFocus?: boolean;
+    /**
+     * What the field holds, so the system can offer to fill it in: a saved `username` or `password` from the keychain
+     * or a password manager, a strong `newPassword` for a sign-up, the `oneTimeCode` from a text message, the user's own
+     * `emailAddress`, `name`, `telephoneNumber` or address. iOS's `textContentType`; on Android a Compose autofill
+     * hint, which an autofill service (Google's, a password manager) answers.
+     */
+    contentType?: TextFieldContentType;
     /** 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`. */
@@ -14,15 +55,47 @@ export type TextFieldProps = {
      * colour is a pale red in dark mode. `true` marks it without a message.
      */
     error?: boolean | string;
+    /**
+     * The keyboard it brings up. `default` by default. `email` and `url` add their `@` and `.` keys and turn
+     * capitals and corrections off unless `autoCapitalize` or `autoCorrect` say otherwise; `number` is a pad of digits,
+     * `decimal` adds the locale's decimal separator, `phone` is a dial pad. With `secure`, Android brings up its password
+     * keyboard (a numeric one for `number`).
+     */
+    keyboard?: TextFieldKeyboard;
     /** Shown above the field, in `labelMedium`. */
     label?: string;
+    /**
+     * The most characters it takes. What is typed past it is cut off as the user types; `defaultValue` is not. No limit
+     * by default.
+     */
+    maxLength?: number;
     /** 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. */
+    /** Called with the whole text after every change, `clear()` included. */
     onChangeText?: (text: string) => void;
+    /** Called with `true` when the field starts editing and `false` when it stops. */
+    onFocusChange?: (focused: boolean) => void;
+    /**
+     * Called with the whole text when the return key is pressed. A `multiline` field never calls it: its return key
+     * starts a new line. Neither do iOS's `number`, `decimal` and `phone` pads, which have no return key.
+     */
+    onSubmit?: (text: string) => void;
+    /**
+     * Shown in the empty field, in the platform's placeholder colour, until the first character is typed. A hint at
+     * the format (`name@example.com`), not a replacement for `label`.
+     */
+    placeholder?: string;
+    /** `focus`, `blur` and `clear`, for moving to the next field from `onSubmit`. */
+    ref?: Ref<TextFieldRef>;
     /** Masks the text, for a password. */
     secure?: boolean;
-    /** iOS: forwarded to the native field. Android ignores it. */
+    /**
+     * What the return key says. Unset, each platform's own (`return` on iOS). It names the key; what pressing it does
+     * is up to `onSubmit`, so a `next` focuses the following field through its `ref`. Android's `next` also moves focus
+     * to the next field in the same host by itself. A `multiline` field ignores it: its return key starts a new line.
+     */
+    submitLabel?: TextFieldSubmitLabel;
+    /** Test identifier, forwarded to the native field (not the label above it). */
     testID?: string;
 };
 export type TextFieldComponent = (props: TextFieldProps) => ReactNode;

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

@@ -12,5 +12,7 @@ export type CollapsibleProps = {
     label: string;
     /** The user pressed the row; it passes the state the row asks for. */
     onExpandedChange: (expanded: boolean) => void;
+    /** Test identifier: on SwiftUI's `DisclosureGroup` on iOS, on the pressable row on Android. */
+    testID?: string;
 };
 export type CollapsibleComponent = (props: CollapsibleProps) => ReactNode;

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

@@ -11,10 +11,14 @@ export type RadioOption = {
  * native atom: it renders inside `<Screen>` or `<Island>`.
  */
 export type RadioGroupProps = {
+    /** Stops the user changing the selection, and dims the options. */
+    disabled?: boolean;
     /** The user pressed an option; it passes that option's `value`. */
     onValueChange?: (value: string) => void;
     /** The choices, top to bottom. */
     options: RadioOption[];
+    /** Test identifier, on the whole group. Reach an option by its label. */
+    testID?: string;
     /** The selected option's `value`. Update it from `onValueChange`. */
     value: string;
 };