Add KeybindingHint component

.changeset/short-boats-cover.md

@@ -0,0 +1,5 @@
+---
+'@primer/react': minor
+---
+
+Add `KeybindingHint` component for indicating an available keyboard shortcut

docs/content/KeybindingHint.mdx

@@ -0,0 +1,157 @@
+---
+title: KeybindingHint
+componentId: keybinding_hint
+status: Alpha
+source: https://github.com/primer/react/tree/main/packages/react/src/KeybindingHint
+storybook: '/react/storybook?path=/story/components-keybindinghint'
+description: Indicates the presence of a keybinding available for an action.
+---
+
+import data from '../../packages/react/src/KeybindingHint/KeybindingHint.docs.json'
+import {ActionList, KeybindingHint, Button, Text, Box} from '@primer/react'
+import {TrashIcon} from '@primer/octicons-react'
+
+Use `KeybindingHint` to make keyboard shortcuts discoverable. Can render visual keybinding hints in condensed (abbreviated) form or expanded form, and provides accessible alternative text for screen reader users.
+
+<Box sx={{border: '1px solid', borderColor: 'border.default', borderRadius: 2, padding: 6, marginBottom: 3}}>
+  <ActionList sx={{width: 320}}>
+    <ActionList.Item>
+      Move down
+      <ActionList.TrailingVisual>
+        <KeybindingHint keys="Mod+ArrowDown" />
+      </ActionList.TrailingVisual>
+    </ActionList.Item>
+    <ActionList.Item>
+      Unsubscribe
+      <ActionList.TrailingVisual>
+        <KeybindingHint keys="i j" />
+      </ActionList.TrailingVisual>
+    </ActionList.Item>
+    <ActionList.Item variant="danger">
+      <ActionList.LeadingVisual>
+        <TrashIcon />
+      </ActionList.LeadingVisual>
+      Delete
+      <ActionList.TrailingVisual>
+        <KeybindingHint keys="Mod+Shift+Delete" />
+      </ActionList.TrailingVisual>
+    </ActionList.Item>
+  </ActionList>
+</Box>
+
+## Examples
+
+### Single keys
+
+Use the [full names of the keys as returned by `KeyboardEvent.key`](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values). Key names are case-insensitive.
+
+```javascript live noinline
+render(
+  <>
+    <KeybindingHint keys="a" /> <br />
+    <KeybindingHint keys="B" /> <br />
+    <KeybindingHint keys="ArrowLeft" /> <br />
+    <KeybindingHint keys="shift" />
+  </>,
+)
+```
+
+#### Special key names
+
+Because the `+` and ` `&nbsp;(space) characters are used to build chords and sequences as described below, their names must be spelled out to be used as keys.
+
+```javascript live noinline
+render(
+  <>
+    <KeybindingHint keys="Plus" /> <br />
+    <KeybindingHint keys="Space" />
+  </>,
+)
+```
+
+### Chords
+
+_Chords_ are multiple keys that are pressed at the same time. Combine keys in a chord with `+`. Keys are automatically sorted into a standardized order so that modifiers come first.
+
+```javascript live noinline
+render(
+  <>
+    <KeybindingHint keys="Alt+a" /> <br />
+    <KeybindingHint keys="a+Alt" /> <br />
+    <KeybindingHint keys="Control+Shift+ArrowUp" /> <br />
+    <KeybindingHint keys="Meta+Shift+&" />
+  </>,
+)
+```
+
+#### Platform-dependent modifier
+
+Typical chords use `Command` on MacOS and `Control` on other devices. To automatically render `Command` or `Control` based on the user's operating system, use the special key name `Mod`.
+
+```javascript live noinline
+render(<KeybindingHint keys="Mod+Shift+X" />)
+```
+
+### Sequences
+
+_Sequences_ are keys or chords that are pressed one after the other. Combine elements in a sequence with ` `. For example, `a b` means "press a, then press b".
+
+```javascript live noinline
+render(
+  <>
+    <KeybindingHint keys="a b" /> <br />
+    <KeybindingHint keys="Mod+g ArrowLeft" />
+  </>,
+)
+```
+
+### Full display format
+
+The default `condensed` format should be used on UI elements like buttons, menuitems, and inputs. In long-form text (prose), the `full` variant can be used instead to help the text flow better.
+
+```javascript live noinline
+render(
+  <Text>
+    Press <KeybindingHint keys="Mod+Enter" format="ful" /> to submit the form.
+  </Text>,
+)
+```
+
+### `onEmphasis` variant
+
+When rendering on 'emphasis' colors, use the `onEmphasis` variant.
+
+```javascript live noinline
+const CmdEnterHint = () => <KeybindingHint variant="onEmphasis" keys="Mod+Enter" />
+
+render(
+  <Button variant="primary" trailingVisual={CmdEnterHint}>
+    Submit
+  </Button>,
+)
+```
+
+## Props
+
+<ComponentProps data={data} />
+
+## Status
+
+<ComponentChecklist
+  items={{
+    propsDocumented: true,
+    noUnnecessaryDeps: true,
+    adaptsToThemes: true,
+    adaptsToScreenSizes: true,
+    fullTestCoverage: true,
+    usedInProduction: true,
+    usageExamplesDocumented: true,
+    hasStorybookStories: true,
+    designReviewed: false,
+    a11yReviewed: false,
+    stableApi: false,
+    addressedApiFeedback: false,
+    hasDesignGuidelines: false,
+    hasFigmaComponent: false,
+  }}
+/>

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

@@ -82,6 +82,8 @@
       url: /Heading
     - title: IconButton
       url: /IconButton
+    - title: KeybindingHint
+      url: /KeybindingHint
     - title: Label
       url: /Label
     - title: LabelGroup

packages/react/src/KeybindingHint/KeybindingHint.docs.json

@@ -0,0 +1,28 @@
+{
+  "id": "KeybindingHint",
+  "name": "KeybindingHint",
+  "status": "alpha",
+  "a11yReviewed": false,
+  "stories": [],
+  "importPath": "@primer/react",
+  "props": [
+    {
+      "name": "keys",
+      "type": "string",
+      "description": "The keys involved in this keybinding."
+    },
+    {
+      "name": "format",
+      "type": "'condensed' | 'full'",
+      "defaultValue": "'condensed'",
+      "description": "Control the display format."
+    },
+    {
+      "name": "variant",
+      "type": "'normal' | 'onEmphasis'",
+      "defaultValue": "'normal'",
+      "description": "Set to `onEmphasis` for display on 'emphasis' colors."
+    }
+  ],
+  "subcomponents": []
+}

packages/react/src/KeybindingHint/KeybindingHint.stories.tsx

@@ -0,0 +1,28 @@
+import type React from 'react'
+import type {Meta} from '@storybook/react'
+import {KeybindingHint} from './KeybindingHint'
+
+type KeybindingHintProps = React.ComponentProps<typeof KeybindingHint>
+
+const args = {
+  keys: 'Mod+Shift+K',
+} satisfies KeybindingHintProps
+
+const meta = {
+  title: 'Components/KeybindingHint',
+  component: KeybindingHint,
+} satisfies Meta<typeof KeybindingHint>
+
+export default meta
+
+export const Condensed = {args}
+
+export const Full = {args: {...args, format: 'full'}}
+
+const sequenceArgs = {
+  keys: 'Mod+x y z',
+} satisfies KeybindingHintProps
+
+export const SequenceCondensed = {args: sequenceArgs}
+
+export const SequenceFull = {args: {...sequenceArgs, format: 'full'}}

packages/react/src/KeybindingHint/KeybindingHint.tsx

@@ -0,0 +1,49 @@
+import React, {type ReactNode} from 'react'
+import {memo} from 'react'
+import Text from '../Text'
+
+import {Chord} from './components/Chord'
+import type {KeybindingHintProps} from './props'
+import {accessibleSequenceString} from './components/Sequence'
+
+/** `kbd` element with style resets. */
+const Kbd = ({children}: {children: ReactNode}) => (
+  <Text
+    as={'kbd' as 'span'}
+    sx={{
+      color: 'inherit',
+      fontFamily: 'inherit',
+      fontSize: 'inherit',
+      border: 'none',
+      background: 'none',
+      boxShadow: 'none',
+      p: 0,
+      lineHeight: 'unset',
+      position: 'relative',
+      overflow: 'visible',
+      verticalAlign: 'baseline',
+    }}
+  >
+    {children}
+  </Text>
+)
+
+/** Indicates the presence of an available keybinding. */
+// KeybindingHint is a good candidate for memoizing since props will rarely change
+export const KeybindingHint = memo((props: KeybindingHintProps) => (
+  <Kbd>
+    <Chord {...props} />
+  </Kbd>
+))
+KeybindingHint.displayName = 'KeybindingHint'
+
+/**
+ * AVOID: `KeybindingHint` is nearly always sufficient for providing both visible and accessible keyboard hints, and
+ * will result in a good screen reader experience when used as the target for `aria-describedby` and `aria-labelledby`.
+ * However, there may be cases where we need a plain string version, such as when building `aria-label` or
+ * `aria-description`. In that case, this plain string builder can be used instead.
+ *
+ * NOTE that this string should _only_ be used when building `aria-label` or `aria-description` props (never rendered
+ * visibly) and should nearly always also be paired with a visible hint for sighted users.
+ */
+export const getAccessibleKeybindingHintString = accessibleSequenceString

packages/react/src/KeybindingHint/components/Chord.tsx

@@ -0,0 +1,70 @@
+import React, {Fragment} from 'react'
+import Text from '../../Text'
+import type {KeybindingHintProps} from '../props'
+import {Key} from './Key'
+import {accessibleKeyName} from '../key-names'
+
+/**
+ * Consistent sort order for modifier keys. There should never be more than one non-modifier
+ * key in a chord, so we don't need to worry about sorting those - we just put them at
+ * the end.
+ */
+const keySortPriorities: Partial<Record<string, number>> = {
+  control: 1,
+  meta: 2,
+  alt: 3,
+  option: 4,
+  shift: 5,
+  function: 6,
+}
+
+const keySortPriority = (priority: string) => keySortPriorities[priority] ?? Infinity
+
+const compareLowercaseKeys = (a: string, b: string) => keySortPriority(a) - keySortPriority(b)
+
+/** Split and sort the chord keys in standard order. */
+const splitChord = (chord: string) =>
+  chord
+    .split('+')
+    .map(k => k.toLowerCase())
+    .sort(compareLowercaseKeys)
+
+export const Chord = ({keys, format = 'condensed', variant = 'normal'}: KeybindingHintProps) => (
+  <Text
+    sx={{
+      display: 'inline-flex',
+      bg: variant === 'onEmphasis' ? 'transparent' : 'canvas.default',
+      color: variant === 'onEmphasis' ? 'fg.onEmphasis' : 'fg.muted',
+      border: '1px solid',
+      borderColor: 'border.default',
+      borderRadius: 2,
+      fontWeight: 'normal',
+      fontFamily: 'normal',
+      fontSize: 0,
+      p: 1,
+      gap: '0.5ch',
+      boxShadow: 'none',
+      verticalAlign: 'baseline',
+      overflow: 'hidden',
+      lineHeight: '10px',
+    }}
+  >
+    {splitChord(keys).map((k, i) => (
+      <Fragment key={i}>
+        {i > 0 && format === 'full' ? (
+          <span aria-hidden> + </span> // hiding the plus sign helps screen readers be more concise
+        ) : (
+          ' ' // space is nonvisual due to flex layout but critical for labelling / screen readers
+        )}
+
+        <Key name={k} format={format} />
+      </Fragment>
+    ))}
+  </Text>
+)
+
+/** Plain string version of `Chord` for use in `aria` string attributes. */
+export const accessibleChordString = (chord: string, isMacOS: boolean) =>
+  splitChord(chord)
+    .map(key => accessibleKeyName(key, isMacOS))
+    .join(' ')

packages/react/src/KeybindingHint/components/Key.tsx

@@ -0,0 +1,22 @@
+import React from 'react'
+import VisuallyHidden from '../../_VisuallyHidden'
+import {accessibleKeyName, condensedKeyName, fullKeyName} from '../key-names'
+import type {KeybindingHintFormat} from '../props'
+import {useIsMacOS} from '../../hooks/useIsMacOS'
+
+interface KeyProps {
+  name: string
+  format: KeybindingHintFormat
+}
+
+/** Renders a single key with accessible alternative text. */
+export const Key = ({name, format}: KeyProps) => {
+  const isMacOS = useIsMacOS()
+
+  return (
+    <>
+      <VisuallyHidden>{accessibleKeyName(name, isMacOS)}</VisuallyHidden>
+      <span aria-hidden>{format === 'condensed' ? condensedKeyName(name, isMacOS) : fullKeyName(name, isMacOS)}</span>
+    </>
+  )
+}