0
# CSS Function Transformations
1

2
Transformations for emotion `css` function calls and template literals, including automatic labeling, source map generation, and CSS minification.
3

4
## Capabilities
5

6
### CSS Template Literal Transformation
7

8
Transforms emotion CSS template literals into optimized function calls.
9

10
```typescript { .api }
11
/**
12
 * Transforms template literal CSS into function calls
13
 * Input: css`styles...`
14
 * Output: css("minified-styles", "label:context", "sourcemap")
15
 */
16
```
17

18
**Transformation Examples:**
19

20
```typescript
21
// Input
22
import { css } from "@emotion/react";
23

24
const buttonStyles = css`
25
  color: blue;
26
  font-size: 16px;
27
  /* This is a comment */
28
  padding: 8px;
29
`;
30

31
// Output (with autoLabel: "always", sourceMap: true)
32
const buttonStyles = css(
33
  "color:blue;font-size:16px;padding:8px;",
34
  "label:buttonStyles;",
35
  "/*# sourceMappingURL=data:application/json;base64,... */"
36
);
37
```
38

39
### CSS Object Transformation
40

41
Transforms emotion CSS object calls with automatic enhancements.
42

43
```typescript { .api }
44
/**
45
 * Transforms CSS object calls with labels and source maps
46
 * Input: css({ styles })
47
 * Output: css({ styles }, "label:context", "sourcemap")
48
 */
49
```
50

51
**Transformation Examples:**
52

53
```typescript
54
// Input
55
import { css } from "@emotion/react";
56

57
const flexStyles = css({
58
  display: 'flex',
59
  alignItems: 'center',
60
  justifyContent: 'space-between'
61
});
62

63
// Output (with autoLabel: "dev-only" in development)
64
const flexStyles = css(
65
  {
66
    display: 'flex',
67
    alignItems: 'center', 
68
    justifyContent: 'space-between'
69
  },
70
  "label:flexStyles;"
71
);
72
```
73

74
### Namespace CSS Transformation
75

76
Transforms CSS calls from namespace imports.
77

78
```typescript { .api }
79
/**
80
 * Transforms CSS from namespace imports
81
 * Input: emotion.css`styles...`
82
 * Output: emotion.css("minified-styles", "label:context", "sourcemap")
83
 */
84
```
85

86
**Transformation Examples:**
87

88
```typescript
89
// Input
90
import * as emotion from "@emotion/react";
91

92
const cardStyles = emotion.css`
93
  border: 1px solid #ccc;
94
  border-radius: 4px;
95
`;
96

97
// Output
98
const cardStyles = emotion.css(
99
  "border:1px solid #ccc;border-radius:4px;",
100
  "label:cardStyles;"
101
);
102
```
103

104
### CSS Minification
105

106
The plugin automatically minifies CSS strings by removing comments and unnecessary whitespace.
107

108
```typescript { .api }
109
/**
110
 * CSS minification process:
111
 * 1. Remove single-line comments (// comments)
112
 * 2. Remove multi-line comments (/* comments */)
113
 * 3. Trim whitespace around colons, semicolons, braces
114
 * 4. Preserve URL content with double slashes
115
 */
116
```
117

118
**Minification Examples:**
119

120
```typescript
121
// Input CSS
122
const styles = css`
123
  /* Main styles */
124
  color: red;     // Primary color
125
  font-size: 16px;
126
  
127
  // Spacing
128
  margin: 0 auto;
129
  background-image: url('//domain.com/image.png');
130
`;
131

132
// Minified output
133
const styles = css(
134
  "color:red;font-size:16px;margin:0 auto;background-image:url('//domain.com/image.png');"
135
);
136
```
137

138
### Label Generation for CSS
139

140
Automatic label generation for CSS functions based on context and configuration.
141

142
```typescript { .api }
143
/**
144
 * Label generation for CSS functions
145
 * Uses variable names, function contexts, and file information
146
 * Sanitizes labels by replacing invalid characters with hyphens
147
 */
148
```
149

150
**Label Context Examples:**
151

152
```typescript
153
// Variable declaration context
154
const primaryButton = css`color: blue;`;
155
// Label: "primaryButton"
156

157
// Object property context  
158
const styles = {
159
  header: css`font-size: 24px;`,
160
  footer: css`font-size: 12px;`
161
};
162
// Labels: "header", "footer"
163

164
// Function parameter context
165
function createButton(type) {
166
  const buttonStyle = css`padding: 8px;`;
167
  // Label: "buttonStyle"
168
}
169

170
// Class method context
171
class Component {
172
  getStyles() {
173
    const methodStyles = css`margin: 16px;`;
174
    // Label: "methodStyles"
175
  }
176
}
177
```
178

179
### Source Map Generation for CSS
180

181
Inline source map generation for debugging transformed CSS.
182

183
```typescript { .api }
184
/**
185
 * Source map generation creates base64-encoded inline maps
186
 * Maps transformed CSS back to original template literal positions
187
 * Only generated when sourceMap option is enabled
188
 */
189
```
190

191
**Source Map Example:**
192

193
```typescript
194
// Input at line 15, column 20
195
const styles = css`color: red;`;
196

197
// Output with source map
198
const styles = css(
199
  "color:red;",
200
  "/*# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uI... */"
201
);
202

203
// Decoded source map points back to:
204
// - file: "src/component.tsx"
205
// - line: 15
206
// - column: 20
207
```
208

209
### Interpolation Handling
210

211
Template literal interpolation is preserved in transformations.
212

213
```typescript { .api }
214
/**
215
 * Template literal interpolations are preserved as function arguments
216
 * Each interpolated expression becomes a separate argument
217
 */
218
```
219

220
**Interpolation Examples:**
221

222
```typescript
223
// Input with interpolation
224
const color = 'blue';
225
const size = 16;
226

227
const styles = css`
228
  color: ${color};
229
  font-size: ${size}px;
230
  margin: ${size / 2}px;
231
`;
232

233
// Output
234
const styles = css(
235
  "color:",
236
  color,
237
  ";font-size:",
238
  size,
239
  "px;margin:",
240
  size / 2,
241
  "px;"
242
);
243
```
244

245
### Supported CSS Import Patterns
246

247
The plugin recognizes these import patterns for CSS transformation:
248

249
```typescript { .api }
250
/**
251
 * Supported import patterns:
252
 * - Named imports: import { css } from "@emotion/react"
253
 * - Default imports: import css from "@emotion/css" 
254
 * - Namespace imports: import * as emotion from "@emotion/react"
255
 * - CommonJS: const { css } = require("@emotion/react")
256
 */
257
```
258

259
**Import Pattern Examples:**
260

261
```typescript
262
// Named import
263
import { css } from "@emotion/react";
264
const styles = css`color: red;`; // ✓ Transformed
265

266
// Default import  
267
import css from "@emotion/css";
268
const styles = css`color: blue;`; // ✓ Transformed
269

270
// Namespace import
271
import * as emotion from "@emotion/react";
272
const styles = emotion.css`color: green;`; // ✓ Transformed
273

274
// CommonJS
275
const { css } = require("@emotion/react");
276
const styles = css`color: yellow;`; // ✓ Transformed
277
```