@ecopages/browser-router 0.2.0-alpha.1

package/src/client/types.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Shared types for the EcoPages transitions package
+ * @module
+ */
+/**
+ * Prefetch configuration options.
+ */
+export interface PrefetchConfig {
+    /**
+     * Prefetching strategy:
+     * - 'viewport': Prefetch when links enter viewport
+     * - 'hover': Prefetch on hover/focus intent
+     * - 'intent': Viewport + prioritize hover (recommended)
+     * @default 'intent'
+     */
+    strategy?: 'viewport' | 'hover' | 'intent';
+    /**
+     * Hover intent delay in ms before triggering prefetch.
+     * @default 65
+     */
+    delay?: number;
+    /**
+     * Attribute to disable prefetch on specific links.
+     * @default 'data-eco-no-prefetch'
+     */
+    noPrefetchAttribute?: string;
+    /**
+     * Respect navigator.connection.saveData and slow connections.
+     * @default true
+     */
+    respectDataSaver?: boolean;
+}
+/**
+ * Configuration options for the EcoRouter
+ */
+export interface EcoRouterOptions {
+    /** Selector for links to intercept. @default 'a[href]' */
+    linkSelector?: string;
+    /** Attribute to mark elements for DOM persistence. @default 'data-eco-persist' */
+    persistAttribute?: string;
+    /** Attribute to force full page reload. @default 'data-eco-reload' */
+    reloadAttribute?: string;
+    /** Whether to update browser history. @default true */
+    updateHistory?: boolean;
+    /**
+     * Scroll behavior after navigation:
+     * - 'top': Always scroll to top (default)
+     * - 'preserve': Keep current scroll position
+     * - 'auto': Scroll to top only when pathname changes
+     */
+    scrollBehavior?: 'top' | 'preserve' | 'auto';
+    /**
+     * Whether to use the View Transition API for animations.
+     * Falls back to instant swap if not supported.
+     * @default true
+     */
+    viewTransitions?: boolean;
+    /**
+     * Whether to use smooth scrolling during navigation.
+     * If true, uses 'smooth' behavior. If false, uses 'instant' behavior.
+     * @default false
+     */
+    smoothScroll?: boolean;
+    /**
+     * Prefetch configuration. Set to false to disable prefetching entirely.
+     * @default { strategy: 'intent', delay: 65, noPrefetchAttribute: 'data-eco-no-prefetch', respectDataSaver: true }
+     */
+    prefetch?: PrefetchConfig | false;
+}
+/** Events emitted during the navigation lifecycle */
+export interface EcoNavigationEvent {
+    url: URL;
+    direction: 'forward' | 'back' | 'replace';
+}
+/** Event fired before the DOM swap occurs */
+export interface EcoBeforeSwapEvent extends EcoNavigationEvent {
+    newDocument: Document;
+    reload: () => void;
+}
+/** Event fired after the DOM swap completes */
+export interface EcoAfterSwapEvent extends EcoNavigationEvent {
+}
+/** Default configuration options */
+export declare const DEFAULT_OPTIONS: Required<EcoRouterOptions>;

package/src/client/types.js

@@ -0,0 +1,19 @@
+const DEFAULT_PREFETCH_CONFIG = {
+  strategy: "intent",
+  delay: 65,
+  noPrefetchAttribute: "data-eco-no-prefetch",
+  respectDataSaver: true
+};
+const DEFAULT_OPTIONS = {
+  linkSelector: "a[href]",
+  persistAttribute: "data-eco-persist",
+  reloadAttribute: "data-eco-reload",
+  updateHistory: true,
+  scrollBehavior: "top",
+  viewTransitions: true,
+  smoothScroll: false,
+  prefetch: DEFAULT_PREFETCH_CONFIG
+};
+export {
+  DEFAULT_OPTIONS
+};

package/src/client/types.ts

@@ -0,0 +1,109 @@
+/**
+ * Shared types for the EcoPages transitions package
+ * @module
+ */
+
+/**
+ * Prefetch configuration options.
+ */
+export interface PrefetchConfig {
+	/**
+	 * Prefetching strategy:
+	 * - 'viewport': Prefetch when links enter viewport
+	 * - 'hover': Prefetch on hover/focus intent
+	 * - 'intent': Viewport + prioritize hover (recommended)
+	 * @default 'intent'
+	 */
+	strategy?: 'viewport' | 'hover' | 'intent';
+
+	/**
+	 * Hover intent delay in ms before triggering prefetch.
+	 * @default 65
+	 */
+	delay?: number;
+
+	/**
+	 * Attribute to disable prefetch on specific links.
+	 * @default 'data-eco-no-prefetch'
+	 */
+	noPrefetchAttribute?: string;
+
+	/**
+	 * Respect navigator.connection.saveData and slow connections.
+	 * @default true
+	 */
+	respectDataSaver?: boolean;
+}
+
+/**
+ * Configuration options for the EcoRouter
+ */
+export interface EcoRouterOptions {
+	/** Selector for links to intercept. @default 'a[href]' */
+	linkSelector?: string;
+	/** Attribute to mark elements for DOM persistence. @default 'data-eco-persist' */
+	persistAttribute?: string;
+	/** Attribute to force full page reload. @default 'data-eco-reload' */
+	reloadAttribute?: string;
+	/** Whether to update browser history. @default true */
+	updateHistory?: boolean;
+	/**
+	 * Scroll behavior after navigation:
+	 * - 'top': Always scroll to top (default)
+	 * - 'preserve': Keep current scroll position
+	 * - 'auto': Scroll to top only when pathname changes
+	 */
+	scrollBehavior?: 'top' | 'preserve' | 'auto';
+	/**
+	 * Whether to use the View Transition API for animations.
+	 * Falls back to instant swap if not supported.
+	 * @default true
+	 */
+	viewTransitions?: boolean;
+	/**
+	 * Whether to use smooth scrolling during navigation.
+	 * If true, uses 'smooth' behavior. If false, uses 'instant' behavior.
+	 * @default false
+	 */
+	smoothScroll?: boolean;
+	/**
+	 * Prefetch configuration. Set to false to disable prefetching entirely.
+	 * @default { strategy: 'intent', delay: 65, noPrefetchAttribute: 'data-eco-no-prefetch', respectDataSaver: true }
+	 */
+	prefetch?: PrefetchConfig | false;
+}
+
+/** Events emitted during the navigation lifecycle */
+export interface EcoNavigationEvent {
+	url: URL;
+	direction: 'forward' | 'back' | 'replace';
+}
+
+/** Event fired before the DOM swap occurs */
+export interface EcoBeforeSwapEvent extends EcoNavigationEvent {
+	newDocument: Document;
+	reload: () => void;
+}
+
+/** Event fired after the DOM swap completes */
+export interface EcoAfterSwapEvent extends EcoNavigationEvent {}
+
+/** Default prefetch configuration */
+const DEFAULT_PREFETCH_CONFIG: Required<PrefetchConfig> = {
+	strategy: 'intent',
+	delay: 65,
+	noPrefetchAttribute: 'data-eco-no-prefetch',
+	respectDataSaver: true,
+};
+
+/** Default configuration options */
+export const DEFAULT_OPTIONS: Required<EcoRouterOptions> = {
+	linkSelector: 'a[href]',
+	persistAttribute: 'data-eco-persist',
+	reloadAttribute: 'data-eco-reload',
+	updateHistory: true,
+	scrollBehavior: 'top',
+	viewTransitions: true,
+	smoothScroll: false,
+	prefetch: DEFAULT_PREFETCH_CONFIG,
+};

package/src/client/view-transition-utils.d.ts

@@ -0,0 +1,14 @@
+/**
+ * View transition utilities for applying transition names from data attributes.
+ * @module
+ */
+/**
+ * Applies view-transition-name CSS property to elements with data-view-transition attribute.
+ * By default, it also injects styles to prevent "ghosting" (sets animation: none) for clean morphing,
+ * unless data-view-transition-animate="fade" is present.
+ */
+export declare function applyViewTransitionNames(): void;
+/**
+ * Clears view-transition-name CSS property from all elements.
+ */
+export declare function clearViewTransitionNames(): void;

package/src/client/view-transition-utils.js

@@ -0,0 +1,60 @@
+const VIEW_TRANSITION_ATTR = "data-view-transition";
+const VIEW_TRANSITION_ANIMATE_ATTR = "data-view-transition-animate";
+const VIEW_TRANSITION_DURATION_ATTR = "data-view-transition-duration";
+function applyViewTransitionNames() {
+  const elements = document.querySelectorAll(`[${VIEW_TRANSITION_ATTR}]`);
+  const morphNames = [];
+  const customDurations = [];
+  elements.forEach((el) => {
+    const name = el.getAttribute(VIEW_TRANSITION_ATTR);
+    if (name) {
+      el.style.viewTransitionName = name;
+      const animate = el.getAttribute(VIEW_TRANSITION_ANIMATE_ATTR);
+      if (animate !== "fade") {
+        morphNames.push(name);
+      }
+      const duration = el.getAttribute(VIEW_TRANSITION_DURATION_ATTR);
+      if (duration) {
+        customDurations.push({ name, duration });
+      }
+    }
+  });
+  if (morphNames.length > 0 || customDurations.length > 0) {
+    injectDynamicStyles(morphNames, customDurations);
+  }
+}
+function injectDynamicStyles(morphNames, customDurations) {
+  let styleEl = document.getElementById("eco-vt-dynamic-styles");
+  if (!styleEl) {
+    styleEl = document.createElement("style");
+    styleEl.id = "eco-vt-dynamic-styles";
+    styleEl.setAttribute("data-eco-persist", "");
+    document.head.appendChild(styleEl);
+  }
+  const morphCss = morphNames.map(
+    (name) => `
+		::view-transition-old(${name}) { display: none !important; }
+		::view-transition-new(${name}) { animation: none !important; opacity: 1 !important; }
+	`
+  ).join("\n");
+  const durationCss = customDurations.map(
+    ({ name, duration }) => `
+		::view-transition-group(${name}) { animation-duration: ${duration} !important; }
+	`
+  ).join("\n");
+  styleEl.textContent = morphCss + "\n" + durationCss;
+}
+function clearViewTransitionNames() {
+  const elements = document.querySelectorAll(`[${VIEW_TRANSITION_ATTR}]`);
+  elements.forEach((el) => {
+    el.style.viewTransitionName = "";
+  });
+  const styleEl = document.getElementById("eco-vt-dynamic-styles");
+  if (styleEl) {
+    styleEl.textContent = "";
+  }
+}
+export {
+  applyViewTransitionNames,
+  clearViewTransitionNames
+};

package/src/client/view-transition-utils.ts

@@ -0,0 +1,98 @@
+/**
+ * View transition utilities for applying transition names from data attributes.
+ * @module
+ */
+
+const VIEW_TRANSITION_ATTR = 'data-view-transition';
+const VIEW_TRANSITION_ANIMATE_ATTR = 'data-view-transition-animate';
+const VIEW_TRANSITION_DURATION_ATTR = 'data-view-transition-duration';
+
+/**
+ * Applies view-transition-name CSS property to elements with data-view-transition attribute.
+ * By default, it also injects styles to prevent "ghosting" (sets animation: none) for clean morphing,
+ * unless data-view-transition-animate="fade" is present.
+ */
+export function applyViewTransitionNames(): void {
+	const elements = document.querySelectorAll(`[${VIEW_TRANSITION_ATTR}]`);
+	const morphNames: string[] = [];
+	const customDurations: { name: string; duration: string }[] = [];
+
+	elements.forEach((el) => {
+		const name = el.getAttribute(VIEW_TRANSITION_ATTR);
+		if (name) {
+			(el as HTMLElement).style.viewTransitionName = name;
+
+			/**
+			 * By default, we apply a clean geometric morph (no cross-fade/ghosting).
+			 * The 'fade' value is reserved for opting out of this behavior.
+			 */
+			const animate = el.getAttribute(VIEW_TRANSITION_ANIMATE_ATTR);
+			if (animate !== 'fade') {
+				morphNames.push(name);
+			}
+
+			const duration = el.getAttribute(VIEW_TRANSITION_DURATION_ATTR);
+			if (duration) {
+				customDurations.push({ name, duration });
+			}
+		}
+	});
+
+	if (morphNames.length > 0 || customDurations.length > 0) {
+		injectDynamicStyles(morphNames, customDurations);
+	}
+}
+
+/**
+ * Injects dynamic CSS to hide old snapshots and apply custom durations.
+ */
+function injectDynamicStyles(morphNames: string[], customDurations: { name: string; duration: string }[]) {
+	let styleEl = document.getElementById('eco-vt-dynamic-styles');
+	if (!styleEl) {
+		styleEl = document.createElement('style');
+		styleEl.id = 'eco-vt-dynamic-styles';
+		/**
+		 * Persistence is required to prevent the head-morpher from removing this style tag during navigation.
+		 * @see {@link DomSwapper}
+		 */
+		styleEl.setAttribute('data-eco-persist', '');
+		document.head.appendChild(styleEl);
+	}
+
+	const morphCss = morphNames
+		.map(
+			(name) => `
+		::view-transition-old(${name}) { display: none !important; }
+		::view-transition-new(${name}) { animation: none !important; opacity: 1 !important; }
+	`,
+		)
+		.join('\n');
+
+	const durationCss = customDurations
+		.map(
+			({ name, duration }) => `
+		::view-transition-group(${name}) { animation-duration: ${duration} !important; }
+	`,
+		)
+		.join('\n');
+
+	styleEl.textContent = morphCss + '\n' + durationCss;
+}
+
+/**
+ * Clears view-transition-name CSS property from all elements.
+ */
+export function clearViewTransitionNames(): void {
+	const elements = document.querySelectorAll(`[${VIEW_TRANSITION_ATTR}]`);
+	elements.forEach((el) => {
+		(el as HTMLElement).style.viewTransitionName = '';
+	});
+
+	/**
+	 * Cleanup dynamic styles to ensure a clean slate for the next transition.
+	 */
+	const styleEl = document.getElementById('eco-vt-dynamic-styles');
+	if (styleEl) {
+		styleEl.textContent = '';
+	}
+}

package/src/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @ecopages/browser-router
+ * Client-side navigation and view transitions for Ecopages
+ * @module
+ */
+export type { EcoRouterOptions, EcoNavigationEvent, EcoBeforeSwapEvent, EcoAfterSwapEvent, EcoRouterEventMap, } from './types.js';
+export { DEFAULT_OPTIONS } from './types.js';
+export { EcoRouter, createRouter } from './client/eco-router.js';
+export { DomSwapper, ScrollManager, ViewTransitionManager } from './client/services/index.js';

package/src/index.js

@@ -0,0 +1,11 @@
+import { DEFAULT_OPTIONS } from "./types.js";
+import { EcoRouter, createRouter } from "./client/eco-router.js";
+import { DomSwapper, ScrollManager, ViewTransitionManager } from "./client/services/index.js";
+export {
+  DEFAULT_OPTIONS,
+  DomSwapper,
+  EcoRouter,
+  ScrollManager,
+  ViewTransitionManager,
+  createRouter
+};

package/src/index.ts

@@ -0,0 +1,19 @@
+/**
+ * @ecopages/browser-router
+ * Client-side navigation and view transitions for Ecopages
+ * @module
+ */
+
+export type {
+	EcoRouterOptions,
+	EcoNavigationEvent,
+	EcoBeforeSwapEvent,
+	EcoAfterSwapEvent,
+	EcoRouterEventMap,
+} from './types.ts';
+
+export { DEFAULT_OPTIONS } from './types.ts';
+
+export { EcoRouter, createRouter } from './client/eco-router.ts';
+
+export { DomSwapper, ScrollManager, ViewTransitionManager } from './client/services/index.ts';

package/src/styles.css

@@ -0,0 +1,218 @@
+/**
+ * Default View Transition CSS for EcoPages transitions
+ *
+ * NOTE: This file is not exported from the package.
+ * JSR does not support CSS exports yet: https://github.com/jsr-io/jsr/issues/293
+ *
+ * Use the ecopages npm package instead:
+ * @import 'ecopages/css/view-transitions.css';
+ */
+
+/* Disable root animation to prevent full page flash during transitions */
+::view-transition-old(root),
+::view-transition-new(root) {
+	animation: none;
+}
+
+/* Shared element transitions animate position/size smoothly */
+::view-transition-group(*) {
+	animation-duration: 180ms;
+	animation-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+/* Prevent transitioning elements from affecting layout of non-transitioning elements */
+::view-transition-image-pair(*) {
+	isolation: isolate;
+}
+
+/* Respect reduced motion preference */
+@media (prefers-reduced-motion: reduce) {
+	::view-transition-group(*),
+	::view-transition-old(*),
+	::view-transition-new(*) {
+		animation: none !important;
+	}
+}
+
+@keyframes eco-fade-out {
+	from {
+		opacity: 1;
+	}
+	to {
+		opacity: 0;
+	}
+}
+
+@keyframes eco-fade-in {
+	from {
+		opacity: 0;
+	}
+	to {
+		opacity: 1;
+	}
+}
+
+/* Slide transition for elements with view-transition-name: eco-slide */
+::view-transition-image-pair(eco-slide) {
+	isolation: isolate;
+}
+
+::view-transition-old(eco-slide),
+::view-transition-new(eco-slide) {
+	animation-duration: 180ms;
+	animation-timing-function: ease-out;
+	mix-blend-mode: normal;
+}
+
+::view-transition-old(eco-slide) {
+	animation-name: eco-slide-out;
+}
+
+::view-transition-new(eco-slide) {
+	animation-name: eco-slide-in;
+}
+
+@keyframes eco-slide-out {
+	from {
+		opacity: 1;
+		transform: translateX(0);
+	}
+	to {
+		opacity: 0;
+		transform: translateX(-30px);
+	}
+}
+
+@keyframes eco-slide-in {
+	from {
+		opacity: 0;
+		transform: translateX(30px);
+	}
+	to {
+		opacity: 1;
+		transform: translateX(0);
+	}
+}
+
+/* Persistent elements should not animate */
+[data-eco-persist] {
+	view-transition-name: none;
+}
+
+/* Declarative transition attributes */
+[data-eco-transition='slide'] {
+	view-transition-name: eco-slide;
+}
+[data-eco-transition='fade'] {
+	view-transition-name: eco-fade;
+}
+[data-eco-transition='zoom'] {
+	view-transition-name: eco-zoom;
+}
+[data-eco-transition='slide-up'] {
+	view-transition-name: eco-slide-up;
+}
+[data-eco-transition='slide-down'] {
+	view-transition-name: eco-slide-down;
+}
+
+/* FADE */
+::view-transition-old(eco-fade) {
+	animation: eco-fade-out 180ms ease-out both;
+}
+::view-transition-new(eco-fade) {
+	animation: eco-fade-in 180ms ease-out both;
+}
+
+/* ZOOM */
+::view-transition-image-pair(eco-zoom) {
+	isolation: isolate;
+}
+::view-transition-old(eco-zoom) {
+	animation: eco-zoom-out 180ms ease-in both;
+}
+::view-transition-new(eco-zoom) {
+	animation: eco-zoom-in 180ms ease-out both;
+}
+@keyframes eco-zoom-out {
+	from {
+		opacity: 1;
+		transform: scale(1);
+	}
+	to {
+		opacity: 0;
+		transform: scale(0.9);
+	}
+}
+@keyframes eco-zoom-in {
+	from {
+		opacity: 0;
+		transform: scale(0.9);
+	}
+	to {
+		opacity: 1;
+		transform: scale(1);
+	}
+}
+
+/* SLIDE UP */
+::view-transition-image-pair(eco-slide-up) {
+	isolation: isolate;
+}
+::view-transition-old(eco-slide-up) {
+	animation: eco-slide-up-out 180ms ease-in both;
+}
+::view-transition-new(eco-slide-up) {
+	animation: eco-slide-up-in 180ms ease-out both;
+}
+@keyframes eco-slide-up-out {
+	from {
+		opacity: 1;
+		transform: translateY(0);
+	}
+	to {
+		opacity: 0;
+		transform: translateY(-30px);
+	}
+}
+@keyframes eco-slide-up-in {
+	from {
+		opacity: 0;
+		transform: translateY(30px);
+	}
+	to {
+		opacity: 1;
+		transform: translateY(0);
+	}
+}
+
+/* SLIDE DOWN */
+::view-transition-image-pair(eco-slide-down) {
+	isolation: isolate;
+}
+::view-transition-old(eco-slide-down) {
+	animation: eco-slide-down-out 180ms ease-in both;
+}
+::view-transition-new(eco-slide-down) {
+	animation: eco-slide-down-in 180ms ease-out both;
+}
+@keyframes eco-slide-down-out {
+	from {
+		opacity: 1;
+		transform: translateY(0);
+	}
+	to {
+		opacity: 0;
+		transform: translateY(30px);
+	}
+}
+@keyframes eco-slide-down-in {
+	from {
+		opacity: 0;
+		transform: translateY(-30px);
+	}
+	to {
+		opacity: 1;
+		transform: translateY(0);
+	}
+}

package/src/types.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Types for the @ecopages/browser-router package
+ * @module
+ */
+import type { EcoNavigationEvent, EcoBeforeSwapEvent, EcoAfterSwapEvent } from './client/types';
+export type { EcoRouterOptions, EcoNavigationEvent, EcoBeforeSwapEvent, EcoAfterSwapEvent } from './client/types';
+export { DEFAULT_OPTIONS } from './client/types';
+/**
+ * Custom event map for navigation lifecycle
+ */
+export interface EcoRouterEventMap {
+    'eco:before-swap': CustomEvent<EcoBeforeSwapEvent>;
+    'eco:after-swap': CustomEvent<EcoAfterSwapEvent>;
+    'eco:page-load': CustomEvent<EcoNavigationEvent>;
+}

package/src/types.js

@@ -0,0 +1,4 @@
+import { DEFAULT_OPTIONS } from "./client/types";
+export {
+  DEFAULT_OPTIONS
+};

package/src/types.ts

@@ -0,0 +1,19 @@
+/**
+ * Types for the @ecopages/browser-router package
+ * @module
+ */
+
+import type { EcoNavigationEvent, EcoBeforeSwapEvent, EcoAfterSwapEvent } from './client/types';
+
+export type { EcoRouterOptions, EcoNavigationEvent, EcoBeforeSwapEvent, EcoAfterSwapEvent } from './client/types';
+
+export { DEFAULT_OPTIONS } from './client/types';
+
+/**
+ * Custom event map for navigation lifecycle
+ */
+export interface EcoRouterEventMap {
+	'eco:before-swap': CustomEvent<EcoBeforeSwapEvent>;
+	'eco:after-swap': CustomEvent<EcoAfterSwapEvent>;
+	'eco:page-load': CustomEvent<EcoNavigationEvent>;
+}