Select input component

.changeset/cool-parrots-double.md

@@ -0,0 +1,5 @@
+---
+'@primer/react': minor
+---
+
+Adds a component for a native select input

docs/content/Select.mdx

@@ -0,0 +1,129 @@
+---
+title: Select
+description: Use a select input when a user needs to select one option from a long list
+status: Alpha
+source: https://github.com/primer/react/blob/main/src/Select.tsx
+storybook: '/react/storybook?path=/story/forms-select--default'
+---
+
+import {Select, Text} from '@primer/react'
+import {ComponentChecklist} from '../src/component-checklist'
+import PropsTable from '../src/props-table'
+
+## Examples
+
+### Basic
+
+```jsx live
+<>
+  <Text fontWeight="bold" fontSize={1} as="label" display="block" htmlFor="basic">
+    Preferred Primer component interface
+  </Text>
+  <Select id="basic">
+    <Select.Option value="figma">Figma</Select.Option>
+    <Select.Option value="css">Primer CSS</Select.Option>
+    <Select.Option value="prc">Primer React components</Select.Option>
+    <Select.Option value="pvc">Primer ViewComponents</Select.Option>
+  </Select>
+</>
+```
+
+### With grouped options
+
+```jsx live
+<>
+  <Text fontWeight="bold" fontSize={1} as="label" display="block" htmlFor="grouped">
+    Preferred Primer component interface
+  </Text>
+  <Select id="grouped">
+    <Select.OptGroup label="GUI">
+      <Select.Option value="figma">Figma</Select.Option>
+    </Select.OptGroup>
+    <Select.OptGroup label="Code">
+      <Select.Option value="css">Primer CSS</Select.Option>
+      <Select.Option value="prc">Primer React components</Select.Option>
+      <Select.Option value="pvc">Primer ViewComponents</Select.Option>
+    </Select.OptGroup>
+  </Select>
+</>
+```
+
+### With a placeholder
+
+```jsx live
+<>
+  <Text fontWeight="bold" fontSize={1} as="label" display="block" htmlFor="withPlaceholder">
+    Preferred Primer component interface
+  </Text>
+  <Select id="withPlaceholder" placeholder="Pick an interface">
+    <Select.Option value="figma">Figma</Select.Option>
+    <Select.Option value="css">Primer CSS</Select.Option>
+    <Select.Option value="prc">Primer React components</Select.Option>
+    <Select.Option value="pvc">Primer ViewComponents</Select.Option>
+  </Select>
+</>
+```
+
+## Props
+
+### Select
+
+<PropsTable>
+  <PropsTableRow
+    name="block"
+    type="boolean"
+    defaultValue="false"
+    description={<>Creates a full width input element</>}
+  />
+  <PropsTableRow
+    name="contrast"
+    type="boolean"
+    defaultValue="false"
+    description="Changes background color to a higher contrast color"
+  />
+  <PropsTableRow
+    name="size"
+    type="'small' | 'medium' | 'large'"
+    description="Creates a smaller or larger input than the default."
+  />
+  <PropsTableRow name="validationStatus" type="'warning' | 'error'" description="Style the input to match the status" />
+  <tr>
+
+    <Box as="td" colSpan={4} fontSize={1} verticalAlign="top">
+      Additional props are passed to the <InlineCode>&lt;select&gt;</InlineCode> element. See{' '}
+      <Link href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select#attributes">MDN</Link> for a list of
+      props accepted by the <InlineCode>&lt;select&gt;</InlineCode> element.
+
+      <br /> The <InlineCode>multiple</InlineCode> prop is not accepted.
+    </Box>
+
+  </tr>
+</PropsTable>
+
+### Select.OptGroup
+
+The `Select.OptGroup` component accepts the same props as a native HTML [`<optgroup>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/optgroup).
+
+### Select.Option
+
+The `Select.Option` component accepts the same props as a native HTML [`<option>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option).
+
+## Status
+
+<ComponentChecklist
+  items={{
+    propsDocumented: true,
+    noUnnecessaryDeps: true,
+    adaptsToThemes: true,
+    adaptsToScreenSizes: true,
+    fullTestCoverage: true,
+    usedInProduction: false,
+    usageExamplesDocumented: false,
+    designReviewed: false,
+    a11yReviewed: false,
+    stableApi: false,
+    addressedApiFeedback: false,
+    hasDesignGuidelines: false,
+    hasFigmaComponent: false
+  }}
+/>

docs/src/@primer/gatsby-theme-doctocat/nav.yml

@@ -95,6 +95,8 @@
       url: /ProgressBar
     - title: Radio
       url: /Radio
+    - title: Select
+      url: /Select
     - title: SideNav
       url: /SideNav
     - title: Spinner

src/Select.tsx

@@ -0,0 +1,78 @@
+import React from 'react'
+import styled from 'styled-components'
+import {get} from './constants'
+import TextInputWrapper, {StyledWrapperProps} from './_TextInputWrapper'
+
+type SelectProps = Omit<
+  Omit<React.HTMLProps<HTMLSelectElement>, 'size'> & StyledWrapperProps,
+  'multiple' | 'hasLeadingVisual' | 'hasTrailingVisual' | 'as'
+>
+
+const StyledSelect = styled.select`
+  appearance: none;
+  background-color: transparent;
+  border: 0;
+  color: currentColor;
+  outline: none;
+
+  /* colors the select input's placeholder text */
+  &:invalid {
+    color: ${get('colors.fg.subtle')};
+  }
+
+  /* For Firefox: reverts color of non-placeholder options in the dropdown */
+  &:invalid option:not(:first-child) {
+    color: ${get('colors.fg.default')};
+  }
+`
+
+const ArrowIndicatorSVG: React.FC<{className?: string}> = ({className}) => (
+  <svg width="16" height="16" fill="currentColor" xmlns="http://www.w3.org/2000/svg" className={className}>
+    <path d="m4.074 9.427 3.396 3.396a.25.25 0 0 0 .354 0l3.396-3.396A.25.25 0 0 0 11.043 9H4.251a.25.25 0 0 0-.177.427ZM4.074 7.47 7.47 4.073a.25.25 0 0 1 .354 0L11.22 7.47a.25.25 0 0 1-.177.426H4.251a.25.25 0 0 1-.177-.426Z" />
+  </svg>
+)
+
+const ArrowIndicator = styled(ArrowIndicatorSVG)`
+  pointer-events: none;
+  position: absolute;
+  right: 4px;
+  top: 50%;
+  transform: translateY(-50%);
+`
+
+const Select = React.forwardRef<HTMLSelectElement, SelectProps>(
+  ({children, disabled, placeholder, size, required, ref: _propsRef, ...rest}: SelectProps, ref) => (
+    <TextInputWrapper
+      sx={{
+        position: 'relative'
+      }}
+      size={size}
+    >
+      <StyledSelect
+        ref={ref}
+        required={required || Boolean(placeholder)}
+        disabled={disabled}
+        aria-required={required}
+        aria-disabled={disabled}
+        {...rest}
+      >
+        {placeholder ? (
+          <option value="" disabled={required} selected hidden={required}>
+            {placeholder}
+          </option>
+        ) : null}
+        {children}
+      </StyledSelect>
+      <ArrowIndicator />
+    </TextInputWrapper>
+  )
+)
+
+const Option: React.FC<React.HTMLProps<HTMLOptionElement> & {value: string}> = props => <option {...props} />
+
+const OptGroup: React.FC<React.HTMLProps<HTMLOptGroupElement>> = props => <optgroup {...props} />
+
+export default Object.assign(Select, {
+  Option,
+  OptGroup
+})

src/_TextInputWrapper.tsx

@@ -38,7 +38,7 @@ const sizeVariants = variant({
   }
 })
 
-type StyledWrapperProps = {
+export type StyledWrapperProps = {
   disabled?: boolean
   hasLeadingVisual?: boolean
   hasTrailingVisual?: boolean
@@ -80,7 +80,8 @@ const TextInputWrapper = styled.span<StyledWrapperProps>`
       padding-left: ${props.hasLeadingVisual ? textInputHorizPadding : 0};
       padding-right: ${props.hasTrailingVisual ? textInputHorizPadding : 0};
 
-      > input {
+      > input,
+      > select {
         padding-left: ${!props.hasLeadingVisual ? textInputHorizPadding : 0};
         padding-right: ${!props.hasTrailingVisual ? textInputHorizPadding : 0};
       }

src/__tests__/Select.test.tsx

@@ -0,0 +1,136 @@
+import React from 'react'
+import {Select} from '..'
+import {render} from '@testing-library/react'
+import {toHaveNoViolations} from 'jest-axe'
+import 'babel-polyfill'
+import '@testing-library/jest-dom'
+
+expect.extend(toHaveNoViolations)
+
+describe('Select', () => {
+  it('renders a select input', () => {
+    const {getByLabelText} = render(
+      <>
+        {/* eslint-disable-next-line jsx-a11y/label-has-for */}
+        <label htmlFor="default">Choice</label>
+        <Select id="default">
+          <Select.Option value="one">Choice one</Select.Option>
+          <Select.Option value="two">Choice two</Select.Option>
+          <Select.Option value="three">Choice three</Select.Option>
+          <Select.Option value="four">Choice four</Select.Option>
+          <Select.Option value="five">Choice five</Select.Option>
+          <Select.Option value="six">Choice six</Select.Option>
+        </Select>
+      </>
+    )
+
+    const select = getByLabelText('Choice')
+
+    expect(select).toBeDefined()
+  })
+
+  it('renders a select input with grouped options', () => {
+    const {getByLabelText} = render(
+      <>
+        {/* eslint-disable-next-line jsx-a11y/label-has-for */}
+        <label htmlFor="grouped">Choice</label>
+        <Select id="grouped">
+          <Select.OptGroup label="Group one">
+            <Select.Option value="one">Choice one</Select.Option>
+            <Select.Option value="two">Choice two</Select.Option>
+            <Select.Option value="three">Choice three</Select.Option>
+          </Select.OptGroup>
+          <Select.OptGroup label="Group two">
+            <Select.Option value="four">Choice four</Select.Option>
+            <Select.Option value="five">Choice five</Select.Option>
+            <Select.Option value="six">Choice six</Select.Option>
+          </Select.OptGroup>
+        </Select>
+      </>
+    )
+
+    const select = getByLabelText('Choice')
+
+    expect(select.querySelectorAll('optgroup')).toHaveLength(2)
+  })
+
+  it('renders a select input with a placeholder', () => {
+    const {getByText, getByLabelText} = render(
+      <>
+        {/* eslint-disable-next-line jsx-a11y/label-has-for */}
+        <label htmlFor="placeholder">Choice</label>
+        <Select id="placeholder" placeholder="Pick a choice">
+          <Select.Option value="one">Choice one</Select.Option>
+          <Select.Option value="two">Choice two</Select.Option>
+          <Select.Option value="three">Choice three</Select.Option>
+          <Select.Option value="four">Choice four</Select.Option>
+          <Select.Option value="five">Choice five</Select.Option>
+          <Select.Option value="six">Choice six</Select.Option>
+        </Select>
+      </>
+    )
+
+    const placeholderOption = getByText('Pick a choice')
+    const select = getByLabelText('Choice')
+
+    expect(select).not.toHaveAttribute('aria-required')
+
+    expect(placeholderOption).toBeDefined()
+    expect(placeholderOption.tagName.toLowerCase()).toBe('option')
+    // @ts-expect-error Property 'selected' does not exist on type 'HTMLElement'
+    expect(placeholderOption.selected).not.toBeNull()
+    expect(placeholderOption).not.toHaveAttribute('disabled')
+    expect(placeholderOption).not.toHaveAttribute('hidden')
+  })
+
+  it('renders a required select input with a placeholder', () => {
+    const {getByText, getByLabelText} = render(
+      <>
+        {/* eslint-disable-next-line jsx-a11y/label-has-for */}
+        <label htmlFor="reqWithPlaceholder">Choice</label>
+        <Select id="reqWithPlaceholder" placeholder="Pick a choice" required>
+          <Select.Option value="one">Choice one</Select.Option>
+          <Select.Option value="two">Choice two</Select.Option>
+          <Select.Option value="three">Choice three</Select.Option>
+          <Select.Option value="four">Choice four</Select.Option>
+          <Select.Option value="five">Choice five</Select.Option>
+          <Select.Option value="six">Choice six</Select.Option>
+        </Select>
+      </>
+    )
+
+    const placeholderOption = getByText('Pick a choice')
+    const select = getByLabelText('Choice')
+
+    expect(select).toHaveAttribute('aria-required')
+
+    expect(placeholderOption).toBeDefined()
+    expect(placeholderOption.tagName.toLowerCase()).toBe('option')
+    // @ts-expect-error Property 'selected' does not exist on type 'HTMLElement'
+    expect(placeholderOption.selected).not.toBeNull()
+    expect(placeholderOption).toHaveAttribute('disabled')
+    expect(placeholderOption).toHaveAttribute('hidden')
+  })
+
+  it('renders a disabled select input', () => {
+    const {getByLabelText} = render(
+      <>
+        {/* eslint-disable-next-line jsx-a11y/label-has-for */}
+        <label htmlFor="disabled">Choice</label>
+        <Select id="disabled" disabled>
+          <Select.Option value="one">Choice one</Select.Option>
+          <Select.Option value="two">Choice two</Select.Option>
+          <Select.Option value="three">Choice three</Select.Option>
+          <Select.Option value="four">Choice four</Select.Option>
+          <Select.Option value="five">Choice five</Select.Option>
+          <Select.Option value="six">Choice six</Select.Option>
+        </Select>
+      </>
+    )
+
+    const select = getByLabelText('Choice')
+
+    expect(select).toHaveAttribute('aria-disabled')
+    expect(select).toHaveAttribute('disabled')
+  })
+})