Arithmosphere-calculator

ArithmoSphere est une web calculatrice conçue avec React + Typescript.

Table des matières

• Présentation
• Fonctionnalités
• Aperçu
• Technologies Utilisées
• Architecture du Projet (Frontend)
• Démarrage Rapide
• Stratégie de Test
• Lancer les Tests
• Roadmap & Idées de fonctionnalités
• Contribuer
• Contact / Support

Présentation

ArithmoSphere est une calculatrice web pensée pour être un mini-laboratoire de calculs : aujourd'hui elle couvre l'arithmétique et quelques fonctions scientifiques, mais l'objectif est d'étendre le périmètre aux conversions, calculs chimiques, physiques, opérations matricielles, géomètriques et plus encore. Et pourquoi pas intégrer un model IA pour expliquer les différents calculs et comment procéder.

Fonctionnalités

• Calculs Arithmétiques & scientifiques : Opérations de base (addition, soustraction, multiplication, division), exponentiation, modulo, pourcentages, factorielle, racines carrée et cubique, etc
• Internationalisation (i18n) : Interface disponible en Français et en Anglais, avec possibilité de basculer facilement.
• Interface Réactive (Responsive) : (En cours) Conçue pour s'adapter à différentes tailles d'écran (bureau, tablette, mobile).
• Tests Unitaires : (En cours) Couverture de tests pour les composants et la logique métier à l'aide de Jest et React Testing Library.

Aperçu :

Technologies Utilisées

Domaine	Technologie
Framework/Bibliothèque	React
Langage	TypeScript
Style	Sass/SCSS
Internationalisation	i18n, i18next, react-i18next
Icônes	React Icons, React Feather
Tests	Jest, React Testing Library

Architecture du Projet (Frontend)

Le projet suit une structure de dossiers axée sur les fonctionnalités :

• Composants : Organisés par fonctionnalité (Header, Footer, Home, ..etc) avec un fichier .scss pour chaque composant.

• Pages : Représenter les différentes pages de l'application.

• Sous-Composants: composants spécifiques à un type de calcul (comme Arithmetic) sont dans le dossier (home/sub-components/).

• Core : Sépare la logique non-UI (modèles de données, fonctions de calcul, utilitaires) des composants React.

• Tests : Le dossier _tests_ à la racine contient les tests unitaires organisés de manière à refléter la structure du code source (src/) pour faciliter la localisation des tests correspondants.

Démarrage Rapide

Suivez ces étapes pour cloner et exécuter le projet localement.

Prérequis :

• Node.js (version 16 ou supérieure recommandée)

Étapes :

1. Cloner le dépôt :

   git clone https://github.com/YouvaLo/arithmosphere-calculator.git

2. Accéder au dossier du projet :

   cd arithmosphere

3. Installer les dépendances :

   npm install

4. Lancer l'application en mode développement :

   npm run dev

   Il faut Vérifier dans le package.json pour la commande exacte qu'est peut être modifiée d'ailleurs)*

Stratégie de Test

1. Tests Unitaires

• Objectif : Vérifier que chaque composant ou fonction utilitaire fonctionne correctement de manière isolée.
• Cibles : Composants React individuels et fonctions de logique métier (ex: les fonctions de calcul).
• Approche :
  • Utilisation de Jest comme exécuteur de tests et plateforme d'assertions.
  • Utilisation de React Testing Library (RTL) pour rendre les composants et interagir avec eux d'une manière qui simule le comportement de l'utilisateur.
  • Les dépendances externes (i18n, useNavigate et icônes) sont maquettées (mocked).

2. Tests d'Intégration

• Objectif : Vérifier que plusieurs composants fonctionnent correctement ensemble, en particulier au niveau de la navigation.
• Cibles : Composant racine App.tsx pour valider l'intégration du routage, du layout principal (MainLayout), et des différentes pages.
• Approche :
  • Toujours avec Jest et React Testing Library.
  • Utilisation de MemoryRouter de react-router-dom pour simuler la navigation entre les différentes routes de l'application dans l'environnement de test.
  • Les composants intégrés ne sont pas maquettés, permettant de tester leur assemblage réel.
  • Seules les dépendances externes sont maquettées.
  • Les tests vérifient que :
    • La bonne page est rendue pour une URL donnée.

Les tests se trouvent dans le dossier _tests_, avec une structure de dossiers qui reflète celle du code source (src/).

3. Outils Utilisés

• Jest : Framework de test JavaScript.
• React Testing Library (RTL) : Bibliothèque pour tester les composants React en se concentrant sur l'expérience utilisateur.
• @testing-library/jest-dom : Ajoute des matchers Jest personnalisés pour les assertions sur le DOM.
• ts-jest : Préprocesseur pour permettre à Jest d'exécuter des tests écrits en TypeScript.

Lancer les Tests

Pour exécuter la suite de tests unitaires :

npm test

Pour connaître la couverture des tests en % (sous forme d'un tableau) :

npm run test:coverage

Roadmap & Idées de fonctionnalités

Court terme

• Finaliser la responsivité et améliorer l'accessibilité.
• Ajouter les tests unitaires et d'intégration.
• Augmenter la couverture des tests (composants + logique de calcul).
• Ajouter davantage d'opérations arithmétiques/scientifiques (trigonométrie, log, équations, etc).

Moyen terme

• Modules de conversion d'unités (distance, masse, température, temps, etc.).
• Calculs matriciels : addition, multiplication, inversion, déterminant, systèmes linéaires.
• Calculs scientifiques avancés (statistiques de base, régressions simples).

Long terme (mini-laboratoire)

• Calculs chimiques (masse molaire, conversions, etc).
• Outils de physique (lois de base, conversions d'unités physiques, résolutions d'équations courantes).
• Un environnement modulaire où chaque « domaine » est un module séparé (modules/chemistry, modules/matrix).

Aller plus loin :

• Intégrer un modèle d'intélligence artificielle pour l'explication des différents calculs (Théorie, procédure, résultat, etc.).

Contribuer

Merci d'envisager de contribuer ! Voici comment vous pouvez aider à faire grandir ArithmoSphere.

Pourquoi contribuer ?

• S'entraîner sur un vrai projet React + TypeScript.
• Travailler l'internationalisation, les tests, la logique métier (algorithmes de calcul).
• Ajouter des fonctionnalités discipline-spécifiques (chimie, physique, conversions, matrices, etc.).

Comment démarrer

• Forker le dépôt et clonez votre fork.

• Créer une branche descriptive :

  • feat/[domaine]-[courte-description]
  • fix/[ticket-number]-[description]

• Installer les dépendances et lancez l'app localement.

• Ouvrir une Pull Request (PR) vers la branche dev du dépôt original lorsque votre fonctionnalité est prête.

Bonnes tâches pour débuter :

• Écrire des tests unitaires pour une fonction de calcul existante.

• Ajouter une nouvelle opération arithmétique avec tests.

• Amélioration UI : Rendre la page d'accueil responsive pour les petits écrans.

• i18n : Ajouter/compléter des traductions pour le Français/Anglais.

Règles de contribution

• Respecter le style UI du projet (possibilité de proposer un autre style, par une maquette Figma).

• Ajouter des tests pour toute nouvelle logique métier.

• Si c'est nécessaire d'intégrer une Api, il faut la Documenter interne dans un fichier .md.

• Ouvrir une issue avant de commencer une grosse fonctionnalité - cela permettra d'aligner la conception.

Processus PR

• Intitulé clair et descriptif.

• Lien vers l'issue correspondante si existante.

• Description des changements et exemples d'utilisation.

• Exécuter npm test et inclure les résultats si nécessaire.

Contact / Support

Si vous voulez contribuer ou discuter d'une idée :

• Ouvrez une issue sur GitHub.
• Ou envoyez un message via la page du projet (ou contactez YouvaLo sur GitHub).