Technique Docs

Appearance

🧭 Système de Navigation au Focus (D-pad) ​

L'application utilise un système de navigation sur mesure conçu pour les téléviseurs, où l'utilisateur interagit principalement via les touches fléchées (D-pad) d'une télécommande. Ce système permet de gérer le focus visuel de manière prévisible à travers une hiérarchie de composants.

🏗️ Architecture du Système ​

Le cœur du système repose sur la classe Selectable (src/lib/navigation/selectable.ts). Elle construit dynamiquement une arborescence d'objets selectables calquée sur la hiérarchie du DOM.

1. Enregistrement des éléments ​

Les éléments HTML deviennent "selectables" via des Actions Svelte. Lorsqu'un composant est monté, il enregistre son élément HTML auprès de la classe Selectable.

2. Arborescence hiérarchique ​

Le système détecte automatiquement les relations parent-enfant en analysant l'imbrication des éléments dans le DOM. Cela permet de créer des conteneurs (listes, grilles, modales) qui gèrent le focus de leurs enfants.

🎮 Mécanismes de Navigation ​

Flux de Focus (giveFocus) ​

Lorsqu'une touche directionnelle est pressée, le système appelle Selectable.giveFocus(direction).

  1. Recherche locale : Le composant actuellement focalisé cherche un frère (sibling) dans la direction demandée.
  2. Remontée (Bubbling) : Si aucun frère n'est trouvé, la demande remonte au parent.
  3. Redescente : Le parent cherche parmi ses autres enfants celui qui est le plus apte à recevoir le focus dans cette direction.

Types de Flux (Flow Direction) ​

Les conteneurs peuvent définir comment leurs enfants sont organisés :

  • vertical : Navigation haut/bas entre les enfants.
  • horizontal : Navigation gauche/droite entre les enfants.
  • Grilles : Support de la navigation 2D via la propriété gridColumns.

🔒 Fonctionnalités Avancées ​

Trap Focus (Confinement) ​

Utilisé principalement pour les modales. Lorsqu'un conteneur est configuré avec trapFocus: true, le focus ne peut pas sortir de ce conteneur via les touches directionnelles. L'utilisateur doit explicitement fermer la modale (touche Back) pour rendre le focus au reste de l'application.

Auto-Scroll ​

Le système s'intègre avec un store de scroll (scroll.store.ts). Lorsqu'un élément reçoit le focus, le système calcule sa position et déclenche automatiquement un défilement du conteneur parent pour garantir que l'élément focalisé est toujours visible à l'écran.

🛠️ Utilisation dans les Composants ​

Pour rendre un élément navigable :

svelte
<script>
	import { register } from '$lib/navigation/selectable';
</script>

<!-- L'action 'use:register' transforme l'élément en Selectable -->
<div use:register={{ name: 'MonBouton' }} on:focus={() => console.log("J'ai le focus !")}>
	Cliquez-moi
</div>

Pour créer un conteneur :

svelte
<Container direction="vertical" name="MaListe">
	<Item name="Item 1" />
	<Item name="Item 2" />
</Container>

Retour à l'accueil