feat(Popover): Add Popover component

.github/workflows/bundlesize.yml

@@ -0,0 +1,23 @@
+name: 💾 Bundlesize
+on:
+  push:
+    branches-ignore:
+      - master
+
+jobs:
+  bundlesize:
+    name: Check Bundle Size
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          path: 'old'
+          ref: 'master'
+      - uses: actions/checkout@v2
+        with:
+          path: 'new'
+
+      - name: Check Bundle Size Change
+        uses: "BinaryMuse/action-bundlesize@master"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

docs/content/Popover.md

@@ -0,0 +1,110 @@
+---
+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
+<Relative>
+  <Text textAlign="center" display="block">
+    <ButtonPrimary>Hello!</ButtonPrimary>
+  </Text>
+
+  <Popover relative open={true} caret="top">
+    <Popover.Content mt={2}>
+      <Heading fontSize={2}>Popover heading</Heading>
+      <Text as="p">Message about this particular piece of UI.</Text>
+      <Button>Got it!</Button>
+    </Popover.Content>
+  </Popover>
+</Relative>
+```
+
+## 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" fontSize={3}>Caret Position</Heading>
+      <CaretSelector current={pos} onChange={setPos} />
+      <Heading as="h3" fontSize={3}>Popover Visibility</Heading>
+      <Box my={2}>
+        <label>
+          <input type="checkbox" value={open} checked={open}
+            onChange={() => setOpen(open => !open)}/> Open
+        </label>
+      </Box>
+
+      <Relative pt={4}>
+        <Popover relative open={open} caret={pos}>
+          <Popover.Content>
+            <Heading 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>
+      </Relative>
+    </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 (
+    <Grid gridTemplateColumns="repeat(4, auto)" gridGap={3} my={2}>
+      {choices}
+    </Grid>
+  )
+}
+
+render(<PopoverDemo />)
+```
+
+## System props
+
+`Popover` components get `COMMON`, `LAYOUT`, and `POSITION` system props. `Popover.Content` components get `COMMON`, `LAYOUT`, and `BORDER` 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. |

docs/package.json

@@ -11,7 +11,7 @@
     "node": "10.x"
   },
   "dependencies": {
-    "@primer/gatsby-theme-doctocat": "^0.16.10",
+    "@primer/gatsby-theme-doctocat": "^0.17.0",
     "@primer/octicons-react": "^9.2.0",
     "@styled-system/prop-types": "^5.1.0",
     "@styled-system/theme-get": "^5.1.0",

docs/src/@primer/gatsby-theme-doctocat/nav.yml

@@ -62,6 +62,8 @@
       url: /Link
     - title: PointerBox
       url: /PointerBox
+    - title: Popover
+      url: /Popover
     - title: Position
       url: /Position
     - title: ProgressBar

docs/yarn.lock

@@ -1234,10 +1234,10 @@
     react-is "16.10.2"
     styled-system "5.1.2"
 
-"@primer/gatsby-theme-doctocat@^0.16.10":
-  version "0.16.10"
-  resolved "https://registry.yarnpkg.com/@primer/gatsby-theme-doctocat/-/gatsby-theme-doctocat-0.16.10.tgz#9798bca7b08b548e8b9bd62f8ca7a8be9003d5a5"
-  integrity sha512-173EeoIEwf1cAO3te4XDYg+kjQwLhtlOU2LAHty8T7Hb8hjOLysBPO3rmmtz583+eWhASA0GBb6cvR5S6/OQHg==
+"@primer/gatsby-theme-doctocat@^0.17.0":
+  version "0.17.0"
+  resolved "https://registry.yarnpkg.com/@primer/gatsby-theme-doctocat/-/gatsby-theme-doctocat-0.17.0.tgz#01295b47729fc1ae6c245b5bcc717fc33c088051"
+  integrity sha512-0vshaWRPogBo7F9nhmxdhuf7SwgFrsgNJ3FXEO4GisCWQ2BWb3VzYtMx2q7f7z4z99O0g/cIQUzDTU5xPVgGug==
   dependencies:
     "@babel/preset-env" "^7.5.5"
     "@babel/preset-react" "^7.0.0"

index.d.ts

@@ -221,6 +221,30 @@ declare module '@primer/components' {
 
   export const PointerBox: React.FunctionComponent<PointerBoxProps>
 
+  export interface PopoverProps extends CommonProps, LayoutProps, PositionProps {
+    caret?:
+    | 'top'
+    | 'bottom'
+    | 'left'
+    | 'right'
+    | 'bottom-left'
+    | 'bottom-right'
+    | 'top-left'
+    | 'top-right'
+    | 'left-bottom'
+    | 'left-top'
+    | 'right-bottom'
+    | 'right-top'
+    open?: boolean
+    relative?: boolean
+  }
+
+  export interface PopoverContentProps extends BorderBoxProps { }
+
+  export const Popover: React.FunctionComponent<PopoverProps> & {
+    Content: React.FunctionComponent<PopoverContentProps>
+  }
+
   export interface PositionComponentProps
     extends PositionProps,
       CommonProps,
@@ -506,6 +530,10 @@ declare module '@primer/components/src/PointerBox' {
   import {PointerBox} from '@primer/components'
   export default PointerBox
 }
+declare module '@primer/components/src/Popover' {
+  import {Popover} from '@primer/components'
+  export default Popover
+}
 declare module '@primer/components/src/Relative' {
   import {Relative} from '@primer/components'
   export default Relative

package.json

@@ -83,5 +83,18 @@
   "peerDependencies": {
     "react": "^16.8.0",
     "styled-components": "4.x || 5.x"
+  },
+  "actionBundlesize": {
+    "build": "yarn && yarn dist",
+    "files": [
+      {
+        "path": "dist/index.esm.js",
+        "name": "ESM Build"
+      },
+      {
+        "path": "dist/index.esm.js",
+        "name": "UMD Build"
+      }
+    ]
   }
 }