@jetbrains/ring-ui 8.0.0-beta.2 → 8.0.0-beta.4

package/components/table/table.d.ts

@@ -1,226 +1,207 @@
-import Table from './table-component';
-import type { ReactNode, RefObject } from 'react';
-import type Selection from '../legacy-table/selection';
-export default Table;
-export interface TableProps<T> {
-    /**
-     * The data items to render. `null` and `undefined` as an item is not supported.
-     * Referentially same items are not supported either.
-     */
-    data: T[];
-    /**
-     * Columns specification.
-     */
-    columns: Column<T>[];
-    /**
-     * Used to render a row key, e.g. `<tr key={getKey(item, index)}>`.
-     */
-    getKey: (item: T, index: number) => React.Key;
-    /**
-     * Displays the selection and focus state.
-     */
-    selection?: Selection<T>;
-    /**
-     * If true, the item can be focused by keyboard up/down arrows.
-     * Note that `false` doesn't prevent from `selection.focus()`.
-     */
-    isItemKeyboardFocusable?: (item: T, index: number, items: T[]) => boolean;
-    /**
-     * When the item should get focused by keyboard navigation.
-     * The client is expected to update `selection`.
-     */
-    onItemFocus?: (item: T | null, index: number, items: T[]) => void;
-    /**
-     * Called when the client moves a row by dragging it.
-     */
-    onItemMove?: (item: T, fromIndex: number, toIndex: number, items: T[]) => void;
-    /**
-     * Called when the client clicks on SortButton in a column header.
-     */
-    onSort?: (columnIndex: number, newOrder: SortOrder) => void;
-    /**
-     * Called when the client clicks on a column delete button in the header.
-     */
-    onColumnDelete?: (columnIndex: number) => void;
-    /**
-     * Called when the client moves a column.
-     */
-    onColumnMove?: (fromIndex: number, toIndex: number) => void;
-    /**
-     * Implement to specify props like `clickable`, handlers like `onClick`,
-     * a custom `className`, a `ref` etc., or to provide a custom renderer.
-     *
-     * ```tsx
-     * <Table
-     *   renderItem={(item, index) => (
-     *     <DefaultItemRenderer
-     *       index={index}
-     *       className='my-row'
-     *       clickable
-     *       onClick={() => setSelection(selection.focus(item))}
-     *     />
-     *   )}
-     * />
-     * ```
-     *
-     * In your custom implementation, use `TableRow` and `TableCell` base components to apply the
-     * standard classnames, but beware that `tdClassName` won't be applied.
-     *
-     * You can also use `DefaultItemRenderer` in combination with your custom rows.
-     */
-    renderItem?: (item: T, index: number, items: T[]) => ReactNode;
-    /**
-     * Only renders rows near the viewport.
-     *
-     * Rows may transition between two states:
-     * - materialized: rendered as actual table rows. This happens when the corresponding
-     *   spacer approaches the viewport, as specified by `lookaheadPx`.
-     * - virtualized: replaced with spacer rows of the same height. This happens when the row
-     *   moves sufficiently far from the viewport, as specified by `retentionMarginPx`.
-     */
-    virtualizeRows?: boolean;
-    /**
-     * Used with `virtualizeRows` as a source of scroll events, as a target for ResizeObserver,
-     * and as the root for IntersectionObserver. Required when the scrollable container is not
-     * the whole document.
-     *
-     * If not set:
-     * - scroll listener is attached to `window`
-     * - ResizeObserver observes `document.body`
-     * - IntersectionObserver has no root (i.e. the viewport is used)
-     */
-    scrollerRef?: React.RefObject<HTMLElement | null>;
-    /**
-     * Used with `virtualizeRows` to estimate the height of items that have not been rendered yet.
-     * The function should be fast and side-effect free. Do not measure the DOM here.
-     * Once a row is rendered, its actual height will be measured and used instead of this estimate.
-     *
-     * Note the effects of imprecise estimates:
-     * - When the height is underestimated, the table may materialize more rows than specified by `lookaheadPx`.
-     *   If the resulting rows extend beyond `retentionMarginPx`, they will be virtualized again.
-     *   If this causes relayout flickering, increase `retentionMarginPx`.
-     * - When the height is overestimated, the table may materialize fewer rows than specified by `lookaheadPx`,
-     *   which may leave a spacer partially visible. To avoid this, increase `lookaheadPx` (and
-     *   `retentionMarginPx` accordingly, since it should be greater than `lookaheadPx`).
-     *
-     * Default: 37px = 16px padding + 20px line height + 1px border.
-     */
-    estimateHeight?: (index: number) => number;
-    /**
-     * When using `virtualizeRows`, the number of pixels above and below the viewport
-     * to materialize in advance.
-     *
-     * Increase this value if blank space becomes visible during fast scrolling.
-     *
-     * Default: 400px.
-     */
-    lookaheadPx?: number;
-    /**
-     * Used with `virtualizeRows`. Additional margin around the viewport before
-     * materialized rows become eligible for virtualization.
-     *
-     * Increasing this value reduces row churn when heights are underestimated.
-     * In that case, the table may materialize more rows than needed and then immediately
-     * virtualize them again. A larger margin keeps such rows rendered for longer,
-     * at the cost of rendering more rows overall.
-     *
-     * This value should be greater than `lookaheadPx`.
-     * Increase it if you notice table relayouts during initial render or scrolling.
-     *
-     * Default: 450px.
-     */
-    retentionMarginPx?: number;
-    /**
-     * When using `virtualizeRows`, ignore scroll and resize position changes
-     * smaller than this value.
-     *
-     * Measurement inaccuracies and rounding artifacts may slightly change the
-     * table layout during materialization and virtualization. With scroll
-     * anchoring enabled (the default browser behavior), the browser may then
-     * adjust the scroll position, triggering additional scroll or resize events.
-     * Small deltas are ignored to prevent such feedback loops from causing
-     * oscillations at virtualization boundaries.
-     *
-     * Increase if you expect high inaccuracy in height measurements, or if you
-     * notice oscillations at virtualization boundaries.
-     *
-     * Default: 50px.
-     */
-    minScrollAndResizeDeltaPx?: number;
-    /**
-     * Whether to show a small gear button at the top right corner.
-     */
-    columnEditButton?: 'everywhere' | 'mobileOnly';
-    /**
-     * Optional ref to install on the table element.
-     */
-    ref?: RefObject<HTMLTableElement | null>;
-    /**
-     * Applied to the `<thead>` element.
-     */
-    theadClassName?: string;
-    /**
-     * Applied to the only `<tr>` element within the `<thead>`.
-     */
-    theadTrClassName?: string;
-    /**
-     * Applied to the `<tbody>` element.
-     */
-    tbodyClassName?: string;
-}
-export type SortOrder = 'none' | 'ascending' | 'descending';
+import React, { type ComponentPropsWithRef } from 'react';
+import type { TableProps } from './table-props';
 /**
- * The column specification.
+ * 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.
+ *
+ * ## Rows 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.
+ *
+ * ## 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.
+ *
+ * ### Column reorder animation
+ *
+ * Default-rendered rows highlight the column that was just reordered. To apply
+ * the same animation to your custom-rendered rows, use `ColumnAnimationContext`
+ * (from `table/table-const`) to get information about the currently animated column.
  */
-export interface Column<T> {
-    /**
-     * Used to render a row key, e.g. `<thead><tr><td key={getKey(item, index)}...</td></tr></thead>`.
-     */
-    key: React.Key;
-    /**
-     * Used in aria-labels of controls which do not contain text,
-     * e.g. `DeleteColumnButton`. If not set, the `String(key)` is used.
-     */
-    name?: string;
-    /**
-     * Default: name ?? String(key)
-     */
-    renderHeader?: () => ReactNode;
-    /**
-     * Renders a single cell value for a column.
-     * Default:
-     * - If item is an Array, renders `String(item[columnIndex])`
-     * - If item is an Object, renders `Object.values(item)[columnIndex]`
-     * - Otherwise:
-     *   - The first column renders `String(item)`
-     *   - Other columns render empty value
-     */
-    renderCell?: (item: T, index: number, items: T[]) => ReactNode;
-    /**
-     * If the column gets an indent when `TableProps.getItemLevel()` returns
-     * a positive number.
-     */
-    indent?: boolean;
-    /**
-     * The current sort order displayed by `SortButton` and indicated
-     * by `aria-sort` in `th`.
-     *
-     * - `undefined` or not set means that the column is not sortable,
-     * and it shouldn't have a `SortButton`.
-     * - `none` means that the column is sortable, but currently not sorted.
-     * It should include a `SortButton`.
-     * - `ascending` and `descending` mean that the column is sorted
-     * in the corresponding order, and it should include a `SortButton`.
-     */
-    sortOrder?: SortOrder;
-    /**
-     * The classname to apply to the `th` element inside `table / thead`.
-     */
-    thClassName?: string;
-    /**
-     * The classname to apply to the `td` element inside `table / tbody`.
-     * If a custom `TableProps.renderItem` is provided, this prop is not used,
-     * unless the custom renderer falls back to `DefaultItemRenderer`.
-     */
-    tdClassName?: (item: T, index: number, items: T[]) => string | undefined;
-}
+export default function Table<T>(props: TableProps<T> & ComponentPropsWithRef<'table'>): React.JSX.Element;