@absolutejs/absolute 0.20.0-beta.169 → 0.20.0-beta.170

package/dist/svelte/router/goto.ts

@@ -1,93 +1,22 @@
-import type { GotoOptions, RouterMode } from '../../types/svelteRouter';
-import { buildHashHref } from './hashMode';
-import { setPage } from './page.js';
-import { withViewTransition } from './viewTransitions';
+import type { GotoOptions } from '../../types/svelteRouter';
+import { navigate } from './navigation';
 
-let activeMode: RouterMode = 'history';
+export { setRouterMode } from './navigation';
 
 /**
- * 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`.
+ * Programmatically navigate to a URL. Runs the navigation guards
+ * (`beforeNavigate`, `<Router guard>`, `<Route guard>`), then updates
+ * `page.url`, writes history, swaps the route (inside
+ * `document.startViewTransition` when supported) and scrolls: to the
+ * `#hash` target when the URL has one, otherwise to the top — unless
+ * `noScroll` is set.
+ *
+ * Resolves to what happened: `'committed'`, `'cancelled'` (a guard said
+ * no), `'redirected'`, `'superseded'` (a newer navigation started while a
+ * guard was pending) or `'external'` (another origin; the browser loads it).
  *
  * 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;
-	}
-
-	// `goto` performs no network fetch of its own: the swap is a client-side
-	// route match against the registered <Route>s. What `<Link prefetch>`
-	// buys the click is therefore already in place by now — the target's
-	// HTML sits in the HTTP cache (content-hash ETag → 304 on a later real
-	// navigation), its client modules are in the modulepreload map and, when
-	// `prerender` was set, a speculation rule has the page rendered in a
-	// hidden tab. Nothing to consume here.
-	const mutate = () => {
-		writeHistory(url, options);
-		setPage({
-			params: {},
-			state: options.state ?? null,
-			url
-		});
-		applyScrollAndFocus(options);
-	};
-
-	await withViewTransition(mutate);
-};
+export const goto = (target: string, options: GotoOptions = {}) =>
+	navigate(target, options, 'goto');

package/dist/svelte/router/guards.ts

@@ -0,0 +1,112 @@
+import type {
+	NavigationContext,
+	NavigationRedirectTarget,
+	RouteGuard
+} from '../../types/svelteRouter';
+
+/* Guard evaluation shared by the browser navigation path and the server
+ * render: run a chain of guards in order and reduce their answers to one
+ * decision. Pure apart from awaiting the guards themselves. */
+
+export type GuardEntry = {
+	guard: RouteGuard;
+	params: Record<string, string | undefined>;
+};
+
+export type GuardDecision =
+	| { kind: 'allow' }
+	| { kind: 'cancel' }
+	| { kind: 'redirect'; location: string; replace: boolean }
+	| { kind: 'stale' };
+
+export type GuardRunContext = Omit<NavigationContext, 'params'>;
+
+const ALLOW: GuardDecision = { kind: 'allow' };
+const CANCEL: GuardDecision = { kind: 'cancel' };
+const STALE: GuardDecision = { kind: 'stale' };
+
+/** Thrown (or returned) by `redirect()`. An `Error` so a throw from deep
+ *  inside a helper keeps a useful stack; recognised structurally, so a
+ *  copy of the router bundled twice still understands it. */
+export class NavigationRedirect
+	extends Error
+	implements NavigationRedirectTarget
+{
+	redirect: string;
+	replace: boolean;
+
+	constructor(location: string, replace: boolean) {
+		super(`Redirect to ${location}`);
+		this.name = 'NavigationRedirect';
+		this.redirect = location;
+		this.replace = replace;
+	}
+}
+
+const isRedirectTarget = (value: unknown): value is NavigationRedirectTarget =>
+	typeof value === 'object' &&
+	value !== null &&
+	'redirect' in value &&
+	typeof value.redirect === 'string';
+
+const toDecision = (result: unknown): GuardDecision => {
+	if (result === false) return CANCEL;
+	if (typeof result === 'string') {
+		return { kind: 'redirect', location: result, replace: false };
+	}
+	if (!isRedirectTarget(result)) return ALLOW;
+	const replace = 'replace' in result && result.replace === true;
+
+	return { kind: 'redirect', location: result.redirect, replace };
+};
+
+const evaluateGuard = async (entry: GuardEntry, context: GuardRunContext) => {
+	try {
+		return toDecision(
+			await entry.guard({ ...context, params: entry.params })
+		);
+	} catch (error) {
+		if (isRedirectTarget(error)) return toDecision(error);
+		throw error;
+	}
+};
+
+const runFrom = async (
+	entries: GuardEntry[],
+	index: number,
+	context: GuardRunContext,
+	isStale: () => boolean
+): Promise<GuardDecision> => {
+	const entry = entries[index];
+	if (!entry) return ALLOW;
+	const decision = await evaluateGuard(entry, context);
+	if (isStale()) return STALE;
+	if (decision.kind !== 'allow') return decision;
+
+	return runFrom(entries, index + 1, context, isStale);
+};
+
+/**
+ * Redirect from inside a guard. Return it, or throw it from a helper the
+ * guard calls — both short-circuit the guard chain the same way:
+ *
+ *   guard={({ request }) => {
+ *     if (!isSignedIn(request)) throw redirect('/login');
+ *   }}
+ *
+ * In the browser the redirect adds a history entry unless
+ * `{ replace: true }`; on the server it is a 302.
+ */
+export const redirect = (
+	location: string,
+	options: { replace?: boolean } = {}
+) => new NavigationRedirect(location, options.replace === true);
+
+/** Run `entries` one after another; the first guard that cancels or
+ *  redirects decides. `isStale` is checked after every guard so a newer
+ *  navigation can abandon this one mid-chain. */
+export const runGuardChain = (
+	entries: GuardEntry[],
+	context: GuardRunContext,
+	isStale: () => boolean = () => false
+) => runFrom(entries, 0, context, isStale);

package/dist/svelte/router/index.ts

@@ -11,13 +11,23 @@
 // AbsoluteJS's Svelte compile pipeline.
 
 export { goto } from './goto';
+export { NavigationRedirect, redirect } from './guards';
+export { beforeNavigate, preloadRoute } from './navigation';
 export { page } from './page.js';
 export { pushState, replaceState } from './pushState';
 
 export type {
 	ExtractRouteParams,
 	GotoOptions,
+	LazyRouteLoader,
+	LazyRouteModule,
 	LinkPrefetchMode,
+	NavigationContext,
+	NavigationOutcome,
+	NavigationRedirectTarget,
+	NavigationType,
 	PageState,
+	RouteGuard,
+	RouteGuardResult,
 	RouterMode
 } from '../../types/svelteRouter';

package/dist/svelte/router/lazy.ts

@@ -0,0 +1,82 @@
+import type { LazyRouteLoader } from '../../types/svelteRouter';
+import {
+	type LazyComponent,
+	readSeededLazy,
+	toLazyComponent
+} from './lazyModule';
+
+/* Browser-side cache of lazy route components. A `<Route loader>` usually
+ * passes an inline arrow, so a fresh function arrives with every Route
+ * instance; the cache is keyed by the route pattern plus the loader's
+ * source text instead, which is stable for the life of the bundle. A
+ * route visited (or prefetched) once therefore renders synchronously the
+ * next time it becomes active — no pending flash on revisits. */
+
+const resolvedComponents = new Map<string, LazyComponent>();
+const inflightLoads = new Map<string, Promise<LazyComponent>>();
+const LAZY_SETTLE_TIMEOUT_MS = 3_000;
+
+/** Forget a failed (or stale) load so the next attempt calls the loader
+ *  again. */
+export const forgetLazy = (key: string) => {
+	resolvedComponents.delete(key);
+	inflightLoads.delete(key);
+};
+
+export const hasPendingLazyLoads = () => inflightLoads.size > 0;
+
+export const lazyCacheKey = (pattern: string, loader: LazyRouteLoader) =>
+	`${pattern}\u0000${String(loader)}`;
+
+/** Load (once) and cache the component behind `loader`. */
+export const loadLazy = (key: string, loader: LazyRouteLoader) => {
+	const cached = resolvedComponents.get(key);
+	if (cached) return Promise.resolve(cached);
+	const inflight = inflightLoads.get(key);
+	if (inflight) return inflight;
+
+	const load = loader()
+		.then((value) => {
+			const component = toLazyComponent(value);
+			if (!component) {
+				throw new Error(
+					'A lazy <Route> loader must resolve to a Svelte component or to a module whose default export is one, e.g. `() => import("./Page.svelte")`.'
+				);
+			}
+			resolvedComponents.set(key, component);
+
+			return component;
+		})
+		.finally(() => {
+			inflightLoads.delete(key);
+		});
+	inflightLoads.set(key, load);
+
+	return load;
+};
+
+/** The component for `key` if it has already loaded — or, during the
+ *  first hydration, the module the hydration entry loaded ahead of time
+ *  for this route pattern. */
+export const peekLazy = (key: string, pattern: string) => {
+	const cached = resolvedComponents.get(key);
+	if (cached) return cached;
+	const seeded = readSeededLazy(pattern);
+	if (seeded) resolvedComponents.set(key, seeded);
+
+	return seeded;
+};
+
+/** Resolves once every lazy route load in flight has settled, or after a
+ *  few seconds — scroll restoration waits on this so it doesn't restore a
+ *  position into content that hasn't rendered yet. */
+export const whenLazySettled = async () => {
+	if (inflightLoads.size === 0) return;
+	const settled = Promise.allSettled(Array.from(inflightLoads.values()));
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const timeout = new Promise<void>((resolve) => {
+		timer = setTimeout(resolve, LAZY_SETTLE_TIMEOUT_MS);
+	});
+	await Promise.race([settled, timeout]);
+	clearTimeout(timer);
+};

package/dist/svelte/router/lazyModule.ts

@@ -0,0 +1,74 @@
+import type { Component } from 'svelte';
+
+/* Pure helpers shared by the router (browser + server render) and the
+ * Svelte page handler: turn whatever a lazy route's loader resolved to
+ * into a component, and read the source id the AbsoluteJS Svelte compiler
+ * stamps on every compiled component module. No module state lives here,
+ * so it is safe to bundle more than once. */
+
+export type LazyComponent = Component<Record<string, unknown>>;
+
+/** `globalThis` record of `route pattern → module` that the hydration
+ *  entry fills before it hydrates a page whose server render included lazy
+ *  routes. Compiled client modules fill a sibling registry,
+ *  `Symbol.for('absolutejs.svelte.lazy-modules')`, of `source id →
+ *  () => import(chunk)` for every `.svelte` file they import dynamically
+ *  (see {@link lazyModuleRegistration}). */
+export const LAZY_RESOLVED_KEY = Symbol.for('absolutejs.svelte.lazy-resolved');
+
+/** Export (and component property) the Svelte compiler adds to every
+ *  compiled component: the component's source path, relative to the
+ *  project root. The server records it for each lazy route it rendered so
+ *  the browser can load the same module before hydrating. */
+export const LAZY_SOURCE_EXPORT = '__ABSOLUTE_SVELTE_SOURCE__';
+
+const isRecord = (value: unknown): value is Record<string | symbol, unknown> =>
+	typeof value === 'object' && value !== null;
+
+const isComponent = (value: unknown): value is LazyComponent =>
+	typeof value === 'function';
+
+/** The component a loader resolved to: a module namespace's `default`, or
+ *  the value itself when the loader already unwrapped it. */
+export const toLazyComponent = (value: unknown) => {
+	if (isComponent(value)) return value;
+	if (!isRecord(value)) return undefined;
+	const fallback = value.default;
+
+	return isComponent(fallback) ? fallback : undefined;
+};
+
+const readSourceFrom = (value: unknown) => {
+	if (!isRecord(value) && !isComponent(value)) return undefined;
+	const source: unknown = Reflect.get(value, LAZY_SOURCE_EXPORT);
+
+	return typeof source === 'string' ? source : undefined;
+};
+
+/** The statement a compiled client module appends for each `.svelte` file
+ *  it imports dynamically, registering `source id → () => import(chunk)`,
+ *  so the hydration entry can load the module a lazy route rendered on the
+ *  server before it hydrates. Used by the build (compileSvelte) and the dev
+ *  module server. */
+export const lazyModuleRegistration = (sourceId: string, specifier: string) =>
+	`\n;(globalThis[Symbol.for("absolutejs.svelte.lazy-modules")] ??= new Map()).set(${JSON.stringify(sourceId)}, () => import(${JSON.stringify(specifier)}));`;
+
+/** The compiler-stamped source id of a loader result, from the module
+ *  namespace or from the component itself. */
+export const readLazySource = (value: unknown) => {
+	const fromValue = readSourceFrom(value);
+	if (fromValue !== undefined) return fromValue;
+	if (!isRecord(value)) return undefined;
+
+	return readSourceFrom(value.default);
+};
+
+/** The module the hydration entry loaded for `pattern` before hydrating,
+ *  if any. */
+export const readSeededLazy = (pattern: string) => {
+	if (typeof window === 'undefined') return undefined;
+	const seeded: unknown = Reflect.get(globalThis, LAZY_RESOLVED_KEY);
+	if (!isRecord(seeded)) return undefined;
+
+	return toLazyComponent(seeded[pattern]);
+};