@hzblj/kara-components 0.16.0 → 0.18.0

package/src/atoms/text-field/text-field.ios.tsx

@@ -1,11 +1,27 @@
-import {SecureField, TextField as SwiftUITextField, useNativeState, VStack} from '@expo/ui/swift-ui'
-import {disabled as disabledModifier, textFieldStyle} from '@expo/ui/swift-ui/modifiers'
+import {
+  SecureField,
+  TextField as SwiftUITextField,
+  type TextFieldRef as SwiftUITextFieldRef,
+  useNativeState,
+  VStack,
+} from '@expo/ui/swift-ui'
+import {
+  autocorrectionDisabled,
+  disabled as disabledModifier,
+  keyboardType,
+  onSubmit as onSubmitModifier,
+  submitLabel as submitLabelModifier,
+  textContentType,
+  textFieldStyle,
+  textInputAutocapitalization,
+} from '@expo/ui/swift-ui/modifiers'
 import {useSxModifiers} from '@hzblj/kara-sx'
 import {type ColorToken, spacing} from '@hzblj/kara-theme'
-import {useMemo} from 'react'
+import {useImperativeHandle, useMemo, useRef} from 'react'
 import {useHostGuard} from '../../host-context'
 import {Text} from '../text'
-import type {TextFieldComponent, TextFieldProps} from './text-field.types'
+import type {TextFieldAutoCapitalize, TextFieldComponent, TextFieldKeyboard, TextFieldProps} from './text-field.types'
+import {autoCorrectFor, capitalizationFor, ignoreDetachedView} from './text-field-input'
 
 type FieldTone = 'default' | 'disabled' | 'error'
 
@@ -21,6 +37,23 @@ const TONE = {
   error: {bg: 'surface.primary', border: 'border.destructive', label: 'content.destructive'},
 } as const satisfies Record<FieldTone, FieldToneColors>
 
+/** UIKit's keyboards. `number` is the digits-only pad, which, like `decimal` and `phone`, has no return key. */
+const KEYBOARD = {
+  decimal: 'decimal-pad',
+  default: 'default',
+  email: 'email-address',
+  number: 'numeric',
+  phone: 'phone-pad',
+  url: 'url',
+} as const satisfies Record<TextFieldKeyboard, Parameters<typeof keyboardType>[0]>
+
+const CAPITALIZATION = {
+  characters: 'characters',
+  none: 'never',
+  sentences: 'sentences',
+  words: 'words',
+} as const satisfies Record<TextFieldAutoCapitalize, Parameters<typeof textInputAutocapitalization>[0]>
+
 /**
  * Disabled outranks error — a field nobody can edit should recede rather than shout. `.disabled` only
  * dims the text, so the chrome has to carry the state itself.
@@ -34,19 +67,50 @@ const toneOf = (disabled: boolean, error: boolean): FieldTone => {
 }
 
 export const TextField: TextFieldComponent = ({
+  autoCapitalize,
+  autoCorrect,
+  autoFocus = false,
+  contentType,
   defaultValue = '',
   disabled = false,
   error = false,
+  keyboard = 'default',
   label,
+  maxLength,
   multiline = false,
   onChangeText,
+  onFocusChange,
+  onSubmit,
+  placeholder,
+  ref,
   secure = false,
+  submitLabel,
   testID,
 }: TextFieldProps) => {
   useHostGuard('TextField')
   const text = useNativeState(defaultValue)
+  // One handle for either field: `SecureFieldRef` is `TextFieldRef` without the selection.
+  const field = useRef<SwiftUITextFieldRef>(null)
   const tone = TONE[toneOf(disabled, Boolean(error))]
   const message = tone === TONE.error && typeof error === 'string' && error ? error : undefined
+  const capitalization = capitalizationFor(keyboard, autoCapitalize)
+  const corrects = autoCorrectFor(keyboard, autoCorrect)
+  // A `SecureField` is one line whatever `multiline` says; a vertical `TextField`'s return key starts a new line.
+  const singleLine = secure || !multiline
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      blur: () => field.current?.blur().catch(ignoreDetachedView),
+      // Neither field reports a text set from code, so the change is reported here.
+      clear: () => {
+        field.current?.clear().catch(ignoreDetachedView)
+        onChangeText?.('')
+      },
+      focus: () => field.current?.focus().catch(ignoreDetachedView),
+    }),
+    [onChangeText]
+  )
 
   const sxModifiers = useSxModifiers({
     bg: tone.bg,
@@ -65,8 +129,33 @@ export const TextField: TextFieldComponent = ({
       list.push(disabledModifier(true))
     }
 
+    if (keyboard !== 'default') {
+      list.push(keyboardType(KEYBOARD[keyboard]))
+    }
+
+    if (capitalization) {
+      list.push(textInputAutocapitalization(CAPITALIZATION[capitalization]))
+    }
+
+    if (!corrects) {
+      list.push(autocorrectionDisabled(true))
+    }
+
+    if (contentType) {
+      list.push(textContentType(contentType))
+    }
+
+    if (singleLine && submitLabel) {
+      list.push(submitLabelModifier(submitLabel))
+    }
+
+    if (singleLine && onSubmit) {
+      // `onSubmit` reports no text, so it is read off the field's state, which the typing has already written.
+      list.push(onSubmitModifier(() => onSubmit(text.get())))
+    }
+
     return list
-  }, [disabled, sxModifiers])
+  }, [capitalization, contentType, corrects, disabled, keyboard, onSubmit, singleLine, submitLabel, sxModifiers, text])
 
   return (
     <VStack alignment="leading" spacing={spacing.s4}>
@@ -76,12 +165,27 @@ export const TextField: TextFieldComponent = ({
         </Text>
       ) : null}
       {secure ? (
-        <SecureField modifiers={modifiers} onTextChange={onChangeText} testID={testID} text={text} />
+        <SecureField
+          autoFocus={autoFocus}
+          maxLength={maxLength}
+          modifiers={modifiers}
+          onFocusChange={onFocusChange}
+          onTextChange={onChangeText}
+          placeholder={placeholder}
+          ref={field}
+          testID={testID}
+          text={text}
+        />
       ) : (
         <SwiftUITextField
+          autoFocus={autoFocus}
           axis={multiline ? 'vertical' : 'horizontal'}
+          maxLength={maxLength}
           modifiers={modifiers}
+          onFocusChange={onFocusChange}
           onTextChange={onChangeText}
+          placeholder={placeholder}
+          ref={field}
           testID={testID}
           text={text}
         />

package/src/atoms/text-field/text-field.types.ts

@@ -1,10 +1,72 @@
-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`. */
@@ -15,15 +77,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
 }
 

package/src/molecules/collapsible/collapsible.android.tsx

@@ -13,6 +13,7 @@ import {
   defaultMinSize,
   fillMaxWidth,
   graphicsLayer,
+  testID as testIdModifier,
   tween,
 } from '@expo/ui/jetpack-compose/modifiers'
 import {useAccessibilityModifiers} from '@hzblj/kara-sx'
@@ -44,7 +45,13 @@ const ROW_HEIGHT = 48
  * toward it, as a Material disclosure does — it used to jump between two glyphs. The row spans its parent, the chevron
  * at the far end, and is never shorter than a touch target.
  */
-export const Collapsible: CollapsibleComponent = ({children, expanded, label, onExpandedChange}: CollapsibleProps) => {
+export const Collapsible: CollapsibleComponent = ({
+  children,
+  expanded,
+  label,
+  onExpandedChange,
+  testID,
+}: CollapsibleProps) => {
   useHostGuard('Collapsible')
   const theme = useAppTheme()
   const reduced = useReducedMotion()
@@ -53,10 +60,11 @@ export const Collapsible: CollapsibleComponent = ({children, expanded, label, on
     () => [
       fillMaxWidth(),
       defaultMinSize({minHeight: ROW_HEIGHT}),
+      ...(testID ? [testIdModifier(testID)] : []),
       clickable(() => onExpandedChange(!expanded)),
       ...accessibilityModifiers,
     ],
-    [accessibilityModifiers, expanded, onExpandedChange]
+    [accessibilityModifiers, expanded, onExpandedChange, testID]
   )
   const turn = useMemo(
     () => [graphicsLayer({rotationZ: animated(expanded ? 90 : 0, reduced ? SNAP : TURN)})],

package/src/molecules/collapsible/collapsible.ios.tsx

@@ -3,11 +3,17 @@ import {DisclosureGroup} from '@expo/ui/swift-ui'
 import {useHostGuard} from '../../host-context'
 import type {CollapsibleComponent, CollapsibleProps} from './collapsible.types'
 
-export const Collapsible: CollapsibleComponent = ({children, expanded, label, onExpandedChange}: CollapsibleProps) => {
+export const Collapsible: CollapsibleComponent = ({
+  children,
+  expanded,
+  label,
+  onExpandedChange,
+  testID,
+}: CollapsibleProps) => {
   useHostGuard('Collapsible')
 
   return (
-    <DisclosureGroup isExpanded={expanded} label={label} onIsExpandedChange={onExpandedChange}>
+    <DisclosureGroup isExpanded={expanded} label={label} onIsExpandedChange={onExpandedChange} testID={testID}>
       {children}
     </DisclosureGroup>
   )

package/src/molecules/collapsible/collapsible.types.ts

@@ -13,6 +13,8 @@ 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/src/molecules/radio-group/radio-group.android.tsx

@@ -5,25 +5,39 @@ import {VStack} from '../../atoms/v-stack'
 import {useHostGuard} from '../../host-context'
 import type {RadioGroupComponent, RadioGroupProps} from './radio-group.types'
 
-export const RadioGroup: RadioGroupComponent = ({onValueChange, options, value}: RadioGroupProps) => {
+/**
+ * Material's radio buttons, each in a full-width row that selects it as a whole. A disabled group keeps every
+ * button's handler, so Material keeps the touch target an enabled one has; `enabled` is what stops the input.
+ */
+export const RadioGroup: RadioGroupComponent = ({
+  disabled = false,
+  onValueChange,
+  options,
+  testID,
+  value,
+}: RadioGroupProps) => {
   useHostGuard('RadioGroup')
 
   const theme = useAppTheme()
 
   return (
-    <VStack spacing="s4" wide>
+    <VStack spacing="s4" testID={testID} wide>
       {options.map(option => (
         <Row
           key={option.value}
-          modifiers={[fillMaxWidth(), clickable(() => onValueChange?.(option.value))]}
+          modifiers={disabled ? [fillMaxWidth()] : [fillMaxWidth(), clickable(() => onValueChange?.(option.value))]}
           verticalAlignment="center"
         >
           <RadioButton
             colors={{selectedColor: theme.color('fill.accent.primary')}}
+            enabled={!disabled}
             onClick={() => onValueChange?.(option.value)}
             selected={option.value === value}
           />
-          <ComposeText color={theme.colorString('content.primary')} style={theme.typography.body}>
+          <ComposeText
+            color={theme.colorString(disabled ? 'content.tertiary' : 'content.primary')}
+            style={theme.typography.body}
+          >
             {option.label}
           </ComposeText>
         </Row>

package/src/molecules/radio-group/radio-group.ios.tsx

@@ -6,16 +6,30 @@ import {Glyph} from '../../glyph'
 import {useHostGuard} from '../../host-context'
 import type {RadioGroupComponent, RadioGroupProps} from './radio-group.types'
 
-export const RadioGroup: RadioGroupComponent = ({onValueChange, options, value}: RadioGroupProps) => {
+export const RadioGroup: RadioGroupComponent = ({
+  disabled = false,
+  onValueChange,
+  options,
+  testID,
+  value,
+}: RadioGroupProps) => {
   useHostGuard('RadioGroup')
 
   return (
-    <VStack spacing="s4" wide>
+    <VStack spacing="s4" testID={testID} wide>
       {options.map(option => (
-        <HStack align="center" key={option.value} onPress={() => onValueChange?.(option.value)} py="s8" wide>
-          <Text>{option.label}</Text>
+        <HStack
+          align="center"
+          key={option.value}
+          onPress={disabled ? undefined : () => onValueChange?.(option.value)}
+          py="s8"
+          wide
+        >
+          <Text color={disabled ? 'content.tertiary' : 'content.primary'}>{option.label}</Text>
           <Spacer />
-          {option.value === value ? <Glyph color="content.accent" name="check" size="s20" /> : null}
+          {option.value === value ? (
+            <Glyph color={disabled ? 'content.tertiary' : 'content.accent'} name="check" size="s20" />
+          ) : null}
         </HStack>
       ))}
     </VStack>

package/src/molecules/radio-group/radio-group.types.ts

@@ -13,10 +13,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/src/molecules/search-bar/search-bar.tsx

@@ -7,7 +7,11 @@ import {RnGlyph} from '../../glyph'
 import type {SearchBarComponent, SearchBarProps} from './search-bar.types'
 
 export const SearchBar: SearchBarComponent = ({
+  autoCapitalize = 'none',
+  autoCorrect = false,
+  autoFocus = false,
   onChangeText,
+  onSubmit,
   placeholder = 'Search',
   testID,
   value,
@@ -35,9 +39,14 @@ export const SearchBar: SearchBarComponent = ({
     >
       <RnGlyph color="content.tertiary" name="search" size="s20" />
       <TextInput
+        autoCapitalize={autoCapitalize}
+        autoCorrect={autoCorrect}
+        autoFocus={autoFocus}
         onChangeText={onChangeText}
+        onSubmitEditing={onSubmit ? event => onSubmit(event.nativeEvent.text) : undefined}
         placeholder={placeholder}
         placeholderTextColor={theme.color('content.quaternary')}
+        returnKeyType="search"
         style={[text, {color: theme.color('content.primary'), flex: 1, padding: 0}]}
         value={value}
       />

package/src/molecules/search-bar/search-bar.types.ts

@@ -1,12 +1,23 @@
 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/src/molecules/stepper/stepper.android.tsx

@@ -7,25 +7,45 @@ import {useHostGuard} from '../../host-context'
 import type {StepperComponent, StepperProps} from './stepper.types'
 
 export const Stepper: StepperComponent = ({
+  decrementLabel = 'Decrement',
+  disabled = false,
+  incrementLabel = 'Increment',
   label,
   max = Number.MAX_SAFE_INTEGER,
   min = Number.MIN_SAFE_INTEGER,
   onValueChange,
   step = 1,
+  testID,
   value,
 }: StepperProps) => {
   useHostGuard('Stepper')
 
   const onDecrement = useCallback(() => onValueChange(Math.max(min, value - step)), [min, onValueChange, step, value])
   const onIncrement = useCallback(() => onValueChange(Math.min(max, value + step)), [max, onValueChange, step, value])
+  const color = disabled ? 'content.tertiary' : 'content.primary'
 
   return (
     <HStack align="center" spacing="s8" wide>
-      <Text>{label}</Text>
+      <Text color={color}>{label}</Text>
       <Spacer />
-      <GlyphButton accessibilityLabel="Decrement" disabled={value <= min} name="minus" onPress={onDecrement} />
-      <Text variant="labelMedium">{String(value)}</Text>
-      <GlyphButton accessibilityLabel="Increment" disabled={value >= max} name="plus" onPress={onIncrement} />
+      {/* The control in a row of its own, the same gap apart, so the id lands on it and not on the label. */}
+      <HStack align="center" spacing="s8" testID={testID}>
+        <GlyphButton
+          accessibilityLabel={decrementLabel}
+          disabled={disabled || value <= min}
+          name="minus"
+          onPress={onDecrement}
+        />
+        <Text color={color} variant="labelMedium">
+          {String(value)}
+        </Text>
+        <GlyphButton
+          accessibilityLabel={incrementLabel}
+          disabled={disabled || value >= max}
+          name="plus"
+          onPress={onIncrement}
+        />
+      </HStack>
     </HStack>
   )
 }

package/src/molecules/stepper/stepper.ios.tsx

@@ -1,5 +1,5 @@
 import {Stepper as SwiftUIStepper} from '@expo/ui/swift-ui'
-import {labelsHidden} from '@expo/ui/swift-ui/modifiers'
+import {disabled as disabledModifier, labelsHidden} from '@expo/ui/swift-ui/modifiers'
 import {useReducedMotion} from '@hzblj/kara-theme'
 import {useRef} from 'react'
 
@@ -12,12 +12,24 @@ import type {StepperComponent, StepperProps} from './stepper.types'
 /** The label stays VoiceOver's, on the control; on screen it is the row's own text. */
 const LABEL_HIDDEN = [labelsHidden()]
 
+const LABEL_HIDDEN_DISABLED = [labelsHidden(), disabledModifier(true)]
+
 /**
  * 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 const Stepper: StepperComponent = ({label, max, min, onValueChange, step = 1, value}: StepperProps) => {
+export const Stepper: StepperComponent = ({
+  disabled = false,
+  label,
+  max,
+  min,
+  onValueChange,
+  step = 1,
+  testID,
+  value,
+}: StepperProps) => {
   useHostGuard('Stepper')
   const reduced = useReducedMotion()
   const previous = useRef(value)
@@ -26,10 +38,10 @@ export const Stepper: StepperComponent = ({label, max, min, onValueChange, step
 
   return (
     <HStack align="center" spacing="s12" wide>
-      <Text>{label}</Text>
+      <Text color={disabled ? 'content.tertiary' : 'content.primary'}>{label}</Text>
       <Spacer />
       <Text
-        color="content.secondary"
+        color={disabled ? 'content.tertiary' : 'content.secondary'}
         ios={{
           animation: {value},
           contentTransition: reduced ? {type: 'opacity'} : {countsDown, type: 'numericText'},
@@ -38,13 +50,16 @@ export const Stepper: StepperComponent = ({label, max, min, onValueChange, step
       >
         {String(value)}
       </Text>
+      {/* iOS 27 stops a disabled stepper but draws its buttons at full strength. Pinned to its value, UIKit greys
+          both buttons, as it greys one at a limit. */}
       <SwiftUIStepper
         label={label}
-        max={max}
-        min={min}
-        modifiers={LABEL_HIDDEN}
+        max={disabled ? value : max}
+        min={disabled ? value : min}
+        modifiers={disabled ? LABEL_HIDDEN_DISABLED : LABEL_HIDDEN}
         onValueChange={onValueChange}
         step={step}
+        testID={testID}
         value={value}
       />
     </HStack>

package/src/molecules/stepper/stepper.types.ts

@@ -5,6 +5,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`. */
@@ -15,6 +27,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
 }