@primer/components 32.1.0 → 33.0.0-rc.b495ba4a

package/docs/content/StyledOcticon.md

@@ -0,0 +1,27 @@
+---
+title: StyledOcticon
+status: Alpha
+---
+
+StyledOcticon renders an [Octicon](https://octicons.github.com) with common system props, including `color`, margin, and padding.
+
+## Default example
+
+```jsx live
+<>
+  <StyledOcticon icon={CheckIcon} size={32} color="success.fg" mr={2} />
+  <StyledOcticon icon={XIcon} size={32} color="danger.fg" />
+</>
+```
+
+## Component props
+
+StyledOcticon passes all of its props except the common system props down to the [Octicon component](https://github.com/primer/octicons/tree/master/lib/octicons_react#usage), including:
+
+| Name          | Type              |    Default    | Description                                                                                                  |
+| :------------ | :---------------- | :-----------: | :----------------------------------------------------------------------------------------------------------- |
+| ariaLabel     | String            |               | Specifies the `aria-label` attribute, which is read verbatim by screen readers                               |
+| icon          | Component         |               | [Octicon component](https://github.com/primer/octicons/tree/master/lib/octicons_react) used in the component |
+| size          | Number            |      16       | Sets the uniform `width` and `height` of the SVG element                                                     |
+| verticalAlign | String            | `text-bottom` | Sets the `vertical-align` CSS property                                                                       |
+| sx            | SystemStyleObject |      {}       | Style to be applied to the component                                                                         |

package/docs/content/SubNav.md

@@ -0,0 +1,101 @@
+---
+title: SubNav
+status: Alpha
+---
+
+Use the SubNav component for navigation on a dashboard-type interface with another set of navigation components above it. This helps distinguish navigation hierarchy.
+
+To use SubNav with [react-router](https://github.com/ReactTraining/react-router) or
+[react-router-dom](https://www.npmjs.com/package/react-router-dom), pass
+`as={NavLink}` and omit the `selected` prop.
+This ensures that the NavLink gets `activeClassName='selected'`
+
+**Attention:** Make sure to properly label your `SubNav` with an `aria-label` to provide context about the type of navigation contained in `SubNav`.
+
+## Default example
+
+```jsx live
+<SubNav aria-label="Main">
+  <SubNav.Links>
+    <SubNav.Link href="#home" selected>
+      Home
+    </SubNav.Link>
+    <SubNav.Link href="#documentation">Documentation</SubNav.Link>
+    <SubNav.Link href="#support">Support</SubNav.Link>
+  </SubNav.Links>
+</SubNav>
+```
+
+## SubNav with search example
+
+```jsx live
+<SubNav aria-label="Main">
+  <SubNav.Links>
+    <SubNav.Link href="#home" selected>
+      Home
+    </SubNav.Link>
+    <SubNav.Link href="#documentation">Documentation</SubNav.Link>
+    <SubNav.Link href="#support">Support</SubNav.Link>
+  </SubNav.Links>
+
+  <TextInput type="search" icon={SearchIcon} sx={{width: 320}} />
+</SubNav>
+```
+
+## SubNav with filtered search example
+
+```jsx live
+<SubNav aria-label="Main">
+  <FilteredSearch>
+    <Dropdown>
+      <Dropdown.Button>Filter</Dropdown.Button>
+      <Dropdown.Menu direction="sw">
+        <Dropdown.Item>
+          <a href="#">Item 1</a>
+        </Dropdown.Item>
+        <Dropdown.Item>
+          <a href="#">Item 2</a>
+        </Dropdown.Item>
+        <Dropdown.Item>
+          <a href="#">Item 3</a>
+        </Dropdown.Item>
+      </Dropdown.Menu>
+    </Dropdown>
+    <TextInput type="search" icon={SearchIcon} width={320} />
+  </FilteredSearch>
+  <SubNav.Links>
+    <SubNav.Link href="#home" selected>
+      Home
+    </SubNav.Link>
+    <SubNav.Link href="#documentation">Documentation</SubNav.Link>
+    <SubNav.Link href="#support">Support</SubNav.Link>
+  </SubNav.Links>
+</SubNav>
+```
+
+## Component props
+
+### SubNav
+
+| Name       | Type              | Default | Description                                                                            |
+| :--------- | :---------------- | :-----: | :------------------------------------------------------------------------------------- |
+| actions    | Node              |         | Place another element, such as a button, to the opposite side of the navigation items. |
+| align      | String            |         | Use `right` to have navigation items aligned right.                                    |
+| full       | Boolean           |         | Used to make navigation fill the width of the container.                               |
+| aria-label | String            |         | Used to set the `aria-label` on the top level `<nav>` element.                         |
+| sx         | SystemStyleObject |   {}    | Style to be applied to the component                                                   |
+
+### SubNav.Link
+
+| Name     | Type              | Default | Description                                      |
+| :------- | :---------------- | :-----: | :----------------------------------------------- |
+| as       | String            |         | sets the HTML tag for the component              |
+| href     | String            |         | URL to be used for the Link                      |
+| selected | Boolean           |         | Used to style the link as selected or unselected |
+| sx       | SystemStyleObject |   {}    | Style to be applied to the component             |
+
+### SubNav.Links
+
+| Name | Type              | Default | Description                          |
+| :--- | :---------------- | :-----: | :----------------------------------- |
+| sx   | SystemStyleObject |   {}    | Style to be applied to the component |

package/docs/content/TabNav.md

@@ -0,0 +1,43 @@
+---
+title: TabNav
+status: Alpha
+---
+
+Use the TabNav component to style navigation with a tab-based selected state, typically used for navigation placed at the top of the page.
+
+To use TabNav with [react-router](https://github.com/ReactTraining/react-router) or
+[react-router-dom](https://www.npmjs.com/package/react-router-dom), pass
+`as={NavLink}` and omit the `selected` prop.
+This ensures that the NavLink gets `activeClassName='selected'`
+
+**Attention:** Make sure to properly label your `TabNav` with an `aria-label` to provide context about the type of navigation contained in `TabNav`.
+
+## Default example
+
+```jsx live
+<TabNav aria-label="Main">
+  <TabNav.Link href="#home" selected>
+    Home
+  </TabNav.Link>
+  <TabNav.Link href="#documentation">Documentation</TabNav.Link>
+  <TabNav.Link href="#support">Support</TabNav.Link>
+</TabNav>
+```
+
+## Component props
+
+### TabNav
+
+| Name       | Type              | Default | Description                                                    |
+| :--------- | :---------------- | :-----: | :------------------------------------------------------------- |
+| aria-label | String            |         | Used to set the `aria-label` on the top level `<nav>` element. |
+| sx         | SystemStyleObject |   {}    | Style to be applied to the component                           |
+
+### TabNav.Link
+
+| Name     | Type              | Default | Description                                      |
+| :------- | :---------------- | :-----: | :----------------------------------------------- |
+| as       | String            |         | sets the HTML tag for the component              |
+| href     | String            |         | URL to be used for the Link                      |
+| selected | Boolean           |         | Used to style the link as selected or unselected |
+| sx       | SystemStyleObject |   {}    | Style to be applied to the component             |

package/docs/content/Text.md

@@ -0,0 +1,32 @@
+---
+title: Text
+status: Alpha
+---
+
+The Text component is a wrapper component that will apply typography styles to the text inside.
+
+## Default example
+
+```jsx live
+<>
+  <Text as="p" fontWeight="bold">
+    bold
+  </Text>
+  <Text as="p" color="danger.fg">
+    danger color
+  </Text>
+  <Text as="p" color="fg.onEmphasis" bg="neutral.emphasis" p={2}>
+    inverse colors
+  </Text>
+</>
+```
+
+## System props
+
+Text components get `TYPOGRAPHY` and `COMMON` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+## Component props
+
+| Name | Type   | Default | Description                         |
+| :--- | :----- | :-----: | :---------------------------------- |
+| as   | String | `span`  | Sets the HTML tag for the component |

package/docs/content/TextInput.md

@@ -0,0 +1,42 @@
+---
+title: TextInput
+status: Alpha
+---
+
+TextInput is a form component to add default styling to the native text input.
+
+**Note:** Don't forget to set `aria-label` to make the TextInput accessible to screen reader users.
+
+## Default example
+
+```jsx live
+<>
+  <TextInput aria-label="Zipcode" name="zipcode" placeholder="Zipcode" autoComplete="postal-code" />
+
+  <TextInput sx={{ml: 4}} aria-label="City" name="city" placeholder="City" contrast />
+
+  <TextInput
+    sx={{ml: 4}}
+    icon={SearchIcon}
+    aria-label="Zipcode"
+    name="zipcode"
+    placeholder="Find user"
+    autoComplete="postal-code"
+  />
+</>
+```
+
+## Component props
+
+Native `<input>` attributes are forwarded to the underlying React `input` component and are not listed below.
+
+| Name       | Type                                                                      | Default | Description                                                                           |
+| :--------- | :------------------------------------------------------------------------ | :-----: | :------------------------------------------------------------------------------------ |
+| aria-label | String                                                                    |         | Required. Allows input to be accessible.                                              |
+| block      | Boolean                                                                   |         | Adds `display: block` to element                                                      |
+| contrast   | Boolean                                                                   |         | Changes background color to a higher contrast color                                   |
+| variant    | String                                                                    |         | Can be either `small` or `large`. Creates a smaller or larger input than the default. |
+| width      | String or Number                                                          |         | Set the width of the input                                                            |
+| maxWidth   | String or Number or [Array](https://styled-system.com/guides/array-props) |         | Set the maximum width of the input                                                    |
+| minWidth   | String or Number or [Array](https://styled-system.com/guides/array-props) |         | Set the minimum width of the input                                                    |
+| icon       | Node (pass Octicon react component)                                       |         | Icon to be used inside of input. Positioned on the left edge.                         |

package/docs/content/TextInputWithTokens.mdx

@@ -0,0 +1,211 @@
+---
+title: TextInputWithTokens
+status: Alpha
+source: https://github.com/primer/react/tree/main/src/TextInputWithTokens.tsx
+---
+
+import {Props} from '../src/props'
+import {TextInputWithTokens} from '@primer/components'
+
+A `TextInputWithTokens` component is used to show multiple values in one field.
+
+It supports all of the features of a [TextInput](/TextInput) component, but it can render a list of [Tokens](/Token) next to the area a user types in.
+
+## Basic Example
+
+```javascript live noinline
+const BasicExample = () => {
+  const [tokens, setTokens] = React.useState([
+    {text: 'zero', id: 0},
+    {text: 'one', id: 1},
+    {text: 'two', id: 2}
+  ])
+  const onTokenRemove = tokenId => {
+    setTokens(tokens.filter(token => token.id !== tokenId))
+  }
+
+  return (
+    <>
+      <Box as="label" display="block" htmlFor="inputWithTokens-basic">
+        Basic example tokens
+      </Box>
+      <TextInputWithTokens tokens={tokens} onTokenRemove={onTokenRemove} id="inputWithTokens-basic" />
+    </>
+  )
+}
+
+render(BasicExample)
+```
+
+## Component Props
+
+| Name                   | Type                                  |   Default    | Description                                                                                                               |
+| :--------------------- | :------------------------------------ | :----------: | :------------------------------------------------------------------------------------------------------------------------ |
+| tokens                 | `TokenProps[]`                        | `undefined`  | Required. The array of tokens to render                                                                                   |
+| onTokenRemove          | `(tokenId: string \| number) => void` | `undefined`  | Required. The function that gets called when a token is removed                                                           |
+| tokenComponent         | `React.ComponentType<any>`            |   `Token`    | Optional. The component used to render each token                                                                         |
+| maxHeight              | `React.CSSProperties['maxHeight']`    | `undefined`  | Optional. The maximum height of the component. If the content in the input exceeds this height, it will scroll vertically |
+| preventTokenWrapping   | `boolean`                             |   `false`    | Optional. Whether tokens should render inline horizontally. By default, tokens wrap to new lines.                         |
+| size                   | `TokenSizeKeys`                       | `extralarge` | Optional. The size of the tokens                                                                                          |
+| hideTokenRemoveButtons | `boolean`                             |   `false`    | Optional. Whether the remove buttons should be rendered in the tokens                                                     |
+| visibleTokenCount      | `number`                              | `undefined`  | Optional. The number of tokens to display before truncating                                                               |
+
+## Adding and removing tokens
+
+The array passed to the `tokens` prop needs to be manually updated to add and remove tokens.
+
+The function passed to the `onRemoveToken` prop is called when:
+
+- Clicking the remove button in the token
+- Pressing the `Backspace` key when the input is empty
+- Selecting a token using the arrow keys or by clicking on a token and then pressing the `Backspace` key
+
+There is no function that gets called to "add" a token, so the user needs to be provided with a UI to select tokens.
+
+## Custom token rendering
+
+By default, the `Token` component is used to render the tokens in the input. If this component does not make sense for the kinds of tokens you're rendering, you can pass a component to the `tokenComponent` prop
+
+Example: a `TextInputWithTokens` that renders tokens as `IssueLabelToken`:
+
+```javascript live noinline
+const UsingIssueLabelTokens = () => {
+  const [tokens, setTokens] = React.useState([
+    {text: 'enhancement', id: 1, fillColor: '#a2eeef'},
+    {text: 'bug', id: 2, fillColor: '#d73a4a'},
+    {text: 'good first issue', id: 3, fillColor: '#0cf478'}
+  ])
+  const onTokenRemove = tokenId => {
+    setTokens(tokens.filter(token => token.id !== tokenId))
+  }
+
+  return (
+    <>
+      <Box as="label" display="block" htmlFor="inputWithTokens-issueLabels">
+        Issue labels
+      </Box>
+      <TextInputWithTokens
+        tokenComponent={IssueLabelToken}
+        tokens={tokens}
+        onTokenRemove={onTokenRemove}
+        id="inputWithTokens-issueLabels"
+      />
+    </>
+  )
+}
+
+render(<UsingIssueLabelTokens />)
+```
+
+## Dealing with long lists of tokens
+
+By default, all tokens will be visible when the component is rendered.
+
+If the component is being used in an area where it's height needs to be constrained, there are options to limit the height of the input.
+
+### Hide and show tokens
+
+```javascript live noinline
+const VisibleTokenCountExample = () => {
+  const [tokens, setTokens] = React.useState([
+    {text: 'zero', id: 0},
+    {text: 'one', id: 1},
+    {text: 'two', id: 2},
+    {text: 'three', id: 3}
+  ])
+  const onTokenRemove = tokenId => {
+    setTokens(tokens.filter(token => token.id !== tokenId))
+  }
+
+  return (
+    <Box maxWidth="500px">
+      <Box as="label" display="block" htmlFor="inputWithTokens-basic">
+        Tokens truncated after 2
+      </Box>
+      <TextInputWithTokens
+        visibleTokenCount={2}
+        block
+        tokens={tokens}
+        onTokenRemove={onTokenRemove}
+        id="inputWithTokens-basic"
+      />
+    </Box>
+  )
+}
+
+render(VisibleTokenCountExample)
+```
+
+### Render tokens on a single line
+
+```javascript live noinline
+const PreventTokenWrappingExample = () => {
+  const [tokens, setTokens] = React.useState([
+    {text: 'zero', id: 0},
+    {text: 'one', id: 1},
+    {text: 'two', id: 2},
+    {text: 'three', id: 3},
+    {text: 'four', id: 4},
+    {text: 'five', id: 5},
+    {text: 'six', id: 6},
+    {text: 'seven', id: 7}
+  ])
+  const onTokenRemove = tokenId => {
+    setTokens(tokens.filter(token => token.id !== tokenId))
+  }
+
+  return (
+    <Box maxWidth="500px">
+      <Box as="label" display="block" htmlFor="inputWithTokens-basic">
+        Tokens on one line
+      </Box>
+      <TextInputWithTokens
+        preventTokenWrapping
+        block
+        tokens={tokens}
+        onTokenRemove={onTokenRemove}
+        id="inputWithTokens-basic"
+      />
+    </Box>
+  )
+}
+
+render(PreventTokenWrappingExample)
+```
+
+### Set a maximum height for the input
+
+```javascript live noinline
+const MaxHeightExample = () => {
+  const [tokens, setTokens] = React.useState([
+    {text: 'zero', id: 0},
+    {text: 'one', id: 1},
+    {text: 'two', id: 2},
+    {text: 'three', id: 3},
+    {text: 'four', id: 4},
+    {text: 'five', id: 5},
+    {text: 'six', id: 6},
+    {text: 'seven', id: 7}
+  ])
+  const onTokenRemove = tokenId => {
+    setTokens(tokens.filter(token => token.id !== tokenId))
+  }
+
+  return (
+    <Box maxWidth="500px">
+      <Box as="label" display="block" htmlFor="inputWithTokens-basic">
+        Tokens restricted to a max height
+      </Box>
+      <TextInputWithTokens
+        maxHeight="50px"
+        block
+        tokens={tokens}
+        onTokenRemove={onTokenRemove}
+        id="inputWithTokens-basic"
+      />
+    </Box>
+  )
+}
+
+render(MaxHeightExample)
+```

package/docs/content/Timeline.md

@@ -0,0 +1,149 @@
+---
+title: Timeline
+status: Alpha
+---
+
+The Timeline.Item component is used to display items on a vertical timeline, connected by Timeline.Badge elements.
+
+## Example with in-line links
+
+```jsx live
+<Timeline>
+  <Timeline.Item>
+    <Timeline.Badge>
+      <StyledOcticon icon={FlameIcon} />
+    </Timeline.Badge>
+    <Timeline.Body>
+      <Link href="#" sx={{fontWeight: 'bold', color: 'fg.default', mr: 1}} muted>
+        Monalisa
+      </Link>
+      created one <Link href="#" sx={{fontWeight: 'bold', color: 'fg.default', mr: 1}} muted>
+        hot potato
+      </Link>
+      <Link href="#" color="fg.muted" muted>
+        Just now
+      </Link>
+    </Timeline.Body>
+  </Timeline.Item>
+</Timeline>
+```
+
+## Default Color example
+
+The default Timeline.Badge color is dark text on a light grey background.
+
+```jsx live
+<Timeline>
+  <Timeline.Item>
+    <Timeline.Badge>
+      <StyledOcticon icon={FlameIcon} />
+    </Timeline.Badge>
+    <Timeline.Body>Default badge color</Timeline.Body>
+  </Timeline.Item>
+</Timeline>
+```
+
+## Adding color to a Badge
+
+To have color variants, use the `bg` prop on the `Timeline.Badge`. If an icon is being used, set the `color` prop
+of the child `StyledOcticon` if necessary.
+
+```jsx live
+<Timeline>
+  <Timeline.Item>
+    <Timeline.Badge sx={{bg: 'danger.emphasis'}}>
+      <StyledOcticon icon={FlameIcon} sx={{color: 'fg.onEmphasis'}} />
+    </Timeline.Badge>
+    <Timeline.Body>Background used when closed events occur</Timeline.Body>
+  </Timeline.Item>
+  <Timeline.Item>
+    <Timeline.Badge sx={{bg: 'danger.emphasis'}}>
+      <StyledOcticon icon={FlameIcon} color="fg.onEmphasis" />
+    </Timeline.Badge>
+    <Timeline.Body>Background when opened or passed events occur</Timeline.Body>
+  </Timeline.Item>
+  <Timeline.Item>
+    <Timeline.Badge sx={{bg: 'danger.emphasis'}}>
+      <StyledOcticon icon={FlameIcon} sx={{color: 'fg.onEmphasis'}} />
+    </Timeline.Badge>
+    <Timeline.Body>Background used when pull requests are merged</Timeline.Body>
+  </Timeline.Item>
+</Timeline>
+```
+
+## Condensed items
+
+Timeline has a condensed prop that will reduce the vertical padding and remove the background from the badge item. These are most commonly used in commits. To condense a single item, remove the top or bottom padding with the `pt={0}` or `pb={0}` prop.
+
+```jsx live
+<Timeline>
+  <Timeline.Item condensed>
+    <Timeline.Badge>
+      <StyledOcticon icon={GitCommitIcon} />
+    </Timeline.Badge>
+    <Timeline.Body>This is the message of a condensed TimelineItem</Timeline.Body>
+  </Timeline.Item>
+  <Timeline.Item condensed>
+    <Timeline.Badge>
+      <StyledOcticon icon={GitCommitIcon} />
+    </Timeline.Badge>
+    <Timeline.Body>This is the message of a condensed TimelineItem</Timeline.Body>
+  </Timeline.Item>
+</Timeline>
+```
+
+## Timeline Break
+
+To create a visual break in the timeline, use Timeline.Break. This adds a horizontal bar across the timeline to show that something has disrupted it. Usually this happens when a close or merged event occurs.
+
+```jsx live
+<Timeline>
+  <Timeline.Item>
+    <Timeline.Badge sx={{bg: 'danger.emphasis'}}>
+      <StyledOcticon icon={FlameIcon} color="fg.onEmphasis" />
+    </Timeline.Badge>
+    <Timeline.Body>Background used when closed events occur</Timeline.Body>
+  </Timeline.Item>
+  <Timeline.Break />
+  <Timeline.Item>
+    <Timeline.Badge sx={{bg: 'success.emphasis'}}>
+      <StyledOcticon icon={FlameIcon} sx={{color: 'fg.onEmphasis'}} />
+    </Timeline.Badge>
+    <Timeline.Body>Background when opened or passed events occur</Timeline.Body>
+  </Timeline.Item>
+</Timeline>
+```
+
+## Component props
+
+### Timeline
+
+| Name        | Type              | Default | Description                                                                       |
+| :---------- | :---------------- | :-----: | :-------------------------------------------------------------------------------- |
+| clipSidebar | Boolean           |         | Hides the sidebar above the first Timeline.Item and below the last Timeline.Item. |
+| sx          | SystemStyleObject |   {}    | Style to be applied to the component                                              |
+
+### Timeline.Item
+
+| Name      | Type              | Default | Description                                                           |
+| :-------- | :---------------- | :-----: | :-------------------------------------------------------------------- |
+| condensed | Boolean           |         | Reduces vertical padding and removes background from an item's badge. |
+| sx        | SystemStyleObject |   {}    | Style to be applied to the component                                  |
+
+### Timeline.Badge
+
+| Name | Type              | Default | Description                          |
+| :--- | :---------------- | :-----: | :----------------------------------- |
+| sx   | SystemStyleObject |   {}    | Style to be applied to the component |
+
+### Timeline.Body
+
+| Name | Type              | Default | Description                          |
+| :--- | :---------------- | :-----: | :----------------------------------- |
+| sx   | SystemStyleObject |   {}    | Style to be applied to the component |
+
+### Timeline.Break
+
+| Name | Type              | Default | Description                          |
+| :--- | :---------------- | :-----: | :----------------------------------- |
+| sx   | SystemStyleObject |   {}    | Style to be applied to the component |