feat(transition): discard stale transitions when routing

Author: dvcol

src/lib/components/RouteComponent.svelte

@@ -102,12 +102,16 @@
     return _properties;
   });
 
+  const updateOnPropsChange = $derived(!!transition?.updateOnPropsChange);
+  const transitionProps = $derived([transition?.in, transition?.out, transition?.params]);
+
   // Trigger transition on route change or component update
   const transitionKey = $derived.by(() => {
-    const _keys: any[] = [routedComponent];
-    if (transition?.updateOnPropsChange) _keys.push(_properties);
+    const _keys: any[] = [routedComponent, ...transitionProps];
+    if (updateOnPropsChange) _keys.push(_properties);
     return _keys;
   });
+
   // Final unique identifier for the current route change
   let resolvedID = $state();
 

src/lib/components/RouteTransition.svelte

@@ -5,6 +5,7 @@
   import type { TransitionProps } from '~/models/component.model.js';
 
   import { toStyle } from '@dvcol/common-utils/common/class';
+  import { mutation } from '@dvcol/svelte-utils/mutation';
 
   const { children, key, id, transition }: { children: Snippet; id: string; key: any | any[]; transition: TransitionProps } = $props();
 
@@ -37,9 +38,20 @@
     if (typeof _name === 'boolean') _name = `sr-container-${id}`;
     return toStyle(`--container-transition-name: ${_name}`, _containerProps?.style);
   });
+
+  const ifElement = (node?: Node | null): HTMLElement | undefined => {
+    if (node instanceof HTMLElement) return node;
+  };
+
+  const _mutation = $derived((record: MutationRecord, index: number, entries: MutationRecord[]) => {
+    if (transition?.discard === false) return;
+    if (typeof transition?.discard === 'function' && !transition.discard(record, index, entries)) return;
+    if (!ifElement(record.previousSibling?.previousSibling)?.inert) return;
+    ifElement(record.previousSibling)?.remove();
+  });
 </script>
 
-<div data-transition-id="container" {..._containerProps} style={_style}>
+<div data-transition-id="container" {..._containerProps} style={_style} use:mutation={{ callback: _mutation, options: { childList: true } }}>
   {#if transition?.in || transition?.out}
     {#key key}
       <div data-transition-id="wrapper" in:_in={_inParams} out:_out={_outParams} {..._wrapperProps} style={toStyle(_wrapperProps?.style)}>

src/lib/models/component.model.ts

@@ -27,6 +27,8 @@ export interface RouterContextProps<Name extends RouteName = any> {
   children?: Snippet<[IRouter<Name>]>;
 }
 
+export type TransitionDiscardFunction = (entry: MutationRecord, index: number, entries: MutationRecord[]) => boolean;
+
 export interface TransitionProps<
   T extends { in?: Record<string, any>; out?: Record<string, any> } = { in?: Record<string, any>; out?: Record<string, any> },
 > {
@@ -84,6 +86,15 @@ export interface TransitionProps<
     routing?: number;
     loading?: number;
   };
+  /**
+   * Whether to discard stale transitions when multiple transitions are triggered.
+   * This is useful when the transition is triggered multiple times in quick succession and intro/outro transitions have not yet completed.
+   *
+   * By default, only the first inert elements and the latest node are kept.
+   *
+   * @default true
+   */
+  discard?: boolean | TransitionDiscardFunction;
 }
 
 export interface RouteContainerProps<Name extends RouteName = any> {