feat: keep alive mode to handle vue transitions

Author: juliendargelos

playground/App.vue

@@ -15,6 +15,7 @@
   const index = ref(0)
   const id = ref('')
 
+  const destroy = shallowRef<() => void>()
   const player = shallowRef<Player>()
   const paused = ref(false)
   const muted = ref(true)
@@ -106,23 +107,31 @@
       </form>
     </div>
     <div>
-      <FreecasterPlayer
-        v-if="mounted"
-        class="player"
-        :video-id="ids[index]"
-        controls
-        autoplay
-        subtitles-default-lang="fr"
-        v-model="player"
-        v-model:paused="paused"
-        v-model:muted="muted"
-        v-model:current-time="currentTime"
-        v-model:fullscreen="fullscreen"
-        v-model:volume="volume"
-        v-model:ready-state="readyState"
-        v-model:current-subtitles="currentSubtitles"
-        v-model:subtitles="subtitles"
-      />
+      <transition
+        mode="out-in"
+        @after-leave="destroy()"
+      >
+        <FreecasterPlayer
+          v-if="mounted"
+          ref="component"
+          class="player"
+          :video-id="ids[index]"
+          controls
+          autoplay
+          subtitles-default-lang="fr"
+          keep-alive
+          v-model="player"
+          v-model:paused="paused"
+          v-model:muted="muted"
+          v-model:current-time="currentTime"
+          v-model:fullscreen="fullscreen"
+          v-model:volume="volume"
+          v-model:ready-state="readyState"
+          v-model:current-subtitles="currentSubtitles"
+          v-model:subtitles="subtitles"
+          v-model:destroy="destroy"
+        />
+      </transition>
       <div class="controls">
         <button @click="paused = !paused">
           {{ paused ? 'play' : 'pause' }}
@@ -259,6 +268,14 @@
     position: relative;
     margin: 0;
     display: block !important;
+
+    &.v-enter-from, &.v-leave-to {
+      opacity: 0;
+    }
+
+    &.v-enter-active, &.v-leave-active {
+      transition: opacity .2s;
+    }
   }
 
   .controls {

src/components/FreecasterPlayer.vue

@@ -4,7 +4,7 @@
   import type { Player, PlayerOptions, PlayerEvents } from '../types/Player'
 
   export interface FreecasterPlayerProps extends PlayerOptions {
-
+    keepAlive?: boolean
   }
 
   export type FreecasterPlayerEmits = PlayerEvents
@@ -21,18 +21,7 @@
   const readyState = defineModel<number>('readyState', { default: 0 })
   const currentSubtitles = defineModel<TextTrack>('currentSubtitles')
   const subtitles = defineModel<TextTrack[]>('subtitles', { default: [] })
-
-  defineExpose({
-    player,
-    paused,
-    muted,
-    fullscreen,
-    volume,
-    currentTime,
-    readyState,
-    currentSubtitles,
-    subtitles
-  })
+  const destroyModel = defineModel<() => void>('destroy')
 
   const options = computed(() => ({
     videoId: props.videoId,
@@ -71,7 +60,8 @@
 
   const attrs = useAttrs()
 
-  const { element, key, attributes } = usePlayer({
+  const { element, key, attributes, destroy } = usePlayer({
+    keepAlive: computed(() => props.keepAlive),
     options,
     player,
     paused,
@@ -84,6 +74,21 @@
     currentSubtitles,
     subtitles,
   })
+
+  destroyModel.value = destroy
+
+  defineExpose({
+    player,
+    paused,
+    muted,
+    fullscreen,
+    volume,
+    currentTime,
+    readyState,
+    currentSubtitles,
+    subtitles,
+    destroy
+  })
 </script>
 
 <template>

src/composables/player.ts

@@ -6,6 +6,7 @@ import {
   shallowRef,
   toRef,
   isRef,
+  unref,
   type Ref,
   type MaybeRefOrGetter,
   type MaybeRef,
@@ -84,6 +85,15 @@ export interface UsePlayerParameters {
    */
   element?: MaybeRef<HTMLElement | undefined>
 
+  /**
+   * Wether to keep the player instance alive after the component is unmounted.
+   * It can then be manually destroyed by calling
+   * {@link UsePlayerContext.destroy}. This can be useful to keep the player
+   * instance alive during vue leave transitions.
+   * @default false
+   */
+  keepAlive?: MaybeRef<boolean>
+
   /**
    * Default event listener, called for all events
    * @default undefined
@@ -105,12 +115,46 @@ export interface UsePlayerParameters {
 }
 
 export interface UsePlayerContext extends UsePlayerParameters {
+  /**
+   * Ref to the freecaster load function.
+   */
   load: Ref<((element: Element) => void) | undefined>
+
+  /**
+   * Destroy the currently attached player instance.
+   */
+  destroy: () => void
+
+  /**
+   * Event listeners for the player.
+   */
   listeners: Required<UsePlayerParameters>['listeners']
+
+  /**
+   * Player options provided in {@link UsePlayerParameters.options}.
+   */
   options: Ref<PlayerOptions | undefined>
+
+  /**
+   * Ref to the player instance.
+   */
   player: Ref<Player | undefined>
+
+  /**
+   * Ref to the element where the player is attached. Can be passed to the
+   * special ref prop of an element to attach the player to.
+   */
   element: Ref<HTMLElement | undefined>
+
+  /**
+   * Ref to the player attributes that can be used to bind to the player. Can be
+   * passed the v-bind directive of an element to attach the player to.
+   */
   attributes: Ref<PlayerAttributes>
+
+  /**
+   * Ref to a key that is updated every time the player loads a new video.
+   */
   key: Ref<number>
 }
 
@@ -124,6 +168,7 @@ export function usePlayer(parameters: UsePlayerParameters = {}): UsePlayerContex
 
   const context: UsePlayerContext = {
     ...parameters,
+    destroy: () => remove(context),
     load: shallowRef(),
     listeners,
     key: shallowRef(0),
@@ -281,6 +326,10 @@ function useLifecycle({
   options,
   ...context
 }: UsePlayerContext): void {
+  if (context.player.value) {
+    context.player.value = undefined
+  }
+
   let loadInterval: ReturnType<typeof setInterval>
 
   const initialize = (value: Player) => {
@@ -321,7 +370,7 @@ function useLifecycle({
     clearInterval(loadInterval)
     const index = (window._fcpr ||= []).indexOf(initialize)
     index === -1 || _fcpr.splice(index, 1)
-    remove(context)
+    unref(context.keepAlive) || context.destroy()
   })
 }
 

src/index.ts

@@ -5,8 +5,7 @@ export * from './composables/player'
 export {
   default as FreecasterPlayer,
   type FreecasterPlayerProps,
-  type FreecasterPlayerEmits,
-  type FreecasterPlayerSlots
+  type FreecasterPlayerEmits
 } from './components/FreecasterPlayer.vue'
 
 export {