@wrikka/solid-framework 0.0.0-stage → 0.15.0

package/src/render/presentation/RemoteIsland.tsx

@@ -0,0 +1,68 @@
+/**
+ * RemoteIsland — embed an island rendered by another origin
+ * (or this app's `/_island` endpoint). The fragment arrives as
+ * HTML and is injected as-is; hydrate it by shipping the remote
+ * app's island bundle, or leave it static.
+ *
+ *   <RemoteIsland src="https://cms.example.com/_island/Banner"
+ *                 props={{ theme: "dark" }}
+ *                 fallback={<Spinner />} />
+ */
+
+import { createResource, type JSX, onCleanup, onMount, Show } from "solid-js";
+import { isServer } from "solid-js/web";
+
+export interface RemoteIslandProps {
+	/** Island endpoint URL — `/_island/<name>` on any origin */
+	src: string;
+	/** Serialized into `?props=<json>` — keep it JSON-safe */
+	props?: Record<string, unknown>;
+	fallback?: JSX.Element;
+	/**
+	 * Client bundle URL that registers the island — imported on
+	 * mount, then the injected markup is hydrated in place
+	 */
+	hydrate?: string;
+}
+
+const islandUrl = (src: string, props?: Record<string, unknown>): string =>
+	props ? `${src}?props=${encodeURIComponent(JSON.stringify(props))}` : src;
+
+const fetchIsland = async (src: string): Promise<string> => {
+	const response = await fetch(src);
+	if (!response.ok) {
+		throw new Error(
+			`[solid-framework] remote island ${src} → ${response.status}`,
+		);
+	}
+	return response.text();
+};
+
+export const RemoteIsland = (props: RemoteIslandProps): JSX.Element => {
+	const url = islandUrl(props.src, props.props);
+	const [html] = createResource(url, fetchIsland);
+	let host: HTMLDivElement | undefined;
+	let disposers: Array<() => void> = [];
+	onCleanup(() => {
+		for (const dispose of disposers) dispose();
+	});
+
+	onMount(() => {
+		if (isServer || !props.hydrate) return;
+		const load = async () => {
+			await import(/* @vite-ignore */ props.hydrate as string);
+			// wait one tick for the fragment to land in the DOM
+			await Promise.resolve();
+			if (!host) return;
+			const { hydrateIslands } = await import("./Island");
+			disposers = hydrateIslands(host);
+		};
+		void load();
+	});
+
+	return (
+		<Show when={html()} fallback={props.fallback}>
+			<div ref={host} data-remote-island={props.src} innerHTML={html()} />
+		</Show>
+	);
+};

package/src/render/presentation/entries.ts

@@ -0,0 +1,83 @@
+/**
+ * Entry Helpers
+ * Conventional server/client entry points for SSR apps
+ */
+
+import { wrapAppProviders } from "#app/presentation/providers";
+import { hydrateApp } from "#render/adapters/solid-web/hydration";
+import { createSolidServerRenderer } from "#render/adapters/solid-web/renderer";
+import {
+	renderPage,
+	streamPage,
+} from "#render/modules/render/application/usecases";
+import {
+	createRenderContext,
+	hydrationScriptTag,
+	readHydrationPayload,
+} from "#render/modules/render/domain";
+import type { Renderable, RenderMode } from "#render/types";
+
+export interface ServerEntryOptions {
+	mode?: RenderMode;
+	title?: string;
+	lang?: string;
+}
+
+export type ServerEntryHandler = (request: Request) => Promise<Response>;
+
+/**
+ * Create a fetch-style server handler that SSRs the renderable.
+ * Works with Bun.serve, web-server adapters, and edge runtimes.
+ */
+export const createServerEntry = (
+	renderable: Renderable,
+	options: ServerEntryOptions = {},
+): ServerEntryHandler => {
+	const renderer = createSolidServerRenderer();
+	const mode = options.mode ?? "stream";
+
+	return async (request: Request): Promise<Response> => {
+		const context = createRenderContext(mode, request);
+
+		if (mode === "stream") {
+			return streamPage(renderer, {
+				renderable,
+				options: { context },
+			});
+		}
+
+		const { html } = await renderPage(renderer, {
+			renderable,
+			options: { context },
+			title: options.title,
+			lang: options.lang,
+		});
+
+		return new Response(html, {
+			headers: { "Content-Type": "text/html; charset=utf-8" },
+		});
+	};
+};
+
+export interface ClientEntryOptions {
+	element?: Element | null;
+}
+
+/**
+ * Hydrate the SSR markup on the client (conventional entry-client).
+ * Wraps the app in the same provider stack as the server entry —
+ * hydration keys must match or hydrate() reports a mismatch.
+ */
+export const createClientEntry = (
+	renderable: Renderable,
+	options: ClientEntryOptions = {},
+): (() => void) =>
+	hydrateApp(
+		wrapAppProviders(renderable, {
+			request: new Request(window.location.href),
+			hydration: readHydrationPayload(),
+		}),
+		options.element ?? document.getElementById("app"),
+	);
+
+export { hydrationScriptTag };

package/src/render/presentation/index.ts

@@ -0,0 +1,5 @@
+export * from "./ClientComponent";
+export * from "./Document";
+export * from "./entries";
+export * from "./Island";
+export * from "./RemoteIsland";

package/src/render/shared/index.ts

@@ -0,0 +1,2 @@
+export * from "./types";
+export * from "./utils";

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

@@ -0,0 +1,9 @@
+/**
+ * Shared Render Types
+ */
+
+export interface Result<T, E = Error> {
+	success: boolean;
+	data?: T;
+	error?: E;
+}

package/src/render/shared/utils/index.ts

@@ -0,0 +1 @@
+export * from "./result";

package/src/render/shared/utils/result.ts

@@ -0,0 +1,30 @@
+/**
+ * Result Utility
+ * Functional implementation of Result type for error handling
+ */
+
+import type { Result } from "#render/shared/types";
+
+export const ok = <T>(data: T): Result<T> => ({
+	success: true,
+	data,
+});
+
+export const err = <E = Error>(error: E): Result<never, E> => ({
+	success: false,
+	error,
+});
+
+export const isOk = <T, E>(
+	result: Result<T, E>,
+): result is { success: true; data: T } => result.success;
+
+export const isErr = <T, E>(
+	result: Result<T, E>,
+): result is { success: false; error: E } => !result.success;
+
+export const unwrap = <T, E>(result: Result<T, E>, defaultValue?: T): T => {
+	if (isOk(result)) return result.data as T;
+	if (defaultValue !== undefined) return defaultValue;
+	throw (result as { success: false; error: E }).error;
+};

package/src/render/types/index.ts

@@ -0,0 +1,58 @@
+/**
+ * Render Domain Types
+ * Shared types for SSR, streaming, CSR and island rendering
+ */
+
+import type { JSX } from "solid-js";
+
+export type RenderMode = "ssr" | "stream" | "csr" | "islands";
+
+/**
+ * Data serialized into the HTML document and read back during client hydration
+ */
+export interface HydrationPayload {
+	loaders: Record<string, unknown>;
+	stores: Record<string, unknown>;
+	/** Server-component markup — hydrated verbatim, no client JS runs */
+	components?: Record<string, string>;
+	/** Deferred loader values resolved before serialization (ssr mode) */
+	deferred?: Record<string, unknown>;
+	route?: string;
+	meta?: Record<string, unknown>;
+}
+
+/**
+ * Static assets collected by the build that must be referenced by the document
+ */
+export interface DocumentAssets {
+	entry?: string;
+	css?: string[];
+	js?: string[];
+	preload?: string[];
+}
+
+/**
+ * Per-request render context shared across the render pipeline
+ */
+export interface RenderContext {
+	mode: RenderMode;
+	request?: Request;
+	hydration: HydrationPayload;
+	head?: { renderToString(): string };
+}
+
+export interface RenderResult {
+	html: string;
+	hydration: HydrationPayload;
+}
+
+/**
+ * A renderable is anything the Solid renderer can turn into markup
+ */
+export type Renderable = () => JSX.Element;
+
+export interface RenderOptions {
+	mode?: RenderMode;
+	context?: RenderContext;
+	nonce?: string;
+}

package/src/router/adapters/index.ts

@@ -0,0 +1 @@
+export * from "./solid-start";

package/src/router/adapters/solid-start/index.ts

@@ -0,0 +1,42 @@
+import type { RouteConfig } from "#router/shared/types";
+
+// Pure function to configure routes
+export const configureRoutesAdapter = (
+	_currentRoutes: RouteConfig[],
+	newRoutes: RouteConfig[],
+): RouteConfig[] => {
+	return [...newRoutes];
+};
+
+// Pure function to get route tree
+export const getRouteTreeAdapter = (routes: RouteConfig[]): RouteConfig[] => {
+	return [...routes];
+};
+
+// Pure function for file-based routing with @solidjs/start
+export const createFileBasedRoutes = (
+	fileSystem: Record<string, () => unknown>,
+): RouteConfig[] => {
+	return Object.entries(fileSystem).map(([path, component]) => ({
+		path:
+			path
+				.replace(/\.tsx?$/, "")
+				.replace(/\/index$/, "")
+				.replace(/\[(\w+)\]/g, ":$1")
+				.replace(/^/, "/")
+				.replace(/\/$/, "/") || "/",
+		component,
+	}));
+};
+
+// Pure function to convert file path to route path
+export const filePathToRoutePath = (filePath: string): string => {
+	return (
+		filePath
+			.replace(/\.tsx?$/, "")
+			.replace(/\/index$/, "")
+			.replace(/\[(\w+)\]/g, ":$1")
+			.replace(/^/, "/")
+			.replace(/\/$/, "/") || "/"
+	);
+};

package/src/router/cli/bundle-analyzer.ts

@@ -0,0 +1,142 @@
+export type BundleSize = {
+	name: string;
+	size: number;
+	gzipped: number;
+	percentage: number;
+};
+
+export type BundleAnalysis = {
+	totalSize: number;
+	totalGzipped: number;
+	chunks: BundleSize[];
+	largestChunks: BundleSize[];
+	recommendations: string[];
+};
+
+export class BundleAnalyzer {
+	analyze(): BundleAnalysis {
+		const chunks = this.analyzeChunks();
+		const totalSize = chunks.reduce((sum, chunk) => sum + chunk.size, 0);
+		const totalGzipped = chunks.reduce((sum, chunk) => sum + chunk.gzipped, 0);
+
+		const chunksWithPercentage = chunks.map((chunk) => ({
+			...chunk,
+			percentage: (chunk.size / totalSize) * 100,
+		}));
+
+		const largestChunks = chunksWithPercentage
+			.sort((a, b) => b.size - a.size)
+			.slice(0, 10);
+
+		const recommendations = this.generateRecommendations(
+			chunksWithPercentage,
+			totalSize,
+		);
+
+		return {
+			totalSize,
+			totalGzipped,
+			chunks: chunksWithPercentage,
+			largestChunks,
+			recommendations,
+		};
+	}
+
+	private analyzeChunks(): BundleSize[] {
+		// In a real implementation, this would read the actual build output
+		// For now, we'll return mock data based on the package structure
+
+		const mockChunks: BundleSize[] = [
+			{ name: "router-core.js", size: 30000, gzipped: 10000, percentage: 0 },
+			{
+				name: "router-optimization.js",
+				size: 15000,
+				gzipped: 5000,
+				percentage: 0,
+			},
+			{ name: "router-devtools.js", size: 8000, gzipped: 2500, percentage: 0 },
+			{ name: "router-hmr.js", size: 5000, gzipped: 1500, percentage: 0 },
+			{
+				name: "router-lazy-loading.js",
+				size: 4000,
+				gzipped: 1200,
+				percentage: 0,
+			},
+		];
+
+		return mockChunks;
+	}
+
+	private generateRecommendations(
+		chunks: BundleSize[],
+		totalSize: number,
+	): string[] {
+		const recommendations: string[] = [];
+
+		// Check for large chunks
+		const largeChunks = chunks.filter((chunk) => chunk.percentage > 10);
+		if (largeChunks.length > 0) {
+			recommendations.push(
+				`Consider code splitting these large chunks: ${largeChunks
+					.map((c) => c.name)
+					.join(", ")}`,
+			);
+		}
+
+		// Check for duplicate code
+		if (totalSize > 100000) {
+			recommendations.push(
+				"Total bundle size is large. Consider using dynamic imports for rarely used features.",
+			);
+		}
+
+		// Check for devtools in production
+		const devtoolsChunk = chunks.find((c) => c.name.includes("devtools"));
+		if (devtoolsChunk) {
+			recommendations.push(
+				"DevTools should be excluded from production builds.",
+			);
+		}
+
+		// Check for HMR in production
+		const hmrChunk = chunks.find((c) => c.name.includes("hmr"));
+		if (hmrChunk) {
+			recommendations.push("HMR should be excluded from production builds.");
+		}
+
+		if (recommendations.length === 0) {
+			recommendations.push("Bundle size looks good! No major issues detected.");
+		}
+
+		return recommendations;
+	}
+
+	printAnalysis(analysis: BundleAnalysis): void {
+		console.log("\n=== Bundle Size Analysis ===\n");
+		console.log(`Total Size: ${this.formatSize(analysis.totalSize)}`);
+		console.log(`Total Gzipped: ${this.formatSize(analysis.totalGzipped)}\n`);
+
+		console.log("=== Largest Chunks ===\n");
+		for (const chunk of analysis.largestChunks) {
+			console.log(
+				`${chunk.name}: ${this.formatSize(chunk.size)} (${chunk.percentage.toFixed(1)}%)`,
+			);
+		}
+
+		console.log("\n=== Recommendations ===\n");
+		for (const recommendation of analysis.recommendations) {
+			console.log(`- ${recommendation}`);
+		}
+		console.log();
+	}
+
+	private formatSize(bytes: number): string {
+		if (bytes < 1024) return `${bytes} B`;
+		if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(2)} KB`;
+		return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+	}
+}
+
+export const createBundleAnalyzer = (): BundleAnalyzer => {
+	return new BundleAnalyzer();
+};

package/src/router/cli/index.ts

@@ -0,0 +1,3 @@
+export * from "./bundle-analyzer";
+export * from "./migration-cli";
+export * from "./route-generator";

package/src/router/cli/migration-cli.ts

@@ -0,0 +1,217 @@
+#!/usr/bin/env bun
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+
+interface MigrationConfig {
+	source: "tanstack" | "react-router" | "vue-router";
+	target: string;
+	input: string;
+	output?: string;
+}
+
+interface MigrationResult {
+	success: boolean;
+	transformedFiles: string[];
+	errors: string[];
+}
+
+class MigrationCLI {
+	async migrate(config: MigrationConfig): Promise<MigrationResult> {
+		const result: MigrationResult = {
+			success: false,
+			transformedFiles: [],
+			errors: [],
+		};
+
+		try {
+			switch (config.source) {
+				case "tanstack":
+					await this.migrateFromTanStack(config, result);
+					break;
+				case "react-router":
+					await this.migrateFromReactRouter(config, result);
+					break;
+				case "vue-router":
+					await this.migrateFromVueRouter(config, result);
+					break;
+				default:
+					result.errors.push(`Unsupported source: ${config.source}`);
+					return result;
+			}
+
+			result.success = result.errors.length === 0;
+		} catch (error) {
+			result.errors.push(
+				error instanceof Error ? error.message : String(error),
+			);
+		}
+
+		return result;
+	}
+
+	private async migrateFromTanStack(
+		config: MigrationConfig,
+		result: MigrationResult,
+	): Promise<void> {
+		const inputPath = config.input;
+		const outputPath = config.output || inputPath;
+
+		if (!existsSync(inputPath)) {
+			result.errors.push(`Input file not found: ${inputPath}`);
+			return;
+		}
+
+		const content = readFileSync(inputPath, "utf-8");
+		let transformed = content;
+
+		// Transform createRoute to SolidJS createRoute
+		transformed = transformed.replace(/createRoute\(/g, "createSolidRoute(");
+
+		// Transform createRouter to SolidJS createRouteMatcher
+		transformed = transformed.replace(/createRouter\(/g, "createRouteMatcher(");
+
+		// Transform useNavigate to SolidJS navigate
+		transformed = transformed.replace(
+			/useNavigate\(\)/g,
+			"createNavigationService()",
+		);
+
+		// Transform useParams to SolidJS route params
+		transformed = transformed.replace(
+			/useParams\(\)/g,
+			"createRouteState().params()",
+		);
+
+		// Transform useSearchParams to SolidJS search params
+		transformed = transformed.replace(
+			/useSearchParams\(\)/g,
+			"createSearchParams()",
+		);
+
+		writeFileSync(outputPath, transformed, "utf-8");
+		result.transformedFiles.push(outputPath);
+	}
+
+	private async migrateFromReactRouter(
+		config: MigrationConfig,
+		result: MigrationResult,
+	): Promise<void> {
+		const inputPath = config.input;
+		const outputPath = config.output || inputPath;
+
+		if (!existsSync(inputPath)) {
+			result.errors.push(`Input file not found: ${inputPath}`);
+			return;
+		}
+
+		const content = readFileSync(inputPath, "utf-8");
+		let transformed = content;
+
+		// Transform <Routes> to SolidJS Router
+		transformed = transformed.replace(/<Routes>/g, "<Router>");
+
+		// Transform <Route> to SolidJS route
+		transformed = transformed.replace(
+			/<Route path="([^"]*)"/g,
+			'<Route path="$1" component={() => import("$1")}',
+		);
+
+		// Transform useNavigate to SolidJS navigate
+		transformed = transformed.replace(
+			/useNavigate\(\)/g,
+			"createNavigationService()",
+		);
+
+		// Transform useParams to SolidJS route params
+		transformed = transformed.replace(
+			/useParams\(\)/g,
+			"createRouteState().params()",
+		);
+
+		// Transform useSearchParams to SolidJS search params
+		transformed = transformed.replace(
+			/useSearchParams\(\)/g,
+			"createSearchParams()",
+		);
+
+		writeFileSync(outputPath, transformed, "utf-8");
+		result.transformedFiles.push(outputPath);
+	}
+
+	private async migrateFromVueRouter(
+		config: MigrationConfig,
+		result: MigrationResult,
+	): Promise<void> {
+		const inputPath = config.input;
+		const outputPath = config.output || inputPath;
+
+		if (!existsSync(inputPath)) {
+			result.errors.push(`Input file not found: ${inputPath}`);
+			return;
+		}
+
+		const content = readFileSync(inputPath, "utf-8");
+		let transformed = content;
+
+		// Transform router.push to SolidJS navigate
+		transformed = transformed.replace(
+			/router\.push\(/g,
+			"createNavigationService().navigate(",
+		);
+
+		// Transform router.replace to SolidJS navigate with replace
+		transformed = transformed.replace(
+			/router\.replace\(/g,
+			"createNavigationService().navigate(",
+		);
+
+		// Transform useRoute to SolidJS route state
+		transformed = transformed.replace(/useRoute\(\)/g, "createRouteState()");
+
+		// Transform useRouter to SolidJS navigation service
+		transformed = transformed.replace(
+			/useRouter\(\)/g,
+			"createNavigationService()",
+		);
+
+		writeFileSync(outputPath, transformed, "utf-8");
+		result.transformedFiles.push(outputPath);
+	}
+}
+
+// CLI entry point
+async function main() {
+	const args = process.argv.slice(2);
+
+	if (args.length < 3) {
+		console.error("Usage: migration-cli <source> <input> [output]");
+		console.error("Sources: tanstack, react-router, vue-router");
+		process.exit(1);
+	}
+
+	const [source, input, output] = args;
+
+	const cli = new MigrationCLI();
+	const result = await cli.migrate({
+		source: source as MigrationConfig["source"],
+		target: "solid-framework",
+		input,
+		output,
+	});
+
+	if (result.success) {
+		console.log("Migration successful!");
+		console.log("Transformed files:", result.transformedFiles);
+	} else {
+		console.error("Migration failed!");
+		result.errors.forEach((error) => {
+			console.error("Error:", error);
+		});
+		process.exit(1);
+	}
+}
+
+if (import.meta.main) {
+	main();
+}
+
+export { MigrationCLI, type MigrationConfig, type MigrationResult };