Arabica Framework

Framework SCSS basé sur des grilles réactives, responsives et paramétrables.

Installation

Installation via NPM :

npm install @cafefrappe/arabica

Usage

Le Framework Arabica met à disposition plusieurs fonctionnalités :

Modale

Il faut tout d'abord créer une classe héritant de la classe "Modale", en définissant la méthode de callback qui sera appelée lors de l'ouverture de la modale :

// authentification-modale.ts

import {Modale, ModaleConfiguration} from "@cafefrappe/arabica";

export class AuthentificationModale extends Modale {

    constructor(configuration?: ModaleConfiguration){

        super(configuration);
    }
    
    get openCallback(): () => void {

        return (): void => {
        
            // Le script défini ici sera appelée lors de l'ouverture de la modale
        }
    }
}

Une instance peut ensuite être crée :

// main.ts

import {AuthentificationModale} from "./authentification-modale";

const modale = new AuthentificationModale();

La classe prend 1 paramètre en entrée :

• configuration (optionnel) : Options de configuration de la modale

  La modale est composée de plusieurs éléments qui peuvent tous être surchargés :

  • overlayElement (optionnel) : Élément HTML réprésentant l'overlay de la modale
  • closeElement (optionnel) : Élément HTML réprésentant le bouton de fermeture de la modale
  • bodyElement (optionnel) : Élément HTML réprésentant le corps de la modale
  • loaderElement (optionnel) : Élément HTML affiché lors du chargement du contenu de la modale

// main.ts

import {AuthentificationModale} from "./authentification-modale";

const loaderElement = (): HTMLElement => {

    const element: HTMLElement = document.createElement('div');

    element.classList.add('custom_loader');

    return element;
};

const modale = new AuthentificationModale({
    loaderElement: loaderElement()
});

Méthodes

• open : Ouvre la modale
• close: Ferme la modale
• appendToBody : Permet d'ajouter des noeuds ou des chaînes de caractère dans le corps de la modale (similaire à la méthode native append())
• addHtmlToBody : Permet d'ajouter une chaîne de caractère correspondant à un élement HTML dans le corps de la modale
• clearHtmlBody : Vide le contenu du corps de la modale
• openCallback : Détermine la fonctionne de callback à appeler lors de l'ouverture de la modale
• container : Retourne l'élément de destination de la modale
• bodyElement : Retourne l'élement correspondant au corps de la modale
• opened : Détermine si la modale est ouverte
• closed : Détermine si la modale est fermée

Exemple d'utilisation

Cet example présente le cas d'un formulaire affiché dans une modale, sur lequel une validation de formulaire est effectuée :

// authentification-modale.ts

import {Modale, ModaleConfiguration} from "@cafefrappe/arabica";
import {formValidation} from "@cafefrappe/formvalidation";

export class AuthentificationModale extends Modale {

    constructor(configuration?: ModaleConfiguration){

        super(configuration);
    }

    get openCallback(): () => void {

        return (): void => {

            fetch("https://mon-template-html.fr")
                .then((response: Response): Promise<string> => {

                    return response.text();
                })
                .then((html: string): void => {

                    // Mise à jour du contenu de la modale
                    this.addHtmlToBody(html);

                    // Initialisation de la validation du formulaire
                    formValidation(this.bodyElement.querySelector('#mon-formulaire'));
                })
            ;
        }
    }
}

// main.ts

import {AuthentificationModale} from "./authentification-modale";

document.addEventListener('DOMContentLoaded', (): void => {

    const button: HTMLButtonElement = document.querySelector('#open-modale');

    const modale = new AuthentificationModale();

    button.onclick = (): void => {

        modale.open();
    };
});

Implémentation

La structure des dossiers impérative

• / projet
  • / assets
    • / libs
      • / Arabica
        • scss
        • ts
        • README.md
    • / scss
      • / blocs
      • / composants
      • / settings
        • stgs_arabica.scss
        • stgs_projet.scss
      • app.scss

1. Le framework Arabica doit impérativement être dans le dossier libs
2. Le projet doit contenir un dossier 'scss' dans 'assets' dans lequel le fichier 'app.scss' doit être présent
3. Le fichier 'app.scss' importe en premier les settings généraux du projet : 'stgs_projet.scss'
4. Le fichier 'app.scss' importe en second les settings arabica du projet : 'stgs_arabica.scss'
5. Ces deux fichiers de settings doivent ce trouver dans un dossier 'setting' dans 'scss'

Fonctionnement

Le fichier 'app.scss' importe le 'stgs_projet.scss' propre au projet. Puis, il importe le 'stgs_arabica.scss' (du projet) qui peut faire appel aux variables du 'stgs_projet.scss' Le 'stgs_arabica.scss' importe le framework Arabica en fin de fichier afin d'écraser la configuration par défaut.

Fonctions Scss

Default

Cette fontion détermine le comportement par défaut du framework.

fluidMode / fluidMap / breakpointMap / marges / colonnes / modales

Reset

Cette fontion permet d'uniformiser les comportement entre les différents navigateurs.

IE 10+ / Edge 12+ / Firefox 2+ / Chrome 4+ / Safari 3.1+ / Opera 12.1+ / IOS Safari 3.2+ / Opera Mini / Android Browser 2.1+ / Blackberry Browser 7+ / Opera Mobile 12.1+ / Chrome for Android / Firefox for Android / IE Mobile 10+ / UC Browser for Android / Samsung Internet / QQ Browser / Baidu Browser / KaiOS Browser

Opérations

Cette fontion permet de rendre la valeur numérique d'une variable. Elle s'utilise directement en sass.

$value / ($value * 0 + 1)

Médias

Ces mixins s'importent directement en sass : '@include mixin;' ou via la classe associée : class="mixin"

Minimum et maximum

En fonction de la largeur

• Média querie min-width

@include media_x_min(valeur en px ou 'breakpoint') { //content };

• Média querie max-width

@include media_x_max(valeur en px ou 'breakpoint') { //content };

• Média querie between-width (cible les médias entre la valeur min et la valeur max)

@include media_x_between(valeur min en px ou 'breakpoint min', valeur max en px ou 'breakpoint max' ) { //content };

• Média querie around-width (cible les médias plus petit que la valeur min et plus grand que la valeur max)

@include media_x_around(valeur min en px ou 'breakpoint min', valeur max en px ou 'breakpoint max' ) { //content };

En fonction de la hauteur

• Média querie min-height

@include media_y_min(valeur en px ou 'breakpoint') { //content };

• Média querie max-height

@include media_y_max(valeur en px ou 'breakpoint') { //content };

• Média querie between-height (cible les médias entre la valeur min et la valeur max)

@include media_y_between(valeur min en px ou 'breakpoint min', valeur max en px ou 'breakpoint max' ) { //content };

• Média querie around-height (cible les médias plus petit que la valeur min et plus grand que la valeur max)

@include media_y_around(valeur min en px ou 'breakpoint min', valeur max en px ou 'breakpoint max' ) { //content };

Détection de l'orientation

• Portrait

@include media_portrait { //content };

@include media_portrait_x_min(valeur en px ou 'breakpoint') { //content };

@include media_portrait_x_max(valeur en px ou 'breakpoint') { //content };

@include media_portrait_x_between(valeur min en px ou 'breakpoint min', valeur max en px ou 'breakpoint max' ) { //content };

@include media_portrait_x_around(valeur min en px ou 'breakpoint min', valeur max en px ou 'breakpoint max' ) { //content };

@include media_portrait_y_min(valeur en px ou 'breakpoint') { //content };

@include media_portrait_y_max(valeur en px ou 'breakpoint') { //content };

@include media_portrait_y_between(valeur min en px ou 'breakpoint min', valeur max en px ou 'breakpoint max' ) { //content };

@include media_portrait_y_around(valeur min en px ou 'breakpoint min', valeur max en px ou 'breakpoint max' ) { //content };

• Landscape

@include media_landscape { //content };

@include media_landscape_x_min(valeur en px ou 'breakpoint') { //content };

@include media_landscape_x_max(valeur en px ou 'breakpoint') { //content };

@include media_landscape_x_between(valeur min en px ou 'breakpoint min', valeur max en px ou 'breakpoint max' ) { //content };

@include media_landscape_x_around(valeur min en px ou 'breakpoint min', valeur max en px ou 'breakpoint max' ) { //content };

@include media_landscape_y_min(valeur en px ou 'breakpoint') { //content };

@include media_landscape_y_max(valeur en px ou 'breakpoint') { //content };

@include media_landscape_y_between(valeur min en px ou 'breakpoint min', valeur max en px ou 'breakpoint max' ) { //content };

@include media_landscape_y_around(valeur min en px ou 'breakpoint min', valeur max en px ou 'breakpoint max' ) { //content };

Type de device

• Touch device

@include media_touch { //content };

@include media_touch_x_min(valeur en px ou 'breakpoint') { //content };

@include media_touch_x_max(valeur en px ou 'breakpoint') { //content };

@include media_touch_x_between(valeur min en px ou 'breakpoint min', valeur max en px ou 'breakpoint max' ) { //content };

@include media_touch_x_around(valeur min en px ou 'breakpoint min', valeur max en px ou 'breakpoint max' ) { //content };

@include media_touch_y_min(valeur en px ou 'breakpoint') { //content };

@include media_touch_y_max(valeur en px ou 'breakpoint') { //content };

@include media_touch_y_between(valeur min en px ou 'breakpoint min', valeur max en px ou 'breakpoint max' ) { //content };

@include media_touch_y_around(valeur min en px ou 'breakpoint min', valeur max en px ou 'breakpoint max' ) { //content };

• Pointer device

@include media_pointer { //content };

@include media_pointer_x_min(valeur en px ou 'breakpoint') { //content };

@include media_pointer_x_max(valeur en px ou 'breakpoint') { //content };

@include media_pointer_x_between(valeur min en px ou 'breakpoint min', valeur max en px ou 'breakpoint max' ) { //content };

@include media_pointer_x_around(valeur min en px ou 'breakpoint min', valeur max en px ou 'breakpoint max' ) { //content };

@include media_pointer_y_min(valeur en px ou 'breakpoint') { //content };

@include media_pointer_y_max(valeur en px ou 'breakpoint') { //content };

@include media_pointer_y_between(valeur min en px ou 'breakpoint min', valeur max en px ou 'breakpoint max' ) { //content };

@include media_pointer_y_around(valeur min en px ou 'breakpoint min', valeur max en px ou 'breakpoint max' ) { //content };

• Print

@include media_print { //content };

Fluid

Cette fonction est le coeur d'Arabica, elle permet de mapper des éléments avec des valeurs minimum et maximum

basées sur la grille pour générer un comportement fluid responsive entre ces deux valeurs pour chaque propriété.

Les propriétes doivent être définissables par des valeurs numériques en 'px'.

Cependant une autre propriété unique (valeur fixe sans min / max) peut aussi être définie dans le mapping.

$MapName : (
    '.mon_élément' : (
        'ma_propriété': (
            20px,
            40px
        ),
        'autre_propriété': (
            40px
        )
    ),
);
@include fluid($MapName);

Display

Ces mixins s'importent directement en sass : '@include mixin;' ou via la classe associée : class="mixin"

Chaque mixinx ou classe peut être suffixée par un breakpoint : class="propriete_breakpoint"

None

@include d_none; class="d_none"

@include d_none_breakpoint; class="d_none_breakpoint"

Inline-block

@include d_ib; class="d_ib"

@include d_ib_breakpoint; class="d_ib_breakpoint"

Flex

@include d_flex; class="d_flex"

@include d_flex_breakpoint; class="d_flex_breakpoint"

Grille

Cette fonction crée la grille de contenu basé sur la breakpointMap

Ces fonctions s'importent directement en classe : class="fonction"

Chaque classe peut être suffixée par un breakpoint : class="propriete_breakpoint"

Avec X entier positif compris entre 0 et nombreDeColonnesDeLaGrille (configuré dans 'stgs_arabica' du projet)

Box

Ces fonctions s'importent directement en classe : class="box"

• Box breakpoint

class="box_breakpoint"

• Box en pleine largeur

class="box_full"

Lignes

Ces fonctions s'importent directement en classe : class="row"

• Par défaut

class="row"

• Avec marge entre les colonnes

class="row marges"

• Avec verrouillage de l'affichage en ligne

class="row no_wrap"

Colonnes

Ces fonctions s'importent directement en classe : class="col"

Chaque classe peut être suffixée par un breakpoint : class="col_propriete_breakpoint"

• Colonne qui prend toute la place disponible sur la largeur

class="col"

class="col_breakpoint";

• Comportement de col, mais qui partage la largeur en nombre de colonne

class="col_X";

class="col_breakpoint_X";

• Colonne qui prend la largeur de son contenu

class="col_content"

class="col_breakpoint_content";

• Comportement de col, mais qui partage la largeur avec les autres colonnes en fonction de la largeur de son contenu

class="col_auto"

class="col_breakpoint_auto";

• Comportement de col, mais qui gère un décalage d'une largeur définie en nombre de colonnes

class="col_offset_X"

class="col_offset_breakpoint_X";

Alignements

Ces mixins s'importent directement en sass : '@include mixin;' ou via la classe associée : class="mixin"

Chaque classe peut être suffixée par un breakpoint : class="axe_propriete_breakpoint"

Absolute

• Alignement horizontal absolute

@include x_align_absolute; class="x_align_absolute"

@include x_align_absolute_breakpoint; class="x_align_absolute_breakpoint"

• Alignement vertical absolute

@include y_align_absolute; class="y_align_absolute"

@include y_align_absolute_breakpoint; class="y_align_absolute_breakpoint"

• Alignement central absolute

@include center_align_absolute; class="center_align_absolute"

@include center_align_absolute_breakpoint; class="center_align_absolute_breakpoint"

• Alignement reset absolute

@include reset_align_absolute; class="reset_align_absolute"

@include reset_align_absolute_breakpoint; class="reset_align_absolute_breakpoint"

Fixed

• Alignement horizontal fixed

@include x_align_fixed; class="x_align_fixed"

@include x_align_fixed_breakpoint; class="x_align_fixed_breakpoint"

• Alignement horizontal fixed

@include y_align_fixed; class="y_align_fixed"

@include y_align_fixed_breakpoint; class="y_align_fixed_breakpoint"

• Alignement central fixed

@include center_align_fixed; class="center_align_fixed"

@include center_align_fixed_breakpoint; class="center_align_fixed_breakpoint"

• Alignement reset fixed

@include reset_align_fixed; class="reset_align_fixed"

@include reset_align_fixed_breakpoint; class="reset_align_fixed_breakpoint"

Relative

• Alignement horizontal relative

@include x_align_relative; class="x_align_relative"

@include x_align_relative_breakpoint; class="x_align_relative_breakpoint"

• Alignement horizontal relative

@include y_align_relative; class="y_align_relative"

@include y_align_relative_breakpoint; class="y_align_relative_breakpoint"

• Alignement central relative

@include center_align_relative; class="center_align_relative"

@include center_align_relative_breakpoint; class="center_align_relative_breakpoint"

• Alignement reset relative

@include reset_align_relative; class="reset_align_relative"

@include reset_align_relative_breakpoint; class="reset_align_relative_breakpoint"

Horizontaux (x)

• Alignement horizontal à gauche

@include x_start; class="x_start"

@include x_start_breakpoint; class="x_start_breakpoint"

• Alignement horizontal au centre

@include x_center; class="x_center"

@include x_center_breakpoint; class="x_center_breakpoint"

• Alignement horizontal à droite

@include x_end; class="x_end"

@include x_end_breakpoint; class="x_end_breakpoint"

• Alignement horizontal "espace libre entre les colonnes"

@include x_between; class="x_between"

@include x_between_breakpoint; class="x_between_breakpoint"

• Alignement horizontal "espace libre autours des colonnes"

@include x_around; class="x_around"

@include x_around_breakpoint; class="x_around_breakpoint"

• Alignement horizontal "espace libre égal"

@include x_evenly; class="x_evenly"

@include x_evenly_breakpoint; class="x_evenly_breakpoint"

Verticaux des lignes de contenu (y)

• Alignement vertical des lignes de contenu en haut

@include y_content_start; class="y_content_start"

@include y_content_start_breakpoint; class="y_content_start_breakpoint"

• Alignement vertical des lignes de contenu au milieu

@include y_content_center; class="y_content_center"

@include y_content_center_breakpoint; class="y_content_center_breakpoint"

• Alignement vertical des lignes de contenu en bas

@include y_content_end; class="y_content_end"

@include y_content_end_breakpoint; class="y_content_end_breakpoint"

• Alignement vertical des lignes de contenu "espace libre entre les colonnes"

@include y_content_between; class="y_content_between"

• Alignement vertical des lignes de contenu "espace libre autours des colonnes"

@include y_content_around; class="y_content_around"

@include y_content_around_breakpoint; class="y_content_around_breakpoint"

• Alignement vertical des lignes de contenu en remplissage

@include y_content_stretch; class="y_content_stretch"

@include y_content_stretch_breakpoint; class="y_content_stretch_breakpoint"

Verticaux des items (y)

• Alignement vertical des items en haut

@include y_items_start; class="y_items_start"

@include y_items_start_breakpoint; class="y_items_start_breakpoint"

• Alignement vertical des items au milieu

@include y_items_center; class="y_items_center"

@include y_items_center_breakpoint; class="y_items_center_breakpoint"

• Alignement vertical des items en bas

@include y_items_end; class="y_items_end"

@include y_items_end_breakpoint; class="y_items_end_breakpoint"

• Alignement vertical des items en remplissage

@include y_items_stretch; class="y_items_stretch"

@include y_items_stretch_breakpoint; class="y_items_stretch_breakpoint"

Ordre

Ces mixins s'importent directement en sass : '@include mixin;' ou via la classe associée : class="mixin"

Chaque classe peut être suffixée par un breakpoint : class="propriete_breakpoint"

First & last

• Place l'élément en premier

@include order_first; class="order_first"

@include order_first_breakpoint; class="order_first_breakpoint"

• Place l'élément en dernier

@include order_last; class="order_last"

@include order_last_breakpoint; class="order_last_breakpoint"

Direction

Ces mixins s'importent directement en sass : '@include mixin;' ou via la classe associée : class="mixin"

Chaque classe peut être suffixée par un breakpoint : class="propriete_breakpoint"

Row

• Direction normale de la row

@include direction_x; class="direction_x"

@include direction_x_breakpoint; class="direction_x_breakpoint"

• Inverser la direction de la row

@include direction_x_revert; class="direction_x_revert"

@include direction_x_revert_breakpoint; class="direction_x_revert_breakpoint"

Colonne

• Direction normale de la colonne

@include direction_y; class="direction_y"

@include direction_y_breakpoint; class="direction_y_breakpoint"

• Inverser la direction de la colonne

@include direction_y_revert; class="direction_y_revert"

@include direction_y_revert_breakpoint; class="direction_y_revert_breakpoint"

Taille

Ces mixins s'importent directement en sass : '@include mixin;' ou via la classe associée : class="mixin"

Chaque classe peut être suffixée par un breakpoint : class="propriete_breakpoint"

Largeur

• Pleine largeure forcée

@include w_full; class="w_full"

@include w_full_breakpoint; class="w_full_breakpoint"

• Pleine hauteur forcée

@include h_full; class="h_full"

@include h_full_breakpoint; class="h_full_breakpoint"

Transition

Ce mixin s'importe directement en sass : '@include mixin;'

Transition

@include transition(transition);

Delay

@include delay(delay);

Animations

Ce mixin s'importe directement en sass : '@include mixin;'

Keyframes

• Définitions des keyframes

@include keyframes(animation_name) { //content };

Animation

• Application des keyframes et définition de l'animation

@include animation(animation_name proprietes);

Transform

Ce mixin s'importe directement en sass : '@include mixin;'

@include transform(transform);

Interactions

Ce mixin s'importe directement en sass : '@include mixin;'

Hover

• Hover inactif par défaut sur les touch device

@include hover { //content };

@include hover_x_min(valeur en px ou 'breakpoint') { //content };

@include hover_x_max(valeur en px ou 'breakpoint') { //content };

@include hover_y_min(valeur en px ou 'breakpoint') { //content };

@include hover_y_max(valeur en px ou 'breakpoint') { //content };

Focus

• Focus inactif par défaut sur les touch device

@include focus { //content };

@include focus_x_min(valeur en px ou 'breakpoint') { //content };

@include focus_x_max(valeur en px ou 'breakpoint') { //content };

@include focus_y_min(valeur en px ou 'breakpoint') { //content };

@include focus_y_max(valeur en px ou 'breakpoint') { //content };

Active

@include active { //content };

Visited

@include visited { //content };

Ombre

Ce mixin s'importe directement en sass : '@include mixin;'

@include ombre(ombre);

Radius

Ce mixin s'importe directement en sass : '@include mixin;'

@include radius(radius);