inline-style-expand-shorthand

Expanding shorthand properties in JavaScript style objects.

Installation

``sh
yarn add inline-style-expand-shorthand
`

Alternatively use npm i --save inline-style-expand-shorthand.

Why?

When using a library that generates Atomic CSS such as Fela or Styletron, one can run into an issue where mixed shorthand and longhand properties are applied in an unexpected way due to the rendering order of CSS classes.

This packages helps to prevent those issues by always expanding shorthand values so that no conflicts occur at all.

How?

As this library runs on the browser as well, it needs to be very small and performant. In order to achieve that, we renounced using complex parsing algorithms, but rather rely on a set of simple regular expressions.

This also comes with some downsides: We make a lot of consumptions about the CSS value. All in all, it must be a valid CSS value. Otherwise one might experience strange behaviour.

Supported Properties

- border
- borderTop
- borderRight
- borderBottom
- borderLeft
- borderWidth
- borderStyle
- borderColor
- borderRadius
- padding
- paddingInline
- paddingBlock
- margin
- marginInline
- marginBlock
- outline
- flex
- flexFlow
- textDecoration
- overflow
- gap
- placeContent
- placeItems
- placeSelf
- transition
- inset
- scroll-margin
- scroll-padding

> Need more? Feel free to create an issue with a proposal!

Usage

This package exports 3 methods, one to expand single properties and two to expand properties on full style objects.

$3

| Parameter  | Description  |
| ---------- | -------------------------------------------------------- |
| property | The property name (in camelCase) that should be expanded |
| value | The value that is going to be expanded |

`js
import { expandProperty } from 'inline-style-expand-shorthand'

const longhands = expandProperty('padding', '10px 15px 5px')

// longhands === output
const output = {
paddingTop: '10px',
paddingRight: '15px',
paddingBottom: '5px',
paddingLeft: '15px',
}
`

$3

This is just a convenient wrapper for objects that uses expandProperty under the hood.

| Parameter  | Description  |
| ---------- | ----------------------------------------------------------- |
| style | A (nested) style objects that contains shorthand properties |

`js
import { expand } from 'inline-style-expand-shorthand'

const style = {
padding: '10px 20px',
borderLeft: '1px solid black',
}

const expanded = expand(style)

// expanded === output
const output = {
paddingTop: '10px',
paddingRight: '20px',
paddingBottom: '10px',
paddingLeft: '20px',
borderLeftWidth: '1px',
borderLeftStyle: 'solid',
borderLeftColor: 'black',
}
`

$3

This one is similar to expand except that it also merges mixed longhand and shorthand properties.

> Warning: Beware that there are different border properties with the same specificity. In order to solve that deterministically, we had to choose a order. borderWidth, borderStyle and borderColor will always overwrite borderLeft, borderRight, borderTop and borderBottom.

| Parameter  | Description  |
| ---------- | ----------------------------------------------------------- |
| style | A (nested) style objects that contains shorthand properties |

`js
import { expandWithMerge } from 'inline-style-expand-shorthand'

const style = {
padding: '10px 20px',
paddingLeft: '15px',
}

const expanded = expandWithMerge(style)

// expanded === output
const output = {
paddingTop: '10px',
paddingRight: '20px',
paddingBottom: '10px',
// overwrites the expanded padding-left value due to it being more specific
paddingLeft: '15px',
}
``

License

inline-style-expand-shorthand is licensed under the MIT License.

Documentation is licensed under Creative Common License.

Created with ♥ by @robinweser.