ActionList

.eslintrc.json

@@ -62,7 +62,7 @@
       "rules": {
         "@typescript-eslint/no-explicit-any": 2,
         "@typescript-eslint/explicit-module-boundary-types": 0,
-        "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }]
+        "@typescript-eslint/no-unused-vars": ["error", {"argsIgnorePattern": "^_"}]
       }
     }
   ]

docs/content/ActionList.mdx

@@ -0,0 +1,67 @@
+---
+title: ActionList
+---
+
+An `ActionList` is a list of items which can be activated or selected. `ActionList` is the base component for many of our menu-type components, including `DropdownMenu` and `ActionMenu`.
+
+## Minimal example
+
+```jsx live
+<ActionList
+  items={[
+    {text: 'New file'},
+    ActionList.Divider,
+    {text: 'Copy link'},
+    {text: 'Edit file'},
+    {text: 'Delete file', variant: 'danger'}
+  ]}
+/>
+```
+
+## Example with grouped items
+
+```jsx live
+<ActionList
+  groupMetadata={[
+    {groupId: '0'},
+    {groupId: '1', header: {title: 'Live query', variant: 'subtle'}},
+    {groupId: '2', header: {title: 'Layout', variant: 'subtle'}},
+    {groupId: '3'},
+    {groupId: '4'}
+  ]}
+  items={[
+    {leadingVisual: TypographyIcon, text: 'Rename', groupId: '0'},
+    {leadingVisual: VersionsIcon, text: 'Duplicate', groupId: '0'},
+    {leadingVisual: SearchIcon, text: 'repo:github/memex,github/github', groupId: '1'},
+    {
+      leadingVisual: NoteIcon,
+      text: 'Table',
+      description: 'Information-dense table optimized for operations across teams',
+      descriptionVariant: 'block',
+      groupId: '2'
+    },
+    {
+      leadingVisual: ProjectIcon,
+      text: 'Board',
+      description: 'Kanban-style board focused on visual states',
+      descriptionVariant: 'block',
+      groupId: '2'
+    },
+    {
+      leadingVisual: FilterIcon,
+      text: 'Save sort and filters to current view',
+      groupId: '3'
+    },
+    {leadingVisual: FilterIcon, text: 'Save sort and filters to new view', groupId: '3'},
+    {leadingVisual: GearIcon, text: 'View settings', groupId: '4'}
+  ]}
+/>
+```
+
+## Component props
+
+| Name          | Type                                |      Default      | Description                                                                                                                                             |
+| :------------ | :---------------------------------- | :---------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| items         | `ItemProps[]`                       |    `undefined`    | Required. A list of item objects conforming to the `ActionList.Item` props interface.                                                                   |
+| renderItems   | `(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. |

src/ActionList/Divider.tsx

@@ -0,0 +1,25 @@
+import React from 'react'
+import styled from 'styled-components'
+import {get} from '../constants'
+
+const StyledDivider = styled.div`
+  height: 1px;
+  background: ${get('colors.selectMenu.borderSecondary')};
+  margin-top: calc(${get('space.2')} - 1px);
+  margin-bottom: ${get('space.2')};
+`
+
+/**
+ * Visually separates `Item`s or `Group`s in an `ActionList`.
+ */
+export function Divider(): JSX.Element {
+  return <StyledDivider />
+}
+
+/**
+ * `Divider` fulfills the `ItemPropsWithCustomRenderer` contract,
+ * so it can be used inline in an `ActionList`’s `items` prop.
+ * In other words, `items={[ActionList.Divider]}` is supported as a concise
+ * alternative to `items={[{renderItem: () => <ActionList.Divider />}]}`.
+ */
+Divider.renderItem = Divider

src/ActionList/Group.tsx

@@ -0,0 +1,35 @@
+import React from 'react'
+import styled from 'styled-components'
+import sx, {SxProp} from '../sx'
+import {Header, HeaderProps} from './Header'
+
+/**
+ * Contract for props passed to the `Group` component.
+ */
+export interface GroupProps extends React.ComponentPropsWithoutRef<'div'>, SxProp {
+  /**
+   * Props for a `Header` to render in the `Group`.
+   */
+  header?: HeaderProps
+
+  /**
+   * `Items` to render in the `Group`.
+   */
+  items?: JSX.Element[]
+}
+
+const StyledGroup = styled.div`
+  ${sx}
+`
+
+/**
+ * Collects related `Items` in an `ActionList`.
+ */
+export function Group({header, items, ...props}: GroupProps): JSX.Element {
+  return (
+    <StyledGroup {...props}>
+      {header && <Header {...header} />}
+      {items}
+    </StyledGroup>
+  )
+}

src/ActionList/Header.tsx

@@ -0,0 +1,74 @@
+import React from 'react'
+import styled, {css} from 'styled-components'
+import {get} from '../constants'
+import sx, {SxProp} from '../sx'
+
+/**
+ * Contract for props passed to the `Header` component.
+ */
+export interface HeaderProps extends React.ComponentPropsWithoutRef<'div'>, SxProp {
+  /**
+   * 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
+}
+
+const StyledHeader = styled.div<{variant: HeaderProps['variant']} & SxProp>`
+   {
+    /* 6px vertical padding + 20px line height = 32px total height
+     *
+     * TODO: When rem-based spacing on a 4px scale lands, replace
+     * hardcoded '6px' with 'calc((${get('space.s32')} - ${get('space.20')}) / 2)'.
+     */
+  }
+  padding: 6px ${get('space.3')};
+  font-size: ${get('fontSizes.0')};
+  font-weight: ${get('fontWeights.bold')};
+  color: ${get('colors.text.secondary')};
+
+  ${({variant}) =>
+    variant === 'filled' &&
+    css`
+      background: ${get('colors.bg.tertiary')};
+      margin: ${get('space.2')} 0;
+      border-top: 1px solid ${get('colors.border.tertiary')};
+      border-bottom: 1px solid ${get('colors.border.tertiary')};
+
+      &:first-child {
+        margin-top: 0;
+      }
+    `}
+
+  ${sx}
+`
+
+/**
+ * Displays the name and description of a `Group`.
+ */
+export function Header({
+  variant = 'subtle',
+  title,
+  auxiliaryText,
+  children: _children,
+  ...props
+}: HeaderProps): JSX.Element {
+  return (
+    <StyledHeader role="heading" variant={variant} {...props}>
+      {title}
+      {auxiliaryText && <span>auxiliaryText</span>}
+    </StyledHeader>
+  )
+}

src/ActionList/Item.tsx

@@ -0,0 +1,118 @@
+import type {IconProps} from '@primer/octicons-react'
+import React from 'react'
+import styled from 'styled-components'
+import {get} from '../constants'
+import sx, {SxProp} from '../sx'
+
+/**
+ * Contract for props passed to the `Item` component.
+ */
+export interface ItemProps extends React.ComponentPropsWithoutRef<'div'>, SxProp {
+  /**
+   * Primary text which names an `Item`.
+   */
+  text: string
+
+  /**
+   * Secondary text which provides additional information about an `Item`.
+   */
+  description?: string
+
+  /**
+   * Secondary text style variations. Usage is discretionary.
+   *
+   * - `"inline"` - Secondary text is positioned beside primary text.
+   * - `"block"` - Secondary text is positioned below primary text.
+   */
+  descriptionVariant?: 'inline' | 'block'
+
+  /**
+   * Icon (or similar) positioned before `Item` text.
+   */
+  leadingVisual?: React.FunctionComponent<IconProps>
+
+  /**
+   * Style variations associated with various `Item` types.
+   *
+   * - `"default"` - An action `Item`.
+   * - `"danger"` - A destructive action `Item`.
+   */
+  variant?: 'default' | 'danger'
+}
+
+const StyledItem = styled.div<{variant: ItemProps['variant']} & SxProp>`
+  /* 6px vertical padding + 20px line height = 32px total height
+   *
+   * TODO: When rem-based spacing on a 4px scale lands, replace
+   * hardcoded '6px' with 'calc((${get('space.s32')} - ${get('space.20')}) / 2)'.
+   */
+  padding: 6px ${get('space.2')};
+  display: flex;
+  border-radius: ${get('radii.2')};
+  color: ${({variant}) => (variant === 'danger' ? get('colors.text.danger') : 'inherit')};
+
+  @media (hover: hover) and (pointer: fine) {
+    :hover {
+      background: ${props =>
+        props.variant === 'danger' ? get('colors.bg.danger') : get('colors.selectMenu.tapHighlight')};
+      cursor: pointer;
+    }
+  }
+
+  ${sx}
+`
+
+const StyledTextContainer = styled.div<{descriptionVariant: ItemProps['descriptionVariant']}>`
+  flex-direction: ${({descriptionVariant}) => (descriptionVariant === 'inline' ? 'row' : 'column')};
+`
+
+const LeadingVisualContainer = styled.div`
+   {
+    /* Match visual height to adjacent text line height.
+     *
+     * TODO: When rem-based spacing on a 4px scale lands, replace
+     * hardcoded '20px' with '${get('space.s20')}'.
+     */
+  }
+  height: 20px;
+  width: ${get('space.3')};
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  margin-right: ${get('space.2')};
+
+  svg {
+    fill: ${get('colors.text.secondary')};
+    font-size: ${get('fontSizes.0')};
+  }
+`
+
+const DescriptionContainer = styled.span`
+  color: ${get('colors.text.secondary')};
+`
+
+/**
+ * An actionable or selectable `Item` with an optional icon and description.
+ */
+export function Item({
+  text,
+  description,
+  descriptionVariant = 'inline',
+  leadingVisual: LeadingVisual,
+  variant = 'default',
+  ...props
+}: Partial<ItemProps>): JSX.Element {
+  return (
+    <StyledItem variant={variant} {...props}>
+      {LeadingVisual && (
+        <LeadingVisualContainer>
+          <LeadingVisual />
+        </LeadingVisualContainer>
+      )}
+      <StyledTextContainer descriptionVariant={descriptionVariant}>
+        <div>{text}</div>
+        {description && <DescriptionContainer>{description}</DescriptionContainer>}
+      </StyledTextContainer>
+    </StyledItem>
+  )
+}