Deprecate utility components

.changeset/green-worms-nail.md

@@ -1,5 +1,5 @@
 ---
-"@primer/components": minor
+'@primer/components': minor
 ---
 
 `Box` now accepts all [styled system props](https://styled-system.com/table/).

.changeset/metal-swans-allow.md

@@ -0,0 +1,30 @@
+---
+'@primer/components': minor
+---
+
+Deprecate utility components in favor of using Box.
+
+The following components will be deprecated:
+
+Flex
+Grid
+Position
+Absolute
+Fixed
+Relative
+Sticky
+BorderBox
+
+In place of these components, you may now use `Box`, which accepts all system props. There is a codemod availible to effectively handle these deprecations.
+
+First, install jscodeshift:
+
+`npm install -g jscodeshift`
+
+Then, run the codemod using the appropriate command (examples given from the primer/components root directory)
+
+typescript example:
+`jscodeshift -t codemods/deprecateUtilityComponents.js --parser=tsx path/to/workspace/src/*.tsx`
+
+babel example:
+`jscodeshift -t codemods/deprecateUtilityComponents.js --parser=babel path/to/workspace/src/*.jsx`

codemods/__tests__/deprecateUtilityComponents.js

@@ -0,0 +1,200 @@
+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'
+)
+
+defineInlineTest(
+  deprecateUtilityComponents,
+  {},
+  `
+import {BorderBox} from '@primer/components'
+export default () => (
+  <BorderBox borderColor="border.secondary" borderRadius={1}>
+    <div />
+  </BorderBox>
+)
+`.trim(),
+  `
+import {Box} from '@primer/components'
+export default () => (
+  <Box borderColor="border.secondary" borderRadius={1} borderWidth="1px" borderStyle="solid">
+    <div />
+  </Box>
+)
+`.trim(),
+  'deprecateUtilityComponents'
+)
+
+defineInlineTest(
+  deprecateUtilityComponents,
+  {},
+  `
+import {Flex} from '@primer/components'
+export default () => (
+  <Flex p={2} m={1}>
+    <div />
+  </Flex>
+)
+`.trim(),
+  `
+import {Box} from '@primer/components'
+export default () => (
+  <Box p={2} m={1} display="flex">
+    <div />
+  </Box>
+)
+`.trim(),
+  'deprecateUtilityComponents'
+)

codemods/deprecateUtilityComponents.js

@@ -0,0 +1,111 @@
+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'
+      }
+    },
+    BorderBox: {
+      identifier: 'Box',
+      attributes: {
+        borderWidth: '1px',
+        borderStyle: 'solid',
+        borderColor: 'border.primary',
+        borderRadius: 2
+      }
+    }
+  })
+
+  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 || {})) {
+        const expression = typeof value === 'string' ? j.literal(value) : j.jsxExpressionContainer(j.literal(value))
+        const attrExists = nodePath.value.attributes.find(a => a?.name?.name === attr)
+        if (!attrExists) {
+          nodePath.value.attributes.push(j.jsxAttribute(j.jsxIdentifier(attr), expression))
+        }
+      }
+    })
+
+    // 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: 'typescript',
         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>
     )
   }}