@arc-js/native-core

@arc-js/native-core est un ensemble de hooks et utilitaires de routage avancés pour les applications React Native avec TypeScript/JavaScript. Il fournit des fonctionnalités de navigation avancées, une gestion automatique des langues et des utilitaires pour simplifier le développement d'applications React Navigation.

✨ Fonctionnalités Principales

🧭 Navigation Avancée

• Navigation type-safe avec validation des paramètres
• Gestion automatique des query strings avec support multi-langue
• Résolution de routes avec paramètres dynamiques
• Navigation avec rechargement pour les mises à jour critiques
• Analyse d'URL complète avec extraction des données
• Support React Navigation Native Stack

🌍 Support Multi-Langue

• Gestion automatique du paramètre de langue lang
• Support intégré pour français et anglais
• Fallback sécurisé vers le français par défaut
• Codes de langue standardisés (fr_FR, en_US)

⚡ Utilitaires de Routage

• Validation de route actuelle avec correspondance de chemin
• Extraction des paramètres de query string
• Génération d'URL avec paramètres et queries
• Navigation externe vers des URL spécifiques

🛡️ Gestion d'Erreurs

• Fallback sécurisé pour les routes invalides
• Validation stricte des paramètres d'entrée
• Logs détaillés en mode développement
• Types TypeScript complets pour une meilleure autocomplétion

📦 Installation

Via npm/yarn/pnpm

npm install @arc-js/native-core @arc-js/qust @react-navigation/native @react-navigation/native-stack react-native react
# ou
yarn add @arc-js/native-core @arc-js/qust @react-navigation/native @react-navigation/native-stack react-native react
# ou
pnpm add @arc-js/native-core @arc-js/qust @react-navigation/native @react-navigation/native-stack react-native react

Dépendances requises

• React 19+
• React Native 0.81+
• React Navigation Native 7+
• React Navigation Native Stack 7+
• TypeScript 5.0+ (recommandé)
• @arc-js/qust 1.0.0+ (pour la manipulation de query strings)

🚀 Démarrage Rapide

Configuration de base

// App.tsx
import React from 'react';
import { NavigationContainer } from '@react-navigation/native';
import { createNativeStackNavigator } from '@react-navigation/native-stack';
import { useRootingActions } from '@arc-js/native-core';

const Stack = createNativeStackNavigator();

const HomeScreen = () => {
  const { goToRoute } = useRootingActions();
  
  return (
    <View>
      <Text>Accueil</Text>
      <Button 
        title="Voir le profil utilisateur" 
        onPress={() => goToRoute({
          path: 'Profile',
          params: { userId: '123' },
          queries: { lang: 'fr', view: 'profile' }
        })}
      />
    </View>
  );
};

const ProfileScreen = () => {
  const { params, queries } = useRootingActions();
  
  return (
    <View>
      <Text>Profil de l'utilisateur {params.userId}</Text>
      <Text>Langue: {queries.lang || 'fr'}</Text>
    </View>
  );
};

const App = () => {
  return (
    <NavigationContainer>
      <Stack.Navigator>
        <Stack.Screen name="Home" component={HomeScreen} />
        <Stack.Screen name="Profile" component={ProfileScreen} />
      </Stack.Navigator>
    </NavigationContainer>
  );
};

export default App;

📚 Documentation API

Hook useRootingActions

import { useRootingActions } from '@arc-js/native-core';

const MyComponent = () => {
  const {
    // Paramètres de l'écran actuel
    params,           // { userId: "123", slug: "article" }
    queries,          // { lang: "fr", page: "1" }
    pathName,         // "Profile" (nom de l'écran)
    urlSearch,        // "?lang=fr&page=1"
    
    // Fonctions de navigation
    navigate,         // navigate() de react-navigation
    goBack,           // goBack() de react-navigation
    resolveRoute,     // Générer un chemin complet
    goToRoute,        // Naviguer vers un écran
    goAndReloadRoute, // Naviguer avec rechargement
    goToUrl,          // Naviguer vers une URL
    
    // Utilitaires
    getParams,        // Obtenir les paramètres
    getUrlData,       // Analyser une URL
    checkIfIsCurrentRoute // Vérifier l'écran actuel
  } = useRootingActions();
  
  return (
    <View>
      <Text>ID Utilisateur: {params.userId}</Text>
      <Text>Langue: {queries.lang || 'fr'}</Text>
    </View>
  );
};

Interfaces principales

// Configuration de navigation
interface ConfigGoToRoute {
  path?: string;           // Nom de l'écran (ex: "Profile")
  params?: any;           // Paramètres de navigation (ex: { userId: "123" })
  queries?: any;          // Query parameters (ex: { lang: "fr" })
  refreshPage?: boolean;  // Forcer le rechargement
  replace?: boolean;      // Remplacer l'historique
  enableLoader?: boolean; // Afficher un loader
}

// Configuration de résolution
interface ConfigResolveRoute {
  path?: string;
  params?: any;
  queries?: any;
}

// Configuration de navigation externe
interface ConfigGoToSpecificUrl {
  path?: string;
  queries?: any;
  refreshPage?: boolean;
  replace?: boolean;
  enableLoader?: boolean;
}

// Valeur de retour du hook
interface RootingActionReturns {
  params: any;
  queries: any;
  getParams: () => Record<string, any>;
  navigate: (name: string, params?: any) => void;
  goBack: () => void;
  resolveRoute: (config: ConfigResolveRoute) => string;
  goToRoute: (config: ConfigGoToRoute) => void;
  goAndReloadRoute: (config: ConfigGoAndReloadRoute) => void;
  pathName: string;
  urlSearch: string;
  getUrlData: (url: string) => {
    pathname: string;
    queries: any;
  } | undefined;
  goToUrl: (config: ConfigGoToSpecificUrl) => string;
  checkIfIsCurrentRoute: (path?: string, exact?: boolean, strict?: boolean) => boolean;
}

Fonctions utilitaires

import { nativeResolveRoute, getLang, getLangCode } from '@arc-js/native-core';

// Générer un chemin sans utiliser le hook
const profilePath = nativeResolveRoute({
  path: 'Profile/:id/details',
  params: { id: '456' },
  queries: { lang: 'en', tab: 'settings' }
});
// Résultat: "Profile/456/details?lang=en&tab=settings"

// Gestion des langues
const currentLang = getLang('fr');    // "fr" (valide)
const fallbackLang = getLang('es');   // "fr" (fallback)
const langCode = getLangCode('en');   // "en_US"

🔧 Utilisation Avancée

Navigation avec gestion de langue

const LanguageAwareNavigation = () => {
  const { goToRoute, queries } = useRootingActions();
  const currentLang = queries.lang || 'fr';
  
  const navigateWithLang = (screenName: string, params?: any, additionalQueries?: any) => {
    goToRoute({
      path: screenName,
      params,
      queries: {
        ...additionalQueries,
        lang: currentLang
      }
    });
  };
  
  return (
    <View>
      <Button 
        title="Voir l'équipe" 
        onPress={() => navigateWithLang('About', { section: 'team' })} 
      />
    </View>
  );
};

Navigation conditionnelle

const SmartNavigation = () => {
  const { goToRoute, checkIfIsCurrentRoute } = useRootingActions();
  
  const navigateSmartly = (screenName: string) => {
    // Si déjà sur l'écran, ne rien faire
    if (checkIfIsCurrentRoute(screenName)) {
      return;
    }
    
    // Sinon, naviguer
    goToRoute({ path: screenName });
  };
  
  return (
    <View>
      <Button title="Accueil" onPress={() => navigateSmartly('Home')} />
      <Button title="À propos" onPress={() => navigateSmartly('About')} />
    </View>
  );
};

🎯 Exemples Complets

Exemple 1 : Formulaire avec redirection

import { useState } from 'react';
import { View, TextInput, Button, Alert } from 'react-native';
import { useRootingActions } from '@arc-js/native-core';

const ContactForm = () => {
  const { goToRoute, goAndReloadRoute } = useRootingActions();
  const [formData, setFormData] = useState({ name: '', email: '', message: '' });
  
  const handleSubmit = async () => {
    try {
      // Envoyer les données
      const response = await fetch('https://api.example.com/contact', {
        method: 'POST',
        body: JSON.stringify(formData)
      });
      
      if (response.ok) {
        // Redirection simple vers la page de confirmation
        goToRoute({
          path: 'ContactSuccess',
          queries: { ref: 'contact-form' }
        });
      } else {
        // Redirection avec rechargement pour nettoyer les erreurs
        goAndReloadRoute({
          path: 'Contact',
          queries: { error: 'submission_failed' }
        });
      }
    } catch (error) {
      Alert.alert('Erreur', 'Une erreur réseau est survenue');
      goToRoute({
        path: 'Contact',
        queries: { error: 'network_error' }
      });
    }
  };
  
  return (
    <View>
      <TextInput
        value={formData.name}
        onChangeText={text => setFormData({...formData, name: text})}
        placeholder="Votre nom"
      />
      <TextInput
        value={formData.email}
        onChangeText={text => setFormData({...formData, email: text})}
        placeholder="Votre email"
        keyboardType="email-address"
      />
      <TextInput
        value={formData.message}
        onChangeText={text => setFormData({...formData, message: text})}
        placeholder="Votre message"
        multiline
        numberOfLines={4}
      />
      <Button title="Envoyer" onPress={handleSubmit} />
    </View>
  );
};

Exemple 2 : Système de pagination

import { View, Text, Button } from 'react-native';
import { useRootingActions } from '@arc-js/native-core';

const PaginatedList = ({ items, currentPage, totalPages }) => {
  const { goToRoute, queries } = useRootingActions();
  
  const goToPage = (page: number) => {
    goToRoute({
      path: 'Items',
      queries: {
        ...queries,
        page: page.toString()
      }
    });
  };
  
  return (
    <View>
      <Text>Liste des éléments</Text>
      
      {/* Liste des éléments */}
      {items.map(item => (
        <Text key={item.id}>{item.name}</Text>
      ))}
      
      {/* Pagination */}
      <View style={{ flexDirection: 'row', justifyContent: 'center', alignItems: 'center' }}>
        <Button
          title="Précédent"
          disabled={currentPage <= 1}
          onPress={() => goToPage(currentPage - 1)}
        />
        
        <Text>Page {currentPage} sur {totalPages}</Text>
        
        <Button
          title="Suivant"
          disabled={currentPage >= totalPages}
          onPress={() => goToPage(currentPage + 1)}
        />
      </View>
    </View>
  );
};

Exemple 3 : Menu de navigation intelligent

import { View, Text, TouchableOpacity } from 'react-native';
import { useRootingActions } from '@arc-js/native-core';

const NavigationMenu = () => {
  const { goToRoute, checkIfIsCurrentRoute } = useRootingActions();
  
  const menuItems = [
    { path: 'Home', label: 'Accueil' },
    { path: 'Products', label: 'Produits' },
    { path: 'About', label: 'À propos' },
    { path: 'Contact', label: 'Contact' }
  ];
  
  return (
    <View style={{ flexDirection: 'row', justifyContent: 'space-around' }}>
      {menuItems.map(item => {
        const isActive = checkIfIsCurrentRoute(item.path);
        
        return (
          <TouchableOpacity
            key={item.path}
            style={{ padding: 10, backgroundColor: isActive ? '#007AFF' : '#EFEFEF' }}
            onPress={() => goToRoute({ path: item.path })}
          >
            <Text style={{ color: isActive ? 'white' : 'black' }}>{item.label}</Text>
          </TouchableOpacity>
        );
      })}
    </View>
  );
};

Exemple 4 : Sélecteur de langue

import { View, TouchableOpacity, Text } from 'react-native';
import { useRootingActions } from '@arc-js/native-core';

const LanguageSelector = () => {
  const { goToRoute, queries } = useRootingActions();
  const currentLang = queries.lang || 'fr';
  
  const languages = [
    { code: 'fr', name: 'Français', flag: '🇫🇷' },
    { code: 'en', name: 'English', flag: '🇬🇧' }
  ];
  
  const changeLanguage = (langCode: string) => {
    goToRoute({
      path: queries.pathName || 'Home',
      queries: {
        ...queries,
        lang: langCode
      }
    });
  };
  
  return (
    <View style={{ flexDirection: 'row' }}>
      {languages.map(lang => (
        <TouchableOpacity
          key={lang.code}
          style={{ 
            padding: 8, 
            marginHorizontal: 4,
            backgroundColor: currentLang === lang.code ? '#007AFF' : '#EFEFEF',
            borderRadius: 4
          }}
          onPress={() => changeLanguage(lang.code)}
        >
          <Text style={{ color: currentLang === lang.code ? 'white' : 'black' }}>
            {lang.flag} {lang.name}
          </Text>
        </TouchableOpacity>
      ))}
    </View>
  );
};

🔧 Configuration

Configuration des langues

// Configuration par défaut dans @arc-js/native-core
export const langs = ['en', 'fr']; // Langues supportées
export const langCodes = {
  'fr': 'fr_FR',
  'en': 'en_US',
};

Variables d'environnement

// config.ts
export const NODEENV: 'development' | 'production' | 'debug' = 'development';

🛡️ Gestion des Erreurs

Fallback sécurisé

const SafeNavigation = () => {
  const { resolveRoute, goToRoute } = useRootingActions();
  
  const safeGoToRoute = (config: ConfigGoToRoute) => {
    try {
      goToRoute(config);
    } catch (error) {
      console.error('Navigation error:', error);
      // Fallback vers l'écran d'accueil
      goToRoute({ path: 'Home' });
    }
  };
  
  return (
    <Button 
      title="Naviguer en sécurité" 
      onPress={() => safeGoToRoute({ path: 'InvalidScreen' })} 
    />
  );
};

📋 Table des Conventions

Paramètres de query string

| Paramètre | Type | Description | Valeur par défaut | |-----------|------|-------------|-------------------| | lang | fr \| en | Langue de l'application | fr | | page | number | Numéro de page | 1 | | sort | string | Tri des résultats | date | | filter | string | Filtre appliqué | all |

Codes de langue

| Code court | Code long | Description | |------------|-----------|-------------| | fr | fr_FR | Français (France) | | en | en_US | Anglais (États-Unis) |

🔧 Build et Développement

Scripts disponibles

{
  "scripts": {
    "init": "npm init --scope=@arc-js/native-core",
    "login": "npm login"
  }
}

Configuration TypeScript

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable", "ESNext"],
    "module": "ESNext",
    "skipLibCheck": true,
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true
  }
}

📄 Licence

MIT License - Voir le fichier LICENSE pour plus de détails.

🐛 Signaler un Bug

Envoyez nous un mail à l'adresse [email protected] pour :

• Signaler un bug
• Proposer une amélioration
• Poser une question

@arc-js/native-core - Les hooks et utilitaires de routage avancés pour React Native et TypeScript.

Développé par l'équipe INICODE