import { Canvas, Controls, Meta } from '@storybook/blocks'
import { ResourceLinks, KAIOInstallation, RenameNotice } from '~storybook/components'
import * as TitleBlockStories from './TitleBlock.stories'

<Meta title="Components/TitleBlock/API Specification" />

# TitleBlock

<ResourceLinks
  sourceCode="https://github.com/cultureamp/kaizen-design-system/tree/main/packages/components/src/TitleBlock"
  designGuidelines="/?path=/docs/components-titleblock-usage-guidelines--docs"
/>

<KAIOInstallation exportNames="TitleBlock" />

## Overview

`TitleBlock` A consistent pattern to allow users to navigate and complete tasks easily.

<Canvas of={TitleBlockStories.Playground} />

## Props

<Controls
  of={TitleBlockStories.Playground}
  include={[
    'avatar',
    'breadcrumb',
    'defaultAction',
    'handleHamburgerClick',
    'navigationTabs',
    'primaryAction',
    'secondaryActions',
    'secondaryOverflowMenuItems',
    'surveyStatus',
    'title',
  ]}
/>

## Options

### primaryAction

The primary action (the "main" button in the top right) can either be a Button,
or a Button that reveals a Menu (a menu button).

If you want it to be a Button, you can't pass in a `<Button />`, because the Title Block needs to grab the Button's
props and use them to render the mobile actions drawer as well as the Button itself. Instead, you have to pass
in the Button's props as an object, and there must be a `primary` property set to `true`.

```
type PrimaryActionProps =
 | MenuGroup
 | (TitleBlockButtonProps & { primary: true });
```

If you want it to be a Menu, pass in this object of type `MenuGroup`:

```
{
  label: string
  menuItems: MenuItemProps[]
}
```

Using the `label`, the Title Block will render a Button with a chevron icon and your `menuItems` will appear
in the dropdown menu when you click it. (`MenuItemProps` is a type imported from the `Menu` component.)

### secondaryActions & secondaryOverflowMenuItems

Secondary Actions sit below the Primary Actions, and consist of

- actions/links (just a button),
- menus (a menu button), and
- the overflow menu (a menu button with a "meatballs" icon).

**IMPORTANT:** The visual order of these from left to right should always be:

```text
buttons (far left) -> menu buttons -> overflow menu (far right)
```

The overflow menu has a separate prop that accepts an array of `MenuItemProps`:

```
secondaryOverflowMenuItems?: MenuItemProps[]
```

The `secondaryActions` prop accepts an **array** of objects.
Each object can be a MenuGroup (see code snippet for `primaryAction` above) or an object containing Button props:

```
type SecondaryActionsProps = Array<MenuGroup | TitleBlockButtonProps>;
```

The order of elements in the array will determine the visual order on the page, so
please be aware of the intended order mentioned above.