fp-units
Version:
An FP-oriented library to easily convert CSS units.
206 lines (136 loc) • 6.7 kB
Markdown
# fp-units
An FP-oriented library to easily convert CSS units. Provides some convenient curried functions to convert any CSS units available in the spec.
[](https://travis-ci.org/anthonydugois/fp-units)
[](https://codecov.io/gh/anthonydugois/fp-units)
1. [Installation](#installation)
2. [Basic usage](#basic-usage)
3. [Supported units](#supported-units)
4. [API](#api)
## Installation
npm install --save fp-units
## Basic usage
### Absolute units
```js
import { converter } from 'fp-units'
converter({}, 'px', '100px 2cm 15mm 4q 4in 30pc 24pt')
// [[100, 75.59055, 56.69291, 3.77953, 384, 480, 32]]
converter({}, 'px', [30, '4px 8px', '2cm'])
// [[30], [4, 8], [75.59055]]
converter({}, 'px', 30)
// [[30]]
converter({}, 'px', 'calc(2 * calc(12px + 3px))')
// [[30]]
```
### Relative units
In order to be able to do conversions between relative units, **fp-units** needs to know some values to perform calculus. For example, to convert `px` into `%`, you have to provide a fixed size to let **fp-units** know on what constant coefficient it should base the converter.
In a browser environment, **fp-units** is able to guess the majority of the configuration object by itself: in most cases, you'll just have to provide the `node` property. For more advanced config, please see the [config object](#config-object) below.
```js
import { converter } from 'fp-units'
converter(
{ node: document.querySelector('#foobar') },
'px',
'2rem 4em 2rlh 4lh 50% 25vw 40vh 5vmin 10vmax',
)
// [[32, 96, 32, 104, 50, 480, 432, 54, 192]]
```
**Note**: since all the provided functions are automatically curried, you can create a custom `to` function based on your own configuration:
```js
import { converter } from 'fp-units'
const to = converter({ /* your config */ })
to('px', '5rem')
to('%', '30vw')
to('vmin', '50% 40px')
```
### Config object
All properties are optional.
```js
const config = {
// used to convert vw, vh, vmin, vmax
window: window,
// fallback
window: {
innerWidth: 0,
innerHeight: 0,
},
// used to convert rem, rlh
document: document,
// fallback
document: {
lineHeight: 16,
fontSize: 16,
},
// used to convert em, lh, %
node: document.querySelector('#foobar'),
// fallback
node: {
lineHeight: 16,
fontSize: 16,
width: 0, // must match `property` below
},
// specify the style property to look for in `node`
// used to convert %
property: 'width',
}
```
## Supported units
**fp-units** supports conversions of every units described in the [CSS spec](https://www.w3.org/TR/css3-values/), as long as the starting unit and the arrival unit have the same nature. For example, it is possible to convert `px` to `%`, but it is impossible to convert `deg` to `px`, because `deg` describes an angle while `px` describes a length.
### Length
`px` (_canonical_), `cm`, `mm`, `q`, `in`, `pt`, `pc`, `%`, `em`, `rem`, `ex`, `ch`, `ic`, `lh`, `rlh`, `vw`, `vh`, `vmin`, `vmax`, `vb`, `vi`
### Angle
`rad` (_canonical_), `deg`, `grad`, `turn`
### Time
`s` (_canonical_), `ms`
### Frequency
`hz` (_canonical_), `khz`
### Resolution
`dppx` (_canonical_), `dpi`, `dpcm`
## API
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
### convert
Naively converts a numeric value into the desired unit. This function is more granular than `converter`, but it does not handle automatic parsing, calc expressions and multiple conversions. This function is more useful when you need specialized converters.
The config object allows you to adjust some parameters used to perform relative units conversions (e.g. `rem` or `%`).
**Parameters**
- `config` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The config object.
- `unit` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The desired unit.
- `from` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The base unit.
- `value` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** The value to convert.
**Examples**
```javascript
import { convert } from 'fp-units'
convert({}, 'rem', 'px', 32)
// 2
convert({}, 'deg', 'rad', Math.PI)
// 180
// Note: you can take advantage of automatic currying to have your own conversion API!
const rad2deg = convert({}, 'deg', 'rad')
rad2deg(Math.PI)
// 180
rad2deg(Math.PI / 4)
// 45
```
Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)**
### converter
Smartly converts the provided values into the desired unit. You can convert numbers, strings and calc expressions.
Note: if the provided values don't have any unit, it will assume that they are expressed in the canonical unit corresponding to the nature of the desired unit (e.g. `px` if the desired unit is a length).
**Parameters**
- `config` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The config object.
- `unit` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The desired unit.
- `values` **([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) \| [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number))>)** The values and units to convert.
**Examples**
```javascript
import { converter } from 'fp-units'
const to = converter({
node: document.querySelector('#foobar'),
})
to('px', '30 2rem 4em 2rlh 4lh 50% 25vw 40vh 5vmin 10vmax')
// [[30, 32, 96, 32, 104, 50, 480, 432, 54, 192]]
to('px', [30, '2rem 4px', '4em'])
// [[30], [32, 4], [96]]
to('rem', 32)
// [[2]]
to('rem', 'calc(2 * calc(12px + 4px))')
// [[2]]
```
Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)>>**
## License
MIT