Composables

useCommandPalette

Composable singleton per gestire stato apertura, ricerca ed esecuzione comandi della command palette.

Panoramica

useCommandPalette espone lo state e le API della command palette. Lo state è singleton: tutte le istanze condividono isOpen, searchQuery, registro comandi e binding Ctrl+K/Cmd+K. Il binding viene installato lazily alla prima invocazione tramite useMagicKeys di @vueuse/core. I comandi passati in initialCommands sono rimossi automaticamente al dispose dello scope corrente.

Firma

function useCommandPalette(
  initialCommands?: Command[]
): UseCommandPaletteReturn

Parametri

Parametro	Tipo	Default	Descrizione
`initialCommands`	`Command[]`	`[]`	Comandi da registrare per lo scope corrente. Vengono rimossi al dispose

`Command`

interface Command {
  id: string
  label: string
  description?: string
  category?: string
  icon?: string
  keywords?: string[]
  handler: () => void | Promise<void>
  enabled?: boolean
}

Campo	Tipo	Descrizione
`id`	`string`	Identificatore univoco. Una seconda registrazione con lo stesso `id` viene ignorata
`label`	`string`	Etichetta principale visualizzata nel `CommandPalette`
`description`	`string`	Descrizione secondaria opzionale
`category`	`string`	Categoria visualizzata in alto a destra del comando
`icon`	`string`	Icona visualizzata a sinistra (testo o classe icon font come `pi pi-home`)
`keywords`	`string[]`	Keyword aggiuntive non visualizzate ma incluse nel filtro
`handler`	`() => void \| Promise<void>`	Funzione invocata all'esecuzione. Errori vengono loggati ma non bloccano la chiusura
`enabled`	`boolean`	Se `false`, il comando è filtrato dai risultati

Return

Proprietà	Tipo	Descrizione
`isOpen`	`Ref<boolean>`	Stato apertura della palette
`searchQuery`	`Ref<string>`	Testo del filtro corrente. Bindato automaticamente all'input di `CommandPalette`
`filteredCommands`	`ComputedRef<Command[]>`	Comandi filtrati dal `searchQuery` corrente. Esclude comandi `enabled: false`
`allCommands`	`Readonly<Ref<Command[]>>`	Registro completo dei comandi registrati
`toggle`	`() => void`	Inverte `isOpen`. Se apre, azzera `searchQuery`
`open`	`() => void`	Apre la palette e azzera `searchQuery`
`close`	`() => void`	Chiude la palette
`executeCommand`	`(command: Command) => Promise<void>`	Esegue l'handler del comando e chiude la palette (anche in caso di errore)
`addCommand`	`(command: Command) => void`	Aggiunge un comando. Idempotente sull'`id`
`removeCommand`	`(id: string) => void`	Rimuove il comando con l'`id` specificato

Il return type è UseCommandPaletteReturn.

Logica di filtro

filteredCommands confronta il searchQuery (case-insensitive) contro:

command.label
command.description
ogni elemento di command.keywords

Il match è di tipo includes (substring). Comandi con enabled: false sono esclusi. Quando searchQuery è vuoto, restituisce tutti i comandi del registro globale.

Binding Ctrl+K / Cmd+K

Alla prima chiamata di useCommandPalette il composable installa un watch su useMagicKeys() di @vueuse/core che ascolta ctrl_k e meta_k. Quando uno dei due passa a true, viene chiamato toggle(). Il binding è installato una sola volta indipendentemente da quante volte il composable viene invocato.

Esempio: registrazione di base

<script setup lang="ts">
import { CommandPalette, useCommandPalette } from '@pzeta/vue-scorciatoie'

useCommandPalette([
  {
    id: 'nav-dashboard',
    label: 'Dashboard',
    icon: 'pi pi-home',
    handler: () => router.push('/'),
  },
  {
    id: 'nav-anagrafica',
    label: 'Anagrafiche',
    category: 'Navigazione',
    keywords: ['clienti', 'fornitori'],
    handler: () => router.push('/anagrafica'),
  },
])
</script>

<template>
  <CommandPalette />
</template>

Esempio: apertura programmatica

import { useCommandPalette } from '@pzeta/vue-scorciatoie'

const { open, close, toggle, isOpen } = useCommandPalette()

// Apertura da un pulsante o evento esterno
function apriPalette() {
  open()
}

// Apertura/chiusura
toggle()

// Lettura stato
watch(isOpen, (aperta) => {
  console.log(aperta ? 'palette aperta' : 'palette chiusa')
})

Esempio: comandi dinamici per modulo

const { addCommand, removeCommand } = useCommandPalette()

// Modulo CRM caricato on-demand
function registraComandiCRM() {
  addCommand({
    id: 'crm-pipeline',
    label: 'Pipeline vendite',
    category: 'CRM',
    handler: () => router.push('/crm/pipeline'),
  })
  addCommand({
    id: 'crm-leads',
    label: 'Lead aperti',
    category: 'CRM',
    handler: () => router.push('/crm/leads'),
  })
}

function deregistraComandiCRM() {
  removeCommand('crm-pipeline')
  removeCommand('crm-leads')
}

Esempio: esecuzione manuale

executeCommand è normalmente invocato da CommandPalette quando l'utente preme Enter o clicca un risultato, ma può essere chiamato programmaticamente:

const { allCommands, executeCommand } = useCommandPalette()

const cmd = allCommands.value.find((c) => c.id === 'nav-dashboard')
if (cmd) await executeCommand(cmd)

API di reset (testing)

import { _resetCommandPaletteState } from '@pzeta/vue-scorciatoie'

// Resetta state, comandi, binding magic keys.
// Solo per test unitari, NON usare in produzione.
_resetCommandPaletteState()

Note

L'apertura via toggle/open azzera sempre searchQuery per partire da elenco completo
executeCommand chiama close() nel finally: la palette si chiude sempre, anche se l'handler lancia un'eccezione
searchQuery è esposto come Ref mutabile: può essere modificato dall'esterno (es. ricerca pre-filtrata da un altro componente)
L'integrazione con CommandPalette è automatica: registrare i comandi è sufficiente, il rendering è gestito dal componente

CommandPalette

Tavolozza comandi stile Cmd+K con ricerca, navigazione tastiera e accessibilità ARIA.

useOS

Rilevamento sistema operativo e helper per visualizzare correttamente i tasti modificatori.