@lensui/lens-table 0.1.6 → 0.1.7

package/README.md

@@ -104,12 +104,12 @@ export function Example() {
 | `virtualized`                | `boolean \| { enabled?: boolean; overscan?: number }`                               | `true`          | 虚拟渲染配置。传`false` 时渲染全部行列；传对象时可通过 `enabled` 开关，并用 `overscan` 配置可见范围外的缓冲行列数量，默认 `4`。 |
 | `tooltip`                    | `boolean \| { header?: boolean; cell?: boolean }`                                   | `true`          | 文本 tooltip 总配置。传`true` 时表头和单元格 hover 都显示完整文本；传 `false` 可关闭；传对象可分别控制表头和单元格。                |
 | `summary`                    | `boolean \| { position?: 'top' \| 'bottom'; verticalBordered?: boolean; emptyValue?: ReactNode }` | `false`         | 表格级合计行配置。默认不显示；传 `true` 或对象即开启合计行，对象可控制显示在表头下方或底部、是否显示内部竖线，以及无合计值单元格的填充内容。     |
-| `rowNumber`                  | `boolean`                                                                          | `true`          | 是否显示序号列。默认开启并自动生成左侧序号列，不需要在`columns` 中配置；传 `false` 可关闭。                                         |
+| `rowNumber`                  | `boolean \| TableRowNumberConfig`                                                                          | `true`          | 是否显示序号列。默认开启并自动生成左侧序号列，不需要在`columns` 中配置；传 `false` 可关闭。传 `{ fixed: false }` 可取消序号列固定，`fixed` 默认 `true`。                                         |
 | `selectedCell`               | `GridSelectionTarget \| null`                                                       | 非受控            | 受控单元格选中状态。传 `columnKey`，行可使用 `rowKey` 或 `rowIndex` 定位。                                                              |
 | `defaultSelectedCell`        | `GridSelectionTarget \| null`                                                       | `null`            | 默认选中单元格。传 `columnKey`，行可使用 `rowKey` 或 `rowIndex` 定位。                                                                  |
 | `onSelectedCellChange`       | `(selection) => void`                                                              | -                 | 单元格选中变化回调，`selection.value` 为当前单元格的原始值。                                                                            |
 | `rangeSelection`             | `boolean`                                                                          | `false`         | 是否允许鼠标拖动选择多个单元格。开启后支持范围复制、范围右键菜单和右下角拖拽扩展范围。                                                  |
-| `rowSelection`               | `boolean \| AxisSelectionConfig`                                                    | `false`         | 开启行选择。可传`{ mode: 'single' \| 'multiple' }`；开启后组件自动生成左侧选择列，不需要在 `columns` 中配置。                        |
+| `rowSelection`               | `boolean \| RowSelectionConfig`                                                     | `false`         | 开启行选择。可传`{ mode: 'single' \| 'multiple', showCheckbox: false }` 隐藏选择框并通过点击数据单元格选择行；默认显示选择框。默认自动生成左侧选择列，不需要在 `columns` 中配置。                        |
 | `selectedRowKeys`            | `GridKey[]`                                                                        | 非受控            | 受控行选择 key 列表。                                                                                                                   |
 | `defaultSelectedRowKeys`     | `GridKey[]`                                                                        | `[]`            | 非受控模式下默认选中的行 key。                                                                                                          |
 | `onSelectedRowChange`        | `(keys, rows, indices) => void`                                                    | -                 | 行选择变化回调。                                                                                                                        |
@@ -128,6 +128,8 @@ export function Example() {
 | `onSortChange`               | `(rows, state) => Row[]`                                                           | -                 | 自定义排序方法。排序状态由组件内部管理；返回排序后的行。                                                                                |
 | `onFilterChange`             | `(rows, values) => Row[]`                                                          | -                 | 自定义筛选方法。筛选值由组件内部管理；返回符合条件的行。                                                                                |
 | `onCellChange`               | `(change) => void`                                                                 | -                 | 单元格编辑提交回调。                                                                                                                    |
+| `onCellClick` | `(cell: TableCellContext<Row>, event: React.MouseEvent<HTMLElement>) => void` | - | 数据单元格单击回调；调用 `event.preventDefault()` 可阻止默认选择行为。 |
+| `onCellDoubleClick` | `(cell: TableCellContext<Row>, event: React.MouseEvent<HTMLElement>) => void` | - | 数据单元格双击回调，在编辑前触发；调用 `event.preventDefault()` 可阻止进入编辑。 |
 | `onCellContextMenu`          | `(event) => void`                                                                  | -                 | 单元格右键回调，可用于扩展自定义菜单逻辑。                                                                                              |
 | `contextMenu`                | `boolean \| { header?, cell?, range? }`                                             | `true`          | `true` 开启默认右键菜单，`false` 关闭右键菜单，传对象可自定义菜单项、顺序和分割线。                                                 |
 | `emptyContent`               | `ReactNode`                                                                        | 内置空状态        | 自定义空数据内容。                                                                                                                      |
@@ -206,7 +208,7 @@ export function Example() {
 | `width`      | `number`                                                                 | `140`              | 列宽，单位 px。最小宽度由内部布局保护。                                                     |
 | `fixed`      | `'left' \| 'right'`                                                       | -                    | 固定列位置。左/右固定列会覆盖滚动列并显示阴影。                                             |
 | `align`      | `'left' \| 'center' \| 'right'`                                            | `'left'`           | 单元格文本和拖拽预览文本对齐方式。                                                          |
-| `editable`   | `boolean`                                                                | `false`            | 是否允许双击或按 Enter 进入编辑。                                                           |
+| `editable`   | `boolean \| ((value: unknown, row: Row, rowIndex: number) => boolean)`                                                                | `false`            | 是否允许双击、Enter 或右键菜单进入编辑。函数按当前单元格动态判断，提交时再次检查权限。                                                           |
 | `editor`     | `EditorConfig`                                                           | `{ type: 'text' }` | 内置编辑器配置。详见下方编辑器表。未配置时默认使用文本编辑器。                              |
 | `sortable`   | `boolean`                                                                | `true`             | 表头显示排序按钮。普通数据列默认开启，传 `false` 可关闭。                 |
 | `filterable` | `boolean`                                                                | `true`             | 表头显示筛选按钮。普通数据列默认开启，传 `false` 可关闭。                 |
@@ -494,7 +496,7 @@ const columns: GridColumn<Row>[] = [
 
 拖拽后组件会在内部维护新的行列顺序，因此排序回调不是必需的。需要持久化或同步结果时，可以通过回调直接取得排序后的 `rows` 或 `columns`。列宽调整默认开启并支持非受控使用，传 `columnResizable={false}` 可关闭。
 
-`columnDraggable` 默认开启，普通列会自动显示表头拖拽入口。行选择和行拖拽是表格级配置：开启 `rowSelection` 后自动生成左侧选择列，开启 `rowDraggable` 后自动生成左侧拖拽手柄列，不需要在 `columns` 里配置 `rowSelection` 或 `rowDragHandle`。
+`columnDraggable` 默认开启，普通列会自动显示表头拖拽入口。行选择和行拖拽是表格级配置：开启 `rowSelection` 后默认自动生成左侧选择列（`showCheckbox: false` 时隐藏），开启 `rowDraggable` 后自动生成左侧拖拽手柄列，不需要在 `columns` 里配置 `rowSelection` 或 `rowDragHandle`。
 
 ```tsx
 <Table
@@ -514,6 +516,20 @@ const columns: GridColumn<Row>[] = [
 />;
 ```
 
+隐藏选择框时不生成选择列，表头全选框也会隐藏；行选择状态、回调和右键菜单仍然可用。多选模式支持 Ctrl / Command 点击追加或取消选择，以及 Shift 点击连续选择。
+
+```tsx
+<Table
+  columns={columns}
+  rows={rows}
+  rowNumber={{ fixed: false }}
+  rowSelection={{ mode: 'multiple', showCheckbox: false }}
+  onSelectedRowChange={(keys, selectedRows) => console.log(keys, selectedRows)}
+/>
+```
+
+`rowNumber={true}` 或 `rowNumber={{ fixed: true }}` 固定序号列；`rowNumber={false}` 隐藏序号列。
+
 ## 虚拟渲染
 
 默认开启虚拟渲染，只绘制可见区域和少量缓冲区域。缓冲数量默认是 `4`，可以通过对象形式调整。
@@ -693,3 +709,76 @@ pnpm check
 ## License
 
 MIT
+
+## 单元格事件与动态编辑权限
+
+```tsx
+const columns: TableColumn<MyRow>[] = [
+  {
+    key: 'name',
+    title: '姓名',
+    dataIndex: 'name',
+    editable: (_value, row, _rowIndex) => row.status === 'draft',
+  },
+];
+
+<Table
+  columns={columns}
+  rows={rows}
+  onCellClick={(cell, event) => {
+    console.log(cell.row, cell.column, cell.value, cell.rowIndex, cell.columnIndex);
+  }}
+  onCellDoubleClick={(cell, event) => {
+    console.log(cell.rowKey, cell.columnKey);
+    // event.preventDefault(); // 阻止本次双击进入编辑
+  }}
+/>
+```
+
+事件只针对数据单元格，表头、序号列、选择列和拖拽手柄不触发；只读单元格也会触发。双击时先触发一次单击回调，再触发双击回调，不延迟单击。合并单元格返回其起始单元格，索引基于当前显示顺序，`columnIndex` 包含工具列。
+
+`editable` 保持兼容布尔值；函数接收当前值、行数据和当前行索引，返回 `true` 才允许编辑。编辑期间权限变为 `false` 时，提交会关闭编辑器并丢弃草稿，不触发 `onCellChange`。
+
+## Ref 方法
+
+支持 React 18+ 的对象 ref 和回调 ref，保留行数据的泛型推导；`VelocityGrid` 别名同样支持。可导入 `TableRef<Row>`（或 `VelocityGridRef<Row>`）。
+
+```tsx
+import { useRef } from 'react';
+import { Table, type TableRef } from '@lensui/lens-table';
+
+function Example() {
+  const tableRef = useRef<TableRef<MyRow>>(null);
+  return (
+    <>
+      <button onClick={() => tableRef.current?.scrollToCell({ rowKey: 1, columnKey: 'name' })}>
+        定位
+      </button>
+      <button onClick={() => tableRef.current?.startEdit({ rowKey: 1, columnKey: 'name' })}>
+        编辑
+      </button>
+      <Table ref={tableRef} columns={columns} rows={rows} rowSelection />
+    </>
+  );
+}
+```
+
+| 方法 | 说明 |
+| --- | --- |
+| `focus()` | 聚焦表格，启用键盘操作。 |
+| `scrollToCell(target)` | 将目标数据单元格滚入可见区域，不改变选择；目标不存在时返回 `false`。 |
+| `getSelectedCell()` | 返回当前单元格的 `TableCellContext<Row>`，未选择时返回 `null`。 |
+| `setSelectedCell(target \| null)` | 设置或清除单元格选择，同时清除范围选择；无效目标返回 `false` 并保留原选择。 |
+| `getSelectedRowKeys()` | 返回所选行 key 的数组副本。 |
+| `getSelectedRows()` | 返回当前筛选和排序结果中选中的行数据，按显示顺序排列。 |
+| `setSelectedRowKeys(keys)` | 设置行选择并触发现有回调；需要开启 `rowSelection`，单选模式只取第一个 key。 |
+| `getSelectedColumnKeys()` | 返回所选列 key 的数组副本。 |
+| `setSelectedColumnKeys(keys)` | 设置数据列选择，忽略无效列；需要开启 `columnSelection`，单选模式只取第一个有效 key。 |
+| `clearSelection()` | 清空单元格、范围、行和列选择，并取消编辑。 |
+| `startEdit(target?)` | 选择并编辑目标单元格；省略参数时编辑当前选择。目标无效或 `editable` 不允许时返回 `false`。 |
+| `commitEdit()` | 提交当前草稿并关闭编辑器，遵循 `editable` 动态权限和 `onCellChange`。 |
+| `cancelEdit()` | 丢弃当前草稿并关闭编辑器。 |
+
+`target` 使用 `{ rowKey, columnKey }` 或 `{ rowIndex, columnKey }`；`rowKey` 优先，`rowIndex` 为当前显示顺序中的零基索引。工具列不能作为目标；合并单元格自动定位到起始单元格。
+
+选择方法遵守受控／非受控约定：传入 `selectedCell`、`selectedRowKeys` 或 `selectedColumnKeys` 后，需要在相应回调中更新这些 props。尤其是受控单元格选择下的 `startEdit`，外部需要接受新的选择才能保持编辑器打开。读取方法反映最近一次 React 渲染完成后的状态，不保证在调用设置方法的同一同步代码段内立即更新；返回的行和列对象是原数据引用。

package/dist/index.cjs

@@ -1522,7 +1522,7 @@ function resolveContextMenuSection(section, defaults) {
   }
   return defaults;
 }
-function Table({
+function TableInner({
   columns: columnProps,
   rows: sourceRows,
   rowKey,
@@ -1568,13 +1568,15 @@ function Table({
   onSortChange,
   onFilterChange,
   onCellChange,
+  onCellClick,
+  onCellDoubleClick,
   onCellContextMenu,
   contextMenu: contextMenuConfig = true,
   emptyContent,
   className = "",
   style,
   ariaLabel = "Data grid"
-}) {
+}, ref) {
   const [sourceColumns, setSourceColumns] = (0, import_react5.useState)(columnProps);
   (0, import_react5.useEffect)(() => {
     setSourceColumns((current) => reconcileColumns(current, columnProps));
@@ -1620,6 +1622,7 @@ function Table({
   const customContextMenuConfig = typeof contextMenuConfig === "object" ? contextMenuConfig : void 0;
   const [resizedColumnWidths, setResizedColumnWidths] = (0, import_react5.useState)({});
   const leafSourceColumns = (0, import_react5.useMemo)(() => flattenDataColumns(sourceColumns), [sourceColumns]);
+  const showRowCheckbox = Boolean(rowSelection) && (typeof rowSelection !== "object" || rowSelection.showCheckbox !== false);
   (0, import_react5.useEffect)(() => {
     if (!isProductionRuntime() && hasNestedFixedColumns(sourceColumns)) {
       console.warn("[Table] Multi-level headers only support fixed columns on top-level columns. Nested fixed values are ignored.");
@@ -1630,19 +1633,19 @@ function Table({
     if (rowDraggable) {
       utilityColumns.push({ key: "__rvg_row_drag__", title: "", width: 36, align: "center", fixed: "left", rowDragHandle: true });
     }
-    if (rowSelection) {
+    if (showRowCheckbox) {
       utilityColumns.push({ key: "__rvg_row_selection__", title: "", width: 44, align: "center", fixed: "left", rowSelection: true });
     }
     if (rowNumber) {
-      utilityColumns.push({ key: "__rvg_row_number__", title: "#", width: getRowNumberColumnWidth(sourceRows.length), align: "center", fixed: "left", rowNumber: true });
+      utilityColumns.push({ key: "__rvg_row_number__", title: "#", width: getRowNumberColumnWidth(sourceRows.length), align: "center", fixed: typeof rowNumber === "object" && rowNumber.fixed === false ? void 0 : "left", rowNumber: true });
     }
     const dataColumns = leafSourceColumns.map((column) => {
       const resizedWidth = resizedColumnWidths[column.key];
       return resizedWidth === void 0 ? column : { ...column, width: resizedWidth };
     });
     return [...utilityColumns, ...dataColumns];
-  }, [leafSourceColumns, resizedColumnWidths, rowDraggable, rowNumber, rowSelection, sourceRows.length]);
-  const utilityColumnCount = (rowDraggable ? 1 : 0) + (rowSelection ? 1 : 0) + (rowNumber ? 1 : 0);
+  }, [leafSourceColumns, resizedColumnWidths, rowDraggable, rowNumber, showRowCheckbox, sourceRows.length]);
+  const utilityColumnCount = (rowDraggable ? 1 : 0) + (showRowCheckbox ? 1 : 0) + (rowNumber ? 1 : 0);
   const headerCells = (0, import_react5.useMemo)(() => buildHeaderCells(sourceColumns, utilityColumnCount, headerDepth), [headerDepth, sourceColumns, utilityColumnCount]);
   const activeCustomHeaderLevels = (0, import_react5.useMemo)(() => {
     const levels = /* @__PURE__ */ new Map();
@@ -3348,9 +3351,15 @@ function Table({
     scrollRef.current = { left: scroller.scrollLeft, top: scroller.scrollTop };
     scheduleDraw();
   }, [bodyTop, columns, fixedHeader, fixedWidth, getCellDisplayWidth, getCellSpan, getScrollableColumnLeft, metrics, rightFixedWidth, rowHeight, scheduleDraw, viewport.width]);
+  const isCellEditable = (0, import_react5.useCallback)((cell) => {
+    const column = columns[cell.columnIndex];
+    const row = rows[cell.rowIndex];
+    if (!column || !row || column.dataIndex === void 0 || column.rowNumber || column.rowSelection || column.rowDragHandle) return false;
+    return typeof column.editable === "function" ? column.editable(row[column.dataIndex], row, cell.rowIndex) : column.editable === true;
+  }, [columns, rows]);
   const beginEdit = (0, import_react5.useCallback)((cell) => {
     const column = columns[cell.columnIndex];
-    if (!column?.editable || column.dataIndex === void 0) return;
+    if (!isCellEditable(cell) || column.dataIndex === void 0) return;
     const value = rows[cell.rowIndex]?.[column.dataIndex];
     setDraft(value == null ? "" : String(value));
     const scroller = scrollerRef.current;
@@ -3392,7 +3401,7 @@ function Table({
       return;
     }
     setEditing(cell);
-  }, [columns, fixedHeader, fixedWidth, getCellDisplayWidth, getCellSpan, getScrollableColumnLeft, metrics, rightFixedWidth, rowHeight, rows, scheduleDraw, viewport.width]);
+  }, [columns, fixedHeader, fixedWidth, getCellDisplayWidth, getCellSpan, getScrollableColumnLeft, isCellEditable, metrics, rightFixedWidth, rowHeight, rows, scheduleDraw, viewport.width]);
   const getCellEditKey = (cell) => `${typeof cell.rowKey}:${String(cell.rowKey)}\0${cell.columnKey}`;
   const markCellEdited = (cell, previousValue, nextValue) => {
     const key = getCellEditKey(cell);
@@ -3420,6 +3429,10 @@ function Table({
   };
   const commitEdit = (0, import_react5.useCallback)((nextDraft, close = true) => {
     if (!editing) return;
+    if (!isCellEditable(editing)) {
+      setEditing(null);
+      return;
+    }
     const committedDraft = nextDraft ?? draft;
     const column = columns[editing.columnIndex];
     const row = rows[editing.rowIndex];
@@ -3434,7 +3447,7 @@ function Table({
       onCellChange?.({ ...editing, row, value: committedValue, previousValue });
     }
     if (close) setEditing(null);
-  }, [columns, draft, editing, onCellChange, rows]);
+  }, [columns, draft, editing, isCellEditable, onCellChange, rows]);
   const renderEditor = () => {
     if (!editing || !editorStyle) return null;
     const column = columns[editing.columnIndex];
@@ -4336,6 +4349,77 @@ function Table({
       `summary:${column.key}`
     );
   };
+  (0, import_react5.useImperativeHandle)(ref, () => {
+    const resolveDataCell = (target) => {
+      const cell = resolveSelectionTarget(target);
+      if (!cell) return null;
+      const column = columns[cell.columnIndex];
+      if (column.rowNumber || column.rowSelection || column.rowDragHandle) return null;
+      const span = getCellSpan(cell.rowIndex, cell.columnIndex);
+      if (!span) return cell;
+      return {
+        rowIndex: span.rowIndex,
+        columnIndex: span.columnIndex,
+        rowKey: getRowKey(rows[span.rowIndex], span.rowIndex),
+        columnKey: columns[span.columnIndex].key
+      };
+    };
+    return {
+      focus: () => scrollerRef.current?.focus({ preventScroll: true }),
+      scrollToCell: (target) => {
+        const cell = resolveDataCell(target);
+        if (!cell) return false;
+        revealCell(cell);
+        return true;
+      },
+      getSelectedCell: () => {
+        if (!selection) return null;
+        const cell = resolveDataCell(selection);
+        if (!cell) return null;
+        const column = columns[cell.columnIndex];
+        const row = rows[cell.rowIndex];
+        return { ...cell, row, column, value: column.dataIndex === void 0 ? void 0 : row[column.dataIndex] };
+      },
+      setSelectedCell: (target) => {
+        const cell = target === null ? null : resolveDataCell(target);
+        if (target !== null && !cell) return false;
+        setSelectionRange(null);
+        setSelection(cell);
+        return true;
+      },
+      getSelectedRowKeys: () => [...rowKeys],
+      getSelectedRows: () => rows.filter((row, index) => selectedRowKeySet.has(getRowKey(row, index))),
+      setSelectedRowKeys: (keys) => {
+        if (!rowSelection) return;
+        const next = [...new Set(keys)];
+        setRowKeys(rowSelectionMode === "single" ? next.slice(0, 1) : next);
+      },
+      getSelectedColumnKeys: () => [...columnKeys],
+      setSelectedColumnKeys: (keys) => {
+        if (!columnSelection) return;
+        const next = [...new Set(keys)].filter((key) => columns.some((column) => column.key === key && !column.rowNumber && !column.rowSelection && !column.rowDragHandle));
+        setColumnKeys(typeof columnSelection === "object" && columnSelection.mode === "single" ? next.slice(0, 1) : next);
+      },
+      clearSelection: () => {
+        setSelectionRange(null);
+        setSelection(null);
+        setRowKeys([]);
+        setColumnKeys([]);
+        rowAnchorRef.current = null;
+        setEditing(null);
+      },
+      startEdit: (target) => {
+        const cell = target ? resolveDataCell(target) : selection ? resolveDataCell(selection) : null;
+        if (!cell || !isCellEditable(cell)) return false;
+        setSelectionRange(null);
+        setSelection(cell);
+        beginEdit(cell);
+        return true;
+      },
+      commitEdit: () => commitEdit(),
+      cancelEdit: () => setEditing(null)
+    };
+  });
   const rootStyle = {
     width,
     height: autoHeight ? effectiveHeight : height,
@@ -4534,6 +4618,10 @@ function Table({
             }
             if (event.detail > 1) return;
             clickedCellRef.current = cell;
+            const column = columns[cell.columnIndex];
+            const row = rows[cell.rowIndex];
+            onCellClick?.({ ...cell, row, column, value: column.dataIndex === void 0 ? void 0 : row[column.dataIndex] }, event);
+            if (event.defaultPrevented) return;
             setSelectionRange(null);
             scrollerRef.current?.focus({ preventScroll: true });
             setSelection(cell);
@@ -4544,7 +4632,12 @@ function Table({
           },
           onDoubleClick: (event) => {
             const cell = clickedCellRef.current ?? locateCell(event.clientX, event.clientY);
-            if (cell) beginEdit(cell);
+            if (!cell) return;
+            const column = columns[cell.columnIndex];
+            if (column.rowNumber || column.rowSelection || column.rowDragHandle) return;
+            const row = rows[cell.rowIndex];
+            onCellDoubleClick?.({ ...cell, row, column, value: column.dataIndex === void 0 ? void 0 : row[column.dataIndex] }, event);
+            if (!event.defaultPrevented) beginEdit(cell);
           },
           onContextMenu: handleContextMenu
         }
@@ -4557,7 +4650,7 @@ function Table({
             className: "rvg-text-scroll-content",
             style: { left: -fixedWidth, width: contentWidth, transform: `translateX(${-currentScroll.left}px)` },
             children: [
-              columns.map((column, columnIndex) => column.fixed || columnIndex < utilityColumnCount || headerDepth > 1 ? null : columnIndex >= domRange.columnStart && columnIndex < domRange.columnEnd ? /* @__PURE__ */ (0, import_jsx_runtime7.jsx)("span", { children: renderHeaderTitle(columnIndex, getScrollableColumnLeft(columnIndex)) }, column.key) : null),
+              columns.map((column, columnIndex) => column.fixed || columnIndex >= utilityColumnCount && headerDepth > 1 ? null : columnIndex >= domRange.columnStart && columnIndex < domRange.columnEnd ? /* @__PURE__ */ (0, import_jsx_runtime7.jsx)("span", { children: renderHeaderTitle(columnIndex, getScrollableColumnLeft(columnIndex)) }, column.key) : null),
               headerCells.map((cell) => {
                 if (columns[cell.startIndex]?.fixed) return null;
                 if (cell.endIndex < domRange.columnStart || cell.startIndex >= domRange.columnEnd) return null;
@@ -4575,7 +4668,7 @@ function Table({
           const left = column.fixed === "left" ? leftFixedOffsets.get(columnIndex) ?? 0 : viewport.width - (rightFixedOffsets.get(columnIndex) ?? 0) - metrics[columnIndex].width;
           return renderCellText(rowIndex, columnIndex, left);
         })) }),
-        columns.map((column, columnIndex) => columnIndex < utilityColumnCount || headerDepth === 1 && (column.fixed === "left" || column.fixed === "right") ? renderHeaderTitle(columnIndex, column.fixed === "right" ? viewport.width - (rightFixedOffsets.get(columnIndex) ?? 0) - metrics[columnIndex].width : column.fixed === "left" ? leftFixedOffsets.get(columnIndex) ?? 0 : getScrollableColumnLeft(columnIndex)) : null),
+        columns.map((column, columnIndex) => column.fixed && (columnIndex < utilityColumnCount || headerDepth === 1) ? renderHeaderTitle(columnIndex, column.fixed === "right" ? viewport.width - (rightFixedOffsets.get(columnIndex) ?? 0) - metrics[columnIndex].width : column.fixed === "left" ? leftFixedOffsets.get(columnIndex) ?? 0 : getScrollableColumnLeft(columnIndex)) : null),
         headerCells.map((cell) => columns[cell.startIndex]?.fixed ? renderGroupedHeaderCell(cell) : null),
         fixedWidth > 0 && currentScroll.left > 0 && /* @__PURE__ */ (0, import_jsx_runtime7.jsx)("div", { className: "rvg-text-fixed-shadow is-left", style: { left: fixedWidth } }),
         rightFixedWidth > 0 && currentScroll.left < contentWidth - viewport.width && /* @__PURE__ */ (0, import_jsx_runtime7.jsx)("div", { className: "rvg-text-fixed-shadow is-right", style: { right: rightFixedWidth } }),
@@ -4792,7 +4885,7 @@ function Table({
       const affectedRows = selectedIndices.includes(cell.rowIndex) ? selectedIndices : [cell.rowIndex];
       const cellContext = { ...cell, row, column, value: dataIndex === void 0 ? void 0 : row[dataIndex] };
       return renderConfiguredContextMenu(resolveContextMenuSection(customContextMenuConfig?.cell, DEFAULT_CELL_CONTEXT_MENU), cellContext, (item, override) => {
-        if (item === "edit") return renderContextMenuButton("cell-edit", cellContext, labels.edit, () => beginEdit(cell), override, { disabled: !column.editable, icon: /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(ContextMenuIcon, { type: "edit" }) });
+        if (item === "edit") return renderContextMenuButton("cell-edit", cellContext, labels.edit, () => beginEdit(cell), override, { disabled: !isCellEditable(cell), icon: /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(ContextMenuIcon, { type: "edit" }) });
         if (item === "copy") return renderContextMenuButton("cell-copy", cellContext, labels.copyContent, async () => {
           try {
             await navigator.clipboard.writeText(getCellLabel(cell.rowIndex, cell.columnIndex));
@@ -5032,6 +5125,7 @@ function Table({
     loading && !hasCustomLoading && hasCompletedLoadRef.current && /* @__PURE__ */ (0, import_jsx_runtime7.jsx)("div", { className: "rvg-refresh-loading", "aria-label": labels.refreshing, children: /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(LoadingSpinnerIcon, {}) })
   ] });
 }
+var Table = (0, import_react5.forwardRef)(TableInner);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Table,

package/dist/index.d.cts

@@ -1,5 +1,4 @@
-import * as react from 'react';
-import { ReactNode, CSSProperties } from 'react';
+import { ReactNode, MouseEvent, CSSProperties, RefAttributes, ReactElement } from 'react';
 
 type GridKey = string | number;
 type SelectionMode = 'single' | 'multiple';
@@ -155,6 +154,14 @@ interface AxisSelectionConfig {
     /** single uses radio-style selection, multiple uses checkbox-style selection. */
     mode?: SelectionMode;
 }
+interface RowSelectionConfig extends AxisSelectionConfig {
+    /** Show the selection column. Defaults to true; when false, click body cells to select rows. */
+    showCheckbox?: boolean;
+}
+interface TableRowNumberConfig {
+    /** Fix the row number column to the left. Defaults to true. */
+    fixed?: boolean;
+}
 /**
  * Column definition consumed by both the canvas renderer and DOM editor layer.
  *
@@ -179,7 +186,7 @@ interface GridColumn<Row> {
     /** Text alignment for body cells and drag previews. */
     align?: 'left' | 'center' | 'right';
     /** Enables double-click / Enter editing when an editor or fallback input exists. */
-    editable?: boolean;
+    editable?: boolean | ((value: unknown, row: Row, rowIndex: number) => boolean);
     /** Built-in editor configuration for text, selectable, date, time, and range cells. */
     editor?: {
         type: 'text';
@@ -241,6 +248,31 @@ interface CellChange<Row> extends GridSelection {
     previousValue: unknown;
     row: Row;
 }
+/** Data cell identity and content passed to mouse callbacks. */
+interface TableCellContext<Row> extends GridSelection {
+    row: Row;
+    column: GridColumn<Row>;
+    value: unknown;
+}
+/** Imperative Table API. Selection getters reflect the latest committed render. */
+interface TableRef<Row extends object> {
+    focus: () => void;
+    /** Reveal a data cell without changing selection; false if the target is unavailable. */
+    scrollToCell: (target: GridSelectionTarget) => boolean;
+    getSelectedCell: () => TableCellContext<Row> | null;
+    setSelectedCell: (target: GridSelectionTarget | null) => boolean;
+    getSelectedRowKeys: () => GridKey[];
+    getSelectedRows: () => Row[];
+    setSelectedRowKeys: (keys: GridKey[]) => void;
+    getSelectedColumnKeys: () => string[];
+    setSelectedColumnKeys: (keys: string[]) => void;
+    /** Clear cell, range, row, and column selections. */
+    clearSelection: () => void;
+    /** Select and edit a cell, or edit the current selection. Returns false for invalid or read-only cells. */
+    startEdit: (target?: GridSelectionTarget) => boolean;
+    commitEdit: () => void;
+    cancelEdit: () => void;
+}
 /** Fired when the consumer wants to observe or extend a cell context menu. */
 interface ContextMenuEvent<Row> extends GridSelection {
     row: Row;
@@ -331,13 +363,13 @@ interface TableProps<Row extends object> {
     /** Show and position the summary row for columns with summary configured. */
     summary?: TableSummaryConfig;
     /** Show an automatically generated row number column on the left. */
-    rowNumber?: boolean;
+    rowNumber?: boolean | TableRowNumberConfig;
     selectedCell?: GridSelectionTarget | null;
     defaultSelectedCell?: GridSelectionTarget | null;
     onSelectedCellChange?: (selection: SelectedCellChange | null) => void;
     /** Enable spreadsheet-style mouse drag selection across multiple body cells. Defaults to false. */
     rangeSelection?: boolean;
-    rowSelection?: boolean | AxisSelectionConfig;
+    rowSelection?: boolean | RowSelectionConfig;
     selectedRowKeys?: GridKey[];
     defaultSelectedRowKeys?: GridKey[];
     onSelectedRowChange?: (keys: GridKey[], rows: Row[], indices: number[]) => void;
@@ -371,6 +403,10 @@ interface TableProps<Row extends object> {
     /** Overrides the built-in text filtering. Return the rows that match the internally managed filter values. */
     onFilterChange?: (rows: Row[], values: Readonly<Record<string, string>>) => Row[];
     onCellChange?: (change: CellChange<Row>) => void | Promise<void>;
+    /** Fires on a data cell click, before the default selection behavior. */
+    onCellClick?: (cell: TableCellContext<Row>, event: MouseEvent<HTMLElement>) => void;
+    /** Fires before double-click editing. preventDefault() cancels editing. */
+    onCellDoubleClick?: (cell: TableCellContext<Row>, event: MouseEvent<HTMLElement>) => void;
     onCellContextMenu?: (event: ContextMenuEvent<Row>) => void;
     /** true uses the built-in menu, false disables custom menus, object customizes menu content and order. */
     contextMenu?: TableContextMenu<Row>;
@@ -386,7 +422,7 @@ interface ViewportRange {
     columnEnd: number;
 }
 
-declare function Table<Row extends object>({ columns: columnProps, rows: sourceRows, rowKey, width, height, autoHeight, layout, rowHeight: rowHeightProp, headerHeight: headerHeightProp, fixedHeader, locale, borderless, verticalBorderless, striped, highlight, cellSpans, loading, loadingContent, virtualized, tooltip, summary, rowNumber, selectedCell, defaultSelectedCell, onSelectedCellChange, rangeSelection, rowSelection, selectedRowKeys, defaultSelectedRowKeys, onSelectedRowChange, columnSelection, selectedColumnKeys, defaultSelectedColumnKeys, onSelectedColumnChange, columnDraggable, columnResizable, onColumnsReorder, onColumnResize, rowDraggable, onRowsReorder, onInsertRows, onDeleteRows, onSortChange, onFilterChange, onCellChange, onCellContextMenu, contextMenu: contextMenuConfig, emptyContent, className, style, ariaLabel, }: TableProps<Row>): react.JSX.Element;
+declare const Table: <Row extends object>(props: TableProps<Row> & RefAttributes<TableRef<Row>>) => ReactElement;
 
 type LayoutColumn<Row> = GridColumn<Row> & {
     rowSelection?: boolean;
@@ -433,4 +469,4 @@ declare function hitTestColumn(metrics: ColumnMetric[], contentX: number): numbe
 
 type TableFilterValues = Record<string, string>;
 
-export { type AxisSelectionConfig, type CellChange, type ContextMenuEvent, type GridCellPosition, type GridColumn, type GridKey, type GridSelection, type GridSelectionTarget, type GridSortState, type SelectedCellChange, type SelectionMode, type SortDirection, Table, type CellChange as TableCellChange, type GridCellPosition as TableCellPosition, type TableCellSpan, type TableCellSpanRule, type TableCellSpanRuleContext, type TableCellSpans, type GridColumn as TableColumn, type TableContextMenu, type TableContextMenuConfig, type ContextMenuEvent as TableContextMenuEvent, type GridSelection as TableEditingCell, type TableFilterValues, type TableHighlightConfig, type GridKey as TableKey, type TableLabels, type TableLayoutConfig, type TableLocaleCode, type TableLocaleConfig, type TableProps, type TableResolvedCellSpan, type GridSortState as TableSorter, type TableSummaryConfig, type TableTooltipConfig, type ViewportRange as TableViewportRange, type TableVirtualizedConfig, Table as VelocityGrid, type TableCellSpan as VelocityGridCellSpan, type TableCellSpanRule as VelocityGridCellSpanRule, type TableCellSpanRuleContext as VelocityGridCellSpanRuleContext, type TableCellSpans as VelocityGridCellSpans, type TableContextMenu as VelocityGridContextMenu, type TableContextMenuConfig as VelocityGridContextMenuConfig, type TableHighlightConfig as VelocityGridHighlightConfig, type TableLabels as VelocityGridLabels, type TableLayoutConfig as VelocityGridLayoutConfig, type TableLocaleCode as VelocityGridLocaleCode, type TableLocaleConfig as VelocityGridLocaleConfig, type TableProps as VelocityGridProps, type TableResolvedCellSpan as VelocityGridResolvedCellSpan, type TableSummaryConfig as VelocityGridSummaryConfig, type TableTooltipConfig as VelocityGridTooltipConfig, type TableVirtualizedConfig as VelocityGridVirtualizedConfig, type ViewportRange, buildColumnMetrics, getViewportRange, hitTestColumn };
+export { type AxisSelectionConfig, type CellChange, type ContextMenuEvent, type GridCellPosition, type GridColumn, type GridKey, type GridSelection, type GridSelectionTarget, type GridSortState, type RowSelectionConfig, type SelectedCellChange, type SelectionMode, type SortDirection, Table, type CellChange as TableCellChange, type TableCellContext, type GridCellPosition as TableCellPosition, type TableCellSpan, type TableCellSpanRule, type TableCellSpanRuleContext, type TableCellSpans, type GridColumn as TableColumn, type TableContextMenu, type TableContextMenuConfig, type ContextMenuEvent as TableContextMenuEvent, type GridSelection as TableEditingCell, type TableFilterValues, type TableHighlightConfig, type GridKey as TableKey, type TableLabels, type TableLayoutConfig, type TableLocaleCode, type TableLocaleConfig, type TableProps, type TableRef, type TableResolvedCellSpan, type TableRowNumberConfig, type GridSortState as TableSorter, type TableSummaryConfig, type TableTooltipConfig, type ViewportRange as TableViewportRange, type TableVirtualizedConfig, Table as VelocityGrid, type TableCellSpan as VelocityGridCellSpan, type TableCellSpanRule as VelocityGridCellSpanRule, type TableCellSpanRuleContext as VelocityGridCellSpanRuleContext, type TableCellSpans as VelocityGridCellSpans, type TableContextMenu as VelocityGridContextMenu, type TableContextMenuConfig as VelocityGridContextMenuConfig, type TableHighlightConfig as VelocityGridHighlightConfig, type TableLabels as VelocityGridLabels, type TableLayoutConfig as VelocityGridLayoutConfig, type TableLocaleCode as VelocityGridLocaleCode, type TableLocaleConfig as VelocityGridLocaleConfig, type TableProps as VelocityGridProps, type TableRef as VelocityGridRef, type TableResolvedCellSpan as VelocityGridResolvedCellSpan, type TableSummaryConfig as VelocityGridSummaryConfig, type TableTooltipConfig as VelocityGridTooltipConfig, type TableVirtualizedConfig as VelocityGridVirtualizedConfig, type ViewportRange, buildColumnMetrics, getViewportRange, hitTestColumn };

package/dist/index.d.ts

@@ -1,5 +1,4 @@
-import * as react from 'react';
-import { ReactNode, CSSProperties } from 'react';
+import { ReactNode, MouseEvent, CSSProperties, RefAttributes, ReactElement } from 'react';
 
 type GridKey = string | number;
 type SelectionMode = 'single' | 'multiple';
@@ -155,6 +154,14 @@ interface AxisSelectionConfig {
     /** single uses radio-style selection, multiple uses checkbox-style selection. */
     mode?: SelectionMode;
 }
+interface RowSelectionConfig extends AxisSelectionConfig {
+    /** Show the selection column. Defaults to true; when false, click body cells to select rows. */
+    showCheckbox?: boolean;
+}
+interface TableRowNumberConfig {
+    /** Fix the row number column to the left. Defaults to true. */
+    fixed?: boolean;
+}
 /**
  * Column definition consumed by both the canvas renderer and DOM editor layer.
  *
@@ -179,7 +186,7 @@ interface GridColumn<Row> {
     /** Text alignment for body cells and drag previews. */
     align?: 'left' | 'center' | 'right';
     /** Enables double-click / Enter editing when an editor or fallback input exists. */
-    editable?: boolean;
+    editable?: boolean | ((value: unknown, row: Row, rowIndex: number) => boolean);
     /** Built-in editor configuration for text, selectable, date, time, and range cells. */
     editor?: {
         type: 'text';
@@ -241,6 +248,31 @@ interface CellChange<Row> extends GridSelection {
     previousValue: unknown;
     row: Row;
 }
+/** Data cell identity and content passed to mouse callbacks. */
+interface TableCellContext<Row> extends GridSelection {
+    row: Row;
+    column: GridColumn<Row>;
+    value: unknown;
+}
+/** Imperative Table API. Selection getters reflect the latest committed render. */
+interface TableRef<Row extends object> {
+    focus: () => void;
+    /** Reveal a data cell without changing selection; false if the target is unavailable. */
+    scrollToCell: (target: GridSelectionTarget) => boolean;
+    getSelectedCell: () => TableCellContext<Row> | null;
+    setSelectedCell: (target: GridSelectionTarget | null) => boolean;
+    getSelectedRowKeys: () => GridKey[];
+    getSelectedRows: () => Row[];
+    setSelectedRowKeys: (keys: GridKey[]) => void;
+    getSelectedColumnKeys: () => string[];
+    setSelectedColumnKeys: (keys: string[]) => void;
+    /** Clear cell, range, row, and column selections. */
+    clearSelection: () => void;
+    /** Select and edit a cell, or edit the current selection. Returns false for invalid or read-only cells. */
+    startEdit: (target?: GridSelectionTarget) => boolean;
+    commitEdit: () => void;
+    cancelEdit: () => void;
+}
 /** Fired when the consumer wants to observe or extend a cell context menu. */
 interface ContextMenuEvent<Row> extends GridSelection {
     row: Row;
@@ -331,13 +363,13 @@ interface TableProps<Row extends object> {
     /** Show and position the summary row for columns with summary configured. */
     summary?: TableSummaryConfig;
     /** Show an automatically generated row number column on the left. */
-    rowNumber?: boolean;
+    rowNumber?: boolean | TableRowNumberConfig;
     selectedCell?: GridSelectionTarget | null;
     defaultSelectedCell?: GridSelectionTarget | null;
     onSelectedCellChange?: (selection: SelectedCellChange | null) => void;
     /** Enable spreadsheet-style mouse drag selection across multiple body cells. Defaults to false. */
     rangeSelection?: boolean;
-    rowSelection?: boolean | AxisSelectionConfig;
+    rowSelection?: boolean | RowSelectionConfig;
     selectedRowKeys?: GridKey[];
     defaultSelectedRowKeys?: GridKey[];
     onSelectedRowChange?: (keys: GridKey[], rows: Row[], indices: number[]) => void;
@@ -371,6 +403,10 @@ interface TableProps<Row extends object> {
     /** Overrides the built-in text filtering. Return the rows that match the internally managed filter values. */
     onFilterChange?: (rows: Row[], values: Readonly<Record<string, string>>) => Row[];
     onCellChange?: (change: CellChange<Row>) => void | Promise<void>;
+    /** Fires on a data cell click, before the default selection behavior. */
+    onCellClick?: (cell: TableCellContext<Row>, event: MouseEvent<HTMLElement>) => void;
+    /** Fires before double-click editing. preventDefault() cancels editing. */
+    onCellDoubleClick?: (cell: TableCellContext<Row>, event: MouseEvent<HTMLElement>) => void;
     onCellContextMenu?: (event: ContextMenuEvent<Row>) => void;
     /** true uses the built-in menu, false disables custom menus, object customizes menu content and order. */
     contextMenu?: TableContextMenu<Row>;
@@ -386,7 +422,7 @@ interface ViewportRange {
     columnEnd: number;
 }
 
-declare function Table<Row extends object>({ columns: columnProps, rows: sourceRows, rowKey, width, height, autoHeight, layout, rowHeight: rowHeightProp, headerHeight: headerHeightProp, fixedHeader, locale, borderless, verticalBorderless, striped, highlight, cellSpans, loading, loadingContent, virtualized, tooltip, summary, rowNumber, selectedCell, defaultSelectedCell, onSelectedCellChange, rangeSelection, rowSelection, selectedRowKeys, defaultSelectedRowKeys, onSelectedRowChange, columnSelection, selectedColumnKeys, defaultSelectedColumnKeys, onSelectedColumnChange, columnDraggable, columnResizable, onColumnsReorder, onColumnResize, rowDraggable, onRowsReorder, onInsertRows, onDeleteRows, onSortChange, onFilterChange, onCellChange, onCellContextMenu, contextMenu: contextMenuConfig, emptyContent, className, style, ariaLabel, }: TableProps<Row>): react.JSX.Element;
+declare const Table: <Row extends object>(props: TableProps<Row> & RefAttributes<TableRef<Row>>) => ReactElement;
 
 type LayoutColumn<Row> = GridColumn<Row> & {
     rowSelection?: boolean;
@@ -433,4 +469,4 @@ declare function hitTestColumn(metrics: ColumnMetric[], contentX: number): numbe
 
 type TableFilterValues = Record<string, string>;
 
-export { type AxisSelectionConfig, type CellChange, type ContextMenuEvent, type GridCellPosition, type GridColumn, type GridKey, type GridSelection, type GridSelectionTarget, type GridSortState, type SelectedCellChange, type SelectionMode, type SortDirection, Table, type CellChange as TableCellChange, type GridCellPosition as TableCellPosition, type TableCellSpan, type TableCellSpanRule, type TableCellSpanRuleContext, type TableCellSpans, type GridColumn as TableColumn, type TableContextMenu, type TableContextMenuConfig, type ContextMenuEvent as TableContextMenuEvent, type GridSelection as TableEditingCell, type TableFilterValues, type TableHighlightConfig, type GridKey as TableKey, type TableLabels, type TableLayoutConfig, type TableLocaleCode, type TableLocaleConfig, type TableProps, type TableResolvedCellSpan, type GridSortState as TableSorter, type TableSummaryConfig, type TableTooltipConfig, type ViewportRange as TableViewportRange, type TableVirtualizedConfig, Table as VelocityGrid, type TableCellSpan as VelocityGridCellSpan, type TableCellSpanRule as VelocityGridCellSpanRule, type TableCellSpanRuleContext as VelocityGridCellSpanRuleContext, type TableCellSpans as VelocityGridCellSpans, type TableContextMenu as VelocityGridContextMenu, type TableContextMenuConfig as VelocityGridContextMenuConfig, type TableHighlightConfig as VelocityGridHighlightConfig, type TableLabels as VelocityGridLabels, type TableLayoutConfig as VelocityGridLayoutConfig, type TableLocaleCode as VelocityGridLocaleCode, type TableLocaleConfig as VelocityGridLocaleConfig, type TableProps as VelocityGridProps, type TableResolvedCellSpan as VelocityGridResolvedCellSpan, type TableSummaryConfig as VelocityGridSummaryConfig, type TableTooltipConfig as VelocityGridTooltipConfig, type TableVirtualizedConfig as VelocityGridVirtualizedConfig, type ViewportRange, buildColumnMetrics, getViewportRange, hitTestColumn };
+export { type AxisSelectionConfig, type CellChange, type ContextMenuEvent, type GridCellPosition, type GridColumn, type GridKey, type GridSelection, type GridSelectionTarget, type GridSortState, type RowSelectionConfig, type SelectedCellChange, type SelectionMode, type SortDirection, Table, type CellChange as TableCellChange, type TableCellContext, type GridCellPosition as TableCellPosition, type TableCellSpan, type TableCellSpanRule, type TableCellSpanRuleContext, type TableCellSpans, type GridColumn as TableColumn, type TableContextMenu, type TableContextMenuConfig, type ContextMenuEvent as TableContextMenuEvent, type GridSelection as TableEditingCell, type TableFilterValues, type TableHighlightConfig, type GridKey as TableKey, type TableLabels, type TableLayoutConfig, type TableLocaleCode, type TableLocaleConfig, type TableProps, type TableRef, type TableResolvedCellSpan, type TableRowNumberConfig, type GridSortState as TableSorter, type TableSummaryConfig, type TableTooltipConfig, type ViewportRange as TableViewportRange, type TableVirtualizedConfig, Table as VelocityGrid, type TableCellSpan as VelocityGridCellSpan, type TableCellSpanRule as VelocityGridCellSpanRule, type TableCellSpanRuleContext as VelocityGridCellSpanRuleContext, type TableCellSpans as VelocityGridCellSpans, type TableContextMenu as VelocityGridContextMenu, type TableContextMenuConfig as VelocityGridContextMenuConfig, type TableHighlightConfig as VelocityGridHighlightConfig, type TableLabels as VelocityGridLabels, type TableLayoutConfig as VelocityGridLayoutConfig, type TableLocaleCode as VelocityGridLocaleCode, type TableLocaleConfig as VelocityGridLocaleConfig, type TableProps as VelocityGridProps, type TableRef as VelocityGridRef, type TableResolvedCellSpan as VelocityGridResolvedCellSpan, type TableSummaryConfig as VelocityGridSummaryConfig, type TableTooltipConfig as VelocityGridTooltipConfig, type TableVirtualizedConfig as VelocityGridVirtualizedConfig, type ViewportRange, buildColumnMetrics, getViewportRange, hitTestColumn };

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/Table.tsx
-import { Fragment as Fragment2, useCallback as useCallback2, useEffect as useEffect2, useLayoutEffect as useLayoutEffect2, useMemo, useRef as useRef2, useState as useState4 } from "react";
+import { forwardRef, useImperativeHandle, Fragment as Fragment2, useCallback as useCallback2, useEffect as useEffect2, useLayoutEffect as useLayoutEffect2, useMemo, useRef as useRef2, useState as useState4 } from "react";
 import { flushSync } from "react-dom";
 
 // src/components/EmptyState.tsx
@@ -1492,7 +1492,7 @@ function resolveContextMenuSection(section, defaults) {
   }
   return defaults;
 }
-function Table({
+function TableInner({
   columns: columnProps,
   rows: sourceRows,
   rowKey,
@@ -1538,13 +1538,15 @@ function Table({
   onSortChange,
   onFilterChange,
   onCellChange,
+  onCellClick,
+  onCellDoubleClick,
   onCellContextMenu,
   contextMenu: contextMenuConfig = true,
   emptyContent,
   className = "",
   style,
   ariaLabel = "Data grid"
-}) {
+}, ref) {
   const [sourceColumns, setSourceColumns] = useState4(columnProps);
   useEffect2(() => {
     setSourceColumns((current) => reconcileColumns(current, columnProps));
@@ -1590,6 +1592,7 @@ function Table({
   const customContextMenuConfig = typeof contextMenuConfig === "object" ? contextMenuConfig : void 0;
   const [resizedColumnWidths, setResizedColumnWidths] = useState4({});
   const leafSourceColumns = useMemo(() => flattenDataColumns(sourceColumns), [sourceColumns]);
+  const showRowCheckbox = Boolean(rowSelection) && (typeof rowSelection !== "object" || rowSelection.showCheckbox !== false);
   useEffect2(() => {
     if (!isProductionRuntime() && hasNestedFixedColumns(sourceColumns)) {
       console.warn("[Table] Multi-level headers only support fixed columns on top-level columns. Nested fixed values are ignored.");
@@ -1600,19 +1603,19 @@ function Table({
     if (rowDraggable) {
       utilityColumns.push({ key: "__rvg_row_drag__", title: "", width: 36, align: "center", fixed: "left", rowDragHandle: true });
     }
-    if (rowSelection) {
+    if (showRowCheckbox) {
       utilityColumns.push({ key: "__rvg_row_selection__", title: "", width: 44, align: "center", fixed: "left", rowSelection: true });
     }
     if (rowNumber) {
-      utilityColumns.push({ key: "__rvg_row_number__", title: "#", width: getRowNumberColumnWidth(sourceRows.length), align: "center", fixed: "left", rowNumber: true });
+      utilityColumns.push({ key: "__rvg_row_number__", title: "#", width: getRowNumberColumnWidth(sourceRows.length), align: "center", fixed: typeof rowNumber === "object" && rowNumber.fixed === false ? void 0 : "left", rowNumber: true });
     }
     const dataColumns = leafSourceColumns.map((column) => {
       const resizedWidth = resizedColumnWidths[column.key];
       return resizedWidth === void 0 ? column : { ...column, width: resizedWidth };
     });
     return [...utilityColumns, ...dataColumns];
-  }, [leafSourceColumns, resizedColumnWidths, rowDraggable, rowNumber, rowSelection, sourceRows.length]);
-  const utilityColumnCount = (rowDraggable ? 1 : 0) + (rowSelection ? 1 : 0) + (rowNumber ? 1 : 0);
+  }, [leafSourceColumns, resizedColumnWidths, rowDraggable, rowNumber, showRowCheckbox, sourceRows.length]);
+  const utilityColumnCount = (rowDraggable ? 1 : 0) + (showRowCheckbox ? 1 : 0) + (rowNumber ? 1 : 0);
   const headerCells = useMemo(() => buildHeaderCells(sourceColumns, utilityColumnCount, headerDepth), [headerDepth, sourceColumns, utilityColumnCount]);
   const activeCustomHeaderLevels = useMemo(() => {
     const levels = /* @__PURE__ */ new Map();
@@ -3318,9 +3321,15 @@ function Table({
     scrollRef.current = { left: scroller.scrollLeft, top: scroller.scrollTop };
     scheduleDraw();
   }, [bodyTop, columns, fixedHeader, fixedWidth, getCellDisplayWidth, getCellSpan, getScrollableColumnLeft, metrics, rightFixedWidth, rowHeight, scheduleDraw, viewport.width]);
+  const isCellEditable = useCallback2((cell) => {
+    const column = columns[cell.columnIndex];
+    const row = rows[cell.rowIndex];
+    if (!column || !row || column.dataIndex === void 0 || column.rowNumber || column.rowSelection || column.rowDragHandle) return false;
+    return typeof column.editable === "function" ? column.editable(row[column.dataIndex], row, cell.rowIndex) : column.editable === true;
+  }, [columns, rows]);
   const beginEdit = useCallback2((cell) => {
     const column = columns[cell.columnIndex];
-    if (!column?.editable || column.dataIndex === void 0) return;
+    if (!isCellEditable(cell) || column.dataIndex === void 0) return;
     const value = rows[cell.rowIndex]?.[column.dataIndex];
     setDraft(value == null ? "" : String(value));
     const scroller = scrollerRef.current;
@@ -3362,7 +3371,7 @@ function Table({
       return;
     }
     setEditing(cell);
-  }, [columns, fixedHeader, fixedWidth, getCellDisplayWidth, getCellSpan, getScrollableColumnLeft, metrics, rightFixedWidth, rowHeight, rows, scheduleDraw, viewport.width]);
+  }, [columns, fixedHeader, fixedWidth, getCellDisplayWidth, getCellSpan, getScrollableColumnLeft, isCellEditable, metrics, rightFixedWidth, rowHeight, rows, scheduleDraw, viewport.width]);
   const getCellEditKey = (cell) => `${typeof cell.rowKey}:${String(cell.rowKey)}\0${cell.columnKey}`;
   const markCellEdited = (cell, previousValue, nextValue) => {
     const key = getCellEditKey(cell);
@@ -3390,6 +3399,10 @@ function Table({
   };
   const commitEdit = useCallback2((nextDraft, close = true) => {
     if (!editing) return;
+    if (!isCellEditable(editing)) {
+      setEditing(null);
+      return;
+    }
     const committedDraft = nextDraft ?? draft;
     const column = columns[editing.columnIndex];
     const row = rows[editing.rowIndex];
@@ -3404,7 +3417,7 @@ function Table({
       onCellChange?.({ ...editing, row, value: committedValue, previousValue });
     }
     if (close) setEditing(null);
-  }, [columns, draft, editing, onCellChange, rows]);
+  }, [columns, draft, editing, isCellEditable, onCellChange, rows]);
   const renderEditor = () => {
     if (!editing || !editorStyle) return null;
     const column = columns[editing.columnIndex];
@@ -4306,6 +4319,77 @@ function Table({
       `summary:${column.key}`
     );
   };
+  useImperativeHandle(ref, () => {
+    const resolveDataCell = (target) => {
+      const cell = resolveSelectionTarget(target);
+      if (!cell) return null;
+      const column = columns[cell.columnIndex];
+      if (column.rowNumber || column.rowSelection || column.rowDragHandle) return null;
+      const span = getCellSpan(cell.rowIndex, cell.columnIndex);
+      if (!span) return cell;
+      return {
+        rowIndex: span.rowIndex,
+        columnIndex: span.columnIndex,
+        rowKey: getRowKey(rows[span.rowIndex], span.rowIndex),
+        columnKey: columns[span.columnIndex].key
+      };
+    };
+    return {
+      focus: () => scrollerRef.current?.focus({ preventScroll: true }),
+      scrollToCell: (target) => {
+        const cell = resolveDataCell(target);
+        if (!cell) return false;
+        revealCell(cell);
+        return true;
+      },
+      getSelectedCell: () => {
+        if (!selection) return null;
+        const cell = resolveDataCell(selection);
+        if (!cell) return null;
+        const column = columns[cell.columnIndex];
+        const row = rows[cell.rowIndex];
+        return { ...cell, row, column, value: column.dataIndex === void 0 ? void 0 : row[column.dataIndex] };
+      },
+      setSelectedCell: (target) => {
+        const cell = target === null ? null : resolveDataCell(target);
+        if (target !== null && !cell) return false;
+        setSelectionRange(null);
+        setSelection(cell);
+        return true;
+      },
+      getSelectedRowKeys: () => [...rowKeys],
+      getSelectedRows: () => rows.filter((row, index) => selectedRowKeySet.has(getRowKey(row, index))),
+      setSelectedRowKeys: (keys) => {
+        if (!rowSelection) return;
+        const next = [...new Set(keys)];
+        setRowKeys(rowSelectionMode === "single" ? next.slice(0, 1) : next);
+      },
+      getSelectedColumnKeys: () => [...columnKeys],
+      setSelectedColumnKeys: (keys) => {
+        if (!columnSelection) return;
+        const next = [...new Set(keys)].filter((key) => columns.some((column) => column.key === key && !column.rowNumber && !column.rowSelection && !column.rowDragHandle));
+        setColumnKeys(typeof columnSelection === "object" && columnSelection.mode === "single" ? next.slice(0, 1) : next);
+      },
+      clearSelection: () => {
+        setSelectionRange(null);
+        setSelection(null);
+        setRowKeys([]);
+        setColumnKeys([]);
+        rowAnchorRef.current = null;
+        setEditing(null);
+      },
+      startEdit: (target) => {
+        const cell = target ? resolveDataCell(target) : selection ? resolveDataCell(selection) : null;
+        if (!cell || !isCellEditable(cell)) return false;
+        setSelectionRange(null);
+        setSelection(cell);
+        beginEdit(cell);
+        return true;
+      },
+      commitEdit: () => commitEdit(),
+      cancelEdit: () => setEditing(null)
+    };
+  });
   const rootStyle = {
     width,
     height: autoHeight ? effectiveHeight : height,
@@ -4504,6 +4588,10 @@ function Table({
             }
             if (event.detail > 1) return;
             clickedCellRef.current = cell;
+            const column = columns[cell.columnIndex];
+            const row = rows[cell.rowIndex];
+            onCellClick?.({ ...cell, row, column, value: column.dataIndex === void 0 ? void 0 : row[column.dataIndex] }, event);
+            if (event.defaultPrevented) return;
             setSelectionRange(null);
             scrollerRef.current?.focus({ preventScroll: true });
             setSelection(cell);
@@ -4514,7 +4602,12 @@ function Table({
           },
           onDoubleClick: (event) => {
             const cell = clickedCellRef.current ?? locateCell(event.clientX, event.clientY);
-            if (cell) beginEdit(cell);
+            if (!cell) return;
+            const column = columns[cell.columnIndex];
+            if (column.rowNumber || column.rowSelection || column.rowDragHandle) return;
+            const row = rows[cell.rowIndex];
+            onCellDoubleClick?.({ ...cell, row, column, value: column.dataIndex === void 0 ? void 0 : row[column.dataIndex] }, event);
+            if (!event.defaultPrevented) beginEdit(cell);
           },
           onContextMenu: handleContextMenu
         }
@@ -4527,7 +4620,7 @@ function Table({
             className: "rvg-text-scroll-content",
             style: { left: -fixedWidth, width: contentWidth, transform: `translateX(${-currentScroll.left}px)` },
             children: [
-              columns.map((column, columnIndex) => column.fixed || columnIndex < utilityColumnCount || headerDepth > 1 ? null : columnIndex >= domRange.columnStart && columnIndex < domRange.columnEnd ? /* @__PURE__ */ jsx7("span", { children: renderHeaderTitle(columnIndex, getScrollableColumnLeft(columnIndex)) }, column.key) : null),
+              columns.map((column, columnIndex) => column.fixed || columnIndex >= utilityColumnCount && headerDepth > 1 ? null : columnIndex >= domRange.columnStart && columnIndex < domRange.columnEnd ? /* @__PURE__ */ jsx7("span", { children: renderHeaderTitle(columnIndex, getScrollableColumnLeft(columnIndex)) }, column.key) : null),
               headerCells.map((cell) => {
                 if (columns[cell.startIndex]?.fixed) return null;
                 if (cell.endIndex < domRange.columnStart || cell.startIndex >= domRange.columnEnd) return null;
@@ -4545,7 +4638,7 @@ function Table({
           const left = column.fixed === "left" ? leftFixedOffsets.get(columnIndex) ?? 0 : viewport.width - (rightFixedOffsets.get(columnIndex) ?? 0) - metrics[columnIndex].width;
           return renderCellText(rowIndex, columnIndex, left);
         })) }),
-        columns.map((column, columnIndex) => columnIndex < utilityColumnCount || headerDepth === 1 && (column.fixed === "left" || column.fixed === "right") ? renderHeaderTitle(columnIndex, column.fixed === "right" ? viewport.width - (rightFixedOffsets.get(columnIndex) ?? 0) - metrics[columnIndex].width : column.fixed === "left" ? leftFixedOffsets.get(columnIndex) ?? 0 : getScrollableColumnLeft(columnIndex)) : null),
+        columns.map((column, columnIndex) => column.fixed && (columnIndex < utilityColumnCount || headerDepth === 1) ? renderHeaderTitle(columnIndex, column.fixed === "right" ? viewport.width - (rightFixedOffsets.get(columnIndex) ?? 0) - metrics[columnIndex].width : column.fixed === "left" ? leftFixedOffsets.get(columnIndex) ?? 0 : getScrollableColumnLeft(columnIndex)) : null),
         headerCells.map((cell) => columns[cell.startIndex]?.fixed ? renderGroupedHeaderCell(cell) : null),
         fixedWidth > 0 && currentScroll.left > 0 && /* @__PURE__ */ jsx7("div", { className: "rvg-text-fixed-shadow is-left", style: { left: fixedWidth } }),
         rightFixedWidth > 0 && currentScroll.left < contentWidth - viewport.width && /* @__PURE__ */ jsx7("div", { className: "rvg-text-fixed-shadow is-right", style: { right: rightFixedWidth } }),
@@ -4762,7 +4855,7 @@ function Table({
       const affectedRows = selectedIndices.includes(cell.rowIndex) ? selectedIndices : [cell.rowIndex];
       const cellContext = { ...cell, row, column, value: dataIndex === void 0 ? void 0 : row[dataIndex] };
       return renderConfiguredContextMenu(resolveContextMenuSection(customContextMenuConfig?.cell, DEFAULT_CELL_CONTEXT_MENU), cellContext, (item, override) => {
-        if (item === "edit") return renderContextMenuButton("cell-edit", cellContext, labels.edit, () => beginEdit(cell), override, { disabled: !column.editable, icon: /* @__PURE__ */ jsx7(ContextMenuIcon, { type: "edit" }) });
+        if (item === "edit") return renderContextMenuButton("cell-edit", cellContext, labels.edit, () => beginEdit(cell), override, { disabled: !isCellEditable(cell), icon: /* @__PURE__ */ jsx7(ContextMenuIcon, { type: "edit" }) });
         if (item === "copy") return renderContextMenuButton("cell-copy", cellContext, labels.copyContent, async () => {
           try {
             await navigator.clipboard.writeText(getCellLabel(cell.rowIndex, cell.columnIndex));
@@ -5002,6 +5095,7 @@ function Table({
     loading && !hasCustomLoading && hasCompletedLoadRef.current && /* @__PURE__ */ jsx7("div", { className: "rvg-refresh-loading", "aria-label": labels.refreshing, children: /* @__PURE__ */ jsx7(LoadingSpinnerIcon, {}) })
   ] });
 }
+var Table = forwardRef(TableInner);
 export {
   Table,
   Table as VelocityGrid,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lensui/lens-table",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "A lightweight, canvas-rendered React table component for LensUI.",
   "type": "module",
   "main": "./dist/index.cjs",