# layout

> Organize and layout items based on various algorithms

Latest version **2.2.0** (published 2015-02-19) · 0 weekly downloads

## Install

```sh
npm install layout
pnpm add layout
yarn add layout
bun add layout
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.2.0 |
| Published | 2015-02-19 |
| First published | 2012-11-06 |
| Weekly downloads | 0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >= 0.8.0 |
| Dependencies | 1 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 118 |
| Author | Todd Wolfson |
| Maintainers | twolfson |
| Keywords | layout, blueprint, organize, pack, algorithm |

## Links

- npm: https://www.npmjs.com/package/layout
- Repository: https://github.com/twolfson/layout
- Issues: https://github.com/twolfson/layout/issues
- npm.io page: https://npm.io/package/layout

## Dependencies (1)

- [bin-pack](https://npm.io/package/bin-pack.md) ~1.0.1

## Alternatives

- [raw-loader](https://npm.io/package/raw-loader.md) — 4.3M weekly downloads
- [plop](https://npm.io/package/plop.md) — 1.4M weekly downloads
- [webpack-deadcode-plugin](https://npm.io/package/webpack-deadcode-plugin.md) — 80.3K weekly downloads
- [@storybook/preact-vite](https://npm.io/package/@storybook/preact-vite.md) — 54.2K weekly downloads
- [vite-plugin-transform](https://npm.io/package/vite-plugin-transform.md) — 2.4K weekly downloads

## Recent versions

- 2.2.0 (latest) — 2015-02-19
- 2.1.0 — 2015-01-27
- 2.0.2 — 2014-12-14
- 2.0.1 — 2014-12-14
- 2.0.0 — 2014-04-16
- 1.3.2 — 2014-04-16
- 1.3.1 — 2013-06-19
- 1.3.0 — 2013-04-26
- 1.2.1 — 2012-11-15
- 1.2.0 — 2012-11-15
- 1.1.0 — 2012-11-15
- 0.2.0 — 2012-11-15
- 0.1.1 — 2012-11-06
- 0.1.0 — 2012-11-06

## README

# layout [![Build status](https://travis-ci.org/twolfson/layout.png?branch=master)](https://travis-ci.org/twolfson/layout)

Organize and layout items based on various algorithms

Visualizations of output data:

|         `top-down`        |          `left-right`         |         `diagonal`        |           `alt-diagonal`          |          `binary-tree`          |
|---------------------------|-------------------------------|---------------------------|-----------------------------------|---------------------------------|
| ![top-down][top-down-img] | ![left-right][left-right-img] | ![diagonal][diagonal-img] | ![alt-diagonal][alt-diagonal-img] | ![binary-tree][binary-tree-img] |

[top-down-img]: docs/top-down.png
[left-right-img]: docs/left-right.png
[diagonal-img]: docs/diagonal.png
[alt-diagonal-img]: docs/alt-diagonal.png
[binary-tree-img]: docs/binary-tree.png

## Getting Started
Install the module with: `npm install layout`

```js
// Load in layout
var layout = require('layout');

// Generate a new layer to organize items on
var layer = layout('top-down');

// Add items that you want to organize
layer.addItem({'height': 20, 'width': 10, 'meta': 'medium'});
layer.addItem({'height': 10, 'width': 10, 'meta': 'small'});
layer.addItem({'height': 50, 'width': 40, 'meta': 'large'});

// Export the info
var info = layer['export']();

// We get back the width and height of the pack as well as organized items
{
    height: 80,
    width: 40,
    items: [{
        height: 10,
        width: 10,
        meta: 'small',
        x: 0,
        y: 0
    }, {
        height: 20,
        width: 10,
        meta: 'medium',
        x: 0,
        y: 10
    }, {
        height: 50,
        width: 40,
        meta: 'large',
        x: 0,
        y: 30
    }]
}
```

## Documentation
Layout is a constructor function

```js
/**
 * Layout adds items in an algorithmic fashion
 * @constructor
 * @param {String|Object} [algorithm="top-down"] Name of algorithm or custom algorithm to use
 *   Available algorithms are listed in the Algorithms section
 * @param {Mixed} [options] Options to provide for the algorithm
 */
```

Items can be added via `addItem` which are required to have a `height` and `width`. Any additional info should be stored inside of `meta`.

```js
/**
 * @param {Object} item Item to store -- this currently is mutated in-memory
 * @param {Number} item.width Width of the item
 * @param {Number} item.height Height of the item
 * @param {Mixed} [item.meta] Any meta data you would like to store related to the item
 */
```

`export` is how you take your items and organize them.

```js
/**
 * @returns {Object} retObj
 * @returns {Number} retObj.height Height of the processed layout
 * @returns {Number} retObj.width Width of the processed layout
 * @returns {Mixed[]} retObj.items Organized items
 */
```

### Algorithms
Currently `layout` supports 5 different layout types which are listed below.

#### `top-down`
The `top-down` algorithm places items vertically.

![top-down image][top-down-img]

By default, it sorts from smallest (top) to largest (bottom). However, this can be disabled via `sort: false`.

**Options:**

- sort `Boolean` Flag to enable/disable sorting from smallest (top) to largest (bottom)
    - By default, this is enabled (`true`)

#### `left-right`
The `left-right` algorithm places items horizontally.

![left-right image][left-right-img]

By default, it sorts from smallest (left) to largest (right). However, this can be disabled via `sort: false`.

**Options:**

- sort `Boolean` Flag to enable/disable sorting from smallest (left) to largest (right)
    - By default, this is enabled (`true`)

#### `diagonal`
The `diagonal` algorithm places items diagonally (top-left to bottom-right).

![diagonal image][diagonal-img]

By default, it sorts from smallest (top-left) to largest (bottom-right). However, this can be disabled via `sort: false`.

**Options:**

- sort `Boolean` Flag to enable/disable sorting from smallest (top-left) to largest (bottom-right)
    - By default, this is enabled (`true`)

#### `alt-diagonal`
The `alt-diagonal` algorithm places items diagonally (top-right to bottom-left).

![alt-diagonal image][alt-diagonal-img]

By default, it sorts from smallest (top-right) to largest (bottom-left). However, this can be disabled via `sort: false`.

**Options:**

- sort `Boolean` Flag to enable/disable sorting from smallest (top-right) to largest (bottom-left)
    - By default, this is enabled (`true`)

#### `binary-tree`
The `binary-tree` algorithm packs items via the [binary tree algorithm][].

This is an efficient way to pack items into the smallest container possible.

[binary tree algorithm]: http://codeincomplete.com/posts/2011/5/7/bin_packing/

![binary-tree image][binary-tree-img]

### Custom algorithms
You can add your own algorithm via `layout.addAlgorithm`
```js
/**
 * Method to add new algorithms via
 * @param {String} name Name of algorithm
 * @param {Object} algorithm Algorithm to bind under name
 * @param {Function} algorithm.sort Algorithm to sort object by
 * @param {Function} algorithm.placeItems Algorithm to place items by
 */
```

## Contributing
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint via `npm run lint` and test via `npm test`.

## Donating
Support this project and [others by twolfson][gratipay] via [gratipay][].

[![Support via Gratipay][gratipay-badge]][gratipay]

[gratipay-badge]: https://cdn.rawgit.com/gratipay/gratipay-badge/2.x.x/dist/gratipay.png
[gratipay]: https://www.gratipay.com/twolfson/

## License
Copyright (c) 2012-2014 Todd Wolfson
Licensed under the MIT license.

---
_Source: https://npm.io/package/layout · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._