docs: header and column docs (#5531)

* docs: header and column docs

* undo example log

Author: KevinVandy

docs/guide/cells.md

@@ -8,7 +8,7 @@ title: Cells Guide
 
 ## Cells Guide
 
-This quick guide will discuss the different ways you can retrieve and interact with cell objects in TanStack Table.
+This quick guide will discuss the different ways you can retrieve and interact with `cell` objects in TanStack Table.
 
 ### Where to Get Cells From
 

docs/guide/column-defs.md

@@ -8,6 +8,8 @@ title: Columns Guide
 
 ## Column Definitions Guide
 
+> Note: This guide is about setting up column definitions for your table and NOT about the actual [`column`](../columns) objects that are generated within the table instance.
+
 Column defs are the single most important part of building a table. They are responsible for:
 
 - Building the underlying data model that will be used for everything including sorting, filtering, grouping, etc.

docs/guide/columns.md

@@ -6,4 +6,67 @@ title: Columns Guide
 
 [Header API](../../api/core/column)
 
-## Columns Guide
+## Columns Guide
+
+> Note: This guide is about the actual `column` objects that are generated within the table instance and NOT about setting up the [column definitions](../column-defs) for your table.
+
+This quick guide will discuss the different ways you can retrieve and interact with `column` objects in TanStack Table.
+
+### Where to Get Columns From
+
+You can find the `column` objects in many places. They are often attached
+
+#### Header and Cell Objects
+
+Before you reach for one of the `table` instance APIs, consider if you actually need to retrieve either [`headers`](../headers) or [`cells`](../cells) instead of `columns`. If you are rending out the markup for your table, you will most likely want to reach for the APIs that return headers or cells instead of columns. The column objects themselves are not really meant to render out the headers or cells, but the `header` and `cell` objects will contain references to these `column` objects from which they can derive the necessary information to render their UI.
+
+```js
+const column = cell.column; // get column from cell
+const column = header.column; // get column from header
+```
+
+#### Column Table Instance APIs
+
+There are dozens of `table` instance APIs you can use to retrieve columns from the table instance. Which APIs you will use will depend entirely on which features you are using in your table and your use-case.
+
+##### Get Column
+
+If you need to just get a single column by its ID, you can use the `table.getColumn` API.
+
+```js
+const column = table.getColumn('firstName');
+```
+
+##### Get Columns
+
+The simplest column API is `table.getAllColumns`, which will return a list of all columns in the table. There are dozens of other column APIs that are affected by other features and the state of the table that come alongside this API though. `table.getAllFlatColumns`, `table.getAllLeafColumns`, `getCenterLeafColumns`, `table.getLeftVisibleLeafColumns` are just some examples of other column APIs that you might use in tandem with the column visibility or column pinning features.
+
+### Column Objects
+
+Column objects are not actually meant to be used to render out the table UI directly, so they are not associated 1-to-1 with any `<th>` or `<td>` elements in your table, but they contain a lot of useful properties and methods that you can use to interact with the table state.
+
+#### Column IDs
+
+Every column must have a unique `id` defined in their associated [Column Definition](../column-defs). Usually, you define this `id` yourself, or it is derived from the `accessorKey` or `header` properties in the column definition.
+
+#### ColumnDef
+
+A reference to the original `columnDef` object that was used to created the column is always available on the column object.
+
+#### Nested Grouped Columns Properties
+
+There are a few properties on `column` objects that are only useful if the column is part of a nested or grouped column structure. These properties include:
+
+- `columns`: An array of child columns that belong to a group column.
+- `depth`: The header group "row index" that the column group belongs to.
+- `parent`: The parent column of the column. If the column is a top-level column, this will be `undefined`.
+
+### More Column APIs
+
+There are dozens of Column APIs that you can use to interact with the table state and extract cell values from the table based on the state of the table. See each features column API documentation for more information.
+
+### Column Rendering
+
+Don't necessarily use `column` objects to render `headers` or `cells` directly. Instead, use the [`header](../headers) and [`cell`](../cells) objects, as discussed above.
+
+But if you are just rendering a list of columns somewhere else in your UI for something like a column visibility menu or something similar, you can just map over a columns array and render out the UI as you normally would.

docs/guide/headers.md

@@ -6,4 +6,79 @@ title: Headers Guide
 
 [Header API](../../api/core/header)
 
-## Headers Guide
+## Headers Guide
+
+This quick guide will discuss the different ways you can retrieve and interact with `header` objects in TanStack Table.
+
+Headers are the equivalent of cells, but meant for the `<thead>` section of the table instead of the `<tbody>` section.
+
+### Where to Get Headers From
+
+Headers come from [Header Groups](../header-groups), which are the equivalent of rows, but meant for the `<thead>` section of the table instead of the `<tbody>` section.
+
+#### HeaderGroup Headers
+
+If you are in a header group, the headers are stored as an array in the `headerGroup.headers` property. Usually you will just map over this array to render your headers.
+
+```jsx
+<thead>
+  {table.getHeaderGroups().map(headerGroup => {
+    return (
+      <tr key={headerGroup.id}>
+        {headerGroup.headers.map(header => ( // map over the headerGroup headers array
+          <th key={header.id} colSpan={header.colSpan}>
+            {/* */}
+          </th>
+        ))}
+      </tr>
+    )
+  })}
+</thead>
+```
+
+#### Header Table Instance APIs
+
+There are multiple `table` instance APIs that you can use to retrieve a list of headers depending on the features that you are using. The most common API you might use is `table.getFlatHeaders`, which will return a flat list of all headers in the table, but there are at least a dozen other headers that are useful in tandem with the column visibility and column pinning features. APIs like `table.getLeftLeafHeaders` or `table.getRightFlatHeaders` could be useful depending on your use case.
+
+### Header Objects
+
+Header objects are similar to [Cell](../cells) objects, but meant for the `<thead>` section of the table instead of the `<tbody>` section. Every header object can be associated with a `<th>` or similar cell element in your UI. There are a few properties and methods on `header` objects that you can use to interact with the table state and extract cell values from the table based on the state of the table.
+
+#### Header IDs
+
+Every header object has an `id` property that makes it unique within the table instance. Usually you only need this `id` as a unique identifier for React keys or if you are following the [performant column resizing example](../../framework/react/examples/column-resizing-performant).
+
+For simple headers with no advanced nested or grouped headers logic, the `header.id` will be the same as it's parent `column.id`. However, if the header is part group column or a placeholder cell, it will have a more complicated id that is constructed from the header family, depth/header row index, column id, and header group id.
+
+#### Nested Grouped Headers Properties
+
+There are a few properties on `header` objects that are only useful if the header is part of a nested or grouped header structure. These properties include:
+
+- `colspan`: The number of columns that the header should span. This is useful for rendering the `colSpan` attribute on the `<th>` element.
+- `rowSpan`: The number of rows that the header should span. This is useful for rendering the `rowSpan` attribute on the `<th>` element. (Currently not implemented in default TanStack Table)
+- `depth`: The header group "row index" that the header group belongs to.
+- `isPlaceholder`: A boolean flag that is true if the header is a placeholder header. Placeholder headers are used to fill in the gaps when a column is hidden or when a column is part of a group column.
+- `placeholderId`: The unique identifier for the placeholder header.
+- `subHeaders`: The array of sub/child headers that belong to this header. Will be empty if the header is a leaf header.
+
+> Note: `header.index` refers to its index within the header group (row of headers), i.e. its position from left to right. It is not the same as `header.depth`, which refers to the header group "row index".
+
+#### Header Parent Objects
+
+Every header stores a reference to its parent [column](../columns) object and its parent [header group](../header-groups) object.
+
+### More Header APIs
+
+Headers have a few more useful APIs attached to them that are useful for interacting with the table state. Most of them relate to the Column sizing and resizing features. See the [Column Resizing Guide](../column-resizing) for more information.
+
+### Header Rendering
+
+Since the `header` column option you defined can be either a string, jsx, or a function returning either of those, the best way to render the headers is to use the `flexRender` utility from your adapter, which will handle all of those cases for you.
+
+```jsx
+{headerGroup.headers.map(header => (
+  <th key={header.id} colSpan={header.colSpan}>
+    {/* Handles all possible header column def scenarios for `header` */}
+    {flexRender(header.column.columnDef.header, header.getContext())}
+  </th>
+))}

docs/guide/tables.md

@@ -10,6 +10,8 @@ title: Table Instance Guide
 
 TanStack Table is a headless UI library. When we talk about the `table` or "table instance", we're not talking about a literal `<table>` element. Instead, we're referring to the core table object that contains the table state and APIs. The `table` instance is created by calling your adapter's `createTable` function (e.g. `useReactTable`, `createSolidTable`, `createSvelteTable`, `useQwikTable`, `useVueTable`).
 
+The `table` instance that is returned from the `createTable` function (from the framework adapter) is the main object that you will interact with to read and mutate the table state. It is the one place where everything happens in TanStack Table.
+
 ### Creating a Table Instance
 
 To create a table instance, 2 `options` are required: `columns` and `data`. There are dozens of other table options to configure features and behavior, but these 2 are required.