fibrae 0.1.0

package/dist/router/History.js

@@ -0,0 +1,241 @@
+/**
+ * History service - track and manage browser navigation history.
+ *
+ * Features:
+ * - Current location (pathname, search, hash, state)
+ * - Navigation methods (push, replace, back, forward, go)
+ * - BrowserHistoryLive - real browser history with popstate handling
+ * - MemoryHistoryLive - in-memory history for testing/SSR
+ * - Cleanly manages event listeners with Effect finalizers
+ *
+ * Design:
+ * - Uses Atom for reactive location updates
+ * - Browser history: listens to window.popstate for back/forward
+ * - Memory history: in-memory stack, useful for SSR/testing
+ * - All navigation returns Effects, integrates with Effect runtime
+ */
+import * as Effect from "effect/Effect";
+import * as Context from "effect/Context";
+import * as Layer from "effect/Layer";
+import { Atom, Registry as AtomRegistry } from "@effect-atom/atom";
+// =============================================================================
+// Service Tag
+// =============================================================================
+/**
+ * History service tag for Effect dependency injection.
+ */
+export class History extends Context.Tag("fibrae/History")() {
+}
+// =============================================================================
+// Browser History Implementation
+// =============================================================================
+/**
+ * Get current browser location.
+ */
+function getBrowserLocation() {
+    return {
+        pathname: window.location.pathname,
+        search: window.location.search,
+        hash: window.location.hash,
+        state: window.history.state,
+    };
+}
+/**
+ * Parse path into location object.
+ */
+function parseLocation(path, state) {
+    try {
+        const url = new URL(path, window.location.origin);
+        return {
+            pathname: url.pathname,
+            search: url.search,
+            hash: url.hash,
+            state,
+        };
+    }
+    catch {
+        return {
+            pathname: path,
+            search: "",
+            hash: "",
+            state,
+        };
+    }
+}
+/**
+ * Browser history layer - real browser history with popstate handling.
+ *
+ * Features:
+ * - Tracks current location in an Atom
+ * - Listens to popstate for back/forward
+ * - Provides push/replace/go navigation methods
+ * - Cleanly removes event listener on scope close
+ * - Properly cleans up event listeners on scope close
+ */
+/* is-tree-shakable-suppress */
+export const BrowserHistoryLive = Layer.scoped(History, Effect.gen(function* () {
+    const registry = yield* AtomRegistry.AtomRegistry;
+    // Create location atom with initial browser location
+    const locationAtom = Atom.make(getBrowserLocation());
+    // Subscribe to popstate for browser back/forward
+    const handlePopState = () => {
+        registry.set(locationAtom, getBrowserLocation());
+    };
+    window.addEventListener("popstate", handlePopState);
+    // Cleanup on scope close
+    yield* Effect.addFinalizer(() => Effect.sync(() => {
+        window.removeEventListener("popstate", handlePopState);
+    }));
+    // Track history index for canGoBack (simplified approach)
+    let historyIndex = 0;
+    const service = {
+        location: locationAtom,
+        push: (path, state) => Effect.sync(() => {
+            const location = parseLocation(path, state);
+            const href = `${location.pathname}${location.search}${location.hash}`;
+            window.history.pushState(state, "", href);
+            historyIndex++;
+            registry.set(locationAtom, {
+                ...location,
+                state,
+            });
+        }),
+        replace: (path, state) => Effect.sync(() => {
+            const location = parseLocation(path, state);
+            const href = `${location.pathname}${location.search}${location.hash}`;
+            window.history.replaceState(state, "", href);
+            registry.set(locationAtom, {
+                ...location,
+                state,
+            });
+        }),
+        back: Effect.sync(() => {
+            window.history.back();
+            // Note: popstate handler will update location
+        }),
+        forward: Effect.sync(() => {
+            window.history.forward();
+            // Note: popstate handler will update location
+        }),
+        go: (n) => Effect.sync(() => {
+            window.history.go(n);
+            // Note: popstate handler will update location
+        }),
+        canGoBack: Effect.sync(() => historyIndex > 0),
+    };
+    return service;
+}));
+/**
+ * Create a memory history layer - useful for testing/SSR.
+ *
+ * Features:
+ * - In-memory navigation stack
+ * - Tracks current location in an Atom
+ * - No browser API usage (safe for SSR/testing)
+ * - Supports push/replace/back/forward/go navigation
+ * - Optional initial location/state configuration
+ */
+export function MemoryHistoryLive(options = {}) {
+    return Layer.scoped(History, Effect.gen(function* () {
+        const registry = yield* AtomRegistry.AtomRegistry;
+        // Create location atom with initial location
+        const initialLocation = {
+            pathname: options.initialPathname ?? "/",
+            search: options.initialSearch ?? "",
+            hash: options.initialHash ?? "",
+            state: options.initialState,
+        };
+        const locationAtom = Atom.make(initialLocation);
+        // Track history stack for back/forward
+        const historyStack = [initialLocation];
+        let historyIndex = 0;
+        const service = {
+            location: locationAtom,
+            push: (path, state) => Effect.sync(() => {
+                const location = parseLocation(path, state);
+                // Remove entries after current index
+                historyStack.splice(historyIndex + 1);
+                // Add new entry
+                historyStack.push(location);
+                historyIndex = historyStack.length - 1;
+                registry.set(locationAtom, location);
+            }),
+            replace: (path, state) => Effect.sync(() => {
+                const location = parseLocation(path, state);
+                // Replace current entry
+                historyStack[historyIndex] = location;
+                registry.set(locationAtom, location);
+            }),
+            back: Effect.sync(() => {
+                if (historyIndex > 0) {
+                    historyIndex--;
+                    registry.set(locationAtom, historyStack[historyIndex]);
+                }
+            }),
+            forward: Effect.sync(() => {
+                if (historyIndex < historyStack.length - 1) {
+                    historyIndex++;
+                    registry.set(locationAtom, historyStack[historyIndex]);
+                }
+            }),
+            go: (n) => Effect.sync(() => {
+                const newIndex = historyIndex + n;
+                if (newIndex >= 0 && newIndex < historyStack.length) {
+                    historyIndex = newIndex;
+                    registry.set(locationAtom, historyStack[historyIndex]);
+                }
+            }),
+            canGoBack: Effect.sync(() => historyIndex > 0),
+        };
+        return service;
+    }));
+}
+// =============================================================================
+// Convenience Accessors
+// =============================================================================
+/**
+ * Get current location.
+ */
+/* is-tree-shakable-suppress */
+export const getLocation = Effect.gen(function* () {
+    const history = yield* History;
+    return yield* Atom.get(history.location);
+});
+/**
+ * Push a new location.
+ */
+export const push = (path, state) => Effect.gen(function* () {
+    const history = yield* History;
+    yield* history.push(path, state);
+});
+/**
+ * Replace current location.
+ */
+export const replace = (path, state) => Effect.gen(function* () {
+    const history = yield* History;
+    yield* history.replace(path, state);
+});
+/**
+ * Go back in history.
+ */
+/* is-tree-shakable-suppress */
+export const back = Effect.gen(function* () {
+    const history = yield* History;
+    yield* history.back;
+});
+/**
+ * Go forward in history.
+ */
+/* is-tree-shakable-suppress */
+export const forward = Effect.gen(function* () {
+    const history = yield* History;
+    yield* history.forward;
+});
+/**
+ * Go n entries in history.
+ */
+export const go = (n) => Effect.gen(function* () {
+    const history = yield* History;
+    yield* history.go(n);
+});
+//# sourceMappingURL=History.js.map

package/dist/router/History.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"History.js","sourceRoot":"","sources":["../../src/router/History.ts"],"names":[],"mappings":"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"}

package/dist/router/Link.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Link component - declarative navigation.
+ *
+ * Renders an <a> element with correct href and handles click for SPA navigation.
+ * - <Link to="routeName">text</Link>
+ * - <Link to="routeName" params={{ id: 123 }}>text</Link>
+ * - <Link to="routeName" search={{ sort: "date" }}>text</Link>
+ * - <Link to="routeName" replace>text</Link>
+ *
+ * Design: href is pre-computed for SSR/accessibility. onClick prevents default
+ * and uses Navigator for SPA navigation.
+ */
+import * as Effect from "effect/Effect";
+import { Registry as AtomRegistry } from "@effect-atom/atom";
+import { Navigator } from "./Navigator.js";
+import type { Router } from "./Router.js";
+import type { VElement } from "../shared.js";
+/**
+ * Props for the Link component.
+ */
+export interface LinkProps {
+    /** Route name to navigate to */
+    readonly to: string;
+    /** Path parameters for the route */
+    readonly params?: Record<string, unknown>;
+    /** Search/query parameters */
+    readonly search?: Record<string, unknown>;
+    /** Use history.replace instead of push */
+    readonly replace?: boolean;
+    /** Additional CSS class names */
+    readonly class?: string;
+    /** Active class name (default: "active") */
+    readonly activeClass?: string;
+    /** Data attributes for testing */
+    readonly "data-cy"?: string;
+    /** Children to render inside the anchor (already normalized by JSX runtime) */
+    readonly children?: ReadonlyArray<VElement>;
+}
+/**
+ * Create a Link component bound to a router.
+ *
+ * The Link component must know which router to use for:
+ * - Building hrefs from route names
+ * - Checking active state
+ *
+ * Usage:
+ * ```typescript
+ * const Link = createLink(appRouter);
+ * <Link to="posts" params={{ id: 123 }}>View Post</Link>
+ * ```
+ */
+export declare function createLink(router: Router): (props: LinkProps) => Effect.Effect<VElement, never, Navigator | AtomRegistry.AtomRegistry>;

package/dist/router/Link.js

@@ -0,0 +1,131 @@
+/**
+ * Link component - declarative navigation.
+ *
+ * Renders an <a> element with correct href and handles click for SPA navigation.
+ * - <Link to="routeName">text</Link>
+ * - <Link to="routeName" params={{ id: 123 }}>text</Link>
+ * - <Link to="routeName" search={{ sort: "date" }}>text</Link>
+ * - <Link to="routeName" replace>text</Link>
+ *
+ * Design: href is pre-computed for SSR/accessibility. onClick prevents default
+ * and uses Navigator for SPA navigation.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { Atom, Registry as AtomRegistry } from "@effect-atom/atom";
+import { Navigator } from "./Navigator.js";
+// =============================================================================
+// Helpers
+// =============================================================================
+/**
+ * Find a route by name in the router.
+ */
+function findRouteByName(router, name) {
+    for (const group of router.groups) {
+        for (const route of group.routes) {
+            if (route.name === name) {
+                return Option.some(route);
+            }
+        }
+    }
+    return Option.none();
+}
+/**
+ * Build search string from params object.
+ */
+function buildSearchString(params) {
+    const searchParams = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined && value !== null) {
+            searchParams.set(key, String(value));
+        }
+    }
+    const str = searchParams.toString();
+    return str ? `?${str}` : "";
+}
+/**
+ * Build the href for a route with params.
+ */
+function buildHref(router, routeName, params, search, basePath = "") {
+    const route = findRouteByName(router, routeName);
+    if (Option.isNone(route)) {
+        return "#";
+    }
+    const pathname = route.value.interpolate(params ?? {});
+    const searchString = search ? buildSearchString(search) : "";
+    return `${basePath}${pathname}${searchString}`;
+}
+// =============================================================================
+// Link Component Factory
+// =============================================================================
+/**
+ * Create a Link component bound to a router.
+ *
+ * The Link component must know which router to use for:
+ * - Building hrefs from route names
+ * - Checking active state
+ *
+ * Usage:
+ * ```typescript
+ * const Link = createLink(appRouter);
+ * <Link to="posts" params={{ id: 123 }}>View Post</Link>
+ * ```
+ */
+export function createLink(router) {
+    return function Link(props) {
+        return Effect.gen(function* () {
+            const navigator = yield* Navigator;
+            const currentRoute = yield* Atom.get(navigator.currentRoute);
+            // Build href for SSR/accessibility (includes basePath)
+            const href = buildHref(router, props.to, props.params, props.search, navigator.basePath);
+            // Check if this link is active
+            const isActive = Option.match(currentRoute, {
+                onNone: () => false,
+                onSome: (route) => {
+                    if (route.routeName !== props.to) {
+                        return false;
+                    }
+                    // If params provided, check they match
+                    if (props.params) {
+                        for (const [key, value] of Object.entries(props.params)) {
+                            if (route.params[key] !== value) {
+                                return false;
+                            }
+                        }
+                    }
+                    return true;
+                },
+            });
+            // Build class string
+            const activeClass = props.activeClass ?? "active";
+            const classes = [props.class, isActive ? activeClass : null]
+                .filter(Boolean)
+                .join(" ");
+            // Click handler - prevent default and use Navigator
+            const handleClick = (e) => {
+                // Allow ctrl/cmd click for new tab
+                if (e.ctrlKey || e.metaKey || e.shiftKey) {
+                    return;
+                }
+                e.preventDefault();
+                return navigator.go(props.to, {
+                    path: props.params,
+                    searchParams: props.search,
+                    replace: props.replace,
+                });
+            };
+            // Return VElement directly - children are already normalized by JSX runtime
+            return {
+                type: "a",
+                props: {
+                    href,
+                    class: classes || undefined,
+                    "data-cy": props["data-cy"],
+                    onClick: handleClick,
+                    children: [...(props.children ?? [])],
+                },
+            };
+        });
+    };
+}
+//# sourceMappingURL=Link.js.map

package/dist/router/Link.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Link.js","sourceRoot":"","sources":["../../src/router/Link.ts"],"names":[],"mappings":"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"}

package/dist/router/Navigator.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Navigator service - type-safe route-aware navigation.
+ *
+ * Provides route-aware navigation on top of History:
+ * - nav.go("routeName", { path: {...}, searchParams: {...} })
+ * - nav.back, nav.forward
+ * - nav.isActive("routeName", params) for active link detection
+ * - currentRoute Atom reflects matched route info
+ *
+ * Design: Navigator uses History internally but provides route-aware API.
+ * It knows about routes and can build URLs from route names.
+ */
+import * as Effect from "effect/Effect";
+import * as Context from "effect/Context";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import { Atom, Registry as AtomRegistry } from "@effect-atom/atom";
+import { History } from "./History.js";
+import type { Router } from "./Router.js";
+/**
+ * Current route info - what route is currently matched.
+ */
+export interface CurrentRoute {
+    readonly routeName: string;
+    readonly params: Record<string, unknown>;
+    readonly searchParams: Record<string, string>;
+}
+/**
+ * Navigation options for go().
+ */
+export interface NavigateOptions<PathParams extends Record<string, unknown> = Record<string, unknown>, SearchParams extends Record<string, unknown> = Record<string, unknown>> {
+    readonly path?: PathParams;
+    readonly searchParams?: SearchParams;
+    readonly replace?: boolean;
+}
+/**
+ * Navigator service interface.
+ * Provides type-safe navigation by route name.
+ */
+export interface NavigatorService {
+    /**
+     * Base path prefix for all routes (e.g., "/ssr/router").
+     * Used for apps mounted at non-root paths.
+     */
+    readonly basePath: string;
+    /**
+     * Current matched route info - updates on navigation.
+     */
+    readonly currentRoute: Atom.Writable<Option.Option<CurrentRoute>, Option.Option<CurrentRoute>>;
+    /**
+     * Navigate to a route by name with optional params.
+     */
+    readonly go: (routeName: string, options?: NavigateOptions) => Effect.Effect<void, never, AtomRegistry.AtomRegistry>;
+    /**
+     * Go back in history.
+     */
+    readonly back: Effect.Effect<void, never, AtomRegistry.AtomRegistry>;
+    /**
+     * Go forward in history.
+     */
+    readonly forward: Effect.Effect<void, never, AtomRegistry.AtomRegistry>;
+    /**
+     * Check if a route is currently active.
+     * Optionally match specific params.
+     */
+    readonly isActive: (routeName: string, params?: Record<string, unknown>) => Effect.Effect<boolean, never, AtomRegistry.AtomRegistry>;
+}
+declare const Navigator_base: Context.TagClass<Navigator, "fibrae/Navigator", NavigatorService>;
+/**
+ * Navigator service tag for Effect dependency injection.
+ */
+export declare class Navigator extends Navigator_base {
+}
+/**
+ * Options for creating a Navigator layer.
+ */
+export interface NavigatorOptions {
+    /** Base path prefix for all routes (e.g., "/ssr/router") */
+    readonly basePath?: string;
+}
+/**
+ * Create a Navigator layer for the given router.
+ *
+ * Features:
+ * - Type-safe navigation by route name
+ * - Automatic URL building via route.interpolate
+ * - Tracks current matched route in an Atom
+ * - Delegates to History for actual navigation
+ * - Supports basePath for apps mounted at non-root paths
+ */
+export declare function NavigatorLive(router: Router, options?: NavigatorOptions): Layer.Layer<Navigator, never, History | AtomRegistry.AtomRegistry>;
+/**
+ * Navigate to a route by name.
+ */
+export declare const go: (routeName: string, options?: NavigateOptions) => Effect.Effect<void, never, Navigator | AtomRegistry.AtomRegistry>;
+/**
+ * Go back in history.
+ */
+export declare const back: Effect.Effect<void, never, Navigator | AtomRegistry.AtomRegistry>;
+/**
+ * Go forward in history.
+ */
+export declare const forward: Effect.Effect<void, never, Navigator | AtomRegistry.AtomRegistry>;
+/**
+ * Get current route info.
+ */
+export declare const getCurrentRoute: Effect.Effect<Option.Option<CurrentRoute>, never, Navigator | AtomRegistry.AtomRegistry>;
+export {};