import { Canvas, Meta } from "@storybook/blocks";
import { action } from "@storybook/addon-actions";
import "./useGridKeyboardNavigation.stories.scss";
import * as UseGridKeyboardNavigationStories from "./useGridKeyboardNavigation.stories";

<Meta of={UseGridKeyboardNavigationStories} />

# useGridKeyboardNavigation

*   [Overview](#overview)
*   [Usage](#usage)
*   [Arguments](#arguments)
*   [Returns](#returns)
*   [Feedback](#feedback)

## Overview

Used for accessible keyboard navigation. Useful for components rendering items that can be navigated and selected with a keyboard.

export const ELEMENT_WIDTH_PX = 72;
export const PADDING_PX = 24;

export const ON_CLICK = action("item selected");

<Canvas of={UseGridKeyboardNavigationStories.Overview} />

## Usage

<UsageGuidelines guidelines={["Use this hook when you want to add keyboard navigation to a grid-like component."]} />

## Arguments

<FunctionArguments>
  <FunctionArgument name="options" type="Object">
    <FunctionArgument
      name="ref"
      type="React.MutableRefObject<HTMLElement>"
      description={
        <>
          A React
          <Link href="https://react.dev/reference/react/useRef">
            ref
          </Link>
          object. The reference for the component that listens to keyboard. <br />
          <b>Important:</b> the referred element must have a <code>tabIndex={-1}</code> for the focus to work properly.
        </>
      }
      required
    />

    <FunctionArgument name="itemsCount" type="Number" description="The number of items." required />

    <FunctionArgument name="numberOfItemsInLine" type="Number" description="The number of items on each line of the grid." required />

    <FunctionArgument name="onItemClicked" type="(item, index) => void" description="The callback for selecting an item. It will be called when an active item is selected, for example with 'Enter'." required />

    <FunctionArgument name="getItemByIndex" type="(index) => item" description="A function which gets an index as a param, and returns the item on that index." />

    <FunctionArgument name="focusOnMount" type="boolean" description="If true, the referenced element will be focused when mounted." />

    <FunctionArgument
      name="focusItemIndexOnMount"
      type="number"
      description={
        <>
          Optional item index to focus when mounted. Only works with <code>options.focusOnMount</code>.
        </>
      }
    />

    <FunctionArgument name="disabledIndexes" type="number[]" description="Optional array of disabled indices, which will be skipped while navigating." />
  </FunctionArgument>
</FunctionArguments>

## Returns

<FunctionArguments>
  <FunctionArgument name="result" type="Object">
    <FunctionArgument name="activeIndex" type="number" description="The index of the currently active item." />

    <FunctionArgument
      name="onSelectionAction"
      type="(itemIndex) => void"
      description={
        <>
          A wrapper around the passed <code>onItemClicked</code> function. Use it as the handler for selecting items
          (e.g. <code>onClick</code>)
        </>
      }
    />

    <FunctionArgument
      name="isInitialActiveState"
      type="boolean"
      description={
        <>
          If true, the currently active element was due to an initial mounting index option. See{" "}
          <code>options.focusItemIndexOnMount</code>.
        </>
      }
    />
  </FunctionArgument>
</FunctionArguments>