mirror of
https://github.com/ArthurDanjou/ui.git
synced 2026-01-14 20:19:34 +01:00
docs(composables): update
This commit is contained in:
Benjamin Canac
@@ -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
|
||||
<UDropdown :items="[[{ label: 'Edit', shortcuts: ['E'] }]]" />
|
||||
```
|
||||
|
||||
Shortcuts are displayed and styled through the [Kbd](/components/kbd) component.
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<div class="flex items-center gap-0.5">
|
||||
<UKbd>⌘</UKbd>
|
||||
<UKbd>K</UKbd>
|
||||
</div>
|
||||
</template>
|
||||
```
|
||||
|
||||
::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
|
||||
<template>
|
||||
<UModal v-model="isOpen" />
|
||||
</template>
|
||||
|
||||
<script setup lang="ts">
|
||||
const isOpen = ref(false)
|
||||
const open = ref(false)
|
||||
|
||||
defineShortcuts({
|
||||
meta_k: {
|
||||
usingInput: true,
|
||||
handler: () => {
|
||||
isOpen.value = !isOpen.value
|
||||
}
|
||||
meta_k: () => {
|
||||
open.value = !open.value
|
||||
}
|
||||
})
|
||||
</script>
|
||||
```
|
||||
|
||||
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
|
||||
<script setup lang="ts">
|
||||
defineShortcuts({
|
||||
'?': () => openHelpModal(),
|
||||
'meta_k': () => openCommandPalette(),
|
||||
'g-d': () => navigateToDashboard()
|
||||
})
|
||||
</script>
|
||||
```
|
||||
|
||||
### With input focus handling
|
||||
|
||||
The `usingInput` option allows you to specify that a shortcut should only trigger when a specific input is focused.
|
||||
|
||||
```vue
|
||||
<template>
|
||||
@@ -89,21 +120,34 @@ const query = ref('')
|
||||
defineShortcuts({
|
||||
enter: {
|
||||
usingInput: 'queryInput',
|
||||
handler: () => {
|
||||
// TODO
|
||||
}
|
||||
handler: () => performSearch()
|
||||
},
|
||||
escape: {
|
||||
usingInput: true,
|
||||
handler: () => clearSearch()
|
||||
}
|
||||
})
|
||||
</script>
|
||||
```
|
||||
_`enter` shortcut will only trigger when `queryInput` is focused._
|
||||
|
||||
### Simple shortcut
|
||||
### Extracting shortcuts from menu items
|
||||
|
||||
In case the shortcut does not need any config, it can be written as a function.
|
||||
The `extractShortcuts` utility can be used to automatically define shortcuts from menu items:
|
||||
|
||||
```ts
|
||||
defineShortcuts({
|
||||
'?': () => openHelpModal()
|
||||
})
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
const items = [{
|
||||
label: 'Save',
|
||||
icon: 'i-heroicons-document-arrow-down',
|
||||
kbds: ['meta', 'S'],
|
||||
select: () => save()
|
||||
}, {
|
||||
label: 'Copy',
|
||||
icon: 'i-heroicons-document-duplicate',
|
||||
kbds: ['meta', 'C'],
|
||||
select: () => copy()
|
||||
}]
|
||||
|
||||
defineShortcuts(extractShortcuts(items))
|
||||
</script>
|
||||
```
|
||||
|
||||
17
docs/content/2.composables/use-modal.md
Normal file
17
docs/content/2.composables/use-modal.md
Normal file
@@ -0,0 +1,17 @@
|
||||
---
|
||||
title: useModal
|
||||
description: 'A composable to programmatically control a Modal component.'
|
||||
navigation:
|
||||
badge:
|
||||
label: Todo
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
Use the auto-imported `useModal` composable to programmatically control a [Modal](/components/modal) component.
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
const modal = useModal()
|
||||
</script>
|
||||
```
|
||||
17
docs/content/2.composables/use-slideover.md
Normal file
17
docs/content/2.composables/use-slideover.md
Normal file
@@ -0,0 +1,17 @@
|
||||
---
|
||||
title: useSlideover
|
||||
description: 'A composable to programmatically control a Slideover component.'
|
||||
navigation:
|
||||
badge:
|
||||
label: Todo
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
Use the auto-imported `useSlideover` composable to programmatically control a [Slideover](/components/slideover) component.
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
const slideover = useSlideover()
|
||||
</script>
|
||||
```
|
||||
@@ -1,23 +1,106 @@
|
||||
---
|
||||
title: useToast
|
||||
description: 'A composable to display toast notifications in your Nuxt application.'
|
||||
navigation:
|
||||
badge:
|
||||
label: Todo
|
||||
description: 'A composable to display toast notifications in your app.'
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
Use the auto-imported `useToast` composable to display [Toast](/components/toast) notifications.
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
const toast = useToast()
|
||||
</script>
|
||||
```
|
||||
|
||||
### `add()`
|
||||
- The `useToast` composable uses Vue's `useState` to manage the toast state, ensuring reactivity across your application.
|
||||
- A maximum of 5 toasts are displayed at a time. When adding a new toast that would exceed this limit, the oldest toast is automatically removed.
|
||||
- When removing a toast, there's a 200ms delay before it's actually removed from the state, allowing for exit animations.
|
||||
|
||||
### `update()`
|
||||
::tip{to="/components/toast"}
|
||||
Learn how to customize the appearance and behavior of toasts in the **Toast** component documentation.
|
||||
::
|
||||
|
||||
### `remove()`
|
||||
## API
|
||||
|
||||
### `add(toast: Partial<Toast>): Toast`
|
||||
|
||||
Adds a new toast notification.
|
||||
|
||||
- Parameters:
|
||||
- `toast`: A partial `Toast` object with the following properties:
|
||||
- `id` (optional): A unique identifier for the toast. If not provided, a timestamp will be used.
|
||||
- `open` (optional): Whether the toast is open. Defaults to `true`.
|
||||
- Other properties from the `Toast` interface.
|
||||
- Returns: The complete `Toast` object that was added.
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
const toast = useToast()
|
||||
|
||||
function showToast() {
|
||||
toast.add({
|
||||
title: 'Success',
|
||||
description: 'Your action was completed successfully.',
|
||||
color: 'green'
|
||||
})
|
||||
}
|
||||
</script>
|
||||
```
|
||||
|
||||
### `update(id: string | number, toast: Partial<Toast>)`
|
||||
|
||||
Updates an existing toast notification.
|
||||
|
||||
- Parameters:
|
||||
- `id`: The unique identifier of the toast to update.
|
||||
- `toast`: A partial `Toast` object with the properties to update.
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
const toast = useToast()
|
||||
|
||||
function updateToast(id: string | number) {
|
||||
toast.update(id, {
|
||||
title: 'Updated Toast',
|
||||
description: 'This toast has been updated.'
|
||||
})
|
||||
}
|
||||
</script>
|
||||
```
|
||||
|
||||
### `remove(id: string | number)`
|
||||
|
||||
Removes a toast notification.
|
||||
|
||||
- Parameters:
|
||||
- `id`: The unique identifier of the toast to remove.
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
const toast = useToast()
|
||||
|
||||
function removeToast(id: string | number) {
|
||||
toast.remove(id)
|
||||
}
|
||||
</script>
|
||||
```
|
||||
|
||||
### `clear()`
|
||||
|
||||
Removes all toast notifications.
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
const toast = useToast()
|
||||
|
||||
function clearAllToasts() {
|
||||
toast.clear()
|
||||
}
|
||||
</script>
|
||||
```
|
||||
|
||||
### `toasts`
|
||||
|
||||
- Type: `Ref<Toast[]>`
|
||||
- Description: A reactive array containing all current toast notifications.
|
||||
|
||||
Reference in New Issue
Block a user