@inflector/keeno-router 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iliesw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,24 @@
-# Temporary Holding Version
+# @inflector/keeno-router
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Client-side router for [Keeno](https://github.com/iliesw/Keeno): `<Router>`, `<Link>`, `navigate()`, `useRoute()` and the `link` click handler. It also supports a base path, lazy routes and server rendering.
+
+```bash
+bun add @inflector/keeno-router
+```
+
+```html
+<script lang="ts">
+  import { Link, Router } from '@inflector/keeno-router'
+  import Home from './Home.kn'
+  import User from './User.kn'
+  const routes = [
+    { path: '/', component: Home },
+    { path: '/users/:id', component: User },
+  ]
+</script>
+
+<Link href="/users/1">Ada</Link>
+<Router routes={routes} />
+```
+
+See [Routing](https://github.com/iliesw/Keeno/blob/main/docs/routing.md). MIT license.

package/dist/index.d.ts

@@ -0,0 +1,81 @@
+import { type Children, type Component } from '@inflector/keeno';
+export type Params = Record<string, string>;
+/** Props passed to a route's component. */
+export interface RouteProps {
+    /** Path parameters (`/users/:id` → `{ id }`); updates in place when only they change. */
+    params: Params;
+}
+export interface RouteDefinition {
+    /**
+     * `/users/:id` matches one segment per `:name`; a final `*` (or `*name`) matches the rest of the
+     * path (`params['*']` or `params.name`). Routes are tried in order: put specific ones first.
+     */
+    path: string;
+    /** Receives `RouteProps`. Typed loosely so components can declare their own params type. */
+    component: Component<any>;
+}
+/** 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`. */
+    readonly path: string;
+    readonly params: Params;
+    readonly query: URLSearchParams;
+    /** Including the `#`, or ''. */
+    readonly hash: string;
+    /** The matched route definition, or null. */
+    readonly matched: RouteDefinition | null;
+}
+/** The URL for an app path, with the router's `base` in front: `href('/users/1')`. */
+export declare function href(path: string): string;
+export interface NavigateOptions {
+    /** Replace the current history entry instead of adding one. */
+    replace?: boolean;
+    /** `history.state` for the new entry. */
+    state?: unknown;
+    /** Scroll to the top after navigating (default true, unless the URL has a hash). */
+    scroll?: 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;
+/**
+ * Click handler for your own `<a>` elements: `<a href="/about" onClick={link}>About</a>`. With a
+ * `base`, write `href={href('/about')}`.
+ */
+export declare function link(e: MouseEvent): void;
+/** Match `path` against a route pattern; returns its params, or null. */
+export declare function matchPath(pattern: string | RouteDefinition, path: string): Params | null;
+/** True if the browser's current path is `path` or below it (`exact`: only `path` itself). Tracked. */
+export declare function isActive(path: string, exact?: boolean): boolean;
+export interface RouterProps {
+    routes: RouteDefinition[];
+    /** Path prefix the app is served under, e.g. `/app`. */
+    base?: string;
+    /** Server rendering: the request URL to render, instead of the browser location. */
+    url?: string;
+    /** Rendered when no route matches. */
+    fallback?: () => unknown;
+}
+/**
+ * Render the component of the first route matching the URL. The component is kept when only
+ * the params change, and replaced when another route matches.
+ */
+export declare function Router(props: RouterProps): unknown;
+/** The current route of the closest `<Router>` (call it while the component is created). */
+export declare function useRoute(): Route;
+export interface LinkProps {
+    /** App path (`/users/1`) or relative URL. */
+    href: string;
+    /** Replace the current history entry. */
+    replace?: boolean;
+    /** Class added while the link's path is active (default `active`). */
+    activeClass?: string;
+    /** Only active on exactly this path, not below it. */
+    exact?: boolean;
+    class?: unknown;
+    children?: Children;
+}
+/**
+ * A link that navigates without reloading the page, with `aria-current="page"` and `activeClass`
+ * while active. The scoped styles of the component that renders it apply to its `<a>`.
+ */
+export declare function Link(props: LinkProps): unknown;

package/dist/index.js

@@ -0,0 +1,280 @@
+// ../../../../../../../tmp/keeno-build/_inflector_keeno-router/src/index.ts
+import { State, createContext, derived, inject, provide, untrack } from "@inflector/keeno";
+import { attr, callerScope, createComponent, insert, on, template } from "@inflector/keeno/internal";
+var hasWindow = typeof window !== "undefined" && typeof location !== "undefined";
+function readLocation() {
+  if (!hasWindow)
+    return { pathname: "/", search: "", hash: "" };
+  return { pathname: location.pathname, search: location.search, hash: location.hash };
+}
+function parseUrl(url) {
+  const u = new URL(url, "http://localhost");
+  return { pathname: u.pathname, search: u.search, hash: u.hash };
+}
+var current = new State(readLocation(), {
+  equals: (a, b) => a.pathname === b.pathname && a.search === b.search && a.hash === b.hash
+});
+var listening = false;
+var base = new State("");
+var scrollPositions = new Map;
+var locKey = (l) => l.pathname + l.search + l.hash;
+function saveScroll(l) {
+  if (typeof window.scrollY === "number")
+    scrollPositions.set(locKey(l), [window.scrollX, window.scrollY]);
+}
+function setScrollRestoration(mode) {
+  try {
+    if ("scrollRestoration" in history)
+      history.scrollRestoration = mode;
+  } catch {}
+}
+function restoreScroll(l) {
+  const saved = scrollPositions.get(locKey(l));
+  if (!saved && l.hash)
+    return scrollToHash(l.hash);
+  const run = () => {
+    try {
+      window.scrollTo(saved?.[0] ?? 0, saved?.[1] ?? 0);
+    } catch {}
+  };
+  if (typeof requestAnimationFrame === "function")
+    requestAnimationFrame(run);
+  else
+    setTimeout(run, 0);
+}
+function sync() {
+  if (!hasWindow)
+    return;
+  current.set(readLocation());
+  if (listening)
+    return;
+  listening = true;
+  window.addEventListener("popstate", () => {
+    saveScroll(current.peek());
+    const next = readLocation();
+    current.set(next);
+    restoreScroll(next);
+  });
+  setScrollRestoration("manual");
+  window.addEventListener("pagehide", () => setScrollRestoration("auto"));
+  window.addEventListener("pageshow", () => setScrollRestoration("manual"));
+}
+function normalizeBase(b) {
+  if (!b || b === "/")
+    return "";
+  return "/" + b.replace(/^\/+|\/+$/g, "");
+}
+function underBase(pathname, b) {
+  return !b || pathname === b || pathname.startsWith(b + "/");
+}
+function stripBase(pathname, b) {
+  if (!b)
+    return pathname;
+  if (pathname === b)
+    return "/";
+  return pathname.startsWith(b + "/") ? pathname.slice(b.length) : pathname;
+}
+function withBase(b, path) {
+  return path.startsWith("/") ? b + "/" + path.replace(/^\/+/, "") : path;
+}
+function href(path) {
+  return withBase(base.get(), path);
+}
+function scrollToHash(hash) {
+  const id = decode(hash.slice(1));
+  const run = () => {
+    const el = id && document.getElementById(id);
+    if (el && typeof el.scrollIntoView === "function")
+      el.scrollIntoView();
+  };
+  if (typeof requestAnimationFrame === "function")
+    requestAnimationFrame(run);
+  else
+    setTimeout(run, 0);
+}
+function navigate(to, options = {}) {
+  if (!hasWindow)
+    throw new Error("[keeno-router] navigate() only works in the browser");
+  const url = new URL(href(to), location.href);
+  if (url.origin !== location.origin) {
+    location.assign(url.href);
+    return;
+  }
+  saveScroll(current.peek());
+  if (options.replace)
+    history.replaceState(options.state ?? null, "", url);
+  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 {}
+  }
+}
+function isExternalClick(e, a) {
+  if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey)
+    return true;
+  if (a.target && a.target !== "_self" || a.hasAttribute("download"))
+    return true;
+  const url = new URL(a.href, location.href);
+  return url.origin !== location.origin;
+}
+function link(e) {
+  const a = e.currentTarget?.closest("a");
+  if (!a || isExternalClick(e, a))
+    return;
+  const url = new URL(a.href, location.href);
+  if (!underBase(url.pathname, base.peek()))
+    return;
+  e.preventDefault();
+  navigate(stripBase(url.pathname, base.peek()) + url.search + url.hash, { replace: a.hasAttribute("data-replace") });
+}
+var compiled = new WeakMap;
+function compile(route) {
+  let c = compiled.get(route);
+  if (c)
+    return c;
+  const segments = route.path.split("/").filter(Boolean);
+  let rest = null;
+  const last = segments[segments.length - 1];
+  if (last?.startsWith("*")) {
+    rest = last.slice(1) || "*";
+    segments.pop();
+  }
+  compiled.set(route, c = { segments, rest });
+  return c;
+}
+function decode(s) {
+  try {
+    return decodeURIComponent(s);
+  } catch {
+    return s;
+  }
+}
+function matchPath(pattern, path) {
+  const { segments, rest } = compile(typeof pattern === "string" ? { path: pattern, component: () => null } : pattern);
+  const parts = path.split("/").filter(Boolean);
+  if (rest === null ? parts.length !== segments.length : parts.length < segments.length)
+    return null;
+  const params = {};
+  for (let i = 0;i < segments.length; i++) {
+    const seg = segments[i];
+    if (seg.startsWith(":"))
+      params[seg.slice(1)] = decode(parts[i]);
+    else if (seg !== parts[i])
+      return null;
+  }
+  if (rest !== null)
+    params[rest] = parts.slice(segments.length).map(decode).join("/");
+  return params;
+}
+var RouteContext = createContext(null, "route");
+var BaseContext = createContext(null, "route-base");
+function pathIsActive(here, path, exact) {
+  if (here === path)
+    return true;
+  if (exact || path === "/")
+    return false;
+  return here.startsWith(path.endsWith("/") ? path : path + "/");
+}
+function isActive(path, exact = false) {
+  return pathIsActive(stripBase(current.get().pathname, base.get()), path, exact);
+}
+function Router(props) {
+  const routerBase = normalizeBase(untrack(() => props.base));
+  const url = untrack(() => props.url);
+  const loc = url != null ? new State(parseUrl(url)) : current;
+  if (url == null) {
+    base.set(routerBase);
+    sync();
+  }
+  const outside = (l) => !underBase(l.pathname, routerBase);
+  const info = derived(() => {
+    const l = loc.get();
+    const path = stripBase(l.pathname, routerBase);
+    if (outside(l))
+      return { l, path, matched: null, params: {} };
+    for (const r of props.routes) {
+      const params = matchPath(r, path);
+      if (params)
+        return { l, path, matched: r, params };
+    }
+    return { l, path, matched: null, params: {} };
+  });
+  const matched = derived(() => info.get().matched);
+  const route = {
+    get path() {
+      return info.get().path;
+    },
+    get params() {
+      return info.get().params;
+    },
+    get query() {
+      return new URLSearchParams(info.get().l.search);
+    },
+    get hash() {
+      return info.get().l.hash;
+    },
+    get matched() {
+      return matched.get();
+    }
+  };
+  provide(RouteContext, route);
+  provide(BaseContext, routerBase);
+  return () => {
+    const r = matched.get();
+    if (!r)
+      return props.fallback ? untrack(props.fallback) : null;
+    return untrack(() => createComponent(r.component, {
+      get params() {
+        return info.get().params;
+      }
+    }));
+  };
+}
+function useRoute() {
+  const route = inject(RouteContext);
+  if (!route)
+    throw new Error("[keeno-router] useRoute() must be called inside a <Router>");
+  return route;
+}
+var anchor = template("<a></a>");
+function Link(props) {
+  const a = anchor();
+  const scope = callerScope();
+  const route = inject(RouteContext);
+  const routerBase = inject(BaseContext);
+  if (!route)
+    sync();
+  const active = derived(() => {
+    const path = props.href.split(/[?#]/)[0];
+    return route ? pathIsActive(route.path, path, !!props.exact) : isActive(path, props.exact);
+  });
+  attr(a, "href", () => withBase(routerBase ?? base.get(), props.href));
+  attr(a, "class", () => [props.class, active.get() && (props.activeClass ?? "active")], scope ?? undefined);
+  attr(a, "aria-current", () => active.get() ? "page" : null);
+  on(a, "click", (e) => {
+    if (isExternalClick(e, a))
+      return;
+    e.preventDefault();
+    navigate(props.href, { replace: props.replace });
+  });
+  insert(a, () => props.children?.());
+  return a;
+}
+export {
+  Link,
+  Router,
+  href,
+  isActive,
+  link,
+  matchPath,
+  navigate,
+  useRoute
+};

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@inflector/keeno-router",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Client-side router for Keeno (.kn) apps",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iliesw/Keeno.git",
+    "directory": "packages/router"
+  },
+  "homepage": "https://github.com/iliesw/Keeno/tree/main/packages/router#readme",
+  "bugs": {
+    "url": "https://github.com/iliesw/Keeno/issues"
+  },
+  "keywords": [
+    "keeno",
+    "router",
+    "routing",
+    "spa"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "keeno-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun ../../scripts/build-package.ts --target=browser",
+    "prepack": "bun run build"
+  },
+  "peerDependencies": {
+    "@inflector/keeno": ">=0.3.0 <1.0.0"
+  },
+  "devDependencies": {
+    "@inflector/keeno": "0.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}