@absolutejs/absolute 0.19.0-beta.1043 → 0.19.0-beta.1044

package/dist/svelte/router/Link.svelte

@@ -0,0 +1,124 @@
+<script lang="ts">
+	import { onDestroy, onMount, type Snippet } from 'svelte';
+	import type { LinkPrefetchMode } from '../../types/svelteRouter';
+	import { goto } from './goto';
+	import { prefetch, scheduleHoverPrefetch } from './prefetchCache';
+
+	type LinkProps = {
+		/** Destination URL — relative or absolute. */
+		to: string;
+		/** `true` → use `history.replaceState` instead of `pushState`.
+		 *  Same name as SvelteKit's `goto` option. */
+		replaceState?: boolean;
+		/** `'hover'` (default) — prefetch on `pointerenter`.
+		 *  `'viewport'` — prefetch when the link enters the viewport.
+		 *  `'none'` — disable prefetch for this link. */
+		prefetch?: LinkPrefetchMode;
+		/** Don't reset focus to body on navigate. */
+		keepFocus?: boolean;
+		/** Don't scroll to top on navigate. */
+		noScroll?: boolean;
+		/** Forwarded to the underlying `<a>` element. */
+		class?: string;
+		/** Forwarded to the underlying `<a>` element. */
+		target?: string;
+		children?: Snippet;
+		/** Allow arbitrary HTML attributes through. */
+		[key: string]: unknown;
+	};
+
+	let {
+		to,
+		replaceState = false,
+		prefetch: prefetchMode = 'hover',
+		keepFocus = false,
+		noScroll = false,
+		class: classProp,
+		target,
+		children,
+		...rest
+	}: LinkProps = $props();
+
+	let anchor: HTMLAnchorElement | null = null;
+	let hoverHandle: { cancel: () => void } | null = null;
+	let viewportObserver: IntersectionObserver | null = null;
+
+	const isModifierClick = (event: MouseEvent) =>
+		event.metaKey || event.ctrlKey || event.shiftKey || event.altKey;
+
+	const isExternal = (href: string) => {
+		if (typeof window === 'undefined') return false;
+
+		try {
+			const url = new URL(href, window.location.href);
+
+			return url.origin !== window.location.origin;
+		} catch {
+			return false;
+		}
+	};
+
+	const handleClick = (event: MouseEvent) => {
+		if (isModifierClick(event)) return;
+		if (event.button !== 0) return;
+		if (target && target !== '_self') return;
+		if (rest['download'] !== undefined) return;
+		if (isExternal(to)) return;
+
+		event.preventDefault();
+		void goto(to, {
+			keepFocus,
+			noScroll,
+			replaceState
+		});
+	};
+
+	const handlePointerEnter = () => {
+		if (prefetchMode !== 'hover' || isExternal(to)) return;
+		hoverHandle?.cancel();
+		hoverHandle = scheduleHoverPrefetch(to);
+	};
+
+	const handlePointerLeave = () => {
+		hoverHandle?.cancel();
+		hoverHandle = null;
+	};
+
+	onMount(() => {
+		if (prefetchMode !== 'viewport' || !anchor) return;
+		if (typeof IntersectionObserver === 'undefined') return;
+		if (isExternal(to)) return;
+
+		viewportObserver = new IntersectionObserver(
+			(entries) => {
+				for (const entry of entries) {
+					if (entry.isIntersecting) {
+						prefetch(to);
+						viewportObserver?.disconnect();
+						return;
+					}
+				}
+			},
+			{ rootMargin: '128px' }
+		);
+		viewportObserver.observe(anchor);
+	});
+
+	onDestroy(() => {
+		hoverHandle?.cancel();
+		viewportObserver?.disconnect();
+	});
+</script>
+
+<a
+	bind:this={anchor}
+	href={to}
+	class={classProp}
+	{target}
+	onclick={handleClick}
+	onpointerenter={handlePointerEnter}
+	onpointerleave={handlePointerLeave}
+	{...rest}
+>
+	{@render children?.()}
+</a>

package/dist/svelte/router/Link.svelte.d.ts

@@ -0,0 +1,21 @@
+import type { Snippet } from 'svelte';
+import type { LinkPrefetchMode } from '../../types/svelteRouter';
+
+type LinkProps = {
+	to: string;
+	replaceState?: boolean;
+	prefetch?: LinkPrefetchMode;
+	keepFocus?: boolean;
+	noScroll?: boolean;
+	class?: string;
+	target?: string;
+	children?: Snippet;
+	[key: string]: unknown;
+};
+
+declare const __propDef: { props: LinkProps };
+type Props = typeof __propDef.props;
+
+import { SvelteComponent } from 'svelte';
+
+export default class Link extends SvelteComponent<Props> {}

package/dist/svelte/router/Route.svelte

@@ -0,0 +1,54 @@
+<script lang="ts" generics="Path extends string">
+	import { getContext, onDestroy, type Snippet } from 'svelte';
+	import type { ExtractRouteParams } from '../../types/svelteRouter';
+	import type { RouterRegistry } from './Router.svelte';
+	import { compilePattern, joinBasepath } from './matchPath';
+
+	const ROUTER_CONTEXT_KEY = Symbol.for('absolutejs.svelte-router');
+
+	type RouteProps = {
+		path: Path;
+		content: Snippet<[ExtractRouteParams<Path>]>;
+	};
+
+	let { path, content }: RouteProps = $props();
+
+	const registry = getContext<RouterRegistry | undefined>(ROUTER_CONTEXT_KEY);
+	if (!registry) {
+		throw new Error(
+			'<Route> must be a descendant of <Router>. ' +
+				'Wrap your routes in `<Router url={...}>` (server) or `<Router>` (client).'
+		);
+	}
+
+	const id = registry.nextRouteId();
+	const registrationOrder = Number(id.slice(1));
+
+	// Register synchronously at script-body time so SSR (which doesn't
+	// run $effect) sees the registration before the template runs.
+	registry.register(id, {
+		pattern: compilePattern(joinBasepath(registry.basepath, path)),
+		registrationOrder
+	});
+
+	$effect(() => {
+		registry.register(id, {
+			pattern: compilePattern(joinBasepath(registry.basepath, path)),
+			registrationOrder
+		});
+	});
+
+	onDestroy(() => registry.deregister(id));
+
+	// The Router computes the active match across all registered Routes
+	// (specificity-ranked). Each Route checks if it's the winner and
+	// renders its own content at its own location in the markup. That
+	// way `<Route>` nested inside a layout `<section>` renders inside
+	// that section instead of getting hoisted to the Router's root.
+	const match = $derived(registry.getActiveMatch());
+	const isActive = $derived(match?.id === id);
+</script>
+
+{#if isActive && match}
+	{@render content(match.params as ExtractRouteParams<Path>)}
+{/if}

package/dist/svelte/router/Route.svelte.d.ts

@@ -0,0 +1,13 @@
+import type { Snippet } from 'svelte';
+import type { ExtractRouteParams } from '../../types/svelteRouter';
+
+type RouteProps<Path extends string> = {
+	path: Path;
+	content: Snippet<[ExtractRouteParams<Path>]>;
+};
+
+import { SvelteComponent } from 'svelte';
+
+export default class Route<
+	Path extends string = string
+> extends SvelteComponent<RouteProps<Path>> {}

package/dist/svelte/router/Router.svelte

@@ -0,0 +1,189 @@
+<script lang="ts" module>
+	type RouteEntry = {
+		// reactive — read by the winner-resolver
+		pattern: ReturnType<typeof import('./matchPath').compilePattern>;
+		// stable — assigned at registration time, used as tiebreaker
+		registrationOrder: number;
+	};
+
+	type ActiveMatch = {
+		id: string;
+		params: Record<string, string | undefined>;
+	};
+
+	export type RouterRegistry = {
+		basepath: string;
+		mode: import('../../types/svelteRouter').RouterMode;
+		register: (id: string, entry: RouteEntry) => void;
+		deregister: (id: string) => void;
+		nextRouteId: () => string;
+		// Returns the currently-winning Route's id and matched params, or null
+		// if no Route matches. Routes call this to decide whether to render.
+		// Reads $state internally, so callers using it inside $derived/$effect
+		// auto-subscribe to URL + registration changes.
+		getActiveMatch: () => ActiveMatch | null;
+	};
+</script>
+
+<script lang="ts">
+	import { getContext, onMount, setContext, type Snippet } from 'svelte';
+	import type { RouterMode } from '../../types/svelteRouter';
+	import { setRouterMode } from './goto';
+	import { hashPathnameOf } from './hashMode';
+	import { joinBasepath, matchPattern } from './matchPath';
+	import { page, seedPage, setPage } from './page.js';
+
+	const ROUTER_CONTEXT_KEY = Symbol.for('absolutejs.svelte-router');
+
+	type RouterProps = {
+		/** SSR URL passthrough. On the server, the page handler forwards
+		 *  `request.url` here. On the client, this prop is omitted and the
+		 *  router reads `window.location` instead. */
+		url?: string;
+		/** Optional URL prefix the router operates under. Stacks with
+		 *  parent `<Router basepath>` blocks for nested routers. */
+		basepath?: string;
+		/** `'history'` (default, clean URLs) or `'hash'` (`/#/path`,
+		 *  for static deploys). */
+		mode?: RouterMode;
+		children?: Snippet;
+	};
+
+	let {
+		url,
+		basepath = '',
+		mode = 'history',
+		children
+	}: RouterProps = $props();
+
+	const parent = getContext<RouterRegistry | undefined>(ROUTER_CONTEXT_KEY);
+	const stackedBasepath = parent
+		? joinBasepath(parent.basepath, basepath)
+		: basepath === ''
+			? ''
+			: basepath.startsWith('/')
+				? basepath
+				: `/${basepath}`;
+	const stackedMode: RouterMode = parent?.mode ?? mode;
+	const isOutermost = parent === undefined;
+
+	// Specificity ranking across siblings: each <Route> registers with
+	// its compiled pattern + a stable mount-order index. The winner is
+	// computed lazily from the current URL — highest score wins; ties
+	// break by earlier registration order. The winning Route then renders
+	// its own content at ITS location in the markup (so a Route nested
+	// inside a layout `<section>` renders inside that section, not at the
+	// Router's root).
+	const routes = $state(new Map<string, RouteEntry>());
+	let routeCounter = 0;
+
+	const computeWinner = (): ActiveMatch | null => {
+		let bestId: string | null = null;
+		let bestParams: Record<string, string | undefined> | null = null;
+		let bestScore = -Infinity;
+		let bestOrder = Infinity;
+
+		for (const [id, entry] of routes) {
+			const match = matchPattern(entry.pattern, page.url.pathname);
+			if (!match.matched) continue;
+
+			if (
+				entry.pattern.score > bestScore ||
+				(entry.pattern.score === bestScore &&
+					entry.registrationOrder < bestOrder)
+			) {
+				bestScore = entry.pattern.score;
+				bestOrder = entry.registrationOrder;
+				bestId = id;
+				bestParams = match.params as Record<string, string | undefined>;
+			}
+		}
+
+		return bestId && bestParams ? { id: bestId, params: bestParams } : null;
+	};
+
+	// Recompute on every call rather than caching via $derived. SSR
+	// renders Routes in declaration order; each Route's template invokes
+	// `getActiveMatch()` immediately after registering itself, before its
+	// siblings have registered. A cached value would freeze on whichever
+	// Route triggered the computation first, so later-registered (more
+	// specific) Routes would lose. Calling `computeWinner()` afresh on
+	// every read sees the full registry by the time all Routes have
+	// rendered. Each call is O(N) over N routes; for typical pages
+	// (N < 20) the recomputation is negligible. Reactivity still works:
+	// each Route wraps the call in its own `$derived`, which tracks the
+	// `$state(routes)` and `page.url` reads inside `computeWinner`.
+	const registry: RouterRegistry = {
+		basepath: stackedBasepath,
+		deregister: (id) => {
+			routes.delete(id);
+		},
+		getActiveMatch: () => computeWinner(),
+		mode: stackedMode,
+		nextRouteId: () => `r${routeCounter++}`,
+		register: (id, entry) => {
+			routes.set(id, entry);
+		}
+	};
+
+	setContext<RouterRegistry>(ROUTER_CONTEXT_KEY, registry);
+
+	if (isOutermost) {
+		setRouterMode(stackedMode);
+
+		const baseUrl =
+			typeof window !== 'undefined' ? window.location.href : (url ?? '/');
+		const fullUrl =
+			typeof window !== 'undefined'
+				? new URL(baseUrl)
+				: new URL(baseUrl, 'http://localhost/');
+
+		const routablePathname =
+			stackedMode === 'hash' ? hashPathnameOf(fullUrl) : fullUrl.pathname;
+		const initial = new URL(fullUrl.href);
+		initial.pathname = routablePathname;
+		seedPage(initial);
+	}
+
+	onMount(() => {
+		if (!isOutermost) return;
+
+		const onPopState = (event: PopStateEvent) => {
+			const next = new URL(window.location.href);
+			const routable =
+				stackedMode === 'hash' ? hashPathnameOf(next) : next.pathname;
+			const synthetic = new URL(next.href);
+			synthetic.pathname = routable;
+			setPage({
+				params: {},
+				state: event.state ?? null,
+				url: synthetic
+			});
+		};
+
+		const onHashChange = () => {
+			const next = new URL(window.location.href);
+			const synthetic = new URL(next.href);
+			synthetic.pathname = hashPathnameOf(next);
+			setPage({
+				params: {},
+				state: window.history.state ?? null,
+				url: synthetic
+			});
+		};
+
+		window.addEventListener('popstate', onPopState);
+		if (stackedMode === 'hash') {
+			window.addEventListener('hashchange', onHashChange);
+		}
+
+		return () => {
+			window.removeEventListener('popstate', onPopState);
+			if (stackedMode === 'hash') {
+				window.removeEventListener('hashchange', onHashChange);
+			}
+		};
+	});
+</script>
+
+{@render children?.()}

package/dist/svelte/router/Router.svelte.d.ts

@@ -0,0 +1,16 @@
+import type { Snippet } from 'svelte';
+import type { RouterMode } from '../../types/svelteRouter';
+
+type RouterProps = {
+	url?: string;
+	basepath?: string;
+	mode?: RouterMode;
+	children?: Snippet;
+};
+
+declare const __propDef: { props: RouterProps };
+type Props = typeof __propDef.props;
+
+import { SvelteComponent } from 'svelte';
+
+export default class Router extends SvelteComponent<Props> {}

package/dist/svelte/router/browser.ts

@@ -0,0 +1,14 @@
+// Browser entry — same shape as ./index.ts. Components are imported by
+// their .svelte path; this entry exposes only the runtime API.
+
+export { goto } from './goto';
+export { page } from './page.js';
+export { pushState, replaceState } from './pushState';
+
+export type {
+	ExtractRouteParams,
+	GotoOptions,
+	LinkPrefetchMode,
+	PageState,
+	RouterMode
+} from '../../types/svelteRouter';

package/dist/svelte/router/goto.ts

@@ -0,0 +1,89 @@
+import type { GotoOptions, RouterMode } from '../../types/svelteRouter';
+import { buildHashHref } from './hashMode';
+import { setPage } from './page.js';
+import { consumePrefetch } from './prefetchCache';
+import { withViewTransition } from './viewTransitions';
+
+let activeMode: RouterMode = 'history';
+
+/**
+ * Internal — called by Router.svelte on mount so navigation primitives
+ * know which URL strategy to use. Hash mode rewrites the URL bar to
+ * `#/path` instead of `/path`.
+ */
+export const setRouterMode = (mode: RouterMode) => {
+	activeMode = mode;
+};
+
+const resolveAbsoluteUrl = (target: string) => {
+	if (typeof window === 'undefined') {
+		// Programmatic goto on the server is rare but we tolerate it as a
+		// way for tests to drive the router without a real DOM.
+		return new URL(target, 'http://localhost/');
+	}
+
+	return new URL(target, window.location.href);
+};
+
+const isExternal = (target: URL) => {
+	if (typeof window === 'undefined') return false;
+
+	return target.origin !== window.location.origin;
+};
+
+const writeHistory = (target: URL, options: GotoOptions) => {
+	if (typeof window === 'undefined') return;
+
+	const href =
+		activeMode === 'hash'
+			? `${window.location.pathname}${window.location.search}${buildHashHref(target.pathname + target.search)}`
+			: `${target.pathname}${target.search}${target.hash}`;
+
+	const method = options.replaceState
+		? window.history.replaceState
+		: window.history.pushState;
+	method.call(window.history, options.state ?? null, '', href);
+};
+
+const applyScrollAndFocus = (options: GotoOptions) => {
+	if (typeof window === 'undefined') return;
+
+	if (!options.noScroll) window.scrollTo({ left: 0, top: 0 });
+	if (!options.keepFocus && document.activeElement instanceof HTMLElement) {
+		document.activeElement.blur();
+	}
+};
+
+/**
+ * Programmatically navigate to a URL. Updates `page.url`, writes history,
+ * and (when supported) wraps the swap in `document.startViewTransition`.
+ *
+ * Mirrors SvelteKit's `goto` from `$app/navigation` — same name, same
+ * options shape, so a SvelteKit user finds the primitive familiar.
+ */
+export const goto = async (target: string, options: GotoOptions = {}) => {
+	const url = resolveAbsoluteUrl(target);
+
+	if (isExternal(url)) {
+		// External URLs go through the browser — we don't try to SPA them.
+		if (typeof window !== 'undefined') {
+			window.location.href = url.href;
+		}
+
+		return;
+	}
+
+	consumePrefetch(target);
+
+	const mutate = () => {
+		writeHistory(url, options);
+		setPage({
+			params: {},
+			state: options.state ?? null,
+			url
+		});
+		applyScrollAndFocus(options);
+	};
+
+	await withViewTransition(mutate);
+};

package/dist/svelte/router/hashMode.ts

@@ -0,0 +1,31 @@
+/**
+ * Hash mode: routing happens against `window.location.hash` with the
+ * leading `#/` stripped. Useful for static deploys (GitHub Pages, S3)
+ * where the host can't be configured to wildcard-route to one HTML file.
+ *
+ * URLs look like `https://example.com/#/dashboard/settings`. The
+ * `pathname` part stays at `/` so the server always serves the same
+ * page; `<Route>` matching looks at the hash instead.
+ */
+
+/**
+ * Extract the routable pathname from a full URL when hash mode is on.
+ * Returns the part after `#/`, prefixed with `/` so it parses as a
+ * normal pathname.
+ */
+export const buildHashHref = (pathname: string) => {
+	const trimmed = pathname.replace(/^\/+/, '');
+
+	return trimmed === '' ? '#/' : `#/${trimmed}`;
+};
+export const hashPathnameOf = (url: URL) => {
+	const {hash} = url;
+	if (!hash || hash === '#') return '/';
+
+	// Tolerate both `#/foo` and `#foo`.
+	const trimmed = hash.startsWith('#/') ? hash.slice(2) : hash.slice(1);
+
+	if (trimmed === '') return '/';
+
+	return `/${trimmed.replace(/^\/+/, '')}`;
+};

package/dist/svelte/router/index.ts

@@ -0,0 +1,23 @@
+// Svelte components are imported by their .svelte path, not from this entry:
+//   import Router from '@absolutejs/absolute/svelte/router/Router.svelte';
+//   import Route from '@absolutejs/absolute/svelte/router/Route.svelte';
+//   import Link from '@absolutejs/absolute/svelte/router/Link.svelte';
+//
+// This entry only re-exports the non-component runtime API (programmatic
+// navigation, reactive state, shallow routing). It mirrors the existing
+// `@absolutejs/absolute/svelte/components/*.svelte` convention used by
+// the framework's other Svelte components (Island, Image, StreamSlot,
+// etc.) so user .svelte files can import the components directly via
+// AbsoluteJS's Svelte compile pipeline.
+
+export { goto } from './goto';
+export { page } from './page.js';
+export { pushState, replaceState } from './pushState';
+
+export type {
+	ExtractRouteParams,
+	GotoOptions,
+	LinkPrefetchMode,
+	PageState,
+	RouterMode
+} from '../../types/svelteRouter';