Skip to content

robinlopez/gridaflex

BranchesTags

Repository files navigation

Gridaflex

Un système de mise en page flexbox à axes X / Y : des groupes horizontaux ou verticaux (flex-x / flex-y) remplis de cellules (cell), sur un moteur gap moderne, sans marges ni paddings négatifs.

Le préfixe est flex- (pas grid-) car c'est bien du flexbox, à distinguer de CSS Grid Layout.

D'où ça vient. Gridaflex reprend l'API et les noms de classes d'une grille historique très répandue (la grille XY de Foundation), pour que les équipes n'aient rien à réapprendre — mais son moteur est entièrement modernisé. Là où l'ancienne grille simulait les gouttières avec des marges/paddings négatifs (sources de conflits avec gap/flex/CSS Grid), Gridaflex utilise directement column-gap / row-gap.

Le moteur en bref

Concept Approche héritée Gridaflex
Gouttières (gap) marges négatives + marges sur cellules column-gap / row-gap par axe
Gouttières padding padding + marge négative de compensation padding interne (border-box)
Valeur de gouttière recopiée dans chaque media-query variables CSS d'axe --flex-gap-x / --flex-gap-y
Largeur d'une cellule calc(% - gutter) (approximatif) calc(f·100% − (1−f)·gap) — exact, gap-aware, sans override

La formule clé : pour une cellule de fraction f, dans une grille à gouttière g, la largeur exacte est f·100% − (1−f)·g. Vérifiable : 3 cellules desktop-4 (f = 1/3) donnent chacune 33.33% − 0.667g, soit (100% − 2g) / 3. ✔

Installation

npm install gridaflex

Quel mode choisir ?

Votre besoin Mode Comment
Juste les classes, sans build Sass CSS compilé un <link> vers le .min.css
Les classes, mais avec vos réglages (colonnes, breakpoints, gouttières) Sass + config un fichier de config (voir plus bas)
Une grille sémantique (vos propres sélecteurs, pas de classes utilitaires) API Sass les mixins xy-flex*

=== "CSS compilé"

```html
<link rel="stylesheet" href="node_modules/gridaflex/dist/gridaflex.min.css">
```

=== "Sass + config (recommandé)"

```scss
// Surcharger les réglages AVANT d'émettre les classes
@use 'gridaflex/src/settings' with ($flex-columns: 12);
@use 'gridaflex/src/classes';
```

=== "API Sass sémantique"

```scss
@use 'gridaflex' as flex;

.galerie {
  @include flex.xy-flex;
  @include flex.xy-flex-margin(xy);
  @include flex.xy-flex-layout(3, '.item');
}
```

🤖 Vous codez avec un assistant IA ? Le package fournit llms.txt et gridaflex.skill.md à embarquer dans votre projet pour qu'il maîtrise la grille — voir Assistant IA.

Classes disponibles

  • Groupes : flex-x, flex-y, cell
  • Gouttières (gap, par axe) : flex-gap-x (= column-gap), flex-gap-y (= row-gap), flex-gap / flex-gap-xy (les deux). Padding : flex-padding-x/y/xy. Alias de compat : flex-margin-*.
  • Conteneur : flex-container, .fluid, .full
  • Tailles : phone-1…phone-12 (et tablet-portrait-, desktop-, … selon vos breakpoints)
  • Auto : auto, shrink, [bp]-auto, [bp]-shrink
  • Offsets : [bp]-offset-[n]
  • Block grid : [bp]-up-[n]
  • Collapse : [bp]-gap-collapse (alias [bp]-margin-collapse), [bp]-padding-collapse
  • Frame : flex-frame, [bp]-flex-frame, cell-block, cell-block-y, cell-block-container
  • Alignement : align-left/right/center/justify/spaced, align-top/middle/bottom/stretch, align-self-*, align-center-middle
  • Ordre : [bp]-order-[n]
  • Helpers flex : flex-box, flex-dir-*, flex-child-* (+ variantes responsive)
  • Visibilité : show-for-[bp], hide-for-[bp], show-for-[bp]-only, hide-for-[bp]-only, hide, invisible, visible

Exemple

<div class="flex-container">
  <div class="flex-x flex-gap-x">
    <div class="cell tablet-portrait-6 desktop-4">12 / 6 / 4</div>
    <div class="cell tablet-portrait-6 desktop-8">12 / 6 / 8</div>
  </div>
</div>

Breakpoints : sémantique & responsive

Les breakpoints sont renommables et extensibles. Les classes de grille et le mixin breakpoint() se génèrent à partir de vos noms.

@use 'gridaflex/src/settings' with (
  $breakpoints: (
    'phone': 0,             // le premier DOIT valoir 0
    'tablet-portrait': 600px,
    'tablet-landscape': 900px,
    'desktop': 1200px,
    'big-desktop': 1800px,
  ),
  $breakpoint-classes: (phone tablet-portrait tablet-landscape desktop big-desktop)
);
@use 'gridaflex/src/classes';

Vous obtenez alors phone-12, desktop-6, tablet-portrait-up-3, desktop-offset-2, big-desktop-auto… Ajouter un breakpoint = ajouter une clé.

Le mixin breakpoint()

Reprend la logique Foundation (limites en em, compatibles zoom) :

@use 'gridaflex' as flex;

.menu {
  @include flex.breakpoint(tablet-portrait only) { flex-direction: column; }
  @include flex.breakpoint(desktop)              { gap: 24px; }       // et au-dessus
  @include flex.breakpoint(desktop down)         { padding: 8px; }
  @include flex.breakpoint(768px)                { font-size: 14px; } // valeur brute → em
  @include flex.breakpoint(landscape)            { height: 100vh; }
  @include flex.breakpoint(retina)               { /* @2x */ }
}
Forme Génère
breakpoint(X) X et au-dessus (min-width)
breakpoint(X down) X et en-dessous (max-width)
breakpoint(X only) la plage exacte
breakpoint(768px) valeur px/rem/em → em
breakpoint(landscape|portrait) orientation
breakpoint(retina) résolution HiDPI

Visibilité responsive

Mêmes classes que Foundation : show-for-[bp], hide-for-[bp], show-for-[bp]-only, hide-for-[bp]-only, plus .hide / .invisible / .visible et les variantes landscape/portrait. Mixins équivalents : show-for($bp), hide-for($bp), show-for-only($bp), hide-for-only($bp).

Fichier de configuration

Le principe : un seul fichier d'entrée qui (1) règle les variables puis (2) émet les classes. C'est le seul endroit où configurer Gridaflex.

1. Copiez le template gridaflex.config.example.scss dans votre projet, par ex. _gridaflex-settings.scss :

cp node_modules/gridaflex/gridaflex.config.example.scss src/styles/_gridaflex-settings.scss

2. Ajustez vos réglages dans le with (…) (colonnes, breakpoints, gouttières).

3. Importez ce fichier depuis votre bundle principal — et lui seul (il émet déjà les classes) :

// main.scss
@use 'gridaflex-settings';

Le contenu type du fichier de config :

// _gridaflex-settings.scss
@use 'gridaflex/src/settings' with (
  $flex-columns: 12,
  $breakpoints: ('phone': 0, 'tablet': 768px, 'desktop': 1200px),
  $breakpoint-classes: (phone tablet desktop),
  $flex-margin-gutters: ('phone': 16px, 'desktop': 24px),
);
@use 'gridaflex/src/classes';   // ← émet toutes les classes avec VOS réglages

⚠️ Ordre des @use (piège Sass classique). @use … with (…) doit être dans le premier fichier qui charge settings. Mettez donc le with (…) et l'@use 'src/classes' dans ce même fichier. Un with (…) placé après coup, ou dans un autre fichier, sera ignoré (erreur Sass « module already loaded »).

Gestion des axes

flex-gap-x ne gère que l'axe horizontal (column-gap), flex-gap-y que le vertical (row-gap). Combinez-les, ou prenez le raccourci. Gap et padding sont indépendants et cumulables :

<div class="flex-x flex-gap-x">…</div>              <!-- horizontal seul -->
<div class="flex-x flex-gap-x flex-gap-y">…</div>    <!-- les deux, indépendamment -->
<div class="flex-x flex-gap-xy">…</div>              <!-- les deux d'un coup -->
<div class="flex-x flex-gap-xy flex-padding-y">…</div> <!-- gap horizontal + padding vertical -->

Les classes flex-margin-* existent en alias de compatibilité (comportement identique) ; privilégiez flex-gap-* dans le code neuf.

Surcharge à la volée

Les gouttières vivent dans des variables CSS d'axe, surchargeables par instance :

<div class="flex-x flex-gap-x"  style="--flex-gap-x: 8px">…</div>
<div class="flex-x flex-gap-xy" style="--flex-gap-x: 8px; --flex-gap-y: 16px">…</div>

Réglages (src/_settings.scss)

Variable Défaut
$flex-container 1200px
$flex-columns 12
$breakpoints phone 0, tablet-portrait 600px, tablet-landscape 900px, desktop 1200px, medium-desktop 1440px, big-desktop 1800px
$breakpoints-hidpi hidpi-1 1, hidpi-1-5 1.5, hidpi-2 2, retina 2, hidpi-3 3
$breakpoint-classes phone tablet-portrait tablet-landscape desktop medium-desktop big-desktop
$print-breakpoint null (désactivé)
$flex-margin-gutters phone 16px, tablet-portrait 24px
$flex-padding-gutters $flex-margin-gutters
$gutters default → $flex-margin-gutters (tailles de gap nommées)
$padding-gutters default → $flex-padding-gutters (tailles de padding nommées)
$xy-block-flex-max 8

Compatibilité : les anciens noms $grid-container, $grid-columns, $grid-margin-gutters, $grid-padding-gutters, $grid-container-padding, $xy-block-grid-max restent acceptés en alias dépréciés (un with ($grid-columns: …) existant compile toujours). Préférez le préfixe $flex-.

Migration depuis Foundation XY

Dans la quasi-totalité des cas : on remplace la feuille de styles, rien d'autre.

  • flex-margin-x collé aux bords ne nécessite plus body { overflow-x: hidden }.
  • Push/Pull non repris (déprécié côté Foundation) → utilisez [bp]-order-[n].
  • Plus aucun conflit avec vos gap maison — c'est tout l'objectif.

Build

npm run build      # dist/gridaflex.css + dist/gridaflex.min.css
npm run watch      # recompilation à la volée

Documentation

Le site de documentation est construit avec Zensical (équipe Material for MkDocs). Sources Markdown dans docs/, configuration dans zensical.toml. Il inclut un constructeur de grille interactif (docs/builder.md).

# Outils (une fois) : Python + Zensical
python3 -m venv .venv && .venv/bin/pip install zensical

# Aperçu local (recompile le CSS puis sert avec live-reload)
npm run docs:css && .venv/bin/zensical serve

# Build statique → site/
npm run docs:css && .venv/bin/zensical build

Publication GitHub Pages

La documentation est versionnée et publiée sur GitHub Pages via mike. Le détail du process (build, déploiement d'une version, version par défaut) est décrit dans docs/demarrage.md et VERSIONING.md. Pensez à ajuster site_url dans zensical.toml.

Licence

MIT

About

robinlopez.github.io/gridaflex/

Resources

Readme

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

1 tags

Packages

 
 
 

Contributors

Languages