@primer/components 29.1.1 → 30.0.0-rc.9be85598

package/docs/.gitignore

@@ -0,0 +1,91 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# TypeScript v1 declaration files
+typings/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variables file
+.env
+.env.test
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+
+# next.js build output
+.next
+
+# nuxt.js build output
+.nuxt
+
+# vuepress build output
+.vuepress/dist
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# Gatsby
+public/

package/docs/components/PropsList.js

@@ -0,0 +1,5 @@
+import React from 'react'
+
+const PropsList = ({systemProps}) => <div>{systemProps.propNames.join(', ')}</div>
+
+export default PropsList

package/docs/components/State.js

@@ -0,0 +1,9 @@
+import React from 'react'
+
+const State = props => {
+  const result = React.useState(props.default)
+
+  return props.children(result)
+}
+
+export default State

package/docs/components/constants.js

@@ -0,0 +1,34 @@
+import {theme} from '@primer/components'
+import systemPropTypes from '@styled-system/prop-types'
+import themeGet from '@styled-system/theme-get'
+import * as styledSystem from 'styled-system'
+
+const {get: getKey, compose, system} = styledSystem
+
+export const get = key => themeGet(key, getKey(theme, key))
+
+const whiteSpace = system({
+  whiteSpace: {
+    property: 'whiteSpace',
+    cssProperty: 'whiteSpace'
+  }
+})
+
+export const TYPOGRAPHY = compose(styledSystem.typography, whiteSpace)
+
+export const COMMON = compose(styledSystem.space, styledSystem.color, styledSystem.display)
+
+export const BORDER = compose(styledSystem.border, styledSystem.shadow)
+
+// these are 1:1 with styled-system's API now,
+// so you could consider dropping the abstraction
+export const LAYOUT = styledSystem.layout
+export const POSITION = styledSystem.position
+export const FLEX = styledSystem.flexbox
+export const GRID = styledSystem.grid
+
+TYPOGRAPHY.propTypes = systemPropTypes.typography
+LAYOUT.propTypes = systemPropTypes.layout
+POSITION.propTypes = systemPropTypes.position
+FLEX.propTypes = systemPropTypes.flexbox
+GRID.propTypes = systemPropTypes.grid

package/docs/components/index.js

@@ -0,0 +1,2 @@
+export {default as PropsList} from './PropsList'
+export {COMMON, LAYOUT, BORDER, TYPOGRAPHY, FLEX, POSITION, GRID} from './constants'

package/docs/content/ActionList.mdx

@@ -0,0 +1,72 @@
+---
+title: ActionList
+---
+
+An `ActionList` is a list of items which can be activated or selected. `ActionList` is the base component for many of our menu-type components, including `DropdownMenu` and `ActionMenu`.
+
+## Minimal example
+
+```jsx live
+<ActionList
+  items={[
+    {text: 'New file'},
+    ActionList.Divider,
+    {text: 'Copy link'},
+    {text: 'Edit file'},
+    {text: 'Delete file', variant: 'danger'}
+  ]}
+/>
+```
+
+## Example with grouped items
+
+```jsx live
+<ActionList
+  groupMetadata={[
+    {groupId: '0'},
+    {groupId: '1', header: {title: 'Live query', variant: 'subtle'}},
+    {groupId: '2', header: {title: 'Layout', variant: 'subtle'}},
+    {groupId: '3'},
+    {groupId: '4'}
+  ]}
+  items={[
+    {key: '1', leadingVisual: TypographyIcon, text: 'Rename', groupId: '0'},
+    {key: '2', leadingVisual: VersionsIcon, text: 'Duplicate', groupId: '0'},
+    {key: '3', leadingVisual: SearchIcon, text: 'repo:github/github', groupId: '1'},
+    {
+      key: '4',
+      leadingVisual: NoteIcon,
+      text: 'Table',
+      description: 'Information-dense table optimized for operations across teams',
+      descriptionVariant: 'block',
+      groupId: '2'
+    },
+    {
+      key: '5',
+      leadingVisual: ProjectIcon,
+      text: 'Board',
+      description: 'Kanban-style board focused on visual states',
+      descriptionVariant: 'block',
+      groupId: '2'
+    },
+    {
+      key: '6',
+      leadingVisual: FilterIcon,
+      text: 'Save sort and filters to current view',
+      disabled: true,
+      groupId: '3'
+    },
+    {key: '7', leadingVisual: FilterIcon, text: 'Save sort and filters to new view', groupId: '3'},
+    {key: '8', leadingVisual: GearIcon, text: 'View settings', groupId: '4'}
+  ]}
+/>
+```
+
+## Component props
+
+| Name             | Type                                |      Default      | Description                                                                                                                                             |
+| :--------------- | :---------------------------------- | :---------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| items            | `ItemProps[]`                       |    `undefined`    | Required. A list of item objects conforming to the `ActionList.Item` props interface.                                                                   |
+| renderItem       | `(props: ItemProps) => JSX.Element` | `ActionList.Item` | Optional. If defined, each item in `items` will be passed to this function, allowing for `ActionList`-wide custom item rendering.                       |
+| groupMetadata    | `GroupProps[]`                      |    `undefined`    | Optional. If defined, `ActionList` will group `items` into `ActionList.Group`s separated by `ActionList.Divider` according to their `groupId` property. |
+| showItemDividers | `boolean`                           |      `false`      | Optional. If `true` dividers will be displayed above each `ActionList.Item` which does not follow an `ActionList.Header` or `ActionList.Divider`        |

package/docs/content/ActionMenu.mdx

@@ -0,0 +1,80 @@
+---
+title: ActionMenu
+---
+
+An `ActionMenu` is an ActionList-based component for creating a menu of actions that expands through a trigger button.
+
+## Default example
+
+```jsx live
+<ActionMenu
+  anchorContent="Menu"
+  onAction={({text}) => console.log(text)}
+  items={[
+    {text: 'New file', key: 'new-file'},
+    ActionMenu.Divider,
+    {text: 'Copy link', key: 'copy-link'},
+    {text: 'Edit file', key: 'edit-file'},
+    {text: 'Delete file', variant: 'danger', key: 'delete-file'}
+  ]}
+/>
+```
+
+## Example with grouped items
+
+```jsx live
+<ActionMenu
+  anchorContent="Menu"
+  onAction={({text}) => console.log(text)}
+  groupMetadata={[
+    {groupId: '0'},
+    {groupId: '1', header: {title: 'Live query', variant: 'subtle'}},
+    {groupId: '2', header: {title: 'Layout', variant: 'subtle'}},
+    {groupId: '3'},
+    {groupId: '4'}
+  ]}
+  items={[
+    {key: '1', leadingVisual: TypographyIcon, text: 'Rename', groupId: '0'},
+    {key: '2', leadingVisual: VersionsIcon, text: 'Duplicate', groupId: '0'},
+    {key: '3', leadingVisual: SearchIcon, text: 'repo:github/github', groupId: '1'},
+    {
+      key: '4',
+      leadingVisual: NoteIcon,
+      text: 'Table',
+      description: 'Information-dense table optimized for operations across teams',
+      descriptionVariant: 'block',
+      groupId: '2'
+    },
+    {
+      key: '5',
+      leadingVisual: ProjectIcon,
+      text: 'Board',
+      description: 'Kanban-style board focused on visual states',
+      descriptionVariant: 'block',
+      groupId: '2'
+    },
+    {
+      key: '6',
+      leadingVisual: FilterIcon,
+      text: 'Save sort and filters to current view',
+      disabled: true,
+      groupId: '3'
+    },
+    {key: '7', leadingVisual: FilterIcon, text: 'Save sort and filters to new view', groupId: '3'},
+    {key: '8', leadingVisual: GearIcon, text: 'View settings', groupId: '4'}
+  ]}
+/>
+```
+
+## Component props
+
+| Name          | Type                                  |      Default      | Description                                                                                                                                                                                        |
+| :------------ | :------------------------------------ | :---------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| items         | `ItemProps[]`                         |    `undefined`    | Required. A list of item objects conforming to the `ActionList.Item` props interface.                                                                                                              |
+| renderItem    | `(props: ItemProps) => JSX.Element`   | `ActionList.Item` | Optional. If defined, each item in `items` will be passed to this function, allowing for `ActionList`-wide custom item rendering.                                                                  |
+| groupMetadata | `GroupProps[]`                        |    `undefined`    | Optional. If defined, `ActionList` will group `items` into `ActionList.Group`s separated by `ActionList.Divider` according to their `groupId` property.                                            |
+| renderAnchor  | `(props: ButtonProps) => JSX.Element` |     `Button`      | Optional. If defined, provided component will be used to render the menu anchor. Will receive the selected `Item` text as `children` prop when an item is activated.                               |
+| anchorContent | React.ReactNode                       |    `undefined`    | Optional. If defined, it will be passed to the trigger as the elements child.                                                                                                                      |
+| onAction      | (props: ItemProps) => void            |    `undefined`    | Optional. If defined, this function will be called when a menu item is activated either by a click or a keyboard press.                                                                            |
+| open          | boolean                               |    `undefined`    | Optional. If defined, ActionMenu will use this to control the open/closed state of the Overlay instead of controlling the state internally. Should be used in conjunction with the `setOpen` prop. |
+| setOpen       | (state: boolean) => void              |    `undefined`    | Optional. If defined, ActionMenu will use this to control the open/closed state of the Overlay instead of controlling the state internally. Should be used in conjunction with the `open` prop.    |

package/docs/content/AnchoredOverlay.mdx

@@ -0,0 +1,37 @@
+---
+title: AnchoredOverlay
+status: Alpha
+---
+
+An `AnchoredOverlay` provides an anchor that will open a floating overlay positioned relative to the anchor.
+The overlay can be opened and navigated using keyboard or mouse.
+
+See also [Overlay positioning](/Overlay#positioning).
+
+## Example
+
+```jsx live
+<State default={false}>
+  {([isOpen, setIsOpen]) => {
+    const openOverlay = React.useCallback(() => setIsOpen(true), [setIsOpen])
+    const closeOverlay = React.useCallback(() => setIsOpen(false), [setIsOpen])
+    return (
+      <AnchoredOverlay
+        renderAnchor={anchorProps => <DropdownButton {...anchorProps}>Click me to open</DropdownButton>}
+        open={isOpen}
+        onOpen={openOverlay}
+        onClose={closeOverlay}
+      >
+        <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
+          </p>
+          <Button mb={1}>Button 1</Button>
+          <Button mb={1}>Button 2</Button>
+          <Button>Button 3</Button>
+        </Box>
+      </AnchoredOverlay>
+    )
+  }}
+</State>
+```

package/docs/content/Avatar.mdx

@@ -0,0 +1,33 @@
+---
+title: Avatar
+componentId: avatar
+source: https://github.com/primer/react/blob/main/src/Avatar.tsx
+---
+
+import {Props} from '../src/props'
+import {Avatar} from '@primer/components'
+
+```jsx live
+<Avatar src="https://avatars.githubusercontent.com/primer" />
+```
+
+## Props
+
+<Props of={Avatar} />
+
+## Examples
+
+### Square
+
+```jsx live
+<Avatar square src="https://avatars.githubusercontent.com/primer" />
+```
+
+### AvatarPair
+
+```jsx live
+<AvatarPair>
+  <Avatar src="https://avatars.githubusercontent.com/github" />
+  <Avatar src="https://avatars.githubusercontent.com/primer" />
+</AvatarPair>
+```

package/docs/content/AvatarStack.mdx

@@ -0,0 +1,43 @@
+---
+title: AvatarStack
+---
+
+AvatarStack is used to display more than one Avatar in an inline stack.
+
+### Default example
+
+```jsx live
+<AvatarStack>
+  <Avatar alt="Primer" src="https://avatars.githubusercontent.com/primer" />
+  <Avatar alt="GitHub" src="https://avatars.githubusercontent.com/github" />
+  <Avatar alt="Atom" src="https://avatars.githubusercontent.com/atom" />
+  <Avatar alt="Desktop" src="https://avatars.githubusercontent.com/desktop" />
+</AvatarStack>
+```
+
+### Right aligned
+
+```jsx live
+<AvatarStack alignRight>
+  <Avatar alt="Primer" src="https://avatars.githubusercontent.com/primer" />
+  <Avatar alt="GitHub" src="https://avatars.githubusercontent.com/github" />
+  <Avatar alt="Atom" src="https://avatars.githubusercontent.com/atom" />
+  <Avatar alt="Desktop" src="https://avatars.githubusercontent.com/desktop" />
+</AvatarStack>
+```
+
+## System props
+
+<Note variant="warning">
+
+System props are deprecated in all components except [Box](/Box). Please use the [`sx` prop](/overriding-styles) instead.
+
+</Note>
+
+AvatarStack components get `COMMON` system props, AvatarStack.Item components do not get any system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+## AvatarStack Component props
+
+| Name       | Type    | Default | Description                       |
+| :--------- | :------ | :-----: | :-------------------------------- |
+| alignRight | Boolean |         | Creates right aligned AvatarStack |

package/docs/content/BorderBox.md

@@ -0,0 +1,46 @@
+---
+title: BorderBox
+status: Deprecated
+---
+
+BorderBox is a Box component with a border. When no `borderColor` is present, the component defaults to a primary border.
+
+## Deprecation
+
+Use [Box](/Box) instead.
+
+**Before**
+
+```jsx
+<BorderBox>Item 1</BorderBox>
+```
+
+**After**
+
+```jsx
+<Box borderWidth="1px" borderStyle="solid" borderColor="border.default" borderRadius={2}>
+  Item 1
+</Box>
+```
+
+## Default example
+
+```jsx live
+<BorderBox>This is a BorderBox</BorderBox>
+```
+
+Note that `BorderBox` has default props set for `borderWidth`, `borderStyle`, and `borderColor`. This means that you cannot use `border={0} borderBottom={1}` or similar patterns; instead, use individual properties like `borderWidth={0} borderBottomWidth={1}`.
+
+## System props
+
+BorderBox components get `COMMON`, `LAYOUT`, `BORDER`, and `FLEX` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+## Component props
+
+| Prop name    | Type             |            Default            | Description                                                   |
+| :----------- | :--------------- | :---------------------------: | :------------------------------------------------------------ |
+| borderWidth  | String           |             '1px'             | Sets the border, use theme values or provide your own.        |
+| borderStyle  | String           |            'solid'            | Sets the border style, use theme values or provide your own.  |
+| borderColor  | String           | 'border.primary' (from theme) | Sets the border color, use theme values or provide your own.  |
+| borderRadius | String or Number |        2 (from theme)         | Sets the border radius, use theme values or provide your own. |
+| boxShadow    | String           |                               | Sets box shadow, use theme values or provide your own.        |

package/docs/content/Box.md

@@ -0,0 +1,74 @@
+---
+title: Box
+description: A low-level utility component that accepts styled system props to enable custom theme-aware styling
+source: https://github.com/primer/react/blob/main/src/Box.tsx
+---
+
+import {Props} from '../src/props'
+import {Box} from '@primer/components'
+
+```jsx live
+<Box color="fg.muted" bg="canvas.subtle" p={3}>
+  Hello
+</Box>
+```
+
+## Props
+
+<Props of={Box} />
+
+Box also accepts all [styled system props](https://styled-system.com/table/).
+
+## Examples
+
+### Border on all sides
+
+```jsx live
+<Box borderColor="border.default" borderWidth={1} borderStyle="solid" p={3}>
+  Hello
+</Box>
+```
+
+### Border on one side
+
+```jsx live
+<Box borderColor="border.default" 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.default" borderWidth={1} borderStyle="solid">
+    1
+  </Box>
+  <Box flexGrow={1} p={3} borderColor="border.default" borderWidth={1} borderStyle="solid">
+    2
+  </Box>
+  <Box p={3} borderColor="border.default" 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.default" borderWidth={1} borderStyle="solid">
+    1
+  </Box>
+  <Box p={3} borderColor="border.default" borderWidth={1} borderStyle="solid">
+    2
+  </Box>
+  <Box p={3} borderColor="border.default" borderWidth={1} borderStyle="solid">
+    3
+  </Box>
+</Box>
+```

package/docs/content/BranchName.md

@@ -0,0 +1,18 @@
+---
+title: BranchName
+---
+
+BranchName is a label-type component rendered as an `<a>` tag by default with monospace font.
+
+## Default example
+
+```jsx live live
+<BranchName>a_new_feature_branch</BranchName>
+```
+
+## Component props
+
+| Name | Type   | Default | Description                         |
+| :--- | :----- | :-----: | :---------------------------------- |
+| as   | String |  `<a>`  | sets the HTML tag for the component |
+| href | String |         | a URL to link the component to      |

package/docs/content/Breadcrumbs.md

@@ -0,0 +1,52 @@
+---
+title: Breadcrumbs
+status: Alpha
+source: https://github.com/primer/react/blob/main/src/Breadcrumbs.tsx
+---
+
+Breadcrumbs are used to show taxonomical context on pages that are many levels deep in a site’s hierarchy. Breadcrumbs show and link to parent, grandparent, and sometimes great-grandparent pages. Breadcrumbs are most appropriate on pages that:
+
+- Are many levels deep on a site
+- Do not have a section-level navigation
+- May need the ability to quickly go back to the previous (parent) page
+
+To use Breadcrumbs with [react-router](https://github.com/ReactTraining/react-router) or
+[react-router-dom](https://www.npmjs.com/package/react-router-dom), pass
+`as={NavLink}` and omit the `selected` prop.
+This ensures that the NavLink gets `activeClassName='selected'`
+
+## Default example
+
+```jsx live
+<Breadcrumbs>
+  <Breadcrumbs.Item href="/">Home</Breadcrumbs.Item>
+  <Breadcrumbs.Item href="/about">About</Breadcrumbs.Item>
+  <Breadcrumbs.Item href="/about/team" selected>
+    Team
+  </Breadcrumbs.Item>
+</Breadcrumbs>
+```
+
+## System props
+
+<Note variant="warning">
+
+System props are deprecated in all components except [Box](/Box). Please use the [`sx` prop](/overriding-styles) instead.
+
+</Note>
+
+Breadcrumbs and Breadcrumbs.Item components get `COMMON` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+## Component props
+
+### Breadcrumbs
+
+The `Breadcrumbs` component does not receive any additional props besides `COMMON` system props.
+
+### Breadcrumbs.Item
+
+| Prop name | Type    | Default | Description                                      |
+| :-------- | :------ | :-----: | :----------------------------------------------- |
+| as        | String  |   `a`   | Sets the HTML tag for the component              |
+| href      | String  |         | URL to be used for the Link                      |
+| selected  | Boolean |  false  | Used to style the link as selected or unselected |

package/docs/content/Buttons.md

@@ -0,0 +1,56 @@
+---
+title: Buttons
+---
+
+`Button` is used for actions, like in forms, while `Link` is used for destinations, or moving from one page to another.
+
+In special cases where you'd like to use a `<a>` styled like a Button, use `<Button as='a'>` and provide an `href`.
+
+To create a button group, wrap `Button` elements in the `ButtonGroup` element. `ButtonGroup` gets the same props as `Box`.
+
+## Default examples
+
+```jsx live
+<>
+  <Button>Button</Button>
+  <ButtonDanger>Button Danger</ButtonDanger>
+  <ButtonOutline>Button Outline</ButtonOutline>
+  <ButtonPrimary>Button Primary</ButtonPrimary>
+  <ButtonInvisible>Button Invisible</ButtonInvisible>
+  <ButtonClose onClick={() => window.alert('button clicked')}/>
+
+  <ButtonGroup display='block' my={2}>
+    <Button>Button</Button>
+    <Button>Button</Button>
+    <Button>Button</Button>
+  </ButtonGroup>
+
+  <ButtonTableList>Button Table List </ButtonTableList>
+</>
+```
+
+## System props
+
+<Note variant="warning">
+
+System props are deprecated in all components except [Box](/Box). Please use the [`sx` prop](/overriding-styles) instead.
+
+</Note>
+
+`Button` and `ButtonGroup` components get `COMMON` and `LAYOUT` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+## Component props
+
+Native `<button>` HTML attributes are forwarded to the underlying React `button` component and are not listed below.
+
+### Button
+
+| Prop name | Type             | Default  | Description                                                                                                                 |
+| :-------- | :--------------- | :------: | :-------------------------------------------------------------------------------------------------------------------------- |
+| as        | String           | `button` | sets the HTML tag for the component                                                                                         |
+| fontSize  | Number or String |          | explicitly sets the font size for the Button text; overrides any value for the `variant` prop                               |
+| variant   | String           | 'medium' | a value of `small`, `medium`, or `large` results in smaller or larger Button text size; no effect if `fontSize` prop is set |
+
+### ButtonGroup
+
+`ButtonGroup` has access to the same props as `Box`