animarte

<div align="center"> <a href="https://gitlab.com/lucasmc64/animarte">GitLab</a> • <a href="https://www.npmjs.com/package/animarte">NPM</a> • <a href="https://unpkg.com/browse/animarte@latest">CDN</a> • <a href="https://ko-fi.com/lucasmc64">Ko-fi</a> </div> ![Animarte](https://gitlab.com/lucasmc64/animarte/-/raw/main/readme/cover.png) # 📽️ Animarte ## 🎯 Goal This project is a dependency-free library that aims to provide a set of pre-made animations, avoiding rework and Control+C/Control+V between projects. > **Note**: [Click here](https://animarte.lucasmc64.dev) to see all animations already available! ## 🎨 How to use it in my project? ### <span id="classic-scripts">🙌 Classic scripts</span> The project is also exported using [UMD](https://github.com/umdjs/umd), which means that all variables and classes such as the `Animarte` class and the `animations` array are exposed globally, and can be used in any script imported after the library. > **Note**: You should **change `X.Y.Z` to the library version number** according to your needs, this is just an example. It is recommended to always use the latest version. > > It is recommended that you pin to the latest stable version of the lib. However, if you always want to use the latest version, you can also use `latest` instead of a predefined version number. **Be careful** though, breaking changes may be introduced and your project may need to adapt to the changes. ```html <!DOCTYPE html> <html> <head>  <link rel="stylesheet" href="https://unpkg.com/animarte@X.Y.Z/animarte.css" /> <script src="https://unpkg.com/animarte@X.Y.Z/animarte.js" defer></script>  </head> <body> <div id="loading-animation"></div> </body> </html> ``` ```js "use strict"; new Animarte({ animation: "ellipsis", variant: "agitated", parentElement: document.getElementById("loading-animation"), }); ``` ### 📦️ ES6 Modules The HTML is very similar to the classic scripts version, just change the `.js` extension to `.mjs`, which will result in something similar to this: > **Note**: Please read the [previous section](#classic-scripts) to get the details involved in importing CSS and choosing a package version, they are the same here. ```html <script src="https://unpkg.com/animarte@X.Y.Z/animarte.mjs" defer></script> ``` ```javascript import { Animarte } from "animarte"; new Animarte({ animation: "ellipsis", variant: "agitated, parentElement: document.getElementById("loading-animation"), }); ``` ### ⚛️ React Install the lib using your favorite package manager. ```bash npm install animarte ``` Since the library was designed primarily to be used with vanilla JS, a _helper_ component needs to be created to encapsulate Animarte's behavior and make it simple to reuse throughout the application. > **Note**: There is TypeScript support, and even if your project doesn't use the JS superset, it should help VSCode and other editors provide autocomplete/code suggestions. ```tsx import { memo, useEffect, useRef } from "react"; import { Animarte, AnimarteProps } from "animarte"; import "animarte/animarte.css"; // Example using Vite, React and TypeScript extraxcted from the Animarte website export const AnimarteWrapper = memo( ({ className="", props }: AnimarteProps) => { const ref = useRef<HTMLDivElement>(null); useEffect(() => { const parentElement = ref.current; if (parentElement) { new Animarte({ ...props, parentElement: parentElement, }); } return () => { // Required to avoid animation duplication when React is in Strict Mode if (parentElement) { parentElement.innerHTML = ""; } }; }, [props]); return <div className={`animarte-wrapper ${className}`} ref={ref} />; }, (prevProps, nextProps) => { function compareObjects(obj1, obj2) { const keys1 = Object.keys(obj1); const keys2 = Object.keys(obj2); if (keys1.length !== keys2.length) { return false; } for (const key of keys1) { if (typeof obj1[key] === "object" && typeof obj2[key] === "object") { if (!compareObjects(obj1[key], obj2[key])) { return false; } continue; } if (obj1[key] !== obj2[key]) { return false; } } return true; } return compareObjects(prevProps, nextProps); }, ); ``` ### 💅 Use only CSS Regardless of whether or not you are using a framework to develop your website, you still have the option of simply importing the styles and manually inserting and controlling the animation. Here is an example: > See the previous steps for how to import the CSS into your project. ```html <div style="--animarte-size: 4em; --animarte-speed: 2.5s; --animarte-color: #d2d2d8;" class="animarte animarte-ellipsis animarte-ellipsis--one-for-all-2" > <div class="animarte-ellipsis__element"></div> <div class="animarte-ellipsis__element"></div> <div class="animarte-ellipsis__element"></div> </div> ``` - In the container, the `style` attribute has the power to change the variables that modify the style and behavior of the animation. - Still in the container, the `class` attribute must have 3 classes that must respect the following nomenclature: - `animarte`: It has styles common to all animation - `animarte-<ANIMATION>`: Has specific styles of the type of animation - `animarte-<ANIMATION>--<VARIANT>`: Has animation variant specific styles - Child items must have the `class` attribute that follows the following naming pattern: - `animarte-<ANIMATION>__element`: Identifies the items that are part of the animation composition The number of child items can vary depending on the animation and its variant. So, to know how many child elements you should manually create, [click here](https://gitlab.com/lucasmc64/animarte/-/blob/main/src/ts/animations.ts?ref_type=heads), search for the animation you want to implement and look at the `children` attribute. > In the future, we intend to make this information explicit and more easily accessible on the project website! > **Note**: Besides the bundled CSS file, a CSS file for each animation is generated in `animarte/animations/<animation>/<variant>.css`. This is useful when you only want to ship the CSS for a specific animation instead of the full bundle. ## 🧐 Properties and options You must pass some properties to Animarte to identify which animation you want to use. Now, the `parentElement` property has a very impractical default value, so it is **highly recommended** to define it as well. Here are its specifications: | Property | Type | Default value | Is required? | Description | | --------------- | ------------- | ---------------------- | ------------ | ------------------------------------------------------------ | | `animation` | `string` | - | Yes | Animation name | | `variant` | `string` | - | Yes | Animation variant name | | `parentElement` | `HTMLElement` | `window.document.body` | No | Element where the animation will be inserted | | `options` | `object` | `{}` | No | Optional properties to change the look or behavior of the animation | > Don't try to pass an `input` as `parentElement`, I'm not handling that... yet ‘-’ If you want to tweak the animation a little bit, you can specify a few things by passing the `options` property. Here's what you can change: | Property | Type | Default value | Is required? | Description | | ----------- | --------- | ------------- | ------------ | ------------------------------------- | | `color` | `string` | - | No | Color used in the animation | | `size` | `string` | - | No | Size of the animation | | `speed` | `string` | - | No | Speed of the animation | | `show` | `boolean` | `true` | No | Whether the animation should be shown | | `ariaLabel` | `string` | - | No | Accessibility label for the animation | > You can experiment with how these options affect the animation by visiting the [project website](https://animarte.lucasmc64.dev) :) ## 🤔 How do I run the project on my machine? The first step is to clone the project, either via terminal or even by downloading the compressed file (.zip). After that, go ahead. ### 🛠️ Requirements - [NodeJS and NPM](https://nodejs.org) - (Optional) [Python](https://www.python.org/) - (Optional) [Yarn](https://yarnpkg.com/) ### 🔍️ Installing dependencies With Node.JS installed, access the project directory via terminal and run the `npm install` command. If you prefer to use Yarn, just run the `yarn` command. Now, you will need to install the `sass` package globally which is responsible for processing the .scss files and generating the .css files. ```bash # Using NPM npm i -g sass # Using Yarn yarn global add sass ``` Now, if you intend to use `live-server` to serve CSS, you will also need to install it globally. > If you prefer to use Python for this, you don't need to install anything else. ```bash # Using NPM npm i -g live-server # Using Yarn yarn global add live-server ``` If you prefer to use Python, you can modify the NPM Script `start` as follows: ```json "start": "gulp watchAll & python3 -m http.server 5645" ``` ### ✨ Running the project With the dependencies properly installed, still in the terminal, run `npm start` or ` yarn start`. If the port has not been manually changed and the default port is free, simply access access the address _http://127.0.0.1:5645/demo_ in your favorite browser, to see the project running. ### 🎉 If everything went well... Now you are running the project beautifully! ### ✏️ License This project is under the GPL v3 license. See the [LICENSE](https://gitlab.com/lucasmc64/animarte/-/blob/main/LICENSE) for more information. --- Made with 💜 by a dreamer