@tinyfx/runtime 0.1.4 → 0.1.8

package/README.md

@@ -1,16 +1,15 @@
 # @tinyfx/runtime
 
-> The minimal, browser-side runtime for tinyfx.
-
-A lightweight collection of helpers for reactivity, DOM manipulation, and typed HTTP communication. Designed to be used standalone or as part of the `tinyfx` build pipeline.
+The TinyFX browser runtime: signals, DOM helpers, typed HTTP, and router lifecycle utilities.
 
 ## Features
 
-- **Signals** — Explicit reactivity without Proxies.
-- **DOM Helpers** — One-way bindings for text, attributes, and classes.
-- **Typed HTTP** — Minimal wrapper over `fetch` with response typing.
-- **DI Container** — Simple `provide()`/`inject()` registry for app services.
-- **Tiny** — No dependencies, tree-shakeable, and extremely fast.
+- Signals (`signal`, `effect`)
+- DOM binding helpers (`bindText`, `bindAttr`, `bindClass`)
+- Typed HTTP client (`createHttp`)
+- Router helpers (`initRouter`, `navigate`, `goBack`, `getParam`)
+- Lifecycle hooks (`onMount`, `onDestroy`)
+- Lightweight `TinyFxContext` (`params`, `navigate`)
 
 ## Installation
 
@@ -20,27 +19,21 @@ npm install @tinyfx/runtime
 
 ## Usage
 
-### Signals (Reactivity)
-
-Signals provide a simple way to manage state that triggers effects when changed.
+### Signals
 
 ```ts
 import { signal, effect } from "@tinyfx/runtime";
 
 const count = signal(0);
 
-// Runs immediately, and re-runs whenever count() changes
 effect(() => {
-  console.log("The count is:", count());
+  console.log("count:", count());
 });
 
-count.set(1); // logs: "The count is: 1"
-count.set(count() + 1); // logs: "The count is: 2"
+count.set(count() + 1);
 ```
 
-### DOM Bindings
-
-Keep your JS decoupled from the DOM while maintaining reactive updates.
+### DOM bindings
 
 ```ts
 import { signal, bindText, bindClass, bindAttr } from "@tinyfx/runtime";
@@ -51,132 +44,66 @@ const isActive = signal(false);
 const el = document.getElementById("counter");
 const btn = document.querySelector("button");
 
-bindText(el, () => `Count: ${count()}`);
-bindClass(btn, "active", isActive);
-bindAttr(btn, "disabled", () => count() > 10);
-```
-
-### Typed HTTP Client
-
-A thin wrapper over `fetch` that returns typed responses.
-
-```ts
-import { createHttp } from "@tinyfx/runtime";
-
-interface User {
-  id: number;
-  name: string;
+if (el && btn) {
+  bindText(el, () => `Count: ${count()}`);
+  bindClass(btn, "active", isActive);
+  bindAttr(btn, "disabled", () => count() > 10);
 }
-
-const api = createHttp({ baseUrl: "/api" });
-
-// Fully typed response
-const users = await api.get<User[]>("/users");
-
-// POST with data
-await api.post("/users", { name: "Alice" });
 ```
 
-### DI Container (provide / inject)
-
-TinyFX includes a small dependency injection container to avoid importing singleton instances everywhere.
-
-Import it from `@tinyfx/runtime/di`:
+### HTTP client
 
 ```ts
-import { Container } from "@tinyfx/runtime/di";
-
-class Config {
-  constructor(public baseUrl: string) {}
-}
-
-const container = new Container();
-container.provide(Config, new Config("/api"));
-
-const cfg = container.inject(Config);
-console.log(cfg.baseUrl);
-```
-
-#### Using DI with tinyfx components
-
-When you use the tinyfx compiler, the generated glue calls your component behavior as:
+import { createHttp } from "@tinyfx/runtime";
 
-```ts
-init(el, { container })
+const http = createHttp({ baseUrl: "/api" });
+const users = await http.get<{ id: number; name: string }[]>("/users");
 ```
 
-So your component can inject services without importing global singletons:
+### TinyFxContext
 
 ```ts
-import type { TinyFxContext } from "@tinyfx/runtime/di";
-import { HttpService } from "../lib/http.service";
+import type { TinyFxContext } from "@tinyfx/runtime";
 
 export function init(el: HTMLElement, ctx: TinyFxContext) {
-  const http = ctx.container.inject(HttpService);
-  http.getWeather().then((text) => {
-    el.textContent = text;
-  });
+  console.log(ctx.params);
+  ctx.navigate("/about");
 }
 ```
 
-#### Example: service that uses the HTTP helper
+### Router + lifecycle hooks
 
 ```ts
-// src/lib/http.service.ts
-import { createHttp } from "@tinyfx/runtime";
-
-export class HttpService {
-  private readonly http;
+import { initRouter, onMount, onDestroy } from "@tinyfx/runtime";
 
-  constructor(baseUrl: string) {
-    this.http = createHttp({ baseUrl });
-  }
-
-  getWeather() {
-    // wttr.in can return plain text; your wrapper returns text when not JSON.
-    return this.http.get<string>("");
-  }
-}
-```
-
-```ts
-// src/main.ts
-import { Container } from "@tinyfx/runtime/di";
-import { setupComponents } from "./tinyfx.gen";
-import { HttpService } from "./lib/http.service";
+initRouter({
+  "/": { page: "index", path: "/" },
+});
 
-const container = new Container();
-container.provide(HttpService, new HttpService("https://wttr.in/tunisa"));
+onMount(() => {
+  console.log("mounted");
+});
 
-document.addEventListener("DOMContentLoaded", () => {
-  setupComponents(container);
+onDestroy(() => {
+  console.log("destroyed");
 });
 ```
 
-## API Overview
-
-### Signals
-- `signal<T>(value: T): Signal<T>`
-- `effect(fn: () => void): void`
-
-### DOM
-- `bindText(el: HTMLElement, source: Signal<any> | (() => any)): void`
-- `bindAttr(el: HTMLElement, attr: string, source: Signal<any> | (() => any)): void`
-- `bindClass(el: HTMLElement, className: string, source: Signal<boolean> | (() => boolean)): void`
-
-### HTTP
-- `createHttp(config: HttpConfig): HttpClient`
-- `client.get<T>(url: string): Promise<T>`
-- `client.post<T>(url: string, data?: any): Promise<T>`
-- `client.put<T>(url: string, data?: any): Promise<T>`
-- `client.del<T>(url: string): Promise<T>`
-
-### DI
-- `new Container()`
-- `container.provide(token, instance)`
-- `container.inject(token)`
-- `createToken<T>(description: string): symbol`
-- `TinyFxContext` (passed to component init via tinyfx glue)
+## API overview
+
+- `signal<T>(value: T)`
+- `effect(fn)`
+- `bindText(el, source)`
+- `bindAttr(el, attr, source)`
+- `bindClass(el, className, source)`
+- `createHttp(config?)`
+- `initRouter(routes)`
+- `getParam(name)`
+- `navigate(path)`
+- `goBack()`
+- `onMount(fn)`
+- `onDestroy(fn)`
+- `TinyFxContext`
 
 ## License
 

package/dist/context.d.ts

@@ -0,0 +1,4 @@
+export interface TinyFxContext {
+    params: Record<string, string>;
+    navigate: (path: string) => void;
+}

package/dist/context.js

@@ -0,0 +1,3 @@
+// Lightweight page context passed to components by the runtime.
+// Not a DI container — services are created explicitly via factory functions.
+export {};

package/dist/di.d.ts

@@ -2,7 +2,7 @@
 export type Token<T> = (new (...args: any[]) => T) | symbol;
 /** Create a unique symbol token with a debug description. */
 export declare function createToken<T>(description: string): Token<T>;
-/** Context passed to every component's init() function. */
+/** Context passed to every component's mount() factory function. */
 export interface TinyFxContext {
     container: Container;
 }

package/dist/http.d.ts

@@ -1,10 +1,2 @@
-export interface HttpConfig {
-    baseUrl?: string;
-    headers?: Record<string, string>;
-}
-export declare function createHttp(config?: HttpConfig): {
-    get: <T>(url: string) => Promise<T>;
-    post: <T>(url: string, body?: unknown) => Promise<T>;
-    put: <T>(url: string, body?: unknown) => Promise<T>;
-    del: <T>(url: string) => Promise<T>;
-};
+export { createHttp } from "./http/http";
+export type { HttpConfig } from "./http/data";

package/dist/http.js

@@ -1,38 +1 @@
-// @tinyfx/runtime — HTTP client
-// Thin, typed wrapper over fetch.
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-export function createHttp(config = {}) {
-    var _a, _b;
-    const base = (_a = config.baseUrl) !== null && _a !== void 0 ? _a : "";
-    const defaultHeaders = (_b = config.headers) !== null && _b !== void 0 ? _b : {};
-    function request(method, url, body) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const headers = Object.assign({}, defaultHeaders);
-            if (body !== undefined) {
-                headers["Content-Type"] = "application/json";
-            }
-            const res = yield fetch(base + url, {
-                method,
-                headers,
-                body: body !== undefined ? JSON.stringify(body) : undefined,
-            });
-            if (!res.ok)
-                throw new Error(`${method} ${url}: ${res.status} ${res.statusText}`);
-            return res.json();
-        });
-    }
-    return {
-        get: (url) => request("GET", url),
-        post: (url, body) => request("POST", url, body),
-        put: (url, body) => request("PUT", url, body),
-        del: (url) => request("DELETE", url),
-    };
-}
+export { createHttp } from "./http/http";

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-export { signal, effect, Signal } from "./signals";
+export { signal, effect } from "./signals";
 export { bindText, bindAttr, bindClass } from "./dom";
-export { createHttp } from "./http/http";
-export type { HttpConfig } from "./http/data";
-export { Container, createToken } from "./di";
-export type { Token, TinyFxContext } from "./di";
+export { createHttp } from "./http";
+export { initRouter, getParam, navigate, goBack } from "./router/index";
+export { onMount, onDestroy } from "./router/lifecycle";
+export type { TinyFxContext } from "./context";
+export type { RouteMap, RouteMeta } from "./router/types";

package/dist/index.js

@@ -1,5 +1,6 @@
 // @tinyfx/runtime — barrel export
-export { signal, effect, Signal } from "./signals";
+export { signal, effect } from "./signals";
 export { bindText, bindAttr, bindClass } from "./dom";
-export { createHttp } from "./http/http";
-export { Container, createToken } from "./di";
+export { createHttp } from "./http";
+export { initRouter, getParam, navigate, goBack } from "./router/index";
+export { onMount, onDestroy } from "./router/lifecycle";

package/dist/router/active-links.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Mark anchor tags whose `href` pathname matches `pathname` with
+ * `data-active="true"`, removing the attribute from all others.
+ *
+ * Only the pathname portion of each href is compared (query strings and
+ * fragments are ignored).
+ *
+ * @example
+ * // In a nav: <a href="/blog">Blog</a>
+ * // On the /blog page this element will get data-active="true"
+ * highlightActiveLinks("/blog");
+ */
+export declare function highlightActiveLinks(pathname: string): void;

package/dist/router/active-links.js

@@ -0,0 +1,31 @@
+// @tinyfx/runtime — active link highlighting
+/**
+ * Mark anchor tags whose `href` pathname matches `pathname` with
+ * `data-active="true"`, removing the attribute from all others.
+ *
+ * Only the pathname portion of each href is compared (query strings and
+ * fragments are ignored).
+ *
+ * @example
+ * // In a nav: <a href="/blog">Blog</a>
+ * // On the /blog page this element will get data-active="true"
+ * highlightActiveLinks("/blog");
+ */
+export function highlightActiveLinks(pathname) {
+    const links = document.querySelectorAll("a[href]");
+    links.forEach((link) => {
+        try {
+            // Resolve href against the current origin to normalise relative URLs
+            const url = new URL(link.getAttribute("href"), window.location.origin);
+            if (url.pathname === pathname) {
+                link.setAttribute("data-active", "true");
+            }
+            else {
+                link.removeAttribute("data-active");
+            }
+        }
+        catch (_a) {
+            // Ignore malformed / external hrefs
+        }
+    });
+}

package/dist/router/index.d.ts

@@ -0,0 +1,24 @@
+import type { RouteMap } from "./types";
+import { navigate, goBack } from "./navigate";
+import { getParam } from "./params";
+export type { RouteMap };
+export { navigate, goBack, getParam };
+/**
+ * Initialise the TinyFX router for the current page.
+ *
+ * Called automatically from the compiler-generated `tinyfx.gen.ts` on every
+ * page load.  Matches `window.location.pathname` against the compiled route
+ * map, resolves URL params, starts lifecycle hooks, and highlights active
+ * navigation links.
+ *
+ * @param routes - The route map emitted by `tinyfx build`.
+ *
+ * @example
+ * // tinyfx.gen.ts (auto-generated — do not edit)
+ * initRouter({
+ *   "/":          { page: "home",      path: "/" },
+ *   "/blog":      { page: "blog",      path: "/blog" },
+ *   "/blog/:slug":{ page: "blog-post", path: "/blog/:slug" },
+ * });
+ */
+export declare function initRouter(routes: RouteMap): void;

package/dist/router/index.js

@@ -0,0 +1,38 @@
+// @tinyfx/runtime — router entry point
+import { navigate, goBack } from "./navigate";
+import { getParam, resolveParams } from "./params";
+import { initLifecycle } from "./lifecycle";
+import { highlightActiveLinks } from "./active-links";
+export { navigate, goBack, getParam };
+/**
+ * Initialise the TinyFX router for the current page.
+ *
+ * Called automatically from the compiler-generated `tinyfx.gen.ts` on every
+ * page load.  Matches `window.location.pathname` against the compiled route
+ * map, resolves URL params, starts lifecycle hooks, and highlights active
+ * navigation links.
+ *
+ * @param routes - The route map emitted by `tinyfx build`.
+ *
+ * @example
+ * // tinyfx.gen.ts (auto-generated — do not edit)
+ * initRouter({
+ *   "/":          { page: "home",      path: "/" },
+ *   "/blog":      { page: "blog",      path: "/blog" },
+ *   "/blog/:slug":{ page: "blog-post", path: "/blog/:slug" },
+ * });
+ */
+export function initRouter(routes) {
+    const pathname = window.location.pathname;
+    for (const pattern of Object.keys(routes)) {
+        if (resolveParams(pattern, pathname)) {
+            // Match found
+            initLifecycle();
+            highlightActiveLinks(pathname);
+            return;
+        }
+    }
+    // No route matched — log a warning and do nothing else.
+    console.warn(`[tinyfx] No route matched for pathname: "${pathname}". ` +
+        "Check that a page file exists for this URL in src/pages/.");
+}

package/dist/router/lifecycle.d.ts

@@ -0,0 +1,24 @@
+type LifecycleCallback = () => void;
+/**
+ * Register a callback to run when the page has mounted (DOM ready).
+ *
+ * - If the document is still loading, the callback runs after DOMContentLoaded.
+ * - If the document is already loaded, the callback runs immediately.
+ */
+export declare function onMount(fn: LifecycleCallback): void;
+/**
+ * Register a callback to run when the user navigates away from this page.
+ * Fires on the browser's `pagehide` event.
+ */
+export declare function onDestroy(fn: LifecycleCallback): void;
+/**
+ * Trigger all registered `onMount` callbacks.
+ * Called by `initRouter` after matching the current route.
+ */
+export declare function flushMount(): void;
+/**
+ * Wire up registered `onDestroy` callbacks to the `pagehide` event.
+ * Called by `initRouter` after matching the current route.
+ */
+export declare function initLifecycle(): void;
+export {};

package/dist/router/lifecycle.js

@@ -0,0 +1,44 @@
+// @tinyfx/runtime — page lifecycle hooks
+const mountCallbacks = [];
+const destroyCallbacks = [];
+/**
+ * Register a callback to run when the page has mounted (DOM ready).
+ *
+ * - If the document is still loading, the callback runs after DOMContentLoaded.
+ * - If the document is already loaded, the callback runs immediately.
+ */
+export function onMount(fn) {
+    if (document.readyState === "loading") {
+        mountCallbacks.push(fn);
+        return;
+    }
+    fn();
+}
+/**
+ * Register a callback to run when the user navigates away from this page.
+ * Fires on the browser's `pagehide` event.
+ */
+export function onDestroy(fn) {
+    destroyCallbacks.push(fn);
+}
+/**
+ * Trigger all registered `onMount` callbacks.
+ * Called by `initRouter` after matching the current route.
+ */
+export function flushMount() {
+    const run = () => mountCallbacks.forEach((fn) => fn());
+    if (document.readyState === "loading") {
+        document.addEventListener("DOMContentLoaded", run, { once: true });
+    }
+    else {
+        run();
+    }
+}
+/**
+ * Wire up registered `onDestroy` callbacks to the `pagehide` event.
+ * Called by `initRouter` after matching the current route.
+ */
+export function initLifecycle() {
+    flushMount();
+    window.addEventListener("pagehide", () => destroyCallbacks.forEach((fn) => fn()), { once: true });
+}

package/dist/router/navigate.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Navigate to the given path.
+ * This is a full browser navigation — not a DOM swap.
+ *
+ * @example
+ * navigate("/blog/hello-world");
+ */
+export declare function navigate(path: string): void;
+/**
+ * Go back one step in the browser history.
+ */
+export declare function goBack(): void;

package/dist/router/navigate.js

@@ -0,0 +1,18 @@
+// @tinyfx/runtime — navigation helpers
+// Hard router: navigation is always a real browser page load.
+/**
+ * Navigate to the given path.
+ * This is a full browser navigation — not a DOM swap.
+ *
+ * @example
+ * navigate("/blog/hello-world");
+ */
+export function navigate(path) {
+    window.location.href = path;
+}
+/**
+ * Go back one step in the browser history.
+ */
+export function goBack() {
+    window.history.go(-1);
+}

package/dist/router/params.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Match `pattern` (e.g. "/blog/:slug") against `pathname` (e.g. "/blog/hello").
+ *
+ * Returns true if they match, and stores any `:param` captures in the
+ * module-level store so `getParam()` can retrieve them.
+ *
+ * Static segments must match exactly; `:param` segments match any non-empty
+ * path segment.
+ */
+export declare function resolveParams(pattern: string, pathname: string): boolean;
+/**
+ * Retrieve a URL parameter resolved for the current page.
+ *
+ * @example
+ * // On the page with route "/blog/:slug" and URL "/blog/hello-world"
+ * getParam("slug"); // → "hello-world"
+ */
+export declare function getParam(key: string): string | undefined;
+export declare function getParams(): Record<string, string>;

package/dist/router/params.js

@@ -0,0 +1,45 @@
+// @tinyfx/runtime — route param resolution
+/** Module-level store for the current page's resolved params. */
+let currentParams = {};
+/**
+ * Match `pattern` (e.g. "/blog/:slug") against `pathname` (e.g. "/blog/hello").
+ *
+ * Returns true if they match, and stores any `:param` captures in the
+ * module-level store so `getParam()` can retrieve them.
+ *
+ * Static segments must match exactly; `:param` segments match any non-empty
+ * path segment.
+ */
+export function resolveParams(pattern, pathname) {
+    const patternParts = pattern.split("/").filter(Boolean);
+    const pathParts = pathname.split("/").filter(Boolean);
+    if (patternParts.length !== pathParts.length)
+        return false;
+    const captured = {};
+    for (let i = 0; i < patternParts.length; i++) {
+        const seg = patternParts[i];
+        if (seg.startsWith(":")) {
+            // Dynamic segment — capture the value
+            captured[seg.slice(1)] = decodeURIComponent(pathParts[i]);
+        }
+        else if (seg !== pathParts[i]) {
+            // Static segment mismatch
+            return false;
+        }
+    }
+    currentParams = captured;
+    return true;
+}
+/**
+ * Retrieve a URL parameter resolved for the current page.
+ *
+ * @example
+ * // On the page with route "/blog/:slug" and URL "/blog/hello-world"
+ * getParam("slug"); // → "hello-world"
+ */
+export function getParam(key) {
+    return currentParams[key];
+}
+export function getParams() {
+    return Object.assign({}, currentParams);
+}

package/dist/router/types.d.ts

@@ -0,0 +1,9 @@
+/** Metadata for a single route, produced by the compiler. */
+export interface RouteMeta {
+    /** The page name, derived from the source filename. */
+    page: string;
+    /** The declared URL pattern, e.g. "/blog/:slug". */
+    path: string;
+}
+/** The full route map emitted by `tinyfx build` into tinyfx.gen.ts. */
+export type RouteMap = Record<string, RouteMeta>;

package/dist/router/types.js

@@ -0,0 +1,2 @@
+// @tinyfx/runtime — router types
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tinyfx/runtime",
-  "version": "0.1.4",
+  "version": "0.1.8",
   "description": "Minimal frontend runtime — signals, DOM helpers, typed HTTP, DTO mapping",
   "type": "module",
   "main": "./dist/index.js",
@@ -10,7 +10,7 @@
     "./signals": "./dist/signals.js",
     "./dom": "./dist/dom.js",
     "./http": "./dist/http.js",
-    "./di": "./dist/di.js"
+    "./router": "./dist/router/index.js"
   },
   "files": [
     "dist"