Merge pull request #97 from bfred-it/Khan/native

Accepts all kinds of Array-like objects

.gitignore

@@ -0,0 +1 @@
+node_modules

NOTICE

@@ -1,17 +1,3 @@
 Balance Text is licensed under the Apache License, Version 2.0 (see LICENSE file).
 
-Balance Text uses the following third party libraries that may have licenses
-differing from that of Balance Text itself. You can find the libraries and their
-respective licenses below.
-
-
- - jQuery - /sample/jquery-1.9.1.js
-
-    Copyright 2011, John Resig
-    Dual licensed under the MIT or GPL Version 2 licenses.
-    http://jquery.org/license
-
-    Includes Sizzle.js
-    http://sizzlejs.com/
-    Copyright 2011, The Dojo Foundation
-    Released under the MIT, BSD, and GPL Licenses.
+Balance Text uses no third party libraries

README.md

@@ -1,6 +1,6 @@
 # BalanceText
 
-A jQuery plugin to provide an alternate text wrapping algorithm. I hope to get this into the CSS spec, so it's implemented as a polyfill. It already appears in the [CSS Text Module Level 4 Editor's Draft.](https://drafts.csswg.org/css-text-4/#text-wrap)
+A utility to provide an alternate text wrapping algorithm. I hope to get this into the CSS spec, so it's implemented as an optional "polyfill". It already appears in the [CSS Text Module Level 4 Editor's Draft.](https://drafts.csswg.org/css-text-4/#text-wrap)
 
 The default text rendering algorithm is:
 
@@ -13,58 +13,100 @@ That algorithm guarantees that the text is rendered using the least number of li
 ## How it works
 Here is a simple Balance Text setup:
 
-```
+```html
   <style type="text/css">
   /* Plugin looks for elements with class named "balance-text" */
   .balance-text {
       text-wrap: balanced;  /* Apply (proposed) CSS style */
   }
   </style>
 
-  <script src="jquery-1.9.1.min.js"></script>
-  <script src="jquery.balancetext.min.js"></script>
+  <script src="balancetext.min.js"></script>
+  <script>
+    balanceText();
+  </script>
 ```
 
 See the demo provided or [this online version for a working sample](http://adobe-webplatform.github.io/balance-text/demo/index.html).
 
-Balance Text will *automatically* run on any elements with <code>balance-text</code> class:
+If you call `balanceText()`, Balance Text will *automatically* run on any elements with <code>balance-text</code> class:
 
 - when the page loads (DOM Ready event)
 - when it is resized
 
 You may also *manually* trigger it, e.g. if you're dynamically adding text to the DOM:
 
-```
-    $('.my-class').balanceText();
+```javascript
+    balanceText(el);       // Balance a single element
+    balanceText([el, el]); // Balance a list of elements
+    balanceText('.el');    // Balance a list of elements based on query selector
 ```
 
-You can use any selector of your choice (you may wish to use an ID or restrict the scope for performance). These will _not_  re-balance on resize.
+This will apply the balance-text formatting once.  If you'd like to re-apply automatically during window resize, you can use pass an options parameter instead:
+
+```javascript
+    balanceText(el, {watch: true});
+```
 
 If you need to manually re-balance all triggered elements, use:
 
-```
-    $.fn.balanceTextUpdate();
+```javascript
+    balanceText.updateWatched();
 ```
 
-To Balance Text and have it automatically update on resize, use:
+## How to use with jQuery
+This library used to be implemented as a jQuery plugin (as of v2.0.0) but was re-written as a native utility (as of 3.0.0).  If you'd like to continue using the jQuery interface, you can continue using 2.0.0 (link below).
 
-```
-    $.balanceText('.my-class');
-```
+You can also migrate to `balanceText()` from jQuery using this guide (shown compared to the 2.0.0 interface):
+```javascript
+    // Put the balanceText utility into "polyfill" mode
+    // This was the default mode of the 2.0.0 jQuery plugin when it loaded
+    $.ready(function() {
+        balanceText(); 
+    });
+
+    // manually trigger on a list of elements
+    balanceText($('.my-class')); // equivalent to $('.my-class').balanceText();
+
+    // manually trigger on a list of elements and update on browser resize
+    balanceText($('.my-class'), {watch: true}); // equivalent to $.balanceText('.my-class');
+
+    // manually re-balance all triggered elements
+    balanceText.updateWatched(); // equivalent to $.fn.balanceTextUpdate();
 
+```
 
 ## Use from a CDN
+[//cdnjs.cloudflare.com/ajax/libs/balance-text/3.0.0/balancetext.min.js](//cdnjs.cloudflare.com/ajax/libs/balance-text/3.0.0/balancetext.min.js)
+
+[//cdn.jsdelivr.net/balancetext/3.0.0/balancetext.min.js](//cdn.jsdelivr.net/balancetext/3.0.0/balancetext.min.js)
+
+
+### Legacy (2.0.0)
+(Has a hard requirement on jQuery)
 
 [//cdnjs.cloudflare.com/ajax/libs/balance-text/2.0.0/jquery.balancetext.min.js](//cdnjs.cloudflare.com/ajax/libs/balance-text/2.0.0/jquery.balancetext.min.js)
 
 [//cdn.jsdelivr.net/jquery.balancetext/2.0.0/jquery.balancetext.min.js](//cdn.jsdelivr.net/jquery.balancetext/2.0.0/jquery.balancetext.min.js)
 
 ## Requirements
-BalanceText is designed to run in most common browsers and implemented as a jQuery plugin. This means that the standard jQuery library is required for it to work. This plugin was last updated using jQuery 1.9.1, but it should work with all newer (and some older) versions of jQuery.
+BalanceText does not have any dependencies.
+BalanceText is designed to run in most common browsers.
+
+## Development
+### Linting
+Make sure the code passes JSLint
 
-jQuery was used so that the code would be easier to write to work in most common browsers. None of the novel ideas introduced by this code require jQuery.
+```
+npm run lint
+```
+
+### Minification
+We minify using Uglify-JS
 
-Code is minified using: http://marijnhaverbeke.nl/uglifyjs
+```
+npm run build
+```
 
 ## Changelog
 * v 1.0.x - Initial Release, bug fix by chrisbank, better break point detection mmcgahan
@@ -76,3 +118,4 @@ Code is minified using: http://marijnhaverbeke.nl/uglifyjs
 * v 1.6.x - Add balanceTextUpdate() method (rileyjshaw), bug fixes (bfred-it)
 * v 1.7.0 - Hack for partially working with jQuery 3, remove deprecation warning
 * v 2.0.0 - Fix automatic updating of custom selectors for jQuery 3 (bfred-it)
+* v 3.0.0 - Remove the jQuery dependency