wee-framework

Wee is a lightweight front-end framework for logically building complex, responsive web projects.

Features

Mobile-first CSS framework with configurable reset and mixin library ~ 3KB gzip

• Central configuration for style normalization
• Feature toggling to minimize build size
• Structured breakpoints to organize responsive logic
• Print styling to generate print-optimized pages

JavaScript toolset to build scalable, organized client logic ~ 15KB gzip

• Foundation of utilities, helpers, and controller structure
• Chainable DOM traversal and manipulation with familiar API
• Animation methods to tween CSS attributes and properties
• Touch support for directional swipe events
• Routing library to flexibly associate endpoints to actions
• Event handling to bind actions to elements
• Data loading for Ajax and JSON interaction
• HTML5 history and PJAX helper to create dynamic experiences
• Template rendering to parse complex data structures
• Data binding to sync data models to the DOM
• Resource loading for JavaScript, CSS, and images
• Breakpoint watching for efficient media query callbacks

JSON-configured build process to compile, optimize, and minify your project

• Built-in server for local static development
• Live reloading of assets and markup
• Ghost mode to mirror actions across multiple browsers
• Static site generator perfect for living style guides
• Sourcemap output to line match unminified JavaScript
• Validation of JavaScript against JSCS and JSHint rules

Structured foundation of markup, icons, and supporting files

Examples

Here are a few basic examples. There's much more so check out the documentation.

Mixins →

Improved organization and readability using Less along with Wee's powerful mixin library.

<nav class="nav" role="navigation">
    <a href="/about" class="nav__link">About</a>
    <a href="/contact" class="nav__link -is-active">Contact</a>
</nav>

.nav {
    &__link {
        .font(@headingFont; 1.2);
        .spaced-block(1);
        .uppercase();
        &:hover {
            .background(dark; 5%);
        }
        &.-is-active {
            .border(bottom; @primary);
        }
    }
}

Becomes...

.nav__link {
    font-family: Lato, sans-serif;
    font-size: 1.2rem;
    display: block;
    margin-bottom: 1rem;
    text-transform: uppercase;
}
.nav__link:hover {
    background-color: rgba(0, 0, 0, .05);
}
.nav__link.-is-active {
    border-bottom: 1px solid #349bb9;
}

Core →

There are a couple dozen useful features and utilities in the core script. For instance, you can handle environment detection, loop through selections, serialize objects, and observe data models.

$.env({
    prod: 'www.domain.com',
    test: 'dev.domain.com'
});
 
$.env(); // "local"

$.observe('user.status', function(data, type, diff) {
    // Trigger logic
}, {
    diff: true,
    once: true,
    val: 'active'
);
 
$.set('user.status', 'active');

DOM →

Familiar chainable API and pre-cached references make DOM interaction quick and easy.

<button data-ref="element">Button</button>

$('ref:element').addClass('-is-active')
    .attr('aria-selected', 'true');

Controllers →

Controllers along with the automated build process create well-organized projects. There are public and private objects with constructors, destructors, and other helpful components.

Wee.fn.make('controllerName', {
    /**
     * Set public variable and execute init method
     *
     * @constructor
     */
    _construct: function() {
        this.publicVariable = 'Public Variable';
        this.init();
    },
    
    /**
     * Call a private method with an argument
     */
    init: function() {
        this.$private.privateMethod('varName');
    }
}, {
    /**
     * Return the provided argument
     *
     * @param {string} key 
     * @returns {string} 
     */
    privateMethod: function(key) {
        return key;
    }
});

Routing →

Create independence between markup and script using the powerful routing options. There are some helpful built-in filters and custom filters can also also be registered.

Wee.routes.map({
    '$any:once': 'common', // Fire the init method of the common controller
    '$root': 'home',
    '$root:unload': 'home:unload',
    'category': {
        '$root': 'controllerName:publicMethod',
        '$slug': {
            '$root': function() {
                console.log('Category index');
            },
            '$num': function(id) {
                console.log('Product ID is ' + id);
            }
        }
    }
});

Templating →

The template parser supports fallbacks, loops, helpers, partials, and more. It also powers the static site generator and data-binding apps.

Wee.view.render('My name is {{ firstName }}{{ #lastName|notEmpty }} {{ lastName }}{{ /lastName }}', {
    firstName: 'John',
    lastName: 'Smith'
});

Becomes...

"My name is John Smith"

Apps →

Wee includes a powerful application framework for one-way data-binding. Simply call into one of the many data manipulation methods to update your model and watch the DOM update automatically.

var app = Wee.app.make('testApp', {
    view: 'ref:application',
    model: {
        key: 'value'
    }
});
 
app.$set('key', 'new value');

Breakpoints →

Seamlessly combine and trigger breakpoint logic based on configured project media queries. Events can be setup to watch, initially fire, trigger only once, and more.

Wee.screen.map([
    {
        size: 1,
        callback: [
            'common:mobile', // Fire the mobile method of the common controller
            'common:smallScreen'
        ]
    },
    {
        min: 3,
        max: 4,
        watch: false,
        callback: 'common:mediumScreen'
    },
    {
        min: 5,
        once: true,
        callback: function(obj, val) {
            console.log(val); // varName
            console.log(obj);
        }
    }
]);

Events →

Create organized interaction on your page with the simple event API. Custom events can also be registered as they are with the core Wee touch events.

Wee.events.on('ref:element', 'click swipeRight', function(e, el) {
    // Event logic
    e.preventDefault();
}, {
    delegate: '.js-selector',
    once: true
});

Requests →

Submit any type of request with a number of callback options. Supports advanced features like custom headers and JSONP handling.

Wee.data.request({
    url: '/login',
    method: 'post',
    json: true,
    data: {
        username: '[e-mail]',
        password: 'pass123'
    },
    success: function(data, xhr) {
        // Success logic
    },
    error: function(xhr) {
        // Failure logic
    }
});

Asset Loading →

Load what you need on demand to optimize page speed and preserve bandwidth. Assets can be grouped and checked against later for advanced usage.

Wee.assets.load({
    root: 'https://cdn.weepower.com/assets/alert/',
    files: [
        'close.svg',
        'style.min.css',
        'script.min.js'
    ],
    success: function() {
        // Success logic
    },
    error: function() {
        // Failure logic
    }
});

Animation →

Tween attributes and properties with granular control and callback functionality. Custom easing function can be registered for granular control of the motion.

Wee.animate.tween('ref:element', {
    height: 100,
    width: 200
}, {
    duration: 200,
    ease: 'custom',
    complete: function() {
        // Completion logic
    }
});

History →

Create dynamic experiences through partial Ajax loading and the HTML5 History API. With one method static navigation can transform into a seamless, efficient user flow.

Wee.history.init({
    bind: true,
    scrollTop: '.heading',
    partials: 'title, main, .heading',
    request: {
        success: function(data, xhr) {
            // Success logic
        },
        error: function(xhr) {
            // Failure logic
        }
    },
    complete: function(obj) {
        // Complete logic
    }
});

Get Started

• Install the Wee CLI by running npm install -g wee-cli

Then create a new Wee project using one of these methods:

• Download the latest release
• Clone the repository using git clone git://github.com/weepower/wee.git
• Install with npm by running npm install wee-framework

Now run npm install from the project root to install the build dependencies followed by wee to launch it.

Node.js 4.4+ is recommended for the build process.

Compatibility

Wee officially supports the following minimum browser versions:

Chrome	Edge	Firefox	IE	Safari
30	20	29	9	7.1

Bugs

Have a bug or a feature request? Open a new issue.
To view the working to-do list check out our public Trello board.

Automated testing generously provided by BrowserStack.

Versioning

Wee adheres to Semantic Versioning in the form of MAJOR.MINOR.PATCH.
Regardless of version we recommend thoroughly reviewing the release notes before updating.

Community

Keep track of development and news by following @weecss on Twitter.

License

Copyright 2016 Caddis Interactive, LLC. Licensed under the Apache License, Version 2.0.