expo-tvos-search 1.3.0 → 1.4.0

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.
      */

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"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"}

package/ios/CachedAsyncImage.swift

@@ -0,0 +1,78 @@
+#if os(tvOS)
+
+import SwiftUI
+
+/// Thread-safe NSCache-backed image cache singleton.
+/// Auto-evicts under memory pressure via NSCache's built-in LRU behavior.
+final class ImageCache {
+    static let shared = ImageCache()
+
+    private let cache = NSCache<NSURL, UIImage>()
+
+    private init() {
+        cache.countLimit = 100
+        cache.totalCostLimit = 100 * 1024 * 1024 // 100 MB
+    }
+
+    func image(for url: URL) -> UIImage? {
+        cache.object(forKey: url as NSURL)
+    }
+
+    func setImage(_ image: UIImage, for url: URL) {
+        let cost = image.cgImage.map { $0.bytesPerRow * $0.height } ?? 0
+        cache.setObject(image, forKey: url as NSURL, cost: cost)
+    }
+}
+
+/// SwiftUI view that loads images with NSCache backing.
+/// Cached images appear instantly (no loading flash).
+/// On failure, renders EmptyView so the parent placeholder shows through.
+struct CachedAsyncImage: View {
+    let url: URL
+    let contentMode: ContentMode
+    let width: CGFloat
+    let height: CGFloat
+
+    @State private var uiImage: UIImage?
+    @State private var isLoading = true
+
+    var body: some View {
+        Group {
+            if let uiImage = uiImage {
+                Image(uiImage: uiImage)
+                    .resizable()
+                    .aspectRatio(contentMode: contentMode)
+                    .frame(width: width, height: height)
+            } else if isLoading {
+                ProgressView()
+            } else {
+                // Failure — show nothing, parent placeholder shows through
+                EmptyView()
+            }
+        }
+        .frame(width: width, height: height)
+        .task(id: url) {
+            uiImage = nil
+            isLoading = true
+
+            if let cached = ImageCache.shared.image(for: url) {
+                uiImage = cached
+                isLoading = false
+                return
+            }
+
+            do {
+                let (data, _) = try await URLSession.shared.data(from: url)
+                if let image = UIImage(data: data) {
+                    ImageCache.shared.setImage(image, for: url)
+                    uiImage = image
+                }
+            } catch {
+                // Cancelled or network error — placeholder shows through
+            }
+            isLoading = false
+        }
+    }
+}
+
+#endif

package/ios/ExpoTvosSearchModule.swift

@@ -8,11 +8,28 @@ public class ExpoTvosSearchModule: Module {
     private static let maxMarqueeDelay: Double = 60.0
     private static let maxStringLength = 500
 
+    /// Truncates a string to maxStringLength and emits a validation warning if truncation occurred.
+    private static func truncateString(
+        _ value: String,
+        propName: String,
+        view: ExpoTvosSearchView
+    ) -> String {
+        let truncated = String(value.prefix(maxStringLength))
+        if truncated.count < value.count {
+            view.onValidationWarning([
+                "type": "value_truncated",
+                "message": "\(propName) truncated to \(maxStringLength) characters",
+                "context": "original length: \(value.count)"
+            ])
+        }
+        return truncated
+    }
+
     public func definition() -> ModuleDefinition {
         Name("ExpoTvosSearch")
 
         View(ExpoTvosSearchView.self) {
-            Events("onSearch", "onSelectItem", "onError", "onValidationWarning")
+            Events("onSearch", "onSelectItem", "onError", "onValidationWarning", "onSearchFieldFocused", "onSearchFieldBlurred")
 
             Prop("results") { (view: ExpoTvosSearchView, results: [[String: Any]]) in
                 // Limit results array size to prevent memory issues
@@ -41,8 +58,15 @@ public class ExpoTvosSearchModule: Module {
             }
 
             Prop("placeholder") { (view: ExpoTvosSearchView, placeholder: String) in
-                // Limit placeholder length to prevent layout issues
-                view.placeholder = String(placeholder.prefix(Self.maxStringLength))
+                view.placeholder = Self.truncateString(placeholder, propName: "placeholder", view: view)
+            }
+
+            Prop("searchText") { (view: ExpoTvosSearchView, text: String?) in
+                if let text = text {
+                    view.searchTextProp = Self.truncateString(text, propName: "searchText", view: view)
+                } else {
+                    view.searchTextProp = nil
+                }
             }
 
             Prop("isLoading") { (view: ExpoTvosSearchView, isLoading: Bool) in
@@ -96,19 +120,19 @@ public class ExpoTvosSearchModule: Module {
             }
 
             Prop("emptyStateText") { (view: ExpoTvosSearchView, text: String) in
-                view.emptyStateText = String(text.prefix(Self.maxStringLength))
+                view.emptyStateText = Self.truncateString(text, propName: "emptyStateText", view: view)
             }
 
             Prop("searchingText") { (view: ExpoTvosSearchView, text: String) in
-                view.searchingText = String(text.prefix(Self.maxStringLength))
+                view.searchingText = Self.truncateString(text, propName: "searchingText", view: view)
             }
 
             Prop("noResultsText") { (view: ExpoTvosSearchView, text: String) in
-                view.noResultsText = String(text.prefix(Self.maxStringLength))
+                view.noResultsText = Self.truncateString(text, propName: "noResultsText", view: view)
             }
 
             Prop("noResultsHintText") { (view: ExpoTvosSearchView, text: String) in
-                view.noResultsHintText = String(text.prefix(Self.maxStringLength))
+                view.noResultsHintText = Self.truncateString(text, propName: "noResultsHintText", view: view)
             }
 
             Prop("textColor") { (view: ExpoTvosSearchView, colorHex: String?) in