import { Story, ArgTypes, Canvas, Meta } from '@storybook/addon-docs/blocks';
import * as PageHeaderStories from './PageHeader.stories';
import { stackblitzPrefillConfig } from '../../../previewer/codePreviewer';

<Meta isTemplate />

# PageHeader

[Source code](https://github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/PageHeader)
&nbsp;|&nbsp;
[Usage guidelines](https://www.carbondesignsystem.com/components/page-header/usage)
&nbsp;|&nbsp;
[Accessibility](https://www.carbondesignsystem.com/components/page-header/accessibility)

{/* <!-- START doctoc generated TOC please keep comment here to allow auto update --> <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> */}

## Table of Contents

- [Overview](#overview)
- [PageHeader.BreadcrumbBar](#pageheaderbreadcrumbbar)
- [PageHeader.Content](#pageheadercontent)
  - [PageHeader.Content With Hero Image](#pageheadercontent-with-hero-image)
- [PageHeader.TabsBar](#pageheadertabsbar)
  - [PageHeader.TabsBar With Tags](#pageheadertabsbar-with-tags)
- [Component API](#component-api)
- [Feedback](#feedback)

{/* <!-- END doctoc generated TOC please keep comment here to allow auto update --> */}

## Overview

The `PageHeader` is a large family of components, composed of three zones; the Breadcrumb, Content, and Tabs.

<Canvas
  of={PageHeaderStories.Default}
  additionalActions={[
    {
      title: 'Open in Stackblitz',
      onClick: () => stackblitzPrefillConfig(PageHeaderStories.Default),
    },
  ]}
/>

## PageHeader.BreadcrumbBar

The `PageHeader.BreadcrumbBar` component is used to render the breadcrumb navigation area within the `PageHeader`.
It accepts `Breadcrumb` and `BreadcrumbItem` components as children to define the breadcrumb trail. Additionally, it accepts
`contentActions` and` pageActions` props, allowing for actions, such as `Button` or `IconButton` — alongside
the breadcrumb content.

```jsx
import { Bee, Activity } from '@carbon/icons-react';

const BeeIcon = () => <Bee size={16} />;

const pageActions = (
  <Button
    renderIcon={Activity}
    iconDescription="Icon Description 1"
    hasIconOnly
    size="md"
    kind="ghost"
  />
);

const contentActions = (
  <Button size="md">Button</Button>
)

return (
  <PageHeader.Root>
    <PageHeader.BreadcrumbBar
      renderIcon={BeeIcon}
      contentActions={contentActions}
      pageActions={pageActions}>
      <Breadcrumb>
        <BreadcrumbItem href="/#">Breadcrumb 1</BreadcrumbItem>
        <BreadcrumbItem href="#">Breadcrumb 2</BreadcrumbItem>
      </Breadcrumb>
    </PageHeader.BreadcrumbBar>
    ...
  </PageHeader.Root>
)
```

## PageHeader.Content

<Canvas
  of={PageHeaderStories.ContentWithContextualActionsAndPageActions}
  additionalActions={[
    {
      title: 'Open in Stackblitz',
      onClick: () => stackblitzPrefillConfig(PageHeaderStories.ContentWithContextualActionsAndPageActions),
    },
  ]}
/>

The `PageHeader.Content` component defines the primary content area of the `PageHeader`, including the title, subtitle, and
any supporting text or contextual actions. It accepts a `title` prop to display the main heading and can optionally include a `renderIcon` prop
to show an icon adjacent to the title. Child components such as `PageHeader.ContentText` can be used to provide additional descriptive text.
To support use cases such as tags, `contextualActions` can be passed as a prop to render components beside the content.
`pageActions` allows integration of action buttons aligned with the content section.

The `PageHeader.ContentPageActions` component provides responsive behavior by collapsing actions into a `MenuButton` when the viewport
width is reduced. To enable this functionality, it expects an array of action objects with a specific API shape, as demonstrated below:

```jsx

const actionItems = [
  {
    // props used for both collapse menu item and non-collapsed action form
    id: 'action1',
    onClick: () => console.log(`Action 1`),
    // component to render when non-collapsed
    body: (
      <Button
        renderIcon={AiGenerate}
        iconDescription="Icon Description 1"
        hasIconOnly
        size="md"
        kind="ghost"
      />
    ),
    // props to pass to the corresponding collapsed menu item
    menuItem: {
      label: 'action 1',
    },
  },
  ...
];

return (
  <PageHeader.Root>
   ...
    <PageHeader.Content
      title="Title text"
      contextualActions={
        <>
          <Tag className="tag" type="blue" size="lg">
            Moop
          </Tag>
        </>
      }
      pageActions={
        <PageHeader.ContentPageActions
          menuButtonLabel="Actions"
          actions={actionItems}></PageHeader.ContentPageActions>
      }>
      <PageHeader.ContentText subtitle="Subtitle">
        Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
        tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
        veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex.
      </PageHeader.ContentText>
    </PageHeader.Content>
  </PageHeader.Root>
)
```

### PageHeader.Content With Hero Image

<Canvas
  of={PageHeaderStories.ContentWithHeroImage}
  additionalActions={[
    {
      title: 'Open in Stackblitz',
      onClick: () => stackblitzPrefillConfig(PageHeaderStories.ContentWithHeroImage),
    },
  ]}
/>

When including a hero image within the `PageHeader`, the `Grid` and `Column` components will need to be utilized in order
to define the layout correctly.

```jsx
import { Grid, Column } from '@carbon/react';

return (
  <PageHeader.Root>
    <Grid>
      <Column lg={8} md={4} sm={4}>
        <PageHeader.BreadcrumbBar ... />
        <PageHeader.Content ... />
      </Column>
      <Column lg={8} md={4} sm={0}>
        <PageHeader.HeroImage>
          <picture>
            <source
              srcset={image1}
              media={`(min-width: ${breakpoints.lg.width})`}
            />
            <source
              srcset={image2}
              media={`(max-width: ${breakpoints.lg.width})`}
            />
            <img
              src={image1}
              alt="a default image"
              style={{ maxWidth: '100%', height: 'auto' }}
            />
          </picture>
        </PageHeader.HeroImage>
      </Column>
    </Grid>
  </PageHeader.Root>
)

```

## PageHeader.TabsBar

To render the Tabs zone, utilitize the `PageHeader.TabBar` component, passing in the `TabList` and `Tab` components
as its children. Then set up the `TabPanels` and `TabPanel` components outside of the `PageHeader`, making sure to
wrap all components within the `Tabs` component to ensures proper linkage of tab and its associated panel.

```jsx
<Tabs>
  <PageHeader.Root>
    ...
    <PageHeader.TabBar>
      <TabList>
        <Tab>Dashboard</Tab>
        <Tab>Monitoring</Tab>
        <Tab>Activity</Tab>
        <Tab>Settings</Tab>
      </TabList>
    </PageHeader.TabBar>
  </PageHeader.Root>
  <TabPanels>
    <TabPanel>Dashboard Tab Panel</TabPanel>
    <TabPanel>Monitoring Tab Panel</TabPanel>
    <TabPanel>Activity Tab Panel</TabPanel>
    <TabPanel>Settings Tab Panel</TabPanel>
  </TabPanels>
</Tabs>
```

### PageHeader.TabsBar With Tags

<Canvas
  of={PageHeaderStories.TabBarWithTabsAndTags}
  additionalActions={[
    {
      title: 'Open in Stackblitz',
      onClick: () => stackblitzPrefillConfig(PageHeaderStories.TabBarWithTabsAndTags),
    },
  ]}
/>

The `PageHeader.TabsBar` component accepts a `tags` prop expecting an array of objects as shown below. When the viewport
width is reduced, these tags automatically collapse into a `Popover` for responsive display.

```jsx
const tags = [
  {
    type: 'blue',
    text: 'Tag 1',
    size: 'md',
  },
  {
    type: 'purple',
    text: 'Tag 2',
    size: 'md',
  },
];

return (
<Tabs>
  <PageHeader.Root>
    <PageHeader.TabBar tags={tags}>
      <TabList>
        <Tab>Tab 1</Tab>
        ...
      </TabList>
    </PageHeader.TabBar>
  </PageHeader.Root>
  <TabPanels>
    <TabPanel>Tab Panel 1</TabPanel>
    ...
  </TabPanels>
</Tabs>
);
```

## Component API

<ArgTypes />

## Feedback

Help us improve this component by providing feedback, asking questions on Slack,
or updating this file on
[GitHub](https://github.com/carbon-design-system/carbon/edit/main/packages/react/src/components/PageHeader/PageHeader.mdx).
