Update the docs and README based on the refactor

Author: adamschwartz

README.md

@@ -2,8 +2,4 @@
 
 ### [Demo](http://github.hubspot.com/sortable/docs/welcome)    [Documentation](http://github.hubspot.com/sortable)
 
-Sortable is an open-source javascript and CSS library which adds sorting functionality to tables. It is tiny (`<2kb`) and has no dependencies.
-
-#### Credits
-
-Loosely based on [Stuart Langridge](https://github.com/stuartlangridge)'s [SortTable](http://www.kryogenix.org/code/browser/sorttable/) ([History](https://github.com/HubSpot/sortable/commits/e068642453bb39eed676ed338e9bbeb372ca74c4/sorttable.js), [Original](https://github.com/HubSpot/sortable/blob/37894eb51bda9f0e438d735967f16eef0d403ef9/sorttable.js))
+Sortable is an open-source JavaScript and CSS library which adds sorting functionality to tables. It is tiny (`<2kb` min+gzip) and has no dependencies.

docs/api/1-Options.md

@@ -16,7 +16,7 @@ Example:
 
 All tables on the page will be automatically initted when the page is loaded.
 
-If you add tables with javascript, call `init` after they are added to the page:
+If you add tables with JavaScript, call `init` after they are added to the page:
 
 ```coffeescript
 Sortable.init()
@@ -68,6 +68,68 @@ To disable sorting on a particular column, add `data-sortable="false"` to the `<
 </table>
 ```
 
+##### `th` `data-sortable-type="TYPE_NAME"`
+
+By default, the `type` of data in each column is determined by reading the first cell of a column and trying to `match` it to the list of types. To specify a type directly, use `data-sortable-type`.
+
+The default types supplied by Sortable are `alpha`, `numeric`, and `date`.
+
+```html
+<table data-sortable>
+    <thead>
+        <tr>
+            <th data-sortable-type="alpha">Numbers sorted alphabetically</th>
+            <!-- ... -->
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <td>10</td>
+            <td>2</td>
+            <td>312</td>
+            <td>4</td>
+        </tr>
+        <!-- ... -->
+    </tbody>
+</table>
+```
+
+#### Custom Types
+
+The default types supplied by Sortable are `alpha`, `numeric`, and `date`. To supply you own, call `Sortable.setupTypes(customTypesArray)` and pass in your custom types array.
+
+Here’s how Sortable internally sets up the defaults.
+
+```coffeescript
+sortable.setupTypes [{
+  name: 'numeric'
+  defaultSortDirection: 'descending'
+  match: (a) -> a.match numberRegExp
+  comparator: (a) -> parseFloat(a.replace(/[^0-9.-]/g, ''), 10) or 0
+}, {
+  name: 'date'
+  defaultSortDirection: 'ascending'
+  reverse: true
+  match: (a) -> not isNaN Date.parse a
+  comparator: (a) -> Date.parse(a) or 0
+}, {
+  name: 'alpha'
+  defaultSortDirection: 'ascending'
+  match: -> true
+  compare: (a, b) -> a.localeCompare b
+}]
+```
+
+Each type must specify the following:
+
+- A `name` which is used to identify the type, in particular the `data-sortable-type="NAME"` attibute which can be specified on a `th`.
+- A `defaultSortDirection` which can be either `ascending` or `descending`.
+- A `match` function which is used to decide which columns are which types (unless `data-sortable-type` is specified).
+- Either a `comparator` or a `compare` function for the custom sorting handled by this type:
+    - `comparator` is used when you want to simply write a function to process the values before the each sort comparison is made by Sortable.
+    - `compare` is used when you want to actually do handle the entire sort comparison yourself.
+- Optionally specify `reverse` to change what `ascending` and `descending` mean with respect to the sort direction of the data for this column type.
+
 <!-- Resources for the demos -->
 <p style="-webkit-transform: translateZ(0)"></p>
 <script src="/sortable/js/sortable.js"></script>

docs/intro.md

@@ -1,10 +1,10 @@
 ## Sortable
 
-Sortable is an open-source javascript and CSS library which adds sorting functionality to tables. It is tiny (<code>&lt;2kb</code>) and has no dependencies.
+Sortable is an open-source JavaScript and CSS library which adds sorting functionality to tables. It is tiny (<code>&lt;2kb</code> min+gzip) and has no dependencies.
 
 #### Demo
 
-Here is a demo of the "Bootstrap" theme.
+Here is a demo of the “Bootstrap” theme.
 
 <p style="display: none"></p>
 <table class="sortable-theme-bootstrap" data-sortable> <thead> <tr> <th data-sortable="false">Browser</th> <th data-sorted="true" data-sorted-direction="descending">Usage</th> <th>Initial release</th> <th>Stable version</th> </tr> </thead> <tbody> <tr> <td>Chrome</td> <td>42.68%</td> <td data-value="2008">September 2, 2008</td> <td>31.0.1650.57</td> </tr> <tr> <td>Internet Explorer</td> <td>25.44%</td> <td data-value="1995">August 16, 1995</td> <td>11.0.1</td> </tr> <tr> <td>Firefox</td> <td>20.01%</td> <td data-value="2002">September 23, 2002</td> <td>25.0.1</td> </tr> <tr> <td>Safari</td> <td>8.39%</td> <td data-value="2003">January 7, 2003</td> <td>7.0</td> </tr> <tr> <td>Opera</td> <td>1.03%</td> <td data-value="1994">Late 1994</td> <td>18.0.1284.49</td> </tr> <tr> <td>Other</td> <td data-value="0">2.44%</td> <td data-value="-1"></td> <td></td> </tr> </tbody> </table>
@@ -14,7 +14,7 @@ Here is a demo of the "Bootstrap" theme.
 
 - Drop-in script and styles
 - 6 beautiful CSS themes
-- Tiny footprint (<code>&lt;2kb</code>) and no dependencies
+- Tiny footprint (<code>&lt;2kb</code> min+gzip) and no dependencies
 - Looks and behaves great on mobile devices
 
 #### Requirements
@@ -30,22 +30,22 @@ Here is a demo of the "Bootstrap" theme.
 
 #### Including
 
-For the most common usage of sortable, you'll want to include following:
+For the most common usage of sortable, you’ll want to include following:
 
 ```html
 <script src="sortable.min.js"></script>
 <link rel="stylesheet" href="sortable-theme-bootstrap.css" />
 ```
 
-Now any table with the attribute `sortable` will be made sortable. To get the styling, you'll also need to add a class name to the table to match the theme you chose:
+Now any table with the attribute `sortable` will be made sortable. To get the styling, you’ll also need to add a class name to the table to match the theme you chose:
 
 ```html
 <table class="sortable-theme-bootstrap" data-sortable>
     <!-- ... -->
 </table>
 ```
 
-This example uses the "bootstrap" theme. For a full list of supported themes, check out [Themes](/sortable/api/themes).
+This example uses the “Bootstrap” theme. For a full list of supported themes, check out [Themes](/sortable/api/themes).
 
 #### Learn More