@primer/components 30.3.0-rc.2010c7d4 → 31.0.0-rc.15aa0a10

package/src/hooks/useOpenAndCloseFocus.ts

@@ -5,14 +5,19 @@ export type UseOpenAndCloseFocusSettings = {
   initialFocusRef?: React.RefObject<HTMLElement>
   containerRef: React.RefObject<HTMLElement>
   returnFocusRef: React.RefObject<HTMLElement>
+  preventFocusOnOpen?: boolean
 }
 
 export function useOpenAndCloseFocus({
   initialFocusRef,
   returnFocusRef,
-  containerRef
+  containerRef,
+  preventFocusOnOpen
 }: UseOpenAndCloseFocusSettings): void {
   useEffect(() => {
+    if (preventFocusOnOpen) {
+      return
+    }
     const returnRef = returnFocusRef.current
     if (initialFocusRef && initialFocusRef.current) {
       initialFocusRef.current.focus()
@@ -23,5 +28,5 @@ export function useOpenAndCloseFocus({
     return function () {
       returnRef?.focus()
     }
-  }, [initialFocusRef, returnFocusRef, containerRef])
+  }, [initialFocusRef, returnFocusRef, containerRef, preventFocusOnOpen])
 }

package/src/hooks/useOverlay.tsx

@@ -10,6 +10,7 @@ export type UseOverlaySettings = {
   onEscape: (e: KeyboardEvent) => void
   onClickOutside: (e: TouchOrMouseEvent) => void
   overlayRef?: React.RefObject<HTMLDivElement>
+  preventFocusOnOpen?: boolean
 }
 
 export type OverlayReturnProps = {
@@ -22,10 +23,11 @@ export const useOverlay = ({
   initialFocusRef,
   onEscape,
   ignoreClickRefs,
-  onClickOutside
+  onClickOutside,
+  preventFocusOnOpen
 }: UseOverlaySettings): OverlayReturnProps => {
   const overlayRef = useProvidedRefOrCreate<HTMLDivElement>(_overlayRef)
-  useOpenAndCloseFocus({containerRef: overlayRef, returnFocusRef, initialFocusRef})
+  useOpenAndCloseFocus({containerRef: overlayRef, returnFocusRef, initialFocusRef, preventFocusOnOpen})
   useOnOutsideClick({containerRef: overlayRef, ignoreClickRefs, onClickOutside})
   useOnEscapePress(onEscape)
   return {ref: overlayRef}

package/src/index.ts

@@ -30,6 +30,8 @@ export {useConfirm} from './Dialog/ConfirmationDialog'
 export {ActionList} from './ActionList'
 export {ActionMenu} from './ActionMenu'
 export type {ActionMenuProps} from './ActionMenu'
+export {default as Autocomplete} from './Autocomplete'
+export type {AutocompleteMenuProps, AutocompleteInputProps, AutocompleteOverlayProps} from './Autocomplete'
 export {default as Avatar} from './Avatar'
 export type {AvatarProps} from './Avatar'
 export {default as AvatarPair} from './AvatarPair'

package/src/stories/Autocomplete.stories.tsx

@@ -0,0 +1,572 @@
+import React, {ChangeEventHandler, RefObject, useCallback, useRef, useState} from 'react'
+import {Meta} from '@storybook/react'
+
+import {BaseStyles, Box, Text, TextInput, ThemeProvider} from '..'
+import TextInputTokens from '../TextInputWithTokens'
+import Autocomplete from '../Autocomplete/Autocomplete'
+import {AnchoredOverlay} from '../AnchoredOverlay'
+import {ButtonInvisible} from '../Button'
+
+type ItemMetadata = {
+  fillColor: React.CSSProperties['backgroundColor']
+}
+
+type Datum = {
+  id: string | number
+  text: string
+  selected?: boolean
+  metadata?: ItemMetadata
+}
+
+const items: Datum[] = [
+  {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},
+  {text: 'twenty', id: 20},
+  {text: 'twentyone', id: 21}
+]
+
+const mockTokens: Datum[] = [
+  {text: 'zero', id: 0},
+  {text: 'one', id: 1},
+  {text: 'three', id: 3},
+  {text: 'four', id: 4}
+]
+
+export default {
+  title: 'Forms/Autocomplete',
+
+  decorators: [
+    Story => {
+      const [lastKey, setLastKey] = useState('none')
+      const reportKey = useCallback((event: React.KeyboardEvent<HTMLDivElement>) => {
+        setLastKey(event.key)
+      }, [])
+
+      return (
+        <ThemeProvider>
+          <BaseStyles>
+            <Box onKeyDownCapture={reportKey}>
+              <Box position="absolute" right={5} top={2}>
+                Last key pressed: {lastKey}
+              </Box>
+              <Box paddingTop={5}>
+                <Story />
+              </Box>
+            </Box>
+          </BaseStyles>
+        </ThemeProvider>
+      )
+    }
+  ]
+} as Meta
+
+export const SingleSelect = () => {
+  return (
+    <>
+      <Box as="label" display="block" htmlFor="autocompleteInput" id="autocompleteLabel">
+        Pick an option
+      </Box>
+      <Autocomplete>
+        <Autocomplete.Input id="autocompleteInput" />
+        <Autocomplete.Overlay>
+          <Autocomplete.Menu items={items} selectedItemIds={[]} aria-labelledby="autocompleteLabel" />
+        </Autocomplete.Overlay>
+      </Autocomplete>
+    </>
+  )
+}
+
+export const MultiSelect = () => {
+  const [selectedItemIds, setSelectedItemIds] = useState<Array<string | number>>([])
+  const onSelectedChange = (newlySelectedItems: Datum | Datum[]) => {
+    if (!Array.isArray(newlySelectedItems)) {
+      return
+    }
+
+    setSelectedItemIds(newlySelectedItems.map(item => item.id))
+  }
+
+  const getItemById = (id: string | number) => items.find(item => item.id === id)
+
+  return (
+    <Box display="flex" sx={{gap: '1em'}}>
+      <div>
+        <Box as="label" display="block" htmlFor="autocompleteInput" id="autocompleteLabel">
+          Pick an option
+        </Box>
+        <Autocomplete>
+          <Autocomplete.Input id="autocompleteInput" />
+          <Autocomplete.Overlay>
+            <Autocomplete.Menu
+              items={items}
+              selectedItemIds={selectedItemIds}
+              aria-labelledby="autocompleteLabel"
+              onSelectedChange={onSelectedChange}
+              selectionVariant="multiple"
+            />
+          </Autocomplete.Overlay>
+        </Autocomplete>
+      </div>
+      <div>
+        <div>Selected items:</div>
+        <Box as="ul" my={0}>
+          {selectedItemIds.map(selectedItemId => (
+            <li key={selectedItemId}>{getItemById(selectedItemId)?.text}</li>
+          ))}
+        </Box>
+      </div>
+    </Box>
+  )
+}
+
+export const MultiSelectWithTokenInput = () => {
+  const [tokens, setTokens] = useState<Datum[]>(mockTokens)
+  const selectedTokenIds = tokens.map(token => token.id)
+  const [selectedItemIds, setSelectedItemIds] = useState<Array<string | number>>(selectedTokenIds)
+  const onTokenRemove: (tokenId: string | number) => void = tokenId => {
+    setTokens(tokens.filter(token => token.id !== tokenId))
+    setSelectedItemIds(selectedItemIds.filter(id => id !== tokenId))
+  }
+  const onSelectedChange = (newlySelectedItems: Datum | Datum[]) => {
+    if (!Array.isArray(newlySelectedItems)) {
+      return
+    }
+
+    setSelectedItemIds(newlySelectedItems.map(item => item.id))
+
+    if (newlySelectedItems.length < selectedItemIds.length) {
+      const newlySelectedItemIds = newlySelectedItems.map(({id}) => id)
+      const removedItemIds = selectedTokenIds.filter(id => !newlySelectedItemIds.includes(id))
+
+      for (const removedItemId of removedItemIds) {
+        onTokenRemove(removedItemId)
+      }
+
+      return
+    }
+
+    setTokens(newlySelectedItems.map(({id, text}) => ({id, text})))
+  }
+
+  return (
+    <>
+      <Box as="label" display="block" htmlFor="autocompleteInput" id="autocompleteLabel">
+        Pick options
+      </Box>
+      <Autocomplete>
+        <Autocomplete.Input as={TextInputTokens} tokens={tokens} onTokenRemove={onTokenRemove} id="autocompleteInput" />
+        <Autocomplete.Overlay>
+          <Autocomplete.Menu
+            items={items}
+            selectedItemIds={selectedItemIds}
+            onSelectedChange={onSelectedChange}
+            selectionVariant="multiple"
+            aria-labelledby="autocompleteLabel"
+          />
+        </Autocomplete.Overlay>
+      </Autocomplete>
+    </>
+  )
+}
+
+export const MultiSelectAddNewItem = () => {
+  const [localItemsState, setLocalItemsState] = useState<Datum[]>(items)
+  const [filterVal, setFilterVal] = useState<string>('')
+  const [tokens, setTokens] = useState<Datum[]>(mockTokens)
+  const selectedTokenIds = tokens.map(token => token.id)
+  const [selectedItemIds, setSelectedItemIds] = useState<Array<string | number>>(selectedTokenIds)
+  const onTokenRemove: (tokenId: string | number) => void = tokenId => {
+    setTokens(tokens.filter(token => token.id !== tokenId))
+    setSelectedItemIds(selectedItemIds.filter(id => id !== tokenId))
+  }
+  const onSelectedChange = (newlySelectedItems: Datum | Datum[]) => {
+    if (!Array.isArray(newlySelectedItems)) {
+      return
+    }
+
+    setSelectedItemIds(newlySelectedItems.map(item => item.id))
+
+    if (newlySelectedItems.length < selectedItemIds.length) {
+      const newlySelectedItemIds = newlySelectedItems.map(({id}) => id)
+      const removedItemIds = selectedTokenIds.filter(id => !newlySelectedItemIds.includes(id))
+
+      for (const removedItemId of removedItemIds) {
+        onTokenRemove(removedItemId)
+      }
+
+      return
+    }
+
+    setTokens(newlySelectedItems.map(({id, text}) => ({id, text})))
+  }
+
+  const onItemSelect: (item: Datum) => void = item => {
+    onSelectedChange([...selectedItemIds.map(id => items.find(selectedItem => selectedItem.id === id) as Datum), item])
+
+    if (!localItemsState.some(localItem => localItem.id === item.id)) {
+      setLocalItemsState([...localItemsState, item])
+    }
+  }
+
+  const handleChange: ChangeEventHandler<HTMLInputElement> = e => {
+    setFilterVal(e.currentTarget.value)
+  }
+
+  return (
+    <>
+      <Box as="label" display="block" htmlFor="autocompleteInput" id="autocompleteLabel">
+        Pick options
+      </Box>
+      <Autocomplete>
+        <Autocomplete.Input
+          as={TextInputTokens}
+          tokens={tokens}
+          onTokenRemove={onTokenRemove}
+          onChange={handleChange}
+          id="autocompleteInput"
+        />
+        <Autocomplete.Overlay>
+          <Autocomplete.Menu
+            addNewItem={
+              filterVal && !localItemsState.map(localItem => localItem.text).includes(filterVal)
+                ? {
+                    text: `Add '${filterVal}'`,
+                    handleAddItem: item => {
+                      onItemSelect({
+                        ...item,
+                        text: filterVal,
+                        selected: true
+                      })
+                      setFilterVal('')
+                    }
+                  }
+                : undefined
+            }
+            items={localItemsState}
+            selectedItemIds={selectedItemIds}
+            onSelectedChange={onSelectedChange}
+            selectionVariant="multiple"
+            aria-labelledby="autocompleteLabel"
+          />
+        </Autocomplete.Overlay>
+      </Autocomplete>
+    </>
+  )
+}
+
+export const CustomEmptyStateMessage = () => {
+  return (
+    <>
+      <Box as="label" display="block" htmlFor="autocompleteInput" id="autocompleteLabel">
+        Pick an option
+      </Box>
+      <Autocomplete>
+        <Autocomplete.Input id="autocompleteInput" />
+        <Autocomplete.Overlay>
+          <Autocomplete.Menu
+            items={items}
+            selectedItemIds={[]}
+            aria-labelledby="autocompleteLabel"
+            emptyStateText="Sorry, no matches"
+          />
+        </Autocomplete.Overlay>
+      </Autocomplete>
+    </>
+  )
+}
+
+export const CustomSearchFilter = () => {
+  const [filterVal, setFilterVal] = useState<string>('')
+  const handleChange: ChangeEventHandler<HTMLInputElement> = e => {
+    setFilterVal(e.currentTarget.value)
+  }
+  const customFilterFn = (item: Datum) => item.text.includes(filterVal)
+
+  return (
+    <>
+      <Box as="label" display="block" htmlFor="autocompleteInput" id="autocompleteLabel">
+        Pick an option
+      </Box>
+      <Autocomplete>
+        <Autocomplete.Input id="autocompleteInput" onChange={handleChange} />
+        <Autocomplete.Overlay>
+          <Autocomplete.Menu
+            items={items}
+            selectedItemIds={[]}
+            aria-labelledby="autocompleteLabel"
+            filterFn={customFilterFn}
+          />
+        </Autocomplete.Overlay>
+      </Autocomplete>
+      <Text fontSize={0} display="block" color="fg.subtle" mt={2}>
+        Items in dropdown are filtered if their text has no part that matches the input value
+      </Text>
+    </>
+  )
+}
+
+export const CustomSortAfterMenuClose = () => {
+  const [selectedItemIds, setSelectedItemIds] = useState<Array<string | number>>([])
+  const isItemSelected = (itemId: string | number) => selectedItemIds.includes(itemId)
+  const onSelectedChange = (newlySelectedItems: Datum | Datum[]) => {
+    if (!Array.isArray(newlySelectedItems)) {
+      return
+    }
+
+    setSelectedItemIds(newlySelectedItems.map(item => item.id))
+  }
+  const customSortFn = (itemIdA: string | number, itemIdB: string | number) =>
+    isItemSelected(itemIdA) === isItemSelected(itemIdB) ? 0 : isItemSelected(itemIdA) ? 1 : -1
+
+  return (
+    <>
+      <Box as="label" display="block" htmlFor="autocompleteInput" id="autocompleteLabel">
+        Pick an option
+      </Box>
+      <Autocomplete>
+        <Autocomplete.Input id="autocompleteInput" />
+        <Autocomplete.Overlay>
+          <Autocomplete.Menu
+            items={items}
+            selectedItemIds={selectedItemIds}
+            aria-labelledby="autocompleteLabel"
+            onSelectedChange={onSelectedChange}
+            sortOnCloseFn={customSortFn}
+            selectionVariant="multiple"
+          />
+        </Autocomplete.Overlay>
+      </Autocomplete>
+      <Text fontSize={0} display="block" color="fg.subtle" mt={2}>
+        When the dropdown closes, selected items are sorted to the end
+      </Text>
+    </>
+  )
+}
+
+export const WithCallbackWhenOverlayOpenStateChanges = () => {
+  const [isMenuOpen, setIsMenuOpen] = useState<boolean>(false)
+  const onOpenChange = (isOpen: boolean) => {
+    setIsMenuOpen(isOpen)
+  }
+
+  return (
+    <Box display="flex" sx={{gap: '1em'}}>
+      <div>
+        <Box as="label" display="block" htmlFor="autocompleteInput" id="autocompleteLabel">
+          Pick an option
+        </Box>
+        <Autocomplete>
+          <Autocomplete.Input id="autocompleteInput" />
+          <Autocomplete.Overlay>
+            <Autocomplete.Menu
+              items={items}
+              selectedItemIds={[]}
+              aria-labelledby="autocompleteLabel"
+              onOpenChange={onOpenChange}
+            />
+          </Autocomplete.Overlay>
+        </Autocomplete>
+      </div>
+      <div>
+        The menu is <strong>{isMenuOpen ? 'opened' : 'closed'}</strong>
+      </div>
+    </Box>
+  )
+}
+
+export const AsyncLoadingOfItems = () => {
+  const [loadedItems, setLoadedItems] = useState<Datum[]>([])
+  const onOpenChange = () => {
+    setTimeout(() => {
+      setLoadedItems(items)
+    }, 1500)
+  }
+
+  return (
+    <>
+      <Box as="label" display="block" htmlFor="autocompleteInput" id="autocompleteLabel">
+        Pick an option
+      </Box>
+      <Autocomplete>
+        <Autocomplete.Input id="autocompleteInput" />
+        <Autocomplete.Overlay>
+          <Autocomplete.Menu
+            items={loadedItems}
+            selectedItemIds={[]}
+            aria-labelledby="autocompleteLabel"
+            onOpenChange={onOpenChange}
+            loading={loadedItems.length === 0}
+          />
+        </Autocomplete.Overlay>
+      </Autocomplete>
+    </>
+  )
+}
+
+export const RenderingTheMenuOutsideAnOverlay = () => {
+  return (
+    <>
+      <Box as="label" display="block" htmlFor="autocompleteInput" id="autocompleteLabel">
+        Pick an option
+      </Box>
+      <Autocomplete>
+        <Autocomplete.Input id="autocompleteInput" />
+        <Autocomplete.Menu items={items} selectedItemIds={[]} aria-labelledby="autocompleteLabel" />
+      </Autocomplete>
+    </>
+  )
+}
+
+export const CustomOverlayMenuAnchor = () => {
+  const menuAnchorRef = useRef<HTMLElement>(null)
+  const anchorWrapperStyles = {
+    display: 'flex',
+    alignItems: 'center',
+    flexGrow: 1,
+    flexShrink: 0,
+    flexBasis: '25%',
+    border: '1px solid black',
+    padding: '1em'
+  }
+
+  return (
+    <>
+      <Box as="label" htmlFor="autocompleteInput" id="autocompleteLabel">
+        Pick labels
+      </Box>
+      <Box {...anchorWrapperStyles} ref={menuAnchorRef as React.RefObject<HTMLDivElement>}>
+        <Autocomplete>
+          <Autocomplete.Input
+            as={TextInput}
+            id="autocompleteInput"
+            sx={{
+              border: '0',
+              padding: '0',
+              boxShadow: 'none',
+              ':focus-within': {
+                border: '0',
+                boxShadow: 'none'
+              }
+            }}
+          />
+          <Autocomplete.Overlay menuAnchorRef={menuAnchorRef}>
+            <Autocomplete.Menu items={items} selectedItemIds={[]} aria-labelledby="autocompleteLabel" />
+          </Autocomplete.Overlay>
+        </Autocomplete>
+      </Box>
+      <Text fontSize={0} display="block" color="fg.subtle" mt={2}>
+        The overlay menu&apos;s position is anchored to the div with the black border instead of to the text input
+      </Text>
+    </>
+  )
+}
+
+export const WithCustomOverlayProps = () => {
+  return (
+    <>
+      <Box as="label" display="block" htmlFor="autocompleteInput" id="autocompleteLabel">
+        Pick an option
+      </Box>
+      <Autocomplete>
+        <Autocomplete.Input id="autocompleteInput" />
+        <Autocomplete.Overlay
+          overlayProps={{
+            width: 'large',
+            height: 'xsmall'
+          }}
+        >
+          <Autocomplete.Menu items={items} selectedItemIds={[]} aria-labelledby="autocompleteLabel" />
+        </Autocomplete.Overlay>
+      </Autocomplete>
+    </>
+  )
+}
+
+export const InOverlayWithCustomScrollContainerRef = () => {
+  const scrollContainerRef = useRef<HTMLElement>(null)
+  const inputRef = useRef<HTMLInputElement>(null)
+
+  const [isOpen, setIsOpen] = useState(false)
+  const handleOpen = () => {
+    setIsOpen(true)
+    inputRef.current && inputRef.current.focus()
+  }
+
+  return (
+    <AnchoredOverlay
+      open={isOpen}
+      onOpen={handleOpen}
+      onClose={() => setIsOpen(false)}
+      width="large"
+      height="xsmall"
+      focusTrapSettings={{initialFocusRef: inputRef}}
+      side="inside-top"
+      renderAnchor={props => <ButtonInvisible {...props}>open overlay</ButtonInvisible>}
+    >
+      <Box
+        as="label"
+        display="block"
+        htmlFor="autocompleteInput"
+        id="autocompleteLabel"
+        sx={{
+          // visually hides this label for sighted users
+          position: 'absolute',
+          width: '1px',
+          height: '1px',
+          padding: '0',
+          margin: '-1px',
+          overflow: 'hidden',
+          clip: 'rect(0, 0, 0, 0)',
+          whiteSpace: 'nowrap',
+          borderWidth: '0'
+        }}
+      >
+        Pick options
+      </Box>
+      <Autocomplete>
+        <Box display="flex" flexDirection="column" height="100%">
+          <Box
+            paddingX="3"
+            paddingY="1"
+            borderWidth={0}
+            borderBottomWidth={1}
+            borderColor="border.default"
+            borderStyle="solid"
+          >
+            <Autocomplete.Input
+              block
+              as={TextInput}
+              ref={inputRef}
+              id="autocompleteInput"
+              sx={{
+                display: 'flex',
+                border: '0',
+                padding: '0',
+                boxShadow: 'none',
+                ':focus-within': {
+                  border: '0',
+                  boxShadow: 'none'
+                }
+              }}
+            />
+          </Box>
+          <Box overflow="auto" flexGrow={1} ref={scrollContainerRef as RefObject<HTMLDivElement>}>
+            <Autocomplete.Menu
+              items={items}
+              selectedItemIds={[]}
+              // onSelectedChange={onSelectedChange}
+              customScrollContainerRef={scrollContainerRef}
+              aria-labelledby="autocompleteLabel"
+            />
+          </Box>
+        </Box>
+      </Autocomplete>
+    </AnchoredOverlay>
+  )
+}

package/src/stories/Dialog.stories.tsx

@@ -150,7 +150,7 @@ function CustomHeader({
   }, [onClose])
   if (typeof title === 'string' && typeof subtitle === 'string') {
     return (
-      <Box bg="auto.blue.3">
+      <Box bg="accent.subtle">
         <h1 id={dialogLabelId}>{title.toUpperCase()}</h1>
         <h2 id={dialogDescriptionId}>{subtitle.toLowerCase()}</h2>
         <Dialog.CloseButton onClose={onCloseClick} />
@@ -160,11 +160,11 @@ function CustomHeader({
   return null
 }
 function CustomBody({children}: React.PropsWithChildren<DialogProps>) {
-  return <Dialog.Body bg="auto.red.3">{children}</Dialog.Body>
+  return <Dialog.Body bg="danger.subtle">{children}</Dialog.Body>
 }
 function CustomFooter({footerButtons}: React.PropsWithChildren<DialogProps>) {
   return (
-    <Dialog.Footer bg="auto.yellow.3">
+    <Dialog.Footer bg="attention.subtle">
       {footerButtons ? <Dialog.Buttons buttons={footerButtons} /> : null}
     </Dialog.Footer>
   )

package/src/stories/IssueLabelToken.stories.tsx

@@ -47,7 +47,7 @@ const SingleExampleContainer: React.FC<{label?: string}> = ({children, label}) =
     }}
   >
     {label ? (
-      <Text fontSize={0} color="text.tertiary">
+      <Text fontSize={0} color="fg.muted">
         {label}
       </Text>
     ) : null}

package/src/stories/ProfileToken.stories.tsx

@@ -44,7 +44,7 @@ const SingleExampleContainer: React.FC<{label?: string}> = ({children, label}) =
     }}
   >
     {label ? (
-      <Text fontSize={0} color="text.tertiary">
+      <Text fontSize={0} color="fg.muted">
         {label}
       </Text>
     ) : null}

package/src/utils/types/MandateProps.ts

@@ -0,0 +1,19 @@
+/* 
+Used to convert a list of properties in a type from optional to required
+
+For example, we could make a new type from `Datum`
+where 'id' and 'label' required:
+  type Datum = {
+    description?: string
+    id?: string
+    label?: string
+    value: string
+  }
+
+  type DatumWithRequiredIdAndLabel = MandateProps<Datum, 'id' | 'label'>
+*/
+
+export type MandateProps<T extends unknown, K extends keyof T> = Omit<T, K> &
+  {
+    [MK in K]-?: NonNullable<T[MK]>
+  }

package/src/utils/types/index.ts

@@ -2,3 +2,4 @@ export * from './AriaRole'
 export * from './ComponentProps'
 export * from './Flatten'
 export * from './Merge'
+export * from './MandateProps'