From dbd50a6c09b159a8df11648c11c3fd1f8c251812 Mon Sep 17 00:00:00 2001
From: David Linke <davelinke@users.noreply.github.com>
Date: Fri, 30 Aug 2024 11:38:56 -0400
Subject: [PATCH] docs: add header pattern documentation (#1523)

* docs(patterns): add header documentation

* feat(patterns): add pattern links in main readme

* docs(patterns): add BackLink props to Header documentation

* docs(patterns): simplify header code sample

* docs(patterns): add changeset on Header component documentation

* docs(patterns): fix nativeElement props for BackLink props

* docs(patterns): lint HeaderPropTable and header doc page

* chore: pr comments

---------

Co-authored-by: Chancellor Clark <chancellor.clark@bigcommerce.com>
---
 .changeset/cyan-games-pump.md                 |   5 +
 README.md                                     |   2 +
 packages/docs/PropTables/HeaderPropTable.tsx  | 119 +++++++++++++++
 .../components/CodePreview/CodePreview.tsx    |   2 +
 .../docs/components/PropTable/PropTable.tsx   |   4 +-
 packages/docs/components/SideNav/SideNav.tsx  |   4 +
 packages/docs/pages/header.tsx                | 140 ++++++++++++++++++
 7 files changed, 274 insertions(+), 2 deletions(-)
 create mode 100644 .changeset/cyan-games-pump.md
 create mode 100644 packages/docs/PropTables/HeaderPropTable.tsx
 create mode 100644 packages/docs/pages/header.tsx

diff --git a/.changeset/cyan-games-pump.md b/.changeset/cyan-games-pump.md
new file mode 100644
index 000000000..9646e985f
--- /dev/null
+++ b/.changeset/cyan-games-pump.md
@@ -0,0 +1,5 @@
+---
+'@bigcommerce/docs': patch
+---
+
+Added Header component documentation
diff --git a/README.md b/README.md
index 34c360d15..775924772 100644
--- a/README.md
+++ b/README.md
@@ -58,6 +58,7 @@ Workspaces are inside the [packages](https://github.com/bigcommerce/big-design/b
 - [big-design](https://github.com/bigcommerce/big-design/blob/main/packages/big-design): React component library.
 - [big-design-theme](https://github.com/bigcommerce/big-design/blob/main/packages/big-design-theme): Default Theme.
 - [big-design-icons](https://github.com/bigcommerce/big-design/blob/main/packages/big-design-icons): Icons library.
+- [big-design-patterns](https://github.com/bigcommerce/big-design/tree/main/packages/big-design-patterns): Pattern library.
 - [docs](https://github.com/bigcommerce/big-design/blob/main/packages/docs): Documentation live here.
 - [configs](https://github.com/bigcommerce/big-design/blob/main/packages/configs): (internal) Shared configs between packages.
 
@@ -68,6 +69,7 @@ As this is a monorepo, each package has it's own Changelog. Links for each can b
 - [big-design](https://github.com/bigcommerce/big-design/blob/main/packages/big-design/CHANGELOG.md)
 - [big-design-theme](https://github.com/bigcommerce/big-design/blob/main/packages/big-design-theme/CHANGELOG.md)
 - [big-design-icons](https://github.com/bigcommerce/big-design/blob/main/packages/big-design-icons/CHANGELOG.md)
+- [big-design-patterns](https://github.com/bigcommerce/big-design/blob/main/packages/big-design-patterns/CHANGELOG.md)
 - [configs](https://github.com/bigcommerce/big-design/tree/main/packages/configs)
 - [docs](https://github.com/bigcommerce/big-design/blob/main/packages/docs/CHANGELOG.md)
 
diff --git a/packages/docs/PropTables/HeaderPropTable.tsx b/packages/docs/PropTables/HeaderPropTable.tsx
new file mode 100644
index 000000000..d91550e09
--- /dev/null
+++ b/packages/docs/PropTables/HeaderPropTable.tsx
@@ -0,0 +1,119 @@
+import React from 'react';
+
+import { NextLink, Prop, PropTable, PropTableWrapper } from '../components';
+
+const headerProps: Prop[] = [
+  {
+    name: 'title',
+    types: 'string',
+    description: 'The main title of the header.',
+    required: true,
+  },
+  {
+    name: 'actions',
+    types: (
+      <>
+        {'Array<'}
+        <NextLink href={{ hash: 'action-button-prop-table', query: { props: 'action-button' } }}>
+          ActionButton
+        </NextLink>
+        {' | '}
+        <NextLink
+          href={{ hash: 'action-dropdown-prop-table', query: { props: 'action-dropdown' } }}
+        >
+          ActionDropdown
+        </NextLink>
+        {'>'}
+      </>
+    ),
+    description: 'An array of actions to display in the header. Can include buttons or dropdowns.',
+  },
+  {
+    name: 'backLink',
+    types: (
+      <NextLink href={{ hash: 'backlink-prop-table', query: { props: 'back-link' } }}>
+        BackLink
+      </NextLink>
+    ),
+    description: 'Configuration for a back link displayed at the top left of the header.',
+  },
+  {
+    name: 'badge',
+    types: (
+      <NextLink href="/badge#props" key="badge-type">
+        BadgeProps
+      </NextLink>
+    ),
+    description: 'Props to display a badge next to the title.',
+  },
+  {
+    name: 'description',
+    types: [
+      'string',
+      <NextLink
+        href={{ pathname: '/typography', query: { implementation: 'text', props: 'text' } }}
+        key="text-type"
+      >
+        Text
+      </NextLink>,
+    ],
+    description: 'A description to display under the title.',
+  },
+  {
+    name: 'icon',
+    types: 'ReactNode',
+    description: 'An icon to display to the left of the title.',
+  },
+];
+
+export const HeaderPropTable: React.FC<PropTableWrapper> = (props) => (
+  <PropTable propList={headerProps} title="Header" {...props} />
+);
+
+const actionButtonProps: Prop[] = [
+  {
+    name: 'text',
+    types: 'string',
+    description: 'The text content of the button.',
+    required: true,
+  },
+];
+
+export const ActionButtonPropsTable: React.FC<PropTableWrapper> = (props) => (
+  <PropTable propList={actionButtonProps} title="Header[ActionButton]" {...props} />
+);
+
+const actionDropdownProps: Prop[] = [
+  {
+    name: 'toggle',
+    types: (
+      <NextLink href={{ hash: 'action-button-prop-table', query: { props: 'action-button' } }}>
+        ActionButton
+      </NextLink>
+    ),
+    description: 'The button used to toggle the dropdown.',
+    required: true,
+  },
+];
+
+export const ActionDropdownPropsTable: React.FC<PropTableWrapper> = (props) => (
+  <PropTable propList={actionDropdownProps} title="Header[ActionDropdown]" {...props} />
+);
+
+const backLinkProps: Prop[] = [
+  {
+    name: 'text',
+    types: 'string',
+    description: 'The text content of the back link.',
+    required: true,
+  },
+];
+
+export const BackLinkPropsTable: React.FC<PropTableWrapper> = (props) => (
+  <PropTable
+    nativeElement={['a', 'all']}
+    propList={backLinkProps}
+    title="Header[BackLink]"
+    {...props}
+  />
+);
diff --git a/packages/docs/components/CodePreview/CodePreview.tsx b/packages/docs/components/CodePreview/CodePreview.tsx
index 90079f654..62dea7e56 100644
--- a/packages/docs/components/CodePreview/CodePreview.tsx
+++ b/packages/docs/components/CodePreview/CodePreview.tsx
@@ -1,6 +1,7 @@
 import { transform } from '@babel/standalone';
 import * as BigDesign from '@bigcommerce/big-design';
 import * as BigDesignIcons from '@bigcommerce/big-design-icons';
+import * as BigDesignPatterns from '@bigcommerce/big-design-patterns';
 import clipboardCopy from 'clipboard-copy';
 import parser from 'prettier/parser-babel';
 import { format } from 'prettier/standalone';
@@ -16,6 +17,7 @@ import { StyledLiveError } from './styled';
 const defaultScope = {
   ...BigDesign,
   ...BigDesignIcons,
+  ...BigDesignPatterns,
   React,
   useEffect,
   useState,
diff --git a/packages/docs/components/PropTable/PropTable.tsx b/packages/docs/components/PropTable/PropTable.tsx
index cce3c0c7a..a831c9c04 100644
--- a/packages/docs/components/PropTable/PropTable.tsx
+++ b/packages/docs/components/PropTable/PropTable.tsx
@@ -41,10 +41,10 @@ export const PropTable: FC<PropTableProps> = (props) => {
                 header: 'Prop name',
                 hash: 'propName',
                 render: ({ name, required }) => (
-                  <>
+                  <span style={{ whiteSpace: 'nowrap' }}>
                     <Code primary>{name}</Code>
                     {required ? <b> *</b> : null}
-                  </>
+                  </span>
                 ),
               },
               {
diff --git a/packages/docs/components/SideNav/SideNav.tsx b/packages/docs/components/SideNav/SideNav.tsx
index 0b34edae0..cad3c699d 100644
--- a/packages/docs/components/SideNav/SideNav.tsx
+++ b/packages/docs/components/SideNav/SideNav.tsx
@@ -102,6 +102,10 @@ export const SideNav: React.FC = () => {
                 <SideNavLink href="/tooltip">Tooltip</SideNavLink>
               </SideNavGroup>
 
+              <SideNavGroup title="Patterns">
+                <SideNavLink href="/header">Header</SideNavLink>
+              </SideNavGroup>
+
               <SideNavGroup title="Utilities">
                 <SideNavLink href="/box">Box</SideNavLink>
                 <SideNavLink href="/breakpoints">Breakpoints</SideNavLink>
diff --git a/packages/docs/pages/header.tsx b/packages/docs/pages/header.tsx
new file mode 100644
index 000000000..4da15509d
--- /dev/null
+++ b/packages/docs/pages/header.tsx
@@ -0,0 +1,140 @@
+import { H1, Panel, Text } from '@bigcommerce/big-design';
+import { AddIcon, ArrowDropDownIcon } from '@bigcommerce/big-design-icons';
+import { Header } from '@bigcommerce/big-design-patterns';
+import React, { Fragment } from 'react';
+
+import {
+  Code,
+  CodePreview,
+  CodeSnippet,
+  ContentRoutingTabs,
+  GuidelinesTable,
+  List,
+} from '../components';
+import { ButtonPropTable, DropdownPropTable } from '../PropTables';
+import {
+  ActionButtonPropsTable,
+  ActionDropdownPropsTable,
+  BackLinkPropsTable,
+  HeaderPropTable,
+} from '../PropTables/HeaderPropTable';
+
+const HeaderPage = () => {
+  return (
+    <>
+      <H1>Header</H1>
+
+      <Panel header="Overview" headerId="overview">
+        <Text>
+          <Code primary>Header</Code> is a layout component that provides a standard structure for
+          page titles, descriptions, icons, badges, and actions.
+        </Text>
+
+        <Text bold>When to use:</Text>
+        <List>
+          <List.Item>To display a title and related actions at the top of a page.</List.Item>
+          <List.Item>To provide context and quick actions for users.</List.Item>
+        </List>
+      </Panel>
+
+      <Panel header="Implementation" headerId="implementation">
+        <Fragment key="basic">
+          <Text>
+            To use <Code primary>Header</Code> import the component from the package:
+          </Text>
+          <CodeSnippet>{`import { Header } from '@bigcommerce/big-design-patterns';`}</CodeSnippet>
+        </Fragment>
+        <CodePreview>
+          {/* jsx-to-string:start */}
+          <Header
+            actions={[
+              {
+                text: 'Main',
+                variant: 'primary',
+                iconLeft: <AddIcon />,
+              },
+              {
+                items: [
+                  { content: 'Option 1', onItemClick: (item) => item },
+                  { content: 'Option 2', onItemClick: (item) => item },
+                ],
+                toggle: {
+                  text: 'Secondary',
+                  variant: 'secondary',
+                  iconRight: <ArrowDropDownIcon />,
+                },
+              },
+              {
+                text: 'Tertiary',
+                variant: 'subtle',
+              },
+            ]}
+            backLink={{
+              text: 'Back to Dashboard',
+              href: '/dashboard',
+            }}
+            badge={{ label: 'New', variant: 'success' }}
+            description="This is a description of the page content."
+            title="Page Title"
+          />
+          {/* jsx-to-string:end */}
+        </CodePreview>
+      </Panel>
+
+      <Panel header="Props" headerId="props">
+        <ContentRoutingTabs
+          id="props"
+          routes={[
+            {
+              id: 'header',
+              title: 'Header',
+              render: () => <HeaderPropTable />,
+            },
+            {
+              id: 'action-button',
+              title: 'ActionButton',
+              render: () => (
+                <ActionButtonPropsTable
+                  id="action-button-prop-table"
+                  inheritedProps={<ButtonPropTable collapsible />}
+                />
+              ),
+            },
+            {
+              id: 'action-dropdown',
+              title: 'ActionDropdown',
+              render: () => (
+                <ActionDropdownPropsTable
+                  id="action-dropdown-prop-table"
+                  inheritedProps={<DropdownPropTable collapsible />}
+                />
+              ),
+            },
+            {
+              id: 'back-link',
+              title: 'BackLink',
+              render: () => <BackLinkPropsTable id="backlink-prop-table" />,
+            },
+          ]}
+        />
+      </Panel>
+
+      <Panel header="Do's and Don'ts" headerId="guidelines">
+        <GuidelinesTable
+          discouraged={[
+            'Don’t overload the header with too many actions or content.',
+            'Don’t use more than one primary action button.',
+            'Avoid unrelated or non-contextual content in the header.',
+          ]}
+          recommended={[
+            'Use the header to provide a clear overview of the page’s purpose.',
+            'Limit the number of actions to three.',
+            'Utilize the back link option for easy navigation.',
+          ]}
+        />
+      </Panel>
+    </>
+  );
+};
+
+export default HeaderPage;