@primer/components 32.0.0 → 32.0.2-rc.859381a1

package/docs/content/Heading.md

@@ -0,0 +1,22 @@
+---
+title: Heading
+---
+
+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 fontSize={1} mb={2}>H2 heading with fontSize={1}</Heading>
+```
+
+## System props
+
+Heading components get `TYPOGRAPHY` and `COMMON` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+## Component props
+
+| Prop name | Type    | Description                                      |
+| :-------- | :------ | :----------------------------------------------- |
+| as        | String or React element  | sets the HTML tag for the component              |

package/docs/content/Label.md

@@ -0,0 +1,49 @@
+---
+title: Label
+---
+
+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                                                 |
+| bg         | String            | 'label.primary.border' | Part of the `COMMON` system props, used to change the background of the label. |
+| sx         | SystemStyleObject |           {}           | Style to be applied to the component                                           |

package/docs/content/LabelGroup.md

@@ -0,0 +1,21 @@
+---
+title: LabelGroup
+---
+
+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,28 @@
+---
+title: Link
+---
+
+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,85 @@
+---
+title: Overlay
+---
+
+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,18 @@
+---
+title: Pagehead
+---
+
+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,178 @@
+---
+title: Pagination
+---
+
+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,81 @@
+---
+title: PointerBox
+---
+
+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. |

package/docs/content/Popover.md

@@ -0,0 +1,129 @@
+---
+title: Popover
+---
+
+Popovers are used to bring attention to specific user interface elements, typically to suggest an action or to guide users through a new experience.
+
+Two components make up a popover; the `Popover` component controls the absolute positioning of the popover, and `Popover.Content` renders the inner content of the popover as well as the caret.
+
+By default, the popover renders with absolute positioning, meaning it should usually be wrapped in an element with a relative position in order to be positioned properly. To render the popover with relative positioning, use the `relative` property.
+
+It can be useful to give the `Popover.Content` element a margin to help align the popover.
+
+## Default Example
+
+```jxs live
+<Box position="relative">
+  <Text textAlign="center" display="block">
+    <ButtonPrimary>Hello!</ButtonPrimary>
+  </Text>
+
+  <Popover relative open={true} caret="top">
+    <Popover.Content sx={{mt: 2}}>
+      <Heading sx={{fontSize: 2}}>Popover heading</Heading>
+      <Text as="p">Message about this particular piece of UI.</Text>
+      <Button>Got it!</Button>
+    </Popover.Content>
+  </Popover>
+</Box>
+```
+
+## Caret position
+
+`Popover` supports various caret positions, which you can specify via the `caret` property. This demo shows all the valid values for the prop. The default is `top`. Note that the `top-left`, `bottom-left`, `top-right`, and `bottom-right` values modify the horizontal alignment of the popover.
+
+```javascript live noinline
+function PopoverDemo(props) {
+  const [pos, setPos] = React.useState('top')
+  const [open, setOpen] = React.useState(true)
+
+  return (
+    <Box>
+      <Heading as="h3" sx={{fontSize: 3}}>
+        Caret Position
+      </Heading>
+      <CaretSelector current={pos} onChange={setPos} />
+      <Heading as="h3" sx={{fontSize: 3}}>
+        Popover Visibility
+      </Heading>
+      <Box my={2}>
+        <label>
+          <input type="checkbox" value={open} checked={open} onChange={() => setOpen(open => !open)} /> Open
+        </label>
+      </Box>
+
+      <Box position="relative" pt={4}>
+        <Popover relative open={open} caret={pos}>
+          <Popover.Content>
+            <Heading sx={{fontSize: 2}}>
+              <code>{pos}</code> caret
+            </Heading>
+            <Text as="p">Message about this particular piece of UI.</Text>
+            <Button onClick={() => setOpen(false)}>Got it!</Button>
+          </Popover.Content>
+        </Popover>
+      </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(<PopoverDemo />)
+```
+
+## Component props
+
+### Popover
+
+| Name     | Type              | Default | Description                                                                    |
+| :------- | :---------------- | :-----: | :----------------------------------------------------------------------------- |
+| as       | String            |  'div'  | Sets the HTML tag for the component.                                           |
+| caret    | String            |  'top'  | Controls the position of the caret. See below for the list of caret positions. |
+| open     | Boolean           |  false  | Controls the visibility of the popover.                                        |
+| relative | Boolean           |  false  | Set to true to render the popover using relative positioning.                  |
+| sx       | SystemStyleObject |   {}    | Style to be applied to the component                                           |
+
+#### Caret Positions
+
+The `caret` prop can be one of the following values: `top`, `bottom`, `left`, `right`, `bottom-left`, `bottom-right`, `top-left`, `top-right`, `left-bottom`, `left-top`, `right-bottom`, or `right-top`.
+
+### Popover.Content
+
+| Name | Type              | Default | Description                          |
+| :--- | :---------------- | :-----: | :----------------------------------- |
+| as   | String            |  'div'  | Sets the HTML tag for the component. |
+| sx   | SystemStyleObject |   {}    | Style to be applied to the component |