docs: refactor guides section and new table instance guide (#5254)

* update readme * refactor guide section, table instance guide * prettier
TanStack · Jan 4, 2024 · b327934 · b327934
1 parent 80d92d6
commit b327934
Show file tree

Hide file tree

Showing 28 changed files with 566 additions and 267 deletions.
diff --git a/README.md b/README.md
@@ -6,27 +6,41 @@ Headless UI for building **powerful tables & datagrids** for **React, Solid, Vue
 
 <a href="https://twitter.com/intent/tweet?button_hashtag=TanStack" target="\_parent">
   <img alt="#TanStack" src="https://img.shields.io/twitter/url?color=%2308a0e9&label=%23TanStack&style=social&url=https%3A%2F%2Ftwitter.com%2Fintent%2Ftweet%3Fbutton_hashtag%3DTanStack" />
-</a><a href="https://github.com/tanstack/table/actions?table=workflow%3A%22react-table+tests%22">
-<img src="https://github.com/tanstack/table/workflows/react-table%20tests/badge.svg" />
-</a><a href="https://npmjs.com/package/@tanstack/react-table" target="\_parent">
+</a>
+<a href="https://github.com/tanstack/table/actions?table=workflow%3A%22react-table+tests%22">
+  <img src="https://github.com/tanstack/table/workflows/react-table%20tests/badge.svg" />
+</a>
+<a href="https://npmjs.com/package/@tanstack/react-table" target="\_parent">
   <img alt="" src="https://img.shields.io/npm/dm/@tanstack/react-table.svg" />
-</a><a href="https://bundlephobia.com/result?p=@tanstack/react-table@latest" target="\_parent">
+</a>
+<a href="https://bundlephobia.com/result?p=@tanstack/react-table@latest" target="\_parent">
   <img alt="" src="https://badgen.net/bundlephobia/minzip/@tanstack/react-table@latest" />
-</a><a href="#badge">
-    <img alt="semantic-release" src="https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg">
-  </a><a href="https://github.com/tanstack/table/discussions">
+</a>
+<a href="#badge">
+  <img alt="semantic-release" src="https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg">
+</a>
+<a href="https://github.com/tanstack/table/discussions">
   <img alt="Join the discussion on Github" src="https://img.shields.io/badge/Github%20Discussions%20%26%20Support-Chat%20now!-blue" />
-</a><a href="https://github.com/tanstack/table" target="\_parent">
+</a>
+<a href="https://github.com/tanstack/table" target="\_parent">
   <img alt="" src="https://img.shields.io/github/stars/tanstack/react-table.svg?style=social&label=Star" />
-</a><a href="https://twitter.com/tannerlinsley" target="\_parent">
+</a>
+<a href="https://twitter.com/tannerlinsley" target="\_parent">
   <img alt="" src="https://img.shields.io/twitter/follow/tannerlinsley.svg?style=social&label=Follow" />
 </a>
 
 > [Looking for version 7 of `react-table`? Click here!](https://github.com/tanstack/table/tree/v7)
 
 ## Enjoy this library?
 
-Try some other [TanStack](https://tanstack.com) like [React Query](https://github.com/TanStack/query), [React Form](https://github.com/tannerlinsley/react-form), [React Charts](https://github.com/TanStack/react-charts)
+Try other [TanStack](https://tanstack.com) libraries:
+
+- [TanStack Query](https://github.com/TanStack/query) <img alt="" src="https://img.shields.io/github/stars/tanstack/query.svg" />
+- [TanStack Table](https://github.com/TanStack/table) <img alt="" src="https://img.shields.io/github/stars/tanstack/table.svg" />
+- [TanStack Router](https://github.com/TanStack/router) <img alt="" src="https://img.shields.io/github/stars/tanstack/router.svg" />
+- [TanStack Virtual](https://github.com/TanStack/virtual) <img alt="" src="https://img.shields.io/github/stars/tanstack/virtual.svg" />
+- [TanStack Form](https://github.com/TanStack/form) <img alt="" src="https://img.shields.io/github/stars/tanstack/form.svg" />
+- [TanStack Ranger](https://github.com/TanStack/ranger) <img alt="" src="https://img.shields.io/github/stars/tanstack/ranger.svg" />
 
 ## Visit [tanstack.com/table](https://tanstack.com/table) for docs, guides, API and more!
 
@@ -55,7 +69,7 @@ JS/TS ecosystem and every use-case.
 
 - Agnostic core (JS/TS)
 - 1st-class framework bindings for React, Vue, Solid
-- ~14kb or less (with tree-shaking)
+- ~15kb or less (with tree-shaking)
 - 100% TypeScript (but not required)
 - Headless (100% customizable, Bring-your-own-UI)
 - Auto out of the box, opt-in controllable state
@@ -92,73 +106,18 @@ There are a fair amount of breaking changes (they're worth it, trust us!):
 - Plugin system has been removed so plugins must be rewritten to wrap/compose the new functional API. Contact us if you need help!
 - Column configuration options have changed, but only slightly.
 - Table options are mostly the same, with some larger changes around optional state management/control and data pipeline control
-- The `tableInstance` while similar in spirit to v7 has been reconfigured to be much faster.
-
-## Todo (in order of priority)
-
-- [x] Rewrite Core
-  - [x] Core
-  - [x] Columns
-  - [x] Headers
-  - [x] Visibility
-  - [x] Pinning
-  - [x] Filters
-  - [x] Sorting
-  - [x] Grouping
-  - [x] Expanding
-  - [x] Column Sizing
-  - [x] Pagination
-  - [x] Row Selection
-- [ ] Migrate [Examples](https://github.com/tanstack/table/tree/main/examples)
-  - [x] column-visibility
-  - [x] column-ordering
-  - [x] column-pinning
-  - [x] basic
-  - [x] filters
-  - [x] sorting
-  - [x] pagination
-  - [x] pagination-controlled
-  - [x] column-sizing
-  - [x] row-selection
-  - [x] expanding
-  - [x] grouping-and-aggregation
-  - [x] editable-data
-  - [ ] kitchen-sink
-  - [x] row-dnd
-  - [ ] streaming-rows
-  - [x] sub-components
-  - [x] virtualized-rows
-  - [ ] absolute-layout
-  - [ ] block-layout
-  - [ ] animated-framer-motion
-  - [x] bootstrap
-  - [ ] bootstrap-ui-components
-  - [ ] data-driven-classes-and-styles
-  - [x] full-width-resizable-table
-  - [x] full-width-table
-  - [ ] material-ui-components
-  - [ ] material-UI-enhanced-table
+- The `table` instance while similar in spirit to v7 has been reconfigured to be much faster.
 
 ## Installation
 
+Install one of the following packages based on your framework of choice:
+
 ```bash
 # Npm
 npm install @tanstack/react-table
 npm install @tanstack/solid-table
 npm install @tanstack/vue-table
 npm install @tanstack/svelte-table
-
-#pnpm
-pnpm install @tanstack/react-table
-pnpm install @tanstack/solid-table
-pnpm install @tanstack/vue-table
-pnpm install @tanstack/svelte-table
-
-#Yarn
-yarn add @tanstack/react-table
-yarn add @tanstack/solid-table
-yarn add @tanstack/vue-table
-yarn add @tanstack/svelte-table
 ```
 
 ## How to help?
@@ -168,7 +127,6 @@ yarn add @tanstack/svelte-table
 - Introspect the types! Even without the docs finished, the library ships with 100% typescript to help you explore its capabilities.
 - [Read the contribution guidelines](https://github.com/tanstack/table/tree/main/CONTRIBUTING.md)
 - Write some docs! Start with the [API docs](https://github.com/TanStack/react-table/tree/main/docs/api) and try adding some information about one or more of the features. The types do a decent job of showing what's supported and the capabilities of the library.
-- Try your hand at migrating an example to v8! The todo list for the examples is above!
 - **Using a plugin?** Try rewriting your plugin (v8 doesn't have a plugin system any more) as a functional wrapper that uses TanStack Table internally. The new API is much more powerful and easier to compose. If you find something you can't figure out, let us know and we'll add it to the API.
 
 ### [Become a Sponsor](https://github.com/sponsors/tannerlinsley/)

diff --git a/docs/api/core/header.md b/docs/api/core/header.md
@@ -38,15 +38,15 @@ The depth of the header, zero-indexed based.
 column: Column<TData>
 ```
 
-The header's associated [Column](./column.md) object
+The header's associated [Column](./column) object
 
 ### `headerGroup`
 
 ```tsx
 headerGroup: HeaderGroup<TData>
 ```
 
-The header's associated [HeaderGroup](./header-group.md) object
+The header's associated [HeaderGroup](./header-group) object
 
 ### `subHeaders`
 

diff --git a/docs/api/core/row.md b/docs/api/core/row.md
@@ -120,4 +120,4 @@ An array of the original subRows as returned by the `options.getSubRows` option.
 type getAllCells = () => Cell<TData>[]
 ```
 
-Returns all of the [Cells](./cell.md) for the row.
+Returns all of the [Cells](./cell) for the row.
diff --git a/docs/config.json b/docs/config.json
@@ -49,13 +49,17 @@
           "label": "Migrating to V8",
           "to": "guide/migrating"
         },
+        {
+          "label": "Tables (Getting Started)",
+          "to": "guide/tables"
+        },
         {
           "label": "Column Defs",
           "to": "guide/column-defs"
         },
         {
-          "label": "Tables",
-          "to": "guide/tables"
+          "label": "Rows Models",
+          "to": "guide/row-models"
         },
         {
           "label": "Rows",
@@ -77,6 +81,10 @@
           "label": "Column Ordering",
           "to": "guide/column-ordering"
         },
+        {
+          "label": "Column Pinning",
+          "to": "guide/column-pinning"
+        },
         {
           "label": "Column Sizing",
           "to": "guide/column-sizing"
@@ -86,8 +94,20 @@
           "to": "guide/column-visibility"
         },
         {
-          "label": "Filters",
-          "to": "guide/filters"
+          "label": "Column Filtering",
+          "to": "guide/column-filtering"
+        },
+        {
+          "label": "Global Filtering",
+          "to": "guide/global-filtering"
+        },
+        {
+          "label": "Fuzzy Filtering",
+          "to": "guide/fuzzy-filtering"
+        },
+        {
+          "label": "Faceted Values",
+          "to": "guide/faceted-values"
         },
         {
           "label": "Sorting",
@@ -106,8 +126,8 @@
           "to": "guide/pagination"
         },
         {
-          "label": "Pinning",
-          "to": "guide/pinning"
+          "label": "Row Pinning",
+          "to": "guide/row-pinning"
         },
         {
           "label": "Row Selection",

diff --git a/docs/guide/column-filtering.md b/docs/guide/column-filtering.md
@@ -0,0 +1,24 @@
+---
+title: Column Filtering
+---
+
+## Examples
+
+Want to skip to the implementation? Check out these examples:
+
+- [filters](../examples/react/filters) (includes faceting)
+- [editable-data](../examples/react/editable-data)
+- [expanding](../examples/react/expanding)
+- [grouping](../examples/react/grouping)
+- [pagination](../examples/react/pagination)
+- [row-selection](../examples/react/row-selection)
+
+## API
+
+[Filters API](../api/features/filters)
+
+## Column Filtering Guide
+
+Filtering comes in 2 flavors: Column Filtering and Global Filtering.
+
+This guide will focus on column filtering, which is a filter that is applied to a single column's accessor value.
diff --git a/docs/guide/column-ordering.md b/docs/guide/column-ordering.md
@@ -12,7 +12,7 @@ Want to skip to the implementation? Check out these examples:
 
 [Column Ordering API](../api/features/column-ordering)
 
-## Overview
+## Column Ordering Guide
 
 There are 3 table features that can reorder columns, which happen in the following order:
 

diff --git a/docs/guide/column-pinning.md b/docs/guide/column-pinning.md
@@ -0,0 +1,22 @@
+---
+title: Column Pinning
+---
+
+## Examples
+
+Want to skip to the implementation? Check out these examples:
+
+- [column-pinning](../examples/react/column-pinning)
+- [row-pinning](../examples/react/row-pinning)
+
+## API
+
+[Pinning API](../api/features/pinning)
+
+## Column Pinning Guide
+
+There are 3 table features that can reorder columns, which happen in the following order:
+
+1. **Column Pinning** - If pinning, columns are split into left, center (unpinned), and right pinned columns.
+2. Manual [Column Ordering](../guide/column-ordering) - A manually specified column order is applied.
+3. [Grouping](../guide/grouping) - If grouping is enabled, a grouping state is active, and `tableOptions.columnGroupingMode` is set to `'reorder' | 'remove'`, then the grouped columns are reordered to the start of the column flow.
diff --git a/docs/guide/column-sizing.md b/docs/guide/column-sizing.md
@@ -13,7 +13,7 @@ Want to skip to the implementation? Check out these examples:
 
 [Column Sizing API](../api/features/column-sizing)
 
-## Guide
+## Column Sizing Guide
 
 The column sizing feature allows you to optionally specify the width of each column including min and max widths. It also allows you and your users the ability to dynamically change the width of all columns at will, eg. by dragging the column headers.
 

diff --git a/docs/guide/column-visibility.md b/docs/guide/column-visibility.md
@@ -12,3 +12,5 @@ Want to skip to the implementation? Check out these examples:
 ## API
 
 [Column Visibility API](../api/features/column-visibility)
+
+## Column Visibility Guide
diff --git a/docs/guide/expanding.md b/docs/guide/expanding.md
@@ -12,3 +12,5 @@ Want to skip to the implementation? Check out these examples:
 ## API
 
 [Expanding API](../api/features/expanding)
+
+## Expanding Feature Guide
diff --git a/docs/guide/faceted-values.md b/docs/guide/faceted-values.md
@@ -0,0 +1,15 @@
+---
+title: Faceted Values
+---
+
+## Examples
+
+Want to skip to the implementation? Check out these examples:
+
+- [filters](../examples/react/filters) (includes faceting)
+
+## API
+
+[Filters API](../api/features/filters)
+
+## Faceted Values Guide
diff --git a/docs/guide/features.md b/docs/guide/features.md
@@ -4,13 +4,14 @@ title: Features
 
 TanStack Table comes with many features, each with their own associated options and API:
 
-- [Column Visibility](./guide/column-visibility)
 - [Column Ordering](./guide/column-ordering)
 - [Column Pinning](./guide/column-pinning)
 - [Column Sizing](./guide/column-sizing)
+- [Column Visibility](./guide/column-visibility)
+- [Expanding](./guide/expanding)
 - [Filters](./guide/filters)
-- [Sorting](./guide/sorting)
 - [Grouping](./guide/grouping)
-- [Expanding](./guide/expanding)
-- [Row Selection](./guide/row-selection)
 - [Pagination](./guide/pagination)
+- [Row Pinning](./guide/row-pinning)
+- [Row Selection](./guide/row-selection)
+- [Sorting](./guide/sorting)
diff --git a/docs/guide/filters.md b/docs/guide/filters.md
@@ -2,28 +2,11 @@
 title: Filters
 ---
 
-## Examples
+<!-- Deprecated -->
 
-Want to skip to the implementation? Check out these examples:
+The filter guides are now split into multiple guides:
 
-- [filters](../examples/react/filters) (includes faceting)
-- [editable-data](../examples/react/editable-data)
-- [expanding](../examples/react/expanding)
-- [grouping](../examples/react/grouping)
-- [pagination](../examples/react/pagination)
-- [row-selection](../examples/react/row-selection)
-
-## API
-
-[Filters API](../api/features/filters)
-
-## Overview
-
-Filters come in two flavors:
-
-- Column filters
-  - A filter that is applied to a single column's accessor value.
-  - Stored in the `state.columnFilters` array as an object containing the columnId and the filter value.
-- Global filters
-  - A single filter value that is applied to all or some of columns' accessor values.
-  - Stored in the `state.globalFilter` array as any value, usually a string.
+- [Column Filtering](./column-filtering)
+- [Global Filtering](./global-filtering)
+- [Fuzzy Filtering](./fuzzy-filtering)
+- [Faceted Values](./faceted-values)
Original file line number	Diff line number	Diff line change
Expand Up		@@ -12,3 +12,5 @@ Want to skip to the implementation? Check out these examples:
		## API

		[Column Visibility API](../api/features/column-visibility)

		## Column Visibility Guide