0
# StyleSheet Operations
1

2
StyleSheet lifecycle management including creation, rule manipulation, DOM attachment, and dynamic updates for managing CSS styles at runtime.
3

4
## Capabilities
5

6
### StyleSheet Interface
7

8
The primary interface for managing CSS stylesheets with dynamic rule manipulation and DOM integration.
9

10
```javascript { .api }
11
interface StyleSheet<RuleName extends string | number | symbol = string | number | symbol> {
12
  /** Generated class name mappings for stylesheet rules */
13
  classes: Classes<RuleName>;
14
  /** Generated keyframe name mappings */
15
  keyframes: Keyframes<string>;
16
  /** Configuration options for this stylesheet */
17
  options: StyleSheetOptions;
18
  /** Whether stylesheet is linked to a component */
19
  linked: boolean;
20
  /** Whether stylesheet is attached to DOM */
21
  attached: boolean;
22
  
23
  /** Attach stylesheet to the render tree (DOM) */
24
  attach(): this;
25
  /** Remove stylesheet from render tree (DOM) */
26
  detach(): this;
27
  /** Deploy stylesheet with renderer */
28
  deploy(): this;
29
  
30
  /** Add a rule to the stylesheet */
31
  addRule(style: JssStyle, options?: Partial<RuleOptions>): Rule;
32
  addRule(name: RuleName, style: JssStyle, options?: Partial<RuleOptions>): Rule | null;
33
  /** Replace an existing rule in the stylesheet */
34
  replaceRule(name: RuleName, style: JssStyle, options?: Partial<RuleOptions>): [Rule | null, Rule | null];
35
  /** Insert a pre-created rule */
36
  insertRule(rule: Rule): void;
37
  /** Create and add multiple rules at once */
38
  addRules(styles: Partial<Styles<RuleName, any, undefined>>, options?: Partial<RuleOptions>): Rule[];
39
  
40
  /** Get a rule by name or selector */
41
  getRule(nameOrSelector: RuleName | string): Rule;
42
  /** Delete a rule by name */
43
  deleteRule(name: RuleName): boolean;
44
  /** Get index position of a rule */
45
  indexOf(rule: Rule): number;
46
  
47
  /** Update function-based styles with new data */
48
  update(name: string, data: object, options?: UpdateOptions): this;
49
  update(data: object, options?: UpdateOptions): this;
50
  
51
  /** Convert stylesheet to CSS string */
52
  toString(options?: ToCssOptions): string;
53
}
54
```
55

56
### Creating StyleSheets
57

58
Create stylesheets using a JSS instance with style definitions.
59

60
```javascript { .api }
61
/**
62
 * Create a new stylesheet from style definitions
63
 * @param styles - Object containing style definitions
64
 * @param options - Optional configuration for the stylesheet
65
 * @returns New StyleSheet instance
66
 */
67
createStyleSheet<Name extends string | number | symbol>(
68
  styles: Partial<Styles<Name, any, undefined>>,
69
  options?: StyleSheetFactoryOptions
70
): StyleSheet<Name>;
71

72
interface StyleSheetFactoryOptions {
73
  /** Media query for the stylesheet */
74
  media?: string;
75
  /** Metadata identifier for the stylesheet */
76
  meta?: string;
77
  /** Index position for stylesheet ordering */
78
  index?: number;
79
  /** Whether to link stylesheet to a component */
80
  link?: boolean;
81
  /** Existing DOM element to use */
82
  element?: HTMLStyleElement;
83
  /** Custom ID generator for this sheet */
84
  generateId?: GenerateId;
85
  /** Prefix for generated class names */
86
  classNamePrefix?: string;
87
}
88
```
89

90
**Usage Examples:**
91

92
```javascript
93
import jss from "jss";
94

95
// Basic stylesheet creation
96
const sheet = jss.createStyleSheet({
97
  button: {
98
    background: 'blue',
99
    color: 'white',
100
    border: 'none',
101
    padding: '10px 20px'
102
  },
103
  header: {
104
    fontSize: '24px',
105
    fontWeight: 'bold'
106
  }
107
});
108

109
// With options
110
const responsiveSheet = jss.createStyleSheet({
111
  container: {
112
    maxWidth: '1200px',
113
    margin: '0 auto'
114
  }
115
}, {
116
  media: '(min-width: 768px)',
117
  meta: 'responsive-layout',
118
  classNamePrefix: 'my-app-'
119
});
120
```
121

122
### DOM Attachment
123

124
Control stylesheet presence in the DOM for runtime style application.
125

126
```javascript { .api }
127
/**
128
 * Attach stylesheet to the render tree (DOM)
129
 * @returns The stylesheet instance for chaining
130
 */
131
attach(): this;
132

133
/**
134
 * Remove stylesheet from render tree (DOM)
135
 * @returns The stylesheet instance for chaining
136
 */
137
detach(): this;
138
```
139

140
**Usage Example:**
141

142
```javascript
143
const sheet = jss.createStyleSheet({
144
  button: { background: 'blue' }
145
});
146

147
// Attach to DOM - styles become active
148
sheet.attach();
149

150
// Later, remove from DOM - styles become inactive
151
sheet.detach();
152

153
// Check attachment status
154
if (sheet.attached) {
155
  console.log('Stylesheet is active');
156
}
157
```
158

159
### Dynamic Rule Management
160

161
Add, modify, and remove rules from stylesheets at runtime.
162

163
```javascript { .api }
164
/**
165
 * Add a rule to the stylesheet
166
 * @param style - Style object for anonymous rule
167
 * @param options - Rule configuration options
168
 * @returns Created rule instance
169
 */
170
addRule(style: JssStyle, options?: Partial<RuleOptions>): Rule;
171

172
/**
173
 * Add a named rule to the stylesheet
174
 * @param name - Name for the rule (becomes class name)
175
 * @param style - Style object for the rule
176
 * @param options - Rule configuration options
177
 * @returns Created rule instance or null if failed
178
 */
179
addRule(name: RuleName, style: JssStyle, options?: Partial<RuleOptions>): Rule | null;
180

181
/**
182
 * Add multiple rules at once
183
 * @param styles - Object containing multiple style definitions
184
 * @param options - Rule configuration options
185
 * @returns Array of created rule instances
186
 */
187
addRules(styles: Partial<Styles<RuleName, any, undefined>>, options?: Partial<RuleOptions>): Rule[];
188

189
/**
190
 * Replace an existing rule
191
 * @param name - Name of rule to replace
192
 * @param style - New style object
193
 * @param options - Rule configuration options
194
 * @returns Tuple of [old rule, new rule]
195
 */
196
replaceRule(name: RuleName, style: JssStyle, options?: Partial<RuleOptions>): [Rule | null, Rule | null];
197

198
/**
199
 * Delete a rule by name
200
 * @param name - Name of rule to delete
201
 * @returns True if rule was deleted from DOM
202
 */
203
deleteRule(name: RuleName): boolean;
204
```
205

206
**Usage Examples:**
207

208
```javascript
209
const sheet = jss.createStyleSheet({
210
  button: { background: 'blue' }
211
});
212
sheet.attach();
213

214
// Add new rule dynamically
215
sheet.addRule('newButton', {
216
  background: 'red',
217
  color: 'white'
218
});
219

220
// Add multiple rules
221
sheet.addRules({
222
  header: { fontSize: '24px' },
223
  footer: { fontSize: '12px' }
224
});
225

226
// Replace existing rule
227
sheet.replaceRule('button', {
228
  background: 'green',
229
  border: '1px solid black'
230
});
231

232
// Delete a rule
233
sheet.deleteRule('newButton');
234
```
235

236
### Rule Access
237

238
Retrieve and query rules within a stylesheet.
239

240
```javascript { .api }
241
/**
242
 * Get a rule by name or selector
243
 * @param nameOrSelector - Rule name or CSS selector
244
 * @returns Rule instance if found
245
 */
246
getRule(nameOrSelector: RuleName | string): Rule;
247

248
/**
249
 * Get index position of a rule
250
 * @param rule - Rule instance to find
251
 * @returns Index position or -1 if not found
252
 */
253
indexOf(rule: Rule): number;
254
```
255

256
**Usage Example:**
257

258
```javascript
259
const sheet = jss.createStyleSheet({
260
  button: { background: 'blue' },
261
  header: { fontSize: '24px' }
262
});
263

264
// Get rule by name
265
const buttonRule = sheet.getRule('button');
266
const headerRule = sheet.getRule('header');
267

268
// Get rule position
269
const position = sheet.indexOf(buttonRule);
270
console.log(`Button rule is at position ${position}`);
271
```
272

273
### Dynamic Updates
274

275
Update function-based styles with new data for reactive styling.
276

277
```javascript { .api }
278
/**
279
 * Update specific rule with new data
280
 * @param name - Name of rule to update
281
 * @param data - New data object for function-based styles
282
 * @param options - Update configuration options
283
 * @returns The stylesheet instance for chaining
284
 */
285
update(name: string, data: object, options?: UpdateOptions): this;
286

287
/**
288
 * Update all rules with new data
289
 * @param data - New data object for function-based styles
290
 * @param options - Update configuration options
291
 * @returns The stylesheet instance for chaining
292
 */
293
update(data: object, options?: UpdateOptions): this;
294

295
interface UpdateOptions {
296
  /** Whether to process the updated styles through plugins */
297
  process?: boolean;
298
  /** Whether to force update even if data hasn't changed */
299
  force?: boolean;
300
}
301
```
302

303
**Usage Example:**
304

305
```javascript
306
// Stylesheet with function-based styles
307
const sheet = jss.createStyleSheet({
308
  button: (data) => ({
309
    background: data.primary ? 'blue' : 'gray',
310
    fontSize: data.size === 'large' ? '18px' : '14px'
311
  }),
312
  text: (data) => ({
313
    color: data.theme === 'dark' ? 'white' : 'black'
314
  })
315
});
316
sheet.attach();
317

318
// Update with new data
319
sheet.update({
320
  primary: true,
321
  size: 'large',
322
  theme: 'dark'
323
});
324

325
// Update specific rule
326
sheet.update('button', { primary: false });
327
```
328

329
### CSS Output
330

331
Convert stylesheet to CSS string for server-side rendering or debugging.
332

333
```javascript { .api }
334
/**
335
 * Convert stylesheet to CSS string
336
 * @param options - CSS formatting options
337
 * @returns CSS string representation
338
 */
339
toString(options?: ToCssOptions): string;
340

341
interface ToCssOptions {
342
  /** Number of spaces for indentation */
343
  indent?: number;
344
  /** Whether to format CSS with line breaks */
345
  format?: boolean;
346
  /** Whether to include empty rules */
347
  allowEmpty?: boolean;
348
}
349
```
350

351
**Usage Example:**
352

353
```javascript
354
const sheet = jss.createStyleSheet({
355
  button: {
356
    background: 'blue',
357
    color: 'white'
358
  }
359
});
360

361
// Get CSS string
362
const css = sheet.toString();
363
console.log(css);
364
// Output: ".button-0-1-2 { background: blue; color: white; }"
365

366
// Formatted CSS
367
const formattedCss = sheet.toString({ format: true, indent: 2 });
368
console.log(formattedCss);
369
// Output:
370
// .button-0-1-2 {
371
//   background: blue;
372
//   color: white;
373
// }
374
```
375

376
### Class Name Access
377

378
Access generated class names for use in components.
379

380
```javascript { .api }
381
/** Generated class name mappings for stylesheet rules */
382
classes: Classes<RuleName>;
383

384
/** Generated keyframe name mappings */
385
keyframes: Keyframes<string>;
386

387
type Classes<Name extends string | number | symbol = string> = Record<Name, string>;
388
type Keyframes<Name extends string = string> = Record<Name, string>;
389
```
390

391
**Usage Example:**
392

393
```javascript
394
const sheet = jss.createStyleSheet({
395
  button: { background: 'blue' },
396
  '@keyframes slideIn': {
397
    from: { transform: 'translateX(-100%)' },
398
    to: { transform: 'translateX(0)' }
399
  }
400
});
401
sheet.attach();
402

403
// Use generated class names
404
const buttonClass = sheet.classes.button; // "button-0-1-2"
405
const slideInKeyframe = sheet.keyframes.slideIn; // "slideIn-0-1-3"
406

407
// Apply to DOM elements
408
document.getElementById('myButton').className = buttonClass;
409
```