@tinyfx/runtime 0.1.8 → 0.1.9

package/dist/init.js

@@ -0,0 +1,40 @@
+// @tinyfx/runtime — unified initialization
+// Single entry point for TinyFX bootstrap.
+import { matchPath, splitPath } from "./router/path-matcher";
+import { initLifecycle } from "./router/lifecycle";
+import { highlightActiveLinks } from "./router/active-links";
+import { navigate } from "./router/navigate";
+import { mountComponents } from "./registry";
+import { runPageInit } from "./page-registry";
+let initialized = false;
+export function init(config) {
+    if (initialized)
+        return null;
+    initialized = true;
+    const pathname = window.location.pathname;
+    const pathSegments = splitPath(pathname);
+    let matchedPath = null;
+    let params = {};
+    for (const [path, def] of Object.entries(config.routes)) {
+        const result = matchPath(def, pathSegments);
+        if (result) {
+            matchedPath = path;
+            params = result;
+            break;
+        }
+    }
+    if (!matchedPath) {
+        console.warn(`[tinyfx] No route matched for pathname: "${pathname}". ` +
+            "Check that a page file exists for this URL in src/pages/.");
+        return null;
+    }
+    initLifecycle();
+    highlightActiveLinks(pathname);
+    const ctx = { params, navigate };
+    const instances = mountComponents(ctx);
+    if (config.setupDirectives) {
+        config.setupDirectives(ctx);
+    }
+    runPageInit(matchedPath, ctx);
+    return { matchedPath, params, instances };
+}

package/dist/mount-state.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Mark an element as mounted. Returns false if already mounted.
+ *
+ * @param el - The element to mark
+ * @returns true if newly marked, false if already mounted
+ *
+ * @example
+ * if (!markMounted(el)) return undefined;
+ */
+export declare function markMounted(el: HTMLElement): boolean;
+/**
+ * Check if an element has been marked as mounted.
+ *
+ * @param el - The element to check
+ * @returns true if the element is marked as mounted
+ */
+export declare function isMounted(el: HTMLElement): boolean;

package/dist/mount-state.js

@@ -0,0 +1,27 @@
+// @tinyfx/runtime — mount state tracking
+// WeakSet-based mount tracking that is safe for minifier mangling.
+const mounted = new WeakSet();
+/**
+ * Mark an element as mounted. Returns false if already mounted.
+ *
+ * @param el - The element to mark
+ * @returns true if newly marked, false if already mounted
+ *
+ * @example
+ * if (!markMounted(el)) return undefined;
+ */
+export function markMounted(el) {
+    if (mounted.has(el))
+        return false;
+    mounted.add(el);
+    return true;
+}
+/**
+ * Check if an element has been marked as mounted.
+ *
+ * @param el - The element to check
+ * @returns true if the element is marked as mounted
+ */
+export function isMounted(el) {
+    return mounted.has(el);
+}

package/dist/page-registry.d.ts

@@ -0,0 +1,31 @@
+import type { TinyFxContext } from "./context";
+type PageModule = {
+    init?: (el: HTMLElement, ctx: TinyFxContext) => void;
+};
+/**
+ * Register a page module by its route path.
+ *
+ * @param path - The route path (e.g., "/blog/:slug")
+ * @param module - The page module object with optional init()
+ * @returns Nothing
+ *
+ * @example
+ * registerPage("/blog/:slug", PageModule);
+ */
+export declare function registerPage(path: string, module: PageModule): void;
+/**
+ * Retrieve a registered page module.
+ *
+ * @param path - The route path to look up
+ * @returns The page module, or undefined if not registered
+ */
+export declare function getPageModule(path: string): PageModule | undefined;
+/**
+ * Run the init() function for a registered page module.
+ *
+ * @param path - The route path of the page to initialize
+ * @param ctx - The TinyFx context to pass to page init
+ * @returns Nothing
+ */
+export declare function runPageInit(path: string, ctx: TinyFxContext): void;
+export {};

package/dist/page-registry.js

@@ -0,0 +1,38 @@
+// @tinyfx/runtime — page module registry
+// Decoupled page module registration for tree-shakable bundles.
+const modules = new Map();
+/**
+ * Register a page module by its route path.
+ *
+ * @param path - The route path (e.g., "/blog/:slug")
+ * @param module - The page module object with optional init()
+ * @returns Nothing
+ *
+ * @example
+ * registerPage("/blog/:slug", PageModule);
+ */
+export function registerPage(path, module) {
+    modules.set(path, module);
+}
+/**
+ * Retrieve a registered page module.
+ *
+ * @param path - The route path to look up
+ * @returns The page module, or undefined if not registered
+ */
+export function getPageModule(path) {
+    return modules.get(path);
+}
+/**
+ * Run the init() function for a registered page module.
+ *
+ * @param path - The route path of the page to initialize
+ * @param ctx - The TinyFx context to pass to page init
+ * @returns Nothing
+ */
+export function runPageInit(path, ctx) {
+    const mod = modules.get(path);
+    if (typeof (mod === null || mod === void 0 ? void 0 : mod.init) === "function") {
+        mod.init(document.body, ctx);
+    }
+}

package/dist/registry.d.ts

@@ -0,0 +1,31 @@
+import type { TinyFxContext } from "./context";
+type ComponentFactory = (el: HTMLElement, ctx: TinyFxContext) => any;
+/**
+ * Register a component factory by name.
+ *
+ * @param name - The component name (matches `data-component` attribute)
+ * @param factory - A function that mounts the component and returns an instance
+ * @returns Nothing
+ *
+ * @example
+ * registerComponent("Button", (el, ctx) => {
+ *   return ButtonModule.mount(el, ctx);
+ * });
+ */
+export declare function registerComponent(name: string, factory: ComponentFactory): void;
+/**
+ * Retrieve a registered component factory.
+ *
+ * @param name - The component name to look up
+ * @returns The factory function, or undefined if not registered
+ */
+export declare function getComponentFactory(name: string): ComponentFactory | undefined;
+/**
+ * Mount all registered components found within a root element.
+ *
+ * @param ctx - The TinyFx context to pass to each component
+ * @param root - The root element to scan (defaults to document)
+ * @returns Array of mounted component instances
+ */
+export declare function mountComponents(ctx: TinyFxContext, root?: Document | HTMLElement): any[];
+export {};

package/dist/registry.js

@@ -0,0 +1,49 @@
+// @tinyfx/runtime — component registry
+// Decoupled component registration for tree-shakable bundles.
+const factories = new Map();
+/**
+ * Register a component factory by name.
+ *
+ * @param name - The component name (matches `data-component` attribute)
+ * @param factory - A function that mounts the component and returns an instance
+ * @returns Nothing
+ *
+ * @example
+ * registerComponent("Button", (el, ctx) => {
+ *   return ButtonModule.mount(el, ctx);
+ * });
+ */
+export function registerComponent(name, factory) {
+    factories.set(name, factory);
+}
+/**
+ * Retrieve a registered component factory.
+ *
+ * @param name - The component name to look up
+ * @returns The factory function, or undefined if not registered
+ */
+export function getComponentFactory(name) {
+    return factories.get(name);
+}
+/**
+ * Mount all registered components found within a root element.
+ *
+ * @param ctx - The TinyFx context to pass to each component
+ * @param root - The root element to scan (defaults to document)
+ * @returns Array of mounted component instances
+ */
+export function mountComponents(ctx, root = document) {
+    const instances = [];
+    root.querySelectorAll("[data-component]").forEach((el) => {
+        const name = el.getAttribute("data-component");
+        if (!name)
+            return;
+        const factory = factories.get(name);
+        if (!factory)
+            return;
+        const inst = factory(el, ctx);
+        if (inst)
+            instances.push(inst);
+    });
+    return instances;
+}

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

@@ -5,6 +5,9 @@
  * Only the pathname portion of each href is compared (query strings and
  * fragments are ignored).
  *
+ * @param pathname - The pathname to compare each link against
+ * @returns Nothing
+ *
  * @example
  * // In a nav: <a href="/blog">Blog</a>
  * // On the /blog page this element will get data-active="true"

package/dist/router/active-links.js

@@ -6,6 +6,9 @@
  * Only the pathname portion of each href is compared (query strings and
  * fragments are ignored).
  *
+ * @param pathname - The pathname to compare each link against
+ * @returns Nothing
+ *
  * @example
  * // In a nav: <a href="/blog">Blog</a>
  * // On the /blog page this element will get data-active="true"

package/dist/router/index.d.ts

@@ -12,6 +12,7 @@ export { navigate, goBack, getParam };
  * navigation links.
  *
  * @param routes - The route map emitted by `tinyfx build`.
+ * @returns Nothing
  *
  * @example
  * // tinyfx.gen.ts (auto-generated — do not edit)

package/dist/router/index.js

@@ -13,6 +13,7 @@ export { navigate, goBack, getParam };
  * navigation links.
  *
  * @param routes - The route map emitted by `tinyfx build`.
+ * @returns Nothing
  *
  * @example
  * // tinyfx.gen.ts (auto-generated — do not edit)

package/dist/router/lifecycle.d.ts

@@ -4,21 +4,47 @@ type LifecycleCallback = () => void;
  *
  * - If the document is still loading, the callback runs after DOMContentLoaded.
  * - If the document is already loaded, the callback runs immediately.
+ *
+ * @param fn - The callback to run on mount
+ * @returns Nothing
+ *
+ * @example
+ * onMount(() => {
+ *   console.log("page ready");
+ * });
  */
 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.
+ *
+ * @param fn - The callback to run during page teardown
+ * @returns Nothing
+ *
+ * @example
+ * onDestroy(() => {
+ *   console.log("page leaving");
+ * });
  */
 export declare function onDestroy(fn: LifecycleCallback): void;
 /**
  * Trigger all registered `onMount` callbacks.
  * Called by `initRouter` after matching the current route.
+ *
+ * @returns Nothing
+ *
+ * @example
+ * flushMount();
  */
 export declare function flushMount(): void;
 /**
  * Wire up registered `onDestroy` callbacks to the `pagehide` event.
  * Called by `initRouter` after matching the current route.
+ *
+ * @returns Nothing
+ *
+ * @example
+ * initLifecycle();
  */
 export declare function initLifecycle(): void;
 export {};

package/dist/router/lifecycle.js

@@ -6,6 +6,14 @@ const destroyCallbacks = [];
  *
  * - If the document is still loading, the callback runs after DOMContentLoaded.
  * - If the document is already loaded, the callback runs immediately.
+ *
+ * @param fn - The callback to run on mount
+ * @returns Nothing
+ *
+ * @example
+ * onMount(() => {
+ *   console.log("page ready");
+ * });
  */
 export function onMount(fn) {
     if (document.readyState === "loading") {
@@ -17,6 +25,14 @@ export function onMount(fn) {
 /**
  * Register a callback to run when the user navigates away from this page.
  * Fires on the browser's `pagehide` event.
+ *
+ * @param fn - The callback to run during page teardown
+ * @returns Nothing
+ *
+ * @example
+ * onDestroy(() => {
+ *   console.log("page leaving");
+ * });
  */
 export function onDestroy(fn) {
     destroyCallbacks.push(fn);
@@ -24,6 +40,11 @@ export function onDestroy(fn) {
 /**
  * Trigger all registered `onMount` callbacks.
  * Called by `initRouter` after matching the current route.
+ *
+ * @returns Nothing
+ *
+ * @example
+ * flushMount();
  */
 export function flushMount() {
     const run = () => mountCallbacks.forEach((fn) => fn());
@@ -37,6 +58,11 @@ export function flushMount() {
 /**
  * Wire up registered `onDestroy` callbacks to the `pagehide` event.
  * Called by `initRouter` after matching the current route.
+ *
+ * @returns Nothing
+ *
+ * @example
+ * initLifecycle();
  */
 export function initLifecycle() {
     flushMount();

package/dist/router/navigate.d.ts

@@ -2,11 +2,19 @@
  * Navigate to the given path.
  * This is a full browser navigation — not a DOM swap.
  *
+ * @param path - The destination pathname or URL
+ * @returns Nothing
+ *
  * @example
  * navigate("/blog/hello-world");
  */
 export declare function navigate(path: string): void;
 /**
  * Go back one step in the browser history.
+ *
+ * @returns Nothing
+ *
+ * @example
+ * goBack();
  */
 export declare function goBack(): void;

package/dist/router/navigate.js

@@ -4,6 +4,9 @@
  * Navigate to the given path.
  * This is a full browser navigation — not a DOM swap.
  *
+ * @param path - The destination pathname or URL
+ * @returns Nothing
+ *
  * @example
  * navigate("/blog/hello-world");
  */
@@ -12,6 +15,11 @@ export function navigate(path) {
 }
 /**
  * Go back one step in the browser history.
+ *
+ * @returns Nothing
+ *
+ * @example
+ * goBack();
  */
 export function goBack() {
     window.history.go(-1);

package/dist/router/params.d.ts

@@ -6,14 +6,33 @@
  *
  * Static segments must match exactly; `:param` segments match any non-empty
  * path segment.
+ *
+ * @param pattern - The route pattern produced by the compiler
+ * @param pathname - The current browser pathname
+ * @returns `true` when the pathname matches the pattern, otherwise `false`
+ *
+ * @example
+ * resolveParams("/blog/:slug", "/blog/hello-world");
  */
 export declare function resolveParams(pattern: string, pathname: string): boolean;
 /**
  * Retrieve a URL parameter resolved for the current page.
  *
+ * @param key - The route parameter name to read
+ * @returns The decoded parameter value, or `undefined` when it is missing
+ *
  * @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;
+/**
+ * Returns a shallow copy of all currently resolved route params.
+ *
+ * @returns An object containing the current route parameters
+ *
+ * @example
+ * const params = getParams();
+ * console.log(params.slug);
+ */
 export declare function getParams(): Record<string, string>;

package/dist/router/params.js

@@ -9,6 +9,13 @@ let currentParams = {};
  *
  * Static segments must match exactly; `:param` segments match any non-empty
  * path segment.
+ *
+ * @param pattern - The route pattern produced by the compiler
+ * @param pathname - The current browser pathname
+ * @returns `true` when the pathname matches the pattern, otherwise `false`
+ *
+ * @example
+ * resolveParams("/blog/:slug", "/blog/hello-world");
  */
 export function resolveParams(pattern, pathname) {
     const patternParts = pattern.split("/").filter(Boolean);
@@ -33,6 +40,9 @@ export function resolveParams(pattern, pathname) {
 /**
  * Retrieve a URL parameter resolved for the current page.
  *
+ * @param key - The route parameter name to read
+ * @returns The decoded parameter value, or `undefined` when it is missing
+ *
  * @example
  * // On the page with route "/blog/:slug" and URL "/blog/hello-world"
  * getParam("slug"); // → "hello-world"
@@ -40,6 +50,15 @@ export function resolveParams(pattern, pathname) {
 export function getParam(key) {
     return currentParams[key];
 }
+/**
+ * Returns a shallow copy of all currently resolved route params.
+ *
+ * @returns An object containing the current route parameters
+ *
+ * @example
+ * const params = getParams();
+ * console.log(params.slug);
+ */
 export function getParams() {
     return Object.assign({}, currentParams);
 }

package/dist/router/path-matcher.d.ts

@@ -0,0 +1,30 @@
+export interface RouteDef {
+    /** Static segment values (null for dynamic segments) */
+    staticSegments: (string | null)[];
+    /** Param names at dynamic positions */
+    paramNames: string[];
+}
+/**
+ * Match a pre-compiled route definition against path segments.
+ *
+ * @param def - The route definition from the compiler
+ * @param pathSegments - Pre-split path segments from splitPath()
+ * @returns Captured params on match, null on mismatch
+ *
+ * @example
+ * const def = { staticSegments: ["blog", null], paramNames: ["slug"] };
+ * matchPath(def, ["blog", "hello-world"]);
+ * // Returns: { slug: "hello-world" }
+ */
+export declare function matchPath(def: RouteDef, pathSegments: string[]): Record<string, string> | null;
+/**
+ * Split a pathname into segments for matching.
+ *
+ * @param pathname - The browser pathname (e.g., "/blog/hello")
+ * @returns Array of non-empty segments
+ *
+ * @example
+ * splitPath("/blog/hello-world");
+ * // Returns: ["blog", "hello-world"]
+ */
+export declare function splitPath(pathname: string): string[];

package/dist/router/path-matcher.js

@@ -0,0 +1,45 @@
+// @tinyfx/runtime — path matcher
+// Unified path resolution with pre-split array support for compiler optimization.
+/**
+ * Match a pre-compiled route definition against path segments.
+ *
+ * @param def - The route definition from the compiler
+ * @param pathSegments - Pre-split path segments from splitPath()
+ * @returns Captured params on match, null on mismatch
+ *
+ * @example
+ * const def = { staticSegments: ["blog", null], paramNames: ["slug"] };
+ * matchPath(def, ["blog", "hello-world"]);
+ * // Returns: { slug: "hello-world" }
+ */
+export function matchPath(def, pathSegments) {
+    const { staticSegments, paramNames } = def;
+    if (staticSegments.length !== pathSegments.length)
+        return null;
+    const params = {};
+    let paramIdx = 0;
+    for (let i = 0; i < staticSegments.length; i++) {
+        const expected = staticSegments[i];
+        const actual = pathSegments[i];
+        if (expected === null) {
+            params[paramNames[paramIdx++]] = decodeURIComponent(actual);
+        }
+        else if (expected !== actual) {
+            return null;
+        }
+    }
+    return params;
+}
+/**
+ * Split a pathname into segments for matching.
+ *
+ * @param pathname - The browser pathname (e.g., "/blog/hello")
+ * @returns Array of non-empty segments
+ *
+ * @example
+ * splitPath("/blog/hello-world");
+ * // Returns: ["blog", "hello-world"]
+ */
+export function splitPath(pathname) {
+    return pathname.split("/").filter(Boolean);
+}

package/dist/router/types.d.ts

@@ -1,9 +1,22 @@
-/** Metadata for a single route, produced by the compiler. */
+/**
+ * Metadata for a single route produced by the compiler.
+ *
+ * @example
+ * const route: RouteMeta = { page: "blog-post", path: "/blog/:slug" };
+ */
 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. */
+/**
+ * The full route map emitted by `tinyfx build` into `tinyfx.gen.ts`.
+ *
+ * @example
+ * const routes: RouteMap = {
+ *   "/": { page: "index", path: "/" },
+ *   "/blog/:slug": { page: "blog-post", path: "/blog/:slug" },
+ * };
+ */
 export type RouteMap = Record<string, RouteMeta>;

package/dist/signals.d.ts

@@ -1,3 +1,16 @@
+/**
+ * Reactive value container used by TinyFX signals.
+ *
+ * Reading the value through {@link Signal.get} during an active effect records
+ * that effect as a subscriber. Writing through {@link Signal.set} re-runs the
+ * affected subscribers.
+ *
+ * @example
+ * const count = new Signal(0);
+ * console.log(count.get());
+ * count.set(1);
+ * console.log(count.get());
+ */
 export declare class Signal<T> {
     private value;
     private subs;
@@ -5,7 +18,35 @@ export declare class Signal<T> {
     get(): T;
     set(v: T): void;
 }
+/**
+ * Creates a reactive signal function.
+ *
+ * @param v - The initial value stored by the signal
+ * @returns A callable signal that reads the current value and exposes `.set()`
+ *          to update it
+ *
+ * @example
+ * const count = signal(0);
+ * console.log(count());
+ * count.set(1);
+ */
 export declare function signal<T>(v: T): (() => T) & {
     set(v: T): void;
 };
+/**
+ * Registers and runs a reactive effect.
+ *
+ * Every signal read while `fn` runs is tracked, and the effect is re-run when
+ * any of those signal values change.
+ *
+ * @param fn - The reactive callback to execute and subscribe
+ * @returns Nothing
+ *
+ * @example
+ * const count = signal(0);
+ * effect(() => {
+ *   console.log(`count = ${count()}`);
+ * });
+ * count.set(1);
+ */
 export declare function effect(fn: () => void): void;