@primer/components 29.1.0 → 29.1.1-rc.cea79543

package/docs/content/FilterList.md

@@ -0,0 +1,44 @@
+---
+title: FilterList
+---
+
+The FilterList component is a menu with filter options that filter the main content of the page.
+
+## Default example
+
+```jsx live
+<FilterList>
+  <FilterList.Item selected count="32" href="#foo">
+    First Filter
+  </FilterList.Item>
+  <FilterList.Item count="2" href="#bar">
+    Second Filter
+  </FilterList.Item>
+  <FilterList.Item href="#baz">Third Filter</FilterList.Item>
+</FilterList>
+```
+
+## System props
+
+<Note variant="warning">
+
+System props are deprecated in all components except [Box](/Box). Please use the [`sx` prop](/overriding-styles) instead.
+
+</Note>
+
+FilterList components get `COMMON` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+## Component props
+
+#### FilterList
+
+`FilterList` does not get any additional props other than the system props mentioned above.
+
+#### FilterList.Item
+
+| Name     | Type    | Default | Description                                                      |
+| :------- | :------ | :-----: | :--------------------------------------------------------------- |
+| count    | Number  |         | Number to be displayed in the list item                          |
+| as       | String  |   `a`   | sets the HTML tag for the component                              |
+| selected | Boolean |         | Used to set selected style                                       |
+| small    | Boolean |  false  | Used to create a smaller version of the standard FilterList.Item |

package/docs/content/FilteredSearch.md

@@ -0,0 +1,39 @@
+---
+title: FilteredSearch
+---
+
+The FilteredSearch component helps style a Dropdown and a TextInput side-by-side.
+
+**Note:** You _must_ use a `TextInput` and `Dropdown` (or native `<details>` and `<summary>`) in order for this component to work properly.
+
+## Default example
+
+```jsx live
+<FilteredSearch>
+  <Dropdown>
+    <Dropdown.Button>Filter</Dropdown.Button>
+    <Dropdown.Menu direction="sw">
+      <Dropdown.Item>Item 1</Dropdown.Item>
+      <Dropdown.Item>Item 2</Dropdown.Item>
+      <Dropdown.Item>Item 3</Dropdown.Item>
+    </Dropdown.Menu>
+  </Dropdown>
+  <TextInput icon={SearchIcon} />
+</FilteredSearch>
+```
+
+## System props
+
+<Note variant="warning">
+
+System props are deprecated in all components except [Box](/Box). Please use the [`sx` prop](/overriding-styles) instead.
+
+</Note>
+
+FilteredSearch gets `COMMON` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+## Component props
+
+#### FilteredSearch.Children
+
+FilteredSearch is expected to contain a [`Dropdown`](/Dropdown) followed by a [`TextInput`](/TextInput).

package/docs/content/Flash.md

@@ -0,0 +1,42 @@
+---
+title: Flash
+---
+
+The Flash component informs users of successful or pending actions.
+
+## Default example
+
+```jsx live
+<Flash>Default Flash</Flash>
+<Flash variant="success">Success Flash</Flash>
+<Flash variant="warning">Warning Flash</Flash>
+<Flash variant="danger">Danger Flash</Flash>
+```
+
+## With an icon
+
+Flash components with icons inside of them will automatically set the correct color for the icon depending on the type of Flash, as well as applying the correct right margin.
+
+```jsx live
+<Flash variant="success">
+  <StyledOcticon icon={CheckIcon} />
+  Success!
+</Flash>
+```
+
+## System props
+
+<Note variant="warning">
+
+System props are deprecated in all components except [Box](/Box). Please use the [`sx` prop](/overriding-styles) instead.
+
+</Note>
+
+Flash components get `COMMON` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+## Component props
+
+| Name    | Type    | Default | Description                                                                                                              |
+| :------ | :------ | :-----: | :----------------------------------------------------------------------------------------------------------------------- |
+| full    | Boolean |         | Creates a full width Flash component                                                                                     |
+| variant | String  | default | Can be one of `default`, `success`, `warning`, or `danger` - sets the background color and border of the Flash component |

package/docs/content/Flex.md

@@ -0,0 +1,58 @@
+---
+title: Flex
+status: Deprecated
+---
+
+The `Flex` component behaves the same as the `Box` component except that it has `display: flex` set by default.
+
+## Deprecation
+
+Use [Box](/Box) instead.
+
+**Before**
+
+```jsx
+<Flex flexWrap="nowrap">
+  <Box p={3} color="text.inverse" bg="bg.infoInverse">
+    Item 1
+  </Box>
+</Flex>
+```
+
+**After**
+
+```jsx
+<Box display="flex" flexWrap="nowrap">
+  <Box p={3} color="text.inverse" bg="bg.infoInverse">
+    Item 1
+  </Box>
+</Box>
+```
+
+## Default example
+
+```jsx live
+<Box borderWidth="1px" borderStyle="solid" borderColor="border.primary" width={300} height={300} borderRadius={0}>
+  <Flex flexWrap="nowrap">
+    <Box p={3} color="text.inverse" bg="bg.infoInverse">
+      Item 1
+    </Box>
+    <Box p={3} color="text.inverse" bg="bg.warningInverse">
+      Item 2
+    </Box>
+    <Box p={3} color="text.inverse" bg="bg.dangerInverse">
+      Item 3
+    </Box>
+  </Flex>
+</Box>
+```
+
+## System props
+
+Flex components get `FLEX`, `COMMON`, and `LAYOUT` system props.
+
+Read our [System Props](/system-props) doc page for a full list of available props.
+
+## Component props
+
+`Flex` does not get any additional props other than the system props mentioned above.

package/docs/content/FormGroup.md

@@ -0,0 +1,44 @@
+---
+title: FormGroup
+---
+
+Adds styles for multiple form elements used together.
+
+## Default example
+
+```jsx live
+<FormGroup>
+  <FormGroup.Label htmlFor="example-text">Example text</FormGroup.Label>
+  <TextInput id="example-text" value="Example Value" />
+</FormGroup>
+
+<FormGroup>
+  <FormGroup.Label htmlFor="example-text-b">Example text</FormGroup.Label>
+  <TextInput id="example-text-b" value="Example Value" />
+</FormGroup>
+```
+
+## System props
+
+<Note variant="warning">
+
+System props are deprecated in all components except [Box](/Box). Please use the [`sx` prop](/overriding-styles) instead.
+
+</Note>
+
+FormGroup components get `COMMON` system props. FormGroup.Label components get `COMMON` and `TYPOGRAPHY` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+## Component props
+
+### FormGroup
+
+| Name | Type   | Default | Description                         |
+| :--- | :----- | :-----: | :---------------------------------- |
+| as   | String |  `div`  | Sets the HTML tag for the component |
+
+### FormGroup.Label
+
+| Name    | Type   | Default | Description                                                                    |
+| :------ | :----- | :-----: | :----------------------------------------------------------------------------- |
+| as      | String | `label` | Sets the HTML tag for the component                                            |
+| htmlFor | String |         | The value of `htmlFor` needs to be the same as the `id` of the input it labels |

package/docs/content/Grid.md

@@ -0,0 +1,59 @@
+---
+title: Grid
+status: Deprecated
+---
+
+Grid is a component that exposes grid system props. See the [CSS Tricks Complete Guide to Grid](https://css-tricks.com/snippets/css/complete-guide-grid/) to learn more about Grid Layout.
+
+## Deprecation
+
+Use [Box](/Box) instead.
+
+**Before**
+
+```jsx
+<Grid gridTemplateColumns="repeat(2, auto)" gridGap={3}>
+  <Box p={3} color="text.inverse" bg="bg.infoInverse">
+    1
+  </Box>
+  <Box p={3} color="text.inverse" bg="bg.warningInverse">
+    2
+  </Box>
+</Grid>
+```
+
+**After**
+
+```jsx
+<Box display="grid" gridTemplateColumns="repeat(2, auto)" gridGap={3}>
+  <Box p={3} color="text.inverse" bg="bg.infoInverse">
+    1
+  </Box>
+  <Box p={3} color="text.inverse" bg="bg.warningInverse">
+    2
+  </Box>
+</Box>
+```
+
+## Default example
+
+```jsx live
+<Grid gridTemplateColumns="repeat(2, auto)" gridGap={3}>
+  <Box p={3} color="text.inverse" bg="bg.infoInverse">
+    1
+  </Box>
+  <Box p={3} color="text.inverse" bg="bg.warningInverse">
+    2
+  </Box>
+</Grid>
+```
+
+## System props
+
+Grid components get `GRID`, `COMMON`, and `LAYOUT` system props.
+
+Read our [System Props](/system-props) doc page for a full list of available props.
+
+## Component props
+
+`Grid` does not get any additional props other than the system props mentioned above.

package/docs/content/Header.md

@@ -0,0 +1,79 @@
+---
+title: Header
+---
+
+Use the `Header` component to create a header that has all of its items aligned vertically with consistent horizontal spacing.
+
+## Default example
+
+All items directly under the Header component should be a `Header.Item` component. Inside these components can be anything (text, forms, images...), and the `Header.Item` component will make sure these elements vertically align with each other.
+
+`Header.Item` elements have a built-in margin that will need to be overridden with the `mr={0}` props for the last element in the container. We relied on the prop here instead of `:last-child` because the last child isn't always the item visible. On responsive pages, there's a mobile menu that gets presented to the user at smaller breakpoints.
+
+```jsx live
+<Header>
+  <Header.Item>
+    <Header.Link href="#" fontSize={2}>
+      <StyledOcticon icon={MarkGithubIcon} size={32} mr={2} />
+      <span>GitHub</span>
+    </Header.Link>
+  </Header.Item>
+  <Header.Item full>Menu</Header.Item>
+  <Header.Item mr={0}>
+    <Avatar src="https://github.com/octocat.png" size={20} square alt="@octocat" />
+  </Header.Item>
+</Header>
+```
+
+## Header with full-size item example
+
+```jsx live
+<Header>
+  <Header.Item>Item 1</Header.Item>
+  <Header.Item full border={1} borderStyle="solid">
+    Item 2
+  </Header.Item>
+  <Header.Item mr={0}>Item 3</Header.Item>
+</Header>
+```
+
+## Header with links example
+
+```jsx live
+<Header>
+  <Header.Item>
+    <Header.Link href="#">About</Header.Link>
+  </Header.Item>
+  <Header.Item>
+    <Header.Link href="#">Releases</Header.Link>
+  </Header.Item>
+  <Header.Item>
+    <Header.Link href="#">Team</Header.Link>
+  </Header.Item>
+</Header>
+```
+
+## System props
+
+<Note variant="warning">
+
+System props are deprecated in all components except [Box](/Box). Please use the [`sx` prop](/overriding-styles) instead.
+
+</Note>
+
+`Header` and `Header.Item` components get `COMMON` and `BORDER` system props. `Header.Link` component gets `COMMON`, `BORDER`, and `TYPOGRAPHY` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+## Component props
+
+### Header.Item
+
+| Prop name | Type    | Description                                |
+| :-------- | :------ | :----------------------------------------- |
+| full      | Boolean | stretches item to fill the available space |
+
+### Header.Link
+
+| Prop name | Type   | Description                         |
+| :-------- | :----- | :---------------------------------- |
+| as        | String | sets the HTML tag for the component |
+| href      | String | URL to be used for the Link         |

package/docs/content/Heading.md

@@ -0,0 +1,22 @@
+---
+title: Heading
+---
+
+The Heading component will render an html `h2` tag without any default styling. Other heading level elements `h1-h6` are available through use of the `as` prop (see [System Props](/system-props) for additional explanation). Please reference the [w3 recommendations for headings](https://www.w3.org/WAI/tutorials/page-structure/headings/) to ensure your headings provide an accessible experience for screen reader users.
+
+**Attention:** Make sure to include a valid heading element to render a Heading component other than `h2` (`<Heading as="h1">H1 Element</Heading>`).
+
+## Default example
+```jsx live
+<Heading fontSize={1} mb={2}>H2 heading with fontSize={1}</Heading>
+```
+
+## System props
+
+Heading components get `TYPOGRAPHY` and `COMMON` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+## Component props
+
+| Prop name | Type    | Description                                      |
+| :-------- | :------ | :----------------------------------------------- |
+| as        | String or React element  | sets the HTML tag for the component              |

package/docs/content/Label.md

@@ -0,0 +1,40 @@
+---
+title: Label
+---
+
+The Label component is used to add contextual metadata to a design. Visually it styles text, adds padding, and rounded corners.
+
+## Default example
+
+```jsx live
+  <Label variant="small" outline sx={{borderColor: "border.danger", mr: 2, color: "text.danger"}}>small</Label>
+  <Label variant="medium" sx={{mr: 2}}>medium (default)</Label>
+  <Label variant="large" sx={{mr: 2}}>large</Label>
+  <Label variant="xl">xl label</Label>
+
+  <Box mt={4}/>
+  <Label variant="medium" sx={{bg:"#A575FF", m: 1}}>good first issue</Label>
+  <Label variant="medium" sx={{bg:"#FF75C8", m: 1}}>🚂 deploy: train</Label>
+  <Label variant="medium" sx={{bg:"#1C90FA", m: 1}}>css</Label>
+  <Label variant="medium" sx={{bg:"#FFF06C", color:"#24292E", m: 1}}>documentation</Label>
+  <Label variant="medium" sx={{bg: "#656BFE", m: 1}}>primer</Label>
+```
+
+## System props
+
+<Note variant="warning">
+
+System props are deprecated in all components except [Box](/Box). Please use the [`sx` prop](/overriding-styles) instead.
+
+</Note>
+
+Label components get `COMMON` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+## Component props
+
+| Name       | Type    |        Default         | Description                                                                    |
+| :--------- | :------ | :--------------------: | :----------------------------------------------------------------------------- |
+| outline    | Boolean |                        | Creates an outline style label                                                 |
+| variant    | String  |        'medium'        | Can be one of `small`, `medium` (default), `large` or `xl` .                   |
+| dropshadow | Boolean |                        | Adds a dropshadow to the label                                                 |
+| bg         | String  | 'label.primary.border' | Part of the `COMMON` system props, used to change the background of the label. |

package/docs/content/LabelGroup.md

@@ -0,0 +1,31 @@
+---
+title: LabelGroup
+---
+
+The LabelGroup component is used to add commonly used margins and wrapping for groups of Labels.
+
+## Default example
+
+```jsx live
+<LabelGroup>
+  <Label>Default label</Label>
+  <Label sx={{color: 'prState.closed.text', bg: 'prState.closed.bg'}}>
+    Label with background indicating a closed PR state
+  </Label>
+  <Label outline>Default outline label</Label>
+</LabelGroup>
+```
+
+## System props
+
+<Note variant="warning">
+
+System props are deprecated in all components except [Box](/Box). Please use the [`sx` prop](/overriding-styles) instead.
+
+</Note>
+
+LabelGroup components get `COMMON` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+## Component props
+
+LabelGroup does not get any additional props.

package/docs/content/Link.md

@@ -0,0 +1,37 @@
+---
+title: Link
+---
+
+The Link component styles anchor tags with default hyperlink color cues and hover text decoration. `Link` is used for destinations, or moving from one page to another.
+
+In special cases where you'd like a `<button>` styled like a `Link`, use `<Link as='button'>`. Make sure to provide a click handler with `onClick`.
+
+**Important:** When using the `as` prop, be sure to always render an accessible element type, like `a`, `button`, `input`, or `summary`.
+
+## Default example
+
+```jsx live
+<Link sx={{mb: 1}} href="https://github.com">
+  Link
+</Link>
+```
+
+## System props
+
+<Note variant="warning">
+
+System props are deprecated in all components except [Box](/Box). Please use the [`sx` prop](/overriding-styles) instead.
+
+</Note>
+
+Link components get `COMMON` and `TYPOGRAPHY` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+## Component props
+
+| Name       | Type    | Default | Description                                                                     |
+| :--------- | :------ | :-----: | :------------------------------------------------------------------------------ |
+| href       | String  |         | URL to be used for the Link                                                     |
+| muted      | Boolean |  false  | Uses a less prominent shade for Link color, and the default link shade on hover |
+| underline  | Boolean |  false  | Adds underline to the Link                                                      |
+| as         | String  |   'a'   | Can be 'a', 'button', 'input', or 'summary'                                     |
+| hoverColor | String  |         | Color used when hovering over link                                              |

package/docs/content/Overlay.mdx

@@ -0,0 +1,94 @@
+---
+title: Overlay
+---
+
+An `Overlay` is a flexible floating surface, used to display transient content such as menus, selection options, dialogs, and more. Overlays use shadows to express elevation. The `Overlay` component handles all behaviors needed by overlay UIs as well as the common styles that all overlays should have. `Overlay` is the base component for many of our overlay-type components.
+
+Behaviors include:
+
+- Rendering the overlay in a React Portal so that it always renders on top of other content on the page
+- Trapping focus
+- Calling a user provided function when the user presses `Escape`
+- Calling a user provided function when the user clicks outside of the container
+- Focusing either user provided element, or the first focusable element in the container when it is opened
+- Returning focus to an element when container is closed
+
+## Accessibility considerations
+
+- The `Overlay` must either have:
+  - A value set for the `aria-labelledby` attribute that refers to a visible title.
+  - An `aria-label` attribute
+- If the `Overlay` should also have a longer description, use `aria-describedby`
+- The `Overlay` component has a `role="dialog"` set on it, if you are using `Overlay` for alerts, you can pass in `role="alertdialog"` instead. Please read the [W3C guidelines](https://www.w3.org/TR/wai-aria-1.1/#alertdialog) to determine which role is best for your use case
+- The `Overlay` component has `aria-modal` set to `true` by default and should not be overridden as all `Overlay`s behave as modals.
+
+See the W3C accessibility recommendations for modals [here](https://www.w3.org/TR/wai-aria-practices-1.1/#dialog_roles_states_props).
+
+## Positioning
+
+`Overlay` renders its `children` within a div positioned absolutely within a portal within the default portal root. The overlay will not update its positioning if the portal root's positioning changes (e.g., if the portal root is statically positioned after some DOM element that dynamically resizes). You may consider [customizing the portal or specifying a different portal root](/Portal#customizing-the-portal-root) to achieve different positioning behavior.
+
+## Default example
+
+```javascript live noinline
+const Demo = () => {
+  // you must manage your own open state
+  const [isOpen, setIsOpen] = React.useState(false)
+  const noButtonRef = React.useRef(null)
+  const anchorRef = React.useRef(null)
+  return (
+    <>
+      <Button ref={anchorRef} onClick={() => setIsOpen(!isOpen)}>
+        open overlay
+      </Button>
+      {/* be sure to conditionally render the Overlay. This helps with performance and is required. */}
+      {isOpen && (
+        <Overlay
+          initialFocusRef={noButtonRef}
+          returnFocusRef={anchorRef}
+          ignoreClickRefs={[anchorRef]}
+          onEscape={() => setIsOpen(!isOpen)}
+          onClickOutside={() => setIsOpen(false)}
+          aria-labelledby="title"
+        >
+          <Box display="flex" flexDirection="column" p={2}>
+            <Text id="title">Are you sure you would like to delete this item?</Text>
+            <Button>yes</Button>
+            <Button ref={noButtonRef}>no</Button>
+          </Box>
+        </Overlay>
+      )}
+    </>
+  )
+}
+
+render(<Demo />)
+```
+
+## System props
+
+<Note variant="warning">
+
+System props are deprecated in all components except [Box](/Box). Please use the [`sx` prop](/overriding-styles) instead.
+
+</Note>
+
+`Overlay` gets `COMMON` system props. Read the [System Props](/system-props) doc page for a full list of available props.
+
+## Component props
+
+| Name                | Type                                                           |   Default   | Description                                                                                                                                                                                                                                                                                                                   |
+| :------------------ | :------------------------------------------------------------- | :---------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ignoreClickRefs     | `React.RefObject<HTMLElement> []`                              | `undefined` | Optional. An array of ref objects to ignore clicks on in the `onOutsideClick` behavior. This is often used to ignore clicking on the element that toggles the open/closed state for the `Overlay` to prevent the `Overlay` from being toggled twice.                                                                          |
+| initialFocusRef     | `React.RefObject<HTMLElement>`                                 | `undefined` | Optional. Ref for the element to focus when the `Overlay` is opened. If nothing is provided, the first focusable element in the `Overlay` body is focused.                                                                                                                                                                    |
+| anchorRef           | `React.RefObject<HTMLElement>`                                 | `undefined` | Required. Element the `Overlay` should be anchored to.                                                                                                                                                                                                                                                                        |
+| returnFocusRef      | `React.RefObject<HTMLElement>`                                 | `undefined` | Required. Ref for the element to focus when the `Overlay` is closed.                                                                                                                                                                                                                                                          |
+| onClickOutside      | `function`                                                     | `undefined` | Required. Function to call when clicking outside of the `Overlay`. Typically this function sets the `Overlay` visibility state to `false`.                                                                                                                                                                                    |
+| onEscape            | `function`                                                     | `undefined` | Required. Function to call when user presses `Escape`. Typically this function sets the `Overlay` visibility state to `false`.                                                                                                                                                                                                |
+| width               | `'small' │ 'medium' │ 'large' │ 'xlarge' │ 'xxlarge' │ 'auto'` |   `auto`    | Sets the width of the `Overlay`, pick from our set list of widths, or pass `auto` to automatically set the width based on the content of the `Overlay`. `small` corresponds to `256px`, `medium` corresponds to `320px`, `large` corresponds to `480px`, `xlarge` corresponds to `640px`, `xxlarge` corresponds to `960px`.   |
+| height              | `'xsmall', 'small', 'medium', 'large', 'xlarge', 'auto'`       |   `auto`    | Sets the height of the `Overlay`, pick from our set list of heights, or pass `auto` to automatically set the height based on the content of the `Overlay`. `xsmall` corresponds to `192px`, `small` corresponds to `256px`, `medium` corresponds to `320px`, `large` corresponds to `432px`, `xlarge` corresponds to `600px`. |
+| visibility          | `'visible', 'hidden'`                                          |  `visible`  | Sets the visibility of the `Overlay`.                                                                                                                                                                                                                                                                                         |
+| anchorSide          | `AnchorSide`                                                   |  undefined  | Optional. If provided, the Overlay will slide into position from the side of the anchor with a brief animation                                                                                                                                                                                                                |
+| top                 | `number`                                                       |      0      | Vertical position of the overlay, relative to its closest positioned ancestor (often its `Portal`).                                                                                                                                                                                                                           |
+| left                | `number`                                                       |      0      | Horizontal position of the overlay, relative to its closest positioned ancestor (often its `Portal`).                                                                                                                                                                                                                         |
+| portalContainerName | `string`                                                       | `undefined` | Optional. If defined, Overlays will be rendered in the named portal. See also `Portal`.                                                                                                                                                                                                                                       |

package/docs/content/Pagehead.md

@@ -0,0 +1,27 @@
+---
+title: Pagehead
+---
+
+Give a page a clear, separated title and optional top nav by using Pagehead.
+
+## Default example
+
+```jsx live
+<Pagehead>Pagehead</Pagehead>
+```
+
+## System props
+
+<Note variant="warning">
+
+System props are deprecated in all components except [Box](/Box). Please use the [`sx` prop](/overriding-styles) instead.
+
+</Note>
+
+Pagehead components get `COMMON` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+## Component props
+
+| Name | Type   | Default | Description                         |
+| :--- | :----- | :-----: | :---------------------------------- |
+| as   | String |  `div`  | Sets the HTML tag for the component |