expo-tvos-search 1.2.3 → 1.3.0

package/README.md

@@ -3,6 +3,7 @@
 [![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. Handles focus, keyboard navigation, and accessibility out of the box.
 
@@ -27,7 +28,6 @@ A native tvOS search component for Expo and React Native using SwiftUI's `.searc
   </tr>
 </table>
 
-
 ## Installation
 
 ```bash
@@ -40,30 +40,114 @@ Or install from GitHub:
 npx expo install github:keiver/expo-tvos-search
 ```
 
-Then rebuild your native project:
+Then follow the **tvOS prerequisites** below and rebuild your native project.
+
+## 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
+```
+
+### 2. Install the tvOS config plugin
+
+Install:
+
+```bash
+npx expo install @react-native-tvos/config-tv
+```
+
+Then add the plugin in `app.json` / `app.config.js`:
+
+```json
+{
+  "expo": {
+    "plugins": ["@react-native-tvos/config-tv"]
+  }
+}
+```
+
+### 3. Generate native projects with tvOS enabled
 
 ```bash
 EXPO_TV=1 npx expo prebuild --clean
+```
+
+Then run:
+
+```bash
 npx expo run:ios
 ```
 
+### 4. Common gotchas
+
+- **Prebuild must be re-run** if you add/remove tvOS dependencies or change the tvOS plugin configuration.
+- **If you see App Transport Security errors** for images, ensure your `imageUrl` uses `https://` (recommended) or add the appropriate ATS exceptions.
+- **If the tvOS keyboard/search UI doesn't appear**, confirm you're actually running a tvOS target/simulator, not an iOS target.
+
 ## Usage
 
 ```tsx
-import { TvosSearchView, isNativeSearchAvailable } from 'expo-tvos-search';
-
-function SearchScreen() {
-  const [results, setResults] = useState([]);
+import React, { useState } from "react";
+import { Alert } from "react-native";
+import {
+  TvosSearchView,
+  isNativeSearchAvailable,
+  type SearchResult,
+} from "expo-tvos-search";
+
+const PLANETS: SearchResult[] = [
+  { id: "mercury", title: "Mercury", subtitle: "Smallest planet", imageUrl: "https://upload.wikimedia.org/wikipedia/commons/thumb/4/4a/Mercury_in_true_color.jpg/400px-Mercury_in_true_color.jpg" },
+  { id: "venus", title: "Venus", subtitle: "Hottest planet", imageUrl: "https://upload.wikimedia.org/wikipedia/commons/thumb/e/e5/Venus-real_color.jpg/400px-Venus-real_color.jpg" },
+  { id: "earth", title: "Earth", subtitle: "Our home", imageUrl: "https://upload.wikimedia.org/wikipedia/commons/thumb/9/97/The_Earth_seen_from_Apollo_17.jpg/400px-The_Earth_seen_from_Apollo_17.jpg" },
+  { id: "mars", title: "Mars", subtitle: "The red planet", imageUrl: "https://upload.wikimedia.org/wikipedia/commons/thumb/0/02/OSIRIS_Mars_true_color.jpg/400px-OSIRIS_Mars_true_color.jpg" },
+  { id: "jupiter", title: "Jupiter", subtitle: "Largest planet", imageUrl: "https://upload.wikimedia.org/wikipedia/commons/thumb/c/c1/Jupiter_New_Horizons.jpg/400px-Jupiter_New_Horizons.jpg" },
+  { id: "saturn", title: "Saturn", subtitle: "Ringed giant", imageUrl: "https://upload.wikimedia.org/wikipedia/commons/thumb/c/c7/Saturn_during_Equinox.jpg/400px-Saturn_during_Equinox.jpg" },
+  { id: "uranus", title: "Uranus", subtitle: "Ice giant", imageUrl: "https://upload.wikimedia.org/wikipedia/commons/thumb/3/3d/Uranus2.jpg/400px-Uranus2.jpg" },
+  { id: "neptune", title: "Neptune", subtitle: "Windiest planet", imageUrl: "https://upload.wikimedia.org/wikipedia/commons/thumb/6/63/Neptune_-_Voyager_2_%2829347980845%29_flatten_crop.jpg/400px-Neptune_-_Voyager_2_%2829347980845%29_flatten_crop.jpg" },
+];
+
+export function SearchScreen() {
+  const [results, setResults] = useState<SearchResult[]>([]);
   const [isLoading, setIsLoading] = useState(false);
 
-  const handleSearch = (event) => {
-    const query = event.nativeEvent.query;
-    // Fetch your results...
+  const handleSearch = (event: { nativeEvent: { query: string } }) => {
+    const { query } = event.nativeEvent;
+
+    if (!query.trim()) {
+      setResults([]);
+      return;
+    }
+
+    setIsLoading(true);
+
+    // Simulate async search
+    setTimeout(() => {
+      const filtered = PLANETS.filter((planet) =>
+        planet.title.toLowerCase().includes(query.toLowerCase()) ||
+        planet.subtitle?.toLowerCase().includes(query.toLowerCase())
+      );
+      setResults(filtered);
+      setIsLoading(false);
+    }, 300);
   };
 
-  const handleSelect = (event) => {
-    const id = event.nativeEvent.id;
-    // Navigate to detail...
+  const handleSelect = (event: { nativeEvent: { id: string } }) => {
+    const planet = PLANETS.find((p) => p.id === event.nativeEvent.id);
+    if (planet) {
+      Alert.alert(planet.title, planet.subtitle);
+    }
   };
 
   if (!isNativeSearchAvailable()) {
@@ -74,7 +158,7 @@ function SearchScreen() {
     <TvosSearchView
       results={results}
       columns={5}
-      placeholder="Search..."
+      placeholder="Search planets..."
       isLoading={isLoading}
       topInset={140}
       onSearch={handleSearch}
@@ -85,13 +169,146 @@ function SearchScreen() {
 }
 ```
 
+> **⚠️ IMPORTANT**: Always debounce the `onSearch` callback to prevent excessive API calls or expensive operations on every keystroke. In production apps, use a debounce library like lodash or implement your own debounce function:
+>
+> ```tsx
+> import { useMemo } from 'react';
+> import { debounce } from 'lodash'; // or your preferred debounce implementation
+>
+> function SearchScreen() {
+>   const [results, setResults] = useState([]);
+>
+>   const debouncedSearch = useMemo(
+>     () => debounce((query: string) => {
+>       // Your actual search logic (API call, etc.)
+>       fetchSearchResults(query).then(setResults);
+>     }, 300), // 300ms delay
+>     []
+>   );
+>
+>   return (
+>     <TvosSearchView
+>       results={results}
+>       onSearch={(e) => debouncedSearch(e.nativeEvent.query)}
+>       onSelectItem={handleSelect}
+>     />
+>   );
+> }
+> ```
+
+### Error Handling and Monitoring
+
+The library provides error and validation warning callbacks for production monitoring:
+
+```tsx
+<TvosSearchView
+  results={results}
+  onSearch={handleSearch}
+  onSelectItem={handleSelect}
+  onError={(e) => {
+    const { category, message, context } = e.nativeEvent;
+    // Log to your error monitoring service
+    console.error(`[Search Error] ${category}: ${message}`, context);
+    // Examples: 'module_unavailable', 'validation_failed', 'image_load_failed', 'unknown'
+  }}
+  onValidationWarning={(e) => {
+    const { type, message, context } = e.nativeEvent;
+    // Log non-fatal issues for monitoring
+    console.warn(`[Validation] ${type}: ${message}`, context);
+    // Examples: 'field_truncated', 'value_clamped', 'url_invalid', 'validation_failed'
+  }}
+/>
+```
+
+These callbacks help you:
+- Monitor data quality issues (truncated fields, invalid URLs)
+- Track when props are clamped to safe ranges
+- Detect when results exceed the 500-item limit
+- Log errors for debugging in production
+
+### Customizing Colors and Card Dimensions
+
+You can customize the appearance of the search interface with color and dimension props:
+
+```tsx
+<TvosSearchView
+  results={results}
+  onSearch={handleSearch}
+  onSelectItem={handleSelect}
+  // Custom colors
+  textColor="#E5E5E5"      // Light gray text on dark background
+  accentColor="#E50914"    // Red focused borders (House Flix style 😂)
+  // Custom card dimensions
+  cardWidth={420}          // Landscape cards
+  cardHeight={240}         // 16:9 aspect ratio
+  style={{ flex: 1 }}
+/>
+```
+
+**Color props:**
+- `textColor` - Affects subtitle text, empty state text, and placeholder icons
+- `accentColor` - Affects focused card borders and highlights
+
+**Dimension props:**
+- Default: 280x420 (portrait, 2:3 aspect ratio)
+- Landscape example: 420x240 (16:9)
+- Square example: 300x300 (1:1)
+
+### Layout and Spacing Customization
+
+Control image display, card spacing, and overlay padding for different layouts:
+
+```tsx
+<TvosSearchView
+  results={results}
+  onSearch={handleSearch}
+  onSelectItem={handleSelect}
+  // Image display mode
+  imageContentMode="fit"      // 'fill' (default, crop), 'fit'/'contain' (letterbox)
+  // Card spacing
+  cardMargin={60}              // Space between cards (default: 40)
+  cardPadding={20}             // Padding inside overlay (default: 16)
+  style={{ flex: 1 }}
+/>
+```
+
+**Layout props:**
+- `imageContentMode` - How images fill cards:
+  - `'fill'` (default) - Crops image to fill entire card
+  - `'fit'` or `'contain'` - Shows entire image, may add letterboxing
+- `cardMargin` - Controls spacing between cards in the grid (both horizontal and vertical)
+- `cardPadding` - Controls padding inside the card's title overlay for better text spacing
+
+**Common use cases:**
+- **Portrait posters** (movie/TV): `imageContentMode="fill"` + `cardMargin={40}`
+- **Landscape thumbnails** (episodes): `imageContentMode="fit"` + `cardMargin={60}`
+- **Compact grid** (music): `cardMargin={20}` + `cardPadding={12}`
+- **Spacious layout** (photos): `cardMargin={60}` + `cardPadding={20}`
+
+## Example App
+
+**[Tomo TV](https://github.com/keiver/tomotv)** is a tvOS application that uses `expo-tvos-search` in a real-world Jellyfin client. It demonstrates the search component integrated with a complete media browsing experience, including:
+
+- Search interaction with tvOS remote
+- Focus navigation through results
+- Integration with a live media library
+- Complete setup instructions and screenshots
+
+Check out Tomo TV to see `expo-tvos-search` in action and reference its implementation for your own projects.
+
+## 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" />
+</p>
+
 ## Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `results` | `SearchResult[]` | `[]` | Array of search results |
 | `columns` | `number` | `5` | Number of columns in the grid |
-| `placeholder` | `string` | `"Search..."` | Search field placeholder |
+| `placeholder` | `string` | `"Search movies and videos..."` | Search field placeholder |
 | `isLoading` | `boolean` | `false` | Shows loading indicator |
 | `showTitle` | `boolean` | `false` | Show title below each result |
 | `showSubtitle` | `boolean` | `false` | Show subtitle below title |
@@ -104,8 +321,19 @@ function SearchScreen() {
 | `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 |
+| `textColor` | `string` | system default | Color for text and UI elements (hex format, e.g., "#FFFFFF") |
+| `accentColor` | `string` | `"#FFC312"` | Accent color for focused elements (hex format, e.g., "#FFC312") |
+| `cardWidth` | `number` | `280` | Width of each result card in points |
+| `cardHeight` | `number` | `420` | Height of each result card in points |
+| `imageContentMode` | `'fill' \| 'fit' \| 'contain'` | `'fill'` | How images fill the card: `fill` (crop to fill), `fit`/`contain` (letterbox) |
+| `cardMargin` | `number` | `40` | Spacing between cards in the grid (horizontal and vertical) |
+| `cardPadding` | `number` | `16` | Padding inside the card for overlay content (title/subtitle) |
+| `overlayTitleSize` | `number` | `20` | Font size for title text in the blur overlay (when showTitleOverlay is true) |
 | `onSearch` | `function` | required | Called when search text changes |
 | `onSelectItem` | `function` | required | Called when result is selected |
+| `onError` | `function` | optional | Called when errors occur (image loading failures, validation errors) |
+| `onValidationWarning` | `function` | optional | Called for non-fatal warnings (truncated fields, clamped values, invalid URLs) |
+| `style` | `ViewStyle` | optional | Style object for the view container |
 
 ## SearchResult Type
 
@@ -127,12 +355,77 @@ The native implementation applies the following validation and constraints:
 - **Image URL schemes**: Only HTTP and HTTPS URLs are accepted for `imageUrl`. Other URL schemes (e.g., `file://`, `data:`) 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>
+  );
+}
+```
+
 ## Requirements
 
-- Node.js 18.0+
+- Node.js 18+
 - Expo SDK 51+
-- tvOS 15.0+
-- React Native TVOS
+- tvOS 15+
+- Project configured for tvOS (`react-native-tvos` + `@react-native-tvos/config-tv`)
 
 ## Troubleshooting
 
@@ -146,6 +439,8 @@ 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)
@@ -183,6 +478,19 @@ Tests cover:
 - Component rendering when native module is unavailable
 - Event structure validation
 
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on:
+- Code of conduct
+- Development setup
+- Testing requirements
+- Commit message conventions
+- Pull request process
+
+### Adding New Props
+
+If you're adding new props to the library, follow the comprehensive checklist in [.claude/CLAUDE-adding-new-props.md](.claude/CLAUDE-adding-new-props.md). This memory bank provides a 9-step guide ensuring props are properly wired from TypeScript through to Swift rendering.
+
 ## License
 
 MIT

package/build/index.d.ts

@@ -1,5 +1,5 @@
-import React from "react";
-import { ViewStyle } from "react-native";
+/// <reference types="react" />
+import type { ViewStyle } from "react-native";
 /**
  * Event payload for search text changes.
  * Fired when the user types in the native search field.
@@ -20,6 +20,38 @@ export interface SelectItemEvent {
         id: string;
     };
 }
+/**
+ * Categories of errors that can occur in the search view.
+ */
+export type SearchViewErrorCategory = "module_unavailable" | "validation_failed" | "image_load_failed" | "unknown";
+/**
+ * Event payload for error callbacks.
+ * Provides details about errors that occur during search view operations.
+ */
+export interface SearchViewErrorEvent {
+    nativeEvent: {
+        /** Category of the error for programmatic handling */
+        category: SearchViewErrorCategory;
+        /** Human-readable error message */
+        message: string;
+        /** Optional additional context (e.g., result ID, URL) */
+        context?: string;
+    };
+}
+/**
+ * Event payload for validation warnings.
+ * Non-fatal issues like truncated fields or clamped values.
+ */
+export interface ValidationWarningEvent {
+    nativeEvent: {
+        /** Type of validation warning */
+        type: "field_truncated" | "value_clamped" | "url_invalid" | "validation_failed";
+        /** Human-readable warning message */
+        message: string;
+        /** Optional additional context */
+        context?: string;
+    };
+}
 /**
  * Represents a single search result displayed in the grid.
  */
@@ -69,7 +101,7 @@ export interface TvosSearchViewProps {
     columns?: number;
     /**
      * Placeholder text shown in the search field when empty.
-     * @default "Search..."
+     * @default "Search movies and videos..."
      */
     placeholder?: string;
     /**
@@ -141,6 +173,61 @@ export interface TvosSearchViewProps {
      * @default "Try a different search term"
      */
     noResultsHintText?: string;
+    /**
+     * Color for text and UI elements in the search interface.
+     * Hex color string (e.g., "#FFFFFF", "#E5E5E5").
+     * @default Uses system default based on userInterfaceStyle
+     * @example "#E5E5E5" for light gray text on dark background
+     */
+    textColor?: string;
+    /**
+     * Accent color for focused elements and highlights.
+     * Hex color string (e.g., "#FFC312").
+     * @default "#FFC312" (gold)
+     * @example "#E50914" for Netflix red
+     */
+    accentColor?: string;
+    /**
+     * Width of each result card in points.
+     * Allows customization for portrait, landscape, or square layouts.
+     * @default 280
+     * @example 420 for landscape cards
+     */
+    cardWidth?: number;
+    /**
+     * Height of each result card in points.
+     * Allows customization for portrait, landscape, or square layouts.
+     * @default 420
+     * @example 240 for landscape cards (16:9 ratio with width=420)
+     */
+    cardHeight?: number;
+    /**
+     * How the image fills the card area.
+     * - 'fill': Image fills entire card, may crop (default)
+     * - 'fit': Image fits within card, may show letterboxing
+     * - 'contain': Same as fit (alias for consistency)
+     * @default "fill"
+     */
+    imageContentMode?: 'fill' | 'fit' | 'contain';
+    /**
+     * Spacing between cards in the grid layout (both horizontal and vertical).
+     * @default 40
+     * @example 60 for spacious layouts, 20 for compact grids
+     */
+    cardMargin?: number;
+    /**
+     * Padding inside the card for overlay content (title, subtitle).
+     * @default 16
+     * @example 20 for more breathing room, 12 for compact cards
+     */
+    cardPadding?: number;
+    /**
+     * Font size for title in the blur overlay (when showTitleOverlay is true).
+     * Allows customization of overlay text size for different card layouts.
+     * @default 20
+     * @example 18 for smaller cards, 24 for larger cards
+     */
+    overlayTitleSize?: number;
     /**
      * Callback fired when the search text changes.
      * Debounce this handler to avoid excessive API calls.
@@ -151,6 +238,30 @@ export interface TvosSearchViewProps {
      * Use the `id` from the event to identify which result was selected.
      */
     onSelectItem: (event: SelectItemEvent) => void;
+    /**
+     * Optional callback fired when errors occur.
+     * Use this to monitor and log issues in production.
+     * @example
+     * ```tsx
+     * onError={(e) => {
+     *   const { category, message, context } = e.nativeEvent;
+     *   logger.error(`Search error [${category}]: ${message}`, { context });
+     * }}
+     * ```
+     */
+    onError?: (event: SearchViewErrorEvent) => void;
+    /**
+     * Optional callback fired for non-fatal validation warnings.
+     * Examples: truncated fields, clamped values, invalid URLs.
+     * @example
+     * ```tsx
+     * onValidationWarning={(e) => {
+     *   const { type, message } = e.nativeEvent;
+     *   console.warn(`Validation warning [${type}]: ${message}`);
+     * }}
+     * ```
+     */
+    onValidationWarning?: (event: ValidationWarningEvent) => void;
     /**
      * Optional style for the view container.
      */
@@ -189,7 +300,7 @@ export interface TvosSearchViewProps {
  * @param props - Component props
  * @returns The native search view on tvOS, or `null` if unavailable
  */
-export declare function TvosSearchView(props: TvosSearchViewProps): React.JSX.Element | null;
+export declare function TvosSearchView(props: TvosSearchViewProps): JSX.Element | null;
 /**
  * Checks if the native tvOS search component is available.
  *

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAY,MAAM,cAAc,CAAC;AAEnD;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE;QACX,0DAA0D;QAC1D,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE;QACX,0DAA0D;QAC1D,EAAE,EAAE,MAAM,CAAC;KACZ,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,EAAE,EAAE,MAAM,CAAC;IACX,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;OAMG;IACH,OAAO,EAAE,YAAY,EAAE,CAAC;IAExB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B;;;OAGG;IACH,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;IAEvC;;;OAGG;IACH,YAAY,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;IAE/C;;OAEG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAmBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,4BAKxD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,CAEjD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"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"}

package/build/index.js

@@ -1,9 +1,9 @@
 import React from "react";
 import { Platform } from "react-native";
-// 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
+/**
+ * Native view component loaded at module initialization.
+ * Returns null on non-tvOS platforms or when the native module is unavailable.
+ */
 let NativeView = null;
 if (Platform.OS === "ios" && Platform.isTV) {
     try {
@@ -11,9 +11,38 @@ if (Platform.OS === "ios" && Platform.isTV) {
         if (typeof requireNativeViewManager === "function") {
             NativeView = requireNativeViewManager("ExpoTvosSearch");
         }
+        else {
+            console.warn("[expo-tvos-search] requireNativeViewManager is not a function. " +
+                "This usually indicates an incompatible expo-modules-core version. " +
+                "Try reinstalling expo-modules-core or updating to a compatible version.");
+        }
     }
-    catch {
-        // Native module not available - will fall back to React Native implementation
+    catch (error) {
+        // Categorize the error to help with debugging
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        if (errorMessage.includes("expo-modules-core")) {
+            console.warn("[expo-tvos-search] Failed to load expo-modules-core. " +
+                "Make sure expo-modules-core is installed: npm install expo-modules-core\n" +
+                `Error: ${errorMessage}`);
+        }
+        else if (errorMessage.includes("ExpoTvosSearch")) {
+            console.warn("[expo-tvos-search] Native module ExpoTvosSearch not found. " +
+                "This usually means:\n" +
+                "1. You haven't run 'expo prebuild' yet, or\n" +
+                "2. The native project needs to be rebuilt (try 'expo prebuild --clean')\n" +
+                "3. You're not running on a tvOS simulator/device\n" +
+                `Error: ${errorMessage}`);
+        }
+        else {
+            // Unexpected error - log full details for debugging
+            console.warn("[expo-tvos-search] Unexpected error loading native module.\n" +
+                `Error: ${errorMessage}\n` +
+                "Please report this issue at: https://github.com/keiver/expo-tvos-search/issues");
+            // In development, log the full error for debugging
+            if (typeof __DEV__ !== "undefined" && __DEV__) {
+                console.error("[expo-tvos-search] Full error details:", error);
+            }
+        }
     }
 }
 /**
@@ -51,6 +80,25 @@ if (Platform.OS === "ios" && Platform.isTV) {
  */
 export function TvosSearchView(props) {
     if (!NativeView) {
+        // Warn in development when native module is unavailable
+        if (typeof __DEV__ !== "undefined" && __DEV__) {
+            const isRunningOnTvOS = Platform.OS === "ios" && Platform.isTV;
+            if (isRunningOnTvOS) {
+                // On tvOS but module failed to load - this is unexpected
+                console.warn("[expo-tvos-search] TvosSearchView is rendering null on tvOS. " +
+                    "This usually means:\n" +
+                    "1. The native module wasn't built properly (try 'expo prebuild --clean')\n" +
+                    "2. expo-modules-core is missing or incompatible\n" +
+                    "3. The app needs to be restarted after installing the module\n\n" +
+                    "Check the earlier console logs for specific error details.");
+            }
+            else {
+                // Not on tvOS - expected behavior, but developer might want to know
+                console.info("[expo-tvos-search] TvosSearchView is not available on " +
+                    `${Platform.OS}${Platform.isTV ? " (TV)" : ""}. ` +
+                    "Use isNativeSearchAvailable() to check before rendering this component.");
+            }
+        }
         return null;
     }
     return React.createElement(NativeView, { ...props });