@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/components/kbd.md

@@ -0,0 +1,423 @@
+# Kbd
+
+Shows a keyboard key or shortcut.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Kbd.tsx)
+
+Figma: [Keyboard Key](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5402-2104)
+
+## Overview
+
+Kbd renders a key or shortcut in a native `<kbd>` element. Pass the main key as children and modifiers as props. Modifiers follow the platform's conventions, and screen readers announce them by name.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Kbd } from '@tempoxyz/ds'
+
+export function Demo() {
+  return <Kbd>Esc</Kbd>
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Kbd/Basic.tsx)
+
+### Modifiers
+
+Set `ctrl`, `alt`, `shift`, or `meta` to add modifiers before the key. Apple platforms show the glyphs `⌃`, `⌥`, `⇧`, and `⌘`, always in that order. Windows and Linux show Win (Super on Linux), Ctrl, Alt, and Shift, in that order.
+
+Set `mod` for the primary shortcut modifier, which is `⌘` on Apple platforms and Ctrl elsewhere.
+
+```tsx
+import { Kbd, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <Kbd mod>K</Kbd>
+      <Kbd meta>K</Kbd>
+      <Kbd shift>P</Kbd>
+      <Kbd alt>Space</Kbd>
+      <Kbd ctrl>C</Kbd>
+      <Kbd alt meta shift>
+        T
+      </Kbd>
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '8' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Kbd/Modifiers.tsx)
+
+### Platform
+
+Kbd reads the browser's platform after hydration, and the server renders Apple glyphs. If the request identifies the platform, set `platform` so the server renders the final labels. The `Sec-CH-UA-Platform` request header maps to `platform` as follows:
+
+| `Sec-CH-UA-Platform`                                   | `platform`      |
+| ------------------------------------------------------ | --------------- |
+| `"iOS"`, `"macOS"`                                     | `apple`         |
+| `"Android"`, `"Chrome OS"`, `"Chromium OS"`, `"Linux"` | `linux`         |
+| `"Windows"`                                            | `windows`       |
+| `"Unknown"`, or no header                              | Omit `platform` |
+
+Kbd ignores any other `platform` value, such as the raw header, and reads the browser's platform instead.
+
+```tsx
+import { Kbd, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      {(['apple', 'linux', 'windows'] as const).map((platform) => (
+        <div key={platform} {...styles.row()}>
+          <Kbd mod platform={platform} shift>
+            P
+          </Kbd>
+          <Kbd meta platform={platform}>
+            K
+          </Kbd>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '8' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Kbd/Platform.tsx)
+
+### Size
+
+Set `size` to `small`, `medium` (default), or `large`.
+
+```tsx
+import { Kbd, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      {(['small', 'medium', 'large'] as const).map((size) => (
+        <div key={size} {...styles.row()}>
+          <Kbd size={size}>Esc</Kbd>
+          <Kbd mod size={size}>
+            K
+          </Kbd>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '8' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Kbd/Size.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Kbd } from '@tempoxyz/ds'
+
+<Kbd />
+```
+
+## Guidelines
+
+### When to Use
+
+* Show the shortcut beside its action, such as in a [Menu](/docs/components/menu) item, a [Tooltip](/docs/components/tooltip), or a search field hint.
+* Name keys in instructions, such as Press Esc to close.
+
+### When Not to Use
+
+* Use [Snippet](/docs/components/snippet) for terminal commands.
+* Use [Badge](/docs/components/badge) for a status or attribute.
+* Use a visible [Button](/docs/components/button) to run an action. A shortcut only makes it faster.
+
+### Use Modifier Props
+
+Kbd orders and labels modifier props for the reader's platform. Glyphs typed into children lose the platform labels, the order, and the spoken names. Screen readers may skip or misread a typed `⌘`.
+
+**Do:** Set modifier props and pass the main key as children.
+
+```tsx
+/**
+ * Do example for "Use Modifier Props" on the Kbd page.
+ * Set modifier props and pass the main key as children.
+ * @module
+ */
+import { Kbd, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <span {...styles.label()}>Open command menu</span>
+      <Kbd mod shift size="small">
+        P
+      </Kbd>
+    </div>
+  )
+}
+
+namespace styles {
+  export const label = style({ color: 'content.primary', typography: 'body.b2' })
+
+  export const row = style({
+    alignItems: 'center',
+    display: 'flex',
+    gap: '16',
+    justifyContent: 'space-between',
+    width: '100% !custom',
+  })
+}
+```
+
+**Don't:** Type modifier glyphs into children.
+
+```tsx
+/** Don't example for "Use Modifier Props" on the Kbd page. Don't type modifier glyphs into children. @module */
+import { Kbd, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <span {...styles.label()}>Open command menu</span>
+      <Kbd size="small">⌘⇧P</Kbd>
+    </div>
+  )
+}
+
+namespace styles {
+  export const label = style({ color: 'content.primary', typography: 'body.b2' })
+
+  export const row = style({
+    alignItems: 'center',
+    display: 'flex',
+    gap: '16',
+    justifyContent: 'space-between',
+    width: '100% !custom',
+  })
+}
+```
+
+### Show the Platform's Modifier
+
+Set `mod` for shortcuts that take Command on macOS and Ctrl on Windows and Linux, so the hint matches the keys people press. Set `meta` only when the shortcut takes Command on macOS and the Windows or Super key elsewhere.
+
+* **macOS (mod):** `mod` renders `⌘` for Command shortcuts on macOS.
+* **Windows and Linux (mod):** `mod` renders Ctrl for the same shortcut on Windows and Linux.
+
+### Use One Kbd per Chord
+
+One `Kbd` shows keys pressed together.
+
+**Do:** For a sequence, use one `Kbd` per step with a word between them.
+
+```tsx
+/**
+ * Do example for "Use One Kbd per Chord" on the Kbd page.
+ * For a sequence, use one `Kbd` per step with a word between them.
+ * @module
+ */
+import { Kbd, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <span {...styles.label()}>Go to activity</span>
+      <span {...styles.keys()}>
+        <Kbd size="small">G</Kbd>
+        then
+        <Kbd size="small">A</Kbd>
+      </span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const keys = style({
+    alignItems: 'center',
+    color: 'content.secondary',
+    display: 'flex',
+    gap: '4',
+    typography: 'body.b3',
+  })
+
+  export const label = style({ color: 'content.primary', typography: 'body.b2' })
+
+  export const row = style({
+    alignItems: 'center',
+    display: 'flex',
+    gap: '16',
+    justifyContent: 'space-between',
+    width: '100% !custom',
+  })
+}
+```
+
+**Don't:** Put the steps of a sequence in one `Kbd`.
+
+```tsx
+/**
+ * Don't example for "Use One Kbd per Chord" on the Kbd page.
+ * Don't put the steps of a sequence in one `Kbd`.
+ * @module
+ */
+import { Kbd, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <span {...styles.label()}>Go to activity</span>
+      <Kbd size="small">G A</Kbd>
+    </div>
+  )
+}
+
+namespace styles {
+  export const label = style({ color: 'content.primary', typography: 'body.b2' })
+
+  export const row = style({
+    alignItems: 'center',
+    display: 'flex',
+    gap: '16',
+    justifyContent: 'space-between',
+    width: '100% !custom',
+  })
+}
+```
+
+### Keep Shortcuts Optional
+
+If a shortcut is a single character, such as `/`, let people turn it off or remap it ([Character Key Shortcuts](https://www.w3.org/WAI/WCAG22/Understanding/character-key-shortcuts.html)).
+
+**Do:** Give every shortcut a visible control that does the same thing.
+
+```tsx
+/**
+ * Do example for "Keep Shortcuts Optional" on the Kbd page.
+ * Give every shortcut a visible control that does the same thing.
+ * @module
+ */
+import { Kbd, style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <TextInput.Group {...styles.field()}>
+      <TextInput.Control
+        aria-keyshortcuts="Meta+K Control+K"
+        aria-label="Search"
+        placeholder="Search payments"
+      />
+      <TextInput.Suffix>
+        <Kbd mod size="small">
+          K
+        </Kbd>
+      </TextInput.Suffix>
+    </TextInput.Group>
+  )
+}
+
+namespace styles {
+  export const field = style({ width: '100% !custom' })
+}
+```
+
+**Don't:** Make a shortcut the only way to reach an action.
+
+```tsx
+/**
+ * Don't example for "Keep Shortcuts Optional" on the Kbd page.
+ * Don't make a shortcut the only way to reach an action.
+ * @module
+ */
+import { Kbd, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <span {...styles.hint()}>
+      Press
+      <Kbd mod size="small">
+        K
+      </Kbd>
+      to search payments
+    </span>
+  )
+}
+
+namespace styles {
+  export const hint = style({
+    alignItems: 'center',
+    color: 'content.secondary',
+    display: 'flex',
+    gap: '4',
+    typography: 'body.b2',
+  })
+}
+```
+
+### Match Size to the Text
+
+Heights match static badges.
+
+* **Small (20px):** For menus and tooltips.
+* **Medium (24px):** The default, for body text.
+* **Large (32px):** Beside large controls.
+
+## Content
+
+* **Key names:** Write them as printed on keys, such as Esc, Enter, Tab, and Space.
+* **Letter keys:** Write them as capitals, such as K, even without Shift.
+* **Verb:** Write Press, not Hit or Type.
+
+## Accessibility
+
+Kbd renders a native `<kbd>` element and is not interactive.
+
+### Semantics
+
+* **Root (kbd):** Marks the text as keyboard input.
+* **Modifier Props (aria-hidden):** Each label, such as ⌘ or Ctrl, is hidden. Screen readers read the key's name instead.
+* **Modifier Order:** Modifiers render in the platform's order, such as Control, Option, Shift, Command on macOS, whatever the order of the props.
+
+### Keyboard
+
+* **Display Only:** Kbd takes no focus and does not listen for key presses. Your app registers the shortcut.
+* **Declare the Shortcut (aria-keyshortcuts):** Set it on the control the shortcut triggers, such as `aria-keyshortcuts="Meta+K Control+K"` for a search field that accepts both.
+
+## Related
+
+[Menu](/docs/components/menu)
+
+Use for actions with shortcuts.
+
+[Tooltip](/docs/components/tooltip)
+
+Use for labelling icon buttons.
+
+[Snippet](/docs/components/snippet)
+
+Use for terminal commands.
+
+[Badge](/docs/components/badge)
+
+Use for statuses and attributes.