@primer/components 31.2.0 → 31.2.1-rc.0e01900c

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,78 @@
+---
+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")
+
+// ...
+
+export default () => (
+    <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,100 @@
+---
+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.default" borderRadius={2} size="100%">
+      <Absolute left="100%" top={0} color="fg.onEmphasis" bg="success.emphasis" p={1}>
+        rt
+      </Absolute>
+      <Absolute right="100%" top={0} color="fg.onEmphasis" bg="success.emphasis" p={1}>
+        lt
+      </Absolute>
+      <Absolute left="100%" bottom={0} color="fg.onEmphasis" bg="success.emphasis" p={1}>
+        rb
+      </Absolute>
+      <Absolute right="100%" bottom={0} color="fg.onEmphasis" bg="success.emphasis" p={1}>
+        lb
+      </Absolute>
+      <Absolute left={0} top="100%" color="fg.onEmphasis" bg="success.emphasis" p={1}>
+        bl
+      </Absolute>
+      <Absolute right={0} top="100%" color="fg.onEmphasis" bg="success.emphasis" p={1}>
+        br
+      </Absolute>
+      <Absolute left={0} bottom="100%" color="fg.onEmphasis" bg="success.emphasis" p={1}>
+        tl
+      </Absolute>
+      <Absolute right={0} bottom="100%" color="fg.onEmphasis" bg="success.emphasis" p={1}>
+        tr
+      </Absolute>
+    </Box>
+  </Relative>
+
+  <Heading my={2}>Sticky</Heading>
+
+  <Box
+    borderWidth="1px"
+    borderStyle="solid"
+    borderColor="success.emphasis"
+    borderRadius={2}
+    border={1}
+    height={500}
+  >
+    <Sticky top={0} bg="success.subtle" 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="fg.onEmphasis" bg="danger.emphasis" 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                                                                                 |