@hzblj/kara-components 0.17.0 → 0.19.0

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;
 };

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

@@ -1,11 +1,21 @@
 import type { ReactNode } from 'react';
+import type { TextFieldAutoCapitalize } from '../../atoms/text-field';
 /**
  * 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.
+ * while there is text. The keyboard's return key reads Search, and a query is taken as typed: no capitals and no
+ * corrections unless asked for. The React Native tier: it needs no host.
  */
 export type SearchBarProps = {
+    /** When the keyboard turns Shift on by itself. `none` by default: a query is not a sentence. */
+    autoCapitalize?: TextFieldAutoCapitalize;
+    /** Lets the keyboard correct words as they are typed. Off by default, so a query is searched as typed. */
+    autoCorrect?: boolean;
+    /** Takes focus, and brings up the keyboard, as soon as the field appears. Off by default. */
+    autoFocus?: boolean;
     /** Every edit, and `''` when the clear button is pressed. */
     onChangeText?: (text: string) => void;
+    /** Called with the query when the keyboard's Search key is pressed. The keyboard goes down after it. */
+    onSubmit?: (text: string) => void;
     /** Shown while the field is empty. `Search` by default. */
     placeholder?: string;
     /** Test identifier, put on the field's container view rather than on the `TextInput`. */

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

@@ -2,6 +2,7 @@ import type { StepperComponent } from './stepper.types';
 /**
  * SwiftUI's `Stepper` at the end of a row, the label leading and the value just before the control — the way iOS's own
  * settings show a stepped value. The value rolls to the next one (`numericText`), up or down with the change, in
- * monospaced digits so the row does not jump. With motion reduced it cross-fades instead.
+ * monospaced digits so the row does not jump. With motion reduced it cross-fades instead. Its buttons are labelled by
+ * the system, so `decrementLabel` and `incrementLabel` are Android's alone.
  */
 export declare const Stepper: StepperComponent;

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

@@ -4,6 +4,18 @@ import type { ReactNode } from 'react';
  * two icon buttons in a row. A native atom: it renders inside `<Screen>` or `<Island>`.
  */
 export type StepperProps = {
+    /**
+     * What TalkBack says for the minus button. `Decrement` by default: pass the app's own words, in its language.
+     * Android only. iOS ignores it: its native stepper labels its buttons itself, in the device's language.
+     */
+    decrementLabel?: string;
+    /** Stops the user changing the value, and dims the row. */
+    disabled?: boolean;
+    /**
+     * What TalkBack says for the plus button. `Increment` by default: pass the app's own words, in its language. Android
+     * only. iOS ignores it: its native stepper labels its buttons itself, in the device's language.
+     */
+    incrementLabel?: string;
     /** 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`. */
@@ -14,6 +26,11 @@ export type StepperProps = {
     onValueChange: (value: number) => void;
     /** How much one press adds or takes away. `1` by default. */
     step?: number;
+    /**
+     * Test identifier, on the control rather than the row: SwiftUI's `Stepper` on iOS, the minus and plus buttons with
+     * the value between them on Android. Reach a button by what screen readers say for it.
+     */
+    testID?: string;
     /** The current value. Update it from `onValueChange`. iOS's native stepper counts in whole numbers. */
     value: number;
 };

package/lib/typescript/organisms/action-sheet/action-sheet.ios.d.ts

@@ -1,2 +1,6 @@
 import type { ActionSheetComponent } from './action-sheet.types';
+/**
+ * `titleVisibility="visible"`: left to `automatic`, SwiftUI drops the title of a dialog presented as an action sheet,
+ * and the actions lose what they are about.
+ */
 export declare const ActionSheet: ActionSheetComponent;

package/lib/typescript/organisms/action-sheet/action-sheet.types.d.ts

@@ -2,14 +2,19 @@ import type { ReactNode } from 'react';
 import type { MenuAction } from '../menu';
 /**
  * A list of actions to pick one from: SwiftUI's confirmation dialog on iOS, a `Sheet` of Material rows (icon and label)
- * under the title on Android. A native atom: it renders inside `<Screen>` or `<Island>`.
+ * under the title and message on Android. A native atom: it renders inside `<Screen>` or `<Island>`.
  */
 export type ActionSheetProps = {
-    /** The choices, top to bottom. Picking one closes the sheet. */
+    /** The choices, top to bottom. Picking one closes the sheet. A `disabled` one stays in the list, greyed. */
     actions: MenuAction[];
+    /**
+     * A line under the title saying what the choice is about: "The photo will be removed from all your devices." Unset,
+     * the title stands alone.
+     */
+    message?: string;
     /** The sheet closed (after a pick too), so turn `visible` off. */
     onDismiss: () => void;
-    /** The heading above the actions. Android always shows it; on iOS the system decides, and may hide it. */
+    /** The heading above the actions, shown on both platforms. */
     title: string;
     /** Presents the sheet while true. */
     visible: boolean;

package/lib/typescript/organisms/alert/alert.types.d.ts

@@ -1,9 +1,14 @@
 import type { ReactNode } from 'react';
 /**
- * A modal alert with a confirm button and Cancel: SwiftUI's alert on iOS, Material's `AlertDialog` on Android. A native
- * atom: it renders inside `<Screen>` or `<Island>`.
+ * A modal alert with a confirm button and a cancel button (or the confirm button alone): SwiftUI's alert on iOS,
+ * Material's `AlertDialog` on Android. A native atom: it renders inside `<Screen>` or `<Island>`.
  */
 export type AlertProps = {
+    /**
+     * The cancel button's label, in the app's language: "Zrušit". `Cancel` by default. `null` leaves the button out, for
+     * an alert that only informs and is closed by its confirm button alone ("OK").
+     */
+    cancelLabel?: string | null;
     /** The confirm button's label. `OK` by default. */
     confirmLabel?: string;
     /** Marks the confirm button destructive: the system's destructive role on iOS, the destructive colour on Android. */
@@ -12,7 +17,7 @@ export type AlertProps = {
     message?: string;
     /** The confirm button was pressed. `onDismiss` follows, as it does for every way the alert closes. */
     onConfirm?: () => void;
-    /** The alert closed (either button, or on Android a tap outside or back), so turn `visible` off. */
+    /** The alert closed (any of its buttons, or on Android a tap outside or back), so turn `visible` off. */
     onDismiss: () => void;
     /** The alert's heading. */
     title: string;

package/lib/typescript/organisms/menu/menu-parts.d.ts

@@ -0,0 +1,14 @@
+import type { ColorToken } from '@hzblj/kara-theme';
+import type { IconName } from '../../atoms/icon';
+import type { MenuAction, MenuProps } from './menu.types';
+/**
+ * An action's colour in a row kara draws itself (the Android menus and sheets): greyed when disabled, as `IconButton`
+ * greys, red when destructive. A Compose `DropdownMenuItem` cannot grey its own text here, since the text sets its
+ * colour explicitly.
+ */
+export declare const menuActionColor: ({ destructive, disabled }: MenuAction) => ColorToken;
+/** A trigger with no text: the props' union guarantees its icon and the words a screen reader says for it. */
+export declare const isIconOnly: (props: MenuProps) => props is MenuProps & {
+    accessibilityLabel: string;
+    icon: IconName;
+};

package/lib/typescript/organisms/menu/menu.types.d.ts

@@ -8,8 +8,13 @@ export type MenuAction = {
      */
     destructive?: boolean;
     /**
-     * One of the app's icons, before the label. `ContextMenu` and `FabMenu` show it on both platforms, `Menu` and
-     * `ActionSheet` on Android only.
+     * Greys the action out and stops it responding, for one that does not apply right now: "Paste" with nothing copied.
+     * Off by default. `FabMenu` ignores it on Android, where Material's FAB menu items have no disabled state.
+     */
+    disabled?: boolean;
+    /**
+     * One of the app's icons, before the label. `Menu`, `ContextMenu` and `FabMenu` show it on both platforms,
+     * `ActionSheet` on Android only: an iOS confirmation dialog draws text alone.
      */
     icon?: IconName;
     /** The action's text. Rows are keyed by it, so keep labels unique within one list. */
@@ -17,14 +22,37 @@ export type MenuAction = {
     /** Called when the action is chosen; the menu closes by itself. */
     onPress: () => void;
 };
+/** What the trigger needs: its text, or an icon and the words a screen reader says for it. */
+type MenuTrigger = {
+    label: string;
+} | {
+    accessibilityLabel: string;
+    icon: IconName;
+};
 /**
- * A text button that opens a list of actions: a SwiftUI `Menu` on iOS, a Material dropdown anchored to it on Android.
- * A native atom: it renders inside `<Screen>` or `<Island>`.
+ * A button that opens a list of actions: a SwiftUI `Menu` on iOS, a Material dropdown anchored to it on Android. The
+ * trigger is text, an icon and text, or an icon alone. A native atom: it renders inside `<Screen>` or `<Island>`.
  */
-export type MenuProps = {
+export type MenuProps = MenuTrigger & {
+    /**
+     * What VoiceOver and TalkBack say for the trigger: "More options". Required with an `icon` and no `label`, since an
+     * icon has no words of its own. With a label, it replaces the label for screen readers.
+     */
+    accessibilityLabel?: string;
     /** The menu's actions, top to bottom. */
     actions: MenuAction[];
-    /** The trigger's text. Android draws it in the accent colour, with a chevron. */
-    label: string;
+    /**
+     * One of the app's icons on the trigger. Before the `label`, in the same colour, when there is one; alone, the
+     * trigger is drawn as an `IconButton` (`content.primary`, in a 44pt target on iOS and 48dp on Android) and needs an
+     * `accessibilityLabel`.
+     */
+    icon?: IconName;
+    /**
+     * The trigger's text. Android draws it in the accent colour, with a chevron. Required unless there is an `icon`.
+     */
+    label?: string;
+    /** Test identifier, forwarded to the trigger. Reach an action by its label once the menu is open. */
+    testID?: string;
 };
 export type MenuComponent = (props: MenuProps) => ReactNode;
+export {};

package/lib/typescript/organisms/sheet/sheet.types.d.ts

@@ -46,7 +46,7 @@ export type SheetRef = {
  * one; native atoms in its content go in an `Island`.
  */
 export type SheetProps = {
-    /** The sheet's colour. `surface.primary` by default. */
+    /** The sheet's colour. `surface.primary` by default; ignored on iOS with `systemBackground`. */
     bg?: ColorToken;
     /** The content. A `<Sheet.Header>` among the direct children becomes the native header instead. */
     children: ReactNode;
@@ -75,6 +75,12 @@ export type SheetProps = {
      * and a header scrolls with the iOS 26 edge effect. Off by default; set it with a scrolling body.
      */
     scrollable?: boolean;
+    /**
+     * iOS: the system's own sheet background instead of `bg` — untinted Liquid Glass on iOS 26, a material blur before
+     * it — for a sheet that floats over content it should let through, like a map. Keep the content free of fills. Android
+     * keeps `bg`. Off by default.
+     */
+    systemBackground?: boolean;
     /** Test identifier, forwarded to the native sheet. */
     testID?: string;
     /** Presents the sheet while true; going false dismisses it. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hzblj/kara-components",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "The atoms, molecules, organisms and templates of @hzblj/kara-ui — real SwiftUI and Jetpack Compose views through @expo/ui.",
   "author": "Jan Blazej",
   "license": "MIT",
@@ -61,9 +61,9 @@
   "dependencies": {
     "@hzblj/expo-native-icons": "^0.1.0",
     "@hzblj/expo-rich-haptics": "^0.1.0",
-    "@hzblj/kara-native": "^0.17.0",
-    "@hzblj/kara-sx": "^0.17.0",
-    "@hzblj/kara-theme": "^0.17.0",
+    "@hzblj/kara-native": "^0.19.0",
+    "@hzblj/kara-sx": "^0.19.0",
+    "@hzblj/kara-theme": "^0.19.0",
     "sf-symbols-typescript": "^2.2.0"
   },
   "peerDependencies": {

package/src/atoms/badge/badge.android.tsx

@@ -1,17 +1,24 @@
 import {Badge as ComposeBadge, Text as ComposeText} from '@expo/ui/jetpack-compose'
+import {testID as testIdModifier} from '@expo/ui/jetpack-compose/modifiers'
 import {useAppTheme} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
 import {useHostGuard} from '../../host-context'
 import type {BadgeComponent, BadgeProps} from './badge.types'
 import {BADGE_TOKENS} from './badge-tokens'
 
 /** Material's badge. Its content is a Compose `Text` — `@expo/ui`'s badge takes composable content, not a string. */
-export const Badge: BadgeComponent = ({label, tone = 'neutral'}: BadgeProps) => {
+export const Badge: BadgeComponent = ({label, testID, tone = 'neutral'}: BadgeProps) => {
   useHostGuard('Badge')
   const theme = useAppTheme()
   const tokens = BADGE_TOKENS[tone]
+  const modifiers = useMemo(() => (testID ? [testIdModifier(testID)] : undefined), [testID])
 
   return (
-    <ComposeBadge containerColor={theme.color(tokens.fill)} contentColor={theme.color(tokens.content)}>
+    <ComposeBadge
+      containerColor={theme.color(tokens.fill)}
+      contentColor={theme.color(tokens.content)}
+      modifiers={modifiers}
+    >
       <ComposeText color={theme.colorString(tokens.content)} style={theme.typography.captionMedium}>
         {label}
       </ComposeText>

package/src/atoms/badge/badge.ios.tsx

@@ -5,13 +5,13 @@ import {Text} from '../text'
 import type {BadgeComponent, BadgeProps} from './badge.types'
 import {BADGE_TOKENS} from './badge-tokens'
 
-export const Badge: BadgeComponent = ({label, tone = 'neutral'}: BadgeProps) => {
+export const Badge: BadgeComponent = ({label, testID, tone = 'neutral'}: BadgeProps) => {
   useHostGuard('Badge')
   const tokens = BADGE_TOKENS[tone]
   const modifiers = useSxModifiers({bg: tokens.fill, borderRadius: 'full', px: 's8', py: 's2'})
 
   return (
-    <HStack modifiers={modifiers}>
+    <HStack modifiers={modifiers} testID={testID}>
       <Text color={tokens.content} variant="labelMedium">
         {label}
       </Text>

package/src/atoms/badge/badge.types.ts

@@ -6,6 +6,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/src/atoms/button/button-tokens.ts

@@ -2,16 +2,18 @@ import type {ColorToken, ShadowName, Theme} from '@hzblj/kara-theme'
 
 import type {ButtonVariant} from './button.types'
 
+/** `fill` and `shadow` are unset for `plain`: a text button has no container to fill or lift. */
 type ButtonTokens = {
   content: ColorToken
-  fill: ColorToken
-  shadow: ShadowName
+  fill: ColorToken | undefined
+  shadow: ShadowName | undefined
 }
 
 const TOKENS = {
   accent: {content: 'content.on.accent', fill: 'fill.accent.primary', shadow: 'btn.accent'},
   destructive: {content: 'content.on.destructive', fill: 'fill.destructive.primary', shadow: 'btn.destructive'},
   glass: {content: 'content.primary', fill: 'btn.bg.glass.base', shadow: 'btn.glass'},
+  plain: {content: 'content.accent', fill: undefined, shadow: undefined},
   secondary: {content: 'content.primary', fill: 'btn.bg.secondary.base', shadow: 'btn.secondary'},
 } as const satisfies Record<ButtonVariant, ButtonTokens>
 
@@ -26,8 +28,9 @@ export const buttonTokens = (variant: ButtonVariant, disabled: boolean, theme: T
     accent: 'fill.accent.disabled',
     destructive: 'fill.destructive.disabled',
     glass: 'btn.bg.glass.disabled',
+    plain: undefined,
     secondary: 'btn.bg.secondary.disabled',
-  } as const satisfies Record<ButtonVariant, ColorToken>
+  } as const satisfies Record<ButtonVariant, ColorToken | undefined>
 
   void theme
 

package/src/atoms/button/button.android.tsx

@@ -1,23 +1,43 @@
-import {Button as ComposeButton, Text as ComposeText, OutlinedButton} from '@expo/ui/jetpack-compose'
-import {testID as testIdModifier} from '@expo/ui/jetpack-compose/modifiers'
+import {
+  Button as ComposeButton,
+  Spacer as ComposeSpacer,
+  Text as ComposeText,
+  OutlinedButton,
+  TextButton,
+} from '@expo/ui/jetpack-compose'
+import {testID as testIdModifier, width as widthModifier} from '@expo/ui/jetpack-compose/modifiers'
 import {useAccessibilityModifiers, useSxModifiers} from '@hzblj/kara-sx'
-import {useAppTheme} from '@hzblj/kara-theme'
+import {spacing, useAppTheme} from '@hzblj/kara-theme'
 import {useMemo} from 'react'
 import {useHostGuard} from '../../host-context'
+import {Icon} from '../icon'
 import type {ButtonComponent, ButtonProps} from './button.types'
 import {buttonTokens, contentOnTint} from './button-tokens'
 
+/** Material's `ButtonDefaults.IconSpacing`: the gap between a button's icon and its label. */
+const ICON_GAP = [widthModifier(spacing.s8)]
+
+/**
+ * Material's padding for a button with a leading icon (`ButtonWithIconContentPadding`,
+ * `TextButtonWithIconContentPadding`): the icon side a step tighter than the label's. Top and bottom keep the defaults.
+ */
+const WITH_ICON_PADDING = {end: spacing.s24, start: spacing.s16}
+const TEXT_WITH_ICON_PADDING = {end: spacing.s16, start: spacing.s12}
+
 /**
  * Material's filled button, in its own stadium shape. No `borderRadius` or `shadow` from the tokens: those shape the
  * SwiftUI button's glossy ring, and laid over a Compose button they clip and outline a rounded rectangle around the
- * pill Material draws. The label is a Compose `Text` — `@expo/ui`'s button takes composable content, not a string.
+ * pill Material draws. The label is a Compose `Text` — `@expo/ui`'s button takes composable content, not a string —
+ * after the `icon`, when there is one, in the same row.
  *
- * Material has no glass, so `glass` is its outlined button — and a `tint` makes any variant a filled button in that
- * colour, as a prominent style does on iOS. `buttonStyle` and `controlSize` are SwiftUI's alone.
+ * Material has no glass, so `glass` is its outlined button — and a `tint` makes any variant but `plain` a filled
+ * button in that colour, as a prominent style does on iOS. `plain` is Material's `TextButton`, and a `tint` colours its
+ * label. `buttonStyle` and `controlSize` are SwiftUI's alone.
  */
 export const Button: ButtonComponent = ({
   accessibilityHint,
   disabled = false,
+  icon,
   label,
   onPress,
   testID,
@@ -35,27 +55,31 @@ export const Button: ButtonComponent = ({
     [accessibilityModifiers, sxModifiers, testID]
   )
   const style = theme.typography.body
+  const text = variant === 'plain'
   const outlined = variant === 'glass' && !tint
   const fill = tint && !disabled ? tint : tokens.fill
-  const content = tint && !disabled ? contentOnTint(tint, theme) : tokens.content
-  const MaterialButton = outlined ? OutlinedButton : ComposeButton
+  const content = !tint || disabled ? tokens.content : text ? tint : contentOnTint(tint, theme)
+  const MaterialButton = text ? TextButton : outlined ? OutlinedButton : ComposeButton
 
   return (
     <MaterialButton
       colors={
-        outlined
-          ? {contentColor: theme.color(content), disabledContentColor: theme.color(content)}
-          : {
+        fill && !text && !outlined
+          ? {
               containerColor: theme.color(fill),
               contentColor: theme.color(content),
               disabledContainerColor: theme.color(fill),
               disabledContentColor: theme.color(content),
             }
+          : {contentColor: theme.color(content), disabledContentColor: theme.color(content)}
       }
+      contentPadding={icon ? (text ? TEXT_WITH_ICON_PADDING : WITH_ICON_PADDING) : undefined}
       enabled={!disabled}
       modifiers={modifiers}
       onClick={onPress}
     >
+      {icon ? <Icon color={content} name={icon} size="s20" /> : null}
+      {icon ? <ComposeSpacer modifiers={ICON_GAP} /> : null}
       <ComposeText
         color={theme.colorString(content)}
         style={{