diff --git a/.changeset/tall-moles-smoke.md b/.changeset/tall-moles-smoke.md new file mode 100644 index 00000000000..8c37de5742a --- /dev/null +++ b/.changeset/tall-moles-smoke.md @@ -0,0 +1,5 @@ +--- +'@primer/components': minor +--- + +Add experimental `ActionList` with composable API diff --git a/docs/content/ActionList2.mdx b/docs/content/ActionList2.mdx new file mode 100644 index 00000000000..76bb9b39703 --- /dev/null +++ b/docs/content/ActionList2.mdx @@ -0,0 +1,354 @@ +--- +title: ActionList +status: Alpha +source: https://github.com/primer/react/tree/main/src/ActionList2 +storybook: '/react/storybook?path=/story/composite-components-actionlist2' +description: 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. +--- + +import {BorderBox, Avatar} from '@primer/components' +import {ActionList} from '@primer/components/unreleased' +import {Props} from '../src/props' + +import {ImageContainer} from '@primer/gatsby-theme-doctocat' +import {LinkIcon, AlertIcon, ArrowRightIcon} from '@primer/octicons-react' + +
+ + + + + + + + github.com/primer + + A React implementation of GitHub's Primer Design System + + + + + + + mona + Monalisa Octocat + + + + + + 4 vulnerabilities + + + + + + + +
+ +```js +import {ActionList} from '@primer/components/unreleased' +``` + +
+ +## Examples + +## Minimal example + +```javascript live noinline +const {ActionList} = unreleased + +render( + + New file + Copy link + Edit file + + Delete file + +) +``` + +
+ +## With Leading Visual + +Leading visuals are optional and appear at the start of an item. They can be octicons, avatars, and other custom visuals that fit a small area. + + +```javascript live noinline +const {ActionList} = unreleased + +render( + + + + github.com/primer + + + + 4 vulnerabilities + + + + mona + + +) +``` + +
+ +## With Trailing Visual + +Trailing visual and trailing text can display auxiliary information. They're placed at the right of the item, and can denote status, keyboard shortcuts, or be used to set expectations about what the action does. + +```javascript live noinline +const {ActionList} = unreleased + +render( + + + New file + ⌘ + N + + + Copy link + ⌘ + C + + + Edit file + ⌘ + E + + + Delete file + ⌫ + + +) +``` + +
+ +## With Description and Dividers + +Item dividers allow users to parse heavier amounts of information. They're placed between items and are useful in complex lists, particularly when descriptions or multi-line text is present. + +```javascript live noinline +const {ActionList} = unreleased + +render( + + + + + + mona + Monalisa Octocat + + + + + + hubot + Hubot + + + + + + primer-css + GitHub Design Systems Bot + + +) +``` + +## With Links + +When you want to add links to the List instead of actions, use `ActionList.LinkItem` + + +```javascript live noinline +const {ActionList} = unreleased + +render( + + + + + + github/primer + + + + + + MIT License + + + + + + 1.4k stars + + +) +``` + +
+ +## With Groups + +```javascript live noinline +const {ActionList} = unreleased + +const SelectFields = () => { + const [options, setOptions] = React.useState([ + {text: 'Status', selected: true}, + {text: 'Stage', selected: true}, + {text: 'Assignee', selected: true}, + {text: 'Team', selected: true}, + {text: 'Estimate', selected: false}, + {text: 'Due Date', selected: false} + ]) + + const visibleOptions = options.filter(option => option.selected) + const hiddenOptions = options.filter(option => !option.selected) + + const toggle = text => { + setOptions( + options.map(option => { + if (option.text === text) option.selected = !option.selected + return option + }) + ) + } + + return ( + + + {visibleOptions.map(option => ( + toggle(option.text)}> + {option.text} + + ))} + + + {hiddenOptions.map((option, index) => ( + toggle(option.text)}> + {option.text} + + ))} + {hiddenOptions.length === 0 && No hidden fields} + + + ) +} + +render() +``` + +
+ +## Props / API reference + +## ActionList + +| Name | Type | Default | Description | +| :--------------- | :------------------------------------------------------------------------------------------------ | :-----: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| children\* | `ActionList.Item[]` or ActionList.LinkItem[] or `ActionList.Group[]` | - | Required. | +| variant | `'inset'` or `'full'` | 'inset' | Optional. Usage is discretionary, `inset` children are offset (vertically and horizontally) from `List`’s edges, `full` children are flush (vertically and horizontally) with `List` edges | +| selectionVariant | `'single'` or `'multiple'` | - | Optional. Whether multiple Items or a single Item can be selected. | +| showDivider | boolean | false | Optional. Display a divider above each `Item` in this `List` when it does not follow a `Header` or `Divider`. | +| sx | sxProp | - | Optional. See guide to [Overriding styles](/overriding-styles) | +| role | [AriaRole](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques#roles) | - | Optional. The ARIA role describing the function of `List` component. `listbox` or `menu` are a common values. | + +
+ +## ActionList.Item + +| Name | Type | Default | Description | +| :--------- | :------------------------------------------------------------------------------------------------------------ | :---------: | :----------------------------------------------------------------------------------------------- | +| children\* | one of [`React.ReactNode`, `ActionList.LeadingVisual`, `ActionList.Description`, `ActionList.TrailingVisual`] | - | Required. | +| variant | `'default'` or `'danger'` | `'default'` | Optional. variant="danger" creates a destructive action `Item`. | +| onSelect | Function | - | Optional. Callback that will trigger both on click selection and keyboard selection. | +| selected | boolean | false | Optional. For `Item`s which can be selected, whether the `Item` is currently selected. | +| disabled | boolean | false | Optional. Items that are disabled can not be clicked, selected, or navigated through. | +| role | [AriaRole](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques#roles) | - | Optional. The ARIA role describing the function of `Item` component. `option` is a common value. | +| sx | sxProp | - | Optional. See guide to [Overriding styles](/overriding-styles) | + +
+ +## ActionList.LinkItem + +| Name | Type | Default | Description | +| :-------------------------------------------------- | :------------------------------------------------------------------------------------------------------------ | :-----: | :------------------------------------------------------------- | +| children\* | one of [`React.ReactNode`, `ActionList.LeadingVisual`, `ActionList.Description`, `ActionList.TrailingVisual`] | - | Required. | +| sx | sxProp | - | Optional. See guide to [Overriding styles](/overriding-styles) | +| + AnchorHTMLAttributes like href, target, rel, etc. | | | | + +
+ +## ActionList.LeadingVisual + +| Name | Type | Default | Description | +| :--------- | :------------------ | :-----: | :------------------------------------------------------------- | +| children\* | `React.ReactNode` - | - | Required. Icon (or similar) positioned before `Item` text. | +| sx | sxProp | - | Optional. See guide to [Overriding styles](/overriding-styles) | + +## ActionList.TrailingVisual + +| Name | Type | Default | Description | +| :--------- | :------------------ | :-----: | :------------------------------------------------------------- | +| children\* | `React.ReactNode` - | - | Required. Visual positioned after `Item` text. | +| sx | sxProp | - | Optional. See guide to [Overriding styles](/overriding-styles) | + +
+ +## ActionList.Description + +| Name | Type | Default | Description | +| :--------- | :---------------------- | :--------: | :-------------------------------------------------------------------------------------------------------------------------------- | +| children\* | `React.ReactNode` - | - | Required. Visual positioned after `Item` text. | +| variant | `'inline'` or `'block'` | `'inline'` | Optional. `"inline"` secondary text is positioned beside primary text. `"block"` secondary text is positioned below primary text. | +| sx | sxProp | - | Optional. See guide to [Overriding styles](/overriding-styles) | + +
+ +## ActionList.Group + +| Name | Type | Default | Description | +| :--------------- | :------------------------------------------- | :--------: | :--------------------------------------------------------------------------------------------------------------------------------------- | +| children\* | `ActionList.Item[] or ActionList.LinkItem[]` | - | Required. | +| title | string | - | Optional. Primary text which names a `Group` | +| auxiliaryText | string | - | Optional. Secondary text which provides additional information about a `Group`. | +| variant | `'filled'` or `'subtle'` | `'subtle'` | Optional. `"filled"` - Superimposed on a background, offset from nearby content, `"subtle"` - Relatively less offset from nearby content | +| selectionVariant | `'single'` or `'multiple'` or `false` | - | Optional. Set `selectionVariant` at the group level | + +
+ +## Further reading + +[Interface guidelines: Action List](https://primer.style/design/components/action-list) + +
+ +## Related components + +- [ActionMenu](/ActionMenu) +- [SelectPanel](/SelectPanel) + +
diff --git a/docs/src/@primer/gatsby-theme-doctocat/live-code-scope.js b/docs/src/@primer/gatsby-theme-doctocat/live-code-scope.js index c5e30f6a6d7..ad451ada796 100644 --- a/docs/src/@primer/gatsby-theme-doctocat/live-code-scope.js +++ b/docs/src/@primer/gatsby-theme-doctocat/live-code-scope.js @@ -1,4 +1,6 @@ +import React from 'react' import * as primerComponents from '@primer/components' +import * as unreleased from '@primer/components/unreleased' import * as doctocatComponents from '@primer/gatsby-theme-doctocat' import { CheckIcon, @@ -18,6 +20,10 @@ import { GearIcon, TypographyIcon, VersionsIcon, + LinkIcon, + LawIcon, + StarIcon, + AlertIcon, ArrowRightIcon } from '@primer/octicons-react' import State from '../../../components/State' @@ -26,9 +32,16 @@ import {AnchoredOverlay} from '../../../../src/AnchoredOverlay' import {ConfirmationDialog, useConfirm} from '../../../../src/Dialog/ConfirmationDialog' import {SelectPanel} from '../../../../src/SelectPanel/SelectPanel' +const ReactRouterLink = ({to, ...props}) => { + // eslint-disable-next-line jsx-a11y/anchor-has-content + return +} + export default { ...doctocatComponents, ...primerComponents, + unreleased, + ReactRouterLink, State, CheckIcon, SearchIcon, @@ -47,6 +60,10 @@ export default { GearIcon, TypographyIcon, VersionsIcon, + LinkIcon, + LawIcon, + StarIcon, + AlertIcon, ArrowRightIcon, Dialog2, ConfirmationDialog, diff --git a/package-lock.json b/package-lock.json index e05c0f786c8..98ab3b1563e 100644 --- a/package-lock.json +++ b/package-lock.json @@ -10,7 +10,7 @@ "license": "MIT", "dependencies": { "@primer/octicons-react": "^13.0.0", - "@primer/primitives": "5.1.0", + "@primer/primitives": "6.1.0", "@radix-ui/react-polymorphic": "0.0.14", "@react-aria/ssr": "3.1.0", "@styled-system/css": "5.1.5", @@ -90,6 +90,8 @@ "lodash.isobject": "3.0.2", "prettier": "2.3.2", "react": "17.0.2", + "react-dnd": "14.0.4", + "react-dnd-html5-backend": "14.0.2", "react-dom": "17.0.2", "react-test-renderer": "17.0.2", "rollup": "2.56.3", @@ -7559,9 +7561,9 @@ } }, "node_modules/@primer/primitives": { - "version": "5.1.0", - "resolved": "https://registry.npmjs.org/@primer/primitives/-/primitives-5.1.0.tgz", - "integrity": "sha512-pW8DIh6rZV0/R7lxHnVRJ/tdN4kDVSpAtdcCecxKsvtgK5d9haekt3ERpM6i93xKwB5CJYy9ouuC9C0UqWPI0A==" + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/@primer/primitives/-/primitives-6.1.0.tgz", + "integrity": "sha512-gwSVf5rVf2CMa/bU3/47LZosDHNfODMRJfKi7uJOqHWABVNl6Lf+thDM7Jb8tS9sEQQsUnrLDiGNjCScS81IXA==" }, "node_modules/@radix-ui/react-polymorphic": { "version": "0.0.14", @@ -7598,6 +7600,24 @@ "react": "^16.8.0 || ^17.0.0-rc.1" } }, + "node_modules/@react-dnd/asap": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/@react-dnd/asap/-/asap-4.0.0.tgz", + "integrity": "sha512-0XhqJSc6pPoNnf8DhdsPHtUhRzZALVzYMTzRwV4VI6DJNJ/5xxfL9OQUwb8IH5/2x7lSf7nAZrnzUD+16VyOVQ==", + "dev": true + }, + "node_modules/@react-dnd/invariant": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/@react-dnd/invariant/-/invariant-2.0.0.tgz", + "integrity": "sha512-xL4RCQBCBDJ+GRwKTFhGUW8GXa4yoDfJrPbLblc3U09ciS+9ZJXJ3Qrcs/x2IODOdIE5kQxvMmE2UKyqUictUw==", + "dev": true + }, + "node_modules/@react-dnd/shallowequal": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/@react-dnd/shallowequal/-/shallowequal-2.0.0.tgz", + "integrity": "sha512-Pc/AFTdwZwEKJxFJvlxrSmGe/di+aAOBn60sremrpLo6VI/6cmiUYNNwlI5KNYttg7uypzA3ILPMPgxB2GYZEg==", + "dev": true + }, "node_modules/@rollup/plugin-commonjs": { "version": "19.0.2", "resolved": "https://registry.npmjs.org/@rollup/plugin-commonjs/-/plugin-commonjs-19.0.2.tgz", @@ -17234,6 +17254,17 @@ "integrity": "sha1-44Mx8IRLukm5qctxx3FYWqsbxlo=", "dev": true }, + "node_modules/dnd-core": { + "version": "14.0.1", + "resolved": "https://registry.npmjs.org/dnd-core/-/dnd-core-14.0.1.tgz", + "integrity": "sha512-+PVS2VPTgKFPYWo3vAFEA8WPbTf7/xo43TifH9G8S1KqnrQu0o77A3unrF5yOugy4mIz7K5wAVFHUcha7wsz6A==", + "dev": true, + "dependencies": { + "@react-dnd/asap": "^4.0.0", + "@react-dnd/invariant": "^2.0.0", + "redux": "^4.1.1" + } + }, "node_modules/doctrine": { "version": "3.0.0", "resolved": "https://registry.npmjs.org/doctrine/-/doctrine-3.0.0.tgz", @@ -31528,6 +31559,45 @@ "node": ">= 8" } }, + "node_modules/react-dnd": { + "version": "14.0.4", + "resolved": "https://registry.npmjs.org/react-dnd/-/react-dnd-14.0.4.tgz", + "integrity": "sha512-AFJJXzUIWp5WAhgvI85ESkDCawM0lhoVvfo/lrseLXwFdH3kEO3v8I2C81QPqBW2UEyJBIPStOhPMGYGFtq/bg==", + "dev": true, + "dependencies": { + "@react-dnd/invariant": "^2.0.0", + "@react-dnd/shallowequal": "^2.0.0", + "dnd-core": "14.0.1", + "fast-deep-equal": "^3.1.3", + "hoist-non-react-statics": "^3.3.2" + }, + "peerDependencies": { + "@types/hoist-non-react-statics": ">= 3.3.1", + "@types/node": ">= 12", + "@types/react": ">= 16", + "react": ">= 16.14" + }, + "peerDependenciesMeta": { + "@types/hoist-non-react-statics": { + "optional": true + }, + "@types/node": { + "optional": true + }, + "@types/react": { + "optional": true + } + } + }, + "node_modules/react-dnd-html5-backend": { + "version": "14.0.2", + "resolved": "https://registry.npmjs.org/react-dnd-html5-backend/-/react-dnd-html5-backend-14.0.2.tgz", + "integrity": "sha512-QgN6rYrOm4UUj6tIvN8ovImu6uP48xBXF2rzVsp6tvj6d5XQ7OjHI4SJ/ZgGobOneRAU3WCX4f8DGCYx0tuhlw==", + "dev": true, + "dependencies": { + "dnd-core": "14.0.1" + } + }, "node_modules/react-docgen": { "version": "5.4.0", "resolved": "https://registry.npmjs.org/react-docgen/-/react-docgen-5.4.0.tgz", @@ -31956,6 +32026,15 @@ "node": ">=8" } }, + "node_modules/redux": { + "version": "4.1.2", + "resolved": "https://registry.npmjs.org/redux/-/redux-4.1.2.tgz", + "integrity": "sha512-SH8PglcebESbd/shgf6mii6EIoRM0zrQyjcuQ+ojmfxjTtE0z9Y8pa62iA/OJ58qjP6j27uyW4kUF4jl/jd6sw==", + "dev": true, + "dependencies": { + "@babel/runtime": "^7.9.2" + } + }, "node_modules/refractor": { "version": "3.5.0", "resolved": "https://registry.npmjs.org/refractor/-/refractor-3.5.0.tgz", @@ -43272,9 +43351,9 @@ "requires": {} }, "@primer/primitives": { - "version": "5.1.0", - "resolved": "https://registry.npmjs.org/@primer/primitives/-/primitives-5.1.0.tgz", - "integrity": "sha512-pW8DIh6rZV0/R7lxHnVRJ/tdN4kDVSpAtdcCecxKsvtgK5d9haekt3ERpM6i93xKwB5CJYy9ouuC9C0UqWPI0A==" + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/@primer/primitives/-/primitives-6.1.0.tgz", + "integrity": "sha512-gwSVf5rVf2CMa/bU3/47LZosDHNfODMRJfKi7uJOqHWABVNl6Lf+thDM7Jb8tS9sEQQsUnrLDiGNjCScS81IXA==" }, "@radix-ui/react-polymorphic": { "version": "0.0.14", @@ -43302,6 +43381,24 @@ "@babel/runtime": "^7.6.2" } }, + "@react-dnd/asap": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/@react-dnd/asap/-/asap-4.0.0.tgz", + "integrity": "sha512-0XhqJSc6pPoNnf8DhdsPHtUhRzZALVzYMTzRwV4VI6DJNJ/5xxfL9OQUwb8IH5/2x7lSf7nAZrnzUD+16VyOVQ==", + "dev": true + }, + "@react-dnd/invariant": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/@react-dnd/invariant/-/invariant-2.0.0.tgz", + "integrity": "sha512-xL4RCQBCBDJ+GRwKTFhGUW8GXa4yoDfJrPbLblc3U09ciS+9ZJXJ3Qrcs/x2IODOdIE5kQxvMmE2UKyqUictUw==", + "dev": true + }, + "@react-dnd/shallowequal": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/@react-dnd/shallowequal/-/shallowequal-2.0.0.tgz", + "integrity": "sha512-Pc/AFTdwZwEKJxFJvlxrSmGe/di+aAOBn60sremrpLo6VI/6cmiUYNNwlI5KNYttg7uypzA3ILPMPgxB2GYZEg==", + "dev": true + }, "@rollup/plugin-commonjs": { "version": "19.0.2", "resolved": "https://registry.npmjs.org/@rollup/plugin-commonjs/-/plugin-commonjs-19.0.2.tgz", @@ -50661,6 +50758,17 @@ "integrity": "sha1-44Mx8IRLukm5qctxx3FYWqsbxlo=", "dev": true }, + "dnd-core": { + "version": "14.0.1", + "resolved": "https://registry.npmjs.org/dnd-core/-/dnd-core-14.0.1.tgz", + "integrity": "sha512-+PVS2VPTgKFPYWo3vAFEA8WPbTf7/xo43TifH9G8S1KqnrQu0o77A3unrF5yOugy4mIz7K5wAVFHUcha7wsz6A==", + "dev": true, + "requires": { + "@react-dnd/asap": "^4.0.0", + "@react-dnd/invariant": "^2.0.0", + "redux": "^4.1.1" + } + }, "doctrine": { "version": "3.0.0", "resolved": "https://registry.npmjs.org/doctrine/-/doctrine-3.0.0.tgz", @@ -61611,6 +61719,28 @@ } } }, + "react-dnd": { + "version": "14.0.4", + "resolved": "https://registry.npmjs.org/react-dnd/-/react-dnd-14.0.4.tgz", + "integrity": "sha512-AFJJXzUIWp5WAhgvI85ESkDCawM0lhoVvfo/lrseLXwFdH3kEO3v8I2C81QPqBW2UEyJBIPStOhPMGYGFtq/bg==", + "dev": true, + "requires": { + "@react-dnd/invariant": "^2.0.0", + "@react-dnd/shallowequal": "^2.0.0", + "dnd-core": "14.0.1", + "fast-deep-equal": "^3.1.3", + "hoist-non-react-statics": "^3.3.2" + } + }, + "react-dnd-html5-backend": { + "version": "14.0.2", + "resolved": "https://registry.npmjs.org/react-dnd-html5-backend/-/react-dnd-html5-backend-14.0.2.tgz", + "integrity": "sha512-QgN6rYrOm4UUj6tIvN8ovImu6uP48xBXF2rzVsp6tvj6d5XQ7OjHI4SJ/ZgGobOneRAU3WCX4f8DGCYx0tuhlw==", + "dev": true, + "requires": { + "dnd-core": "14.0.1" + } + }, "react-docgen": { "version": "5.4.0", "resolved": "https://registry.npmjs.org/react-docgen/-/react-docgen-5.4.0.tgz", @@ -61956,6 +62086,15 @@ "strip-indent": "^3.0.0" } }, + "redux": { + "version": "4.1.2", + "resolved": "https://registry.npmjs.org/redux/-/redux-4.1.2.tgz", + "integrity": "sha512-SH8PglcebESbd/shgf6mii6EIoRM0zrQyjcuQ+ojmfxjTtE0z9Y8pa62iA/OJ58qjP6j27uyW4kUF4jl/jd6sw==", + "dev": true, + "requires": { + "@babel/runtime": "^7.9.2" + } + }, "refractor": { "version": "3.5.0", "resolved": "https://registry.npmjs.org/refractor/-/refractor-3.5.0.tgz", diff --git a/package.json b/package.json index bdbf226beb2..a4eee2d2c39 100644 --- a/package.json +++ b/package.json @@ -44,7 +44,7 @@ "license": "MIT", "dependencies": { "@primer/octicons-react": "^13.0.0", - "@primer/primitives": "5.1.0", + "@primer/primitives": "6.1.0", "@radix-ui/react-polymorphic": "0.0.14", "@react-aria/ssr": "3.1.0", "@styled-system/css": "5.1.5", @@ -124,6 +124,8 @@ "lodash.isobject": "3.0.2", "prettier": "2.3.2", "react": "17.0.2", + "react-dnd": "14.0.4", + "react-dnd-html5-backend": "14.0.2", "react-dom": "17.0.2", "react-test-renderer": "17.0.2", "rollup": "2.56.3", diff --git a/src/ActionList2/Description.tsx b/src/ActionList2/Description.tsx new file mode 100644 index 00000000000..d50fe34dfe4 --- /dev/null +++ b/src/ActionList2/Description.tsx @@ -0,0 +1,49 @@ +import React from 'react' +import Box from '../Box' +import {SxProp, merge} from '../sx' +import Truncate from '../Truncate' +import {Slot, ItemContext} from './Item' + +export type DescriptionProps = { + /** + * Secondary text style variations. + * + * - `"inline"` - Secondary text is positioned beside primary text. + * - `"block"` - Secondary text is positioned below primary text. + */ + variant?: 'inline' | 'block' +} & SxProp + +export const Description: React.FC = ({variant = 'inline', sx = {}, ...props}) => { + const styles = { + color: 'fg.muted', + fontSize: 0, + lineHeight: '16px', + flexGrow: 1, + flexBasis: 0, + minWidth: 0, + marginLeft: variant === 'block' ? 0 : 2 + } + + return ( + + {({blockDescriptionId, inlineDescriptionId}: ItemContext) => + variant === 'block' ? ( + + {props.children} + + ) : ( + + {props.children} + + ) + } + + ) +} diff --git a/src/ActionList2/Divider.tsx b/src/ActionList2/Divider.tsx new file mode 100644 index 00000000000..d6f9444dd93 --- /dev/null +++ b/src/ActionList2/Divider.tsx @@ -0,0 +1,24 @@ +import React from 'react' +import Box from '../Box' +import {get} from '../constants' +import {Theme} from '../ThemeProvider' + +/** + * Visually separates `Item`s or `Group`s in an `ActionList`. + */ +export function Divider(): JSX.Element { + return ( + `calc(${get('space.2')(theme)} - 1px)`, + marginBottom: 2, + listStyle: 'none' // hide the ::marker inserted by browser's stylesheet + }} + data-component="ActionList.Divider" + /> + ) +} diff --git a/src/ActionList2/Group.tsx b/src/ActionList2/Group.tsx new file mode 100644 index 00000000000..30cb1ed74a2 --- /dev/null +++ b/src/ActionList2/Group.tsx @@ -0,0 +1,34 @@ +import React from 'react' +import Box from '../Box' +import {SxProp} from '../sx' +import {Header, HeaderProps} from './Header' +import {ListProps} from './List' + +export type GroupProps = HeaderProps & + SxProp & { + selectionVariant?: ListProps['selectionVariant'] | false + } + +type ContextProps = Pick +export const GroupContext = React.createContext({}) + +export const Group: React.FC = ({title, variant, auxiliaryText, selectionVariant, sx = {}, ...props}) => { + return ( + + {title &&
} + + + {props.children} + + + + ) +} diff --git a/src/ActionList2/Header.tsx b/src/ActionList2/Header.tsx new file mode 100644 index 00000000000..d04fce24df0 --- /dev/null +++ b/src/ActionList2/Header.tsx @@ -0,0 +1,58 @@ +import React from 'react' +import Box from '../Box' +import {SxProp} from '../sx' +import {ListContext} from './List' + +/** + * Contract for props passed to the `Header` component. + */ +export type HeaderProps = { + /** + * Style variations. Usage is discretionary. + * + * - `"filled"` - Superimposed on a background, offset from nearby content + * - `"subtle"` - Relatively less offset from nearby content + */ + variant?: 'subtle' | 'filled' + + /** + * Primary text which names a `Group`. + */ + title?: string + + /** + * Secondary text which provides additional information about a `Group`. + */ + auxiliaryText?: string +} & SxProp + +/** + * Displays the name and description of a `Group`. + */ +export const Header = ({variant = 'subtle', title, auxiliaryText, sx = {}, ...props}: HeaderProps): JSX.Element => { + const {variant: listVariant} = React.useContext(ListContext) + + const styles = { + paddingY: '6px', + paddingX: listVariant === 'full' ? 2 : 3, + fontSize: 0, + fontWeight: 'bold', + color: 'fg.muted', + ...(variant === 'filled' && { + backgroundColor: 'canvas.subtle', + marginX: 0, + marginBottom: 2, + borderTop: '1px solid', + borderBottom: '1px solid', + borderColor: 'neutral.muted' + }), + ...sx + } + + return ( + + {title} + {auxiliaryText && {auxiliaryText}} + + ) +} diff --git a/src/ActionList2/Item.tsx b/src/ActionList2/Item.tsx new file mode 100644 index 00000000000..0f5958abe74 --- /dev/null +++ b/src/ActionList2/Item.tsx @@ -0,0 +1,228 @@ +import React from 'react' +import {ForwardRefComponent as PolymorphicForwardRefComponent} from '@radix-ui/react-polymorphic' +import {useSSRSafeId} from '@react-aria/ssr' +import styled from 'styled-components' +import {useTheme} from '../ThemeProvider' +import Box, {BoxProps} from '../Box' +import sx, {SxProp, merge} from '../sx' +import createSlots from '../utils/create-slots' +import {AriaRole} from '../utils/types' +import {ListContext} from './List' +import {Selection} from './Selection' + +export const getVariantStyles = (variant: ItemProps['variant'], disabled: ItemProps['disabled']) => { + if (disabled) { + return { + color: 'fg.muted', + iconColor: 'fg.muted', + annotationColor: 'fg.muted' + } + } + + switch (variant) { + case 'danger': + return { + color: 'danger.fg', + iconColor: 'danger.fg', + annotationColor: 'fg.muted', + hoverColor: 'actionListItem.danger.hoverText' + } + default: + return { + color: 'fg.default', + iconColor: 'fg.muted', + annotationColor: 'fg.muted', + hoverColor: 'fg.default' + } + } +} + +export type ItemProps = { + /** + * Primary content for an Item + */ + children?: React.ReactNode + /** + * Callback that will trigger both on click selection and keyboard selection. + */ + onSelect?: (event: React.MouseEvent | React.KeyboardEvent) => void + /** + * Is the `Item` is currently selected? + */ + selected?: boolean + /** + * Style variations associated with various `Item` types. + * + * - `"default"` - An action `Item`. + * - `"danger"` - A destructive action `Item`. + */ + variant?: 'default' | 'danger' + /** + * Items that are disabled can not be clicked, selected, or navigated through. + */ + disabled?: boolean + /** + * The ARIA role describing the function of `Item` component. `option` is a common value. + */ + role?: AriaRole + /** + * id to attach to the root element of the Item + */ + id?: string + /** + * Private API for use internally only. Used by LinkItem to wrap contents in an anchor + */ + _PrivateItemWrapper?: React.FC +} & SxProp + +const {Slots, Slot} = createSlots(['LeadingVisual', 'InlineDescription', 'BlockDescription', 'TrailingVisual']) +export {Slot} +export type ItemContext = Pick & { + inlineDescriptionId: string + blockDescriptionId: string +} + +const LiBox = styled.li(sx) +export const TEXT_ROW_HEIGHT = '20px' // custom value off the scale + +export const Item = React.forwardRef( + ( + { + variant = 'default', + disabled = false, + selected = undefined, + onSelect = () => null, + sx: sxProp = {}, + id, + _PrivateItemWrapper = ({children}) => <>{children}, + ...props + }, + forwardedRef + ): JSX.Element => { + const {variant: listVariant, showDividers} = React.useContext(ListContext) + + const {theme} = useTheme() + + const styles = { + display: 'flex', + paddingX: 2, + fontSize: 1, + paddingY: '6px', // custom value off the scale + lineHeight: TEXT_ROW_HEIGHT, + marginX: listVariant === 'inset' ? 2 : 0, + minHeight: 5, + borderRadius: 2, + transition: 'background 33.333ms linear', + color: getVariantStyles(variant, disabled).color, + textDecoration: 'none', // for as="a" + ':not([aria-disabled])': {cursor: 'pointer'}, + '@media (hover: hover) and (pointer: fine)': { + ':hover:not([aria-disabled])': { + backgroundColor: `actionListItem.${variant}.hoverBg`, + color: getVariantStyles(variant, disabled).hoverColor + }, + ':focus:not([aria-disabled])': { + backgroundColor: `actionListItem.${variant}.selectedBg`, + color: getVariantStyles(variant, disabled).hoverColor, + outline: 'none' + }, + ':active:not([aria-disabled])': { + backgroundColor: `actionListItem.${variant}.activeBg`, + color: getVariantStyles(variant, disabled).hoverColor + } + }, + + /** Divider styles */ + '[data-component="ActionList.Item--DividerContainer"]': { + position: 'relative' + }, + '[data-component="ActionList.Item--DividerContainer"]::before': { + content: '" "', + display: 'block', + position: 'absolute', + width: '100%', + top: '-7px', + border: '0 solid', + borderTopWidth: showDividers ? `1px` : '0', + borderColor: 'var(--divider-color, transparent)' + }, + // show between 2 items + ':not(:first-of-type):not([aria-selected=true])': {'--divider-color': theme?.colors.actionListItem.inlineDivider}, + // hide divider after dividers & group header, with higher importance! + '[data-component="ActionList.Divider"] + &': {'--divider-color': 'transparent !important'}, + // hide border on current and previous item + '&:hover:not([aria-disabled]), &:focus:not([aria-disabled])': {'--divider-color': 'transparent'}, + '&:hover:not([aria-disabled]) + &, &:focus:not([aria-disabled]) + &': {'--divider-color': 'transparent'}, + // hide border around selected item + '&[aria-selected=true] + &': {'--divider-color': 'transparent'} + } + + const clickHandler = React.useCallback( + event => { + if (disabled) return + if (!event.defaultPrevented) onSelect(event) + }, + [onSelect, disabled] + ) + + // use props.id if provided, otherwise generate one. + const labelId = useSSRSafeId(id) + const inlineDescriptionId = useSSRSafeId(id && `${id}--inline-description`) + const blockDescriptionId = useSSRSafeId(id && `${id}--block-description`) + + return ( + + {slots => ( + + <_PrivateItemWrapper> + + {slots.LeadingVisual} + + + + + {props.children} + + {slots.InlineDescription} + + {slots.TrailingVisual} + + {slots.BlockDescription} + + + + )} + + ) + } +) as PolymorphicForwardRefComponent<'li', ItemProps> + +Item.displayName = 'ActionList.Item' + +const ConditionalBox: React.FC<{if: boolean} & BoxProps> = props => { + const {if: condition, ...rest} = props + + if (condition) return {props.children} + else return <>{props.children} +} diff --git a/src/ActionList2/LinkItem.tsx b/src/ActionList2/LinkItem.tsx new file mode 100644 index 00000000000..e2bad03244a --- /dev/null +++ b/src/ActionList2/LinkItem.tsx @@ -0,0 +1,49 @@ +import React from 'react' +import {ForwardRefComponent as PolymorphicForwardRefComponent} from '@radix-ui/react-polymorphic' +import Link from '../Link' +import {SxProp, merge} from '../sx' +import {Item, ItemProps} from './Item' + +// adopted from React.AnchorHTMLAttributes +type LinkProps = { + download?: string + href?: string + hrefLang?: string + media?: string + ping?: string + rel?: string + target?: string + type?: string + referrerPolicy?: React.AnchorHTMLAttributes['referrerPolicy'] +} + +// LinkItem does not support selected, variants, etc. +type LinkItemProps = Pick & LinkProps + +export const LinkItem = React.forwardRef(({sx = {}, as: Component, ...props}, forwardedRef) => { + const styles = { + // occupy full size of Item + paddingX: 2, + paddingY: '6px', // custom value off the scale + display: 'flex', + flexGrow: 1, // full width + borderRadius: 2, + + // inherit Item styles + color: 'inherit', + '&:hover': {color: 'inherit', textDecoration: 'none'} + } + + return ( + ( + + {children} + + )} + > + {props.children} + + ) +}) as PolymorphicForwardRefComponent<'a', LinkItemProps> diff --git a/src/ActionList2/List.tsx b/src/ActionList2/List.tsx new file mode 100644 index 00000000000..9a8e12e569a --- /dev/null +++ b/src/ActionList2/List.tsx @@ -0,0 +1,55 @@ +import React from 'react' +import {ForwardRefComponent as PolymorphicForwardRefComponent} from '@radix-ui/react-polymorphic' +import styled from 'styled-components' +import sx, {SxProp, merge} from '../sx' +import {AriaRole} from '../utils/types' + +export type ListProps = { + /** + * `inset` children are offset (vertically and horizontally) from `List`’s edges, `full` children are flush (vertically and horizontally) with `List` edges + */ + variant?: 'inset' | 'full' + /** + * Whether multiple Items or a single Item can be selected. + */ + selectionVariant?: 'single' | 'multiple' + /** + * Display a divider above each `Item` in this `List` when it does not follow a `Header` or `Divider`. + */ + showDividers?: boolean + /** + * The ARIA role describing the function of `List` component. `listbox` or `menu` are a common values. + */ + role?: AriaRole +} & SxProp + +type ContextProps = Omit +export const ListContext = React.createContext({}) + +const ListBox = styled.ul(sx) + +export const List = React.forwardRef( + ( + {variant = 'inset', selectionVariant, showDividers = false, sx: sxProp = {}, ...props}, + forwardedRef + ): JSX.Element => { + const styles = { + margin: 0, + paddingInlineStart: 0, // reset ul styles + paddingY: variant === 'inset' ? 2 : 0 + } + + return ( + + {props.children} + + ) + } +) as PolymorphicForwardRefComponent<'ul', ListProps> + +List.displayName = 'ActionList' diff --git a/src/ActionList2/Selection.tsx b/src/ActionList2/Selection.tsx new file mode 100644 index 00000000000..e9efa21a158 --- /dev/null +++ b/src/ActionList2/Selection.tsx @@ -0,0 +1,40 @@ +import React from 'react' +import {CheckIcon} from '@primer/octicons-react' +import {ListContext} from './List' +import {GroupContext} from './Group' +import {ItemProps} from './Item' +import {LeadingVisualContainer} from './Visuals' + +type SelectionProps = Pick +export const Selection: React.FC = ({selected, disabled}) => { + const {selectionVariant: listSelectionVariant} = React.useContext(ListContext) + const {selectionVariant: groupSelectionVariant} = React.useContext(GroupContext) + + /** selectionVariant in Group can override the selectionVariant in List root */ + const selectionVariant = typeof groupSelectionVariant !== 'undefined' ? groupSelectionVariant : listSelectionVariant + + // if selectionVariant is not set on List, don't show selection + if (!selectionVariant) { + // to avoid confusion, fail loudly instead of silently ignoring + if (selected) + throw new Error( + 'For Item to be selected, ActionList or ActionList.Group needs to have a selectionVariant defined' + ) + return null + } + + if (selectionVariant === 'single') { + return {selected && } + } + + /** + * selectionVariant is multiple + * readOnly is required because we are doing a one-way bind to `checked` + * aria-readonly="false" tells screen that they can still interact with the checkbox + */ + return ( + + + + ) +} diff --git a/src/ActionList2/Visuals.tsx b/src/ActionList2/Visuals.tsx new file mode 100644 index 00000000000..1e4e98bf84b --- /dev/null +++ b/src/ActionList2/Visuals.tsx @@ -0,0 +1,76 @@ +import React from 'react' +import Box from '../Box' +import {SxProp, merge} from '../sx' +import {get} from '../constants' +import {getVariantStyles, Slot, ItemContext, TEXT_ROW_HEIGHT} from './Item' + +type VisualProps = SxProp & React.HTMLAttributes + +export const LeadingVisualContainer: React.FC = ({sx = {}, ...props}) => { + return ( + + ) +} + +export type LeadingVisualProps = VisualProps +export const LeadingVisual: React.FC = ({sx = {}, ...props}) => { + return ( + + {({variant, disabled}: ItemContext) => ( + + {props.children} + + )} + + ) +} + +export type TrailingVisualProps = VisualProps +export const TrailingVisual: React.FC = ({sx = {}, ...props}) => { + return ( + + {({variant, disabled}: ItemContext) => ( + + {props.children} + + )} + + ) +} diff --git a/src/ActionList2/index.ts b/src/ActionList2/index.ts new file mode 100644 index 00000000000..d05da47652f --- /dev/null +++ b/src/ActionList2/index.ts @@ -0,0 +1,39 @@ +import {List} from './List' +import {Group} from './Group' +import {Item} from './Item' +import {LinkItem} from './LinkItem' +import {Divider} from './Divider' +import {Description} from './Description' +import {LeadingVisual, TrailingVisual} from './Visuals' + +export type {ListProps as ActionListProps} from './List' +export type {GroupProps} from './Group' +export type {ItemProps} from './Item' +export type {DescriptionProps} from './Description' +export type {LeadingVisualProps, TrailingVisualProps} from './Visuals' + +/** + * Collection of list-related components. + */ +export const ActionList = Object.assign(List, { + /** Collects related `Items` in an `ActionList`. */ + Group, + + /** An actionable or selectable `Item` */ + Item, + + /** A `Item` that renders a full-size anchor inside ListItem */ + LinkItem, + + /** Visually separates `Item`s or `Group`s in an `ActionList`. */ + Divider, + + /** Secondary text which provides additional information about an `Item`. */ + Description, + + /** Icon (or similar) positioned before `Item` text. */ + LeadingVisual, + + /** Icon (or similar) positioned after `Item` text. */ + TrailingVisual +}) diff --git a/src/__tests__/ActionList2.test.tsx b/src/__tests__/ActionList2.test.tsx new file mode 100644 index 00000000000..0a0679466b0 --- /dev/null +++ b/src/__tests__/ActionList2.test.tsx @@ -0,0 +1,47 @@ +import {cleanup, render as HTMLRender} from '@testing-library/react' +import 'babel-polyfill' +import {axe, toHaveNoViolations} from 'jest-axe' +import React from 'react' +import theme from '../theme' +import {ActionList} from '../ActionList2' +import {behavesAsComponent, checkExports} from '../utils/testing' +import {BaseStyles, ThemeProvider, SSRProvider} from '..' +expect.extend(toHaveNoViolations) + +function SimpleActionList(): JSX.Element { + return ( + + + + + New file + + Copy link + Edit file + Delete file + + + + + ) +} + +describe('ActionList', () => { + behavesAsComponent({ + Component: ActionList, + options: {skipAs: true, skipSx: true}, + toRender: () => + }) + + checkExports('ActionList2', { + default: undefined, + ActionList + }) + + it('should have no axe violations', async () => { + const {container} = HTMLRender() + const results = await axe(container) + expect(results).toHaveNoViolations() + cleanup() + }) +}) diff --git a/src/__tests__/__snapshots__/ActionList2.test.tsx.snap b/src/__tests__/__snapshots__/ActionList2.test.tsx.snap new file mode 100644 index 00000000000..5bbbad35875 --- /dev/null +++ b/src/__tests__/__snapshots__/ActionList2.test.tsx.snap @@ -0,0 +1,14 @@ +// Jest Snapshot v1, https://goo.gl/fbAQLP + +exports[`ActionList renders consistently 1`] = ` +.c0 { + margin: 0; + padding-inline-start: 0; + padding-top: 8px; + padding-bottom: 8px; +} + +