import { Canvas, Meta } from "@storybook/blocks";
import { MENU, MENU_BUTTON } from "../../../../storybook/components/related-components/component-description-map";
import { TipOtherMenuItemComponents } from "./MenuGridItem.stories.helpers";
import * as MenuGridItemStories from "./MenuGridItem.stories";

<Meta of={MenuGridItemStories} />

# MenuGridItem

- [Overview](#overview)
- [Props](#props)
- [Usage](#usage)
- [Use cases and examples](#use-cases-and-examples)
- [Related components](#related-components)
- [Feedback](#feedback)

## Overview

<code>MenuGridItem</code> can be used to place a grid-like, keyboard navigable container, inside a Menu. The user will be
able to interact and navigate into and from the grid in a natural way.

<Canvas of={MenuGridItemStories.Overview} />

## Props

Since <code>MenuGridItem</code> should be used only inside a <code>Menu</code>, almost all of the props below will be supplied automatically by the wrapping <code>Menu</code>.

<PropsTable />

## Usage

<UsageGuidelines
  guidelines={[
    "MenuGridItem should always be used inside a Menu component",
    "A MenuGridItem can only have a single child",
    "The child of MenuGridItem should use the useGridKeyboardNavigation hook",
    "The child should use forwardRef, and have the same referenced element for useGridKeyboardNavigation.",
    <>
      Also, the referenced element should have a <code>tabIndex</code> value (probably -1).
    </>,
    <>
      MenuGridItem will pass the <code>disabled</code> prop to the child. The child should handle this prop and disable
      interactions.
    </>,
    <>
      To support a "disabled" mode, the child must have a prop named <code>disabled</code> (it will be automatically
      detected).
    </>,
    <>
      NOTE: Due to technical limitations, <code>useDocumentEventListeners</code> is not fully supported.
    </>
  ]}
/>

<TipOtherMenuItemComponents />

## Use cases and examples

### With disabled states

Disabled items will be "skipped" when using keyboard navigation. Try it for yourself!

<Canvas of={MenuGridItemStories.WithDisabledStates} />

### Inside sub-menus

Keyboard navigation is also supported in sub-menus

<Canvas of={MenuGridItemStories.InsideSubMenus} />

## Related components

<RelatedComponents componentsNames={[MENU, MENU_BUTTON]} />