@tinyfx/runtime 0.1.8 → 0.2.0

package/dist/__tests__/http-errors.test.d.ts

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

package/dist/__tests__/http-errors.test.js

@@ -0,0 +1,65 @@
+import { describe, it, expect } from "vitest";
+import { httpError, timeoutError, parseError } from "../http/data";
+describe("httpError", () => {
+    it("creates http error with all fields", () => {
+        const err = httpError(404, "Not Found", "/api/test", "GET");
+        expect(err.kind).toBe("http");
+        if (err.kind === "http") {
+            expect(err.status).toBe(404);
+            expect(err.statusText).toBe("Not Found");
+            expect(err.url).toBe("/api/test");
+            expect(err.method).toBe("GET");
+        }
+    });
+    it("includes optional response", () => {
+        const response = new Response();
+        const err = httpError(500, "Server Error", "/api", "POST", response);
+        if (err.kind === "http") {
+            expect(err.response).toBe(response);
+        }
+    });
+});
+describe("timeoutError", () => {
+    it("creates timeout error with url and timeout", () => {
+        const err = timeoutError("/api/slow", 5000);
+        expect(err.kind).toBe("timeout");
+        if (err.kind === "timeout") {
+            expect(err.url).toBe("/api/slow");
+            expect(err.timeout).toBe(5000);
+        }
+    });
+});
+describe("parseError", () => {
+    it("creates parse error with message and url", () => {
+        const err = parseError("Unexpected token", "/api/json");
+        expect(err.kind).toBe("parse");
+        if (err.kind === "parse") {
+            expect(err.message).toBe("Unexpected token");
+            expect(err.url).toBe("/api/json");
+        }
+    });
+});
+describe("error discrimination", () => {
+    it("allows discriminating by kind", () => {
+        const errors = [
+            httpError(400, "Bad Request", "/a", "GET"),
+            timeoutError("/b", 1000),
+            parseError("Bad JSON", "/c"),
+        ];
+        const httpErr = errors.find((e) => e.kind === "http");
+        expect(httpErr === null || httpErr === void 0 ? void 0 : httpErr.kind).toBe("http");
+        if ((httpErr === null || httpErr === void 0 ? void 0 : httpErr.kind) === "http") {
+            expect(httpErr.status).toBe(400);
+        }
+        const timeoutErr = errors.find((e) => e.kind === "timeout");
+        expect(timeoutErr === null || timeoutErr === void 0 ? void 0 : timeoutErr.kind).toBe("timeout");
+        if ((timeoutErr === null || timeoutErr === void 0 ? void 0 : timeoutErr.kind) === "timeout") {
+            expect(timeoutErr.timeout).toBe(1000);
+        }
+        const parseErr = errors.find((e) => e.kind === "parse");
+        expect(parseErr === null || parseErr === void 0 ? void 0 : parseErr.kind).toBe("parse");
+        if ((parseErr === null || parseErr === void 0 ? void 0 : parseErr.kind) === "parse") {
+            expect(parseErr.message).toBe("Bad JSON");
+        }
+    });
+});

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/__tests__/router-merged.test.d.ts

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

package/dist/__tests__/router-merged.test.js

@@ -0,0 +1,33 @@
+import { describe, it, expect, vi } from "vitest";
+import { navigate, goBack } from "../router/index";
+describe("navigate", () => {
+    it("is a function that accepts a path string", () => {
+        expect(typeof navigate).toBe("function");
+        expect(() => navigate("/test/path")).not.toThrow();
+    });
+});
+describe("goBack", () => {
+    it("calls history.go(-1)", () => {
+        const spy = vi.spyOn(window.history, "go");
+        goBack();
+        expect(spy).toHaveBeenCalledWith(-1);
+        spy.mockRestore();
+    });
+});
+describe("RouteMeta type", () => {
+    it("accepts valid route metadata", () => {
+        const meta = { page: "blog-post", path: "/blog/:slug" };
+        expect(meta.page).toBe("blog-post");
+        expect(meta.path).toBe("/blog/:slug");
+    });
+});
+describe("RouteMap type", () => {
+    it("accepts route map object", () => {
+        const routes = {
+            "/": { page: "index", path: "/" },
+            "/blog/:slug": { page: "blog-post", path: "/blog/:slug" },
+        };
+        expect(Object.keys(routes)).toHaveLength(2);
+        expect(routes["/blog/:slug"].page).toBe("blog-post");
+    });
+});

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

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

package/dist/__tests__/signals.test.js

@@ -0,0 +1,93 @@
+import { describe, it, expect } from "vitest";
+import { signal, effect } from "../signals";
+describe("signal (inlined)", () => {
+    it("returns current value when called", () => {
+        const count = signal(0);
+        expect(count()).toBe(0);
+    });
+    it("updates value via set()", () => {
+        const count = signal(0);
+        count.set(5);
+        expect(count()).toBe(5);
+    });
+    it("does not notify subscribers when value is the same", () => {
+        const count = signal(0);
+        let runs = 0;
+        effect(() => {
+            count();
+            runs++;
+        });
+        expect(runs).toBe(1);
+        count.set(0);
+        expect(runs).toBe(1);
+    });
+    it("notifies subscribers on change", () => {
+        const count = signal(0);
+        let value = 0;
+        effect(() => {
+            value = count();
+        });
+        expect(value).toBe(0);
+        count.set(10);
+        expect(value).toBe(10);
+    });
+    it("supports multiple subscribers", () => {
+        const count = signal(0);
+        let a = 0;
+        let b = 0;
+        effect(() => { a = count(); });
+        effect(() => { b = count() * 2; });
+        count.set(3);
+        expect(a).toBe(3);
+        expect(b).toBe(6);
+    });
+    it("works with objects", () => {
+        const user = signal({ name: "Alice" });
+        expect(user().name).toBe("Alice");
+        user.set({ name: "Bob" });
+        expect(user().name).toBe("Bob");
+    });
+    it("does not re-run effect when unrelated signal changes", () => {
+        const a = signal(0);
+        const b = signal(0);
+        let runs = 0;
+        effect(() => {
+            a();
+            runs++;
+        });
+        expect(runs).toBe(1);
+        b.set(1);
+        expect(runs).toBe(1);
+    });
+});
+describe("effect", () => {
+    it("runs immediately on creation", () => {
+        let ran = false;
+        effect(() => { ran = true; });
+        expect(ran).toBe(true);
+    });
+    it("re-runs when tracked signal changes", () => {
+        const count = signal(0);
+        let runs = 0;
+        effect(() => {
+            count();
+            runs++;
+        });
+        expect(runs).toBe(1);
+        count.set(1);
+        expect(runs).toBe(2);
+    });
+    it("supports nested signal reads", () => {
+        const a = signal(1);
+        const b = signal(2);
+        let sum = 0;
+        effect(() => {
+            sum = a() + b();
+        });
+        expect(sum).toBe(3);
+        a.set(10);
+        expect(sum).toBe(12);
+        b.set(5);
+        expect(sum).toBe(15);
+    });
+});

package/dist/context.d.ts

@@ -1,3 +1,18 @@
+/**
+ * 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

@@ -1,3 +1 @@
-// Lightweight page context passed to components by the runtime.
-// Not a DI container — services are created explicitly via factory functions.
 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);
+    });
+}

package/dist/http/data.d.ts

@@ -1,20 +1,59 @@
-export declare class HttpError extends Error {
-    readonly status: number;
-    readonly statusText: string;
-    readonly url: string;
-    readonly method: string;
-    readonly response?: Response | undefined;
-    constructor(status: number, statusText: string, url: string, method: string, response?: Response | undefined);
-}
-export declare class HttpTimeoutError extends Error {
-    readonly url: string;
-    readonly timeout: number;
-    constructor(url: string, timeout: number);
-}
-export declare class HttpParseError extends Error {
-    readonly url: string;
-    constructor(message: string, url: string);
-}
+/**
+ * Discriminated union type for HTTP errors.
+ *
+ * @example
+ * try {
+ *   await http.get("/posts");
+ * } catch (error) {
+ *   if (error.kind === "http") {
+ *     console.error(error.status, error.url);
+ *   } else if (error.kind === "timeout") {
+ *     console.error(error.timeout);
+ *   } else if (error.kind === "parse") {
+ *     console.error(error.url);
+ *   }
+ * }
+ */
+export type HttpError = {
+    kind: "http";
+    status: number;
+    statusText: string;
+    url: string;
+    method: string;
+    response?: Response;
+} | {
+    kind: "timeout";
+    url: string;
+    timeout: number;
+} | {
+    kind: "parse";
+    message: string;
+    url: string;
+};
+export declare function httpError(status: number, statusText: string, url: string, method: string, response?: Response): HttpError;
+export declare function timeoutError(url: string, timeout: number): HttpError;
+export declare function parseError(message: string, url: string): HttpError;
+export declare function isHttpError(err: unknown): err is Extract<HttpError, {
+    kind: "http";
+}>;
+export declare function isTimeoutError(err: unknown): err is Extract<HttpError, {
+    kind: "timeout";
+}>;
+export declare function isParseError(err: unknown): err is Extract<HttpError, {
+    kind: "parse";
+}>;
+/**
+ * Hook that can rewrite an outgoing request before `fetch` runs.
+ *
+ * @example
+ * const addToken: RequestInterceptor = (url, options) => ({
+ *   url,
+ *   options: {
+ *     ...options,
+ *     headers: { ...options.headers, Authorization: "Bearer token" },
+ *   },
+ * });
+ */
 export interface RequestInterceptor {
     (url: string, options: RequestInit): Promise<{
         url: string;
@@ -24,9 +63,28 @@ export interface RequestInterceptor {
         options: RequestInit;
     };
 }
+/**
+ * Hook that can inspect or replace a response before TinyFX handles it.
+ *
+ * @example
+ * const logResponse: ResponseInterceptor = (response) => {
+ *   console.log(response.status);
+ *   return response;
+ * };
+ */
 export interface ResponseInterceptor {
     (response: Response): Promise<Response> | Response;
 }
+/**
+ * Default options for an HTTP client created by `createHttp()`.
+ *
+ * @example
+ * const config: HttpConfig = {
+ *   baseUrl: "/api",
+ *   timeout: 5000,
+ *   retries: 1,
+ * };
+ */
 export interface HttpConfig {
     baseUrl?: string;
     headers?: Record<string, string>;
@@ -36,6 +94,15 @@ export interface HttpConfig {
     requestInterceptors?: RequestInterceptor[];
     responseInterceptors?: ResponseInterceptor[];
 }
+/**
+ * Per-request overrides for an HTTP call.
+ *
+ * @example
+ * const options: RequestOptions = {
+ *   params: { page: 2 },
+ *   timeout: 1000,
+ * };
+ */
 export interface RequestOptions {
     headers?: Record<string, string>;
     timeout?: number;