animotionjs-plus 1.1.1 → 1.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "animotionjs-plus",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "An advanced custom web animation engine for Vanilla JS, React, and Next.js with CSS, Three.js, Lottie, and dotLottie support.",
   "main": "dist/animotion.min.js",
   "module": "src/index.core.js",

package/README.md

@@ -1,470 +0,0 @@
-# Animotion-js
-
-Animotion is a custom web animation engine for Vanilla JS, React, and Next.js.
-
-It now supports:
-
-- direct JS tweens and timelines
-- declarative `am-*` custom attributes
-- DOM, CSS, CSS variables, transforms, filters, and scroll properties
-- plain objects and nested property paths
-- Three.js objects and scene state
-- Lottie and dotLottie playback control
-- scoped animation contexts for framework apps
-
-## Core Setup Modes
-
-You can use Animotion in 3 main ways:
-
-1. Imperative JS with `Animotion.to()`, `Animotion.from()`, `Animotion.timeline()`
-2. Declarative custom attributes with `am-*`
-3. Scoped attribute hydration in React/Next with hooks
-
-## Installation
-
-```bash
-npm install animotion-js
-```
-
-Optional peer integrations:
-
-- `three`
-- `@lottiefiles/dotlottie-web`
-
-## Main API
-
-```js
-import Animotion from 'animotion-js';
-import 'animotion-js/styles.css';
-```
-
-Available top-level methods:
-
-- `Animotion.init()`
-- `Animotion.initAttributes()`
-- `Animotion.to()`
-- `Animotion.from()`
-- `Animotion.fromTo()`
-- `Animotion.set()`
-- `Animotion.tween()`
-- `Animotion.timeline()`
-- `Animotion.spring()`
-- `Animotion.keyframes()`
-- `Animotion.motionPath()`
-- `Animotion.sequence()`
-- `Animotion.context()`
-- `Animotion.interactions()`
-- `Animotion.video()`
-- `Animotion.lottie()`
-- `Animotion.dotLottie()`
-- `Animotion.threeStateMachine()`
-- `Animotion.animotionAttrs()`
-
-## Supported Property Scenarios
-
-Animotion can tween:
-
-- regular CSS properties like `opacity`, `backgroundColor`, `boxShadow`, `clipPath`, `borderRadius`
-- transform aliases like `x`, `y`, `z`, `scale`, `scaleX`, `scaleY`, `rotate`, `rotateX`, `rotateY`, `rotateZ`
-- filter aliases like `blur`, `brightness`, `contrast`, `grayscale`, `hueRotate`, `invert`, `saturate`, `sepia`
-- CSS custom properties like `--brand-hue`
-- DOM properties like `scrollTop`, `scrollLeft`, `value`
-- attributes with `attr.data-state`
-- nested object paths like `position.x`, `rotation.y`, `material.opacity`, `camera.position.z`
-- plain JS state objects used for counters, controllers, and render loops
-- Three.js object trees
-- Lottie and dotLottie playhead/frame/progress control
-
-Interpolation currently covers:
-
-- numbers
-- unit strings
-- colors
-- arrays
-- nested objects
-- complex CSS-like strings containing numbers
-
-## Vanilla JS
-
-```js
-Animotion.to('.card', {
-  opacity: 1,
-  y: '0px',
-  rotateY: '0deg',
-  backgroundColor: '#111827',
-  boxShadow: '0 24px 80px rgba(0, 0, 0, 0.35)'
-}, {
-  duration: 1.2,
-  ease: 'expo-out',
-  stagger: 0.08
-});
-
-Animotion.fromTo('.meter', {
-  '--fill': '0%'
-}, {
-  '--fill': '100%'
-}, {
-  duration: 1.4
-});
-```
-
-## Timelines
-
-```js
-const timeline = Animotion.timeline({ autoplay: false })
-  .addLabel('intro')
-  .from('.hero-title', { opacity: 0, y: '60px' }, 0.9, 'expo-out', 'intro')
-  .from('.hero-copy', { opacity: 0, y: '30px' }, 0.7, 'expo-out', 'intro+=0.15')
-  .to('.hero-card', { rotateY: '14deg', z: '24px' }, 1.2, 'ease-in-out', 'intro+=0.2')
-  .set('.badge', { opacity: 1 }, 'intro+=0.4')
-  .call(() => console.log('intro complete'), 'intro+=1');
-
-timeline.play();
-```
-
-## Higher-Level Motion
-
-```js
-Animotion.spring('.chip', { x: 240, opacity: 1 }, {
-  stiffness: 220,
-  damping: 24
-});
-
-Animotion.keyframes('.panel', [
-  { to: { opacity: 1, y: '0px' }, duration: 0.5 },
-  { to: { rotateY: '12deg' }, duration: 0.8, at: '+=0.1' },
-  { to: { rotateY: '0deg' }, duration: 0.5 }
-]);
-
-Animotion.motionPath('.orb', {
-  points: [{ x: 0, y: 0 }, { x: 140, y: -40 }, { x: 260, y: 80 }],
-  autoRotate: true,
-  duration: 2
-});
-
-Animotion.sequence([
-  { id: 'intro', enter: { target: '.title', to: { opacity: 1, y: '0px' }, duration: 0.8 } },
-  { id: 'detail', enter: { target: '.card', to: { opacity: 1, scale: 1 }, duration: 0.6 } }
-]);
-```
-
-## The Declarative `am-*` Attribute System
-
-Animotion now supports a custom attribute workflow built around the `am-*` prefix.
-Every `am-*` declaration also has a matching `data-anim-*` alias. For example, `am-to` can be written as `data-anim-to`, `am-video-frames` can be written as `data-anim-video-frames`, and `am-motion-path` can be written as `data-anim-motion-path`.
-
-Legacy aliases still work too:
-
-- `data-anim` maps to `am`
-- `data-anim-scroll-trigger` maps to `am-scroll`
-- `data-anim-split-text` maps to `am-split`
-
-You can hydrate it with:
-
-```js
-Animotion.initAttributes();
-```
-
-or:
-
-```js
-Animotion.init({ root: document, attributePrefix: 'am' });
-```
-
-### Base Motion Attributes
-
-- `am`
-- `data-anim`
-- `am-id`
-- `am-target`
-- `am-to`
-- `am-from`
-- `am-set`
-- `am-options`
-- `am-duration`
-- `am-delay`
-- `am-ease`
-- `am-repeat`
-- `am-yoyo`
-- `am-stagger`
-
-All of the above also work as `data-anim-id`, `data-anim-target`, `data-anim-to`, and so on.
-
-### Trigger Attributes
-
-- `am-on="load"`
-- `am-on="click"`
-- `am-on="mouseenter"`
-- `am-on="focus"`
-- `am-on="pointerdown"`
-- `am-on="inview"`
-- `am-on="click,mouseenter"`
-- `am-once="true"`
-- `am-prevent-default="true"`
-
-### Timeline Attributes
-
-- `am-timeline="hero"`
-- `am-timeline-auto="true"`
-- `am-timeline-options='{"repeat":1}'`
-- `am-position=">"`
-- `am-position="intro+=0.2"`
-- `am-label="intro"`
-- `am-control="hero"`
-- `am-action="play"`
-
-### Scroll / Scene Attributes
-
-- `am-scroll='{"start":"top center","once":true}'`
-- `am-scroll='{"scrub":true}'`
-- `am-mouse='{"movement":24,"duration":0.35}'`
-- `am-parallax="0.35"`
-- `am-parallax-options='{"axis":"x","speed":0.2}'`
-- `am-draggable='{"lockAxis":"x"}'`
-- `am-spring='{"to":{"x":240,"opacity":1},"stiffness":220,"damping":24}'`
-- `am-keyframes='[{"to":{"opacity":1},"duration":0.4},{"to":{"x":"80px"},"duration":0.6}]'`
-- `am-motion-path='{"points":[{"x":0,"y":0},{"x":140,"y":-40},{"x":260,"y":80}],"autoRotate":true}'`
-- `am-path='{"points":[{"x":0,"y":0},{"x":120,"y":60}]}'`
-- `am-sequence='[{"id":"intro","enter":{"target":".title","to":{"opacity":1}}}]'`
-
-Each scene-level attribute has the same `data-anim-*` form, including `data-anim-spring`, `data-anim-keyframes`, `data-anim-motion-path`, `data-anim-path`, and `data-anim-sequence`.
-
-### Text / Media Attributes
-
-- `am-split="chars"`
-- `am-split="words"`
-- `am-split="lines"`
-- `am-split-target="chars"`
-- `am-lottie="/animations/hero.json"`
-- `am-lottie-options='{"loop":false,"renderer":"svg"}'`
-- `am-lottie-on="inview"`
-- `am-lottie-action="play"`
-- `am-lottie-progress="0.65"`
-- `am-lottie-frame="120"`
-- `am-lottie-segment="40,120"`
-- `am-dotlottie="/animations/hero.lottie"`
-- `am-dotlottie-options='{"loop":true}'`
-- `am-dotlottie-on="click"`
-- `am-video="/video/scene.mp4"`
-- `am-video-autoplay="inview"`
-- `am-video-action="play"`
-- `am-video-action="scrub"`
-- `am-video-segment="4.5,9.25"`
-- `am-video-frames="120,220"`
-- `am-video-frame-rate="24"`
-- `am-video-pause-on-leave="true"`
-- `am-three-state="Walk"`
-- `am-three-machine="hero-character"`
-- `am-three-action="play"`
-- `am-three-on="click"`
-
-Media and Three.js declarations also work as `data-anim-video`, `data-anim-video-autoplay`, `data-anim-video-frames`, `data-anim-three-state`, `data-anim-three-machine`, and the rest of the systematic aliases.
-
-## HTML Example
-
-```html
-<section am am-target=".card" am-from='{"opacity":0,"y":"60px","scale":0.92}' am-to='{"opacity":1,"y":"0px","scale":1}' am-duration="1" am-stagger="0.08">
-  <article class="card">One</article>
-  <article class="card">Two</article>
-  <article class="card">Three</article>
-</section>
-
-<button am-control="hero" am-action="play" am-on="click">Play Timeline</button>
-
-<div am-scroll='{"scrub":true}' am-to='{"rotateY":"20deg","x":"80px"}'></div>
-
-<h1 am am-split="chars" am-split-target="chars" am-from='{"opacity":0,"y":"40px"}' am-to='{"opacity":1,"y":"0px"}' am-stagger="0.03"></h1>
-```
-
-## React Setup
-
-Use scoped hydration:
-
-```jsx
-import { useAnimotionAttributes, animotionAttrs } from 'animotion-js/react';
-import 'animotion-js/styles.css';
-
-export function Hero() {
-  const scopeRef = useAnimotionAttributes({}, []);
-
-  return (
-    <section ref={scopeRef}>
-      <h1
-        {...animotionAttrs({
-          split: 'chars',
-          splitTarget: 'chars',
-          from: { opacity: 0, y: '48px' },
-          to: { opacity: 1, y: '0px' },
-          duration: 0.9,
-          stagger: 0.03
-        })}
-      >
-        Animotion
-      </h1>
-
-      <div
-        {...animotionAttrs({
-          on: 'mouseenter',
-          from: { scale: 1 },
-          to: { scale: 1.08, rotateY: '8deg' },
-          duration: 0.4
-        })}
-      />
-    </section>
-  );
-}
-```
-
-## Next.js Setup
-
-```jsx
-'use client';
-
-import { useAnimotionAttributes, animotionAttrs } from 'animotion-js/next';
-import 'animotion-js/styles.css';
-
-export default function Page() {
-  const scopeRef = useAnimotionAttributes({}, []);
-
-  return (
-    <main ref={scopeRef}>
-      <canvas
-        {...animotionAttrs({
-          dotlottie: '/animations/hero.lottie',
-          dotlottieOn: 'inview',
-          dotlottieAction: 'play'
-        })}
-      />
-    </main>
-  );
-}
-```
-
-## Three.js
-
-```js
-Animotion.to(mesh, {
-  position: { x: 3, y: 1.5, z: -2 },
-  rotation: { y: Math.PI * 1.5 },
-  material: { opacity: 0.4, color: '#22c55e' }
-}, {
-  duration: 1.6,
-  ease: 'ease-in-out',
-  render: () => renderer.render(scene, camera)
-});
-```
-
-GLTF files can expose multiple animation clips. Animotion can wrap those clips as a small action state machine:
-
-```js
-const actor = Animotion.threeStateMachine(gltf, {
-  THREE,
-  renderer,
-  scene,
-  camera,
-  initialState: 'Idle',
-  fade: 0.25
-});
-
-actor.play('Walk');
-actor.play('Jump', { fade: 0.1, loop: 'LoopOnce', clampWhenFinished: true });
-actor.update(delta);
-actor.stopLoop();
-```
-
-For declarative Three.js state controls, register the machine with an id and point an element at it:
-
-```js
-Animotion.threeStateMachine(gltf, {
-  id: 'hero-character',
-  THREE,
-  renderer,
-  scene,
-  camera,
-  initialState: 'Idle'
-});
-```
-
-```html
-<button data-anim-three-machine="hero-character" data-anim-three-state="Walk" data-anim-three-action="play" data-anim-three-on="click">
-  Walk
-</button>
-```
-
-## Video Sections
-
-Use one video as a cinematic source and play different time or frame ranges per section:
-
-```js
-const reel = Animotion.video(document.querySelector('.scene-a'), {
-  src: '/video/reel.mp4',
-  autoplay: false,
-  frameRate: 24,
-  sections: {
-    opening: { frames: [0, 96] },
-    reveal: { start: 8.5, end: 14.2 }
-  }
-});
-
-reel.playSegment('opening');
-reel.playFrames(144, 220);
-```
-
-Declarative sections can autoplay on viewport entry or scrub only the selected slice:
-
-```html
-<section am-video="/video/reel.mp4" am-video-autoplay="inview" am-video-frames="0,96" am-video-frame-rate="24"></section>
-<section am-video="/video/reel.mp4" am-video-on="inview" am-video-action="scrub" am-video-segment="8.5,14.2"></section>
-```
-
-The same setup with complete `data-anim-*` aliases:
-
-```html
-<section data-anim-video="/video/reel.mp4" data-anim-video-autoplay="inview" data-anim-video-frames="0,96" data-anim-video-frame-rate="24"></section>
-<section data-anim-video="/video/reel.mp4" data-anim-video-on="inview" data-anim-video-action="scrub" data-anim-video-segment="8.5,14.2"></section>
-```
-
-## Lottie
-
-```js
-const lottie = Animotion.lottie({
-  container: document.querySelector('#lottie'),
-  renderer: 'svg',
-  loop: false,
-  autoplay: false,
-  path: '/animations/hero.json'
-});
-
-lottie.tweenToProgress(0.75, {
-  duration: 1.2,
-  ease: 'ease-in-out'
-});
-```
-
-## dotLottie
-
-```js
-const dotLottie = Animotion.dotLottie({
-  canvas: document.querySelector('#dotlottie'),
-  src: '/animations/hero.lottie',
-  autoplay: false,
-  loop: true
-});
-
-dotLottie.setSpeed(1.2).play();
-```
-
-## Notes
-
-- Legacy `data-anim-*` attributes still work.
-- The new recommended declarative setup is `am-*`.
-- React and Next can use the same attribute model via `animotionAttrs()`.
-- `npm test` currently passes with no tests because the repo still has no actual Jest test suite.
-
-## Commands
-
-```bash
-npm run lint
-npm test
-npm run build
-```