0
# Styled Component Transformations
1

2
Transformations for emotion styled component calls, including target class generation, automatic labeling, and template literal optimization.
3

4
## Capabilities
5

6
### Styled Template Literal Transformation
7

8
Transforms styled component template literals into optimized function calls with target classes.
9

10
```typescript { .api }
11
/**
12
 * Transforms styled template literals
13
 * Input: styled.div`styles...`
14
 * Output: styled("div", { target: "e1abc123", label: "context" })("minified-styles", "sourcemap")
15
 */
16
```
17

18
**Transformation Examples:**
19

20
```typescript
21
// Input
22
import styled from "@emotion/styled";
23

24
const Button = styled.button`
25
  background: blue;
26
  color: white;
27
  padding: 8px 16px;
28
`;
29

30
// Output (with autoLabel: "always")
31
const Button = styled("button", { 
32
  target: "e1a2b3c4", 
33
  label: "Button" 
34
})(
35
  "background:blue;color:white;padding:8px 16px;",
36
  "/*# sourceMappingURL=... */"
37
);
38
```
39

40
### Styled Function Call Transformation
41

42
Transforms styled function calls with element selectors.
43

44
```typescript { .api }
45
/**
46
 * Transforms styled function calls
47
 * Input: styled('div')`styles...`
48
 * Output: styled("div", { target: "e1abc123", label: "context" })("minified-styles")
49
 */
50
```
51

52
**Transformation Examples:**
53

54
```typescript
55
// Input
56
import styled from "@emotion/styled";
57

58
const Container = styled('div')`
59
  display: flex;
60
  flex-direction: column;
61
`;
62

63
// Output
64
const Container = styled("div", {
65
  target: "e5f6g7h8",
66
  label: "Container"
67
})(
68
  "display:flex;flex-direction:column;"
69
);
70
```
71

72
### Styled Object Syntax Transformation
73

74
Transforms styled components with object syntax.
75

76
```typescript { .api }
77
/**
78
 * Transforms styled components with object styles
79
 * Input: styled('div')({ styles })
80
 * Output: styled("div", { target: "e1abc123", label: "context" })({ styles }, "sourcemap")
81
 */
82
```
83

84
**Transformation Examples:**
85

86
```typescript
87
// Input
88
import styled from "@emotion/styled";
89

90
const Card = styled('div')({
91
  border: '1px solid #ccc',
92
  borderRadius: '4px',
93
  padding: '16px'
94
});
95

96
// Output
97
const Card = styled("div", {
98
  target: "e9a8b7c6", 
99
  label: "Card"
100
})({
101
  border: '1px solid #ccc',
102
  borderRadius: '4px', 
103
  padding: '16px'
104
});
105
```
106

107
### Target Class Generation
108

109
Generates stable, unique target class names for styled components.
110

111
```typescript { .api }
112
/**
113
 * Target class generation creates unique identifiers
114
 * Format: "e" + base36(fileHash) + incrementalCounter
115
 * Provides stable class names for CSS debugging and testing
116
 */
117
```
118

119
**Target Class Examples:**
120

121
```typescript
122
// File: src/components/Button.tsx (hash: 123456)
123
const PrimaryButton = styled.button`color: blue;`;
124
// Target: "e3g3jy0"
125

126
const SecondaryButton = styled.button`color: gray;`;  
127
// Target: "e3g3jy1"
128

129
// File: src/components/Card.tsx (hash: 789012)
130
const CardWrapper = styled.div`padding: 16px;`;
131
// Target: "e5s5lm0"
132
```
133

134
### Styled Label Generation
135

136
Automatic label generation for styled components based on variable names and context.
137

138
```typescript { .api }
139
/**
140
 * Label generation for styled components
141
 * Uses variable names, component names, and class contexts
142
 * Sanitizes labels by replacing invalid CSS characters
143
 */
144
```
145

146
**Label Context Examples:**
147

148
```typescript
149
// Variable assignment context
150
const HeaderComponent = styled.h1`font-size: 24px;`;
151
// Label: "HeaderComponent"
152

153
// Object property context
154
const components = {
155
  sidebar: styled.aside`width: 200px;`,
156
  content: styled.main`flex: 1;`
157
};
158
// Labels: "sidebar", "content"
159

160
// Class property context
161
class Layout {
162
  static Container = styled.div`max-width: 1200px;`;
163
  // Label: "Container"
164
}
165

166
// Function context
167
function createStyledButton() {
168
  const StyledButton = styled.button`padding: 8px;`;
169
  // Label: "StyledButton"
170
  return StyledButton;
171
}
172
```
173

174
### Complex Styled Transformations
175

176
Handles complex styled component patterns including conditional styles and composition.
177

178
```typescript { .api }
179
/**
180
 * Complex styled transformations preserve logic and interpolations
181
 * Template literal interpolations become function call arguments
182
 * Conditional styling and props are maintained
183
 */
184
```
185

186
**Complex Examples:**
187

188
```typescript
189
// Input with props and interpolation
190
const Button = styled.button`
191
  background: ${props => props.primary ? 'blue' : 'gray'};
192
  padding: ${({ size }) => size === 'large' ? '12px 24px' : '6px 12px'};
193
  opacity: 0.8;
194
`;
195

196
// Output
197
const Button = styled("button", {
198
  target: "e1a2b3c4",
199
  label: "Button"
200
})(
201
  "background:",
202
  props => props.primary ? 'blue' : 'gray',
203
  ";padding:",
204
  ({ size }) => size === 'large' ? '12px 24px' : '6px 12px',
205
  ";opacity:0.8;"
206
);
207

208
// Input with composition
209
const BaseButton = styled.button`padding: 8px;`;
210
const RedButton = styled(BaseButton)`color: red;`;
211

212
// Output  
213
const BaseButton = styled("button", {
214
  target: "e5f6g7h8",
215
  label: "BaseButton"
216
})("padding:8px;");
217

218
const RedButton = styled(BaseButton, {
219
  target: "e9a8b7c6",
220
  label: "RedButton"
221
})("color:red;");
222
```
223

224
### Styled Component Source Maps
225

226
Source map generation for styled component template literals.
227

228
```typescript { .api }
229
/**
230
 * Source maps for styled components map back to template literal positions
231
 * Enables debugging of transformed CSS within styled components
232
 * Generated only when sourceMap option is enabled
233
 */
234
```
235

236
**Source Map Example:**
237

238
```typescript
239
// Input at line 25, column 30
240
const Header = styled.h1`
241
  font-size: 32px;
242
  color: #333;
243
`;
244

245
// Output with source map
246
const Header = styled("h1", {
247
  target: "e1b2c3d4",
248
  label: "Header"
249
})(
250
  "font-size:32px;color:#333;",
251
  "/*# sourceMappingURL=data:application/json;base64,... */"
252
);
253
```
254

255
### Supported Styled Import Patterns
256

257
The plugin recognizes these import patterns for styled transformation:
258

259
```typescript { .api }
260
/**
261
 * Supported styled import patterns:
262
 * - Default imports: import styled from "@emotion/styled"
263
 * - Named imports with alias: import { default as styled } from "@emotion/styled"  
264
 * - CommonJS: const styled = require("@emotion/styled")
265
 */
266
```
267

268
**Import Pattern Examples:**
269

270
```typescript
271
// Default import
272
import styled from "@emotion/styled";
273
const Button = styled.button`color: blue;`; // ✓ Transformed
274

275
// Named import with alias
276
import { default as styled } from "@emotion/styled";
277
const Card = styled.div`padding: 16px;`; // ✓ Transformed
278

279
// CommonJS
280
const styled = require("@emotion/styled");
281
const Header = styled.h1`font-size: 24px;`; // ✓ Transformed
282
```
283

284
### Styled Component Element Types
285

286
The plugin supports all HTML element types and custom components.
287

288
```typescript { .api }
289
/**
290
 * Supported element patterns:
291
 * - HTML elements: styled.div, styled.button, styled.input, etc.
292
 * - Function calls: styled('div'), styled('button'), etc.  
293
 * - Custom components: styled(MyComponent)
294
 */
295
```
296

297
**Element Type Examples:**
298

299
```typescript
300
// HTML elements
301
const Div = styled.div`display: block;`;
302
const Button = styled.button`cursor: pointer;`;
303
const Input = styled.input`border: 1px solid #ccc;`;
304

305
// Function call syntax
306
const Section = styled('section')`margin: 16px;`;
307
const Article = styled('article')`padding: 24px;`;
308

309
// Custom component styling
310
const MyComponent = (props) => <div {...props} />;
311
const StyledMyComponent = styled(MyComponent)`
312
  background: white;
313
  border-radius: 8px;
314
`;
315
```
316

317
### Error Handling in Styled Transformations
318

319
The plugin gracefully handles various edge cases in styled component usage.
320

321
```typescript { .api }
322
/**
323
 * Error handling scenarios:
324
 * - Invalid element types: Skipped transformation
325
 * - Missing imports: No transformation applied
326
 * - Malformed template literals: Original structure preserved
327
 * - Complex interpolations: Maintained as-is in output
328
 */
329
```