0
# Runtime API
1

2
Low-level runtime functions for DOM manipulation, style injection, and element management.
3

4
## Capabilities
5

6
### Style Injection Functions
7

8
Core functions that handle the injection of CSS content into the DOM via different strategies.
9

10
#### injectStylesIntoStyleTag
11

12
Main style injection manager for `<style>` elements with full feature support.
13

14
```javascript { .api }
15
/**
16
 * Injects CSS modules into <style> elements
17
 * @param list - Array of CSS modules to inject
18
 * @param options - Runtime configuration options
19
 * @returns Update function for modifying injected styles
20
 */
21
function injectStylesIntoStyleTag(
22
  list: CSSModule[], 
23
  options: RuntimeOptions
24
): UpdateFunction;
25

26
type UpdateFunction = (newList?: CSSModule[] | null) => void;
27
```
28

29
#### injectStylesIntoLinkTag
30

31
Link tag injection manager for `<link rel="stylesheet">` elements.
32

33
```javascript { .api }
34
/**
35
 * Injects CSS via <link> elements
36
 * @param url - CSS file URL to load
37
 * @param options - Runtime configuration options  
38
 * @returns Update function for changing URL or removing link
39
 */
40
function injectStylesIntoLinkTag(
41
  url: string,
42
  options: RuntimeOptions
43
): UpdateFunction;
44

45
type UpdateFunction = (newUrl?: string | null) => void;
46
```
47

48
### DOM API Functions
49

50
Low-level DOM manipulation functions for creating and managing style elements.
51

52
#### styleDomAPI
53

54
DOM API for individual style elements with full CSS feature support including source maps, media queries, CSS cascade layers, and @supports rules.
55

56
```javascript { .api }
57
/**
58
 * Creates DOM API for individual style elements
59
 * @param options - Runtime options including insertion and attribute functions
60
 * @returns Object with update and remove methods
61
 */
62
function styleDomAPI(options: RuntimeOptions): DOMAPIResult;
63

64
interface DOMAPIResult {
65
  /**
66
   * Updates the style element with new CSS content
67
   * @param obj - CSS module with content, media, supports, layer
68
   */
69
  update(obj: CSSModule): void;
70
  
71
  /**
72
   * Removes the style element from DOM
73
   */
74
  remove(): void;
75
}
76
```
77

78
#### singletonStyleDomAPI
79

80
DOM API for singleton style elements that share a single `<style>` tag across multiple CSS modules.
81

82
```javascript { .api }
83
/**
84
 * Creates DOM API for singleton style management
85
 * @param options - Runtime options for shared style element
86
 * @returns Object with update and remove methods
87
 */
88
function singletonStyleDomAPI(options: RuntimeOptions): DOMAPIResult;
89

90
// Same interface as styleDomAPI but manages shared element internally
91
interface DOMAPIResult {
92
  update(obj: CSSModule): void;
93
  remove(): void;
94
}
95
```
96

97
### Element Creation and Management
98

99
Functions for creating and configuring DOM elements used by the style injection system.
100

101
#### insertStyleElement
102

103
Factory function for creating `<style>` elements with proper configuration.
104

105
```javascript { .api }
106
/**
107
 * Creates a new style element with configured attributes and insertion
108
 * @param options - Configuration for element creation
109
 * @returns Created HTML style element
110
 */
111
function insertStyleElement(options: StyleElementOptions): HTMLStyleElement;
112

113
interface StyleElementOptions {
114
  setAttributes: (element: HTMLStyleElement, attributes?: object) => void;
115
  attributes?: Record<string, string>;
116
  insert: (element: HTMLStyleElement, options?: object) => void;
117
  options?: object;
118
}
119
```
120

121
#### insertBySelector
122

123
Inserts style elements into the DOM using CSS selectors for target location with iframe support.
124

125
```javascript { .api }
126
/**
127
 * Inserts element at location specified by CSS selector
128
 * Handles iframe content document access with memoization
129
 * @param insert - CSS selector string for target location
130
 * @param style - Style element to insert
131
 */
132
function insertBySelector(insert: string, style: HTMLElement): void;
133
```
134

135
### Attribute Management
136

137
Functions for setting HTML attributes on style and link elements.
138

139
#### setAttributesWithAttributes
140

141
Sets custom attributes on elements with automatic webpack nonce handling.
142

143
```javascript { .api }
144
/**
145
 * Sets custom attributes with automatic webpack nonce
146
 * @param styleElement - Target HTML element
147
 * @param attributes - Object containing attribute key-value pairs
148
 */
149
function setAttributesWithAttributes(
150
  styleElement: HTMLElement, 
151
  attributes: Record<string, string>
152
): void;
153
```
154

155
#### setAttributesWithAttributesAndNonce
156

157
Sets custom attributes on elements without automatic nonce handling.
158

159
```javascript { .api }
160
/**
161
 * Sets custom attributes without automatic nonce handling
162
 * @param styleElement - Target HTML element  
163
 * @param attributes - Object containing attribute key-value pairs
164
 */
165
function setAttributesWithAttributesAndNonce(
166
  styleElement: HTMLElement,
167
  attributes: Record<string, string>
168
): void;
169
```
170

171
#### setAttributesWithoutAttributes
172

173
Minimal attribute setter that only handles webpack nonce.
174

175
```javascript { .api }
176
/**
177
 * Sets only webpack nonce attribute
178
 * @param element - Target HTML element
179
 */
180
function setAttributesWithoutAttributes(element: HTMLElement): void;
181
```
182

183
### CSS Content Processing
184

185
Functions for processing and transforming CSS content before DOM insertion.
186

187
#### styleTagTransform
188

189
Default CSS content insertion function with cross-browser compatibility.
190

191
```javascript { .api }
192
/**
193
 * Inserts CSS content into style elements with IE compatibility
194
 * @param css - CSS content string
195
 * @param styleElement - Target style element
196
 */
197
function styleTagTransform(css: string, styleElement: HTMLStyleElement): void;
198
```
199

200
### Utility Functions
201

202
Helper functions for browser detection and data comparison.
203

204
#### isOldIE
205

206
Detects Internet Explorer versions 6-9 with memoization using `document.all && !window.atob` feature detection.
207

208
```javascript { .api }
209
/**
210
 * Detects IE6-9 browsers using feature detection
211
 * Uses memoization for performance - checks document.all exists but window.atob doesn't
212
 * @returns True if browser is IE6-9, false otherwise
213
 */
214
function isOldIE(): boolean;
215
```
216

217
#### isEqualLocals
218

219
Deep equality comparison for CSS module locals, used in Hot Module Replacement.
220

221
```javascript { .api }
222
/**
223
 * Compares CSS module locals for equality  
224
 * @param a - First locals object
225
 * @param b - Second locals object
226
 * @param isNamedExport - Whether to skip 'default' property comparison
227
 * @returns True if locals are equal, false otherwise
228
 */
229
function isEqualLocals(
230
  a: Record<string, any>, 
231
  b: Record<string, any>, 
232
  isNamedExport: boolean
233
): boolean;
234
```
235

236
## Runtime Configuration Types
237

238
Core types used throughout the runtime API system.
239

240
```javascript { .api }
241
/**
242
 * CSS module format used throughout runtime system
243
 * Array format: [id, css, media?, sourceMap?, supports?, layer?]
244
 */
245
type CSSModule = [
246
  string,        // Module identifier
247
  string,        // CSS content  
248
  string?,       // Media query (e.g., "screen and (max-width: 768px)")
249
  string?,       // Source map (base64 encoded)
250
  string?,       // Supports rule (e.g., "display: grid")
251
  string?        // CSS cascade layer name (e.g., "utilities", "components")
252
];
253

254
/**
255
 * Runtime options passed to injection and DOM API functions
256
 */
257
interface RuntimeOptions {
258
  /** Custom HTML attributes for elements */
259
  attributes?: Record<string, string>;
260
  
261
  /** DOM insertion function */
262
  insert?: (element: HTMLElement) => void;
263
  
264
  /** DOM API implementation function */
265
  domAPI?: DOMAPIFunction;
266
  
267
  /** Style element creation function */
268
  insertStyleElement?: (options: StyleElementOptions) => HTMLStyleElement;
269
  
270
  /** Attribute setting function */
271
  setAttributes?: (element: HTMLElement, attributes?: object) => void;
272
  
273
  /** CSS transformation function */
274
  styleTagTransform?: (css: string, element: HTMLStyleElement) => void;
275
  
276
  /** Base number for module IDs */
277
  base?: number;
278
}
279

280
/**
281
 * DOM API function signature
282
 */
283
interface DOMAPIFunction {
284
  (options: RuntimeOptions): {
285
    update(obj: CSSModule): void;
286
    remove(): void;
287
  };
288
}
289
```
290

291
## Advanced Usage Examples
292

293
### Custom DOM API Implementation
294

295
```javascript
296
// custom-dom-api.js
297
function customDomAPI(options) {
298
  let styleElement;
299
  
300
  return {
301
    update(obj) {
302
      if (!styleElement) {
303
        styleElement = options.insertStyleElement({
304
          setAttributes: options.setAttributes,
305
          attributes: options.attributes,
306
          insert: options.insert,
307
          options: options.options
308
        });
309
      }
310
      
311
      // Custom CSS processing
312
      const processedCSS = obj[1].replace(/\/\*.*?\*\//g, ''); // Remove comments
313
      options.styleTagTransform(processedCSS, styleElement);
314
    },
315
    
316
    remove() {
317
      if (styleElement && styleElement.parentNode) {
318
        styleElement.parentNode.removeChild(styleElement);
319
        styleElement = null;
320
      }
321
    }
322
  };
323
}
324

325
module.exports = customDomAPI;
326
```
327

328
### Custom Insertion Function
329

330
```javascript
331
// custom-insert.js
332
function customInsert(element) {
333
  // Insert at specific location in shadow DOM
334
  const shadowHost = document.getElementById('shadow-host');
335
  if (shadowHost && shadowHost.shadowRoot) {
336
    shadowHost.shadowRoot.appendChild(element);
337
  } else {
338
    // Fallback to document head
339
    document.head.appendChild(element);
340
  }
341
}
342

343
module.exports = customInsert;
344
```
345

346
### Runtime Options Configuration
347

348
```javascript
349
// Advanced runtime configuration example
350
const runtimeOptions = {
351
  attributes: {
352
    'data-component': 'MyComponent',
353
    'data-version': '1.0.0'
354
  },
355
  
356
  insert: function(element) {
357
    // Custom insertion logic
358
    const target = document.querySelector('#style-container') || document.head;
359
    target.appendChild(element);
360
  },
361
  
362
  domAPI: customDomAPI,
363
  
364
  setAttributes: function(element, attributes) {
365
    // Custom attribute setting
366
    if (attributes) {
367
      Object.keys(attributes).forEach(key => {
368
        element.setAttribute(key, attributes[key]);
369
      });
370
    }
371
    
372
    // Add CSP nonce if available
373
    if (typeof __webpack_nonce__ !== 'undefined') {
374
      element.setAttribute('nonce', __webpack_nonce__);
375
    }
376
  },
377
  
378
  styleTagTransform: function(css, styleElement) {
379
    // Custom CSS transformation
380
    const minifiedCSS = css.replace(/\s+/g, ' ').trim();
381
    
382
    if (styleElement.styleSheet) {
383
      styleElement.styleSheet.cssText = minifiedCSS;
384
    } else {
385
      styleElement.textContent = minifiedCSS;
386
    }
387
  }
388
};
389
```