@primer/components 31.0.2-rc.c7dafefb → 31.2.0-rc.25d7c83f

package/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'
+
+<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/unreleased'
+```
+
+<br />
+
+## Examples
+
+## Minimal example
+
+```javascript live noinline
+const {ActionList} = unreleased
+
+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
+const {ActionList} = unreleased
+
+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
+const {ActionList} = unreleased
+
+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
+const {ActionList} = unreleased
+
+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
+const {ActionList} = unreleased
+
+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
+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 (
+    <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)
+
+<br />

package/docs/content/FilterList.md

@@ -8,10 +8,10 @@ The FilterList component is a menu with filter options that filter the main cont
 
 ```jsx live
 <FilterList>
-  <FilterList.Item selected count="32" href="#foo">
+  <FilterList.Item selected count={32} href="#foo">
     First Filter
   </FilterList.Item>
-  <FilterList.Item count="2" href="#bar">
+  <FilterList.Item count={2} href="#bar">
     Second Filter
   </FilterList.Item>
   <FilterList.Item href="#baz">Third Filter</FilterList.Item>

package/docs/content/TextInputWithTokens.mdx

@@ -48,6 +48,7 @@ render(BasicExample)
 | preventTokenWrapping   | `boolean`                             |   `false`    | Optional. Whether tokens should render inline horizontally. By default, tokens wrap to new lines.                         |
 | size                   | `TokenSizeKeys`                       | `extralarge` | Optional. The size of the tokens                                                                                          |
 | hideTokenRemoveButtons | `boolean`                             |   `false`    | Optional. Whether the remove buttons should be rendered in the tokens                                                     |
+| visibleTokenCount      | `number`                              | `undefined`  | Optional. The number of tokens to display before truncating                                                               |
 
 ## Adding and removing tokens
 
@@ -95,3 +96,116 @@ const UsingIssueLabelTokens = () => {
 
 render(<UsingIssueLabelTokens />)
 ```
+
+## Dealing with long lists of tokens
+
+By default, all tokens will be visible when the component is rendered.
+
+If the component is being used in an area where it's height needs to be constrained, there are options to limit the height of the input.
+
+### Hide and show tokens
+
+```javascript live noinline
+const VisibleTokenCountExample = () => {
+  const [tokens, setTokens] = React.useState([
+    {text: 'zero', id: 0},
+    {text: 'one', id: 1},
+    {text: 'two', id: 2},
+    {text: 'three', id: 3}
+  ])
+  const onTokenRemove = tokenId => {
+    setTokens(tokens.filter(token => token.id !== tokenId))
+  }
+
+  return (
+    <Box maxWidth="500px">
+      <Box as="label" display="block" htmlFor="inputWithTokens-basic">
+        Tokens truncated after 2
+      </Box>
+      <TextInputWithTokens
+        visibleTokenCount={2}
+        block
+        tokens={tokens}
+        onTokenRemove={onTokenRemove}
+        id="inputWithTokens-basic"
+      />
+    </Box>
+  )
+}
+
+render(VisibleTokenCountExample)
+```
+
+### Render tokens on a single line
+
+```javascript live noinline
+const PreventTokenWrappingExample = () => {
+  const [tokens, setTokens] = React.useState([
+    {text: 'zero', id: 0},
+    {text: 'one', id: 1},
+    {text: 'two', id: 2},
+    {text: 'three', id: 3},
+    {text: 'four', id: 4},
+    {text: 'five', id: 5},
+    {text: 'six', id: 6},
+    {text: 'seven', id: 7}
+  ])
+  const onTokenRemove = tokenId => {
+    setTokens(tokens.filter(token => token.id !== tokenId))
+  }
+
+  return (
+    <Box maxWidth="500px">
+      <Box as="label" display="block" htmlFor="inputWithTokens-basic">
+        Tokens on one line
+      </Box>
+      <TextInputWithTokens
+        preventTokenWrapping
+        block
+        tokens={tokens}
+        onTokenRemove={onTokenRemove}
+        id="inputWithTokens-basic"
+      />
+    </Box>
+  )
+}
+
+render(PreventTokenWrappingExample)
+```
+
+### Set a maximum height for the input
+
+```javascript live noinline
+const MaxHeightExample = () => {
+  const [tokens, setTokens] = React.useState([
+    {text: 'zero', id: 0},
+    {text: 'one', id: 1},
+    {text: 'two', id: 2},
+    {text: 'three', id: 3},
+    {text: 'four', id: 4},
+    {text: 'five', id: 5},
+    {text: 'six', id: 6},
+    {text: 'seven', id: 7}
+  ])
+  const onTokenRemove = tokenId => {
+    setTokens(tokens.filter(token => token.id !== tokenId))
+  }
+
+  return (
+    <Box maxWidth="500px">
+      <Box as="label" display="block" htmlFor="inputWithTokens-basic">
+        Tokens restricted to a max height
+      </Box>
+      <TextInputWithTokens
+        maxHeight="50px"
+        block
+        tokens={tokens}
+        onTokenRemove={onTokenRemove}
+        id="inputWithTokens-basic"
+      />
+    </Box>
+  )
+}
+
+render(MaxHeightExample)
+```

package/docs/content/getting-started.md

@@ -105,7 +105,7 @@ If you're rendering React components both server- and client-side, we suggest fo
 
 ## TypeScript
 
-Primer React includes TypeScript support and ships with its own typings. You will need still need to to install type typings for the peer dependencies if you import those in your own application code.
+Primer React includes TypeScript support and ships with its own typings. You will still need to install type definitions for the peer dependencies if you import those in your own application code.
 
 Once installed, you can import components and their prop type interfaces from the `@primer/components` package:
 

package/docs/content/theming.md

@@ -3,6 +3,8 @@ title: Theming
 description: Theming in Primer React is made possible by a theme object that defines your application's colors, spacing, fonts, and more.
 ---
 
+import Code from '@primer/gatsby-theme-doctocat/src/components/code'
+
 ## ThemeProvider
 
 To give components access to the theme object, you must add `ThemeProvider` to the root of your application:
@@ -50,6 +52,27 @@ Some components may break if your custom theme does not include all the same key
 
 You can reference theme values in your application using [system props](/system-props), the [`sx` prop](/overriding-styles), the `themeGet` function, or the `useTheme` hook.
 
+<Note variant="warning">
+
+Only use `theme` objects accessed via Primer's theme context to ensure your application’s styling draws from the same theme as Primer components’ internal styling. The `sx` prop, styled system props, `themeGet`, and `useTheme` all use the theme from context.
+
+<DoDontContainer>
+  <Do>
+    <Code className="language-jsx">
+      {`<Box textShadow="shadow.medium">`}
+    </Code>
+    <Caption>Use the theme from the same context as Primer.</Caption>
+  </Do>
+  <Dont>
+    <Code className="language-jsx">
+      {`import {theme} from '@primer/components'\n\n<Box textShadow={theme.shadows.shadow.medium}>`}
+    </Code>
+    <Caption>Don't style components with any other instance of theme</Caption>
+  </Dont>
+</DoDontContainer>
+
+</Note>
+
 ### System props and the `sx` prop
 
 Some [system props](/system-props) and [`sx` prop](/overriding-styles) keys are theme-aware. For example, the `bg` prop maps to the `colors` theme key which means you can use the `bg` prop to reference values in the `colors` object:

package/docs/src/@primer/gatsby-theme-doctocat/components/hero.js

@@ -9,9 +9,7 @@ export default function Hero() {
     <ThemeProvider colorMode="night" nightScheme="dark_dimmed">
       <Box bg="canvas.default" py={6}>
         <Container>
-          <Heading color="accent.fg" fontSize={7} lineHeight="condensed" pb={3} m={0}>
-            Primer React
-          </Heading>
+          <Heading sx={{color: 'accent.fg', fontSize: 7, lineHeight: 'condensed', pb: 3, m: 0}}>Primer React</Heading>
           <Text as="p" fontFamily="mono" mt={0} mb={2} color="fg.default" fontSize={2}>
             v{version}
           </Text>

package/docs/src/@primer/gatsby-theme-doctocat/components/live-preview-wrapper.js

@@ -8,7 +8,7 @@ function ThemeSwitcher() {
   return (
     <DropdownMenu
       renderAnchor={({children, ...anchorProps}) => (
-        <DropdownButton variant="small" {...anchorProps}>
+        <DropdownButton {...anchorProps} sx={{variant: 'small'}}>
           {children}
         </DropdownButton>
       )}

package/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 <a href={to} {...props} />
+}
+
 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,

package/lib/ActionList/Header.js

@@ -45,7 +45,7 @@ function Header({
   return /*#__PURE__*/_react.default.createElement(StyledHeader, _extends({
     role: "heading",
     variant: variant
-  }, props), title, auxiliaryText && /*#__PURE__*/_react.default.createElement("span", null, "auxiliaryText"));
+  }, props), title, auxiliaryText && /*#__PURE__*/_react.default.createElement("span", null, auxiliaryText));
 }
 
 Header.displayName = "Header";

package/lib/ActionList2/Description.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+import { SxProp } from '../sx';
+export declare 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 declare const Description: React.FC<DescriptionProps>;