-
Notifications
You must be signed in to change notification settings - Fork 64
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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>
- Loading branch information
1 parent
fd0ab6e
commit dbd50a6
Showing
7 changed files
with
274 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| --- | ||
| '@bigcommerce/docs': patch | ||
| --- | ||
|
|
||
| Added Header component documentation |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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} | ||
| /> | ||
| ); |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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; |