router-kit 1.3.0 → 1.3.2

package/README.md

@@ -1,186 +1,459 @@
-# Router Kit
+# Documentation Index
 
-Un petit fournisseur de routing pour React, minimal et léger, créé par Mohammed Ben Cheikh.
+Complete documentation for Router-Kit v1.3.1
 
-Ce README documente l'utilisation publique du package `router-kit` : installation, API, exemples d'utilisation et bonnes pratiques.
+🌐 **Website:** [https://routerkit.com/](https://routerkit.com/)
 
-## Table des matières
+---
+
+## 📚 Documentation Structure
 
-- Introduction
-- Installation
-- Concepts clés
-- API publique
-  - `createRouter(routes)`
-  - `<RouterProvider routes={...} />`
-  - `<Link to="...">` et `<NavLink to="...">`
-  - Hooks : `useParams()`, `useQuery()` et `useRouter()`
-- Exemple d'utilisation
-- Routes et 404
-- Développement
-- Contribuer
-- Licence
+This directory contains comprehensive documentation for Router-Kit. Choose the documentation that best fits your needs:
 
-## Introduction
+### For Users
 
-`router-kit` fournit un routeur côté client très simple pour les applications React. Il ne dépend que de React et d'une petite utilité `url-join` pour composer les chemins.
+- **[Quick Start Guide](#quick-start-guide)** - Get up and running in 5 minutes
+- **[Complete Documentation](./DOCUMENTATION.md)** - Full feature guide with examples
+- **[API Reference](./API_REFERENCE.md)** - Detailed API documentation
+- **[Examples](./EXAMPLES.md)** - Real-world usage examples
 
-Le routeur :
+### For Developers
 
-- Résout les composants en fonction du `window.location.pathname`.
-- Expose un contexte pour naviguer (`navigate`) et connaître le `path` courant.
-- Prend en charge des paramètres de route de type `/:id` et l'extraction via `useParams()`.
-- Fournit un 404 configurable.
+- **[Architecture](./ARCHITECTURE.md)** - Internal implementation details
+- **[Contributing Guide](#contributing)** - How to contribute to Router-Kit
 
-## Installation
+---
 
-Installer en tant que dépendance (ex : npm) :
+## Quick Start Guide
+
+### Installation
 
 ```bash
 npm install router-kit
 ```
 
-N.B. `react` et `react-dom` sont des peerDependencies ; installez-les dans votre projet si nécessaire.
+### Basic Setup
 
-## Important
+```tsx
+import React from "react";
+import { createRouter, RouterProvider, Link } from "router-kit";
 
-⚠️ Tous les hooks et composants de router-kit doivent être utilisés à l'intérieur du `RouterProvider`. Assurez-vous de wrapper votre application avec le `RouterProvider` au plus haut niveau possible.
+// 1. Define your components
+const Home = () => <h1>Home Page</h1>;
+const About = () => <h1>About Page</h1>;
 
-Si vous utilisez des composants ou hooks en dehors du `RouterProvider`, vous obtiendrez une erreur explicite :
+// 2. Create routes
+const routes = createRouter([
+  { path: "/", component: <Home /> },
+  { path: "about", component: <About /> },
+]);
+
+// 3. Wrap your app with RouterProvider
+function App() {
+  return <RouterProvider routes={routes} />;
+}
 
+export default App;
 ```
-RouterKit: Common hooks and components must be used within the RouterProvider returned by createRouter(). Wrap your app with the RouterProvider.
+
+### Navigation
+
+```tsx
+import { Link, NavLink } from "router-kit";
+
+function Navigation() {
+  return (
+    <nav>
+      <Link to="/">Home</Link>
+      <NavLink to="/about" activeClassName="active">
+        About
+      </NavLink>
+    </nav>
+  );
+}
 ```
 
-## Concepts clés
+### Dynamic Routes
 
-- Route : objet avec `path` (string) et `component` (JSX.Element). Les `children` sont supportés pour construire des arborescences.
-- `createRouter(routes)` : normalise les chemins (supprime les slashs initiaux) et retourne la structure de routes.
-- `RouterProvider` : fournit le contexte et rend le composant correspondant au `path` courant.
-- `navigate(to, { replace })` : change l'URL en utilisant l'API History et met à jour le rendu.
+```tsx
+import { useParams } from "router-kit";
 
-## API publique
+// Route: /users/:id
+const routes = createRouter([
+  { path: "users/:id", component: <UserProfile /> },
+]);
 
-Voici l'API exposée par le package (extraits depuis `src/index.ts`).
+function UserProfile() {
+  const { id } = useParams();
+  return <h1>User {id}</h1>;
+}
+```
 
-- export { default as Link } from "./components/Link";
-- export { default as NavLink } from "./components/NavLink";
-- export { default as RouterProvider } from "./context/RouterProvider";
-- export { default as createRouter } from "./core/createRouter";
-- export { useParams, useQuery } from "./hooks/hook";
+### Programmatic Navigation
 
-### createRouter(routes)
+```tsx
+import { useRouter } from "router-kit";
 
-Fonction d'aide qui normalise une liste de routes. Elle supprime les slashs initiaux dans les `path` et renvoie la structure prête à être passée à `RouterProvider`.
+function LoginForm() {
+  const { navigate } = useRouter();
 
-Signature :
+  const handleLogin = () => {
+    // After successful login
+    navigate("/dashboard");
+  };
 
-```ts
-createRouter(routes: Route[]): Route[]
+  return <button onClick={handleLogin}>Login</button>;
+}
 ```
 
-### RouterProvider
+---
+
+## Documentation Files
 
-Composant qui prend une prop `routes` (Route[]) et rend le composant correspondant à l'URL actuelle.
+### [DOCUMENTATION.md](./DOCUMENTATION.md)
 
-Usage :
+**Complete user guide covering:**
 
-```tsx
-import { RouterProvider } from "router-kit";
+- Introduction and key features
+- Installation instructions
+- Core concepts explained
+- API reference with examples
+- Advanced usage patterns
+- Error handling strategies
+- TypeScript support
+- Best practices
+- Migration guide from other routers
+- Real-world examples
+
+**Best for:** Learning Router-Kit from scratch, understanding concepts, and finding usage examples.
+
+### [API_REFERENCE.md](./API_REFERENCE.md)
+
+**Comprehensive API documentation including:**
+
+- `createRouter()` function
+- `RouterProvider` component
+- `Link` and `NavLink` components
+- `useRouter()` hook
+- `useParams()` hook
+- `useQuery()` hook
+- `useLocation()` hook
+- `useDynamicComponents()` hook
+- Type definitions
+- Error system reference
 
+**Best for:** Looking up specific APIs, understanding function signatures, and exploring available options.
+
+### [EXAMPLES.md](./EXAMPLES.md)
+
+**Practical examples featuring:**
+
+- Basic routing examples
+- E-commerce application
+- Blog platform
+- Dashboard application
+- Multi-language website
+- Authentication flow
+- Advanced patterns (lazy loading, modals, breadcrumbs, animations)
+
+**Best for:** Finding real-world implementation patterns and copy-paste solutions.
+
+### [ARCHITECTURE.md](./ARCHITECTURE.md)
+
+**Technical implementation details including:**
+
+- System architecture overview
+- Core component implementations
+- Route matching algorithm
+- History management
+- Context system
+- Error handling system
+- Type system
+- Performance considerations
+- Build and distribution
+
+**Best for:** Understanding internals, contributing to the project, or debugging complex issues.
+
+---
+
+## Common Use Cases
+
+### Simple Website
+
+```tsx
 const routes = createRouter([
   { path: "/", component: <Home /> },
-  { path: "users/:id", component: <User /> },
+  { path: "about", component: <About /> },
+  { path: "contact", component: <Contact /> },
   { path: "/404", component: <NotFound /> },
 ]);
+```
 
-function App() {
-  return <RouterProvider routes={routes} />;
-}
+📖 **See:** [Basic Examples in EXAMPLES.md](./EXAMPLES.md#basic-examples)
+
+### Blog or CMS
+
+```tsx
+const routes = createRouter([
+  { path: "/", component: <BlogHome /> },
+  { path: "posts/:category/:slug", component: <BlogPost /> },
+  { path: "author/:username", component: <AuthorProfile /> },
+]);
 ```
 
-Le provider expose via le contexte :
+📖 **See:** [Blog Platform in EXAMPLES.md](./EXAMPLES.md#blog-platform)
 
-- `path` : le pathname courant (ex: `/users/42`)
-- `fullPathWithParams` : le chemin défini dans la route incluant les paramètres (ex: `/users/:id`)
-- `navigate(to: string, options?: { replace?: boolean })`
+### Dashboard Application
 
-### Link et NavLink
+```tsx
+const routes = createRouter([
+  { path: "dashboard/:view", component: <Dashboard /> },
+]);
+
+function Dashboard() {
+  const views = {
+    overview: <OverviewView />,
+    analytics: <AnalyticsView />,
+    settings: <SettingsView />,
+  };
 
-`<Link to="...">` : rend un lien <a> qui empêche le comportement par défaut et appelle `navigate(to)`.
+  return useDynamicComponents(views, "view");
+}
+```
 
-`<NavLink to="..." activeClassName="...">` : comme `Link` mais ajoute `activeClassName` quand la route est active (comparaison stricte `path === to`).
+📖 **See:** [Dashboard Application in EXAMPLES.md](./EXAMPLES.md#dashboard-application)
 
-Exemple :
+### E-commerce Site
 
 ```tsx
-<Link to="/about">À propos</Link>
-<NavLink to="/">Accueil</NavLink>
+const routes = createRouter([
+  { path: "/", component: <HomePage /> },
+  { path: "products", component: <ProductList /> },
+  { path: "products/:id", component: <ProductDetail /> },
+  { path: "cart", component: <Cart /> },
+  { path: "checkout", component: <Checkout /> },
+]);
 ```
 
-### Hooks
+📖 **See:** [E-commerce Application in EXAMPLES.md](./EXAMPLES.md#e-commerce-application)
 
-- `useRouter()` : hook interne retournant le contexte `{ path, fullPathWithParams, navigate }`. Lance une erreur si utilisé hors du provider.
-- `useParams()` : renvoie un objet clé/valeur pour les segments paramétrés de la route (ex: `{ id: "42" }`). Se base sur `fullPathWithParams` et `path`.
-- `useQuery()` : parse `window.location.search` et renvoie un objet `{ [key]: value }`.
-- `useLocation()` : renvoie un objet avec les informations de localisation courante : `{ pathname, search, hash, state }`. Utile pour accéder aux détails de l'URL actuelle.
+### Protected Routes
 
-## Exemple complet
+```tsx
+const routes = createRouter([
+  { path: "/", component: <PublicHome /> },
+  {
+    path: "dashboard",
+    component: (
+      <ProtectedRoute>
+        <Dashboard />
+      </ProtectedRoute>
+    ),
+  },
+]);
+```
+
+📖 **See:** [Authentication Flow in EXAMPLES.md](./EXAMPLES.md#authentication-flow)
+
+---
+
+## Feature Matrix
+
+| Feature               | Status | Documentation                                    |
+| --------------------- | ------ | ------------------------------------------------ |
+| Static Routes         | ✅     | [Docs](./DOCUMENTATION.md#routes)                |
+| Dynamic Routes        | ✅     | [Docs](./DOCUMENTATION.md#useparams)             |
+| Nested Routes         | ✅     | [Docs](./DOCUMENTATION.md#nested-routes)         |
+| Multiple Path Aliases | ✅     | [Docs](./DOCUMENTATION.md#multiple-path-aliases) |
+| Query Parameters      | ✅     | [Docs](./DOCUMENTATION.md#usequery)              |
+| Navigation State      | ✅     | [Docs](./DOCUMENTATION.md#navigation-state)      |
+| Custom 404 Pages      | ✅     | [Docs](./DOCUMENTATION.md#custom-404-pages)      |
+| TypeScript Support    | ✅     | [Docs](./DOCUMENTATION.md#typescript-support)    |
+| Error Handling        | ✅     | [Docs](./DOCUMENTATION.md#error-handling)        |
+| Dynamic Components    | ✅     | [Docs](./API_REFERENCE.md#usedynamiccomponents)  |
+| Hash Routing          | ⏳     | Planned                                          |
+| Regex Routes          | ⏳     | Planned                                          |
+
+---
+
+## Quick Reference
+
+### Imports
 
 ```tsx
-import React from "react";
+// Core
 import { createRouter, RouterProvider } from "router-kit";
 
-const Home = () => <div>Accueil</div>;
-const About = () => <div>À propos</div>;
+// Components
+import { Link, NavLink } from "router-kit";
+
+// Hooks
+import {
+  useRouter,
+  useParams,
+  useQuery,
+  useLocation,
+  useDynamicComponents,
+} from "router-kit";
+
+// Types
+import type {
+  Route,
+  RouterContextType,
+  NavigateOptions,
+  Location,
+  RouterKitError,
+} from "router-kit";
+
+// Error System
+import { RouterErrorCode, RouterErrors, createRouterError } from "router-kit";
+```
 
-const routes = createRouter([
-  { path: "/", component: <Home /> },
-  { path: "about", component: <About /> },
-  { path: "/404", component: <div>Not Found</div> },
-]);
+### Route Patterns
 
-// Les composants de navigation doivent être à l'intérieur du RouterProvider
-function App() {
-  return <RouterProvider routes={routes} />;
+```tsx
+// Static route
+{ path: "about", component: <About /> }
+
+// Dynamic parameter
+{ path: "users/:id", component: <UserProfile /> }
+
+// Multiple parameters
+{ path: "posts/:category/:slug", component: <BlogPost /> }
+
+// Multiple paths
+{ path: ["about", "about-us"], component: <About /> }
+
+// Nested routes
+{
+  path: "dashboard",
+  component: <Dashboard />,
+  children: [
+    { path: "settings", component: <Settings /> }
+  ]
 }
 
-export default App;
+// 404 page
+{ path: "/404", component: <NotFound /> }
+```
+
+### Hook Usage
+
+```tsx
+// Get router context
+const { path, navigate } = useRouter();
+
+// Get route parameters
+const { id, slug } = useParams();
+
+// Get query parameters
+const { search, page } = useQuery();
+
+// Get location details
+const { pathname, search, hash, state } = useLocation();
+
+// Dynamic components
+const component = useDynamicComponents(viewsObject, "paramName");
 ```
 
-## Routes et 404
+---
+
+## Version Information
+
+- **Current Version:** 1.3.1
+- **React Version:** >=16 <20
+- **TypeScript:** >=5.2.0
+- **License:** MIT
+
+---
+
+## Support & Community
+
+- **Website:** [routerkit.com](https://routerkit.com/)
+- **GitHub Repository:** [github.com/Mohammed-Ben-Cheikh/router-kit](https://github.com/Mohammed-Ben-Cheikh/router-kit)
+- **Issues:** [Report bugs or request features](https://github.com/Mohammed-Ben-Cheikh/router-kit/issues)
+- **Author:** Mohammed Ben Cheikh
+- **Email:** mohammed.bencheikh.dev@gmail.com
+- **Website:** [mohammedbencheikh.com](https://mohammedbencheikh.com/)
+
+---
+
+## Contributing
+
+We welcome contributions! Here's how to get started:
+
+1. **Fork the repository**
+2. **Create a feature branch:** `git checkout -b feature/amazing-feature`
+3. **Make your changes**
+4. **Run tests and type checks:** `npm run typecheck`
+5. **Commit your changes:** `git commit -m 'Add amazing feature'`
+6. **Push to your fork:** `git push origin feature/amazing-feature`
+7. **Open a Pull Request**
+
+**See:** [ARCHITECTURE.md](./ARCHITECTURE.md) for implementation details.
+
+---
+
+## Changelog
+
+### v1.3.1 (Current)
+
+- Full TypeScript support with comprehensive types
+- Enhanced error handling system with detailed context
+- New `useDynamicComponents` hook
+- New `useLocation` hook with state support
+- Improved type exports
+- Better error messages
+
+### Previous Versions
+
+See [GitHub Releases](https://github.com/Mohammed-Ben-Cheikh/router-kit/releases) for full changelog.
+
+---
 
-Le provider recherche les routes et compare le `fullPath` de chaque route avec le pathname courant en remplaçant dynamiquement les segments commençant par `:` (ex: `/:id`).
+## FAQ
 
-Pour afficher une page 404 personnalisée, ajoutez une route avec `path: "/404"` et `component` : elle sera utilisée par défaut quand aucune route ne matche.
+### How does Router-Kit compare to React Router?
 
-## Développement
+Router-Kit is simpler and lighter. It's perfect for small to medium projects that don't need the full complexity of React Router.
 
-Scripts disponibles (définis dans `package.json`) :
+📖 **See:** [Migration Guide in DOCUMENTATION.md](./DOCUMENTATION.md#migration-guide)
 
-- `npm run build` : compile TypeScript vers `dist/` (utilise `tsc`).
-- `npm run typecheck` : vérifie les types sans émettre de fichiers.
-- `npm run clean` : supprime `dist`.
+### Can I use Router-Kit with TypeScript?
 
-Pour développer localement :
+Yes! Router-Kit is written in TypeScript and provides full type definitions.
 
-1. Cloner le dépôt et installer les dépendances.
-2. Lancer `npm run build:watch` si vous modifiez le package et voulez recompiler automatiquement.
+📖 **See:** [TypeScript Support in DOCUMENTATION.md](./DOCUMENTATION.md#typescript-support)
 
-## Contribuer
+### How do I handle authentication?
 
-Les contributions sont bienvenues. Pour des petites améliorations :
+Use the ProtectedRoute pattern with useRouter and useLocation hooks.
 
-1. Ouvrir une issue décrivant le problème ou la fonctionnalité.
-2. Soumettre une PR avec un seul changement logique par PR.
+📖 **See:** [Authentication Flow in EXAMPLES.md](./EXAMPLES.md#authentication-flow)
 
-Propositions d'améliorations possibles :
+### How do I create nested routes?
 
-- Support d'URL basées sur hash (/#/path).
-- Support plus riche du matching (wildcards, regex, exact/partial).
-- Tests unitaires et CI.
+Use the `children` property in route configuration.
 
-## Licence
+📖 **See:** [Nested Routes in DOCUMENTATION.md](./DOCUMENTATION.md#nested-routes)
 
-MIT — voir le fichier `LICENSE`.
+### What about 404 pages?
+
+Add a route with `path: "/404"` and Router-Kit will use it automatically.
+
+📖 **See:** [Custom 404 Pages in DOCUMENTATION.md](./DOCUMENTATION.md#custom-404-pages)
+
+---
+
+## Learn More
+
+Ready to dive deeper? Start with the [Complete Documentation](./DOCUMENTATION.md) or explore specific topics:
+
+- New to Router-Kit? → [DOCUMENTATION.md](./DOCUMENTATION.md)
+- Need API details? → [API_REFERENCE.md](./API_REFERENCE.md)
+- Want examples? → [EXAMPLES.md](./EXAMPLES.md)
+- Curious about internals? → [ARCHITECTURE.md](./ARCHITECTURE.md)
 
 ---
+
+**Happy Routing! 🚀**

package/dist/context/RouterProvider.js

@@ -17,18 +17,6 @@ const RouterProvider = ({ routes }) => {
     const [path, setPath] = useState("");
     const [fullPathWithParams, setFullPathWithParams] = useState("");
     let page404 = null;
-    const paths = routes.flatMap((route) => {
-        const collectPaths = (r, parentPath = "/") => {
-            const fullPath = join(parentPath, `/${r.path}`);
-            const currentPaths = [fullPath];
-            if (r.children) {
-                const childPaths = r.children.flatMap((child) => collectPaths(child, fullPath));
-                return [...currentPaths, ...childPaths];
-            }
-            return currentPaths;
-        };
-        return collectPaths(route);
-    });
     useEffect(() => {
         setPath(window.location.pathname);
         const patchHistory = (method) => {
@@ -57,22 +45,7 @@ const RouterProvider = ({ routes }) => {
     }, []);
     const pathValidation = (routeFullPath, currentPath) => {
         const routePaths = routeFullPath.split("|");
-        const staticPaths = [];
-        const dynamicPaths = [];
         for (const routePath of routePaths) {
-            if (routePath.includes(":")) {
-                dynamicPaths.push(routePath);
-            }
-            else {
-                staticPaths.push(routePath);
-            }
-        }
-        for (const routePath of staticPaths) {
-            if (routePath === currentPath) {
-                return routePath;
-            }
-        }
-        for (const routePath of dynamicPaths) {
             const routeParts = routePath.split("/").filter(Boolean);
             const pathParts = currentPath.split("/").filter(Boolean);
             if (routeParts.length !== pathParts.length)
@@ -94,12 +67,39 @@ const RouterProvider = ({ routes }) => {
         return false;
     };
     const getComponent = (routesList, currentPath, parentPath = "/") => {
+        const staticRoutes = [];
+        const dynamicRoutes = [];
         for (const route of routesList) {
             const is404 = route.path === "404" || route.path === "/404";
             if (is404) {
                 page404 = route.component;
                 continue;
             }
+            const pathArray = Array.isArray(route.path) ? route.path : [route.path];
+            const hasDynamicParams = pathArray.some((p) => p.includes(":"));
+            if (hasDynamicParams) {
+                dynamicRoutes.push(route);
+            }
+            else {
+                staticRoutes.push(route);
+            }
+        }
+        for (const route of staticRoutes) {
+            const fullPath = join(parentPath, `/${route.path}`);
+            const matchedPath = pathValidation(fullPath, currentPath);
+            if (matchedPath) {
+                if (matchedPath !== fullPathWithParams) {
+                    setFullPathWithParams(matchedPath);
+                }
+                return route.component;
+            }
+            if (route.children) {
+                const childMatch = getComponent(route.children, currentPath, fullPath);
+                if (childMatch)
+                    return childMatch;
+            }
+        }
+        for (const route of dynamicRoutes) {
             const fullPath = join(parentPath, `/${route.path}`);
             const matchedPath = pathValidation(fullPath, currentPath);
             if (matchedPath) {

package/package.json

@@ -5,7 +5,7 @@
     "email": "mohammed.bencheikh.dev@gmail.com",
     "url": "https://mohammedbencheikh.com/"
   },
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "A small React routing provider library",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",