@absolutejs/absolute 0.19.0-beta.819 → 0.19.0-beta.820

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.svelte';
+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,37 @@
+/**
+ * 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 hashPathnameOf = (url: URL) => {
+	const hash = url.hash;
+	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(/^\/+/, '')}`;
+};
+
+/**
+ * Build a hash URL from a routable pathname. Used by goto() / pushState()
+ * when in hash mode — converts `/dashboard/settings` to `#/dashboard/settings`
+ * and writes the result back to the URL.
+ */
+export const buildHashHref = (pathname: string) => {
+	const trimmed = pathname.replace(/^\/+/, '');
+
+	return trimmed === '' ? '#/' : `#/${trimmed}`;
+};

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.svelte';
+export { pushState, replaceState } from './pushState';
+
+export type {
+	ExtractRouteParams,
+	GotoOptions,
+	LinkPrefetchMode,
+	PageState,
+	RouterMode
+} from '../../types/svelteRouter';

package/dist/svelte/router/matchPath.ts

@@ -0,0 +1,158 @@
+import type {
+	ExtractRouteParams,
+	RouteMatchResult
+} from '../../types/svelteRouter';
+
+type CompiledSegment =
+	| { kind: 'static'; value: string }
+	| { kind: 'param'; name: string; optional: boolean }
+	| { kind: 'wildcard' };
+
+type CompiledPattern = {
+	segments: CompiledSegment[];
+	score: number;
+};
+
+const STATIC_SEGMENT_WEIGHT = 100;
+const PARAM_SEGMENT_WEIGHT = 10;
+const WILDCARD_SEGMENT_WEIGHT = 1;
+const OPTIONAL_PENALTY = 1;
+
+const splitPath = (path: string) => {
+	const trimmed = path.replace(/^\/+/, '').replace(/\/+$/, '');
+	if (trimmed === '') return [];
+
+	return trimmed.split('/');
+};
+
+const compileSegment = (raw: string): CompiledSegment => {
+	if (raw === '*' || raw.startsWith('*')) {
+		return { kind: 'wildcard' };
+	}
+
+	if (raw.startsWith(':')) {
+		const body = raw.slice(1);
+		const optional = body.endsWith('?');
+		const name = optional ? body.slice(0, -1) : body;
+
+		return { kind: 'param', name, optional };
+	}
+
+	return { kind: 'static', value: raw };
+};
+
+/**
+ * Compile a `<Route path>` pattern into segments + a specificity score.
+ * Higher score = more specific (longer static prefix beats parameterised).
+ */
+export const compilePattern = (pattern: string): CompiledPattern => {
+	const segments = splitPath(pattern).map(compileSegment);
+
+	let score = 0;
+	for (const segment of segments) {
+		if (segment.kind === 'static') score += STATIC_SEGMENT_WEIGHT;
+		else if (segment.kind === 'param') {
+			score += PARAM_SEGMENT_WEIGHT;
+			if (segment.optional) score -= OPTIONAL_PENALTY;
+		} else if (segment.kind === 'wildcard')
+			score += WILDCARD_SEGMENT_WEIGHT;
+	}
+
+	return { segments, score };
+};
+
+/**
+ * Match a URL pathname against a compiled pattern. Returns the extracted
+ * params on a successful match, or a miss otherwise.
+ */
+export const matchPattern = <Path extends string>(
+	pattern: CompiledPattern,
+	pathname: string
+): RouteMatchResult<ExtractRouteParams<Path>> => {
+	const pathSegments = splitPath(pathname);
+	const params: Record<string, string | undefined> = {};
+
+	let pi = 0;
+	for (let si = 0; si < pattern.segments.length; si++) {
+		const segment = pattern.segments[si];
+		if (!segment) continue;
+
+		if (segment.kind === 'wildcard') {
+			params['wildcard'] = pathSegments.slice(pi).join('/');
+			return {
+				matched: true,
+				params: params as ExtractRouteParams<Path>
+			};
+		}
+
+		const candidate = pathSegments[pi];
+
+		if (candidate === undefined) {
+			if (segment.kind === 'param' && segment.optional) {
+				params[segment.name] = undefined;
+				continue;
+			}
+
+			return { matched: false };
+		}
+
+		if (segment.kind === 'static') {
+			if (segment.value !== candidate) return { matched: false };
+			pi++;
+			continue;
+		}
+
+		// param
+		params[segment.name] = candidate;
+		pi++;
+	}
+
+	if (pi !== pathSegments.length) {
+		return { matched: false };
+	}
+
+	return {
+		matched: true,
+		params: params as ExtractRouteParams<Path>
+	};
+};
+
+/**
+ * Stable comparator for compiled patterns. Higher specificity sorts first.
+ * When two patterns have equal score, declaration order (the original index)
+ * decides — passed in via the `index` field on each entry.
+ */
+export const comparePatterns = (
+	a: { score: number; index: number },
+	b: { score: number; index: number }
+) => {
+	if (a.score !== b.score) return b.score - a.score;
+
+	return a.index - b.index;
+};
+
+/**
+ * Join a basepath stack with a child pattern, producing an absolute pattern
+ * that the route matcher can compile against an incoming pathname.
+ *
+ * Handles slash edge cases:
+ *   joinBasepath('', '/users')           → '/users'
+ *   joinBasepath('/portal', '/users')    → '/portal/users'
+ *   joinBasepath('/portal/', '/users')   → '/portal/users'
+ *   joinBasepath('/portal', 'users')     → '/portal/users'
+ *   joinBasepath('/portal', '/')         → '/portal'
+ */
+export const joinBasepath = (basepath: string, pattern: string) => {
+	const trimmedBase = basepath.replace(/\/+$/, '');
+	const trimmedPattern = pattern.replace(/^\/+/, '');
+
+	if (trimmedPattern === '') {
+		return trimmedBase === '' ? '/' : trimmedBase;
+	}
+
+	if (trimmedBase === '') {
+		return `/${trimmedPattern}`;
+	}
+
+	return `${trimmedBase}/${trimmedPattern}`;
+};

package/dist/svelte/router/page.svelte.ts

@@ -0,0 +1,57 @@
+import type { PageState } from '../../types/svelteRouter';
+
+const initialUrl = () => {
+	if (typeof window !== 'undefined') {
+		return new URL(window.location.href);
+	}
+
+	// On the server we don't know the URL yet — Router.svelte initializes
+	// it from its `url` prop. Use a placeholder that Router.svelte will
+	// overwrite immediately.
+	return new URL('http://localhost/');
+};
+
+const initialState = (): PageState => ({
+	params: {},
+	state: undefined,
+	url: initialUrl()
+});
+
+const inner = $state<PageState>(initialState());
+
+/**
+ * Reactive route state. Mirrors SvelteKit's `page` from `$app/state`:
+ *
+ *   import { page } from '@absolutejs/absolute/svelte/router';
+ *   page.url.pathname        // current path (reactive)
+ *   page.url.searchParams    // parsed URLSearchParams (reactive)
+ *   page.params.id           // active route params (reactive)
+ *   page.state               // history.state for the current entry
+ *
+ * Backed by `$state`. Direct property access in templates re-renders.
+ */
+export const page = inner;
+
+/**
+ * Internal — only Router.svelte and the navigation primitives call this.
+ * Replaces the entire page state in one assignment so subscribers fire
+ * once per navigation rather than once per mutated field.
+ */
+export const setPage = (next: Partial<PageState>) => {
+	if (next.url !== undefined) inner.url = next.url;
+	if (next.params !== undefined) inner.params = next.params;
+	if (next.state !== undefined) inner.state = next.state;
+};
+
+/**
+ * Internal — used during SSR to seed the page state before render so
+ * `<Route>` blocks see the correct `page.url`.
+ */
+export const seedPage = (
+	url: URL,
+	params: Record<string, string | undefined> = {}
+) => {
+	inner.url = url;
+	inner.params = params;
+	inner.state = undefined;
+};

package/dist/svelte/router/prefetchCache.ts

@@ -0,0 +1,89 @@
+const PREFETCH_CACHE_LIMIT = 16;
+const HOVER_DEBOUNCE_MS = 250;
+
+type CacheEntry = {
+	url: string;
+	promise: Promise<Response>;
+};
+
+const cache = new Map<string, CacheEntry>();
+
+const isSlowConnection = () => {
+	if (typeof navigator === 'undefined') return false;
+
+	const connection = (
+		navigator as Navigator & {
+			connection?: { saveData?: boolean };
+		}
+	).connection;
+
+	return connection?.saveData === true;
+};
+
+const prefersReducedData = () => {
+	if (typeof window === 'undefined' || !window.matchMedia) return false;
+
+	return window.matchMedia('(prefers-reduced-data: reduce)').matches;
+};
+
+const evictOldest = () => {
+	const oldest = cache.keys().next();
+	if (oldest.done) return;
+	cache.delete(oldest.value);
+};
+
+/**
+ * Prefetch a URL into the in-memory cache. No-op if the user has signalled
+ * data-saver / reduced-data, or if the URL is already cached.
+ */
+export const prefetch = (url: string) => {
+	if (typeof fetch === 'undefined') return;
+	if (isSlowConnection() || prefersReducedData()) return;
+	if (cache.has(url)) return;
+
+	while (cache.size >= PREFETCH_CACHE_LIMIT) evictOldest();
+
+	const promise = fetch(url, { credentials: 'same-origin' }).catch(
+		() => new Response(null, { status: 0 })
+	);
+	cache.set(url, { promise, url });
+};
+
+/**
+ * Consume a cached prefetch entry on actual navigation, removing it from
+ * the cache. Returns the cached Promise<Response> or undefined.
+ */
+export const consumePrefetch = (url: string) => {
+	const entry = cache.get(url);
+	if (!entry) return undefined;
+	cache.delete(url);
+
+	return entry.promise;
+};
+
+export const clearPrefetchCache = () => {
+	cache.clear();
+};
+
+type HoverHandle = {
+	cancel: () => void;
+};
+
+/**
+ * Wrap a prefetch trigger in a hover-debounce so glancing across many links
+ * doesn't fire a fetch storm. The returned handle's `cancel()` aborts the
+ * pending hover prefetch (e.g. on `pointerleave`).
+ */
+export const scheduleHoverPrefetch = (url: string): HoverHandle => {
+	if (typeof window === 'undefined') {
+		return { cancel: () => {} };
+	}
+
+	const timer = window.setTimeout(() => {
+		prefetch(url);
+	}, HOVER_DEBOUNCE_MS);
+
+	return {
+		cancel: () => window.clearTimeout(timer)
+	};
+};

package/dist/svelte/router/pushState.ts

@@ -0,0 +1,35 @@
+import { setPage } from './page.svelte';
+
+const resolveTarget = (target: string) => {
+	if (typeof window === 'undefined')
+		return new URL(target, 'http://localhost/');
+
+	return new URL(target, window.location.href);
+};
+
+/**
+ * Shallow routing: update the URL bar and `page.state` without re-running
+ * `<Route>` matching. Useful for modals / drawers / overlays that want a
+ * shareable URL without swapping the active route's content.
+ *
+ * Mirrors SvelteKit's `pushState` from `$app/navigation`.
+ */
+export const pushState = (target: string, state: unknown) => {
+	if (typeof window === 'undefined') return;
+
+	const url = resolveTarget(target);
+	window.history.pushState(state, '', url.href);
+	setPage({ state, url });
+};
+
+/**
+ * Same as `pushState` but uses `history.replaceState`. Mirrors SvelteKit's
+ * `replaceState` from `$app/navigation`.
+ */
+export const replaceState = (target: string, state: unknown) => {
+	if (typeof window === 'undefined') return;
+
+	const url = resolveTarget(target);
+	window.history.replaceState(state, '', url.href);
+	setPage({ state, url });
+};

package/dist/svelte/router/viewTransitions.ts

@@ -0,0 +1,31 @@
+type StartViewTransition = (callback: () => void | Promise<void>) => {
+	finished: Promise<void>;
+};
+
+const supportsViewTransitions = () => {
+	if (typeof document === 'undefined') return false;
+
+	return (
+		typeof (document as { startViewTransition?: StartViewTransition })
+			.startViewTransition === 'function'
+	);
+};
+
+/**
+ * Wrap a state mutation in `document.startViewTransition` when supported.
+ * Falls through to a synchronous call otherwise. Reduced-motion users get
+ * instant swaps via the browser's own handling of `prefers-reduced-motion`.
+ */
+export const withViewTransition = async (
+	mutate: () => void | Promise<void>
+) => {
+	if (!supportsViewTransitions()) {
+		await mutate();
+
+		return;
+	}
+
+	const start = (document as { startViewTransition: StartViewTransition })
+		.startViewTransition;
+	await start(() => mutate()).finished;
+};

package/dist/types/svelteRouter.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Public type surface for the AbsoluteJS Svelte router.
+ *
+ * `ExtractRouteParams<P>` walks a path-pattern string literal and produces
+ * a typed `params` shape:
+ *
+ *   ExtractRouteParams<'/users/:id'>            → { id: string }
+ *   ExtractRouteParams<'/users/:id/posts/:pid'> → { id: string; pid: string }
+ *   ExtractRouteParams<'/users/:id?'>           → { id: string | undefined }
+ *   ExtractRouteParams<'/files/*'>              → { wildcard: string }
+ *   ExtractRouteParams<'/dashboard'>            → Record<string, never>
+ *
+ * Edge cases:
+ *  - Optional params (`:name?`) appear as `string | undefined`
+ *  - Wildcard tail (`*`) is exposed as the `wildcard` key
+ *  - Same-name twice in one path is intentionally not detected at the type
+ *    level (it's a logic bug in the user's pattern, not something the type
+ *    system meaningfully rescues).
+ */
+type IsOptionalParamSegment<Segment extends string> = Segment extends `${string}?` ? true : false;
+type StripOptionalSuffix<Segment extends string> = Segment extends `${infer Name}?` ? Name : Segment;
+type WildcardSegment = '*' | `*${string}`;
+type ParseSegment<Segment extends string> = Segment extends WildcardSegment ? {
+    wildcard: string;
+} : Segment extends `:${infer Name}` ? IsOptionalParamSegment<Name> extends true ? {
+    [K in StripOptionalSuffix<Name>]: string | undefined;
+} : {
+    [K in Name]: string;
+} : Record<never, never>;
+type SplitPath<Path extends string> = Path extends `/${infer Rest}` ? SplitPath<Rest> : Path extends `${infer Head}/${infer Tail}` ? ParseSegment<Head> & SplitPath<Tail> : ParseSegment<Path>;
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+export type ExtractRouteParams<Path extends string> = string extends Path ? Record<string, string> : Simplify<SplitPath<Path>> extends infer Result ? keyof Result extends never ? Record<string, never> : Result : never;
+export type RouteMatch<Params extends Record<string, unknown>> = {
+    matched: true;
+    params: Params;
+};
+export type RouteMiss = {
+    matched: false;
+};
+export type RouteMatchResult<Params extends Record<string, unknown>> = RouteMatch<Params> | RouteMiss;
+export type RouterMode = 'history' | 'hash';
+export type GotoOptions = {
+    /** Use `history.replaceState` instead of `pushState`. */
+    replaceState?: boolean;
+    /** Don't reset focus to body on navigation. */
+    keepFocus?: boolean;
+    /** Don't scroll to top on navigation. */
+    noScroll?: boolean;
+    /** Value attached to `history.state`. */
+    state?: unknown;
+};
+export type LinkPrefetchMode = 'hover' | 'viewport' | 'none';
+export type PageState = {
+    url: URL;
+    params: Record<string, string | undefined>;
+    state: unknown;
+};
+export type RouterContextValue = {
+    /** Stacked basepath from outer to inner Router (joined). */
+    basepath: string;
+    mode: RouterMode;
+};
+export {};

package/dist/types/svelteRouter.ts

@@ -0,0 +1,91 @@
+/**
+ * Public type surface for the AbsoluteJS Svelte router.
+ *
+ * `ExtractRouteParams<P>` walks a path-pattern string literal and produces
+ * a typed `params` shape:
+ *
+ *   ExtractRouteParams<'/users/:id'>            → { id: string }
+ *   ExtractRouteParams<'/users/:id/posts/:pid'> → { id: string; pid: string }
+ *   ExtractRouteParams<'/users/:id?'>           → { id: string | undefined }
+ *   ExtractRouteParams<'/files/*'>              → { wildcard: string }
+ *   ExtractRouteParams<'/dashboard'>            → Record<string, never>
+ *
+ * Edge cases:
+ *  - Optional params (`:name?`) appear as `string | undefined`
+ *  - Wildcard tail (`*`) is exposed as the `wildcard` key
+ *  - Same-name twice in one path is intentionally not detected at the type
+ *    level (it's a logic bug in the user's pattern, not something the type
+ *    system meaningfully rescues).
+ */
+
+type IsOptionalParamSegment<Segment extends string> =
+	Segment extends `${string}?` ? true : false;
+
+type StripOptionalSuffix<Segment extends string> =
+	Segment extends `${infer Name}?` ? Name : Segment;
+
+type WildcardSegment = '*' | `*${string}`;
+
+type ParseSegment<Segment extends string> = Segment extends WildcardSegment
+	? { wildcard: string }
+	: Segment extends `:${infer Name}`
+		? IsOptionalParamSegment<Name> extends true
+			? { [K in StripOptionalSuffix<Name>]: string | undefined }
+			: { [K in Name]: string }
+		: Record<never, never>;
+
+type SplitPath<Path extends string> = Path extends `/${infer Rest}`
+	? SplitPath<Rest>
+	: Path extends `${infer Head}/${infer Tail}`
+		? ParseSegment<Head> & SplitPath<Tail>
+		: ParseSegment<Path>;
+
+type Simplify<T> = { [K in keyof T]: T[K] } & {};
+
+export type ExtractRouteParams<Path extends string> = string extends Path
+	? Record<string, string>
+	: Simplify<SplitPath<Path>> extends infer Result
+		? keyof Result extends never
+			? Record<string, never>
+			: Result
+		: never;
+
+export type RouteMatch<Params extends Record<string, unknown>> = {
+	matched: true;
+	params: Params;
+};
+
+export type RouteMiss = {
+	matched: false;
+};
+
+export type RouteMatchResult<Params extends Record<string, unknown>> =
+	| RouteMatch<Params>
+	| RouteMiss;
+
+export type RouterMode = 'history' | 'hash';
+
+export type GotoOptions = {
+	/** Use `history.replaceState` instead of `pushState`. */
+	replaceState?: boolean;
+	/** Don't reset focus to body on navigation. */
+	keepFocus?: boolean;
+	/** Don't scroll to top on navigation. */
+	noScroll?: boolean;
+	/** Value attached to `history.state`. */
+	state?: unknown;
+};
+
+export type LinkPrefetchMode = 'hover' | 'viewport' | 'none';
+
+export type PageState = {
+	url: URL;
+	params: Record<string, string | undefined>;
+	state: unknown;
+};
+
+export type RouterContextValue = {
+	/** Stacked basepath from outer to inner Router (joined). */
+	basepath: string;
+	mode: RouterMode;
+};