feat(transition): adds custom first transition

Author: dvcol

src/lib/components/RouteTransition.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-  import type { TransitionFunction } from '@dvcol/svelte-utils/transition';
+  import type { TransitionFunction, TransitionWithProps } from '@dvcol/svelte-utils/transition';
   import type { Snippet } from 'svelte';
 
   import type { TransitionProps } from '~/models/component.model.js';
@@ -10,23 +10,31 @@
   const { children, key, id, transition }: { children: Snippet; id: string; key: any | any[]; transition: TransitionProps } = $props();
 
   let firstRender = true;
-  const skipFirst = $derived<boolean>(transition?.skipFirst ?? true);
+  const skipFirst = $derived<TransitionProps['skipFirst']>(transition?.skipFirst ?? false);
   const skipTransition = (skip = skipFirst) => {
-    if (!firstRender || !skip) return false;
+    if (!firstRender) return false;
     firstRender = false;
-    return true;
+    return skip === true;
   };
 
+  const isTransitionFunction = (skip?: TransitionProps['skipFirst']): skip is TransitionFunction => typeof skip === 'function' && !!skip;
+  const isTransitionObject = (skip?: TransitionProps['skipFirst']): skip is TransitionWithProps => typeof skip === 'object' && !!skip?.use;
+
   const _in = $derived<TransitionFunction>(((node, props, options) => {
     if (skipTransition()) return;
+    if (firstRender && isTransitionFunction(skipFirst)) return skipFirst;
+    if (firstRender && isTransitionObject(skipFirst)) return skipFirst.use;
     return transition?.in?.(node, props, options);
   }) as TransitionFunction);
   const _out = $derived<TransitionFunction>(((node, props, options) => {
     if (firstRender && skipFirst) return;
     return transition?.out?.(node, props, options);
   }) as TransitionFunction);
 
-  const _inParams = $derived(transition?.params?.in ?? {});
+  const _inParams = $derived.by(() => {
+    if (firstRender && isTransitionObject(skipFirst) && skipFirst.props) return skipFirst.props;
+    return transition?.params?.in ?? {};
+  });
   const _outParams = $derived(transition?.params?.out ?? {});
 
   const _containerProps = $derived(transition?.props?.container);

src/lib/models/component.model.ts

@@ -1,5 +1,5 @@
 import type { Values } from '@dvcol/common-utils/common/class';
-import type { TransitionFunction } from '@dvcol/svelte-utils/transition';
+import type { TransitionFunction, TransitionProps as TransitionParams, TransitionWithProps } from '@dvcol/svelte-utils/transition';
 import type { Snippet } from 'svelte';
 import type { HTMLAttributes } from 'svelte/elements';
 
@@ -30,14 +30,14 @@ export interface RouterContextProps<Name extends RouteName = any> {
 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> },
+  T extends { in?: TransitionParams; out?: TransitionParams; first?: TransitionParams } = { in?: TransitionParams; out?: TransitionParams; first?: TransitionParams },
 > {
   /**
    * Skip the first enter transition.
    * This is useful when the first route load is fast and the transition is not needed.
-   * @default true
+   * @default false
    */
-  skipFirst?: boolean;
+  skipFirst?: boolean | TransitionFunction<T['first']> | TransitionWithProps<TransitionParams>;
   /**
    * If `true`, the transition will be updated on any route change.
    * By default, the transition is only triggered when the component changes to avoid unnecessary mounting and unmounting.

src/lib/utils/transition.utils.ts

@@ -8,5 +8,5 @@ export const transition: TransitionProps<{ in?: ScaleFreezeParams; out?: ScaleFr
   in: scaleFreeze,
   out: scaleFreeze,
   params: { in: { delay: 400 } },
-  skipFirst: true,
+  skipFirst: { use: scaleFreeze, props: { delay: 100 } },
 };