Create platform-aware keyboard shortcuts with automatic detection of Apple vs non-Apple platforms
npm install @portabletext/keyboard-shortcuts@portabletext/keyboard-shortcutsA TypeScript library for creating platform-aware keyboard shortcuts with automatic detection of Apple vs non-Apple platforms.
- Platform Detection: Automatically detects Apple platforms and uses appropriate key combinations
- Flexible Definitions: Support for multiple key combinations per shortcut
- Event Matching: Built-in keyboard event matching functionality
- Common Shortcuts: Pre-defined shortcuts for common text editing operations
``bash`
npm install @portabletext/keyboard-shortcuts
Defines a single keyboard event that can be part of a shortcut.
`typescript`
type KeyboardEventDefinition = (
| {key: KeyboardEvent['key']; code: KeyboardEvent['code']}
| {key: KeyboardEvent['key']; code?: undefined}
| {key?: undefined; code: KeyboardEvent['code']}
) & {
alt?: KeyboardEvent['altKey']
ctrl?: KeyboardEvent['ctrlKey']
meta?: KeyboardEvent['metaKey']
shift?: KeyboardEvent['shiftKey']
}
Properties:
- key: The keyboard key (case-insensitive)code
- : The keyboard code (case-insensitive)alt
- : Alt/Option key modifierctrl
- : Ctrl key modifiermeta
- : Meta/Command key modifiershift
- : Shift key modifier
At least one of key or code must be provided.
Defines a complete keyboard shortcut with platform-specific configurations.
`typescript`
type KeyboardShortcutDefinition = {
default: ReadonlyArray
apple?: ReadonlyArray
}
Properties:
- default: Required array of keyboard event definitions for non-Apple platformsapple
- : Optional array of keyboard event definitions for Apple platforms (falls back to default if not provided)
A resolved keyboard shortcut for the current platform.
`typescript`
type KeyboardShortcut
guard: (event: TKeyboardEvent) => boolean
keys: ReadonlyArray
}
Properties:
- guard: Function that determines if a keyboard event matches this shortcutkeys
- : Display-friendly key combination for the current platform
#### createKeyboardShortcut(definition)
Creates a KeyboardShortcut from a KeyboardShortcutDefinition.
`typescript`
function createKeyboardShortcut
definition: KeyboardShortcutDefinition,
): KeyboardShortcut
Example:
`typescript
import {createKeyboardShortcut} from '@portabletext/keyboard-shortcuts'
const boldShortcut = createKeyboardShortcut({
default: [
{
key: 'B',
ctrl: true,
meta: false,
alt: false,
shift: false,
},
],
apple: [
{
key: 'B',
ctrl: false,
meta: true,
alt: false,
shift: false,
},
],
})
// On non-Apple platforms: Ctrl+B
// On Apple platforms: ⌘+B
`
Example:
`typescript
import {isKeyboardShortcut} from '@portabletext/keyboard-shortcuts'
const definition = {
key: 'B',
ctrl: true,
meta: false,
alt: false,
shift: false,
}
const isMatch = isKeyboardShortcut(definition, keyboardEvent)
`
The library provides pre-defined shortcuts for common text editing operations:
`typescript`
import {
blockquote,
bold,
code,
h1,
h2,
h3,
h4,
h5,
h6,
italic,
link,
normal,
strikeThrough,
underline,
} from '@portabletext/keyboard-shortcuts'
#### Basic Usage
`typescript
import {createKeyboardShortcut} from '@portabletext/keyboard-shortcuts'
const saveShortcut = createKeyboardShortcut({
default: [
{
key: 'S',
ctrl: true,
meta: false,
alt: false,
shift: false,
},
],
apple: [
{
key: 'S',
ctrl: false,
meta: true,
alt: false,
shift: false,
},
],
})
// Use the shortcut
document.addEventListener('keydown', (event) => {
if (saveShortcut.guard(event)) {
event.preventDefault()
saveDocument()
}
})
// Display the shortcut keys
console.log(saveShortcut.keys.join('+')) // "Ctrl+S" or "⌘+S"
`
#### Using Pre-defined Shortcuts
`typescript
import {bold, italic} from '@portabletext/keyboard-shortcuts'
document.addEventListener('keydown', (event) => {
if (bold.guard(event)) {
event.preventDefault()
toggleBold()
} else if (italic.guard(event)) {
event.preventDefault()
toggleItalic()
}
})
`
#### Multiple Key Combinations
`typescript``
const deleteShortcut = createKeyboardShortcut({
default: [
{key: 'Delete', ctrl: false, meta: false, alt: false, shift: false},
{key: 'Backspace', ctrl: false, meta: false, alt: false, shift: false},
],
})