@jetbrains/ring-ui 7.0.124 → 8.0.0-beta.10

package/components/table/table.d.ts

@@ -1,109 +1,233 @@
+import React, { type ComponentPropsWithRef } from 'react';
+import type { TableProps } from './table-props';
 /**
- * @name Table
+ * Table component replacing the tables in the `legacy-table` folder.
+ *
+ * This documentation provides an overview of the most common usage patterns.
+ * See individual props and exported components for detailed behavior.
+ *
+ * ## Minimal usage
+ *
+ * You need the following props:
+ * - `data`
+ * - `getKey`
+ * - `columns`
+ *   - `key`
+ *   - `name` (optional but needed in most cases)
+ *   - `renderCell` (optional but needed in most cases)
+ *
+ * ## Item rendering
+ *
+ * If `renderItem` is not specified, each item is rendered using
+ * `DefaultItemRenderer` (from `table/default-item-renderer`)
+ * as if the following code were used:
+ *
+ * ```tsx
+ * <Table
+ *   renderItem={(_item, index, _items) => (
+ *     <DefaultItemRenderer index={index} />
+ *   )}
+ * />
+ * ```
+ *
+ * `DefaultItemRenderer` renders a table row using the column definitions
+ * (`Column.renderCell`) and provides built-in support for features such as
+ * selection, keyboard navigation, and virtualization. It also accepts all
+ * standard `tr` attributes, including `ref`.
+ *
+ * Use `renderItem` to configure `DefaultItemRenderer` for each item:
+ *
+ * ```tsx
+ * <Table
+ *   renderItem={(item, index, items) => (
+ *     <DefaultItemRenderer
+ *       index={index}
+ *       keyboardFocusable
+ *       className='my-item'
+ *       onClick={e => handleClick(e, item, items)}
+ *     />
+ *   )}
+ * />
+ * ```
+ *
+ * If you need complete control over rendering, `renderItem` can instead
+ * return your own table rows. See "Custom item rendering" below.
+ *
+ * ## Selection
+ *
+ * Selection is typically implemented using the following props
+ * of the `DefaultItemRenderer`:
+ *
+ * - `clickable`
+ * - `selected`
+ * - `onClick` or `onPointerUp`, etc.
+ *
+ * The following utilities (from `global`) may come in handy:
+ *
+ * - `TableSelection` class to manage selection state
+ *   - An alternative approach is to keep a `selected` field on each item
+ * - `isWithinInteractiveElement()` to check if a click was made on a control
+ *   or on "empty space"
+ *
+ * ```tsx
+ * <Table
+ *   renderItem={(item, index) => (
+ *     <DefaultItemRenderer
+ *       index={index}
+ *       clickable
+ *       selected={selection.isSelected(item)}
+ *       onClick={e => {
+ *         if (!isWithinInteractiveElement(e)) {
+ *           setSelection(selection.toggleSelection(item));
+ *         }
+ *       }}
+ *     />
+ *   )}
+ * />
+ * ```
+ *
+ * Note that for accessibility reasons, you should have a cell with a checkbox
+ * to display and toggle item selection.
+ *
+ * ## Row focus
+ *
+ * The table implements the ["roving tabindex"](https://developer.mozilla.org/en-US/docs/Web/Accessibility/Guides/Keyboard-navigable_JavaScript_widgets#technique_1_roving_tabindex)
+ * technique to focus rows with the up/down arrow keys.
+ * Rows can also be focused on click or other pointer events.
+ * To support it, use the following props of the `DefaultItemRenderer`:
+ *
+ * - `keyboardFocusable`
+ * - `clickable`, if you want to react to hover
+ * - `onClick`, if you want to focus on click
+ *
+ * Useful utils:
+ * - `focusWithTemporaryTabIndex()` from `global` to focus a row temporarily
+ *   patching its `tabindex`.
+ *
+ * ```tsx
+ * <Table
+ *   renderItem={(item, index) => (
+ *     <DefaultItemRenderer
+ *       index={index}
+ *       clickable
+ *       keyboardFocusable
+ *       onClick={e => {
+ *         if (!isWithinInteractiveElement(e)) {
+ *           focusWithTemporaryTabIndex(e.currentTarget);
+ *         }
+ *       }}
+ *     />
+ *   )}
+ * />
+ * ```
+ *
+ * Note that the table does not implement standard accessibility patterns such
+ * as `grid` or `treegrid`, so row focus is not announced by screen readers.
+ * Make sure all essential actions remain available without row focus, for
+ * example via standard Tab navigation.
+ *
+ * ## Sorting
+ *
+ * You need the following to support sorting:
+ *
+ * - Set `Column.sortOrder` to `'none'`, `'ascending'` or `'descending'`
+ *   to render the sort button, `aria-sort`, and indicate the current
+ *   sort order.
+ * - Handle `TableProps.onSort` callback in the client code.
+ *
+ * ## Deleting columns
+ *
+ * You need the following to support deleting columns:
+ *
+ * - Set `Column.deletable` to `true`. This will render a delete button in the
+ *   column header.
+ * - Make sure the `column` has a proper `name` or `key` prop, which will be
+ *   automatically included in the aria-label of the column delete button.
+ * - Handle `TableProps.onColumnDelete` callback in the client code. It is
+ *   expected to update `columns` by removing the corresponding column.
+ *
+ * ## Moving columns
+ *
+ * - Set `Column.canReorder` to `true` or to predicate specifying possible
+ *   insertion targets.
+ *   This will render a reorder button in the column header.
+ * - Make sure the `column` has a proper `name` or `key` prop, which will be
+ *   automatically included in the aria-label of the column reorder button.
+ * - Handle `TableProps.onColumnReorder` callback in the client code. It is
+ *   expected to update `columns` by moving the corresponding column to the
+ *   new position.
+ *
+ * ## Item reorder
+ *
+ * To allow the user to reorder rows by dragging:
+ *
+ * - Place `ItemReorderHandle` (from `table/table-primitives`) anywhere inside
+ *   a cell. It renders a drag icon button the user can grab to reorder the row.
+ * - Handle `TableProps.onItemReorder`. It is expected to update `data` by
+ *   moving the item to the new position.
+ * - Optionally, set `TableProps.canReorderItem` to restrict which positions
+ *   an item may be dropped into.
+ *
+ * By default, dragging shows a drag frame (a border around the dragged row)
+ * and an insertion indicator (a line between rows showing where the item will
+ * land). To implement fully custom drag visuals, set `noDragFrame` and
+ * `noHandleTranslate` on `ItemReorderHandle` and use its `onUserDrag` callback
+ * to track the drag lifecycle.
+ *
+ * ## Row virtualization
+ *
+ * To render only rows near the viewport while replacing off-screen rows with
+ * spacers, use:
+ *
+ * - `virtualizeRows` prop set to `true`
+ * - `scrollerRef` — required when the scrollable container is not the whole
+ *    document
+ * - `estimateHeight` — recommended when rows are expected to be taller than
+ *   the default height (e.g. multiline or custom content)
+ * - Fine-tuning props: `lookaheadPx`, `retentionMarginPx`,
+ *   `minScrollAndResizeDeltaPx`
+ *
+ * ## Custom item rendering
+ *
+ * Use the `renderItem` prop to render an item in a completely custom way.
+ * The prop is expected to return one or more table rows for the item.
+ * Use `TableRow` and `TableCell` from `table/table-primitives` to apply
+ * the default row and cell styles.
+ *
+ * ### Focus
+ *
+ * Just like `DefaultItemRenderer`, `TableRow` accepts the
+ * `keyboardFocusable` prop.
+ *
+ * Focusable rows rendered by either component form a single keyboard
+ * navigation sequence.
+ *
+ * ### Virtualization
+ *
+ * If `Table.virtualizeRows` is set to `true`, you need to handle visibility
+ * for your custom-rendered component yourself with the
+ * `useItemVirtualization()` hook (from `table/item-virtualization`). The hook
+ * allows observing the intersection of one or multiple elements rendered for
+ * the item, and, based on their intersection status, reporting the item as
+ * eligible for virtualization.
+ *
+ * If you use `DefaultItemRenderer` as part of your custom row renderer,
+ * set the `noItemVirtualization` prop to `true`, otherwise it will also try
+ * to control the virtualization, possibly reporting incorrect item height.
+ *
+ * ### Item reorder
+ *
+ * If `TableProps.onItemReorder` is set and your item spans multiple rows, call
+ * `useReorderItemLayout()` (from `table/reorder-item-layout`) to register the
+ * item's boundaries so the insertion indicator and insertion point calculation
+ * are correct. If `DefaultItemRenderer` is included inside your custom renderer,
+ * set its `noReorderLayout` prop to `true` to prevent double registration.
+ *
+ * ### Reorder animation
+ *
+ * After a column or item is reordered, the table briefly highlights the moved
+ * element. To apply the same animation in your custom-rendered rows, use
+ * `useReorderAnimation()` (from `table/reorder-animation`) to get information
+ * about the currently animated column or item.
  */
-import { Component, PureComponent, type ReactNode, type SyntheticEvent } from 'react';
-import * as React from 'react';
-import { type OnChangeMeta } from 'react-movable/lib/types';
-import { type FocusSensorAddProps, type FocusSensorProps } from '../global/focus-sensor-hoc';
-import { type SelectionShortcutsAddProps, type SelectionShortcutsProps } from './selection-shortcuts-hoc';
-import { type DisableHoverAddProps, type DisableHoverProps } from './disable-hover-hoc';
-import Row from './row-with-focus-sensor';
-import { type Column, type SortParams } from './header-cell';
-export interface ReorderParams<T> {
-    data: T[];
-    oldIndex: number;
-    newIndex: number;
-}
-export interface TableProps<T extends object> extends FocusSensorAddProps<HTMLTableRowElement>, SelectionShortcutsAddProps<T>, DisableHoverAddProps {
-    data: readonly T[];
-    columns: readonly Column<T>[] | ((item: T | null) => readonly Column<T>[]);
-    isItemSelectable: (item: T) => boolean;
-    loading: boolean;
-    onSort: (params: SortParams) => void;
-    onReorder: (params: ReorderParams<T>) => void;
-    getItemKey: (item: T) => string | number;
-    sortKey: string;
-    sortOrder: boolean;
-    draggable: boolean;
-    alwaysShowDragHandle: boolean;
-    dragHandleTitle?: string;
-    stickyHeader: boolean;
-    wideFirstColumn: boolean;
-    getItemLevel: (item: T) => number;
-    getItemClassName: (item: T) => string | null | undefined;
-    getMetaColumnClassName: (item: T) => string | null | undefined;
-    getItemDataTest: (item: T) => string | null | undefined;
-    isItemCollapsible: (item: T) => boolean;
-    isParentCollapsible: (item: T) => boolean;
-    isItemCollapsed: (item: T) => boolean;
-    onItemCollapse: (item: T) => void;
-    onItemExpand: (item: T) => void;
-    onItemDoubleClick: (item: T) => void;
-    onItemClick: (item: T, e: React.MouseEvent<HTMLTableRowElement>) => void;
-    remoteSelection: boolean;
-    isDisabledSelectionVisible: (item: T) => boolean;
-    getCheckboxTooltip: (item: T) => string | undefined;
-    className?: string | null | undefined;
-    wrapperClassName?: string | null | undefined;
-    headerClassName?: string | null | undefined;
-    cellClassName?: string | null | undefined;
-    loaderClassName?: string | undefined;
-    caption?: string | null | undefined;
-    stickyHeaderOffset?: string | undefined;
-    renderEmpty?: (() => ReactNode) | null | undefined;
-    RowComponent: typeof Row;
-    renderLoader?: ((loaderClassName?: string) => ReactNode) | null | undefined;
-}
-/**
- * Interactive table with selection and keyboard navigation support.
- */
-export declare class Table<T extends object> extends PureComponent<TableProps<T>> {
-    static defaultProps: {
-        isItemSelectable: () => boolean;
-        loading: boolean;
-        onSort: () => void;
-        onReorder: () => void;
-        getItemKey: (item: object) => string | number;
-        sortKey: string;
-        sortOrder: boolean;
-        draggable: boolean;
-        alwaysShowDragHandle: boolean;
-        stickyHeader: boolean;
-        getItemLevel: () => number;
-        getItemClassName: () => null;
-        getMetaColumnClassName: () => null;
-        getItemDataTest: () => null;
-        isItemCollapsible: () => boolean;
-        isParentCollapsible: () => boolean;
-        isItemCollapsed: () => boolean;
-        onItemCollapse: () => void;
-        onItemExpand: () => void;
-        onItemDoubleClick: () => void;
-        onItemClick: () => void;
-        remoteSelection: boolean;
-        isDisabledSelectionVisible: () => boolean;
-        getCheckboxTooltip: () => undefined;
-        RowComponent: typeof Row;
-        wideFirstColumn: boolean;
-    };
-    state: {
-        shortcutsScope: string;
-        userSelectNone: boolean;
-    };
-    componentDidMount(): void;
-    componentDidUpdate({ data, selection, onSelect, selectable, remoteSelection }: TableProps<T>): void;
-    componentWillUnmount(): void;
-    onMouseDown: (e: React.MouseEvent) => void;
-    onMouseUp: () => void;
-    onRowFocus: (row: T) => void;
-    onRowSelect: (row: T, selected: boolean) => void;
-    onSortEnd: ({ oldIndex, newIndex }: OnChangeMeta) => void;
-    onCheckboxChange: (e: SyntheticEvent<HTMLInputElement>) => void;
-    restoreFocusWithoutScroll: () => void;
-    render(): React.JSX.Element;
-}
-export type TableAttrs<T extends object> = DisableHoverProps<SelectionShortcutsProps<T, FocusSensorProps<TableProps<T>, HTMLTableRowElement, typeof Table>>>;
-export default class TableContainer<T extends object> extends Component<TableAttrs<T>> {
-    Table: React.ComponentClass<DisableHoverProps<SelectionShortcutsProps<T, FocusSensorProps<TableProps<T>, HTMLTableRowElement, typeof Table>>>, any>;
-    render(): React.JSX.Element;
-}
+export default function Table<T>(props: TableProps<T> & ComponentPropsWithRef<'table'>): React.JSX.Element;