arthur/ui
1
0
Fork 0
mirror of https://github.com/ArthurDanjou/ui.git synced 2026-01-27 18:30:35 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs(composables): update

Browse Source
This commit is contained in:
Benjamin Canac
2024-09-05 10:22:58 +02:00
parent 85d172339f
commit fba4d6a385
4 changed files with 237 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files

182
docs/content/2.composables/define-shortcuts.md
View File

@@ -1,82 +1,113 @@
--- ---
title: defineShortcuts title: defineShortcuts
description: 'Learn how to display and define keyboard shortcuts in your app.' description: 'A composable to define keyboard shortcuts in your app.'
navigation:
badge:
label: Todo
--- ---
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 ```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"> <script setup lang="ts">
const isOpen = ref(false) const open = ref(false)
defineShortcuts({ defineShortcuts({
meta_k: { meta_k: () => {
usingInput: true, open.value = !open.value
handler: () => {
isOpen.value = !isOpen.value
}
} }
}) })
</script> </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: ::tip{to="/components/kbd"}
- `meta`: acts as `Command` for MacOS and `Control` for others Learn how to display shortcuts in components in the **Kbd** component documentation.
- `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.
:: ::
### `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 ```vue
<template> <template>
@@ -89,21 +120,34 @@ const query = ref('')
defineShortcuts({ defineShortcuts({
enter: { enter: {
usingInput: 'queryInput', usingInput: 'queryInput',
handler: () => { handler: () => performSearch()
// TODO },
} escape: {
usingInput: true,
handler: () => clearSearch()
} }
}) })
</script> </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 ```vue
defineShortcuts({ <script setup lang="ts">
'?': () => openHelpModal() 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
View 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
View 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>
```

97
docs/content/2.composables/use-toast.md
View File

@@ -1,23 +1,106 @@
--- ---
title: useToast title: useToast
description: 'A composable to display toast notifications in your Nuxt application.' description: 'A composable to display toast notifications in your app.'
navigation:
badge:
label: Todo
--- ---
## Usage ## Usage
Use the auto-imported `useToast` composable to display [Toast](/components/toast) notifications.
```vue ```vue
<script setup lang="ts"> <script setup lang="ts">
const toast = useToast() const toast = useToast()
</script> </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()` ### `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.