Necessarily Precedes Mischief

    the-dom-box

    1.4.3 • Public • Published

    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()](<{@link 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.

    Install

    npm i the-dom-box

    DownloadsWeekly Downloads

    7

    Version

    1.4.3

    License

    MIT

    Last publish

    Collaborators

    • avatar