diff --git a/docs/content/2.composables/define-shortcuts.md b/docs/content/2.composables/define-shortcuts.md index 091da9b9..3fcfccb0 100644 --- a/docs/content/2.composables/define-shortcuts.md +++ b/docs/content/2.composables/define-shortcuts.md @@ -1,82 +1,113 @@ --- title: defineShortcuts -description: 'Learn how to display and define keyboard shortcuts in your app.' -navigation: - badge: - label: Todo +description: 'A composable to define keyboard shortcuts in your app.' --- -Some components like [Dropdown](/components/dropdown), [Command Palette](/components/command-palette) and [Tooltip](/components/tooltip) support the display of keyboard shortcuts. +## Usage + +Use the auto-imported `defineShortcuts` composable to define keyboard shortcuts. ```vue - -``` - -Shortcuts are displayed and styled through the [Kbd](/components/kbd) component. - -```vue - -``` - -::tip -You will have a preview of how shortcuts are rendered in each component page. -:: - -## `defineShortcuts` - -This module provides a `defineShortcuts` composable that allows you to define keyboard shortcuts in your app really easily. - -```vue - - ``` -Shortcuts keys are written as the literal keyboard key value. Combinations are made with `_` separator. Chained shortcuts are made with `-` separator. +- Shortcuts are automatically adjusted for non-macOS platforms, converting `meta` to `ctrl`. +- The composable uses Vue's `useEventListener` to handle keydown events. +- For a complete list of available shortcut keys, refer to the [`KeyboardEvent.key`](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values) API documentation. Note that the key should be written in lowercase. -Modifiers are also available: -- `meta`: acts as `Command` for MacOS and `Control` for others -- `ctrl`: acts as `Control` -- `shift`: acts as `Shift` and is only necessary for alphabetic keys - -Examples of keys: -- `escape`: will trigger by hitting `Esc` -- `meta_k`: will trigger by hitting `⌘` and `K` at the same time on MacOS, and `Ctrl` and `K` on Windows and Linux -- `ctrl_k`: will trigger by hitting `Ctrl` and `K` at the same time on MacOS, Windows and Linux -- `shift_e`: will trigger by hitting `Shift` and `E` at the same time on MacOS, Windows and Linux -- `?`: will trigger by hitting `?` on some keyboard layouts, or for example `Shift` and `/`, which results in `?` on US Mac keyboards -- `g-d`: will trigger by hitting `g` then `d` with a maximum delay of 800ms by default -- `arrowleft`: will trigger by hitting `←` (also: `arrowright`, `arrowup`, `arrowdown`) - -::tip -For a complete list of available shortcut keys, refer to the [`KeyboardEvent`](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values) API docs. Note the `KeyboardEvent.key` has to be written in lowercase. +::tip{to="/components/kbd"} +Learn how to display shortcuts in components in the **Kbd** component documentation. :: -### `usingInput` +## API -Prop: `usingInput?: string | boolean` +### `defineShortcuts(config: ShortcutsConfig, options?: ShortcutsOptions)` -By default, `usingInput` is `false`, meaning it will only trigger when no input is focused. When set to `true`, the shortcut will also trigger when any input is focused. +Define keyboard shortcuts for your application. -For a more advanced behavior, `usingInput` can be set to the name of an input, so it only triggers when focusing this specific input. +- `config`: An object where keys are shortcut definitions and values are either handler functions or shortcut configuration objects. +- `options`: Optional configuration for the shortcuts behavior. + +#### Shortcut Definition + +Shortcuts are defined using the following format: + +- Single key: `'a'`, `'b'`, `'1'`, `'?'`, etc. +- Key combinations: Use `_` to separate keys, e.g., `'meta_k'`, `'ctrl_shift_f'` +- Key sequences: Use `-` to define a sequence, e.g., `'g-d'` + +#### Modifiers + +- `meta`: Represents Command (⌘) on macOS and Control on other platforms +- `ctrl`: Represents Control key +- `shift`: Used for alphabetic keys when Shift is required + +#### Special Keys + +- `escape`: Triggers on Esc key +- `enter`: Triggers on Enter key +- `arrowleft`, `arrowright`, `arrowup`, `arrowdown`: Trigger on respective arrow keys + +#### Shortcut Configuration + +Each shortcut can be defined as a function or an object with the following properties: + +```ts +interface ShortcutConfig { + handler: () => void + usingInput?: boolean | string +} +``` + +- `handler`: Function to be executed when the shortcut is triggered +- `usingInput`: + - `false` (default): Shortcut only triggers when no input is focused + - `true`: Shortcut triggers even when any input is focused + - `string`: Shortcut only triggers when the specified input (by name) is focused + +#### ShortcutsOptions + +The `options` parameter allows you to configure the behavior of the shortcuts. It has the following properties: + +```ts +interface ShortcutsOptions { + repeat?: boolean + trigger?: 'keydown' | 'keyup' + capture?: boolean + passive?: boolean +} +``` + +- `repeat`: If `true`, the shortcut will trigger repeatedly while the key is held down. Default is `false`. +- `trigger`: Specifies whether the shortcut should trigger on 'keydown' or 'keyup' events. Default is 'keydown'. +- `capture`: If `true`, the event listener will be set to capture phase. Default is `false`. +- `passive`: If `true`, indicates that the function specified by listener will never call preventDefault(). Default is `false`. + +## Examples + +### Basic usage + +```vue + +``` + +### With input focus handling + +The `usingInput` option allows you to specify that a shortcut should only trigger when a specific input is focused. ```vue