@primer/components 32.1.0 → 33.0.0-rc.b3e4ccee

package/docs/content/Grid.md

@@ -0,0 +1,59 @@
+---
+title: Grid
+status: Deprecated
+---
+
+Grid is a component that exposes grid system props. See the [CSS Tricks Complete Guide to Grid](https://css-tricks.com/snippets/css/complete-guide-grid/) to learn more about Grid Layout.
+
+## Deprecation
+
+Use [Box](/Box) instead.
+
+**Before**
+
+```jsx
+<Grid gridTemplateColumns="repeat(2, auto)" gridGap={3}>
+  <Box p={3} color="fg.onEmphasis" bg="accent.emphasis">
+    1
+  </Box>
+  <Box p={3} color="fg.onEmphasis" bg="attention.emphasis">
+    2
+  </Box>
+</Grid>
+```
+
+**After**
+
+```jsx
+<Box display="grid" gridTemplateColumns="repeat(2, auto)" gridGap={3}>
+  <Box p={3} color="fg.onEmphasis" bg="accent.emphasis">
+    1
+  </Box>
+  <Box p={3} color="fg.onEmphasis" bg="attention.emphasis">
+    2
+  </Box>
+</Box>
+```
+
+## Default example
+
+```jsx live
+<Grid gridTemplateColumns="repeat(2, auto)" gridGap={3}>
+  <Box p={3} color="fg.onEmphasis" bg="accent.emphasis">
+    1
+  </Box>
+  <Box p={3} color="fg.onEmphasis" bg="attention.emphasis">
+    2
+  </Box>
+</Grid>
+```
+
+## System props
+
+Grid components get `GRID`, `COMMON`, and `LAYOUT` system props.
+
+Read our [System Props](/system-props) doc page for a full list of available props.
+
+## Component props
+
+`Grid` does not get any additional props other than the system props mentioned above.

package/docs/content/Header.md

@@ -0,0 +1,78 @@
+---
+title: Header
+status: Alpha
+---
+
+Use the `Header` component to create a header that has all of its items aligned vertically with consistent horizontal spacing.
+
+## Default example
+
+All items directly under the Header component should be a `Header.Item` component. Inside these components can be anything (text, forms, images...), and the `Header.Item` component will make sure these elements vertically align with each other.
+
+`Header.Item` elements have a built-in margin that will need to be overridden with the `mr={0}` props for the last element in the container. We relied on the prop here instead of `:last-child` because the last child isn't always the item visible. On responsive pages, there's a mobile menu that gets presented to the user at smaller breakpoints.
+
+```jsx live
+<Header>
+  <Header.Item>
+    <Header.Link href="#" fontSize={2}>
+      <StyledOcticon icon={MarkGithubIcon} size={32} mr={2} />
+      <span>GitHub</span>
+    </Header.Link>
+  </Header.Item>
+  <Header.Item full>Menu</Header.Item>
+  <Header.Item mr={0}>
+    <Avatar src="https://github.com/octocat.png" size={20} square alt="@octocat" />
+  </Header.Item>
+</Header>
+```
+
+## Header with full-size item example
+
+```jsx live
+<Header>
+  <Header.Item>Item 1</Header.Item>
+  <Header.Item full border={1} borderStyle="solid">
+    Item 2
+  </Header.Item>
+  <Header.Item mr={0}>Item 3</Header.Item>
+</Header>
+```
+
+## Header with links example
+
+```jsx live
+<Header>
+  <Header.Item>
+    <Header.Link href="#">About</Header.Link>
+  </Header.Item>
+  <Header.Item>
+    <Header.Link href="#">Releases</Header.Link>
+  </Header.Item>
+  <Header.Item>
+    <Header.Link href="#">Team</Header.Link>
+  </Header.Item>
+</Header>
+```
+
+## Component props
+
+### Header
+
+| Name | Type              | Default | Description                          |
+| :--- | :---------------- | :-----: | :----------------------------------- |
+| sx   | SystemStyleObject |   {}    | Style to be applied to the component |
+
+### Header.Item
+
+| Name | Type              | Default | Description                                |
+| :--- | :---------------- | :-----: | :----------------------------------------- |
+| full | Boolean           |         | stretches item to fill the available space |
+| sx   | SystemStyleObject |   {}    | Style to be applied to the component       |
+
+### Header.Link
+
+| Name | Type              | Default | Description                          |
+| :--- | :---------------- | :-----: | :----------------------------------- |
+| as   | String            |         | sets the HTML tag for the component  |
+| href | String            |         | URL to be used for the Link          |
+| sx   | SystemStyleObject |   {}    | Style to be applied to the component |

package/docs/content/Heading.md

@@ -0,0 +1,21 @@
+---
+title: Heading
+status: Alpha
+---
+
+The Heading component will render an html `h2` tag without any default styling. Other heading level elements `h1-h6` are available through use of the `as` prop (see [System Props](/system-props) for additional explanation). Please reference the [w3 recommendations for headings](https://www.w3.org/WAI/tutorials/page-structure/headings/) to ensure your headings provide an accessible experience for screen reader users.
+
+**Attention:** Make sure to include a valid heading element to render a Heading component other than `h2` (`<Heading as="h1">H1 Element</Heading>`).
+
+## Default example
+
+```jsx live
+<Heading sx={{fontSize: 1, mb: 2}}>H2 heading with fontSize={1}</Heading>
+```
+
+## Component props
+
+| Name | Type                    | Default | Description                          |
+| :--- | :---------------------- | :-----: | :----------------------------------- |
+| as   | String or React element |         | sets the HTML tag for the component  |
+| sx   | SystemStyleObject       |   {}    | Style to be applied to the component |

package/docs/content/Label.md

@@ -0,0 +1,49 @@
+---
+title: Label
+status: Alpha
+---
+
+The Label component is used to add contextual metadata to a design. Visually it styles text, adds padding, and rounded corners.
+
+## Default example
+
+```jsx live
+<>
+  <Label variant="small" outline sx={{borderColor: 'danger.emphasis', mr: 2, color: 'danger.fg'}}>
+    small
+  </Label>
+  <Label variant="medium" sx={{mr: 2}}>
+    medium (default)
+  </Label>
+  <Label variant="large" sx={{mr: 2}}>
+    large
+  </Label>
+  <Label variant="xl">xl label</Label>
+
+  <Box mt={4} />
+  <Label variant="medium" sx={{bg: '#A575FF', m: 1}}>
+    good first issue
+  </Label>
+  <Label variant="medium" sx={{bg: '#FF75C8', m: 1}}>
+    🚂 deploy: train
+  </Label>
+  <Label variant="medium" sx={{bg: '#1C90FA', m: 1}}>
+    css
+  </Label>
+  <Label variant="medium" sx={{bg: '#FFF06C', color: '#24292E', m: 1}}>
+    documentation
+  </Label>
+  <Label variant="medium" sx={{bg: '#656BFE', m: 1}}>
+    primer
+  </Label>
+</>
+```
+
+## Component props
+
+| Name       | Type              | Default  | Description                                                  |
+| :--------- | :---------------- | :------: | :----------------------------------------------------------- |
+| outline    | Boolean           |          | Creates an outline style label                               |
+| variant    | String            | 'medium' | Can be one of `small`, `medium` (default), `large` or `xl` . |
+| dropshadow | Boolean           |          | Adds a dropshadow to the label                               |
+| sx         | SystemStyleObject |    {}    | Style to be applied to the component                         |

package/docs/content/LabelGroup.md

@@ -0,0 +1,22 @@
+---
+title: LabelGroup
+status: Alpha
+---
+
+The LabelGroup component is used to add commonly used margins and wrapping for groups of Labels.
+
+## Default example
+
+```jsx live
+<LabelGroup>
+  <Label>Default label</Label>
+  <Label sx={{color: 'fg.onEmphasis', bg: 'danger.emphasis'}}>Label with background indicating a closed PR state</Label>
+  <Label outline>Default outline label</Label>
+</LabelGroup>
+```
+
+## Component props
+
+| Name | Type              | Default | Description                          |
+| :--- | :---------------- | :-----: | :----------------------------------- |
+| sx   | SystemStyleObject |   {}    | Style to be applied to the component |

package/docs/content/Link.md

@@ -0,0 +1,29 @@
+---
+title: Link
+status: Alpha
+---
+
+The Link component styles anchor tags with default hyperlink color cues and hover text decoration. `Link` is used for destinations, or moving from one page to another.
+
+In special cases where you'd like a `<button>` styled like a `Link`, use `<Link as='button'>`. Make sure to provide a click handler with `onClick`.
+
+**Important:** When using the `as` prop, be sure to always render an accessible element type, like `a`, `button`, `input`, or `summary`.
+
+## Default example
+
+```jsx live
+<Link sx={{mb: 1}} href="https://github.com">
+  Link
+</Link>
+```
+
+## Component props
+
+| Name       | Type              | Default | Description                                                                     |
+| :--------- | :---------------- | :-----: | :------------------------------------------------------------------------------ |
+| href       | String            |         | URL to be used for the Link                                                     |
+| muted      | Boolean           |  false  | Uses a less prominent shade for Link color, and the default link shade on hover |
+| underline  | Boolean           |  false  | Adds underline to the Link                                                      |
+| as         | String            |   'a'   | Can be 'a', 'button', 'input', or 'summary'                                     |
+| hoverColor | String            |         | Color used when hovering over link                                              |
+| sx         | SystemStyleObject |   {}    | Style to be applied to the component                                            |

package/docs/content/Overlay.mdx

@@ -0,0 +1,86 @@
+---
+title: Overlay
+status: Alpha
+---
+
+An `Overlay` is a flexible floating surface, used to display transient content such as menus, selection options, dialogs, and more. Overlays use shadows to express elevation. The `Overlay` component handles all behaviors needed by overlay UIs as well as the common styles that all overlays should have. `Overlay` is the base component for many of our overlay-type components.
+
+Behaviors include:
+
+- Rendering the overlay in a React Portal so that it always renders on top of other content on the page
+- Trapping focus
+- Calling a user provided function when the user presses `Escape`
+- Calling a user provided function when the user clicks outside of the container
+- Focusing either user provided element, or the first focusable element in the container when it is opened
+- Returning focus to an element when container is closed
+
+## Accessibility considerations
+
+- The `Overlay` must either have:
+  - A value set for the `aria-labelledby` attribute that refers to a visible title.
+  - An `aria-label` attribute
+- If the `Overlay` should also have a longer description, use `aria-describedby`
+- The `Overlay` component has a `role="dialog"` set on it, if you are using `Overlay` for alerts, you can pass in `role="alertdialog"` instead. Please read the [W3C guidelines](https://www.w3.org/TR/wai-aria-1.1/#alertdialog) to determine which role is best for your use case
+- The `Overlay` component has `aria-modal` set to `true` by default and should not be overridden as all `Overlay`s behave as modals.
+
+See the W3C accessibility recommendations for modals [here](https://www.w3.org/TR/wai-aria-practices-1.1/#dialog_roles_states_props).
+
+## Positioning
+
+`Overlay` renders its `children` within a div positioned absolutely within a portal within the default portal root. The overlay will not update its positioning if the portal root's positioning changes (e.g., if the portal root is statically positioned after some DOM element that dynamically resizes). You may consider [customizing the portal or specifying a different portal root](/Portal#customizing-the-portal-root) to achieve different positioning behavior.
+
+## Default example
+
+```javascript live noinline
+const Demo = () => {
+  // you must manage your own open state
+  const [isOpen, setIsOpen] = React.useState(false)
+  const noButtonRef = React.useRef(null)
+  const anchorRef = React.useRef(null)
+  return (
+    <>
+      <Button ref={anchorRef} onClick={() => setIsOpen(!isOpen)}>
+        open overlay
+      </Button>
+      {/* be sure to conditionally render the Overlay. This helps with performance and is required. */}
+      {isOpen && (
+        <Overlay
+          initialFocusRef={noButtonRef}
+          returnFocusRef={anchorRef}
+          ignoreClickRefs={[anchorRef]}
+          onEscape={() => setIsOpen(!isOpen)}
+          onClickOutside={() => setIsOpen(false)}
+          aria-labelledby="title"
+        >
+          <Box display="flex" flexDirection="column" p={2}>
+            <Text id="title">Are you sure you would like to delete this item?</Text>
+            <Button>yes</Button>
+            <Button ref={noButtonRef}>no</Button>
+          </Box>
+        </Overlay>
+      )}
+    </>
+  )
+}
+
+render(<Demo />)
+```
+
+## Component props
+
+| Name                | Type                                                           |   Default   | Description                                                                                                                                                                                                                                                                                                                   |
+| :------------------ | :------------------------------------------------------------- | :---------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ignoreClickRefs     | `React.RefObject<HTMLElement> []`                              | `undefined` | Optional. An array of ref objects to ignore clicks on in the `onOutsideClick` behavior. This is often used to ignore clicking on the element that toggles the open/closed state for the `Overlay` to prevent the `Overlay` from being toggled twice.                                                                          |
+| initialFocusRef     | `React.RefObject<HTMLElement>`                                 | `undefined` | Optional. Ref for the element to focus when the `Overlay` is opened. If nothing is provided, the first focusable element in the `Overlay` body is focused.                                                                                                                                                                    |
+| anchorRef           | `React.RefObject<HTMLElement>`                                 | `undefined` | Required. Element the `Overlay` should be anchored to.                                                                                                                                                                                                                                                                        |
+| returnFocusRef      | `React.RefObject<HTMLElement>`                                 | `undefined` | Required. Ref for the element to focus when the `Overlay` is closed.                                                                                                                                                                                                                                                          |
+| onClickOutside      | `function`                                                     | `undefined` | Required. Function to call when clicking outside of the `Overlay`. Typically this function sets the `Overlay` visibility state to `false`.                                                                                                                                                                                    |
+| onEscape            | `function`                                                     | `undefined` | Required. Function to call when user presses `Escape`. Typically this function sets the `Overlay` visibility state to `false`.                                                                                                                                                                                                |
+| width               | `'small' │ 'medium' │ 'large' │ 'xlarge' │ 'xxlarge' │ 'auto'` |   `auto`    | Sets the width of the `Overlay`, pick from our set list of widths, or pass `auto` to automatically set the width based on the content of the `Overlay`. `small` corresponds to `256px`, `medium` corresponds to `320px`, `large` corresponds to `480px`, `xlarge` corresponds to `640px`, `xxlarge` corresponds to `960px`.   |
+| height              | `'xsmall', 'small', 'medium', 'large', 'xlarge', 'auto'`       |   `auto`    | Sets the height of the `Overlay`, pick from our set list of heights, or pass `auto` to automatically set the height based on the content of the `Overlay`. `xsmall` corresponds to `192px`, `small` corresponds to `256px`, `medium` corresponds to `320px`, `large` corresponds to `432px`, `xlarge` corresponds to `600px`. |
+| visibility          | `'visible', 'hidden'`                                          |  `visible`  | Sets the visibility of the `Overlay`.                                                                                                                                                                                                                                                                                         |
+| anchorSide          | `AnchorSide`                                                   |  undefined  | Optional. If provided, the Overlay will slide into position from the side of the anchor with a brief animation                                                                                                                                                                                                                |
+| top                 | `number`                                                       |      0      | Vertical position of the overlay, relative to its closest positioned ancestor (often its `Portal`).                                                                                                                                                                                                                           |
+| left                | `number`                                                       |      0      | Horizontal position of the overlay, relative to its closest positioned ancestor (often its `Portal`).                                                                                                                                                                                                                         |
+| portalContainerName | `string`                                                       | `undefined` | Optional. If defined, Overlays will be rendered in the named portal. See also `Portal`.                                                                                                                                                                                                                                       |
+| sx                  | SystemStyleObject                                              |     {}      | Style to be applied to the component                                                                                                                                                                                                                                                                                          |

package/docs/content/Pagehead.md

@@ -0,0 +1,19 @@
+---
+title: Pagehead
+status: Alpha
+---
+
+Give a page a clear, separated title and optional top nav by using Pagehead.
+
+## Default example
+
+```jsx live
+<Pagehead>Pagehead</Pagehead>
+```
+
+## Component props
+
+| Name | Type              | Default | Description                          |
+| :--- | :---------------- | :-----: | :----------------------------------- |
+| as   | String            |  `div`  | Sets the HTML tag for the component  |
+| sx   | SystemStyleObject |   {}    | Style to be applied to the component |

package/docs/content/Pagination.md

@@ -0,0 +1,179 @@
+---
+title: Pagination
+status: Alpha
+---
+
+import State from '../components/State'
+
+Use the pagination component to create a connected set of links that lead to related pages (for example, previous, next, or page numbers).
+
+## Basic example
+
+The pagination component only requires two properties to render: `pageCount`, which is the total number of pages, and `currentPage`, which is the currently selected page number (which should be managed by the consuming application).
+
+```jsx live
+<Pagination pageCount={15} currentPage={2} onPageChange={e => e.preventDefault()} />
+```
+
+However, to handle state changes when the user clicks a page, you also need to pass `onPageChange`, which is a function that takes a click event and page number as an argument:
+
+```javascript
+type PageChangeCallback = (evt: React.MouseEvent, page: number) => void
+```
+
+By default, clicking a link in the pagination component will cause the browser to navigate to the URL specified by the page. To cancel navigation and handle state management on your own, you should call `preventDefault` on the event, as in this example:
+
+```jsx live
+<State default={1}>
+  {([page, setPage]) => {
+    const totalPages = 15
+    const onPageChange = (evt, page) => {
+      evt.preventDefault()
+      setPage(page)
+    }
+
+    return (
+      <Box borderWidth="1px" borderStyle="solid" borderColor="border.default" borderRadius={2} p={2}>
+        <Box>
+          Current page: {page} / {totalPages}
+        </Box>
+        <Pagination pageCount={totalPages} currentPage={page} onPageChange={onPageChange} />
+      </Box>
+    )
+  }}
+</State>
+```
+
+## Customizing link URLs
+
+To customize the URL generated for each link, you can pass a function to the `hrefBuilder` property. The function should take a page number as an argument and return a URL to use for the link.
+
+```javascript
+type HrefBuilder = (page: number) => string
+```
+
+```jsx live
+<State default={'(nothing clicked yet)'}>
+  {([lastUrl, setLastUrl]) => {
+    const onPageChange = (evt, page) => {
+      evt.preventDefault()
+      setLastUrl(evt.target.href)
+    }
+    const hrefBuilder = page => {
+      return `https://example.com/pages/${page}`
+    }
+
+    return (
+      <Box borderWidth="1px" borderStyle="solid" borderColor="border.default" borderRadius={2} p={2}>
+        <Box>The last URL clicked was: {lastUrl}</Box>
+        <Pagination pageCount={15} currentPage={2} onPageChange={onPageChange} hrefBuilder={hrefBuilder} />
+      </Box>
+    )
+  }}
+</State>
+```
+
+## Customizing which pages are shown
+
+Two props control how many links are displayed in the pagination container at any given time. `marginPageCount` controls how many pages are guaranteed to be displayed on the left and right of the component; `surroundingPageCount` controls how many pages will be displayed to the left and right of the current page.
+
+```jsx live
+<Pagination
+  pageCount={20}
+  currentPage={10}
+  marginPageCount={1}
+  surroundingPageCount={2}
+  onPageChange={e => e.preventDefault()}
+/>
+```
+
+The algorithm tries to minimize the amount the component shrinks and grows as the user changes pages; for this reason, if any of the pages in the margin (controlled via `marginPageCount`) intersect with pages in the center (controlled by `surroundingPageCount`), the center section will be shifted away from the margin. Consider the following examples, where pages one through six are shown when any of the first four pages are selected. Only when the fifth page is selected and there is a gap between the margin pages and the center pages does a break element appear.
+
+```jsx live
+<Box>
+  {[1, 2, 3, 4, 5].map(page => (
+    <Pagination
+      pageCount={20}
+      currentPage={page}
+      marginPageCount={1}
+      surroundingPageCount={2}
+      onPageChange={e => e.preventDefault()}
+    />
+  ))}
+</Box>
+```
+
+### Previous/next pagination
+
+To hide all the page numbers and create a simple pagination container with just the Previous and Next buttons, set `showPages` to `false`.
+
+```jsx live
+<State default={1}>
+  {([page, setPage]) => {
+    const totalPages = 10
+    const onPageChange = (evt, page) => {
+      evt.preventDefault()
+      setPage(page)
+    }
+
+    return (
+      <Box borderWidth="1px" borderStyle="solid" borderColor="border.default" borderRadius={2} p={2}>
+        <Box>
+          Current page: {page} / {totalPages}
+        </Box>
+        <Pagination pageCount={totalPages} currentPage={page} onPageChange={onPageChange} showPages={false} />
+      </Box>
+    )
+  }}
+</State>
+```
+
+## Component props
+
+| Name                 | Type              |  Default   | Description                                                            |
+| :------------------- | :---------------- | :--------: | :--------------------------------------------------------------------- |
+| currentPage          | Number            |            | **Required.** The currently selected page.                             |
+| hrefBuilder          | Function          | `#${page}` | A function to generate links based on page number.                     |
+| marginPageCount      | Number            |     1      | How many pages to always show at the left and right of the component.  |
+| onPageChange         | Function          |   no-op    | Called with event and page number when a page is clicked.              |
+| pageCount            | Number            |            | **Required.** The total number of pages.                               |
+| showPages            | Boolean           |   `true`   | Whether or not to show the individual page links.                      |
+| surroundingPageCount | Number            |     2      | How many pages to display on each side of the currently selected page. |
+| sx                   | SystemStyleObject |     {}     | Style to be applied to the component                                   |
+
+## Theming
+
+The following snippet shows the properties in the theme that control the styling of the pagination component:
+
+```javascript
+export default {
+  // ... rest of theme ...
+  pagination: {
+    borderRadius,
+    spaceBetween,
+    colors: {
+      normal: {
+        fg
+      },
+      disabled: {
+        fg,
+        border
+      },
+      hover: {
+        border
+      },
+      selected: {
+        fg,
+        bg,
+        border
+      },
+      active: {
+        border
+      },
+      nextPrevious: {
+        fg
+      }
+    }
+  }
+}
+```

package/docs/content/PointerBox.md

@@ -0,0 +1,82 @@
+---
+title: PointerBox
+status: Alpha
+---
+
+PointerBox is a [BorderBox](./BorderBox) component with a caret added to it.
+
+## Default example
+
+```jsx live
+<PointerBox m={4} p={2} minHeight={100} bg="success.subtle" borderColor="success.emphasis">
+  PointerBox
+</PointerBox>
+```
+
+```javascript live noinline
+function PointerBoxDemo(props) {
+  const [pos, setPos] = React.useState('top')
+
+  return (
+    <Box>
+      <Heading as="h3" sx={{fontSize: 3}}>
+        Caret Position
+      </Heading>
+      <CaretSelector current={pos} onChange={setPos} />
+      <Box position="relative" pt={4}>
+        <PointerBox m={4} p={2} minHeight={100} bg="success.subtle" borderColor="success.emphasis" caret={pos}>
+          {' '}
+          Content{' '}
+        </PointerBox>
+      </Box>
+    </Box>
+  )
+}
+
+function CaretSelector(props) {
+  const choices = [
+    'top',
+    'bottom',
+    'left',
+    'right',
+    'left-bottom',
+    'left-top',
+    'right-bottom',
+    'right-top',
+    'top-left',
+    'bottom-left',
+    'top-right',
+    'bottom-right'
+  ].map(dir => (
+    <label>
+      <input
+        key={dir}
+        type="radio"
+        name="caret"
+        value={dir}
+        checked={dir === props.current}
+        onChange={() => props.onChange(dir)}
+      />{' '}
+      {dir}
+    </label>
+  ))
+
+  return (
+    <Box display="grid" gridTemplateColumns="repeat(4, auto)" gridGap={3} my={2}>
+      {choices}
+    </Box>
+  )
+}
+
+render(<PointerBoxDemo />)
+```
+
+## System props
+
+PointerBox components get `COMMON`, `LAYOUT`, `BORDER`, and `FLEX` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+## Component props
+
+| Name  | Type   | Default | Description                                                                                                                                                                                                                                                  |
+| :---- | :----- | :-----: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| caret | String | bottom  | Sets the location of the caret. The format is `[edge]-[position on edge]`. For example, `right-top` will position the caret on the top of the right edge of the box. Use `top`, `right`, `bottom`, or `left` to position a caret in the center of that edge. |