@inflector/keeno-router 0.1.1 → 0.2.0

package/dist/index.d.ts

@@ -13,7 +13,38 @@ export interface RouteDefinition {
     path: string;
     /** Receives `RouteProps`. Typed loosely so components can declare their own params type. */
     component: Component<any>;
+    /**
+     * Layouts around the component, outermost first. Each receives `params` and `children`. A layout
+     * is kept while the routes navigated between share it at the same depth.
+     */
+    layouts?: Component<any>[];
+    /**
+     * Pages for errors thrown while the component renders, by HTTP status (`httpError(404)`, other
+     * errors are 500). Each receives `ErrorPageProps` and renders inside the route's layouts.
+     */
+    errors?: Record<number, Component<any>>;
+}
+/** Props passed to a layout. */
+export interface LayoutProps extends RouteProps {
+    children: Children;
+}
+/** Props passed to an error page (`_404.kn`, `_500.kn`, ...). */
+export interface ErrorPageProps extends RouteProps {
+    status: number;
+    /** What was thrown: an `HttpError` for `httpError()`, anything else for a 500. */
+    error: unknown;
+    /** Render the page again. */
+    reset: () => void;
 }
+/** An error carrying an HTTP status: throw it from a page to show that status's error page. */
+export declare class HttpError extends Error {
+    readonly status: number;
+    constructor(status: number, message?: string);
+}
+/** `throw httpError(403)` renders the route's 403 page (`_403.kn`). */
+export declare function httpError(status: number, message?: string): HttpError;
+/** The HTTP status of a thrown value: its numeric `status`, else 500. */
+export declare function errorStatus(error: unknown): number;
 /** The current route. Its fields are reactive: reading them in a template or `update` tracks them. */
 export interface Route {
     /** Path without the router's `base`, e.g. `/users/1`. */
@@ -79,3 +110,26 @@ export interface LinkProps {
  * while active. The scoped styles of the component that renders it apply to its `<a>`.
  */
 export declare function Link(props: LinkProps): unknown;
+/** A page module: loaded (`{ default }`) or a loader (`() => import('./page.kn')`). */
+export type PageModule = {
+    default: Component<any>;
+} | (() => Promise<{
+    default: Component<any>;
+}>);
+/**
+ * Routes from a directory of page files, as `import.meta.glob('/src/pages/**\/*.kn')` returns it
+ * (keys starting with `dir`):
+ *
+ * - `index.kn` is the directory's path, `about.kn` is `/about`, `[id].kn` is `/:id`.
+ * - `_layout.kn` wraps every page of its directory and the ones below it.
+ * - `_all.kn` matches every path below its directory that no other page does (`params['*']`).
+ * - `_404.kn` renders for paths below its directory that match nothing, and `_500.kn`, `_403.kn`…
+ *   for errors with that status thrown by a page (`throw httpError(403)`; other errors are 500).
+ * - Other files starting with `_` are left out, so pages can keep their own components next to them.
+ */
+export declare function pageRoutes(files: Record<string, PageModule>, dir?: string): RouteDefinition[];
+/**
+ * Load the page that matches `url` (an app path or full URL), if it loads on demand. Await it
+ * before `renderToString` or `hydrate`, so the page renders in the first pass.
+ */
+export declare function preloadRoute(routes: RouteDefinition[], url: string): Promise<void>;

package/dist/index.js

@@ -1,6 +1,22 @@
 // ../../../../../../../tmp/keeno-build/_inflector_keeno-router/src/index.ts
-import { State, createContext, derived, inject, provide, untrack } from "@inflector/keeno";
+import { ErrorBoundary, State, createContext, derived, inject, lazy, provide, untrack } from "@inflector/keeno";
 import { attr, callerScope, createComponent, insert, on, template } from "@inflector/keeno/internal";
+
+class HttpError extends Error {
+  status;
+  constructor(status, message) {
+    super(message ?? `HTTP ${status}`);
+    this.status = status;
+    this.name = "HttpError";
+  }
+}
+function httpError(status, message) {
+  return new HttpError(status, message);
+}
+function errorStatus(error) {
+  const status = error?.status;
+  return typeof status === "number" && status >= 100 && status <= 599 ? status : 500;
+}
 var hasWindow = typeof window !== "undefined" && typeof location !== "undefined";
 function readLocation() {
   if (!hasWindow)
@@ -227,15 +243,59 @@ function Router(props) {
   };
   provide(RouteContext, route);
   provide(BaseContext, routerBase);
-  return () => {
+  const withParams = (extra) => Object.defineProperty(extra, "params", { get: () => info.get().params, enumerable: true });
+  const chain = derived(() => {
     const r = matched.get();
-    if (!r)
-      return props.fallback ? untrack(props.fallback) : null;
-    return untrack(() => createComponent(r.component, {
-      get params() {
-        return info.get().params;
+    return r ? [...r.layouts ?? [], r] : [];
+  });
+  const depth = untrack(() => Math.max(1, ...props.routes.map((r) => (r.layouts?.length ?? 0) + 1)));
+  const levels = [];
+  for (let i = 0;i < depth; i++) {
+    const entry = derived(() => chain.get()[i]);
+    levels.push(() => {
+      const e = entry.get();
+      if (!e)
+        return null;
+      if (typeof e === "function")
+        return untrack(() => createComponent(e, withParams({ children: levels[i + 1] })));
+      return untrack(() => renderPage(e));
+    });
+  }
+  let resetError = null;
+  derived(() => info.get().path).onUpdate(() => {
+    const reset = resetError;
+    resetError = null;
+    reset?.();
+  });
+  const renderPage = (r) => {
+    const page = () => createComponent(r.component, withParams({}));
+    const errors = r.errors;
+    if (!errors || !Object.keys(errors).length)
+      return page();
+    return createComponent(ErrorBoundary, {
+      children: page,
+      fallback: (error, reset) => {
+        const status = errorStatus(error);
+        const ErrorPage = errors[status];
+        if (!ErrorPage)
+          throw error;
+        resetError = reset;
+        return createComponent(ErrorPage, withParams({
+          status,
+          error,
+          reset: () => {
+            resetError = null;
+            reset();
+          }
+        }));
       }
-    }));
+    });
+  };
+  const found = derived(() => !!matched.get());
+  return () => {
+    if (!found.get())
+      return props.fallback ? untrack(props.fallback) : null;
+    return levels[0]();
   };
 }
 function useRoute() {
@@ -268,13 +328,103 @@ function Link(props) {
   insert(a, () => props.children?.());
   return a;
 }
+var ERROR_FILE = /^_([1-5]\d\d)$/;
+function fileSegment(name) {
+  const m = /^\[(\.\.\.)?([^\]]+)\]$/.exec(name);
+  return m ? (m[1] ? "*" : ":") + m[2] : name;
+}
+function rank(seg) {
+  if (seg === undefined)
+    return 1;
+  if (seg.startsWith("*"))
+    return 0;
+  return seg.startsWith(":") ? 2 : 3;
+}
+function compareRoutes(a, b) {
+  const sa = a.split("/").filter(Boolean);
+  const sb = b.split("/").filter(Boolean);
+  for (let i = 0;i < Math.max(sa.length, sb.length); i++) {
+    const d = rank(sb[i]) - rank(sa[i]);
+    if (d)
+      return d;
+  }
+  return 0;
+}
+function notFound() {
+  throw new HttpError(404, "Not found");
+}
+function pageRoutes(files, dir = "") {
+  const prefix = dir.replace(/\/+$/, "") + "/";
+  const dirs = new Map;
+  const getDir = (key) => {
+    let d = dirs.get(key);
+    if (!d)
+      dirs.set(key, d = { path: key ? key.split("/").map(fileSegment) : [], errors: {} });
+    return d;
+  };
+  const pages = [];
+  const component = (m) => typeof m === "function" ? lazy(m) : m.default;
+  for (const file of Object.keys(files).sort()) {
+    if (!file.startsWith(prefix) || !file.endsWith(".kn"))
+      continue;
+    const parts = file.slice(prefix.length, -".kn".length).split("/");
+    const name = parts.pop();
+    if (parts.some((p) => p.startsWith("_")))
+      continue;
+    const key = parts.join("/");
+    const d = getDir(key);
+    const mod = files[file];
+    const error = ERROR_FILE.exec(name);
+    if (name === "_layout")
+      d.layout = component(mod);
+    else if (error)
+      d.errors[+error[1]] = component(mod);
+    else if (name === "_all")
+      pages.push({ dir: key, path: [...d.path, "*"], component: component(mod) });
+    else if (name === "index")
+      pages.push({ dir: key, path: d.path, component: component(mod) });
+    else if (!name.startsWith("_"))
+      pages.push({ dir: key, path: [...d.path, fileSegment(name)], component: component(mod) });
+  }
+  const ancestors = (key) => {
+    const parts = key ? key.split("/") : [];
+    return [getDir(""), ...parts.map((_, i) => getDir(parts.slice(0, i + 1).join("/")))];
+  };
+  const scope = (key) => {
+    const chain = ancestors(key);
+    return {
+      layouts: chain.flatMap((d) => d.layout ? [d.layout] : []),
+      errors: Object.assign({}, ...chain.map((d) => d.errors))
+    };
+  };
+  const routes = pages.map((p) => ({
+    path: "/" + p.path.join("/"),
+    component: p.component,
+    ...scope(p.dir)
+  }));
+  for (const [key, d] of [...dirs]) {
+    if (d.errors[404])
+      routes.push({ path: "/" + [...d.path, "*"].join("/"), component: notFound, fallback: true, ...scope(key) });
+  }
+  return routes.map((r, i) => ({ r, i })).sort((a, b) => compareRoutes(a.r.path, b.r.path) || Number(!!a.r.fallback) - Number(!!b.r.fallback) || a.i - b.i).map(({ r: { fallback, ...r } }) => r);
+}
+async function preloadRoute(routes, url) {
+  const path = parseUrl(url).pathname;
+  const route = routes.find((r) => matchPath(r, path));
+  await route?.component?.preload?.();
+}
 export {
+  HttpError,
   Link,
   Router,
+  errorStatus,
   href,
+  httpError,
   isActive,
   link,
   matchPath,
   navigate,
+  pageRoutes,
+  preloadRoute,
   useRoute
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inflector/keeno-router",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Client-side router for Keeno (.kn) apps",
   "license": "MIT",
   "repository": {
@@ -39,10 +39,10 @@
     "prepack": "bun run build"
   },
   "peerDependencies": {
-    "@inflector/keeno": ">=0.3.0 <1.0.0"
+    "@inflector/keeno": ">=0.4.0 <1.0.0"
   },
   "devDependencies": {
-    "@inflector/keeno": "0.3.0"
+    "@inflector/keeno": "0.4.0"
   },
   "publishConfig": {
     "access": "public"