router-kit 0.1.2 → 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mohammed Ben Cheikh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,180 @@
+# Router Kit
+
+Un petit fournisseur de routing pour React, minimal et léger, créé par Mohammed Ben Cheikh.
+
+Ce README documente l'utilisation publique du package `router-kit` : installation, API, exemples d'utilisation et bonnes pratiques.
+
+## Table des matières
+
+- 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
+
+## Introduction
+
+`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.
+
+Le routeur :
+
+- 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.
+
+## Installation
+
+Installer en tant que dépendance (ex : npm) :
+
+```bash
+npm install router-kit
+```
+
+N.B. `react` et `react-dom` sont des peerDependencies ; installez-les dans votre projet si nécessaire.
+
+## Concepts clés
+
+- 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.
+
+## API publique
+
+Voici l'API exposée par le package (extraits depuis `src/index.ts`).
+
+- 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";
+
+### createRouter(routes)
+
+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`.
+
+Signature :
+
+```ts
+createRouter(routes: Route[]): Route[]
+```
+
+### RouterProvider
+
+Composant qui prend une prop `routes` (Route[]) et rend le composant correspondant à l'URL actuelle.
+
+Usage :
+
+```tsx
+import { RouterProvider } from "router-kit";
+
+const routes = createRouter([
+  { path: "/", component: <Home /> },
+  { path: "users/:id", component: <User /> },
+  { path: "/404", component: <NotFound /> },
+]);
+
+function App() {
+  return <RouterProvider routes={routes} />;
+}
+```
+
+Le provider expose via le contexte :
+
+- `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 })`
+
+### Link et NavLink
+
+`<Link to="...">` : rend un lien <a> qui empêche le comportement par défaut et appelle `navigate(to)`.
+
+`<NavLink to="..." activeClassName="...">` : comme `Link` mais ajoute `activeClassName` quand la route est active (comparaison stricte `path === to`).
+
+Exemple :
+
+```tsx
+<Link to="/about">À propos</Link>
+<NavLink to="/">Accueil</NavLink>
+```
+
+### Hooks
+
+- `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 }`.
+
+## Exemple complet
+
+```tsx
+import React from "react";
+import { createRouter, RouterProvider, Link } from "router-kit";
+
+const Home = <div>Accueil</div>;
+const About = <div>À propos</div>;
+
+const routes = createRouter([
+  { path: "/", component: Home },
+  { path: "about", component: About },
+  { path: "/404", component: <div>Not Found</div> },
+]);
+
+export default function App() {
+  return (
+    <div>
+      <nav>
+        <Link to="/">Home</Link>
+        <Link to="/about">About</Link>
+      </nav>
+      <RouterProvider routes={routes} />
+    </div>
+  );
+}
+```
+
+## Routes et 404
+
+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`).
+
+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.
+
+## Développement
+
+Scripts disponibles (définis dans `package.json`) :
+
+- `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`.
+
+Pour développer localement :
+
+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.
+
+## Contribuer
+
+Les contributions sont bienvenues. Pour des petites améliorations :
+
+1. Ouvrir une issue décrivant le problème ou la fonctionnalité.
+2. Soumettre une PR avec un seul changement logique par PR.
+
+Propositions d'améliorations possibles :
+
+- Support d'URL basées sur hash (/#/path).
+- Support plus riche du matching (wildcards, regex, exact/partial).
+- Tests unitaires et CI.
+
+## Licence
+
+MIT — voir le fichier `LICENSE`.
+
+---

package/dist/{Link.js → components/Link.js}

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useRouter } from "./useRouter";
+import { useRouter } from "../hooks/useRouter";
 function Link({ to, children, className, }) {
     const { navigate } = useRouter();
     return (_jsx("a", { onClick: (e) => {

package/dist/{NavLink.js → components/NavLink.js}

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useRouter } from "./useRouter";
+import { useRouter } from "../hooks/useRouter";
 function NavLink({ to, children, className, activeClassName = "active", }) {
     const { navigate, path } = useRouter();
     const isActive = path === to;

package/dist/{RouterContext.d.ts → context/RouterContext.d.ts}

@@ -1,3 +1,3 @@
-import type { RouterContextType } from "./types";
+import type { RouterContextType } from "../types";
 declare const RouterContext: import("react").Context<RouterContextType | undefined>;
 export default RouterContext;

package/dist/{RouterProvider.d.ts → context/RouterProvider.d.ts}

@@ -1,4 +1,4 @@
-import type { Route } from "./types";
+import type { Route } from "../types";
 declare const RouterProvider: ({ routes }: {
     routes: Route[];
 }) => import("react/jsx-runtime").JSX.Element;

package/dist/{RouterProvider.js → context/RouterProvider.js}

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useState } from "react";
 import join from "url-join";
-import Page404 from "./pages/404";
+import Page404 from "../pages/404";
 import RouterContext from "./RouterContext";
 const RouterProvider = ({ routes }) => {
     const [path, setPath] = useState(window.location.pathname);

package/dist/{createRouter.d.ts → core/createRouter.d.ts}

@@ -1,3 +1,3 @@
-import type { Route } from "./types";
+import type { Route } from "../types";
 declare function createRouter(routes: Route[]): Route[];
 export default createRouter;

package/dist/hooks/useRouter.d.ts

@@ -0,0 +1 @@
+export declare function useRouter(): import("../types").RouterContextType;

package/dist/{useRouter.js → hooks/useRouter.js}

@@ -1,5 +1,5 @@
 import { useContext } from "react";
-import RouterContext from "./RouterContext";
+import RouterContext from "../context/RouterContext";
 export function useRouter() {
     const ctx = useContext(RouterContext);
     if (!ctx)

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export { default as createRouter } from "./createRouter";
-export { useParams, useQuery } from "./hook";
-export { default as Link } from "./Link";
-export { default as NavLink } from "./NavLink";
-export { default as RouterProvider } from "./RouterProvider";
+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";

package/dist/index.js

@@ -1,5 +1,5 @@
-export { default as createRouter } from "./createRouter";
-export { useParams, useQuery } from "./hook";
-export { default as Link } from "./Link";
-export { default as NavLink } from "./NavLink";
-export { default as RouterProvider } from "./RouterProvider";
+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";

package/dist/pages/404/index.d.ts

@@ -1,3 +1,2 @@
-import "./styles.css";
 declare const Page404: () => import("react/jsx-runtime").JSX.Element;
 export default Page404;

package/dist/pages/404/index.js

@@ -1,10 +1,56 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useRouter } from "../../useRouter";
-import "./styles.css";
+import { useState } from "react";
+import { useRouter } from "../../hooks/useRouter";
+const staile = {
+    errorPage: {
+        minHeight: "100vh",
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        backgroundColor: "#f3f4f6",
+    },
+    errorContainer: {
+        textAlign: "center",
+        padding: "0 1rem",
+    },
+    errorTitle: {
+        fontSize: "9rem",
+        fontWeight: 700,
+        color: "#1f2937",
+        margin: 0,
+    },
+    errorSubtitle: {
+        fontSize: "1.5rem",
+        fontWeight: 600,
+        color: "#4b5563",
+        marginTop: "1rem",
+        marginBottom: 0,
+    },
+    errorMessage: {
+        color: "#6b7280",
+        margin: "1rem 0 2rem 0",
+    },
+    errorButton: {
+        padding: "0.75rem 1.5rem",
+        backgroundColor: "#2563eb",
+        color: "white",
+        border: "none",
+        borderRadius: "0.5rem",
+        cursor: "pointer",
+        transition: "background-color 0.2s",
+    },
+    errorButtonHover: {
+        backgroundColor: "#1d4ed8",
+    },
+};
 const Page404 = () => {
     const { navigate } = useRouter();
-    return (_jsx("div", { className: "error-page", children: _jsxs("div", { className: "error-container", children: [_jsx("h1", { className: "error-title", children: "404" }), _jsx("h2", { className: "error-subtitle", children: "Page Not Found" }), _jsx("p", { className: "error-message", children: "Sorry, the page you are looking for does not exist or has been moved." }), _jsx("button", { onClick: () => {
+    const [hover, setHover] = useState(false);
+    return (_jsx("div", { style: staile.errorPage, children: _jsxs("div", { style: staile.errorContainer, children: [_jsx("h1", { style: staile.errorTitle, children: "404" }), _jsx("h2", { style: staile.errorSubtitle, children: "Page Not Found" }), _jsx("p", { style: staile.errorMessage, children: "Sorry, the page you are looking for does not exist or has been moved." }), _jsx("button", { onClick: () => {
                         navigate("/");
-                    }, className: "error-button", children: "Go Back Home" })] }) }));
+                    }, onMouseEnter: () => setHover(true), onMouseLeave: () => setHover(false), style: {
+                        ...staile.errorButton,
+                        ...(hover ? staile.errorButtonHover : {}),
+                    }, children: "Go Back Home" })] }) }));
 };
 export default Page404;

package/package.json

@@ -5,10 +5,10 @@
     "email": "mohammed.bencheikh.dev@gmail.com",
     "url": "https://mohammedbencheikh.com/"
   },
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "A small React routing provider library",
   "main": "dist/index.js",
-  "types": "dist/*.d.ts",
+  "types": "dist/index.d.ts",
   "files": [
     "dist"
   ],
@@ -16,11 +16,13 @@
     "clean": "rm -rf dist",
     "build": "tsc -p tsconfig.json",
     "build:watch": "tsc -p tsconfig.json --watch",
-    "prepare": "npm run build"
+    "prepare": "npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "pack:verify": "npm pack --dry-run"
   },
   "peerDependencies": {
-    "react": ">=17 <19",
-    "react-dom": ">=17 <19"
+    "react": ">=16 <20",
+    "react-dom": ">=16 <20"
   },
   "dependencies": {
     "url-join": "^5.0.0"

package/dist/useRouter.d.ts

@@ -1 +0,0 @@
-export declare function useRouter(): import("./types").RouterContextType;