@hps1978/react-native-web-tv 0.21.2-tv.0

package/src/exports/useWindowDimensions/index.js

@@ -0,0 +1,36 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and 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 strict-local
+ */
+
+'use client';
+
+import type { DisplayMetrics } from '../Dimensions';
+
+import Dimensions from '../Dimensions';
+import { useEffect, useState } from 'react';
+
+export default function useWindowDimensions(): DisplayMetrics {
+  const [dims, setDims] = useState(() => Dimensions.get('window'));
+  useEffect(() => {
+    function handleChange({ window }) {
+      if (window != null) {
+        setDims(window);
+      }
+    }
+    Dimensions.addEventListener('change', handleChange);
+    // We might have missed an update between calling `get` in render and
+    // `addEventListener` in this handler, so we set it here. If there was
+    // no change, React will filter out this update as a no-op.
+    setDims(Dimensions.get('window'));
+    return () => {
+      Dimensions.removeEventListener('change', handleChange);
+    };
+  }, []);
+  return dims;
+}

package/src/index.js

@@ -0,0 +1,79 @@
+// @flow strict
+export { default as unstable_createElement } from './exports/createElement';
+export { default as findNodeHandle } from './exports/findNodeHandle';
+export { default as processColor } from './exports/processColor';
+export { default as render } from './exports/render';
+export { default as unmountComponentAtNode } from './exports/unmountComponentAtNode';
+export { default as NativeModules } from './exports/NativeModules';
+
+// APIs
+export { default as AccessibilityInfo } from './exports/AccessibilityInfo';
+export { default as Alert } from './exports/Alert';
+export { default as Animated } from './exports/Animated';
+export { default as Appearance } from './exports/Appearance';
+export { default as AppRegistry } from './exports/AppRegistry';
+export { default as AppState } from './exports/AppState';
+export { default as BackHandler } from './exports/BackHandler';
+export { default as Clipboard } from './exports/Clipboard';
+export { default as Dimensions } from './exports/Dimensions';
+export { default as Easing } from './exports/Easing';
+export { default as I18nManager } from './exports/I18nManager';
+export { default as Keyboard } from './exports/Keyboard';
+export { default as InteractionManager } from './exports/InteractionManager';
+export { default as LayoutAnimation } from './exports/LayoutAnimation';
+export { default as Linking } from './exports/Linking';
+export { default as NativeEventEmitter } from './exports/NativeEventEmitter';
+export { default as PanResponder } from './exports/PanResponder';
+export { default as PixelRatio } from './exports/PixelRatio';
+export { default as Platform } from './exports/Platform';
+export { default as Share } from './exports/Share';
+export { default as StyleSheet } from './exports/StyleSheet';
+export { default as UIManager } from './exports/UIManager';
+export { default as Vibration } from './exports/Vibration';
+
+// components
+export { default as ActivityIndicator } from './exports/ActivityIndicator';
+export { default as Button } from './exports/Button';
+export { default as CheckBox } from './exports/CheckBox';
+export { default as FlatList } from './exports/FlatList';
+export { default as Image } from './exports/Image';
+export { default as ImageBackground } from './exports/ImageBackground';
+export { default as KeyboardAvoidingView } from './exports/KeyboardAvoidingView';
+export { default as Modal } from './exports/Modal';
+export { default as Picker } from './exports/Picker';
+export { default as Pressable } from './exports/Pressable';
+export { default as ProgressBar } from './exports/ProgressBar';
+export { default as RefreshControl } from './exports/RefreshControl';
+export { default as SafeAreaView } from './exports/SafeAreaView';
+export { default as ScrollView } from './exports/ScrollView';
+export { default as SectionList } from './exports/SectionList';
+export { default as StatusBar } from './exports/StatusBar';
+export { default as Switch } from './exports/Switch';
+export { default as Text } from './exports/Text';
+export { default as TextInput } from './exports/TextInput';
+export { default as Touchable } from './exports/Touchable';
+export { default as TouchableHighlight } from './exports/TouchableHighlight';
+export { default as TouchableNativeFeedback } from './exports/TouchableNativeFeedback';
+export { default as TouchableOpacity } from './exports/TouchableOpacity';
+export { default as TouchableWithoutFeedback } from './exports/TouchableWithoutFeedback';
+export { default as View } from './exports/View';
+export { default as VirtualizedList } from './exports/VirtualizedList';
+export { default as YellowBox } from './exports/YellowBox';
+export { default as LogBox } from './exports/LogBox';
+
+// plugins
+export { default as DeviceEventEmitter } from './exports/DeviceEventEmitter';
+
+// hooks
+export { default as useColorScheme } from './exports/useColorScheme';
+export { default as useLocaleContext } from './exports/useLocaleContext';
+export { default as useWindowDimensions } from './exports/useWindowDimensions';
+
+// #region TV
+export { default as TVEventHandler } from './exports/TV/TVEventHandler';
+export { default as TVEventControl } from './exports/TV/TVEventControl';
+export { default as TVFocusGuideView } from './exports/TV/TVFocusGuideView';
+export type { TVRemoteEvent } from './exports/TV/types';
+export { default as TVTextScrollView } from './exports/TV/TVTextScrollView';
+export { default as useTVEventHandler } from './exports/TV/useTVEventHandler';
+// #endregion

package/src/modules/AccessibilityUtil/index.js

@@ -0,0 +1,20 @@
+/**
+ * Copyright (c) Nicolas Gallagher.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow
+ */
+
+import isDisabled from './isDisabled';
+import propsToAccessibilityComponent from './propsToAccessibilityComponent';
+import propsToAriaRole from './propsToAriaRole';
+
+const AccessibilityUtil = {
+  isDisabled,
+  propsToAccessibilityComponent,
+  propsToAriaRole
+};
+
+export default AccessibilityUtil;

package/src/modules/AccessibilityUtil/isDisabled.js

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) Nicolas Gallagher.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow
+ */
+
+const isDisabled = (props: Object): boolean =>
+  props.disabled ||
+  (Array.isArray(props.accessibilityStates) &&
+    props.accessibilityStates.indexOf('disabled') > -1);
+
+export default isDisabled;

package/src/modules/AccessibilityUtil/propsToAccessibilityComponent.js

@@ -0,0 +1,58 @@
+/**
+ * Copyright (c) Nicolas Gallagher.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow
+ */
+
+import propsToAriaRole from './propsToAriaRole';
+
+const roleComponents = {
+  article: 'article',
+  banner: 'header',
+  blockquote: 'blockquote',
+  button: 'button',
+  code: 'code',
+  complementary: 'aside',
+  contentinfo: 'footer',
+  deletion: 'del',
+  emphasis: 'em',
+  figure: 'figure',
+  insertion: 'ins',
+  form: 'form',
+  list: 'ul',
+  listitem: 'li',
+  main: 'main',
+  navigation: 'nav',
+  paragraph: 'p',
+  region: 'section',
+  strong: 'strong'
+};
+
+const emptyObject = {};
+
+const propsToAccessibilityComponent = (
+  props: Object = emptyObject
+): void | string => {
+  const roleProp = props.role || props.accessibilityRole;
+  // special-case for "label" role which doesn't map to an ARIA role
+  if (roleProp === 'label') {
+    return 'label';
+  }
+
+  const role = propsToAriaRole(props);
+  if (role) {
+    if (role === 'heading') {
+      const level = props.accessibilityLevel || props['aria-level'];
+      if (level != null) {
+        return `h${level}`;
+      }
+      return 'h1';
+    }
+    return roleComponents[role];
+  }
+};
+
+export default propsToAccessibilityComponent;

package/src/modules/AccessibilityUtil/propsToAriaRole.js

@@ -0,0 +1,42 @@
+/**
+ * Copyright (c) Nicolas Gallagher.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow
+ */
+
+const accessibilityRoleToWebRole = {
+  adjustable: 'slider',
+  button: 'button',
+  header: 'heading',
+  image: 'img',
+  imagebutton: null,
+  keyboardkey: null,
+  label: null,
+  link: 'link',
+  none: 'presentation',
+  search: 'search',
+  summary: 'region',
+  text: null
+};
+
+const propsToAriaRole = ({
+  accessibilityRole,
+  role
+}: {
+  accessibilityRole?: string,
+  role?: string
+}): string | void => {
+  const _role = role || accessibilityRole;
+  if (_role) {
+    const inferredRole = accessibilityRoleToWebRole[_role];
+    if (inferredRole !== null) {
+      // ignore roles that don't map to web
+      return inferredRole || _role;
+    }
+  }
+};
+
+export default propsToAriaRole;

package/src/modules/AssetRegistry/index.js

@@ -0,0 +1,32 @@
+/**
+ * Copyright (c) Nicolas Gallagher.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow
+ */
+
+export type PackagerAsset = {
+  __packager_asset: boolean,
+  fileSystemLocation: string,
+  httpServerLocation: string,
+  width: ?number,
+  height: ?number,
+  scales: Array<number>,
+  hash: string,
+  name: string,
+  type: string
+};
+
+const assets: Array<PackagerAsset> = [];
+
+export function registerAsset(asset: PackagerAsset): number {
+  // `push` returns new array length, so the first asset will
+  // get id 1 (not 0) to make the value truthy
+  return assets.push(asset);
+}
+
+export function getAssetByID(assetId: number): PackagerAsset {
+  return assets[assetId - 1];
+}

package/src/modules/ImageLoader/index.js

@@ -0,0 +1,167 @@
+/**
+ * Copyright (c) Nicolas Gallagher.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow
+ */
+
+const dataUriPattern = /^data:/;
+
+export class ImageUriCache {
+  static _maximumEntries: number = 256;
+  static _entries = {};
+
+  static has(uri: string): boolean {
+    const entries = ImageUriCache._entries;
+    const isDataUri = dataUriPattern.test(uri);
+    return isDataUri || Boolean(entries[uri]);
+  }
+
+  static add(uri: string) {
+    const entries = ImageUriCache._entries;
+    const lastUsedTimestamp = Date.now();
+    if (entries[uri]) {
+      entries[uri].lastUsedTimestamp = lastUsedTimestamp;
+      entries[uri].refCount += 1;
+    } else {
+      entries[uri] = {
+        lastUsedTimestamp,
+        refCount: 1
+      };
+    }
+  }
+
+  static remove(uri: string) {
+    const entries = ImageUriCache._entries;
+    if (entries[uri]) {
+      entries[uri].refCount -= 1;
+    }
+    // Free up entries when the cache is "full"
+    ImageUriCache._cleanUpIfNeeded();
+  }
+
+  static _cleanUpIfNeeded() {
+    const entries = ImageUriCache._entries;
+    const imageUris = Object.keys(entries);
+
+    if (imageUris.length + 1 > ImageUriCache._maximumEntries) {
+      let leastRecentlyUsedKey;
+      let leastRecentlyUsedEntry;
+
+      imageUris.forEach((uri) => {
+        const entry = entries[uri];
+        if (
+          (!leastRecentlyUsedEntry ||
+            entry.lastUsedTimestamp <
+              leastRecentlyUsedEntry.lastUsedTimestamp) &&
+          entry.refCount === 0
+        ) {
+          leastRecentlyUsedKey = uri;
+          leastRecentlyUsedEntry = entry;
+        }
+      });
+
+      if (leastRecentlyUsedKey) {
+        delete entries[leastRecentlyUsedKey];
+      }
+    }
+  }
+}
+
+let id = 0;
+const requests = {};
+
+const ImageLoader = {
+  abort(requestId: number) {
+    let image = requests[`${requestId}`];
+    if (image) {
+      image.onerror = null;
+      image.onload = null;
+      image = null;
+      delete requests[`${requestId}`];
+    }
+  },
+  getSize(
+    uri: string,
+    success: (width: number, height: number) => void,
+    failure: () => void
+  ) {
+    let complete = false;
+    const interval = setInterval(callback, 16);
+    const requestId = ImageLoader.load(uri, callback, errorCallback);
+
+    function callback() {
+      const image = requests[`${requestId}`];
+      if (image) {
+        const { naturalHeight, naturalWidth } = image;
+        if (naturalHeight && naturalWidth) {
+          success(naturalWidth, naturalHeight);
+          complete = true;
+        }
+      }
+      if (complete) {
+        ImageLoader.abort(requestId);
+        clearInterval(interval);
+      }
+    }
+
+    function errorCallback() {
+      if (typeof failure === 'function') {
+        failure();
+      }
+      ImageLoader.abort(requestId);
+      clearInterval(interval);
+    }
+  },
+  has(uri: string): boolean {
+    return ImageUriCache.has(uri);
+  },
+  load(uri: string, onLoad: Function, onError: Function): number {
+    id += 1;
+    const image = new window.Image();
+    image.onerror = onError;
+    image.onload = (e) => {
+      // avoid blocking the main thread
+      const onDecode = () => onLoad({ nativeEvent: e });
+      if (typeof image.decode === 'function') {
+        // Safari currently throws exceptions when decoding svgs.
+        // We want to catch that error and allow the load handler
+        // to be forwarded to the onLoad handler in this case
+        image.decode().then(onDecode, onDecode);
+      } else {
+        setTimeout(onDecode, 0);
+      }
+    };
+    image.src = uri;
+    requests[`${id}`] = image;
+    return id;
+  },
+  prefetch(uri: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+      ImageLoader.load(
+        uri,
+        () => {
+          // Add the uri to the cache so it can be immediately displayed when used
+          // but also immediately remove it to correctly reflect that it has no active references
+          ImageUriCache.add(uri);
+          ImageUriCache.remove(uri);
+          resolve();
+        },
+        reject
+      );
+    });
+  },
+  queryCache(uris: Array<string>): Promise<{| [uri: string]: 'disk/memory' |}> {
+    const result = {};
+    uris.forEach((u) => {
+      if (ImageUriCache.has(u)) {
+        result[u] = 'disk/memory';
+      }
+    });
+    return Promise.resolve(result);
+  }
+};
+
+export default ImageLoader;

package/src/modules/SpatialManager/README.md

@@ -0,0 +1,122 @@
+# SpatialManager Smooth Scrolling
+
+This document explains how smooth scrolling is implemented for TV spatial navigation in React Native Web.
+
+## Overview
+When the user navigates with the arrow keys, the SpatialManager determines the next focusable element and ensures it is fully visible inside the nearest scrollable container (or the window if no scrollable ancestor exists). The scroll behavior is coordinated outside the React tree and is driven by DOM measurements.
+
+## How scrolling is triggered
+1. A keydown event is received (ArrowUp/ArrowDown/ArrowLeft/ArrowRight).
+2. The next focusable element is computed by the LRUD engine.
+3. `scrollToElement()` runs before focusing the element.
+4. The target element’s bounding rect is compared with the visible container rect.
+5. If the element is outside the visible area (with padding), the scroll offset is updated to bring it fully into view.
+
+## Scroll target selection
+- **Primary**: The closest scrollable ancestor with the correct overflow and scrollable dimension.
+- **Fallback**: The window, using a lightweight wrapper that maps `scrollTop`, `scrollLeft`, and `scrollTo()` to `window.scroll`.
+
+## Visibility calculation
+The algorithm uses viewport-relative rectangles to avoid mismatched coordinate systems:
+- `targetRect` (element’s bounding box)
+- `visibleContainerRect` (scroll container clamped to the viewport)
+
+If the target is outside the safe zone (defined by `leftEdgePaddingPx` and `topEdgePaddingPx`), the code computes a delta and applies it to the current scroll offset:
+- **Vertical**: scroll down when `targetRect.bottom` exceeds the container’s bottom minus padding; scroll up when `targetRect.top` is above the container’s top plus padding.
+- **Horizontal**: same logic with left/right edges.
+
+## Animation
+Smooth scrolling is controlled by these options:
+- `smoothScrollEnabled`: uses native smooth behavior where supported.
+- `scrollAnimationDurationMsVertical`: optional override for vertical only.
+- `scrollAnimationDurationMsHorizontal`: optional override for horizontal only.
+
+If a duration is provided, a `requestAnimationFrame` loop performs the scroll. Use with caution as this may have performance impacts.
+
+## TV Platform Compatibility
+
+The SpatialManager includes **one-time API capability detection at module load** and implements fallbacks for TV platforms with limited API support.
+
+### Detected Capabilities
+- **`hasPerformance`**: Checks if `performance.now()` is available
+- **`hasRequestAnimationFrame`**: Checks if `requestAnimationFrame` is available
+- **`hasGetComputedStyle`**: Checks if `window.getComputedStyle()` is available
+- **`hasGetBoundingClientRect`**: Checks if `getBoundingClientRect()` is available
+
+### Fallback Mechanisms
+
+| API | Fallback | Impact |
+|-----|----------|--------|
+| `performance.now()` | `Date.now()` (milliseconds) | Animation timing less precise but functional |
+| `requestAnimationFrame()` | `setTimeout(callback, 16ms)` | Simulates ~60fps; ensures animation works on all platforms |
+| `getComputedStyle()` | Inline `style` attribute check | Scroll target detection uses only inline styles if computed styles unavailable |
+| `getBoundingClientRect()` | `offsetTop/Left/Height/Width` | Less precise positioning but ensures visibility detection works |
+
+### Helper Functions
+
+- **`getCurrentTime()`**: Returns high-precision time if available, falls back to `Date.now()`
+- **`scheduleAnimationFrame(callback)`**: Schedules next frame via `rAF` or `setTimeout`
+- **`cancelScheduledFrame(frameId)`**: Cancels scheduled frame using appropriate API
+
+### Compatibility Notes
+- Animation always works, but less smoothly on platforms without `rAF`
+- Scroll target detection is accurate on modern browsers, approximate on platforms without `getBoundingClientRect`
+- The module degrades gracefully: core scrolling functionality is always available, even if some APIs are missing
+
+## Configuration summary
+
+Spatial navigation reads configuration from `window.appConfig` at runtime. The config object supports these top-level keys:
+
+- `keyMap`: Optional LRUD key mapping overrides.
+- `scrollConfig`: Scroll behavior settings (listed below).
+- `keydownThrottleMs`: Optional minimum time (ms) between keydown events to reduce rapid repeats.
+- `focusConfig`: Focus scrolling behavior configuration (mode). AlignLeft keeps left moves default and aligns right moves to the current focus X position when scrolling.
+
+`scrollConfig` fields:
+- `scrollConfig.leftEdgePaddingPx`: padding from scroll container left edge.
+- `scrollConfig.topEdgePaddingPx`: padding from scroll container top edge.
+- `scrollThrottleMs`: Minimum time between scrolls to avoid rapid repeat scrolling. NOTE: not implemented.
+- `smoothScrollEnabled`: Enables native smooth behavior when not using manual animation.
+- `scrollAnimationDurationMsVertical`: Vertical-only animation duration (ms).
+- `scrollAnimationDurationMsHorizontal`: Horizontal-only animation duration (ms).
+
+## Usage Patterns
+
+### Pattern 1: Global Config
+
+```html
+<!-- Add before app bundle -->
+<script>
+  window.appConfig = {
+    keyMap: {
+        'ArrowLeft': 'left',
+        'ArrowRight': 'right',
+        'ArrowUp': 'up',
+        'ArrowDown': 'down'
+    },
+    keydownThrottleMs: 0,
+    focusConfig: {
+      mode: 'default'  // or 'AlignLeft' for horizontal-only alignment
+    },
+    scrollConfig: {
+      leftEdgePaddingPx: 10,
+      topEdgePaddingPx: 15,
+      scrollThrottleMs: 80, // Not implemented
+      smoothScrollEnabled: true,
+      scrollAnimationDurationMsVertical: 600,
+      scrollAnimationDurationMsHorizontal: 400
+    }
+  };
+</script>
+<script src="app-bundle.js"></script>
+```
+
+### Priority Order
+1. `window.appConfig` (if present)
+2. Default config (fallback)
+
+## Notes
+- The scroll logic runs before `focus()` to avoid browser `scrollIntoView()` interference.
+- Window fallback is used when no scrollable ancestor is found.
+- The algorithm is symmetric for vertical and horizontal directions.
+- API capability checks are performed once at module load, not on every scroll operation.