@mrmeg/expo-ui 0.26.0 → 0.27.1

package/CHANGELOG.md

@@ -5,6 +5,174 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.27.1]
+
+### Fixed
+
+- **`BottomSheet.Content` paints no fill of its own; the native surface set
+  through `backgroundStyle` is the sheet's only background.** `@expo/ui`'s iOS
+  sheet lays the hosted RN column out 16 pt below the sheet's top edge while the
+  native grabber is shown, so the column's own card fill covered everything
+  below that line and the strip behind the grabber showed the native
+  `presentationBackground` alone. Opaque theme colors matched and hid the seam,
+  but a translucent card, or a translucent `backgroundStyle`, read as two layers
+  below the line and one above it: a differently shaded band behind the grabber
+  in every app with a glass-style sheet (iPhone 17 simulator, iOS 27, `@expo/ui`
+  58.0.2, 60% card: strip 30,30,32 over a 24,24,27 body; one continuous
+  30,30,32 surface from the rim down after the change). Web (vaul panel) and
+  Android (`containerColor`) already paint the surface natively, so the column
+  fill was redundant there too. `backgroundStyle={{ backgroundColor:
+  "transparent" }}` no longer needs a `style` clearing the column; content sits
+  directly on the transparent surface, so add a fill inside the content if a
+  card behind it was intended.
+- **iOS `Dialog` and `AlertDialog` present through React Native's `Modal`, so
+  `@expo/ui`-hosted controls inside them mount and take focus.** Both dialogs
+  rendered through react-native-screens' `FullWindowOverlay` on iOS, which adds
+  its container straight to the `UIWindow` with no `UIViewController` above it.
+  `expo-modules-core`'s `ExpoSwiftUI.HostingView` attaches its
+  `UIHostingController` only when `reactViewController()` finds a parent
+  controller and otherwise removes the SwiftUI view, so every hosted control
+  inside a dialog — the package `TextInput`, and `Slider` / `SegmentedControl`
+  — was a zero-height box: no editable accessibility element, no focus, no
+  keyboard (fieldnest `start-trip-modal-keyboard-avoidance`, iOS 27 simulator,
+  0.27.0; reproduced in the template's `Dialog` `form` variant, where the
+  accessibility tree listed only the two field labels and a tap raised no
+  keyboard, while the same content mounted and focused with the overlay
+  replaced by a Fragment — but then did not move for the keyboard, because the
+  portal host sits outside `UIProvider`'s root avoidance). `DialogContent` and
+  `AlertDialogContent` now present through a transparent, unanimated
+  `overFullScreen` `Modal` on iOS, rendered inline where the dialog sits in
+  the tree instead of through the portal host: RN presents a `Modal` from the
+  view controller nearest its host view, so a portal-hosted `Modal` presents
+  from the root controller and silently fails while a native stack modal or
+  sheet is up (device-verified — the trigger reported expanded, nothing
+  appeared), while the inline one presents from the screen, native stack modal
+  or sheet that contains the dialog and stacks above it (device-verified over
+  a `presentation: "modal"` route). `portalHost` is honored on Android and web
+  only, and a `Dialog` placed inside `FullWindowOverlay`-hosted content
+  (`Drawer`, `Popover`, `Select`, `DropdownMenu`, `Tooltip`) has no view
+  controller to present from on iOS — render it at screen level and open it
+  from the item's `onPress`. The platform close request (`onRequestClose`)
+  reaches the root's `onOpenChange(false)`. The Modal is
+  outside the root keyboard avoidance, so the dialog owns it there: the
+  centered container is wrapped in the package `KeyboardAvoidingView`
+  (`behavior="padding"`), the card recenters above the keyboard, and
+  `useKeyboardAvoidance()` is `true` inside dialog content — do not wrap dialog
+  content in another `KeyboardAvoidingView`. Device-verified on iOS 27: the
+  first tap on each field focuses it, the keyboard appears, typing lands, and
+  both fields and the footer stay visible. Android and web keep the inline
+  portal-host tree unchanged; there the portal host is still outside the root
+  avoidance, so an Android dialog does not avoid the keyboard yet (follow-up).
+  `Drawer`, `Popover`, `Select`, `DropdownMenu` and `Tooltip` still render
+  through `FullWindowOverlay`, so hosted controls inside those do not mount on
+  iOS either (follow-up).
+- **Android `BottomSheet` names the host requirement its keyboard avoidance
+  depends on.** 0.27.0 said Material owns Android avoidance. That is true for
+  the window and, on `expo-modules-core` >= 57.0.4, for the hosted column too:
+  Material3's `ModalBottomSheet` shrinks the sheet with `imePadding()`,
+  `@expo/ui`'s `RNHostView` re-reports its Compose size to the shadow tree, and
+  the `flexGrow: 1, height: 0` column follows, so `Footer` and the tail of
+  `Body` stay above the keyboard and `Body` scrolls. `expo-modules-core`
+  <= 57.0.3 flushed that report only from a pre-draw listener on the activity
+  window, which does not draw while the sheet's own dialog window animates the
+  IME, so the column kept its detent height until the activity redrew
+  (expo/expo#47778, fixed by expo/expo#47810 in 57.0.4 and 58.0.0; no 56.x
+  release has it). That is the clipped `Footer` tractor-tools-direct #32 saw on
+  Expo 57 with core 57.0.3, and background/resume "fixing" it. The package adds
+  no inset or height of its own — nothing in JS can observe a size the shadow
+  tree never received — and instead warns once in development on Android when
+  the native core compiled into the app is older (`globalThis.expo`'s
+  `expoModulesCoreVersion`), and the docs state the floor: `npx expo install
+  --fix` (or `bun update expo-modules-core`), then rebuild. iOS and web are
+  untouched.
+- **Android state surfaces no longer re-parent their children on a
+  `disabled` / `pending` / `checked` flip.** `Button` (surface and content),
+  `TextInput`, `Slider`, `InputOTP` and the `Switch` labels express state as
+  `opacity` on a plain `View`. On Fabric a View whose only stacking-context
+  prop is that opacity has its children hoisted into the parent while the
+  opacity is 1 and pulled back under it when the opacity changes, and a flip
+  that raced a navigation pop crashed with `addViewAt: cannot insert view …
+  View already has a parent` (doglog #57, Pixel 6a). Those Views now set
+  `collapsable={false}` on Android so the native tree shape is fixed across
+  state. iOS and web are unchanged. `stateSurfaceProps()` from
+  `@mrmeg/expo-ui/lib` is the same guard for app-owned surfaces; RN's
+  `Pressable` already pins itself, so `Pressable`-based controls need nothing.
+
+- **`BottomSheet` names the ancestor `ScrollView` that swallows the first tap
+  on a sheet control while a sheet field is focused (Android).** Sheet content
+  is drawn in the Material dialog window but stays in the screen's React tree,
+  and React Native's responder negotiation walks that tree: a `ScrollView`
+  around the `BottomSheet` on the default `keyboardShouldPersistTaps="never"`
+  claims a tap on `Footer` (or any sheet control) in the capture phase once a
+  field is focused — RN's `Keyboard` reports the sheet's IME from the activity
+  root — and blurs the field on release, so the keyboard closes and `onPress`
+  never runs (Pixel_10 / API 36, `@expo/ui` 58.0.2: 0 of 3 Footer taps fired
+  inside a default `ScrollView`, 3 of 3 inside
+  `keyboardShouldPersistTaps="always"` or a plain `View`; `Body`'s own `always`
+  covers only ScrollViews inside the sheet). Nothing inside the tree can preempt
+  a capture-phase claim,
+  so `BottomSheet.Content` now warns once in development on Android when a
+  touch starts on its column without having reached the column's own capture
+  handler while a package `TextInput` holds focus — the exact signature of that
+  claim — and the docs state the remedy: `keyboardShouldPersistTaps="always"`
+  (or `"handled"`) on scroll views that contain a sheet, or `DismissKeyboard`,
+  which already sets it. The tap-away boundary itself is unchanged; iOS and web
+  are untouched.
+
+## [0.27.0]
+
+### Changed
+
+- **`StyledText` is non-selectable by default on Android.** RN implements
+  `selectable` with `TextView.setTextIsSelectable(true)`, which makes the label
+  focusable-in-touch-mode, so a tap on any default `StyledText` next to a
+  focused `TextInput` moved view focus to the label and hid the keyboard
+  (tractor-tools-direct #19, mindmap #38 worked around it per label). The
+  Android default is now `false`; pass `selectable` to opt copyable content in.
+  iOS and web keep `true`, an explicit `selectable` prop still wins everywhere,
+  and `TextSelectabilityContext` still overrides the platform default. Consumers
+  can drop `selectable={false}` added only to keep the Android keyboard up;
+  keeping it on control chrome is harmless and still recommended for iOS/web.
+- **`BottomSheet.Content avoidKeyboard` is documented as platform-owned, with
+  the iOS behavior verified on device.** The prop stays accepted-and-ignored,
+  like `swipeEnabled` and `dismissKeyboardOnDrag`. On iOS (iPhone 17 Pro, iOS
+  27, `@expo/ui` 58.0.2) UIKit's sheet presentation keeps the hosted RN column
+  above the keyboard by itself: a 45% sheet is lifted whole (its column shrinks
+  393 → 363 pt), a 92% sheet is shrunk in place (700 → 468 pt), and in both
+  cases the column's bottom edge lands at the keyboard's top, so `Footer` and
+  the tail of `Body` sit 50 pt (`spacing.md` + home-indicator inset) above the
+  keyboard and a long `Body` scrolls. The package therefore adds no inset, and
+  none could be correct from JS: `measureInWindow` inside the `layoutRoot`
+  sheet host reports host-relative coordinates (the 45% column read bottom 409
+  while sitting at screen y 546), and a window-height estimate would lift a
+  lifted sheet twice. Android: Material3's `ModalBottomSheet` owns avoidance
+  (no JS keyboard signal exists inside the Compose dialog window: RN reads IME
+  insets from the main root view, and keyboard-controller watches only the
+  main window and RN `Modal` dialogs). Web: none. Never nest a
+  `KeyboardAvoidingView` inside a sheet.
+
+### Fixed
+
+- **`TextInput` no longer forwards the Android mount blur.** Compose reports
+  `isFocused=false` when the field is first composed and the Android field
+  forwarded it as `onBlur`, so forms validating on blur showed "required"
+  errors before the user typed anything (tractor-tools-direct #28 gated it in
+  app code). `onBlur` now fires only after the field has reported focus, and a
+  repeated blur with no focus in between is dropped too. Android only; iOS and
+  web are unchanged. Consumers can drop touched-field guards added for this.
+- **`BottomSheet.Body` no longer swallows the first tap on its controls while a
+  sheet field is focused on iOS.** `Body`'s `ScrollView` now sets
+  `keyboardShouldPersistTaps="always"` (before `{...props}`, so an explicit
+  consumer value still wins). Without it RN's default `never` policy claimed the
+  tap in the capture phase whenever a registered field was focused and the
+  keyboard was visible, then blurred the field on release, so chips, buttons,
+  tabs and field-to-field handoff inside `Body` needed a second tap. The
+  `BottomSheet.Content` column boundary already owns tap-away dismissal, so
+  dead-space taps inside `Body` still dismiss on release and a short drag still
+  does not. Android >= 30 was already unaffected: RN reads keyboard insets from
+  the main root view, and the Material sheet is its own window, so RN's policy
+  never armed there.
+
 ## [0.26.0]
 
 ### Changed

package/LLM_USAGE.md

@@ -85,13 +85,48 @@ call `dismissKeyboard()` explicitly.
 SwiftUI `.sheet()`, Android Material3 `ModalBottomSheet`, web `vaul`). The
 platform owns gestures and keyboard avoidance: `swipeEnabled`, `avoidKeyboard`,
 and `dismissKeyboardOnDrag` are accepted for call-site ergonomics but have no
-effect. `Slider` and `SegmentedControl` are also `@expo/ui`-backed.
+effect. On iOS the sheet presentation lifts or shrinks the hosted content so
+`Footer` and the tail of `Body` end at the keyboard's top (device-verified);
+on Android Material3 shrinks the sheet and `@expo/ui`'s `RNHostView` re-reports
+its size to the shadow tree, which needs the app built against
+`expo-modules-core` >= 57.0.4 (expo/expo#47778) — below that the column keeps
+its detent height and `Footer` sits under the keyboard; the sheet warns once in
+dev on Android, and the fix is `npx expo install --fix` plus a rebuild, never
+padding in app code. Do not nest a `KeyboardAvoidingView` inside a
+sheet. `BottomSheet.Content` mounts the tap-away keyboard-dismiss boundary on
+its column, and `BottomSheet.Body` sets `keyboardShouldPersistTaps="always"` on
+its ScrollView so that boundary owns dismissal; do not pass `never`. Sheet
+content stays in the screen's React tree although it is drawn in another
+window, so a ScrollView *around* a `BottomSheet` on the default
+`keyboardShouldPersistTaps="never"` claims the first tap on any sheet control
+(`Footer` included) while a sheet field is focused and blurs the field instead:
+give scroll views that contain a sheet `keyboardShouldPersistTaps="always"` (or
+`"handled"`), or use `DismissKeyboard`; the sheet warns once in dev on Android
+when it sees such a tap. `Slider` and `SegmentedControl` are also
+`@expo/ui`-backed.
 
 `BottomSheet.Content` themes the native sheet surface with the card color. Pass
 `backgroundStyle={{ backgroundColor: "transparent" }}`, plus a `style` clearing
 the content column's card fill, when custom chrome such as a glass backdrop must
 show through.
 
+`Dialog` and `AlertDialog` present their content through React Native's `Modal`
+on iOS, rendered inline where the dialog sits (transparent, `overFullScreen`,
+unanimated; the package fade/scale run inside), so it stacks above whatever
+screen, native stack modal or sheet contains it; `portalHost` is honored on
+Android and web only. `@expo/ui`-hosted controls (`TextInput`, `Slider`,
+`SegmentedControl`) need a view controller above them and render as empty,
+unfocusable boxes inside react-native-screens' `FullWindowOverlay`, which
+`Drawer`, `Popover`, `Select`, `DropdownMenu` and `Tooltip` still use on iOS —
+keep hosted controls out of those, and do not place a `Dialog` inside their
+content (no view controller to present from; render it at screen level and open
+it from the item's `onPress`). The dialog owns keyboard avoidance inside its Modal (package
+`KeyboardAvoidingView`, `behavior="padding"`; the card recenters above the
+keyboard and `useKeyboardAvoidance()` is `true` in dialog content); do not wrap
+dialog content in another `KeyboardAvoidingView`. Android and web render dialog
+content inline into the portal host, outside the root avoidance, so an Android
+dialog does not avoid the keyboard yet.
+
 i18n is optional. Do not add app-level i18n setup just to use this package;
 plain children and `text` props work without `i18next` or `react-i18next`. `tx`
 props render their fallback text when provided, otherwise the key. Package-owned
@@ -258,14 +293,15 @@ Check this before creating a new app-local primitive. All components come from
 `caption`, `label`, `eyebrow`), `size` (`xs`, `sm`, `base`, `body`, `lg`, `xl`,
 `xxl`, `display`), `fontWeight` (`light`–`bold`), `variant` (`sansSerif`,
 `serif`, `mono`), `align`, `text`, `tx`, `txOptions`, `selectable` (default
-`true`). Aliases: `DisplayText`, `TitleText`, `HeadingText`, `SubheadingText`,
+`true` on iOS and web, `false` on Android since 0.27.0). Aliases: `DisplayText`, `TitleText`, `HeadingText`, `SubheadingText`,
 `BodyText`, `CaptionText`, `LabelText`, `EyebrowText`, `MonoText`, `SerifText`,
 `SansSerifText`, `SerifBoldText`, `SansSerifBoldText`.
 
-Set `selectable={false}` on text labels inside app-owned `Pressable`s. Selectable
-Android text can take input focus even if the press handler never dismisses the
-keyboard. Package controls already scope label selectability; ordinary text
-should remain selectable.
+Set `selectable={false}` on text labels inside app-owned `Pressable`s on every
+platform (control chrome shows no selection cursor). On Android `StyledText` is
+non-selectable by default because a selectable `Text` takes input focus and hides
+the keyboard; pass `selectable` to opt copyable content in. Package controls
+already scope label selectability; ordinary iOS/web text stays selectable.
 
 ## Component Selection Rules
 
@@ -275,6 +311,8 @@ should remain selectable.
 - `Carousel` for a horizontal snap row of a known, small set of slides. It renders every child (no virtualization), so slides survive into the exported HTML shell and the first client frame; use `FlatList` for large or unbounded data. Dots are pressable and jump to their slide. A fractional `itemWidth` (default `0.85`) measures the viewport until the first layout, so pass absolute pixels (`> 1`) when the parent is narrower than the window and the first frame matters.
 - `Avatar` with both `source` and `name` whenever both exist: `name` supplies the initials shown when the image is absent, still loading, or failed, plus the default accessibility label. Inside `AvatarGroup`, set `size`/`shape` on the group — children inherit them and gain the ring; the group's count is a hidden summary node, so each member stays individually announceable and the group needs no `accessible` wrapper.
 - Pair a standalone `Label` with its control using two DISTINCT ids: `nativeID` is the label's own id, `htmlFor` is the input's id (`<Label nativeID="email-label" htmlFor="email-input">` + `<TextInput nativeID="email-input" />`). One id on both renders duplicate ids on web and associates nothing. Prefer `TextInput`'s own `label` prop when no separate label element is needed.
+- A plain `View` whose `opacity`/`pointerEvents` follows state must be `collapsable={false}` on Android (Fabric re-parents its children on the flip; a flip racing a navigation pop crashes). Package surfaces are pinned; spread `stateSurfaceProps()` from `@mrmeg/expo-ui/lib` on app-owned ones. `Pressable` already pins itself.
+- `TextInput` `onBlur` fires only after a real focus on Android (the native field's first-composition blur is dropped in the package); validate on blur directly and do not add a touched-fields guard in app code.
 - `Drawer.Header` takes `icon`, `title`, and `action` slots for a compact app-brand row; put `Drawer.ToggleCollapse` in `action` for a trailing rail control. `Drawer.Content` owns safe-area top/bottom padding — do not duplicate it in children.
 
 ## Minimal Examples

package/README.md

@@ -314,12 +314,17 @@ import { BodyText, CaptionText, HeadingText, StyledText } from "@mrmeg/expo-ui/c
 - `fontWeight`: `light`, `regular`, `medium`, `semibold`, `bold`
 - `variant`: `sansSerif`, `serif`, `mono`
 - `align`, `text`, `tx`, `txOptions`
-- `selectable`: defaults to `true`; package controls disable it for labels and
-  interactive chrome where accidental drag selection would feel broken.
-
-For app-owned `Pressable` labels, explicitly set `selectable={false}` on the
-nested `StyledText`. On Android selectable label text can take focus and the IME
-connection from an active input. Preserve selection for ordinary readable text.
+- `selectable`: defaults to `true` on iOS and web and to `false` on Android
+  (0.27.0), where a selectable `Text` is focusable and takes focus and the IME
+  from an active input. Opt copyable content in per element with `selectable`
+  (codes, addresses, chat bubbles). Package controls disable it on every
+  platform for labels and interactive chrome where accidental drag selection
+  would feel broken.
+
+For app-owned `Pressable` labels, still set `selectable={false}` on the nested
+`StyledText` so iOS and web show no selection cursor on control chrome. Ordinary
+readable text keeps selection on iOS and web; on Android it selects only when
+opted in.
 
 Aliases: `DisplayText`, `TitleText`, `HeadingText`, `SubheadingText`,
 `BodyText`, `CaptionText`, `LabelText`, `EyebrowText`, `MonoText` (code, IDs,
@@ -553,6 +558,16 @@ web, where the window cannot be read during export or hydration.
   Native targets add computed hit slop up to 44px. Nested `StyledText` inherits
   the Button size, so use `size="sm"` for popover, tooltip, and toolbar
   triggers.
+- A plain `View` whose `opacity` or `pointerEvents` follows state (`disabled`,
+  `loading`, `checked`, `editable`) must be `collapsable={false}` on Android.
+  Fabric hoists the children of a filled or bordered View into its parent while
+  the opacity is 1 and pulls them back when it changes, and a flip racing a
+  navigation pop crashes with `addViewAt: … View already has a parent`. The
+  package pins its own surfaces (`Button`, `TextInput`, `Slider`, `InputOTP`,
+  `Switch` labels); spread `stateSurfaceProps()` from `@mrmeg/expo-ui/lib` on
+  app-owned surfaces (`<View {...stateSurfaceProps()} style={{ opacity:
+  disabled ? 0.5 : 1 }} />`). `Pressable` already pins itself. iOS and web get
+  no prop.
 - Pair a standalone `Label` with its control using two DISTINCT ids: `nativeID`
   is the label's own id, `htmlFor` is the input's id (`<Label
   nativeID="email-label" htmlFor="email-input">` + `<TextInput
@@ -564,25 +579,84 @@ web, where the window cannot be read during export or hydration.
   `numberPassword` for numeric keyboards) in both the masked and the revealed
   eye-toggle state, with autocorrect off by default; that Android field is
   package-owned on top of `@expo/ui/jetpack-compose`'s `BasicTextField`, while
-  iOS uses `@expo/ui`'s universal field (SwiftUI `SecureField`).
+  iOS uses `@expo/ui`'s universal field (SwiftUI `SecureField`). On Android the
+  native field reports a blur when it is first composed; the package forwards
+  `onBlur` only after the field has reported focus, so blur validation never
+  flags an untouched field and app code needs no touched-fields guard.
 - `BottomSheet` renders the platform's native sheet through `@expo/ui`: iOS
   SwiftUI `.sheet()`, Android Material3 `ModalBottomSheet`, web `vaul`. The
   platform owns gestures and keyboard avoidance, so `swipeEnabled`,
   `avoidKeyboard`, and `dismissKeyboardOnDrag` are accepted for call-site
-  ergonomics but have no effect. The sheet hosts its content in a separate
+  ergonomics but have no effect. On iOS the sheet presentation itself keeps the
+  hosted content above the keyboard — a short sheet is lifted whole, a tall one
+  is shrunk — so `Footer` and the tail of `Body` end at the keyboard's top with
+  only their home-indicator padding as clearance (device-verified on iOS 27 with
+  `@expo/ui` 58); on Android Material3's `ModalBottomSheet` shrinks the sheet
+  for the keyboard and `@expo/ui`'s `RNHostView` re-reports its size to the
+  React Native shadow tree, so the hosted column follows and `Footer` stays
+  above the keyboard — this needs the app built against `expo-modules-core`
+  >= 57.0.4 (expo/expo#47778; older cores dropped that size update until the
+  activity redrew, leaving `Footer` under the keyboard; no 56.x release has the
+  fix). Run `npx expo install --fix` (or `bun update expo-modules-core`) and
+  rebuild; the sheet warns once in development on Android when the native core
+  is older. Web has none. Do not wrap sheet content in another
+  `KeyboardAvoidingView`: it would lift twice.
+  The sheet hosts its content in a separate
   native window outside the app's `DismissKeyboard`, so `BottomSheet.Content`
   mounts its own tap-away keyboard-dismiss boundary on the content column: it
   never claims the touch (buttons, tabs and other fields fire on the first tap
   with the keyboard up) and dismisses an unclaimed dead-space tap on release,
-  matching `DismissKeyboard`. Android has only two snap states (partial /
-  expanded) and maps extra snap points to the nearest; because Material ignores
-  percentage snap points, the Android body fills the rendered sheet height
-  rather than a window-percentage cap. `BottomSheet.Content` also takes
-  `backgroundStyle`, merged over the themed card default on the native sheet
-  surface (web panel, Android `containerColor`, iOS `presentationBackground`) —
-  pass `{ backgroundColor: "transparent" }`, plus a `style` clearing the
-  content column's card fill, to let custom chrome such as a glass backdrop
-  show through.
+  matching `DismissKeyboard`. `BottomSheet.Body` sets
+  `keyboardShouldPersistTaps="always"` on its ScrollView so that column boundary
+  owns dismissal; do not pass `never`, which lets RN claim the first tap on a
+  body control and blur the field instead. That covers ScrollViews inside the
+  sheet only: the sheet's content stays in the screen's React tree even though
+  it is drawn in another window, and RN's responder negotiation walks that tree,
+  so a ScrollView *around* the `BottomSheet` left on the default
+  `keyboardShouldPersistTaps="never"` claims the first tap on any sheet control
+  (`Footer` included) while a sheet field is focused and blurs the field instead
+  of firing the control. Set `keyboardShouldPersistTaps="always"` (or
+  `"handled"`) on scroll views that contain a sheet, or use `DismissKeyboard`,
+  which already does; the sheet warns once in development on Android when it
+  observes such a swallowed tap. Android has only two snap states
+  (partial / expanded) and maps extra snap points to the nearest; because
+  Material ignores percentage snap points, the Android body fills the rendered
+  sheet height rather than a window-percentage cap. `BottomSheet.Content` also
+  takes `backgroundStyle`, merged over the themed card default on the native
+  sheet surface (web panel, Android `containerColor`, iOS
+  `presentationBackground`). That surface is the sheet's only background: the
+  content column paints no fill of its own, so a translucent card reads as one
+  layer from the grabber down (a second, column-level fill made the 16 pt
+  strip behind the iOS grabber a different shade), and
+  `{ backgroundColor: "transparent" }` alone lets custom chrome such as a glass
+  backdrop show through.
+- `Dialog` and `AlertDialog` present their content through React Native's
+  `Modal` on iOS, rendered inline where the dialog sits in the tree
+  (transparent, `overFullScreen`, no animation of its own; the package's fade
+  and scale still run inside). The Modal presents a real view controller, which
+  `@expo/ui`-hosted controls need: `expo-modules-core`'s SwiftUI hosting view
+  drops its content when no `UIViewController` sits above it, so inside
+  react-native-screens' `FullWindowOverlay` — which adds its container straight
+  to the window — a package `TextInput`, `Slider` or `SegmentedControl`
+  rendered as an empty box that could not take focus (device-verified on
+  iOS 27). RN presents a `Modal` from the view controller nearest its host
+  view, so the dialog stacks above whatever screen, native stack modal or sheet
+  contains it (device-verified over a `presentation: "modal"` route);
+  `portalHost` is honored on Android and web only. `Drawer`, `Popover`,
+  `Select`, `DropdownMenu` and `Tooltip` still use that overlay on iOS, so do
+  not put `@expo/ui`-hosted controls inside them yet, and do not place a
+  `Dialog` inside their content either — it has no view controller to present
+  from there; render it at screen level and open it from the item's
+  `onPress`. The iOS Modal is outside `UIProvider`'s root
+  keyboard avoidance, so the dialog owns it there: the centered container is a
+  package `KeyboardAvoidingView` (`behavior="padding"`), the card recenters
+  above the keyboard with its fields and footer visible, and
+  `useKeyboardAvoidance()` is `true` inside dialog content. Do not wrap dialog
+  content in another `KeyboardAvoidingView`. The platform close request
+  (hardware back, TV menu) routes to the root's `onOpenChange(false)`. Android
+  and web render dialog content inline into the portal host, which sits
+  outside the root avoidance, so an Android dialog does not avoid the keyboard
+  yet.
 - `Carousel` renders every child (no virtualization), so slides survive into
   the exported HTML shell and the first client frame; use `FlatList` for large
   or unbounded data. An `itemWidth` below 1 (default `0.85`) is a fraction of

package/dist/components/BottomSheet.d.ts

@@ -10,8 +10,28 @@ import { ViewProps, StyleProp, ViewStyle, ScrollViewProps } from "react-native";
  *
  * The compound surface (Trigger / Content / Handle / Header / Body / Footer /
  * Close), controlled + uncontrolled state, and theming match a hand-rolled
- * sheet, but the platform owns gestures and keyboard avoidance — so there's no
- * PanResponder, snap-physics, or keyboard lift-and-shrink code to maintain.
+ * sheet, but the platform owns gestures — so there's no PanResponder or
+ * snap-physics code to maintain. Keyboard avoidance is the platform's too.
+ * iOS (device-verified, iOS 27 / `@expo/ui` 58): UIKit's sheet presentation
+ * keeps the hosted RN column above the keyboard by itself — a short sheet is
+ * lifted whole, a tall one is shrunk — so the column's bottom edge lands at the
+ * keyboard's top and `Footer` / the tail of `Body` stay reachable with only
+ * their own home-indicator padding as clearance. The package adds no inset:
+ * nothing in JS can measure the column in screen space (`measureInWindow`
+ * inside the `layoutRoot` sheet host reports host-relative coordinates), and a
+ * window-height estimate would lift a lifted sheet twice. Android: Material3's
+ * `ModalBottomSheet` shrinks the sheet with `imePadding()`, `@expo/ui`'s
+ * `RNHostView` re-reports its Compose size to the shadow tree, and the
+ * `flexGrow: 1, height: 0` column the host wraps our children in follows, so
+ * `Footer` and the tail of `Body` stay above the keyboard. That report is
+ * delivered reliably only by `expo-modules-core` >= 57.0.4 (expo/expo#47778,
+ * fixed by #47810): older cores flushed it from a pre-draw listener on the
+ * activity window, which does not draw while the sheet's dialog window animates
+ * the IME, so the column kept its detent height until the activity redrew. The
+ * package warns once in dev on Android below that floor
+ * (`bottomSheetHostSupport.ts`). No JS keyboard signal exists inside the
+ * Compose dialog window, and none is needed. Web: none. Never nest a
+ * `KeyboardAvoidingView` in a sheet.
  *
  * Platform-owned behaviors (props accepted for ergonomics, but the platform
  * decides):
@@ -24,6 +44,22 @@ import { ViewProps, StyleProp, ViewStyle, ScrollViewProps } from "react-native";
  *     platform's on native; theming reaches the content + background color.
  *   - On Android only two snap states exist (partial / expanded); extra snap
  *     points map to the nearest of those two.
+ *   - `Body` sets `keyboardShouldPersistTaps="always"` on its ScrollView so RN's
+ *     own tap-dismissal never claims the first tap on a chip, button or field
+ *     while a sheet field is focused; the `Content` boundary owns tap-away
+ *     dismissal instead. That covers ScrollViews *inside* the sheet only. The
+ *     sheet's content is drawn in another native window but stays in the
+ *     screen's React tree, and RN's responder negotiation walks that tree, so a
+ *     ScrollView *around* the `BottomSheet` with the default
+ *     `keyboardShouldPersistTaps="never"` claims a tap on any sheet control
+ *     (`Footer` included) in the capture phase once a field is focused and
+ *     blurs the field on release: the keyboard closes and the control never
+ *     fires (Pixel_10 / API 36: 0 of 3 taps inside a default ScrollView, 3 of 3
+ *     inside `always` or a plain View). Nothing inside the tree can preempt a
+ *     capture-phase claim, so `Content` warns once in dev on Android when it
+ *     observes one (`useAncestorClaimWarning`); the remedy is
+ *     `keyboardShouldPersistTaps="always"` / `"handled"` on scroll views that
+ *     contain a sheet, or `DismissKeyboard`, which already sets it.
  *
  * Scrollable bodies: the native sheet doesn't bound the hosted RN content to
  * the detent height, so a tall `Body` overflows and clips its footer/tail. When
@@ -113,16 +149,23 @@ interface BottomSheetTriggerProps {
 interface BottomSheetContentProps extends ViewProps {
     /** Accepted for call-site ergonomics; ignored (platform owns gestures). */
     swipeEnabled?: boolean;
-    /** Accepted for call-site ergonomics; ignored (platform owns keyboard avoidance). */
+    /**
+     * Accepted for call-site ergonomics; ignored (platform owns keyboard
+     * avoidance). iOS: UIKit's sheet presentation lifts or shrinks the hosted
+     * content so its bottom edge sits at the keyboard's top (device-verified).
+     * Android: Material3's `ModalBottomSheet`. Web: none. `false` has no effect;
+     * do not wrap sheet content in another `KeyboardAvoidingView`.
+     */
     avoidKeyboard?: boolean;
     /** Accepted for call-site ergonomics; ignored (platform owns keyboard). */
     dismissKeyboardOnDrag?: boolean;
     /**
-     * Style for the native sheet surface behind the RN content — the web (vaul)
-     * panel, Android `containerColor`, iOS `presentationBackground`. Merged over
-     * the themed card default, so `{ backgroundColor: "transparent" }` lets a
-     * custom chrome (e.g. a glass backdrop) show through. The RN content column
-     * paints its own card fill too; clear that via `style`.
+     * Style for the native sheet surface — the web (vaul) panel, Android
+     * `containerColor`, iOS `presentationBackground`. Merged over the themed card
+     * default. This is the sheet's only background: the RN content column paints
+     * no fill of its own, so a translucent color here reads as one layer from the
+     * grabber down, and `{ backgroundColor: "transparent" }` lets custom chrome
+     * (e.g. a glass backdrop) show through with nothing to clear via `style`.
      */
     backgroundStyle?: StyleProp<ViewStyle>;
     style?: StyleProp<ViewStyle>;
@@ -145,6 +188,12 @@ interface BottomSheetCloseProps {
     children: React.ReactNode;
     style?: StyleProp<ViewStyle>;
 }
+/**
+ * Dev warning (Android) when an ancestor claimed a tap inside the sheet before
+ * the sheet was asked, while a package field held focus. See the header and
+ * `useAncestorClaimWarning`.
+ */
+export declare const bottomSheetAncestorClaimWarning: string;
 declare function useBottomSheetContext(): BottomSheetContextValue;
 declare function BottomSheetRoot({ open: controlledOpen, onOpenChange: controlledOnOpenChange, defaultOpen, snapPoints, closeOnBackdropPress, children, }: BottomSheetProps): React.JSX.Element;
 declare function BottomSheetTrigger({ asChild, children, style: styleOverride }: BottomSheetTriggerProps): React.JSX.Element;

package/dist/components/BottomSheet.js

@@ -8,7 +8,8 @@ import { spacing } from "../constants/spacing.js";
 import { useScalePress } from "../hooks/useScalePress.js";
 import { TextColorContext, TextClassContext } from "./StyledText.context";
 import { Icon } from "./Icon.js";
-import { useKeyboardDismissResponder } from "./keyboardDismiss.js";
+import { useAncestorClaimWarning, useKeyboardDismissResponder } from "./keyboardDismiss.js";
+import { warnIfBottomSheetHostDropsResize } from "./bottomSheetHostSupport.js";
 const DEFAULT_SNAP_POINTS = ["50%"];
 function clampSnapIndex(index, maxSnapIndex) {
     return Math.min(Math.max(index, 0), maxSnapIndex);
@@ -86,6 +87,18 @@ function bottomSheetRootReducer(state, action) {
 // ============================================================================
 // Context
 // ============================================================================
+/**
+ * Dev warning (Android) when an ancestor claimed a tap inside the sheet before
+ * the sheet was asked, while a package field held focus. See the header and
+ * `useAncestorClaimWarning`.
+ */
+export const bottomSheetAncestorClaimWarning = "@mrmeg/expo-ui BottomSheet: an ancestor claimed a tap inside the sheet before the sheet " +
+    "was asked, while a sheet field was focused, so the tapped control did not fire and the " +
+    "keyboard was dismissed instead. That is usually a ScrollView around the BottomSheet on React " +
+    'Native\'s default keyboardShouldPersistTaps="never" (sheet content stays in the screen\'s ' +
+    "React tree even though it is drawn in another window). Set " +
+    'keyboardShouldPersistTaps="always" or "handled" on scroll views that contain the ' +
+    "BottomSheet, or wrap the screen in DismissKeyboard.";
 const BottomSheetContext = createContext(null);
 function useBottomSheetContext() {
     const context = use(BottomSheetContext);
@@ -272,6 +285,15 @@ swipeEnabled: _swipeEnabled, avoidKeyboard: _avoidKeyboard, dismissKeyboardOnDra
     // dead-space tap dismisses on release only, through the registered field's
     // own window-independent blur handle.
     const dismissResponderProps = useKeyboardDismissResponder();
+    // Android, dev, once per session: name an ancestor ScrollView that claimed a
+    // tap inside the sheet in the capture phase (nothing in here can preempt it).
+    const columnResponderProps = useAncestorClaimWarning(dismissResponderProps, bottomSheetAncestorClaimWarning);
+    // Android only, dev only, once per session: name the host floor the column's
+    // keyboard avoidance depends on when the app was built against an
+    // `expo-modules-core` that drops `RNHostView`'s size update (see the header).
+    useEffect(() => {
+        warnIfBottomSheetHostDropsResize();
+    }, []);
     // Boolean open → native imperative index. The root resets snapIndex to the
     // highest point while closed; -1 keeps the native sheet closed.
     const index = open ? snapIndex : -1;
@@ -287,7 +309,11 @@ swipeEnabled: _swipeEnabled, avoidKeyboard: _avoidKeyboard, dismissKeyboardOnDra
     // and Material's `ModalBottomSheet` ignores percentage snap points
     // (partial / expanded only) — a window-percentage cap would leave the Body
     // short of the rendered sheet with a blank strip below it. Android therefore
-    // keeps `flex:1` alone (see the content column style).
+    // keeps `flex:1` alone (see the content column style). The same measured
+    // height is how the column follows the keyboard: Material shrinks the sheet
+    // with `imePadding()` and `RNHostView` re-reports its Compose size to the
+    // shadow tree, which needs `expo-modules-core` >= 57.0.4 to always land
+    // (expo/expo#47778) — see `warnIfBottomSheetHostDropsResize` above.
     const expandedSnap = snapPoints[snapPoints.length - 1];
     const detentHeight = typeof expandedSnap === "number"
         ? expandedSnap
@@ -321,15 +347,16 @@ swipeEnabled: _swipeEnabled, avoidKeyboard: _avoidKeyboard, dismissKeyboardOnDra
             { backgroundColor: theme.colors.card },
             backgroundStyleOverride,
         ]), children: _jsx(TextColorContext.Provider, { value: theme.colors.foreground, children: _jsx(TextClassContext.Provider, { value: "", children: _jsxs(View, { testID: testID, style: [
-                        {
-                            flex: 1,
-                            // Themes the content surface across all platforms regardless of
-                            // native sheet chrome.
-                            backgroundColor: theme.colors.card,
-                        },
+                        // No fill of its own: the native surface (`backgroundStyle`) is
+                        // the sheet's only background. On iOS the hosted column starts
+                        // 16 pt below the sheet's top edge when the native grabber is
+                        // shown, so a second, column-level fill made a translucent card
+                        // read as two layers below that line and one above it — a
+                        // differently colored strip behind the grabber.
+                        { flex: 1 },
                         Platform.OS !== "android" && { maxHeight: detentHeight },
                         styleOverride,
-                    ], ...dismissResponderProps, children: [children, showFloatingClose && (_jsx(SheetCloseButton, { style: {
+                    ], ...columnResponderProps, children: [children, showFloatingClose && (_jsx(SheetCloseButton, { style: {
                                 // The sheet card sits below the status bar, so no top inset
                                 // is needed — just clear the sheet's own top edge / handle.
                                 position: "absolute",
@@ -435,7 +462,15 @@ function BottomSheetBody({ children, style, contentContainerStyle, onContentSize
                 paddingBottom: spacing.md + (hasFooter ? 0 : insets.bottom),
             },
             contentContainerStyle,
-        ], showsVerticalScrollIndicator: false, onLayout: (e) => {
+        ], 
+        // The `Content` column's keyboard-dismiss boundary owns tap-away
+        // dismissal (see DismissKeyboard). RN's default `never` claims the first
+        // tap on any non-input child while a registered field is focused and
+        // blurs it on release; `handled` can still blur independently after a
+        // non-scrolling drag. `always` leaves every tap to its target and lets
+        // dead-space taps bubble to the boundary. Placed before `{...props}` so an
+        // explicit consumer value still wins.
+        keyboardShouldPersistTaps: "always", showsVerticalScrollIndicator: false, onLayout: (e) => {
             viewportH.current = e.nativeEvent.layout.height;
             evaluate();
             onLayout?.(e);

package/dist/components/Button.js

@@ -11,6 +11,7 @@ import { useFontStyle } from "../hooks/useFontStyle.js";
 import { useScalePress } from "../hooks/useScalePress.js";
 import { useThemeStore } from "../state/themeStore.js";
 import { createThemedStyles } from "../lib/themedStyles.js";
+import { stateSurfaceProps } from "../lib/stateSurface.js";
 const SIZE_CONFIGS = {
     sm: {
         paddingVertical: spacing.xxs,
@@ -181,7 +182,10 @@ function ButtonRoot(props) {
             return nextWidth;
         });
     }, [fullWidth, loading]);
-    return (_jsx(TextColorContext.Provider, { value: textColor, children: _jsx(TextSelectabilityContext.Provider, { value: false, children: _jsx(TextStyleContext.Provider, { value: labelTextStyle, children: _jsx(Pressable, { accessibilityRole: "button", accessibilityState: { disabled: !!isDisabled, busy: loading }, ...rest, onPressIn: handlePressIn, onPressOut: handlePressOut, onFocus: showFocusRing, onBlur: hideFocusRing, style: { alignSelf: fullWidth ? "stretch" : flattenedStyle?.alignSelf ?? "flex-start" }, hitSlop: rest.hitSlop ?? (Platform.OS === "web" ? undefined : getNativeHitSlop(sizeConfig)), disabled: isDisabled, children: (state) => (_jsx(Animated.View, { style: scaleStyle, children: _jsxs(View, { style: [
+    return (_jsx(TextColorContext.Provider, { value: textColor, children: _jsx(TextSelectabilityContext.Provider, { value: false, children: _jsx(TextStyleContext.Provider, { value: labelTextStyle, children: _jsx(Pressable, { accessibilityRole: "button", accessibilityState: { disabled: !!isDisabled, busy: loading }, ...rest, onPressIn: handlePressIn, onPressOut: handlePressOut, onFocus: showFocusRing, onBlur: hideFocusRing, style: { alignSelf: fullWidth ? "stretch" : flattenedStyle?.alignSelf ?? "flex-start" }, hitSlop: rest.hitSlop ?? (Platform.OS === "web" ? undefined : getNativeHitSlop(sizeConfig)), disabled: isDisabled, children: (state) => (_jsx(Animated.View, { style: scaleStyle, children: _jsxs(View
+                        // Android: fixed native tree across disabled/pressed/loading
+                        // flips (see `stateSurfaceProps`).
+                        , { ...stateSurfaceProps(), style: [
                                 styles.button,
                                 // Host-app radius override (see `setShape`). Sits right
                                 // after the static radius so presets, state styles, and —
@@ -205,7 +209,7 @@ function ButtonRoot(props) {
                                 loading && restingWidth !== undefined && !fullWidth && { width: restingWidth },
                                 // Spread array styles from Slot to prevent nested arrays on web
                                 ...(Array.isArray(styleOverride) ? styleOverride : [styleOverride]),
-                            ], onLayout: handleButtonLayout, children: [loading && (_jsx(View, { style: [styles.loaderOverlay, { pointerEvents: "none" }], children: _jsx(ActivityIndicator, { size: "small", color: textColor }) })), _jsxs(View, { style: [styles.content, loading && styles.loadingContent, { pointerEvents: loading ? "none" : "auto" }], children: [!!LeftAccessory && (_jsx(LeftAccessory, { style: styles.leftAccessory, pressableState: state, disabled: isDisabled })), (tx || text) ? (_jsx(StyledText, { tx: tx, text: text, txOptions: txOptions, style: [
+                            ], onLayout: handleButtonLayout, children: [loading && (_jsx(View, { style: [styles.loaderOverlay, { pointerEvents: "none" }], children: _jsx(ActivityIndicator, { size: "small", color: textColor }) })), _jsxs(View, { ...stateSurfaceProps(), style: [styles.content, loading && styles.loadingContent, { pointerEvents: loading ? "none" : "auto" }], children: [!!LeftAccessory && (_jsx(LeftAccessory, { style: styles.leftAccessory, pressableState: state, disabled: isDisabled })), (tx || text) ? (_jsx(StyledText, { tx: tx, text: text, txOptions: txOptions, style: [
                                                 labelTextStyle,
                                                 state.pressed && styles.pressedText,
                                                 state.pressed && pressedTextStyleOverride,