@wrikka/solid-framework 0.0.0-stage → 0.15.0

package/src/router/presentation/solid/devtools/router-inspector.ts

@@ -0,0 +1,54 @@
+import type { RouteMatch, RouterState } from "../../../shared/types";
+
+export interface RouterDevTools {
+	inspectRoute(): RouteMatch | null;
+	inspectState(): RouterState;
+	trackNavigation(callback: (route: RouteMatch) => void): () => void;
+}
+
+export class RouterInspector implements RouterDevTools {
+	private navigationCallbacks: Array<(route: RouteMatch) => void> = [];
+	private currentRoute: RouteMatch | null = null;
+	private state: RouterState = {
+		currentRoute: null,
+		isLoading: false,
+		error: null,
+	};
+
+	setCurrentRoute(route: RouteMatch): void {
+		this.currentRoute = route;
+		this.state.currentRoute = route;
+		this.notifyNavigation(route);
+	}
+
+	setState(newState: Partial<RouterState>): void {
+		this.state = { ...this.state, ...newState };
+	}
+
+	inspectRoute(): RouteMatch | null {
+		return this.currentRoute;
+	}
+
+	inspectState(): RouterState {
+		return this.state;
+	}
+
+	trackNavigation(callback: (route: RouteMatch) => void): () => void {
+		this.navigationCallbacks.push(callback);
+		return () => {
+			this.navigationCallbacks = this.navigationCallbacks.filter(
+				(cb) => cb !== callback,
+			);
+		};
+	}
+
+	private notifyNavigation(route: RouteMatch): void {
+		for (const callback of this.navigationCallbacks) {
+			callback(route);
+		}
+	}
+}
+
+export const createRouterInspector = (): RouterInspector => {
+	return new RouterInspector();
+};

package/src/router/presentation/solid/hmr.ts

@@ -0,0 +1,77 @@
+import { onCleanup, onMount } from "solid-js";
+
+export type HMRState = {
+	enabled: boolean;
+	hotRoutes: Set<string>;
+};
+
+export class HMRManager {
+	private state: HMRState = {
+		enabled: false,
+		hotRoutes: new Set(),
+	};
+
+	constructor() {
+		if (typeof window !== "undefined" && (window as any).__HMR__) {
+			this.state.enabled = true;
+			this.setupHMR();
+		}
+	}
+
+	private setupHMR(): void {
+		if (typeof (window as any).__VITE_HMR__ !== "undefined") {
+			(window as any).__VITE_HMR__.on(
+				"router:reload",
+				(data: { path: string }) => {
+					this.reloadRoute(data.path);
+				},
+			);
+		}
+	}
+
+	enableHotRoute(path: string): void {
+		this.state.hotRoutes.add(path);
+	}
+
+	disableHotRoute(path: string): void {
+		this.state.hotRoutes.delete(path);
+	}
+
+	isHotRoute(path: string): boolean {
+		return this.state.hotRoutes.has(path);
+	}
+
+	reloadRoute(path: string): void {
+		if (this.isHotRoute(path)) {
+			// Trigger route reload without full page refresh
+			window.dispatchEvent(
+				new CustomEvent("router:reload", { detail: { path } }),
+			);
+		}
+	}
+
+	getState(): HMRState {
+		return { ...this.state, hotRoutes: new Set(this.state.hotRoutes) };
+	}
+}
+
+export const createHMRManager = (): HMRManager => {
+	return new HMRManager();
+};
+
+export const useHMR = (path: string) => {
+	const hmrManager = createHMRManager();
+
+	onMount(() => {
+		hmrManager.enableHotRoute(path);
+	});
+
+	onCleanup(() => {
+		hmrManager.disableHotRoute(path);
+	});
+
+	return {
+		isEnabled: hmrManager.getState().enabled,
+		reload: () => hmrManager.reloadRoute(path),
+	};
+};

package/src/router/presentation/solid/index.ts

@@ -0,0 +1,7 @@
+export * from "./components/router";
+export * from "./devtools/router-inspector";
+export * from "./hmr";
+export * from "./lazy-loading";
+export * from "./preloading";
+export * from "./route-state";
+export * from "./signals";

package/src/router/presentation/solid/lazy-loading.ts

@@ -0,0 +1,111 @@
+import { onCleanup, onMount } from "solid-js";
+
+export type LazyLoadTrigger = "viewport" | "hover" | "click" | "manual";
+
+export class LazyLoadManager {
+	private observers: Map<string, IntersectionObserver> = new Map();
+	private loadedElements: Set<string> = new Set();
+
+	loadOnViewport(
+		element: HTMLElement,
+		callback: () => void,
+		id?: string,
+	): void {
+		const elementId = this.getElementId(element, id);
+
+		if (this.loadedElements.has(elementId)) {
+			return;
+		}
+
+		const observer = new IntersectionObserver(
+			(entries) => {
+				entries.forEach((entry) => {
+					if (entry.isIntersecting) {
+						callback();
+						this.loadedElements.add(elementId);
+						observer.disconnect();
+					}
+				});
+			},
+			{ threshold: 0.1 },
+		);
+
+		observer.observe(element);
+		this.observers.set(elementId, observer);
+	}
+
+	loadOnHover(element: HTMLElement, callback: () => void, id?: string): void {
+		const elementId = this.getElementId(element, id);
+
+		const handleMouseEnter = () => {
+			callback();
+			this.loadedElements.add(elementId);
+		};
+
+		element.addEventListener("mouseenter", handleMouseEnter);
+	}
+
+	loadOnClick(element: HTMLElement, callback: () => void, id?: string): void {
+		const elementId = this.getElementId(element, id);
+
+		const handleClick = () => {
+			callback();
+			this.loadedElements.add(elementId);
+		};
+
+		element.addEventListener("click", handleClick);
+	}
+
+	private getElementId(element: HTMLElement, id?: string): string {
+		if (id) {
+			return id;
+		}
+
+		if (element.id) {
+			return element.id;
+		}
+
+		throw new Error(
+			"LazyLoadManager: an explicit id is required when the element has no id",
+		);
+	}
+
+	cleanup(): void {
+		for (const observer of this.observers.values()) {
+			observer.disconnect();
+		}
+		this.observers.clear();
+		this.loadedElements.clear();
+	}
+}
+
+export const createLazyLoadManager = (): LazyLoadManager => {
+	return new LazyLoadManager();
+};
+
+export const useLazyLoad = (
+	element: HTMLElement,
+	trigger: LazyLoadTrigger,
+	callback: () => void,
+	id?: string,
+) => {
+	const manager = createLazyLoadManager();
+
+	onMount(() => {
+		switch (trigger) {
+			case "viewport":
+				manager.loadOnViewport(element, callback, id);
+				break;
+			case "hover":
+				manager.loadOnHover(element, callback, id);
+				break;
+			case "click":
+				manager.loadOnClick(element, callback, id);
+				break;
+		}
+	});
+
+	onCleanup(() => {
+		manager.cleanup();
+	});
+};

package/src/router/presentation/solid/preloading.ts

@@ -0,0 +1,81 @@
+import { onCleanup } from "solid-js";
+import type { RouteConfig } from "#router/shared/types";
+
+export type PreloadStrategy = "hover" | "viewport" | "idle" | "manual";
+
+export class SignalRoutePreloader {
+	private preloadQueue: Set<string> = new Set();
+	private preloadStrategies: Map<string, PreloadStrategy> = new Map();
+
+	constructor(private routes: RouteConfig[]) {}
+
+	setPreloadStrategy(path: string, strategy: PreloadStrategy): void {
+		this.preloadStrategies.set(path, strategy);
+	}
+
+	preloadRoute(path: string): void {
+		if (this.preloadQueue.has(path)) return;
+
+		this.preloadQueue.add(path);
+		const route = this.routes.find((r) => r.path === path);
+
+		if (route?.component) {
+			route.component();
+		}
+	}
+
+	preloadOnHover(element: HTMLElement, path: string): void {
+		const handleMouseEnter = () => {
+			this.preloadRoute(path);
+		};
+
+		element.addEventListener("mouseenter", handleMouseEnter);
+		onCleanup(() => {
+			element.removeEventListener("mouseenter", handleMouseEnter);
+		});
+	}
+
+	preloadOnViewport(path: string, threshold = 0.1): void {
+		const observer = new IntersectionObserver(
+			(entries) => {
+				entries.forEach((entry) => {
+					if (entry.isIntersecting) {
+						this.preloadRoute(path);
+					}
+				});
+			},
+			{ threshold },
+		);
+
+		const links = document.querySelectorAll(`a[href="${path}"]`);
+		links.forEach((link) => {
+			observer.observe(link);
+		});
+
+		onCleanup(() => {
+			observer.disconnect();
+		});
+	}
+
+	preloadOnIdle(path: string): void {
+		if ("requestIdleCallback" in window) {
+			(window as any).requestIdleCallback(() => {
+				this.preloadRoute(path);
+			});
+		} else {
+			setTimeout(() => {
+				this.preloadRoute(path);
+			}, 1000);
+		}
+	}
+
+	getPreloadedRoutes(): string[] {
+		return Array.from(this.preloadQueue);
+	}
+}
+
+export const createSignalRoutePreloader = (
+	routes: RouteConfig[],
+): SignalRoutePreloader => {
+	return new SignalRoutePreloader(routes);
+};

package/src/router/presentation/solid/route-state.ts

@@ -0,0 +1,58 @@
+import { createEffect, createSignal } from "solid-js";
+
+export type RouteState<T = unknown> = {
+	data: T;
+	isLoading: boolean;
+	error: Error | null;
+};
+
+export class RouteStateManager {
+	private routeStates: Map<string, RouteState> = new Map();
+
+	setState<T>(path: string, state: Partial<RouteState<T>>): void {
+		const current = this.routeStates.get(path) || {
+			data: null,
+			isLoading: false,
+			error: null,
+		};
+		this.routeStates.set(path, { ...current, ...state });
+	}
+
+	getState<T>(path: string): RouteState<T> | undefined {
+		return this.routeStates.get(path) as RouteState<T> | undefined;
+	}
+
+	createSignal<T>(path: string) {
+		const [state, setState] = createSignal<RouteState<T>>(
+			(this.routeStates.get(path) || {
+				data: null,
+				isLoading: false,
+				error: null,
+			}) as RouteState<T>,
+		);
+
+		createEffect(() => {
+			setState(
+				(this.routeStates.get(path) || {
+					data: null,
+					isLoading: false,
+					error: null,
+				}) as RouteState<T>,
+			);
+		});
+
+		return state;
+	}
+
+	clearState(path: string): void {
+		this.routeStates.delete(path);
+	}
+
+	clearAllStates(): void {
+		this.routeStates.clear();
+	}
+}
+
+export const createRouteStateManager = (): RouteStateManager => {
+	return new RouteStateManager();
+};

package/src/router/presentation/solid/signals/index.ts

@@ -0,0 +1,2 @@
+export * from "./route-state";
+export * from "./search-params";

package/src/router/presentation/solid/signals/route-state.ts

@@ -0,0 +1,39 @@
+import { createSignal } from "solid-js";
+import type { RouteMatch } from "../../../shared/types";
+
+export const createRouteState = (initialRoute: RouteMatch | null = null) => {
+	const [currentRoute, setCurrentRoute] = createSignal<RouteMatch | null>(
+		initialRoute,
+	);
+	const [isLoading, setIsLoading] = createSignal(false);
+	const [error, setError] = createSignal<Error | null>(null);
+
+	const routerState = () => ({
+		currentRoute: currentRoute(),
+		isLoading: isLoading(),
+		error: error(),
+	});
+
+	const navigate = (route: RouteMatch) => {
+		setIsLoading(true);
+		setError(null);
+		setCurrentRoute(route);
+		setIsLoading(false);
+	};
+
+	const setErrorState = (err: Error) => {
+		setError(err);
+		setIsLoading(false);
+	};
+
+	return {
+		routerState,
+		currentRoute,
+		isLoading,
+		error,
+		navigate,
+		setErrorState,
+	};
+};
+
+export type RouteStateSignal = ReturnType<typeof createRouteState>;

package/src/router/presentation/solid/signals/search-params.ts

@@ -0,0 +1,31 @@
+import { createSignal } from "solid-js";
+import type { SearchParams } from "../../../shared/types";
+
+export const createSearchParams = (initial: SearchParams = {}) => {
+	const [params, setParams] = createSignal<SearchParams>(initial);
+
+	const setParam = (key: string, value: unknown) => {
+		setParams((prev) => ({ ...prev, [key]: value }));
+	};
+
+	const removeParam = (key: string) => {
+		setParams((prev) => {
+			const { [key]: _, ...rest } = prev;
+			return rest;
+		});
+	};
+
+	const clearParams = () => {
+		setParams({});
+	};
+
+	return {
+		params,
+		setParams,
+		setParam,
+		removeParam,
+		clearParams,
+	};
+};
+
+export type SearchParamsSignal = ReturnType<typeof createSearchParams>;

package/src/router/shared/constants/index.ts

@@ -0,0 +1,6 @@
+export const DEFAULT_ROUTE = "/";
+export const NOT_FOUND_ROUTE = "/404";
+export const ERROR_ROUTE = "/error";
+
+export const NAVIGATION_EVENT = "router:navigate";
+export const ROUTE_CHANGE_EVENT = "router:change";

package/src/router/shared/errors/enhanced-errors.ts

@@ -0,0 +1,94 @@
+export class RouterError extends Error {
+	constructor(
+		message: string,
+		public code: string,
+		public suggestions: string[] = [],
+		public context?: Record<string, unknown>,
+	) {
+		super(message);
+		this.name = "RouterError";
+	}
+
+	override toString(): string {
+		let output = `[${this.code}] ${this.message}\n`;
+
+		if (this.suggestions.length > 0) {
+			output += "\nSuggestions:\n";
+			for (const suggestion of this.suggestions) {
+				output += `  - ${suggestion}\n`;
+			}
+		}
+
+		if (this.context) {
+			output += "\nContext:\n";
+			for (const [key, value] of Object.entries(this.context)) {
+				output += `  ${key}: ${JSON.stringify(value)}\n`;
+			}
+		}
+
+		return output;
+	}
+}
+
+export const createRouteNotFoundError = (path: string): RouterError => {
+	return new RouterError(
+		`Route not found: ${path}`,
+		"ROUTE_NOT_FOUND",
+		[
+			"Check if the route path is correct",
+			"Ensure the route is registered in the router",
+			"Verify route parameters match the pattern",
+		],
+		{ path },
+	);
+};
+
+export const createParameterError = (
+	param: string,
+	expected: string,
+	received: unknown,
+): RouterError => {
+	return new RouterError(
+		`Invalid parameter: ${param}`,
+		"INVALID_PARAMETER",
+		[
+			`Expected type: ${expected}`,
+			`Received: ${typeof received}`,
+			"Check parameter validation schema",
+		],
+		{ param, expected, received },
+	);
+};
+
+export const createNavigationError = (
+	from: string,
+	to: string,
+	reason: string,
+): RouterError => {
+	return new RouterError(
+		`Navigation failed from ${from} to ${to}: ${reason}`,
+		"NAVIGATION_FAILED",
+		[
+			"Check if the target route exists",
+			"Verify route guards allow this navigation",
+			"Ensure navigation parameters are valid",
+		],
+		{ from, to, reason },
+	);
+};
+
+export const createGuardError = (
+	guardName: string,
+	reason: string,
+): RouterError => {
+	return new RouterError(
+		`Route guard failed: ${guardName}`,
+		"GUARD_FAILED",
+		[
+			"Check guard implementation",
+			"Verify guard conditions",
+			"Ensure user has required permissions",
+		],
+		{ guardName, reason },
+	);
+};

package/src/router/shared/errors/index.ts

@@ -0,0 +1,30 @@
+export class RouteNotFoundError extends Error {
+	constructor(path: string) {
+		super(`Route not found: ${path}`);
+		this.name = "RouteNotFoundError";
+	}
+}
+
+export class NavigationError extends Error {
+	constructor(to: string, reason: string) {
+		super(`Navigation to ${to} failed: ${reason}`);
+		this.name = "NavigationError";
+	}
+}
+
+export class DataLoadError extends Error {
+	constructor(route: string, cause: unknown) {
+		super(`Failed to load data for route ${route}: ${String(cause)}`);
+		this.name = "DataLoadError";
+		this.cause = cause;
+	}
+}
+
+export class ValidationError extends Error {
+	constructor(field: string, value: unknown) {
+		super(`Validation failed for ${field}: ${String(value)}`);
+		this.name = "ValidationError";
+	}
+}
+
+export * from "./enhanced-errors";

package/src/router/shared/index.ts

@@ -0,0 +1,4 @@
+export * from "./constants";
+export * from "./errors";
+export * from "./types";
+export * from "./utils";

package/src/router/shared/types/either.ts

@@ -0,0 +1,55 @@
+// Either type for handling two possible outcomes
+export type Either<L, R> =
+	| { left: L; right?: never }
+	| { right: R; left?: never };
+
+export const left = <L>(value: L): Either<L, never> => ({ left: value });
+
+export const right = <R>(value: R): Either<never, R> => ({ right: value });
+
+export const isLeft = <L, R>(either: Either<L, R>): either is { left: L } =>
+	"left" in either;
+
+export const isRight = <L, R>(either: Either<L, R>): either is { right: R } =>
+	"right" in either;
+
+export const fold = <L, R, T>(
+	either: Either<L, R>,
+	onLeft: (left: L) => T,
+	onRight: (right: R) => T,
+): T => {
+	if (isLeft(either)) {
+		return onLeft(either.left);
+	}
+	return onRight(either.right);
+};
+
+export const mapEither = <L, R, U>(
+	either: Either<L, R>,
+	fn: (right: R) => U,
+): Either<L, U> => {
+	if (isRight(either)) {
+		return right(fn(either.right));
+	}
+	return either;
+};
+
+export const mapLeft = <L, R, U>(
+	either: Either<L, R>,
+	fn: (left: L) => U,
+): Either<U, R> => {
+	if (isLeft(either)) {
+		return left(fn(either.left));
+	}
+	return either;
+};
+
+export const chainEither = <L, R, U>(
+	either: Either<L, R>,
+	fn: (right: R) => Either<L, U>,
+): Either<L, U> => {
+	if (isRight(either)) {
+		return fn(either.right);
+	}
+	return either;
+};

package/src/router/shared/types/index.ts

@@ -0,0 +1,5 @@
+export * from "./either";
+export * from "./option";
+export * from "./result";
+export * from "./route-inference";
+export * from "./routing";

package/src/router/shared/types/option.ts

@@ -0,0 +1,20 @@
+// Option type for nullable values
+export type Option<T> = T | null;
+
+export const some = <T>(value: T): Option<T> => value;
+
+export const none = (): Option<never> => null;
+
+export const mapOption = <T, U>(
+	option: Option<T>,
+	fn: (value: T) => U,
+): Option<U> => {
+	if (option === null) {
+		return null;
+	}
+	return fn(option);
+};
+
+export const unwrapOr = <T>(option: Option<T>, defaultValue: T): T => {
+	return option === null ? defaultValue : option;
+};