@primer/components 31.0.1 → 31.0.2-rc.1e80de40

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,99 @@
+---
+title: ActionList
+status: Alpha
+source: https://github.com/primer/react/tree/main/src/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', trailingVisual: '⌘R'},
+    {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', trailingVisual: ArrowRightIcon}
+  ]}
+/>
+```
+
+## Example with custom item renderer
+
+```jsx
+<ActionList
+  items={[
+    {
+      text: 'Vanilla link',
+      renderItem: props => <ActionList.Item as="a" href="/about" {...props} />
+    },
+    {
+      text: 'React Router link',
+      renderItem: props => <ActionList.Item as={ReactRouterLikeLink} to="/about" {...props} />
+    },
+    {
+      text: 'NextJS style',
+      renderItem: props => (
+        <NextJSLikeLink href="/about">
+          <ActionList.Item as="a" {...props} />
+        </NextJSLikeLink>
+      )
+    }
+  ]}
+/>
+```
+
+## Props
+
+| Name             | Type                                                                                                                                              |      Default      | Description                                                                                                                                             |
+| :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| items            | `(ItemProps & Omit<React.ComponentPropsWithoutRef<'div'>, keyof ItemProps>) \| ((Partial<ItemProps> & {renderItem: RenderItemFn}) & {key?: Key})` |    `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>
+```