expo-tvos-search 1.3.0 → 1.4.0

package/src/__tests__/events.test.ts

@@ -95,6 +95,109 @@ describe('onSelectItem event structure', () => {
   });
 });
 
+describe('onSearchFieldFocused event structure', () => {
+  it('provides empty nativeEvent object', () => {
+    const mockHandler = jest.fn();
+    const event = { nativeEvent: {} };
+
+    mockHandler(event);
+
+    expect(mockHandler).toHaveBeenCalledWith({
+      nativeEvent: {},
+    });
+    expect(mockHandler.mock.calls[0][0].nativeEvent).toEqual({});
+  });
+
+  it('fires when search field gains focus', () => {
+    const onSearchFieldFocused = jest.fn();
+
+    // Native module fires focus event
+    onSearchFieldFocused({ nativeEvent: {} });
+
+    expect(onSearchFieldFocused).toHaveBeenCalledTimes(1);
+    expect(onSearchFieldFocused).toHaveBeenCalledWith({ nativeEvent: {} });
+  });
+});
+
+describe('onSearchFieldBlurred event structure', () => {
+  it('provides empty nativeEvent object', () => {
+    const mockHandler = jest.fn();
+    const event = { nativeEvent: {} };
+
+    mockHandler(event);
+
+    expect(mockHandler).toHaveBeenCalledWith({
+      nativeEvent: {},
+    });
+    expect(mockHandler.mock.calls[0][0].nativeEvent).toEqual({});
+  });
+
+  it('fires when search field loses focus', () => {
+    const onSearchFieldBlurred = jest.fn();
+
+    // Native module fires blur event
+    onSearchFieldBlurred({ nativeEvent: {} });
+
+    expect(onSearchFieldBlurred).toHaveBeenCalledTimes(1);
+    expect(onSearchFieldBlurred).toHaveBeenCalledWith({ nativeEvent: {} });
+  });
+});
+
+describe('search field focus integration', () => {
+  it('simulates focus/blur cycle for Apple TV keyboard input', () => {
+    const onSearchFieldFocused = jest.fn();
+    const onSearchFieldBlurred = jest.fn();
+    const onSearch = jest.fn();
+
+    // User focuses search field (keyboard appears)
+    onSearchFieldFocused({ nativeEvent: {} });
+    expect(onSearchFieldFocused).toHaveBeenCalledTimes(1);
+
+    // User types in search field
+    onSearch({ nativeEvent: { query: 'm' } });
+    onSearch({ nativeEvent: { query: 'ma' } });
+    onSearch({ nativeEvent: { query: 'mat' } });
+    expect(onSearch).toHaveBeenCalledTimes(3);
+
+    // User exits search field (keyboard dismissed)
+    onSearchFieldBlurred({ nativeEvent: {} });
+    expect(onSearchFieldBlurred).toHaveBeenCalledTimes(1);
+  });
+
+  it('handles multiple focus/blur cycles', () => {
+    const onSearchFieldFocused = jest.fn();
+    const onSearchFieldBlurred = jest.fn();
+
+    // First focus/blur cycle
+    onSearchFieldFocused({ nativeEvent: {} });
+    onSearchFieldBlurred({ nativeEvent: {} });
+
+    // Second focus/blur cycle
+    onSearchFieldFocused({ nativeEvent: {} });
+    onSearchFieldBlurred({ nativeEvent: {} });
+
+    // Third focus/blur cycle
+    onSearchFieldFocused({ nativeEvent: {} });
+    onSearchFieldBlurred({ nativeEvent: {} });
+
+    expect(onSearchFieldFocused).toHaveBeenCalledTimes(3);
+    expect(onSearchFieldBlurred).toHaveBeenCalledTimes(3);
+  });
+
+  it('does not require focus handlers to be provided', () => {
+    // These callbacks are optional - ensure no errors when undefined
+    const onSearch = jest.fn();
+    const onSelectItem = jest.fn();
+
+    // Simulate usage without focus callbacks
+    onSearch({ nativeEvent: { query: 'test' } });
+    onSelectItem({ nativeEvent: { id: 'item-1' } });
+
+    expect(onSearch).toHaveBeenCalledTimes(1);
+    expect(onSelectItem).toHaveBeenCalledTimes(1);
+  });
+});
+
 describe('event handler integration', () => {
   it('simulates full search flow', () => {
     const onSearch = jest.fn();
@@ -123,4 +226,29 @@ describe('event handler integration', () => {
     expect(onSearch).toHaveBeenCalledTimes(2);
     expect(onSearch.mock.calls[1][0].nativeEvent.query).toBe('');
   });
+
+  it('simulates full Apple TV search flow with focus handling', () => {
+    const onSearchFieldFocused = jest.fn();
+    const onSearchFieldBlurred = jest.fn();
+    const onSearch = jest.fn();
+    const onSelectItem = jest.fn();
+
+    // User navigates to search and focuses the field
+    onSearchFieldFocused({ nativeEvent: {} });
+
+    // User types search query using Siri Remote keyboard
+    onSearch({ nativeEvent: { query: 'matrix' } });
+    onSearch({ nativeEvent: { query: 'matrix reloaded' } });
+
+    // User exits keyboard to browse results
+    onSearchFieldBlurred({ nativeEvent: {} });
+
+    // User selects a result
+    onSelectItem({ nativeEvent: { id: 'movie-456' } });
+
+    expect(onSearchFieldFocused).toHaveBeenCalledTimes(1);
+    expect(onSearchFieldBlurred).toHaveBeenCalledTimes(1);
+    expect(onSearch).toHaveBeenCalledTimes(2);
+    expect(onSelectItem).toHaveBeenCalledTimes(1);
+  });
 });

package/src/__tests__/index.test.tsx

@@ -104,7 +104,7 @@ describe('TvosSearchViewProps defaults', () => {
     // The actual defaults are applied in Swift (ExpoTvosSearchView.swift)
     const expectedDefaults = {
       columns: 5,
-      placeholder: 'Search movies and videos...', // Matches Swift default
+      placeholder: 'Search...', // Matches Swift default
       isLoading: false,
       showTitle: false,
       showSubtitle: false,
@@ -542,11 +542,14 @@ describe('TvosSearchView with native module available', () => {
     const { TvosSearchView } = require('../index');
 
     const mockOnValidationWarning = jest.fn();
+    const mockOnSearchFieldFocused = jest.fn();
+    const mockOnSearchFieldBlurred = jest.fn();
 
     const result = TvosSearchView({
       results: [{ id: 'test', title: 'Test', subtitle: 'Sub', imageUrl: 'http://example.com/img.jpg' }],
       columns: 5,
       placeholder: 'Custom placeholder',
+      searchText: 'initial query',
       isLoading: false,
       showTitle: true,
       showSubtitle: true,
@@ -571,9 +574,52 @@ describe('TvosSearchView with native module available', () => {
       onSelectItem: jest.fn(),
       onError: jest.fn(),
       onValidationWarning: mockOnValidationWarning,
+      onSearchFieldFocused: mockOnSearchFieldFocused,
+      onSearchFieldBlurred: mockOnSearchFieldBlurred,
       style: { flex: 1 },
     });
 
     expect(result).not.toBeNull();
   });
+
+  it('renders without optional focus callbacks', () => {
+    const { TvosSearchView } = require('../index');
+
+    // onSearchFieldFocused and onSearchFieldBlurred are optional
+    const result = TvosSearchView({
+      results: [],
+      onSearch: jest.fn(),
+      onSelectItem: jest.fn(),
+      // Note: onSearchFieldFocused and onSearchFieldBlurred are not provided
+    });
+
+    expect(result).not.toBeNull();
+  });
+
+  it('accepts searchText prop', () => {
+    const { TvosSearchView } = require('../index');
+
+    const result = TvosSearchView({
+      results: [],
+      onSearch: jest.fn(),
+      onSelectItem: jest.fn(),
+      searchText: 'test query',
+    });
+
+    expect(result).not.toBeNull();
+  });
+
+  it('accepts undefined searchText prop', () => {
+    const { TvosSearchView } = require('../index');
+
+    const result = TvosSearchView({
+      results: [],
+      onSearch: jest.fn(),
+      onSelectItem: jest.fn(),
+      searchText: undefined,
+    });
+
+    expect(result).not.toBeNull();
+  });
 });
+

package/src/index.tsx

@@ -55,7 +55,7 @@ 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 */
@@ -63,6 +63,15 @@ export interface ValidationWarningEvent {
   };
 }
 
+/**
+ * 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.
  */
@@ -73,7 +82,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;
 }
 
@@ -85,7 +94,7 @@ export interface SearchResult {
  * <TvosSearchView
  *   results={searchResults}
  *   columns={5}
- *   placeholder="Search movies..."
+ *   placeholder="Search..."
  *   isLoading={loading}
  *   topInset={140}
  *   onSearch={(e) => handleSearch(e.nativeEvent.query)}
@@ -115,10 +124,22 @@ export interface TvosSearchViewProps {
 
   /**
    * 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
@@ -178,7 +199,7 @@ export interface TvosSearchViewProps {
 
   /**
    * 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;
 
@@ -266,6 +287,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;
 
@@ -301,6 +325,38 @@ 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.
    */