New events for Astro's view transition API

packages/astro/client.d.ts

@@ -116,10 +116,30 @@ declare module 'astro:transitions' {
 
 declare module 'astro:transitions/client' {
 	type TransitionRouterModule = typeof import('./dist/transitions/router.js');
-	export const supportsViewTransitions: TransitionRouterModule['supportsViewTransitions'];
-	export const transitionEnabledOnThisPage: TransitionRouterModule['transitionEnabledOnThisPage'];
 	export const navigate: TransitionRouterModule['navigate'];
-	export type Options = import('./dist/transitions/router.js').Options;
+
+	type TransitionUtilModule = typeof import('./dist/transitions/util.js');
+	export const supportsViewTransitions: TransitionUtilModule['supportsViewTransitions'];
+	export const getFallback: TransitionUtilModule['getFallback'];
+	export const transitionEnabledOnThisPage: TransitionUtilModule['transitionEnabledOnThisPage'];
+
+	export type Fallback = import('./dist/transitions/types.ts').Fallback;
+	export type Direction = import('./dist/transitions/types.ts').Direction;
+	export type NavigationTypeString = import('./dist/transitions/types.ts').NavigationTypeString;
+	export type Options = import('./dist/transitions/types.ts').Options;
+
+	type EventModule = typeof import('./dist/transitions/events.js');
+	export const TRANSITION_BEFORE_PREPARATION: EventModule['TRANSITION_BEFORE_PREPARATION'];
+	export const TRANSITION_AFTER_PREPARATION: EventModule['TRANSITION_AFTER_PREPARATION'];
+	export const TRANSITION_BEFORE_SWAP: EventModule['TRANSITION_BEFORE_SWAP'];
+	export const TRANSITION_AFTER_SWAP: EventModule['TRANSITION_AFTER_SWAP'];
+	export const TRANSITION_PAGE_LOAD: EventModule['TRANSITION_PAGE_LOAD'];
+	export type TransitionBeforePreparationEvent =
+		import('./dist/transitions/events.ts').TransitionBeforePreparationEvent;
+	export type TransitionBeforeSwapEvent =
+		import('./dist/transitions/events.ts').TransitionBeforeSwapEvent;
+	export const isTransitionBeforePreparationEvent: EventModule['isTransitionBeforePreparationEvent'];
+	export const isTransitionBeforeSwapEvent: EventModule['isTransitionBeforeSwapEvent'];
 }
 
 declare module 'astro:prefetch' {

packages/astro/components/ViewTransitions.astro

@@ -4,9 +4,10 @@ type Fallback = 'none' | 'animate' | 'swap';
 export interface Props {
 	fallback?: Fallback;
 	handleForms?: boolean;
+	intraPageTransitions?: boolean;
 }
 
-const { fallback = 'animate', handleForms } = Astro.props;
+const { fallback = 'animate', handleForms, intraPageTransitions } = Astro.props;
 ---
 
 <style is:global>
@@ -26,13 +27,15 @@ const { fallback = 'animate', handleForms } = Astro.props;
 <meta name="astro-view-transitions-enabled" content="true" />
 <meta name="astro-view-transitions-fallback" content={fallback} />
 {handleForms ? <meta name="astro-view-transitions-forms" content="true" /> : ''}
+{intraPageTransitions && <meta name="astro-view-transitions-intra-page" content="true" />}
 <script>
 	import type { Options } from 'astro:transitions/client';
 	import { supportsViewTransitions, navigate } from 'astro:transitions/client';
 	// NOTE: import from `astro/prefetch` as `astro:prefetch` requires the `prefetch` config to be enabled
+	// @ts-ignore
 	import { init } from 'astro/prefetch';
 
-	export type Fallback = 'none' | 'animate' | 'swap';
+	type Fallback = 'none' | 'animate' | 'swap';
 
 	function getFallback(): Fallback {
 		const el = document.querySelector('[name="astro-view-transitions-fallback"]');
@@ -77,6 +80,7 @@ const { fallback = 'animate', handleForms } = Astro.props;
 			ev.preventDefault();
 			navigate(link.href, {
 				history: link.dataset.astroHistory === 'replace' ? 'replace' : 'auto',
+				sourceElement: link,
 			});
 		});
 
@@ -94,7 +98,7 @@ const { fallback = 'animate', handleForms } = Astro.props;
 				let action = submitter?.getAttribute('formaction') ?? form.action ?? location.pathname;
 				const method = submitter?.getAttribute('formmethod') ?? form.method;
 
-				const options: Options = {};
+				const options: Options = { sourceElement: submitter ?? form };
 				if (method === 'get') {
 					const params = new URLSearchParams(formData as any);
 					const url = new URL(action);

packages/astro/e2e/view-transitions.test.js

@@ -332,6 +332,8 @@ test.describe('View Transitions', () => {
 		await page.goBack();
 		locator = page.locator('#click-one-again');
 		await expect(locator).toBeInViewport();
+
+		await page.goForward(); // prevent preemptive close of browser
 	});
 
 	test('Scroll position restored when transitioning back to fragment', async ({ page, astro }) => {

packages/astro/package.json

@@ -78,7 +78,9 @@
       "default": "./dist/core/middleware/namespace.js"
     },
     "./transitions": "./dist/transitions/index.js",
+    "./transitions/events": "./dist/transitions/events.js",
     "./transitions/router": "./dist/transitions/router.js",
+    "./transitions/types": "./dist/transitions/types.js",
     "./prefetch": "./dist/prefetch/index.js",
     "./i18n": "./dist/i18n/index.js"
   },

packages/astro/src/@types/astro.ts

@@ -82,17 +82,20 @@ export interface TransitionAnimationPair {
 	new: TransitionAnimation | TransitionAnimation[];
 }
 
-export interface TransitionDirectionalAnimations {
+export interface TransitionStrictDirectionalAnimations {
 	forwards: TransitionAnimationPair;
 	backwards: TransitionAnimationPair;
 }
 
+export type TransitionFreeDirectionalAnimations = Record<string, TransitionAnimationPair>;
+
 export type TransitionAnimationValue =
 	| 'initial'
 	| 'slide'
 	| 'fade'
 	| 'none'
-	| TransitionDirectionalAnimations;
+	| TransitionStrictDirectionalAnimations
+	| TransitionFreeDirectionalAnimations;
 
 // Allow users to extend this for astro-jsx.d.ts
 // eslint-disable-next-line @typescript-eslint/no-empty-interface

packages/astro/src/runtime/server/transition.ts

@@ -113,13 +113,18 @@ class ViewTransitionStyleSheet {
 	}
 
 	addAnimationPair(
-		direction: 'forwards' | 'backwards',
+		direction: 'forwards' | 'backwards' | string,
 		image: 'old' | 'new',
 		rules: TransitionAnimation | TransitionAnimation[]
 	) {
 		const { scope, name } = this;
 		const animation = stringifyAnimation(rules);
-		const prefix = direction === 'backwards' ? `[data-astro-transition=back]` : '';
+		const prefix =
+			direction === 'backwards'
+				? `[data-astro-transition=back]`
+				: direction === 'forwards'
+				? ''
+				: `[data-astro-transition=${direction}]`;
 		this.addRule('modern', `${prefix}::view-transition-${image}(${name}) { ${animation} }`);
 		this.addRule(
 			'fallback',

packages/astro/src/transitions/events.ts

@@ -0,0 +1,184 @@
+import { updateScrollPosition } from './router.js';
+import type { Direction, NavigationTypeString } from './types.js';
+
+export const TRANSITION_BEFORE_PREPARATION = 'astro:before-preparation';
+export const TRANSITION_AFTER_PREPARATION = 'astro:after-preparation';
+export const TRANSITION_BEFORE_SWAP = 'astro:before-swap';
+export const TRANSITION_AFTER_SWAP = 'astro:after-swap';
+export const TRANSITION_PAGE_LOAD = 'astro:page-load';
+
+type Events =
+	| typeof TRANSITION_AFTER_PREPARATION
+	| typeof TRANSITION_AFTER_SWAP
+	| typeof TRANSITION_PAGE_LOAD;
+export const triggerEvent = (name: Events) => document.dispatchEvent(new Event(name));
+export const onPageLoad = () => triggerEvent(TRANSITION_PAGE_LOAD);
+
+/*
+ * Common stuff
+ */
+class BeforeEvent extends Event {
+	readonly from: URL;
+	to: URL;
+	direction: Direction | string;
+	readonly navigationType: NavigationTypeString;
+	readonly sourceElement: Element | undefined;
+	readonly info: any;
+	newDocument: Document;
+
+	constructor(
+		type: string,
+		eventInitDict: EventInit | undefined,
+		from: URL,
+		to: URL,
+		direction: Direction | string,
+		navigationType: NavigationTypeString,
+		sourceElement: Element | undefined,
+		info: any,
+		newDocument: Document
+	) {
+		super(type, eventInitDict);
+		this.from = from;
+		this.to = to;
+		this.direction = direction;
+		this.navigationType = navigationType;
+		this.sourceElement = sourceElement;
+		this.info = info;
+		this.newDocument = newDocument;
+
+		Object.defineProperties(this, {
+			from: { enumerable: true },
+			to: { enumerable: true, writable: true },
+			direction: { enumerable: true, writable: true },
+			navigationType: { enumerable: true },
+			sourceElement: { enumerable: true },
+			info: { enumerable: true },
+			newDocument: { enumerable: true, writable: true },
+		});
+	}
+}
+
+/*
+ * TransitionBeforePreparationEvent
+
+ */
+export const isTransitionBeforePreparationEvent = (
+	value: any
+): value is TransitionBeforePreparationEvent => value.type === TRANSITION_BEFORE_PREPARATION;
+export class TransitionBeforePreparationEvent extends BeforeEvent {
+	formData: FormData | undefined;
+	loader: () => Promise<void>;
+	constructor(
+		from: URL,
+		to: URL,
+		direction: Direction | string,
+		navigationType: NavigationTypeString,
+		sourceElement: Element | undefined,
+		info: any,
+		newDocument: Document,
+		formData: FormData | undefined,
+		loader: (event: TransitionBeforePreparationEvent) => Promise<void>
+	) {
+		super(
+			TRANSITION_BEFORE_PREPARATION,
+			{ cancelable: true },
+			from,
+			to,
+			direction,
+			navigationType,
+			sourceElement,
+			info,
+			newDocument
+		);
+		this.formData = formData;
+		this.loader = loader.bind(this, this);
+		Object.defineProperties(this, {
+			formData: { enumerable: true },
+			loader: { enumerable: true, writable: true },
+		});
+	}
+}
+
+/*
+ * TransitionBeforeSwapEvent
+ */
+
+export const isTransitionBeforeSwapEvent = (value: any): value is TransitionBeforeSwapEvent =>
+	value.type === TRANSITION_BEFORE_SWAP;
+export class TransitionBeforeSwapEvent extends BeforeEvent {
+	readonly direction: Direction | string;
+	readonly viewTransition: ViewTransition;
+	swap: () => void;
+
+	constructor(
+		afterPreparation: BeforeEvent,
+		viewTransition: ViewTransition,
+		swap: (event: TransitionBeforeSwapEvent) => void
+	) {
+		super(
+			TRANSITION_BEFORE_SWAP,
+			undefined,
+			afterPreparation.from,
+			afterPreparation.to,
+			afterPreparation.direction,
+			afterPreparation.navigationType,
+			afterPreparation.sourceElement,
+			afterPreparation.info,
+			afterPreparation.newDocument
+		);
+		this.direction = afterPreparation.direction;
+		this.viewTransition = viewTransition;
+		this.swap = swap.bind(this, this);
+
+		Object.defineProperties(this, {
+			direction: { enumerable: true },
+			viewTransition: { enumerable: true },
+			swap: { enumerable: true, writable: true },
+		});
+	}
+}
+
+export async function doPreparation(
+	from: URL,
+	to: URL,
+	direction: Direction | string,
+	navigationType: NavigationTypeString,
+	sourceElement: Element | undefined,
+	info: any,
+	formData: FormData | undefined,
+	defaultLoader: (event: TransitionBeforePreparationEvent) => Promise<void>
+) {
+	const event = new TransitionBeforePreparationEvent(
+		from,
+		to,
+		direction,
+		navigationType,
+		sourceElement,
+		info,
+		window.document,
+		formData,
+		defaultLoader
+	);
+	if (document.dispatchEvent(event)) {
+		await event.loader();
+		if (!event.defaultPrevented) {
+			triggerEvent(TRANSITION_AFTER_PREPARATION);
+			if (event.navigationType !== 'traverse') {
+				// save the current scroll position before we change the DOM and transition to the new page
+				updateScrollPosition({ scrollX, scrollY });
+			}
+		}
+	}
+	return event;
+}
+
+export async function doSwap(
+	afterPreparation: BeforeEvent,
+	viewTransition: ViewTransition,
+	defaultSwap: (event: TransitionBeforeSwapEvent) => void
+) {
+	const event = new TransitionBeforeSwapEvent(afterPreparation, viewTransition, defaultSwap);
+	document.dispatchEvent(event);
+	event.swap();
+	return event;
+}

packages/astro/src/transitions/index.ts

@@ -1,12 +1,15 @@
-import type { TransitionAnimationPair, TransitionDirectionalAnimations } from '../@types/astro.js';
+import type {
+	TransitionAnimationPair,
+	TransitionStrictDirectionalAnimations,
+} from '../@types/astro.js';
 
 const EASE_IN_OUT_QUART = 'cubic-bezier(0.76, 0, 0.24, 1)';
 
 export function slide({
 	duration,
 }: {
 	duration?: string | number;
-} = {}): TransitionDirectionalAnimations {
+} = {}): TransitionStrictDirectionalAnimations {
 	return {
 		forwards: {
 			old: [
@@ -50,7 +53,7 @@ export function fade({
 	duration,
 }: {
 	duration?: string | number;
-} = {}): TransitionDirectionalAnimations {
+} = {}): TransitionStrictDirectionalAnimations {
 	const anim = {
 		old: {
 			name: 'astroFadeOut',