# HotKeys

A component that displays keyboard shortcuts in a visually appealing and accessible format using Tag components. It automatically formats key combinations, separates alternative shortcuts with "or" text, and provides comprehensive accessibility support for screen readers and other assistive technologies.

## When to Use

- Display keyboard shortcuts in tooltips or help documentation
- Show available hotkeys in command palettes or menus
- Provide visual feedback for keyboard navigation instructions
- Document keyboard shortcuts in user interfaces
- Create accessible keyboard shortcut references

## Component

---

### Properties

- **`children`** `string` — Key combination string (e.g., "mod+k, ctrl+k")
- **`type`** `'default' | 'primary' | 'inherit'` (default: `default`) — Visual appearance type: default (subtle), primary (high contrast), or inherit (adapts to parent color)

### Base Properties

Supports [Base properties](../../BaseProperties.md)

### Styling Properties

#### styles

Customizes the root element of the component (Space component).

**Sub-elements:**
- None - The component uses Tag components for individual keys

### Style Properties

These properties allow direct style application without using the `styles` prop:

- **Base:** `display`, `font`, `preset`, `hide`, `whiteSpace`, `opacity`, `transition`
- **Position:** `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `inset`, `position`
- **Dimension:** `width`, `height`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`
- **Block:** `border`, `radius`, `shadow`, `outline`, `padding`, `paddingInline`, `paddingBlock`, `overflow`, `scrollbar`, `textAlign`
- **Color:** `color`, `fill`, `fade`, `image`
- **Flow:** `flow`, `placeItems`, `placeContent`, `alignItems`, `alignContent`, `justifyItems`, `justifyContent`, `align`, `justify`, `gap`, `columnGap`, `rowGap`, `gridColumns`, `gridRows`, `gridTemplate`, `gridAreas`

### Accessibility Properties

#### label

Provides an accessible label for the keyboard shortcuts. If not provided, defaults to "Keyboard shortcuts".

#### description

Provides additional context about what the keyboard shortcuts do. This is announced by screen readers along with the shortcuts.

### Modifiers

The `mods` property accepts standard Space component modifiers.

## Examples

### Basic Usage

```jsx
<HotKeys>mod+k</HotKeys>
```

### Types

The HotKeys component supports different visual types:

#### Default Type

```jsx
<HotKeys>mod+k</HotKeys>
```

#### Primary Type

```jsx
<HotKeys type="primary" aria-label="Search">mod+k</HotKeys>
```

#### Inherit Type

The `inherit` type uses the current text color for the border and text, making it adapt to its parent's color context.

```jsx
<HotKeys type="inherit" aria-label="Search">mod+k</HotKeys>
```

#### Inherit Type in Context

The inherit type is particularly useful when the HotKeys component needs to match the surrounding text color:

```jsx
<div style={{ color: '#2563eb' }}>
  <span>Press </span>
  <HotKeys type="inherit" aria-label="Search">mod+k</HotKeys>
  <span> to search</span>
</div>
```

### With Accessibility Labels

```jsx
<HotKeys aria-label="Submit action">
  enter
</HotKeys>
```

### With Description

```jsx
<HotKeys 
  aria-label="Command palette"
  aria-description="Opens the command palette for quick actions"
>
  mod+shift+p
</HotKeys>
```

### Alternative Shortcuts

```jsx
<HotKeys 
  aria-label="Search"
  aria-description="Opens the search dialog"
>
  mod+k, ctrl+k
</HotKeys>
```

### Complex Alternatives

```jsx
<HotKeys 
  aria-label="Quick actions"
  aria-description="Multiple ways to access quick actions menu"
>
  mod+shift+p, ctrl+shift+p, alt+space
</HotKeys>
```

### Function Keys

```jsx
<HotKeys 
  aria-label="Help functions"
  aria-description="Function keys for help, rename, and search"
>
  f1, f2, f3
</HotKeys>
```

### Arrow Keys

```jsx
<HotKeys 
  aria-label="Navigation"
  aria-description="Arrow keys for directional navigation"
>
  up, down, left, right
</HotKeys>
```

### Special Keys

```jsx
<HotKeys 
  aria-label="Common actions"
  aria-description="Frequently used special keys"
>
  esc, enter, space, backspace, delete
</HotKeys>
```

### Platform-Specific Keys

```jsx
<HotKeys 
  aria-label="Copy"
  aria-description="Copy selected content to clipboard"
>
  mod+c, ctrl+c, cmd+c
</HotKeys>
```

### With Custom Styles

```jsx
<HotKeys 
  aria-label="Styled shortcuts"
  aria-description="Custom styled keyboard shortcuts"
  styles={{
    padding: '2x',
    fill: '#purple.10',
    radius: '1r',
  }}
>
  mod+k, ctrl+k
</HotKeys>
```

## Key Format

The component children accepts a string with the following format:

- **Single key**: `"enter"`, `"space"`, `"a"`
- **Key combinations**: `"mod+k"`, `"ctrl+shift+p"`
- **Multiple alternatives**: `"mod+k, ctrl+k"` (separated by commas)

### Supported Modifiers

- `mod` - Command (⌘) on macOS, Ctrl on Windows/Linux
- `ctrl`, `control` - Control key (⌃ on macOS, Ctrl on Windows/Linux)
- `alt`, `option` - Alt/Option key (⌥ on macOS, ⎇ on Windows/Linux)
- `shift` - Shift key (⇧)
- `meta`, `cmd`, `command` - Command key (⌘ on macOS, ⊞ on Windows/Linux)

### Special Keys

- `esc`, `escape` - Escape key (⎋)
- `enter`, `return` - Enter key (⏎)
- `space` - Space key (␣)
- `backspace` - Backspace key (⌫)
- `delete` - Delete key (⌦)

## Accessibility

The HotKeys component is designed with comprehensive accessibility support:

### Screen Reader Support

- **Semantic Structure**: Uses proper ARIA roles and grouping for logical organization
- **Descriptive Labels**: Each key combination is properly labeled for screen readers
- **Contextual Information**: Provides meaningful descriptions of what shortcuts do
- **Keyboard Shortcuts**: Individual keys are announced clearly with their symbolic representations
- **Alternative Separators**: The "or" text between alternatives is marked as decorative to avoid confusion

### ARIA Attributes

- `role="group"` - Identifies the component as a group of related keyboard shortcuts
- `aria-label` - Provides an accessible name for the shortcuts group (defaults to "Keyboard shortcuts")
- `aria-description` - Provides additional context about what the shortcuts do
- `role="text"` - Ensures individual keys are read as text content
- `aria-label` on individual keys - Provides clear pronunciation for each key
- `role="separator"` - Marks the "or" text as a separator between alternatives
- `aria-hidden="true"` - Hides decorative "or" text from screen readers to avoid redundancy

### Keyboard Navigation

- The component itself is not focusable as it's for display purposes only
- Individual keys are presented as non-interactive elements using semantic `<kbd>` tags
- Screen readers can navigate through the shortcuts using standard reading commands

### Semantic HTML

- Uses `<kbd>` elements for individual keys, which is the semantic HTML element for keyboard input
- Proper grouping structure with ARIA roles for logical organization
- Clear separation between different shortcut alternatives

## Best Practices

1. **Provide meaningful labels**: Always use the `aria-label` prop to describe what the shortcuts do
   ```jsx
   <HotKeys 
     aria-label="Search" 
     aria-description="Opens the search dialog"
   >
     mod+k
   </HotKeys>
   ```

2. **Use platform-appropriate modifiers**: Use `mod` instead of `ctrl` for cross-platform shortcuts
   ```jsx
   <HotKeys aria-label="Search">mod+k</HotKeys> // Good: Works on both Mac and PC
   <HotKeys aria-label="Search">ctrl+k</HotKeys> // Limited: PC-specific
   ```

3. **Group related alternatives**: Separate alternative shortcuts with commas
   ```jsx
   <HotKeys 
     aria-label="Search"
     aria-description="Opens search dialog"
   >
     mod+k, ctrl+k
   </HotKeys> // Good: Shows alternatives with context
   ```

4. **Provide descriptions for complex shortcuts**: Use the `aria-description` prop for clarity
   ```jsx
   <HotKeys 
     aria-label="Command palette"
     aria-description="Opens the command palette for quick actions"
   >
     mod+shift+p
   </HotKeys>
   ```

5. **Use clear, recognizable keys**: Stick to standard key names
   ```jsx
   <HotKeys aria-label="Confirm">enter, space</HotKeys> // Good: Clear key names
   <HotKeys aria-label="Confirm">ret, spc</HotKeys> // Avoid: Unclear abbreviations
   ```

6. **Keep combinations reasonable**: Avoid overly complex key combinations
   ```jsx
   <HotKeys aria-label="Command palette">mod+shift+p</HotKeys> // Good: Reasonable complexity
   <HotKeys aria-label="Command palette">mod+ctrl+shift+alt+p</HotKeys> // Avoid: Too complex
   ```

7. **Consider context**: Provide context about when and where shortcuts are available
   ```jsx
   <HotKeys 
     aria-label="Cancel"
     aria-description="Cancel current action and close dialog"
   >
     esc
   </HotKeys>
   ```

## Platform Behavior

The component automatically adapts key symbols based on the user's platform:

- **macOS**: Shows ⌘ for `mod`, ⌃ for `ctrl`, ⌥ for `alt`
- **Windows/Linux**: Shows Ctrl for `mod`, Ctrl for `ctrl`, ⎇ for `alt`

This ensures users see familiar symbols regardless of their operating system.

## Related Components

- [Tag](./Tag.md) - Individual key display component
- [Space](./Layout.md) - Layout container used internally
- Text - Used for separator text
- [Tooltip](../overlays/Tooltip.md) - Often used together to show shortcuts

## Suggested Improvements

- Add support for mouse button indicators (e.g., "Click + Drag")
- Consider adding animation for key press feedback
- Support for custom key symbol mappings
- Integration with system accessibility preferences
- Support for voice command alternatives 
