Common

usePopoverPosition

Composable interno per posizionamento popover/tooltip con 12 posizioni, auto-flip e tracking scroll.

Composable interno — utilizzato dai componenti Popover, Tooltip e OverlayPanel della libreria.

Firma TypeScript

export function usePopoverPosition(
  triggerRef: Ref<HTMLElement | null>,
  popoverRef: Ref<HTMLElement | null>,
  options?: UsePopoverPositionOptions
): UsePopoverPositionResult

export type PopoverPlacement =
  | 'top' | 'top-start' | 'top-end'
  | 'bottom' | 'bottom-start' | 'bottom-end'
  | 'left' | 'left-start' | 'left-end'
  | 'right' | 'right-start' | 'right-end'

export interface UsePopoverPositionOptions {
  placement?: PopoverPlacement;  // default: 'top'
  gap?: number;                  // default: 8px
  viewportMargin?: number;       // default: 8px
  autoFlip?: boolean;            // default: true
  arrowOffset?: number;          // default: 12px
}

export interface UsePopoverPositionResult {
  position: Ref<PopoverPositionStyle>;   // { top, left } con 'px'
  arrowPosition: Ref<ArrowPositionStyle>;
  actualPlacement: Ref<PopoverPlacement>; // placement effettivo dopo auto-flip
  isInViewport: Ref<boolean>;
  updatePosition: () => void;
  startTracking: () => void;
  stopTracking: () => void;
  isTracking: Ref<boolean>;
}

Parametri

Parametro	Tipo	Descrizione
`triggerRef`	`Ref<HTMLElement \| null>`	Elemento che scatena il popover
`popoverRef`	`Ref<HTMLElement \| null>`	Elemento popover da posizionare
`options.placement`	`PopoverPlacement`	Posizione preferita (default: `'top'`)
`options.autoFlip`	`boolean`	Flip automatico al lato opposto se manca spazio (default: true)
`options.gap`	`number`	Gap tra trigger e popover in px (default: 8)

Valore di Ritorno

Proprietà	Tipo	Descrizione
`position`	`Ref<PopoverPositionStyle>`	Stile `{ top, left }` da bindare al popover
`arrowPosition`	`Ref<ArrowPositionStyle>`	Stile CSS per la freccia del popover
`actualPlacement`	`Ref<PopoverPlacement>`	Placement effettivo dopo eventuali flip
`isInViewport`	`Ref<boolean>`	True se il trigger e visibile nel viewport
`updatePosition`	`() => void`	Ricalcola posizione e freccia
`startTracking`	`() => void`	Attiva scroll/resize tracking
`stopTracking`	`() => void`	Disattiva scroll/resize tracking

Esempio

const triggerRef = ref<HTMLElement | null>(null)
const popoverRef = ref<HTMLElement | null>(null)

const { position, arrowPosition, actualPlacement, updatePosition, startTracking, stopTracking } =
  usePopoverPosition(triggerRef, popoverRef, { placement: 'bottom' })

// Aggiorna al mount del popover
onMounted(() => {
  updatePosition()
  startTracking()
})
onBeforeUnmount(() => stopTracking())

Note

Supporta 12 placement: i 4 lati principali (top/bottom/left/right) ciascuno con allineamento start/center/end.
Auto-flip: se manca spazio nel lato richiesto, passa automaticamente al lato opposto.
arrowPosition calcola gli stili CSS della freccia (posizione e rotazione) coerentemente con il placement effettivo.
isInViewport verifica se il trigger e ancora visibile — utile per nascondere il popover quando si scrolla.
Cleanup tracking in onBeforeUnmount automatico.

useListNavigation

Composable interno per navigazione tastiera in liste con skip disabilitati e auto-scroll.

useReorderList

Composable interno per riordinamento elementi con moveUp/moveDown/moveTop/moveBottom, usato da OrderList e PickList.