@primer/components 29.1.0 → 29.1.1-rc.cea79543

package/docs/content/Pagination.md

@@ -0,0 +1,187 @@
+---
+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.primary" 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.primary" 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.primary" borderRadius={2} p={2}>
+        <Box>
+          Current page: {page} / {totalPages}
+        </Box>
+        <Pagination pageCount={totalPages} currentPage={page} onPageChange={onPageChange} showPages={false} />
+      </Box>
+    )
+  }}
+</State>
+```
+
+## System props
+
+<Note variant="warning">
+
+System props are deprecated in all components except [Box](/Box). Please use the [`sx` prop](/overriding-styles) instead.
+
+</Note>
+
+Pagination 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                                                            |
+| :------------------- | :------- | :--------: | :--------------------------------------------------------------------- |
+| 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. |
+
+## Theming
+
+The following snippet shows the properties in the theme that control the styling of the pagination component:
+
+```javascript
+{
+  // ... 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="bg.success" borderColor="border.success">
+  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="bg.success" borderColor="border.success" 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,137 @@
+---
+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 />)
+```
+
+## System props
+
+<Note variant="warning">
+
+System props are deprecated in all components except [Box](/Box). Please use the [`sx` prop](/overriding-styles) instead.
+
+</Note>
+
+ProgressBar components get `COMMON` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+## 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.                  |
+
+#### 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. |

package/docs/content/Portal.mdx

@@ -0,0 +1,73 @@
+---
+title: Portal
+---
+
+Portals allow you to create a separation between the logical React component hierarchy and the physical DOM. See the [React documentation on portals](https://reactjs.org/docs/portals.html) for an in-depth explanation.
+
+This Portal component will render all children into the portal root DOM node instead of as children of this Portal's parent DOM element. This is useful for breaking out of the current stacking context. For example, popup menus and tooltips may need to render on top of (read: covering up) other UI. The best way to guarantee this is to add these elements to top-level DOM, such as directly on `document.body`. These elements can then be moved to the correct location using absolute positioning.
+
+## Customizing the portal root
+
+By default, Primer will create a portal root for you as a child of the closest `<BaseStyles>` element, or `document.body` if none is found. That root will be positioned absolutely in the top-left corner of its parent element. If you would like to specify your own portal root, there are two options:
+
+1. Before rendering a `<Portal>` for the first time, ensure that an element exists with id `__primerPortalRoot__`. If that exists, it will be used as the default portal root.
+2. Call the `registerPortalRoot` function, passing in the element you would like to use as your default portal root.
+
+Keep in mind that any inherited styles applied to portaled elements are based on its physical DOM parent. Practically this means that styles added by a `<BaseStyles>` element will not apply to the portaled content unless the portal root is a descendent of a `<BaseStyles>` element.
+
+Also, as `<ThemeProvider>` affects the _React_ context, which applies to the logical React component hierarchy, the portal root is not required to be a child of a `<ThemeProvider>` for its children to receive that context.
+
+## Multiple portal roots
+
+There may be situations where you want to have multiple portal roots. Advanced scenarios may necessitate multiple stacking contexts for overlays. You can set up multiple roots using the `registerPortalRoot` function. Calling this function with an element and a string `name` will register the root, which can then be used by creating a `<Portal>` with a `name` prop matching the one you registered.
+
+## Default example
+
+```jsx
+<Portal>
+  Regardless of where this appears in the React component tree, this text will be rendered in the DOM within the portal
+  root at document.body.
+</Portal>
+```
+
+## Example: custom portal root
+
+```html
+<!-- Wherever in your DOM tree you would like to have the default portal root -->
+<div id="__primerPortalRoot__"></div>
+```
+
+or
+
+```js
+import { registerPortalRoot } from "@primer/components"
+registerPortalRoot(document.querySelector(".my-portal-root")!)
+```
+
+## Example: multiple portal roots
+
+```jsx
+import { Portal, registerPortalRoot } from "@primer/components"
+registerPortalRoot(document.querySelector(".scrolling-canvas-root")!, "scrolling-canvas")
+// ...
+<Portal containerName="scrolling-canvas">
+    <div>This div will be rendered into the element registered above.</div>
+    <Portal>
+        <div>
+            This div will be rendered into the default
+            portal root created at document.body
+        </div>
+    </Portal>
+</Portal>
+```
+
+## System props
+
+Since Portals do not render UI on their own, they do not accept any system props.
+
+## Component props
+
+| Name          | Type       | Default | Description                                                                                                                                    |
+| :------------ | :--------- | :-----: | :--------------------------------------------------------------------------------------------------------------------------------------------- |
+| onMount       | () => void |         | Called when this portal is added to the DOM                                                                                                    |
+| containerName | string     |         | Renders the portal children into the container registered with the given name. If omitted, children are rendered into the default portal root. |

package/docs/content/Position.md

@@ -0,0 +1,97 @@
+---
+title: Position Components
+status: Deprecated
+---
+
+The Position component is a wrapper component that gives the containing component css positioning abilities.
+
+## Deprecation
+
+Use [Box](/Box) instead.
+
+**Before**
+
+```jsx
+<Position position="absolute">...</Position>
+<Absolute>...</Absolute>
+<Relative>...</Relative>
+<Fixed>...</Fixed>
+<Sticky>...</Sticky>
+```
+
+**After**
+
+```jsx
+<Box position="absolute">...</Box>
+<Box position="absolute">...</Box>
+<Box position="relative">...</Box>
+<Box position="fixed">...</Box>
+<Box position="sticky">...</Box>
+```
+
+## Default examples
+
+```jsx live
+<Box p={2} mb={200}>
+  <Heading mb={2}>Relative + Absolute</Heading>
+  <Relative size={128} mx={128} my={6}>
+    <Box borderWidth="1px" borderStyle="solid" borderColor="border.primary" borderRadius={2} size="100%">
+      <Absolute left="100%" top={0} color="text.inverse" bg="bg.successInverse" p={1}>
+        rt
+      </Absolute>
+      <Absolute right="100%" top={0} color="text.inverse" bg="bg.successInverse" p={1}>
+        lt
+      </Absolute>
+      <Absolute left="100%" bottom={0} color="text.inverse" bg="bg.successInverse" p={1}>
+        rb
+      </Absolute>
+      <Absolute right="100%" bottom={0} color="text.inverse" bg="bg.successInverse" p={1}>
+        lb
+      </Absolute>
+      <Absolute left={0} top="100%" color="text.inverse" bg="bg.successInverse" p={1}>
+        bl
+      </Absolute>
+      <Absolute right={0} top="100%" color="text.inverse" bg="bg.successInverse" p={1}>
+        br
+      </Absolute>
+      <Absolute left={0} bottom="100%" color="text.inverse" bg="bg.successInverse" p={1}>
+        tl
+      </Absolute>
+      <Absolute right={0} bottom="100%" color="text.inverse" bg="bg.successInverse" p={1}>
+        tr
+      </Absolute>
+    </Box>
+  </Relative>
+
+  <Heading my={2}>Sticky</Heading>
+
+  <Box
+    borderWidth="1px"
+    borderStyle="solid"
+    borderColor="border.primary"
+    borderRadius={2}
+    border={1}
+    borderColor="border.success"
+    height={500}
+  >
+    <Sticky top={0} bg="bg.success" p={6}>
+      I'm sticky!
+    </Sticky>
+  </Box>
+
+  <Heading my={2}>Fixed</Heading>
+  <p>(see the bottom right of the screen)</p>
+
+  <Fixed bottom={0} right={0} color="text.inverse" bg="bg.dangerInverse" p={2}>
+    I'm fixed to the bottom right.
+  </Fixed>
+</Box>
+```
+
+## System props
+
+Position components get `POSITION`, `LAYOUT`, `FLEX`, and `COMMON` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+## Component props
+
+Position does not get any additional props other than the system props mentioned above.

package/docs/content/ProgressBar.mdx

@@ -0,0 +1,29 @@
+---
+title: ProgressBar
+componentId: progress_bar
+source: https://github.com/primer/react/blob/main/src/ProgressBar.tsx
+---
+
+## Default example
+
+```jsx live
+<ProgressBar progress={80} />
+```
+
+If you'd like to use ProgressBar inline, pass the `inline` boolean prop & **be sure to set a width**.
+
+```jsx live
+<>
+  <Text mr={3}>5 of 10</Text>
+  <ProgressBar progress={50} inline sx={{width: '100px'}} />
+</>
+```
+
+## Component props
+
+| Name     | Type    |       Default       | Description                                                                                                                      |
+| :------- | :------ | :-----------------: | :------------------------------------------------------------------------------------------------------------------------------- |
+| progress | Number  |                     | Used to set the size of the green bar                                                                                            |
+| barSize  | String  |      'default'      | Controls the height of the progress bar. Can be 'small', 'large', or 'default'. If omitted, height is set to the default height. |
+| inline   | Boolean |        false        | Styles the progress bar inline                                                                                                   |
+| bg       | String  | 'bg.successInverse' | Set the progress bar color, defaults to bg-green                                                                                 |