Deprecate utility components

.changeset/green-worms-nail.md

@@ -0,0 +1,5 @@
+---
+"@primer/components": patch
+---
+
+Box may accept all system props.

.changeset/metal-swans-allow.md

@@ -0,0 +1,5 @@
+---
+"@primer/components": minor
+---
+
+Deprecate utility components.

codemods/__tests__/deprecateUtilityComponents.js

@@ -0,0 +1,156 @@
+import {defineInlineTest} from 'jscodeshift/dist/testUtils'
+import deprecateUtilityComponents from '../deprecateUtilityComponents'
+
+defineInlineTest(
+  deprecateUtilityComponents,
+  {},
+  `
+import {Flex} from '@primer/components'
+export default () => (
+  <Flex>
+    <div />
+  </Flex>
+)
+`.trim(),
+  `
+import {Box} from '@primer/components'
+export default () => (
+  <Box display="flex">
+    <div />
+  </Box>
+)
+`.trim(),
+  'deprecateUtilityComponents'
+)
+
+defineInlineTest(
+  deprecateUtilityComponents,
+  {},
+  `
+import {Grid} from '@primer/components'
+export default () => (
+  <Grid>
+    <div />
+  </Grid>
+)
+`.trim(),
+  `
+import {Box} from '@primer/components'
+export default () => (
+  <Box display="grid">
+    <div />
+  </Box>
+)
+`.trim(),
+  'deprecateUtilityComponents'
+)
+
+defineInlineTest(
+  deprecateUtilityComponents,
+  {},
+  `
+import {Position} from '@primer/components'
+export default () => (
+  <Position>
+    <div />
+  </Position>
+)
+`.trim(),
+  `
+import {Box} from '@primer/components'
+export default () => (
+  <Box>
+    <div />
+  </Box>
+)
+`.trim(),
+  'deprecateUtilityComponents'
+)
+
+defineInlineTest(
+  deprecateUtilityComponents,
+  {},
+  `
+import {Absolute} from '@primer/components'
+export default () => (
+  <Absolute>
+    <div />
+  </Absolute>
+)
+`.trim(),
+  `
+import {Box} from '@primer/components'
+export default () => (
+  <Box position="absolute">
+    <div />
+  </Box>
+)
+`.trim(),
+  'deprecateUtilityComponents'
+)
+
+defineInlineTest(
+  deprecateUtilityComponents,
+  {},
+  `
+import {Relative} from '@primer/components'
+export default () => (
+  <Relative>
+    <div />
+  </Relative>
+)
+`.trim(),
+  `
+import {Box} from '@primer/components'
+export default () => (
+  <Box position="relative">
+    <div />
+  </Box>
+)
+`.trim(),
+  'deprecateUtilityComponents'
+)
+
+defineInlineTest(
+  deprecateUtilityComponents,
+  {},
+  `
+import {Fixed} from '@primer/components'
+export default () => (
+  <Fixed>
+    <div />
+  </Fixed>
+)
+`.trim(),
+  `
+import {Box} from '@primer/components'
+export default () => (
+  <Box position="fixed">
+    <div />
+  </Box>
+)
+`.trim(),
+  'deprecateUtilityComponents'
+)
+
+defineInlineTest(
+  deprecateUtilityComponents,
+  {},
+  `
+import {Sticky} from '@primer/components'
+export default () => (
+  <Sticky>
+    <div />
+  </Sticky>
+)
+`.trim(),
+  `
+import {Box} from '@primer/components'
+export default () => (
+  <Box position="sticky">
+    <div />
+  </Box>
+)
+`.trim(),
+  'deprecateUtilityComponents'
+)

codemods/deprecateUtilityComponents.js

@@ -0,0 +1,98 @@
+const prettify = require('./lib/prettify')
+
+module.exports = (file, api) => {
+  const j = api.jscodeshift
+  const ast = j(file.source)
+
+  deprecateComponents(ast, j, '@primer/components', {
+    Flex: {
+      identifier: 'Box',
+      attributes: {
+        display: 'flex'
+      }
+    },
+    Grid: {
+      identifier: 'Box',
+      attributes: {
+        display: 'grid'
+      }
+    },
+    Position: {
+      identifier: 'Box',
+      attributes: {}
+    },
+    Absolute: {
+      identifier: 'Box',
+      attributes: {
+        position: 'absolute'
+      }
+    },
+    Relative: {
+      identifier: 'Box',
+      attributes: {
+        position: 'relative'
+      }
+    },
+    Fixed: {
+      identifier: 'Box',
+      attributes: {
+        position: 'fixed'
+      }
+    },
+    Sticky: {
+      identifier: 'Box',
+      attributes: {
+        position: 'sticky'
+      }
+    }
+  })
+
+  return prettify(ast, file)
+}
+
+function deprecateComponents(ast, j, importSource, importMap) {
+  const imports = ast.find(j.ImportDeclaration, {source: {value: importSource}})
+  const importsByName = {}
+
+  imports.forEach(decl => {
+    j(decl)
+      .find(j.ImportSpecifier)
+      .forEach(spec => {
+        importsByName[spec.node.imported.name] = spec
+      })
+  })
+
+  for (const [from, to] of Object.entries(importMap)) {
+    rewriteImport(from, to.identifier, to.attributes)
+  }
+
+  function rewriteImport(from, to, attributes) {
+    imports.forEach(decl => {
+      j(decl)
+        .find(j.ImportSpecifier, {imported: {name: from}})
+        .forEach(spec => {
+          if (importsByName[to]) {
+            // if the destination import already exists and there are members
+            // in this identifier, then this one is a dupe
+            j(spec).remove()
+          } else {
+            // otherwise, we can safely rename this one to the new identifier
+            spec.node.imported.name = to
+            importsByName[to] = spec
+          }
+        })
+    })
+
+    ast.find(j.JSXOpeningElement, {name: {name: from}}).forEach(nodePath => {
+      for (const [attr, value] of Object.entries(attributes || {})) {
+        nodePath.value.attributes.push(j.jsxAttribute(j.jsxIdentifier(attr), j.literal(value)))
+      }
+    })
+
+    // replace all of the rewritten identifiers with member expressions
+    ast
+      .find(j.Identifier, {name: from})
+      .filter(id => id.parent.node.type !== 'ImportSpecifier')
+      .replaceWith(j.jsxIdentifier(to))
+  }
+}

codemods/lib/prettify.js

@@ -7,7 +7,7 @@ module.exports = function prettify(ast, file) {
     source,
     Object.assign(
       {
-        parser: 'babylon',
+        parser: 'babel',
         filepath: file.path
       },
       config

docs/content/AnchoredOverlay.mdx

@@ -15,23 +15,19 @@ The overlay can be opened and navigated using keyboard or mouse.
     const closeOverlay = React.useCallback(() => setIsOpen(false), [setIsOpen])
     return (
       <AnchoredOverlay
-        renderAnchor={(anchorProps) => (
-          <DropdownButton {...anchorProps}>
-            Click me to open
-          </DropdownButton>
-        )}
+        renderAnchor={anchorProps => <DropdownButton {...anchorProps}>Click me to open</DropdownButton>}
         open={isOpen}
         onOpen={openOverlay}
         onClose={closeOverlay}
       >
-        <Flex flexDirection="column" maxWidth="300px" padding={2}>
+        <Box display="flex" flexDirection="column" maxWidth="300px" padding={2}>
           <p>
-            This menu automatically receives a focus trap and focus zone.  Use up/down keys to navigate between buttons
+            This menu automatically receives a focus trap and focus zone. Use up/down keys to navigate between buttons
           </p>
           <Button mb={1}>Button 1</Button>
           <Button mb={1}>Button 2</Button>
           <Button>Button 3</Button>
-        </Flex>
+        </Box>
       </AnchoredOverlay>
     )
   }}

docs/content/Box.md

@@ -4,33 +4,75 @@ title: Box
 
 The Box component serves as a wrapper component for most layout related needs. Use Box to set values such as `display`, `width`, `height`, and more. See the LAYOUT section of our [System Props](/system-props) documentation for the full list of available props. In practice, this component is used frequently as a wrapper around other components to achieve Box Model related styling.
 
-## Default example
-
-```jsx live live
-<Box>
-  Box can be used to create both{' '}
-  <Box as="span" color="text.inverse" bg="bg.successInverse">
-    inline
-  </Box>{' '}
-  and
-  <Box color="text.inverse" bg="bg.dangerInverse">
-    block-level elements,
+## Examples
+
+### Default
+
+```jsx live
+<Box color="text.secondary" bg="bg.tertiary" p={3}>
+  Hello
+</Box>
+```
+
+### Border on all sides
+
+```jsx live
+<Box borderColor="border.primary" borderWidth={1} borderStyle="solid" p={3}>
+  Hello
+</Box>
+```
+
+### Border on one side
+
+```jsx live
+<Box borderColor="border.primary" borderBottomWidth={1} borderBottomStyle="solid" pb={3}>
+  Hello
+</Box>
+```
+
+### Flexbox
+
+Use `Box` to create [flexbox](https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Flexbox) layouts.
+
+```jsx live
+<Box display="flex">
+  <Box p={3} borderColor="border.primary" borderWidth={1} borderStyle="solid">
+    1
+  </Box>
+  <Box flexGrow={1} p={3} borderColor="border.primary" borderWidth={1} borderStyle="solid">
+    2
+  </Box>
+  <Box p={3} borderColor="border.primary" borderWidth={1} borderStyle="solid">
+    3
+  </Box>
+</Box>
+```
+
+### Grid
+
+Use `Box` to create [grid](https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Grids) layouts.
+
+```jsx live
+<Box display="grid" gridTemplateColumns="1fr 1fr" gridGap={3}>
+  <Box p={3} borderColor="border.primary" borderWidth={1} borderStyle="solid">
+    1
   </Box>
-  <Box color="text.inverse" bg="bg.warningInverse" width={[1, 1, 1 / 2]}>
-    elements with fixed or responsive width and height,
+  <Box p={3} borderColor="border.primary" borderWidth={1} borderStyle="solid">
+    2
   </Box>
-  <Box color="text.inverse" bg="bg.infoInverse" p={4} mt={2}>
-    and more!
+  <Box p={3} borderColor="border.primary" borderWidth={1} borderStyle="solid">
+    3
   </Box>
 </Box>
 ```
 
 ## System props
 
-Box components get the `COMMON`, `LAYOUT`, and `FLEX` categories of system props. Read our [System Props](/system-props) doc page for a full list of available props.
+Box components may receive system props of any category. Read our [System Props](/system-props) doc page for a full list of available props.
 
 ## Component props
 
-| Prop name | Type   | Default | Description                         |
-| :-------- | :----- | :-----: | :---------------------------------- |
-| as        | String |  `div`  | sets the HTML tag for the component |
+| Prop | Type                |                                 Default                                  | Description |
+| :--- | :------------------ | :----------------------------------------------------------------------: | :---------- |
+| `as` |                     | [`"div"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div) |             |
+| `sx` | `SystemStyleObject` |                                    —                                     |             |