Add KeybindingHint component

.changeset/short-boats-cover.md

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

.vscode/settings.json

@@ -13,11 +13,11 @@
   "json.schemas": [
     {
       "fileMatch": ["*.docs.json"],
-      "url": "./script/components-json/component.schema.json"
+      "url": "./packages/react/script/components-json/component.schema.json"
     },
     {
       "fileMatch": ["generated/components.json"],
-      "url": "./script/components-json/output.schema.json"
+      "url": "./packages/react/script/components-json/output.schema.json"
     }
   ]
 }

docs/content/KeybindingHint.mdx

@@ -0,0 +1,162 @@
+---
+title: KeybindingHint
+componentId: keybinding_hint
+status: Draft
+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, Button, Text, Box} from '@primer/react'
+import {KeybindingHint} from '@primer/react/drafts'
+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>
+
+```js
+import {KeybindingHint} from '@primer/react/drafts'
+```
+
+## 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 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 a space. 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": "draft",
+  "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.examples.stories.tsx

@@ -0,0 +1,64 @@
+import React from 'react'
+import type {Meta, StoryObj} from '@storybook/react'
+import {KeybindingHint, type KeybindingHintProps} from '.'
+import {Button, ActionList, FormControl, TextInput} from '..'
+
+export default {
+  title: 'Drafts/Components/KeybindingHint/Examples',
+  component: KeybindingHint,
+} satisfies Meta<typeof KeybindingHint>
+
+export const ButtonExample: StoryObj<KeybindingHintProps> = {
+  render: args => <Button trailingVisual={() => <KeybindingHint {...args} />}>Pull requests</Button>,
+  args: {keys: 'g p'},
+  name: 'Button',
+}
+
+export const PrimaryButton: StoryObj<KeybindingHintProps> = {
+  render: args => (
+    <Button variant="primary" trailingVisual={() => <KeybindingHint {...args} />}>
+      Submit
+    </Button>
+  ),
+  args: {keys: 'Mod+Enter', variant: 'onEmphasis'},
+}
+
+export const ActionListExample: StoryObj<KeybindingHintProps> = {
+  render: args => (
+    <ActionList sx={{maxWidth: '300px', border: '1px solid', borderColor: 'border.default', borderRadius: 2}}>
+      <ActionList.Item>Add comment</ActionList.Item>
+      <ActionList.Item>
+        Copy text{' '}
+        <ActionList.TrailingVisual>
+          <KeybindingHint {...args} />
+        </ActionList.TrailingVisual>
+      </ActionList.Item>
+      <ActionList.Item>Cancel</ActionList.Item>
+    </ActionList>
+  ),
+  args: {keys: 'Mod+c'},
+  name: 'ActionList',
+}
+
+export const Prose: StoryObj<KeybindingHintProps> = {
+  render: args => (
+    <p>
+      Press <KeybindingHint {...args} /> to toggle between write and preview modes.
+    </p>
+  ),
+  args: {
+    keys: 'Mod+Shift+P',
+    format: 'full',
+  },
+}
+
+export const TextInputExample: StoryObj<KeybindingHintProps> = {
+  render: args => (
+    <FormControl>
+      <FormControl.Label visuallyHidden>Search</FormControl.Label>
+      <TextInput trailingVisual={() => <KeybindingHint {...args} />} placeholder="Search" />
+    </FormControl>
+  ),
+  args: {keys: '/'},
+  name: 'TextInput',
+}

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

@@ -0,0 +1,30 @@
+import React from 'react'
+import type {Meta, StoryObj} from '@storybook/react'
+import {KeybindingHint, type KeybindingHintProps} from '.'
+import Box from '../Box'
+
+export default {
+  title: 'Drafts/Components/KeybindingHint/Features',
+  component: KeybindingHint,
+} satisfies Meta<typeof KeybindingHint>
+
+const chord = 'Mod+Shift+K'
+
+export const Condensed = {args: {keys: chord}}
+
+export const Full = {args: {keys: chord, format: 'full'}}
+
+const sequence = 'Mod+x y z'
+
+export const SequenceCondensed = {args: {keys: sequence}}
+
+export const SequenceFull = {args: {keys: sequence, format: 'full'}}
+
+export const OnEmphasis: StoryObj<KeybindingHintProps> = {
+  render: args => (
+    <Box sx={{backgroundColor: 'accent.fg', p: 3}}>
+      <KeybindingHint {...args} />
+    </Box>
+  ),
+  args: {keys: chord, variant: 'onEmphasis'},
+}

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

@@ -0,0 +1,9 @@
+import type {Meta} from '@storybook/react'
+import {KeybindingHint} from './KeybindingHint'
+
+export default {
+  title: 'Drafts/Components/KeybindingHint',
+  component: KeybindingHint,
+} satisfies Meta<typeof KeybindingHint>
+
+export const Default = {args: {keys: 'Mod+Shift+K'}}

packages/react/src/KeybindingHint/KeybindingHint.tsx

@@ -0,0 +1,48 @@
+import React, {type ReactNode} from 'react'
+import {memo} from 'react'
+import Text from '../Text'
+import type {KeybindingHintProps} from './props'
+import {accessibleSequenceString, Sequence} 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',
+      textWrap: 'nowrap',
+    }}
+  >
+    {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>
+    <Sequence {...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