Merge pull request #9 from Applelo/dev

Version 2.0.0
Applelo · May 3, 2024 · e0478b0 · e0478b0
2 parents d448177 + 2bb71c2
commit e0478b0
Show file tree

Hide file tree

Showing 15 changed files with 3,862 additions and 3,398 deletions.
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -14,14 +14,14 @@ Lay out the reasoning behind it and ideally, you should have a practical example
 
 ## Pull Requests
 
-I only accept contributions via Pull Requests on [Github](https://github.com/{{ githubAccount }}/{{ name }}).
+I only accept contributions via Pull Requests on [Github](https://github.com/Applelo/blottie).
 
 Here are some guidelines to make the process smoother and easier for me and you:
 
 - **Add a test** - New features and maybe bugs need tests. If you find it difficult to test, please tell me in the pull request and I will try to help you!
 - **Document any change in behaviour** - Make sure the `README.md` and any other relevant documentation are kept up-to-date.
-- **Run `pnpm test` locally** - This will allow you to go faster
-- **Run `pnpm lint` and `pnpm typechecking` locally** - This will prevent you to have surprise for not respecting eslint config and problem with typescript
+- **Run `pnpm cypress` locally** - This will allow you to go faster
+- **Run `pnpm lint` and `pnpm typecheck` locally** - This will prevent you to have surprise for not respecting eslint config and problem with typescript
 - **One pull request per feature** - If you want to do more than one thing, send multiple pull requests.
 - **Send coherent history** - Make sure your commits message means something
 

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -19,7 +19,7 @@ jobs:
 
       - uses: pnpm/[email protected]
         with:
-          version: 8
+          version: 9
 
       - name: Set node version to 20
         uses: actions/setup-node@v3

diff --git a/LICENCE b/LICENCE
diff --git a/README.md b/README.md
@@ -8,8 +8,9 @@ Blottie is the verb `blottir` in french meaning `snuggle` (yes I was looking for
 
 ## Features
 
-- 🔥 Integrated with VueJS with all Lottie `loadAnimations` [options](https://github.com/airbnb/lottie-web#other-loading-options) and [events](https://github.com/airbnb/lottie-web#events)
-- 🚀 Load automatically the best renderer : you can't be lighter
+- 🔥 Integrated to VueJS with all Lottie `loadAnimations` [options](https://github.com/airbnb/lottie-web#other-loading-options) and [events](https://github.com/airbnb/lottie-web#events)
+- 😎 Available through `Blottie` component or `useBlottie` composable.
+- 🚀 Load automatically the best renderer: you can't be lighter
 - 📠 Fully typed
 - ✨ Expose lottie player/animation for more control and customization
 
@@ -23,10 +24,15 @@ yarn add -D blottie
 
 # pnpm
 pnpm add -D blottie
+
+#bun
+bun add -D blottie
 ```
 
 ## Usage
 
+### Component
+
 ```vue
 <script setup lang="ts">
 import type { AnimationItem } from 'lottie-web'
@@ -45,9 +51,11 @@ function onReady(anim?: AnimationItem) {
 <template>
   <Blottie
     ref="blottie"
-    :loop="true"
-    renderer="svg"
-    path="/my-lottie-anim.json"
+    :lottie="{
+      loop: true,
+      renderer: 'svg',
+      path: '/my-lottie-anim.json',
+    }"
     @ready="onReady"
     @enter-frame="onFrame"
   />
@@ -61,24 +69,34 @@ If you don't use the renderer prop, it will use the default LottiePlayer which c
 
 ### Props
 
-The Blottie component accepts all [loadAnimation options](https://github.com/airbnb/lottie-web#other-loading-options). You can pass a Lottie Animation JSON via the `path` prop (relative or absolute link) or directly by importing the json file as an object in the `animation-data` prop.
+The Blottie component accepts all [loadAnimation options](https://github.com/airbnb/lottie-web#other-loading-options) through `lottie` prop. You can pass a Lottie Animation JSON via the `path` option (relative or absolute link) or directly by importing the json file as an object in the `animationData` option.
 
-By default, Blottie will load the lighter version (`light`) of Lottie for the renderer you choose. If necessary, you can enforce the lottie player with the `player` option : `canvas_worker`, `canvas`, `light_canvas`, `html`, `light_html`, `light`, `svg`, `worker` or `default`.
+By default, Blottie will load the lighter version (`light`) of Lottie for the renderer you choose. If necessary, you can enforce the lottie player with the `player` option (inside the `lottie` prop) : `canvas_worker`, `canvas`, `light_canvas`, `html`, `light_html`, `light`, `svg`, `worker` or `default`.
 
 ```vue
+<script lang="ts" setup>
+import { Blottie } from 'blottie'
+</script>
+
 <template>
-  <Blottie player="svg" renderer="svg" path="/my-lottie-anim.json" />
+  <Blottie
+    :lottie="{
+      player: 'svg',
+      renderer: 'svg',
+      path: '/my-lottie-anim.json',
+    }"
+  />
 </template>
 ```
 
 If needed, you can access the lottie player before the lottie `loadAnimation` method. You can use the `before-init` prop allowing you to pass an asynchrone callback with the player as an argument (check the example below).
 
-This is necessary for allowing to use `setLocationHref` to [fix Safari issue](https://github.com/airbnb/lottie-web#issues).
+> This is necessary for allowing to use `setLocationHref` to [fix Safari issue](https://github.com/airbnb/lottie-web#issues).
 
 ```vue
 <script setup lang="ts">
 import type { LottiePlayer } from 'lottie-web'
-import { Blottie } from './../..'
+import { Blottie } from 'blottie'
 
 async function beforeInit(player: LottiePlayer) {
   console.log(player)
@@ -89,9 +107,11 @@ async function beforeInit(player: LottiePlayer) {
   <div>
     <Blottie
       class="animation"
-      path="vue-js.json"
       :before-init="beforeInit"
-      :autoplay="true"
+      :lottie="{
+        path: 'vue-js.json',
+        autoplay: true,
+      }"
     />
   </div>
 </template>
@@ -100,8 +120,18 @@ async function beforeInit(player: LottiePlayer) {
 An additional prop `container-tag` is available to change the default `div` tag container.
 
 ```vue
+<script lang="ts" setup>
+import { Blottie } from 'blottie'
+</script>
+
 <template>
-  <Blottie container-tag="main" renderer="svg" path="/my-lottie-anim.json" />
+  <Blottie
+    container-tag="main"
+    :lottie="{
+      renderer: 'svg',
+      path: '/my-lottie-anim.json',
+    }"
+  />
 </template>
 ```
 
@@ -135,8 +165,10 @@ const blottie = ref<BlottieExpose>()
     <Blottie
       ref="blottie"
       class="animation"
-      :animation-data="animationData"
-      renderer="canvas"
+      :lottie="{
+        animationData: 'animationData',
+        renderer: 'canvas',
+      }"
     />
     <div v-if="blottie && blottie.anim" class="controls">
       <progress
@@ -170,9 +202,88 @@ const blottie = ref<BlottieExpose>()
 
 You can use the slot `loading` to insert content inside the container to wait the display like a temporary fallback.
 
+```vue
+<script lang="ts" setup>
+import { Blottie } from 'blottie'
+</script>
+
+<template>
+  <Blottie
+    :lottie="{
+      autoplay: true,
+      loop: true,
+      path: '/my-lottie-anim.json',
+    }"
+  >
+    <template #loading>
+      Loading...
+    </template>
+  </Blottie>
+</template>
+```
+
+### Composable
+
+Since 2.0, you can use the composable `useBlottie`. This allowing you full control to create a custom component if  you need it.
+
+The first argument is a [template ref](https://vuejs.org/guide/essentials/template-refs.html#template-refs).
+The second argument is an object accepting all [loadAnimation options](https://github.com/airbnb/lottie-web#other-loading-options).
+
+```vue
+<script setup lang="ts">
+import { useBlottie } from 'blottie'
+const el = ref<HTMLElement | null>(null)
+const { lottie, anim } = useBlottie(el, {
+  player: 'svg',
+  renderer: 'svg',
+  path: '/my-lottie-anim.json',
+})
+</script>
+
+<template>
+  <div>
+    <div ref="el" class="blottie" />
+    <button @click="lottie.play()">
+      Play
+    </button>
+  </div>
+</template>
+```
+
+## Migration from 1.0 to 2.0
+
+All Lottie options are now move into `lottie` attribute to use typings from lottie (and not a version provided by Blottie).
+
+For example, if you have this
+```vue
+<template>
+  <Blottie
+    class="animation"
+    path="https://assets6.lottiefiles.com/packages/lf20_bXGMKilbSf.json"
+    :loop="true"
+    container-tag="main"
+    @ready="onReady"
+  >
+    <template #loading>
+      Loading...
+    </template>
+  </Blottie>
+</template>
+```
+
+This will be change to this
 ```vue
 <template>
-  <Blottie :autoplay="true" :loop="true" path="/my-lottie-anim.json">
+  <Blottie
+    class="animation"
+    :lottie="{
+      loop: true,
+      path: 'https://assets6.lottiefiles.com/packages/lf20_bXGMKilbSf.json',
+    }"
+    container-tag="main"
+    @ready="onReady"
+    @loop-complete="onLoop"
+  >
     <template #loading>
       Loading...
     </template>
@@ -192,4 +303,4 @@ LottieFiles provides a player named [lottie-player](https://github.com/LottieFil
 
 ## 👨‍💼 Licence
 
-GPL-3.0
+MIT
diff --git a/cypress/test/Blottie.cy.ts b/cypress/test/Blottie.cy.ts
@@ -18,10 +18,12 @@ describe('<Blottie />', () => {
             class: 'animation',
           },
           props: {
-            autoplay: true,
-            loop: true,
-            animationData: animVueJS,
-            renderer: key,
+            lottie: {
+              autoplay: true,
+              loop: true,
+              animationData: animVueJS,
+              renderer: key,
+            },
           },
         })
 
@@ -36,10 +38,12 @@ describe('<Blottie />', () => {
         class: 'animation',
       },
       props: {
-        autoplay: true,
-        loop: true,
-        path: 'https://assets5.lottiefiles.com/packages/lf20_z49WoSvxKM.json',
-        renderer: 'svg',
+        lottie: {
+          autoplay: true,
+          loop: true,
+          path: 'https://assets5.lottiefiles.com/packages/lf20_z49WoSvxKM.json',
+          renderer: 'svg',
+        },
         beforeInit: async () => {
           await new Promise<void>((resolve) => {
             setTimeout(() => {
@@ -58,26 +62,28 @@ describe('<Blottie />', () => {
 
   it('events', () => {
     const onReadySpy = cy.spy().as('onReadySpy')
-    const onEnterFrameSpy = cy.spy().as('onEnterFrameSpy')
-    const onLoopCompleteSpy = cy.spy().as('onLoopCompleteSpy')
+    // const onEnterFrameSpy = cy.spy().as('onEnterFrameSpy')
+    // const onLoopCompleteSpy = cy.spy().as('onLoopCompleteSpy')
     const onDrawnFrameSpy = cy.spy().as('onDrawnFrameSpy')
 
     cy.mount(Blottie, {
       props: {
-        autoplay: true,
-        loop: true,
-        animationData: animVueJS,
-        renderer: 'svg',
+        lottie: {
+          autoplay: true,
+          loop: true,
+          animationData: animVueJS,
+          renderer: 'svg',
+        },
         onReady: onReadySpy,
-        onEnterFrame: onEnterFrameSpy,
+        // onEnterFrame: onEnterFrameSpy,
         onDrawnFrame: onDrawnFrameSpy,
-        onLoopComplete: onLoopCompleteSpy,
+        // onLoopComplete: onLoopCompleteSpy,
       },
     })
 
     cy.get('@onReadySpy').should('have.been.calledOnce')
-    cy.get('@onEnterFrameSpy').should('have.been.called')
+    // cy.get('@onEnterFrameSpy').should('have.been.called')
     cy.get('@onDrawnFrameSpy').should('have.been.called')
-    cy.get('@onLoopCompleteSpy').should('have.been.called')
+    // cy.get('@onLoopCompleteSpy').should('have.been.called')
   })
 })
diff --git a/cypress/tsconfig.json b/cypress/tsconfig.json
@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "target": "es5",
+    "lib": ["es5", "dom"],
+    "resolveJsonModule": true,
+    "types": ["cypress", "node"],
+    "esModuleInterop": true
+  },
+  "include": ["**/*.ts"]
+}
diff --git a/demo/package.json b/demo/package.json
@@ -9,12 +9,13 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "vue": "^3.3.10"
+    "vue": "^3.4.26"
   },
   "devDependencies": {
-    "@vitejs/plugin-vue": "^4.5.2",
-    "typescript": "^5.3.3",
-    "vite": "^4.5.1",
-    "vue-tsc": "^1.8.25"
+    "@vitejs/plugin-vue": "^5.0.4",
+    "blottie": "workspace:*",
+    "typescript": "^5.4.5",
+    "vite": "^5.2.11",
+    "vue-tsc": "^2.0.16"
   }
 }