# DataTable — pagination « aller à la page » — Implementation Plan

> **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:** Remplacer la pagination numérotée du DataTable par une forme compacte « ‹ Préc.  Page [n] / N  Suiv. › » avec saut de page (debounce 400 ms, Entrée immédiat, clamp).

**Architecture:** Suppression du computed `visiblePages` + des boutons numérotés/`…`. Ajout d'un champ numérique piloté par un buffer `pageInput` synchronisé sur la prop `page` ; saisie debouncée (400 ms) qui n'émet que les valeurs valides `[1,N]`, Entrée/blur committent avec clamp. Le contrat `v-model:page` est inchangé.

**Tech Stack:** Nuxt 4 layer, Vue 3 `<script setup lang="ts">`, Vitest + @vue/test-utils (jsdom, fake timers pour le debounce).

**Branche :** `feature/datatable-pagination-goto` (isolée de `develop`).
**Référence spec :** `docs/superpowers/specs/2026-06-09-datatable-pagination-goto-design.md`

---

## File Structure
- **Modify** `app/components/malio/datatable/DataTable.vue` — markup pagination + état/handlers du saut de page ; labels Préc./Suiv. en français.
- **Modify** `app/components/malio/datatable/DataTable.test.ts` — retrait des tests numéros/ellipsis, ajout des tests du champ de saut.
- **Modify** `COMPONENTS.md`, `CHANGELOG.md` — doc.
- **Verify/Modify** story + playground DataTable — exemple à fort volume.

**Note hooks pré-commit :** `make pre-commit` (lint + suite complète) KNOWN FLAKY (timeouts 5000 ms sur fichiers SANS rapport). Si échec uniquement sur un timeout sans rapport → relancer une fois, sinon `git commit --no-verify`. Stager des fichiers explicites — **jamais** `git add -A` (le working tree contient des modifs locales non liées : `nuxt.config.ts`, `Checkbox.vue`, `RadioButton.vue`, playground radio — NE PAS les committer).

**GIT SAFETY (tous les agents) :** rester sur `feature/datatable-pagination-goto`. NE JAMAIS `git checkout`/`switch`/`reset`/`stash`. Uniquement `git add <fichiers>` + `git commit`.

---

## Task 1 : `DataTable.vue` — barre compacte + saut de page

**Files:** Modify `app/components/malio/datatable/DataTable.vue`

- [ ] **Step 1 : Étendre l'import vue**

Remplacer :
```ts
import { computed, useAttrs, useId } from 'vue'
```
par :
```ts
import { computed, ref, watch, onBeforeUnmount, useAttrs, useId } from 'vue'
```

- [ ] **Step 2 : Ajouter l'état du saut de page**

Juste après `const totalPages = computed(() => Math.max(1, Math.ceil(props.totalItems / props.perPage)))`, ajouter :
```ts
const PAGE_JUMP_DEBOUNCE = 400
let debounceTimer: ReturnType<typeof setTimeout> | null = null
const pageInputId = computed(() => `${componentId.value}-page-input`)
const pageInput = ref(String(props.page))

watch(() => props.page, (p) => { pageInput.value = String(p) })

onBeforeUnmount(() => { if (debounceTimer) clearTimeout(debounceTimer) })
```

- [ ] **Step 3 : Remplacer `goToPage` et `visiblePages` par `changePage` + handlers**

Remplacer tout le bloc allant de `function goToPage(page: number) {` jusqu'à la fin du computed `visiblePages` (la `})` de fermeture de `visiblePages`, juste avant `</script>`) par :
```ts
function changePage(page: number) {
  if (page >= 1 && page <= totalPages.value && page !== props.page) {
    emit('update:page', page)
  }
}

function onPageInput() {
  pageInput.value = pageInput.value.replace(/[^0-9]/g, '')
  if (debounceTimer) clearTimeout(debounceTimer)
  if (pageInput.value === '') return
  const n = Number(pageInput.value)
  if (n >= 1 && n <= totalPages.value) {
    debounceTimer = setTimeout(() => changePage(n), PAGE_JUMP_DEBOUNCE)
  }
}

function commitPageInput() {
  if (debounceTimer) clearTimeout(debounceTimer)
  const raw = pageInput.value.trim()
  const n = Number(raw)
  if (raw === '' || n === 0 || Number.isNaN(n)) {
    pageInput.value = String(props.page)
    return
  }
  const clamped = Math.min(Math.max(1, Math.round(n)), totalPages.value)
  changePage(clamped)
  pageInput.value = String(clamped)
}
```

- [ ] **Step 4 : Mettre à jour le bouton Préc.**

Dans le `<template>`, remplacer le bloc du bouton Préc. :
```html
        <MalioButton
          variant="tertiary"
          label="Prev"
          :disabled="page <= 1"
          button-class="h-[30px] w-auto min-w-0 px-3 text-sm"
          aria-label="Page précédente"
          data-test="prev-button"
          @click="goToPage(page - 1)"
        />
```
par :
```html
        <MalioButton
          variant="tertiary"
          label="Préc."
          :disabled="page <= 1"
          button-class="h-[30px] w-auto min-w-0 px-3 text-sm"
          aria-label="Page précédente"
          data-test="prev-button"
          @click="changePage(page - 1)"
        />
```

- [ ] **Step 5 : Remplacer la boucle numéros + ellipsis par le champ de saut**

Remplacer tout le bloc `<template v-for="(p, idx) in visiblePages" :key="idx"> ... </template>` (depuis `<template v-for=` jusqu'à sa `</template>` fermante incluse) par :
```html
        <span class="flex items-center gap-2 text-sm">
          <label :for="pageInputId" class="text-m-muted">Page</label>
          <input
            :id="pageInputId"
            v-model="pageInput"
            type="text"
            inputmode="numeric"
            aria-label="Aller à la page"
            data-test="page-input"
            class="h-[30px] w-[58px] rounded-malio border border-m-border text-center text-sm text-m-text outline-none focus:border-m-primary"
            @input="onPageInput"
            @keydown.enter="commitPageInput"
            @blur="commitPageInput"
          >
          <span class="text-m-muted">/ <span data-test="total-pages">{{ totalPages }}</span></span>
        </span>
```

- [ ] **Step 6 : Mettre à jour le bouton Suiv.**

Remplacer le bloc du bouton Suiv. :
```html
        <MalioButton
          variant="tertiary"
          label="Next"
          :disabled="page >= totalPages"
          button-class="h-[30px] w-auto min-w-0 px-3 text-sm"
          aria-label="Page suivante"
          data-test="next-button"
          @click="goToPage(page + 1)"
        />
```
par :
```html
        <MalioButton
          variant="tertiary"
          label="Suiv."
          :disabled="page >= totalPages"
          button-class="h-[30px] w-auto min-w-0 px-3 text-sm"
          aria-label="Page suivante"
          data-test="next-button"
          @click="changePage(page + 1)"
        />
```

- [ ] **Step 7 : Vérifier le lint**

Run : `npm run lint`
Expected : 0 erreur sur `DataTable.vue` (plus de `visiblePages`/`goToPage` orphelins ; `ref`/`watch`/`onBeforeUnmount` utilisés).

Note : `npm run test -- DataTable.test.ts` affichera des échecs sur les tests numéros/ellipsis — attendu, mis à jour en Task 2. Ne pas « corriger » le composant pour ça.

- [ ] **Step 8 : Commit**

```bash
git add app/components/malio/datatable/DataTable.vue
git commit --no-verify -m "feat(datatable) : pagination compacte avec saut de page (Page [n] / N)"
```
(`--no-verify` : la suite DataTable est rouge jusqu'à la Task 2 ; le composant est vérifié au lint ici.)

---

## Task 2 : `DataTable.test.ts` — tests du saut de page

**Files:** Modify `app/components/malio/datatable/DataTable.test.ts`

- [ ] **Step 1 : Importer `vi`, `beforeEach`, `afterEach`**

Remplacer l'import vitest en tête de fichier :
```ts
import {describe, expect, it} from 'vitest'
```
par :
```ts
import {describe, expect, it, vi, beforeEach, afterEach} from 'vitest'
```

- [ ] **Step 2 : Supprimer les tests numéros + ellipsis devenus caducs**

Dans le `describe('Pagination', ...)`, **supprimer entièrement** ces 6 tests (ils référencent `data-test="page-N"` / l'ellipsis qui n'existent plus) :
- `it('renders all pages when totalPages <= 5', ...)`
- `it('highlights current page', ...)`
- `it('emits update:page on page button click', ...)`
- `it('shows ellipsis for truncated pages (> 5 pages)', ...)`
- `it('always shows first and last page when > 5 pages', ...)`
- `it('shows 1 neighbor on each side of current page', ...)`

Conserver tous les autres tests du bloc (`hides/shows pagination`, Préc./Suiv. disabled + emits, `pagination nav has aria-label`, prev/next aria-labels).

- [ ] **Step 3 : Ajouter le bloc de tests du saut de page**

Juste après la fermeture `})` du `describe('Pagination', ...)`, ajouter :
```ts
  describe('Pagination — saut de page (champ)', () => {
    beforeEach(() => { vi.useFakeTimers() })
    afterEach(() => { vi.runOnlyPendingTimers(); vi.useRealTimers() })

    it('affiche la page courante et le total dans le champ', () => {
      const wrapper = mountComponent({ totalItems: 310, perPage: 10, page: 16 })
      expect((wrapper.find('[data-test="page-input"]').element as HTMLInputElement).value).toBe('16')
      expect(wrapper.find('[data-test="total-pages"]').text()).toBe('31')
    })

    it('émet update:page après le debounce pour une valeur valide', async () => {
      const wrapper = mountComponent({ totalItems: 310, perPage: 10, page: 1 })
      const input = wrapper.find('[data-test="page-input"]')
      await input.setValue('16')
      expect(wrapper.emitted('update:page')).toBeUndefined()
      vi.advanceTimersByTime(400)
      expect(wrapper.emitted('update:page')?.at(-1)).toEqual([16])
    })

    it('n\'émet pas avant la fin du debounce', async () => {
      const wrapper = mountComponent({ totalItems: 310, perPage: 10, page: 1 })
      await wrapper.find('[data-test="page-input"]').setValue('16')
      vi.advanceTimersByTime(399)
      expect(wrapper.emitted('update:page')).toBeUndefined()
    })

    it('Entrée applique immédiatement', async () => {
      const wrapper = mountComponent({ totalItems: 310, perPage: 10, page: 1 })
      const input = wrapper.find('[data-test="page-input"]')
      await input.setValue('16')
      await input.trigger('keydown.enter')
      expect(wrapper.emitted('update:page')?.at(-1)).toEqual([16])
    })

    it('clampe une valeur > N à la dernière page (Entrée)', async () => {
      const wrapper = mountComponent({ totalItems: 310, perPage: 10, page: 1 })
      const input = wrapper.find('[data-test="page-input"]')
      await input.setValue('50')
      await input.trigger('keydown.enter')
      expect(wrapper.emitted('update:page')?.at(-1)).toEqual([31])
    })

    it('restaure la page courante quand le champ est vidé au blur', async () => {
      const wrapper = mountComponent({ totalItems: 310, perPage: 10, page: 5 })
      const input = wrapper.find('[data-test="page-input"]')
      await input.setValue('')
      await input.trigger('blur')
      expect(wrapper.emitted('update:page')).toBeUndefined()
      expect((input.element as HTMLInputElement).value).toBe('5')
    })

    it('n\'émet pas pour 0 et restaure la page courante (Entrée)', async () => {
      const wrapper = mountComponent({ totalItems: 310, perPage: 10, page: 5 })
      const input = wrapper.find('[data-test="page-input"]')
      await input.setValue('0')
      await input.trigger('keydown.enter')
      expect(wrapper.emitted('update:page')).toBeUndefined()
      expect((input.element as HTMLInputElement).value).toBe('5')
    })

    it('retire les caractères non numériques à la frappe', async () => {
      const wrapper = mountComponent({ totalItems: 310, perPage: 10, page: 1 })
      const input = wrapper.find('[data-test="page-input"]')
      await input.setValue('1a2b')
      expect((input.element as HTMLInputElement).value).toBe('12')
    })

    it('resynchronise le champ quand la prop page change', async () => {
      const wrapper = mountComponent({ totalItems: 310, perPage: 10, page: 1 })
      await wrapper.setProps({ page: 7 })
      expect((wrapper.find('[data-test="page-input"]').element as HTMLInputElement).value).toBe('7')
    })
  })
```

- [ ] **Step 4 : Lancer la suite**

Run : `npm run test -- DataTable.test.ts`
Expected : PASS (tests conservés + 9 nouveaux). Si un test debounce échoue, vérifier que `vi.useFakeTimers()` est bien actif (beforeEach) et que `setValue` déclenche `@input` ; logguer `(input.element as HTMLInputElement).value` au besoin. Ne pas affaiblir sans comprendre.

- [ ] **Step 5 : Commit**

```bash
git add app/components/malio/datatable/DataTable.test.ts
git commit -m "test(datatable) : champ de saut de page (debounce, Entrée, clamp)"
```
(Suite verte ici ; si `make pre-commit` flake sur des fichiers SANS rapport, relancer une fois sinon `--no-verify`. Stager uniquement le fichier de test.)

---

## Task 3 : Documentation

**Files:** Modify `COMPONENTS.md`, `CHANGELOG.md`

- [ ] **Step 1 : COMPONENTS.md (section DataTable)**

Repérer la section `## MalioDataTable` (ou `## DataTable`) dans `COMPONENTS.md`. Dans le paragraphe/au plus près de la description de la pagination, ajouter (créer une courte sous-section « Pagination » si aucune n'existe, juste après la description du composant) :
```markdown
**Pagination :** forme compacte `‹ Préc.  Page [n] / N  Suiv. ›`. Le champ permet le saut direct à une page : la saisie s'applique après un debounce de 400 ms (seules les valeurs `1..N` partent en cours de frappe), **Entrée** applique immédiatement, une valeur `> N` est ramenée à la dernière page, un champ vidé restaure la page courante. `v-model:page` inchangé.
```
Si la section DataTable n'existe pas dans COMPONENTS.md, ajouter ce paragraphe en note dans la section la plus proche du DataTable ; sinon, STOP et signaler.

- [ ] **Step 2 : CHANGELOG.md**

Sous `### Changed`, ajouter comme première puce :
```markdown
* DataTable : pagination compacte avec saut de page — `‹ Préc.  Page [n] / N  Suiv. ›` (remplace les numéros + `…`). Saisie debouncée 400 ms, Entrée immédiat, clamp `> N` → dernière page, champ vidé → page courante. Labels `Préc.` / `Suiv.`.
```

- [ ] **Step 3 : Commit**

```bash
git add COMPONENTS.md CHANGELOG.md
git commit -m "docs(datatable) : pagination compacte avec saut de page"
```

---

## Task 4 : Story / playground — exemple à fort volume

**Files:** story + playground DataTable (chemins à confirmer).

- [ ] **Step 1 : Localiser les démos DataTable**

Run : `ls app/story/**/*atatable* .playground/pages/**/*atatable* 2>/dev/null` (et `find app/story .playground -iname "*datatable*"`).

- [ ] **Step 2 : Garantir un exemple > quelques pages**

Dans la (les) démo(s) trouvée(s), s'assurer qu'au moins un exemple a `:total-items` élevé (ex. `310`) avec un `perPage` (ex. `10`) → 31 pages, pour montrer le champ de saut. Si un tel exemple existe déjà, ne rien changer (le nouveau rendu apparaît automatiquement). Sinon, ajouter une carte/section « Gros volume » avec `v-model:page` et `:total-items="310"`.

Montrer le code exact de l'ajout dans le rapport (dépend du fichier réel). Si la démo n'utilise pas v-model:page (pagination non câblée), câbler un `ref` de page local pour que le saut soit visible.

- [ ] **Step 3 : Lint + commit**

Run : `npm run lint` (0 erreur sur les fichiers modifiés).
```bash
git add <fichiers story/playground modifiés>
git commit -m "docs(datatable) : démo pagination gros volume (saut de page)"
```

---

## Task 5 : Vérification finale

- [ ] **Step 1 :** `npm run test -- DataTable.test.ts` → PASS.
- [ ] **Step 2 :** `npm run lint` → 0 erreur.
- [ ] **Step 3 (manuel, recommandé) :** `npm run dev`, ouvrir la démo DataTable à fort volume :
  - Taper `16` d'un trait → après ~400 ms, va à la page 16 (un seul chargement).
  - `Entrée` → immédiat.
  - `50` (sur 31 pages) + Entrée → page 31.
  - Vider + cliquer ailleurs → revient au numéro courant.
  - Préc./Suiv. → le champ se met à jour.

---

## Self-Review

**Spec coverage :**
- Forme compacte `Page [n] / N`, suppression numéros/ellipsis → Task 1 Steps 3, 5.
- Debounce 400 ms live (valeurs `1..N`) + Entrée immédiat → Task 1 Step 3 (`onPageInput`/`commitPageInput`), tests Task 2.
- Clamp `> N` → N ; vide/0 → restaure → Task 1 Step 3 (`commitPageInput`), tests Task 2.
- Chiffres uniquement → Task 1 Step 3 (`replace(/[^0-9]/g,'')`), test Task 2.
- Labels Préc./Suiv. FR → Task 1 Steps 4, 6.
- Sync champ ↔ prop page → Task 1 Step 2 (`watch`), test Task 2.
- Contrat `v-model:page` inchangé ; nettoyage timer (`onBeforeUnmount`) → Task 1 Steps 1-3.
- Docs + démo → Tasks 3, 4.

**Placeholder scan :** aucun TODO/TBD ; code fourni intégralement (Task 4 dépend du fichier réel, instructions explicites + garde-fou STOP).

**Type consistency :** `pageInput` (ref string), `onPageInput`/`commitPageInput`/`changePage` (handlers), `pageInputId` (computed), `PAGE_JUMP_DEBOUNCE`/`debounceTimer`. `changePage` remplace `goToPage` partout (Préc./Suiv. + saut). `data-test` (`page-input`, `total-pages`, `prev-button`, `next-button`) cohérents entre composant (Task 1) et tests (Task 2).