Composables

useOS

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

Panoramica

useOS rileva il sistema operativo del client ed espone label coerenti per visualizzare i modificatori delle scorciatoie nell'interfaccia. Il rilevamento avviene una sola volta per sessione e il risultato è cachato. Il composable lavora a stretto contatto con la logica di matching cross-platform di useShortcuts (BR-17 e BR-18): mostra all'utente la combinazione effettiva di tasti che produce il match sulla sua piattaforma.

Tipi

type OSPlatform = 'macos' | 'windows' | 'linux' | 'unknown'

Funzione `detectOS`

function detectOS(): OSPlatform

Esegue il rilevamento puro (senza cache, side-effect free). Strategia in cascata:

navigator.userAgentData.platform (Chrome 90+, Edge 90+) — preferito
navigator.platform (deprecato ma universalmente supportato)
navigator.userAgent come ultimo fallback
'unknown' se nessuna fonte è disponibile (es. SSR)

Conforme a BR-20: rilevamento automatico senza configurazione manuale.

Composable `useOS`

function useOS(): {
  os: OSPlatform
  isMac: boolean
  primaryModifierLabel: 'Ctrl' | 'Alt'
  paletteModifierLabel: 'Cmd' | 'Ctrl'
}

Return

Proprietà	Tipo	Descrizione
`os`	`OSPlatform`	Sistema operativo rilevato (`'macos'`, `'windows'`, `'linux'`, `'unknown'`)
`isMac`	`boolean`	`true` se `os === 'macos'`
`primaryModifierLabel`	`'Ctrl' \| 'Alt'`	Label modificatore primario delle scorciatoie. macOS: `'Ctrl'` (perché `alt` → `Ctrl` su macOS, BR-17). Altrimenti `'Alt'`
`paletteModifierLabel`	`'Cmd' \| 'Ctrl'`	Label modificatore della command palette. macOS: `'Cmd'` (BR-18). Altrimenti `'Ctrl'`

Il valore os è cachato a livello di modulo: chiamate successive restituiscono il valore già calcolato senza ripetere il rilevamento.

Esempio base

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

const { os, isMac, primaryModifierLabel, paletteModifierLabel } = useOS()
</script>

<template>
  <div class="text-sm text-gray-500">
    <p>Premi <kbd>{{ paletteModifierLabel }}</kbd> + <kbd>K</kbd> per aprire la palette</p>
    <p>Sistema rilevato: {{ os }}</p>
  </div>
</template>

Su macOS l'utente vede Cmd + K, su Windows/Linux Ctrl + K.

Esempio: visualizzazione cheat-sheet

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

const { primaryModifierLabel, paletteModifierLabel } = useOS()
const { shortcuts } = useShortcuts()

function formattaCombo(s: { ctrl?: boolean; alt?: boolean; shift?: boolean; key: string }) {
  const parts: string[] = []
  if (s.ctrl) parts.push(paletteModifierLabel) // Ctrl/Cmd
  if (s.alt) parts.push(primaryModifierLabel)  // Alt/Ctrl
  if (s.shift) parts.push('Shift')
  parts.push(s.key.toUpperCase())
  return parts.join(' + ')
}
</script>

<template>
  <ul>
    <li v-for="s in shortcuts" :key="s.id">
      <kbd>{{ formattaCombo(s) }}</kbd> — {{ s.description }}
    </li>
  </ul>
</template>

Esempio: contenuto condizionale per piattaforma

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

const { isMac } = useOS()
</script>

<template>
  <p v-if="isMac">Su macOS, usa <kbd>Cmd</kbd> + <kbd>S</kbd> per salvare.</p>
  <p v-else>Su Windows/Linux, usa <kbd>Ctrl</kbd> + <kbd>S</kbd> per salvare.</p>
</template>

API di reset (testing)

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

// Azzera la cache di useOS forzando un nuovo rilevamento.
// Solo per test unitari, NON usare in produzione.
_resetOSCache()

Note

Il rilevamento avviene la prima volta che useOS o detectOS viene invocato; il valore non cambia durante la sessione del browser
In ambiente SSR (navigator non definito) detectOS restituisce 'unknown'. Le label di fallback sono comunque coerenti ('Alt', 'Ctrl')
Le label sono pensate per allinearsi con la logica di matching di useShortcuts: se definisci una scorciatoia con ctrl: true, mostra all'utente paletteModifierLabel (Ctrl o Cmd); per alt: true mostra primaryModifierLabel (Alt o Ctrl)
detectOS è esportato come funzione pura per casi in cui serve il valore senza la cache di useOS (es. test, telemetria)

useCommandPalette

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

useShortcuts

Composable singleton per registrare scorciatoie da tastiera con cleanup automatico per scope.