@cube-dev/ui-kit 0.121.0 → 0.121.2

package/docs/components/content/HotKeys.md

@@ -0,0 +1,352 @@
+# 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)
+- **`aria-label`** `string` — Accessible label for the keyboard shortcuts
+- **`aria-description`** `string` — Additional description for the keyboard shortcuts
+
+### 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: `width`, `height`, `padding`, `margin`, `gap`, `flow`, `placeContent`, `placeItems`.
+
+#### type
+
+Defines the visual appearance of the keyboard shortcuts.
+
+**Type:** `'default' | 'primary' | 'inherit'`
+
+**Default:** `'default'`
+
+- `default` - Standard appearance with subtle background and border
+- `primary` - High contrast appearance with white text and border on transparent background
+- `inherit` - Adapts to parent's text color for both text and border, transparent background
+
+### 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