1 | [![version](https://img.shields.io/npm/v/bss.svg)]() [![gzipped](http://img.badgesize.io/porsager/bss/master/bss.js.svg?compression=gzip&label=gzipped)]() [![license](https://img.shields.io/github/license/porsager/wright.svg)]()
|
2 |
|
3 | ## 🎨 `bss`
|
4 |
|
5 | A simpler way to do CSS in Javascript directly on the elements you're styling.
|
6 |
|
7 | `bss` allows you to write your styles directly on the element where they matter using plenty of fun constructors.
|
8 |
|
9 | - [CSS Strings](#css-strings)
|
10 | - [Lean Strings](#lean-strings)
|
11 | - [JS Objects](#js-objects)
|
12 | - [Functions](#functions)
|
13 | - [Helpers](#helpers)
|
14 |
|
15 | Any group of definitions are resolved once one of the following properties are accessed / called
|
16 |
|
17 | - [`.style` Returns a Javascript style object ](#style)
|
18 | - [`.class` Returns a class name](#class)
|
19 | - [`.valueOf() or '' +` returns '.' + b.class](#tostring)
|
20 |
|
21 | ## Installation
|
22 |
|
23 | Using npm
|
24 | ``` bash
|
25 | npm install bss -S
|
26 | ```
|
27 |
|
28 | Require from CDN
|
29 | ``` html
|
30 | <script src="https://unpkg.com/bss"></script>
|
31 | ```
|
32 |
|
33 | Or download and include - [download bss.js](https://unpkg.com/bss/bss.js)
|
34 |
|
35 |
|
36 | ## Example usage
|
37 |
|
38 | Here's a quick example of using bss together with [mithril](https://github.com/mithriljs/mithril.js) - see the example [live here](https://flems.io/#0=N4IgtglgJlA2CmIBcBWFA6AzCgNCA9gK4AuADicsQE6Hx4DO8CAxsfFMiOgFb0h4AzCAj5IA2qAB2AQzCIkXXvxDN8ktus4JiAAjU6AvDuq0AOpPNh0YIuoAUUfM0Jz16AEb4oATxw7g5jo6AG4Q8ADuSCGSXvCGAHw6YHYA5AAWAIwpOgDUOu4ezKlU7CkAlOhFKeFpEGzl6AL0dpgATBXE0qnM8OrwVOV+AZJBQfTE3ghRBe5F+gBk8zopAOYlvQ3jk3SBo2rMsBDMANZRdmUJeiNGAIRquwC+fikAEkyw+Drh+FSwUOXmB5lEAPAC6eEOkmOogkIEIv04aWIZHoSAA9GjCJJSMcVpV8GA0ZBiGkqMIAAIZdBUzDKCakeQgJR4UjSYjMNLwGFiDJ4dgASUkUHgAA9TCBlLsdModAAfWU6NnUfgZABsOFaAAYcJhMGrMDq9arMOCeXhWOxxTpFjK7FKgjLgjFhegODg1RqACyGjIATgNur9JpwZpAxAgwXgAFEEK5iOYZaMgvLorFXQT0KySuoY-A44YDEYdAASRzMdDSVgR6Ox3rxkajMoJvCmYgPcytgRYqtqfitb0ADgA7IbWnrR3rQaCnqB4bBEcjSKiMVicXjVIT3PQ+Hh6YylGCHkA)
|
39 |
|
40 | ``` js
|
41 | // Some js file
|
42 | import b from 'bss'
|
43 | import m from 'mithril'
|
44 |
|
45 | let on = true
|
46 |
|
47 | m.mount(document.body, {
|
48 | view: vnode => m('h1' + b.bc('red').c('white').fs(32).ta('center'), {
|
49 | style: b.bc(on && 'green').style,
|
50 | onclick: () => on = !on
|
51 | }, 'Hello world')
|
52 | })
|
53 | ```
|
54 |
|
55 | Creates the following in the dom, which toggles the style attribute on click.
|
56 | ``` html
|
57 |
|
58 | <style>
|
59 | .bdp4f3o1 {
|
60 | background-color: red;
|
61 | color: white;
|
62 | font-size: 32px;
|
63 | }
|
64 | </style>
|
65 |
|
66 | <body>
|
67 | <h1 class="bdp4f3o1" style="background:green;">Hello world</h1>
|
68 | </body>
|
69 | ```
|
70 |
|
71 | ## Ways of writing CSS
|
72 |
|
73 | In the spirit of Javscript - `bss` Allows you to write the same thing in many different ways.
|
74 |
|
75 | ### CSS Strings
|
76 |
|
77 | ``` js
|
78 | b`
|
79 | background-color: black;
|
80 | text-align: center;
|
81 | `
|
82 | .$hover(`
|
83 | background-color: red;
|
84 | `)
|
85 | ```
|
86 |
|
87 | ### Lean Strings
|
88 | ``` js
|
89 | b`
|
90 | background-color black
|
91 | text-align center
|
92 | `
|
93 | .$hover`
|
94 | background-color red
|
95 | `
|
96 | ```
|
97 |
|
98 | ### JS Objects
|
99 |
|
100 | ``` js
|
101 | b({
|
102 | backgroundColor: 'black',
|
103 | textAlign: 'center',
|
104 | $hover: {
|
105 | backgroundColor: 'red'
|
106 | }
|
107 | })
|
108 | ```
|
109 |
|
110 | ### Functions
|
111 |
|
112 | ``` js
|
113 | b.backgroundColor('black')
|
114 | .textAlign('center')
|
115 | .$hover(
|
116 | b.backgroundColor('red')
|
117 | )
|
118 | ```
|
119 |
|
120 | ## Output
|
121 |
|
122 | ### `.class`
|
123 |
|
124 | The `.class` getter closes the current style description, creates a class name, adds the styles to a stylesheet in `<head>` and returns the class name
|
125 | ``` js
|
126 | b.textAlign('center').class // Returns eg. bdp4f3o1
|
127 | ```
|
128 |
|
129 | ### `.style`
|
130 |
|
131 | The `.style` getter also closes the current style description and return a JS object with the styles
|
132 | ``` js
|
133 | b.textAlign('center').style // Returns { textAlign: 'center' }
|
134 | ```
|
135 |
|
136 | ### `valueOf()`
|
137 |
|
138 | `.valueOf()` will be called if b is used like `'div' + b` because javascript casts automatically using `.valueOf()`.
|
139 | Casting `b` to a string will call `.class` and prepend a period for easy use in vdom libraries.
|
140 | ``` js
|
141 | 'div' + b.textAlign('center') // Returns eg. div.bdp4f3o1
|
142 | ```
|
143 |
|
144 | You can also override `.valueOf` if you set classNames instead of selectors
|
145 | ```
|
146 | b.valueOf = function() { return this.class + ' ' }
|
147 |
|
148 | `<div class="${ b.textAlign('center') }`"></div>` // Returns eg. <div class="bdp4f3o1"></div>
|
149 | ```
|
150 |
|
151 | ## Short property names
|
152 |
|
153 | Short property names can also be used and are the acronyms of full css properties with collisions [handpicked by popularity](lib/popular.js)
|
154 |
|
155 | ``` js
|
156 | b.bc('black')
|
157 | .ta('center')
|
158 | .$hover(
|
159 | b.bc('red')
|
160 | )
|
161 | ```
|
162 |
|
163 | ## `.helper`
|
164 |
|
165 | Define your own helpers to work in a fashion similar to tachyons, or simply to make your life easier.
|
166 |
|
167 | Tachyon style helpers
|
168 | ``` js
|
169 | b.f1.p1 // { font-size: '3rem'; padding: '0.25rem'; }
|
170 |
|
171 | // Created like this:
|
172 | b.helper('f1', b.fontSize('3rem'))
|
173 | b.helper('p1', b.padding('0.25rem'))
|
174 |
|
175 | // Or like this:
|
176 | b.helper{
|
177 | f1: b.fontSize('3rem'),
|
178 | p1: b.padding('0.25rem')
|
179 | })
|
180 | ```
|
181 |
|
182 | Helpers can also take values like this:
|
183 |
|
184 | ``` js
|
185 | b.size('100%').align('center') // Fills an element in it's parent and centers all children on both axes.
|
186 |
|
187 | // Created like this:
|
188 | b.helper('size', (width, height) =>
|
189 | b.width(width).height(height || width)
|
190 | )
|
191 |
|
192 | b.helper('align', (x, y) =>
|
193 | b.display('flex').justifyContent(x).alignItems(y || x)
|
194 | )
|
195 | ```
|
196 |
|
197 | They can even be easy to use media query groupers like this:
|
198 |
|
199 | ```js
|
200 | b.desktop(
|
201 | b.fontSize(128)
|
202 | )
|
203 |
|
204 | // Equally valid is
|
205 | b.desktop(`
|
206 | fs 128
|
207 | `)
|
208 |
|
209 | // Created like this:
|
210 | b.helper('desktop', style => b.$media('(min-width:801px)', style))
|
211 | ```
|
212 |
|
213 | ## Pixel values and Numbers
|
214 |
|
215 | Properties accepting pixel values will automatically have `px` added if a number type is passed.
|
216 |
|
217 | ```
|
218 | b.fontSize(32) // font-size: 32px;
|
219 | b.width(200) // width: 200px;
|
220 | ```
|
221 |
|
222 | ## `.$hover` :pseudo selectors
|
223 |
|
224 | All of the different css pseudo selectors normally used with a colon `:` is added with the dollor `$` for ease of use in js.
|
225 |
|
226 | ``` js
|
227 | b(`
|
228 | color: red;
|
229 | `).$hover(`
|
230 | color: blue;
|
231 | `)
|
232 |
|
233 | b.color('red').$hover(b.color('blue'))
|
234 | ```
|
235 |
|
236 | ## `.$nest` nested selectors
|
237 |
|
238 | Targeting nested children is sometimes useful, and is done by using `$nest` and supplying the first argument with a regular child css selector, and then supply styling as the second argument for that selector.
|
239 |
|
240 | ``` js
|
241 | b.color('red').$nest('li', b.color('blue'))
|
242 | b.color('red').$nest(':hover li', b.color('blue'))
|
243 | b.color('red').$nest('> &', b.margin(10))
|
244 | ```
|
245 |
|
246 | `&` is a placeholder for the generated class like in `sass/less`.
|
247 |
|
248 | ## `.$media` @media queries
|
249 |
|
250 | ``` js
|
251 | b.color('red').$media('(max-width: 600px)', b.color('blue'))
|
252 | ```
|
253 |
|
254 | ## `.$keyframes` @keyframes
|
255 |
|
256 | Animation in CSS is usually a mixture of `transition` and `animation / @keyframes`. `Transition` is handled as usual css properties by `bss`, but `@keyframes` are a bit different.
|
257 |
|
258 | Creating a keyframe animation is done using `b.$keyframes` and will return a generated name for the animation specified.
|
259 |
|
260 | ```js
|
261 | const fadeIn = b.$keyframes({
|
262 | from: b.o(0).style,
|
263 | to: b.o(1).style
|
264 | })
|
265 |
|
266 | // To use the animation do:
|
267 | b.animation(fadeIn + ' 1s')
|
268 | ```
|
269 |
|
270 | ## `.$animate`
|
271 |
|
272 | Often it might not be necessary to consider the animation name so a built in helper method called `$animate` comes in handy. It takes a regular animation shorthand value as the first argument, excluding the animation name. The second parameter is the animation definition itself.
|
273 |
|
274 | ``` js
|
275 |
|
276 | b.$animate('1s linear', {
|
277 | from: b.o(0).style,
|
278 | to: b.o(1).style
|
279 | })
|
280 |
|
281 | ```
|
282 |
|
283 | ## `.css`
|
284 |
|
285 | A way to add regular css properties to a selector and prepend to the generated stylesheet
|
286 |
|
287 | ```
|
288 | b.css('html', b.boxSizing('border-box'))
|
289 | b.css('*, *:before, *:after', b.boxSizing('inherit'))
|
290 | ```
|
291 |
|
292 | ## `.setDebug`
|
293 |
|
294 | Since chrome dev tools doesn't allow changing styles applied using CSSOM you can activate debugging mode which doesn't apply the styles using CSSOM.
|
295 |
|
296 | ```
|
297 | b.setDebug(true)
|
298 | ```
|
299 |
|
300 | The only caveat here is that animations and applied styles can result in small quicks like blinking fonts and styles.
|
301 |
|
302 | ## Browser support
|
303 | `bss` is tested and works in ie9+ and the other major browsers.
|
304 | > TODO - Create browser support table
|
305 |
|
306 | ### Prefixes
|
307 | When using `bss` in the browser it automatically adds only the necessary prefixes, so you can go ahead and use the raw property and expect it to work in browsers that only has the prefixed version.
|
308 |
|
309 | Prefixes for css property values like `linear-gradient` are not supported yet.
|
310 |
|
311 |
|
312 | ## Server support
|
313 | > TODO - If using it on the server you can specify the prefixes that you'd like to be generated when generating the css.
|