render.data_frame: change to iloc instead of loc

Instead of returning Pandas index values for selected rows, use 0-indexed row
numbers instead. This is more likely to work with non-Pandas data frame libraries
in the future, and also saves us from needing to try to serialize/deserialize
arbitrary index types.

Author: jcheng5

e2e/bugs/0676-row-selection/app.py

@@ -39,7 +39,7 @@ def detail():
             and len(input.grid_selected_rows()) > 0
         ):
             # "split", "records", "index", "columns", "values", "table"
-            return df.loc[list(input.grid_selected_rows())]
+            return df.iloc[list(input.grid_selected_rows())]
 
 
 app = App(app_ui, server, debug=True)

js/dataframe/index.tsx

@@ -60,16 +60,6 @@ const ShinyDataGrid: FC<ShinyDataGridProps<unknown>> = (props) => {
   const { id, data, bgcolor } = props;
   const { columns, index, type_hints, data: rowData } = data;
   const { width, height, filters: withFilters } = data.options;
-  // The terminology here is a bit confusing. The "key" is the `data-key` attribute on
-  // the table>tbody>tr, which is populated by Tanstack table API's row id, which is
-  // always [0, 1, 2, ...]. The "index" refers to the Pandas index coming from the
-  // Python side, which may or may not be [0, 1, 2, ...]--it could be strings,
-  // discontiguous numbers, or whatever. So the keyToIndex map lets you convert a
-  // Tanstack row to the Pandas index.
-  const keyToIndex: Record<string, unknown> = {};
-  index.forEach((value, i) => {
-    keyToIndex[i + ""] = value;
-  });
 
   const containerRef = useRef<HTMLDivElement>(null);
   const theadRef = useRef<HTMLTableSectionElement>(null);
@@ -198,7 +188,7 @@ const ShinyDataGrid: FC<ShinyDataGridProps<unknown>> = (props) => {
           rowSelection
             .keys()
             .toList()
-            .map((key) => keyToIndex[key])
+            .map((key) => parseInt(key))
         );
       }
     }

shiny/api-examples/data_frame/app.py

@@ -63,6 +63,8 @@ def summary_data():
 
     @reactive.Calc
     def filtered_df():
+        # input.summary_data_selected_rows() is a tuple, so we must convert it to list,
+        # as that's what Pandas requires for indexing.
         selected_idx = list(req(input.summary_data_selected_rows()))
         countries = summary_df["country"][selected_idx]
         # Filter data for selected countries

shiny/render/_dataframe.py

@@ -255,29 +255,44 @@ def data_frame(
     _fn: DataFrameTransformer.ValueFn | None = None,
 ) -> DataFrameTransformer.OutputRenderer | DataFrameTransformer.OutputRendererDecorator:
     """
-    Reactively render a Pandas data frame object (or similar) as a basic HTML table.
-
+    Reactively render a Pandas data frame object (or similar) as an interactive table or
+    grid. Features fast virtualized scrolling, sorting, filtering, and row selection
+    (single or multiple).
 
     Returns
     -------
     :
         A decorator for a function that returns any of the following:
 
-        1. A pandas :class:`DataFrame` object.
-        2. A pandas :class:`Styler` object.
+        1. A :class:`~shiny.render.DataGrid` or :class:`~shiny.render.DataTable` object,
+           which can be used to customize the appearance and behavior of the data frame
+           output.
+        2. A pandas :class:`DataFrame` object. (Equivalent to
+           `shiny.render.DataGrid(df)`.)
         3. Any object that has a `.to_pandas()` method (e.g., a Polars data frame or
-           Arrow table).
+           Arrow table). (Equivalent to `shiny.render.DataGrid(df.to_pandas())`.)
+
+    Row selection
+    -------------
+    When using the row selection feature, you can access the selected rows by using the
+    `input.<id>_selected_rows()` function, where `<id>` is the `id` of the
+    :func:`~shiny.ui.output_data_frame`. The value returned will be `None` if no rows
+    are selected, or a tuple of integers representing the indices of the selected rows.
+    To filter a pandas data frame down to the selected rows, use
+    `df.iloc[list(input.<id>_selected_rows())]`.
 
     Tip
     ----
     This decorator should be applied **before** the ``@output`` decorator. Also, the
-    name of the decorated function (or ``@output(id=...)``) should match the ``id`` of
-    a :func:`~shiny.ui.output_table` container (see :func:`~shiny.ui.output_table` for
+    name of the decorated function (or ``@output(id=...)``) should match the ``id`` of a
+    :func:`~shiny.ui.output_table` container (see :func:`~shiny.ui.output_table` for
     example usage).
 
     See Also
     --------
-    ~shiny.ui.output_data_frame
+    * :func:`~shiny.ui.output_data_frame`
+    * :class:`~shiny.render.DataGrid` and :class:`~shiny.render.DataTable` are the
+      objects you can return from the rendering function to specify options.
     """
     return DataFrameTransformer(_fn)
 

shiny/ui/dataframe/_dataframe.py

@@ -23,12 +23,13 @@ def data_frame_deps() -> HTMLDependency:
 
 def output_data_frame(id: str) -> Tag:
     """
-    Create a output container for a data frame.
+    Create an output container for an interactive table or grid. Features fast
+    virtualized scrolling, sorting, filtering, and row selection (single or multiple).
 
     Parameters
     ----------
     id
-        An input id.
+        An output id.
 
     Returns
     -------