Installazione

Installazione

npm install @pzeta/vue-scorciatoie

Peer dependencies

L'unica peer dependency è Vue 3.5+:

{
  "peerDependencies": {
    "vue": "^3.5.0"
  }
}

Formati del pacchetto

Il pacchetto espone un solo entry point, in tre formati:

Le dichiarazioni TypeScript sono dist/index.d.ts per import e dist/index.d.cts per require. Lo state dei composable è un singleton per modulo: in un processo va caricato un solo formato, altrimenti ESM e CommonJS avrebbero due registri separati.

Setup minimo

@pzeta/vue-scorciatoie non richiede un plugin Vue: composable e componente si importano e condividono uno state singleton interno.

Registrare scorciatoie globali

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

useShortcuts([
  {
    id: 'salva',
    key: 's',
    ctrl: true,
    description: 'Salva il record corrente',
    handler: () => salvaRecord(),
  },
])

Il listener keydown su window viene registrato alla prima chiamata di useShortcuts. Le scorciatoie registrate da un componente vengono rimosse quando il componente si smonta.

Aggiungere la Command Palette

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

useCommandPalette([
  {
    id: 'apri-anagrafica',
    label: 'Apri anagrafica',
    category: 'Navigazione',
    handler: () => router.push('/anagrafica'),
  },
])
</script>

<template>
  <CommandPalette />
  <!-- resto dell'app -->
</template>

La prima chiamata di useCommandPalette registra Ctrl+K (Windows/Linux) o Cmd+K (macOS) come scorciatoia di useShortcuts per aprire e chiudere la palette. CommandPalette usa <Teleport to="body">, quindi la sua posizione nel template è indifferente: va montato una sola volta.

Il pacchetto non distribuisce CSS: lo stile del componente è fatto di utility Tailwind, che il Tailwind dell'applicazione deve generare (vedi Stile).

Import disponibili

import {
  // Componenti
  CommandPalette,

  // Composables
  useShortcuts,
  useCommandPalette,
  useOS,
  detectOS,

  // Tipi
  type Shortcut,
  type ShortcutConfig,
  type UseShortcutsReturn,
  type Command,
  type CommandHandlerContext,
  type CommandSource,
  type UseCommandPaletteOptions,
  type UseCommandPaletteReturn,
  type CommandPaletteProps,
  type CommandPaletteLabels,
  type OSPlatform,
} from '@pzeta/vue-scorciatoie'

CommandSource, isLoadingSources, sourceResults, registerSource/unregisterSource, l'etichetta sourcesLoading e le opzioni sourceTimeout/sourceDebounce sono disponibili dalla 1.2.0.