chore: ad-hoc fixes for next-major branch

Author: rezrah

contributor-docs/CONTRIBUTING.md

@@ -29,7 +29,7 @@ If you're looking for something to work on, a great place to start is our issues
 
 A common question asked about Primer Components is how to know what should be added to Primer Components and what is best left as a local component in a consuming application. Though there are no hard & fast rules about what can and cannot be added to Primer Components, here are a few things we take into consideration:
 
-- Is the new feature an existing pattern in Primer CSS or related to UI built at GitHub? Primer Components is first and foremost a library for building UI at GitHub - patterns that aren't currently being used in GitHub UI (either on github.com or in a GitHub owned project outside of github.com) probably shouldn't be added to Primer Components. Exceptions to this could be helper components that don't necessarily render UI but help with the development process (like `Flex`, `Grid`, or `Box`).
+- Is the new feature an existing pattern in Primer CSS or related to UI built at GitHub? Primer Components is first and foremost a library for building UI at GitHub - patterns that aren't currently being used in GitHub UI (either on github.com or in a GitHub owned project outside of github.com) probably shouldn't be added to Primer Components. Exceptions to this could be helper components that don't necessarily render UI but help with the development process (like `Box`).
 
 - Does the proposed component get used in more than one or two places across GitHub UI? A component that's only meant to be used in one place and doesn't have potential to be reused in many places probably should exist as a local component. An example of something like this might be a component that renders content specific to a single GitHub product.
 

docs/content/Autocomplete.mdx

@@ -374,7 +374,11 @@ const InOverlayWithCustomScrollContainerRef = () => {
       height="xsmall"
       focusTrapSettings={{initialFocusRef: inputRef}}
       side="inside-top"
-      renderAnchor={props => <ButtonInvisible {...props}>Pick branches</ButtonInvisible>}
+      renderAnchor={props => (
+        <Button variant="invisible" {...props}>
+          Pick branches
+        </Button>
+      )}
     >
       <FormControl>
         <FormControl.Label visuallyHidden>Pick branches</FormControl.Label>

docs/content/core-concepts.md

@@ -45,7 +45,7 @@ Pattern components are components that are made up of several building block com
 
 - Helper Components
 
-Helper components are components that help the user achieve common CSS patterns while maintaining some control over values used. Some examples of helper components are `Flex`, `Text`, `Grid`, and the `Position` components.
+Helper components are components that help the user achieve common CSS patterns while maintaining some control over values used. An example of a helper component is `Box`.
 
 ## The `as` prop
 

docs/content/getting-started.md

@@ -18,12 +18,12 @@ You can now import Primer React from the main package module:
 
 ```javascript
 // using import syntax
-import {Box, Flex} from '@primer/react'
+import {Box} from '@primer/react'
 ```
 
 ```javascript
 // using require syntax
-const {Box, Flex} = require('@primer/react')
+const {Box} = require('@primer/react')
 ```
 
 ### Polyfills & Browser Support
@@ -41,13 +41,11 @@ Module bundlers that use ECMAScript modules (ESM) will automatically tree-shake
 ```javascript
 // using import syntax
 import Box from '@primer/react/lib/Box'
-import Flex from '@primer/react/lib/Flex'
 ```
 
 ```javascript
 // using require syntax
 const Box = require('@primer/react/lib/Box')
-const Flex = require('@primer/react/lib/Flex')
 ```
 
 Note that the modules in the `lib` folder are CommonJS-style modules; if you're using ESM and a compatible module bundler, importing files individually from `lib` provides no benefit.
@@ -59,8 +57,8 @@ Primer React ships with a few libraries labeled as peer dependencies. These libr
 Primer React requires the following libraries to be installed along with it:
 
 - `styled-components` at version 4.0.0 or higher
-- `react` at versions 16.8.0 or higher
-- `react-dom` at versions 16.8.0 or higher
+- `react` at versions 17.x or higher
+- `react-dom` at versions 17.x or higher
 
 ## ThemeProvider
 

docs/content/philosophy.md

@@ -3,21 +3,21 @@ title: Primer React Philosophy
 ---
 
 ## Presentational Components
- We are focusing primarily on presentational components that help standardize common design patterns. Primer React components don't handle fetching and submitting data to/from APIs. If you would like to handle data in a Primer Component, feel free to create a wrapper around the Primer Component to do so.
+
+We are focusing primarily on presentational components that help standardize common design patterns. Primer React components don't handle fetching and submitting data to/from APIs. If you would like to handle data in a Primer Component, feel free to create a wrapper around the Primer Component to do so.
 
 ## Assume that people will break the rules, provide safe ways for them to do so
-While we aim to standardize design in Primer React, we also provide some flexibility with constraint-based props. We offer system props via [styled-system](https://github.com/styled-system/styled-system) to allow users of the components to make small customizations, such as color and spacing, using values from the theme. Users also have the option to override the theme with a theme of their own.
 
+While we aim to standardize design in Primer React, we also provide some flexibility with constraint-based props. We offer system props via [styled-system](https://github.com/styled-system/styled-system) to allow users of the components to make small customizations, such as color and spacing, using values from the theme. Users also have the option to override the theme with a theme of their own.
 
 ## Pattern Components vs Helper Components
 
 Our components can roughly be categorized into two different component types:
 
-
 - Pattern Components
 
 Pattern components help us repeat commonly used UI patterns and interactions in order to maintain our brand and provide a great user experience. Some examples of pattern components are `Button`, `Avatar`, or `Label`.
 
 - Helper Components
 
-Helper components are components that help the user achieve common CSS patterns while maintaining some control over values used. Some examples of helper components are `Flex`, `Text`, `Grid`, and the `Position` components.
+Helper components are components that help the user achieve common CSS patterns while maintaining some control over values used. An example of a helper component is `Box`.

docs/content/system-props.mdx

@@ -20,7 +20,7 @@ All Primer React components have access to the `as` prop, provided by [styled-co
 
 For example, if you wanted to add some flex utilities to the `Text` component, you could do:
 
-```jsx live
+```jsx live deprecated
 <Text as={Flex}>Hello!</Text>
 ```
 

src/deprecated/DropdownMenu/DropdownButton.tsx

@@ -5,6 +5,9 @@ import StyledOcticon from '../../StyledOcticon'
 
 export type DropdownButtonProps = ButtonProps
 
+/**
+ * @deprecated Use Button with Octicons instead. See https://primer.style/react/drafts/Button2#appending-an-icon for more details.
+ */
 export const DropdownButton = React.forwardRef<HTMLElement, React.PropsWithChildren<DropdownButtonProps>>(
   ({children, ...props}: React.PropsWithChildren<DropdownButtonProps>, ref): JSX.Element => (
     <Button ref={ref} type="button" {...props}>