0
# JSS Preset Default
1

2
JSS Preset Default provides a comprehensive, production-ready preset configuration for JSS (JavaScript Style Sheets) with 12 carefully selected plugins. It simplifies JSS setup by providing sensible defaults for common CSS-in-JS use cases while allowing customization of the most frequently configured options.
3

4
## Package Information
5

6
- **Package Name**: jss-preset-default
7
- **Package Type**: npm
8
- **Language**: JavaScript with TypeScript definitions
9
- **Installation**: `npm install jss-preset-default`
10

11
## Core Imports
12

13
```typescript
14
import preset from "jss-preset-default";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const preset = require("jss-preset-default");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import jss from "jss";
27
import preset from "jss-preset-default";
28

29
// Basic setup with default configuration
30
jss.setup(preset());
31

32
// Create and use styles
33
const styles = jss.createStyleSheet({
34
  button: {
35
    fontSize: 16,        // Automatically becomes '16px'
36
    margin: [10, 20],    // Expands to '10px 20px'
37
    '&:hover': {         // Nested pseudo-selector
38
      backgroundColor: 'blue'
39
    }
40
  }
41
}).attach();
42
```
43

44
## Architecture
45

46
JSS Preset Default is built around a curated collection of 12 JSS plugins that work together to provide comprehensive CSS-in-JS functionality:
47

48
- **Plugin Composition**: Combines 12 complementary plugins in a specific order for optimal results
49
- **Sensible Defaults**: Pre-configured plugins eliminate boilerplate setup for common use cases
50
- **Selective Configuration**: Only the two most commonly customized plugins accept options
51
- **Type Safety**: Full TypeScript support with complete type definitions
52

53
## Capabilities
54

55
### Preset Creation
56

57
Creates a JSS preset configuration object containing a plugins array with 12 pre-configured plugins for modern CSS-in-JS development.
58

59
```typescript { .api }
60
/**
61
 * Creates a JSS preset configuration with 12 pre-configured plugins
62
 * @param options - Optional configuration for customizable plugins
63
 * @returns Object containing configured plugins array
64
 */
65
function preset(options?: Options): { plugins: ReadonlyArray<Plugin> };
66

67
interface Options {
68
  /** Configuration for default CSS units */
69
  defaultUnit?: DefaultUnitOptions;
70
  /** Configuration for observable rule values */
71
  observable?: ObservableOptions;
72
}
73

74
interface DefaultUnitOptions {
75
  /** Maps CSS property names to their default units */
76
  [key: string]: string;
77
}
78

79
interface ObservableOptions {
80
  /** Whether to process observable values */
81
  process?: boolean;
82
  /** Whether to force updates */
83
  force?: boolean;
84
}
85

86

87
interface Plugin {
88
  onCreateRule?(name: string, decl: JssStyle, options: RuleOptions): Rule;
89
  onProcessRule?(rule: Rule, sheet?: StyleSheet): void;
90
  onProcessStyle?(style: JssStyle, rule: Rule, sheet?: StyleSheet): JssStyle;
91
  onProcessSheet?(sheet?: StyleSheet): void;
92
  onChangeValue?(value: string, prop: string, rule: Rule): string | null | false;
93
  onUpdate?(data: object, rule: Rule, sheet?: StyleSheet): void;
94
}
95
```
96

97
**Usage Examples:**
98

99
```typescript
100
import jss from "jss";
101
import preset from "jss-preset-default";
102

103
// Basic usage with defaults
104
jss.setup(preset());
105

106
// Customize default units
107
jss.setup(preset({
108
  defaultUnit: {
109
    'line-height': 'em',
110
    'font-size': 'rem',
111
    'margin': 'rem',
112
    'padding': 'rem'
113
  }
114
}));
115

116
// Configure observable options
117
jss.setup(preset({
118
  observable: {
119
    process: true,
120
    force: false
121
  }
122
}));
123

124
// Combine both configurations
125
jss.setup(preset({
126
  defaultUnit: {
127
    'font-size': 'rem'
128
  },
129
  observable: {
130
    process: true
131
  }
132
}));
133
```
134

135
### Default Unit Configuration
136

137
Customizes automatic unit assignment for numeric CSS property values.
138

139
```typescript { .api }
140
interface DefaultUnitOptions {
141
  /**
142
   * Maps CSS property names to their default units
143
   * When a numeric value is provided for these properties,
144
   * the specified unit will be automatically appended
145
   */
146
  [key: string]: string;
147
}
148
```
149

150
The plugin includes built-in defaults for common properties:
151
- Most sizing properties (width, height, margin, padding, etc.) → `px`
152
- Animation/transition durations → `ms`
153
- Font-size related properties → `px`
154
- Line-height → unitless (special handling)
155

156
**Usage Examples:**
157

158
```typescript
159
// Override built-in defaults
160
const options = {
161
  defaultUnit: {
162
    'line-height': 'em',      // Instead of unitless
163
    'font-size': 'rem',       // Instead of 'px'
164
    'margin': 'rem',          // Instead of 'px'
165
    'padding': 'rem',         // Instead of 'px'
166
    'border-radius': 'em'     // Instead of 'px'
167
  }
168
};
169

170
// Now numeric values use custom units
171
const styles = {
172
  text: {
173
    fontSize: 1.2,      // Becomes '1.2rem'
174
    lineHeight: 1.5,    // Becomes '1.5em'
175
    margin: 16,         // Becomes '16rem'
176
    borderRadius: 0.5   // Becomes '0.5em'
177
  }
178
};
179
```
180

181
### Observable Configuration
182

183
Configures reactive updates for observable rule values.
184

185
```typescript { .api }
186
interface ObservableOptions {
187
  /** Whether to process observable values during updates */
188
  process?: boolean;
189
  /** Whether to force updates even when values haven't changed */
190
  force?: boolean;
191
}
192
```
193

194
**Usage Examples:**
195

196
```typescript
197
import jss from "jss";
198
import preset from "jss-preset-default";
199
import { Observable } from "zen-observable";
200

201
// Configure observable behavior
202
jss.setup(preset({
203
  observable: {
204
    process: true,
205
    force: false
206
  }
207
}));
208

209
// Use observables in styles
210
const color$ = new Observable(observer => {
211
  observer.next('red');
212
  setTimeout(() => observer.next('blue'), 1000);
213
});
214

215
const styles = jss.createStyleSheet({
216
  button: {
217
    color: color$  // Automatically updates when observable emits
218
  }
219
}).attach();
220
```
221

222
## Included Plugins
223

224
The preset includes these 12 plugins in the following order:
225

226
1. **jss-plugin-rule-value-function** - Enables dynamic property values via functions
227
2. **jss-plugin-rule-value-observable** - Enables reactive updates using observables
228
3. **jss-plugin-template** - Support for template string styles
229
4. **jss-plugin-global** - Support for global CSS rules using '@global'
230
5. **jss-plugin-extend** - Rule extension and inheritance using 'extend' property
231
6. **jss-plugin-nested** - Nested CSS selectors support ('&' syntax)
232
7. **jss-plugin-compose** - Rule composition using 'composes' property
233
8. **jss-plugin-camel-case** - Converts camelCase properties to kebab-case CSS
234
9. **jss-plugin-default-unit** - Automatically adds units to numeric values
235
10. **jss-plugin-expand** - Expands shorthand CSS properties
236
11. **jss-plugin-vendor-prefixer** - Automatic vendor prefixing for CSS properties
237
12. **jss-plugin-props-sort** - Consistent property order in output CSS
238

239
**Feature Examples:**
240

241
```typescript
242
import jss from "jss";
243
import preset from "jss-preset-default";
244

245
jss.setup(preset());
246

247
const styles = jss.createStyleSheet({
248
  // Global styles
249
  '@global': {
250
    body: { margin: 0 }
251
  },
252
  
253
  // Main component with multiple features
254
  component: {
255
    // Default units (px added automatically)
256
    fontSize: 16,
257
    margin: [10, 20],
258
    
259
    // Camel case conversion
260
    backgroundColor: 'white',
261
    borderRadius: 4,
262
    
263
    // Property expansion
264
    padding: [10, 15, 10, 15],
265
    
266
    // Nested selectors
267
    '&:hover': {
268
      backgroundColor: 'gray'
269
    },
270
    
271
    // Function values
272
    color: () => Math.random() > 0.5 ? 'red' : 'blue',
273
    
274
    // Vendor prefixing (automatic)
275
    userSelect: 'none',
276
    transform: 'translateX(10px)'
277
  },
278
  
279
  // Rule extension
280
  extendedComponent: {
281
    extend: 'component',
282
    fontSize: 18
283
  }
284
}).attach();
285
```
286

287