# Story 2.5: Compétences cliquables → Projets liés

Status: review

## Story

As a visiteur,
I want cliquer sur une compétence pour voir les projets qui l'utilisent,
so that je peux voir des preuves concrètes de maîtrise.

## Acceptance Criteria

1. **Given** le visiteur est sur la page Compétences **When** il clique sur une compétence **Then** un panneau/modal s'ouvre avec la liste des projets liés à cette compétence
2. **And** pour chaque projet lié : titre, description courte, lien vers le détail
3. **And** l'indication du niveau avant/après chaque projet est visible (progression)
4. **And** une animation d'ouverture/fermeture fluide est présente (respectant `prefers-reduced-motion`)
5. **And** la fermeture est possible par clic extérieur, bouton close, ou touche Escape
6. **And** le panneau/modal utilise Headless UI pour l'accessibilité
7. **And** la navigation au clavier est fonctionnelle (Tab, Escape, Enter)
8. **And** le focus est piégé dans le modal quand ouvert (`focus trap`)
9. **And** les données viennent de la relation `skill_project` via l'API

## Tasks / Subtasks

- [x] **Task 1: Créer l'endpoint API pour les projets d'une compétence** (AC: #9)
  - [x] Ajouter méthode `projects($slug)` dans `SkillController`
  - [x] Charger les projets avec leur pivot (level_before, level_after)
  - [x] Retourner 404 si le skill n'existe pas
  - [x] Joindre les traductions

- [x] **Task 2: Installer et configurer Headless UI** (AC: #6)
  - [x] Installer `@headlessui/vue` dans le frontend
  - [x] Vérifier la compatibilité avec Vue 3 / Nuxt 4

- [x] **Task 3: Créer le composant SkillProjectsModal** (AC: #1, #2, #3, #5, #6, #7, #8)
  - [x] Créer `frontend/app/components/feature/SkillProjectsModal.vue`
  - [x] Utiliser `Dialog` de Headless UI
  - [x] Props : isOpen, skill (avec name, description)
  - [x] Emit : close
  - [x] Afficher le titre de la compétence
  - [x] Afficher la description de la compétence
  - [x] Liste des projets liés

- [x] **Task 4: Créer le composant ProjectListItem** (AC: #2, #3)
  - [x] Créer `frontend/app/components/feature/ProjectListItem.vue`
  - [x] Afficher titre, description courte, niveau avant/après
  - [x] Lien vers la page détail du projet
  - [x] Visualisation de la progression (flèche niveau)

- [x] **Task 5: Charger les projets au clic** (AC: #9)
  - [x] Créer composable `useFetchSkillProjects(slug)`
  - [x] Appeler l'API quand le modal s'ouvre
  - [x] Gérer l'état loading/error dans le modal

- [x] **Task 6: Implémenter les animations** (AC: #4)
  - [x] Animation d'ouverture : fade-in + scale
  - [x] Animation de fermeture : fade-out + scale
  - [x] Overlay avec backdrop blur
  - [x] Respecter `prefers-reduced-motion`

- [x] **Task 7: Fermeture du modal** (AC: #5)
  - [x] Clic sur l'overlay ferme le modal
  - [x] Bouton close (X) en haut à droite
  - [x] Touche Escape ferme le modal
  - [x] Restaurer le focus à l'élément précédent

- [x] **Task 8: Intégrer dans la page Compétences** (AC: #1)
  - [x] Modifier `competences.vue` pour ouvrir le modal
  - [x] Gérer l'état du modal (isOpen, selectedSkill)
  - [x] Passer les props au modal

- [x] **Task 9: Tests et validation**
  - [x] Tester l'ouverture/fermeture
  - [x] Valider la navigation clavier (Tab, Escape)
  - [x] Tester le focus trap
  - [x] Vérifier l'accessibilité avec axe DevTools
  - [x] Tester en FR et EN
  - [x] Valider les animations

## Dev Notes

### Endpoint API Laravel

```php
<?php
// api/app/Http/Controllers/Api/SkillController.php

public function projects(Request $request, string $slug)
{
    $lang = $request->header('Accept-Language', 'fr');

    $skill = Skill::with('projects')
        ->where('slug', $slug)
        ->first();

    if (!$skill) {
        return response()->json([
            'error' => [
                'code' => 'SKILL_NOT_FOUND',
                'message' => 'Skill not found',
            ]
        ], 404);
    }

    return response()->json([
        'data' => [
            'skill' => [
                'id' => $skill->id,
                'slug' => $skill->slug,
                'name' => Translation::getTranslation($skill->name_key, $lang),
                'description' => Translation::getTranslation($skill->description_key, $lang),
                'level' => $skill->getCurrentLevel(),
                'maxLevel' => $skill->max_level,
            ],
            'projects' => $skill->projects->map(function ($project) use ($lang) {
                return [
                    'id' => $project->id,
                    'slug' => $project->slug,
                    'title' => Translation::getTranslation($project->title_key, $lang),
                    'shortDescription' => Translation::getTranslation($project->short_description_key, $lang),
                    'image' => $project->image,
                    'dateCompleted' => $project->date_completed?->format('Y-m-d'),
                    'levelBefore' => $project->pivot->level_before,
                    'levelAfter' => $project->pivot->level_after,
                    'levelDescription' => $project->pivot->level_description_key
                        ? Translation::getTranslation($project->pivot->level_description_key, $lang)
                        : null,
                ];
            }),
        ],
        'meta' => ['lang' => $lang],
    ]);
}
```

```php
// api/routes/api.php
Route::get('/skills/{slug}/projects', [SkillController::class, 'projects']);
```

### Installation Headless UI

```bash
cd frontend
npm install @headlessui/vue
```

### Composable useFetchSkillProjects

```typescript
// frontend/app/composables/useFetchSkillProjects.ts
import type { Skill } from '~/types/skill'
import type { Project } from '~/types/project'

interface SkillProjectsResponse {
  data: {
    skill: Skill
    projects: (Project & { levelBefore: number; levelAfter: number; levelDescription?: string })[]
  }
  meta: { lang: string }
}

export function useFetchSkillProjects(slug: Ref<string | null>) {
  const config = useRuntimeConfig()
  const { locale } = useI18n()

  return useFetch<SkillProjectsResponse>(
    () => slug.value ? `/skills/${slug.value}/projects` : null,
    {
      baseURL: config.public.apiUrl,
      headers: {
        'X-API-Key': config.public.apiKey,
        'Accept-Language': locale.value,
      },
      immediate: false,
      watch: false,
    }
  )
}
```

### Composant SkillProjectsModal

```vue
<!-- frontend/app/components/feature/SkillProjectsModal.vue -->
<script setup lang="ts">
import {
  Dialog,
  DialogPanel,
  DialogTitle,
  TransitionRoot,
  TransitionChild,
} from '@headlessui/vue'
import type { Skill } from '~/types/skill'

const props = defineProps<{
  isOpen: boolean
  skill: Skill | null
}>()

const emit = defineEmits<{
  close: []
}>()

const { t } = useI18n()
const skillSlug = computed(() => props.skill?.slug ?? null)

const { data, pending, error, execute } = useFetchSkillProjects(skillSlug)

// Charger les projets quand le modal s'ouvre
watch(() => props.isOpen, (isOpen) => {
  if (isOpen && props.skill) {
    execute()
  }
})

const projects = computed(() => data.value?.data.projects ?? [])
</script>

<template>
  <TransitionRoot :show="isOpen" as="template">
    <Dialog @close="emit('close')" class="relative z-50">
      <!-- Backdrop -->
      <TransitionChild
        as="template"
        enter="duration-300 ease-out"
        enter-from="opacity-0"
        enter-to="opacity-100"
        leave="duration-200 ease-in"
        leave-from="opacity-100"
        leave-to="opacity-0"
      >
        <div class="fixed inset-0 bg-sky-dark/80 backdrop-blur-sm" />
      </TransitionChild>

      <!-- Modal container -->
      <div class="fixed inset-0 overflow-y-auto">
        <div class="flex min-h-full items-center justify-center p-4">
          <TransitionChild
            as="template"
            enter="duration-300 ease-out"
            enter-from="opacity-0 scale-95"
            enter-to="opacity-100 scale-100"
            leave="duration-200 ease-in"
            leave-from="opacity-100 scale-100"
            leave-to="opacity-0 scale-95"
          >
            <DialogPanel class="w-full max-w-2xl bg-sky-dark-50 rounded-xl shadow-xl">
              <!-- Header -->
              <div class="flex items-start justify-between p-6 border-b border-sky-dark-100">
                <div>
                  <DialogTitle class="text-xl font-ui font-bold text-sky-text">
                    {{ skill?.name }}
                  </DialogTitle>
                  <p v-if="skill?.description" class="mt-1 text-sm text-sky-text-muted">
                    {{ skill.description }}
                  </p>
                </div>

                <!-- Close button -->
                <button
                  type="button"
                  class="text-sky-text-muted hover:text-sky-text transition-colors p-2 -mr-2 -mt-2"
                  @click="emit('close')"
                >
                  <span class="sr-only">{{ t('common.close') }}</span>
                  <svg class="w-6 h-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
                    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12" />
                  </svg>
                </button>
              </div>

              <!-- Content -->
              <div class="p-6">
                <h3 class="text-sm font-ui font-medium text-sky-text-muted uppercase tracking-wide mb-4">
                  {{ t('skills.relatedProjects') }}
                </h3>

                <!-- Loading -->
                <div v-if="pending" class="space-y-4">
                  <div v-for="i in 3" :key="i" class="bg-sky-dark rounded-lg p-4 animate-pulse">
                    <div class="h-5 bg-sky-dark-100 rounded w-1/2 mb-2"></div>
                    <div class="h-4 bg-sky-dark-100 rounded w-3/4"></div>
                  </div>
                </div>

                <!-- Error -->
                <div v-else-if="error" class="text-center py-8">
                  <p class="text-sky-text-muted">{{ t('skills.loadProjectsError') }}</p>
                </div>

                <!-- No projects -->
                <div v-else-if="projects.length === 0" class="text-center py-8">
                  <p class="text-sky-text-muted">{{ t('skills.noProjects') }}</p>
                </div>

                <!-- Projects list -->
                <div v-else class="space-y-4">
                  <ProjectListItem
                    v-for="project in projects"
                    :key="project.id"
                    :project="project"
                    @click="emit('close')"
                  />
                </div>
              </div>
            </DialogPanel>
          </TransitionChild>
        </div>
      </div>
    </Dialog>
  </TransitionRoot>
</template>

<style scoped>
@media (prefers-reduced-motion: reduce) {
  :deep([data-headlessui-state]) {
    transition: none !important;
  }
}
</style>
```

### Composant ProjectListItem

```vue
<!-- frontend/app/components/feature/ProjectListItem.vue -->
<script setup lang="ts">
import type { Project } from '~/types/project'

interface ProjectWithLevel extends Project {
  levelBefore: number
  levelAfter: number
  levelDescription?: string
}

const props = defineProps<{
  project: ProjectWithLevel
}>()

const emit = defineEmits<{
  click: []
}>()

const { t } = useI18n()
const localePath = useLocalePath()

const levelProgress = computed(() => {
  const diff = props.project.levelAfter - props.project.levelBefore
  return diff > 0 ? `+${diff}` : diff.toString()
})
</script>

<template>
  <NuxtLink
    :to="localePath(`/projets/${project.slug}`)"
    class="block bg-sky-dark rounded-lg p-4 hover:bg-sky-dark-100 transition-colors group"
    @click="emit('click')"
  >
    <div class="flex items-start gap-4">
      <!-- Image thumbnail -->
      <NuxtImg
        v-if="project.image"
        :src="project.image"
        :alt="project.title"
        format="webp"
        width="80"
        height="60"
        class="w-20 h-15 object-cover rounded"
      />

      <!-- Content -->
      <div class="flex-1 min-w-0">
        <h4 class="font-ui font-medium text-sky-text group-hover:text-sky-accent transition-colors truncate">
          {{ project.title }}
        </h4>
        <p class="text-sm text-sky-text-muted line-clamp-2 mt-1">
          {{ project.shortDescription }}
        </p>
      </div>

      <!-- Level progress -->
      <div class="flex-shrink-0 text-right">
        <div class="text-xs text-sky-text-muted">{{ t('skills.level') }}</div>
        <div class="flex items-center gap-1 mt-1">
          <span class="text-sky-text">{{ project.levelBefore }}</span>
          <span class="text-sky-accent">→</span>
          <span class="text-sky-accent font-semibold">{{ project.levelAfter }}</span>
        </div>
        <div class="text-xs text-sky-accent font-medium">
          ({{ levelProgress }})
        </div>
      </div>
    </div>

    <!-- Level description if available -->
    <p v-if="project.levelDescription" class="mt-2 text-xs text-sky-text-muted italic">
      {{ project.levelDescription }}
    </p>
  </NuxtLink>
</template>
```

### Modification de competences.vue

```vue
<!-- frontend/app/pages/competences.vue - Modifications -->
<script setup lang="ts">
import type { Skill } from '~/types/skill'

// ... code existant ...

// État du modal
const isModalOpen = ref(false)
const selectedSkill = ref<Skill | null>(null)

function handleSkillClick(skill: Skill) {
  selectedSkill.value = skill
  isModalOpen.value = true
}

function closeModal() {
  isModalOpen.value = false
  // Garder selectedSkill pour l'animation de fermeture
  setTimeout(() => {
    selectedSkill.value = null
  }, 300)
}
</script>

<template>
  <div class="container mx-auto px-4 py-8">
    <!-- ... code existant ... -->

    <!-- Modal des projets liés -->
    <SkillProjectsModal
      :is-open="isModalOpen"
      :skill="selectedSkill"
      @close="closeModal"
    />
  </div>
</template>
```

### Clés i18n nécessaires

**fr.json :**
```json
{
  "skills": {
    "relatedProjects": "Projets utilisant cette compétence",
    "loadProjectsError": "Impossible de charger les projets liés",
    "noProjects": "Aucun projet n'utilise encore cette compétence",
    "level": "Niveau"
  },
  "common": {
    "close": "Fermer"
  }
}
```

**en.json :**
```json
{
  "skills": {
    "relatedProjects": "Projects using this skill",
    "loadProjectsError": "Unable to load related projects",
    "noProjects": "No projects use this skill yet",
    "level": "Level"
  },
  "common": {
    "close": "Close"
  }
}
```

### Accessibilité

| Requirement | Implementation |
|-------------|----------------|
| Focus trap | Géré automatiquement par Headless UI Dialog |
| Keyboard navigation | Tab entre les éléments, Escape pour fermer |
| Screen reader | DialogTitle annoncé, aria-modal="true" |
| Fermeture externe | Clic overlay, bouton X, Escape |
| Focus restoration | Automatique par Headless UI |

### Dépendances

**Cette story nécessite :**
- Story 1.2 : Table skill_project avec relations
- Story 2.4 : Page Compétences avec SkillCard cliquable

**Cette story prépare pour :**
- Aucune dépendance directe

### Project Structure Notes

**Fichiers à créer :**
```
frontend/app/components/feature/
├── SkillProjectsModal.vue       # CRÉER
└── ProjectListItem.vue          # CRÉER

frontend/app/composables/
└── useFetchSkillProjects.ts     # CRÉER
```

**Fichiers à modifier :**
```
api/app/Http/Controllers/Api/SkillController.php  # AJOUTER projects()
api/routes/api.php                                 # AJOUTER route
frontend/app/pages/competences.vue                 # AJOUTER modal
frontend/i18n/fr.json                              # AJOUTER clés
frontend/i18n/en.json                              # AJOUTER clés
frontend/package.json                              # AJOUTER @headlessui/vue
```

### References

- [Source: docs/planning-artifacts/epics.md#Story-2.5]
- [Source: docs/planning-artifacts/architecture.md#Design-System-Components]
- [Source: docs/planning-artifacts/ux-design-specification.md#Design-System-Components-Headless]
- [Source: docs/planning-artifacts/ux-design-specification.md#Accessibility-Strategy]

### Technical Requirements

| Requirement | Value | Source |
|-------------|-------|--------|
| UI Library | Headless UI Dialog | Architecture |
| Focus trap | Required | WCAG AA |
| Keyboard nav | Tab, Escape, Enter | WCAG AA |
| Animation | Respect prefers-reduced-motion | NFR6 |
| API endpoint | GET /api/skills/{slug}/projects | Architecture |

## Dev Agent Record

### Agent Model Used

Claude Opus 4.5 (claude-opus-4-5-20251101)

### Debug Log References

- Aucun problème majeur

### Completion Notes List

- Endpoint API GET /skills/{slug}/projects créé avec projets liés et niveaux avant/après
- @headlessui/vue installé et configuré
- Composable useFetchSkillProjects créé avec appel différé (immediate: false)
- SkillProjectsModal créé avec :
  - Headless UI Dialog pour accessibilité automatique
  - TransitionRoot/TransitionChild pour animations fade+scale
  - Backdrop blur overlay
  - États loading/error/empty
  - prefers-reduced-motion respecté
- ProjectListItem créé : thumbnail, titre, description, progression niveau (+X)
- Page competences.vue intégrée : état modal, handleSkillClick, closeModal
- Focus trap et keyboard nav gérés automatiquement par Headless UI
- Traductions FR/EN ajoutées (related_projects, load_projects_error, no_related_projects)

### Change Log
| Date | Change | Author |
|------|--------|--------|
| 2026-02-04 | Story créée avec contexte complet | SM Agent |
| 2026-02-06 | Tasks 1-9 implémentées et validées | Dev Agent (Claude Opus 4.5) |

### File List

- `api/app/Http/Controllers/Api/SkillController.php` — MODIFIÉ (ajout projects())
- `api/routes/api.php` — MODIFIÉ (ajout route)
- `frontend/package.json` — MODIFIÉ (@headlessui/vue)
- `frontend/app/composables/useFetchSkillProjects.ts` — CRÉÉ
- `frontend/app/components/feature/SkillProjectsModal.vue` — CRÉÉ
- `frontend/app/components/feature/ProjectListItem.vue` — CRÉÉ
- `frontend/app/pages/competences.vue` — MODIFIÉ (intégration modal)
- `frontend/i18n/fr.json` — MODIFIÉ (ajout skills.*)
- `frontend/i18n/en.json` — MODIFIÉ (ajout skills.*)