(DNM) Add TableView expandable rows docs

packages/@react-spectrum/table/docs/TableView.mdx

@@ -76,7 +76,7 @@ keywords: [table, grid]
 ```
 
 ## Content
-TableView is a complex [collection component](../react-stately/collections.html) that is built up from many child elements including columns, rows, and cells. Columns are defined within a TableHeader element and rows are defined within a TableBody element. Rows contain Cell elements that correspond to each column. Cells can contain any element, allowing you to have focusable children within the TableView.
+TableView is a complex [collection component](../react-stately/collections.html) that is built up from many child elements including columns, rows, and cells. Columns are defined within a TableHeader element and rows are defined within a TableBody element. Rows contain `Cell` elements that correspond to each column. Cells can contain any element, allowing you to have focusable children within the TableView.
 
 Basic usage of TableView, seen in the example above, shows the use of a static collection where the contents of the TableView is hard coded. Dynamic collections, as shown below, can be used when the options come from an external data source such as an API, or update over time. Providing the data in this way allows TableView to automatically cache the rendering of each item, which dramatically improves performance.
 
@@ -367,7 +367,7 @@ function AsyncTable() {
 ## Selection
 
 By default, TableView doesn't allow row selection but this can be enabled using the `selectionMode` prop.
-Use `defaultSelectedKeys` to provide a default set of selected rows. Note that the value of the selected keys must match the `key` prop of the Row.
+Use `defaultSelectedKeys` to provide a default set of selected rows. Note that the value of the selected keys must match the `key` prop of the `Row`.
 
 The example below enables multiple selection mode, and uses `defaultSelectedKeys` to select the rows with keys "2" and "4".
 
@@ -1622,6 +1622,119 @@ function CustomDragPreviewExample() {
 <CustomDragPreviewExample />
 ```
 
+## Expandable Rows <VersionBadge version="alpha" style={{marginLeft: 4, verticalAlign: 'bottom'}} />
+
+By default, TableView doesn't allow expandable rows, but this can be enabled by toggling the feature flag via `enableTableNestedRows` in your app and then providing the `UNSTABLE_allowsExpandableRows` prop to
+your TableView.
+
+```tsx example
+import {enableTableNestedRows} from '@react-stately/flags';
+
+enableTableNestedRows();
+```
+<br />
+
+Use `UNSTABLE_defaultExpandedKeys` to provide a default set of expanded rows. Note that the value of the expanded keys must match the `key` prop of the `Row` and that an
+expanded child row will only be visible if its parent row key is also included within the expanded key set.
+
+An expandable row can be statically defined by including one or more `Rows` as children. Note that all child `Rows` must be placed after the last `Cell` within the parent `Row`.
+
+The example below enables expandable rows, and uses `UNSTABLE_defaultExpandedKeys` to expand rows with keys "1" and "2".
+
+```tsx example
+<TableView aria-label="Example table with expandable rows" UNSTABLE_allowsExpandableRows UNSTABLE_defaultExpandedKeys={['1', '2']} height="size-4600">
+  <TableHeader>
+    <Column>Name</Column>
+    <Column>Capital</Column>
+    <Column align="end">Population</Column>
+  </TableHeader>
+  <TableBody>
+    <Row key="1">
+      <Cell>United States</Cell>
+      <Cell>Washington, D.C.</Cell>
+      <Cell>331.9 million</Cell>
+      <Row key="2">
+        <Cell>California</Cell>
+        <Cell>Sacramento</Cell>
+        <Cell>39.24 million</Cell>
+        <Row key="3">
+          <Cell>San Jose</Cell>
+          <Cell>-</Cell>
+          <Cell>983.4 thousand</Cell>
+        </Row>
+      </Row>
+    <Row key="4">
+      <Cell>Texas</Cell>
+      <Cell>Austin</Cell>
+      <Cell>29.53 million</Cell>
+      <Row key="5">
+        <Cell>Dallas</Cell>
+        <Cell>-</Cell>
+        <Cell>1.28 million</Cell>
+      </Row>
+    </Row>
+  </Row>
+  </TableBody>
+</TableView>
+```
+
+### Controlled expandable rows
+
+To programmatically control row expansion, use the `UNSTABLE_expandedKeys` prop paired with the `UNSTABLE_onExpandedChange` callback. The `key` prop from the expanded rows will
+be passed into the callback when the row's expand button is pressed, allowing you to update state accordingly.
+
+Here is how you would control expanded rows for the above example. Additionally, note how expandable rows can be dynamically defined by providing the child rows data to the
+parent `Row`'s `UNSTABLE_childItems` prop.
+
+```tsx example
+import type {Key} from '@react-types/shared';
+
+interface ColumnDefinition {
+  name: string,
+  key: string,
+}
+
+function TableExample(props) {
+  let columns: ColumnDefinition[] = [
+    {name: 'Name', key: 'name'},
+    {name: 'Capital', key: 'capital'},
+    {name: 'Population', key: 'population'}
+  ];
+
+  let nestedRows = [
+    {key: '1', name: 'United States', capital: 'Washington, D.C.', population: '331.9 million', childRows: [
+      {key: '2', name: 'California', capital: 'Sacramento', population: '39.24 million', childRows: [
+        {key: '3', name: 'San Jose', capital: '-', population: '983.4 thousand'}
+      ]},
+      {key: '4', name: 'Texas', capital: 'Austin', population: '29.53 million', childRows: [
+        {key: '5', name: 'Dallas', capital: '-', population: '1.28 million'}
+      ]}
+    ]}
+  ];
+
+  let [expandedKeys, setExpandedKeys] = React.useState<'all' | Iterable<Key>>('all');
+
+  return (
+    <TableView aria-label="Example table with controlled expandable rows" UNSTABLE_allowsExpandableRows UNSTABLE_expandedKeys={expandedKeys} UNSTABLE_onExpandedChange={setExpandedKeys} height="size-4600">
+      <TableHeader columns={columns}>
+        {column => (
+          <Column align={column.key === 'population' ? 'end' : 'start'}>
+            {column.name}
+          </Column>
+        )}
+      </TableHeader>
+      <TableBody items={nestedRows}>
+        {item => (
+          <Row key={item.key} UNSTABLE_childItems={item.childRows}>
+            {(key) => <Cell>{item[key]}</Cell>}
+          </Row>
+        )}
+      </TableBody>
+    </TableView>
+  );
+}
+```
+
 ## Props
 
 ### TableView props

packages/@react-spectrum/table/src/TableViewWrapper.tsx

@@ -58,28 +58,24 @@ export interface SpectrumTableProps<T> extends TableProps<T>, SpectrumSelectionP
   /**
    * Whether the TableView should support expandable rows. Requires the feature flag to be enabled first, see https://react-spectrum.adobe.com/react-spectrum/TableView.html#expandable-rows.
    * @version alpha
-   * @private
    */
   UNSTABLE_allowsExpandableRows?: boolean,
   /**
    * The currently expanded keys in the collection (controlled). Requires the feature flag to be
    * enabled along with UNSTABLE_allowsExpandableRows, see https://react-spectrum.adobe.com/react-spectrum/TableView.html#expandable-rows.
    * @version alpha
-   * @private
    */
   UNSTABLE_expandedKeys?: 'all' | Iterable<Key>,
   /**
    * The initial expanded keys in the collection (uncontrolled). Requires the feature flag to be
    * enabled along with UNSTABLE_allowsExpandableRows, see https://react-spectrum.adobe.com/react-spectrum/TableView.html#expandable-rows.
    * @version alpha
-   * @private
    */
   UNSTABLE_defaultExpandedKeys?: 'all' | Iterable<Key>,
   /**
    * Handler that is called when items are expanded or collapsed. Requires the feature flag to be
    * enabled along with UNSTABLE_allowsExpandableRows, see https://react-spectrum.adobe.com/react-spectrum/TableView.html#expandable-rows.
    * @version alpha
-   * @private
    */
   UNSTABLE_onExpandedChange?: (keys: Set<Key>) => any
 }

packages/@react-types/table/src/index.d.ts

@@ -137,7 +137,6 @@ export interface RowProps<T> extends LinkDOMProps {
    * A list of child item objects used when dynamically rendering row children. Requires the feature flag to be
    * enabled along with UNSTABLE_allowsExpandableRows, see https://react-spectrum.adobe.com/react-spectrum/TableView.html#expandable-rows.
    * @version alpha
-   * @private
    */
   UNSTABLE_childItems?: Iterable<T>,
   // TODO: update when async loading is supported for expandable rows