react-native-web-tv 0.21.2-tv.10

package/src/exports/TV/NativeTVNavigationEventEmitter.js

@@ -0,0 +1,141 @@
+/**
+ * @flow
+ */
+
+import RCTDeviceEventEmitter from '../../vendor/react-native/EventEmitter/RCTDeviceEventEmitter';
+
+type HWEvent = {
+  eventType:
+    | 'up'
+    | 'down'
+    | 'right'
+    | 'left'
+    | 'longUp'
+    | 'longDown'
+    | 'longRight'
+    | 'longLeft'
+    | 'blur'
+    | 'focus'
+    | 'pan'
+    | string,
+  eventKeyAction?: -1 | 1 | 0 | number,
+  tag?: number,
+  body?: {
+    state: 'Began' | 'Changed' | 'Ended',
+    x: number,
+    y: number,
+    velocityX: number,
+    velocityY: number
+  }
+};
+
+const EVENT_NAME = 'onHWKeyEvent';
+
+const mapToHWEvent = (event: KeyboardEvent): HWEvent => {
+  let eventType: HWEvent['eventType'];
+  switch (event.key) {
+    case 'ArrowUp':
+      eventType = 'up';
+      break;
+    case 'ArrowDown':
+      eventType = 'down';
+      break;
+    case 'ArrowLeft':
+      eventType = 'left';
+      break;
+    case 'ArrowRight':
+      eventType = 'right';
+      break;
+    case 'Enter':
+      eventType = 'select';
+      break;
+    default:
+      // Detect user configured Menu key for Web TV platforms through window.appConfig.keyMap.Menu
+      if (
+        typeof window !== 'undefined' &&
+        window?.appConfig?.keyMap?.['Menu'] === event.keyCode
+      ) {
+        eventType = 'menu';
+      } else {
+        eventType = event.key;
+      }
+  }
+  return { eventType };
+};
+
+const NativeTVNavigationEventEmitter = {
+  _listenerCount: 0,
+  _keydownHandler: (null: null | ((e: KeyboardEvent) => void)),
+  _onFocusHandler: (null: null | ((e: FocusEvent) => void)),
+  _onBlurHandler: (null: null | ((e: FocusEvent) => void)),
+
+  addListener(eventType: string) {
+    if (eventType !== EVENT_NAME) {
+      return;
+    }
+    if (this._listenerCount === 0) {
+      this._attachKeyboardListener();
+    }
+    this._listenerCount += 1;
+  },
+
+  removeListeners(count: number) {
+    if (this._listenerCount === 0) {
+      return;
+    }
+    this._listenerCount = Math.max(0, this._listenerCount - count);
+    if (this._listenerCount === 0) {
+      this._detachKeyboardListener();
+    }
+  },
+
+  _attachKeyboardListener() {
+    if (typeof window === 'undefined') {
+      return;
+    }
+
+    if (this._keydownHandler) {
+      return;
+    }
+    this._keydownHandler = (e: KeyboardEvent) => {
+      const hwEvent = mapToHWEvent(e);
+      RCTDeviceEventEmitter.emit(EVENT_NAME, hwEvent);
+    };
+    window.addEventListener('keydown', this._keydownHandler);
+    if (typeof document !== 'undefined') {
+      // Use capture phase to catch per-element focus/blur once at the top.
+      this._onFocusHandler = (e: FocusEvent) => {
+        RCTDeviceEventEmitter.emit(EVENT_NAME, {
+          eventType: 'focus',
+          tag: e.target
+        });
+      };
+      this._onBlurHandler = (e: FocusEvent) => {
+        RCTDeviceEventEmitter.emit(EVENT_NAME, {
+          eventType: 'blur',
+          tag: e.target
+        });
+      };
+      document.addEventListener('focus', this._onFocusHandler, true);
+      document.addEventListener('blur', this._onBlurHandler, true);
+    }
+  },
+
+  _detachKeyboardListener() {
+    if (!this._keydownHandler) {
+      return;
+    }
+    window.removeEventListener('keydown', this._keydownHandler);
+    this._keydownHandler = null;
+    if (this._onBlurHandler && typeof document !== 'undefined') {
+      document.removeEventListener('blur', this._onBlurHandler, true);
+    }
+    if (this._onFocusHandler && typeof document !== 'undefined') {
+      document.removeEventListener('focus', this._onFocusHandler, true);
+    }
+    this._onBlurHandler = null;
+    this._onFocusHandler = null;
+  }
+};
+
+export default NativeTVNavigationEventEmitter;

package/src/exports/TV/TVEventControl.js

@@ -0,0 +1,56 @@
+/**
+ * Methods to enable and disable listening for specific OS TV remote events (menu key, pan gesture)
+ *
+ * @format
+ * @flow
+ */
+
+'use strict';
+
+// import NativeTVNavigationEventEmitter from '../../../src/private/specs_DEPRECATED/modules/NativeTVNavigationEventEmitter';
+// import Platform from '../Platform';
+
+const TVEventControl = {
+  enableTVMenuKey: () => {
+    console.warn('TVEventControl.enableTVMenuKey() is not implemented on web.');
+    // Platform.isTV && NativeTVNavigationEventEmitter &&
+    //   NativeTVNavigationEventEmitter.enableTVMenuKey();
+  },
+  disableTVMenuKey: () => {
+    console.warn(
+      'TVEventControl.disableTVMenuKey() is not implemented on web.'
+    );
+    // Platform.isTV && NativeTVNavigationEventEmitter &&
+    //   NativeTVNavigationEventEmitter.disableTVMenuKey();
+  },
+  enableTVPanGesture: () => {
+    console.warn(
+      'TVEventControl.enableTVPanGesture() is not implemented on web.'
+    );
+    // Platform.isTV && NativeTVNavigationEventEmitter &&
+    //   NativeTVNavigationEventEmitter.enableTVPanGesture();
+  },
+  disableTVPanGesture: () => {
+    console.warn(
+      'TVEventControl.disableTVPanGesture() is not implemented on web.'
+    );
+    // Platform.isTV && NativeTVNavigationEventEmitter &&
+    //   NativeTVNavigationEventEmitter.disableTVPanGesture();
+  },
+  enableGestureHandlersCancelTouches: () => {
+    console.warn(
+      'TVEventControl.enableGestureHandlersCancelTouches() is not implemented on web.'
+    );
+    // Platform.isTV && NativeTVNavigationEventEmitter &&
+    //   NativeTVNavigationEventEmitter.enableGestureHandlersCancelTouches();
+  },
+  disableGestureHandlersCancelTouches: () => {
+    console.warn(
+      'TVEventControl.disableGestureHandlersCancelTouches() is not implemented on web.'
+    );
+    // Platform.isTV && NativeTVNavigationEventEmitter &&
+    //   NativeTVNavigationEventEmitter.disableGestureHandlersCancelTouches();
+  }
+};
+
+export default TVEventControl;

package/src/exports/TV/TVEventHandler.js

@@ -0,0 +1,58 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @flow
+ */
+
+'use strict';
+
+import NativeTVNavigationEventEmitter from './NativeTVNavigationEventEmitter';
+import NativeEventEmitter from '../NativeEventEmitter';
+import Platform from '../Platform';
+import type { EventSubscription } from '../../vendor/react-native/vendor/emitter/EventEmitter';
+
+type TVRemoteEventDefinitions = {
+  tag: [{ tag: number }],
+  target: [{ target: number }],
+  eventType: [{ eventType: string }],
+  eventKeyAction: [{ eventKeyAction: string }],
+  body: [{ body: any }]
+};
+let __nativeTVNavigationEventEmitter: ?NativeEventEmitter<TVRemoteEventDefinitions> =
+  null;
+
+type TVEventHandlerCallback = (event: any) => void;
+type TVEventHandlerType = {
+  addListener: (callback: TVEventHandlerCallback) => EventSubscription
+};
+
+const TVEventHandler: TVEventHandlerType = {
+  addListener: (callback: TVEventHandlerCallback) => {
+    if (Platform.OS === 'ios' && !NativeTVNavigationEventEmitter) {
+      return { remove: () => {} };
+    }
+    if (!__nativeTVNavigationEventEmitter) {
+      __nativeTVNavigationEventEmitter =
+        new NativeEventEmitter<TVRemoteEventDefinitions>(
+          NativeTVNavigationEventEmitter
+        );
+    }
+    const subscription: EventSubscription =
+      __nativeTVNavigationEventEmitter.addListener(
+        // $FlowFixMe[prop-missing]
+        'onHWKeyEvent',
+        (data: any) => {
+          if (callback) {
+            callback(data);
+          }
+        }
+      );
+    return subscription;
+  }
+};
+
+export default TVEventHandler;

package/src/exports/TV/TVFocusEventHandler.js

@@ -0,0 +1,43 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @flow
+ */
+
+'use strict';
+
+import type { TVRemoteEvent } from './types';
+
+import Platform from '../Platform';
+import { type EventSubscription } from '../../vendor/react-native/vendor/emitter/EventEmitter';
+import { default as TVEventHandler } from './TVEventHandler';
+
+class TVFocusEventHandler {
+  __subscription: ?EventSubscription = null;
+  __callbackMap: Map<any, Function> = new Map();
+
+  constructor() {
+    this.__subscription = TVEventHandler.addListener((data: TVRemoteEvent) => {
+      const callback = this.__callbackMap.get(data.tag);
+      if (callback) {
+        callback(data);
+      }
+    });
+  }
+
+  register(componentTag: ?any, callback: Function): void {
+    this.__callbackMap.set(componentTag, callback);
+  }
+
+  unregister(componentTag: ?any): void {
+    this.__callbackMap.delete(componentTag);
+  }
+}
+
+export const tvFocusEventHandler: TVFocusEventHandler | null = Platform.isTV
+  ? new TVFocusEventHandler()
+  : null;

package/src/exports/TV/TVFocusGuideView.js

@@ -0,0 +1,163 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ * Modifications copyright (c) 2026 Harpreet Singh.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow
+ * @format
+ */
+
+import type { ViewProps } from '../View/types';
+import type { ComponentOrHandleType } from './tagForComponentOrHandle';
+
+import Platform from '../Platform';
+import useMergeRefs from '../../modules/useMergeRefs';
+import View from '../View';
+// import {Commands} from '../View/ViewNativeComponent';
+import { setDestinations as setNavDestinations } from '../../modules/SpatialManager';
+import tagForComponentOrHandle from './tagForComponentOrHandle';
+
+import StyleSheet from '../StyleSheet';
+import * as React from 'react';
+
+type TVFocusGuideViewProps = $ReadOnly<{
+  ...ViewProps,
+
+  /**
+   * If the view should be "visible". display "flex" if visible, otherwise "none".
+   * Useful for absolute focus guides without children
+   * Defaults to true
+   */
+  enabled?: boolean,
+
+  /**
+   * The views the focus should go to
+   */
+  destinations?: ComponentOrHandleType[],
+
+  /**
+   * @deprecated Don't use it, no longer necessary.
+   */
+  safePadding?: 'vertical' | 'horizontal' | 'both' | null,
+
+  autoFocus?: boolean,
+
+  trapFocusUp?: boolean,
+  trapFocusDown?: boolean,
+  trapFocusLeft?: boolean,
+  trapFocusRight?: boolean,
+
+  /**
+   * When set to false, this view and all its subviews will be NOT focusable.
+   */
+  focusable?: boolean | void
+}>;
+
+export type TVFocusGuideViewImperativeMethods = $ReadOnly<{
+  setDestinations: (destinations: ComponentOrHandleType[]) => void
+}>;
+
+const TVFocusGuideView: React.AbstractComponent<
+  TVFocusGuideViewProps,
+  React.ElementRef<typeof View>
+> = React.forwardRef((props, ref) => {
+  const {
+    enabled = true,
+    // safePadding,
+    destinations: destinationsProp,
+    autoFocus,
+    focusable
+  } = props;
+
+  const focusGuideRef = React.useRef<React.ElementRef<typeof View> | null>(
+    null
+  );
+
+  const setDestinations = React.useCallback(
+    (destinations: ?(ComponentOrHandleType[])) => {
+      if (Platform.isTV) {
+        const focusGuideHost = focusGuideRef.current;
+        if (focusGuideHost != null) {
+          const resolvedDestinations = destinations?.map(
+            tagForComponentOrHandle
+          );
+          setNavDestinations(focusGuideHost, resolvedDestinations);
+        } else {
+          console.warn(
+            '[TVFocusGuideView]: Cannot set destinations as focusGuideView ref unavailable for: ',
+            destinations
+          );
+        }
+      }
+    },
+    []
+  );
+
+  const setLocalRef = React.useCallback(
+    (instance: any /*HostInstance*/ | null) => {
+      // $FlowExpectedError[incompatible-type]
+      focusGuideRef.current = instance;
+
+      if (instance != null) {
+        // $FlowFixMe[prop-missing]
+        // $FlowFixMe[unsafe-object-assign]
+        Object.assign(instance, {
+          setDestinations
+        });
+      }
+    },
+    [setDestinations]
+  );
+
+  const mergedRef = useMergeRefs(setLocalRef, ref);
+
+  React.useEffect(() => {
+    if (focusable === false) {
+      setDestinations([]);
+    } else if (destinationsProp !== null && destinationsProp !== undefined) {
+      setDestinations(destinationsProp); // $FlowFixMe[incompatible-call]
+    }
+  }, [setDestinations, destinationsProp, focusable]);
+
+  let enabledStyle = {};
+  if (props.style) {
+    // If user passes a style we only use display: none if enabled is false.
+    enabledStyle = !enabled ? { display: 'none' } : {};
+  } else {
+    enabledStyle = { display: enabled ? 'flex' : 'none' };
+  }
+  const style = [styles.container, props.style, enabledStyle];
+
+  // If there are no destinations and the autoFocus is false the the default value of focusable should be false
+  // It is then properly handled by the native code
+  const tvOSSelectable =
+    destinationsProp || autoFocus ? focusable !== false : false;
+
+  return (
+    // $FlowFixMe[prop-missing]
+    <View
+      {...props}
+      autoFocus={focusable === false ? true : autoFocus}
+      collapsable={false}
+      isContainer={true} // Sneak this through to allow setting correct DOM props as tvFocusable may be false
+      // tvOS only prop
+      isTVSelectable={tvOSSelectable}
+      ref={mergedRef}
+      style={style}
+      // Android TV only prop, but wait, now for web TVs as well ;-)!
+      tvFocusable={focusable}
+    />
+  );
+});
+
+const styles = StyleSheet.create({
+  container: {
+    minWidth: 1,
+    minHeight: 1,
+    pointerEvents: 'box-none' // FocusGuides should not handle pointer events.
+  }
+});
+
+export default TVFocusGuideView;

package/src/exports/TV/TVParallaxProperties.d.ts

@@ -0,0 +1,42 @@
+export type TVParallaxProperties = {
+  /**
+   * If true, parallax effects are enabled.  Defaults to true.
+   */
+  enabled?: boolean | undefined,
+
+  /**
+   * Defaults to 2.0.
+   */
+  shiftDistanceX?: number | undefined,
+
+  /**
+   * Defaults to 2.0.
+   */
+  shiftDistanceY?: number | undefined,
+
+  /**
+   * Defaults to 0.05.
+   */
+  tiltAngle?: number | undefined,
+
+  /**
+   * Defaults to 1.0
+   */
+  magnification?: number | undefined,
+
+  /**
+   * Defaults to 1.0
+   */
+  pressMagnification?: number | undefined,
+
+  /**
+   * Defaults to 0.3
+   */
+  pressDuration?: number | undefined,
+
+  /**
+   * @deprecated No longer used
+   */
+  pressDelay?: number | undefined,
+};
+

package/src/exports/TV/TVTextScrollView.js

@@ -0,0 +1,160 @@
+/**
+ * Copyright (c) Douglas Lowder.
+ * Modifications copyright (c) 2026 Harpreet Singh.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @flow
+ */
+
+import type { ScrollViewProps } from '../ScrollView/types';
+
+import tagForComponentOrHandle from './tagForComponentOrHandle';
+
+import ScrollView from '../ScrollView';
+import {
+  scrollContainer,
+  leaveKeyHandlerControl,
+  takeKeyHandlerControl
+} from '../../modules/SpatialManager';
+import * as React from 'react';
+const { tvFocusEventHandler } = require('./TVFocusEventHandler');
+
+/**
+ * Convenience wrapper to create a scroll view that will scroll correctly
+ * using swipe gestures on tvOS, even if the scroll view has no focusable
+ * subviews.
+ *
+ * The main use case would be when a large scrolling block of text needs
+ * to be presented to the user.
+ *
+ * Props:
+ *
+ */
+
+class TVTextScrollView extends React.Component<{
+  ...ScrollViewProps,
+  /**
+   * The duration of the scroll animation when a swipe is detected.
+   * Default value is 0.3 s
+   */
+  scrollDuration?: number,
+  /**
+   * Scrolling distance when a swipe is detected
+   * Default value is half the visible height (vertical scroller)
+   * or width (horizontal scroller)
+   */
+  pageSize?: number,
+  /**
+   * If true, will scroll to start when focus moves out past the beginning
+   * of the scroller
+   * Defaults to true
+   */
+  snapToStart?: boolean,
+  /**
+   * If true, will scroll to end when focus moves out past the end of the
+   * scroller
+   * Defaults to true
+   */
+  snapToEnd?: boolean,
+  /**
+   * Called when the scroller comes into focus (e.g. for highlighting)
+   */
+  onFocus?: (evt: Event) => void,
+  /**
+   * Called when the scroller goes out of focus
+   */
+  onBlur?: (evt: Event) => void
+}> {
+  _subscription: any;
+  _scrollViewRef: ?React.ElementRef<typeof ScrollView>;
+  _keyControlOwner: ?HTMLElement;
+
+  _setScrollViewRef = (ref: ?React.ElementRef<typeof ScrollView>) => {
+    this._scrollViewRef = ref;
+  };
+
+  getScrollViewRef(): ?React.ElementRef<typeof ScrollView> {
+    return this._scrollViewRef;
+  }
+
+  _getScrollableNode(): ?HTMLElement {
+    const scrollViewRef: any = this._scrollViewRef;
+    if (
+      scrollViewRef &&
+      typeof scrollViewRef.getScrollableNode === 'function'
+    ) {
+      return scrollViewRef.getScrollableNode();
+    }
+    return null;
+  }
+
+  _handleDirectionalKeyFromSpatial = (keyCode: string): ?boolean => {
+    const scrollableNode = this._keyControlOwner;
+    if (!scrollableNode) {
+      return false;
+    }
+    return scrollContainer(scrollableNode, keyCode, {
+      horizontal: this.props.horizontal === true,
+      pageSize: this.props.pageSize,
+      scrollDurationMs: Math.max(0, (this.props.scrollDuration || 0) * 1000),
+      snapToStart: this.props.snapToStart !== false,
+      snapToEnd: this.props.snapToEnd !== false
+    });
+  };
+
+  _takeDirectionalKeyControl = () => {
+    const owner = this._getScrollableNode();
+    this._keyControlOwner = owner;
+    takeKeyHandlerControl(owner, this._handleDirectionalKeyFromSpatial);
+  };
+
+  _releaseDirectionalKeyControl = () => {
+    leaveKeyHandlerControl(this._keyControlOwner);
+    this._keyControlOwner = null;
+  };
+
+  componentDidMount() {
+    const cmp = this; // eslint-disable-line consistent-this
+    const myTag = tagForComponentOrHandle(this._scrollViewRef);
+    tvFocusEventHandler?.register(myTag, function (evt) {
+      if (myTag === evt.tag) {
+        if (evt.eventType === 'focus') {
+          cmp._takeDirectionalKeyControl();
+          cmp.props.onFocus && cmp.props.onFocus(evt);
+        } else if (evt.eventType === 'blur') {
+          cmp._releaseDirectionalKeyControl();
+          cmp.props.onBlur && cmp.props.onBlur(evt);
+        }
+      }
+    });
+  }
+
+  componentWillUnmount() {
+    this._releaseDirectionalKeyControl();
+    const myTag = tagForComponentOrHandle(this._scrollViewRef);
+    tvFocusEventHandler?.unregister(myTag);
+  }
+
+  render(): $FlowFixMe {
+    const props: $FlowFixMe = {
+      ...this.props,
+      tvParallaxProperties: {
+        pressDuration: this.props.scrollDuration || 0.0
+      },
+      isTVSelectable: true,
+      snapToInterval: this.props.pageSize || 0.0,
+      removeClippedSubviews: false,
+      automaticallyAdjustContentInsets: false
+    };
+    return (
+      <ScrollView {...props} ref={this._setScrollViewRef}>
+        {this.props.children}
+      </ScrollView>
+    );
+  }
+}
+
+export default TVTextScrollView;