@inflector/keeno-router 0.1.1 → 0.3.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`. */
@@ -34,6 +65,11 @@ export interface NavigateOptions {
     state?: unknown;
     /** Scroll to the top after navigating (default true, unless the URL has a hash). */
     scroll?: boolean;
+    /**
+     * Animate the change with the View Transitions API, where the browser supports it (default:
+     * the `viewTransition` prop of `<Router>`). The new page renders inside the transition.
+     */
+    transition?: boolean;
 }
 /** Go to an app path (`/users/1`, prefixed with `base`) or a relative URL (`?tab=2`). */
 export declare function navigate(to: string, options?: NavigateOptions): void;
@@ -54,6 +90,11 @@ export interface RouterProps {
     url?: string;
     /** Rendered when no route matches. */
     fallback?: () => unknown;
+    /**
+     * Animate navigations (links, `navigate()`, back and forward) with the View Transitions API,
+     * where the browser supports it. A navigation can opt out with `transition: false`.
+     */
+    viewTransition?: boolean;
 }
 /**
  * Render the component of the first route matching the URL. The component is kept when only
@@ -67,6 +108,8 @@ export interface LinkProps {
     href: string;
     /** Replace the current history entry. */
     replace?: boolean;
+    /** Animate the navigation with the View Transitions API (default: `<Router viewTransition>`). */
+    transition?: boolean;
     /** Class added while the link's path is active (default `active`). */
     activeClass?: string;
     /** Only active on exactly this path, not below it. */
@@ -79,3 +122,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, flush, 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)
@@ -42,6 +58,21 @@ function restoreScroll(l) {
   else
     setTimeout(run, 0);
 }
+var transitionsDefault = false;
+function withTransition(enabled, update) {
+  const start = enabled && hasWindow ? document.startViewTransition : undefined;
+  if (typeof start !== "function")
+    return update();
+  start.call(document, () => {
+    update();
+    flush();
+  });
+}
+function scrollTo(x, y) {
+  try {
+    window.scrollTo(x, y);
+  } catch {}
+}
 function sync() {
   if (!hasWindow)
     return;
@@ -52,6 +83,18 @@ function sync() {
   window.addEventListener("popstate", () => {
     saveScroll(current.peek());
     const next = readLocation();
+    if (transitionsDefault && typeof document.startViewTransition === "function") {
+      withTransition(true, () => {
+        current.set(next);
+        flush();
+        const saved = scrollPositions.get(locKey(next));
+        if (!saved && next.hash)
+          scrollToHash(next.hash);
+        else
+          scrollTo(saved?.[0] ?? 0, saved?.[1] ?? 0);
+      });
+      return;
+    }
     current.set(next);
     restoreScroll(next);
   });
@@ -106,16 +149,15 @@ function navigate(to, options = {}) {
   else
     history.pushState(options.state ?? null, "", url);
   window.dispatchEvent(new CustomEvent("keeno:navigate", { detail: { url: url.href, state: options.state ?? null } }));
-  current.set(readLocation());
-  if (options.scroll === false)
-    return;
-  if (url.hash)
-    scrollToHash(url.hash);
-  else if (typeof window.scrollTo === "function") {
-    try {
-      window.scrollTo(0, 0);
-    } catch {}
-  }
+  withTransition(options.transition ?? transitionsDefault, () => {
+    current.set(readLocation());
+    if (options.scroll === false)
+      return;
+    if (url.hash)
+      scrollToHash(url.hash);
+    else if (typeof window.scrollTo === "function")
+      scrollTo(0, 0);
+  });
 }
 function isExternalClick(e, a) {
   if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey)
@@ -133,7 +175,10 @@ function link(e) {
   if (!underBase(url.pathname, base.peek()))
     return;
   e.preventDefault();
-  navigate(stripBase(url.pathname, base.peek()) + url.search + url.hash, { replace: a.hasAttribute("data-replace") });
+  navigate(stripBase(url.pathname, base.peek()) + url.search + url.hash, {
+    replace: a.hasAttribute("data-replace"),
+    transition: a.hasAttribute("data-transition") ? a.getAttribute("data-transition") !== "false" : undefined
+  });
 }
 var compiled = new WeakMap;
 function compile(route) {
@@ -192,6 +237,7 @@ function Router(props) {
   const loc = url != null ? new State(parseUrl(url)) : current;
   if (url == null) {
     base.set(routerBase);
+    transitionsDefault = !!untrack(() => props.viewTransition);
     sync();
   }
   const outside = (l) => !underBase(l.pathname, routerBase);
@@ -227,15 +273,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() {
@@ -263,18 +353,108 @@ function Link(props) {
     if (isExternalClick(e, a))
       return;
     e.preventDefault();
-    navigate(props.href, { replace: props.replace });
+    navigate(props.href, { replace: props.replace, transition: props.transition });
   });
   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.3.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.5.0 <1.0.0"
   },
   "devDependencies": {
-    "@inflector/keeno": "0.3.0"
+    "@inflector/keeno": "0.5.0"
   },
   "publishConfig": {
     "access": "public"