feat: 🎸 dotlottie web component (LottieFiles#44)

* feat: 🎸 @lottiefiles/dotlottie-wc initial implementation * chore: 🤖 update README * chore: 🤖 updates * chore: 🤖 update dotlottie-wc * chore: 🤖 update example * chore: 🤖 update README * chore: 🤖 update README * feat: 🎸 auto freeze/unfreeze on document visibility change
sheey11 · Dec 21, 2023 · b226dd7 · b226dd7
1 parent 8732113
commit b226dd7
Show file tree

Hide file tree

Showing 21 changed files with 609 additions and 13 deletions.
diff --git a/.size-limit.cjs b/.size-limit.cjs
@@ -1,4 +1,4 @@
-const dotLottieWebConfig = [
+module.exports = [
   {
     name: '@lottiefiles/dotlottie-web',
     path: 'packages/web/dist/index.js',
@@ -28,6 +28,9 @@ const dotLottieWebConfig = [
       return config;
     },
   },
+  {
+    name: '@lottiefiles/dotlottie-wc',
+    path: 'packages/wc/dist/index.js',
+    import: '*',
+  },
 ];
-
-module.exports = [...dotLottieWebConfig];
diff --git a/README.md b/README.md
@@ -30,7 +30,6 @@ dotLottie is an open-source file format that aggregates one or more Lottie files
 ## Contents
 
 * [Packages](#packages)
-* [Coming Soon Packages](#coming-soon-packages)
 * [Getting Started](#getting-started)
   * [Prerequisites](#prerequisites)
   * [Setup](#setup)
@@ -47,18 +46,22 @@ dotLottie is an open-source file format that aggregates one or more Lottie files
 
 The monorepo contains the following package:
 
-* **[@lottiefiles/dotlottie-web](packages/web/README.md)**: A JavaScript library for rendering Lottie and dotLottie animations in the browser.
-* **[@lottiefiles/dotlottie-react](packages/react/README.md)**: A React component wrapper for `@lottiefiles/dotlottie-web` that provides a declarative API for rendering Lottie and dotLottie animations and UI controls for interacting with them.
+| Package                                                      | Description                                                                                                                                                            |
+| ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **[@lottiefiles/dotlottie-web](packages/web/README.md)**     | A JavaScript library for rendering Lottie and dotLottie animations in the browser or Node.js.                                                                          |
+| **[@lottiefiles/dotlottie-react](packages/react/README.md)** | A React component wrapper for `dotlottie-web` that provides a declarative API for rendering Lottie and dotLottie animations and UI controls for interacting with them. |
+| **[@lottiefiles/dotlottie-wc](packages/wc/README.md)**       | A Web Component wrapper for `dotlottie-web` that provides a declarative API for rendering Lottie and dotLottie animations and UI controls for interacting with them.   |
 
-Each package has its own README.md with detailed documentation on usage and APIs.
+> Note: Each package has its own README.md with detailed documentation on usage and APIs.
 
 ### Coming Soon Packages
 
 We are actively working on expanding our suite of packages. Here's what's coming soon:
 
-* **@lottiefiles/dotlottie-wc**: A Web Component wrapper for `@lottiefiles/dotlottie-web` that provides a declarative API for rendering Lottie and dotLottie animations and UI controls for interacting with them.
-* **@lottiefiles/dotlottie-vue**: A Vue component wrapper for `@lottiefiles/dotlottie-web` that provides a declarative API for rendering Lottie and dotLottie animations and UI controls for interacting with them.
-* **@lottiefiles/dotlottie-svelte**: A Svelte component wrapper for `@lottiefiles/dotlottie-web` that provides a declarative API for rendering Lottie and dotLottie animations and UI controls for interacting with them.
+| Package                         | Description                                                                                                                                                             |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@lottiefiles/dotlottie-vue`    | A Vue component wrapper for `dotlottie-web` that provides a declarative API for rendering Lottie and dotLottie animations and UI controls for interacting with them.    |
+| `@lottiefiles/dotlottie-svelte` | A Svelte component wrapper for `dotlottie-web` that provides a declarative API for rendering Lottie and dotLottie animations and UI controls for interacting with them. |
 
 Stay tuned for updates and releases of these new packages!
 

diff --git a/apps/dotlottie-wc-example/.gitignore b/apps/dotlottie-wc-example/.gitignore
@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
diff --git a/apps/dotlottie-wc-example/index.html b/apps/dotlottie-wc-example/index.html
@@ -0,0 +1,18 @@
+<!DOCTYPE html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>dotlottie-wc basic example</title>
+    </head>
+    <body>
+        <div id="app"></div>
+        <dotlottie-wc
+            src="https://lottie.host/0e2d86ab-604d-4fc4-8512-d44a30eb81a8/YFj05ZHqHA.json"
+            autoplay
+            loop
+        ></dotlottie-wc>
+        <script type="module" src="/src/main.ts"></script>
+    </body>
+</html>
diff --git a/apps/dotlottie-wc-example/package.json b/apps/dotlottie-wc-example/package.json
@@ -0,0 +1,18 @@
+{
+  "name": "@lottiefiles/dotlottie-wc-example",
+  "version": "0.0.0",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "build": "tsc && vite build",
+    "dev": "vite dev --port 3001",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@lottiefiles/dotlottie-wc": "workspace:*"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.2",
+    "vite": "^4.4.5"
+  }
+}
diff --git a/apps/dotlottie-wc-example/public/vite.svg b/apps/dotlottie-wc-example/public/vite.svg
diff --git a/apps/dotlottie-wc-example/src/main.ts b/apps/dotlottie-wc-example/src/main.ts
@@ -0,0 +1,42 @@
+/**
+ * Copyright 2023 Design Barn Inc.
+ */
+
+// eslint-disable-next-line import/no-unassigned-import
+import '@lottiefiles/dotlottie-wc';
+
+import type { DotLottieWC } from '@lottiefiles/dotlottie-wc';
+
+const app = document.querySelector<HTMLDivElement>('#app');
+
+if (app) {
+  app.innerHTML = `
+    <button id="play">play</button>
+    <button id="pause">pause</button>
+    <button id="stop">stop</button>
+  `;
+}
+
+const dotlottieComponent = document.querySelector('dotlottie-wc') as DotLottieWC;
+
+const playButton = document.querySelector('#play');
+const pauseButton = document.querySelector('#pause');
+const stopButton = document.querySelector('#stop');
+
+if (playButton) {
+  playButton.addEventListener('click', () => {
+    dotlottieComponent.dotLottie?.play();
+  });
+}
+
+if (pauseButton) {
+  pauseButton.addEventListener('click', () => {
+    dotlottieComponent.dotLottie?.pause();
+  });
+}
+
+if (stopButton) {
+  stopButton.addEventListener('click', () => {
+    dotlottieComponent.dotLottie?.stop();
+  });
+}
diff --git a/apps/dotlottie-wc-example/src/vite-env.d.ts b/apps/dotlottie-wc-example/src/vite-env.d.ts
@@ -0,0 +1,5 @@
+/**
+ * Copyright 2023 Design Barn Inc.
+ */
+
+/// <reference types="vite/client" />
diff --git a/apps/dotlottie-wc-example/tsconfig.json b/apps/dotlottie-wc-example/tsconfig.json
@@ -0,0 +1,9 @@
+{
+  // Extend from the build config
+  "extends": "../../tsconfig.dev.json",
+
+  // Compiler options
+  "compilerOptions": {},
+
+  "include": ["src"]
+}
diff --git a/apps/dotlottie-web-example/package.json b/apps/dotlottie-web-example/package.json
@@ -4,7 +4,7 @@
   "private": true,
   "scripts": {
     "build": "tsc && vite build",
-    "dev": "vite",
+    "dev": "vite dev --port 3000",
     "preview": "vite preview"
   },
   "dependencies": {

diff --git a/package.json b/package.json
@@ -17,7 +17,7 @@
     "deps:upgrade": "ncu --deep --format repo -i --removeRange",
     "dev": "turbo run dev --parallel",
     "docs:readme": "remark ./**/README.md --output --ignore-path ./.remarkignore --silently-ignore",
-    "format": "pnpm run format:prettier",
+    "format": "pnpm run format:prettier && pnpm run format:remark",
     "format:prettier": "prettier --loglevel=warn --no-editorconfig --write .",
     "format:remark": "remark . --output --ignore-path .remarkignore --silently-ignore",
     "lint": "eslint .",

diff --git a/packages/wc/README.md b/packages/wc/README.md
@@ -0,0 +1,133 @@
+# @lottiefiles/dotlottie-wc
+
+![npm](https://img.shields.io/npm/v/@lottiefiles/dotlottie-wc)
+![npm bundle size](https://img.shields.io/bundlephobia/minzip/%40lottiefiles%2Fdotlottie-wc)
+![npm](https://img.shields.io/npm/dt/%40lottiefiles%2Fdotlottie-wc)
+![NPM](https://img.shields.io/npm/l/@lottiefiles/dotlottie-wc)
+
+<p align="center">
+  <img src="https://user-images.githubusercontent.com/23125742/201124166-c2a0bc2a-018b-463b-b291-944fb767b5c2.png" />
+</p>
+
+> 🚧 **Beta Alert:** We're still refining! The APIs in this package may undergo changes.
+
+## Contents
+
+* [Introduction](#introduction)
+  * [What is dotLottie?](#what-is-dotlottie)
+* [Installation](#installation)
+* [Usage](#usage)
+  * [Via npm](#via-npm)
+  * [Via CDN](#via-cdn)
+* [APIs](#apis)
+  * [Attributes](#attributes)
+* [RenderConfig](#renderconfig)
+  * [Properties](#properties)
+* [Development](#development)
+  * [Setup](#setup)
+  * [Dev](#dev)
+  * [Build](#build)
+
+## Introduction
+
+A web component for rendering and playing [Lottie](https://lottiefiles.github.io/lottie-docs/) and [DotLottie](https://dotlottie.io) animations in web applications.
+
+### What is dotLottie?
+
+dotLottie is an open-source file format that aggregates one or more Lottie files and their associated resources into a single file. They are ZIP archives compressed with the Deflate compression method and carry the file extension of ".lottie".
+
+[Learn more about dotLottie](https://dotlottie.io/).
+
+## Installation
+
+```bash
+npm install @lottiefiles/dotlottie-wc
+```
+
+## Usage
+
+### Via npm
+
+After installation, you can use `dotlottie-wc` in your HTML file:
+
+```html
+<dotlottie-wc src="https://lottie.host/4db68bbd-31f6-4cd8-84eb-189de081159a/IGmMCqhzpt.lottie" autoplay="true" loop="true"></dotlottie-wc>
+```
+
+And import it in your JavaScript or TypeScript module:
+
+```js
+import '@lottiefiles/dotlottie-wc';
+```
+
+### Via CDN
+
+You can also use the component directly via a npm CDN:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8" />
+    <title>@lottiefiles/dotlottie-wc | Basic Example</title>
+</head>
+<body>
+    <dotlottie-wc src="https://lottie.host/4db68bbd-31f6-4cd8-84eb-189de081159a/IGmMCqhzpt.lottie" autoplay loop></dotlottie-wc>
+    <script type="module" src="https://unpkg.com/@lottiefiles/dotlottie-wc@latest/dist/dotlottie-wc.js"></script>
+</body>
+</html>
+```
+
+## APIs
+
+### Attributes
+
+The `dotlottie-wc` component accepts all configuration attributes of [`DotLottie`](../web/README.md#apis) from `@lottiefiles/dotlottie-web`, allowing you to customize your animation as required.
+
+| Attribute         | Type                  | Description                                                                                      |
+| ----------------- | --------------------- | ------------------------------------------------------------------------------------------------ |
+| `src`             | string                | URL of the Lottie or DotLottie animation.                                                        |
+| `autoplay`        | boolean               | Automatically start the animation.                                                               |
+| `loop`            | boolean               | Loop the animation.                                                                              |
+| `speed`           | number                | Playback speed.                                                                                  |
+| `data`            | string                | Animation data as a string or ArrayBuffer for .lottie animations.                                |
+| `segments`        | Array                 | Animation segments as an array of two numbers (start frame and end frame).                       |
+| `mode`            | string                | Animation play mode (e.g., "forward", "bounce").                                                 |
+| `backgroundColor` | string                | Background color of the canvas. Accepts 6-digit or 8-digit hex color string (e.g., "#000000FF"). |
+| `renderConfig`    | Object (RenderConfig) | Configuration for rendering the animation.                                                       |
+
+## RenderConfig
+
+The `renderConfig` object accepts the following properties:
+
+| Property name      | Type   | Required | Default                       | Description             |
+| ------------------ | ------ | :------: | ----------------------------- | ----------------------- |
+| `devicePixelRatio` | number |          | window\.devicePixelRatio \| 1 | The device pixel ratio. |
+
+### Properties
+
+The `dotlottie-wc` exposes the following properties:
+
+| Property name | Type        | Description                                                                                                                                                |
+| ------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `dotLottie`   | `DotLottie` | The dotLottie instance from [`DotLottie`](../web/README.md#apis)  , allowing you to call methods and listen to events for more control over the animation. |
+
+## Development
+
+### Setup
+
+```bash
+npm install
+```
+
+### Dev
+
+```bash
+npm run dev
+```
+
+### Build
+
+```bash
+npm run build
+```
diff --git a/packages/wc/example.html b/packages/wc/example.html
@@ -0,0 +1,21 @@
+<!DOCTYPE html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>Quick example</title>
+    </head>
+    <body>
+        <script type="module" src="./dist/dotlottie-wc.js"></script>
+        <dotlottie-wc
+            src="https://lottie.host/f315768c-a29b-41fd-b5a8-a1c1dfb36cd2/CRiiNg8fqQ.lottie"
+            autoplay="true"
+            loop="true"
+        ></dotlottie-wc>
+        <script>
+            const dotLottieComponent = document.querySelector('dotlottie-wc');
+
+            console.log(dotLottieComponent);
+        </script>
+    </body>
+</html>