Merge pull request #113 from bamlab/feat/add-is-root-active-mechanism

feat(core): add isRootActive mechanism

Author: Pierre Poupin

docs/api.md

@@ -26,7 +26,9 @@ ButtonContent.displayName = 'ButtonContent';
 export const Button = ({ label, onSelect }: ButtonProps) => {
   return (
     <SpatialNavigationFocusableView onSelect={onSelect}>
-      {({ isFocused }) => <ButtonContent label={label} isFocused={isFocused} />}
+      {({ isFocused, isRootActive }) => (
+        <ButtonContent label={label} isFocused={isFocused && isRootActive} />
+      )}
     </SpatialNavigationFocusableView>
   );
 };

packages/example/src/design-system/components/Button.tsx

@@ -22,8 +22,8 @@ export const ProgramNode = forwardRef<SpatialNavigationNodeRef, Props>(
         viewProps={{ accessibilityLabel: programInfo.title }}
         ref={ref}
       >
-        {({ isFocused }) => (
-          <Program isFocused={isFocused} programInfo={programInfo} label={label} />
+        {({ isFocused, isRootActive }) => (
+          <Program isFocused={isFocused && isRootActive} programInfo={programInfo} label={label} />
         )}
       </SpatialNavigationFocusableView>
     );

packages/example/src/modules/program/view/ProgramNode.tsx

@@ -12,8 +12,12 @@ type Props = {
 export const ProgramNodeLandscape = ({ programInfo, onSelect, label }: Props) => {
   return (
     <SpatialNavigationFocusableView onSelect={onSelect}>
-      {({ isFocused }) => (
-        <ProgramLandscape isFocused={isFocused} programInfo={programInfo} label={label} />
+      {({ isFocused, isRootActive }) => (
+        <ProgramLandscape
+          isFocused={isFocused && isRootActive}
+          programInfo={programInfo}
+          label={label}
+        />
       )}
     </SpatialNavigationFocusableView>
   );

packages/example/src/modules/program/view/ProgramNodeLandscape.tsx

@@ -9,7 +9,16 @@ type FocusableViewProps = {
   style?: ViewStyle;
   children:
     | React.ReactElement
-    | ((props: { isFocused: boolean; isActive: boolean }) => React.ReactElement);
+    | ((props: {
+        /** Returns whether the root is focused or not. */
+        isFocused: boolean;
+        /** Returns whether the root is active or not. An active node is active if one of its children is focused. */
+        isActive: boolean;
+        /** Returns whether the root is active or not.
+         * This is very handy if you want to hide the focus on your page elements when
+         * the side-menu is focused (since it is a different root navigator) */
+        isRootActive: boolean;
+      }) => React.ReactElement);
   viewProps?: ViewProps & {
     onMouseEnter?: () => void;
   };
@@ -49,13 +58,14 @@ export const SpatialNavigationFocusableView = forwardRef<SpatialNavigationNodeRe
 
     return (
       <SpatialNavigationNode isFocusable {...props} ref={nodeRef}>
-        {({ isFocused, isActive }) => (
+        {({ isFocused, isActive, isRootActive }) => (
           <InnerFocusableView
             viewProps={viewProps}
             webProps={webProps}
             style={style}
             isActive={isActive}
             isFocused={isFocused}
+            isRootActive={isRootActive}
           >
             {children}
           </InnerFocusableView>
@@ -78,10 +88,11 @@ type InnerFocusableViewProps = FocusableViewProps & {
       };
   isActive: boolean;
   isFocused: boolean;
+  isRootActive: boolean;
 };
 
 const InnerFocusableView = forwardRef<View, InnerFocusableViewProps>(
-  ({ viewProps, webProps, children, isActive, isFocused, style }, ref) => {
+  ({ viewProps, webProps, children, isActive, isFocused, isRootActive, style }, ref) => {
     const accessibilityProps = useSpatialNavigatorFocusableAccessibilityProps();
     const accessibilityState = useMemo(() => ({ selected: isFocused }), [isFocused]);
 
@@ -94,7 +105,9 @@ const InnerFocusableView = forwardRef<View, InnerFocusableViewProps>(
         {...viewProps}
         {...webProps}
       >
-        {typeof children === 'function' ? children({ isFocused, isActive }) : children}
+        {typeof children === 'function'
+          ? children({ isFocused, isActive, isRootActive })
+          : children}
       </View>
     );
   },

packages/lib/src/spatial-navigation/components/FocusableView.tsx

@@ -8,14 +8,33 @@ import { useUniqueId } from '../hooks/useUniqueId';
 import { NodeOrientation } from '../types/orientation';
 import { NodeIndexRange } from '@bam.tech/lrud';
 import { SpatialNavigationNodeRef } from '../types/SpatialNavigationNodeRef';
+import { useIsRootActive } from '../context/IsRootActiveContext';
 
 type FocusableProps = {
   isFocusable: true;
-  children: (props: { isFocused: boolean; isActive: boolean }) => React.ReactElement;
+  children: (props: {
+    /** Returns whether the root is focused or not. */
+    isFocused: boolean;
+    /** Returns whether the root is active or not. An active node is active if one of its children is focused. */
+    isActive: boolean;
+    /** Returns whether the root is active or not.
+     * This is very handy if you want to hide the focus on your page elements when
+     * the side-menu is focused (since it is a different root navigator) */
+    isRootActive: boolean;
+  }) => React.ReactElement;
 };
 type NonFocusableProps = {
   isFocusable?: false;
-  children: React.ReactElement | ((props: { isActive: boolean }) => React.ReactElement);
+  children:
+    | React.ReactElement
+    | ((props: {
+        /** Returns whether the root is active or not. An active node is active if one of its children is focused. */
+        isActive: boolean;
+        /** Returns whether the root is active or not.
+         * This is very handy if you want to hide the focus on your page elements when
+         * the side-menu is focused (since it is a different root navigator) */
+        isRootActive: boolean;
+      }) => React.ReactElement);
 };
 type DefaultProps = {
   onFocus?: () => void;
@@ -95,6 +114,7 @@ export const SpatialNavigationNode = forwardRef<SpatialNavigationNodeRef, Props>
   ) => {
     const spatialNavigator = useSpatialNavigator();
     const parentId = useParentId();
+    const isRootActive = useIsRootActive();
     const [isFocused, setIsFocused] = useState(false);
     const [isActive, setIsActive] = useState(false);
     // If parent changes, we have to re-register the Node + all children -> adding the parentId to the nodeId makes the children re-register.
@@ -180,7 +200,7 @@ export const SpatialNavigationNode = forwardRef<SpatialNavigationNodeRef, Props>
     return (
       <ParentIdContext.Provider value={id}>
         {typeof children === 'function'
-          ? bindRefToChild(children({ isFocused, isActive }))
+          ? bindRefToChild(children({ isFocused, isActive, isRootActive }))
           : children}
       </ParentIdContext.Provider>
     );

packages/lib/src/spatial-navigation/components/Node.tsx

@@ -5,6 +5,7 @@ import { useCreateSpatialNavigator } from '../hooks/useCreateSpatialNavigator';
 import { useRemoteControl } from '../hooks/useRemoteControl';
 import { OnDirectionHandledWithoutMovement } from '../SpatialNavigator';
 import { LockSpatialNavigationContext, useIsLocked } from '../context/LockSpatialNavigationContext';
+import { IsRootActiveContext } from '../context/IsRootActiveContext';
 
 const ROOT_ID = 'root';
 
@@ -13,6 +14,8 @@ type Props = {
    * Determines if the spatial navigation is active.
    * If false, the spatial navigation will be locked, and no nodes can be focused.
    * This is useful to handle a multi page app: you can disable the non-focused pages' spatial navigation roots.
+   *
+   * Note: this is a little redundant with the lock system, but it's useful to have a way to disable the spatial navigation from above AND from below.
    */
   isActive?: boolean;
   /**
@@ -45,7 +48,8 @@ export const SpatialNavigationRoot = ({
 
   const { isLocked, lockActions } = useIsLocked();
 
-  useRemoteControl({ spatialNavigator, isActive: isActive && !isLocked });
+  const isRootActive = isActive && !isLocked;
+  useRemoteControl({ spatialNavigator, isActive: isRootActive });
 
   useEffect(() => {
     spatialNavigator.registerNode(ROOT_ID, { orientation: 'vertical' });
@@ -55,7 +59,9 @@ export const SpatialNavigationRoot = ({
   return (
     <SpatialNavigatorContext.Provider value={spatialNavigator}>
       <LockSpatialNavigationContext.Provider value={lockActions}>
-        <ParentIdContext.Provider value={ROOT_ID}>{children}</ParentIdContext.Provider>
+        <IsRootActiveContext.Provider value={isRootActive}>
+          <ParentIdContext.Provider value={ROOT_ID}>{children}</ParentIdContext.Provider>
+        </IsRootActiveContext.Provider>
       </LockSpatialNavigationContext.Provider>
     </SpatialNavigatorContext.Provider>
   );

packages/lib/src/spatial-navigation/components/Root.tsx

@@ -0,0 +1,7 @@
+import { createContext, useContext } from 'react';
+
+export const IsRootActiveContext = createContext<boolean>(true);
+
+export const useIsRootActive = () => {
+  return useContext(IsRootActiveContext);
+};