expo-tvos-search 1.2.3 → 1.3.1

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 });

package/ios/ExpoTvosSearchModule.swift

@@ -12,17 +12,32 @@ public class ExpoTvosSearchModule: Module {
         Name("ExpoTvosSearch")
 
         View(ExpoTvosSearchView.self) {
-            Events("onSearch", "onSelectItem")
+            Events("onSearch", "onSelectItem", "onError", "onValidationWarning")
 
             Prop("results") { (view: ExpoTvosSearchView, results: [[String: Any]]) in
                 // Limit results array size to prevent memory issues
                 let limitedResults = Array(results.prefix(Self.maxResults))
+                if results.count > Self.maxResults {
+                    view.onValidationWarning([
+                        "type": "value_clamped",
+                        "message": "Results array truncated from \(results.count) to \(Self.maxResults) items",
+                        "context": "maxResults=\(Self.maxResults)"
+                    ])
+                }
                 view.updateResults(limitedResults)
             }
 
             Prop("columns") { (view: ExpoTvosSearchView, columns: Int) in
                 // Clamp columns between min and max for safe grid layout
-                view.columns = min(max(Self.minColumns, columns), Self.maxColumns)
+                let clampedValue = min(max(Self.minColumns, columns), Self.maxColumns)
+                if clampedValue != columns {
+                    view.onValidationWarning([
+                        "type": "value_clamped",
+                        "message": "columns value \(columns) was clamped to range [\(Self.minColumns), \(Self.maxColumns)]",
+                        "context": "columns=\(clampedValue)"
+                    ])
+                }
+                view.columns = clampedValue
             }
 
             Prop("placeholder") { (view: ExpoTvosSearchView, placeholder: String) in
@@ -48,7 +63,15 @@ public class ExpoTvosSearchModule: Module {
 
             Prop("topInset") { (view: ExpoTvosSearchView, topInset: Double) in
                 // Clamp to non-negative values (max 500 points reasonable for any screen)
-                view.topInset = CGFloat(min(max(0, topInset), 500))
+                let clampedValue = min(max(0, topInset), 500)
+                if clampedValue != topInset {
+                    view.onValidationWarning([
+                        "type": "value_clamped",
+                        "message": "topInset value \(topInset) was clamped to range [0, 500]",
+                        "context": "topInset=\(clampedValue)"
+                    ])
+                }
+                view.topInset = CGFloat(clampedValue)
             }
 
             Prop("showTitleOverlay") { (view: ExpoTvosSearchView, show: Bool) in
@@ -61,7 +84,15 @@ public class ExpoTvosSearchModule: Module {
 
             Prop("marqueeDelay") { (view: ExpoTvosSearchView, delay: Double) in
                 // Clamp between 0 and maxMarqueeDelay seconds
-                view.marqueeDelay = min(max(0, delay), Self.maxMarqueeDelay)
+                let clampedValue = min(max(0, delay), Self.maxMarqueeDelay)
+                if clampedValue != delay {
+                    view.onValidationWarning([
+                        "type": "value_clamped",
+                        "message": "marqueeDelay value \(delay) was clamped to range [0, \(Self.maxMarqueeDelay)]",
+                        "context": "marqueeDelay=\(clampedValue)"
+                    ])
+                }
+                view.marqueeDelay = clampedValue
             }
 
             Prop("emptyStateText") { (view: ExpoTvosSearchView, text: String) in
@@ -79,6 +110,38 @@ public class ExpoTvosSearchModule: Module {
             Prop("noResultsHintText") { (view: ExpoTvosSearchView, text: String) in
                 view.noResultsHintText = String(text.prefix(Self.maxStringLength))
             }
+
+            Prop("textColor") { (view: ExpoTvosSearchView, colorHex: String?) in
+                view.textColor = colorHex
+            }
+
+            Prop("accentColor") { (view: ExpoTvosSearchView, colorHex: String) in
+                view.accentColor = colorHex
+            }
+
+            Prop("cardWidth") { (view: ExpoTvosSearchView, width: Double) in
+                view.cardWidth = CGFloat(max(50, min(1000, width)))  // Clamp to reasonable range
+            }
+
+            Prop("cardHeight") { (view: ExpoTvosSearchView, height: Double) in
+                view.cardHeight = CGFloat(max(50, min(1000, height)))  // Clamp to reasonable range
+            }
+
+            Prop("imageContentMode") { (view: ExpoTvosSearchView, mode: String) in
+                view.imageContentMode = mode
+            }
+
+            Prop("cardMargin") { (view: ExpoTvosSearchView, margin: Double) in
+                view.cardMargin = CGFloat(max(0, min(200, margin)))  // Clamp to reasonable range
+            }
+
+            Prop("cardPadding") { (view: ExpoTvosSearchView, padding: Double) in
+                view.cardPadding = CGFloat(max(0, min(100, padding)))  // Clamp to reasonable range
+            }
+
+            Prop("overlayTitleSize") { (view: ExpoTvosSearchView, size: Double) in
+                view.overlayTitleSize = CGFloat(max(8, min(72, size)))  // Clamp to reasonable font size range
+            }
         }
     }
 }