css-shorthand-expanders

Type-safe functions to expand CSS shorthands into their longhand sub-properties.

Motivation

CSS rules can be represented as plain JavaScript objects. While every property has a type definition, longhands offer autocompletion superior to shorthands.

Usually, sub-properties of a shorthand may be specified in any order. This imposes an overhead on developers and type systems alike. Consequently, shorthands without a fixed order syntax should be avoided.

For shorthands with a reasonable value order, typed methods with positional arguments can be defined. This project aims to provide those in the form of self-contained functions.

The main goal is to support atomic CSS-in-JS libraries which can't handle shorthands.

Usage

Install the library with a package manager, e.g. npm:

npm install css-shorthand-expanders

After that, import transformation functions on demand:

import { padding } from "css-shorthand-expanders";

const longhands = padding("8px", "16px");
console.assert(longhands.paddingTop === "8px");
console.assert(longhands.paddingRight === "16px");
console.assert(longhands.paddingBottom === longhands.paddingTop);
console.assert(longhands.paddingLeft === longhands.paddingRight);

By convention, property names are camelCased to be consistent with the CSSOM style property. Unused functions are tree-shaken away, saving on your bundle sizes.

Type checking

Parameter suggestions and accurate return types can be enabled with a .d.ts file:

/* declarations.d.ts */

// Make sure to install the optional peer dependency below
import type { StandardLonghandProperties } from "csstype";

declare module "css-shorthand-expanders" {
  // You may also use `StandardLonghandPropertiesFallback` and any type params
  interface CSSProperties extends StandardLonghandProperties {}
}

Reference

Functions available are listed below in alphabetical order. Please refer to the bundled type definitions for their signatures and overloads.

• animation
• border
• borderBottom
• borderColor
• borderImage
• borderLeft
• borderRadius
• borderRight
• borderStyle
• borderTop
• borderWidth
• columnRule
• columns
• flex
• flexFlow
• gap
• gridArea
• gridColumn
• gridRow
• inset
• lineClamp
• listStyle
• margin
• outline
• overflow
• padding
• placeContent
• placeItems
• placeSelf
• textDecoration
• textEmphasis
• transition

More functions are under construction. Follow along for updates or contribute to the project!

Philosophy

The project adheres to the behavior of shorthands as specified by CSS Cascading and Inheritance:

Some properties are shorthand properties, meaning that they allow authors to specify the values of several properties with a single property. A shorthand property sets all of its longhand sub-properties, exactly as if expanded in place.

When values are omitted from a shorthand form, unless otherwise defined, each “missing” sub-property is assigned its initial value.

Parameters of expanders are in a fallback-oriented order to embrace progressive enhancement. Defaults are mostly identical to the initial values of sub-properties, except for:

• animation – Iteration count defaults to "infinite" (instead of 1)
• border* – Style defaults to "solid" (instead of "none")
• columnRule – Style defaults to "solid" (instead of "none")
• outline – Style defaults to "solid" (instead of "none"), and color defaults to "currentcolor" (instead of ["currentcolor", "invert"])