Added GridKeyboardNavigationContext

plop/stories/index.js

@@ -2,7 +2,7 @@ const fs = require("fs");
 
 module.exports = plop => {
   plop.setGenerator("Stories", {
-    description: "New stories files fore existing component",
+    description: "New stories files for existing component",
     prompts: [
       {
         type: "input",

src/components/GridKeyboardNavigationContext/GridKeyboardNavigationContext.js

@@ -0,0 +1,39 @@
+import React, { useRef, useContext, useCallback } from "react";
+import useEventListener from "../../hooks/useEventListener";
+import { focusElementWithDirection, getDirectionMaps, getOppositeDirection, getOutmostElementInDirection } from "./GridKeyboardNavigationContextHelper";
+
+export const GridKeyboardNavigationContext = React.createContext();
+
+export const useGridKeyboardNavigationContext = (positions, wrapperRef) => {
+  const directionMaps = useRef(getDirectionMaps(positions));
+  const upperContext = useContext(GridKeyboardNavigationContext);
+
+  const onWrapperFocus = useCallback(
+    e => {
+      const keyboardDirection = e?.detail?.keyboardDirection;
+      if (!keyboardDirection) {
+        return;
+      }
+      const oppositeDirection = getOppositeDirection(keyboardDirection);
+      const elementToFocus = getOutmostElementInDirection(directionMaps.current, oppositeDirection);
+      focusElementWithDirection(elementToFocus, keyboardDirection);
+    },
+    [directionMaps]
+  );
+  useEventListener({ eventName: "focus", callback: onWrapperFocus, ref: wrapperRef });
+
+  const onOutboundNavigation = useCallback(
+    (elementRef, direction) => {
+      const maybeNextElement = directionMaps.current[direction].get(elementRef);
+      if (maybeNextElement?.current) {
+        elementRef.current?.blur();
+        focusElementWithDirection(maybeNextElement, direction);
+        return;
+      }
+      // nothing on that direction - try updating the upper context
+      upperContext?.onOutboundNavigation(wrapperRef, direction);
+    },
+    [upperContext, wrapperRef]
+  );
+  return { onOutboundNavigation };
+};

src/components/GridKeyboardNavigationContext/GridKeyboardNavigationContextHelper.js

@@ -0,0 +1,51 @@
+import { NAV_DIRECTIONS } from "../../hooks/useFullKeyboardListeners";
+
+export const getDirectionMaps = positions => {
+  const directionMaps = {
+    [NAV_DIRECTIONS.RIGHT]: new Map(),
+    [NAV_DIRECTIONS.LEFT]: new Map(),
+    [NAV_DIRECTIONS.UP]: new Map(),
+    [NAV_DIRECTIONS.DOWN]: new Map()
+  };
+  positions.forEach(position => {
+    if (position.topElement && position.bottomElement) {
+      directionMaps[NAV_DIRECTIONS.UP].set(position.bottomElement, position.topElement);
+      directionMaps[NAV_DIRECTIONS.DOWN].set(position.topElement, position.bottomElement);
+    }
+    if (position.leftElement && position.rightElement) {
+      directionMaps[NAV_DIRECTIONS.LEFT].set(position.rightElement, position.leftElement);
+      directionMaps[NAV_DIRECTIONS.RIGHT].set(position.leftElement, position.rightElement);
+    }
+  });
+  return directionMaps;
+};
+
+export const getOppositeDirection = direction => {
+  if (direction === NAV_DIRECTIONS.LEFT) return NAV_DIRECTIONS.RIGHT;
+  if (direction === NAV_DIRECTIONS.RIGHT) return NAV_DIRECTIONS.LEFT;
+  if (direction === NAV_DIRECTIONS.UP) return NAV_DIRECTIONS.DOWN;
+  if (direction === NAV_DIRECTIONS.DOWN) return NAV_DIRECTIONS.UP;
+};
+
+export const focusElementWithDirection = (elementRef, direction) =>
+  elementRef?.current?.dispatchEvent(new CustomEvent("focus", { detail: { keyboardDirection: direction } }));
+
+export const getOutmostElementInDirection = (directionMaps, direction) => {
+  const directionMap = directionMaps[direction];
+  const firstEntry = [...directionMap][0]; // start with any element
+  if (!firstEntry) {
+    // no relations were registered for this direction - fallback to a different direction
+    if ([NAV_DIRECTIONS.LEFT, NAV_DIRECTIONS.RIGHT].includes(direction)) {
+      // there are no registered horizontal relations registered, try vertical relations. Get the top-most element.
+      return getOutmostElementInDirection(directionMaps, NAV_DIRECTIONS.UP);
+    }
+    // there are no registered vertical relations registered, try horizontal relations. Get the left-most element.
+    return getOutmostElementInDirection(directionMaps, NAV_DIRECTIONS.LEFT);
+  }
+  let result = firstEntry?.[0];
+  while (directionMap.get(result)) {
+    // as long as there's an element which is outward of the keyboard direction, take it.
+    result = directionMap.get(result);
+  }
+  return result;
+};

src/components/GridKeyboardNavigationContext/__stories__/useGridKeyboardNavigationContext.stories.js

@@ -0,0 +1,70 @@
+import range from "lodash/range";
+import { forwardRef, useMemo, useCallback, useRef } from "react";
+import cx from "classnames";
+import { action } from "@storybook/addon-actions";
+import { Button, Flex } from "../..";
+import useGridKeyboardNavigation from "../../../hooks/useGridKeyboardNavigation/useGridKeyboardNavigation";
+import "./useGridKeyboardNavigationContext.stories.scss";
+import { GridKeyboardNavigationContext, useGridKeyboardNavigationContext } from "../GridKeyboardNavigationContext";
+
+const ELEMENT_WIDTH_PX = 72;
+const PADDING_PX = 24;
+
+const ON_CLICK = action("Selected");
+
+export const DummyNavigableGrid = forwardRef(({ itemsCount, numberOfItemsInLine, itemPrefix }, ref) => {
+  const width = useMemo(() => numberOfItemsInLine * ELEMENT_WIDTH_PX + 2 * PADDING_PX, [numberOfItemsInLine]);
+  const items = useMemo(() => range(itemsCount).map(num => `${itemPrefix} ${num}`), [itemPrefix, itemsCount]);
+  const getItemByIndex = useCallback(index => items[index], [items]);
+  const { activeIndex, onSelectionAction } = useGridKeyboardNavigation({
+    ref,
+    numberOfItemsInLine,
+    itemsCount,
+    getItemByIndex,
+    onItemClicked: ON_CLICK
+  });
+  const onClickByIndex = useCallback(index => () => onSelectionAction(index), [onSelectionAction]);
+  return (
+    <div
+      className="use-grid-keyboard-dummy-grid-wrapper"
+      style={{ width }}
+      ref={ref}
+      tabIndex={-1}
+    >
+      {items.map((item, index) => (
+        <Button
+          key={item}
+          kind={Button.kinds.SECONDARY}
+          onClick={onClickByIndex(index)}
+          className={cx("use-grid-keyboard-dummy-grid-item", { "active-item": index === activeIndex })}
+        >
+          {item}
+        </Button>
+      ))}
+    </div>
+  );
+});
+
+export const LayoutWithInnerKeyboardNavigation = forwardRef((_ignored, ref) => {
+  const leftElRef = useRef(null);
+  const rightElRef = useRef(null);
+  const bottomElRef = useRef(null);
+  const keyboardContext = useGridKeyboardNavigationContext(
+    [
+      { leftElement: leftElRef, rightElement: rightElRef },
+      { topElement: leftElRef, bottomElement: bottomElRef }
+    ],
+    ref
+  );
+  return (
+    <GridKeyboardNavigationContext.Provider value={keyboardContext}>
+      <Flex ref={ref} direction={Flex.directions.COLUMN} align={Flex.align.START} className="use-grid-keyboard-dummy-grid-wrapper">
+        <Flex>
+          <DummyNavigableGrid ref={leftElRef} itemsCount={6} numberOfItemsInLine={3} itemPrefix="L " />
+          <DummyNavigableGrid ref={rightElRef} itemsCount={6} numberOfItemsInLine={2} itemPrefix="R " />
+        </Flex>
+        <DummyNavigableGrid ref={bottomElRef} itemsCount={6} numberOfItemsInLine={2} itemPrefix="B " />
+      </Flex>
+    </GridKeyboardNavigationContext.Provider>
+  );
+});

src/components/GridKeyboardNavigationContext/__stories__/useGridKeyboardNavigationContext.stories.mdx

@@ -0,0 +1,109 @@
+import { useRef } from "react";
+import { useGridKeyboardNavigationContext, GridKeyboardNavigationContext } from "../GridKeyboardNavigationContext";
+import { ArgsTable, Story, Canvas, Meta } from "@storybook/addon-docs";
+import { createStoryMetaSettings } from "../../../storybook/functions/create-component-story";
+import { DummyNavigableGrid, LayoutWithInnerKeyboardNavigation } from "./useGridKeyboardNavigationContext.stories";
+import { Flex } from "../..";
+
+export const metaSettings = createStoryMetaSettings({
+  component: useGridKeyboardNavigationContext
+});
+
+<Meta 
+  title="Hooks/useGridKeyboardNavigationContext" 
+  component={ useGridKeyboardNavigationContext } 
+  argTypes={ metaSettings.argTypes }
+  decorators={ metaSettings.decorators } 
+  />
+
+<!--- Component documentation -->
+
+# useGridKeyboardNavigationContext
+
+- [Overview](#overview)
+- [Usage](#usage)
+- [Arguments](#arguments)
+- [Returns](#returns)
+- [Feedback](#feedback)
+
+## Overview
+
+A hook used to specify a connection between multiple navigable components, which are navigable between each other.
+
+<Canvas>
+  <Story name="Overview">{
+    () => {
+      const wrapperRef = useRef(null);
+      const leftElRef = useRef(null);
+      const rightElRef = useRef(null);
+      const keyboardContext = useGridKeyboardNavigationContext([{leftElement: leftElRef, rightElement: rightElRef}], wrapperRef)
+      return (
+        <GridKeyboardNavigationContext.Provider value={keyboardContext}>
+          <Flex ref={wrapperRef}>
+            <DummyNavigableGrid ref={leftElRef} itemsCount={15} numberOfItemsInLine={4} itemPrefix="L "/>
+            <DummyNavigableGrid ref={rightElRef} itemsCount={7} numberOfItemsInLine={2} itemPrefix="R "/>
+          </Flex>
+        </GridKeyboardNavigationContext.Provider>
+      )
+  }}</Story>
+</Canvas>
+
+## Usage
+
+<UsageGuidelines
+  guidelines={[
+    "Use this hook when you want to add keyboard navigation between multiple grid-like components.",
+    "Each of the components should use `useGridKeyboardNavigation`.",
+    "The components should be wrapped with a single `GridKeyboardNavigationContext`."
+  ]}
+/>
+
+
+## Arguments
+<FunctionArguments>
+  <FunctionArgument 
+    name="positions" 
+    type="Array[ { topElement: React.MutableRefObject, bottomElement: React.MutableRefObject } | { leftElement: React.MutableRefObject, rightElement: React.MutableRefObject } ]"
+    description="An array of relations between pairs of elements"
+    required
+  />
+  <FunctionArgument 
+    name="wrapperRef" 
+    type="React.MutableRefObject"
+    description={<>A React ref for an element which contains all the elements which are listed on the <code>positions</code> argument.</>}
+    required
+  />
+</FunctionArguments>
+
+## Returns
+
+<FunctionArguments>
+  <FunctionArgument 
+    name="result" 
+    type="Object"
+    description={<>A <code>GridKeyboardNavigationContext</code> which should be provided to wrap all the elements from <code>positions</code></>}
+  />
+</FunctionArguments>
+
+## Variants
+
+### Multiple Depths
+The hook can be used inside multiple depths, in more complex layout requirements.
+
+<Canvas>
+  <Story name="Multiple Depths">{
+    () => {
+      const wrapperRef = useRef(null);
+      const topElRef = useRef(null);
+      const bottomElRef = useRef(null);
+      const keyboardContext = useGridKeyboardNavigationContext([{topElement: topElRef, bottomElement: bottomElRef}], wrapperRef)
+      return (
+      <GridKeyboardNavigationContext.Provider value={keyboardContext}>
+        <Flex ref={wrapperRef} direction={Flex.directions.COLUMN}>
+          <LayoutWithInnerKeyboardNavigation ref={topElRef} />
+          <LayoutWithInnerKeyboardNavigation ref={bottomElRef} />
+        </Flex>
+      </GridKeyboardNavigationContext.Provider>
+      );
+  }}</Story>
+</Canvas>

src/components/GridKeyboardNavigationContext/__stories__/useGridKeyboardNavigationContext.stories.scss

@@ -0,0 +1,21 @@
+@import "../../../styles/states.scss";
+@import "../../../styles/typography.scss";
+@import "../../../styles/global-css-settings.scss";
+
+.use-grid-keyboard-dummy-grid-wrapper {
+    padding: 12px;
+    display: flex;
+    flex-wrap: wrap;
+    outline: none;
+    text-align: center;
+    box-shadow: 0 0 0 1px rgba(0, 0, 0, 0.1), 0 0 0 1px var(--primary-hover-color) inset;
+}
+
+.use-grid-keyboard-dummy-grid-item {
+    width: 60px;
+    margin: $spacing-xs-small;
+
+    &.active-item {
+        @include focus-style-css();
+    }
+}