@primer/components 31.2.1-rc.48ecca6e → 32.0.0-next.0

package/contributor-docs/principles.md

@@ -1,39 +0,0 @@
-# Principles
-
-### Communication
-
-Design systems provide a vocabulary between design and engineering, the language we use should be correct but not at the expense of providing clarity. Use words and descriptions that both designers and engineers can understand.
-
-* Be a bridge not a barrier. Use vocabulary that provides meaning to both designers and engineers.
-* Choose language that provides mutual understanding between engineering and design over specificity.
-* Support new vocabulary with descriptions and examples.
-* Be consistent in the application of vocabulary in written and verbal communication to reinforce understandings.
-* Articulate what you are aiming to achieve as well as what you are not doing.
-
-### Judgment
-
-There's often more than one way to do things, and there aren't always best-practice examples to follow. Despite this we still need to make decisions and keep moving forward. To deal with an uncertain future and still move forward we should have _strong opinions, weakly held_.
-
-* Make decisions that move us forward rather than halting progress due to ambiguity or difference of opinion.
-* Make decisions based on long term goals rather than this week's ship.
-* Evaluate technology by the risk they present, not just the solution they offer. High risk deserves careful consideration, low risk deserves less attention.
-* Have opinions and arguments for them, but remain open to seeing and hearing evidence that clashes with them when those opinions become wrong.
-* Prioritize solutions for people who use the system and how it serves the customers who use products built with the system.
-* Seek feedback on code review often, and more often when a solution takes you down a new path.
-* Take time to provide good code review, encompassing the above values when providing feedback.
-
-### Innovation
-
-* Treat everything as an experiment. Make small incremental steps that provide proof towards goals, or disprove them.
-* Ship often. We learn more from tangible outcomes than something that only lives as an idea.
-* Work on reducing complexity and simplifying solutions to enable us to innovate faster.
-
-### Implementation
-
-* Engineer just enough of a solution, value declarative over abstraction.
-* A little verbosity is better than clever code. Avoid implementations that reduce the ability for people to contribute.
-* Automate and abstract when repetition is a hindrance.
-* Seek feedback on implementations as often as possible.
-* Everything is a component.
-* Provide flexibility, but within the boundaries of the system.
-* Assume that people will break the rules, and provide safe ways for them to do so.

package/docs/.gitignore

@@ -1,91 +0,0 @@
-# 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

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

package/docs/components/State.js

@@ -1,9 +0,0 @@
-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

@@ -1,34 +0,0 @@
-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

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

package/docs/content/ActionList.mdx

@@ -1,99 +0,0 @@
----
-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/ActionList2.mdx

@@ -1,358 +0,0 @@
----
-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/drafts'
-import {Props} from '../src/props'
-
-import {ImageContainer} from '@primer/gatsby-theme-doctocat'
-import {LinkIcon, AlertIcon, ArrowRightIcon} from '@primer/octicons-react'
-
-<br />
-
-<BorderBox sx={{padding: 6}}>
-  <ActionList sx={{width: 320}}>
-    <ActionList.Item>
-      <ActionList.LeadingVisual>
-        <LinkIcon />
-      </ActionList.LeadingVisual>
-      github.com/primer
-      <ActionList.Description variant="block">
-        A React implementation of GitHub's Primer Design System
-      </ActionList.Description>
-    </ActionList.Item>
-    <ActionList.Item>
-      <ActionList.LeadingVisual>
-        <Avatar src="https://github.com/mona.png" />
-      </ActionList.LeadingVisual>
-      mona
-      <ActionList.Description>Monalisa Octocat</ActionList.Description>
-    </ActionList.Item>
-    <ActionList.Item variant="danger">
-      <ActionList.LeadingVisual>
-        <AlertIcon />
-      </ActionList.LeadingVisual>
-      4 vulnerabilities
-      <ActionList.TrailingVisual>
-        <ArrowRightIcon />
-      </ActionList.TrailingVisual>
-    </ActionList.Item>
-  </ActionList>
-</BorderBox>
-
-<br />
-
-```js
-import {ActionList} from '@primer/components/drafts'
-```
-
-<br />
-
-## Examples
-
-### Minimal example
-
-```javascript live noinline
-// import {ActionList} from '@primer/components/drafts'
-const {ActionList} = drafts // ignore docs silliness; import like that ↑
-
-render(
-  <ActionList>
-    <ActionList.Item>New file</ActionList.Item>
-    <ActionList.Item>Copy link</ActionList.Item>
-    <ActionList.Item>Edit file</ActionList.Item>
-    <ActionList.Divider />
-    <ActionList.Item variant="danger">Delete file</ActionList.Item>
-  </ActionList>
-)
-```
-
-<br />
-
-### 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.
-
-<!-- prettier-ignore -->
-```javascript live noinline
-// import {ActionList} from '@primer/components/drafts'
-const {ActionList} = drafts // ignore docs silliness; import like that ↑
-
-render(
-  <ActionList>
-    <ActionList.Item>
-      <ActionList.LeadingVisual><LinkIcon /></ActionList.LeadingVisual>
-      github.com/primer
-    </ActionList.Item>
-    <ActionList.Item variant="danger">
-      <ActionList.LeadingVisual><AlertIcon /></ActionList.LeadingVisual>
-      4 vulnerabilities
-    </ActionList.Item>
-    <ActionList.Item>
-      <ActionList.LeadingVisual><Avatar src="https://github.com/mona.png" /></ActionList.LeadingVisual>
-      mona
-    </ActionList.Item>
-  </ActionList>
-)
-```
-
-<br />
-
-### 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
-// import {ActionList} from '@primer/components/drafts'
-const {ActionList} = drafts // ignore docs silliness; import like that ↑
-
-render(
-  <ActionList>
-    <ActionList.Item>
-      New file
-      <ActionList.TrailingVisual>⌘ + N</ActionList.TrailingVisual>
-    </ActionList.Item>
-    <ActionList.Item>
-      Copy link
-      <ActionList.TrailingVisual>⌘ + C</ActionList.TrailingVisual>
-    </ActionList.Item>
-    <ActionList.Item>
-      Edit file
-      <ActionList.TrailingVisual>⌘ + E</ActionList.TrailingVisual>
-    </ActionList.Item>
-    <ActionList.Item variant="danger">
-      Delete file
-      <ActionList.TrailingVisual>⌫</ActionList.TrailingVisual>
-    </ActionList.Item>
-  </ActionList>
-)
-```
-
-<br />
-
-### 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
-// import {ActionList} from '@primer/components/drafts'
-const {ActionList} = drafts // ignore docs silliness; import like that ↑
-
-render(
-  <ActionList showDividers>
-    <ActionList.Item>
-      <ActionList.LeadingVisual>
-        <Avatar src="https://github.com/mona.png" />
-      </ActionList.LeadingVisual>
-      mona
-      <ActionList.Description>Monalisa Octocat</ActionList.Description>
-    </ActionList.Item>
-    <ActionList.Item>
-      <ActionList.LeadingVisual>
-        <Avatar src="https://github.com/hubot.png" />
-      </ActionList.LeadingVisual>
-      hubot
-      <ActionList.Description>Hubot</ActionList.Description>
-    </ActionList.Item>
-    <ActionList.Item>
-      <ActionList.LeadingVisual>
-        <Avatar src="https://github.com/primer-css.png" />
-      </ActionList.LeadingVisual>
-      primer-css
-      <ActionList.Description>GitHub Design Systems Bot</ActionList.Description>
-    </ActionList.Item>
-  </ActionList>
-)
-```
-
-### With links
-
-When you want to add links to the List instead of actions, use `ActionList.LinkItem`
-
-<!-- prettier-ignore -->
-```javascript live noinline
-// import {ActionList} from '@primer/components/drafts'
-const {ActionList} = drafts // ignore docs silliness; import like that ↑
-
-render(
-  <ActionList>
-    <ActionList.LinkItem href="https://github.com/primer">
-      <ActionList.LeadingVisual>
-        <LinkIcon />
-      </ActionList.LeadingVisual>
-      github/primer
-    </ActionList.LinkItem>
-    <ActionList.LinkItem as={ReactRouterLink} to="/">
-      <ActionList.LeadingVisual>
-        <LawIcon />
-      </ActionList.LeadingVisual>
-      MIT License
-    </ActionList.LinkItem>
-    <ActionList.LinkItem 
-      href="https://github.com/primer/react/stargazers"
-      target="_blank"
-      rel="noopener noreferrer"
-    >
-      <ActionList.LeadingVisual>
-        <StarIcon />
-      </ActionList.LeadingVisual>
-      1.4k stars
-    </ActionList.LinkItem>
-  </ActionList>
-)
-```
-
-<br />
-
-### With groups
-
-```javascript live noinline
-// import {ActionList} from '@primer/components/drafts'
-const {ActionList} = drafts // ignore docs silliness; import like that ↑
-
-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 (
-    <ActionList selectionVariant="multiple">
-      <ActionList.Group title="Visible fields (can be reordered)">
-        {visibleOptions.map(option => (
-          <ActionList.Item key={option.text} selected={true} onSelect={() => toggle(option.text)}>
-            {option.text}
-          </ActionList.Item>
-        ))}
-      </ActionList.Group>
-      <ActionList.Group
-        title="Hidden fields"
-        selectionVariant={
-          /** selectionVariant override on Group: disable selection if there are no options */
-          hiddenOptions.length ? 'multiple' : false
-        }
-      >
-        {hiddenOptions.map((option, index) => (
-          <ActionList.Item key={option.text} selected={false} onSelect={() => toggle(option.text)}>
-            {option.text}
-          </ActionList.Item>
-        ))}
-        {hiddenOptions.length === 0 && <ActionList.Item disabled>No hidden fields</ActionList.Item>}
-      </ActionList.Group>
-    </ActionList>
-  )
-}
-
-render(<SelectFields />)
-```
-
-<br />
-
-## 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.                                                                              |
-
-<br />
-
-### 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)                                   |
-
-<br />
-
-### 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. |                                                                                                               |         |                                                                |
-
-<br />
-
-### 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) |
-
-<br />
-
-### 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)                                                                    |
-
-<br />
-
-### 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                                                                                      |
-
-<br />
-
-## Further reading
-
-- [Interface guidelines: Action List](https://primer.style/design/components/action-list)
-
-<br />
-
-## Related components
-
-- [ActionMenu](/ActionMenu)
-- [SelectPanel](/SelectPanel)