hover cell, proof of concept

Author: nojaf

frontend/src/components/data-table/cell-hover-text/feature.ts

@@ -0,0 +1,43 @@
+/* Copyright 2024 Marimo. All rights reserved. */
+"use no memo";
+
+import type {
+  Cell,
+  Column,
+  InitialTableState,
+  Row,
+  RowData,
+  Table,
+  TableFeature,
+} from "@tanstack/react-table";
+import { INDEX_COLUMN_NAME } from "../types";
+import type { CellHoverTextState, CellHoverTextTableState } from "./types";
+
+function getRowId<TData>(row: Row<TData>): string {
+  if (row && typeof row === "object" && INDEX_COLUMN_NAME in row) {
+    return String(row[INDEX_COLUMN_NAME]);
+  }
+  return row.id;
+}
+
+export const CellHoverTextFeature: TableFeature = {
+  getInitialState: (state?: InitialTableState): CellHoverTextTableState => {
+    return {
+      ...state,
+      cellHoverText: {} as CellHoverTextState,
+    };
+  },
+
+  createCell: <TData extends RowData>(
+    cell: Cell<TData, unknown>,
+    column: Column<TData>,
+    row: Row<TData>,
+    table: Table<TData>,
+  ) => {
+    cell.getUserHoverText = () => {
+      const state = table.getState().cellHoverText;
+      const rowId = getRowId(row);
+      return state?.[rowId]?.[column.id] || undefined;
+    };
+  },
+};

frontend/src/components/data-table/cell-hover-text/types.ts

@@ -0,0 +1,26 @@
+/* Copyright 2024 Marimo. All rights reserved. */
+/* eslint-disable @typescript-eslint/no-empty-interface */
+import type { RowData } from "@tanstack/react-table";
+
+export type CellHoverTextState = Record<
+  string,
+  Record<string, string | null | undefined>
+>;
+
+export interface CellHoverTextTableState {
+  cellHoverText: CellHoverTextState | null;
+}
+
+export interface CellHoverTextCell {
+  /**
+   * Returns a hover text for the cell.
+   */
+  getUserHoverText?: () => string | undefined;
+}
+
+// Use declaration merging to add our new feature APIs
+declare module "@tanstack/react-table" {
+  interface TableState extends CellHoverTextTableState {}
+
+  interface Cell<TData extends RowData, TValue> extends CellHoverTextCell {}
+}

frontend/src/components/data-table/data-table.tsx

@@ -24,6 +24,8 @@ import { Table } from "@/components/ui/table";
 import type { GetRowIds } from "@/plugins/impl/DataTablePlugin";
 import { cn } from "@/utils/cn";
 import type { PanelType } from "../editor/chrome/panels/context-aware-panel/context-aware-panel";
+import { CellHoverTextFeature } from "./cell-hover-text/feature";
+import type { CellHoverTextState } from "./cell-hover-text/types";
 import { CellSelectionFeature } from "./cell-selection/feature";
 import type { CellSelectionState } from "./cell-selection/types";
 import { CellStylingFeature } from "./cell-styling/feature";
@@ -63,6 +65,7 @@ interface DataTableProps<TData> extends Partial<DownloadActionProps> {
   rowSelection?: RowSelectionState;
   cellSelection?: CellSelectionState;
   cellStyling?: CellStyleState | null;
+  cellHoverText?: CellHoverTextState | null;
   onRowSelectionChange?: OnChangeFn<RowSelectionState>;
   onCellSelectionChange?: OnChangeFn<CellSelectionState>;
   getRowIds?: GetRowIds;
@@ -103,6 +106,7 @@ const DataTableInternal = <TData,>({
   rowSelection,
   cellSelection,
   cellStyling,
+  cellHoverText,
   paginationState,
   setPaginationState,
   downloadAs,
@@ -176,6 +180,7 @@ const DataTableInternal = <TData,>({
       ColumnFormattingFeature,
       CellSelectionFeature,
       CellStylingFeature,
+      CellHoverTextFeature,
       CopyColumnFeature,
       FocusRowFeature,
     ],
@@ -236,6 +241,7 @@ const DataTableInternal = <TData,>({
       rowSelection,
       cellSelection,
       cellStyling,
+      cellHoverText,
       columnPinning: columnPinning,
     },
   });

frontend/src/components/data-table/renderers.tsx

@@ -101,6 +101,7 @@ export const DataTableBody = <TData,>({
         cell.getUserStyling?.() || {},
         pinningstyle,
       );
+      const hoverText = cell.getUserHoverText?.();
       return (
         <TableCell
           tabIndex={0}
@@ -117,6 +118,7 @@ export const DataTableBody = <TData,>({
           onMouseDown={(e) => handleCellMouseDown(e, cell)}
           onMouseUp={handleCellMouseUp}
           onMouseOver={(e) => handleCellMouseOver(e, cell)}
+          title={hoverText}
         >
           <CellRangeSelectionIndicator cellId={cell.id} />
           <div className="relative">

frontend/src/plugins/impl/DataTablePlugin.tsx

@@ -22,6 +22,7 @@ import React, {
 } from "react";
 import useEvent from "react-use-event-hook";
 import { z } from "zod";
+import type { CellHoverTextState } from "@/components/data-table/cell-hover-text/types";
 import type { CellSelectionState } from "@/components/data-table/cell-selection/types";
 import type { CellStyleState } from "@/components/data-table/cell-styling/types";
 import { TablePanel } from "@/components/data-table/charts/charts";
@@ -208,6 +209,7 @@ type DataTableFunctions = {
     data: TableData<T>;
     total_rows: number | TooManyRows;
     cell_styles?: CellStyleState | null;
+    cell_hover_texts?: CellHoverTextState | null;
   }>;
   get_data_url?: GetDataUrl;
   get_row_ids?: GetRowIds;
@@ -254,6 +256,7 @@ export const DataTablePlugin = createPlugin<S>("marimo-table")
       maxColumns: z.union([z.number(), z.literal("all")]).default("all"),
       hasStableRowId: z.boolean().default(false),
       cellStyles: z.record(z.record(z.object({}).passthrough())).optional(),
+      cellHoverTexts: z.record(z.record(z.string().nullish())).optional(),
       // Whether to load the data lazily.
       lazy: z.boolean().default(false),
       // If lazy, this will preload the first page of data
@@ -298,6 +301,9 @@ export const DataTablePlugin = createPlugin<S>("marimo-table")
           cell_styles: z
             .record(z.record(z.object({}).passthrough()))
             .nullable(),
+          cell_hover_texts: z
+            .record(z.record(z.string().nullable().optional()))
+            .nullable(),
         }),
       ),
     get_row_ids: rpc.input(z.object({}).passthrough()).output(
@@ -385,6 +391,7 @@ interface DataTableProps<T> extends Data<T>, DataTableFunctions {
   // Filters
   enableFilters?: boolean;
   cellStyles?: CellStyleState | null;
+  cellHoverTexts?: CellHoverTextState | null;
   toggleDisplayHeader?: () => void;
   host: HTMLElement;
   cellId?: CellId | null;
@@ -453,16 +460,23 @@ export const LoadingDataTableComponent = memo(
       rows: T[];
       totalRows: number | TooManyRows;
       cellStyles: CellStyleState | undefined | null;
+      cellHoverTexts: CellHoverTextState | undefined | null;
     }>(async () => {
       // If there is no data, return an empty array
       if (props.totalRows === 0) {
-        return { rows: Arrays.EMPTY, totalRows: 0, cellStyles: {} };
+        return {
+          rows: Arrays.EMPTY,
+          totalRows: 0,
+          cellStyles: {},
+          cellHoverTexts: {},
+        };
       }
 
       // Table data is a url string or an array of objects
       let tableData = props.data;
       let totalRows = props.totalRows;
       let cellStyles = props.cellStyles;
+      let cellHoverTexts = props.cellHoverTexts;
 
       const pageSizeChanged = paginationState.pageSize !== props.pageSize;
 
@@ -513,12 +527,14 @@ export const LoadingDataTableComponent = memo(
         tableData = searchResults.data;
         totalRows = searchResults.total_rows;
         cellStyles = searchResults.cell_styles || {};
+        cellHoverTexts = searchResults.cell_hover_texts || {};
       }
       tableData = await loadTableData(tableData);
       return {
         rows: tableData,
         totalRows: totalRows,
         cellStyles,
+        cellHoverTexts,
       };
     }, [
       sorting,
@@ -644,6 +660,7 @@ export const LoadingDataTableComponent = memo(
         paginationState={paginationState}
         setPaginationState={setPaginationState}
         cellStyles={data?.cellStyles ?? props.cellStyles}
+        cellHoverTexts={data?.cellHoverTexts ?? props.cellHoverTexts}
         toggleDisplayHeader={toggleDisplayHeader}
         getRow={getRow}
         cellId={cellId}
@@ -707,6 +724,7 @@ const DataTableComponent = ({
   totalColumns,
   get_row_ids,
   cellStyles,
+  cellHoverTexts,
   toggleDisplayHeader,
   calculate_top_k_rows,
   preview_column,
@@ -904,6 +922,7 @@ const DataTableComponent = ({
             rowSelection={rowSelection}
             cellSelection={cellSelection}
             cellStyling={cellStyles}
+            cellHoverText={cellHoverTexts}
             downloadAs={showDownload ? downloadAs : undefined}
             enableSearch={enableSearch}
             searchQuery={searchQuery}

marimo/_plugins/ui/_impl/table.py

@@ -126,13 +126,15 @@ class SearchTableArgs:
 
 
 CellStyles = dict[RowId, dict[ColumnName, dict[str, Any]]]
+CellHoverTexts = dict[RowId, dict[ColumnName, str | None]]
 
 
 @dataclass(frozen=True)
 class SearchTableResponse:
     data: str
     total_rows: Union[int, Literal["too_many"]]
     cell_styles: Optional[CellStyles] = None
+    cell_hover_texts: Optional[CellHoverTexts] = None
 
 
 @dataclass(frozen=True)
@@ -439,6 +441,7 @@ def __init__(
             ]
         ] = None,
         style_cell: Optional[Callable[[str, str, Any], dict[str, Any]]] = None,
+        hover_cell: Optional[Callable[[str, str, Any], str]] = None,
         # The _internal_* arguments are for overriding and unit tests
         # table should take the value unconditionally
         _internal_column_charts_row_limit: Optional[int] = None,
@@ -603,8 +606,10 @@ def __init__(
                 pagination = False
 
         self._style_cell = style_cell
+        self._hover_cell = hover_cell
 
         search_result_styles: Optional[CellStyles] = None
+        search_result_hover_texts: Optional[CellHoverTexts] = None
         search_result_data: JSONType = []
         field_types: Optional[FieldTypes] = None
         num_columns = 0
@@ -621,6 +626,7 @@ def __init__(
                 )
             )
             search_result_styles = search_result.cell_styles
+            search_result_hover_texts = search_result.cell_hover_texts
             search_result_data = search_result.data
 
             # Validate column configurations
@@ -666,6 +672,7 @@ def __init__(
                 "wrapped-columns": wrapped_columns,
                 "has-stable-row-id": self._has_stable_row_id,
                 "cell-styles": search_result_styles,
+                "cell-hover-texts": search_result_hover_texts,
                 "lazy": _internal_lazy,
                 "preload": _internal_preload,
             },
@@ -1171,6 +1178,42 @@ def do_style_cell(row: str, col: str) -> dict[str, Any]:
             for row in row_ids
         }
 
+    def _hover_cells(
+        self, skip: int, take: int, total_rows: Union[int, Literal["too_many"]]
+    ) -> Optional[CellHoverTexts]:
+        """Calculate the hover text of the cells in the table."""
+        if self._hover_cell is None:
+            return None
+
+        def get_hover_text_of_cell(row: str, col: str) -> str | None:
+            selected_cells = self._searched_manager.select_cells(
+                [TableCoordinate(row_id=row, column_name=col)]
+            )
+            if not selected_cells or self._hover_cell is None:
+                return None
+            return self._hover_cell(row, col, selected_cells[0].value)
+
+        columns = self._searched_manager.get_column_names()
+        response = self._get_row_ids(EmptyArgs())
+
+        # Clamp the take to the total number of rows
+        if total_rows != "too_many" and skip + take > total_rows:
+            take = total_rows - skip
+
+        # Determine row range
+        row_ids: Union[list[int], range]
+        if response.all_rows or response.error:
+            row_ids = range(skip, skip + take)
+        else:
+            row_ids = response.row_ids[skip : skip + take]
+
+        return {
+            str(row): {
+                col: get_hover_text_of_cell(str(row), col) for col in columns
+            }
+            for row in row_ids
+        }
+
     def _search(self, args: SearchTableArgs) -> SearchTableResponse:
         """Search and filter the table data.
 
@@ -1193,6 +1236,7 @@ def _search(self, args: SearchTableArgs) -> SearchTableResponse:
                 - data: Filtered and formatted table data for the requested page
                 - total_rows: Total number of rows after applying filters
                 - cell_styles: User defined styling information for each cell in the page
+                - cell_hover_texts: User defined hover information for each cell in the page
         """
         offset = args.page_number * args.page_size
         max_columns = args.max_columns
@@ -1231,6 +1275,9 @@ def clamp_rows_and_columns(manager: TableManager[Any]) -> str:
                 cell_styles=self._style_cells(
                     offset, args.page_size, total_rows
                 ),
+                cell_hover_texts=self._hover_cells(
+                    offset, args.page_size, total_rows
+                ),
             )
 
         filter_function = (
@@ -1261,6 +1308,9 @@ def clamp_rows_and_columns(manager: TableManager[Any]) -> str:
             data=clamp_rows_and_columns(result),
             total_rows=total_rows,
             cell_styles=self._style_cells(offset, args.page_size, total_rows),
+            cell_hover_texts=self._hover_cells(
+                offset, args.page_size, total_rows
+            ),
         )
 
     def _get_row_ids(self, args: EmptyArgs) -> GetRowIdsResponse: