0
# postcss-ordered-values
1

2
postcss-ordered-values is a PostCSS plugin that ensures CSS property values are consistently ordered. It normalizes properties that accept values in arbitrary order (such as `border`, `animation`, `transition`, etc.) to make it easier for other CSS optimization tools to identify duplicate declarations and improve compression.
3

4
## Package Information
5

6
- **Package Name**: postcss-ordered-values
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install postcss-ordered-values`
10

11
## Core Imports
12

13
```javascript
14
const orderedValues = require('postcss-ordered-values');
15
```
16

17
For TypeScript:
18

19
```typescript
20
import orderedValues = require('postcss-ordered-values');
21
// or
22
const orderedValues = require('postcss-ordered-values');
23
```
24

25
## Basic Usage
26

27
```javascript
28
const postcss = require('postcss');
29
const orderedValues = require('postcss-ordered-values');
30

31
// Process CSS with the plugin
32
const result = postcss([orderedValues()])
33
  .process(css, { from: undefined });
34

35
console.log(result.css);
36
```
37

38
**Input CSS:**
39
```css
40
h1 {
41
  border: solid 1px red;
42
  border: red solid .5em;
43
  border: rgba(0, 30, 105, 0.8) solid 1px;
44
  border: 1px solid red;
45
}
46
```
47

48
**Output CSS:**
49
```css
50
h1 {
51
  border: 1px solid red;
52
  border: .5em solid red;
53
  border: 1px solid rgba(0, 30, 105, 0.8);
54
  border: 1px solid red;
55
}
56
```
57

58
**Additional Examples:**
59

60
```javascript
61
// Animation property normalization
62
const css1 = 'div { animation: bounce infinite 2s ease-in-out; }';
63
// Result: div { animation: bounce 2s ease-in-out infinite; }
64

65
// Box shadow with inset
66
const css2 = 'div { box-shadow: red 10px 10px inset; }';
67
// Result: div { box-shadow: inset 10px 10px red; }
68

69
// Flex flow ordering
70
const css3 = 'div { flex-flow: wrap column; }';
71
// Result: div { flex-flow: column wrap; }
72

73
// Grid auto flow
74
const css4 = 'div { grid-auto-flow: dense row; }';
75
// Result: div { grid-auto-flow: row dense; }
76
```
77

78
## Architecture
79

80
The plugin operates through several key components:
81

82
- **Plugin Creator**: Main export function that returns a PostCSS plugin
83
- **Rule Processors**: Specialized functions for different CSS property types
84
- **Value Parser Integration**: Uses postcss-value-parser for parsing CSS values
85
- **Caching System**: Internal caching to avoid reprocessing identical values
86
- **Vendor Prefix Handling**: Normalizes vendor-prefixed properties
87

88
## Capabilities
89

90
### Main Plugin Function
91

92
Creates a PostCSS plugin that processes CSS declarations to normalize property value order.
93

94
```javascript { .api }
95
/**
96
 * Creates a PostCSS plugin for ordering CSS property values
97
 * @returns {Plugin} PostCSS plugin instance
98
 */
99
function pluginCreator(): Plugin;
100
```
101

102
The plugin processes CSS declarations during the `OnceExit` phase, after all other transformations are complete. It maintains a cache of processed values to improve performance on repeated values.
103

104
### Supported CSS Properties
105

106
The plugin handles the following CSS properties and their vendor-prefixed variants:
107

108
#### Border Properties
109
- `border`, `border-top`, `border-right`, `border-bottom`, `border-left`
110
- `border-block`, `border-inline`, `border-block-start`, `border-block-end`
111
- `border-inline-start`, `border-inline-end`
112
- `outline`
113
- `column-rule`
114

115
**Normalization Order**: `<width> <style> <color>`
116

117
#### Animation Properties
118
- `animation`, `-webkit-animation`
119

120
**Normalization Order**: `<name> <duration> <timing-function> <delay> <iteration-count> <direction> <fill-mode> <play-state>`
121

122
#### Box Shadow
123
- `box-shadow`
124

125
**Normalization Order**: `<inset> <length-values> <color>`
126

127
#### Flex Properties
128
- `flex-flow`
129

130
**Normalization Order**: `<flex-direction> <flex-wrap>`
131

132
#### Grid Properties
133
- `grid-auto-flow`
134
- `grid-column-gap`, `grid-row-gap`
135
- `grid-column`, `grid-row`
136
- `grid-column-start`, `grid-column-end`
137
- `grid-row-start`, `grid-row-end`
138

139
**Grid Auto Flow Normalization Order**: `<row/column> <dense>`
140

141
**Grid Gap Normalization**: Normalizes `normal` keyword to front position when present
142

143
#### List Style
144
- `list-style`
145

146
**Normalization Order**: `<type> <position> <image>`
147

148
#### Transition Properties
149
- `transition`, `-webkit-transition`
150

151
**Normalization Order**: `<property> <duration> <timing-function> <delay>`
152

153
#### Column Properties
154
- `columns`
155

156
**Normalization Order**: `<width> <count>` (only transforms valid two-value declarations)
157

158
### Processing Behavior
159

160
The plugin includes intelligent processing controls:
161

162
- **CSS Variable Support**: Aborts processing when CSS variables (`var()`, `env()`, `constant()`) are detected
163
- **Comment Preservation**: Skips processing when comments are present in values
164
- **Math Function Handling**: Recognizes and properly processes CSS math functions (`calc()`, `clamp()`, `max()`, `min()`) - may abort processing in complex contexts to avoid incorrect transformations
165
- **Vendor Prefix Normalization**: Strips vendor prefixes for internal processing while preserving them in output
166
- **Minimal Value Skip**: Only processes declarations with 2 or more value nodes
167

168
### Error Handling
169

170
The plugin gracefully handles various edge cases:
171

172
- Invalid or malformed CSS values are left unchanged
173
- CSS Loader imports (`___CSS_LOADER_IMPORT___`) abort processing
174
- Complex math functions in certain contexts may abort processing to avoid incorrect transformations
175

176
## Plugin Properties
177

178
```javascript { .api }
179
// Plugin identifier for PostCSS
180
pluginCreator.postcss = true;
181
```
182

183
## Types
184

185
For TypeScript users, the plugin exports match the actual type definitions:
186

187
```typescript { .api }
188
/**
189
 * Main plugin creator function exported via CommonJS
190
 */
191
declare function pluginCreator(): import("postcss").Plugin;
192

193
declare namespace pluginCreator {
194
  let postcss: true;
195
}
196

197
export = pluginCreator;
198
```
199

200
## Dependencies
201

202
- **postcss-value-parser**: Parses CSS property values into node trees
203
- **cssnano-utils**: Provides utility functions for CSS processing
204

205
## Peer Dependencies
206

207
- **postcss**: PostCSS framework (^8.4.32)