docs(docs): improve docs

CONTRIBUTORS.md

@@ -0,0 +1,28 @@
+# Contributing
+
+## Questions
+
+If you have questions about implementation details, help or support, then please use our dedicated community forum at [Spectrum.chat/react-table](https://spectrum.chat/react-table) **PLEASE NOTE:** If you choose to instead open an issue for your question, your issue will be immediately closed and redirected to the forum.
+
+## Reporting Issues
+
+If you have found what you think is a bug, please [file an issue](https://github.com/tannerlinsley/react-table/issues/new). **PLEASE NOTE:** Issues that are identified as implementation questions or non-issues will be immediately closed and redirected to [Spectrum.chat/react-table](https://spectrum.chat/react-table)
+
+## Suggesting new features
+
+If you are here to suggest a feature, first create an issue if it does not already exist. From there, we will discuss use-cases for the feature and then finally discuss how it could be implemented.
+
+## Development
+
+If you have been assigned to fix an issue or develop a new feature, please follow these steps to get started:
+
+- Fork this repository
+- Install dependencies by running `$ yarn`
+- Link `react-table` locally by running `$ yarn link`
+- Auto-build files as you edit by running `$ yarn start`
+- Implement your changes and tests to files in the `src/` directory and corresponding test files
+- To run examples, follow their individual directions. Usually this is just `$ yarn && yarn start`.
+- To run examples using your local build, link to the local `react-table` by running `$ yarn link react-table` from the example's directory
+- Document your changes in the root `README.md`
+- To stage a commit, run `yarn commit`
+- Submit PR for review

docs/README.md

@@ -0,0 +1 @@
+To get started with React Table, [click here](../README.md), or select a specific document from this directory.

docs/concepts.md

@@ -0,0 +1,33 @@
+# Concepts
+
+## React Table is a "headless" UI library
+
+React Table is a headless utility, which means out of the box, it doesn't render or supply any actual UI elements. You are in charge of utilizing the state and callbacks of the hooks provided by this library to render your own table markup. [Read this article to understand why React Table is built this way.](https://medium.com/merrickchristensen/headless-user-interface-components-565b0c0f2e18). If you don't want to, then here's a quick rundown anyway:
+
+- Separation of Concerns - Not that superficial kind you read about all the time. The real kind. React Table as a library honestly has no business being in charge of your UI. The look, feel, and overall experience of your table is what makes your app or product great. The less React Table gets in the way of that, the better!
+- Maintenance - By removing the massive (and seemingly endless) API surface area required to support every UI use-case, React Table can remain small, easy-to-use and simple to update/maintain.
+- Extensibility - UI presents countless edge cases for a library simply because it's a creative medium, and one where every developer does things differently. By not dictating UI concerns, React Table empowers the developer to design and extend the UI based on their unique use-case.
+
+## The React Table instance
+
+At the heart of every React Table is the `useTable` hook and the table `instance` object that it returns. This `instance` object contains everything you'll ever need to build a table and interact with it's state. This includes, but is not limited to:
+
+- Columns
+- Materialized Data
+- Sorting
+- Filtering
+- Grouping
+- Pagination
+- Expanded State
+- Any functionality provided by custom plugin hooks, too!
+
+## Rendering your own UI
+
+As of React Table v7, **you the developer** are responsible for rendering your own UI, but don't let that intimidate you! Table UI's are fun and React Table makes it so easy to wire up your own table UI. The easiest way to learn how to build your own table UI is to [see some existing React Table examples](./examples.md)!
+
+---
+
+After reading about React Table's concepts, you should:
+
+- [Check Out Some Examples](./examples.md)
+- [Study the API](./api.md)

docs/examples.md

@@ -0,0 +1,40 @@
+# Examples
+
+- **Simple** - All of these examples use automatic state management, meaning, they don't hoist any state out of the table or manually control anything. Start here for understanding the basics about how to build your table UI.
+  - Basic
+    - [Source + Guide](https://github.com/tannerlinsley/react-table/tree/master/examples/basic)
+    - [Open in CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/basic)
+  - Sorting
+    - [Source + Guide](https://github.com/tannerlinsley/react-table/tree/master/examples/sorting)
+    - [Open in CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/sorting)
+  - Filtering
+    - [Source + Guide](https://github.com/tannerlinsley/react-table/tree/master/examples/filtering)
+    - [Open in CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/filtering)
+  - Grouping
+    - [Source + Guide](https://github.com/tannerlinsley/react-table/tree/master/examples/grouping)
+    - [Open in CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/grouping)
+  - Pagination
+    - [Source + Guide](https://github.com/tannerlinsley/react-table/tree/master/examples/pagination)
+    - [Open in CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/pagination)
+  - Row Selection
+    - [Source + Guide](https://github.com/tannerlinsley/react-table/tree/master/examples/row-selection)
+    - [Open in CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/row-selection)
+  - Expanding
+    - [Source + Guide](https://github.com/tannerlinsley/react-table/tree/master/examples/expanding)
+    - [Open in CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/expanding)
+  - Sub Components
+    - [Source + Guide](https://github.com/tannerlinsley/react-table/tree/master/examples/sub-components)
+    - [Open in CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/sub-components)
+  - Editable Data
+    - [Source + Guide](https://github.com/tannerlinsley/react-table/tree/master/examples/editable-data)
+    - [Open in CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/editable-data)
+- **Controlled via `useTableState`** - These examples are more advanced because they demonstrate how to manually control and respond to the state of the table using the `useTableState` hook.
+  - Pagination (Controlled)
+    - [Source + Guide](https://github.com/tannerlinsley/react-table/tree/master/examples/pagination-controlled)
+    - [Open in CodeSandobx](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/pagination-controlled)
+- **UI** - These examples demonstrate how to use React Table with your favorite UI libraries or tools!
+  - [] Styled-Components
+  - [] CSS
+  - [] Material-UI
+  - [] Bootstrap
+- Want to write one of these examples or add another? [Submit a PR!](https://github.com/tannerlinsley/react-table/compare)

docs/installation.md

@@ -0,0 +1,27 @@
+# Installation
+
+Install React Table as a dependency using `npm` or `yarn`
+
+```bash
+# NPM
+$ npm install react-table
+
+# Yarn
+$ yarn add react-table
+```
+
+To import React Table:
+
+```js
+import {
+  useTable,
+  useGroupBy,
+  useFilters,
+  useSortBy,
+  useExpanded,
+  usePagination,
+  ...
+} from 'react-table'
+```
+
+Once you've installed React Table, continue to [Concepts](./concepts.md) to read more about how to utilize its API

examples/pagination/README.md

@@ -1,6 +1,98 @@
-This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app) and Rescripts.
-
-You can:
+# Pagination
 
 - [Open this example in a new CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/pagination)
 - `yarn` and `yarn start` to run and edit the example
+
+## Guide
+
+To add automatic client side pagination, use the `usePagination` hook:
+
+```diff
+// Import React
+import React from 'react'
+
+// Import React Table
+import {
+  useTable,
+  useGroupBy,
+  useFilters,
+  useSortBy,
+  useExpanded,
++  usePagination,
+} from 'react-table'
+
+// Create a component to render your table
+function MyTable(props) {
+  // Use the useTable hook to create your table configuration
+  const instance = useTable(
+    props,
+    useGroupBy,
+    useFilters,
+    useSortBy,
+    useExpanded,
++   usePagination,
+  )
+
+  // Use the state and functions returned from useTable to build your UI
+  const {
+    getTableProps,
+    headerGroups,
+    rows,
+    getRowProps,
+    prepareRow,
++   pageOptions,
++   page,
++   state: [{ pageIndex, pageSize }],
++   gotoPage,
++   previousPage,
++   nextPage,
++   setPageSize,
++   canPreviousPage,
++   canNextPage,
+  } = instance
+
+  // Render the UI for your table
+  return (
+    <div>
+      <table {...getTableProps()}>
+        ...
+      </table>
++     <div>
++       <button onClick={() => previousPage()} disabled={!canPreviousPage}>
++         Previous Page
++       </button>
++       <button onClick={() => nextPage()} disabled={!canNextPage}>
++         Next Page
++       </button>
++       <div>
++         Page{' '}
++         <em>
++           {pageIndex + 1} of {pageOptions.length}
++         </em>
++       </div>
++       <div>Go to page:</div>
++       <input
++         type="number"
++         defaultValue={pageIndex + 1 || 1}
++         onChange={e => {
++           const page = e.target.value ? Number(e.target.value) - 1 : 0
++           gotoPage(page)
++         }}
++       />
++       <select
++         value={pageSize}
++         onChange={e => {
++           setPageSize(Number(e.target.value))
++         }}
++       >
++         {pageSizeOptions.map(pageSize => (
++           <option key={pageSize} value={pageSize}>
++             Show {pageSize}
++           </option>
++         ))}
++       </select>
++     </div>
+    </div>
+  )
+}
+```

examples/sorting/README.md

@@ -1,6 +1,62 @@
-This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app) and Rescripts.
+# Sorting
 
-You can:
+Automatic sorting can be accomplished by using the `useSortBy` plugin hook.
 
 - [Open this example in a new CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/sorting)
-- `yarn` and `yarn start` to run and edit the example
+- Or, `yarn` and `yarn start` to run and edit the example
+
+## Guide
+
+Start by importing the hook from `react-table`:
+
+```diff
+-import { useTable } from 'react-table'
++import { useTable, useSortBy } from 'react-table'
+```
+
+Next, add the `useSortBy` hook to your `useTable` hook and add the necessary UI pieces we need to make sorting work:
+
+```diff
+function MyTable() {
+  const { getTableProps, headerGroups, rows, prepareRow } = useTable(
+    {
+      data,
+      columns,
+    },
+-   useSortBy
++   useSortBy
+  )
+
+  return (
+    <table {...getTableProps()}>
+      <thead>
+        {headerGroups.map(headerGroup => (
+          <tr {...headerGroup.getHeaderGroupProps()}>
+            {headerGroup.headers.map(column => (
+-             <th {...column.getHeaderProps()}>
++             <th {...column.getHeaderProps(column.getSortByToggleProps())}>
+                {column.render('Header')}
++               <span>
++                 {column.sorted ? (column.sortedDesc ? ' 🔽' : ' 🔼') : ''}
++               </span>
+              </th>
+            ))}
+          </tr>
+        ))}
+      </thead>
+      <tbody>
+        {rows.map(
+          (row, i) =>
+            prepareRow(row) || (
+              <tr {...row.getRowProps()}>
+                {row.cells.map(cell => {
+                  return <td {...cell.getCellProps()}>{cell.render('Cell')}</td>
+                })}
+              </tr>
+            )
+        )}
+      </tbody>
+    </table>
+  )
+}
+```

src/index.js

@@ -10,5 +10,4 @@ export { usePagination } from './plugin-hooks/usePagination'
 export { useRowSelect } from './plugin-hooks/useRowSelect'
 export { useRowState } from './plugin-hooks/useRowState'
 export { useFlexLayout } from './plugin-hooks/useFlexLayout'
-export { useTokenPagination } from './utility-hooks/useTokenPagination'
 export { actions, addActions } from './actions'