breakup 0.2.0 → 0.2.1

data/.gitignore

@@ -1 +1,2 @@
 *.gem
+.sass-cache

data/README.md

@@ -2,16 +2,217 @@ Breakup
 =======
 
 Breakup is a Sass component that allows you to create multiple CSS files from a
-single Sass partial by wrapping your code within breakpoint blocks. It
-allows you to abstract what your Sass partials folder looks like from what CSS
-files you create. Because of this you can easily create per-breakpoint CSS
-files (e.g. base, mobile, tablet and desktop) and fallback files where no
-styles are wrapped (e.g. for oldIE which does not support media queries).
+single Sass partial by wrapping your code within breakpoint blocks. It allows
+you to abstract what your Sass partials folder looks like from what CSS files
+you create. Because of this you can easily create per-breakpoint CSS files (e.g.
+base, mobile, tablet and desktop) and fallback files where no styles are wrapped
+(e.g. for oldIE which does not support media queries).
+
+
+## The Problem(s)
+
+The current trend towards OOCSS using Sass results in many small partials -- one
+per object. This is excellent for readability and reducing mental overhead until
+the complication of creating per-media query stylesheets, and oldIE stylesheets
+(where media queries are unsupported) appears. The simplest solution is to
+create even more partials named for each component's breakpoint (e.g.
+_component.scss & _component_wide.scss) but this results in a proliferation of
+partials which shall rapidly introduce noise to your partials folder.
+
+
+## Breakup's Solution
+
+Breakup allows you to write a single partial per object. By isolating each
+breakpoint's code inside a mixin block your output stylesheets can choose what
+blocks should be included within them and whether or not those blocks should
+even be wrapped inside a media query (for oldIE stylesheets you can serve the
+basic styles and the unwrapped wide styles so oldIE is given the wide view).
+
+
+## Installation
+
+Breakup is distributed as a Compass plugin (though it is written in pure SCSS,
+so works as a stand-alone file without a dependancy on Compass).
+
+* Run `gem install breakup` or add breakup to your Gemfile.
+* Add `require "breakup"` to the top of your compass.rb
+* Add `@import 'breakup';` to your base stylesheets
+
+Alternatively, if you don't want to be dependant upon Compass, you can copy
+[stylesheets/_breakup.scss](stylesheets/_breakup.scss) into your project and
+`@import` it from there.
+
+
+## Usage
+
+The following examples can also be found in the [examples/](examples) folder
+
+### Setup: Named Blocks & Breakpoints
+
+Blocks are chunks of SCSS to be output, they have arbitrary names. Breakpoints
+are blocks that have an attached media query that they shall be wrapped in.
+
+First of all identify where your major breakpoints shall be and define them as a
+list of lists (where the sub-list contains two items: the breakpoint name and
+its media query it represents):
+
+```SCSS
+// _global_variables.scss
+$breakup-breakpoints: (
+  'thin' '(max-width: 35.999em)',
+  'wide' '(min-width: 36em)',
+  'full' '(min-width: 61em)'
+);
+```
+
+Then in your component define the blocks and breakpoints that make up your
+component. In this example we want the 'basic' block to be output without any
+wrappers, but the 'wide' breakpoint shall be wrapped in an @media block.
+
+```SCSS
+// _component.scss
+@include breakup-block('basic') {
+  .component { background-color: red; }
+}
+
+@include breakup-breakpoint('thin') {
+  .component { background-color: blue; }
+}
+
+@include breakup-breakpoint('wide') {
+  .component { background-color: green; }
+}
+```
+
+### A Single Output File
+
+In your root scss file define what blocks should be rendered by defining the
+list `$breakup-included-blocks`:
+
+```SCSS
+// example_allblocks.scss
+@import 'breakup';
+$breakup-included-blocks: ('basic' 'thin' 'wide' 'full');
+
+@import 'partials/global_variables';
+@import 'partials/component';
+```
+
+This shall output:
+
+```CSS
+.component {
+  background-color: red;
+}
+
+@media (max-width: 35.999em) {
+  .component {
+    background-color: blue;
+  }
+}
+@media (min-width: 36em) {
+  .component {
+    background-color: green;
+  }
+}
+```
+
+
+### Per Media Query Blocks
+
+By changing `$breakpoint-included-blocks` we can change what boxes to include.
+To create a stylesheet that contains only our wide styles we can specify just
+the 'wide' block:
+
+
+```SCSS
+// example_wideonly.scss
+@import 'breakup';
+$breakup-included-blocks: ('wide');
+
+@import 'partials/global_variables';
+@import 'partials/component';
+```
+
+This shall output:
+
+```CSS
+@media (min-width: 36em) {
+  .component {
+    background-color: green;
+  }
+}
+```
+
+### Stripping Media Queries (for oldIE)
+
+OldIE doesn't understand media queries so we need to not wrap our breakpoints
+with an @media block, just output their contents as-is. This is controlled with
+`$breakup-naked` and `$breakup-breakpoints-allow-naked`. `$breakup-naked: true`
+tells breakup that it should not not wrap breakpoints up.
+`$breakup-breakpoints-allow-naked` is a list of breakpoints that should be
+output when `$breakup-naked` is true. By default this is empty and any
+breakpoints not specified shall be not be output, even if they are referenced in
+`$breakup-included-blocks`.
+
+```SCSS
+// example_oldie.scss
+@import 'breakup.scss';
+
+$breakup-included-blocks: ('basic' 'wide' 'full');
+$breakup-naked: true;
+$breakup-breakpoints-allow-naked: ('wide' 'full');
+
+@import 'partials/global_variables';
+@import 'partials/component';
+```
+
+This shall output:
+
+```CSS
+.component {
+  background-color: red;
+}
+
+.component {
+  background-color: green;
+}
+```
+
+### Tweakpoints
+
+Often we want smaller changes to occur at points between our major breakpoints.
+Instead of breaks in layout they are minor adjustments --
+[tweakpoints](http://adactio.com/journal/6044/). This can be accomplished by
+wrapping a `breakup-media` within a `breakup-block`:
+
+```SCSS
+// _component.scss
+@include breakup-block('wide') {
+  @include breakup-media('(min-width: 40em)') {
+    .component {
+      background-color: green;
+    }
+  }
+}
+```
+
+Breakup provides a convenience method for this so the following is a shorthand
+equivalent:
+
+```SCSS
+// _component.scss
+@include breakup-tweakpoint('(min-width: 40em)', 'wide') {
+  .component {
+    background-color: green;
+  }
+}
+```
 
 
 ## TODO
 
-Usage examples and tests coming soon.
+More usage examples and tests coming soon.
 
 
 ## Prior Art

data/breakup.gemspec

@@ -17,7 +17,7 @@ Gem::Specification.new do |gem|
   breakpoint CSS files (e.g. base, mobile, tablet and desktop) and fallback
   files where no styles are wrapped (e.g. for oldIE which does not support media
   queries).'
-  gem.homepage = 'http://github.com/bpscott/breakup'
+  gem.homepage = 'https://github.com/bpscott/breakup'
 
   # Gem Files
   gem.files = `git ls-files`.split($/)

data/examples/example_allblocks.css

@@ -0,0 +1,14 @@
+.component {
+  background-color: red;
+}
+
+@media (max-width: 35.999em) {
+  .component {
+    background-color: blue;
+  }
+}
+@media (min-width: 36em) {
+  .component {
+    background-color: green;
+  }
+}

data/examples/example_allblocks.scss

@@ -0,0 +1,6 @@
+@import '../stylesheets/breakup.scss';
+
+$breakup-included-blocks: ('basic' 'thin' 'wide' 'full');
+
+@import 'partials/global_variables';
+@import 'partials/component';

data/examples/example_oldie.css

@@ -0,0 +1,7 @@
+.component {
+  background-color: red;
+}
+
+.component {
+  background-color: green;
+}

data/examples/example_oldie.scss

@@ -0,0 +1,14 @@
+.component {
+  background-color: red;
+}
+
+@media (max-width: 35.999em) {
+  .component {
+    background-color: blue;
+  }
+}
+@media (min-width: 36em) {
+  .component {
+    background-color: green;
+  }
+}

data/examples/example_wideonly.css

@@ -0,0 +1,5 @@
+@media (min-width: 36em) {
+  .component {
+    background-color: green;
+  }
+}

data/examples/example_wideonly.scss

@@ -0,0 +1,6 @@
+@import '../stylesheets/breakup.scss';
+
+$breakup-included-blocks: ('wide');
+
+@import 'partials/global_variables';
+@import 'partials/component';

data/examples/partials/_component.scss

@@ -0,0 +1,11 @@
+@include breakup-block('basic') {
+  .component { background-color: red; }
+}
+
+@include breakup-breakpoint('thin') {
+  .component { background-color: blue; }
+}
+
+@include breakup-breakpoint('wide') {
+  .component { background-color: green; }
+}

data/examples/partials/_global_variables.scss

@@ -0,0 +1,5 @@
+$breakup-breakpoints: (
+  'thin' '(max-width: 35.999em)',
+  'wide' '(min-width: 36em)',
+  'full' '(min-width: 61em)'
+);

data/lib/breakup/version.rb

@@ -1,3 +1,3 @@
 module Breakup
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

data/script/examples-watch

@@ -0,0 +1,3 @@
+#!/bin/sh
+
+sass --watch examples/*.scss --style expanded

data/stylesheets/_breakup.scss

@@ -4,49 +4,49 @@
 // A tool for defining breakpoints and conditionally loading them.
 //////////////////////////////////////////////////////////////////
 
-/**
- * Global Variables
- *
- * $breakup-breakpoints: List of many named breakpoints that can be called with
- *     breakup-breakpoint. Each breakpoint is a list containing the breakpoint
- *     name and the media query it describes. Example:
- *
- *     $breakup-breakpoints: (
- *       'palm' '(max-width: 480px)',
- *       'lap' '(min-width: 481px) and (max-width: 1023px)',
- *       'portable' '(max-width: 1023px)',
- *       'desk' '(min-width: 1024px)'
- *     );
- *
- *
- * $breakup-included-blocks: A list of blocks to render in your stylesheet
- *
- *
- * $breakup-naked: Should breakpoint/tweakpoint blocks be wrapped in an @media
- *     declaration? You should set this to true within stylesheets for browsers
- *     which don't support @media, such as oldIE.
- *
- *
- * $breakup-allow-naked: List of named breakpoints and if they should be output
- *     when $breakup-naked is true (by default this is false). This is separate
- *     to $breakup-breakpoints because you may want to configure what
- *     breakpoints are unwrapped on a per stylesheet basis.
- */
+
+// Global Variables
+//
+// $breakup-breakpoints: List of many named breakpoints that can be called with
+//     breakup-breakpoint. Each breakpoint is a list containing the breakpoint
+//     name and the media query it describes. Example:
+//
+//     $breakup-breakpoints: (
+//       'palm' '(max-width: 480px)',
+//       'lap' '(min-width: 481px) and (max-width: 1023px)',
+//       'portable' '(max-width: 1023px)',
+//       'desk' '(min-width: 1024px)'
+//     );
+//
+//
+// $breakup-included-blocks: A list of blocks to render in your stylesheet
+//
+//
+// $breakup-naked: Should breakpoint/tweakpoint blocks be wrapped in an @media
+//     declaration? You should set this to true within stylesheets for browsers
+//     which don't support @media, such as oldIE.
+//
+//
+// $breakup-allow-naked: List of named breakpoints and if they should be output
+//     when $breakup-naked is true (by default this is false). This is separate
+//     to $breakup-breakpoints because you may want to configure what
+//     breakpoints are unwrapped on a per stylesheet basis.
+///
 $breakup-breakpoints: () !default;
 $breakup-included-blocks: () !default;
 $breakup-naked: false !default;
 $breakup-breakpoints-allow-naked: () !default;
 
-/**
- * Search a list of lists ($haystack) for value ($needle) at a given position
- * ($offset). Returns that item in the list, or false if not found.
- *
- * Example:
- *  list-key-search((
- *    ('key1' 'value1'),
- *    ('key2' 'value2')
- *  ), 'key1', 1) => (key1 value1)
- */
+
+
+// Search a list of lists ($haystack) for value ($needle) at a given position
+// ($offset). Returns that item in the list, or false if not found.
+//
+// Example:
+//  list-key-search((
+//    ('key1' 'value1'),
+//    ('key2' 'value2')
+//  ), 'key1', 1) => (key1 value1)
 @function breakup-list-key-search($haystack, $needle, $offset: 1) {
     @each $haystack-item in $haystack {
         @if $needle == nth($haystack-item, $offset) {
@@ -58,16 +58,15 @@ $breakup-breakpoints-allow-naked: () !default;
 }
 
 
-/**
- * Wrapper around a @media block. if $breakup-naked is true then the
- * content is output directly if the declaration has been marked as a fallback
- * breakpoint.
- *
- * $declaration:    A @media declaration to wrap the content block in.
- * $allow-naked:    Should this content should be rendered if the we are
- *                    displaying naked content (i.e. not wrapped in a media
- *                    query).
- */
+
+// Wrapper around a @media block. if $breakup-naked is true then the
+// content is output directly if the declaration has been marked as a fallback
+// breakpoint.
+//
+// $declaration:    A @media declaration to wrap the content block in.
+// $allow-naked:    Should this content should be rendered if the we are
+//                    displaying naked content (i.e. not wrapped in a media
+//                    query).
 @mixin breakup-media($declaration, $allow-naked: false) {
     @if not $breakup-naked {
         @media #{$declaration} {
@@ -84,12 +83,11 @@ $breakup-breakpoints-allow-naked: () !default;
 }
 
 
-/**
- * Include a block in the page if it is included in within
- * $breakup-included-blocks
- *
- * $block-name:     The block name to render
- */
+
+// Include a block in the page if it is included in within
+// $breakup-included-blocks
+//
+// $block-name:     The block name to render
 @mixin breakup-block($block-name) {
     @if index($breakup-included-blocks, $block-name) != false {
         @content;
@@ -97,13 +95,12 @@ $breakup-breakpoints-allow-naked: () !default;
 }
 
 
-/**
- * Look up a named breakpoint from $breakup-breakpoints, and wrap it in a block
- * so that it only appears if it is in the current stylesheet's
- * $breakup-included-blocks.
- *
- * $breakpoint-name:     The breakpoint name to render
- */
+
+// Look up a named breakpoint from $breakup-breakpoints, and wrap it in a block
+// so that it only appears if it is in the current stylesheet's
+// $breakup-included-blocks.
+//
+// $breakpoint-name:     The breakpoint name to render
 @mixin breakup-breakpoint($breakpoint-name) {
     $breakpoint: breakup-list-key-search($breakup-breakpoints, $breakpoint-name, 1);
 
@@ -132,16 +129,15 @@ $breakup-breakpoints-allow-naked: () !default;
 }
 
 
-/**
- * Create an unnamed tweakpoint and wrap it in a block so that it only appears
- * if it is in the current stylesheet's $breakup-included-blocks.
- *
- * $declaration:    A media query that the content shall be wrapped in
- * $block-name:     The block name to display
- * $allow-naked:    Should this content should be rendered if the we are
- *                    displaying naked content (i.e. not wrapped in a media
- *                    query).
- */
+
+// Create an unnamed tweakpoint and wrap it in a block so that it only appears
+// if it is in the current stylesheet's $breakup-included-blocks.
+//
+// $declaration:    A media query that the content shall be wrapped in
+// $block-name:     The block name to display
+// $allow-naked:    Should this content should be rendered if the we are
+//                    displaying naked content (i.e. not wrapped in a media
+//                    query).
 @mixin breakup-tweakpoint($declaration, $block-name, $allow-naked: false) {
     @include breakup-block($block-name) {
         @include breakup-media($declaration, $allow-naked) {

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: breakup
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-08 00:00:00.000000000 Z
+date: 2013-09-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sass
@@ -54,10 +54,19 @@ files:
 - LICENSE.txt
 - README.md
 - breakup.gemspec
+- examples/example_allblocks.css
+- examples/example_allblocks.scss
+- examples/example_oldie.css
+- examples/example_oldie.scss
+- examples/example_wideonly.css
+- examples/example_wideonly.scss
+- examples/partials/_component.scss
+- examples/partials/_global_variables.scss
 - lib/breakup.rb
 - lib/breakup/version.rb
+- script/examples-watch
 - stylesheets/_breakup.scss
-homepage: http://github.com/bpscott/breakup
+homepage: https://github.com/bpscott/breakup
 licenses: []
 post_install_message: 
 rdoc_options: []
@@ -87,4 +96,3 @@ summary: Breakup is a Sass component that allows you to create multiple CSS file
   mobile, tablet and desktop) and fallback files where no styles are wrapped (e.g.
   for oldIE which does not support media queries).
 test_files: []
-has_rdoc: