|
| 1 | +import { Meta, Story } from '@storybook/addon-docs/blocks'; |
| 2 | +import ToolNameStories, { |
| 3 | + WithName, |
| 4 | + WithSubsection, |
| 5 | + CustomTheme, |
| 6 | + CssOverrides, |
| 7 | +} from './TopBarToolName.stories'; |
| 8 | +import { |
| 9 | + SandboxReact, |
| 10 | + SandboxCss, |
| 11 | + SandboxJs, |
| 12 | +} from '../../../util/storybook/sandbox/Sandbox'; |
| 13 | +import { |
| 14 | + componentCss, |
| 15 | + componentHtml, |
| 16 | + componentJs, |
| 17 | + componentName, |
| 18 | + componentTsx, |
| 19 | +} from './sandbox'; |
| 20 | + |
| 21 | +<Meta of={ToolNameStories} /> |
| 22 | + |
| 23 | +# Tool Name |
| 24 | + |
| 25 | +The Top Bar Tool Name component represents the identity of the application and (optionally) the current type of content on the page, this is intended to be used within the top bar. |
| 26 | + |
| 27 | +## When to use |
| 28 | + |
| 29 | +- In the header/top bar/navbar of the application |
| 30 | + |
| 31 | +## Peer dependencies |
| 32 | + |
| 33 | +- `@emotion/react` |
| 34 | +- `react` |
| 35 | +- `react-dom` |
| 36 | +- `typescript` |
| 37 | + |
| 38 | +See the `peerDependencies` section of `package.json` for compatible versions. |
| 39 | + |
| 40 | +See [custom component build](#custom-component-build) for usage without React/Emotion. |
| 41 | + |
| 42 | +See [Icon component](?path=/docs/stand-editorial-design-system-components-icon--docs#installing-icons) for more on installing icons. |
| 43 | + |
| 44 | +## Example usage |
| 45 | + |
| 46 | +<SandboxReact componentName={componentName} componentTsx={componentTsx} /> |
| 47 | + |
| 48 | +```tsx |
| 49 | +import { TopBarToolName } from '@guardian/stand/TopBarToolName'; |
| 50 | + |
| 51 | +/* types, if required */ |
| 52 | +import type { |
| 53 | + TopBarToolNameProps, |
| 54 | + TopBarToolNameTheme, |
| 55 | +} from '@guardian/stand/TopBarToolName'; |
| 56 | + |
| 57 | +/* Tool name only */ |
| 58 | +<TopBarToolName name="Songwriter" favicon={{ type: 'letter', letter: 'S' }} />; |
| 59 | + |
| 60 | +/* Tool name and content type */ |
| 61 | +<TopBarToolName |
| 62 | + name="Songwriter" |
| 63 | + favicon={{ type: 'letter', letter: 'S' }} |
| 64 | + subsection="Article" |
| 65 | + subsectionIcon="menu" |
| 66 | +/>; |
| 67 | +``` |
| 68 | + |
| 69 | +## Props |
| 70 | + |
| 71 | +| Name | Type | Required | Default | Description | |
| 72 | +| ---------------- | ----------------------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------- | |
| 73 | +| `name` | `string` | Yes | N/A | Name of the tool. | |
| 74 | +| `favicon` | `FaviconProps` | Yes | N/A | Favicon of the tool | |
| 75 | +| `subsection` | `string` | No | N/A | The subsection or content type of the current page. | |
| 76 | +| `subsectionIcon` | `IconProps['symbol']` \| `Exclude<IconProps['children'], string>` | No | N/A | Icon that represents the content type. | |
| 77 | +| `theme` | `TopBarToolNameTheme` (partial) | No | N/A | Override Stand tokens for this instance; merged over the default theme. | |
| 78 | +| `cssOverrides` | `SerializedStyles` | No | N/A | Low-level escape hatch for Emotion overrides when theming is insufficient. | |
| 79 | +| `className` | `string` | No | N/A | Additional class name(s) for the tool name. | |
| 80 | + |
| 81 | +## Stories |
| 82 | + |
| 83 | +### With name only |
| 84 | + |
| 85 | +<Story of={WithName} /> |
| 86 | + |
| 87 | +### With content type |
| 88 | + |
| 89 | +<Story of={WithSubsection} /> |
| 90 | + |
| 91 | +## Customisation |
| 92 | + |
| 93 | +We recommend using the default theme. When needed, use the `theme` or `cssOverrides` props. |
| 94 | + |
| 95 | +### Custom theme |
| 96 | + |
| 97 | +<Story of={CustomTheme} /> |
| 98 | + |
| 99 | +```tsx |
| 100 | +import type { TopBarToolNameTheme } from '@guardian/stand/TopBarToolName'; |
| 101 | +import { TopBarToolName } from '@guardian/stand/TopBarToolName'; |
| 102 | +import { baseSizing, semanticTypography } from '@guardian/stand'; |
| 103 | + |
| 104 | +const customTheme: Partial<TopBarToolNameTheme> = { |
| 105 | + gap: baseSizing['size-1-px'], |
| 106 | + typography: semanticTypography['article-body-bold-italic-md'], |
| 107 | + subsection: { |
| 108 | + typography: semanticTypography['meta-compact-md'], |
| 109 | + }, |
| 110 | +}; |
| 111 | + |
| 112 | +const faviconCustomTheme = { |
| 113 | + color: { |
| 114 | + background: baseColors['cool-purple'][700], |
| 115 | + text: baseColors.orange[300], |
| 116 | + }, |
| 117 | + typography: semanticTypography['body-italic-lg'], |
| 118 | +}; |
| 119 | + |
| 120 | +const Component = () => ( |
| 121 | + <TopBarToolName |
| 122 | + name="Songwriter" |
| 123 | + subsection="Article" |
| 124 | + subsectionIcon="menu" |
| 125 | + theme={customTheme} |
| 126 | + favicon={{ |
| 127 | + letter: 'S, |
| 128 | + theme: faviconCustomTheme |
| 129 | + }} |
| 130 | + /> |
| 131 | +); |
| 132 | +``` |
| 133 | + |
| 134 | +### CSS overrides |
| 135 | + |
| 136 | +<Story of={CssOverrides} /> |
| 137 | + |
| 138 | +```tsx |
| 139 | +import { TopBarToolName } from '@guardian/stand/TopBarToolName'; |
| 140 | +import { baseColors, baseRadius, baseSizing } from '@guardian/stand'; |
| 141 | +import { css } from '@emotion/react'; |
| 142 | + |
| 143 | +const customStyles = css` |
| 144 | + border: ${baseSizing['size-2-rem']} solid ${baseColors.red[500]}; |
| 145 | + background-color: ${baseColors.orange[700]}; |
| 146 | + color: ${baseColors['warm-purple'][300]}; |
| 147 | + border-radius: ${baseRadius['corner-4-px']}; |
| 148 | +`; |
| 149 | + |
| 150 | +const Component = () => ( |
| 151 | + <TopBarToolName |
| 152 | + name="Songwriter" |
| 153 | + subsection="Article" |
| 154 | + cssOverrides={customStyles} |
| 155 | + /> |
| 156 | +); |
| 157 | +``` |
| 158 | + |
| 159 | +## Custom Component Build |
| 160 | + |
| 161 | +If you're not using React/Emotion, or `@guardian/stand` is not compatible with your project, you can create a custom Tool Name component using the styles defined in the `TopBarToolNameTheme` type. |
| 162 | + |
| 163 | +You will however be responsible for any additional functionality on top of the styles, for example icon loading, accessibility, etc. |
| 164 | + |
| 165 | +**`css`** |
| 166 | + |
| 167 | +You can import the TopBarToolName styles as CSS from the package, make sure that your build process supports importing CSS from `node_modules`/`package.json`: |
| 168 | + |
| 169 | +<SandboxCss |
| 170 | + componentName={componentName} |
| 171 | + componentHtml={componentHtml} |
| 172 | + componentCss={componentCss} |
| 173 | + |
| 174 | +/> |
| 175 | + |
| 176 | +**TypeScript/JavaScript** |
| 177 | + |
| 178 | +Use the `componentTopBar` variable and the `componentTopBar` type to define your custom styles in TypeScript/JavaScript: |
| 179 | + |
| 180 | +<SandboxJs componentName={componentName} componentJs={componentJs} /> |
0 commit comments