@tinyfx/runtime 0.1.6 → 0.1.9

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/__tests__/mount-state.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/mount-state.test.js

@@ -0,0 +1,30 @@
+import { describe, it, expect } from "vitest";
+import { markMounted, isMounted } from "../mount-state";
+describe("markMounted", () => {
+    it("returns true on first call", () => {
+        const el = document.createElement("div");
+        expect(markMounted(el)).toBe(true);
+    });
+    it("returns false on second call for same element", () => {
+        const el = document.createElement("div");
+        markMounted(el);
+        expect(markMounted(el)).toBe(false);
+    });
+    it("returns true for different elements", () => {
+        const el1 = document.createElement("div");
+        const el2 = document.createElement("div");
+        markMounted(el1);
+        expect(markMounted(el2)).toBe(true);
+    });
+});
+describe("isMounted", () => {
+    it("returns false for unmarked element", () => {
+        const el = document.createElement("div");
+        expect(isMounted(el)).toBe(false);
+    });
+    it("returns true after markMounted", () => {
+        const el = document.createElement("div");
+        markMounted(el);
+        expect(isMounted(el)).toBe(true);
+    });
+});

package/dist/__tests__/page-registry.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/page-registry.test.js

@@ -0,0 +1,38 @@
+import { describe, it, expect } from "vitest";
+import { registerPage, getPageModule, runPageInit } from "../page-registry";
+describe("registerPage / getPageModule", () => {
+    it("returns undefined for unregistered page", () => {
+        expect(getPageModule("/unknown")).toBeUndefined();
+    });
+    it("returns module after registration", () => {
+        const mod = { init: () => { } };
+        registerPage("/test", mod);
+        expect(getPageModule("/test")).toBe(mod);
+    });
+});
+describe("runPageInit", () => {
+    it("calls init on page module", () => {
+        let called = false;
+        let receivedEl;
+        let receivedCtx;
+        registerPage("/init-test", {
+            init: (el, ctx) => {
+                called = true;
+                receivedEl = el;
+                receivedCtx = ctx;
+            },
+        });
+        const ctx = { params: { id: "1" }, navigate: () => { } };
+        runPageInit("/init-test", ctx);
+        expect(called).toBe(true);
+        expect(receivedEl).toBe(document.body);
+        expect(receivedCtx).toBe(ctx);
+    });
+    it("does nothing for unregistered page", () => {
+        expect(() => runPageInit("/nonexistent", { params: {}, navigate: () => { } })).not.toThrow();
+    });
+    it("does nothing for page without init", () => {
+        registerPage("/no-init", {});
+        expect(() => runPageInit("/no-init", { params: {}, navigate: () => { } })).not.toThrow();
+    });
+});

package/dist/__tests__/path-matcher.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/path-matcher.test.js

@@ -0,0 +1,43 @@
+import { describe, it, expect } from "vitest";
+import { matchPath, splitPath } from "../router/path-matcher";
+describe("splitPath", () => {
+    it("splits root path", () => {
+        expect(splitPath("/")).toEqual([]);
+    });
+    it("splits nested path", () => {
+        expect(splitPath("/blog/hello-world")).toEqual(["blog", "hello-world"]);
+    });
+    it("handles trailing slash", () => {
+        expect(splitPath("/blog/")).toEqual(["blog"]);
+    });
+});
+describe("matchPath", () => {
+    it("matches static route exactly", () => {
+        const def = { staticSegments: ["blog"], paramNames: [] };
+        expect(matchPath(def, ["blog"])).toEqual({});
+    });
+    it("returns null for static mismatch", () => {
+        const def = { staticSegments: ["blog"], paramNames: [] };
+        expect(matchPath(def, ["about"])).toBeNull();
+    });
+    it("returns null for length mismatch", () => {
+        const def = { staticSegments: ["blog"], paramNames: [] };
+        expect(matchPath(def, ["blog", "extra"])).toBeNull();
+    });
+    it("extracts single param", () => {
+        const def = { staticSegments: ["blog", null], paramNames: ["slug"] };
+        expect(matchPath(def, ["blog", "hello-world"])).toEqual({ slug: "hello-world" });
+    });
+    it("extracts multiple params", () => {
+        const def = { staticSegments: [null, "posts", null], paramNames: ["user", "id"] };
+        expect(matchPath(def, ["alice", "posts", "42"])).toEqual({ user: "alice", id: "42" });
+    });
+    it("decodes URI params", () => {
+        const def = { staticSegments: ["blog", null], paramNames: ["slug"] };
+        expect(matchPath(def, ["blog", "hello%20world"])).toEqual({ slug: "hello world" });
+    });
+    it("matches root route", () => {
+        const def = { staticSegments: [], paramNames: [] };
+        expect(matchPath(def, [])).toEqual({});
+    });
+});

package/dist/__tests__/registry.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/registry.test.js

@@ -0,0 +1,67 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { registerComponent, getComponentFactory, mountComponents } from "../registry";
+describe("registerComponent / getComponentFactory", () => {
+    beforeEach(() => {
+        registerComponent("__test_cleanup__", () => { });
+    });
+    it("returns undefined for unregistered component", () => {
+        expect(getComponentFactory("NonExistent")).toBeUndefined();
+    });
+    it("returns factory after registration", () => {
+        const factory = (el) => ({ mounted: true });
+        registerComponent("TestComp", factory);
+        expect(getComponentFactory("TestComp")).toBe(factory);
+    });
+});
+describe("mountComponents", () => {
+    it("mounts components found in root element", () => {
+        const root = document.createElement("div");
+        const el1 = document.createElement("div");
+        el1.setAttribute("data-component", "CompA");
+        const el2 = document.createElement("div");
+        el2.setAttribute("data-component", "CompB");
+        root.appendChild(el1);
+        root.appendChild(el2);
+        const results = [];
+        registerComponent("CompA", () => {
+            results.push("CompA");
+            return { name: "CompA" };
+        });
+        registerComponent("CompB", () => {
+            results.push("CompB");
+            return { name: "CompB" };
+        });
+        const ctx = { params: {}, navigate: () => { } };
+        const instances = mountComponents(ctx, root);
+        expect(results).toContain("CompA");
+        expect(results).toContain("CompB");
+        expect(instances).toHaveLength(2);
+    });
+    it("skips elements without data-component", () => {
+        const root = document.createElement("div");
+        const el = document.createElement("div");
+        root.appendChild(el);
+        const ctx = { params: {}, navigate: () => { } };
+        const instances = mountComponents(ctx, root);
+        expect(instances).toHaveLength(0);
+    });
+    it("skips unregistered component names", () => {
+        const root = document.createElement("div");
+        const el = document.createElement("div");
+        el.setAttribute("data-component", "Unknown");
+        root.appendChild(el);
+        const ctx = { params: {}, navigate: () => { } };
+        const instances = mountComponents(ctx, root);
+        expect(instances).toHaveLength(0);
+    });
+    it("does not include undefined returns in instances", () => {
+        const root = document.createElement("div");
+        const el = document.createElement("div");
+        el.setAttribute("data-component", "NoReturn");
+        root.appendChild(el);
+        registerComponent("NoReturn", () => undefined);
+        const ctx = { params: {}, navigate: () => { } };
+        const instances = mountComponents(ctx, root);
+        expect(instances).toHaveLength(0);
+    });
+});

package/dist/context.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Lightweight page context passed to page and component behavior.
+ *
+ * TinyFX uses this to expose route params and navigation helpers without a
+ * dependency-injection container.
+ *
+ * @example
+ * import type { TinyFxContext } from "@tinyfx/runtime";
+ *
+ * export function init(el: HTMLElement, ctx: TinyFxContext): void {
+ *   console.log(ctx.params.slug);
+ *   ctx.navigate("/");
+ *   void el;
+ * }
+ */
+export interface TinyFxContext {
+    params: Record<string, string>;
+    navigate: (path: string) => void;
+}

package/dist/context.js

@@ -0,0 +1 @@
+export {};

package/dist/dom.d.ts

@@ -1,3 +1,38 @@
+/**
+ * Binds an element's text content to a reactive getter.
+ *
+ * @param el - The DOM element whose text content should be updated
+ * @param get - A reactive getter that returns the next text value
+ * @returns Nothing
+ *
+ * @example
+ * const count = signal(0);
+ * bindText(span, () => `Count: ${count()}`);
+ */
 export declare function bindText(el: HTMLElement, get: () => any): void;
+/**
+ * Binds an attribute to a reactive getter.
+ *
+ * @param el - The DOM element whose attribute should be updated
+ * @param attr - The attribute name to write
+ * @param get - A reactive getter that returns the attribute value
+ * @returns Nothing
+ *
+ * @example
+ * const isDark = signal(false);
+ * bindAttr(document.body, "data-theme", () => (isDark() ? "dark" : "light"));
+ */
 export declare function bindAttr(el: HTMLElement, attr: string, get: () => string): void;
+/**
+ * Toggles a CSS class from a reactive boolean getter.
+ *
+ * @param el - The DOM element whose class list should be updated
+ * @param cls - The class name to toggle
+ * @param get - A reactive getter that returns whether the class should exist
+ * @returns Nothing
+ *
+ * @example
+ * const open = signal(false);
+ * bindClass(panel, "is-open", () => open());
+ */
 export declare function bindClass(el: HTMLElement, cls: string, get: () => boolean): void;

package/dist/dom.js

@@ -1,16 +1,51 @@
 // @tinyfx/runtime — DOM helpers
 // Helpers for binding reactive state to the DOM.
 import { effect } from "./signals";
+/**
+ * Binds an element's text content to a reactive getter.
+ *
+ * @param el - The DOM element whose text content should be updated
+ * @param get - A reactive getter that returns the next text value
+ * @returns Nothing
+ *
+ * @example
+ * const count = signal(0);
+ * bindText(span, () => `Count: ${count()}`);
+ */
 export function bindText(el, get) {
     effect(() => {
         el.textContent = String(get());
     });
 }
+/**
+ * Binds an attribute to a reactive getter.
+ *
+ * @param el - The DOM element whose attribute should be updated
+ * @param attr - The attribute name to write
+ * @param get - A reactive getter that returns the attribute value
+ * @returns Nothing
+ *
+ * @example
+ * const isDark = signal(false);
+ * bindAttr(document.body, "data-theme", () => (isDark() ? "dark" : "light"));
+ */
 export function bindAttr(el, attr, get) {
     effect(() => {
         el.setAttribute(attr, get());
     });
 }
+/**
+ * Toggles a CSS class from a reactive boolean getter.
+ *
+ * @param el - The DOM element whose class list should be updated
+ * @param cls - The class name to toggle
+ * @param get - A reactive getter that returns whether the class should exist
+ * @returns Nothing
+ *
+ * @example
+ * const open = signal(false);
+ * bindClass(panel, "is-open", () => open());
+ */
 export function bindClass(el, cls, get) {
     effect(() => {
         el.classList.toggle(cls, get());

package/dist/each.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Register a mounted component instance by root element.
+ */
+export declare function registerInstance(el: HTMLElement, instance: {
+    destroy?: () => void;
+}): void;
+/**
+ * Destroy a mounted component instance on a node and nested component nodes.
+ */
+export declare function destroyNode(el: HTMLElement): void;

package/dist/each.js

@@ -0,0 +1,24 @@
+// @tinyfx/runtime — each lifecycle helpers
+const __componentInstances = new WeakMap();
+/**
+ * Register a mounted component instance by root element.
+ */
+export function registerInstance(el, instance) {
+    __componentInstances.set(el, instance);
+}
+/**
+ * Destroy a mounted component instance on a node and nested component nodes.
+ */
+export function destroyNode(el) {
+    var _a;
+    const inst = __componentInstances.get(el);
+    (_a = inst === null || inst === void 0 ? void 0 : inst.destroy) === null || _a === void 0 ? void 0 : _a.call(inst);
+    __componentInstances.delete(el);
+    el.querySelectorAll("[data-component]").forEach((child) => {
+        var _a;
+        const childEl = child;
+        const childInst = __componentInstances.get(childEl);
+        (_a = childInst === null || childInst === void 0 ? void 0 : childInst.destroy) === null || _a === void 0 ? void 0 : _a.call(childInst);
+        __componentInstances.delete(childEl);
+    });
+}