docs: start faceting docs and filter example reorg (#5507)

* docs: faceting docs and filter example reorg * update lock file
TanStack · Apr 24, 2024 · 289eca3 · 289eca3
1 parent 365e0e9
commit 289eca3
Show file tree

Hide file tree

Showing 28 changed files with 1,297 additions and 195 deletions.
diff --git a/docs/config.json b/docs/config.json
@@ -382,7 +382,19 @@
             },
             {
               "to": "framework/react/examples/column-groups",
-              "label": "Column Groups"
+              "label": "Header Groups"
+            },
+            {
+              "to": "framework/react/examples/filters",
+              "label": "Column Filters"
+            },
+            {
+              "to": "framework/react/examples/filters-faceted",
+              "label": "Column Filters (Faceted)"
+            },
+            {
+              "to": "framework/react/examples/filters-fuzzy",
+              "label": "Fuzzy Search Filters"
             },
             {
               "to": "framework/react/examples/column-ordering",
@@ -424,10 +436,6 @@
               "to": "framework/react/examples/sub-components",
               "label": "Sub Components"
             },
-            {
-              "to": "framework/react/examples/filters",
-              "label": "Filters"
-            },
             {
               "to": "framework/react/examples/fully-controlled",
               "label": "Fully Controlled"

diff --git a/docs/guide/column-faceting.md b/docs/guide/column-faceting.md
@@ -6,10 +6,84 @@ title: Column Faceting Guide
 
 Want to skip to the implementation? Check out these examples:
 
-- [filters](../../framework/react/examples/filters) (includes faceting)
+- [filters-faceted](../../framework/react/examples/filters-faceted)
 
 ## API
 
 [Column Faceting API](../../api/features/column-faceting)
 
-## Column Faceting Guide
+## Column Faceting Guide
+
+Column Faceting is a feature that allows you to generate lists of values for a given column from that column's data. For example, a list of unique values in a column can be generated from all rows in that column to be used as search suggestions in an autocomplete filter component. Or, a tuple of minimum and maximum values can be generated from a column of numbers to be used as a range for a range slider filter component.
+
+### Column Faceting Row Models
+
+In order to use any of the column faceting features, you must include the appropriate row models in your table options.
+
+```ts
+//only import the row models you need
+import {
+  getCoreRowModel,
+  getFacetedRowModel,
+  getFacetedMinMaxValues, //depends on getFacetedRowModel
+  getFacetedUniqueValues, //depends on getFacetedRowModel
+}
+//...
+const table = useReactTable({
+  columns,
+  data,
+  getCoreRowModel: getCoreRowModel(),
+  getFacetedRowModel: getFacetedRowModel(), //if you need a list of values for a column (other faceted row models depend on this one)
+  getFacetedMinMaxValues: getFacetedMinMaxValues(), //if you need min/max values
+  getFacetedUniqueValues: getFacetedUniqueValues(), //if you need a list of unique values
+  //...
+})
+```
+
+First, you must include the `getFacetedRowModel` row model. This row model will generate a list of values for a given column. If you need a list of unique values, include the `getFacetedUniqueValues` row model. If you need a tuple of minimum and maximum values, include the `getFacetedMinMaxValues` row model.
+
+### Use Faceted Row Models
+
+Once you have included the appropriate row models in your table options, you will be able to use the faceting column instance APIs to access the lists of values generated by the faceted row models.
+
+```ts
+// list of unique values for autocomplete filter
+const autoCompleteSuggestions = 
+ Array.from(column.getFacetedUniqueValues().keys())
+  .sort()
+  .slice(0, 5000);
+```
+
+```ts
+// tuple of min and max values for range filter
+const [min, max] = column.getFacetedMinMaxValues() ?? [0, 1];
+```
+
+### Custom (Server-Side) Faceting
+
+If instead of using the built-in client-side faceting features, you can implement your own faceting logic on the server-side and pass the faceted values to the client-side. You can use the `getFacetedUniqueValues` and `getFacetedMinMaxValues` table options to resolve the faceted values from the server-side.
+
+```ts
+const facetingQuery = useQuery(
+  //...
+)
+
+const table = useReactTable({
+  columns,
+  data,
+  getCoreRowModel: getCoreRowModel(),
+  getFacetedRowModel: getFacetedRowModel(),
+  getFacetedUniqueValues: (table, columnId) => {
+    const uniqueValueMap = new Map<string, number>();
+    //...
+    return uniqueValueMap;
+  },
+  getFacetedMinMaxValues: (table, columnId) => {
+    //...
+    return [min, max];
+  },
+  //...
+})
+```
+
+Alternatively, you don't have to put any of your faceting logic through the TanStack Table APIs at all. Just fetch your lists and pass them to your filter components directly.
diff --git a/docs/guide/column-filtering.md b/docs/guide/column-filtering.md
@@ -7,6 +7,8 @@ title: Column Filtering Guide
 Want to skip to the implementation? Check out these examples:
 
 - [filters](../../framework/react/examples/filters) (includes faceting)
+- [filters-faceted](../../framework/react/examples/filters-faceted)
+- [filters-fuzzy](../../framework/react/examples/filters-fuzzy)
 - [editable-data](../../framework/react/examples/editable-data)
 - [expanding](../../framework/react/examples/expanding)
 - [grouping](../../framework/react/examples/grouping)

diff --git a/docs/guide/filters.md b/docs/guide/filters.md
@@ -9,4 +9,5 @@ The filter guides are now split into multiple guides:
 - [Column Filtering](../column-filtering)
 - [Global Filtering](../global-filtering)
 - [Fuzzy Filtering](../fuzzy-filtering)
-- [Faceted Values](../faceted-values)
+- [Column Faceting](../column-faceting)
+- [Global Faceting](../global-faceting)
diff --git a/docs/guide/fuzzy-filtering.md b/docs/guide/fuzzy-filtering.md
@@ -6,7 +6,7 @@ title: Fuzzy Filtering Guide
 
 Want to skip to the implementation? Check out these examples:
 
-- [filters](../../framework/react/examples/filters)
+- [filters-fuzzy](../../framework/react/examples/filters-fuzzy)
 
 ## API
 

diff --git a/docs/guide/global-faceting.md b/docs/guide/global-faceting.md
@@ -6,7 +6,7 @@ title: Global Faceting Guide
 
 Want to skip to the implementation? Check out these examples:
 
-- [filters](../../framework/react/examples/filters) (includes faceting)
+- [filters-faceted](../../framework/react/examples/filters)
 
 ## API
 

diff --git a/docs/guide/global-filtering.md b/docs/guide/global-filtering.md
@@ -6,7 +6,7 @@ title: Global Filtering Guide
 
 Want to skip to the implementation? Check out these examples:
 
-- [filters](../../framework/react/examples/filters) (includes faceting)
+- [filters-fuzzy](../../framework/react/examples/filters)
 
 ## API
 

diff --git a/docs/guide/row-models.md b/docs/guide/row-models.md
@@ -45,8 +45,8 @@ import {
 }
 //...
 const table = useReactTable({
-  data,
   columns,
+  data,
   getCoreRowModel: getCoreRowModel(),
   getExpandedRowModel: getExpandedRowModel(),
   getFacetedMinMaxValues: getFacetedMinMaxValues(),

diff --git a/examples/react/filters-faceted/.gitignore b/examples/react/filters-faceted/.gitignore
@@ -0,0 +1,5 @@
+node_modules
+.DS_Store
+dist
+dist-ssr
+*.local
diff --git a/examples/react/filters-faceted/README.md b/examples/react/filters-faceted/README.md
@@ -0,0 +1,6 @@
+# Example
+
+To run this example:
+
+- `npm install` or `yarn`
+- `npm run start` or `yarn start`
diff --git a/examples/react/filters-faceted/index.html b/examples/react/filters-faceted/index.html
@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Vite App</title>
+    <script type="module" src="https://cdn.skypack.dev/twind/shim"></script>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
diff --git a/examples/react/filters-faceted/package.json b/examples/react/filters-faceted/package.json
@@ -0,0 +1,26 @@
+{
+  "name": "tanstack-table-example-filters-faceted",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "serve": "vite preview --port 3001",
+    "start": "vite"
+  },
+  "dependencies": {
+    "@faker-js/faker": "^8.4.1",
+    "@tanstack/match-sorter-utils": "^8.15.1",
+    "@tanstack/react-table": "^8.16.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@rollup/plugin-replace": "^5.0.5",
+    "@types/react": "^18.2.70",
+    "@types/react-dom": "^18.2.22",
+    "@vitejs/plugin-react": "^4.2.1",
+    "typescript": "5.4.3",
+    "vite": "^5.2.6"
+  }
+}
diff --git a/examples/react/filters-faceted/src/index.css b/examples/react/filters-faceted/src/index.css
@@ -0,0 +1,26 @@
+html {
+  font-family: sans-serif;
+  font-size: 14px;
+}
+
+table {
+  border: 1px solid lightgray;
+}
+
+tbody {
+  border-bottom: 1px solid lightgray;
+}
+
+th {
+  border-bottom: 1px solid lightgray;
+  border-right: 1px solid lightgray;
+  padding: 2px 4px;
+}
+
+tfoot {
+  color: gray;
+}
+
+tfoot th {
+  font-weight: normal;
+}