tailwind-animatecss-kit 2.0.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 sericpieap
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+# tailwind-animatecss-kit
+
+A configurable Animate.css integration for Tailwind CSS 3. It reads the installed Animate.css catalog at build time, emits only the animations you select, and namespaces generated keyframes to prevent collisions.
+
+Global `duration`, `delay`, and `iterationCount` values are passed to `@jasperquinn/postcss-motion-helpers`, which generates the corresponding Tailwind base custom properties.
+
+## Installation
+
+```sh
+npm install tailwind-animatecss-kit animate.css
+```
+
+## Basic usage
+
+```js
+// tailwind.config.js
+module.exports = {
+  content: ['./src/**/*.{html,js,jsx,ts,tsx,vue,svelte}'],
+  plugins: [
+    require('tailwind-animatecss-kit')({
+      animations: ['bounce', 'fadeIn', 'fadeOut', 'slideInUp']
+    })
+  ]
+};
+```
+
+Apply the base class together with an animation class:
+
+```html
+<div class="keyframe keyframe-fade-in">Content</div>
+```
+
+Animation names are converted to kebab case in generated class names. For example, `fadeInDownBig` becomes `keyframe-fade-in-down-big`.
+
+## Configuration
+
+```js
+require('tailwind-animatecss-kit')({
+  prefix: 'motion',
+  animations: ['bounce', 'fadeIn'],
+  exclude: ['bounce'],
+  aliases: {
+    enter: 'fadeIn'
+  },
+  duration: '900ms',
+  delay: '0s',
+  iterationCount: '1',
+  namespaceKeyframes: true,
+  respectReducedMotion: true,
+  modifiers: true,
+  durations: {
+    quick: '300ms',
+    deliberate: '1400ms'
+  },
+  delays: {
+    short: '150ms',
+    long: '800ms'
+  },
+  repeats: {
+    twice: '2',
+    forever: 'infinite'
+  }
+})
+```
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `prefix` | `keyframe` | Prefix for classes and generated keyframes |
+| `animations` | `'*'` | Animate.css names to include; `'*'` includes the full catalog |
+| `exclude` | `[]` | Animation names to omit |
+| `aliases` | `{}` | Public class names mapped to Animate.css animation names |
+| `duration` | `1s` | Default animation duration |
+| `delay` | `0s` | Default animation delay |
+| `iterationCount` | `1` | Default iteration count |
+| `namespaceKeyframes` | `true` | Prefix keyframe identifiers to prevent collisions |
+| `respectReducedMotion` | `true` | Minimize animation when the user requests reduced motion |
+| `modifiers` | `true` | Generate timing, repeat, pause, and run utilities |
+| `durations` | Built-in map | Duration modifier tokens |
+| `delays` | Built-in map | Delay modifier tokens |
+| `repeats` | Built-in map | Iteration modifier tokens |
+
+The deprecated `classes` option remains an alias for `animations` during migration.
+
+## Generated utilities
+
+With the default prefix, the plugin generates:
+
+```html
+<div class="keyframe keyframe-bounce keyframe-duration-fast keyframe-delay-1s keyframe-repeat-2"></div>
+```
+
+- `keyframe-duration-{token}` sets the duration variable.
+- `keyframe-delay-{token}` sets the delay variable.
+- `keyframe-repeat-{token}` sets the iteration-count variable.
+- `keyframe-paused` and `keyframe-running` control playback.
+
+Tailwind variants work normally:
+
+```html
+<div class="keyframe keyframe-fade-in hover:keyframe-paused md:keyframe-duration-slow"></div>
+```
+
+## Aliases
+
+Aliases provide stable semantic names without copying keyframes:
+
+```js
+require('tailwind-animatecss-kit')({
+  animations: [],
+  aliases: {
+    notificationEnter: 'fadeInDown',
+    notificationExit: 'fadeOutUp'
+  }
+})
+```
+
+```html
+<aside class="keyframe keyframe-notification-enter"></aside>
+```
+
+## Catalog
+
+The package exposes the animation names found in the installed Animate.css version:
+
+```js
+const keyframes = require('tailwind-animatecss-kit');
+console.log(keyframes.catalog());
+```
+
+## Migration from 1.x
+
+- The default class prefix changed from `animatecss` to `keyframe`.
+- Generated animation class names use kebab case.
+- Keyframe names are namespaced by default.
+- `animations` replaces `classes`; `classes` remains a compatibility alias.
+- `@jasperquinn/postcss-motion-helpers` now processes global timing options and is installed automatically.
+- Reduced-motion handling is enabled by default.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "tailwind-animatecss-kit",
+  "version": "2.0.6",
+  "description": "A configurable, namespaced Animate.css integration for Tailwind CSS",
+  "main": "plugin.js",
+  "exports": "./plugin.js",
+  "files": [
+    "plugin.js",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "homepage": "https://sericpieap.github.io/tailwind-animatecss-kit/",
+  "repository": "https://github.com/sericpieap/tailwind-animatecss-kit/",
+  "author": "sericpieap",
+  "license": "MIT",
+  "keywords": [
+    "tailwindcss",
+    "tailwindcss-plugin",
+    "animate.css",
+    "animation",
+    "keyframes",
+    "motion"
+  ],
+  "scripts": {
+    "lint": "eslint . --ext .js",
+    "test": "node --test"
+  },
+  "dependencies": {
+    "animate.css": "^4.1.1",
+    "postcss": "^8.4.5",
+    "@jasperquinn/postcss-motion-helpers": "^1.0.1",
+    "postcss-js": "^3.0.3",
+    "postcss-selector-parser": "^6.0.8"
+  },
+  "devDependencies": {
+    "eslint": "^8.5.0",
+    "eslint-config-airbnb-base": "15.0.0",
+    "eslint-plugin-import": "^2.25.2",
+    "tailwindcss": "^3.0.7"
+  },
+  "peerDependencies": {
+    "tailwindcss": "^3"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/plugin.js

@@ -0,0 +1,21 @@
+'use strict';
+
+const tailwindPlugin = require('tailwindcss/plugin');
+const { loadCatalog } = require('./src/catalog');
+const { normalizeOptions } = require('./src/config');
+const { buildStyles } = require('./src/styles');
+
+function keyframeTailwindPlugin(options = {}) {
+  const config = normalizeOptions(options);
+
+  return tailwindPlugin(({ addBase, addUtilities }) => {
+    const styles = buildStyles(loadCatalog(), config);
+    addBase(styles.base);
+    addUtilities(styles.utilities);
+  });
+}
+
+keyframeTailwindPlugin.catalog = () => loadCatalog().names.slice();
+keyframeTailwindPlugin.normalizeOptions = normalizeOptions;
+
+module.exports = keyframeTailwindPlugin;

package/src/catalog.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const fs = require('fs');
+const postcss = require('postcss');
+const selectorParser = require('postcss-selector-parser');
+
+let cachedCatalog;
+
+function animateCssPath() {
+  try {
+    return require.resolve('animate.css/animate.css');
+  } catch (error) {
+    const wrapped = new Error('tailwind-animatecss-kit: unable to resolve animate.css/animate.css');
+    wrapped.cause = error;
+    throw wrapped;
+  }
+}
+
+function sourceClasses(selector) {
+  const classes = [];
+  selectorParser(selectors => selectors.walkClasses(node => classes.push(node.value)))
+    .processSync(selector);
+  return classes.filter(name => name.startsWith('animate__'));
+}
+
+function loadCatalog() {
+  if (cachedCatalog) return cachedCatalog;
+
+  const root = postcss.parse(fs.readFileSync(animateCssPath(), 'utf8'));
+  const keyframes = new Map();
+  const animations = new Map();
+
+  root.walkAtRules(/^(?:-webkit-)?keyframes$/, (rule) => {
+    if (!keyframes.has(rule.params)) keyframes.set(rule.params, rule.clone());
+  });
+
+  root.walkRules((rule) => {
+    const names = sourceClasses(rule.selector)
+      .filter(name => name !== 'animate__animated')
+      .map(name => name.slice('animate__'.length));
+    if (names.length === 0) return;
+
+    let animationName;
+    rule.walkDecls(/^(?:-webkit-)?animation-name$/, declaration => {
+      animationName = declaration.value;
+    });
+    if (!animationName || !keyframes.has(animationName)) return;
+
+    names.forEach(name => animations.set(name, {
+      name,
+      keyframeName: animationName,
+      declarations: rule.nodes.map(node => node.clone()),
+      keyframes: keyframes.get(animationName).clone()
+    }));
+  });
+
+  const names = [...animations.keys()].sort();
+  cachedCatalog = Object.freeze({ animations, names: Object.freeze(names) });
+  return cachedCatalog;
+}
+
+module.exports = { loadCatalog, sourceClasses };

package/src/config.js

@@ -0,0 +1,92 @@
+'use strict';
+
+const DEFAULTS = Object.freeze({
+  prefix: 'keyframe',
+  animations: '*',
+  exclude: [],
+  aliases: {},
+  duration: '1s',
+  delay: '0s',
+  iterationCount: '1',
+  namespaceKeyframes: true,
+  respectReducedMotion: true,
+  modifiers: true,
+  durations: {
+    faster: '500ms',
+    fast: '800ms',
+    slow: '2s',
+    slower: '3s'
+  },
+  delays: {
+    '1s': '1s',
+    '2s': '2s',
+    '3s': '3s',
+    '4s': '4s',
+    '5s': '5s'
+  },
+  repeats: {
+    1: '1',
+    2: '2',
+    3: '3',
+    infinite: 'infinite'
+  }
+});
+
+const isRecord = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+function assertString(value, path) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new TypeError(`tailwind-animatecss-kit: ${path} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+function stringList(value, path, allowWildcard = false) {
+  if (allowWildcard && value === '*') return '*';
+  if (!Array.isArray(value)) {
+    throw new TypeError(`tailwind-animatecss-kit: ${path} must be an array${allowWildcard ? " or '*'" : ''}`);
+  }
+  return [...new Set(value.map((item, index) => assertString(item, `${path}[${index}]`)))];
+}
+
+function stringMap(value, path) {
+  if (!isRecord(value)) throw new TypeError(`tailwind-animatecss-kit: ${path} must be an object`);
+  return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+    assertString(key, `${path} key`),
+    assertString(item, `${path}.${key}`)
+  ]));
+}
+
+function normalizeOptions(options) {
+  if (!isRecord(options)) throw new TypeError('tailwind-animatecss-kit: options must be an object');
+
+  const config = {
+    prefix: assertString(options.prefix ?? DEFAULTS.prefix, 'prefix'),
+    animations: stringList(options.animations ?? options.classes ?? DEFAULTS.animations, 'animations', true),
+    exclude: stringList(options.exclude ?? DEFAULTS.exclude, 'exclude'),
+    aliases: stringMap(options.aliases ?? DEFAULTS.aliases, 'aliases'),
+    duration: assertString(options.duration ?? DEFAULTS.duration, 'duration'),
+    delay: assertString(options.delay ?? DEFAULTS.delay, 'delay'),
+    iterationCount: assertString(options.iterationCount ?? DEFAULTS.iterationCount, 'iterationCount'),
+    namespaceKeyframes: options.namespaceKeyframes ?? DEFAULTS.namespaceKeyframes,
+    respectReducedMotion: options.respectReducedMotion ?? DEFAULTS.respectReducedMotion,
+    modifiers: options.modifiers ?? DEFAULTS.modifiers,
+    durations: stringMap(options.durations ?? DEFAULTS.durations, 'durations'),
+    delays: stringMap(options.delays ?? DEFAULTS.delays, 'delays'),
+    repeats: stringMap(options.repeats ?? DEFAULTS.repeats, 'repeats')
+  };
+
+  ['namespaceKeyframes', 'respectReducedMotion', 'modifiers'].forEach((key) => {
+    if (typeof config[key] !== 'boolean') {
+      throw new TypeError(`tailwind-animatecss-kit: ${key} must be a boolean`);
+    }
+  });
+
+  if (!/^-?[_a-zA-Z]+[_a-zA-Z0-9-]*$/.test(config.prefix)) {
+    throw new TypeError('tailwind-animatecss-kit: prefix must be a valid CSS class identifier');
+  }
+
+  return Object.freeze(config);
+}
+
+module.exports = { DEFAULTS, normalizeOptions };

package/src/motion.js

@@ -0,0 +1,33 @@
+'use strict';
+
+const postcss = require('postcss');
+const postcssJs = require('postcss-js');
+const postcssAnimateUtils = require('@jasperquinn/postcss-motion-helpers');
+
+function toPostcssOptions(config) {
+  return {
+    variables: {
+      enabled: true,
+      selector: ':root',
+      prefix: 'keyframe',
+      preserveExisting: false,
+      values: {
+        duration: config.duration,
+        delay: config.delay,
+        iterationCount: config.iterationCount
+      }
+    },
+    rewrite: false,
+    namespace: null,
+    webkit: false,
+    reducedMotion: false
+  };
+}
+
+function buildMotionBase(config) {
+  const processor = postcss([postcssAnimateUtils(toPostcssOptions(config))]);
+  const result = processor.process('', { from: undefined }).sync();
+  return postcssJs.objectify(result.root);
+}
+
+module.exports = { buildMotionBase, toPostcssOptions };

package/src/styles.js

@@ -0,0 +1,101 @@
+'use strict';
+
+const postcss = require('postcss');
+const postcssJs = require('postcss-js');
+const { buildMotionBase } = require('./motion');
+
+const kebab = value => value.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+
+function selectAnimations(catalog, config) {
+  const requested = config.animations === '*' ? catalog.names : config.animations;
+  const excluded = new Set(config.exclude);
+  const unknown = requested.filter(name => !catalog.animations.has(name));
+  const badAliases = Object.entries(config.aliases).filter(([, target]) => !catalog.animations.has(target));
+
+  if (unknown.length || badAliases.length) {
+    const invalid = [...unknown, ...badAliases.map(([alias, target]) => `${alias} -> ${target}`)];
+    throw new Error(`tailwind-animatecss-kit: unknown animation(s): ${invalid.join(', ')}`);
+  }
+
+  const selected = requested
+    .filter(name => !excluded.has(name))
+    .map(name => [name, catalog.animations.get(name)]);
+
+  Object.entries(config.aliases).forEach(([alias, target]) => {
+    if (!excluded.has(alias)) selected.push([alias, catalog.animations.get(target)]);
+  });
+  return selected;
+}
+
+function declarationObject(nodes, keyframeName) {
+  return nodes.reduce((result, node) => {
+    if (node.type !== 'decl') return result;
+    const property = node.prop.replace(/^-(webkit|moz|ms|o)-/, '');
+    result[property] = /animation-name$/.test(property) ? keyframeName : node.value;
+    return result;
+  }, {});
+}
+
+function keyframesObject(rule, name) {
+  const clone = rule.clone({ name: 'keyframes', params: name });
+  const root = postcss.root({ nodes: [clone] });
+  return postcssJs.objectify(root);
+}
+
+function modifierUtilities(config) {
+  if (!config.modifiers) return {};
+  const prefix = `.${config.prefix}`;
+  const utilities = {
+    [`${prefix}-paused`]: { 'animation-play-state': 'paused' },
+    [`${prefix}-running`]: { 'animation-play-state': 'running' }
+  };
+  Object.entries(config.durations).forEach(([token, value]) => {
+    utilities[`${prefix}-duration-${token}`] = { '--keyframe-duration': value };
+  });
+  Object.entries(config.delays).forEach(([token, value]) => {
+    utilities[`${prefix}-delay-${token}`] = { '--keyframe-delay': value };
+  });
+  Object.entries(config.repeats).forEach(([token, value]) => {
+    utilities[`${prefix}-repeat-${token}`] = { '--keyframe-iteration-count': value };
+  });
+  return utilities;
+}
+
+function buildStyles(catalog, config) {
+  const baseSelector = `.${config.prefix}`;
+  const base = buildMotionBase(config);
+  const utilities = {
+    [baseSelector]: {
+      'animation-duration': 'var(--keyframe-duration)',
+      'animation-delay': 'var(--keyframe-delay)',
+      'animation-iteration-count': 'var(--keyframe-iteration-count)',
+      'animation-fill-mode': 'both'
+    },
+    ...modifierUtilities(config)
+  };
+
+  selectAnimations(catalog, config).forEach(([publicName, animation]) => {
+    const keyframeName = config.namespaceKeyframes
+      ? `${config.prefix}-${kebab(publicName)}`
+      : animation.keyframeName;
+    Object.assign(base, keyframesObject(animation.keyframes, keyframeName));
+    utilities[`${baseSelector}.${config.prefix}-${kebab(publicName)}`] = declarationObject(
+      animation.declarations,
+      keyframeName
+    );
+  });
+
+  if (config.respectReducedMotion) {
+    base['@media (prefers-reduced-motion: reduce)'] = {
+      [baseSelector]: {
+        'animation-duration': '1ms !important',
+        'animation-iteration-count': '1 !important',
+        'transition-duration': '1ms !important'
+      }
+    };
+  }
+
+  return { base, utilities };
+}
+
+module.exports = { buildStyles, kebab, selectAnimations };