Merge branch 'stage-v4.1.0'

README.md

@@ -38,7 +38,7 @@ with `__tool`, from which to pick and choose to use for your package.
 
 If you want to use a particular tool in your stylesheet, you will have to
 `@import (reference)` the stylesheet for that tool. For example,
-if you plan to use the `.font-size-block()` mixin in your Less, you must include
+if you plan to use the `.font-size-el()` mixin in your Less, you must include
 
 ```less
 @import (reference) url('/node_modules/xmeter/src/__tool.module.fontsize.less');
@@ -48,7 +48,7 @@ at the top of your stylesheet. Then when you want to “call” the mixin, do
 
 ```less
 .my-selector {
-  .font-size-block(2.0; 1.5);
+  .font-size-el(2.0; 1.5);
 }
 ```
 
@@ -94,22 +94,18 @@ unclassed HTML elements before any specific classes and styles get added on.
 
 See the test page (`doc/test.html`) for a preview.
 
-To install:
-
-    $ bower install https://github.com/chharvey/xmeter.git # not on bower registry
-
-To reference this stylesheet on your own site:
-
+Locally
+```
+$ npm install xmeter
+```
 ```html
-<link rel="stylesheet" href="/bower_components/xmeter/xmeter.css"/>
+<link rel="stylesheet" href="/node_modules/xmeter/xmeter[.min].css"/>
 ```
-
-If for some reason you do not have this stylesheet installed locally, you may
-fetch it off the web as you would from a CDN (though this is not recommended).
-
+Remotely (from a CDN; not recommended)
 ```html
-<link rel="stylesheet" href="https://chharvey.github.io/xmeter/xmeter.css"/>
+<link rel="stylesheet" href="https://cdn.rawgit.com/chharvey/xmeter/‹master›/xmeter[.min].css"/>
 ```
+where `‹master›` can be a branch or a tag, and optional `[.min]` is for the minified version.
 
 ## About
 
@@ -130,24 +126,33 @@ for a demo.
   (dubbed a “vertical rhythm unit” or “vru”) regardless of font size, and
   typographical elements (headings, paragraphs, figures, blockquotes, lists,
   tables, etc.) are separated by integer multiples of that height.
+- The following convention is used to preserve vertical rhythm:
+  - Bottom margin is added to an element in order to push subsequent elements down the page.
+  - Top padding is added to an element to push *itself* down the page.
+  - Negative top margin is added to an element to pull it up the page.
 - Font-size for `html` is set to `100%` to accommodate for user agent settings.
   All other font-sizes are relative (either `rem`s or `em`s, no pixels or inches).
 - All line-height values are unitless.
-- Units for font-size, margin, and padding on block elements are in `rem`s
+- Units for font-size, margin, and padding on **modules** (not explicitly defined in this project)
+  should be set in `rem`s, so that their vertical typography remains the same
+  regardless of where that module is placed (style does not depend on location).
+- Within a module however, font-size, margin, and padding on an element
+  should be set in `em`s, so that its vertical typography scales with
+  its parent module’s font size.
+- ~~Units for font-size, margin, and padding on block elements are in `rem`s
   rather than `em`s, thus the size of an element’s font remains the same
-  regardless of where that element is placed (style does not depend on location).
-- **However:** `em`s are used on text-level elements, so that these elements
+  regardless of where that element is placed (style does not depend on location).~~
+- ~~`em`s are used on text-level elements, so that these elements
   scale accordingly when nested inside elements with a larger font size
-  (style *does* depend on location).
-- Line-height for all inline (text-level) elements is 0. This allows the
-  vertical rhythm to remain unaffected.
+  (style *does* depend on location).~~
+- Line-height for all inline (text-level) elements is 0.
+  This preserves vertical rhythm within a block.
 - Fallback tools for browser discrepancies on CSS3 properties.
 - Module tools add styles to blocks (font-size, borders) without disrupting vertical rhythm
 - A few other modules to make your life easier:
   - `.sprite()` sets background image sprites
   - `.clearfix()` does exactly what it sounds like
   - `.delimiters()` sets quotes and other things
-  - `.translucent()` **may be removed in the future**
 - Minor, albeit prettier, style changes to some text-level elements from the browser default.
 
 ## Changelog

doc/test.html

@@ -1,4 +1,4 @@
-<!DOCTYPE html><html lang="en"><head><title>Base Typography | Xmeter</title><meta charset="utf-8"><meta name="description" content="A test of bare, unclassed elements."><meta name="viewport" content="width=device-width, initial-scale=1"><link rel="stylesheet" href="../xmeter.min.css"><link rel="stylesheet" href="styles/doc.css"></head><body><main><header><h1>Xmeter — Base Typography</h1><nav id="table-contents"><h2>Table of Contents</h2><ol><li><a href="#table-contents">Table of Contents</a></li><li><a href="#headings-paragraphs">Headings &amp; Paragraphs</a></li><li><a href="#lists">Lists</a></li><li><a href="#tables">Tables</a></li><li><a href="#text-level-elements">Text-Level Elements</a><ol><li><a href="#links">Links</a></li><li><a href="#stress">Stress</a></li><li><a href="#documentation">Documentation</a></li><li><a href="#data">Data</a></li></ol></li><li><a href="#embedded-elements">Embedded Elements</a></li><li><a href="#forms">Forms</a></li><li><a href="#interactive-elements">Interactive Elements</a></li></ol></nav></header><section id="headings-paragraphs"><h2>Headings &amp; Paragraphs</h2><figure class="x-c-Fig"><h1>Heading 1 <code class="x-c-Code">h1</code></h1><p>Paragraph <code class="x-c-Code">p</code>
+<!DOCTYPE html><html lang="en"><head><title>Base Typography | Xmeter</title><meta charset="utf-8"><meta name="description" content="A test of bare, unclassed elements."><meta name="viewport" content="width=device-width, initial-scale=1"><link rel="stylesheet" href="../xmeter.css"><link rel="stylesheet" href="styles/doc.css"></head><body><main><header><h1>Xmeter — Base Typography</h1><nav id="table-contents"><h2>Table of Contents</h2><ol><li><a href="#table-contents">Table of Contents</a></li><li><a href="#headings-paragraphs">Headings &amp; Paragraphs</a></li><li><a href="#lists">Lists</a></li><li><a href="#tables">Tables</a></li><li><a href="#text-level-elements">Text-Level Elements</a><ol><li><a href="#links">Links</a></li><li><a href="#stress">Stress</a></li><li><a href="#documentation">Documentation</a></li><li><a href="#data">Data</a></li></ol></li><li><a href="#embedded-elements">Embedded Elements</a></li><li><a href="#forms">Forms</a></li><li><a href="#interactive-elements">Interactive Elements</a></li></ol></nav></header><section id="headings-paragraphs"><h2>Headings &amp; Paragraphs</h2><figure class="x-c-Fig"><h1>Heading 1 <code class="x-c-Code">h1</code></h1><p>Paragraph <code class="x-c-Code">p</code>
 Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 Aliquam sagittis suscipit nunc, a cursus libero euismod at.
 Nulla placerat neque massa, quis interdum leo efficitur vel.

doc/test.jade

@@ -7,7 +7,7 @@ html(lang="en")
     meta(charset="utf-8")
     meta(name="description" content="A test of bare, unclassed elements.")
     meta(name="viewport" content="width=device-width, initial-scale=1")
-    link(rel="stylesheet" href="../xmeter.min.css")
+    link(rel="stylesheet" href="../xmeter.css")
     link(rel="stylesheet" href="styles/doc.css")
   body
     main

package.json

@@ -1,6 +1,6 @@
 {
   "name": "xmeter",
-  "version": "4.0.1",
+  "version": "4.1.0",
   "description": "A default stylesheet with a set of tools that make designing with vertical rhythm easy.",
   "main": "xmeter.css",
   "dependencies": {},

src/__tool.fallback.filter.less

@@ -0,0 +1,23 @@
+
+/*################################*\
+    xmeter  |  __tool.fallback.filter.less
+\*################################*/
+
+
+// Applies one or more graphical filter effects on an element.
+//
+// ^url
+// : https://developer.mozilla.org/en-US/docs/Web/CSS/filter
+// ^params
+// : @arg - a list of space-separated filter functions
+// ^author
+// : Chris Harvey
+// ^updated
+// : 2016-04-05
+.filter(@arg) {
+  -webkit-filter: @arg;
+     -moz-filter: @arg;
+      -ms-filter: @arg;
+       -o-filter: @arg;
+          filter: @arg;
+}

src/__tool.fallback.flexbox.less

@@ -139,25 +139,10 @@
 //++++++++++++++++++++++++++++++++//
 //    # ITEMS
 //++++++++++++++++++++++++++++++++//
-// Shorthand for `flex-grow`, `flex-shrink`, and `flex-basis` properties (in that order).
-//
-// @values - none | [ ‹number:0› ‹number:1›? || ‹length:auto› ]
-// ^author
-// : Chris Harvey
-// ^updated
-// : 2015-09-03
-.flex(@values) {
-  -webkit-box-flex: @values;
-     -moz-box-flex: @values;
-      -webkit-flex: @values;
-         -moz-flex: @values;
-          -ms-flex: @values;
-              flex: @values;
-}
-
 // Determines the order in which items appear in the flex container.
 //
 // @integer - ‹integer:0› the order in which the item appears in the flex container
+//            negative integers may be used.
 // ^author
 // : Chris Harvey
 // ^updated
@@ -191,4 +176,77 @@
       -ms-align-self: @align;
           align-self: @align;
 }
+
+// Specifies what amount of space inside the flex container this item should take up.
+//
+// ^param
+// @number (0) - the flex grow factor, relative to other items’ values.
+//               negative values are not allowed.
+// ^author
+// : Chris Harvey
+// ^updated
+// : 2016-04-26
+.flex-grow(@number) {
+  -webkit-flex-grow: @number;
+      -ms-flex-grow: @number;
+          flex-grow: @number;
+}
+
+// The opposite of flex-grow.
+// Specifies what amount of space inside the flex container this item should take up.
+//
+// ^param
+// @number (1) - the flex shrink factor, relative to other items’ values.
+//               negative values are not allowed.
+// ^author
+// : Chris Harvey
+// ^updated
+// : 2016-04-26
+.flex-shrink(@number) {
+  -webkit-flex-shrink: @number;
+      -ms-flex-shrink: @number;
+          flex-shrink: @number;
+}
+
+// Specifies the initial main size of a flex item.
+// Affects the width of this item’s content-box unless otherwise specified by `box-sizing`.
+//
+// ^param
+// @width - the width of this item (or height if `flex-direction==column`)
+//        - `auto` (default) - gets the width (or height if `flex-direction==column`) of this item
+//        - `content`        - indicates automatic sizing (like `auto` for `width` property)
+// ^author
+// : Chris Harvey
+// ^updated
+// : 2016-04-26
+.flex-basis(@width) {
+  -webkit-flex-basis: @width;
+      -ms-flex-basis: @width;
+          flex-basis: @width;
+}
+
+// Shorthand for `flex-grow`, `flex-shrink`, and `flex-basis` properties (in that order).
+//
+// @arg - a space-separated list of:
+//      - none | [ ‹number› ‹number›? || ‹length› ]
+//      - options:
+//        0. `initial` - computes to `0 1 auto`
+//        1. `none`    - computes to `0 0 auto`
+//        2. `‹flex-grow›`
+//        3. `‹flex-grow› ‹flex-shrink›`
+//        4. `‹flex-basis›`
+//        5. `‹flex-grow› ‹flex-basis›`
+//        6. `‹flex-grow› ‹flex-shrink› ‹flex-basis›`
+// ^author
+// : Chris Harvey
+// ^updated
+// : 2015-09-03
+.flex(@arg) {
+  -webkit-box-flex: @arg;
+     -moz-box-flex: @arg;
+      -webkit-flex: @arg;
+         -moz-flex: @arg;
+          -ms-flex: @arg;
+              flex: @arg;
+}
 //++++ end # ITEMS ++++//

src/__tool.fallback.gradient.less

@@ -4,20 +4,30 @@
 \*################################*/
 
 
-// Applies a linear gradient background on an Element.
+// Applies a single linear gradient background on an element.
+// This is an unusual property in that a single css value list is comprised
+// of comma-separated values (unlike normal css value lists which are space-separated).
+// Thus when you call the mixin, you must append a dummy semicolon at the end of your argument.
+// If you do not, Less will interpret the commas as argument separators.
+//
 // See [MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/linear-gradient) for more info.
 // See [WPD](http://docs.webplatform.org/wiki/css/functions/linear-gradient) for more info.
 //
-// ... - any number of parameters
+// ^params
+// : @arg - a list of comma-separated components (each as a component of one gradient value).
+//          Must be terminated with a semicolon (;).
 // ^author
 // : Chris Harvey
 // ^updated
 // : 2014-07-08
-.gradient(...) {
-  background-image: -webkit-linear-gradient(@arguments);
-  background-image:    -moz-linear-gradient(@arguments);
-  background-image:     -ms-linear-gradient(@arguments);
-  background-image:      -o-linear-gradient(@arguments);
-  background-image:         linear-gradient(@arguments);
-  background-image:        -webkit-gradient(@arguments); // "Old Webkit"
+///////////////////////////////////////////////////////////////////////////////
+// CHANGED: DEPRECATED. use `linear-gradient` name below.
+///////////////////////////////////////////////////////////////////////////////
+.gradient(@arg) {
+  background-image: -webkit-linear-gradient(@arg);
+  background-image:    -moz-linear-gradient(@arg);
+  background-image:     -ms-linear-gradient(@arg);
+  background-image:      -o-linear-gradient(@arg);
+  background-image:         linear-gradient(@arg);
+  background-image:        -webkit-gradient(@arg); // "Old Webkit"
 }

src/__tool.fallback.linear-gradient.less

@@ -0,0 +1,30 @@
+
+/*################################*\
+    xmeter  |  __tool.fallback.linear-gradient.less
+\*################################*/
+
+
+// Applies a single linear gradient background on an element.
+// This is an unusual property in that a single css value list is comprised
+// of comma-separated values (unlike normal css value lists which are space-separated).
+// Thus when you call the mixin, you must append a dummy semicolon at the end of your argument.
+// If you do not, Less will interpret the commas as argument separators.
+//
+// See [MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/linear-gradient) for more info.
+// See [WPD](http://docs.webplatform.org/wiki/css/functions/linear-gradient) for more info.
+//
+// ^params
+// : @arg - a list of comma-separated components (each as a component of one gradient value).
+//          Must be terminated with a semicolon (;).
+// ^author
+// : Chris Harvey
+// ^updated
+// : 2014-07-08
+.linear-gradient(@arg) {
+  background-image: -webkit-linear-gradient(@arg);
+  background-image:    -moz-linear-gradient(@arg);
+  background-image:     -ms-linear-gradient(@arg);
+  background-image:      -o-linear-gradient(@arg);
+  background-image:         linear-gradient(@arg);
+  background-image:        -webkit-gradient(@arg); // "Old Webkit"
+}

src/__tool.fallback.rotate.less

@@ -11,6 +11,16 @@
 // : Chris Harvey
 // ^updated
 // : 2014-05-10
+///////////////////////////////////////////////////////////////////////////////
+// CHANGED: THIS MIXIN IS DEPRECATED.
+// CHANGED
+// IMPORTANT!!!
+// ------------
+// As of v4.1.0
+// This entire file and the code therein is DEPRECATED in favor of
+// `__tool.fallback.transform.less`
+// This tool will be OBSOLETE and this file will be deleted on Version 5.
+///////////////////////////////////////////////////////////////////////////////
 .rotate(@rotation) {
   -webkit-transform: rotate(@rotation);
      -moz-transform: rotate(@rotation);

src/__tool.fallback.transform.less

@@ -0,0 +1,23 @@
+
+/*################################*\
+    xmeter  |  __tool.fallback.transform.less
+\*################################*/
+
+
+// Applies one or more transformations to an element.
+//
+// ^url
+// : https://developer.mozilla.org/en-US/docs/Web/CSS/transform
+// ^params
+// : @arg - a list of space-separated transformation functions
+// ^author
+// : Chris Harvey
+// ^updated
+// : 2016-05-04
+.transform(@arg) {
+  -webkit-transform: @arg;
+     -moz-transform: @arg;
+      -ms-transform: @arg;
+       -o-transform: @arg;
+          transform: @arg;
+}

src/__tool.fallback.transition.less

@@ -4,12 +4,15 @@
 \*################################*/
 
 
-// Applies a transition timing effect on an Element.
+// Applies a single transition timing effect on an element.
+// Each parameter must be a list of (zero or more) comma-separated values.
+// The default value of each parameter is the default value of its corresponding css property.
 //
-// @props - the CSS property name(s). If more than one, they must be comma-separated
-// @dura  - (optional: `0ms`) the length in time, in milliseconds, the transition is to be in effect
-// @func  - (optional: `ease`) the timing-function. See `https://developer.mozilla.org/en-US/docs/Web/CSS/timing-function`
-// @delay - (optional: `0ms`) the length in time, in milliseconds, the transition will wait before starting
+// ^params
+// : @props - the CSS property name(s)
+// : @dura  - (optional: `0ms`) the length(s) in time, in milliseconds, the transition is to be in effect
+// : @func  - (optional: `ease`) the timing-function(s). See `https://developer.mozilla.org/en-US/docs/Web/CSS/timing-function`
+// : @delay - (optional: `0ms`) the length(s) in time, in milliseconds, the transition will wait before starting
 // ^author
 // : Chris Harvey
 // ^updated
@@ -36,3 +39,20 @@
        -o-transition-delay: @delay;
           transition-delay: @delay;
 }
+
+// Applies multiple transition timing effects on an element.
+//
+// ^params
+// : @arg - (optional: `all 0ms ease 0ms`) a list of (zero or more) comma-separated transition effects.
+//          Must be terminated with a semicolon (;).
+// ^author
+// : Chris Harvey
+// ^updated
+// : 2014-06-17
+.transition-multi(@arg: all 0ms ease 0ms) {
+  -webkit-transition: @arg;
+     -moz-transition: @arg;
+      -ms-transition: @arg;
+       -o-transition: @arg;
+          transition: @arg;
+}