expo-tvos-search 1.2.0

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "expo-tvos-search",
+  "version": "1.2.0",
+  "description": "Native tvOS search view using SwiftUI .searchable modifier for Expo/React Native",
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/keiver/expo-tvos-search.git"
+  },
+  "homepage": "https://github.com/keiver/expo-tvos-search#readme",
+  "bugs": {
+    "url": "https://github.com/keiver/expo-tvos-search/issues"
+  },
+  "author": {
+    "name": "Keiver Hernandez",
+    "url": "https://github.com/keiver"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf build",
+    "prepublishOnly": "npm run clean && npm run build",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage"
+  },
+  "keywords": [
+    "expo",
+    "expo-module",
+    "tvos",
+    "appletv",
+    "apple-tv",
+    "search",
+    "swiftui",
+    "searchable",
+    "react-native",
+    "react-native-tvos"
+  ],
+  "peerDependencies": {
+    "expo": ">=51.0.0",
+    "expo-modules-core": ">=1.0.0",
+    "react": ">=18.0.0",
+    "react-native": "*"
+  },
+  "peerDependenciesMeta": {
+    "react-native": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/react": "^18.2.0",
+    "@types/react-native": "^0.72.0",
+    "expo-modules-core": "~3.0.25",
+    "jest": "^29.7.0",
+    "react": "^18.2.0",
+    "react-native": "^0.74.0",
+    "ts-jest": "^29.4.6",
+    "typescript": "~5.3.0"
+  },
+  "files": [
+    "build",
+    "src",
+    "ios",
+    "expo-module.config.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/__tests__/__mocks__/expo-modules-core.ts

@@ -0,0 +1,21 @@
+/**
+ * Mock expo-modules-core module for testing
+ * Uses global state to persist mock values across module resets
+ */
+
+declare global {
+  var __mockNativeViewAvailable: boolean;
+}
+
+// Only initialize if not already set (allows persistence across module resets)
+if (globalThis.__mockNativeViewAvailable === undefined) {
+  globalThis.__mockNativeViewAvailable = false;
+}
+
+export const requireNativeViewManager = (_name: string) => {
+  if (globalThis.__mockNativeViewAvailable) {
+    // Return a mock component function
+    return () => null;
+  }
+  return null;
+};

package/src/__tests__/__mocks__/react-native.ts

@@ -0,0 +1,41 @@
+/**
+ * Mock react-native module for testing
+ * Uses global state to persist mock values across module resets
+ */
+
+// Global state for Platform mock - only initialize if not already set
+declare global {
+  var __mockPlatformOS: 'ios' | 'android' | 'web';
+  var __mockPlatformIsTV: boolean;
+}
+
+// Only initialize if not already set (allows persistence across module resets)
+if (globalThis.__mockPlatformOS === undefined) {
+  globalThis.__mockPlatformOS = 'web';
+}
+if (globalThis.__mockPlatformIsTV === undefined) {
+  globalThis.__mockPlatformIsTV = false;
+}
+
+export const Platform = {
+  get OS() {
+    return globalThis.__mockPlatformOS;
+  },
+  set OS(value: 'ios' | 'android' | 'web') {
+    globalThis.__mockPlatformOS = value;
+  },
+  get isTV() {
+    return globalThis.__mockPlatformIsTV;
+  },
+  set isTV(value: boolean) {
+    globalThis.__mockPlatformIsTV = value;
+  },
+  select: <T>(options: { ios?: T; android?: T; web?: T; default?: T }): T | undefined => {
+    return options.default ?? options.web;
+  },
+};
+
+export interface ViewStyle {
+  flex?: number;
+  [key: string]: unknown;
+}

package/src/__tests__/events.test.ts

@@ -0,0 +1,126 @@
+/**
+ * Tests for event structure validation
+ *
+ * These tests verify that event handlers receive correctly structured events
+ * matching the native Swift implementation in ExpoTvosSearchView.swift
+ */
+
+describe('onSearch event structure', () => {
+  it('provides query in nativeEvent', () => {
+    const mockHandler = jest.fn();
+    const event = { nativeEvent: { query: 'test search' } };
+
+    mockHandler(event);
+
+    expect(mockHandler).toHaveBeenCalledWith({
+      nativeEvent: { query: 'test search' },
+    });
+    expect(mockHandler.mock.calls[0][0].nativeEvent.query).toBe('test search');
+  });
+
+  it('handles empty query string', () => {
+    const mockHandler = jest.fn();
+    const event = { nativeEvent: { query: '' } };
+
+    mockHandler(event);
+
+    expect(mockHandler.mock.calls[0][0].nativeEvent.query).toBe('');
+  });
+
+  it('handles special characters in query', () => {
+    const mockHandler = jest.fn();
+    const specialQueries = [
+      'The Matrix: Reloaded',
+      "Ocean's Eleven",
+      'Amélie',
+      '日本語タイトル',
+      'Film & TV',
+      'Movie (2023)',
+      '50% Off',
+    ];
+
+    specialQueries.forEach((query) => {
+      mockHandler({ nativeEvent: { query } });
+    });
+
+    expect(mockHandler).toHaveBeenCalledTimes(specialQueries.length);
+    specialQueries.forEach((query, index) => {
+      expect(mockHandler.mock.calls[index][0].nativeEvent.query).toBe(query);
+    });
+  });
+
+  it('handles whitespace in query', () => {
+    const mockHandler = jest.fn();
+    const queries = ['  leading', 'trailing  ', '  both  ', 'multiple   spaces'];
+
+    queries.forEach((query) => {
+      mockHandler({ nativeEvent: { query } });
+    });
+
+    expect(mockHandler).toHaveBeenCalledTimes(queries.length);
+  });
+});
+
+describe('onSelectItem event structure', () => {
+  it('provides id in nativeEvent', () => {
+    const mockHandler = jest.fn();
+    const event = { nativeEvent: { id: 'item-123' } };
+
+    mockHandler(event);
+
+    expect(mockHandler).toHaveBeenCalledWith({
+      nativeEvent: { id: 'item-123' },
+    });
+    expect(mockHandler.mock.calls[0][0].nativeEvent.id).toBe('item-123');
+  });
+
+  it('handles various id formats', () => {
+    const mockHandler = jest.fn();
+    const ids = [
+      'simple-id',
+      '12345',
+      'uuid-a1b2c3d4-e5f6-7890',
+      'jellyfin/Items/abc123',
+      'item:with:colons',
+    ];
+
+    ids.forEach((id) => {
+      mockHandler({ nativeEvent: { id } });
+    });
+
+    expect(mockHandler).toHaveBeenCalledTimes(ids.length);
+    ids.forEach((id, index) => {
+      expect(mockHandler.mock.calls[index][0].nativeEvent.id).toBe(id);
+    });
+  });
+});
+
+describe('event handler integration', () => {
+  it('simulates full search flow', () => {
+    const onSearch = jest.fn();
+    const onSelectItem = jest.fn();
+
+    // User types search query
+    onSearch({ nativeEvent: { query: 'matrix' } });
+    expect(onSearch).toHaveBeenCalledTimes(1);
+
+    // User refines search
+    onSearch({ nativeEvent: { query: 'matrix reloaded' } });
+    expect(onSearch).toHaveBeenCalledTimes(2);
+
+    // User selects a result
+    onSelectItem({ nativeEvent: { id: 'movie-456' } });
+    expect(onSelectItem).toHaveBeenCalledTimes(1);
+    expect(onSelectItem.mock.calls[0][0].nativeEvent.id).toBe('movie-456');
+  });
+
+  it('simulates clearing search', () => {
+    const onSearch = jest.fn();
+
+    onSearch({ nativeEvent: { query: 'test' } });
+    onSearch({ nativeEvent: { query: '' } });
+
+    expect(onSearch).toHaveBeenCalledTimes(2);
+    expect(onSearch.mock.calls[1][0].nativeEvent.query).toBe('');
+  });
+});

package/src/__tests__/index.test.tsx

@@ -0,0 +1,124 @@
+/**
+ * Tests for expo-tvos-search TypeScript exports
+ *
+ * Note: Platform checks in index.tsx run at module load time.
+ * These tests verify the behavior when mocked Platform values are set
+ * before the module is required.
+ */
+
+import {
+  mockTvOSPlatform,
+  mockWebPlatform,
+  mockNativeModuleAvailable,
+  mockNativeModuleUnavailable,
+} from './setup';
+
+describe('isNativeSearchAvailable', () => {
+  describe('on non-tvOS platforms', () => {
+    beforeEach(() => {
+      jest.resetModules();
+      mockWebPlatform();
+      mockNativeModuleUnavailable();
+    });
+
+    it('returns false when not on tvOS', () => {
+      const { isNativeSearchAvailable } = require('../index');
+      expect(isNativeSearchAvailable()).toBe(false);
+    });
+  });
+
+  describe('on tvOS without native module', () => {
+    beforeEach(() => {
+      jest.resetModules();
+      mockTvOSPlatform();
+      mockNativeModuleUnavailable();
+    });
+
+    it('returns false when native module unavailable', () => {
+      const { isNativeSearchAvailable } = require('../index');
+      expect(isNativeSearchAvailable()).toBe(false);
+    });
+  });
+
+  describe('on tvOS with native module', () => {
+    beforeEach(() => {
+      jest.resetModules();
+      mockTvOSPlatform();
+      mockNativeModuleAvailable();
+    });
+
+    it('returns true when native module is available', () => {
+      const { isNativeSearchAvailable } = require('../index');
+      expect(isNativeSearchAvailable()).toBe(true);
+    });
+  });
+});
+
+describe('TvosSearchView', () => {
+  beforeEach(() => {
+    jest.resetModules();
+    mockWebPlatform();
+    mockNativeModuleUnavailable();
+  });
+
+  it('returns null when native module is unavailable', () => {
+    const { TvosSearchView } = require('../index');
+    const result = TvosSearchView({
+      results: [],
+      onSearch: jest.fn(),
+      onSelectItem: jest.fn(),
+    });
+    expect(result).toBeNull();
+  });
+});
+
+describe('SearchResult interface', () => {
+  it('accepts valid SearchResult objects', () => {
+    const validResult = {
+      id: 'test-123',
+      title: 'Test Movie',
+      subtitle: 'Optional subtitle',
+      imageUrl: 'https://example.com/poster.jpg',
+    };
+
+    expect(validResult.id).toBe('test-123');
+    expect(validResult.title).toBe('Test Movie');
+    expect(validResult.subtitle).toBe('Optional subtitle');
+    expect(validResult.imageUrl).toBe('https://example.com/poster.jpg');
+  });
+
+  it('accepts SearchResult with only required fields', () => {
+    const minimalResult = {
+      id: 'minimal-123',
+      title: 'Minimal Movie',
+    };
+
+    expect(minimalResult.id).toBe('minimal-123');
+    expect(minimalResult.title).toBe('Minimal Movie');
+  });
+});
+
+describe('TvosSearchViewProps defaults', () => {
+  it('all optional props have documented defaults', () => {
+    // This test documents the expected default values
+    // The actual defaults are applied in Swift (ExpoTvosSearchView.swift)
+    const expectedDefaults = {
+      columns: 5,
+      placeholder: 'Search...',
+      isLoading: false,
+      showTitle: false,
+      showSubtitle: false,
+      showFocusBorder: false,
+      topInset: 0,
+      showTitleOverlay: true,
+      enableMarquee: true,
+      marqueeDelay: 1.5,
+    };
+
+    // Verify default documentation matches Swift implementation
+    expect(expectedDefaults.columns).toBe(5);
+    expect(expectedDefaults.showTitleOverlay).toBe(true);
+    expect(expectedDefaults.enableMarquee).toBe(true);
+    expect(expectedDefaults.marqueeDelay).toBe(1.5);
+  });
+});

package/src/__tests__/setup.ts

@@ -0,0 +1,49 @@
+/**
+ * Jest test setup - helper functions for platform mocking
+ * Uses global state to persist mock values across module resets
+ */
+
+// Import mocks to initialize globals
+import './__mocks__/react-native';
+import './__mocks__/expo-modules-core';
+
+// Helper to simulate tvOS platform
+export function mockTvOSPlatform(): void {
+  globalThis.__mockPlatformOS = 'ios';
+  globalThis.__mockPlatformIsTV = true;
+}
+
+// Helper to simulate iOS (non-TV) platform
+export function mockIOSPlatform(): void {
+  globalThis.__mockPlatformOS = 'ios';
+  globalThis.__mockPlatformIsTV = false;
+}
+
+// Helper to simulate web platform
+export function mockWebPlatform(): void {
+  globalThis.__mockPlatformOS = 'web';
+  globalThis.__mockPlatformIsTV = false;
+}
+
+// Helper to simulate Android platform
+export function mockAndroidPlatform(): void {
+  globalThis.__mockPlatformOS = 'android';
+  globalThis.__mockPlatformIsTV = false;
+}
+
+// Helper to mock native module as available
+export function mockNativeModuleAvailable(): void {
+  globalThis.__mockNativeViewAvailable = true;
+}
+
+// Helper to mock native module as unavailable
+export function mockNativeModuleUnavailable(): void {
+  globalThis.__mockNativeViewAvailable = false;
+}
+
+// Reset mocks between tests
+beforeEach(() => {
+  jest.resetModules();
+  mockWebPlatform();
+  mockNativeModuleUnavailable();
+});

package/src/index.tsx

@@ -0,0 +1,261 @@
+import React from "react";
+import { ViewStyle, Platform } from "react-native";
+
+/**
+ * Event payload for search text changes.
+ * Fired when the user types in the native search field.
+ */
+export interface SearchEvent {
+  nativeEvent: {
+    /** The current search query string entered by the user */
+    query: string;
+  };
+}
+
+/**
+ * Event payload for item selection.
+ * Fired when the user selects a search result.
+ */
+export interface SelectItemEvent {
+  nativeEvent: {
+    /** The unique identifier of the selected search result */
+    id: string;
+  };
+}
+
+/**
+ * Represents a single search result displayed in the grid.
+ */
+export interface SearchResult {
+  /** Unique identifier for the result (used in onSelectItem callback) */
+  id: string;
+  /** Primary display text for the result */
+  title: string;
+  /** Optional secondary text displayed below the title */
+  subtitle?: string;
+  /** Optional image URL for the result poster/thumbnail */
+  imageUrl?: string;
+}
+
+/**
+ * Props for the TvosSearchView component.
+ *
+ * @example
+ * ```tsx
+ * <TvosSearchView
+ *   results={searchResults}
+ *   columns={5}
+ *   placeholder="Search movies..."
+ *   isLoading={loading}
+ *   topInset={140}
+ *   onSearch={(e) => handleSearch(e.nativeEvent.query)}
+ *   onSelectItem={(e) => navigateTo(e.nativeEvent.id)}
+ *   style={{ flex: 1 }}
+ * />
+ * ```
+ */
+export interface TvosSearchViewProps {
+  /**
+   * Array of search results to display in the grid.
+   * Each result should have a unique `id`.
+   * Arrays larger than 500 items are truncated.
+   * Results with empty `id` or `title` are skipped.
+   * @maximum 500
+   */
+  results: SearchResult[];
+
+  /**
+   * Number of columns in the results grid.
+   * Values outside 1-10 range are clamped.
+   * @default 5
+   * @minimum 1
+   * @maximum 10
+   */
+  columns?: number;
+
+  /**
+   * Placeholder text shown in the search field when empty.
+   * @default "Search..."
+   */
+  placeholder?: string;
+
+  /**
+   * Whether to show a loading indicator.
+   * @default false
+   */
+  isLoading?: boolean;
+
+  /**
+   * Show title text below each result card.
+   * @default false
+   */
+  showTitle?: boolean;
+
+  /**
+   * Show subtitle text below title.
+   * Requires `showTitle` to be true to be visible.
+   * @default false
+   */
+  showSubtitle?: boolean;
+
+  /**
+   * Show gold border on focused card.
+   * @default false
+   */
+  showFocusBorder?: boolean;
+
+  /**
+   * Extra top padding in points for tab bar clearance.
+   * Useful when the view is displayed under a navigation bar.
+   * Values outside 0-500 range are clamped.
+   * @default 0
+   * @minimum 0
+   * @maximum 500
+   */
+  topInset?: number;
+
+  /**
+   * Show title overlay with gradient at bottom of card.
+   * This displays the title on top of the image.
+   * @default true
+   */
+  showTitleOverlay?: boolean;
+
+  /**
+   * Enable marquee scrolling for long titles that overflow the card width.
+   * @default true
+   */
+  enableMarquee?: boolean;
+
+  /**
+   * Delay in seconds before marquee starts scrolling when item is focused.
+   * Values outside 0-60 range are clamped.
+   * @default 1.5
+   * @minimum 0
+   * @maximum 60
+   */
+  marqueeDelay?: number;
+
+  /**
+   * Text displayed when the search field is empty and no results are shown.
+   * @default "Search for movies and videos"
+   */
+  emptyStateText?: string;
+
+  /**
+   * Text displayed while searching (when loading with no results yet).
+   * @default "Searching..."
+   */
+  searchingText?: string;
+
+  /**
+   * Text displayed when search returns no results.
+   * @default "No results found"
+   */
+  noResultsText?: string;
+
+  /**
+   * Hint text displayed below the no results message.
+   * @default "Try a different search term"
+   */
+  noResultsHintText?: string;
+
+  /**
+   * Callback fired when the search text changes.
+   * Debounce this handler to avoid excessive API calls.
+   */
+  onSearch: (event: SearchEvent) => void;
+
+  /**
+   * Callback fired when a search result is selected.
+   * Use the `id` from the event to identify which result was selected.
+   */
+  onSelectItem: (event: SelectItemEvent) => void;
+
+  /**
+   * Optional style for the view container.
+   */
+  style?: ViewStyle;
+}
+
+// Safely try to load the native view - it may not be available if:
+// 1. Running on a non-tvOS platform
+// 2. Native module hasn't been built yet (needs expo prebuild)
+// 3. expo-modules-core isn't properly installed
+let NativeView: React.ComponentType<TvosSearchViewProps> | null = null;
+
+if (Platform.OS === "ios" && Platform.isTV) {
+  try {
+    const { requireNativeViewManager } = require("expo-modules-core");
+    if (typeof requireNativeViewManager === "function") {
+      NativeView = requireNativeViewManager("ExpoTvosSearch");
+    }
+  } catch {
+    // Native module not available - will fall back to React Native implementation
+  }
+}
+
+/**
+ * Native tvOS search view component using SwiftUI's `.searchable` modifier.
+ *
+ * This component provides a native search experience on tvOS with proper focus
+ * handling and keyboard navigation. On non-tvOS platforms or when the native
+ * module is unavailable, it renders `null` - use `isNativeSearchAvailable()`
+ * to check availability and render a fallback.
+ *
+ * @example
+ * ```tsx
+ * import { TvosSearchView, isNativeSearchAvailable } from 'expo-tvos-search';
+ *
+ * function SearchScreen() {
+ *   const [results, setResults] = useState<SearchResult[]>([]);
+ *
+ *   if (!isNativeSearchAvailable()) {
+ *     return <FallbackSearchComponent />;
+ *   }
+ *
+ *   return (
+ *     <TvosSearchView
+ *       results={results}
+ *       onSearch={(e) => fetchResults(e.nativeEvent.query)}
+ *       onSelectItem={(e) => router.push(`/detail/${e.nativeEvent.id}`)}
+ *       style={{ flex: 1 }}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @param props - Component props
+ * @returns The native search view on tvOS, or `null` if unavailable
+ */
+export function TvosSearchView(props: TvosSearchViewProps) {
+  if (!NativeView) {
+    return null;
+  }
+  return <NativeView {...props} />;
+}
+
+/**
+ * Checks if the native tvOS search component is available.
+ *
+ * Returns `true` only when:
+ * - Running on tvOS (Platform.OS === "ios" && Platform.isTV)
+ * - The native module has been built (via `expo prebuild`)
+ * - expo-modules-core is properly installed
+ *
+ * Use this to conditionally render a fallback search implementation
+ * on non-tvOS platforms or when the native module is unavailable.
+ *
+ * @returns `true` if TvosSearchView will render, `false` if it will return null
+ *
+ * @example
+ * ```tsx
+ * if (!isNativeSearchAvailable()) {
+ *   return <ReactNativeSearchFallback />;
+ * }
+ * return <TvosSearchView {...props} />;
+ * ```
+ */
+export function isNativeSearchAvailable(): boolean {
+  return NativeView !== null;
+}