@mrmeg/expo-ui 0.26.0 → 0.27.0

package/CHANGELOG.md

@@ -5,6 +5,60 @@ 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

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

@@ -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,
@@ -564,25 +569,38 @@ 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` 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`. 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. 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

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;

package/dist/components/BottomSheet.js

@@ -435,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/StyledText.d.ts

@@ -74,8 +74,12 @@ export type TextProps = RNTextProps & {
  *   real Inter font files on native, and family + numeric fontWeight on web
  * - Per-size letter-spacing scale (tight on large headings, positive on micro
  *   labels); explicit `style` letterSpacing always wins
- * - Text selection enabled by default; pass `selectable={false}` for control
- *   chrome such as button labels, tabs, badges, and field labels
+ * - Text selection on by default on iOS and web, off by default on Android:
+ *   a selectable Android `Text` is focusable-in-touch-mode, so a tap on a label
+ *   next to a focused input moved view focus to the label and hid the keyboard.
+ *   Pass `selectable` to opt copyable content in (codes, addresses, chat
+ *   bubbles); pass `selectable={false}` on every platform for control chrome
+ *   such as button labels, tabs, badges, and field labels
  * - numberOfLines and ellipsizeMode support from RN TextProps
  */
 export declare function StyledText(props: TextProps): import("react").JSX.Element;

package/dist/components/StyledText.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { use } from "react";
-import { Text as RNText, StyleSheet } from "react-native";
+import { Platform, Text as RNText, StyleSheet } from "react-native";
 import { useTheme } from "../hooks/useTheme.js";
 import { resolveFontStyle } from "../constants/fonts.js";
 import { useThemeStore } from "../state/themeStore.js";
@@ -67,8 +67,12 @@ const SEMANTIC_CONFIGS = {
  *   real Inter font files on native, and family + numeric fontWeight on web
  * - Per-size letter-spacing scale (tight on large headings, positive on micro
  *   labels); explicit `style` letterSpacing always wins
- * - Text selection enabled by default; pass `selectable={false}` for control
- *   chrome such as button labels, tabs, badges, and field labels
+ * - Text selection on by default on iOS and web, off by default on Android:
+ *   a selectable Android `Text` is focusable-in-touch-mode, so a tap on a label
+ *   next to a focused input moved view focus to the label and hid the keyboard.
+ *   Pass `selectable` to opt copyable content in (codes, addresses, chat
+ *   bubbles); pass `selectable={false}` on every platform for control chrome
+ *   such as button labels, tabs, badges, and field labels
  * - numberOfLines and ellipsizeMode support from RN TextProps
  */
 export function StyledText(props) {
@@ -81,7 +85,9 @@ export function StyledText(props) {
     const contextColor = use(TextColorContext);
     const contextTextStyle = use(TextStyleContext);
     const contextSelectable = use(TextSelectabilityContext);
-    const resolvedSelectable = selectable ?? contextSelectable ?? true;
+    // Read at render time (not module load) so tests can flip `Platform.OS`.
+    const platformDefaultSelectable = Platform.OS !== "android";
+    const resolvedSelectable = selectable ?? contextSelectable ?? platformDefaultSelectable;
     // Use context color if provided, otherwise use theme default
     const color = contextColor ?? theme.colors.text;
     // If semantic variant is provided, use its config

package/dist/components/TextInput.js

@@ -207,6 +207,10 @@ function WebTextInput({ variant = "outline", size = "md", label, helperText, err
  * toggle laid out beside the native Host. Clear buttons, left/right elements,
  * and the error icon remain web-only; RN overlays are not layered over the
  * native host view.
+ *
+ * On Android `onBlur` is reported only after a forwarded `onFocus`: Compose
+ * reports `isFocused=false` on first composition and the field forwards it,
+ * so an unguarded consumer saw a blur before any interaction.
  */
 function NativeTextInput({ variant = "outline", size = "md", label, helperText, errorText, error, required, rows, forceLight, inputMode, onChangeText, onFocus, onBlur, value, defaultValue, editable = true, multiline, secureTextEntry, showSecureEntryToggle, ref, wrapperStyle, 
 // Web-only affordances. Destructured out of `rest` so they're NOT forwarded to
@@ -321,9 +325,16 @@ leftElement, rightElement, clearable, focusedStyle, style, ...rest }) {
     const handleBlur = useCallback((secure) => {
         if (Platform.OS === "ios" && secure !== activeSecureRef.current)
             return;
+        // Compose reports `isFocused=false` when the field is first composed and
+        // the Android field forwards it as a blur. A blur the field never
+        // preceded with a focus is not the user leaving the field: keep it from
+        // the consumer so blur validation does not flag untouched fields.
+        const wasFocused = isFocusedRef.current;
         isFocusedRef.current = false;
         restoreAfterSecureHandoffRef.current = false;
         clearKeyboardFocusedInput(focusRegistryToken);
+        if (Platform.OS === "android" && !wasFocused)
+            return;
         parentOnBlur?.();
     }, [focusRegistryToken, parentOnBlur]);
     const togglePasswordVisible = useCallback(() => {

package/dist/design-system.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@mrmeg/expo-ui",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "tokens": {
     "spacing": {
       "entries": [

package/llms-full.md

@@ -103,7 +103,7 @@ before creating a new app-local primitive.
 | `AnimatedView` | Entrance and visibility animation | Keep simple reveal effects in this wrapper. |
 | `Avatar`, `AvatarGroup` | Profile images with initials/icon fallback | Pass both `source` and `name`; set `size`/`shape` on the group, not per child. |
 | `Badge` | Short status labels | Prefer over custom pill views. |
-| `BottomSheet` | Mobile-first modal sheets | Requires root `UIProvider`. Native sheet via `@expo/ui`; `swipeEnabled`, `avoidKeyboard`, `dismissKeyboardOnDrag` are accepted but ignored. |
+| `BottomSheet` | Mobile-first modal sheets | Requires root `UIProvider`. Native sheet via `@expo/ui`; `swipeEnabled`, `avoidKeyboard`, `dismissKeyboardOnDrag` are accepted but ignored (the iOS sheet presentation and Android Material3 keep content above the keyboard; never nest a `KeyboardAvoidingView` in a sheet). |
 | `Button` | Commands and CTAs | Use `preset`, not `variant`; heights are 28/32/40. |
 | `Card` | Individual framed content groups | Do not wrap whole page sections in cards. |
 | `Carousel` | Small known set of horizontally snapping slides | Renders every child (no virtualization); fractional `itemWidth` measures the viewport until first layout. |

package/llms.txt

@@ -27,7 +27,10 @@ mount react-native-keyboard-controller's KeyboardProvider above UIProvider.
 
 BottomSheet renders the platform's native sheet via @expo/ui, which owns
 gestures and keyboard avoidance; swipeEnabled, avoidKeyboard, and
-dismissKeyboardOnDrag are accepted but ignored.
+dismissKeyboardOnDrag are accepted but ignored. On iOS the sheet presentation
+lifts or shrinks the hosted content so Footer and Body end at the keyboard's
+top (device-verified); Android avoidance is Material3's. Do not nest a
+KeyboardAvoidingView inside a sheet.
 
 Use useTheme(), useStyles(), semantic tokens, StyledText, and package controls.
 Do not add app-local Appearance or matchMedia listeners for theme sync. On web

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrmeg/expo-ui",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "private": false,
   "description": "Reusable Expo and React Native UI primitives for MrMeg projects.",
   "keywords": [