fix for http://yuilibrary.com/projects/yui3/ticket/2532170

Here is the patch (code,test,docs) for http://yuilibrary.com/projects/yui3/ticket/2532170

(It has a bunch of extra stuff because I forked yui/yui3.)