vite-plugin-vanjs 0.0.3 → 0.0.4

package/router/helpers.mjs

@@ -0,0 +1,198 @@
+import setup from "@vanjs/setup";
+import van from "vanjs-core";
+import { routerState, setRouterState } from "./state";
+import { matchRoute } from "./routes";
+
+/** @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 */
+
+/**
+ * Check if selected page is the current page;
+ * @param {string} pageName
+ * @returns {boolean}
+ */
+export const isCurrentPage = (pageName) => {
+  return routerState.pathname.val === 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}
+ */
+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]
+      : Array.isArray(source)
+      ? source
+      : [source];
+
+    return van.tags.fragment(
+      ...(children || /* istanbul ignore next */ []),
+      ...pageChildren,
+    );
+  };
+  return layout();
+};
+
+/**
+ * Check if component is a lazy component
+ * @param {unknown} component
+ * @returns {component is (() => Promise<VanNode | VanNode[]>)}
+ */
+export const isLazyComponent = (component) => {
+  // Server: Check if it's an async function
+  if (setup.isServer) {
+    return component.constructor.name.includes("AsyncFunction");
+  }
+
+  // Client: Check if it's designated as lazy
+  return component?.isLazy === true;
+};
+
+/**
+ * Execute lifecycle methods preload and / or load
+ * @param {ComponentModule} param0
+ * @param {Record<string, string> | undefined} params
+ * @returns
+ */
+export const executeLifecycle = async ({ route }, params) => {
+  // istanbul ignore next
+  if (!route) return true;
+  try {
+    if (route?.preload) await route.preload(params);
+    if (route?.load) await route.load(params);
+    return true;
+  } catch (error) {
+    // istanbul ignore next
+    console.error("Lifecycle execution error:", error);
+    // istanbul ignore next
+    return false;
+  }
+};
+
+/**
+ * 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}
+ */
+export const navigate = (path, options = {}) => {
+  const { replace = false } = options;
+
+  // istanbul ignore else
+  if (!setup.isServer) {
+    // Client-side navigation
+    const url = new URL(path, globalThis.location.origin);
+    const route = matchRoute(url.pathname);
+
+    // Update history
+    if (replace) {
+      globalThis.history.replaceState({}, "", path);
+    } else {
+      globalThis.history.pushState({}, "", path);
+    }
+
+    // Update router state
+    setRouterState(url.pathname, url.search, route?.params);
+  } else {
+    // Server-side navigation - throw error
+    console.error("Direct navigation is not supported on server");
+  }
+};
+
+/**
+ * Extract route params
+ * @param {string} pattern
+ * @param {string} path
+ * @returns {Record<string, string>}
+ */
+export const extractParams = (pattern, path) => {
+  const params = {};
+  const patternParts = pattern.split("/");
+  const pathParts = path.split("/");
+
+  if (patternParts.length !== pathParts.length) return null;
+
+  for (let i = 0; i < patternParts.length; i++) {
+    const patternPart = patternParts[i];
+    const pathPart = pathParts[i];
+
+    if (patternPart.startsWith(":")) {
+      params[patternPart.slice(1)] = pathPart;
+    } else if (patternPart !== pathPart) {
+      return null;
+    }
+  }
+
+  return params;
+};
+
+/**
+ * Client only reload utility
+ * WORK IN PROGRESS
+ * @param {boolean} forceFetch - Force fetch from server
+ * @returns {void}
+ */
+// export const reload = (forceFetch = false) => {
+//   if (!setup.isServer) {
+//     // Client-side reload
+//     if (forceFetch) {
+//       window.location.reload();
+//     } else {
+//       // Soft reload - just update router state
+//       const { pathname, search } = window.location;
+//       setRouterState(pathname, search);
+//     }
+//   } else {
+//     // Server-side reload - throw error
+//     console.error("Reload is not supported on server");
+//   }
+// };
+
+/**
+ * Isomorphic redirect utility
+ * WORK IN PROGRESS
+ * @param {string} path - The path to redirect to
+ * @param {object} options - Redirect options
+ * @param {number} options.status - HTTP status code (server-side only)
+ * @param {boolean} options.replace - Whether to replace current history entry (client-side only)
+ * @returns {void}
+ */
+// export const redirect = (path, options = {}) => {
+//   const { status = 302, replace = true } = options;
+
+//   if (!setup.isServer) {
+//     // Client-side redirect
+//     navigate(path, { replace });
+//   } else {
+//     // Server-side redirect
+//     const error = new Error(`Redirect to ${path}`);
+//     error.status = status;
+//     error.location = path;
+//     throw error;
+//   }
+// };
+
+// Utility to handle server-side redirects in your server entry point
+// export const handleServerRedirect = (error, res) => {
+//   if (error.location && error.status) {
+//     res.writeHead(error.status, {
+//       Location: error.location,
+//       "Content-Type": "text/plain",
+//     });
+//     res.end(`Redirecting to ${error.location}...`);
+//     return true;
+//   }
+//   return false;
+// };

package/router/index.mjs

@@ -0,0 +1,6 @@
+export * from "./router";
+export * from "./routes";
+export * from "./a";
+export * from "./state";
+export * from "./lazy";
+export * from "./helpers";

package/router/lazy.mjs

@@ -0,0 +1,60 @@
+import setup from "@vanjs/setup";
+import van from "vanjs-core";
+import { cache, getCached } from "./cache";
+
+/** @typedef {import('./types').VanNode} VanNode */
+/** @typedef {import('./types').ComponentModule} ComponentModule */
+
+/**
+ * Registers a lazy component.
+ * @param {Promise<VanNode>} importFn
+ * @returns {ComponentModule | Promise<ComponentModule>}
+ */
+export const lazy = (importFn) => {
+  if (setup.isServer) {
+    return async () => {
+      const cached = getCached(importFn);
+      /* istanbul ignore next */
+      if (cached) {
+        return cached;
+      }
+      const module = await importFn();
+      const component = module.Page || module.default;
+      const result = { component, route: module.route };
+
+      cache(importFn, result);
+      return result;
+    };
+  }
+
+  let initialized = false;
+  const component = van.state(() => "");
+  const route = van.state({});
+
+  const load = () => {
+    if (initialized) return;
+
+    const cached = getCached(importFn);
+    /* istanbul ignore next */
+    if (cached) {
+      component.val = cached.component;
+      route.val = cached.route;
+      return;
+    }
+
+    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;
+    });
+  };
+
+  const lazyComponent = () => {
+    load();
+    return { component: component.val(), route: route.val };
+  };
+  lazyComponent.isLazy = true;
+  return lazyComponent;
+};

package/router/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "router",
+  "main": "./index.mjs",
+  "module": "./index.mjs",
+  "types": "./types.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./types.d.ts",
+      "import": "./index.mjs"
+    }
+  },
+  "peerDependencies": {
+    "vite-plugin-vanjs": "*",
+    "vanjs-core": "*",
+    "vanjs-ext": "*"
+  },
+  "sideEffects": false
+}

package/router/router.mjs

@@ -0,0 +1,43 @@
+import van from "vanjs-core";
+import setup from "@vanjs/setup";
+import { routerState } from "./state";
+import { matchRoute } from "./routes";
+import { executeLifecycle, unwrap } from "./helpers";
+
+export const Router = () => {
+  const { div } = van.tags;
+  // const meta = defaultMeta();
+
+  const mainLayout = () => {
+    const route = matchRoute(routerState.pathname.val);
+    /* istanbul ignore else */
+    if (!route) return div("404 - Not Found");
+
+    routerState.params.val = route.params || {};
+    // Server-side or async component: use renderComponent
+    if (setup.isServer) {
+      const renderComponent = async () => {
+        try {
+          const module = await route.component();
+          const component = module.component();
+          await executeLifecycle(module, route.params);
+          return unwrap(component).children;
+        } catch (error) {
+          /* istanbul ignore next */
+          console.error("Router error:", error);
+          /* istanbul ignore next */
+          return div("Error loading page");
+        }
+      };
+
+      return renderComponent();
+    }
+
+    const module = route.component();
+    // Client-side lazy component, lifeCycle is already executed on the server
+    // or when A component has been clicked in the client
+    return unwrap(module.component);
+  };
+
+  return mainLayout();
+};

package/router/routes.mjs

@@ -0,0 +1,51 @@
+// router/routes.mjs
+import { extractParams, isLazyComponent } from "./helpers";
+import { lazy } from "./lazy";
+
+/** @typedef {import("./types.d.ts").RouteEntry} RouteEntry */
+/** @typedef {import("./types.d.ts").RouteProps} RouteProps */
+
+/** @type {RouteEntry[]} */
+export const routes = [];
+
+/**
+ * @param {RouteProps} routeProps
+ */
+export const Route = (routeProps) => {
+  const { component, preload, load, ...rest } = routeProps;
+
+  // If component has lifecycle methods but isn't lazy, make it lazy
+  if (!isLazyComponent(component)) {
+    const wrappedComponent = lazy(() =>
+      Promise.resolve({
+        default: component,
+        route: { preload, load },
+      })
+    );
+    routes.push({ ...rest, component: wrappedComponent });
+    return;
+  }
+
+  // Otherwise keep original component
+  routes.push(routeProps);
+};
+
+/**
+ * Find a registered route that matches the given path
+ * @param {string} path
+ * @returns {RouteEntry | null}
+ */
+export const matchRoute = (path) => {
+  const exactMatch = routes.find((r) => r.path === path);
+  if (exactMatch) return { ...exactMatch, params: {} };
+
+  for (const route of routes) {
+    if (route.path === "*") continue;
+    const params = extractParams(route.path, path);
+    if (params) {
+      return { ...route, params };
+    }
+  }
+
+  return routes.find((r) => r.path === "*") || null;
+};

package/router/state.mjs

@@ -0,0 +1,27 @@
+// router/state.js
+import van from "vanjs-core";
+import setup from "../setup/index.mjs";
+
+const initialPath = !setup.isServer ? globalThis.location.pathname : "/";
+const initialSearch = !setup.isServer ? globalThis.location.search : "";
+
+/**
+ * @type {typeof import("./types.d.ts").routerState}
+ */
+export const routerState = {
+  pathname: van.state(initialPath),
+  searchParams: van.state(new URLSearchParams(initialSearch)),
+  params: van.state({}),
+};
+
+/**
+ * @type {typeof import("./types.d.ts").setRouterState}
+ */
+export const setRouterState = (path, search = undefined, params) => {
+  const [pathname, searchParams] = path.split("?");
+  routerState.pathname.val = pathname;
+  routerState.searchParams.val = new URLSearchParams(
+    search || searchParams || "",
+  );
+  routerState.params.val = params || {};
+};

package/router/types.d.ts

@@ -0,0 +1,156 @@
+/// <reference path="global.d.ts" />
+import type { Element } from "mini-van-plate/van-plate";
+import van from "vanjs-core";
+import type { PropsWithKnownKeys } from "vanjs-core";
+
+type VanElement = Element & { children: VanNode[] };
+type VanNode = SVGElement | HTMLElement | VanElement;
+
+// router.mjs
+/**
+ * A virtual component that renders the current route
+ * in your VanJS application. It must be used in your main component.
+ *
+ * @example
+ * import { Router } from '@vanjs/router';
+ *
+ * export const App = () => {
+ *   return Router(); // or <Router /> for JSX
+ * }
+ */
+export const Router: () => VanNode | VanNode[];
+
+// a.mjs
+/**
+ * A virtual component that creates an anchor element
+ * that navigates to the specified href when clicked.
+ *
+ * @example
+ * import { A } from '@vanjs/router';
+ * import van from 'vanjs-core';
+ *
+ * export const Navigation = () => {
+ *   const { nav } = van.tags
+ *   return nav(
+ *     A({ href="/" }, "Home"), // or <A href="/">Home</A> with JSX
+ *     A({ href="/about" }, "About"), // or <A href="/about">About</A> with JSX
+ *     // ...other children
+ *   );
+ * }
+ */
+export const A: (
+  props: PropsWithKnownKeys<HTMLAnchorProps>,
+  ...children: (Element | Node | string)[]
+) => HTMLAnchorElement;
+
+// helpers.mjs
+/**
+ * Navigates to the specified href in the client and sets the router state.
+ * Keep in mind that the router handles the search params and hash.
+ *
+ * @param href the URL to navigate to
+ * @param options when true, will replace the current history entry
+ */
+export const navigate: (href: string, options?: { replace?: boolean }) => void;
+
+/**
+ * A client only helper function that reloads the current page.
+ */
+export const reload: () => void;
+
+/**
+ * A helper function that redirects the user to the specified href.
+ * When called in the server, it will return a function that will redirect the user
+ * to the specified href when called.
+ * @param {string | undefined} href the URL to redirect to
+ */
+export const redirect: (href?: string) => void | (() => void);
+
+export type VanComponent = () => VanNode | VanNode[];
+
+// routes.mjs
+export type RouteEntry = {
+  path: string;
+  component: Promise<ComponentModule>;
+  preload?: (params?: Record<string, string>) => void;
+  load?: (params?: Record<string, string>) => void;
+};
+
+export type RouteProps = {
+  path: string;
+  component: VanComponent | (() => ComponentModule);
+  preload?: (params?: Record<string, string>) => void;
+  load?: (params?: Record<string, string>) => void;
+};
+export const routes: RouteEntry[];
+
+/**
+ * Registers a new route in the router state.
+ * @param route the route to register
+ *
+ * @example
+ * import { Route, lazy } from '@vanjs/router';
+ * import Home from './pages/Home';
+ * import NotFound from './pages/NotFound';
+ *
+ * Route({ path: '/', component: Home });
+ * Route({ path: '/about', component: lazy(() => import("./pages/About.ts")) });
+ * Route({ path: '*', component: NotFound });
+ */
+export const Route: (route: RouteProps) => void;
+
+// state.mjs
+export type RouterState = {
+  pathname: string;
+  searchParams: URLSearchParams;
+  params?: Record<string, string>;
+};
+/**
+ * A reactive object that holds the current router state.
+ * This state is maintained by both server and client.
+ */
+export const routerState: {
+  pathname: van.state<RouterState.pathname>;
+  searchParams: van.state<RouterState.searchParams>;
+  params?: van.state<RouterState.params>;
+};
+
+/**
+ * Sets the router state to the specified href.
+ * @param href the URL to navigate to
+ * @param search the search string
+ * @param params the route params object
+ */
+export const setRouterState: (
+  href: string,
+  search?: string,
+  params?: Record<string, string>,
+) => void;
+
+/**
+ * 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 children
+ */
+export const unwrap: (
+  source: VanNode | VanNode[] | (() => VanNode | VanNode[]),
+  ...children: VanNode[]
+) => VanNode;
+
+export type ComponentModule = {
+  component: VanComponent;
+  route: Pick<RouteEntry, "load" | "preload">;
+};
+
+export type DynamicModule = {
+  Page: VanComponent;
+  default?: VanComponent;
+  route?: Pick<RouteEntry, "load" | "preload">;
+};
+
+export type LazyComponent =
+  | Promise<DynamicModule>
+  | (() => Promise<DynamicModule>);
+
+export const lazy: (importFn: () => LazyComponent) => () => ComponentModule;

package/server/global.d.ts

@@ -0,0 +1,49 @@
+declare module "@vanjs/server" {
+  import type { PropsWithKnownKeys } from "vanjs-core";
+  import type { SupportedTags } from "@vanjs/meta";
+  import type { JSX } from "@vanjs/jsx";
+  import type {
+    Element as VanElement,
+    TagFunc,
+  } from "mini-van-plate/van-plate";
+
+  /**
+   * A function that takes a list of files and a manifest and returns a string
+   * representing the HTML markup for preload links.
+   * @param files the list of files
+   * @param manifest the vite manifest
+   * @returns HTML string
+   */
+  export const renderPreloadLinks: (
+    files: string[],
+    manifest: Record<string, string[]>,
+  ) => string;
+
+  type ValidVanNode =
+    | boolean
+    | number
+    | string
+    | VanElement
+    | TagFunc;
+
+  type VanComponent = () =>
+    | ValidVanNode
+    | ValidVanNode[]
+    | SupportedTags
+    | SupportedTags[];
+  export type Source =
+    | JSX.Element
+    | VanComponent
+    | (() => VanComponent)
+    | Promise<ValidVanNode>
+    | ValidVanNode
+    | undefined;
+
+  /**
+   * A function that takes a multitude of source types and returns a string
+   * representing the HTML output.
+   * @param source the source
+   * @returns HTML string
+   */
+  export const renderToString: (source: Source) => Promise<string>;
+}