arcanajs 2.5.3 → 2.6.0

package/framework/cli/templates.js

@@ -9,6 +9,7 @@ exports.configFiles = [
     { src: "postcss.config.js", dest: "postcss.config.js" },
     // types
     { src: "src/arcanajs.d.ts", dest: "src/arcanajs.d.ts" },
+    { src: "src/types/HomePageData.ts", dest: "src/types/HomePageData.ts" },
     // client
     { src: "src/client/globals.css", dest: "src/client/globals.css" },
     { src: "src/client/index.tsx", dest: "src/client/index.tsx" },
@@ -54,6 +55,7 @@ exports.requiredDirs = [
     "src/client",
     "src/db",
     "src/server",
+    "src/types",
     "src/server/routes",
     "src/server/controllers",
     "src/views",

package/framework/lib/shared/components/Link.js

@@ -4,17 +4,20 @@ exports.Link = void 0;
 const jsx_runtime_1 = require("react/jsx-runtime");
 const useRouter_1 = require("../hooks/useRouter");
 const Link = ({ href, children, prefetch = false, ...props }) => {
-    const { navigateTo } = (0, useRouter_1.useRouter)();
+    const { navigateTo, navigateToAsync } = (0, useRouter_1.useRouter)();
     const isExternal = /^https?:\/\//.test(href);
-    const handleClick = (e) => {
+    const handleClick = async (e) => {
         e.preventDefault();
-        if (!isExternal) {
-            navigateTo(href);
-        }
-        else {
+        if (isExternal) {
             // Open external links in a new tab
             window.open(href, "_blank", "noopener,noreferrer");
         }
+        else if (navigateToAsync) {
+            await navigateToAsync(href);
+        }
+        else {
+            navigateTo(href);
+        }
     };
     const handleMouseEnter = () => {
         if (prefetch && !isExternal) {

package/framework/lib/shared/components/Page.d.ts

@@ -1,6 +1,6 @@
 import React from "react";
-export declare const Page: React.FC<{
-    data?: any;
+export declare const Page: <T>({ data, title, children, }: {
+    data?: T;
     title?: string;
     children: React.ReactNode;
-}>;
+}) => import("react/jsx-runtime").JSX.Element;

package/framework/lib/shared/components/Page.js

@@ -4,7 +4,7 @@ exports.Page = void 0;
 const jsx_runtime_1 = require("react/jsx-runtime");
 const PageContext_1 = require("../context/PageContext");
 const Head_1 = require("./Head");
-const Page = ({ data, title, children }) => {
+const Page = ({ data, title, children, }) => {
     return ((0, jsx_runtime_1.jsxs)(PageContext_1.PageContext.Provider, { value: data, children: [title && ((0, jsx_runtime_1.jsx)(Head_1.Head, { children: (0, jsx_runtime_1.jsx)("title", { children: title }) })), children] }));
 };
 exports.Page = Page;

package/framework/lib/shared/context/PageContext.js

@@ -2,4 +2,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PageContext = void 0;
 const createSingletonContext_1 = require("../utils/createSingletonContext");
+// PageContext holds the page data (may be null before hydration).
 exports.PageContext = (0, createSingletonContext_1.createSingletonContext)("PageContext", null);

package/framework/lib/shared/context/RouterContext.d.ts

@@ -1,6 +1,7 @@
 import React from "react";
 export interface RouterContextType {
     navigateTo: (url: string) => void;
+    navigateToAsync?: (url: string) => Promise<void>;
     currentPage: string;
     currentUrl: string;
     params: Record<string, string>;

package/framework/lib/shared/core/ArcanaJSApp.d.ts

@@ -1,14 +1,20 @@
 import React from "react";
-export interface ArcanaJSAppProps {
+export interface ArcanaJSAppProps<TData = any, TParams extends Record<string, string> = Record<string, string>> {
     initialPage: string;
-    initialData: any;
-    initialParams?: Record<string, string>;
+    initialData: TData;
+    initialParams?: TParams;
     initialUrl?: string;
     csrfToken?: string;
-    views: Record<string, React.FC<any>>;
+    views: Record<string, React.ComponentType<{
+        data: TData;
+        navigateTo: (url: string) => Promise<void>;
+        params: TParams;
+    }>>;
     layout?: React.FC<{
         children: React.ReactNode;
     }>;
     onNavigate?: (url: string) => void;
+    /** Maximum number of entries to keep in the navigation cache */
+    cacheLimit?: number;
 }
-export declare const ArcanaJSApp: React.FC<ArcanaJSAppProps>;
+export declare const ArcanaJSApp: <TData = any, TParams extends Record<string, string> = Record<string, string>>(props: ArcanaJSAppProps<TData, TParams>) => import("react/jsx-runtime").JSX.Element;

package/framework/lib/shared/core/ArcanaJSApp.js

@@ -38,15 +38,18 @@ const jsx_runtime_1 = require("react/jsx-runtime");
 const react_1 = __importStar(require("react"));
 const Page_1 = require("../components/Page");
 const RouterContext_1 = require("../context/RouterContext");
-const ArcanaJSApp = ({ initialPage, initialData, initialParams = {}, initialUrl, csrfToken, views, layout: Layout, onNavigate, }) => {
+const ArcanaJSApp = (props) => {
+    const { initialPage, initialData, initialParams = {}, initialUrl, csrfToken, views, layout: Layout, onNavigate, cacheLimit = 50, } = props;
     const [page, setPage] = (0, react_1.useState)(initialPage);
     const [data, setData] = (0, react_1.useState)(initialData);
     const [params, setParams] = (0, react_1.useState)(initialParams);
     const [url, setUrl] = (0, react_1.useState)(initialUrl ||
         (typeof window !== "undefined" ? window.location.pathname : "/"));
     const [isNavigating, setIsNavigating] = (0, react_1.useState)(false);
-    // Navigation cache to store previously visited pages
+    // Navigation cache to store previously visited pages (LRU via Map ordering)
     const navigationCache = react_1.default.useRef(new Map());
+    // Abort controller for in-flight navigation fetch
+    const currentAbort = react_1.default.useRef(null);
     (0, react_1.useEffect)(() => {
         if (typeof window !== "undefined" && !window.history.state) {
             window.history.replaceState({ page: initialPage, data: initialData, params: initialParams }, "", window.location.href);
@@ -59,36 +62,62 @@ const ArcanaJSApp = ({ initialPage, initialData, initialParams = {}, initialUrl,
                 setUrl(window.location.pathname);
             }
             else {
-                window.location.reload();
+                // Try to fetch the page state instead of hard reload
+                const path = window.location.pathname;
+                void navigateTo(path).catch(() => {
+                    window.location.reload();
+                });
             }
         };
         window.addEventListener("popstate", handlePopState);
-        return () => window.removeEventListener("popstate", handlePopState);
+        return () => {
+            window.removeEventListener("popstate", handlePopState);
+            currentAbort.current?.abort();
+        };
     }, []);
+    const setCache = (key, value) => {
+        const map = navigationCache.current;
+        if (map.has(key))
+            map.delete(key);
+        map.set(key, value);
+        if (map.size > cacheLimit) {
+            const firstKey = map.keys().next().value;
+            if (firstKey !== undefined)
+                map.delete(firstKey);
+        }
+    };
     const navigateTo = async (newUrl) => {
         // Check cache first for instant navigation
-        if (navigationCache.current.has(newUrl)) {
-            const cached = navigationCache.current.get(newUrl);
+        const map = navigationCache.current;
+        if (map.has(newUrl)) {
+            const cached = map.get(newUrl);
             setPage(cached.page);
             setData(cached.data);
             setParams(cached.params || {});
             setUrl(newUrl);
             window.history.pushState(cached, "", newUrl);
-            // Scroll to top
             if (typeof window !== "undefined") {
-                window.scrollTo({ top: 0, behavior: "smooth" });
+                try {
+                    window.scrollTo({ top: 0, behavior: "smooth" });
+                }
+                catch {
+                    // ignore in non-browser env or when smooth not supported
+                }
             }
-            if (onNavigate) {
+            if (onNavigate)
                 onNavigate(newUrl);
-            }
             return;
         }
         setIsNavigating(true);
+        // Abort previous request
+        currentAbort.current?.abort();
+        const controller = new AbortController();
+        currentAbort.current = controller;
         try {
             const response = await fetch(newUrl, {
                 headers: { "X-ArcanaJS-Request": "true" },
-                // prevent caching in dev navigation
                 cache: "no-store",
+                signal: controller.signal,
             });
             if (!response.ok) {
                 if (response.status === 404) {
@@ -99,49 +128,61 @@ const ArcanaJSApp = ({ initialPage, initialData, initialParams = {}, initialUrl,
                 }
                 throw new Error(`Navigation failed: ${response.status} ${response.statusText}`);
             }
-            // Ensure server returned JSON. If not, fallback to full navigation reload
             const contentType = response.headers.get("content-type") || "";
             if (!contentType.includes("application/json")) {
-                // The server returned HTML (or something else) instead of JSON.
-                // Do a full reload so the browser displays the correct page instead
-                // of trying to parse HTML as JSON (which causes the SyntaxError).
                 window.location.href = newUrl;
                 return;
             }
             const json = await response.json();
-            // Cache the navigation result
-            navigationCache.current.set(newUrl, {
+            const payload = {
                 page: json.page,
                 data: json.data,
-                params: json.params,
-            });
-            window.history.pushState({ page: json.page, data: json.data, params: json.params }, "", newUrl);
-            setPage(json.page);
-            setData(json.data);
-            setParams(json.params || {});
+                params: (json.params || {}),
+            };
+            setCache(newUrl, payload);
+            window.history.pushState({ page: payload.page, data: payload.data, params: payload.params }, "", newUrl);
+            setPage(payload.page);
+            setData(payload.data);
+            setParams(payload.params || {});
             setUrl(newUrl);
-            // Scroll to top after navigation
             if (typeof window !== "undefined") {
-                window.scrollTo({ top: 0, behavior: "smooth" });
+                try {
+                    window.scrollTo({ top: 0, behavior: "smooth" });
+                }
+                catch {
+                    // ignore
+                }
             }
-            if (onNavigate) {
+            if (onNavigate)
                 onNavigate(newUrl);
-            }
         }
-        catch (error) {
-            console.error("Navigation failed", error);
+        catch (err) {
+            if (err?.name === "AbortError")
+                return;
+            console.error("Navigation failed", err);
+            throw err;
         }
         finally {
+            // Clear abort controller if it's still the one we set
+            if (currentAbort.current === controller)
+                currentAbort.current = null;
             setIsNavigating(false);
         }
     };
     const renderPage = () => {
-        const Component = views[page] || views["NotFoundPage"] || (() => (0, jsx_runtime_1.jsx)("div", { children: "404 Not Found" }));
+        const Component = (views[page] ||
+            views["NotFoundPage"] ||
+            (() => (0, jsx_runtime_1.jsx)("div", { children: "404 Not Found" })));
         return ((0, jsx_runtime_1.jsx)(Page_1.Page, { data: data, children: (0, jsx_runtime_1.jsx)(Component, { data: data, navigateTo: navigateTo, params: params }) }));
     };
     const content = renderPage();
     return ((0, jsx_runtime_1.jsx)(RouterContext_1.RouterProvider, { value: {
-            navigateTo,
+            // keep backward-compatible wrapper that doesn't return a promise
+            navigateTo: (...args) => {
+                void navigateTo(args[0]);
+            },
+            // new async API consumers can use `navigateToAsync` when available
+            navigateToAsync: navigateTo,
             currentPage: page,
             currentUrl: url,
             params,

package/framework/templates/package.json

@@ -8,7 +8,7 @@
     "start": "arcanajs start"
   },
   "dependencies": {
-    "arcanajs": "^2.5.3",
+    "arcanajs": "^2.6.0",
     "react": "^19.2.0",
     "react-dom": "^19.2.0"
   }

package/framework/templates/src/server/controllers/HomeController.ts

@@ -1,7 +1,19 @@
 import { Request, Response } from "arcanajs/server";
+import type { HomePageData } from "../../types/HomePageData";
 
 export default class HomeController {
   home(_req: Request, res: Response) {
-    res.renderPage("HomePage");
+    // Provide example page data to demonstrate passing data to the view
+    const data: HomePageData = {
+      welcome: "Welcome to ArcanaJS",
+      subtitle: "A modern React framework with server-side rendering",
+      time: new Date().toISOString(),
+      posts: [
+        { id: 1, title: "Getting started with ArcanaJS" },
+        { id: 2, title: "Building fast apps with SSR" },
+      ],
+    };
+
+    res.renderPage("HomePage", data);
   }
 }

package/framework/templates/src/server/index.ts

@@ -20,10 +20,13 @@ const server = new ArcanaJSServer({
   // Example: provide a dbConnect function that returns the DB client/connection.
   // You can connect to MySQL/Postgres/MongoDB here and return the client.
   // dbConnect: async () => {
-  //   const { MongoClient } = await import('mongodb');
-  //   const client = new MongoClient(process.env.MONGO_URL || 'mongodb://localhost:27017');
-  //   await client.connect();
-  //   return client.db('mydb');
+  // const { MongoClient } = await import("mongodb");
+  // const url = process.env.MONGO_URL || "mongodb://localhost:27017";
+  // const dbName = process.env.MONGO_DB || "mydb";
+  // const client = new MongoClient(url);
+  // await client.connect();
+  // const db = client.db(dbName);
+  // return { client, db };
   // },
   // Or use one of the provided DB templates (uncomment one):
   // dbConnect: mongoDb,

package/framework/templates/src/types/HomePageData.ts

@@ -0,0 +1,11 @@
+export interface Post {
+  id: number;
+  title: string;
+}
+
+export interface HomePageData {
+  welcome: string;
+  subtitle?: string;
+  time?: string;
+  posts?: Post[];
+}

package/framework/templates/src/views/HomePage.tsx

@@ -1,6 +1,9 @@
-import { Body, Head, Page } from "arcanajs";
+import { Body, Head, Page, usePage } from "arcanajs";
+import type { HomePageData } from "../types/HomePageData";
 
 export default function HomePage() {
+  const pageData = usePage<HomePageData | null>();
+
   return (
     <Page>
       <Head>
@@ -83,6 +86,28 @@ export default function HomePage() {
                     Tailwind CSS v4 support. Build fast, beautiful applications
                     with zero configuration.
                   </p>
+                  {pageData && (
+                    <div className="text-sm text-gray-400 mb-6">
+                      <div className="font-semibold text-white">
+                        {pageData.welcome ?? "Welcome"}
+                      </div>
+                      <div className="text-gray-400 text-sm">
+                        {pageData.subtitle}
+                      </div>
+                      <div className="text-xs text-gray-500 mt-1">
+                        Server time: {pageData.time}
+                      </div>
+                      {Array.isArray(pageData.posts) && (
+                        <ul className="mt-3 text-left list-disc list-inside text-gray-300">
+                          {pageData.posts.map((p) => (
+                            <li key={p.id} className="truncate">
+                              {p.title}
+                            </li>
+                          ))}
+                        </ul>
+                      )}
+                    </div>
+                  )}
                   <div className="flex flex-col sm:flex-row gap-4 justify-center">
                     <button className="btn-primary px-8 py-3.5 text-lg font-semibold rounded-xl inline-flex items-center justify-center gap-2">
                       Get Started

package/package.json

@@ -5,7 +5,7 @@
     "email": "mohammed.bencheikh.dev@gmail.com",
     "url": "https://mohammedbencheikh.com/"
   },
-  "version": "2.5.3",
+  "version": "2.6.0",
   "description": "ArcanaJS Framework",
   "main": "framework/lib/index.js",
   "types": "framework/lib/index.d.ts",