diff --git a/docs/superpowers/plans/2026-08-31-clavier-desktop.md b/docs/superpowers/plans/2026-08-31-clavier-desktop.md new file mode 100644 index 0000000..bb9e70a --- /dev/null +++ b/docs/superpowers/plans/2026-08-31-clavier-desktop.md @@ -0,0 +1,266 @@ +# Clavier physique sur la version Desktop — Plan d'implémentation + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Sur la version Desktop, répondre aux questions avec le clavier physique : chiffres (rangée du haut et pavé numérique) saisissent, Entrée valide, Backspace efface. + +**Architecture:** Deux unités. (1) `GameKeyMapping`, logique pure de mapping touche → action (`KeypadAction`), testable en `commonTest` sans UI. (2) Câblage dans `GameScreen.PlayingContent` : `onPreviewKeyEvent` sur le `Column` racine + `FocusRequester`/`focusable()` pour recevoir les événements ; l'handler appelle les callbacks existants du `GameEngine` et consomme l'événement. Aucun code spécifique desktop : sur mobile tactile aucun événement clavier n'arrive. + +**Tech Stack:** Kotlin Multiplatform (commonMain/commonTest), Compose Multiplatform 1.12.0 (`androidx.compose.ui.input.key`, `androidx.compose.ui.focus`), kotlin.test, Gradle. + +**Spec:** `docs/superpowers/specs/2026-08-31-clavier-desktop-design.md` + +## Global Constraints + +- Commande de test : `./gradlew :sharedUI:jvmTest` (kotlin.test, tests dans `commonTest`) +- Vérification manuelle : `./gradlew :desktopApp:run` (fenêtre 480×800) +- Constantes vérifiées dans CMP 1.12.0 : `Key.Zero`–`Key.Nine`, `Key.NumPad0`–`Key.NumPad9`, `Key.Enter`, `Key.NumPadEnter`, `Key.Backspace`, `Key.A`, `Key.Escape`, `Key.Spacebar`, `Key.Tab`, `KeyEventType.KeyDown`, `KeyEventType.KeyUp` ; `event.key` et `event.type` sont des propriétés d'extension (`androidx.compose.ui.input.key.key` / `.type`) +- `GameEngine`, `Main.kt`, écrans Accueil/Résultats/Historique : non modifiés +- Pas de dépendance nouvelle ; pas de commentaire dans le code ; interface et docs du projet en français +- Touches gérées uniquement (décision produit) : 0-9, Entrée, Backspace. Pas d'Échap. + +--- + +### Task 1: `GameKeyMapping` (logique pure) + tests + +**Files:** +- Create: `sharedUI/src/commonMain/kotlin/com/livrets/ui/GameKeyMapping.kt` +- Test: `sharedUI/src/commonTest/kotlin/com/livrets/ui/GameKeyMappingTest.kt` + +**Interfaces:** +- Consumes: rien (logique autonome, dépendances Compose `Key`/`KeyEventType` déjà dans commonMain via `api(libs.compose.ui)`) +- Produces: `sealed interface KeypadAction { data class Digit(val char: Char); data object Delete; data object Validate }` et `object GameKeyMapping { fun actionFor(key: Key, type: KeyEventType): KeypadAction? }` — utilisés par le Task 2 + +- [ ] **Step 1: Write the failing tests** + +Créer `sharedUI/src/commonTest/kotlin/com/livrets/ui/GameKeyMappingTest.kt` : + +```kotlin +package com.livrets.ui + +import androidx.compose.ui.input.key.Key +import androidx.compose.ui.input.key.KeyEventType +import kotlin.test.Test +import kotlin.test.assertEquals +import kotlin.test.assertNull + +class GameKeyMappingTest { + + @Test + fun `chiffres de la rangee du haut`() { + val expected = mapOf( + Key.Zero to '0', Key.One to '1', Key.Two to '2', Key.Three to '3', + Key.Four to '4', Key.Five to '5', Key.Six to '6', Key.Seven to '7', + Key.Eight to '8', Key.Nine to '9', + ) + for ((key, char) in expected) { + assertEquals(KeypadAction.Digit(char), GameKeyMapping.actionFor(key, KeyEventType.KeyDown)) + } + } + + @Test + fun `chiffres du pave numerique`() { + val expected = mapOf( + Key.NumPad0 to '0', Key.NumPad1 to '1', Key.NumPad2 to '2', Key.NumPad3 to '3', + Key.NumPad4 to '4', Key.NumPad5 to '5', Key.NumPad6 to '6', Key.NumPad7 to '7', + Key.NumPad8 to '8', Key.NumPad9 to '9', + ) + for ((key, char) in expected) { + assertEquals(KeypadAction.Digit(char), GameKeyMapping.actionFor(key, KeyEventType.KeyDown)) + } + } + + @Test + fun `entree valide la reponse`() { + assertEquals(KeypadAction.Validate, GameKeyMapping.actionFor(Key.Enter, KeyEventType.KeyDown)) + } + + @Test + fun `entree du pave numerique valide la reponse`() { + assertEquals(KeypadAction.Validate, GameKeyMapping.actionFor(Key.NumPadEnter, KeyEventType.KeyDown)) + } + + @Test + fun `backspace efface`() { + assertEquals(KeypadAction.Delete, GameKeyMapping.actionFor(Key.Backspace, KeyEventType.KeyDown)) + } + + @Test + fun `relachement de touche ignore`() { + assertNull(GameKeyMapping.actionFor(Key.One, KeyEventType.KeyUp)) + } + + @Test + fun `touches non gerees ignorees`() { + for (key in listOf(Key.A, Key.Escape, Key.Spacebar, Key.Tab)) { + assertNull(GameKeyMapping.actionFor(key, KeyEventType.KeyDown)) + } + } +} +``` + +- [ ] **Step 2: Run tests to verify they fail** + +Run: `./gradlew :sharedUI:jvmTest` +Expected: FAIL — compilation échoue avec `Unresolved reference 'GameKeyMapping'` et `Unresolved reference 'KeypadAction'` (les types n'existent pas encore). + +- [ ] **Step 3: Write the minimal implementation** + +Créer `sharedUI/src/commonMain/kotlin/com/livrets/ui/GameKeyMapping.kt` : + +```kotlin +package com.livrets.ui + +import androidx.compose.ui.input.key.Key +import androidx.compose.ui.input.key.KeyEventType + +sealed interface KeypadAction { + data class Digit(val char: Char) : KeypadAction + data object Delete : KeypadAction + data object Validate : KeypadAction +} + +object GameKeyMapping { + fun actionFor(key: Key, type: KeyEventType): KeypadAction? { + if (type != KeyEventType.KeyDown) return null + return when (key) { + Key.Zero -> KeypadAction.Digit('0') + Key.One -> KeypadAction.Digit('1') + Key.Two -> KeypadAction.Digit('2') + Key.Three -> KeypadAction.Digit('3') + Key.Four -> KeypadAction.Digit('4') + Key.Five -> KeypadAction.Digit('5') + Key.Six -> KeypadAction.Digit('6') + Key.Seven -> KeypadAction.Digit('7') + Key.Eight -> KeypadAction.Digit('8') + Key.Nine -> KeypadAction.Digit('9') + Key.NumPad0 -> KeypadAction.Digit('0') + Key.NumPad1 -> KeypadAction.Digit('1') + Key.NumPad2 -> KeypadAction.Digit('2') + Key.NumPad3 -> KeypadAction.Digit('3') + Key.NumPad4 -> KeypadAction.Digit('4') + Key.NumPad5 -> KeypadAction.Digit('5') + Key.NumPad6 -> KeypadAction.Digit('6') + Key.NumPad7 -> KeypadAction.Digit('7') + Key.NumPad8 -> KeypadAction.Digit('8') + Key.NumPad9 -> KeypadAction.Digit('9') + Key.Enter, Key.NumPadEnter -> KeypadAction.Validate + Key.Backspace -> KeypadAction.Delete + else -> null + } + } +} +``` + +- [ ] **Step 4: Run the full test suite** + +Run: `./gradlew :sharedUI:jvmTest` +Expected: PASS — les 7 nouveaux tests et tous les tests existants (engine, générateur, persistance, navigation) passent. + +- [ ] **Step 5: Commit** + +```bash +git add sharedUI/src/commonMain/kotlin/com/livrets/ui/GameKeyMapping.kt sharedUI/src/commonTest/kotlin/com/livrets/ui/GameKeyMappingTest.kt +git commit -m "feat: mapping des touches clavier vers les actions du pavé" +``` + +--- + +### Task 2: Câblage clavier dans `GameScreen.PlayingContent` + +**Files:** +- Modify: `sharedUI/src/commonMain/kotlin/com/livrets/ui/GameScreen.kt:82-140` (fonction `PlayingContent` et imports) + +**Interfaces:** +- Consumes: `GameKeyMapping.actionFor(key: Key, type: KeyEventType): KeypadAction?`, `KeypadAction.Digit(char: Char)` / `Delete` / `Validate` (Task 1) ; `engine.onDigit(Char)`, `engine.onDelete()`, `engine.onValidate()` (existants, `GameEngine.kt:31-47`) +- Produces: rien de nouveau (comportement utilisateur uniquement) + +- [ ] **Step 1: Add the imports** + +En haut de `sharedUI/src/commonMain/kotlin/com/livrets/ui/GameScreen.kt`, ajouter aux imports existants : + +```kotlin +import androidx.compose.foundation.focusable +import androidx.compose.ui.focus.FocusRequester +import androidx.compose.ui.focus.focusRequester +import androidx.compose.ui.input.key.key +import androidx.compose.ui.input.key.onPreviewKeyEvent +import androidx.compose.ui.input.key.type +``` + +- [ ] **Step 2: Wire the key handler in `PlayingContent`** + +Dans `GameScreen.kt`, remplacer le corps de `PlayingContent` (lignes 81-93 : la signature et l'ouverture du `Column` avec ses modificateurs actuels) par : + +```kotlin +@Composable +private fun PlayingContent( + engine: GameEngine, + state: GameState.Playing, + progress: Float, + onQuitRequest: () -> Unit, +) { + val focusRequester = remember { FocusRequester() } + LaunchedEffect(Unit) { focusRequester.requestFocus() } + Column( + modifier = Modifier + .fillMaxSize() + .windowInsetsPadding(WindowInsets.safeDrawing) + .padding(24.dp) + .focusRequester(focusRequester) + .focusable() + .onPreviewKeyEvent { event -> + when (val action = GameKeyMapping.actionFor(event.key, event.type)) { + is KeypadAction.Digit -> { + engine.onDigit(action.char) + true + } + KeypadAction.Delete -> { + engine.onDelete() + true + } + KeypadAction.Validate -> { + engine.onValidate() + true + } + null -> false + } + }, + horizontalAlignment = Alignment.CenterHorizontally, + ) { +``` + +Le reste de `PlayingContent` (Row « Question x / y », `LinearProgressIndicator`, texte de la question, saisie, `Keypad`) est inchangé. Le `Keypad` et `FeedbackContent` restent inchangés. + +Notes de conception (pour l'implémenteur) : +- `focusRequester` placé **avant** `focusable` dans la chaîne de modificateurs (convention Compose). +- `onPreviewKeyEvent` est en phase de descente : même si un bouton du pavé a le focus après un clic souris, la racine voit l'événement en premier ; retourner `true` le consomme et empêche Entrée d'activer aussi le bouton. +- `LaunchedEffect(Unit)` se relance à chaque remontée de `PlayingContent` (il quitte la composition pendant le feedback) → le focus est ré-acquis à chaque nouvelle question. +- Pendant le feedback, `PlayingContent` n'est pas composé → les touches sont ignorées, aucune modification nécessaire. + +- [ ] **Step 3: Run the full test suite (compilation jvm incluse)** + +Run: `./gradlew :sharedUI:jvmTest` +Expected: PASS — compilation OK pour toutes les cibles de test, tous les tests passent (aucun test UI existant n'est affecté). + +- [ ] **Step 4: Manual verification on desktop** + +Run: `./gradlew :desktopApp:run` +Dans la fenêtre : lancer une partie, puis vérifier : +1. Les chiffres du rangée du haut et du pavé numérique s'affichent dans la zone de saisie. +2. Backspace efface le dernier chiffre. +3. Entrée (rangée et pavé) valide : feedback vert/rouge s'affiche. +4. Entrée sans saisie : rien ne se passe (pas de validation). +5. Au-delà de 4 chiffres : la saisie ne grossit plus (`MAX_ENTRY_LENGTH`). +6. Après le feedback, la question suivante accepte de nouveau les touches (re-focus). +7. Cliquer d'abord sur un bouton du pavé à la souris, puis Entrée : valide une seule fois (pas de double déclenchement). +8. La touche Échap ne fait rien ; ⌘Q/fermeture de fenêtre fonctionne comme avant. + +Expected: les 8 vérifications passent. + +- [ ] **Step 5: Commit** + +```bash +git add sharedUI/src/commonMain/kotlin/com/livrets/ui/GameScreen.kt +git commit -m "feat: répondre au clavier (chiffres, Entrée, Backspace) sur desktop" +```