npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

the-dom-box

v1.4.3

Published

Utilities for working with DOM boxes.

Downloads

68

Readme

The Box

Utilities for working with DOM boxes.

npm npm David Travis

How to use

Install the library via NPM:

npm install the-dom-box --save

Then use in your project like this:

import TheBox from 'the-dom-box';

// define some boxes
var my_element = document.getElementById('my_box');
var my_element_box = TheBox.getBox();
var viewport_box = TheBox.getBox('viewport');

// update box properties to reflext current size and position of input
my_element.style.left = '100px';
my_element_box.update();

// determine whether element can fit inside the viewport
TheBox.canContain(viewport_box, my_element_box); // -> true

// determine whether viewport can contain element with 100px empty space around it
my_element_box.pad(100);
TheBox.canContain(viewport_box, my_element_box); // -> false

Documentation

getBox

Checks for the type of input and returns appropriate Box object.

Parameters

  • input [Any]

Returns Box instance of Box object

BoxProperties

Data object representing a box, with basic properties.

Box

Class representing an abstract Box.

constructor

Constructs generic Box object.

Parameters

pivot

Properties

  • pivot object
    • pivot.left number Left position of Box's pivot.
    • pivot.top number Top position of Box's pivot.

set

Updates properties of the box

Parameters

Returns BoxProperties

get

Gets current properties of the box.

Returns BoxProperties

update

Updates properties of the Box according to the Box's input. This doesn't really do anything in Generic Box. But it recalculates box properties for DOM element, collection, viewport, etc.

Returns BoxProperties

pad

Adds padding to the whole box.

Parameters

  • padding [number] (optional, default 0)

padHorizontal

Adds padding to the left and right side of box.

Parameters

  • padding [number] (optional, default 0)

padVertical

Adds padding to the top and bottom side of box.

Parameters

  • padding [number] (optional, default 0)

moveTo

Move box to a specific location

Parameters

Returns Box

movePivotTo

Moves pivot of the box to a specific location, recalculates the other properties accordingly.

Parameters

Returns BoxProperties

moveBy

Moves the box by a distance.

Parameters

Returns BoxProperties

resizeTo

Resizes the box to a specific size.

Parameters

  • width
  • height

Returns BoxProperties

resizeBy

Resizes the box by a specific value.

Parameters

Returns BoxProperties

toString

Returns text representation of Box properties. Used for debugging.

Parameters

  • pretty [boolean] If true, returns pretty formatted string. (optional, default false)

Returns string

ElementBox

Extends Box

Class representing Box of an Element.

CollectionBox

Extends Box

Class representing bounding Box around collection of elements. Accepts either HTMLCollection (e.g. getElementsByTagName()) or NodeList (e.g. querySelectorAll()).

DocumentBox

Extends Box

Class representing Box of whole document.

ViewportBox

Extends Box

Class representing Box of viewport.

get-distance

Returns horizontal, vertical, direct and pivot distance between two boxes.

Parameters

Returns {horizontal: number, vertical: number, pivot: number}

get-difference

Returns horizontal and vertical difference between two boxes. Positive values mean that boxes are apart, zero value means boxes are touching, negative value means boxes are overlapping.

Parameters

Returns {horizontal: number, vertical: number}

get-overlap

Returns box for an area where both boxes are overlapping. Returns null if boxes do not overlap.

Parameters

Returns (Box | null)

detect-overlap

Returns true if both boxes overlap at least partially.

Parameters

Returns boolean

get-pivot-angle

Returns angle between pivots of both boxes. Can be used with Angle JS to determine direction of one box relative to another.

Parameters

  • a Box
  • b Box
  • use_radian [boolean] If true, returns result in radians, otherwise in degrees. (optional, default false)

Returns number

move-inside

Changes position of b to the closest position where it is completely inside a. If b can not fit a, it is positioned at top-left corner of a.

Parameters

contains

Returns true if box b is completely inside box a.

Parameters

Returns boolean

can-contain

Returns true if b can fit completely inside a.

Parameters

Returns boolean

can-coexist

Returns true if both b and c can fit completely inside a without changing their respective positions. Handy when deciding if boxes can be fully scrolled into a viewport.

Parameters

Returns boolean

can-fit-around

Returns true if c can be positioned inside a so that it will not collide with b.

Parameters

Returns boolean

find-closest

Returns box that is closest to a.

Parameters

  • a Box
  • boxes [Array<Box>] (optional, default [])
  • property [string] Box's distance property (horizontal, vertical, direct or pivot) that will be used to evaluate (see getDistance()). (optional, default 'direct')

Returns (Box | null)

fit-around

Changes positino of c so that it is positioned inside a without colliding with b. If it is not possible, position of c is unchanged. It will move the box to a new position closest to its original position.

Parameters

shrink-to-fit

Adjusts size of b so that it fits a while keeping the original aspect ratio. Does nothing if b is smaller than a.

Parameters

align

Adjusts position of b so that it is aligned to a.

Parameters

  • a Box
  • b Box
  • horizontal [string] 'left', 'right' or 'center'
  • vertical [string] 'top', 'bottom' or 'center

touch

Move b so that it touches a from the outside.

Parameters

  • a Box
  • b Box
  • horizontal [(null | string)] Either left or right.
  • vertical [(null | string)] Either top or bottom.