Naivete Precedes Misrepresentation

    jile

    2.0.4 • Public • Published

    jile

    Manage your styles in JavaScript with the full power of CSS.

    Table of contents

    Installation

    $ npm i jile --save
    

    Usage

    For those that have used both CSS Modules and inline styles, this should feel quite natural.

    import jile from 'jile';
     
    // create your styles as a plain object, with the CSS selector as the keys
    const styles = {
      '.foo': {
        display: 'inline-block'
      },
      '@media print': {
        '.bar': {
          display: 'none'
        }
      }
    };
     
    // optionally provide object of options for the generation of the jile
    const options = {
      id: 'my-custom-id'
    };
     
    // the jile instance returned will have metadata, such as the css, selectors, and the tag injected 
    const j = jile(styles, options);
     
    // usually you just want the selectors so you can use them in your view
    const selectors = j.selectors;
     
    const ExampleComponent = () => {
      return (
        <div className={selectors.foo}>
          I have a scoped class Selector!
        </div>
      );
    };

    With output of:

    <div class="jile__foo__2202820774">
      I have a scoped class selector!
    </div>

    This example uses React, but you can use it with anything as it has no dependencies on a particular view library or framework.

    How it works

    Any styles that you declare in the object passed to the jile function are parsed, scoped, autoprefixed, and converted into CSS which is injected into the head of the document as a <style> tag. Scoping entails hashing selectors (only ID and Class selectors will be hashed) so that you can use the same selector (such as .container) in many components without worrying about specificity or collision. The return from the jile function is a map of the selector names you provided to their respective hashed output names.

    Why

    ...not inline styles?

    Inline styles have become popular again for a reason ... everything is in JavaScript so it is dynamic, specificity is not a concern, and prefixing is handled easily, without the need for proprietary method calls (Compass, for example). That said, inline styles can only provide a limited subset of CSS ... @media queries, @keyframes, psuedo-selectors, etc. are all unable to be done with pure inline styles. Libraries like Radium help with some of these aspects, but it still is incomplete.

    ...not CSS Modules?

    CSS Modules solve the main problem that CSS has ... global everything. A lot of jile concepts are taken from CSS Modules, because you can leverage the full power of CSS while still scoping things to your component. That said, CSS adds another piece to your build process (more dependencies), and now requires consumers of your component to include a second reference (one for your JS, one for your CSS).

    ... not both?

    This is the objective of jile, to combine the flexibility and power of CSS with the implementation simplicity of JS. It leverages a (hopefully) familiar syntax to make transitioning from styles to jiles quick and painless.

    Options

    The following values can be passed in the options object as the second parameter to jile:

    {
        // should the tag be mounted upon creation | optional, defaults to true
        autoMount: Boolean,
        
        // should the selectors be hashed | optional, defaults to true
        hashSelectors: Boolean,
        
        // custom ID for the tag | optional, defaults to 'jile-stylesheet-{#}'
        id: String, 
        
        // should the CSS be minified | optional, defaults to true when in production, false otherwise
        minify: Boolean,
        
        // should the CSS have a sourceMap | optional, defaults to false when in production, true otherwise
        sourceMap: Boolean
    }

    Nested styles

    Use the & before your child declarations to inherit from the parent.

    const styles = jile({
      '.parent': {
        color: '#333',
        fontSize: 32,
        
        '& .child': {
          color: '#777',
          fontSize: 14
        },
        
        '& > button::before': {
          content: '"I am a pseudo-element!"',
          display: 'block'
        }
      }
    });

    Creates the following output:

    .jile__parent__2351223888 {
      color: #333;
      font-size: 32px;
    }
    .jile__parent__2351223888 .jile__child__5403038 {
      color: #777;
      font-size: 14px;
    }
    .jile__parent__2351223888 > button::before {
      content: "I am a pseudo-element!";
      display: block;
    }

    Namespaced declarations

    You can use all forms of @ rules ... @media, @keyframes, even @page.

    const styles = jile({
      '@media screen and (max-width: 1000px)': {
        '.parent': {
          animation: '2s bouncing infinite linear'
        }
      },
      '@keyframes bouncing': {
        '0%': {
          marginTop: 0
        },
        '50%': {
          marginTop: -20
        },
        '100%': {
          marginTop: 0
        }
      },
      '@media print': {
        '.parent': {
          display: 'none'
        }
      },
      '@page': {
        size: 'Letter portrait'
      }
    });

    However, if you wanted to consolidate it, any @media declaration will inherit from the parent it is declared in:

    const styles = jile({
      '.parent': {
        '@media screen and (max-width: 1000px)': {
          animation: '2s bouncing infinite linear'
        },
        '@media print': {
          display: 'none'
        }
      }
      '@keyframes bouncing': {
        '0%': {
          marginTop: 0
        },
        '50%': {
          marginTop: -20
        },
        '100%': {
          marginTop: 0
        }
      },
      '@page': {
        size: 'Letter portrait'
      }
    });

    Both will produce the same CSS.

    @font-face declarations include a little magic, as the "bulletproof font face" rule requires a double-declaration of the src attribute.

    const fontFaceStyles = jile({
        '@font-face': {
            fontFamily: 'WebFont',
            src: 'url("webfont.eot?#iefix") format("embedded-opentype"), url("webfont.woff2") format("woff2"), ' +
               'url("webfont.woff") format("woff"), url("webfont.ttf") format("truetype"), ' +
               'url("webfont.svg#svgFontName") format("svg")'
        }
    });

    Creates the following output:

    @font-face {
        font-family: WebFont;
        src: url("webfont.eot");
        src: url("webfont.eot?#iefix") format("embedded-opentype")url("webfont.woff2") format("woff2")url("webfont.woff") format("woff")url("webfont.ttf") format("truetype")url("webfont.svg#svgFontName") format("svg");
    }

    The injected .eot above the regular declaration is only if you provide an .eot in the provided object as one of the src values, as the injected declaration is for IE9 compat mode where as the #iefix declaration is for standard IE.

    Global selectors

    Sometimes you want to mix your scoped styles with your global styles, and you can easily do that with the :global() wrapper.

    const styles = jile({
        ':global(.unhashed-selector).hashedSelector': {
            display: 'block'
        }
    });

    Creates the following output:

    .unhashed-selector.jile__hashedSelector__12527111 {
        display: block;
    }

    Global stylesheets

    You can create global stylesheets too! You get the same output, just minus the hashing.

    const globalStyles = {
        '.container': {
            height: '100vh'
        }
    };
     
    const options = {
        hashSelectors: false
    };
     
    jile(globalStyles, options);

    Creates the following output:

    .container {
        height: 100vh;
    }

    Prefixing

    All prefixing is handled by inline-style-prefixer automatically, however if you want to customize the usage of the built-in prefixer, you can with the setPrefixer method.

    jile.setPrefixer({
      userAgent: 'Mozilla/5.0 (Android 4.4; Mobile; rv:41.0) Gecko/41.0 Firefox/41.0'
    });

    If you going to customize the prefixer, it is advised you do before creating any stylesheets with it. The options passed to it are the same as the options passed to a new Prefixer() constructor in inline-styles-prefixer, so consult their documentation for the options available.

    Managing a jile sheet

    The object that is returned when you create a jile has several methods for you to manage the tag if you so choose.

    • jileObject.add() will add the tag to the document.head if it is not already there
    • jileObject.remove() will remove the tag from the document.head if it is there
    • jileObject.isMounted() will return a boolean value for whether the jile tag is currently in the DOM or not
    • jileObject.delete() will run jileObject.remove() and also delete it from the cache of object

    Development

    Pretty standard stuff, pull down the repo and npm i. There are some built-in scripts:

    • build = runs webpack to build dist/jile.js
    • build:minified = runs webpack to build dist/jile.min.js
    • clean => runs rimraf to remove lib and dist folders
    • lint => runs eslint on all files in src
    • prepublish:compile = runs clean, lint, test, transpile, build, and build:minified scripts
    • start = runs example app on localhost:3000 (it's a playground, have fun)
    • test = runs AVA test scripts
    • test:timed runs test, but outputs completion times for each test
    • test:watch runs test, but with persistent watcher
    • transpile = transpiles files in src to lib

    Happy jiling!

    Install

    npm i jile

    DownloadsWeekly Downloads

    4

    Version

    2.0.4

    License

    MIT

    Unpacked Size

    666 kB

    Total Files

    20

    Last publish

    Collaborators

    • planttheidea