@tinyfx/runtime 0.1.8 → 0.1.9

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

@@ -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,3 +1,15 @@
+/**
+ * Error thrown for non-success HTTP responses.
+ *
+ * @example
+ * try {
+ *   await http.get("/posts");
+ * } catch (error) {
+ *   if (error instanceof HttpError) {
+ *     console.error(error.status, error.url);
+ *   }
+ * }
+ */
 export declare class HttpError extends Error {
     readonly status: number;
     readonly statusText: string;
@@ -6,15 +18,51 @@ export declare class HttpError extends Error {
     readonly response?: Response | undefined;
     constructor(status: number, statusText: string, url: string, method: string, response?: Response | undefined);
 }
+/**
+ * Error thrown when a request times out.
+ *
+ * @example
+ * try {
+ *   await http.get("/slow", { timeout: 100 });
+ * } catch (error) {
+ *   if (error instanceof HttpTimeoutError) {
+ *     console.error(error.timeout);
+ *   }
+ * }
+ */
 export declare class HttpTimeoutError extends Error {
     readonly url: string;
     readonly timeout: number;
     constructor(url: string, timeout: number);
 }
+/**
+ * Error thrown when a JSON response cannot be parsed.
+ *
+ * @example
+ * try {
+ *   await http.get("/broken-json");
+ * } catch (error) {
+ *   if (error instanceof HttpParseError) {
+ *     console.error(error.url);
+ *   }
+ * }
+ */
 export declare class HttpParseError extends Error {
     readonly url: string;
     constructor(message: string, url: string);
 }
+/**
+ * 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 +72,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 +103,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;

package/dist/http/data.js

@@ -1,3 +1,15 @@
+/**
+ * Error thrown for non-success HTTP responses.
+ *
+ * @example
+ * try {
+ *   await http.get("/posts");
+ * } catch (error) {
+ *   if (error instanceof HttpError) {
+ *     console.error(error.status, error.url);
+ *   }
+ * }
+ */
 export class HttpError extends Error {
     constructor(status, statusText, url, method, response) {
         super(`HTTP ${status} ${statusText}: ${method} ${url}`);
@@ -9,6 +21,18 @@ export class HttpError extends Error {
         this.name = "HttpError";
     }
 }
+/**
+ * Error thrown when a request times out.
+ *
+ * @example
+ * try {
+ *   await http.get("/slow", { timeout: 100 });
+ * } catch (error) {
+ *   if (error instanceof HttpTimeoutError) {
+ *     console.error(error.timeout);
+ *   }
+ * }
+ */
 export class HttpTimeoutError extends Error {
     constructor(url, timeout) {
         super(`Request timeout after ${timeout}ms: ${url}`);
@@ -17,6 +41,18 @@ export class HttpTimeoutError extends Error {
         this.name = "HttpTimeoutError";
     }
 }
+/**
+ * Error thrown when a JSON response cannot be parsed.
+ *
+ * @example
+ * try {
+ *   await http.get("/broken-json");
+ * } catch (error) {
+ *   if (error instanceof HttpParseError) {
+ *     console.error(error.url);
+ *   }
+ * }
+ */
 export class HttpParseError extends Error {
     constructor(message, url) {
         super(message);

package/dist/http/helper.d.ts

@@ -1,2 +1,22 @@
+/**
+ * Builds a request URL by combining a base path with optional query params.
+ *
+ * @param url - The request path or URL fragment
+ * @param base - The configured base URL prefix
+ * @param params - Optional query parameters to append
+ * @returns The final request URL string
+ *
+ * @example
+ * buildUrl("/posts", "/api", { page: 2, published: true });
+ */
 export declare function buildUrl(url: string, base: string, params?: Record<string, string | number | boolean>): string;
+/**
+ * Waits for a number of milliseconds.
+ *
+ * @param ms - The delay duration in milliseconds
+ * @returns A promise that resolves after the delay completes
+ *
+ * @example
+ * await sleep(250);
+ */
 export declare function sleep(ms: number): Promise<void>;

package/dist/http/helper.js

@@ -1,3 +1,14 @@
+/**
+ * Builds a request URL by combining a base path with optional query params.
+ *
+ * @param url - The request path or URL fragment
+ * @param base - The configured base URL prefix
+ * @param params - Optional query parameters to append
+ * @returns The final request URL string
+ *
+ * @example
+ * buildUrl("/posts", "/api", { page: 2, published: true });
+ */
 export function buildUrl(url, base, params) {
     const fullUrl = base + url;
     if (!params || Object.keys(params).length === 0)
@@ -8,6 +19,15 @@ export function buildUrl(url, base, params) {
     });
     return urlObj.toString().replace(urlObj.origin, '');
 }
+/**
+ * Waits for a number of milliseconds.
+ *
+ * @param ms - The delay duration in milliseconds
+ * @returns A promise that resolves after the delay completes
+ *
+ * @example
+ * await sleep(250);
+ */
 export async function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }

package/dist/http/http.d.ts

@@ -1,4 +1,17 @@
 import { HttpConfig, RequestOptions } from "./data";
+/**
+ * Creates a typed HTTP client around `fetch`.
+ *
+ * The client exposes `get`, `post`, `put`, `patch`, `del`, and `delete`
+ * helpers and applies the default configuration to every request.
+ *
+ * @param config - Default HTTP configuration such as base URL, headers, and retry policy
+ * @returns An object containing typed request methods
+ *
+ * @example
+ * const http = createHttp({ baseUrl: "/api", timeout: 5000 });
+ * const posts = await http.get<{ id: number; title: string }[]>("/posts");
+ */
 export declare function createHttp(config?: HttpConfig): {
     get: <T>(url: string, options?: RequestOptions) => Promise<T>;
     post: <T>(url: string, body?: unknown, options?: RequestOptions) => Promise<T>;

package/dist/http/http.js

@@ -2,6 +2,19 @@
 // Thin, typed wrapper over fetch.
 import { HttpError, HttpParseError, HttpTimeoutError } from "./data";
 import { buildUrl, sleep } from "./helper";
+/**
+ * Creates a typed HTTP client around `fetch`.
+ *
+ * The client exposes `get`, `post`, `put`, `patch`, `del`, and `delete`
+ * helpers and applies the default configuration to every request.
+ *
+ * @param config - Default HTTP configuration such as base URL, headers, and retry policy
+ * @returns An object containing typed request methods
+ *
+ * @example
+ * const http = createHttp({ baseUrl: "/api", timeout: 5000 });
+ * const posts = await http.get<{ id: number; title: string }[]>("/posts");
+ */
 export function createHttp(config = {}) {
     var _a, _b, _c, _d, _e, _f, _g;
     const base = (_a = config.baseUrl) !== null && _a !== void 0 ? _a : "";

package/dist/index.d.ts

@@ -1,6 +1,14 @@
 export { signal, effect } from "./signals";
+export { registerInstance, destroyNode } from "./each";
 export { bindText, bindAttr, bindClass } from "./dom";
 export { createHttp } from "./http";
+export { registerComponent, getComponentFactory, mountComponents } from "./registry";
+export { registerPage, getPageModule, runPageInit } from "./page-registry";
+export { markMounted, isMounted } from "./mount-state";
+export { matchPath, splitPath } from "./router/path-matcher";
+export type { RouteDef } from "./router/path-matcher";
+export { init } from "./init";
+export type { InitConfig } from "./init";
 export { initRouter, getParam, navigate, goBack } from "./router/index";
 export { onMount, onDestroy } from "./router/lifecycle";
 export type { TinyFxContext } from "./context";

package/dist/index.js

@@ -1,6 +1,14 @@
 // @tinyfx/runtime — barrel export
 export { signal, effect } from "./signals";
+export { registerInstance, destroyNode } from "./each";
 export { bindText, bindAttr, bindClass } from "./dom";
 export { createHttp } from "./http";
+// New decoupled APIs
+export { registerComponent, getComponentFactory, mountComponents } from "./registry";
+export { registerPage, getPageModule, runPageInit } from "./page-registry";
+export { markMounted, isMounted } from "./mount-state";
+export { matchPath, splitPath } from "./router/path-matcher";
+export { init } from "./init";
+// Keep existing router exports
 export { initRouter, getParam, navigate, goBack } from "./router/index";
 export { onMount, onDestroy } from "./router/lifecycle";

package/dist/init.d.ts

@@ -0,0 +1,12 @@
+import type { TinyFxContext } from "./context";
+import type { RouteDef } from "./router/path-matcher";
+export interface InitConfig {
+    routes: Record<string, RouteDef>;
+    setupDirectives?: (ctx: TinyFxContext) => void;
+}
+export interface InitResult {
+    matchedPath: string;
+    params: Record<string, string>;
+    instances: any[];
+}
+export declare function init(config: InitConfig): InitResult | null;