@mrmeg/expo-ui 0.25.1 → 0.27.0

package/CHANGELOG.md

@@ -5,6 +5,146 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [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
+
+- **`Icon` renders Lucide.** `<Icon name>` draws `lucide-react-native` SVGs
+  instead of the `@expo/vector-icons` Feather font. Lucide is a maintained
+  superset of Feather in the same 24px, 2px round-stroke style, so glyphs look
+  the same, but the set is ten times larger and nothing is loaded as a font.
+  `IconName` is now the union of kebab-case Lucide names in the package
+  registry (`src/components/icon-names.json`, generated into
+  `iconRegistry.generated.ts` by `bun run ui:icons`); only those icons ship in
+  the bundle. The `component` escape hatch is unchanged and accepts any
+  `LucideIcon` (`CustomIconComponentProps.style` is a view style). Names Lucide
+  renamed, which consumers must update: `alert-circle` → `circle-alert`,
+  `check-circle` → `circle-check-big`, `x-circle` → `circle-x`,
+  `alert-triangle` → `triangle-alert`, `help-circle` → `circle-question-mark`,
+  `edit` → `square-pen`, `edit-2` → `pen`, `edit-3` → `pencil`,
+  `sliders` → `sliders-horizontal`, `grid` → `layout-grid`, `home` → `house`,
+  `unlock` → `lock-open`, `trash-2` → `trash`, `tool` → `wrench`,
+  `layout` → `panels-top-left`, `bar-chart-2` → `chart-no-axes-column`,
+  `plus-circle` → `circle-plus`, `stop-circle` → `circle-stop`,
+  `more-vertical` → `ellipsis-vertical`, `more-horizontal` → `ellipsis`,
+  `sidebar` → `panel-left`, `smile` → `face-slightly-smiling`. Brand glyphs
+  (`github`, `chrome`, `facebook`, `instagram`, `linkedin`, `twitter`) have
+  no Lucide equivalent; pass your own SVG through `component`. Every other
+  Feather name resolves unchanged. A name outside the registry is a type error.
+
+### Removed
+
+- **`@expo/vector-icons` is no longer a dependency**, and `useResources` no
+  longer loads or registers an icon font. `ensureIconFontRegistered` is gone:
+  SVG icons render in export-time HTML as `<svg>`, so the hydration fix it
+  existed for has nothing left to fix.
+
+### Added
+
+- **Peers `lucide-react-native` (`>=1.46 <2`) and `react-native-svg`
+  (`>=15 <16`).** Install `react-native-svg` with `npx expo install` so it
+  matches your SDK. They are peers, not dependencies, so an app that imports
+  Lucide components for `<Icon component>` shares one copy.
+- **`icons.names` in `dist/design-system.json`**, the registry's name list, so
+  `@mrmeg/eslint-plugin-expo-ui` can validate icon names against an installed
+  release (a lint rule is a follow-up). `schemaVersion` stays `1`.
+
+### Fixed
+
+- **Popover, DropdownMenu, Select, and Tooltip content receives Android
+  touches.** The fade wrapper between each overlay and its absolutely
+  positioned content now fills the overlay with `pointerEvents="box-none"`, so
+  the card is inside its parent's bounds. Android dispatches `ACTION_DOWN` and
+  accessibility traversal only to children inside their parent's bounds, so
+  native controls (`Switch`, `TextInput`) inside a `PopoverContent` ignored
+  taps and the content was missing from the accessibility tree. Tap-away still
+  closes.
+- **Sheet taps reach controls while the keyboard is up.** `BottomSheet.Content`
+  no longer mounts an absolute-fill "Dismiss keyboard" overlay that swallowed
+  the first tap on every button, tab and field inside the sheet. It spreads the
+  same release-based tap-away boundary `DismissKeyboard` uses onto its content
+  column: the boundary never claims the touch, an unclaimed dead-space tap
+  dismisses on release only, drags and multitouch do not dismiss, and presence
+  still comes from the focus registry so it works in the sheet's isolated
+  native window.
+- **`dismissKeyboard()` clears the focus registry immediately.**
+  `dismissKeyboardFocusedInput()` blurs the registered field and drops its
+  registration in the same call instead of waiting for a native blur callback
+  that may never arrive (submit handlers, isolated sheet window, iOS
+  secure/plain handoff), so no stale focus presence survives a dismissal. A
+  field that takes focus during the blur keeps its registration.
+- **Android sheet bodies fill the rendered sheet.** The content column's
+  `maxHeight` cap (last snap point as a window percentage) now applies only
+  off Android, where the iOS SwiftUI host needs it; Material's
+  `ModalBottomSheet` ignores percentage snap points and its host already bounds
+  the column, so a `55%` sheet no longer shows a blank strip below a capped
+  `BottomSheet.Body`.
+- **Android secure fields declare a password keyboard.** `TextInput` with
+  `secureTextEntry` now reports `textPassword` to the IME (or `numberPassword`
+  for the `number-pad`, `decimal-pad`, `numeric` and `phone-pad` keyboards), so
+  Gboard shows no suggestion strip and learns nothing typed; autocorrect is off
+  and capitalization is `none` unless the props say otherwise. Revealing the
+  text with the eye toggle keeps the password keyboard and only drops the
+  masking, so focus, selection and the input connection survive exactly as in
+  0.25.1. The Android field is now package-owned — a port of `@expo/ui` 58.0.2's
+  universal Android `TextInput` on top of `@expo/ui/jetpack-compose`'s
+  `BasicTextField` — because the universal field offers no way to set Compose's
+  password keyboard type. iOS keeps `@expo/ui`'s universal field.
+
 ## [0.25.1]
 
 ### Fixed

package/LLM_USAGE.md

@@ -85,7 +85,13 @@ 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);
+Android avoidance is Material3's; 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`. `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
@@ -228,7 +234,7 @@ Check this before creating a new app-local primitive. All components come from
 | `DropdownMenu` | Menus and command lists | Homemade popover menus |
 | `EmptyState` | No-data or recoverable error regions | One-off empty placeholders |
 | `ErrorBoundary` | React render error fallback | Unhandled screen crashes |
-| `Icon` | Feather or custom icons with theme tokens | Raw vector icons with hardcoded colors |
+| `Icon` | Lucide or custom icons with theme tokens | Raw vector icons with hardcoded colors |
 | `InputOTP` | Verification code entry | Several manually managed text inputs |
 | `Item`, `ItemMedia`, `ItemContent`, `ItemTitle`, `ItemDescription`, `ItemActions` | List / settings rows with density tokens | Hand-rolled row `View`s |
 | `KeyboardAvoidingView` | Native keyboard-aware layout root | Repeated app-local keyboard wrappers |
@@ -258,14 +264,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 +282,7 @@ 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.
+- `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

@@ -32,6 +32,9 @@ Web 0.21. Install these peers at the versions your Expo SDK recommends: `expo`,
 `react-native-web`, `react-native-gesture-handler`,
 `react-native-keyboard-controller`, `react-native-safe-area-context`,
 `react-native-screens`, `@react-native-async-storage/async-storage`, `zustand`.
+`Icon` renders [Lucide](https://lucide.dev/icons) SVGs, so also install its two
+peers: `npx expo install react-native-svg` (a native module, pinned by your
+SDK) and `bun add lucide-react-native` (`>=1.46 <2`).
 
 `@rn-primitives/*` and `@expo-google-fonts/inter` are package dependencies, not
 peers. Animations use React Native `Animated`. `BottomSheet`, `Slider`, and
@@ -311,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,
@@ -343,9 +351,10 @@ Inter is the sans face on every platform, in four static weights
 from the bundled `@expo-google-fonts/inter`. Serif is Georgia; mono is the
 platform system monospace.
 
-`useResources()` loads those four weights plus `Feather.font` (from the
-package-managed `@expo/vector-icons`) on native, so `StyledText`'s
-`light`–`bold` range resolves to real files instead of a faked OS bold. On web
+`useResources()` loads those four weights on native, so `StyledText`'s
+`light`–`bold` range resolves to real files instead of a faked OS bold. Icons
+are SVG (`lucide-react-native`), so there is no icon font to load on any
+platform. On web
 it injects one Google Fonts Inter stylesheet (all four weights) after hydration
 unless the app already added it; web weight differentiation then comes from a
 numeric `fontWeight` on the shared `"Inter"` family. For better first paint in
@@ -391,7 +400,7 @@ When `sansSerif` is overridden, `useResources` skips downloading the packaged
 Inter faces entirely (native `.ttf`s and the web stylesheet). For the skip to
 apply, call `setFonts` before the hook mounts (module scope, or ahead of
 rendering the root); a later call still re-skins all text, it just doesn't
-prevent the download. Feather always loads.
+prevent the download.
 
 | `webWeightStrategy` | Use when | Effect |
 |---|---|---|
@@ -432,7 +441,7 @@ building a new primitive.
 | `DropdownMenu` | Menus and command lists | Row actions, account menu, sort menu, checkbox/radio groups |
 | `EmptyState` | No-data or recoverable error regions | Empty inbox, no results, failed list load |
 | `ErrorBoundary` | React render error fallback | Route-level and feature-level fallbacks |
-| `Icon` | Feather or custom icons on theme tokens | Button accessories, menu icons, status glyphs |
+| `Icon` | Lucide or custom icons on theme tokens | Button accessories, menu icons, status glyphs |
 | `InputOTP` | Verification code entry | Email/SMS codes, MFA, invite codes |
 | `Item` | List and settings rows on the density tokens | Settings lists, inbox rows, pickers, detail rows |
 | `KeyboardAvoidingView` | Native keyboard-aware layout | Screen roots, composer footers, form-heavy subtrees |
@@ -458,6 +467,43 @@ building a new primitive.
 | `ToggleGroup` | Single or multi toggle groups | Alignment, formatting toolbar, filter chips |
 | `Tooltip` | Short hover/focus help | Icon button labels, field hints, disabled-action reasons |
 
+### Icons
+
+`Icon` renders `lucide-react-native` — Lucide is a maintained superset of
+Feather in the same 24px, 2px round-stroke style. `name` is typed by
+`IconName`, the union of kebab-case Lucide names in the package registry
+(`src/components/icon-names.json`, about 150 names), so only the icons the package
+and its consumers name ship in the bundle: the root `lucide-react-native`
+entry (1,800+ icons) is never imported. `color` takes a theme color name or a
+literal; `decorative` hides the glyph from assistive tech.
+
+```tsx
+import { Icon } from "@mrmeg/expo-ui/components";
+import Rocket from "lucide-react-native/icons/rocket";
+
+<Icon name="circle-check-big" color="success" size={16} />
+<Icon component={Rocket} color="accent" />
+```
+
+Adding an icon: in this repo, add the kebab-case Lucide name to
+`packages/ui/src/components/icon-names.json` (keep it sorted), run
+`bun run ui:icons`, and commit both files — an unknown name fails with the
+alias lines from Lucide's root entry that point at its current name
+(`bun run ui:icons:check` guards freshness in CI). From a consuming app, pass
+any Lucide component through `component` instead; it needs no registry entry.
+Feather-era names that Lucide renamed: `alert-circle` → `circle-alert`,
+`check-circle` → `circle-check-big`, `x-circle` → `circle-x`,
+`alert-triangle` → `triangle-alert`, `help-circle` → `circle-question-mark`,
+`edit` → `square-pen`, `edit-2` → `pen`, `edit-3` → `pencil`,
+`sliders` → `sliders-horizontal`, `grid` → `layout-grid`, `home` → `house`,
+`unlock` → `lock-open`, `trash-2` → `trash`, `tool` → `wrench`,
+`layout` → `panels-top-left`, `bar-chart-2` → `chart-no-axes-column`,
+`plus-circle` → `circle-plus`, `stop-circle` → `circle-stop`,
+`more-vertical` → `ellipsis-vertical`, `more-horizontal` → `ellipsis`,
+`sidebar` → `panel-left`, `smile` → `face-slightly-smiling`. Brand glyphs
+(`github`, `chrome`, `facebook`, `instagram`, `linkedin`, `twitter`) have no
+Lucide equivalent; use `component` with your own SVG.
+
 ### Compound Parts
 
 | Root | Exported Parts |
@@ -492,7 +538,7 @@ are named exports only.
 
 | Hook | Returns |
 |------|---------|
-| `useResources()` | `{ loaded, error }` — loads Feather plus the Inter faces |
+| `useResources()` | `{ loaded, error }` — loads the Inter faces (icons are SVG, nothing to load) |
 | `useTheme()` | Active theme, scheme helpers, shadow/contrast/alpha helpers |
 | `useStyles(factory)` | Memoized theme-aware styles plus the `useTheme()` helpers |
 | `useDimensions()` | `{ width, height, orientation, isSmallScreen, isMediumScreen, isLargeScreen }` against `SCREEN_SIZES` (768 / 1000 / 1200) |
@@ -518,19 +564,43 @@ web, where the window cannot be read during export or hydration.
   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.
+- `TextInput` renders a native field on iOS and Android. On Android a
+  `secureTextEntry` field declares a password keyboard (`textPassword`, or
+  `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`). 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; `BottomSheet.Content` does mount its own
-  tap-away keyboard-dismiss overlay while a field is focused. Android has only
-  two snap states (partial / expanded) and maps extra snap points to the
-  nearest. `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.
+  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` owns it (no JS
+  keyboard signal exists inside the Compose dialog window); 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`. `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. 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.
 - `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
@@ -691,8 +761,9 @@ packed package at the workspace's Expo version, without a custom Metro config.
 `ui:build` also writes `dist/design-system.json`
 ([`scripts/build-design-system-manifest.mjs`](../../scripts/build-design-system-manifest.mjs)):
 the spacing, radius and icon scales, the palette, the light and dark themes, the
-font variants, and every component's variant and size values, serialized out of
-`src` by the same extractor the lint rules use. It is exported as
+font variants, every component's variant and size values, and `icons.names` (the
+`IconName` registry), serialized out of `src` by the same extractor the lint
+rules use. It is exported as
 `@mrmeg/expo-ui/design-system.json`, and `@mrmeg/eslint-plugin-expo-ui` reads it
 in projects that install this package instead of checking out its sources — which
 is what lets the design-system rules quote this release's presets and tokens.

package/dist/components/Avatar.d.ts

@@ -26,7 +26,7 @@ export interface AvatarProps {
     source?: ImageSourcePropType;
     /** Display name; supplies the fallback initials and the default accessibility label. */
     name?: string;
-    /** Feather icon rendered when there is no image and no derivable initials. @default "user" */
+    /** Icon (Lucide name) rendered when there is no image and no derivable initials. @default "user" */
     icon?: IconName;
     /** Size token or explicit pixel diameter. Inherited from `AvatarGroup` when unset. @default "md" */
     size?: AvatarSize;

package/dist/components/BottomSheet.d.ts

@@ -10,8 +10,18 @@ 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` owns it (no JS keyboard signal exists inside the Compose
+ * dialog window). Web: none. Never nest a `KeyboardAvoidingView` in a sheet.
  *
  * Platform-owned behaviors (props accepted for ergonomics, but the platform
  * decides):
@@ -24,6 +34,10 @@ 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.
  *
  * 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,7 +127,13 @@ 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;
@@ -148,7 +168,7 @@ interface BottomSheetCloseProps {
 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;
-declare function BottomSheetContent({ swipeEnabled: _swipeEnabled, avoidKeyboard: _avoidKeyboard, dismissKeyboardOnDrag: _dismissKeyboardOnDrag, backgroundStyle: backgroundStyleOverride, style: styleOverride, children, }: BottomSheetContentProps): React.JSX.Element;
+declare function BottomSheetContent({ swipeEnabled: _swipeEnabled, avoidKeyboard: _avoidKeyboard, dismissKeyboardOnDrag: _dismissKeyboardOnDrag, backgroundStyle: backgroundStyleOverride, style: styleOverride, testID, children, }: BottomSheetContentProps): React.JSX.Element;
 declare function BottomSheetHandle({ style }: BottomSheetHandleProps): React.JSX.Element;
 declare function BottomSheetHeader({ children, style, ...props }: BottomSheetHeaderProps): React.JSX.Element;
 declare function BottomSheetBody({ children, style, contentContainerStyle, onContentSizeChange, onLayout, ...props }: BottomSheetBodyProps): React.JSX.Element;

package/dist/components/BottomSheet.js

@@ -1,15 +1,14 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import React, { createContext, use, useCallback, useEffect, useMemo, useReducer, useRef, useSyncExternalStore } from "react";
+import React, { createContext, use, useCallback, useEffect, useMemo, useReducer, useRef } from "react";
 import { View, Pressable, StyleSheet, ScrollView, Platform, Animated, useWindowDimensions, } from "react-native";
 import { BottomSheet as NativeBottomSheet } from "@expo/ui/community/bottom-sheet";
-import { KeyboardController } from "./keyboardController";
 import { useSafeAreaInsets, initialWindowMetrics } from "react-native-safe-area-context";
 import { useTheme } from "../hooks/useTheme.js";
 import { spacing } from "../constants/spacing.js";
 import { useScalePress } from "../hooks/useScalePress.js";
 import { TextColorContext, TextClassContext } from "./StyledText.context";
 import { Icon } from "./Icon.js";
-import { dismissKeyboardFocusedInput, hasKeyboardFocusedInput, subscribeKeyboardFocus, } from "./keyboardFocusRegistry.js";
+import { useKeyboardDismissResponder } from "./keyboardDismiss.js";
 const DEFAULT_SNAP_POINTS = ["50%"];
 function clampSnapIndex(index, maxSnapIndex) {
     return Math.min(Math.max(index, 0), maxSnapIndex);
@@ -162,48 +161,6 @@ function SheetCloseButton({ style }) {
             ], children: _jsx(Icon, { name: "x", size: 22, color: "text" }) }) }));
 }
 // ============================================================================
-// Keyboard dismiss overlay — tap-away dismissal inside the sheet
-// ============================================================================
-/**
- * Tap-away keyboard dismissal for sheet content.
- *
- * The native sheet (SwiftUI `.sheet()` / Material `ModalBottomSheet`) hosts its
- * RN children in a separate native window via @expo/ui's `RNHostView`, OUTSIDE
- * the app's `KeyboardProvider` / `KeyboardDismissBoundary`. Two consequences,
- * both worked around here:
- *
- *  1. Detection: `react-native-keyboard-controller`'s `useKeyboardState` watches
- *     the main window and does NOT see a keyboard raised inside the sheet's
- *     window (the same isolation that makes `useSafeAreaInsets()` read zero in
- *     here). So presence is read from the `keyboardFocusRegistry` instead, which
- *     is fed by @expo/ui's own native focus events and is window-independent.
- *  2. Dispatch: RN's JS responder chain (onStartShouldSetResponder*) is NOT
- *     dispatched across the `RNHostView` boundary on Android — only `Pressable`
- *     hit-testing (native `measure()`) works inside the host. So this is a
- *     transparent `Pressable` mounted ONLY while a field is focused, mirroring
- *     a tap-to-dismiss overlay in the app. The tap blurs the focused field via
- *     its own native ref (`dismissKeyboardFocusedInput`), which resigns the
- *     responder regardless of window; `KeyboardController.dismiss()` is a
- *     best-effort fallback for the (rare) case with no registered blur handle.
- *
- * iOS doesn't strictly need this (SwiftUI resigns first-responder on outside
- * taps for free), but the same path is harmless and keeps behavior identical.
- */
-function SheetKeyboardDismissOverlay() {
-    const hasFocus = useSyncExternalStore(subscribeKeyboardFocus, hasKeyboardFocusedInput, () => false);
-    if (Platform.OS === "web" || !hasFocus)
-        return null;
-    return (_jsx(Pressable, { style: [StyleSheet.absoluteFill, styles.keyboardDismissOverlay], onPressIn: () => {
-            if (!dismissKeyboardFocusedInput())
-                KeyboardController.dismiss();
-        }, accessibilityLabel: "Dismiss keyboard", accessibilityRole: "button" }));
-}
-const styles = StyleSheet.create({
-    keyboardDismissOverlay: {
-        zIndex: 999,
-    },
-});
-// ============================================================================
 // Root
 // ============================================================================
 function BottomSheetRoot({ open: controlledOpen, onOpenChange: controlledOnOpenChange, defaultOpen = false, snapPoints = DEFAULT_SNAP_POINTS, closeOnBackdropPress = true, children, }) {
@@ -296,21 +253,41 @@ function BottomSheetTrigger({ asChild, children, style: styleOverride }) {
 // ============================================================================
 function BottomSheetContent({ 
 // Accepted-but-ignored ergonomics props (platform owns these behaviors):
-swipeEnabled: _swipeEnabled, avoidKeyboard: _avoidKeyboard, dismissKeyboardOnDrag: _dismissKeyboardOnDrag, backgroundStyle: backgroundStyleOverride, style: styleOverride, children, }) {
+swipeEnabled: _swipeEnabled, avoidKeyboard: _avoidKeyboard, dismissKeyboardOnDrag: _dismissKeyboardOnDrag, backgroundStyle: backgroundStyleOverride, style: styleOverride, testID, children, }) {
     const { open, onOpenChange, snapPoints, snapIndex, setSnapIndex, hasHeader } = useBottomSheetContext();
     const { theme } = useTheme();
     const dismissDisabled = useDismissDisabled();
     const showClose = useShowClose();
     const { height: winH } = useWindowDimensions();
+    // Tap-away keyboard dismissal inside the sheet. The native sheet (SwiftUI
+    // `.sheet()` / Material `ModalBottomSheet`) hosts its RN children in a separate
+    // native window via @expo/ui's `RNHostView`, OUTSIDE the app's
+    // `KeyboardProvider` / `DismissKeyboard`, so an app-level boundary never sees
+    // these touches and the sheet mounts its own on the content column. It is the
+    // same boundary `DismissKeyboard` uses: presence comes from the
+    // `keyboardFocusRegistry` (keyboard-controller's `useKeyboardState` watches
+    // the main window and does not observe a keyboard raised in here), the
+    // boundary never claims the touch — buttons, tabs and other fields win the
+    // responder negotiation and fire on the first tap — and an unclaimed
+    // dead-space tap dismisses on release only, through the registered field's
+    // own window-independent blur handle.
+    const dismissResponderProps = useKeyboardDismissResponder();
     // 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;
-    // The native RN-in-SwiftUI host does NOT clamp our RN column to the sheet's
+    // iOS: the RN-in-SwiftUI host does NOT clamp our RN column to the sheet's
     // detent height — it lays the column out at its full intrinsic content height,
     // SwiftUI then clips it at the sheet edge (footer/tail fall off-screen), and
     // `flex:1` never gets a definite parent height so the ScrollView can't bound
     // and scroll. Cap the column to the expanded detent height (highest snap
-    // point) so `flex:1` resolves and the Body becomes scrollable.
+    // point) so `flex:1` resolves and the Body becomes scrollable. Web (vaul)
+    // sizes the panel itself from the snap point, so the cap is inert there.
+    // Android: the Compose host wraps children in a `flexGrow: 1, height: 0` view
+    // that fills `RNHostView`'s measured height, so `flex:1` already resolves,
+    // 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).
     const expandedSnap = snapPoints[snapPoints.length - 1];
     const detentHeight = typeof expandedSnap === "number"
         ? expandedSnap
@@ -343,16 +320,16 @@ swipeEnabled: _swipeEnabled, avoidKeyboard: _avoidKeyboard, dismissKeyboardOnDra
         backgroundStyle: StyleSheet.flatten([
             { backgroundColor: theme.colors.card },
             backgroundStyleOverride,
-        ]), children: _jsx(TextColorContext.Provider, { value: theme.colors.foreground, children: _jsx(TextClassContext.Provider, { value: "", children: _jsxs(View, { style: [
+        ]), children: _jsx(TextColorContext.Provider, { value: theme.colors.foreground, children: _jsx(TextClassContext.Provider, { value: "", children: _jsxs(View, { testID: testID, style: [
                         {
                             flex: 1,
-                            maxHeight: detentHeight,
                             // Themes the content surface across all platforms regardless of
                             // native sheet chrome.
                             backgroundColor: theme.colors.card,
                         },
+                        Platform.OS !== "android" && { maxHeight: detentHeight },
                         styleOverride,
-                    ], children: [children, _jsx(SheetKeyboardDismissOverlay, {}), showFloatingClose && (_jsx(SheetCloseButton, { style: {
+                    ], ...dismissResponderProps, 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",
@@ -458,7 +435,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/DropdownMenu.js

@@ -76,7 +76,7 @@ function DropdownMenuContent({ side, align = "start", sideOffset = 4, portalHost
     return (_jsx(DropdownMenuPrimitive.Portal, { hostName: portalHost, children: _jsx(FullWindowOverlay, { children: _jsx(DropdownMenuPrimitive.Overlay, { style: Platform.select({
                     native: StyleSheet.absoluteFill,
                     default: undefined,
-                }), children: _jsx(AnimatedView, { type: "fade", children: _jsx(TextClassContext.Provider, { value: "", children: _jsx(TextSelectabilityContext.Provider, { value: false, children: _jsx(DropdownMenuPrimitive.Content, { side: side, align: align, sideOffset: sideOffset, insets: insets, avoidCollisions: true, ...props, style: {
+                }), children: _jsx(AnimatedView, { type: "fade", style: StyleSheet.absoluteFill, pointerEvents: "box-none", children: _jsx(TextClassContext.Provider, { value: "", children: _jsx(TextSelectabilityContext.Provider, { value: false, children: _jsx(DropdownMenuPrimitive.Content, { side: side, align: align, sideOffset: sideOffset, insets: insets, avoidCollisions: true, ...props, style: {
                                     backgroundColor: theme.colors.popover,
                                     borderWidth: 1,
                                     borderColor: theme.colors.border,