Tabulator: confusion around the row value returned by `selection` and the click/edit events

[maximlt]

The Tabulator widget has a few attributes and events that refer to particular rows of the dataframe:

• selection: parameter list value updated when the selection changes
• ClickEvent: event registered with on_click and fired on a cell click
• TableEditEevent: event registered with on_edit and fired on a cell edit

The two events, via their row attribute, and selection, indicate the integer-location of the row(s) relative to the original dataframe, i.e widget.value.

Users have reported sometimes being confused by the semantics of the returned row value (e.g. https://github.com/holoviz/panel/issues/6997):

• Is this the DataFrame index value (df.loc) or integer-position (df.iloc)?
• Is this relative to the original dataframe, or to the sorted | filtered | paginated dataframe?

I would also like to report a small UX issue with the events in particular, which return row and column that often leads me to incorrectly use df.loc[event.row, event.column] when I want to get a handle on the complete row. df.loc will only work if the dataframe has the default Pandas index, otherwise, it will error or, worse, return the wrong row (e.g. with a dataframe that's already be filtered in a preprocessing step). The right call to make is df.loc[df.index.get_loc(event.row), event.column], or alternatively df.iloc[event.row, df.columns.get_loc(event.column)].

• Should the API be improved? => I think so!
• Should the docs be improved? => Even if we already attempt to precise some of the above, I'm sure that we could do better.

[philippjfr]

I'd suggest we add the row index to the events to distinguish and then improve the documentation to be very clear that the .selection and the event row values are integer indexes into the original data.

[philippjfr]

Also let's make sure we add nicer docstrings to the CellClickEvent and TableEditEvent.