vite-plugin-vanjs 0.0.10 → 0.1.0

package/router/global.d.ts

@@ -14,20 +14,30 @@ declare module "@vanjs/router" {
   } from "vanjs-core";
 
   // type VanElement = VElement | Exclude<Primitive, boolean | undefined>;
-  type DOMElement = globalThis.Element;
+  // type DOMElement = globalThis.Element;
   type PrimitiveChild = Primitive | State<Primitive | undefined | null>;
 
-  type VanElement =
+  type DOMElement<T extends keyof HTMLElementTagNameMap = "div"> =
     | SVGElement
     | HTMLElement
-    | DOMElement
     | Node
+    | HTMLElementTagNameMap[T];
+
+  export type VanElement =
+    | DOMElement
     | VElement
     | PrimitiveChild;
+  // type VanElement =
+  //   | SVGElement
+  //   | HTMLElement
+  //   | DOMElement
+  //   | Node
+  //   | VElement
+  //   | PrimitiveChild;
   export type VanNode =
     | VanElement
-    | VanNode[]
-    | (() => VanNode)
+    | VanElement[]
+    | (() => VanElement | VanElement[])
     | null
     | undefined;
 
@@ -62,14 +72,12 @@ declare module "@vanjs/router" {
    *   return Router(); // or <Router /> for JSX
    * }
    */
-  // export const Router: JSX.Component<HTMLElement> & VanComponent<HTMLElement>;
-  // export function Router(props?: ComponentProps<HTMLElement>): HTMLElement;
-  // export function Router(
-  //   props?: JSX.IntrinsicElements["main"] & { children: null },
-  // ): HTMLElement;
   export const Router:
     & VanComponent<"main">
     & JSX.Component<"main">;
+  export const FileSystemRouter:
+    & VanComponent<"main">
+    & JSX.Component<"main">;
 
   // a.mjs
   /**
@@ -123,8 +131,13 @@ declare module "@vanjs/router" {
   export type RouteEntry = {
     path: string;
     component: Promise<ComponentModule>;
-    preload?: (params?: Record<string, string>) => void;
-    load?: (params?: Record<string, string>) => void;
+    params?: Record<string, string>;
+    preload?: (
+      params?: Record<string, string>,
+    ) => boolean | void | Promise<boolean | void>;
+    load?: (
+      params?: Record<string, string>,
+    ) => boolean | void | Promise<boolean | void>;
   };
 
   export type RouteProps = {
@@ -134,9 +147,16 @@ declare module "@vanjs/router" {
         | HTMLElementTagNameMap[unknown]
         | HTMLElementTagNameMap[unknown][])
       | VanComponent
-      | (() => ComponentModule);
-    preload?: (params?: Record<string, string>) => void;
-    load?: (params?: Record<string, string>) => void;
+      | ComponentFn
+      | (() => Promise<DynamicModule>);
+    //   | ComponentModule["component"];
+    // component: ComponentFn | (() => Promise<ComponentModule>);
+    preload?: (
+      params?: Record<string, string>,
+    ) => boolean | void | Promise<boolean | void>;
+    load?: (
+      params?: Record<string, string>,
+    ) => boolean | void | Promise<boolean | void>;
   };
   export const routes: RouteEntry[];
 
@@ -185,42 +205,68 @@ declare module "@vanjs/router" {
 
   /**
    * Merge the children of an Element or an array of elements with an optional array of children
-   * into the childen of a single HTMLFragmentElement element.
-   * @param  source
-   * @param  {...VanNode[]} children
+   * into the childen prperty of a simple object.
+   * @param source
+   * @param children
    */
   export const unwrap: (
     source:
       | VanNode
-      | IsoTagFunc
       | VanNode[]
-      | IsoTagFunc[]
-      | (() => IsoTagFunc | IsoTagFunc[] | VanNode | VanNode[]),
-    ...children: VanNode[]
-  ) => VanNode;
+      | VanComponent
+      | { children: VanNode[] }
+      | ComponentFn
+      | ReturnType<IsoTagFunc>
+      | ReturnType<IsoTagFunc>[]
+      | (() =>
+        | ReturnType<IsoTagFunc>
+        | ReturnType<IsoTagFunc>[]
+        | VanNode
+        | VanNode[]),
+    ...children: ChildDom[]
+  ) => { children: ChildDom[] };
+
+  export type JSXComponentFn = () => JSX.Element;
+  export type FragmentFn = () => ChildDom | ChildDom[];
+  export type ComponentFn = FragmentFn | VanComponent | JSXComponentFn;
 
   export type ComponentModule = {
-    component: VanComponent | JSX.Element;
-    route: Pick<RouteEntry, "load" | "preload">;
+    component: ComponentFn;
+    route?: Pick<RouteEntry, "load" | "preload">;
   };
 
   export type DynamicModule = {
-    Page: VanComponent | JSX.Element;
-    default?: VanComponent | JSX.Element;
+    Page: ComponentFn;
+    default?: ComponentFn;
     route?: Pick<RouteEntry, "load" | "preload">;
   };
 
   export type LazyComponent = Promise<DynamicModule>;
 
+  export type ImportFn = () => LazyComponent;
+
   /**
    * Registers a lazy component.
    * @param importFn
    */
-  export const lazy: (importFn: () => LazyComponent) => () => ComponentModule;
+  export const lazy: (importFn: ImportFn) => () => Promise<ComponentModule>;
 
   /**
    * Fixes the URL of a route.
    * @param url
    */
   export const fixRouteUrl: (url: string) => string;
+
+  /**
+   * Execute lifecycle methods preload and / or load
+   */
+  export const executeLifecycle: (
+    { route }: ComponentModule,
+    params?: Record<string, string> | undefined,
+  ) => Promise<boolean | void>;
+
+  /**
+   * Find a registered route that matches the given path
+   */
+  export const matchRoute: (path: string) => RouteEntry | null;
 }

package/router/helpers.mjs

@@ -1,12 +1,16 @@
 // import van from "vanjs-core";
-import setup from "../setup/index.mjs";
+import isServer from "../setup/isServer.mjs";
 import { routerState, setRouterState } from "./state.mjs";
 import { matchRoute } from "./routes.mjs";
 
+/** @typedef {typeof import("./types.d.ts").unwrap} Unwrap */
+/** @typedef {typeof import("./types.d.ts").navigate} Navigate */
 /** @typedef {import("./types.d.ts").Route} Route */
 /** @typedef {import("./types.d.ts").VanNode} VanNode */
 /** @typedef {import("./types.d.ts").ComponentModule} ComponentModule */
-/** @typedef {import('vanjs-core').TagFunc} TagFunc */
+/** @typedef {import("./types.d.ts").DynamicModule} DynamicModule */
+/** @typedef {import("./types.d.ts").ComponentFn} ComponentFn */
+/** @typedef {import("./types.d.ts").LazyComponent} LazyComponent */
 
 /**
  * Check if selected page is the current page;
@@ -19,22 +23,24 @@ export const isCurrentPage = (pageName) => {
 
 /**
  * Merge the children of an Element or an array of elements with an optional array of children
- * into the childen of a single HTMLFragmentElement element.
- * @param {Element | () => Element | Element[]} source
- * @param  {...Element[]} children
- * @returns {TagFunc<HTMLFragmentElement> | HTMLElement}
+ * into the childen prperty of a simple object.
+ * @type {Unwrap}
  */
 export const unwrap = (source, ...children) => {
   const layout = () => {
-    const pageChildren = Array.isArray(source?.children)
-      ? source.children
-      : typeof source === "function"
-      ? [...source()?.children || source()]
-      : typeof HTMLElement !== "undefined" && source instanceof HTMLElement
-      ? [...source.children]
-      : /* istanbul ignore next */ Array.isArray(source)
-      ? source
-      : [source];
+    /** @type {VanNode[]} */
+    const pageChildren =
+      source && typeof source === "object" && "children" in source &&
+        Array.isArray(source?.children)
+        ? source.children
+        : typeof source === "function"
+        // @ts-expect-error - this case is specific to VanJS components in SSR
+        ? [...source()?.children || source()]
+        : typeof HTMLElement !== "undefined" && source instanceof HTMLElement
+        ? [...source.children]
+        : /* istanbul ignore next */ Array.isArray(source)
+        ? source
+        : [source];
 
     // return van.tags.fragment(
     // ...(children || /* istanbul ignore next */ []),
@@ -52,16 +58,17 @@ export const unwrap = (source, ...children) => {
 
 /**
  * Check if component is a lazy component
- * @param {unknown} component
- * @returns {component is (() => Promise<VanNode | VanNode[]>)}
+ * @param {ComponentFn | (() => LazyComponent)} component
+ * @returns {component is (() => LazyComponent)}
  */
 export const isLazyComponent = (component) => {
   // Server: Check if it's an async function
-  if (setup.isServer) {
+  if (isServer && typeof component === "function") {
     return component.constructor.name.includes("AsyncFunction");
   }
 
   // Client: Check if it's designated as lazy
+  // @ts-expect-error - this property is optional and on purpose
   return component?.isLazy === true;
 };
 
@@ -69,7 +76,7 @@ export const isLazyComponent = (component) => {
  * Execute lifecycle methods preload and / or load
  * @param {ComponentModule} param0
  * @param {Record<string, string> | undefined} params
- * @returns
+ * @returns {Promise<boolean>}
  */
 export const executeLifecycle = async ({ route }, params) => {
   // istanbul ignore next
@@ -88,16 +95,13 @@ export const executeLifecycle = async ({ route }, params) => {
 
 /**
  * Client only navigation utility.
- * @param {string} path - The path to navigate to
- * @param {{ replace: boolean } | undefined} options - Navigation options
- * @param {boolean} options.replace - Whether to replace current history entry
- * @returns {void}
+ * @type {Navigate}
  */
 export const navigate = (path, options = {}) => {
   const { replace = false } = options;
 
   // istanbul ignore else
-  if (!setup.isServer) {
+  if (!isServer) {
     // Client-side navigation
     const url = new URL(path, globalThis.location.origin);
     const route = matchRoute(url.pathname);
@@ -121,9 +125,10 @@ export const navigate = (path, options = {}) => {
  * Extract route params
  * @param {string} pattern
  * @param {string} path
- * @returns {Record<string, string>}
+ * @returns {Record<string, string> | null}
  */
 export const extractParams = (pattern, path) => {
+  /** @type {Record<string, string>} */
   const params = {};
   const patternParts = pattern.split("/");
   const pathParts = path.split("/");
@@ -164,7 +169,7 @@ export const fixRouteUrl = (url) => {
  * @returns {void}
  */
 // export const reload = (forceFetch = false) => {
-//   if (!setup.isServer) {
+//   if (!isServer) {
 //     // Client-side reload
 //     if (forceFetch) {
 //       window.location.reload();
@@ -191,7 +196,7 @@ export const fixRouteUrl = (url) => {
 // export const redirect = (path, options = {}) => {
 //   const { status = 302, replace = true } = options;
 
-//   if (!setup.isServer) {
+//   if (!isServer) {
 //     // Client-side redirect
 //     navigate(path, { replace });
 //   } else {

package/router/lazy.mjs

@@ -1,25 +1,29 @@
-import setup from "../setup/index.mjs";
+import isServer from "../setup/isServer.mjs";
 import van from "vanjs-core";
 import { cache, getCached } from "./cache.mjs";
 
 /** @typedef {import('./types').VanNode} VanNode */
+/** @typedef {import('./types').DynamicModule} DynamicModule */
 /** @typedef {import('./types').ComponentModule} ComponentModule */
+/** @typedef {import('./types').ComponentFn} ComponentFn */
 
 /**
  * Registers a lazy component.
- * @param {Promise<VanNode>} importFn
- * @returns {ComponentModule | Promise<ComponentModule>}
+ * @type {typeof import("./types").lazy}
  */
 export const lazy = (importFn) => {
-  if (setup.isServer) {
+  if (isServer) {
     return async () => {
       const cached = getCached(importFn);
       /* istanbul ignore next */
       if (cached) {
         return cached;
       }
+
       const module = await importFn();
-      const component = module.Page || module.default;
+      /** @type {ComponentFn} */
+      const component = module?.default || module.Page;
+      /** @type {ComponentModule} */
       const result = { component, route: module.route };
 
       cache(importFn, result);
@@ -28,7 +32,9 @@ export const lazy = (importFn) => {
   }
 
   let initialized = false;
+  /** @type {import("vanjs-core").State<(ComponentModule["component"] | (() => string))>} */
   const component = van.state(() => "Loading..");
+  /** @type {import("vanjs-core").State<ComponentModule["route"]>} */
   const route = van.state({});
 
   const load = () => {
@@ -43,12 +49,16 @@ export const lazy = (importFn) => {
     }
 
     initialized = true;
-    importFn().then((module) => {
-      const comp = module.Page || module.default;
-      cache(importFn, { component: comp, route: module.route });
-      component.val = comp;
-      route.val = module.route;
-    });
+    importFn().then(
+      /** @param {DynamicModule} module */
+      (module) => {
+        /** @type {ComponentModule["component"]} */
+        const pageComponent = module?.default || module.Page;
+        cache(importFn, { component: pageComponent, route: module.route });
+        component.val = pageComponent;
+        route.val = module.route;
+      },
+    );
   };
 
   const lazyComponent = () => {
@@ -56,5 +66,6 @@ export const lazy = (importFn) => {
     return { component: component.val(), route: route.val };
   };
   lazyComponent.isLazy = true;
+  // @ts-expect-error - typescript cannot handle this isomorphically
   return lazyComponent;
 };

package/router/router.mjs

@@ -1,22 +1,14 @@
 import van from "vanjs-core";
-import setup from "../setup/index.mjs";
+import isServer from "../setup/isServer.mjs";
 import { routerState, setRouterState } from "./state.mjs";
 import { matchRoute } from "./routes.mjs";
 import { executeLifecycle, unwrap } from "./helpers.mjs";
 import { hydrate } from "../client/index.mjs";
-import { Head, initializeHeadTags } from "@vanjs/meta";
+import { Head, initializeHeadTags } from "../meta/index.mjs";
+
+import "virtual:@vanjs/routes";
 
 let isConnected = false;
-/** @param {Event & {target: globalThis}} e */
-// istanbul ignore next - cannot test
-const popHandler = (e) => {
-  const location = e.target.location;
-  const oldPath = routerState.pathname._oldVal;
-  // istanbul ignore next - cannot test
-  if (location.pathname !== oldPath) {
-    setRouterState(location.pathname, location.search);
-  }
-};
 
 export const Router = (initialProps = /* istanbul ignore next */ {}) => {
   const { div, main } = van.tags;
@@ -29,11 +21,11 @@ export const Router = (initialProps = /* istanbul ignore next */ {}) => {
   const mainLayout = () => {
     const route = matchRoute(routerState.pathname.val);
     /* istanbul ignore else */
-    if (!route) return van.add(wrapper, div("404 - Not Found"));
+    if (!route) return van.add(wrapper, div("No Route Found"));
 
     routerState.params.val = route.params || {};
     // Server-side or async component: use renderComponent
-    if (setup.isServer) {
+    if (isServer) {
       const renderComponent = async () => {
         try {
           const module = await route.component();
@@ -56,19 +48,30 @@ export const Router = (initialProps = /* istanbul ignore next */ {}) => {
 
     const root = document.querySelector("[data-root]");
     // istanbul ignore else - cannot test unmount
-    if (isConnected || !root) {
+    if (!isConnected || !root) {
       initializeHeadTags();
-      globalThis.addEventListener("popstate", popHandler);
-    } else {
-      globalThis.removeEventListener("popstate", popHandler);
+      globalThis.addEventListener(
+        "popstate",
+        /** @param {Event & {target: globalThis}} e */
+        // istanbul ignore next - cannot test
+        (e) => {
+          const location = e.target.location;
+          const oldPath = routerState.pathname._oldVal;
+          // istanbul ignore next - cannot test
+          if (location.pathname !== oldPath) {
+            setRouterState(location.pathname, location.search);
+          }
+        },
+      );
     }
 
     // Client-side lazy component, lifeCycle is already executed on the server
     // or when A component has been clicked in the client
     if (root) {
       // this case is when root is server side rendered
-      const module = route.component();
       const children = () => {
+        const module = route.component();
+        executeLifecycle(module, route.params);
         // istanbul ignore next - cannot test
         const cp = (Array.isArray(module) || module instanceof Element)
           ? module
@@ -79,9 +82,9 @@ export const Router = (initialProps = /* istanbul ignore next */ {}) => {
         const kids = () => cp ? Array.from(unwrap(cp).children) : [];
         const kudos = kids();
 
+        isConnected = true;
         // istanbul ignore else
         if (document.head) {
-          isConnected = true;
           van.hydrate(document.head, (head) => hydrate(head, Head()));
         }
 
@@ -97,7 +100,11 @@ export const Router = (initialProps = /* istanbul ignore next */ {}) => {
     });
 
     const children = van.derive(() => {
-      const md = csrRoute.val.component();
+      const route = csrRoute.val;
+      // istanbul ignore if - can only be tested in client
+      if (!route) return [div("No Route Found")];
+      const md = route.component();
+      executeLifecycle(md, route.params);
       // istanbul ignore next - cannot test all cases
       const cp = (Array.isArray(md) || md instanceof Element)
         ? md

package/router/routes.mjs

@@ -4,6 +4,8 @@ import { lazy } from "./lazy.mjs";
 
 /** @typedef {import("./types.d.ts").RouteEntry} RouteEntry */
 /** @typedef {import("./types.d.ts").RouteProps} RouteProps */
+/** @typedef {import("./types.d.ts").DynamicModule} DynamicModule */
+/** @typedef {import("./types.d.ts").ComponentModule} ComponentModule */
 
 /** @type {RouteEntry[]} */
 export const routes = [];
@@ -15,15 +17,17 @@ export const Route = (routeProps) => {
   const { path, component, preload, load, ...rest } = routeProps;
 
   // istanbul ignore next - no point testing this error
-  if (path === "/" && isLazyComponent(component)) {
-    throw new Error("Home component must not be a lazy component");
+  if (routes.some((r) => r.path === path)) {
+    console.error(`🍦 @vanjs/router: duplicated route for "${path}".`);
+    return;
   }
 
-  // If component has lifecycle methods but isn't lazy, make it lazy
-  if (!isLazyComponent(component) && path !== "/") {
+  // If component isn't lazy, make it lazy
+  if (!isLazyComponent(component)) {
+    /** @type {() => Promise<ComponentModule>} */
     const wrappedComponent = lazy(() =>
       Promise.resolve({
-        default: component,
+        Page: component,
         route: { preload, load },
       })
     );
@@ -32,25 +36,50 @@ export const Route = (routeProps) => {
   }
 
   // Otherwise keep original component
+  // @ts-expect-error - RouteProps and RouteEntry are now equivalent
   routes.push(routeProps);
 };
 
 /**
  * Find a registered route that matches the given path
- * @param {string} path
+ * @param {string} initialPath
  * @returns {RouteEntry | null}
  */
-export const matchRoute = (path) => {
-  const exactMatch = routes.find((r) => r.path === path);
-  if (exactMatch) return { ...exactMatch, params: {} };
+export const matchRoute = (initialPath) => {
+  const path = initialPath !== "/" && initialPath.endsWith("/")
+    ? initialPath.slice(0, -1)
+    : initialPath;
+
+  // First try exact match (excluding wildcards)
+  let foundMatch = routes.find((r) => r.path === path && !r.path.includes("*"));
+
+  // Then try nested wildcard match if no exact match found
+  if (!foundMatch) {
+    // Build the path for potential nested wildcard, e.g. /admin/* for /admin/articles
+    const nestedPath = path.split("/").slice(0, -1).join("/") + "/*";
+    foundMatch = routes.find((r) => r.path === nestedPath);
+  }
 
+  // If we found either an exact or nested wildcard match, return it with params
+  if (foundMatch) {
+    return {
+      ...foundMatch,
+      params: extractParams(foundMatch.path, path) ?? /* istanbul ignore next */
+        undefined,
+    };
+  }
+
+  // Try parameterized routes (like /users/:id)
   for (const route of routes) {
+    // Skip the global catch-all
     if (route.path === "*") continue;
     const params = extractParams(route.path, path);
+
     if (params) {
       return { ...route, params };
     }
   }
 
+  // Finally, fallback to global catch-all route
   return routes.find((r) => r.path === "*") || null;
 };

package/router/state.mjs

@@ -1,10 +1,10 @@
 // router/state.js
 import van from "vanjs-core";
-import setup from "../setup/index.mjs";
+import isServer from "../setup/isServer.mjs";
 import { fixRouteUrl } from "./helpers.mjs";
 
-const initialPath = !setup.isServer ? globalThis.location.pathname : "/";
-const initialSearch = !setup.isServer ? globalThis.location.search : "";
+const initialPath = !isServer ? globalThis.location.pathname : "/";
+const initialSearch = !isServer ? globalThis.location.search : "";
 
 /**
  * @type {typeof import("./types.d.ts").routerState}