Common

useListNavigation

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

Composable interno — utilizzato dai componenti dropdown della libreria (Select, MultiSelect, AutoComplete, ecc.).

Firma TypeScript

export function useListNavigation(options: UseListNavigationOptions): UseListNavigationResult

export interface UseListNavigationOptions {
  itemCount: () => number;
  isItemDisabled?: (index: number) => boolean;
  containerRef?: Ref<HTMLElement | null>;
  itemSelector?: string;          // default: '[data-list-item]'
  circular?: boolean;             // default: false
  autoScroll?: boolean;           // default: true
  scrollBehavior?: ScrollLogicalPosition; // default: 'nearest'
  scrollMode?: ScrollBehavior;    // default: 'smooth'
}

export interface UseListNavigationResult {
  focusedIndex: Ref<number>;    // -1 se nessuno
  navigateDown: () => void;
  navigateUp: () => void;
  navigateFirst: () => void;
  navigateLast: () => void;
  navigateTo: (index: number) => void;
  scrollToFocused: () => void;
  scrollToIndex: (index: number) => void;
  resetFocus: () => void;
  focusFirst: () => void;
}

Parametri

Parametro	Tipo	Descrizione
`itemCount`	`() => number`	Getter reattivo del numero di elementi
`isItemDisabled`	`(index: number) => boolean`	Funzione per verificare se un elemento e disabilitato
`containerRef`	`Ref<HTMLElement \| null>`	Container scrollabile per auto-scroll
`itemSelector`	`string`	Selettore CSS degli elementi (default: `[data-list-item]`)
`circular`	`boolean`	Navigazione circolare (torna all'inizio dalla fine)
`autoScroll`	`boolean`	Auto-scroll quando cambia `focusedIndex` (default: true)

Valore di Ritorno

Proprietà	Tipo	Descrizione
`focusedIndex`	`Ref<number>`	Indice elemento con focus (-1 se nessuno)
`navigateDown`	`() => void`	Sposta focus al successivo
`navigateUp`	`() => void`	Sposta focus al precedente
`navigateFirst`	`() => void`	Sposta focus al primo non-disabilitato
`navigateLast`	`() => void`	Sposta focus all'ultimo non-disabilitato
`navigateTo`	`(index: number) => void`	Sposta focus a un indice specifico
`scrollToFocused`	`() => void`	Scrolla all'elemento focused
`resetFocus`	`() => void`	Rimuove il focus (imposta -1)

Esempio

const { focusedIndex, navigateDown, navigateUp, resetFocus } = useListNavigation({
  itemCount: () => filteredOptions.value.length,
  isItemDisabled: (index) => filteredOptions.value[index]?.disabled,
  containerRef: listRef,
  circular: false,
})

// In handler keydown del componente
const onKeydown = (event: KeyboardEvent) => {
  if (event.key === 'ArrowDown') { event.preventDefault(); navigateDown() }
  if (event.key === 'ArrowUp') { event.preventDefault(); navigateUp() }
  if (event.key === 'Escape') resetFocus()
}

Note

Salta automaticamente gli elementi disabilitati durante la navigazione.
L'auto-scroll avviene tramite nextTick per attendere il render DOM prima di scrollare.
In modalita non-circular, raggiunto il bordo della lista il focus rimane sull'ultimo elemento valido.
focusedIndex e -1 inizialmente; il componente deve mapparlo a una classe CSS per l'evidenziazione visiva.

useLifeTimer

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

usePopoverPosition

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