@mrmeg/expo-ui 0.23.0 → 0.25.0

package/dist/components/TextInput.js

@@ -10,8 +10,11 @@ import { Icon } from "./Icon.js";
 import { hapticLight } from "../lib/haptics.js";
 import { createThemedStyles } from "../lib/themedStyles.js";
 import { palette } from "../constants/colors.js";
-import { clearKeyboardFocusedInputLayout, setKeyboardFocusedInputLayout, } from "./keyboardFocusRegistry.js";
+import { clearKeyboardFocusedInput, setKeyboardFocusedInput, } from "./keyboardFocusRegistry.js";
+import { useTextInputSurfaceResponder } from "./keyboardDismiss.js";
 const NUMERIC_REGEX = /^[0-9]*$/;
+/** Platform touch-target guideline (pt); the compact fields sit below it. */
+const MIN_TOUCH_TARGET = 44;
 const SIZE_CONFIGS = {
     sm: {
         height: 32,
@@ -207,11 +210,36 @@ leftElement, rightElement, clearable, focusedStyle, style, ...rest }) {
     const [passwordVisible, setPasswordVisible] = useState(false);
     const hasError = error || !!errorText;
     const sizeConfig = SIZE_CONFIGS[size];
-    // Password visibility toggle. Flipping `secureTextEntry` swaps SwiftUI's
-    // SecureField <-> TextField on iOS and toggles Compose's visualTransformation
-    // on Android; both bind the same `state` observable, so the text survives.
+    // Password visibility toggle. Flipping `secureTextEntry` toggles Compose's
+    // visualTransformation in place on Android, but on iOS it selects a different
+    // native view (SwiftUI SecureField vs TextField), so React remounts the field
+    // and the keyboard drops with a full dismiss + re-present bounce.
+    //
+    // iOS handoff: while the field is focused, the toggle keeps the OLD view
+    // mounted (and visible) and mounts the NEW view hidden with `autoFocus`.
+    // UIKit hands first responder from old to new without hiding the keyboard;
+    // once the new view reports focus, it takes the layout slot and the old one
+    // unmounts. Both views bind the same `state`, so the text carries over.
     const hasSecureToggle = !!(secureTextEntry && showSecureEntryToggle);
-    const effectiveSecureTextEntry = secureTextEntry && !passwordVisible;
+    const effectiveSecureTextEntry = !!secureTextEntry && !passwordVisible;
+    const [handoff, setHandoff] = useState(null);
+    const handoffRef = useRef(null);
+    const isFocusedRef = useRef(false);
+    const activeSecureRef = useRef(effectiveSecureTextEntry);
+    activeSecureRef.current = effectiveSecureTextEntry;
+    // Taps that land while a handoff is in flight are counted and applied (by
+    // parity) once it settles.
+    const queuedTogglesRef = useRef(0);
+    const toggleRef = useRef(() => { });
+    // Per-flavour mount generation. Bumped whenever a flavour becomes the incoming
+    // view so React always mounts a FRESH native view (whose `autoFocus` will run)
+    // instead of reusing one that is still unmounting from the previous handoff.
+    const generationRef = useRef({ secure: 0, plain: 0 });
+    // Last text the JS side knows about; see handleChangeText.
+    const lastTextRef = useRef(value ?? defaultValue ?? "");
+    // Armed when the hide toggle hands focus to the SecureField (iOS); see
+    // handleChangeText.
+    const restoreAfterSecureHandoffRef = useRef(false);
     // Native text buffer. Seeded once; `value` changes are reconciled below.
     const state = useNativeState(value ?? defaultValue ?? "");
     // Reconcile controlled `value` -> native buffer WITHOUT echoing keystrokes.
@@ -221,62 +249,159 @@ leftElement, rightElement, clearable, focusedStyle, style, ...rest }) {
         if (value !== undefined && value !== state.value) {
             state.value = value;
         }
+        if (value !== undefined)
+            lastTextRef.current = value;
     }, [value, state]);
     // The inner ref is the @expo/ui handle; the outward ref is typed as
     // RNTextInput because that's what the public TextInputCustomProps declares.
     // We expose the subset consumers use, plus a `setNativeProps` shim so the
     // uncontrolled AuthTextField can push corrected text into the native buffer.
-    const innerRef = useRef(null);
-    const surfaceRef = useRef(null);
-    const isFocusedRef = useRef(false);
+    // One ref per native view flavour; only the active one (or, mid-handoff on
+    // iOS, both) is mounted.
+    const secureRef = useRef(null);
+    const plainRef = useRef(null);
+    const activeInput = useCallback(() => (activeSecureRef.current ? secureRef : plainRef).current, []);
+    const blurAll = useCallback(() => {
+        secureRef.current?.blur();
+        plainRef.current?.blur();
+    }, []);
     const focusRegistryToken = useMemo(() => ({}), []);
-    const syncFocusedInputLayout = useCallback(() => {
-        if (!isFocusedRef.current)
+    const finishHandoff = useCallback(() => {
+        const pending = handoffRef.current;
+        if (!pending)
+            return;
+        clearTimeout(pending.timer);
+        handoffRef.current = null;
+        setHandoff(null);
+        const queued = queuedTogglesRef.current;
+        queuedTogglesRef.current = 0;
+        if (queued % 2 === 1) {
+            // Next tick: let this commit settle first.
+            setTimeout(() => toggleRef.current(), 0);
+        }
+    }, []);
+    const parentOnFocus = onFocus;
+    const parentOnBlur = onBlur;
+    // Focus/blur from a view that is not the active flavour is ignored: that is
+    // the outgoing view resigning during a handoff, or a stale event from a view
+    // React is unmounting.
+    const handleFocus = useCallback((secure) => {
+        if (secure !== activeSecureRef.current)
             return;
-        surfaceRef.current?.measureInWindow((absoluteX, absoluteY, width, height) => {
-            if (!isFocusedRef.current)
-                return;
-            setKeyboardFocusedInputLayout(focusRegistryToken, {
-                x: 0,
-                y: 0,
-                width,
-                height,
-                absoluteX,
-                absoluteY,
-            }, 
-            // Window-independent dismissal: blur the native field directly. Inside a
-            // native bottom sheet the field lives in its own window, where
-            // `KeyboardController.dismiss()` can miss; calling the field's own ref
-            // always resigns it.
-            () => innerRef.current?.blur());
-        });
-    }, [focusRegistryToken]);
-    const handleFocus = useCallback(() => {
         isFocusedRef.current = true;
-        syncFocusedInputLayout();
-        onFocus?.();
-    }, [onFocus, syncFocusedInputLayout]);
-    const handleBlur = useCallback(() => {
+        // Register a blur handle so tap-away dismissal (`keyboardDismiss.ts`) and
+        // the BottomSheet overlay can resign this field: RN's `TextInputState`
+        // never sees SwiftUI / Compose fields, so `Keyboard.dismiss()` cannot.
+        // Blurring through the field's own ref is window-independent — inside a
+        // native bottom sheet `KeyboardController.dismiss()` can miss, the ref
+        // never does.
+        setKeyboardFocusedInput(focusRegistryToken, blurAll);
+        if (handoffRef.current) {
+            // The incoming view took first responder; the parent never saw focus leave.
+            restoreAfterSecureHandoffRef.current = secure && lastTextRef.current.length > 0;
+            finishHandoff();
+            return;
+        }
+        parentOnFocus?.();
+    }, [blurAll, finishHandoff, focusRegistryToken, parentOnFocus]);
+    const handleBlur = useCallback((secure) => {
+        if (secure !== activeSecureRef.current)
+            return;
         isFocusedRef.current = false;
-        clearKeyboardFocusedInputLayout(focusRegistryToken);
-        onBlur?.();
-    }, [focusRegistryToken, onBlur]);
+        restoreAfterSecureHandoffRef.current = false;
+        clearKeyboardFocusedInput(focusRegistryToken);
+        parentOnBlur?.();
+    }, [focusRegistryToken, parentOnBlur]);
+    const togglePasswordVisible = useCallback(() => {
+        if (handoffRef.current) {
+            // Mid-handoff: flipping now would unmount the view about to take first
+            // responder and drop the keyboard. Apply it once the handoff settles.
+            queuedTogglesRef.current += 1;
+            return;
+        }
+        restoreAfterSecureHandoffRef.current = false;
+        const outgoingSecure = activeSecureRef.current;
+        if (outgoingSecure)
+            generationRef.current.plain += 1;
+        else
+            generationRef.current.secure += 1;
+        if (Platform.OS === "ios" && isFocusedRef.current) {
+            const timer = setTimeout(() => {
+                // The incoming view never took first responder. Rather than unmount
+                // the focused outgoing view (which would drop the keyboard), undo the
+                // toggle so the outgoing flavour stays active; the user can tap again.
+                finishHandoff();
+                if (!activeInput()?.isFocused()) {
+                    setPasswordVisible(!outgoingSecure);
+                    setTimeout(() => {
+                        // If the outgoing view lost focus in the meantime (e.g. a tap
+                        // away during the handoff), report the blur its handler ignored.
+                        if (!activeInput()?.isFocused()) {
+                            isFocusedRef.current = false;
+                            clearKeyboardFocusedInput(focusRegistryToken);
+                            parentOnBlur?.();
+                        }
+                    }, 0);
+                }
+            }, 600);
+            handoffRef.current = { outgoingSecure, timer };
+            setHandoff({ outgoingSecure });
+        }
+        setPasswordVisible((v) => !v);
+    }, [activeInput, finishHandoff, focusRegistryToken, parentOnBlur]);
+    toggleRef.current = togglePasswordVisible;
+    // iOS clears a secure field's existing text on the first keystroke after it
+    // becomes first responder (text it did not see typed). Right after the hide
+    // toggle hands focus to the SecureField that reads as "type one character,
+    // lose the password", so the wiped text is put back with the keystroke
+    // applied. Only the first change after that handoff is eligible. A wipe
+    // shows up as a single character that cannot be a backspace of the previous
+    // text, or as an empty string (the wipe followed by a backspace that hit
+    // nothing) while the previous text had more than one character.
+    const handleChangeText = useCallback((text) => {
+        const previous = lastTextRef.current;
+        const armed = restoreAfterSecureHandoffRef.current && previous.length > 0;
+        const wipedByKey = armed && text.length === 1 && !previous.startsWith(text);
+        const wipedByBackspace = armed && text === "" && previous.length > 1;
+        const wiped = wipedByKey || wipedByBackspace;
+        restoreAfterSecureHandoffRef.current = false;
+        const next = wipedByKey ? previous + text : wipedByBackspace ? previous.slice(0, -1) : text;
+        lastTextRef.current = next;
+        if (wiped)
+            state.value = next;
+        onChangeText?.(next);
+    }, [onChangeText, state]);
     useEffect(() => {
-        return () => clearKeyboardFocusedInputLayout(focusRegistryToken);
+        return () => {
+            if (handoffRef.current)
+                clearTimeout(handoffRef.current.timer);
+            clearKeyboardFocusedInput(focusRegistryToken);
+        };
     }, [focusRegistryToken]);
+    // The SwiftUI field only hit-tests its text line, so a tap on the box's
+    // vertical padding (or on the hitSlop below) would otherwise be a no-op.
+    const surfaceResponderProps = useTextInputSurfaceResponder(() => {
+        if (editable === false)
+            return;
+        activeInput()?.focus();
+    });
+    // Stretch the touch target to the 44pt guideline without changing the box.
+    const surfaceHitSlop = Math.max(0, Math.ceil((MIN_TOUCH_TARGET - sizeConfig.height) / 2));
     useImperativeHandle(ref, () => ({
-        focus: () => innerRef.current?.focus(),
-        blur: () => innerRef.current?.blur(),
+        focus: () => activeInput()?.focus(),
+        blur: () => blurAll(),
         clear: () => {
             state.value = "";
+            lastTextRef.current = "";
         },
-        isFocused: () => innerRef.current?.isFocused() ?? false,
+        isFocused: () => activeInput()?.isFocused() ?? false,
         setNativeProps: (props) => {
             if (typeof props?.text === "string") {
                 state.value = props.text;
+                lastTextRef.current = props.text;
             }
         },
-    }), [state]);
+    }), [activeInput, blurAll, state]);
     const backgroundColor = forceLight
         ? palette.white
         : variant === "filled"
@@ -335,7 +460,20 @@ leftElement, rightElement, clearable, focusedStyle, style, ...rest }) {
         fontSize: sizeConfig.fontSize,
         ...(nativeFontFamily ? { fontFamily: nativeFontFamily } : null),
     };
-    return (_jsxs(View, { style: wrapperStyle, children: [!!label && (_jsx(View, { style: styles.labelContainer, children: _jsxs(StyledText, { selectable: false, size: "base", fontWeight: "medium", style: styles.label, children: [label, required && _jsx(StyledText, { selectable: false, fontWeight: "bold", style: styles.required, children: " *" })] }) })), _jsxs(View, { ref: surfaceRef, style: [surfaceStyle, hasSecureToggle && styles.nativeRow], onLayout: syncFocusedInputLayout, children: [_jsx(Host, { matchContents: { vertical: true }, style: hasSecureToggle ? styles.nativeHostFlex : styles.nativeHost, children: _jsx(ExpoTextInput, { ...rest, ref: innerRef, value: state, defaultValue: defaultValue, onChangeText: onChangeText, onFocus: handleFocus, onBlur: handleBlur, editable: editable, multiline: multiline, rows: rows, inputMode: inputMode, secureTextEntry: effectiveSecureTextEntry, placeholderTextColor: theme.colors.textDim, style: boxStyle, textStyle: textStyle }) }), hasSecureToggle && (_jsx(Pressable, { style: styles.nativePasswordToggle, onPress: () => setPasswordVisible((v) => !v), accessibilityLabel: passwordVisible ? "Hide password" : "Show password", accessibilityRole: "button", children: _jsx(Icon, { name: passwordVisible ? "eye-off" : "eye", size: spacing.iconSm + 4, color: "textDim" }) }))] }), !!(helperText || errorText) && (_jsx(StyledText, { selectable: false, size: "sm", style: [styles.helperText, hasError && styles.errorText], children: errorText || helperText }))] }));
+    return (_jsxs(View, { style: wrapperStyle, children: [!!label && (_jsx(View, { style: styles.labelContainer, children: _jsxs(StyledText, { selectable: false, size: "base", fontWeight: "medium", style: styles.label, children: [label, required && _jsx(StyledText, { selectable: false, fontWeight: "bold", style: styles.required, children: " *" })] }) })), _jsxs(View, { style: [surfaceStyle, hasSecureToggle && styles.nativeRow], hitSlop: { top: surfaceHitSlop, bottom: surfaceHitSlop }, ...surfaceResponderProps, children: [[true, false].map((secure) => {
+                        const active = secure === effectiveSecureTextEntry;
+                        const outgoing = handoff != null && secure === handoff.outgoingSecure;
+                        if (!active && !outgoing)
+                            return null;
+                        // Mid-handoff the outgoing view keeps the visible slot (and focus)
+                        // while the incoming one mounts hidden and takes first responder.
+                        const inLayout = handoff ? outgoing : active;
+                        return (_jsx(Host, { matchContents: { vertical: true }, style: inLayout
+                                ? hasSecureToggle
+                                    ? styles.nativeHostFlex
+                                    : styles.nativeHost
+                                : styles.nativeHostHandoff, pointerEvents: inLayout ? "auto" : "none", accessibilityElementsHidden: !inLayout, importantForAccessibility: inLayout ? "auto" : "no-hide-descendants", children: _jsx(ExpoTextInput, { ...rest, autoFocus: rest.autoFocus || (handoff != null && active), ref: secure ? secureRef : plainRef, value: state, defaultValue: defaultValue, onChangeText: handleChangeText, onFocus: () => handleFocus(secure), onBlur: () => handleBlur(secure), editable: editable, multiline: multiline, rows: rows, inputMode: inputMode, secureTextEntry: secure, placeholderTextColor: theme.colors.textDim, style: boxStyle, textStyle: textStyle }) }, secure ? `secure-${generationRef.current.secure}` : `plain-${generationRef.current.plain}`));
+                    }), hasSecureToggle && (_jsx(Pressable, { style: styles.nativePasswordToggle, onPress: togglePasswordVisible, accessibilityLabel: passwordVisible ? "Hide password" : "Show password", accessibilityRole: "button", children: _jsx(Icon, { name: passwordVisible ? "eye-off" : "eye", size: spacing.iconSm + 4, color: "textDim" }) }))] }), !!(helperText || errorText) && (_jsx(StyledText, { selectable: false, size: "sm", style: [styles.helperText, hasError && styles.errorText], children: errorText || helperText }))] }));
 }
 const createStyles = (theme, variant, size) => StyleSheet.create({
     nativeHost: {
@@ -349,6 +487,15 @@ const createStyles = (theme, variant, size) => StyleSheet.create({
     nativeHostFlex: {
         flex: 1,
     },
+    // Incoming view during an iOS secure/plain handoff: mounted and focusable,
+    // but invisible and out of the row's layout until it holds first responder.
+    nativeHostHandoff: {
+        position: "absolute",
+        top: 0,
+        left: 0,
+        right: 0,
+        opacity: 0,
+    },
     nativePasswordToggle: {
         paddingHorizontal: spacing.xs,
     },

package/dist/components/Tooltip.d.ts

@@ -1,19 +1,11 @@
 import * as React from "react";
-import { View, ViewProps } from "react-native";
+import { ViewProps } from "react-native";
 import * as TooltipPrimitive from "@rn-primitives/tooltip";
 /**
  * Tooltip Trigger Component
  * The element that triggers the tooltip to appear on hover (web) or press (native)
  */
-declare const TooltipTrigger: {
-    ({ asChild, onPress: onPressProp, disabled, ref, ...props }: Omit<import("react-native").PressableProps & React.RefAttributes<View>, "ref"> & {
-        asChild?: boolean;
-    } & {
-        onKeyDown?: (ev: React.KeyboardEvent) => void;
-        onKeyUp?: (ev: React.KeyboardEvent) => void;
-    } & React.RefAttributes<import("@rn-primitives/tooltip").TriggerRef>): React.JSX.Element;
-    displayName: string;
-};
+declare const TooltipTrigger: typeof TooltipPrimitive.Trigger;
 /**
  * Tooltip variant styles
  */
@@ -100,22 +92,16 @@ interface TooltipProps extends TooltipPrimitive.RootProps {
  * ```
  */
 declare function Tooltip({ delayDuration, skipDelayDuration, ...props }: TooltipProps): React.JSX.Element;
-/**
- * Tooltip Component with Sub-components
- * Properly typed interface for dot notation access (e.g., Tooltip.Trigger)
- */
-declare const TooltipComponent: typeof Tooltip & {
-    Trigger: {
-        ({ asChild, onPress: onPressProp, disabled, ref, ...props }: Omit<import("react-native").PressableProps & React.RefAttributes<View>, "ref"> & {
-            asChild?: boolean;
-        } & {
-            onKeyDown?: (ev: React.KeyboardEvent) => void;
-            onKeyUp?: (ev: React.KeyboardEvent) => void;
-        } & React.RefAttributes<import("@rn-primitives/tooltip").TriggerRef>): React.JSX.Element;
-        displayName: string;
-    };
+type TooltipCompound = typeof Tooltip & {
+    Trigger: typeof TooltipTrigger;
     Content: typeof TooltipContent;
     Body: typeof TooltipBody;
 };
+/**
+ * Tooltip Component with Sub-components
+ * Properly typed interface for dot notation access (e.g., Tooltip.Trigger).
+ * The annotation is what keeps declaration emit portable — see Dialog.tsx (TS2883).
+ */
+declare const TooltipComponent: TooltipCompound;
 export { TooltipComponent as Tooltip, TooltipTrigger, TooltipContent, TooltipBody, };
 export type { TooltipContentProps, TooltipBodyProps, TooltipProps, };

package/dist/components/Tooltip.js

@@ -12,6 +12,8 @@ import { palette } from "../constants/colors.js";
  * Tooltip Trigger Component
  * The element that triggers the tooltip to appear on hover (web) or press (native)
  */
+// Annotated with `typeof` for portable declaration emit — see the note in
+// Dialog.tsx (TS2883). Without it the .d.ts inlines RN 0.88's `PressableInstance`.
 const TooltipTrigger = TooltipPrimitive.Trigger;
 /**
  * FullWindowOverlay wrapper - uses native overlay on iOS for proper z-index handling
@@ -68,7 +70,7 @@ function TooltipContent({ side = "top", align = "center", sideOffset = 4, portal
             maxWidth: 250,
             ...getShadowStyle("soft"),
         },
-    ]);
+    ]) ?? undefined;
     return (_jsx(TooltipPrimitive.Portal, { hostName: portalHost, children: _jsx(FullWindowOverlay, { children: _jsx(TooltipPrimitive.Overlay, { style: Platform.select({ native: StyleSheet.absoluteFill }), children: _jsx(AnimatedView, { type: "fade", enterDuration: 150, children: _jsx(TextColorContext.Provider, { value: colors.text, children: _jsx(TextClassContext.Provider, { value: "", children: _jsx(TextSelectabilityContext.Provider, { value: false, children: _jsx(TooltipPrimitive.Content, { side: side, align: align, sideOffset: sideOffset, style: contentStyle, ...props }) }) }) }) }) }) }) }));
 }
 function TooltipBody({ children, style, ...props }) {
@@ -122,7 +124,8 @@ function Tooltip({ delayDuration = 700, skipDelayDuration = 300, ...props }) {
 }
 /**
  * Tooltip Component with Sub-components
- * Properly typed interface for dot notation access (e.g., Tooltip.Trigger)
+ * Properly typed interface for dot notation access (e.g., Tooltip.Trigger).
+ * The annotation is what keeps declaration emit portable — see Dialog.tsx (TS2883).
  */
 const TooltipComponent = Object.assign(Tooltip, {
     Trigger: TooltipTrigger,

package/dist/components/index.d.ts

@@ -11,6 +11,7 @@ export * from "./Checkbox";
 export * from "./Collapsible";
 export * from "./Dialog";
 export * from "./DismissKeyboard";
+export * from "./keyboardDismiss";
 export * from "./Drawer";
 export * from "./DropdownMenu";
 export * from "./EmptyState";

package/dist/components/index.js

@@ -11,6 +11,7 @@ export * from "./Checkbox.js";
 export * from "./Collapsible.js";
 export * from "./Dialog.js";
 export * from "./DismissKeyboard.js";
+export * from "./keyboardDismiss.js";
 export * from "./Drawer.js";
 export * from "./DropdownMenu.js";
 export * from "./EmptyState.js";

package/dist/components/keyboardController.d.ts

@@ -19,7 +19,6 @@
  * function that has no hook calls of its own).
  */
 import React from "react";
-import { View } from "react-native";
 import type { IKeyboardState, KeyboardAnimationContext, KeyboardAvoidingViewProps, KeyboardControllerModule } from "react-native-keyboard-controller";
 /** No-op imperative module: there is no IME to dismiss or preload on web. */
 export declare const KeyboardController: KeyboardControllerModule;
@@ -41,6 +40,9 @@ type NativeKeyboardAvoidingViewProps = KeyboardAvoidingViewProps & {
  * Plain `View` passthrough. Keyboard-avoidance props are accepted (so callers
  * stay identical across platforms) and dropped, since the browser handles
  * viewport resizing itself.
+ *
+ * The explicit return type keeps declaration emit from inlining `View`'s ref
+ * type (RN 0.88's `ViewInstance`), which older RN typings do not export.
  */
-export declare function NativeKeyboardAvoidingView({ behavior, contentContainerStyle, keyboardVerticalOffset, automaticOffset, enabled, children, ...viewProps }: NativeKeyboardAvoidingViewProps): React.CElement<import("react-native").ViewProps, View>;
+export declare function NativeKeyboardAvoidingView({ behavior, contentContainerStyle, keyboardVerticalOffset, automaticOffset, enabled, children, ...viewProps }: NativeKeyboardAvoidingViewProps): React.ReactElement;
 export {};

package/dist/components/keyboardController.js

@@ -53,6 +53,7 @@ export const KeyboardController = {
     setDefaultMode: () => undefined,
     setInputMode: () => undefined,
     preload: () => undefined,
+    setTranslucent: () => undefined,
     dismiss: () => Promise.resolve(),
     setFocusTo: () => undefined,
     isVisible: () => false,
@@ -77,6 +78,9 @@ export function useKeyboardContext() {
  * Plain `View` passthrough. Keyboard-avoidance props are accepted (so callers
  * stay identical across platforms) and dropped, since the browser handles
  * viewport resizing itself.
+ *
+ * The explicit return type keeps declaration emit from inlining `View`'s ref
+ * type (RN 0.88's `ViewInstance`), which older RN typings do not export.
  */
 export function NativeKeyboardAvoidingView({ behavior, contentContainerStyle, keyboardVerticalOffset, automaticOffset, enabled, children, ...viewProps }) {
     // Dropped rather than forwarded so they never reach the DOM node.

package/dist/components/keyboardDismiss.d.ts

@@ -0,0 +1,37 @@
+import { type GestureResponderEvent, type ViewProps } from "react-native";
+/**
+ * `onStartShouldSetResponder` for a native text-field surface: decline the
+ * responder (the native field keeps every touch phase) but tag the touch so an
+ * enclosing tap-away boundary leaves it alone. The package `TextInput` uses
+ * this through {@link useTextInputSurfaceResponder}.
+ */
+export declare function markTextInputTouchStart(event: GestureResponderEvent): boolean;
+/**
+ * Hide the software keyboard for whatever is focused. Prefers the registered
+ * native field's own blur handle (window-independent), then falls back to
+ * `KeyboardController.dismiss()`, which resigns at the IME level and covers RN
+ * or third-party inputs. No-op on web, which has no software keyboard to hide.
+ */
+export declare function dismissKeyboard(): void;
+export type TextInputSurfaceResponderProps = Pick<ViewProps, "onStartShouldSetResponder" | "onTouchStart" | "onTouchMove" | "onTouchEnd" | "onTouchCancel">;
+/**
+ * View props for the painted surface around a native (`@expo/ui`) text field.
+ *
+ * Two jobs. It tags every touch that begins on the surface so the tap-away
+ * boundary leaves it alone (see {@link markTextInputTouchStart}). And it
+ * focuses the field on release of a tap that no child claimed: the SwiftUI
+ * `TextField` only hit-tests its text line, so taps on the box's vertical
+ * padding never reach it, and a tap on the field's `hitSlop` never can. Calling
+ * `focus` is idempotent when the native field already took the tap, and the eye
+ * toggle is a `Pressable` that claims the responder first, so it never fires
+ * for that.
+ */
+export declare function useTextInputSurfaceResponder(focus: () => void): TextInputSurfaceResponderProps;
+export type KeyboardDismissResponderProps = Pick<ViewProps, "onStartShouldSetResponder" | "onTouchStart" | "onTouchMove" | "onTouchEnd" | "onTouchCancel">;
+/**
+ * View props for a tap-away keyboard-dismiss boundary. Spread onto the wrapper
+ * `View` that encloses the screen (or a form). Nesting is safe: the innermost
+ * boundary owns each touch, so the keyboard is dismissed once. Returns `{}` on
+ * web.
+ */
+export declare function useKeyboardDismissResponder(): KeyboardDismissResponderProps;

package/dist/components/keyboardDismiss.js

@@ -0,0 +1,170 @@
+/**
+ * Tap-away keyboard dismissal that never steals a touch.
+ *
+ * React Native's own `keyboardShouldPersistTaps="handled"` is the model: let the
+ * deepest interactive view win the responder negotiation, and blur on *release*
+ * only when nothing else took the tap and the finger did not scroll. RN cannot
+ * apply that to the native `@expo/ui` field (it is invisible to
+ * `TextInputState`), so this module re-creates the same decision with two
+ * signals that need no rectangles and no responder ownership:
+ *
+ *  1. `onStartShouldSetResponder` in the *bubble* phase is only ever called on a
+ *     view when no descendant claimed the touch. Pressables, RN TextInputs and
+ *     scroll views all claim, so being asked at all means "this tap is on dead
+ *     space or on a native view that does not participate".
+ *  2. The package `TextInput` tags touches that begin on its surface
+ *     (`markTextInputTouchStart`). Its bubble handler runs before any enclosing
+ *     boundary's, so the boundary can tell a tap on *any* native field — focused
+ *     or not — from dead space, and leave focus handoff, double-tap selection
+ *     and the eye toggle to the platform.
+ *
+ * The boundary always answers `false`, so no JS responder is ever set: native
+ * controls (SwiftUI/Compose fields, sliders) keep receiving every touch phase
+ * on both platforms, and scroll views take over drags exactly as before.
+ * Dismissal happens in `onTouchEnd`, a plain bubbling event that fires whether
+ * or not anyone became the responder; a drag past the slop or a cancel drops it.
+ */
+import { useMemo, useRef } from "react";
+import { Platform } from "react-native";
+import { KeyboardController, useKeyboardState } from "./keyboardController";
+import { dismissKeyboardFocusedInput, hasKeyboardFocusedInput } from "./keyboardFocusRegistry.js";
+/** Finger travel (pt) after which a touch counts as a scroll, not a tap. */
+const MOVE_SLOP = 10;
+function keyOf(event) {
+    const { identifier, timestamp } = event.nativeEvent;
+    return { identifier, timestamp };
+}
+/** Same native event: the responder negotiation hands one event to every listener. */
+function isSameEvent(key, event) {
+    return (key != null &&
+        key.identifier === event.nativeEvent.identifier &&
+        key.timestamp === event.nativeEvent.timestamp);
+}
+let textInputTouch = null;
+let claimedTouch = null;
+/**
+ * `onStartShouldSetResponder` for a native text-field surface: decline the
+ * responder (the native field keeps every touch phase) but tag the touch so an
+ * enclosing tap-away boundary leaves it alone. The package `TextInput` uses
+ * this through {@link useTextInputSurfaceResponder}.
+ */
+export function markTextInputTouchStart(event) {
+    textInputTouch = keyOf(event);
+    return false;
+}
+/**
+ * Hide the software keyboard for whatever is focused. Prefers the registered
+ * native field's own blur handle (window-independent), then falls back to
+ * `KeyboardController.dismiss()`, which resigns at the IME level and covers RN
+ * or third-party inputs. No-op on web, which has no software keyboard to hide.
+ */
+export function dismissKeyboard() {
+    if (Platform.OS === "web")
+        return;
+    if (!dismissKeyboardFocusedInput()) {
+        void KeyboardController.dismiss();
+    }
+}
+function isSameTouch(tap, event) {
+    return tap != null && tap.identifier === event.nativeEvent.identifier;
+}
+function movedPastSlop(tap, event) {
+    return (Math.abs(event.nativeEvent.pageX - tap.pageX) > MOVE_SLOP ||
+        Math.abs(event.nativeEvent.pageY - tap.pageY) > MOVE_SLOP);
+}
+/**
+ * View props for the painted surface around a native (`@expo/ui`) text field.
+ *
+ * Two jobs. It tags every touch that begins on the surface so the tap-away
+ * boundary leaves it alone (see {@link markTextInputTouchStart}). And it
+ * focuses the field on release of a tap that no child claimed: the SwiftUI
+ * `TextField` only hit-tests its text line, so taps on the box's vertical
+ * padding never reach it, and a tap on the field's `hitSlop` never can. Calling
+ * `focus` is idempotent when the native field already took the tap, and the eye
+ * toggle is a `Pressable` that claims the responder first, so it never fires
+ * for that.
+ */
+export function useTextInputSurfaceResponder(focus) {
+    const focusRef = useRef(focus);
+    focusRef.current = focus;
+    const tap = useRef(null);
+    return useMemo(() => ({
+        onStartShouldSetResponder: (event) => {
+            markTextInputTouchStart(event);
+            tap.current = { ...keyOf(event), pageX: event.nativeEvent.pageX, pageY: event.nativeEvent.pageY };
+            return false;
+        },
+        onTouchStart: (event) => {
+            if (tap.current && !isSameEvent(tap.current, event))
+                tap.current = null;
+        },
+        onTouchMove: (event) => {
+            if (isSameTouch(tap.current, event) && movedPastSlop(tap.current, event))
+                tap.current = null;
+        },
+        onTouchEnd: (event) => {
+            if (!isSameTouch(tap.current, event))
+                return;
+            tap.current = null;
+            focusRef.current();
+        },
+        onTouchCancel: () => {
+            tap.current = null;
+        },
+    }), []);
+}
+/**
+ * View props for a tap-away keyboard-dismiss boundary. Spread onto the wrapper
+ * `View` that encloses the screen (or a form). Nesting is safe: the innermost
+ * boundary owns each touch, so the keyboard is dismissed once. Returns `{}` on
+ * web.
+ */
+export function useKeyboardDismissResponder() {
+    const isVisible = useKeyboardState((state) => state.isVisible);
+    const isVisibleRef = useRef(isVisible);
+    isVisibleRef.current = isVisible;
+    const pending = useRef(null);
+    return useMemo(() => {
+        if (Platform.OS === "web")
+            return {};
+        return {
+            onStartShouldSetResponder: (event) => {
+                pending.current = null;
+                // `hasKeyboardFocusedInput` covers the window where a field has focus but
+                // keyboard-controller has not reported the keyboard yet (or a hardware
+                // keyboard is attached and there is no software keyboard to observe).
+                if (!isVisibleRef.current && !hasKeyboardFocusedInput())
+                    return false;
+                if (isSameEvent(textInputTouch, event))
+                    return false;
+                // An inner boundary already runs this touch (bubble order is inner-first).
+                if (isSameEvent(claimedTouch, event))
+                    return false;
+                claimedTouch = keyOf(event);
+                pending.current = { ...claimedTouch, pageX: event.nativeEvent.pageX, pageY: event.nativeEvent.pageY };
+                return false;
+            },
+            onTouchStart: (event) => {
+                // Bubbling touch events run after the negotiation for the same native
+                // event, so a fresh pending tap matches here; anything else is stale
+                // (e.g. a touch whose end never reached this view).
+                if (pending.current && !isSameEvent(pending.current, event))
+                    pending.current = null;
+            },
+            onTouchMove: (event) => {
+                if (isSameTouch(pending.current, event) && movedPastSlop(pending.current, event)) {
+                    pending.current = null;
+                }
+            },
+            onTouchEnd: (event) => {
+                if (!isSameTouch(pending.current, event))
+                    return;
+                pending.current = null;
+                dismissKeyboard();
+            },
+            onTouchCancel: () => {
+                pending.current = null;
+            },
+        };
+    }, []);
+}