feat: nodes can take an additional scrolloffset

It alllows to dynamically change the scrollview offsetFromStart depending on each focused item
bamlab · Apr 9, 2024 · b87654b · b87654b
1 parent db1defd
commit b87654b
Show file tree

Hide file tree

Showing 5 changed files with 19 additions and 8 deletions.
diff --git a/docs/api.md b/docs/api.md
@@ -56,6 +56,7 @@ The `SpatialNavigationNode` component receives the following props:
 | `alignInGrid` | `boolean`                                                                                          | `false`      | Determines whether child lists should behave like a grid.                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `indexRange`  | `number[]`                                                                                         | `undefined`  | Determines the indexes when using long nodes in a grid. If a grid row has one `indexRange`, you should specify each element's `indexRange`. You can check for more details in [`GridWithLongNodesPage`](https://github.com/bamlab/react-tv-space-navigation/blob/31bfe1def4a7e18e9e41f26a520090d1b7a5b149/packages/example/src/pages/GridWithLongNodesPage.tsx) example or in [lrud documentation](https://github.com/bbc/lrud/blob/master/docs/usage.md#indexrange). |
 | `children`    | `({ isFocused, isActive }: { isFocused: boolean, isActive: boolean }) => ReactNode` or `ReactNode` | `null`       | Child elements of the component. It can be a function that returns a React element and accepts a parameter with a `isFocused` property when `isFocusable` is `true`. If `isFocusable` is `false` or not provided, it can be any valid React node.                                                                                                                                                                                                                     |
+| `additionalOffset`    | `number` | `0`       | An additional offset used when the node is a children of a scrollview. If specified, this offset will be added to the `offsetFromStart` of the ScrollView. It allows a fine grained scroll for each scrollview item.                                                                                                                                                                                                                    |
 
 The `SpatialNavigationNode` component ref expose the following methods:
 

diff --git a/packages/lib/src/spatial-navigation/components/Node.tsx b/packages/lib/src/spatial-navigation/components/Node.tsx
@@ -26,19 +26,25 @@ type DefaultProps = {
    * @see LRUD docs */
   alignInGrid?: boolean;
   indexRange?: NodeIndexRange;
+  /**
+   * This is an additional offset useful only for the scrollview. It adds up to the offsetFromStart of the scrollview.
+   */
+  additionalOffset?: number;
 };
 type Props = DefaultProps & (FocusableProps | NonFocusableProps);
 
 export type SpatialNavigationNodeDefaultProps = DefaultProps;
 
 const useScrollToNodeIfNeeded = ({
   childRef,
+  additionalOffset,
 }: {
   childRef: React.MutableRefObject<View | null>;
+  additionalOffset?: number;
 }) => {
   const { scrollToNodeIfNeeded } = useSpatialNavigatorParentScroll();
 
-  return () => scrollToNodeIfNeeded(childRef);
+  return () => scrollToNodeIfNeeded(childRef, additionalOffset);
 };
 
 const useBindRefToChild = () => {
@@ -79,6 +85,7 @@ export const SpatialNavigationNode = forwardRef<SpatialNavigationNodeRef, Props>
       alignInGrid = false,
       indexRange,
       children,
+      additionalOffset = 0,
     }: Props,
     ref,
   ) => {
@@ -99,7 +106,10 @@ export const SpatialNavigationNode = forwardRef<SpatialNavigationNodeRef, Props>
 
     const { childRef, bindRefToChild } = useBindRefToChild();
 
-    const scrollToNodeIfNeeded = useScrollToNodeIfNeeded({ childRef });
+    const scrollToNodeIfNeeded = useScrollToNodeIfNeeded({
+      childRef,
+      additionalOffset,
+    });
 
     /*
      * We don't re-register in LRUD on each render, because LRUD does not allow updating the nodes.

diff --git a/packages/lib/src/spatial-navigation/components/ScrollView.tsx b/packages/lib/src/spatial-navigation/components/ScrollView.tsx
@@ -143,7 +143,7 @@ export const SpatialNavigationScrollView = ({
     useRemotePointerScrollviewScrollProps({ pointerScrollSpeed, scrollY, scrollViewRef });
 
   const scrollToNode = useCallback(
-    (newlyFocusedElementRef: RefObject<View>) => {
+    (newlyFocusedElementRef: RefObject<View>, additionalOffset = 0) => {
       try {
         if (deviceTypeRef.current === 'remoteKeys') {
           newlyFocusedElementRef?.current?.measureLayout(
@@ -153,7 +153,7 @@ export const SpatialNavigationScrollView = ({
                 newlyFocusedElementDistanceToLeftRelativeToLayout: left,
                 newlyFocusedElementDistanceToTopRelativeToLayout: top,
                 horizontal,
-                offsetFromStart,
+                offsetFromStart: offsetFromStart + additionalOffset,
                 scrollViewRef,
               }),
             () => {},
@@ -162,7 +162,7 @@ export const SpatialNavigationScrollView = ({
       } catch {
         // A crash can happen when calling measureLayout when a page unmounts. No impact on focus detected in regular use cases.
       }
-      makeParentsScrollToNodeIfNeeded(newlyFocusedElementRef); // We need to propagate the scroll event for parents if we have nested ScrollViews/VirtualizedLists.
+      makeParentsScrollToNodeIfNeeded(newlyFocusedElementRef, additionalOffset); // We need to propagate the scroll event for parents if we have nested ScrollViews/VirtualizedLists.
     },
     [makeParentsScrollToNodeIfNeeded, horizontal, offsetFromStart, deviceTypeRef],
   );

diff --git a/...tial-navigation/components/virtualizedList/SpatialNavigationVirtualizedListWithScroll.tsx b/...tial-navigation/components/virtualizedList/SpatialNavigationVirtualizedListWithScroll.tsx
@@ -33,10 +33,10 @@ const ItemWrapperWithScrollContext = typedMemo(
       useSpatialNavigatorParentScroll();
 
     const scrollToItem: ScrollToNodeCallback = useCallback(
-      (newlyFocusedElementRef) => {
+      (newlyFocusedElementRef, additionalOffset) => {
         setCurrentlyFocusedItemIndex(item.index);
         // We need to propagate the scroll event for parents if we have nested ScrollViews/VirtualizedLists.
-        makeParentsScrollToNodeIfNeeded(newlyFocusedElementRef);
+        makeParentsScrollToNodeIfNeeded(newlyFocusedElementRef, additionalOffset);
       },
       [makeParentsScrollToNodeIfNeeded, setCurrentlyFocusedItemIndex, item.index],
     );

diff --git a/packages/lib/src/spatial-navigation/context/ParentScrollContext.ts b/packages/lib/src/spatial-navigation/context/ParentScrollContext.ts
@@ -1,7 +1,7 @@
 import { createContext, RefObject, useContext } from 'react';
 import { View } from 'react-native';
 
-export type ScrollToNodeCallback = (ref: RefObject<View>) => void;
+export type ScrollToNodeCallback = (ref: RefObject<View>, additionalOffset?: number) => void;
 export const SpatialNavigatorParentScrollContext = createContext<ScrollToNodeCallback>(() => {});
 
 export const useSpatialNavigatorParentScroll = (): {