oncss 1.2.12 → 1.2.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/readme.md CHANGED
@@ -1,397 +1,961 @@
1
- <p align="center">
2
- <img width="120" src="https://raw.githubusercontent.com/devnax/oncss/main/logo.png" alt="ONCSS Logo">
3
- </p>
4
-
5
- <h1 align="center">ONCSS</h1>
6
-
7
- `oncss` is a CSS-in-JS library that provides developers with a powerful `css` function to style their web applications. It enables modern styling techniques, including nested selectors, responsive design, and dynamic keyframes, all while offering seamless integration with JavaScript frameworks like React.
8
-
9
- ---
10
-
11
- ## Installation
12
-
13
- Install the `oncss` package via npm:
14
-
15
- ```bash
16
- npm install oncss
17
- ```
18
-
19
- Import the `css` function in your project:
20
-
21
- ```javascript
22
- import css from 'oncss';
23
- ```
24
-
25
- ---
26
-
27
- ## Core Concept: The `css` Function
28
-
29
- The `css` function is the heart of `oncss`, designed to dynamically generate and inject CSS into your application. It supports:
30
-
31
- - **CSS Properties**: Use standard CSS properties and values.
32
- - **Nested Selectors**: Apply styles to child elements or states using `&`.
33
- - **Media Queries**: Implement responsive designs with `@media` rules.
34
- - **Keyframes**: Create animations with `@keyframes`.
35
- - **Global Styles**: Apply styles globally with `@global`.
36
- - **Custom Breakpoints**: Define reusable breakpoints for responsiveness.
37
- - **Other At-Rules**: Utilize additional at-rules like `@container`, `@layer`, and `@supports`.
38
-
39
- ### Basic Example
40
-
41
- ```typescript
42
- const buttonStyles = css({
43
- backgroundColor: 'blue',
44
- color: 'white',
45
- padding: '10px 20px',
46
- borderRadius: '5px',
47
- '&:hover': {
48
- backgroundColor: 'darkblue',
49
- },
50
- '@media (min-width: 768px)': {
51
- padding: '15px 30px',
52
- },
53
- });
54
-
55
- console.log(buttonStyles);
56
- ```
57
-
58
- ---
59
-
60
- ## Configuration Options
61
-
62
- The `css` function can be customized through an options object:
63
-
64
- ### Available Properties
65
-
66
- | Property | Type | Description |
67
- | ------------- | ---------- | ------------------------------------------------------------------------------------------------- |
68
- | `classPrefix` | `string` | Adds a prefix to generated class names. |
69
- | `breakpoints` | `object` | Custom breakpoints for responsive designs. |
70
- | `aliases` | `object` | Custom shorthand properties for CSS rules. |
71
- | `injectStyle` | `boolean` | Controls whether styles are auto-injected. |
72
- | `skipProps` | `function` | Filters out unwanted properties. Receives `prop`, `value`, and `dept` as arguments. |
73
- | `getValue` | `function` | Transforms property values dynamically. Receives `value`, `prop`, `css`, and `dept` as arguments. |
74
- | `getProps` | `function` | Customizes specific property handling. Receives `prop`, `value`, `css`, and `dept` as arguments. |
75
-
76
- ### Example with Options
77
-
78
- ```typescript
79
- const styles = css({
80
- fontSize: 16,
81
- padding: 10,
82
- }, {
83
- classPrefix: 'myprefix',
84
- breakpoints: {
85
- sm: 480,
86
- md: 768,
87
- lg: 1024,
88
- },
89
- });
90
- ```
91
-
92
- ### Using Breakpoints
93
-
94
- You can use the defined breakpoints in your styles to create responsive designs:
95
-
96
- ```typescript
97
- const responsiveStyles = css({
98
- fontSize: 14,
99
- padding: {
100
- sm: 12,
101
- lg: 24
102
- },
103
-
104
- }, {
105
- breakpoints: {
106
- sm: 480,
107
- md: 768,
108
- lg: 1024,
109
- },
110
- });
111
- ```
112
-
113
- ---
114
-
115
- ## React Integration
116
-
117
- oncss integrates seamlessly with React. Simply pass the generated class name to your component.
118
-
119
- ### React Example
120
-
121
- ```typescript
122
- import React from 'react';
123
- import css from 'oncss';
124
-
125
- const buttonStyle = css({
126
- backgroundColor: 'green',
127
- color: 'white',
128
- padding: '10px 20px',
129
- borderRadius: '8px',
130
- '&:hover': {
131
- backgroundColor: 'darkgreen',
132
- },
133
- });
134
-
135
- function Button() {
136
- return <button className={buttonStyle.toString()}>Click Me</button>;
137
- }
138
-
139
- export default Button;
140
- ```
141
-
142
- ---
143
-
144
- ## Advanced Features
145
-
146
- ### Nested Selectors
147
-
148
- Apply styles to child elements or pseudo-classes:
149
-
150
- ```typescript
151
- const cardStyles = css({
152
- padding: '20px',
153
- border: '1px solid #ccc',
154
- '& h1': {
155
- fontSize: '24px',
156
- margin: 0,
157
- },
158
- '&:hover': {
159
- boxShadow: '0 4px 8px rgba(0, 0, 0, 0.1)',
160
- },
161
- });
162
- ```
163
-
164
- ### Media Queries
165
-
166
- Easily add responsive styles:
167
-
168
- ```typescript
169
- const responsiveStyles = css({
170
- fontSize: '14px',
171
- '@media (min-width: 768px)': {
172
- fontSize: '18px',
173
- },
174
- });
175
- ```
176
-
177
- ### Keyframes
178
-
179
- Define and use animations:
180
-
181
- ```typescript
182
- const animationStyles = css({
183
- '@keyframes fadeIn': {
184
- from: { opacity: 0 },
185
- to: { opacity: 1 },
186
- },
187
- animation: 'fadeIn 2s ease-in-out',
188
- });
189
- ```
190
-
191
- ### Global Styles
192
-
193
- Apply global styles effortlessly:
194
-
195
- ```typescript
196
- const globalStyles = css({
197
- '@global': {
198
- body: {
199
- margin: 0,
200
- fontFamily: 'Arial, sans-serif',
201
- },
202
- a: {
203
- color: 'blue',
204
- textDecoration: 'none',
205
- },
206
- },
207
- });
208
- ```
209
-
210
- ---
211
-
212
- ## Supported At-Rules
213
-
214
- `oncss` supports various CSS at-rules to enhance your styling capabilities. Here is a list of supported at-rules with descriptions:
215
-
216
- | At-Rule | Description |
217
- | ------------ | ---------------------------------------------------------------------------- |
218
- | `@media` | Used for applying styles based on media queries for responsive design. |
219
- | `@keyframes` | Defines animations that can be applied to elements. |
220
- | `@global` | Applies styles globally across the entire application. |
221
- | `@container` | Used for container queries to apply styles based on container size. |
222
- | `@layer` | Defines style layers to control the order of style application. |
223
- | `@supports` | Applies styles based on the support of specific CSS features in the browser. |
224
-
225
- ---
226
-
227
- ## Server-Side Styling
228
-
229
- `oncss` supports server-side rendering (SSR) by utilizing the `CSSFactory` to store and manage generated CSS styles. This allows you to extract and inject styles into your server-rendered HTML.
230
-
231
- ### Example with React
232
-
233
- Here's an example of how to use `oncss` for server-side rendering with React:
234
-
235
- ```tsx
236
- import React from 'react';
237
- import ReactDOMServer from 'react-dom/server';
238
- import css, { CSSFactory } from 'oncss';
239
-
240
- const buttonStyle = css({
241
- backgroundColor: 'blue',
242
- color: 'white',
243
- padding: '10px 20px',
244
- borderRadius: '5px',
245
- '&:hover': {
246
- backgroundColor: 'darkblue',
247
- },
248
- });
249
-
250
- function Button() {
251
- return <button className={buttonStyle}>Click Me</button>;
252
- }
253
-
254
- const App = () => (
255
- <div>
256
- <Button />
257
- </div>
258
- );
259
-
260
- // Render the component to a string
261
- const html = ReactDOMServer.renderToString(<App />);
262
-
263
- let styles: any = Array.from(CSSFactory.values()).map((style) => {
264
- return `<style data-href="${style.classname}">${style.css}</style>`
265
- });
266
-
267
- // Inject the styles into the HTML
268
- const fullHtml = `
269
- <!DOCTYPE html>
270
- <html lang="en">
271
- <head>
272
- <meta charset="UTF-8">
273
- <meta name="viewport" content="width=device-width, initial-scale=1.0">
274
- <title>SSR with oncss</title>
275
- ${styles}
276
- </head>
277
- <body>
278
- <div id="root">${html}</div>
279
- </body>
280
- </html>
281
- `;
282
-
283
- console.log(fullHtml);
284
- ```
285
-
286
- In this example, the `CSSFactory` is used to collect all generated CSS styles during the server-side rendering process. These styles are then injected into the HTML document, ensuring that the styles are applied correctly when the page is loaded in the browser.
287
-
288
- ---
289
-
290
- ## Utility Functions
291
-
292
- ### CSSFactory
293
-
294
- `CSSFactory` is a global cache for storing generated CSS styles. It helps in reusing styles and avoiding redundant style generation.
295
-
296
- ### formatCSSProp
297
-
298
- `formatCSSProp` is a utility function that converts camelCase CSS property names to kebab-case.
299
-
300
- ```typescript
301
- import { formatCSSProp } from 'oncss';
302
-
303
- const formattedProp = formatCSSProp('backgroundColor');
304
- console.log(formattedProp); // 'background-color'
305
- ```
306
-
307
- ### formatCSSValue
308
-
309
- `formatCSSValue` is a utility function that formats CSS values, adding units like `px` where necessary.
310
-
311
- ```typescript
312
- import { formatCSSValue } from 'oncss';
313
-
314
- const formattedValue = formatCSSValue('width', 100);
315
- console.log(formattedValue); // '100px'
316
- ```
317
-
318
- ---
319
-
320
- ## TypeScript Integration
321
-
322
- `oncss` provides full TypeScript support, allowing you to define types for your CSS properties and options.
323
-
324
- ### Defining CSS Properties
325
-
326
- You can define the types for your CSS properties using the `CSSProps` type:
327
-
328
- ```typescript
329
- import { CSSProps } from 'oncss';
330
-
331
- interface MyAliases {
332
- customColor?: string;
333
- }
334
-
335
- const styles: CSSProps<MyAliases, 'sm' | 'md' | 'lg'> = {
336
- backgroundColor: 'blue',
337
- customColor: 'red',
338
- '@media (min-width: 768px)': {
339
- backgroundColor: 'green',
340
- },
341
- };
342
- ```
343
-
344
- ### Using Options with Types
345
-
346
- You can also define types for the options object:
347
-
348
- ```typescript
349
- import { CSSOptionProps } from 'oncss';
350
-
351
- const options: CSSOptionProps<MyAliases, 'sm' | 'md' | 'lg'> = {
352
- classPrefix: 'myprefix',
353
- breakpoints: {
354
- sm: 480,
355
- md: 768,
356
- lg: 1024,
357
- },
358
- aliases: {
359
- customColor: (value) => ({ color: value }),
360
- },
361
- };
362
-
363
- const styles = css({
364
- fontSize: 16,
365
- padding: 10,
366
- }, options);
367
- ```
368
-
369
- ---
370
-
371
- ## Conclusion
372
-
373
- `oncss` simplifies styling for modern web applications. Its robust feature set, from responsive design to keyframe animations, makes it an invaluable tool for developers.
374
-
375
- ## Author
376
-
377
- <table>
378
- <tr>
379
- <td>
380
- <img src="https://raw.githubusercontent.com/devnax/devnax/main/me-circle-200.png" alt="devnax" width="100" height="100">
381
- </td>
382
- <td>
383
- <strong>Naxrul Ahmed</strong><br>
384
- <a href="https://github.com/devnax">GitHub Profile</a><br>
385
- <a href="https://www.npmjs.com/~devnax">npm Profile</a><br>
386
- <a href="https://github.com/devnax/open-source">Open Source Projects</a>
387
- </td>
388
- </tr>
389
- </table>
390
-
391
- <h2>⚡️ Where to find me</h2>
392
-
393
- <p><a target="_blank" href="mailto:devnaxrul@gmail.com" style="display: inline-block;"><img src="https://img.shields.io/badge/-Email-05122A?style=for-the-badge&logo=gmail&logoColor=white&color=orange" alt="gmail" /></a>
394
- <a target="_blank" href="https://twitter.com/devnaxx" style="display: inline-block;"><img src="https://img.shields.io/badge/twitter-x?style=for-the-badge&logo=x&logoColor=white&color=%230f1419" alt="twitter" /></a>
395
- <a target="_blank" href="https://www.linkedin.com/in/devnax" style="display: inline-block;"><img src="https://img.shields.io/badge/linkedin-logo?style=for-the-badge&logo=linkedin&logoColor=white&color=%230a77b6" alt="linkedin" /></a>
396
- <a target="_blank" href="https://www.facebook.com/devnax" style="display: inline-block;"><img src="https://img.shields.io/badge/facebook-logo?style=for-the-badge&logo=facebook&logoColor=white&color=%230866ff" alt="facebook" /></a>
397
- <a target="_blank" href="https://www.instagram.com/devnaxx" style="display: inline-block;"><img src="https://img.shields.io/badge/instagram-logo?style=for-the-badge&logo=instagram&logoColor=white&color=%23F35369" alt="instagram" /></a></p>
1
+ <p align="center">
2
+ <img width="120" src="https://raw.githubusercontent.com/devnax/oncss/main/logo.png" alt="ONCSS logo">
3
+ </p>
4
+
5
+ <h1 align="center">ONCSS</h1>
6
+
7
+ `oncss` is a small CSS-in-JS library that generates scoped CSS from JavaScript or
8
+ TypeScript style objects. It supports nested selectors, custom breakpoints, media
9
+ and container queries, keyframes, global rules, aliases, and custom
10
+ property/value transforms.
11
+
12
+ ## Installation
13
+
14
+ ```bash
15
+ npm install oncss
16
+ ```
17
+
18
+ ```ts
19
+ import { css } from 'oncss';
20
+ ```
21
+
22
+ ## Quick start
23
+
24
+ ```ts
25
+ import { css } from 'oncss';
26
+
27
+ const button = css({
28
+ display: 'inline-flex',
29
+ alignItems: 'center',
30
+ padding: '10px 18px',
31
+ color: 'white',
32
+ backgroundColor: '#2563eb',
33
+ border: 0,
34
+ borderRadius: 8,
35
+
36
+ '&:hover': {
37
+ backgroundColor: '#1d4ed8',
38
+ },
39
+ });
40
+
41
+ const element = document.querySelector('button');
42
+ element?.classList.add(button.classname);
43
+ ```
44
+
45
+ `css()` returns a style factory. By default it generates a class name and injects
46
+ the resulting stylesheet into `document.head`.
47
+
48
+ ```ts
49
+ button.classname; // generated name, for example "x..."
50
+ button.css; // generated CSS string
51
+ button.cssraw; // original style object
52
+ ```
53
+
54
+ > Use `factory.classname` (or `classList.add(factory.classname)`) rather than
55
+ > treating the factory as a string.
56
+
57
+ ## How style objects work
58
+
59
+ Properties use JavaScript CSS names such as `backgroundColor`, `fontSize`, and
60
+ `zIndex`. ONCSS converts camel-case names to CSS kebab-case names.
61
+
62
+ ```ts
63
+ const card = css({
64
+ maxWidth: 480,
65
+ backgroundColor: '#fff',
66
+ boxShadow: '0 10px 30px rgba(0, 0, 0, 0.12)',
67
+ });
68
+ ```
69
+
70
+ Numeric values become pixels by default:
71
+
72
+ ```ts
73
+ css({
74
+ width: 320, // width:320px
75
+ marginTop: 16, // margin-top:16px
76
+ fontWeight: 700, // font-weight:700
77
+ opacity: 0.8, // opacity:0.8
78
+ zIndex: 10, // z-index:10
79
+ });
80
+ ```
81
+
82
+ Unitless handling also includes `line-height`, `flex`, `flex-grow`,
83
+ `flex-shrink`, `flex-basis`, `order`, `columns`, `perspective`, and
84
+ `stroke-dashoffset`. When a unit is not appropriate, provide an explicit string,
85
+ such as `'50%'`, `'1.5rem'`, or `'auto'`.
86
+
87
+ ## Selectors
88
+
89
+ Every nested selector starts with `&`. ONCSS replaces every `&` with the
90
+ generated class name before compiling the stylesheet.
91
+
92
+ ### Pseudo-classes and pseudo-elements
93
+
94
+ ```ts
95
+ const link = css({
96
+ color: '#2563eb',
97
+
98
+ '&:hover': {
99
+ color: '#1d4ed8',
100
+ },
101
+
102
+ '&:focus-visible': {
103
+ outline: '2px solid #2563eb',
104
+ outlineOffset: 3,
105
+ },
106
+
107
+ '&::before': {
108
+ content: '"→ "',
109
+ },
110
+ });
111
+ ```
112
+
113
+ ### Descendants and combinators
114
+
115
+ Include a space, combinator, or attribute selector after `&` exactly as you
116
+ would in CSS:
117
+
118
+ ```ts
119
+ const article = css({
120
+ '& h2': {
121
+ marginTop: 0,
122
+ },
123
+
124
+ '& > img': {
125
+ display: 'block',
126
+ width: '100%',
127
+ },
128
+
129
+ '& input:checked + span': {
130
+ color: '#16a34a',
131
+ },
132
+
133
+ '&[data-size="large"]': {
134
+ padding: 32,
135
+ },
136
+ });
137
+ ```
138
+
139
+ ### Deep selector nesting
140
+
141
+ Selector blocks can contain other selector blocks. Nesting is useful for
142
+ component states that also affect descendants.
143
+
144
+ ```ts
145
+ const menu = css({
146
+ color: '#334155',
147
+
148
+ '&:hover': {
149
+ color: '#0f172a',
150
+
151
+ '& .icon': {
152
+ transform: 'translateX(4px)',
153
+ },
154
+
155
+ '&::after': {
156
+ opacity: 1,
157
+ },
158
+ },
159
+ });
160
+ ```
161
+
162
+ The nested `& .icon` rule is scoped beneath the parent component's `:hover`
163
+ state because nested levels continue from the current generated selector.
164
+
165
+ ### Selector mode
166
+
167
+ The `selector` option controls the prefix applied to the generated name. The
168
+ default is a class selector (`"."`).
169
+
170
+ ```ts
171
+ const classStyle = css(
172
+ { color: 'red' },
173
+ { selector: '.' },
174
+ );
175
+ // .x... { color:red; }
176
+
177
+ const idStyle = css(
178
+ { color: 'red' },
179
+ { selector: '#' },
180
+ );
181
+ // #x... { color:red; }
182
+ ```
183
+
184
+ For ID mode, assign the generated name to `id`:
185
+
186
+ ```tsx
187
+ const panel = css({ padding: 20 }, { selector: '#' });
188
+
189
+ function Panel() {
190
+ return <section id={panel.classname}>Panel</section>;
191
+ }
192
+ ```
193
+
194
+ You can also provide another selector prefix:
195
+
196
+ ```ts
197
+ const dataStyle = css(
198
+ { color: 'rebeccapurple' },
199
+ { selector: 'section.' },
200
+ );
201
+ // section.x... { color:rebeccapurple; }
202
+ ```
203
+
204
+ Use this only when your final generated selector is valid; ONCSS performs no
205
+ selector validation. For ordinary styling, keep the default class mode.
206
+
207
+ ## Responsive values and breakpoints
208
+
209
+ A property value can be an object whose keys are numeric breakpoints or keys
210
+ from the `breakpoints` option. These values compile to `min-width` media
211
+ queries.
212
+
213
+ ```ts
214
+ const layout = css({
215
+ display: 'grid',
216
+ gridTemplateColumns: '1fr',
217
+ gap: 12,
218
+
219
+ gridColumn: {
220
+ 480: 'span 1',
221
+ 768: 'span 2',
222
+ },
223
+ });
224
+ ```
225
+
226
+ This generates the equivalent of:
227
+
228
+ ```css
229
+ .x... {
230
+ display: grid;
231
+ grid-template-columns: 1fr;
232
+ gap: 12px;
233
+ }
234
+
235
+ @media (min-width: 480px) {
236
+ .x... {
237
+ grid-column: span 1;
238
+ }
239
+ }
240
+ ```
241
+
242
+ Named breakpoints are easier to reuse:
243
+
244
+ ```ts
245
+ const responsive = css(
246
+ {
247
+ fontSize: {
248
+ sm: 14,
249
+ md: 16,
250
+ lg: 18,
251
+ },
252
+ padding: {
253
+ sm: 12,
254
+ md: 20,
255
+ lg: 28,
256
+ },
257
+ },
258
+ {
259
+ breakpoints: {
260
+ sm: 480,
261
+ md: 768,
262
+ lg: 1024,
263
+ },
264
+ },
265
+ );
266
+ ```
267
+
268
+ Responsive value rules:
269
+
270
+ - Every breakpoint is a `min-width` query in pixels.
271
+ - Numeric keys are supported directly.
272
+ - A named key must exist in `options.breakpoints`.
273
+ - Keep breakpoints in ascending order in the object when possible. This makes
274
+ the source and emitted CSS easier to reason about.
275
+ - Responsive objects are values for one property. Use an `@media ...` block
276
+ when multiple properties need to change together.
277
+
278
+ ## Explicit media queries
279
+
280
+ Use an `@media` key when an entire group of declarations should respond to a
281
+ condition:
282
+
283
+ ```ts
284
+ const hero = css({
285
+ padding: 24,
286
+ textAlign: 'center',
287
+
288
+ '@media (min-width: 768px)': {
289
+ padding: 48,
290
+ textAlign: 'left',
291
+ },
292
+
293
+ '@media (prefers-reduced-motion: reduce)': {
294
+ animation: 'none',
295
+ scrollBehavior: 'auto',
296
+ },
297
+ });
298
+ ```
299
+
300
+ Media blocks can also include nested selectors:
301
+
302
+ ```ts
303
+ const navigation = css({
304
+ '& .links': {
305
+ display: 'none',
306
+ },
307
+
308
+ '@media (min-width: 900px)': {
309
+ '& .links': {
310
+ display: 'flex',
311
+ gap: 20,
312
+ },
313
+
314
+ '& .menu-button': {
315
+ display: 'none',
316
+ },
317
+ },
318
+ });
319
+ ```
320
+
321
+ The at-rule type and condition become the emitted CSS key verbatim:
322
+
323
+ ```ts
324
+ '@media screen and (min-width: 1200px)'
325
+ ```
326
+
327
+ ## Other at-rules
328
+
329
+ `@container`, `@layer`, and `@supports` blocks use the same shape as media
330
+ queries.
331
+
332
+ ### Container queries
333
+
334
+ ```ts
335
+ const card = css({
336
+ containerType: 'inline-size',
337
+
338
+ '@container (min-width: 420px)': {
339
+ display: 'grid',
340
+ gridTemplateColumns: '120px 1fr',
341
+ },
342
+ });
343
+ ```
344
+
345
+ ### Feature queries
346
+
347
+ ```ts
348
+ const grid = css({
349
+ display: 'block',
350
+
351
+ '@supports (display: grid)': {
352
+ display: 'grid',
353
+ },
354
+ });
355
+ ```
356
+
357
+ ### Layers
358
+
359
+ ```ts
360
+ const component = css({
361
+ '@layer components': {
362
+ padding: 16,
363
+ borderRadius: 8,
364
+ },
365
+ });
366
+ ```
367
+
368
+ The supported TypeScript at-rule prefixes are `@media`, `@container`, `@layer`,
369
+ and `@supports`, each followed by a space and their condition or name.
370
+
371
+ ## Keyframes
372
+
373
+ Define animations with an `@keyframes <name>` key. Steps can use `from`, `to`,
374
+ or percentage keys.
375
+
376
+ ```ts
377
+ const toast = css({
378
+ '@keyframes toast-in': {
379
+ from: {
380
+ opacity: 0,
381
+ transform: 'translateY(12px)',
382
+ },
383
+ '60%': {
384
+ opacity: 1,
385
+ transform: 'translateY(-2px)',
386
+ },
387
+ to: {
388
+ opacity: 1,
389
+ transform: 'translateY(0)',
390
+ },
391
+ },
392
+
393
+ animation: 'toast-in 240ms ease-out both',
394
+ });
395
+ ```
396
+
397
+ Generated keyframes are included with each style factory. ONCSS does not scope
398
+ or rename the animation name automatically, so choose globally unique names in
399
+ shared applications.
400
+
401
+ A keyframe step accepts regular CSS declarations but not responsive breakpoint
402
+ objects:
403
+
404
+ ```ts
405
+ const valid = css({
406
+ '@keyframes pulse': {
407
+ from: { opacity: 0.6 },
408
+ to: { opacity: 1 },
409
+ },
410
+ });
411
+ ```
412
+
413
+ For more complex motion, combine an animation with a media preference:
414
+
415
+ ```ts
416
+ const spinner = css({
417
+ animation: 'spin 800ms linear infinite',
418
+
419
+ '@keyframes spin': {
420
+ to: {
421
+ transform: 'rotate(360deg)',
422
+ },
423
+ },
424
+
425
+ '@media (prefers-reduced-motion: reduce)': {
426
+ animationDuration: '0.001ms',
427
+ animationIterationCount: 1,
428
+ },
429
+ });
430
+ ```
431
+
432
+ ## Global styles
433
+
434
+ `@global` emits each child selector without class scoping. Use it for resets,
435
+ page-level defaults, and non-component styles.
436
+
437
+ ```ts
438
+ css({
439
+ '@global': {
440
+ ':root': {
441
+ color: '#0f172a',
442
+ backgroundColor: '#ffffff',
443
+ fontFamily: 'system-ui, sans-serif',
444
+ },
445
+
446
+ '*, *::before, *::after': {
447
+ boxSizing: 'border-box',
448
+ },
449
+
450
+ body: {
451
+ margin: 0,
452
+ },
453
+
454
+ 'a:hover': {
455
+ color: '#1d4ed8',
456
+ },
457
+ },
458
+ });
459
+ ```
460
+
461
+ Global selectors are literal CSS selectors; do not prefix them with `&`.
462
+
463
+ ## Aliases
464
+
465
+ Aliases expand a custom property into one or more standard properties. The
466
+ alias receives the supplied value and returns a style object.
467
+
468
+ ```ts
469
+ import { css, type OptionAliases } from 'oncss';
470
+
471
+ type Aliases = {
472
+ m: number;
473
+ px: number;
474
+ };
475
+
476
+ const aliases: OptionAliases<Aliases> = {
477
+ m: (value) => ({ margin: value }),
478
+ px: (value) => ({
479
+ paddingLeft: value,
480
+ paddingRight: value,
481
+ }),
482
+ };
483
+
484
+ const box = css(
485
+ {
486
+ m: 12,
487
+ px: 20,
488
+ backgroundColor: '#f8fafc',
489
+ },
490
+ { aliases },
491
+ );
492
+ ```
493
+
494
+ Aliases are expanded before normal declarations are emitted. The recursive
495
+ expansion disables aliases for the returned style object, so aliases should
496
+ return standard CSS properties or rules rather than other aliases.
497
+
498
+ ## Custom transforms
499
+
500
+ The options hooks provide low-level control for integrating design tokens,
501
+ filtering properties, and adapting values.
502
+
503
+ ### `getValue`
504
+
505
+ `getValue` receives `(property, value, fullStyleObject, depth)` and returns the
506
+ value ONCSS should emit:
507
+
508
+ ```ts
509
+ const themed = css(
510
+ {
511
+ color: 'text.primary',
512
+ padding: 'space.4',
513
+ },
514
+ {
515
+ getValue: (property, value) => {
516
+ if (property === 'color' && value === 'text.primary') {
517
+ return '#0f172a';
518
+ }
519
+ if (property === 'padding' && value === 'space.4') {
520
+ return 16;
521
+ }
522
+ return value;
523
+ },
524
+ },
525
+ );
526
+ ```
527
+
528
+ Because numbers are transformed to pixels later, returning `16` produces
529
+ `padding:16px`.
530
+
531
+ ### `getProps`
532
+
533
+ `getProps` receives `(property, value, fullStyleObject, depth)`. Return a style
534
+ object to replace the handling of that property, or return `undefined` to use
535
+ normal processing.
536
+
537
+ ```ts
538
+ const layout = css(
539
+ {
540
+ inset: 24,
541
+ },
542
+ {
543
+ getProps: (property, value) => {
544
+ if (property === 'inset') {
545
+ return {
546
+ top: value,
547
+ right: value,
548
+ bottom: value,
549
+ left: value,
550
+ };
551
+ }
552
+ },
553
+ },
554
+ );
555
+ ```
556
+
557
+ When `getProps` returns an object, its recursive expansion does not call
558
+ `getProps` again.
559
+
560
+ ### `skipProps`
561
+
562
+ Return `true` to omit a property. Skipped properties and the selector they
563
+ belonged to are available on the returned factory:
564
+
565
+ ```ts
566
+ const safeStyle = css(
567
+ {
568
+ color: 'red',
569
+ unsupportedExperimentalProperty: 'value',
570
+ },
571
+ {
572
+ skipProps: (property) =>
573
+ property.startsWith('unsupported'),
574
+ },
575
+ );
576
+
577
+ console.log(safeStyle.skiped);
578
+ ```
579
+
580
+ All hooks receive a `dept` (depth) number. Root declarations start at `1`, and
581
+ the depth increases as nested selectors or at-rules are processed.
582
+
583
+ ## Configuration reference
584
+
585
+ The options object is the second argument to `css()`:
586
+
587
+ ```ts
588
+ const factory = css(styleObject, options);
589
+ ```
590
+
591
+ | Option | Type | Default | Purpose |
592
+ | --- | --- | --- | --- |
593
+ | `classPrefix` | `string` | `''` | Prefixes the generated `classname`. |
594
+ | `selector` | `string` | `'.'` | Prefix added before the generated name in CSS. |
595
+ | `breakpoints` | `Record<string, number>` | none | Resolves named responsive property values to pixel widths. |
596
+ | `aliases` | alias map | none | Expands custom properties into style objects. |
597
+ | `injectStyle` | `boolean` | `true` | Controls automatic style injection. |
598
+ | `container` | `Document \| HTMLElement` | `document` | Chooses where the style tag is inserted. |
599
+ | `cacheId` | `string` | `'global'` | Selects a named cache group. |
600
+ | `skipProps` | function | none | Omits selected declarations. |
601
+ | `getValue` | function | none | Transforms declaration values. |
602
+ | `getProps` | function | none | Replaces declaration handling with another style object. |
603
+
604
+ For class naming, `classPrefix` affects the generated name while `selector`
605
+ affects how that name is addressed by the stylesheet:
606
+
607
+ ```ts
608
+ const button = css(
609
+ { color: 'white' },
610
+ {
611
+ classPrefix: 'button-',
612
+ selector: '.',
613
+ },
614
+ );
615
+
616
+ button.classname.startsWith('button-'); // true
617
+ ```
618
+
619
+ ## Style factory API
620
+
621
+ ```ts
622
+ const factory = css({ color: 'red' });
623
+ ```
624
+
625
+ | Property | Description |
626
+ | --- | --- |
627
+ | `classname` | Generated class or ID name. |
628
+ | `css` | Generated CSS string. |
629
+ | `cssraw` | Original style object. |
630
+ | `cachekey` | Key used to reuse the generated factory. |
631
+ | `cacheId` | Name of the cache containing the factory. |
632
+ | `cache` | `true` when a previous factory was reused for the request. |
633
+ | `skiped` | Properties omitted by `skipProps`, grouped by selector. |
634
+ | `inject()` | Append or populate the factory's style tag. |
635
+ | `refresh()` | Remove the current style tag and inject the CSS again. |
636
+ | `deleteStyle()` | Remove only the injected style tag. |
637
+ | `getStyleTag()` | Return the injected `style` element, or `null`. |
638
+ | `delete()` | Remove the factory from the cache and remove its style tag. |
639
+
640
+ ### Manual injection
641
+
642
+ Disable automatic injection when you need to collect or control CSS output:
643
+
644
+ ```ts
645
+ const button = css(
646
+ { backgroundColor: '#2563eb' },
647
+ { injectStyle: false },
648
+ );
649
+
650
+ console.log(button.css);
651
+ button.inject();
652
+ ```
653
+
654
+ ### Target document or element
655
+
656
+ Use `container` to inject into an iframe document, a shadow-root host element,
657
+ or another owned HTML element.
658
+
659
+ ```ts
660
+ const iframe = document.querySelector('iframe');
661
+ const iframeDocument = iframe?.contentDocument;
662
+
663
+ if (iframeDocument) {
664
+ css(
665
+ { color: 'tomato' },
666
+ { container: iframeDocument },
667
+ );
668
+ }
669
+ ```
670
+
671
+ ```ts
672
+ const host = document.querySelector('#shadow-host') as HTMLElement;
673
+
674
+ css(
675
+ { color: 'tomato' },
676
+ { container: host },
677
+ );
678
+ ```
679
+
680
+ A `Document` injects into its `<head>`. An `HTMLElement` receives the style tag
681
+ directly, allowing styles to be placed in a specific container.
682
+
683
+ ## Caching
684
+
685
+ ONCSS caches factories by `cacheId` and a generated style key. The key includes
686
+ the source style object and `selector`. Repeated equivalent calls can therefore
687
+ reuse the same factory.
688
+
689
+ ```ts
690
+ const first = css({ color: 'red' }, { cacheId: 'dashboard' });
691
+ const second = css({ color: 'red' }, { cacheId: 'dashboard' });
692
+
693
+ first === second; // true
694
+ ```
695
+
696
+ Use different `cacheId` values to isolate groups of generated styles:
697
+
698
+ ```ts
699
+ const appStyle = css(
700
+ { color: 'red' },
701
+ { cacheId: 'main-app' },
702
+ );
703
+
704
+ const previewStyle = css(
705
+ { color: 'red' },
706
+ { cacheId: 'preview' },
707
+ );
708
+ ```
709
+
710
+ The cache API is exported for advanced use:
711
+
712
+ ```ts
713
+ import { ONCSS_CACHE } from 'oncss';
714
+
715
+ const group = ONCSS_CACHE.caches().get('main-app');
716
+
717
+ ONCSS_CACHE.delete('main-app', appStyle.cachekey);
718
+ ```
719
+
720
+ Changing options such as breakpoints, aliases, or transform hooks without
721
+ changing the style object or selector can still reuse the prior cache entry.
722
+ Use a distinct `cacheId` when the same style source is compiled with materially
723
+ different options.
724
+
725
+ ## Server-side rendering
726
+
727
+ With no browser `window`, ONCSS still generates factories and CSS but cannot
728
+ inject a style element. Collect the generated factories from the cache and
729
+ render their `css` into your document head.
730
+
731
+ ```tsx
732
+ import { renderToString } from 'react-dom/server';
733
+ import { css, ONCSS_CACHE } from 'oncss';
734
+
735
+ const button = css(
736
+ {
737
+ color: 'white',
738
+ backgroundColor: '#2563eb',
739
+ '&:hover': {
740
+ backgroundColor: '#1d4ed8',
741
+ },
742
+ },
743
+ {
744
+ cacheId: 'server-render',
745
+ injectStyle: false,
746
+ },
747
+ );
748
+
749
+ const html = renderToString(
750
+ <button className={button.classname}>Save</button>,
751
+ );
752
+
753
+ const styles = Array.from(
754
+ ONCSS_CACHE.caches().get('server-render')?.values() ?? [],
755
+ )
756
+ .map((factory) =>
757
+ `<style data-href="${factory.classname}">${factory.css}</style>`,
758
+ )
759
+ .join('');
760
+
761
+ const documentHtml = `
762
+ <!doctype html>
763
+ <html>
764
+ <head>${styles}</head>
765
+ <body><div id="root">${html}</div></body>
766
+ </html>
767
+ `;
768
+ ```
769
+
770
+ Use a request-specific or intentionally scoped `cacheId` if styles should not
771
+ leak between SSR requests. Also apply your existing HTML escaping policy before
772
+ inserting application-derived content into an HTML response.
773
+
774
+ ## React
775
+
776
+ Pass `factory.classname` to `className`:
777
+
778
+ ```tsx
779
+ import { css } from 'oncss';
780
+
781
+ const buttonStyle = css({
782
+ padding: '10px 18px',
783
+ color: 'white',
784
+ backgroundColor: '#2563eb',
785
+ border: 0,
786
+ borderRadius: 8,
787
+
788
+ '&:hover': {
789
+ backgroundColor: '#1d4ed8',
790
+ },
791
+ });
792
+
793
+ export function Button() {
794
+ return (
795
+ <button type="button" className={buttonStyle.classname}>
796
+ Save
797
+ </button>
798
+ );
799
+ }
800
+ ```
801
+
802
+ For styles generated at module scope, ONCSS injects and caches them once. For
803
+ dynamic styles, call `css()` in response to the relevant state and reuse cache
804
+ IDs where appropriate.
805
+
806
+ ## Utility functions
807
+
808
+ ### `formatCSSProp`
809
+
810
+ ```ts
811
+ import { formatCSSProp } from 'oncss';
812
+
813
+ formatCSSProp('backgroundColor'); // 'background-color'
814
+ ```
815
+
816
+ ### `formatCSSValue`
817
+
818
+ ```ts
819
+ import { formatCSSValue } from 'oncss';
820
+
821
+ formatCSSValue('width', 100); // '100px'
822
+ formatCSSValue('opacity', 0.5); // 0.5
823
+ ```
824
+
825
+ ## TypeScript
826
+
827
+ The package exports the main CSS and option types:
828
+
829
+ ```ts
830
+ import {
831
+ css,
832
+ type CSSOptionProps,
833
+ type CSSProps,
834
+ type OptionAliases,
835
+ } from 'oncss';
836
+
837
+ type Aliases = {
838
+ m: number;
839
+ };
840
+
841
+ type Breakpoint = 'sm' | 'md' | 'lg';
842
+
843
+ const aliases: OptionAliases<Aliases> = {
844
+ m: (value) => ({ margin: value }),
845
+ };
846
+
847
+ const options: CSSOptionProps<Aliases, Breakpoint> = {
848
+ aliases,
849
+ breakpoints: {
850
+ sm: 480,
851
+ md: 768,
852
+ lg: 1024,
853
+ },
854
+ };
855
+
856
+ const styles: CSSProps<Aliases, Breakpoint> = {
857
+ m: 8,
858
+ color: 'red',
859
+ fontSize: {
860
+ sm: 14,
861
+ lg: 18,
862
+ },
863
+ };
864
+
865
+ const generated = css(styles, options);
866
+ ```
867
+
868
+ ## Complete example
869
+
870
+ ```tsx
871
+ import { css, type OptionAliases } from 'oncss';
872
+
873
+ type Aliases = {
874
+ px: number;
875
+ radius: number;
876
+ };
877
+
878
+ const aliases: OptionAliases<Aliases> = {
879
+ px: (value) => ({
880
+ paddingLeft: value,
881
+ paddingRight: value,
882
+ }),
883
+ radius: (value) => ({
884
+ borderRadius: value,
885
+ }),
886
+ };
887
+
888
+ const notification = css(
889
+ {
890
+ px: 16,
891
+ radius: 10,
892
+ paddingTop: 12,
893
+ paddingBottom: 12,
894
+ color: '#0f172a',
895
+ backgroundColor: '#f8fafc',
896
+ boxShadow: '0 10px 30px rgba(15, 23, 42, 0.12)',
897
+ animation: 'notification-enter 220ms ease-out both',
898
+
899
+ '&:hover': {
900
+ backgroundColor: '#f1f5f9',
901
+ },
902
+
903
+ '@media (min-width: 768px)': {
904
+ px: 24,
905
+ '& .actions': {
906
+ display: 'flex',
907
+ },
908
+ },
909
+
910
+ '@keyframes notification-enter': {
911
+ from: {
912
+ opacity: 0,
913
+ transform: 'translateY(8px)',
914
+ },
915
+ to: {
916
+ opacity: 1,
917
+ transform: 'translateY(0)',
918
+ },
919
+ },
920
+ },
921
+ {
922
+ aliases,
923
+ breakpoints: {
924
+ md: 768,
925
+ },
926
+ },
927
+ );
928
+
929
+ export function Notification() {
930
+ return (
931
+ <div className={notification.classname}>
932
+ Saved successfully
933
+ <div className="actions">Actions</div>
934
+ </div>
935
+ );
936
+ }
937
+ ```
938
+
939
+ ## Author
940
+
941
+ <table>
942
+ <tr>
943
+ <td>
944
+ <img src="https://raw.githubusercontent.com/devnax/devnax/main/me-circle-200.png" alt="devnax" width="100" height="100">
945
+ </td>
946
+ <td>
947
+ <strong>Naxrul Ahmed</strong><br>
948
+ <a href="https://github.com/devnax">GitHub Profile</a><br>
949
+ <a href="https://www.npmjs.com/~devnax">npm Profile</a><br>
950
+ <a href="https://github.com/devnax/open-source">Open Source Projects</a>
951
+ </td>
952
+ </tr>
953
+ </table>
954
+
955
+ <h2>Where to find me</h2>
956
+
957
+ <p><a target="_blank" href="mailto:devnaxrul@gmail.com"><img src="https://img.shields.io/badge/-Email-05122A?style=for-the-badge&logo=gmail&logoColor=white&color=orange" alt="Email" /></a>
958
+ <a target="_blank" href="https://twitter.com/devnaxx"><img src="https://img.shields.io/badge/twitter-x?style=for-the-badge&logo=x&logoColor=white&color=%230f1419" alt="Twitter" /></a>
959
+ <a target="_blank" href="https://www.linkedin.com/in/devnax"><img src="https://img.shields.io/badge/linkedin-logo?style=for-the-badge&logo=linkedin&logoColor=white&color=%230a77b6" alt="LinkedIn" /></a>
960
+ <a target="_blank" href="https://www.facebook.com/devnax"><img src="https://img.shields.io/badge/facebook-logo?style=for-the-badge&logo=facebook&logoColor=white&color=%230866ff" alt="Facebook" /></a>
961
+ <a target="_blank" href="https://www.instagram.com/devnaxx"><img src="https://img.shields.io/badge/instagram-logo?style=for-the-badge&logo=instagram&logoColor=white&color=%23F35369" alt="Instagram" /></a></p>