132 lines
3.5 KiB
Markdown
132 lines
3.5 KiB
Markdown
# CSS Calc
|
|
|
|
[<img alt="npm version" src="https://img.shields.io/npm/v/@csstools/css-calc.svg" height="20">][npm-url]
|
|
[<img alt="Build Status" src="https://github.com/csstools/postcss-plugins/workflows/test/badge.svg" height="20">][cli-url]
|
|
[<img alt="Discord" src="https://shields.io/badge/Discord-5865F2?logo=discord&logoColor=white">][discord]
|
|
|
|
Implemented from : https://drafts.csswg.org/css-values-4/ on 2023-02-17
|
|
|
|
## Usage
|
|
|
|
Add [CSS calc] to your project:
|
|
|
|
```bash
|
|
npm install @csstools/css-calc @csstools/css-parser-algorithms @csstools/css-tokenizer --save-dev
|
|
```
|
|
|
|
### With string values :
|
|
|
|
```mjs
|
|
import { calc } from '@csstools/css-calc';
|
|
|
|
// '20'
|
|
console.log(calc('calc(10 * 2)'));
|
|
```
|
|
|
|
### With component values :
|
|
|
|
```mjs
|
|
import { stringify, tokenizer } from '@csstools/css-tokenizer';
|
|
import { parseCommaSeparatedListOfComponentValues } from '@csstools/css-parser-algorithms';
|
|
import { calcFromComponentValues } from '@csstools/css-calc';
|
|
|
|
const t = tokenizer({
|
|
css: 'calc(10 * 2)',
|
|
});
|
|
|
|
const tokens = [];
|
|
|
|
{
|
|
while (!t.endOfFile()) {
|
|
tokens.push(t.nextToken());
|
|
}
|
|
|
|
tokens.push(t.nextToken()); // EOF-token
|
|
}
|
|
|
|
const result = parseCommaSeparatedListOfComponentValues(tokens, {});
|
|
|
|
// filter or mutate the component values
|
|
|
|
const calcResult = calcFromComponentValues(result, { precision: 5, toCanonicalUnits: true });
|
|
|
|
// filter or mutate the component values even further
|
|
|
|
const calcResultStr = calcResult.map((componentValues) => {
|
|
return componentValues.map((x) => stringify(...x.tokens())).join('');
|
|
}).join(',');
|
|
|
|
// '20'
|
|
console.log(calcResultStr);
|
|
```
|
|
|
|
### Options
|
|
|
|
#### `precision` :
|
|
|
|
The default precision is fairly high.
|
|
It aims to be high enough to make rounding unnoticeable in the browser.
|
|
|
|
You can set it to a lower number to suit your needs.
|
|
|
|
```mjs
|
|
import { calc } from '@csstools/css-calc';
|
|
|
|
// '0.3'
|
|
console.log(calc('calc(1 / 3)', { precision: 1 }));
|
|
// '0.33'
|
|
console.log(calc('calc(1 / 3)', { precision: 2 }));
|
|
```
|
|
|
|
#### `globals` :
|
|
|
|
Pass global values as a map of key value pairs.
|
|
|
|
> Example : Relative color syntax (`lch(from pink calc(l / 2) c h)`) exposes color channel information as ident tokens.
|
|
> By passing globals for `l`, `c` and `h` it is possible to solve nested `calc()`'s.
|
|
|
|
```mjs
|
|
import { calc } from '@csstools/css-calc';
|
|
|
|
const globals = new Map([
|
|
['a', '10px'],
|
|
['b', '2rem'],
|
|
]);
|
|
|
|
// '20px'
|
|
console.log(calc('calc(a * 2)', { globals: globals }));
|
|
// '6rem'
|
|
console.log(calc('calc(b * 3)', { globals: globals }));
|
|
```
|
|
|
|
#### `toCanonicalUnits` :
|
|
|
|
By default this package will try to preserve units.
|
|
The heuristic to do this is very simplistic.
|
|
We take the first unit we encounter and try to convert other dimensions to that unit.
|
|
|
|
This better matches what users expect from a CSS dev tool.
|
|
|
|
If you want to have outputs that are closes to CSS serialized values you can pass `toCanonicalUnits: true`.
|
|
|
|
```mjs
|
|
import { calc } from '@csstools/css-calc';
|
|
|
|
// '20hz'
|
|
console.log(calc('calc(0.01khz + 10hz)', { toCanonicalUnits: true }));
|
|
|
|
// '20hz'
|
|
console.log(calc('calc(10hz + 0.01khz)', { toCanonicalUnits: true }));
|
|
|
|
// '0.02khz' !!!
|
|
console.log(calc('calc(0.01khz + 10hz)', { toCanonicalUnits: false }));
|
|
|
|
// '20hz'
|
|
console.log(calc('calc(10hz + 0.01khz)', { toCanonicalUnits: false }));
|
|
```
|
|
|
|
[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
|
|
[discord]: https://discord.gg/bUadyRwkJS
|
|
[npm-url]: https://www.npmjs.com/package/@csstools/css-calc
|
|
|
|
[CSS calc]: https://github.com/csstools/postcss-plugins/tree/main/packages/css-calc
|