VecUI

Tiny, ergonomic and fun vector library for UI engineers.

Why?

CSS doesn't lend itself well to animated layouts with complex constraints. In these cases I almost always had to code the layout myself using JavaScript and absolutely positioned elements in a flat hierarchy. This vector library is meant to make this very easy.

That's because UIs are made of rectangles, and rectangles are made of 2 vectors: one for describing their origin point, and another for describing their width and height. Treating your layout as vectors makes it much easier to reason about and perform operations on it, and can trivially cut complex UI code in half (see demo).

VecUI includes utilities to turn your UI into vectors and back again, and comes with a beautiful API that is both easy to read and write.

Features

• All the vector operations you would expect and more.
• A beautiful, ergonomic API that doesn't make you repeat yourself.
• Immutable values. Treat your vectors just like any other primitive.
• Utilities for working with UIs.
• Probably the most fun you'll ever have with vectors.
• <1 KB

Installation

yarn add vecui

Usage

The best way to get an intuition for VecUI and see what it looks like is to play with the demo.

Generally, you will

1. Create rects and vectors with rect() and vec() to represent your UI elements.
2. Use the vector operations to manipulate them.
3. Apply them to your UI.

// Create a vector for the dimensions of an anchor div
const dimensions = vec(30);
// Create a rect for the anchor div, centered at the origin
const anchorRect = rect(dimensions.div(-2), dimensions);
// Create a rect that is vertically centered and horizontally aligned to the right of the anchor div by
const alignedRect = rect(
  anchorRect.o
    // offsetting its origin by the width of the anchor div
    .add(anchorRect.d.x, 0)
    .add(
      // adding the padding in the x direction and
      8,
      // centering it vertically
      anchorRect.d.sub(alignedRect.d).div(2).y
    ),
  // size of the aligned rect
  vec(20)
);
// Apply it to your UI
const alignedDiv = document.getElementById("aligned");
alignedDiv.style = alignedRect.as.styleObject();

API

The API consists of functions to create and manipulate vectors and rectangles. VecUI vectors are 2 dimensional. Rectangles are composed of 2 vectors, one for the origin point, and another for the width and height. All values are immutable, functions return new values instead of mutating existing ones.

Rectangles

rect()

Creates a rectangle with the specified origin point and dimensions.

const r1 = rect(vec(1, 2), vec(3, 4));
const r2 = rect({ x: 1, y: 2, width: 3, height: 4 });
const r3 = rect(htmlElement.getBoundingClientRect());

o

The origin point of the rectangle.

const r1 = rect(vec(1, 2), vec(3, 4));

r1.o; // => vec(1, 2)

d

The dimensions of the rectangle.

const r1 = rect(vec(1, 2), vec(3, 4));

r1.d; // => vec(3, 4)

as

Utilities for converting the rect to different style formats.

as.styleObject()

Returns a style object that can be applied to an HTML or React element.

const r1 = rect(vec(1, 2), vec(3, 4));

r1.as.styleObject(); // => { left: "1px", top: "2px", width: "3px", height: "4px" }
myDiv.style = r1.as.styleObject();

as.cssText()

Returns a CSS text string.

const r1 = rect(vec(1, 2), vec(3, 4));

r1.as.cssText(); // => "left: 1px; top: 2px; width: 3px; height: 4px;"

setO()

Returns a new rectangle with the origin point set to the specified vector.

const r1 = rect(vec(1, 2), vec(3, 4));

r1.setO(vec(5, 6)); // => rect(vec(5, 6), vec(3, 4))

setD()

Returns a new rectangle with the dimensions set to the specified vector.

const r1 = rect(vec(1, 2), vec(3, 4));

r1.setD(vec(5, 6)); // => rect(vec(1, 2), vec(5, 6))

map()

Map the origin point and dimensions of the rectangle.

const r1 = rect(vec(1, 2), vec(3, 4));

r1.map((o, d) => [o.add(1, 1), d.add(1, 1)]); // => rect(vec(2, 3), vec(4, 5))

equals()

Checks if this rect equals another rect.

const r1 = rect(vec(1, 2), vec(3, 4));
const r2 = rect(vec(1, 2), vec(3, 4));

r1.equals(r2); // => true

Vectors

vec()

Creates a vector with the specified components.

const v1 = vec(1, 2);
const v2 = vec([1, 2]);
const v3 = vec({ x: 1, y: 2 });

// You can also create vectors with a single number.
const v4 = vec(100);

x

The x component of the vector.

const v1 = vec(1, 2);

v1.x; // => 1

y

The y component of the vector.

const v1 = vec(1, 2);

v1.y; // => 2

yx

Returns a new vector with the components swapped.

const v1 = vec(1, 2);

v1.yx; // => vec(2, 1)

setX()

Returns a new vector with the x component set to the specified value.

const v1 = vec(1, 2);

v1.setX(3); // => vec(3, 2)

setY()

Returns a new vector with the y component set to the specified value.

const v1 = vec(1, 2);

v1.setY(3); // => vec(1, 3)

map()

Maps the components of the vector.

const v1 = vec(1, 2);

v1.map((x, y) => [x + 1, y + 1]); // => vec(2, 3)

reduce()

Reduces the vector to a single value.

const v1 = vec(1, 2);

v1.reduce((x, y) => x + y); // => 3

add()

Adds another vector or components to this vector.

const v1 = vec(1, 2);
const v2 = vec(3, 4);

v1.add(v2); // => vec(4, 6)

// You can also directly add scalars to components.
v1.add(3, 4); // => vec(4, 6)

sub()

Subtracts another vector or components from this vector.

const v1 = vec(1, 2);
const v2 = vec(3, 4);

v1.sub(v2); // => vec(-2, -2)

// You can also directly subtract scalars from components.
v1.sub(3, 4); // => vec(-2, -2)

div()

Divides this vector by another vector or components.

const v1 = vec(1, 2);
const v2 = vec(3, 4);

v1.div(v2); // => vec(0.33, 0.5)

// You can also directly divide components by scalars.
v1.div(3, 4); // => vec(0.33, 0.5)

// Or divide by a single scalar.
v1.div(2); // => vec(0.5, 1)

dot()

Calculates the dot product with another vector or components.

const v1 = vec(1, 2);
const v2 = vec(3, 4);

v1.dot(v2); // => 11

// You can also directly calculate the dot product with components.
v1.dot(3, 4); // => 11

cross()

Calculates the cross product with another vector or components.

const v1 = vec(1, 2);
const v2 = vec(3, 4);

v1.cross(v2); // => -2

// You can also directly calculate the cross product with components.
v1.cross(3, 4); // => -2

mul()

Element-wise multiplies the vector with another vector, components, or scalar.

const v1 = vec(1, 2);
const v2 = vec(3, 4);

v1.mul(v2); // => vec(3, 8)

// You can also directly multiply components by scalars.
v1.mul(3, 4); // => vec(3, 8)

// Or multiply by a single scalar.
v1.mul(2); // => vec(2, 4)

len()

Calculates the length (L2 norm) of the vector.

const v1 = vec(3, 4);

v1.len(); // => 5

norm()

Normalizes the vector.

const v1 = vec(3, 4);

v1.norm(); // => vec(0.6, 0.8)

rotRad()

Rotates the vector by a specified number of radians.

const v1 = vec(1, 0);

v1.rotRad(Math.PI / 2); // => vec(0, 1)

rotDeg()

Rotates the vector by a specified number of degrees.

const v1 = vec(1, 0);

v1.rotDeg(90); // => vec(0, 1)

angleTo()

Calculates the angle between this vector and another vector.

const v1 = vec(1, 0);

v1.angleTo(vec(0, 1)); // => Math.PI / 2

lookAt()

Calculate the rotation to apply to an object with coordinates at this vector to look at another vector, with the front of the object at the given side. Assumes a left-handed coordinate system.

const v1 = vec(1, 0);

v1.lookAt(vec(0, 1)); // => Math.PI * 3 / 4
v1.lookAt(vec(0, 1), "y"); // => Math.PI * 5 / 4

asArray()

Returns the vector as an array.

const v1 = vec(1, 2);

v1.asArray(); // => [1, 2]

isInRect()

Checks if the vector is within a given rectangle.

const v1 = vec(1, 2);

v1.isInRect(rect(0, 0, 2, 3)); // => true

// The function also accepts the same inputs as the rect() function so you can use it directly.
v1.isInRect({ x: 0, y: 0, width: 2, height: 3 }); // => true
v1.isInRect(vec(0, 0), vec(2, 3)); // => true

equals()

Checks if the vector equals another vector or specified components.

const v1 = vec(1, 2);
const v2 = vec(1, 2);

v1.equals(v2); // => true

// You can also directly compare components.
v1.equals(1, 2); // => true