@arc-js/core 0.0.1

package/README.md

@@ -0,0 +1,664 @@
+# @arc-js/core
+
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-007ACC)
+![React](https://img.shields.io/badge/React-18+-61DAFB)
+![React Router](https://img.shields.io/badge/React%20Router-6+-CA4245)
+
+**@arc-js/core** est un module de routage intelligent et auto-configuré pour les applications React avec TypeScript/Javascript. Il fournit un système de routage basé sur la structure de fichiers, des hooks de navigation avancés et une configuration minimale pour les applications modulaires.
+
+## ✨ Fonctionnalités Principales
+
+### 🗺️ Routage Auto-Généré
+- **Génération automatique des routes** à partir de la structure du système de fichiers
+- **Support des layouts hiérarchiques** avec héritage automatique
+- **Pages d'erreur spécifiques** par sous-répertoire
+- **Configuration modulaire** avec support des modules indépendants
+
+### 🧭 Hooks de Navigation Avancés
+- **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
+
+### ⚙️ Configuration Modulaire
+- **Configuration par module** avec fichiers `config.json`
+- **Activation/désactivation** dynamique des modules
+- **Chemins personnalisables** par module
+- **Détection automatique** des fichiers de pages
+
+### 🛡️ Sécurité et Fiabilité
+- **Validation des chemins** avec fallback sécurisé
+- **Gestion des erreurs** avec pages d'erreur hiérarchiques
+- **Logs détaillés** en mode développement seulement
+- **Types TypeScript complets** pour une meilleure autocomplétion
+
+## 📦 Installation
+
+### Via npm/yarn/pnpm
+
+```bash
+npm install @arc-js/core react-router-dom react
+# ou
+yarn add @arc-js/core react-router-dom react
+# ou
+pnpm add @arc-js/core react-router-dom react
+```
+
+### Dépendances requises
+- React 18+
+- React Router DOM 6+
+- TypeScript 5.0+ (recommandé)
+- @arc-js/qust (pour la manipulation de query strings)
+
+## 🚀 Démarrage Rapide
+
+### Structure de projet recommandée
+
+```
+src/
+├── pages/
+│   ├── _layout.tsx          # Layout racine
+│   ├── _error.tsx           # Page d'erreur racine
+│   ├── index.tsx            # Page d'accueil
+│   ├── about/
+│   │   ├── _layout.tsx      # Layout spécifique à /about
+│   │   ├── _error.tsx       # Erreur spécifique à /about
+│   │   ├── index.tsx        # /about
+│   │   └── team.tsx         # /about/team
+│   └── users/
+│       ├── _layout.tsx      # Layout spécifique à /users
+│       ├── [id].tsx         # /users/:id (paramètre dynamique)
+│       └── index.tsx        # /users
+├── modules/
+│   └── admin/
+│       ├── config.json      # Configuration du module admin
+│       └── pages/
+│           ├── _layout.tsx  # Layout du module admin
+│           ├── dashboard.tsx # /admin/dashboard
+│           └── users.tsx    # /admin/users
+└── main.tsx
+```
+
+### Configuration de base
+
+```typescript
+// main.tsx
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { BrowserRouter } from 'react-router-dom';
+import getRoutes from '@arc-js/core';
+import { RouterProvider, createBrowserRouter } from 'react-router-dom';
+
+const App = () => {
+  const routes = getRoutes();
+  const router = createBrowserRouter(routes);
+  
+  return <RouterProvider router={router} />;
+};
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);
+```
+
+### Fichier config.json d'un module
+
+```json
+{
+  "path": "/admin",
+  "name": "Administration",
+  "description": "Module d'administration",
+  "author": "Votre Équipe",
+  "isEnabled": true
+}
+```
+
+## 📚 Documentation API
+
+### Hook useRootingActions
+
+```typescript
+import { useRootingActions } from '@arc-js/core';
+
+const MyComponent = () => {
+  const {
+    params,           // Paramètres de route (ex: { id: "123" })
+    queries,          // Query parameters (ex: { lang: "fr", page: "1" })
+    navigate,         // Fonction navigate de react-router-dom
+    resolveRoute,     // Résoudre une route avec paramètres
+    goToRoute,        // Naviguer vers une route
+    goAndReloadRoute, // Naviguer avec rechargement
+    pathName,         // Chemin actuel
+    urlSearch,        // Query string actuelle
+    getUrlData,       // Analyser une URL
+    checkIfIsCurrentRoute // Vérifier si on est sur une route
+  } = useRootingActions();
+  
+  // Exemple d'utilisation
+  const handleClick = () => {
+    goToRoute({
+      path: '/users/:id',
+      params: { id: '123' },
+      queries: { lang: 'fr', view: 'details' }
+    });
+  };
+  
+  return (
+    <div>
+      <button onClick={handleClick}>
+        Voir l'utilisateur 123
+      </button>
+    </div>
+  );
+};
+```
+
+### Interfaces principales
+
+```typescript
+// Configuration de navigation
+interface ConfigGoToRoute {
+  path?: string;
+  params?: any;
+  queries?: any;
+  refreshPage?: boolean;
+  replace?: boolean;
+  enableLoader?: boolean;
+}
+
+// Configuration de résolution de route
+interface ConfigResolveRoute {
+  path?: string;
+  params?: any;
+  queries?: any;
+}
+
+// Route générée automatiquement
+interface RouteDefinition {
+  truePath: string;     // Chemin physique du fichier
+  pathParent?: string;  // Chemin parent
+  path: string;         // Chemin de la route
+  component: React.ComponentType<any>;
+  layout?: React.ComponentType<{ children: ReactNode }>;
+  error?: React.ComponentType<{}>;
+}
+
+// Configuration d'un module
+interface ConfigDatasDefinition {
+  path: string;         // Chemin de base du module
+  name: string | undefined;
+  author: string | undefined;
+  isEnabled: boolean;   // Activation du module
+}
+```
+
+### Fonctions utilitaires
+
+```typescript
+import { nativeResolveRoute } from '@arc-js/core';
+
+// Résoudre une URL sans utiliser le hook
+const url = nativeResolveRoute({
+  path: '/users/:id',
+  params: { id: '456' },
+  queries: { lang: 'en', tab: 'profile' }
+});
+
+console.log(url); // "/users/456?lang=en&tab=profile"
+```
+
+## 🔧 Utilisation Avancée
+
+### Pages dynamiques avec paramètres
+
+```typescript
+// src/pages/users/[id].tsx
+import { useRootingActions } from '@arc-js/core';
+
+const UserPage = () => {
+  const { params, queries } = useRootingActions();
+  const userId = params.id;
+  const lang = queries.lang || 'fr';
+  
+  return (
+    <div>
+      <h1>Utilisateur {userId}</h1>
+      <p>Langue: {lang}</p>
+    </div>
+  );
+};
+
+export default UserPage;
+```
+
+### Layouts hiérarchiques
+
+```typescript
+// src/pages/_layout.tsx (Layout racine)
+const RootLayout = ({ children }) => (
+  <div className="app">
+    <header>Mon Application</header>
+    <main>{children}</main>
+    <footer>© 2024</footer>
+  </div>
+);
+
+// src/pages/admin/_layout.tsx (Layout admin)
+const AdminLayout = ({ children }) => (
+  <div className="admin">
+    <nav>Menu Admin</nav>
+    <div className="admin-content">{children}</div>
+  </div>
+);
+```
+
+### Pages d'erreur spécifiques
+
+```typescript
+// src/pages/_error.tsx (Erreur globale)
+const GlobalErrorPage = () => (
+  <div>
+    <h1>Une erreur est survenue</h1>
+    <p>Veuillez réessayer plus tard.</p>
+  </div>
+);
+
+// src/pages/admin/_error.tsx (Erreur admin)
+const AdminErrorPage = () => (
+  <div className="admin-error">
+    <h1>Erreur d'administration</h1>
+    <p>Contactez le support technique.</p>
+  </div>
+);
+```
+
+### Configuration de modules
+
+```typescript
+// src/modules/blog/config.json
+{
+  "path": "/blog",
+  "name": "Blog",
+  "description": "Module de blog",
+  "author": "Équipe Rédaction",
+  "isEnabled": true
+}
+
+// src/modules/blog/pages/index.tsx sera accessible à /blog
+// src/modules/blog/pages/[slug].tsx sera accessible à /blog/:slug
+```
+
+## 🎯 Exemples Complets
+
+### Exemple 1 : Application avec authentification
+
+```typescript
+// src/pages/_layout.tsx
+import { useRootingActions } from '@arc-js/core';
+import { Link } from 'react-router-dom';
+
+const AppLayout = ({ children }) => {
+  const { checkIfIsCurrentRoute } = useRootingActions();
+  const isActive = (path: string) => checkIfIsCurrentRoute(path);
+  
+  return (
+    <div>
+      <nav>
+        <Link to="/" className={isActive('/') ? 'active' : ''}>
+          Accueil
+        </Link>
+        <Link to="/about" className={isActive('/about') ? 'active' : ''}>
+          À propos
+        </Link>
+        <Link to="/contact" className={isActive('/contact') ? 'active' : ''}>
+          Contact
+        </Link>
+      </nav>
+      {children}
+    </div>
+  );
+};
+
+// src/pages/protected/_layout.tsx
+import { useEffect } from 'react';
+import { useRootingActions } from '@arc-js/core';
+
+const ProtectedLayout = ({ children }) => {
+  const { goToRoute } = useRootingActions();
+  
+  useEffect(() => {
+    const token = localStorage.getItem('auth_token');
+    if (!token) {
+      goToRoute({
+        path: '/login',
+        queries: { redirect: window.location.pathname }
+      });
+    }
+  }, []);
+  
+  return token ? children : null;
+};
+```
+
+### Exemple 2 : Dashboard avec multi-langue
+
+```typescript
+// src/pages/dashboard/index.tsx
+import { useRootingActions } from '@arc-js/core';
+import { useState, useEffect } from 'react';
+
+const DashboardPage = () => {
+  const { queries, goToRoute, resolveRoute } = useRootingActions();
+  const [lang, setLang] = useState(queries.lang || 'fr');
+  
+  const changeLanguage = (newLang: string) => {
+    goToRoute({
+      path: '/dashboard',
+      queries: { ...queries, lang: newLang }
+    });
+  };
+  
+  const getReportUrl = (reportId: string) => {
+    return resolveRoute({
+      path: '/dashboard/reports/:id',
+      params: { id: reportId },
+      queries: { lang, format: 'pdf' }
+    });
+  };
+  
+  return (
+    <div>
+      <div>
+        Langue: 
+        <button onClick={() => changeLanguage('fr')}>FR</button>
+        <button onClick={() => changeLanguage('en')}>EN</button>
+      </div>
+      
+      <a href={getReportUrl('monthly')}>
+        Télécharger le rapport mensuel
+      </a>
+    </div>
+  );
+};
+```
+
+### Exemple 3 : Formulaire avec redirection
+
+```typescript
+// src/pages/contact/index.tsx
+import { useState } from 'react';
+import { useRootingActions } from '@arc-js/core';
+
+const ContactPage = () => {
+  const { goToRoute, goAndReloadRoute } = useRootingActions();
+  const [formData, setFormData] = useState({ name: '', email: '' });
+  
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    
+    // Simulation d'envoi
+    const success = await submitContactForm(formData);
+    
+    if (success) {
+      // Redirection simple
+      goToRoute({
+        path: '/contact/success',
+        queries: { ref: 'contact-form' }
+      });
+    } else {
+      // Redirection avec rechargement pour nettoyer le cache
+      goAndReloadRoute({
+        path: '/contact',
+        queries: { error: 'submission_failed' }
+      });
+    }
+  };
+  
+  return (
+    <form onSubmit={handleSubmit}>
+      <input
+        value={formData.name}
+        onChange={e => setFormData({...formData, name: e.target.value})}
+        placeholder="Nom"
+      />
+      <input
+        value={formData.email}
+        onChange={e => setFormData({...formData, email: e.target.value})}
+        placeholder="Email"
+      />
+      <button type="submit">Envoyer</button>
+    </form>
+  );
+};
+```
+
+## 🔧 Configuration Avancée
+
+### Variables d'environnement
+
+```bash
+# .env
+VITE_APP_NAME="Mon Application"
+VITE_API_URL="http://localhost:3000"
+
+# Activation des logs détaillés
+NODE_ENV=development  # Logs complets
+NODE_ENV=production   # Logs minimaux
+```
+
+### Extension de la configuration
+
+```typescript
+// custom-routes.ts
+import { getRoutes as getBaseRoutes } from '@arc-js/core';
+import { RouteDefinition } from '@arc-js/core/types';
+
+export async function getRoutes() {
+  const baseRoutes = await getBaseRoutes();
+  
+  // Ajouter des routes manuelles
+  const customRoutes: RouteDefinition[] = [
+    {
+      truePath: '/src/pages/custom.tsx',
+      path: '/custom-route',
+      component: () => <div>Route personnalisée</div>,
+      layout: undefined,
+      error: undefined
+    }
+  ];
+  
+  return [...baseRoutes, ...customRoutes];
+}
+```
+
+### Personnalisation du routage
+
+```typescript
+// custom-router.tsx
+import { useRootingActions } from '@arc-js/core';
+import type { ConfigGoToRoute } from '@arc-js/core';
+
+export const useCustomRooting = () => {
+  const baseActions = useRootingActions();
+  
+  const goToRouteWithAnalytics = (
+    config: ConfigGoToRoute,
+    analyticsEvent?: string
+  ) => {
+    // Envoyer l'événement analytics
+    if (analyticsEvent) {
+      window.gtag?.('event', analyticsEvent, {
+        path: config.path,
+        params: config.params
+      });
+    }
+    
+    // Utiliser la navigation standard
+    return baseActions.goToRoute(config);
+  };
+  
+  return {
+    ...baseActions,
+    goToRouteWithAnalytics
+  };
+};
+```
+
+## 🛡️ Gestion des Erreurs
+
+### Structure d'erreur hiérarchique
+
+```
+pages/
+├── _error.tsx                    # Erreur globale
+├── admin/
+│   ├── _error.tsx               # Erreur admin (surcharge globale)
+│   └── dashboard/
+│       └── _error.tsx           # Erreur dashboard (surcharge admin)
+└── public/
+    └── _error.tsx               # Erreur section publique
+```
+
+### Page d'erreur avancée
+
+```typescript
+// src/pages/_error.tsx
+import { useRouteError, Link } from 'react-router-dom';
+import { useRootingActions } from '@arc-js/core';
+
+const ErrorPage = () => {
+  const error = useRouteError();
+  const { pathName, goToRoute } = useRootingActions();
+  
+  console.error('Route Error:', error);
+  
+  const handleRetry = () => {
+    goToRoute({
+      path: pathName,
+      refreshPage: true  // Forcer le rechargement
+    });
+  };
+  
+  return (
+    <div className="error-container">
+      <h1>Oups ! Une erreur est survenue</h1>
+      <p>Désolé, une erreur inattendue s'est produite.</p>
+      
+      <div className="error-actions">
+        <button onClick={handleRetry}>
+          Réessayer
+        </button>
+        <Link to="/">
+          Retour à l'accueil
+        </Link>
+      </div>
+    </div>
+  );
+};
+```
+
+## 📋 Table des Conventions
+
+### Fichiers spéciaux
+
+| Fichier | Chemin de route | Description |
+|---------|----------------|-------------|
+| `index.tsx` | `/` (racine) ou `/dossier/` | Page d'index |
+| `_layout.tsx` | Non accessible | Layout pour le dossier |
+| `_error.tsx` | Non accessible | Page d'erreur pour le dossier |
+| `_404.tsx` | `*` | Page 404 (non trouvé) |
+| `[param].tsx` | `/:param` | Paramètre dynamique |
+| `[...slug].tsx` | `/*` | Catch-all route |
+
+### Paramètres de query string
+
+| Paramètre | Type | Description |
+|-----------|------|-------------|
+| `lang` | `fr` \| `en` | Langue de l'application |
+| `ref` | string | Référence pour le tracking |
+| `modal` | string | Ouvrir un modal spécifique |
+| `page` | number | Numéro de page (pagination) |
+| `sort` | string | Tri des résultats |
+
+## 🔧 Build et Développement
+
+### Scripts recommandés
+
+```json
+{
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview",
+    "type-check": "tsc --noEmit",
+    "generate-routes": "node scripts/generate-routes.js"
+  }
+}
+```
+
+### Configuration Vite
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      '@arc-js/core': '/node_modules/@arc-js/core'
+    }
+  },
+  build: {
+    rollupOptions: {
+      external: ['react', 'react-dom', 'react-router-dom']
+    }
+  }
+});
+```
+
+### Configuration TypeScript
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["DOM", "DOM.Iterable", "ES2020"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src"]
+}
+```
+
+## 📄 Licence
+
+MIT License - Voir le fichier [LICENSE](LICENSE) pour plus de détails.
+
+## 🐛 Signaler un Bug
+
+Envoyez nous un mail à l'adresse `contact.inicode@gmail.com` pour :
+- Signaler un bug
+- Proposer une amélioration
+- Poser une question
+
+---
+
+**@arc-js/core** - Le système de routage intelligent pour React et TypeScript.
+
+*Développé par l'équipe INICODE*

package/index.d.ts

@@ -0,0 +1,10 @@
+import { RouteObject } from 'react-router-dom';
+export { useRootingActions } from './rooting.hooks.js';
+
+/**
+* Permet d'initialiser toutes les routes de l'application
+* @returns RouteObject[]
+*/
+declare const _default: () => RouteObject[];
+
+export { _default as default };

package/index.jsx

@@ -0,0 +1,33 @@
+import { j as jsxRuntimeExports } from './_virtual/jsx-runtime';
+import * as routesUtils_js from './routes-utils.js';
+import { routes } from './routes-utils.js';
+export { useRootingActions } from './rooting.hooks.jsx';
+
+var index = () => {
+    let routes$1 = routes.map((route) => ({
+        path: route.path,
+        element: route.layout ? (jsxRuntimeExports.jsx(route.layout, { children: jsxRuntimeExports.jsx(route.component, {}) })) : (jsxRuntimeExports.jsx(route.component, {})),
+        ...(!!route.error ? {
+            errorElement: jsxRuntimeExports.jsx(route.error, {}),
+        } : {}),
+    }));
+    let homeRoute = undefined;
+    let notFoundRoute = undefined;
+    homeRoute = routes$1.find((a) => a.path === '/');
+    notFoundRoute = routes$1.find((a) => a.path === '*');
+    routes$1 = [
+        ...(!!homeRoute ? [homeRoute] : []),
+        ...routes$1.filter((route) => !(!!route.path &&
+            ['/', '*'].includes(route.path))),
+        ...(!!notFoundRoute ? [notFoundRoute] : []),
+    ].filter((route) => (!!route.path && (route.path.indexOf('/_404') === -1 &&
+        route.path.indexOf('/_layout') === -1)));
+    if (process.env?.NODE_ENV === 'development') {
+        console.log(`[router -> routes.tsx] notFoundRoute:: `, notFoundRoute);
+        console.log(`[router -> routes.tsx] autoRoutes:: `, routesUtils_js);
+        console.log(`[router -> routes.tsx] routes:: `, routes$1);
+    }
+    return routes$1;
+};
+
+export { index as default };

package/index.min.jsx

@@ -0,0 +1 @@
+import{j as jsxRuntimeExports}from"./_virtual/jsx-runtime";import*as routesUtils_js from"./routes-utils.js";import{routes}from"./routes-utils.js";export{useRootingActions}from"./rooting.hooks.jsx";var index=()=>{let t=routes.map(t=>({path:t.path,element:t.layout?jsxRuntimeExports.jsx(t.layout,{children:jsxRuntimeExports.jsx(t.component,{})}):jsxRuntimeExports.jsx(t.component,{}),...t.error?{errorElement:jsxRuntimeExports.jsx(t.error,{})}:{}}));var r=t.find(t=>"/"===t.path),e=t.find(t=>"*"===t.path);return t=[...r?[r]:[],...t.filter(t=>!(t.path&&["/","*"].includes(t.path))),...e?[e]:[]].filter(t=>!!t.path&&-1===t.path.indexOf("/_404")&&-1===t.path.indexOf("/_layout")),process.env?.NODE_ENV,t};export{index as default};