@hzblj/kara-components 0.16.0 → 0.18.0

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>
   )

package/src/organisms/menu/menu.types.ts

@@ -10,8 +10,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. */
@@ -20,15 +25,33 @@ export type MenuAction = {
   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

package/src/organisms/sheet/sheet.tsx

@@ -32,6 +32,7 @@ const SheetRoot = ({
   onPresent,
   ref,
   scrollable = false,
+  systemBackground = false,
   testID,
   visible,
 }: SheetProps) => {
@@ -105,7 +106,7 @@ const SheetRoot = ({
   return (
     <View collapsable={false} pointerEvents="box-none" style={styles.host}>
       <TrueSheet
-        backgroundColor={theme.color(bg)}
+        backgroundColor={systemBackground && Platform.OS === 'ios' ? undefined : theme.color(bg)}
         cornerRadius={CORNER_RADIUS}
         detents={detents}
         dimmed={dimmed}

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

@@ -51,7 +51,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
@@ -80,6 +80,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. */