Metal.js Animation Utility

Common errors

• TypeError: Cannot read properties of undefined (reading 'animate') or (reading 'easing')

  cause The imported `animate` or `easing` function is not found, likely due to incorrect import paths, module resolution issues (ESM vs. CJS), or the library not exporting these symbols as expected.
  fix Ensure `metal-anim` is correctly installed (`npm install metal-anim`) and check your import statement. Verify if your build setup correctly handles ES modules or CommonJS. As official documentation is scarce, confirm expected exports by inspecting the `node_modules/metal-anim` package.

• Animation does not run or element does not change style/position as expected.

  cause This can stem from several issues: the target element selector is incorrect, the element is not in the DOM, CSS properties are being overridden, or the animation API call itself has an error (e.g., incorrect property names, missing `start()` call).
  fix Double-check your element selector (`#animated-box`). Confirm the element is appended to the DOM before the animation starts. Inspect browser developer tools for CSS conflicts or JavaScript errors in the console. Ensure all required parameters for the `animate` function are provided and correctly typed (e.g., `duration` is a number).

Warnings

• breaking The underlying Metal.js framework, which `metal-anim` depends on, has been officially deprecated since September 2023 and is no longer actively maintained. This means `metal-anim` itself is effectively abandoned and unlikely to receive updates, bug fixes, or security patches.
  Fix: Migrate to a modern, actively maintained animation library (e.g., Anime.js, Framer Motion, GSAP) that is compatible with current JavaScript standards and frameworks.
• gotcha Older versions of Metal.js and its utilities, including `metal-anim`, might have assumed a CommonJS (require) module system, especially given the `node: >=0.12.0` engine requirement. Using modern ESM `import` statements might require specific build configurations or bundler setups, or might not work at all without transpilation.
  Fix: If encountering module resolution errors (`require is not defined` or similar), try configuring your bundler (Webpack, Rollup, Parcel) to handle CJS modules or use `require()` syntax directly if in a Node.js environment supporting it. However, the recommended fix is migration to a modern library.
• gotcha Due to the abandonment of the Metal.js ecosystem, `metal-anim` may not be compatible with newer browser APIs, JavaScript language features, or other contemporary frontend frameworks and libraries, potentially leading to unexpected behavior or runtime errors.
  Fix: Thoroughly test `metal-anim` in your target environment. For new projects, or projects experiencing issues, migration to an actively developed animation library is strongly recommended.

Install

• npm install metal-anim npm
• yarn add metal-anim yarn
• pnpm add metal-anim pnpm

Imports

• animate
  wrong:

  const animate = require('metal-anim');

  correct:

  import { animate } from 'metal-anim';

  Assumed named export for the primary animation function. Early versions of Metal.js and Node.js v0.12 might have relied on CommonJS, but modern usage would prefer ESM.
• easing
  wrong:

  import * as anim from 'metal-anim'; const customEase = anim.easing.bounce;

  correct:

  import { easing } from 'metal-anim';

  Assumed named export for animation easing functions. The specific structure (e.g., `easing.bounce`) is inferred from common animation library patterns due to lack of explicit documentation.
• timeline
  wrong:

  import metalAnim from 'metal-anim'; // if not a default export

  correct:

  import { timeline } from 'metal-anim';

  Assumed named export for creating complex animation sequences. This aligns with standard practices in JavaScript animation libraries for orchestrating multiple animations.

Quickstart

Demonstrates animating a DOM element's position, color, and rotation using assumed `animate` and `easing` functions from `metal-anim`.

import { animate, easing } from 'metal-anim';

const element = document.createElement('div');
element.id = 'animated-box';
element.style.width = '100px';
element.style.height = '100px';
element.style.backgroundColor = 'blue';
element.style.position = 'absolute';
element.style.left = '0px';
document.body.appendChild(element);

// Basic animation: move the box to the right
animate({
  element: '#animated-box',
  properties: {
    left: '500px',
    backgroundColor: 'red',
    transform: 'rotate(360deg)'
  },
  duration: 1000, // milliseconds
  easing: easing.easeInOutQuad,
  onComplete: () => {
    console.log('Animation complete!');
    // Animate back or start a new sequence
    animate({
      element: '#animated-box',
      properties: {
        left: '0px',
        backgroundColor: 'blue',
        transform: 'rotate(0deg)'
      },
      duration: 800,
      easing: easing.easeOutBounce,
      delay: 500
    });
  }
}).start();

// Note: The specific API (`element`, `properties`, `duration`, `easing`, `onComplete`, `start()`) is inferred based on common JavaScript animation libraries due to the absence of direct documentation for metal-anim.