0
# Global JSX Transformations
1

2
Transformations for emotion Global JSX components, converting styles attributes to optimized array format with source map integration.
3

4
## Capabilities
5

6
### Global JSX Component Transformation
7

8
Transforms emotion Global JSX components by optimizing the styles attribute format.
9

10
```typescript { .api }
11
/**
12
 * Transforms Global JSX component styles attributes
13
 * Input: <Global styles={cssValue} />
14
 * Output: <Global styles={[cssValue, "sourcemap"]} />
15
 */
16
```
17

18
**Transformation Examples:**
19

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

24
const globalStyles = css`
25
  body { margin: 0; padding: 0; }
26
  * { box-sizing: border-box; }
27
`;
28

29
function App() {
30
  return (
31
    <div>
32
      <Global styles={globalStyles} />
33
      <main>Content</main>
34
    </div>
35
  );
36
}
37

38
// Output (with sourceMap: true)
39
function App() {
40
  return (
41
    <div>
42
      <Global styles={[
43
        globalStyles,
44
        "/*# sourceMappingURL=data:application/json;base64,... */"
45
      ]} />
46
      <main>Content</main>
47
    </div>
48
  );
49
}
50
```
51

52
### Global Literal Styles Transformation
53

54
Transforms Global components with inline literal styles.
55

56
```typescript { .api }
57
/**
58
 * Transforms Global with literal CSS styles
59
 * Input: <Global styles="css-string" />
60
 * Output: <Global styles={["css-string", "sourcemap"]} />
61
 */
62
```
63

64
**Literal Styles Examples:**
65

66
```typescript
67
// Input with string literal
68
function ResetStyles() {
69
  return (
70
    <Global styles="body { margin: 0; } html { font-family: sans-serif; }" />
71
  );
72
}
73

74
// Output
75
function ResetStyles() {
76
  return (
77
    <Global styles={[
78
      "body { margin: 0; } html { font-family: sans-serif; }",
79
      "/*# sourceMappingURL=... */"
80
    ]} />
81
  );
82
}
83
```
84

85
### Global Expression Container Transformation
86

87
Transforms Global components with JSX expression container styles.
88

89
```typescript { .api }
90
/**
91
 * Transforms Global with JSX expression containers
92
 * Input: <Global styles={expression} />
93
 * Output: <Global styles={[expression, "sourcemap"]} />
94
 */
95
```
96

97
**Expression Container Examples:**
98

99
```typescript
100
// Input with expression container
101
import { Global } from "@emotion/react";
102

103
const themeColors = {
104
  primary: '#007bff',
105
  secondary: '#6c757d'
106
};
107

108
function ThemedApp() {
109
  return (
110
    <div>
111
      <Global styles={{
112
        body: {
113
          backgroundColor: themeColors.primary,
114
          color: 'white'
115
        }
116
      }} />
117
      <main>Content</main>
118
    </div>
119
  );
120
}
121

122
// Output
123
function ThemedApp() {
124
  return (
125
    <div>
126
      <Global styles={[
127
        {
128
          body: {
129
            backgroundColor: themeColors.primary,
130
            color: 'white'
131
          }
132
        },
133
        "/*# sourceMappingURL=... */"
134
      ]} />
135
      <main>Content</main>
136
    </div>
137
  );
138
}
139
```
140

141
### Global Array Styles Handling
142

143
Handles Global components that already have array-format styles.
144

145
```typescript { .api }
146
/**
147
 * Handles existing array-format styles by appending source map
148
 * Input: <Global styles={[style1, style2]} />
149
 * Output: <Global styles={[style1, style2, "sourcemap"]} />
150
 */
151
```
152

153
**Array Styles Examples:**
154

155
```typescript
156
// Input with existing array
157
import { Global, css } from "@emotion/react";
158

159
const resetStyles = css`* { margin: 0; padding: 0; }`;
160
const fontStyles = css`body { font-family: Arial, sans-serif; }`;
161

162
function App() {
163
  return (
164
    <Global styles={[resetStyles, fontStyles]} />
165
  );
166
}
167

168
// Output
169
function App() {
170
  return (
171
    <Global styles={[
172
      resetStyles, 
173
      fontStyles,
174
      "/*# sourceMappingURL=... */"
175
    ]} />
176
  );
177
}
178
```
179

180
### Namespace Global Transformation
181

182
Transforms Global components imported via namespace imports.
183

184
```typescript { .api }
185
/**
186
 * Transforms Global from namespace imports
187
 * Input: <emotion.Global styles={value} />
188
 * Output: <emotion.Global styles={[value, "sourcemap"]} />
189
 */
190
```
191

192
**Namespace Import Examples:**
193

194
```typescript
195
// Input with namespace import
196
import * as emotion from "@emotion/react";
197

198
function Layout() {
199
  return (
200
    <div>
201
      <emotion.Global styles={emotion.css`
202
        html, body { height: 100%; }
203
        #root { min-height: 100%; }
204
      `} />
205
      <header>Header</header>
206
    </div>
207
  );
208
}
209

210
// Output
211
function Layout() {
212
  return (
213
    <div>
214
      <emotion.Global styles={[
215
        emotion.css`
216
          html, body { height: 100%; }
217
          #root { min-height: 100%; }
218
        `,
219
        "/*# sourceMappingURL=... */"
220
      ]} />
221
      <header>Header</header>
222
    </div>
223
  );
224
}
225
```
226

227
### Global JSX Member Expression Transformation
228

229
Transforms Global components accessed via member expressions.
230

231
```typescript { .api }
232
/**
233
 * Transforms Global via JSX member expressions
234
 * Handles patterns like <namespace.Global styles={...} />
235
 */
236
```
237

238
**Member Expression Examples:**
239

240
```typescript
241
// Input with member expression
242
import * as Emotion from "@emotion/react";
243

244
const Layout = () => {
245
  return (
246
    <div>
247
      <Emotion.Global styles={Emotion.css`
248
        .app { padding: 20px; }
249
        .container { max-width: 1200px; margin: 0 auto; }
250
      `} />
251
      <div className="app">
252
        <div className="container">Content</div>
253
      </div>
254
    </div>
255
  );
256
};
257

258
// Output
259
const Layout = () => {
260
  return (
261
    <div>
262
      <Emotion.Global styles={[
263
        Emotion.css`
264
          .app { padding: 20px; }
265
          .container { max-width: 1200px; margin: 0 auto; }
266
        `,
267
        "/*# sourceMappingURL=... */"
268
      ]} />
269
      <div className="app">
270
        <div className="container">Content</div>
271
      </div>
272
    </div>
273
  );
274
};
275
```
276

277
### Global Source Map Generation
278

279
Source map generation for Global JSX component transformations.
280

281
```typescript { .api }
282
/**
283
 * Source maps for Global transformations map to JSX element positions
284
 * Enables debugging of global styles within React DevTools
285
 * Only generated when sourceMap option is enabled
286
 */
287
```
288

289
**Source Map Details:**
290

291
```typescript
292
// Input at line 45, column 8
293
<Global styles={globalCSS} />
294

295
// Generated source map data points to:
296
// - file: "src/App.tsx"  
297
// - line: 45
298
// - column: 8
299
// - element: JSX opening element position
300
```
301

302
### Global Transformation Conditions
303

304
The plugin only transforms Global components when specific conditions are met.
305

306
```typescript { .api }
307
/**
308
 * Transformation conditions for Global components:
309
 * 1. Global must be imported from @emotion/react
310
 * 2. Must have a styles attribute/prop
311
 * 3. sourceMap option must be enabled for source map injection
312
 * 4. Plugin must recognize the import pattern
313
 */
314
```
315

316
**Conditional Examples:**
317

318
```typescript
319
// ✓ Transformed - Named import from @emotion/react
320
import { Global } from "@emotion/react";
321
<Global styles={css`body { margin: 0; }`} />
322

323
// ✓ Transformed - Namespace import from @emotion/react  
324
import * as emotion from "@emotion/react";
325
<emotion.Global styles={emotion.css`padding: 0;`} />
326

327
// ✗ Not transformed - Wrong import source
328
import { Global } from "some-other-library";
329
<Global styles={css`margin: 0;`} />
330

331
// ✗ Not transformed - No styles attribute
332
import { Global } from "@emotion/react";
333
<Global className="global-component" />
334

335
// ✗ Not transformed - sourceMap disabled
336
// (with plugin config: { sourceMap: false })
337
<Global styles={css`padding: 16px;`} />
338
```
339

340
### Supported Global Import Patterns
341

342
The plugin recognizes these import patterns for Global transformation:
343

344
```typescript { .api }
345
/**
346
 * Supported Global import patterns:
347
 * - Named imports: import { Global } from "@emotion/react"
348
 * - Namespace imports: import * as emotion from "@emotion/react"
349
 * - Mixed imports: import { Global, css } from "@emotion/react"
350
 */
351
```
352

353
**Import Pattern Examples:**
354

355
```typescript
356
// Named import
357
import { Global } from "@emotion/react";
358
<Global styles={someStyles} />; // ✓ Transformed
359

360
// Namespace import
361
import * as emotion from "@emotion/react";  
362
<emotion.Global styles={someStyles} />; // ✓ Transformed
363

364
// Mixed import
365
import { Global, css } from "@emotion/react";
366
<Global styles={css`margin: 0;`} />; // ✓ Transformed
367
```
368

369
### Error Handling in Global Transformations
370

371
The plugin handles various edge cases gracefully during Global transformations.
372

373
```typescript { .api }
374
/**
375
 * Error handling scenarios:
376
 * - Missing styles attribute: No transformation
377
 * - Invalid JSX structure: Original structure preserved
378
 * - Source map generation failure: Styles transformed without source map
379
 * - Unrecognized import patterns: No transformation applied
380
 */
381
```