Core

Spring

SpringAnimator animates several numbers at once with springs set by a duration in seconds and a bounce from 0 to 1. It’s exact at any frame rate. Changing the target keeps the current velocity, so reversing mid-way stays smooth, which CSS transitions can’t do.

pnpm add @fluidkit/core

import { SpringAnimator } from "@fluidkit/core";

const spring = new SpringAnimator(
  { width: 100, radius: 12 },
  { duration: 0.4, bounce: 0.2 },
  ({ width, radius }) => {
    el.style.width = `${width}px`;
    el.style.borderRadius = `${radius}px`;
  },
  () => console.log("at rest"), // optional
);

spring.to({ width: 240, radius: 24 });
spring.to({ width: 100, radius: 12 }, { duration: 0.6, bounce: 0 }); // new springs are optional
spring.retarget({ width: 110, radius: 12 }); // adjust the current movement, no new bounce
spring.jump({ width: 120 }); // move a channel at once, keeping its velocity and target
spring.values(); // where it is now
spring.velocities(); // how fast each channel moves, units per second: hand it on with to()'s third argument
spring.stop();

Each channel can have a spring of its own:

new SpringAnimator(
  { opacity: 0, scale: 1 },
  {
    opacity: { duration: 0.15, bounce: 0 },
    scale: { duration: 0.45, bounce: 0.3 },
  },
  ({ opacity, scale }) => {
    /* … */
  },
);

SpringParams is { duration, bounce, settle? }. duration is how long the motion feels, in seconds; it isn’t a hard deadline. bounce runs from 0 (no overshoot) to 1; below 1 the spring comes to rest. settle is the bounce after the first overshoot, bounce by default: a bouncy spring with a low settle overshoots once and then comes back without swinging. to() starts a new movement, with its bounce; retarget() changes the target of the current one without a new bounce.

Boxes

What morph and indicator read an element by: where it is, its size, and its corners as the browser draws them, so something else can take its shape. Corners are circular, never an oval: a percent resolves against the box, and an elliptical corner takes the smaller of its two radii. Where two corners on a side ask for more than the side has, all of them shrink by the same factor, so a capsule’s 9999px comes out as half its height.

import { measureBox, radiiCss, still } from "@fluidkit/core";

// Its box on screen, without the inline transforms a press left on it
const box = still(el, () => measureBox(el, true));
// { x, y, width, height, radii: [tl, tr, br, bl], shape }

other.style.borderRadius = radiiCss(box.radii);

Contract

The packages never import each other. Instead, each marks what it does with attributes in the DOM and reads the attributes the others set, so each works alone and any two work together. The names are exported as constants and change only in a major version of every package.