Mixin horizontal-scroll-snap

[cedric07]

Contexte et objectif

Cette PR ajoute un mixin SCSS réutilisable pour des listes ou rangées d’éléments défilables horizontalement, avec scroll snap natif (sans Swiper ni JavaScript). Le cas d’usage visé est typiquement le mobile / petit écran : une carte (ou slide) occupe presque toute la largeur, avec un aperçu de la suivante à droite pour inciter au scroll, tout en respectant le full-bleed par rapport aux gouttières du layout WordPress (--responsive--gutter-*).

Fichier livré : src/scss/02-tools/_m-horizontal-scroll-snap.scss.

Le mixin n’est pas branché sur un composant du thème par défaut : les projets l’appliquent sur le conteneur scrollable (souvent un <ul>) via @include horizontal-scroll-snap, en général derrière un breakpoints(sm, max) pour ne pas remplacer un carrousel desktop.

Comportement CSS

Conteneur (élément qui reçoit le mixin)

Propriété / mécanisme	Rôle
display: flex + flex-wrap: nowrap	Rangée horizontale d’items
gap	Espacement entre slides (--horizontal-scroll-gap)
Largeur + marges / padding inline négatifs	Élargit le track au-delà du conteneur contenu pour aligner le scroll sur les bords visuels de la page (gouttières theme.json)
overflow-x: auto	Défilement horizontal
overscroll-behavior-x: contain	Limite la propagation du scroll au viewport parent
scroll-snap-type: x mandatory	Snap obligatoire sur l’axe X
scroll-padding-inline	Aligne le snap avec les gouttières (première slide flush au bord utile)
-webkit-overflow-scrolling: touch	Scroll plus fluide sur iOS
scrollbar-invisible	Barre de scroll masquée (mixin existant m-scrollbar) — à utiliser sur un sous-conteneur, pas sur html/body (cf. alerte du mixin scrollbar)

Items (sélecteur configurable)

Par défaut : enfants directs > li (listes sémantiques).

Propriété	Rôle
flex: 0 0 calc(100% - var(--horizontal-scroll-peek))	Une slide ≈ pleine largeur utile, moins la zone de peek
min-width: 0	Évite le débordement flex des contenus internes
scroll-snap-align: start	Accrochage au début de chaque item

Variables CSS personnalisables

Définies sur le conteneur ; surcharge optionnelle en CSS :

Custom property	Défaut (via mixin)	Usage
--horizontal-scroll-gap	$settings-spacing-xs	gap entre les slides
--horizontal-scroll-peek	gap + $settings-spacing-xs	Partie visible de la slide suivante

API du mixin

@mixin horizontal-scroll-snap($item-selector: "> li")

• $item-selector : sélecteur des slides (relatif au conteneur). Ex. "> .card" si les enfants ne sont pas des <li>.

Exemple d’intégration

@use "../02-tools/m-horizontal-scroll-snap" as *;
@use "../02-tools/m-breakpoint" as *;

.my-cards {
  @include breakpoints(sm, max) {
    @include horizontal-scroll-snap;
  }
}

Markup typique :

<ul class="my-cards">
  <li>…</li>
  <li>…</li>
</ul>

Surcharge des espacements :

.my-cards {
  --horizontal-scroll-gap: var(--wp--preset--spacing--md);
  --horizontal-scroll-peek: 2rem;

  @include breakpoints(sm, max) {
    @include horizontal-scroll-snap;
  }
}

Accessibilité et choix produit

• Pas de widget carrousel : c’est une zone scrollable native. Pas d’annonces « slide 2 sur 5 », pas de boutons prev/next imposés par le mixin — adapté quand le contenu de chaque item est déjà parcourable au clavier (liens, boutons) et qu’on évite une couche JS lourde sur mobile.
• Le scroll horizontal reste disponible au clavier (focus dans la zone + touches de défilement selon navigateur/OS) et au touch / trackpad.
• Masquer la scrollbar réduit l’indicateur visuel du défilement : à réserver aux contextes où le peek et le geste sont suffisants ; ne pas en abuser sur de longues listes critiques sans autre repère.
• Pour un carrousel avec navigation, annonces et pagination accessibles, préférer la brique Swiper (Slider) du framework.

Dépendances internes

• theme-json : espacements $settings-spacing-xs
• m-scrollbar : scrollbar-invisible
• Variables globales déjà posées dans _variables-css.scss : --responsive--gutter-left, --responsive--gutter-right

Synthèse

Nouveau mixin horizontal-scroll-snap : piste horizontale full-bleed, snap mandatory, peek de la slide suivante, scrollbar invisible, API simple ($item-selector + 2 custom properties). À combiner avec les breakpoints du thème pour les patterns « carrousel CSS » mobile, en complément (et non en doublon) de Swiper sur les vues desktop ou les besoins a11y avancés.

---

Note

Low Risk
Adds an unused SCSS mixin only; no runtime or theme behavior changes until a component opts in.

Overview
Adds a new SCSS tool mixin horizontal-scroll-snap in _m-horizontal-scroll-snap.scss for opt-in, mobile-style horizontal rows that use native scroll-snap instead of Swiper/JS.

The mixin turns a container (default slide selector > li) into a nowrap flex track with overflow-x: auto, mandatory X snap, overscroll-behavior-x: contain, and scrollbar-invisible. It full-bleeds past content width using --responsive--gutter-left/right (negative margins + padding + scroll-padding-inline). Each item is sized to calc(100% - peek) so the next slide shows on the right; --horizontal-scroll-gap and --horizontal-scroll-peek (and optional $item-selector) can be overridden on the container before @include.

Nothing in the theme includes this mixin by default—consumers import it and apply it (typically behind a small-screen breakpoint).

^{Reviewed by Cursor Bugbot for commit dd2ed26. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 5c9164b. Configure here.}

[rsanchez-beapi]

Nice ;)