reveal.js-appearance 1.3.3 → 1.4.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Martijn De Jongh (Martino)
+Copyright (c) 2026 Martijn De Jongh (Martino)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -13,8 +13,6 @@ In Powerpoint you can make slides with items that appear automatically with effe
 
 The animations will start automatically after or at each slide or fragment change if the HTML is set up to use Appearance.
 
-Version 1.3.0 adds an option to animate the words in a sentence, or the letters in a word.
-
 
 ## Basics
 
@@ -42,10 +40,11 @@ The Appearance plugin folder can then be referenced from `node_modules/reveal.js
 
 
 
-## Setup
+## Adding Appearance to your presentation
 
 ### JavaScript
 
+
 There are two JavaScript files for Appearance, a regular one, `appearance.js`, and a module one, `appearance.esm.js`. You only need one of them:
 
 #### Regular 
@@ -61,14 +60,31 @@ If you're not using ES modules, for example, to be able to run your presentation
 	});
 </script>
 ```
-#### As a module 
-If you're using ES modules, you can add it like this:
+
+
+#### From npm
+
+You can run it directly from npm:
+
+```html
+<script type="module">
+	import Reveal from 'reveal.js';
+	import Appearance from 'reveal.js-appearance';
+	import 'reveal.js-appearance/plugin/appearance/appearance.css';
+	Reveal.initialize({
+		// ...
+		plugins: [ Appearance ]
+	});
+</script>
+```
+
+Otherwise, you may want to copy the plugin into a plugin folder or an other location::
 
 ```html
 <script type="module">
-	// This will need a server
-	import Reveal from './dist/reveal.esm.js';
-	import Appearance from './plugin/appearance/appearance.esm.js';
+	import Reveal from './dist/reveal.mjs';
+	import Appearance from './plugin/appearance/appearance.mjs';
+	import './plugin/appearance/appearance.css';
 	Reveal.initialize({
 		// ...
 		plugins: [ Appearance ]
@@ -76,12 +92,29 @@ If you're using ES modules, you can add it like this:
 </script>
 ```
 
+
 ### Styling
-The styling of Appearance is automatically inserted, either loaded through NPM or from the plugin folder. Two files are inserted: The first one is Animate.css by Daniel Eden for the basic animations, we add it through a CDN. The second file adds to the first stylesheet to allow for a non-animated state.
+The styling of Appearance is automatically inserted **when the appearance folder is manually copied** to the Reveal.js plugin folder.
+
+If you **import** reveal.js-appearance from npm, you will need to **import** the CSS file yourself. Depending on your setup this can be something like this:
+```javascript
+import 'reveal.js-appearance/plugin/appearance/appearance.css';
+```
 
-If you want to change the Appearance style, you can simply make your own style and use that stylesheet instead. Linking to your custom styles can be managed through the `csspath` option of Appearance.
+Appearance will detect if it runs in a module environment and will then not autoload the CSS. You can still set `cssautoload` to `true` if you like, but your bundler (Vite, Webpack) may not like that. In any of these cases, `import` the CSS file yourself.
 
+If you want to change the Appearance style, you can do a lot of that via the Reveal.js options. Or you can simply make your own style and use that stylesheet instead. Linking to your custom styles can be managed through the `csspath` option of Appearance or through `import` when using modules.
 
+#### Custom CSS
+If and when you decide to create your own CSS file, make sure that you also include the following CSS variable, that is used by the plugin to avoid loading the CSS multiple times, and to avoid using the autoloading feature when using modules:
+
+```css
+:root {
+	--cssimported-appearance: true;
+}
+```
+
+## Setup
 
 ### HTML
 
@@ -89,9 +122,9 @@ It is easy to set up your HTML structure for Appearance. Each element that you w
 
 ```html
 <ul>
-    <li class="animate__bounceInLeft">Add it to any text element</li>
-    <li class="animate__bounceInLeft">Like list items, or headers.</li>
-    <li class="animate__bounceInLeft">It adds some attention.</li>
+	<li class="animate__bounceInLeft">Add it to any text element</li>
+	<li class="animate__bounceInLeft">Like list items, or headers.</li>
+	<li class="animate__bounceInLeft">It adds some attention.</li>
 </ul>
 ```
 
@@ -102,8 +135,8 @@ When you are working with Markdown (or in any other case), this can be a chore *
 To nicely animate the words in a heading, or the letters of a word, add an animation class to it, and add a data-attribute for the kind of split you want:  
 
 ```html
-<h3 class="animate__fadeInDown" data-split="words">Let words apear and appear</h3>
-<h3 class="animate__fadeInDown" data-split="letters">Let letters apear and appear</h3>
+<h3 class="animate__fadeInDown" data-split="words">Let words appear word by word</h3>
+<h3 class="animate__fadeInDown" data-split="letters">Let letters appear letter by letter</h3>
 ```
 
 
@@ -137,20 +170,22 @@ You can change the speed of each animation, using the tempo classes from Animate
 
 For words and letters, the same techniques can be used. 
 
-Note that the data-delay also gets copied to the smaller elements in it, which means that there is no more 'whole sentence' or 'whole word' to delay. By default, the whole element then gets the delay (depending on if it is following other animations) as defined in the `delay` option in the Configuration, but it can be overriden by an optional `data-container-delay`. 
+Note that the data-delay also gets copied to the smaller elements in it, which means that there is no more 'whole sentence' or 'whole word' to delay. By default, the whole element then gets the delay (depending on if it is following other animations) as defined in the `delay` option in the Configuration, but it can be overriden by an optional `data-container-delay`.
+
+Also note the (optional) `baseline` class here, which makes the words appear from the baseline of the text.
 
 ```html
-<h3 class="animate__fadeInDown animate__faster" 
+<h3 class="animate__fadeInUp animate__faster baseline"
 	data-split="words" 
 	data-delay="80"
-	data-container-delay="600">Let words apear and appear</h3>
+	data-container-delay="600">Let words appear word by word</h3>
 ```
 
 
 ### Changing the 'appearevent'
 When you navigate from slide to slide, you can set transition effects in Reveal. These effects take some time. That's why, by default, Appearance only starts when the slide transition has ended. 
 
-There are cases however, where  there is hardly any transition, for example, when going from an autoanimate slide to another. Reveal then suppresses the user-set transition to a short opacity change. Starting *together with* the transition might then be nicer. You can use any of the following events:
+There are cases however, where there is hardly any transition, for example, when going from an autoanimate slide to another. Reveal then suppresses the user-set transition to a short opacity change. Starting *together with* the transition might then be nicer. You can use any of the following events:
 
 * *slidetransitionend* (default, Appearance will always start animating elements after the transition)
 * *slidechanged* (Appearance will always start together with the transition)
@@ -158,11 +193,11 @@ There are cases however, where  there is hardly any transition, for example, whe
 
 ```html
 <section data-appearevent="auto">
-    <ul>
-        <li class="animate__fadeInLeft">This is list item 1</li>
-        <li class="animate__fadeInLeft">This is list item 2</li>
-        <li class="animate__fadeInLeft">This is list item 1</li>
-    </ul>
+	<ul>
+		<li class="animate__fadeInLeft">This is list item 1</li>
+		<li class="animate__fadeInLeft">This is list item 2</li>
+		<li class="animate__fadeInLeft">This is list item 1</li>
+	</ul>
 </section>
 ```
 
@@ -171,6 +206,18 @@ These same event triggers can be set through the `appearevent` option in the glo
 When using Appearance inside an autoanimate slide, and changing the appearevent to `slidechanged` or `auto`, keep in mind that Reveal transforms opacity for all non-autoanimate items, while Appearance does the same on most of the effects. To avoid strange behaviour, wrap these Appearance items in a parent. For example, a list of animated bullet points works well, because the animated class is on the children, not the parent. Separate headings or other elements do not have that, so should be wrapped.
 
 
+### Initial delay on page load
+You can set a delay before animations start, but only on the initial page load or reloads (not when navigating between slides):
+
+<section data-init-delay="2000">
+	<h3>Welcome</h3>
+	<p class="animate__fadeIn">This will appear 2 seconds after page load</p>
+</section>
+```
+
+
+
+
 ## Autoappear
 
 You can simplify the addition of animation classes.
@@ -198,19 +245,20 @@ Reveal.initialize({
 
 You can add any selector and animation class to this object. You can use a simple JSON object, or more elaborate like this (you can also mix them): `{"ul li": {"animation":"animate__fadeInLeft", "speed":"slow", "delay":"100"}}`. An object like that can contain the following keys:
 
-* animation
-* speed
-* delay
-* split
-* container-delay 
+* **animation**: The Animate.css animation class
+* **speed**: Animation speed (slower, slow, fast, faster)
+* **delay**: Delay between elements in milliseconds
+* **initial-delay**: Delay before the first element of this type appears in milliseconds
+* * **container-delay**: Delay before the first element in each container (when elements are in separate parent containers)
+* **split**: Split text into words (`data-split="words"`) or letters (`data-split="letters"`) for individual animation
 
-where the last two keys are specific for word- and letter-animations.
+where the last key is specific for word- and letter-animations.
 
 If you choose to write all your animation selectors and properties globally, you no longer need to add any classes to the markup and it can stay like this:
 
 ```html
 <ul>
-    <li>Add it to any text element</li>
+	<li>Add it to any text element</li>
 	<li>Like list items, or headers.</li>
 	<li>It adds some attention.</li>
 </ul>
@@ -250,7 +298,7 @@ Reveal.initialize({
 	<ul>
 		<li>This is list item 1</li>
 		<li>This is list item 2</li>
-	</ul>
+		</ul>
 </section>
 ```
 
@@ -272,78 +320,63 @@ In the example below you can see that mixing strings and objects is perfectly fi
 </section>
 ```
 
-## Configuration
+### Container-aware delays
 
-There are a few options that you can change from the Reveal.js options. The values below are default and do not need to be set if they are not changed.
+When you have multiple groups of elements in separate containers, `container-delay` applies to the first element in each container, while `delay` applies between elements within the same container. In the example below, the `delay` is the standard 300ms from the global options.
+
+```html
+<section data-autoappear='{"img.test": {"animation":"animate__fadeInDown", "container-delay":"1200"}}'>
+	<h3>Container-aware delays</h3>
+	<div class="row">
+		<img class="test" src="assets/img/1.jpg">
+		... other images ...
+	</div>
+</section>
+```
+
+
+
+
+
+## Global options
+
+There are a few options that you can change from the Reveal.js options. The values below, in alphabetical order, are default and do not need to be set if they are not changed. Some of the options have been removed, compared to the previous version. This is mainly because we now auto-import Animate.css, so no need to set that up anymore.
 
 ```javascript
 Reveal.initialize({
   // ...
   appearance: {
-    hideagain: true,
-    delay: 300,
-    appearevent: 'slidetransitionend',
-    autoappear: false,
-    autoelements: false,
-    csspath: '',
-    animatecsspath: {
-      link : 'https://cdnjs.cloudflare.com/ajax/libs/animate.css/4.1.1/animate.min.css',
-      compat : 'https://cdnjs.cloudflare.com/ajax/libs/animate.css/4.0.0/animate.compat.css',
-    },
-    compatibility: false,
-    compatibilitybaseclass: 'animated'
+	appearevent: 'slidetransitionend',
+	autoappear: false,
+	autoelements: false,
+	cssautoload: true,
+	csspath: '',
+	delay: 300,
+	hideagain: true,
+	initdelay: 0
   },
   plugins: [ Appearance ]
 });
 ```
 
-* **`hideagain`**: Change this (true/false) if you want to see the shown elements if you go back.
-* **`delay`**: Base time in ms between appearances.
-* **`appearevent`**: Use a specific event at which Appearance starts.
+* **`appearevent`**: Use a specific event at which Appearance starts. Options: `'slidetransitionend'` (default), `'slidechanged'`, or `'auto'`.
 * **`autoappear`**: Use this when you do not want to add classes to each item that you want to appear, and just let Appearance add animation classes to (all of) the provided elements in the presentation. See "Autoappear" mode above.
 * **`autoelements`**: These are the elements that `autoappear` will target. Each element has a selector and an animation class. If `autoappear` is off, the elements will still get animation if the section contains a `data-autoappear` attribute.
+* **`cssautoload`**: Appearance will load the CSS (including Animate.css) if this is set to `true`. If you import reveal.js-appearance from npm, you will need to import the CSS file yourself. If you use 'import', then `cssautoload` should be set to `false`. If you know the path to the CSS file, you can use the `csspath` option and keep `cssautoload` set to `true`.
 * **`csspath`**: Appearance will automatically load the styling of the plugin. If you want to customise the styling, you can link to your own CSS file here.
-* **`animatecsspath`**: Appearance will also automatically load the styling of Animate.css via a CDN. Note that Animate.css has two links, the first (CDN) one is for version 4, the second (old) one is the version 3 compatibility CDN link.
-* **`compatibility`**: This setting can let you use your current markup. However, because this also uses the Animate.css compatibility CSS, and it is likely that they will not support this in the future, please update your markup as shown above.
-* **`compatibilitybaseclass`**: This is the baseclass to use if you don't change your markup. 
-
-
-
-
-## Migration guide
-Appearance v1.1.2 was an update to stay current with the latest version of Animate.css, which itself brought breaking changes in version 4. Animate.css v4 added a prefix for all of the Animate.css classes, defaulting to `animate__` . Appearance will now automatically add the Animate.css base class (`animate__animated`) to any element with a Animate.css animation class.
-
-You have two options to migrate to the new version:
-
-### Adjust your markup
-
-If in Appearance v1.1.1 you used this:
-
-```html
-<img class="animated fadeInDown" data-src="1.jpg">
-```
- 
-you should now use this:
-
-```html
-<img class="animate__fadeInDown" data-src="1.jpg">
-```
-which is the only change in the markup. 
-
-
-### Turn on compatibility mode
-
-If you turn in compatibility mode in Appearance, you can keep using your current markup. However, because this also uses the Animate.css compatibility CSS, this might break your presentations in the future, so it is not recommended. See the options above for compatibility mode and the compatibility base class.
+* **`delay`**: Base time in milliseconds between element appearances. This is the delay between items of the same type.
+* **`hideagain`**: Change this (true/false) if you want to see the shown elements if you go back. When set to `true`, elements will hide again when navigating away from the slide.
+* **`initdelay`**: Sets a delay in milliseconds before any animations start, but only on the initial page load (not when navigating between slides). Default is `0` (no delay). Can be overridden per-slide with `data-init-delay` attribute.
 
 
 
 ## Like it?
 If you like it, please star this repo! 
 
-And if you want to show off what you made with it, please do :-)
+And if you want to show off what you made with it, please do :smiley:
 
 
 ## License
 MIT licensed
 
-Copyright (C) 2023 Martijn De Jongh (Martino)
+Copyright (C) 2026 Martijn De Jongh (Martino)

package/package.json

@@ -1,65 +1,74 @@
 {
-  "name": "reveal.js-appearance",
-  "version": "1.3.3",
-  "description": "An animation plugin for Reveal.js that animates elements sequentially like in Powerpoint. Perfect for online portfolios or other presentations with images.",
-  "keywords": [
-    "reveal",
-    "reveal.js",
-    "reveal-plugin",
-    "plugin",
-    "text effects",
-    "powerpoint"
-  ],
-  "main": "plugin/appearance/appearance.js",
-  "module": "plugin/appearance/appearance.esm.js",
-  "browser": "plugin/appearance/appearance.js",
-  "author": {
-    "name": "Martijn De Jongh (Martino)",
-    "email": "martijn.de.jongh@gmail.com",
-    "web": "https://martinomagnifico.github.io",
-    "url": "https://martinomagnifico.github.io",
-    "username": "martinomagnifico"
-  },
-  "homepage": "https://github.com/Martinomagnifico/reveal.js-appearance",
-  "repository": {
-    "type": "git",
-    "url": "git://github.com/martinomagnifico/reveal.js-appearance.git"
-  },
-  "functionname": "Appearance",
-  "license": "MIT",
-  "scripts": {
-    "start": "gulp demo",
-    "build": "NODE_ENV=prod gulp build"
-  },
-  "overrides": {
-    "chokidar": "3.5.3",
-    "glob-parent": "6.0.2",
-    "axios": "1.6.1"
-  },
-  "browserslist": "> 2%, not dead",
-  "devDependencies": {
-    "@babel/preset-env": "^7.23.2",
-    "@rollup/plugin-babel": "^6.0.4",
-    "@rollup/plugin-commonjs": "^25.0.7",
-    "@rollup/plugin-node-resolve": "^15.2.3",
-    "@rollup/plugin-terser": "^0.4.4",
-    "browser-sync": "^2.29.3",
-    "del": "^5.1.0",
-    "gulp": "^4.0.2",
-    "gulp-autoprefixer": "^8.0.0",
-    "gulp-header": "^2.0.9",
-    "gulp-plumber": "^1.2.1",
-    "gulp-pug": "^5.0.0",
-    "gulp-rename": "^2.0.0",
-    "gulp-sass": "^5.1.0",
-    "merge-stream": "^2.0.0",
-    "rollup": "^4.2.0",
-    "sass": "^1.63.6"
-  },
-  "dependencies": {
-    "reveal.js": "^5.0.1"
-  },
-  "copydependencies": [
-    "reveal.js"
-  ]
+    "name": "reveal.js-appearance",
+    "version": "1.4.0",
+    "description": "An animation plugin for Reveal.js that animates elements sequentially like in Powerpoint. Perfect for online portfolios or other presentations with images.",
+    "keywords": [
+        "reveal",
+        "reveal.js",
+        "reveal-plugin",
+        "plugin",
+        "text effects",
+        "powerpoint"
+    ],
+    "homepage": "https://github.com/martinomagnifico/reveal.js-appearance",
+    "license": "MIT",
+    "author": {
+        "name": "Martijn De Jongh (Martino)",
+        "email": "martijn.de.jongh@gmail.com",
+        "web": "https://martinomagnifico.github.io",
+        "url": "https://martinomagnifico.github.io",
+        "username": "martinomagnifico"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git://github.com/martinomagnifico/reveal.js-appearance.git"
+    },
+    "type": "module",
+    "main": "./plugin/appearance/appearance.js",
+    "module": "./plugin/appearance/appearance.mjs",
+    "exports": {
+        ".": {
+            "import": "./plugin/appearance/appearance.mjs",
+            "require": "./plugin/appearance/appearance.js"
+        },
+        "./plugin/appearance/appearance.esm.js": "./plugin/appearance/appearance.mjs",
+        "./plugin/appearance/appearance.css": "./plugin/appearance/appearance.css",
+        "./appearance.css": "./plugin/appearance/appearance.css"
+    },
+    "style": "plugin/appearance/appearance.css",
+    "files": [
+        "plugin/appearance"
+    ],
+    "scripts": {
+        "start": "npm run dev",
+        "copy-reveal": "node scripts/copy-reveal.mjs",
+        "copy-plugin": "node scripts/copy-plugin.mjs",
+        "dev": "vite",
+        "prebuild": "rimraf demo plugin",
+        "build-plugin": "vite build -c vite.lib.config.ts",
+        "build-demo": "vite build -c vite.config.ts",
+        "build": "npm run build-plugin && npm run build-demo && npm run copy-reveal && npm run copy-plugin",
+        "format": "biome format --write .",
+        "lint": "biome lint .",
+        "check": "biome check --write .",
+        "preview": "npm run build && vite preview",
+        "ci": "biome ci ."
+    },
+    "devDependencies": {
+        "@biomejs/biome": "2.3.11",
+        "@types/node": "^22.10.1",
+        "@types/reveal.js": "^5.0.4",
+        "@vituum/vite-plugin-pug": "latest",
+        "animate.css": "^4.1.1",
+        "fs-extra": "latest",
+        "reveal.js-plugintoolkit": "1.0.2",
+        "rimraf": "^6.0.1",
+        "sass": "latest",
+        "typescript": "^5.7.2",
+        "vite": "latest",
+        "vituum": "1.2.0"
+    },
+    "peerDependencies": {
+        "reveal.js": ">=4.0.0"
+    }
 }