inline-style-expand-shorthand

inline-style-expand-shorthand

Expanding shorthand properties in JavaScript style objects.

Installation

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.

expandProperty

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

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',
}

expand

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

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',
}

expandWithMerge

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

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.