Common

useDropdownPosition

Composable interno per posizionamento dropdown con position:fixed, flip verticale e scroll tracking.

Composable interno — utilizzato da tutti i componenti dropdown della libreria.

Firma TypeScript

export function useDropdownPosition(
  triggerRef?: Ref<HTMLElement | null>,
  options?: UseDropdownPositionOptions
): UseDropdownPositionResult

export interface UseDropdownPositionOptions {
  gap?: number;               // default: 4px
  autoTrack?: boolean;        // default: false
  dropdownHeight?: number;    // default: 250px (per calcolo flip)
  dropdownWidth?: number;     // opzionale
  zIndex?: number;            // default: 50
  viewportMargin?: number;    // default: 8px
  containHorizontal?: boolean; // default: true
  matchTriggerWidth?: boolean; // default: true
}

export interface UseDropdownPositionResult {
  position: Ref<DropdownPosition>;    // { top, left, width, zIndex } con 'px'
  positionRaw: Ref<DropdownPositionRaw>; // valori numerici
  openUp: Ref<boolean>;
  updatePosition: () => void;
  setTarget: (element: HTMLElement | null) => void;
  startTracking: () => void;
  stopTracking: () => void;
  isTracking: Ref<boolean>;
}

Parametri

Parametro	Tipo	Descrizione
`triggerRef`	`Ref<HTMLElement \| null>` (opzionale)	Elemento trigger fisso
`options.gap`	`number`	Spazio tra trigger e dropdown in px (default: 4)
`options.dropdownHeight`	`number`	Altezza stimata per calcolo flip (default: 250)
`options.matchTriggerWidth`	`boolean`	Adatta la larghezza al trigger (default: true)
`options.containHorizontal`	`boolean`	Evita overflow orizzontale (default: true)

Valore di Ritorno

Proprietà	Tipo	Descrizione
`position`	`Ref<DropdownPosition>`	Posizione con stringhe `'Xpx'` da bindare a `:style`
`openUp`	`Ref<boolean>`	True se il dropdown si apre verso l'alto
`updatePosition`	`() => void`	Ricalcola la posizione manualmente
`setTarget`	`(el: HTMLElement \| null) => void`	Imposta target dinamico (per Menu popup)
`startTracking`	`() => void`	Attiva scroll/resize tracking
`stopTracking`	`() => void`	Disattiva scroll/resize tracking
`isTracking`	`Ref<boolean>`	True se il tracking e attivo

Esempio

const triggerRef = ref<HTMLElement | null>(null)
const { position, openUp, updatePosition, startTracking, stopTracking } =
  useDropdownPosition(triggerRef, { gap: 4, dropdownHeight: 300 })

// Aggiorna la posizione all'apertura del dropdown
onOpen: () => {
  updatePosition()
  startTracking()
}

// Pulisci alla chiusura
onClose: () => {
  stopTracking()
}

<div :style="position" class="dropdown-panel">...</div>

Note

Usa position: fixed — non dipende dalla posizione di scroll del container.
Il flip verticale avviene automaticamente se non c'e spazio sotto il trigger (compara spazio sopra/sotto).
setTarget permette l'uso con target dinamico (es. Menu che si apre su un pulsante diverso ogni volta).
Il tracking scroll usa capture phase (true) per intercettare scroll in contenitori scrollabili interni.
Cleanup tracking in onBeforeUnmount automatico.

useDropdownLifecycle

Composable interno per gestire il ciclo di vita di un dropdown (open/close, click-outside, cleanup).

useLifeTimer

Composable interno per auto-dismissal con timer, progress tracking e pausa/ripresa.