@hzblj/kara-components 0.17.0 → 0.19.0

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. */