Improvements and documentation.

README.md

@@ -1,22 +1,307 @@
 # RunCSS
 
-RunCSS is a runtime version of TailwindCSS. It has no build. RunCSS provides all the same CSS utility class names that we know and love from TailwindCSS.
+[RunCSS, A Runtime Version of TailwindCSS and Beyond](https://dev.to/mudgen/runcss-a-runtime-version-of-tailwindcss-5dic)
 
-RunCSS is batteries included. It has feature parity with TailwindCSS and beyond. RunCSS defaults are the same as TailwindCSS defaults plus TailwindCSS's [additional variants](https://tailwindcss.com/docs/configuring-variants). By default all variants such as hover, active, visited, group-hover etc. and responsive variants such as sm, lg etc work with all class names.
+RunCSS is a runtime version of TailwindCSS. It has no build. RunCSS provides all the same CSS utility class names that we know and love from TailwindCSS. 
+
+RunCSS is batteries included. It has feature parity with TailwindCSS and beyond. RunCSS defaults are the same as TailwindCSS defaults plus TailwindCSS's [additional variants](https://tailwindcss.com/docs/configuring-variants), plus more. By default all variants such as `hover`, `active`, `visited`, `group-hover` etc. and responsive variants such as `sm`, `lg` etc work with all class names.
 
 RunCSS is possible because it is a Javascript file that generates CSS at runtime.
 
-The tradeoff to using RunCSS is a small amount of Javascript execution to generate CSS at runtime. The necessary CSS is generated once for each class name when it is first encountered. CSS is only generated for class names that are actually used.
+> The primary difference between TailwindCSS and RunCSS is that TailwindCSS generates CSS at build time and RunCSS generates CSS at runtime.
 
-# Installation
+RunCSS has no build. Just use it. Off to the races!
 
-Add a CSS reset or base CSS file, such as TailwindCSS's preflight, to your web application:
+The tradeoff to using RunCSS is a small amount of Javascript execution to generate CSS at runtime. The necessary CSS for each class name is generated one time as it is encountered. CSS is only generated for class names that are actually used. 
 
-```
+### How to use RunCSS
+
+__Step 1.__ Add a CSS reset or base CSS file, such as TailwindCSS's [preflight](https://unpkg.com/tailwindcss@%5E1/dist/base.css), to your web application:
+```html
 <link href="https://unpkg.com/runcss@^0/dist/preflight.css" 
 rel="stylesheet">
 ```
+__Step 2.__ Import the RunCSS Javascript file into your application:
+```javascript
+import processClasses from 'https://unpkg.com/runcss@^0/dist/runcss.modern.js'
+```
+__Step 3.__ Call the `processClasses` function on CSS class names. It is possible to integrate RunCSS into existing Javascript libraries so that `processClass` is called automatically when CSS class names are used. RunCSS ignores class names it has already generated CSS for so `processClasses` can be called repeatedly on the same class names.
+### Example
+Here is an example that integrates RunCSS with [Webscript](https://mudgen.github.io/webscript/docs/) and creates the same card example given on TailwindCSS's homepage:
+
+```javascript
+// Importing Webscript
+import builders from 'https://unpkg.com/webscript@^0/dist/webscript.modern.js'
+import createDOMElement from 'https://unpkg.com/webscript@^0/dist/createDOMElement.modern.js'
+// Importing RunCSS
+import processClasses from 'https://unpkg.com/runcss@^0/dist/runcss.modern.js'
+
+// Integrating RunCSS with Webscript
+function createElement (type, props, ...children) {
+  if (props.class) {
+    processClasses(props.class)
+  }
+  return createDOMElement(type, props, ...children)
+}
+
+// Create the builders used to build DOM elements
+const { div, img, h2 } = builders(createElement)
+
+// Card display
+const card =
+  div.class`md:flex bg-white rounded-lg p-6`(
+    img.class`h-16 w-16 md:h-24 md:w-24 rounded-full mx-auto md:mx-0 md:mr-6`.src`./avatar.jpg`,
+    div.class`text-center md:text-left`(
+      h2.class`text-lg``Erin Lindford`,
+      div.class`text-purple-500``Customer Support`,
+      div.class`text-gray-600``[email protected]`,
+      div.class`text-gray-600``(555) 765-4321`))
+```
+
+Here is the result of the above code:
+![Result of above code](https://dev-to-uploads.s3.amazonaws.com/i/zfjfxvjwg96y8njyo5wl.png)
+
+## RunCSS File Size
+
+[runcss.modern.js](https://github.com/mudgen/runcss/blob/master/dist/runcss.modern.js) is 8kb compressed and 20kb raw. It has no dependencies.
+
+## Optional Node.js Package
+
+RunCSS can optionally be installed like this:
+```shell
+npm install runcss
+```
+
+## Going Beyond TailwindCSS
+
+Because RunCSS doesn't have build-time constraints it can easily go beyond TailwindCSS and it does. RunCSS provides all the same utility CSS class names that TailwindCSS does plus many more.
+
+For example, by default, TailwindCSS's margin classes have holes in them. There is `m-6`, but no `m-7`. There are no margin classes between `m-24` and `m-32`. The margin classes stop at `m-64`. With TailwindCSS it is possible to plug these holes by manually adding configuration to the TailwindCSS build configuration file. RunCSS doesn't require configuration and has no such holes and the class names don't end. RunCSS includes `m-65` and `m-66` and so on forever or until the browser can't take it anymore.
+
+But there is more. RunCSS accepts any valid CSS length unit in many class names. For example, you could use `m-5%` or `m-1.25rem` or `m-25px` or whatever valid CSS length unit you want to use.
+
+One of the benefits of using utility classes is "designing with constraints". It is easier to build consistent visual designs if you pick your styles from a limited set. With RunCSS this can be done by convention and enforced, if desired, by a linter. In addition with RunCSS you can go outside your design system in special cases where you need maximum control.
+
+Many of the following sections show RunCSS's extended capabilities.
+
+## Configuration
+RunCSS provides the `configure` function that can be used to configure parts of RunCSS. The following sections in this article that can use `configure` show how to use it.
+
+## Colors
+RunCSS provides the same [default color palette](https://tailwindcss.com/docs/customizing-colors#default-color-palette) as TailwindCSS.
+
+These colors can be used in all the same class names as can be used in TailwindCSS. They can be used in text, borders, placeholders, divides, and backgrounds.
+
+### Color Example:
+```javascript
+// Using Webscript with RunCSS
+div.class`bg-blue-500 border-3 border-yellow-700`(
+  p.class`text-white``Example Colors`
+)
+```
+Did you know that CSS specifications and browsers support [150 color keywords](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)? RunCSS supports them all too. From `black` to [rebeccapurple](https://codepen.io/trezy/post/honoring-a-great-man).
+
+RunCSS supports all valid CSS color formats. For example hex, rgb/rgba and hsl/hsla formats
+
+Here is an example that uses various color formats:
+```javascript
+div.class`bg-rebeccapurple border-10 border-rgba(200,10,10,0.1)`(
+  p.class`text-hsl(120,100%,60%) xl:text-#ecc94b``Example Colors`
+)
+```
+> *Note: Make sure there are no spaces in your class names because class names are separated by spaces.*
+
+It is possible to make your own color palette by configuring colors with the `configure` function. You can create your own color keywords.
+
+Here is an example that sets the 'blue' keyword to the color red and sets some banana colors:
+```javascript
+// import the configure function
+import processClasses, { configure } from 'https://unpkg.com/runcss@^0/dist/runcss.modern.js'
+
+// create our own color palette
+configure({
+  colors: {
+    blue: '#ff0000',
+    banana: {
+      100: '#FFFFF0',
+      200: '#FEFCBF',
+      300: '#FAF089'
+    }
+  }
+})
+```
+> Note that the CSS for these color classes is only generated if they are used.
+
+> Note that only hex values can be used in the `configure` function for colors.
+
+## Responsive Design
+
+Responsive design with RunCSS works the same way as it does with TailwindCSS. [Checkout Tailwind's documentation about it.](https://tailwindcss.com/docs/responsive-design/)
+
+By default RunCSS provides the same responsive breakpoints as TailwindCSS: 
+```javascript
+{ sm: '640px', md: '768px', lg: '1024px', xl: '1280px' }
+```
+
+Just like TailwindCSS all RunCSS classes can use the breakpoint prefixes without any configuration. __However, in addition, any CSS class not generated and coming from RunCSS can use them too!__
+
+For example, if you create your own CSS file with some custom CSS you don't have to create media queries for different breakpoints.  Just use the responsive prefixes from RunCSS.
+
+### Example
+
+Here is a custom CSS file. Notice there are no media queries for responsive versions of the class:
+```css
+.myclass {
+  margin: 0 10px;
+  background-color: red;  
+  border-radius: 0.5rem; 
+}
+```
+Go ahead and make it responsive by using RunCSS's responsive prefixes in your DOM building code:
+```javascript
+div.class`lg:myclass`(
+  p`Example text`
+)
+```
+RunCSS only generates CSS for responsive breakpoint classes that are used.
+
+### Configure Your Own Responsive Breakpoints
+
+You can set your own responsive breakpoints and prefixes by calling RunCSS's `configure` function. Here is an example:
+
+```javascript
+configure({
+  screens: { 
+    watch: '300px',
+    phone: '340px',      
+    tablet: '640px'
+   }
+})
+```
+> Note: Make sure you configure screens before you start processing CSS class names with `processClasses`.
+
+## Pseudo-Class Variants
+
+Pseudo-class variants like `hover`, `focus` etc. work with RunCSS class names the same way they do with TailwindCSS class names.
+
+TailwindCSS [provides a number of pseduo-class variants](https://tailwindcss.com/docs/pseudo-class-variants) that are not enabled by default due to file-size constraints. 
+
+RunCSS, not having build file-size constraints, has enabled, by default, all of TailwindCSS's pseudo-class variants.
+
+RunCSS only generates the needed CSS for the class names and variants that are actually used.
+
+By default, RunCSS also provides and has enabled all [psuedo-class](https://developer.mozilla.org/en-US/docs/Web/CSS/Pseudo-classes#Index_of_standard_pseudo-classes) and [psuedo-element](https://developer.mozilla.org/en-US/docs/Web/CSS/Pseudo-elements#Index_of_standard_pseudo-elements) variants that are supported by web browsers.
+
+Just like RunCSS responsive prefixes can be used by CSS class names from third-party CSS style sheets, RunCSS's psuedo-class and psuedo-element prefixes can be used by CSS class names from third-party CSS style sheets.
+
+### Example
+
+Here is a custom CSS file. Notice there are no psuedo-class versions of the class name:
+```css
+.myclass {
+  margin: 0 10px;
+  background-color: red;  
+  border-radius: 0.5rem; 
+}
+```
+Go ahead and apply a RunCSS pseudo-class prefix to it:
+```javascript
+div.class`hover:myclass`(
+  p`Example text`
+)
+```
+No configuration for pseudo-classes and pseudo-elements is needed because they are all available.
+
+## Extracting Components
+
+RunCSS provides the `component` function to create CSS components. This is a way to create your own CSS utilities or components using RunCSS class names and/or CSS properties.
+
+The `component(name, classNames, properties)` function takes three strings as arguments. The third argument is optional. 
+
+CSS will be generated using the last two arguments. 
+
+### Component Example
+```javascript
+import processClasses, { component } from 'https://unpkg.com/runcss@^0/dist/runcss.modern.js'
+
+component(
+  'btn', // new class name
+  'p-2 bg-blue text-white hover:text-green-500 text-base lg:text-lg', // extracting CSS from class names
+  'box-shadow: 0px 8px 15px rgba(0, 0, 0, 0.5); outline: none;' // using CSS properties
+)
+
+// Use the CSS component
+const button = button.class`btn text-yellow``Click Me`
+```
+RunCSS utility class names will override CSS components. This enables you to customize or specialize CSS components when they are used. 
+
+You can think of CSS components as default styles that can be overridden with utility classes.
+
+In the example above the `text-yellow` class overrides the `text-white` class that is defined in the CSS component.
+
+## Increasing Specificity with Important
+
+You can increase specificity of your RunCSS utilities by calling `configure` with `{important: true}`. That will add `!important` to RunCSS styles.
+
+If you want more specificity but less than `!important` then give the important option a selector. Like this: `{important: '#app'}`. And make sure that your RunCSS classes are added under an element with the 'app' id or whatever you specified.
+
+## Prefix
+
+It is possible to add a prefix to all RunCSS utilities by calling `configure` with a prefix option.
+
+Here is an example:
+```Javascript
+configure({ prefix: 'run-' })
+
+div.class`run-text-blue hover:run-text-yellow`(
+  p`My test`
+)
+```
+
+## Separator
+
+Instead of using `:` to separate variants such as `hover`, `sm`, `focus` and the rest you can use a different separator. Call `configure` with the `separator` option. Here is an example:
+
+```Javascript
+configure({separator: '$'})
+
+div.class`run-text-blue hover$run-text-yellow`(
+  p`My test`
+)
+```
+
+## No Build Movement
+
+RunCSS is another tool that's part of the No Build Movement.  
+
+The No Build Movement is a change in web development that favors building web applications without build tools except for minification of resources.
+
+## Project Home
+
+The RunCSS project can be found here:
+{% github mudgen/runcss %}
+
+[Follow me on twitter.](https://twitter.com/mudgen)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 
-Import the RunCSS Javascript file into your application:
 
 

docs/app.js

@@ -23,7 +23,10 @@ configure({
     tablet: '640px'
   }
 })
+
 */
+configure({ prefix: 'run-', separator: '&' })
+
 // Second Part
 function createElement (type, props, ...children) {
   if (props.class) {
@@ -59,7 +62,7 @@ const { body, div, p, ul, li, input, span, button } = builders((type, props, ...
 
 component(
   'btn',
-  'p-2 rounded bg-blue hover:text-green-500 text-base lg:text-lg',
+  'r-p-2 r-rounded r-bg-blue hover:r-text-green-500 text-base lg:text-lg',
   'box-shadow: 0px 8px 15px rgba(0, 0, 0, 0.5);outline: none;'
 )
 
@@ -71,6 +74,9 @@ component(
 
 const app =
   div.id`app`.class`mt-5 ml-1.7rem`(
+    div.class`run-text-blue hover&run-text-yellow`(
+      p`My test`
+    ),
     div.class`lg:myclass`(
       button.class`xl:btn text-green``Click Me`,
       button.class`btn text-yellow``Click Me`
@@ -80,7 +86,7 @@ const app =
       card
     ),
     ul(
-      li.class`pl-1.9em lg:pl-100 tracking-widest``hello`,
+      li.class`r-pl-1.9em lg:r-pl-100 r-tracking-widest``hello`,
       li.class`mt-30 text-pink-700 text-opacity-25``Great`,
       li.class`px-50 lg:hidden``fine`,
       li.class`px-5 text-pink-700``Another little test`,

src/runcss.js

@@ -902,7 +902,7 @@ function setRule (rule, sheet) {
     ruleCls = componentName
     sheetPrefix = 'custom'
   }
-  ruleCls = ruleCls.replace(/[.:()%,#]/g, '\\$&')
+  ruleCls = ruleCls.replace(/[.:()&@~*^$%,#]/g, '\\$&')
   if (config.important) {
     if (config.important === true) {
       rule = rule.replace(/;/g, '!important;') + '!important'