Plan d'intégration — Starlight Scroll to Top

Plan d’Intégration — Plugin `starlight-scroll-to-top`

Document de Référence : GettingStarted/40-plan-starlight-scroll-to-top-integration.md
Source Clonée : ~/astro/starlight-scroll-to-top (packages/starlight-scroll-to-top@2.0.0)
Version cible : starlight-scroll-to-top@2.0.0
Compatibilité : @astrojs/starlight@0.42.4 (peerDependency : >=0.41.0)
Méthodologie : Cycle DOC → SPEC → CODE → TEST → INTÉG

1. Synthèse de l’Investigation

L’analyse du code source cloné dans ~/astro/starlight-scroll-to-top démontre :

1.1 Architecture du Plugin

Mécanisme d’injection : Le plugin n’écrase aucun composant Starlight. Il s’appuie sur le hook astro:config:setup d’Astro avec injectScript('page', ...) pour injecter un script client optimisé par Vite.
Cycle de vie SPA / View Transitions : Le script écoute DOMContentLoaded, astro:page-load et astro:before-preparation pour nettoyer et réinitialiser les écouteurs de défilement proprement lors des navigations sans rechargement.
Indicateur de progression (Progress Ring) : Support d’un anneau circulaire SVG autour du bouton (showProgressRing: true) qui se remplit au fur et à mesure du scroll, stylable via les variables CSS Starlight (ex: var(--sl-color-accent)).
Internationalisation (I18N) : Support natif multilingue pour les infobulles (détecte la langue courante via <html lang="..."> avec repli hiérarchique : fr ➔ en ➔ défaut).
Dépendances : 0 dépendance runtime tierce (deps: none).

1.2 Matrice de Compatibilité avec l’existant

Plugin existant	Composants touchés	Conflit potentiel avec `starlight-scroll-to-top`
`starlight-sidebar-topics`	Surcharge `Sidebar`	❌ Aucun conflit (scroll-to-top utilise `injectScript`)
`starlight-view-modes`	Surcharge `SocialIcons`, `PageTitle`, etc.	❌ Aucun conflit
`starlight-giscus`	Surcharge `Pagination`	❌ Aucun conflit
`starlight-page-actions`	Actions de page (header/title)	❌ Aucun conflit
`starlight-docsearch`	Barre de recherche	❌ Aucun conflit

2. Cycle DOC → SPEC → CODE → TEST → INTÉG

Phase 1 : DOC (Documentation préliminaire)

Vérifier la compatibilité des options Starlight CSS (--sl-color-accent, etc.).
Valider le comportement sur mobile, desktop et avec zoom élevé (>300% le script masque automatiquement le bouton pour préserver l’ergonomie).

Phase 2 : SPEC (Spécification de l’intégration)

Ordre des plugins dans apps/web/astro.config.mjs :
1. starlightViewModes(...)
2. starlightSidebarTopics(...)
3. starlightGiscus(...)
4. starlightScrollToTop(...)
5. starlightPageActions(...)
6. starlightDocSearch(...)
Options recommandées :
- position: 'right'
- threshold: 300 (s’affiche après 300px de scroll)
- smoothScroll: true
- showTooltip: true
- tooltipText: { 'fr': 'Retour en haut', 'en': 'Scroll to top' }
- showProgressRing: true
- progressRingColor: 'var(--sl-color-accent)'
- borderRadius: '50' (bouton rond moderne)
- showOnHomepage: false (masqué sur la landing page)

Phase 3 : CODE (Implémentation)

Installation du paquet :

pnpm --filter amn-astro add starlight-scroll-to-top@2.0.0

Mise à jour de la configuration Starlight :
- Fichier : apps/web/astro.config.mjs
- Import de starlightScrollToTop from 'starlight-scroll-to-top'
- Déclaration dans plugins: [...] avec les options spécifiées.

Phase 4 : TEST (Validation locale)

Validation statique et typage :

pnpm --filter amn-astro run typecheck # (astro check)

Build de production Cloudflare :
Terminal window
```
pnpm --filter amn-astro run build
```
Validation visuelle & fonctionnelle :
- Accéder à une page longue (ex: http://localhost:8787/gettingstarted/01-setup-local/).
- Scroller de plus de 300px : le bouton apparaît avec une animation fluide.
- Vérifier le remplissage de l’anneau de progression SVG au scroll.
- Survoler le bouton : tooltip affichant « Retour en haut ».
- Cliquer sur le bouton : remontée fluide (smooth scroll) vers le haut de la page.
- Naviguer vers une autre page (Astro View Transitions) : vérifier que le composant est réinitialisé sans duplication de bouton dans le DOM.

Phase 5 : INTÉG (Capitalisation & Documentation)

Rédiger la documentation d’intégration dédiée :
docs/L2_Presentation/astro/starlight/Starlight-Plugin-Scroll-To-Top.md
Mettre à jour test-docs/starlight-site-update.md (marquer le point 6 comme complété).

3. Matrice de Risques & Atténuations

Risque	Impact	Solution / Atténuation
Chevauchement avec Giscus ou ToC	Bouton recouvrant du texte	Positionnement absolu/fixé (`bottom: 2rem`, `right: 2rem`) avec marge CSS automatique gérée par le plugin.
Navigation SPA (View Transitions)	Boutons dupliqués dans le DOM	Le plugin implémente nativement `astro:before-preparation` et supprime l’ancien élément avant de réinjecter.
Incohérence graphique en mode sombre/clair	Anneau mal contrasté	Utilisation de `var(--sl-color-accent)` assurant un contraste adapté au thème actif Starlight.

4. Prochaine étape

Attendre la confirmation pour lancer l’installation du paquet (pnpm add starlight-scroll-to-top) et réaliser la configuration dans astro.config.mjs.