@primer/components 29.1.0 → 29.1.1-rc.cea79543

package/docs/content/Spinner.mdx

@@ -0,0 +1,32 @@
+---
+title: Spinner
+status: Alpha
+description: Use spinners to let users know that content is being loaded.
+componentId: spinner
+source: https://github.com/primer/components/blob/main/src/Spinner.tsx
+---
+
+import {Props} from '../src/props'
+import {Spinner} from '@primer/components'
+
+```jsx live
+<Spinner />
+```
+
+## Props
+
+<Props of={Spinner} />
+
+## Examples
+
+### Small
+
+```jsx live
+<Spinner size="small" />
+```
+
+### Large
+
+```jsx live
+<Spinner size="large" />
+```

package/docs/content/StateLabel.md

@@ -0,0 +1,33 @@
+---
+title: StateLabel
+---
+
+Use StateLabel components to show the status of an issue or pull request.
+
+## Default example
+
+```jsx live
+<StateLabel status="issueOpened">Open</StateLabel>
+<StateLabel status="issueClosed">Closed</StateLabel>
+<StateLabel status="pullOpened">Open</StateLabel>
+<StateLabel status="pullClosed">Closed</StateLabel>
+<StateLabel status="pullMerged">Merged</StateLabel>
+<StateLabel status="draft">Draft</StateLabel>
+```
+
+## System props
+
+<Note variant="warning">
+
+System props are deprecated in all components except [Box](/Box). Please use the [`sx` prop](/overriding-styles) instead.
+
+</Note>
+
+StateLabel components get `COMMON` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+## Component props
+
+| Name    | Type   | Default  | Description                                                                                       |
+| :------ | :----- | :------: | :------------------------------------------------------------------------------------------------ |
+| variant | String | 'normal' | a value of `small` or `normal` results in a smaller or larger version of the StateLabel.          |
+| status  | String |          | Can be one of `issueOpened`, `issueClosed`, `pullOpened`, `pullClosed`, `pullMerged`, or `draft`. |

package/docs/content/StyledOcticon.md

@@ -0,0 +1,34 @@
+---
+title: StyledOcticon
+tags: icon
+---
+
+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="icon.success" mr={2} />
+<StyledOcticon icon={XIcon} size={32} color="icon.danger" />
+```
+
+## System props
+
+<Note variant="warning">
+
+System props are deprecated in all components except [Box](/Box). Please use the [`sx` prop](/overriding-styles) instead.
+
+</Note>
+
+StyledOcticon components get `COMMON` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+## 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                                                                       |

package/docs/content/SubNav.md

@@ -0,0 +1,102 @@
+---
+title: SubNav
+---
+
+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>
+```
+
+## System props
+
+<Note variant="warning">
+
+System props are deprecated in all components except [Box](/Box). Please use the [`sx` prop](/overriding-styles) instead.
+
+</Note>
+
+SubNav and SubNav.Link components get `COMMON` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+## Component props
+
+### SubNav
+
+| Prop name  | Type    | 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.                         |
+
+### SubNav.Link
+
+| Prop name | Type    | 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 |

package/docs/content/TabNav.md

@@ -0,0 +1,50 @@
+---
+title: TabNav
+---
+
+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>
+```
+
+## System props
+
+<Note variant="warning">
+
+System props are deprecated in all components except [Box](/Box). Please use the [`sx` prop](/overriding-styles) instead.
+
+</Note>
+
+TabNav and TabNav.Link components get `COMMON` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+## Component props
+
+### TabNav
+
+| Prop name  | Type   | Description                                                    |
+| :--------- | :----- | :------------------------------------------------------------- |
+| aria-label | String | Used to set the `aria-label` on the top level `<nav>` element. |
+
+### TabNav.Link
+
+| Prop name | Type    | 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 |

package/docs/content/Text.md

@@ -0,0 +1,29 @@
+---
+title: Text
+---
+
+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="text.danger">danger color</Text>
+<Text as='p' color="text.inverse" bg="bg.canvasInverse" p={2}>inverse colors</Text>
+```
+
+## System props
+
+<Note variant="warning">
+
+System props are deprecated in all components except [Box](/Box). Please use the [`sx` prop](/overriding-styles) instead.
+
+</Note>
+
+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,32 @@
+---
+title: TextInput
+---
+
+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/Timeline.md

@@ -0,0 +1,138 @@
+---
+title: Timeline
+---
+
+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: 'text.primary', mr: 1}} muted>
+        Monalisa
+      </Link>
+      created one <Link href="#" sx={{fontWeight: 'bold', color: 'text.primary', mr: 1}} muted>
+        hot potato
+      </Link>
+      <Link href="#" color="timeline.text" 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: 'prState.closed.bg'}}>
+      <StyledOcticon icon={FlameIcon} sx={{color: 'prState.closed.text'}} />
+    </Timeline.Badge>
+    <Timeline.Body>Background used when closed events occur</Timeline.Body>
+  </Timeline.Item>
+  <Timeline.Item>
+    <Timeline.Badge sx={{bg: 'prState.closed.bg'}}>
+      <StyledOcticon icon={FlameIcon} color="prState.open.text" />
+    </Timeline.Badge>
+    <Timeline.Body>Background when opened or passed events occur</Timeline.Body>
+  </Timeline.Item>
+  <Timeline.Item>
+    <Timeline.Badge sx={{bg: 'prState.closed.bg'}}>
+      <StyledOcticon icon={FlameIcon} sx={{color: 'prState.merged.text'}} />
+    </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: 'prState.closed.bg'}}>
+      <StyledOcticon icon={FlameIcon} color="prState.closed.text" />
+    </Timeline.Badge>
+    <Timeline.Body>Background used when closed events occur</Timeline.Body>
+  </Timeline.Item>
+  <Timeline.Break />
+  <Timeline.Item>
+    <Timeline.Badge sx={{bg: 'prState.open.bg'}}>
+      <StyledOcticon icon={FlameIcon} sx={{color: 'prState.open.text'}} />
+    </Timeline.Badge>
+    <Timeline.Body>Background when opened or passed events occur</Timeline.Body>
+  </Timeline.Item>
+</Timeline>
+```
+
+## System props
+
+<Note variant="warning">
+
+System props are deprecated in all components except [Box](/Box). Please use the [`sx` prop](/overriding-styles) instead.
+
+</Note>
+
+Timeline and Timeline.Item components get `COMMON` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+## Component props
+
+### Timeline
+
+| Prop name   | Type    | Description                                                                       |
+| :---------- | :------ | :-------------------------------------------------------------------------------- |
+| clipSidebar | Boolean | Hides the sidebar above the first Timeline.Item and below the last Timeline.Item. |
+
+### Timeline.Item
+
+| Prop name | Type    | Description                                                           |
+| :-------- | :------ | :-------------------------------------------------------------------- |
+| condensed | Boolean | Reduces vertical padding and removes background from an item's badge. |

package/docs/content/Tooltip.md

@@ -0,0 +1,41 @@
+---
+title: Tooltip
+---
+
+The Tooltip component adds a tooltip to add context to elements on the page.
+
+**_⚠️ Usage warning! ⚠️_**
+
+Tooltips as a UI pattern should be our last resort for conveying information because it is hidden by default and often with zero or little visual indicator of its existence.
+
+Before adding a tooltip, please consider: Is this information essential and necessary? Can the UI be made clearer? Can the information be shown on the page by default?
+
+**Attention:** we use aria-label for tooltip contents, because it is crucial that they are accessible to screen reader users. However, aria-label replaces the text content of an element in screen readers, so only use Tooltip on elements with no existing text content, or consider using `title` for supplemental information.
+
+## Default example
+
+```jsx live
+<Box borderWidth="1px" borderStyle="solid" borderColor="border.primary" borderRadius={2} p={3}>
+  <Tooltip aria-label="Hello, Tooltip!">Text with a tooltip</Tooltip>
+</Box>
+```
+
+## System props
+
+<Note variant="warning">
+
+System props are deprecated in all components except [Box](/Box). Please use the [`sx` prop](/overriding-styles) instead.
+
+</Note>
+
+Tooltip components get `COMMON` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+## Component props
+
+| Name       | Type    | Default | Description                                              |
+| :--------- | :------ | :-----: | :------------------------------------------------------- | --------------------------------------------------------- |
+| align      | String  |         | Can be either `left` or `right`.                         |
+| direction  | String  |         | Can be one of `n`, `ne`, `e`, `se`, `s`, `sw`, `w`, `nw` | Sets where the tooltip renders in relation to the target. |
+| noDelay    | Boolean |         | When set to `true`, tooltip appears without any delay    |
+| aria-label | String  |         | Text used in `aria-label` (for accessibility).           |
+| wrap       | Boolean |         | Use `true` to allow text within tooltip to wrap.         |

package/docs/content/Truncate.md

@@ -0,0 +1,65 @@
+---
+title: Truncate
+---
+
+The Truncate component will shorten text with an ellipsis. Always add a `title` attribute to the truncated element so the full text remains accessible.
+
+## Default example
+
+Truncate will prevent text that overflows from wrapping. The default max-width is 125px.
+
+```jsx live
+<Truncate title="Some text with a branch-name-that-is-really-long">
+  Some text with a branch-name-that-is-really-long
+</Truncate>
+```
+
+## Custom max-width example
+
+You can override the maximum width of the truncated text with the `maxWidth` prop.
+
+```jsx live
+<Truncate maxWidth={250} title="Some text with a branch-name-that-is-really-long">
+  Some text with a branch-name-that-is-really-long
+</Truncate>
+```
+
+## Inline example
+
+You can use the `inline` boolean prop for inline (or inline-block) elements with a fixed maximum width (default: 125px).
+
+```jsx live
+  Some text with a{' '}
+  <Truncate as="strong" inline title="branch-name-that-is-really-long">
+    branch-name-that-is-really-long
+  </Truncate>
+```
+
+## Expandable example
+
+You can use the `expandable` boolean prop to display the truncated text on hover.
+
+```jsx live
+<Truncate expandable title="Some text with a branch-name-that-is-really-long">
+  Some text with a branch-name-that-is-really-long
+</Truncate>
+```
+
+## System props
+
+<Note variant="warning">
+
+System props are deprecated in all components except [Box](/Box). Please use the [`sx` prop](/overriding-styles) instead.
+
+</Note>
+
+Truncate 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  |  `div`  | Sets the HTML tag for the component                          |
+| maxWidth   | Number  |   125   | Sets the max-width of the text                               |
+| inline     | Boolean |  false  | displays text as inline block and vertical aligns to the top |
+| expandable | Boolean |  false  | allows the truncated text to be displayed on hover           |

package/docs/content/UnderlineNav.md

@@ -0,0 +1,53 @@
+---
+title: UnderlineNav
+---
+
+Use the UnderlineNav component to style navigation with a minimal underlined selected state, typically used for navigation placed at the top of the page.
+
+To use UnderlineNav 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 `UnderlineNav` with an `aria-label` to provide context about the type of navigation contained in `UnderlineNav`.
+
+## Default example
+
+```jsx live
+<UnderlineNav aria-label="Main">
+  <UnderlineNav.Link href="#home" selected>
+    Home
+  </UnderlineNav.Link>
+  <UnderlineNav.Link href="#documentation">Documentation</UnderlineNav.Link>
+  <UnderlineNav.Link href="#support">Support</UnderlineNav.Link>
+</UnderlineNav>
+```
+
+## System props
+
+<Note variant="warning">
+
+System props are deprecated in all components except [Box](/Box). Please use the [`sx` prop](/overriding-styles) instead.
+
+</Note>
+
+UnderlineNav and UnderlineNav.Link components get `COMMON` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+## Component props
+
+### UnderlineNav
+
+| Prop name  | Type    | 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.                         |
+
+### UnderlineNav.Link
+
+| Prop name | Type    | 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 |