expo-tvos-search 1.3.1 → 1.4.0

package/CHANGELOG.md

@@ -0,0 +1,111 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.3.2] - 2026-01-25
+
+### Added
+- **Apple TV hardware keyboard support**: New `onSearchFieldFocused` and `onSearchFieldBlurred` event callbacks
+  - Enables proper Siri Remote keyboard input on physical Apple TV devices
+  - Works with `TVEventControl.disableGestureHandlersCancelTouches()` for JS-side handling
+  - Native Swift implementation automatically disables tap/press gesture recognizers when search field is focused
+  - Keeps swipe/pan recognizers enabled for keyboard navigation
+  - TypeScript type `SearchFieldFocusEvent` for the new focus events
+  - **Data URI support for images**: `imageUrl` now accepts `data:` URIs (e.g., `data:image/png;base64,...`) in addition to HTTP/HTTPS URLs
+    - Enables inline base64-encoded images without external requests
+    - Useful for cached thumbnails or placeholder images
+
+### Fixed
+- Siri Remote click events not reaching native SwiftUI search field on real Apple TV hardware
+- React Native gesture handlers intercepting keyboard input before it reached SwiftUI `.searchable` modifier
+
+## [1.3.1] - 2026-01-21
+
+### Fixed
+- Minor stability improvements
+- Documentation updates
+
+## [1.3.0] - 2026-01-20
+
+### Added
+- `cardMargin` prop - Customize spacing between cards in the grid (default: 40)
+- `cardPadding` prop - Customize padding inside cards for overlay content (default: 16)
+- `overlayTitleSize` prop - Customize font size for title in blur overlay (default: 20)
+
+### Changed
+- Improved grid layout flexibility with customizable spacing
+
+## [1.2.3] - 2026-01-20
+- Patch release for npm publish workflow fix.
+
+### Added
+- GitHub Actions workflow step for npm publish, trigger on PR with labels: `release:patch`, `release:minor`, `release:major`
+
+## [1.2.0] - 2026-01-17
+
+### Added
+- `onError` callback - Receive notifications for fatal errors (image loading failures, validation errors)
+- `onValidationWarning` callback - Receive non-fatal warnings (truncated fields, clamped values, invalid URLs)
+- `SearchViewErrorEvent` and `ValidationWarningEvent` TypeScript types
+- JSDoc documentation for all TypeScript exports
+- `SearchEvent` and `SelectItemEvent` type interfaces for improved type safety
+- Coverage thresholds (80% global) in Jest configuration
+- Explicit tvOS modules section in expo-module.config.json
+- Performance and Accessibility documentation sections in README
+- Debug logging for skipped invalid results (id or title missing/empty)
+
+### Changed
+- Input validation: `columns` prop now clamps between 1-10 (was: min 1 only)
+- Input validation: `topInset` prop now clamps between 0-500 (was: min 0 only)
+- Input validation: `marqueeDelay` prop now clamps between 0-60 seconds (was: min 0 only)
+- Input validation: `placeholder` prop now limited to 500 characters
+- Input validation: `results` array now limited to 500 items max
+- MarqueeAnimationCalculator guards against division by zero
+- MarqueeAnimationCalculator ensures non-negative values for spacing and distances
+
+### Security
+- URL scheme validation: `imageUrl` now only accepts HTTP/HTTPS schemes
+- String length limits: `id`, `title`, `subtitle` clamped to 500 characters each
+- Empty string rejection: Results with empty `id` or `title` are now skipped
+- Added `@types/react-native` and build dependencies for TypeScript compilation
+
+### Fixed
+- TypeScript build now compiles successfully with `jsx: "react"` option
+- Empty strings no longer pass validation for required fields
+
+## [1.1.0] - 2026-01-15
+
+### Added
+- Marquee scrolling animation for long titles that overflow card width
+- `enableMarquee` prop to toggle marquee behavior (default: true)
+- `marqueeDelay` prop to control delay before scrolling starts (default: 1.5s)
+- `showTitleOverlay` prop for gradient title overlay at bottom of cards
+- MarqueeAnimationCalculator for testable animation logic
+
+### Changed
+- Title display now uses overlay by default instead of below-card text
+- Improved focus state visual feedback
+
+## [1.0.0] - 2026-01-10
+
+### Added 
+- Initial release
+- Native SwiftUI search view with `.searchable` modifier
+- Grid layout for search results with configurable columns
+- `TvosSearchView` React Native component
+- `isNativeSearchAvailable()` utility function
+- Core props:
+  - `results`, `columns`, `placeholder`, `isLoading`
+  - `cardWidth`, `cardHeight` - Customizable card dimensions
+  - `imageContentMode` - Image scaling (`fill`, `fit`, `contain`)
+  - `textColor`, `accentColor` - Color customization
+  - `showTitle`, `showSubtitle`, `showFocusBorder` - Display options
+  - `topInset` - Tab bar clearance
+  - `emptyStateText`, `searchingText`, `noResultsText`, `noResultsHintText` - Text customization
+- `onSearch` and `onSelectItem` event callbacks
+- Automatic fallback when native module is unavailable
+- TypeScript type definitions (`SearchResult`, `TvosSearchViewProps`, etc.)
+- Comprehensive test suite

package/README.md

@@ -3,7 +3,6 @@
 [![npm version](https://img.shields.io/npm/v/expo-tvos-search.svg)](https://www.npmjs.com/package/expo-tvos-search)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Test Status](https://github.com/keiver/expo-tvos-search/workflows/Test%20PR/badge.svg)](https://github.com/keiver/expo-tvos-search/actions)
-[![Bundle Size](https://img.shields.io/bundlephobia/minzip/expo-tvos-search)](https://bundlephobia.com/package/expo-tvos-search)
 
 A native tvOS search component for Expo and React Native using SwiftUI's `.searchable` modifier. Provides the native tvOS search experience with automatic focus handling, remote control support, and flexible customization for media apps.
 
@@ -13,7 +12,7 @@ A native tvOS search component for Expo and React Native using SwiftUI's `.searc
 - React Native tvOS 0.71+
 
 <p align="center">
-  <img src="screenshots/demo-mini.png" width="80%" alt="Demo Mini screen for expo-tvos-search" style="border-radius: 16px;max-width: 100%;"/>
+  <img src="screenshots/default.png" alt="expo-tvos-search fullscreen native tvOS search component" style="border-radius: 16px;max-width: 100%;"/>
 </p>
 
 ## Installation
@@ -28,55 +27,18 @@ Or install from GitHub:
 npx expo install github:keiver/expo-tvos-search
 ```
 
-Then follow the **tvOS prerequisites** below and rebuild your native project.
+## Prerequisites for tvOS Builds
 
-## Quick Start
+Your project must be configured for React Native tvOS to use this module.
 
-### Try the Demo App
+### 1. Install react-native-tvos
 
-**[expo-tvos-search-demo](https://github.com/keiver/expo-tvos-search-demo)** - Comprehensive showcase with 7 tabs demonstrating all library features:
-
-- **Default** - 4-column grid with custom colors
-- **Portrait** - Netflix-style tall cards (280×420)
-- **Landscape** - Wide 16:9 cards (500×280)
-- **Mini** - Compact 5-column layout (240×360)
-- **External Title** - Titles displayed below cards
-- **Minimal** - Bare minimum setup (5 props)
-- **Help** - Feature overview and usage guide
-
-Clone and run:
 ```bash
-git clone https://github.com/keiver/expo-tvos-search-demo.git
-cd expo-tvos-search-demo
-npm install
-npm run prebuild
-npm run tvos
-```
-
-The demo uses a planet search theme with 8 planets (Mercury to Neptune) and demonstrates all library features with real working code.
-
-## Prerequisites for tvOS Builds (Expo)
-
-Your project must be configured for React Native tvOS to build and run this module.
-
-**Quick Checklist:**
-
-- ✅ `react-native-tvos` in use
-- ✅ `@react-native-tvos/config-tv` installed + added to Expo plugins
-- ✅ Run prebuild with `EXPO_TV=1`
-
-### 1. Swap to react-native-tvos
-
-Replace `react-native` with the [tvOS fork](https://github.com/react-native-tvos/react-native-tvos):
-
-```bash
-npm remove react-native && npm install react-native-tvos@latest
+npm install react-native-tvos@latest
 ```
 
 ### 2. Install the tvOS config plugin
 
-Install:
-
 ```bash
 npx expo install @react-native-tvos/config-tv
 ```
@@ -91,32 +53,9 @@ Then add the plugin in `app.json` / `app.config.js`:
 }
 ```
 
-### 3. Generate native projects with tvOS enabled
-
-```bash
-EXPO_TV=1 npx expo prebuild --clean
-```
-
-Then run:
-
-```bash
-npx expo run:ios
-```
-
-
 ## Usage
 
-### Minimal Example
-
-For the absolute minimum setup, see the [Minimal tab](https://github.com/keiver/expo-tvos-search-demo/blob/main/app/(tabs)/minimal.tsx) in the demo app.
-
-<p align="center">
-  <img src="screenshots/demo-default.png" width="80%" alt="Minimal demo screen for expo-tvos-search" style="border-radius: 16px;max-width: 100%;"/><br/>
-</p>
-
-### Complete Example
-
-This example from the demo's [Portrait tab](https://github.com/keiver/expo-tvos-search-demo/blob/main/app/(tabs)/portrait.tsx) shows a complete implementation with best practices:
+This example from the demo's [Portrait tab](https://github.com/keiver/expo-tvos-search-demo/blob/main/app/(tabs)/portrait.tsx) shows a complete implementation:
 
 ```tsx
 import { useState } from 'react';
@@ -136,7 +75,7 @@ const PLANETS: SearchResult[] = [
     subtitle: 'Our home planet, the only known world to harbor life',
     imageUrl: require('./assets/planets/earth.webp'),
   },
-  // ... more planets
+  // ... all planets
 ];
 
 export default function SearchScreen() {
@@ -154,7 +93,7 @@ export default function SearchScreen() {
 
     setIsLoading(true);
 
-    // Debounce search (300ms)
+    // Debounce dummy search (300ms)
     setTimeout(() => {
       const filtered = PLANETS.filter(
         planet =>
@@ -194,7 +133,7 @@ export default function SearchScreen() {
         accentColor="#E50914"
         cardWidth={280}
         cardHeight={420}
-        overlayTitleSize={18}  // v1.3.0 - control title font size
+        overlayTitleSize={18}
         style={{ flex: 1 }}
       />
     </LinearGradient>
@@ -202,9 +141,13 @@ export default function SearchScreen() {
 }
 ```
 
-## Layout Styles
+<p align="center">
+  <img src="screenshots/no-results.png" alt="No results for search screen using expo-tvos-search" style="border-radius: 16px;max-width: 100%;"/><br/>
+</p>
+
+## Demo App and Common Configurations
 
-Explore all 7 configurations in the [demo app](https://github.com/keiver/expo-tvos-search-demo).
+Explore all configurations in the [demo app](https://github.com/keiver/expo-tvos-search-demo).
 
 ### Portrait Cards
 
@@ -268,6 +211,28 @@ Explore all 7 configurations in the [demo app](https://github.com/keiver/expo-tv
 />
 ```
 
+### Apple TV Hardware Keyboard Support (v1.3.2+)
+
+On real Apple TV hardware, React Native's `RCTTVRemoteHandler` installs gesture recognizers that consume Siri Remote presses before they reach SwiftUI's `.searchable` text field, which prevents keyboard input. When the search field gains focus, this component temporarily disables touch cancellation using the official `react-native-tvos` notification API, and also disables tap/long-press recognizers from parent views (to cover cases like `react-native-gesture-handler`). Swipe and pan recognizers stay active for keyboard navigation. Everything is restored when focus leaves the field. This only applies to physical devices -- the Simulator doesn't need it.
+
+If this interferes with gesture handling in your app, please [open an issue](https://github.com/keiver/expo-tvos-search/issues) so we can sort it out.
+
+For additional control, you can use the focus callbacks with `TVEventControl`:
+
+```tsx
+import { TVEventControl } from 'react-native';
+
+<TvosSearchView
+  onSearchFieldFocused={() => {
+    TVEventControl.disableGestureHandlersCancelTouches();
+  }}
+  onSearchFieldBlurred={() => {
+    TVEventControl.enableGestureHandlersCancelTouches();
+  }}
+  // ... other props
+/>
+```
+
 ### Customizing Colors and Card Dimensions
 
 ```tsx
@@ -310,101 +275,8 @@ Explore all 7 configurations in the [demo app](https://github.com/keiver/expo-tv
 />
 ```
 
-## TypeScript Support
-
-The library provides comprehensive type definitions for all events and props.
-
-### Event Types
-
-```typescript
-import type {
-  SearchEvent,
-  SelectItemEvent,
-  SearchViewErrorEvent,
-  ValidationWarningEvent,
-  SearchResult,
-} from 'expo-tvos-search';
-
-// Search event - fired on text change
-interface SearchEvent {
-  nativeEvent: {
-    query: string;
-  };
-}
-
-// Selection event - fired when result is selected
-interface SelectItemEvent {
-  nativeEvent: {
-    id: string;
-  };
-}
-
-// Error event - fatal errors (v1.2.0+)
-interface SearchViewErrorEvent {
-  nativeEvent: {
-    category: 'module_unavailable' | 'validation_failed' | 'image_load_failed' | 'unknown';
-    message: string;
-    context?: string;
-  };
-}
-
-// Validation warning - non-fatal issues (v1.2.0+)
-interface ValidationWarningEvent {
-  nativeEvent: {
-    type: 'field_truncated' | 'value_clamped' | 'url_invalid' | 'validation_failed';
-    message: string;
-    context?: string;
-  };
-}
-
-// Search result shape
-interface SearchResult {
-  id: string;           // Required, max 500 chars
-  title: string;        // Required, max 500 chars
-  subtitle?: string;    // Optional, max 500 chars
-  imageUrl?: string;    // Optional, HTTPS recommended
-}
-```
-
-### Typed Usage
-
-```typescript
-const handleSearch = (event: SearchEvent) => {
-  const query = event.nativeEvent.query;
-  // TypeScript knows query is a string
-};
-
-const handleSelect = (event: SelectItemEvent) => {
-  const id = event.nativeEvent.id;
-  // TypeScript knows id is a string
-};
-
-const handleError = (event: SearchViewErrorEvent) => {
-  const { category, message, context } = event.nativeEvent;
-  // Full autocomplete for category values
-  if (category === 'image_load_failed') {
-    logger.warn(`Image failed to load: ${message}`, { context });
-  }
-};
-```
-
-## Demo Apps & Examples
-
-### Official Demo App
-
-**[expo-tvos-search-demo](https://github.com/keiver/expo-tvos-search-demo)** - Complete working examples with 7 different layout styles. Browse the [source code](https://github.com/keiver/expo-tvos-search-demo/tree/main/app/(tabs)) for each configuration.
-
-### Apps Using This Library
-
-**[Tomo TV](https://github.com/keiver/tomotv)** - Full-featured tvOS Jellyfin client
-- Real-world integration with media library API
-- Advanced search with live server calls
-- Complete authentication and navigation flow
-
-## See it in action:
-
 <p align="center">
-  <img src="screenshots/expo-tvos-search.gif" width="700" alt="expo-tvos-search screen in action" loading="lazy" />
+  <img src="screenshots/results.png" alt="Results for search screen using expo-tvos-search" style="border-radius: 16px;max-width: 100%;"/><br/>
 </p>
 
 ## Props
@@ -415,7 +287,8 @@ const handleError = (event: SearchViewErrorEvent) => {
 |------|------|---------|-------------|
 | `results` | `SearchResult[]` | `[]` | Array of search results |
 | `columns` | `number` | `5` | Number of columns in the grid |
-| `placeholder` | `string` | `"Search movies and videos..."` | Search field placeholder |
+| `placeholder` | `string` | `"Search..."` | Search field placeholder |
+| `searchText` | `string` | — | Programmatically set search field text (restore state, deep links) |
 | `isLoading` | `boolean` | `false` | Shows loading indicator |
 
 ### Card Dimensions & Spacing
@@ -457,7 +330,7 @@ const handleError = (event: SearchViewErrorEvent) => {
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `emptyStateText` | `string` | `"Search for movies and videos"` | Text shown when search field is empty |
+| `emptyStateText` | `string` | `"Search your library"` | Text shown when search field is empty |
 | `searchingText` | `string` | `"Searching..."` | Text shown during search |
 | `noResultsText` | `string` | `"No results found"` | Text shown when no results found |
 | `noResultsHintText` | `string` | `"Try a different search term"` | Hint text below no results message |
@@ -470,6 +343,8 @@ const handleError = (event: SearchViewErrorEvent) => {
 | `onSelectItem` | `function` | required | Called when result is selected |
 | `onError` | `function` | optional | **(v1.2.0+)** Called when errors occur (image loading failures, validation errors) |
 | `onValidationWarning` | `function` | optional | **(v1.2.0+)** Called for non-fatal warnings (truncated fields, clamped values, invalid URLs) |
+| `onSearchFieldFocused` | `function` | optional | **(v1.3.2+)** Called when native search field gains focus. Use with `TVEventControl` for Apple TV hardware keyboard support. |
+| `onSearchFieldBlurred` | `function` | optional | **(v1.3.2+)** Called when native search field loses focus. Use to re-enable gesture handlers. |
 
 ### Other
 
@@ -477,127 +352,15 @@ const handleError = (event: SearchViewErrorEvent) => {
 |------|------|---------|-------------|
 | `style` | `ViewStyle` | optional | Style object for the view container |
 
-## SearchResult Type
-
-```typescript
-interface SearchResult {
-  id: string;
-  title: string;
-  subtitle?: string;
-  imageUrl?: string;
-}
-```
-
 ## Result Handling
 
 The native implementation applies the following validation and constraints:
 
 - **Maximum results**: The results array is capped at 500 items. Any results beyond this limit are silently ignored.
 - **Required fields**: Results with empty `id` or `title` are automatically filtered out and not displayed.
-- **Image URL schemes**: Only HTTP and HTTPS URLs are accepted for `imageUrl`. Other URL schemes (e.g., `file://`, `data:`) are rejected.
+- **Image URL schemes**: HTTP, HTTPS, and `data:` URIs are accepted for `imageUrl`. Other URL schemes (e.g., `file://`) are rejected.
 - **HTTPS recommended**: HTTP URLs may be blocked by App Transport Security on tvOS unless explicitly allowed in Info.plist.
 
-## Focus Handling - Do's and Don'ts
-
-The native `.searchable` modifier manages focus automatically. Here's what to do and what to avoid:
-
-### ✅ Do: Render directly in your screen
-
-```tsx
-function SearchScreen() {
-  return (
-    <TvosSearchView
-      results={results}
-      onSearch={handleSearch}
-      onSelectItem={handleSelect}
-      style={{ flex: 1 }}
-    />
-  );
-}
-```
-
-### ❌ Don't: Wrap in focusable containers
-
-```tsx
-// ❌ WRONG - breaks focus navigation
-function SearchScreen() {
-  return (
-    <Pressable>  {/* Don't wrap in Pressable */}
-      <TvosSearchView ... />
-    </Pressable>
-  );
-}
-
-// ❌ WRONG - interferes with native focus
-function SearchScreen() {
-  return (
-    <TouchableOpacity>  {/* Don't wrap in TouchableOpacity */}
-      <TvosSearchView ... />
-    </TouchableOpacity>
-  );
-}
-```
-
-**Why this breaks**: Focusable wrappers steal focus from the native SwiftUI search container, which breaks directional navigation.
-
-### ✅ Do: Use non-interactive containers
-
-```tsx
-// ✅ CORRECT - View is not focusable
-function SearchScreen() {
-  return (
-    <View style={{ flex: 1, backgroundColor: '#000' }}>
-      <TvosSearchView ... />
-    </View>
-  );
-}
-
-// ✅ CORRECT - SafeAreaView is not focusable
-function SearchScreen() {
-  return (
-    <SafeAreaView style={{ flex: 1 }}>
-      <TvosSearchView ... />
-    </SafeAreaView>
-  );
-}
-```
-
-## Troubleshooting
-
-### Native module not found
-
-If you see `requireNativeViewManager("ExpoTvosSearch") returned null`, the native module hasn't been built:
-
-```bash
-# Clean and rebuild with tvOS support
-EXPO_TV=1 npx expo prebuild --clean
-npx expo run:ios
-```
-
-**Note:** Expo Go doesn't support this. Build a dev client or native build instead.
-
-### Images not loading
-
-1. Verify your image URLs are HTTPS (HTTP may be blocked by App Transport Security)
-2. Ensure required authentication parameters are included in image URLs
-3. For local development, ensure your server is accessible from the Apple TV
-
-### Focus issues
-
-If focus doesn't move correctly:
-
-1. Ensure `columns` prop matches your layout (default: 5)
-2. Check `topInset` if the first row is hidden under the tab bar
-3. The native `.searchable` modifier handles focus automatically - avoid wrapping in focusable containers
-
-### Marquee not scrolling
-
-If long titles don't scroll when focused:
-
-1. Verify `enableMarquee={true}` (default)
-2. Check `marqueeDelay` - scrolling starts after this delay (default: 1.5s)
-3. Text only scrolls if it overflows the card width
-
 ## Testing
 
 Run TypeScript tests:
@@ -609,6 +372,7 @@ npm run test:coverage   # Generate coverage report
 ```
 
 Tests cover:
+
 - `isNativeSearchAvailable()` behavior on different platforms
 - Component rendering when native module is unavailable
 - Event structure validation
@@ -616,6 +380,7 @@ Tests cover:
 ## Contributing
 
 We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on:
+
 - Code of conduct
 - Development setup
 - Testing requirements
@@ -628,4 +393,4 @@ If you're adding new props to the library, follow the comprehensive checklist in
 
 ## License
 
-MIT
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/build/index.d.ts

@@ -45,13 +45,21 @@ export interface SearchViewErrorEvent {
 export interface ValidationWarningEvent {
     nativeEvent: {
         /** Type of validation warning */
-        type: "field_truncated" | "value_clamped" | "url_invalid" | "validation_failed";
+        type: "field_truncated" | "value_clamped" | "value_truncated" | "results_truncated" | "url_invalid" | "url_insecure" | "validation_failed";
         /** Human-readable warning message */
         message: string;
         /** Optional additional context */
         context?: string;
     };
 }
+/**
+ * Event payload for search field focus changes.
+ * Fired when the native search field gains or loses focus.
+ * Useful for managing RN gesture handlers via TVEventControl.
+ */
+export interface SearchFieldFocusEvent {
+    nativeEvent: Record<string, never>;
+}
 /**
  * Represents a single search result displayed in the grid.
  */
@@ -62,7 +70,7 @@ export interface SearchResult {
     title: string;
     /** Optional secondary text displayed below the title */
     subtitle?: string;
-    /** Optional image URL for the result poster/thumbnail */
+    /** Optional image URL for the result poster/thumbnail. Supports HTTPS, HTTP, and data: URIs */
     imageUrl?: string;
 }
 /**
@@ -73,7 +81,7 @@ export interface SearchResult {
  * <TvosSearchView
  *   results={searchResults}
  *   columns={5}
- *   placeholder="Search movies..."
+ *   placeholder="Search..."
  *   isLoading={loading}
  *   topInset={140}
  *   onSearch={(e) => handleSearch(e.nativeEvent.query)}
@@ -101,9 +109,20 @@ export interface TvosSearchViewProps {
     columns?: number;
     /**
      * Placeholder text shown in the search field when empty.
-     * @default "Search movies and videos..."
+     * @default "Search..."
      */
     placeholder?: string;
+    /**
+     * Programmatically set the search field text.
+     * Works like React Native TextInput's `value` + `onChangeText` pattern.
+     * Useful for restoring search state, deep links, or "search for similar" flows.
+     *
+     * **Warning:** Avoid setting `searchText` inside your `onSearch` handler with
+     * transforms (e.g., trimming, lowercasing). The native guard only prevents
+     * same-value loops — transformed values will trigger a new `onSearch` event,
+     * creating an infinite update cycle.
+     */
+    searchText?: string;
     /**
      * Whether to show a loading indicator.
      * @default false
@@ -155,7 +174,7 @@ export interface TvosSearchViewProps {
     marqueeDelay?: number;
     /**
      * Text displayed when the search field is empty and no results are shown.
-     * @default "Search for movies and videos"
+     * @default "Search your library"
      */
     emptyStateText?: string;
     /**
@@ -231,6 +250,9 @@ export interface TvosSearchViewProps {
     /**
      * Callback fired when the search text changes.
      * Debounce this handler to avoid excessive API calls.
+     *
+     * **Note:** If using the `searchText` prop, do not set it to a transformed
+     * value inside this handler — see `searchText` docs for loop prevention.
      */
     onSearch: (event: SearchEvent) => void;
     /**
@@ -262,6 +284,36 @@ export interface TvosSearchViewProps {
      * ```
      */
     onValidationWarning?: (event: ValidationWarningEvent) => void;
+    /**
+     * Optional callback fired when the native search field gains focus.
+     * Use this to disable RN gesture handlers via TVEventControl if the
+     * automatic gesture handling doesn't work on your device.
+     *
+     * @example
+     * ```tsx
+     * import { TVEventControl } from 'react-native';
+     *
+     * onSearchFieldFocused={() => {
+     *   TVEventControl.disableGestureHandlersCancelTouches();
+     * }}
+     * ```
+     */
+    onSearchFieldFocused?: (event: SearchFieldFocusEvent) => void;
+    /**
+     * Optional callback fired when the native search field loses focus.
+     * Use this to re-enable RN gesture handlers via TVEventControl if you
+     * disabled them in onSearchFieldFocused.
+     *
+     * @example
+     * ```tsx
+     * import { TVEventControl } from 'react-native';
+     *
+     * onSearchFieldBlurred={() => {
+     *   TVEventControl.enableGestureHandlersCancelTouches();
+     * }}
+     * ```
+     */
+    onSearchFieldBlurred?: (event: SearchFieldFocusEvent) => void;
     /**
      * Optional style for the view container.
      */