@ecopages/core 0.2.0-alpha.27 → 0.2.0-alpha.28

package/src/route-renderer/route-renderer.ts

@@ -1,133 +0,0 @@
-import type { EcoPagesAppConfig } from '../types/internal-types.ts';
-import type { IntegrationPlugin } from '../plugins/integration-plugin.ts';
-import { invariant } from '../utils/invariant.ts';
-import { PathUtils } from '../utils/path-utils.module.ts';
-import type { IntegrationRenderer } from './orchestration/integration-renderer.ts';
-
-/**
- * Narrow route-render contract exposed to higher-level routing code.
- *
- * @remarks
- * Higher-level routing code only needs request execution and page-module
- * loading. Returning this narrowed shape avoids a dedicated wrapper class while
- * still keeping callers off the full integration renderer surface.
- */
-export type PageRouteRenderer = Pick<IntegrationRenderer, 'execute' | 'loadPageModule'>;
-
-/**
- * Narrow explicit-view render contract exposed to static route handling.
- *
- * @remarks
- * Explicit static routes only need `renderToResponse()`, so the factory can
- * hide the broader integration renderer surface there as well.
- */
-export type ExplicitViewRenderer = Pick<IntegrationRenderer, 'renderToResponse'>;
-
-export interface PageRendererResolver {
-	getPageRenderer(filePath: string): PageRouteRenderer;
-}
-
-export interface ExplicitViewRendererResolver {
-	getExplicitViewRenderer(integrationName: string): ExplicitViewRenderer | null;
-}
-
-/**
- * Combined renderer-factory contract used by static generation.
- */
-export type StaticGenerationRendererResolver = PageRendererResolver & ExplicitViewRendererResolver;
-
-/**
- * Selects and caches integration renderers for route files and explicit views.
- *
- * @remarks
- * The factory owns the policy that maps a route file or explicit integration
- * name to one initialized integration renderer. Renderer instances are cached by
- * integration name so repeated requests do not rebuild renderer state.
- */
-export class RouteRendererFactory {
-	private appConfig: EcoPagesAppConfig;
-	runtimeOrigin: string;
-	private rendererModules?: unknown;
-	private rendererCache = new Map<string, IntegrationRenderer>();
-
-	/**
-	 * Creates the route-renderer factory for one app/runtime instance.
-	 */
-	constructor({
-		appConfig,
-		rendererModules,
-		runtimeOrigin,
-	}: {
-		appConfig: EcoPagesAppConfig;
-		rendererModules?: unknown;
-		runtimeOrigin: string;
-	}) {
-		this.appConfig = appConfig;
-		this.rendererModules = rendererModules;
-		this.runtimeOrigin = runtimeOrigin;
-	}
-
-	/**
-	 * Returns a route renderer for the supplied route file.
-	 */
-	getPageRenderer(filePath: string): PageRouteRenderer {
-		const integrationRenderer = this.getRouteRendererEngine(filePath);
-		invariant(!!integrationRenderer, `No integration renderer found for file: ${filePath}`);
-		return integrationRenderer;
-	}
-
-	/**
-	 * Returns a renderer for an explicit view integration.
-	 */
-	getExplicitViewRenderer(integrationName: string): ExplicitViewRenderer | null {
-		const integrationPlugin = this.appConfig.integrations.find((plugin) => plugin.name === integrationName);
-		if (!integrationPlugin) {
-			return null;
-		}
-
-		const cached = this.rendererCache.get(integrationName);
-		if (cached) {
-			return cached;
-		}
-
-		const renderer = integrationPlugin.initializeRenderer({
-			rendererModules: this.rendererModules,
-		});
-		this.rendererCache.set(integrationName, renderer);
-		return renderer;
-	}
-
-	/**
-	 * Resolves the integration plugin that owns a given route file.
-	 */
-	getIntegrationPlugin(filePath: string): IntegrationPlugin {
-		const templateExtension = PathUtils.getEcoTemplateExtension(filePath);
-		const isIntegrationPlugin = (plugin: IntegrationPlugin): boolean => {
-			return plugin.extensions.some((extension) => templateExtension === extension);
-		};
-		const integrationPlugin = this.appConfig.integrations.find(isIntegrationPlugin);
-		invariant(
-			!!integrationPlugin,
-			`No integration plugin found for template extension: ${templateExtension}, file: ${filePath}`,
-		);
-		return integrationPlugin as IntegrationPlugin;
-	}
-
-	/**
-	 * Returns the cached renderer engine for the file's owning integration,
-	 * creating it on first use.
-	 */
-	private getRouteRendererEngine(filePath: string): IntegrationRenderer {
-		const integrationPlugin = this.getIntegrationPlugin(filePath);
-		const cached = this.rendererCache.get(integrationPlugin.name);
-		if (cached) {
-			return cached;
-		}
-
-		const renderer = integrationPlugin.initializeRenderer({
-			rendererModules: this.rendererModules,
-		});
-		this.rendererCache.set(integrationPlugin.name, renderer);
-		return renderer;
-	}
-}

package/src/router/client/link-intent.test.browser.ts

@@ -1,51 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { getAnchorFromNavigationEvent, recoverPendingNavigationHref } from './link-intent.ts';
-
-describe('getAnchorFromNavigationEvent', () => {
-	it('returns the anchor when the event target is a text node inside it', () => {
-		const anchor = document.createElement('a');
-		anchor.href = '/fast';
-		anchor.setAttribute('data-eco-link', 'true');
-		const textNode = document.createTextNode('fast-link');
-		anchor.append(textNode);
-		document.body.append(anchor);
-
-		const event = new MouseEvent('click', { bubbles: true, cancelable: true, composed: true });
-		Object.defineProperty(event, 'target', {
-			configurable: true,
-			value: textNode,
-		});
-
-		expect(getAnchorFromNavigationEvent(event, 'a[data-eco-link]')).toBe(anchor);
-	});
-
-	it('returns the closest matching anchor for nested element targets', () => {
-		const anchor = document.createElement('a');
-		anchor.href = '/fast';
-		anchor.setAttribute('data-eco-link', 'true');
-		const span = document.createElement('span');
-		span.textContent = 'fast-link';
-		anchor.append(span);
-		document.body.append(anchor);
-
-		const event = new MouseEvent('click', { bubbles: true, cancelable: true, composed: true });
-		Object.defineProperty(event, 'target', {
-			configurable: true,
-			value: span,
-		});
-
-		expect(getAnchorFromNavigationEvent(event, 'a[data-eco-link]')).toBe(anchor);
-	});
-});
-
-describe('recoverPendingNavigationHref', () => {
-	it('returns null for stale or missing pending intent state', () => {
-		expect(recoverPendingNavigationHref(null, true, 10)).toBeNull();
-		expect(recoverPendingNavigationHref({ href: '/fast', timestamp: 0 }, false, 10)).toBeNull();
-		expect(recoverPendingNavigationHref({ href: '/fast', timestamp: 0 }, true, 2000, 1000)).toBeNull();
-	});
-
-	it('returns the captured href while a navigation is still in flight', () => {
-		expect(recoverPendingNavigationHref({ href: '/fast', timestamp: 10 }, true, 20, 1000)).toBe('/fast');
-	});
-});

package/src/router/client/link-intent.ts

@@ -1,92 +0,0 @@
-/**
- * Shared client-side navigation intent helpers.
- *
- * Browser runtimes use the same low-level mechanics to:
- * - locate the anchor associated with a click, pointer, or hover event,
- * - persist the last valid pointer or hover target while a navigation is in flight,
- * - recover the final intended href when the DOM changes before the click lands.
- *
- * Keeping those mechanics here lets browser-router and react-router share one
- * implementation while preserving their router-specific interception rules.
- *
- * @module
- */
-
-/**
- * Timestamped navigation intent captured from pointer or hover activity.
- */
-export type EcoPendingNavigationIntent = {
-	href: string;
-	timestamp: number;
-};
-
-/**
- * Finds the nearest matching anchor within an event's composed path.
- *
- * This works across Shadow DOM boundaries, which is required for delegated
- * navigation handling when links are rendered inside custom elements.
- *
- * @param event - Pointer or mouse event being inspected.
- * @param linkSelector - Selector that identifies navigable anchors.
- * @returns The matched anchor element, or `null` when no matching anchor exists.
- */
-export function getAnchorFromNavigationEvent(
-	event: MouseEvent | PointerEvent,
-	linkSelector: string,
-): HTMLAnchorElement | null {
-	const eventTarget = event.target;
-
-	if (eventTarget instanceof HTMLAnchorElement && eventTarget.matches(linkSelector)) {
-		return eventTarget;
-	}
-
-	if (eventTarget instanceof Element) {
-		const closestAnchor = eventTarget.closest(linkSelector);
-		if (closestAnchor instanceof HTMLAnchorElement) {
-			return closestAnchor;
-		}
-	}
-
-	if (eventTarget instanceof Text) {
-		const parentAnchor = eventTarget.parentElement?.closest(linkSelector);
-		if (parentAnchor instanceof HTMLAnchorElement) {
-			return parentAnchor;
-		}
-	}
-
-	return event
-		.composedPath()
-		.find(
-			(target) => target instanceof HTMLAnchorElement && target.matches(linkSelector),
-		) as HTMLAnchorElement | null;
-}
-
-/**
- * Resolves a previously captured intent while a navigation is still in flight.
- *
- * Pending intents expire quickly because they are only meant to bridge the gap
- * between pointer or hover capture and the later click event when the DOM or
- * active runtime changes during a rapid navigation sequence.
- *
- * @param intent - Previously captured pointer or hover intent.
- * @param hasInFlightNavigation - Whether a router navigation is still active.
- * @param now - Current monotonic timestamp, usually from `performance.now()`.
- * @param maxAgeMs - Maximum allowed age for the recovered intent.
- * @returns The intended href when still valid, otherwise `null`.
- */
-export function recoverPendingNavigationHref(
-	intent: EcoPendingNavigationIntent | null,
-	hasInFlightNavigation: boolean,
-	now: number,
-	maxAgeMs = 1000,
-): string | null {
-	if (!intent || !hasInFlightNavigation) {
-		return null;
-	}
-
-	if (now - intent.timestamp > maxAgeMs) {
-		return null;
-	}
-
-	return intent.href;
-}

package/src/router/client/navigation-coordinator.test.ts

@@ -1,237 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-import { getEcoNavigationRuntime } from './navigation-coordinator.ts';
-
-function createWindowLike() {
-	return {} as Window &
-		typeof globalThis & {
-			__ECO_PAGES__?: { navigation?: ReturnType<typeof getEcoNavigationRuntime> };
-		};
-}
-
-describe('getEcoNavigationRuntime', () => {
-	it('returns the same coordinator instance for the same window', () => {
-		const windowLike = createWindowLike();
-		const first = getEcoNavigationRuntime(windowLike);
-		const second = getEcoNavigationRuntime(windowLike);
-
-		expect(first).toBe(second);
-	});
-
-	it('tracks explicit ownership claims', () => {
-		const windowLike = createWindowLike();
-		const runtime = getEcoNavigationRuntime(windowLike);
-
-		runtime.claimOwnership('react-router');
-
-		expect(runtime.getOwnerState()).toEqual({
-			owner: 'react-router',
-			canHandleSpaNavigation: false,
-		});
-	});
-
-	it('shares one navigation transaction sequence across runtimes', () => {
-		const windowLike = createWindowLike();
-		const runtime = getEcoNavigationRuntime(windowLike);
-
-		const first = runtime.beginNavigationTransaction();
-		expect(runtime.hasPendingNavigationTransaction()).toBe(true);
-		expect(first.isCurrent()).toBe(true);
-		expect(first.signal.aborted).toBe(false);
-
-		const second = runtime.beginNavigationTransaction();
-
-		expect(first.isCurrent()).toBe(false);
-		expect(first.signal.aborted).toBe(true);
-		expect(second.isCurrent()).toBe(true);
-		expect(second.signal.aborted).toBe(false);
-		second.complete();
-		expect(runtime.hasPendingNavigationTransaction()).toBe(false);
-	});
-
-	it('cancels only the current navigation transaction', () => {
-		const windowLike = createWindowLike();
-		const runtime = getEcoNavigationRuntime(windowLike);
-
-		const first = runtime.beginNavigationTransaction();
-		const second = runtime.beginNavigationTransaction();
-
-		first.cancel();
-		expect(second.isCurrent()).toBe(true);
-		expect(second.signal.aborted).toBe(false);
-
-		second.cancel();
-		expect(second.isCurrent()).toBe(false);
-		expect(second.signal.aborted).toBe(true);
-		expect(runtime.hasPendingNavigationTransaction()).toBe(false);
-	});
-
-	it('adopts ownership from the rendered document marker', () => {
-		const windowLike = createWindowLike();
-		const runtime = getEcoNavigationRuntime(windowLike);
-		const documentLike = {
-			documentElement: {
-				getAttribute: vi.fn(() => 'custom-router'),
-			},
-		} as unknown as Document;
-
-		expect(runtime.adoptDocumentOwner(documentLike, 'browser-router')).toBe('custom-router');
-		expect(runtime.getOwnerState().owner).toBe('custom-router');
-	});
-
-	it('delegates navigation to another registered runtime when the source cannot handle it', async () => {
-		const windowLike = createWindowLike();
-		const runtime = getEcoNavigationRuntime(windowLike);
-		const navigateSpy = vi.fn(async () => true);
-
-		runtime.register({ owner: 'browser-router', navigate: navigateSpy });
-		runtime.register({ owner: 'react-router', navigate: vi.fn(async () => true) });
-		runtime.claimOwnership('react-router');
-
-		const handled = await runtime.requestNavigation({
-			href: '/docs',
-			direction: 'forward',
-			source: 'react-router',
-		});
-
-		expect(handled).toBe(true);
-		expect(navigateSpy).toHaveBeenCalledWith({
-			href: '/docs',
-			direction: 'forward',
-			source: 'react-router',
-		});
-	});
-
-	it('delegates a fetched document handoff to the targeted runtime without forcing source cleanup first', async () => {
-		const windowLike = createWindowLike();
-		const runtime = getEcoNavigationRuntime(windowLike);
-		const cleanupSpy = vi.fn(async () => undefined);
-		const handoffSpy = vi.fn(async () => true);
-		const documentLike = {
-			documentElement: {
-				getAttribute: vi.fn(() => null),
-			},
-		} as unknown as Document;
-
-		runtime.register({ owner: 'react-router', cleanupBeforeHandoff: cleanupSpy });
-		runtime.register({ owner: 'browser-router', handoffNavigation: handoffSpy });
-		runtime.claimOwnership('react-router');
-
-		const handled = await runtime.requestHandoff({
-			href: '/docs',
-			finalHref: '/docs',
-			direction: 'forward',
-			source: 'react-router',
-			targetOwner: 'browser-router',
-			document: documentLike,
-		});
-
-		expect(handled).toBe(true);
-		expect(cleanupSpy).not.toHaveBeenCalled();
-		expect(handoffSpy).toHaveBeenCalledWith({
-			href: '/docs',
-			finalHref: '/docs',
-			direction: 'forward',
-			source: 'react-router',
-			targetOwner: 'browser-router',
-			document: documentLike,
-		});
-	});
-
-	it('ignores stale handoff requests before cleaning up the active owner', async () => {
-		const windowLike = createWindowLike();
-		const runtime = getEcoNavigationRuntime(windowLike);
-		const cleanupSpy = vi.fn(async () => undefined);
-		const handoffSpy = vi.fn(async () => true);
-		const documentLike = {
-			documentElement: {
-				getAttribute: vi.fn(() => null),
-			},
-		} as unknown as Document;
-
-		runtime.register({ owner: 'react-router', cleanupBeforeHandoff: cleanupSpy });
-		runtime.register({ owner: 'browser-router', handoffNavigation: handoffSpy });
-		runtime.claimOwnership('react-router');
-
-		const handled = await runtime.requestHandoff({
-			href: '/docs',
-			finalHref: '/docs',
-			direction: 'forward',
-			source: 'react-router',
-			targetOwner: 'browser-router',
-			document: documentLike,
-			isStaleSourceNavigation: () => true,
-		});
-
-		expect(handled).toBe(true);
-		expect(cleanupSpy).not.toHaveBeenCalled();
-		expect(handoffSpy).not.toHaveBeenCalled();
-		expect(runtime.getOwnerState().owner).toBe('react-router');
-	});
-
-	it('reloads the current owner through its registration', async () => {
-		const windowLike = createWindowLike();
-		const runtime = getEcoNavigationRuntime(windowLike);
-		const reloadSpy = vi.fn(async () => undefined);
-
-		runtime.register({ owner: 'react-router', reloadCurrentPage: reloadSpy });
-		runtime.claimOwnership('react-router');
-
-		const handled = await runtime.reloadCurrentPage({ clearCache: true, source: 'browser-router' });
-
-		expect(handled).toBe(true);
-		expect(reloadSpy).toHaveBeenCalledWith({ clearCache: true, source: 'browser-router' });
-	});
-
-	it('reloads the current owner even when the request source matches that owner', async () => {
-		const windowLike = createWindowLike();
-		const runtime = getEcoNavigationRuntime(windowLike);
-		const reloadSpy = vi.fn(async () => undefined);
-
-		runtime.register({ owner: 'react-router', reloadCurrentPage: reloadSpy });
-		runtime.claimOwnership('react-router');
-
-		const handled = await runtime.reloadCurrentPage({ clearCache: false, source: 'react-router' });
-
-		expect(handled).toBe(true);
-		expect(reloadSpy).toHaveBeenCalledWith({ clearCache: false, source: 'react-router' });
-	});
-
-	it('cleans up an explicit owner via its registration', async () => {
-		const windowLike = createWindowLike();
-		const runtime = getEcoNavigationRuntime(windowLike);
-		const cleanupSpy = vi.fn();
-
-		runtime.register({ owner: 'react-router', cleanupBeforeHandoff: cleanupSpy });
-		runtime.claimOwnership('react-router');
-
-		await runtime.cleanupOwner('react-router');
-
-		expect(cleanupSpy).toHaveBeenCalledTimes(1);
-		expect(runtime.getOwnerState().owner).toBe('none');
-	});
-
-	it('emits events for registrations and ownership changes', () => {
-		const windowLike = createWindowLike();
-		const runtime = getEcoNavigationRuntime(windowLike);
-		const listener = vi.fn();
-		const unsubscribe = runtime.subscribe(listener);
-
-		const unregister = runtime.register({ owner: 'custom-router' });
-		runtime.claimOwnership('custom-router');
-		runtime.releaseOwnership('custom-router');
-		unregister();
-		unsubscribe();
-
-		expect(listener).toHaveBeenCalledWith({
-			type: 'registration-change',
-			owner: 'custom-router',
-			status: 'registered',
-		});
-		expect(listener).toHaveBeenCalledWith({
-			type: 'owner-change',
-			owner: 'custom-router',
-			previousOwner: 'none',
-			reason: 'claim',
-		});
-	});
-});