@hzblj/kara-components 0.17.0 → 0.18.0

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
 }

package/src/organisms/action-sheet/action-sheet.android.tsx

@@ -4,36 +4,48 @@ import {Island} from '../../atoms/island'
 import {Text} from '../../atoms/text'
 import {VStack} from '../../atoms/v-stack'
 import {useHostGuard} from '../../host-context'
+import {menuActionColor} from '../menu/menu-parts'
 import {Sheet} from '../sheet'
 import type {ActionSheetComponent, ActionSheetProps} from './action-sheet.types'
 
 /**
- * Material's bottom-sheet menu: the title, then a full-width row per action, its icon leading. The sheet is the React
- * Native tier, so the rows — Compose views — sit in an `Island` of their own; rendered straight into the sheet they had
- * no host and threw.
+ * Material's bottom-sheet menu: the title and the message, then a full-width row per action, its icon leading. The
+ * sheet is the React Native tier, so the rows — Compose views — sit in an `Island` of their own; rendered straight into
+ * the sheet they had no host and threw. A disabled row is greyed and has no press at all, so it neither ripples nor
+ * reads as a button.
  */
-export const ActionSheet: ActionSheetComponent = ({actions, onDismiss, title, visible}: ActionSheetProps) => {
+export const ActionSheet: ActionSheetComponent = ({actions, message, onDismiss, title, visible}: ActionSheetProps) => {
   useHostGuard('ActionSheet')
 
   return (
     <Sheet onDismiss={onDismiss} visible={visible}>
       <Island>
         <VStack pb="s16" wide>
-          <HStack px="s24" py="s12" wide>
+          {/* The message at the title's size, lighter: the iOS dialog's own pairing. */}
+          <VStack px="s24" py="s12" spacing="s4" wide>
             <Text color="content.secondary" variant="labelMedium">
               {title}
             </Text>
-          </HStack>
+            {message ? (
+              <Text color="content.secondary" variant="label">
+                {message}
+              </Text>
+            ) : null}
+          </VStack>
           {actions.map(action => {
-            const color = action.destructive ? 'content.destructive' : 'content.primary'
+            const color = menuActionColor(action)
 
             return (
               <HStack
                 key={action.label}
-                onPress={() => {
-                  onDismiss()
-                  action.onPress()
-                }}
+                onPress={
+                  action.disabled
+                    ? undefined
+                    : () => {
+                        onDismiss()
+                        action.onPress()
+                      }
+                }
                 px="s24"
                 py="s16"
                 spacing="s16"

package/src/organisms/action-sheet/action-sheet.ios.tsx

@@ -1,5 +1,5 @@
-import {Button, ConfirmationDialog, Spacer} from '@expo/ui/swift-ui'
-import {frame} from '@expo/ui/swift-ui/modifiers'
+import {Button, ConfirmationDialog, Spacer, Text as SwiftUIText} from '@expo/ui/swift-ui'
+import {disabled, frame} from '@expo/ui/swift-ui/modifiers'
 
 import {useHostGuard} from '../../host-context'
 import type {ActionSheetComponent, ActionSheetProps} from './action-sheet.types'
@@ -11,7 +11,13 @@ import type {ActionSheetComponent, ActionSheetProps} from './action-sheet.types'
  */
 const ANCHOR = [frame({height: 0, width: 0})]
 
-export const ActionSheet: ActionSheetComponent = ({actions, onDismiss, title, visible}: ActionSheetProps) => {
+const DISABLED = [disabled(true)]
+
+/**
+ * `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 const ActionSheet: ActionSheetComponent = ({actions, message, onDismiss, title, visible}: ActionSheetProps) => {
   useHostGuard('ActionSheet')
 
   return (
@@ -23,6 +29,7 @@ export const ActionSheet: ActionSheetComponent = ({actions, onDismiss, title, vi
         }
       }}
       title={title}
+      titleVisibility="visible"
     >
       <ConfirmationDialog.Trigger>
         <Spacer modifiers={ANCHOR} />
@@ -32,11 +39,21 @@ export const ActionSheet: ActionSheetComponent = ({actions, onDismiss, title, vi
           <Button
             key={action.label}
             label={action.label}
+            modifiers={action.disabled ? DISABLED : undefined}
             onPress={action.onPress}
             role={action.destructive ? 'destructive' : 'default'}
           />
         ))}
       </ConfirmationDialog.Actions>
+      {/*
+        A native slot view, which cannot hold a bare string (see `Alert`): the dialog mounts while dismissed, so an
+        unwrapped string would crash on mount. Plain SwiftUI `Text`, so the message keeps the system's styling.
+      */}
+      {message ? (
+        <ConfirmationDialog.Message>
+          <SwiftUIText>{message}</SwiftUIText>
+        </ConfirmationDialog.Message>
+      ) : null}
     </ConfirmationDialog>
   )
 }

package/src/organisms/action-sheet/action-sheet.types.ts

@@ -4,14 +4,19 @@ 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/src/organisms/alert/alert.android.tsx

@@ -7,9 +7,10 @@ import type {AlertComponent, AlertProps} from './alert.types'
 /**
  * Material's `AlertDialog`, built from its slots — title, text, confirm and dismiss buttons. Content passed as plain
  * children has no slot to land in, and the dialog draws empty. The actions mirror the iOS alert: the confirm label
- * (in the destructive colour when asked) and Cancel.
+ * (in the destructive colour when asked) and the cancel label, whose slot stays empty when it is `null`.
  */
 export const Alert: AlertComponent = ({
+  cancelLabel = 'Cancel',
   confirmLabel = 'OK',
   destructive = false,
   message,
@@ -62,13 +63,15 @@ export const Alert: AlertComponent = ({
           </ComposeText>
         </TextButton>
       </AlertDialog.ConfirmButton>
-      <AlertDialog.DismissButton>
-        <TextButton onClick={onDismiss}>
-          <ComposeText color={theme.colorString('content.accent')} style={theme.typography.body}>
-            Cancel
-          </ComposeText>
-        </TextButton>
-      </AlertDialog.DismissButton>
+      {cancelLabel === null ? null : (
+        <AlertDialog.DismissButton>
+          <TextButton onClick={onDismiss}>
+            <ComposeText color={theme.colorString('content.accent')} style={theme.typography.body}>
+              {cancelLabel}
+            </ComposeText>
+          </TextButton>
+        </AlertDialog.DismissButton>
+      )}
     </AlertDialog>
   )
 }

package/src/organisms/alert/alert.ios.tsx

@@ -11,6 +11,7 @@ import type {AlertComponent, AlertProps} from './alert.types'
 const ANCHOR = [frame({height: 0, width: 0})]
 
 export const Alert: AlertComponent = ({
+  cancelLabel = 'Cancel',
   confirmLabel = 'OK',
   destructive = false,
   message,
@@ -36,7 +37,7 @@ export const Alert: AlertComponent = ({
       </SwiftUIAlert.Trigger>
       <SwiftUIAlert.Actions>
         <Button label={confirmLabel} onPress={onConfirm ?? onDismiss} role={destructive ? 'destructive' : 'default'} />
-        <Button label="Cancel" onPress={onDismiss} role="cancel" />
+        {cancelLabel === null ? null : <Button label={cancelLabel} onPress={onDismiss} role="cancel" />}
       </SwiftUIAlert.Actions>
       {/*
         `Alert.Message` is a native slot view, and a SwiftUI host cannot render a bare string — it

package/src/organisms/alert/alert.types.ts

@@ -1,10 +1,15 @@
 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. */
@@ -13,7 +18,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/src/organisms/context-menu/context-menu.android.tsx

@@ -8,6 +8,7 @@ import {Icon} from '../../atoms/icon'
 import {HostBoundary} from '../../host-context'
 import {splitForRipple} from '../../ripple-clip'
 import type {MenuAction} from '../menu'
+import {menuActionColor} from '../menu/menu-parts'
 import type {ContextMenuComponent, ContextMenuExclusionProps, ContextMenuProps} from './context-menu.types'
 
 type Point = {x: number; y: number}
@@ -25,7 +26,7 @@ type MenuRowProps = {
 /** A row's `onClick` closes over its own action, so memoising it needs a component per row. */
 const MenuRow = ({action, onDismiss}: MenuRowProps) => {
   const theme = useAppTheme()
-  const color = action.destructive ? 'content.destructive' : 'content.primary'
+  const color = menuActionColor(action)
 
   const onClick = useCallback(() => {
     onDismiss()
@@ -33,7 +34,7 @@ const MenuRow = ({action, onDismiss}: MenuRowProps) => {
   }, [action, onDismiss])
 
   return (
-    <DropdownMenuItem onClick={onClick}>
+    <DropdownMenuItem enabled={!action.disabled} onClick={onClick}>
       <DropdownMenuItem.Text>
         <ComposeText color={theme.colorString(color)} style={theme.typography.body}>
           {action.label}

package/src/organisms/context-menu/context-menu.ios.tsx

@@ -26,6 +26,7 @@ const ContextMenuRoot = ({
     () =>
       actions.map((action, index) => ({
         destructive: action.destructive,
+        disabled: action.disabled,
         id: String(index),
         image: action.icon ? iconResourceName(action.icon) : undefined,
         title: action.label,

package/src/organisms/fab-menu/fab-menu.android.tsx

@@ -43,6 +43,9 @@ const FabMenuRow = ({action, onSelect}: FabMenuRowProps) => {
 }
 
 /**
+ * `MenuAction.destructive` and `disabled` are not drawn: Material 3's `FloatingActionButtonMenuItem` takes neither a
+ * role nor an `enabled` state, and its pills keep the button's colours.
+ *
  * The menu fills its host and pins itself to the bottom end, so give it the corner of a screen — a `ZStack` over the
  * content — rather than a row of its own. The pills take the button's colours, so the menu reads as the button
  * unfolding rather than a second surface.

package/src/organisms/fab-menu/fab-menu.ios.tsx

@@ -1,4 +1,5 @@
 import {Button, Image, Label, Menu} from '@expo/ui/swift-ui'
+import {disabled} from '@expo/ui/swift-ui/modifiers'
 import {iconResourceName} from '@hzblj/expo-native-icons'
 
 import {Icon} from '../../atoms/icon'
@@ -10,6 +11,8 @@ import type {FabMenuComponent, FabMenuProps} from './fab-menu.types'
 /** Matches `Fab`, so a screen can switch between the two without the button changing shape. */
 const FAB_SIZE = 56
 
+const DISABLED = [disabled(true)]
+
 export const FabMenu: FabMenuComponent = ({accessibilityLabel, actions, icon, testID}: FabMenuProps) => {
   useHostGuard('FabMenu')
 
@@ -35,7 +38,12 @@ export const FabMenu: FabMenuComponent = ({accessibilityLabel, actions, icon, te
       testID={testID}
     >
       {actions.map(action => (
-        <Button key={action.label} onPress={action.onPress} role={action.destructive ? 'destructive' : 'default'}>
+        <Button
+          key={action.label}
+          modifiers={action.disabled ? DISABLED : undefined}
+          onPress={action.onPress}
+          role={action.destructive ? 'destructive' : 'default'}
+        >
           {/* A menu row is the system's Label: our icon is its image, from the asset catalog, and UIKit sizes it. */}
           <Label
             icon={action.icon ? <Image assetName={iconResourceName(action.icon)} /> : undefined}

package/src/organisms/menu/menu-parts.ts

@@ -0,0 +1,21 @@
+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 const menuActionColor = ({destructive, disabled}: MenuAction): ColorToken => {
+  if (disabled) {
+    return 'btn.content.disabled'
+  }
+
+  return destructive ? 'content.destructive' : 'content.primary'
+}
+
+/** A trigger with no text: the props' union guarantees its icon and the words a screen reader says for it. */
+export const isIconOnly = (props: MenuProps): props is MenuProps & {accessibilityLabel: string; icon: IconName} =>
+  props.label === undefined

package/src/organisms/menu/menu.android.tsx

@@ -1,12 +1,14 @@
 import {Text as ComposeText, DropdownMenu, DropdownMenuItem} from '@expo/ui/jetpack-compose'
 import {useAppTheme} from '@hzblj/kara-theme'
-import {useCallback, useState} from 'react'
+import {type ReactNode, useCallback, useState} from 'react'
 import {HStack} from '../../atoms/h-stack'
 import {Icon} from '../../atoms/icon'
+import {IconButton} from '../../atoms/icon-button'
 import {Text} from '../../atoms/text'
 import {Glyph} from '../../glyph'
 import {useHostGuard} from '../../host-context'
 import type {MenuAction, MenuComponent, MenuProps} from './menu.types'
+import {isIconOnly, menuActionColor} from './menu-parts'
 
 type MenuItemProps = {
   action: MenuAction
@@ -15,11 +17,12 @@ type MenuItemProps = {
 
 const MenuItem = ({action, onDismiss}: MenuItemProps) => {
   const theme = useAppTheme()
-  const color = action.destructive ? 'content.destructive' : 'content.primary'
+  const color = menuActionColor(action)
 
   return (
     <DropdownMenuItem
       elementColors={{leadingIconColor: theme.color(color), textColor: theme.color(color)}}
+      enabled={!action.disabled}
       onClick={() => {
         onDismiss()
         action.onPress()
@@ -39,27 +42,53 @@ const MenuItem = ({action, onDismiss}: MenuItemProps) => {
   )
 }
 
+const triggerOf = (props: MenuProps, open: () => void): ReactNode => {
+  if (isIconOnly(props)) {
+    // Material's overflow menu: an icon button, its label carried by the icon.
+    return (
+      <IconButton
+        accessibilityLabel={props.accessibilityLabel}
+        name={props.icon}
+        onPress={open}
+        testID={props.testID}
+      />
+    )
+  }
+
+  const {accessibilityLabel, icon, label, testID} = props
+
+  return (
+    <HStack accessibilityLabel={accessibilityLabel} align="center" onPress={open} spacing="s4" testID={testID}>
+      {icon ? (
+        <HStack align="center" spacing="s8">
+          <Icon color="content.accent" name={icon} size="s20" />
+          <Text color="content.accent">{label}</Text>
+        </HStack>
+      ) : (
+        <Text color="content.accent">{label}</Text>
+      )}
+      <Glyph color="content.accent" name="chevronDown" size="s16" />
+    </HStack>
+  )
+}
+
 /**
  * Material's dropdown menu, anchored to its trigger. The items live in the `Items` slot, which Compose presents in
  * its own popup — anywhere else they would be laid out in place, on top of the trigger.
  */
-export const Menu: MenuComponent = ({actions, label}: MenuProps) => {
+export const Menu: MenuComponent = (props: MenuProps) => {
   useHostGuard('Menu')
 
   const theme = useAppTheme()
   const [expanded, setExpanded] = useState(false)
+  const open = useCallback(() => setExpanded(true), [])
   const dismiss = useCallback(() => setExpanded(false), [])
 
   return (
     <DropdownMenu color={theme.color('surface.primary')} expanded={expanded} onDismissRequest={dismiss}>
-      <DropdownMenu.Trigger>
-        <HStack align="center" onPress={() => setExpanded(true)} spacing="s4">
-          <Text color="content.accent">{label}</Text>
-          <Glyph color="content.accent" name="chevronDown" size="s16" />
-        </HStack>
-      </DropdownMenu.Trigger>
+      <DropdownMenu.Trigger>{triggerOf(props, open)}</DropdownMenu.Trigger>
       <DropdownMenu.Items>
-        {actions.map(action => (
+        {props.actions.map(action => (
           <MenuItem action={action} key={action.label} onDismiss={dismiss} />
         ))}
       </DropdownMenu.Items>

package/src/organisms/menu/menu.ios.tsx

@@ -1,20 +1,70 @@
-import {Button, Menu as SwiftUIMenu} from '@expo/ui/swift-ui'
+import {Button, Image, Label, Menu as SwiftUIMenu} from '@expo/ui/swift-ui'
+import {contentShape, disabled, frame, resizable, shapes} from '@expo/ui/swift-ui/modifiers'
+import {iconResourceName} from '@hzblj/expo-native-icons'
+import {useAccessibilityModifiers} from '@hzblj/kara-sx'
+import {spacing} from '@hzblj/kara-theme'
+import type {ReactNode} from 'react'
 
+import {Icon} from '../../atoms/icon'
+import {ZStack} from '../../atoms/z-stack'
 import {useHostGuard} from '../../host-context'
 import type {MenuComponent, MenuProps} from './menu.types'
+import {isIconOnly} from './menu-parts'
 
-export const Menu: MenuComponent = ({actions, label}: MenuProps) => {
+const DISABLED = [disabled(true)]
+
+/** Apple's least tap target, as `IconButton` takes it. */
+const TARGET = 44
+
+/** The whole square takes the tap, not only the glyph's own pixels. */
+const WHOLE_TARGET = {modifiers: [contentShape(shapes.circle())]}
+
+/**
+ * The icon beside the trigger's text, the size `Link` draws one beside body text. No colour of its own: the asset is a
+ * template image, so it takes the menu's tint with the text.
+ */
+const LABEL_ICON = [resizable(), frame({height: spacing.s20, width: spacing.s20})]
+
+const triggerOf = (props: MenuProps): ReactNode => {
+  if (isIconOnly(props)) {
+    // An icon alone is drawn as an `IconButton`: `content.primary`, its label carried by the icon.
+    return (
+      <ZStack h={TARGET} ios={WHOLE_TARGET} w={TARGET}>
+        <Icon accessibilityLabel={props.accessibilityLabel} color="content.primary" name={props.icon} />
+      </ZStack>
+    )
+  }
+
+  return props.icon ? (
+    <Label icon={<Image assetName={iconResourceName(props.icon)} modifiers={LABEL_ICON} />} title={props.label} />
+  ) : (
+    props.label
+  )
+}
+
+export const Menu: MenuComponent = (props: MenuProps) => {
   useHostGuard('Menu')
+  const {accessibilityLabel, actions, label, testID} = props
+  // An icon alone carries its own label; with text, `accessibilityLabel` replaces it on the menu.
+  const modifiers = useAccessibilityModifiers({
+    accessibilityLabel: label === undefined ? undefined : accessibilityLabel,
+  })
 
   return (
-    <SwiftUIMenu label={label}>
+    <SwiftUIMenu label={triggerOf(props)} modifiers={modifiers} testID={testID}>
       {actions.map(action => (
         <Button
           key={action.label}
-          label={action.label}
+          label={action.icon ? undefined : action.label}
+          modifiers={action.disabled ? DISABLED : undefined}
           onPress={action.onPress}
           role={action.destructive ? 'destructive' : 'default'}
-        />
+        >
+          {/* A menu row is the system's Label: our icon is its image, from the asset catalog, and UIKit sizes it. */}
+          {action.icon ? (
+            <Label icon={<Image assetName={iconResourceName(action.icon)} />} title={action.label} />
+          ) : undefined}
+        </Button>
       ))}
     </SwiftUIMenu>
   )