declarative-svg-animator

A small library for creating SVG animations declaratively using the data-animate attribute. Written in pure JavaScript (CommonJS) and lightweight, suitable for bundlers (Webpack/Rollup/Parcel) or Node-based builds.

Briefly:

• Nama paket: declarative-svg-animator
• Language: JavaScript (CommonJS)
• Goal: declare animations in SVG elements with JSON in the data-animate attribute.

Feature

• Declarative: define animations directly in SVG elements.
• Interpolation of numeric values ​​(including units such as px, %).
• Some basic easing (linear, easeInQuad, easeOutQuad, easeInOutQuad).
• Timeline control: add, stop animation.
• Simple API for integration and testing.

Installation

From npm (after publish):

npm install declarative-svg-animator

Or use the bundler to generate a browser bundle.

How to use (quick example)

Contoh SVG:

<svg width="400" height="120">
<rect id="r" x="10" y="10" width="50" height="50" fill="tomato"
data-animate='{"attribute":"x","to":250,"dur":1200,"easing":"easeInOutQuad"}' />
</svg>

Initialization in JS:

const lib = require('declarative-svg-animator'); // CommonJS
const animations = lib.parse(document);         // cari elemen [data-animate]
const tl = lib.createTimeline();                // create a timeline
animations.forEach(desc => tl.add(desc));      // run all found animations

If you want manual control for a single animation:

const a = new lib.Animator({
element: document.getElementById('r'),
attribute: 'x',
from: 10,
to: 200,
dur: 1000,
easing: 'easeInOutQuad'
});
const tl = lib.createTimeline();
tl.add(a);

Format atribut data-animate

The data-animate attribute contains short JSON. Supported fields:

• attribute (string) — name of the attribute/style to be animated (e.g. "x", "y", "width", "fill").
• to (number|string) — destination value.
• from (number|string, optional) — initial value; if not set, the library reads the value at runtime.
• dur (number, ms) — duration in milliseconds (default 1000).
• delay (number, ms) — delay before starting.
• easing (string) — "linear", "easeInQuad", "easeOutQuad", "easeInOutQuad".
• iterations (number) — number of repetitions (default 1).
• direction (string) — "normal" or "reverse".
• id (string, optional) — id for reference.

Example:

<circle cx="20" cy="50" r="10" data-animate='{"attribute":"cx","to":300,"dur":1500,"delay":200}' />

Note: color interpolation and simple transform support is limited; use numeric values ​​or values ​​with the same units for best results.

API Reference

• parse(root)

• Description: looks for elements with data-animate at the root (Document or element) and returns an array of descriptors.

• Contoh: const list = lib.parse(document);

• createTimeline()

• Description: creates a timeline that runs the animation. Returns an object with the method:

• add(descriptor | Animator) -> Animator

• stopAll()

• isRunning()

• Contoh: const tl = lib.createTimeline(); tl.add(desc);

• Animator (class)

• Konstruktor menerima descriptor { element, attribute, from?, to, dur?, delay?, easing?, iterations?, direction? }.

• Metode: play(), pause(), tick(now), onfinish(fn).

Development & Build

• Project structure:
• index.js (entry)
• package.json
• src/ (animator, parser, timeline, utils)
• To build the browser bundle, add the Rollup/webpack configuration and UMD/ESM build to the dist folder.
• To publish to npm:

1. Make sure package.json contains a unique name.
2. Add README.md and LICENSE.
3. Login npm: npm login
4. Publish: npm publish --access public

Testing & Debug

• The library is structured so that it can be tested with unit tests in the src/ module.
• Run custom tests according to the test script in package.json (if any).

Contribution

• Fork the repo, create a feature/bugfix branch, open a PR with a short description.
• Preferences: add unit tests and short documentation for new features.

License

MIT — add the LICENSE file in the root of the repo before publishing.

Final note

The library focuses on simplicity. For advanced needs (morphs, complex colors, transform matrices), consider adding custom color parsers and interpolators.

# declarative-svg-animator

A small library for creating SVG animations declaratively using the `data-animate` attribute. Written in pure JavaScript (CommonJS) and lightweight, suitable for bundlers (Webpack/Rollup/Parcel) or Node-based builds.

Briefly:
- Nama paket: declarative-svg-animator
- Language: JavaScript (CommonJS)
- Goal: declare animations in SVG elements with JSON in the `data-animate` attribute.

## Feature
- Declarative: define animations directly in SVG elements.
- Interpolation of numeric values ​​(including units such as px, %).
- Some basic easing (linear, easeInQuad, easeOutQuad, easeInOutQuad).
- Timeline control: add, stop animation.
- Simple API for integration and testing.

## Installation
From npm (after publish):
```bash
npm install declarative-svg-animator

Or use the bundler to generate a browser bundle.

How to use (quick example)

Contoh SVG:

<svg width="400" height="120">
<rect id="r" x="10" y="10" width="50" height="50" fill="tomato"
data-animate='{"attribute":"x","to":250,"dur":1200,"easing":"easeInOutQuad"}' />
</svg>

Initialization in JS:

const lib = require('declarative-svg-animator'); // CommonJS
const animations = lib.parse(document);         // cari elemen [data-animate]
const tl = lib.createTimeline();                // create a timeline
animations.forEach(desc => tl.add(desc));      // run all found animations

If you want manual control for a single animation:

const a = new lib.Animator({
element: document.getElementById('r'),
attribute: 'x',
from: 10,
to: 200,
dur: 1000,
easing: 'easeInOutQuad'
});
const tl = lib.createTimeline();
tl.add(a);

Format atribut data-animate

The data-animate attribute contains short JSON. Supported fields:

• attribute (string) — name of the attribute/style to be animated (e.g. "x", "y", "width", "fill").
• to (number|string) — destination value.
• from (number|string, optional) — initial value; if not set, the library reads the value at runtime.
• dur (number, ms) — duration in milliseconds (default 1000).
• delay (number, ms) — delay before starting.
• easing (string) — "linear", "easeInQuad", "easeOutQuad", "easeInOutQuad".
• iterations (number) — number of repetitions (default 1).
• direction (string) — "normal" or "reverse".
• id (string, optional) — id for reference.

Example:

<circle cx="20" cy="50" r="10" data-animate='{"attribute":"cx","to":300,"dur":1500,"delay":200}' />

Note: color interpolation and simple transform support is limited; use numeric values ​​or values ​​with the same units for best results.

API Reference

• parse(root)

• Description: looks for elements with data-animate at the root (Document or element) and returns an array of descriptors.

• Contoh: const list = lib.parse(document);

• createTimeline()

• Description: creates a timeline that runs the animation. Returns an object with the method:

• add(descriptor | Animator) -> Animator

• stopAll()

• isRunning()

• Contoh: const tl = lib.createTimeline(); tl.add(desc);

• Animator (class)

• Konstruktor menerima descriptor { element, attribute, from?, to, dur?, delay?, easing?, iterations?, direction? }.

• Metode: play(), pause(), tick(now), onfinish(fn).

Development & Build

• Project structure:
• index.js (entry)
• package.json
• src/ (animator, parser, timeline, utils)
• To build the browser bundle, add the Rollup/webpack configuration and UMD/ESM build to the dist folder.
• To publish to npm:

1. Make sure package.json contains a unique name.
2. Add README.md and LICENSE.
3. Login npm: npm login
4. Publish: npm publish --access public

Testing & Debug

• The library is structured so that it can be tested with unit tests in the src/ module.
• Run custom tests according to the test script in package.json (if any).

Contribution

• Fork the repo, create a feature/bugfix branch, open a PR with a short description.
• Preferences: add unit tests and short documentation for new features.

License

MIT — add the LICENSE file in the root of the repo before publishing.

Final note

The library focuses on simplicity. For advanced needs (morphs, complex colors, transform matrices), consider adding custom color parsers and interpolators.