@jetbrains/ring-ui 7.0.115 → 8.0.0-beta.1

package/components/table/table.d.ts

@@ -1,109 +1,226 @@
-/**
- * @name Table
- */
-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> {
+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[];
-    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;
+    /**
+     * 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';
 /**
- * Interactive table with selection and keyboard navigation support.
+ * The column specification.
  */
-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 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;
 }

package/components/table/table.js

@@ -1,191 +1,2 @@
-/**
- * @name Table
- */
-import { Component, PureComponent } from 'react';
-import * as React from 'react';
-import classNames from 'classnames';
-import { arrayMove, List } from 'react-movable';
-import focusSensorHOC from '../global/focus-sensor-hoc';
-import getUID from '../global/get-uid';
-import Shortcuts from '../shortcuts/shortcuts';
-import Loader from '../loader/loader';
-import Header from './header';
-import selectionShortcutsHOC from './selection-shortcuts-hoc';
-import disableHoverHOC from './disable-hover-hoc';
-import Row from './row-with-focus-sensor';
-import style from './table.css';
-/**
- * Interactive table with selection and keyboard navigation support.
- */
-export class Table extends PureComponent {
-    static defaultProps = {
-        isItemSelectable: () => true,
-        loading: false,
-        onSort: () => { },
-        onReorder: () => { },
-        getItemKey: (item) => {
-            // Default behavior stays backward compatible: use item's "id" if present
-            if ('id' in item) {
-                return item.id;
-            }
-            // If there's no id provided on item and no getKey supplied, fail fast with a clear message
-            throw new Error('Table: getItemKey is required when items have no "id" property');
-        },
-        sortKey: 'id',
-        sortOrder: true,
-        draggable: false,
-        alwaysShowDragHandle: false,
-        stickyHeader: true,
-        getItemLevel: () => 0,
-        getItemClassName: () => null,
-        getMetaColumnClassName: () => null,
-        getItemDataTest: () => null,
-        isItemCollapsible: () => false,
-        isParentCollapsible: () => false,
-        isItemCollapsed: () => false,
-        onItemCollapse: () => { },
-        onItemExpand: () => { },
-        onItemDoubleClick: () => { },
-        onItemClick: () => { },
-        remoteSelection: false,
-        isDisabledSelectionVisible: () => false,
-        getCheckboxTooltip: () => undefined,
-        RowComponent: Row,
-        wideFirstColumn: false,
-    };
-    state = {
-        shortcutsScope: getUID('ring-table-'),
-        userSelectNone: false,
-    };
-    componentDidMount() {
-        document.addEventListener('mouseup', this.onMouseUp);
-    }
-    componentDidUpdate({ data, selection, onSelect, selectable, remoteSelection }) {
-        if (data !== this.props.data && remoteSelection) {
-            onSelect(selection.cloneWith({ data: this.props.data }));
-        }
-        if (!this.props.selectable && this.props.selectable !== selectable) {
-            onSelect(selection.resetSelection());
-        }
-    }
-    componentWillUnmount() {
-        document.removeEventListener('mouseup', this.onMouseUp);
-    }
-    onMouseDown = (e) => {
-        if (e.shiftKey) {
-            this.setState({ userSelectNone: true });
-        }
-    };
-    onMouseUp = () => {
-        if (this.state.userSelectNone) {
-            this.setState({ userSelectNone: false });
-        }
-    };
-    onRowFocus = (row) => {
-        const { selection, onSelect } = this.props;
-        onSelect(selection.focus(row));
-    };
-    onRowSelect = (row, selected) => {
-        const { selection, onSelect } = this.props;
-        if (selected) {
-            onSelect(selection.select(row));
-        }
-        else {
-            onSelect(selection.deselect(row));
-        }
-    };
-    onSortEnd = ({ oldIndex, newIndex }) => {
-        const data = arrayMove(this.props.data, oldIndex, newIndex);
-        this.props.onReorder({ data, oldIndex, newIndex });
-    };
-    onCheckboxChange = (e) => {
-        const { checked } = e.currentTarget;
-        const { selection, onSelect } = this.props;
-        if (checked) {
-            onSelect(selection.selectAll());
-        }
-        else {
-            onSelect(selection.reset());
-        }
-        this.restoreFocusWithoutScroll();
-    };
-    restoreFocusWithoutScroll = () => {
-        const { scrollX, scrollY } = window;
-        this.props.onFocusRestore();
-        window.scrollTo(scrollX, scrollY);
-    };
-    render() {
-        const { data, selection, columns, caption, getItemKey, selectable, focused, isItemSelectable, getItemLevel, getItemClassName, getMetaColumnClassName, getItemDataTest, draggable, alwaysShowDragHandle, dragHandleTitle, loading, onSort, sortKey, sortOrder, loaderClassName, stickyHeader, stickyHeaderOffset, isItemCollapsible, isParentCollapsible, isItemCollapsed, onItemCollapse, onItemExpand, isDisabledSelectionVisible, getCheckboxTooltip, onItemDoubleClick, onItemClick, renderEmpty, RowComponent, renderLoader, } = this.props;
-        // NOTE: Do not construct new object per render because it causes all rows rerendering
-        const columnsArray = typeof columns === 'function' ? columns(null) : columns;
-        const headerProps = {
-            caption,
-            selectable,
-            draggable,
-            columns: columnsArray,
-            onSort,
-            sortKey,
-            sortOrder,
-            sticky: stickyHeader,
-            topStickOffset: stickyHeaderOffset,
-            className: this.props.headerClassName,
-        };
-        const selectedSize = selection.getSelected().size;
-        const allSelectedSize = selection.selectAll().getSelected().size;
-        headerProps.checked = selectedSize > 0 && selectedSize === allSelectedSize;
-        headerProps.onCheckboxChange = this.onCheckboxChange;
-        headerProps.checkboxDisabled = this.props.data.length === 0;
-        const wrapperClasses = classNames(style.tableWrapper, this.props.wrapperClassName);
-        const classes = classNames(this.props.className, {
-            [style.table]: true,
-            [style.wideFirstColumn]: this.props.wideFirstColumn,
-            [style.userSelectNone]: this.state.userSelectNone,
-            [style.disabledHover]: this.props.disabledHover,
-        });
-        const renderList = ({ children, props }) => {
-            const empty = (<tr>
-          <td colSpan={columnsArray.length || 1} className={style.tableMessage}>
-            {renderEmpty ? renderEmpty() : null}
-          </td>
-        </tr>);
-            const tbody = Array.isArray(children) && children.length > 0 ? children : empty;
-            return (<table className={classes} data-test='ring-table'>
-          <Header {...headerProps}/>
-          <tbody {...props} data-test='ring-table-body'>
-            {tbody}
-          </tbody>
-        </table>);
-        };
-        const renderItem = ({ value, props = {}, isDragged }) => {
-            if (value === null || value === undefined) {
-                return null;
-            }
-            const { ref, ...restProps } = props;
-            const row = (<RowComponent innerRef={ref} level={getItemLevel(value)} item={value} showFocus={selection.isFocused(value)} autofocus={selection.isFocused(value)} focused={focused && selection.isFocused(value)} selectable={selectable && isItemSelectable(value)} selected={selectable && selection.isSelected(value)} onFocus={this.onRowFocus} onSelect={this.onRowSelect} onDoubleClick={onItemDoubleClick} onClick={onItemClick} collapsible={isItemCollapsible(value)} parentCollapsible={isParentCollapsible(value)} collapsed={isItemCollapsed(value)} onCollapse={onItemCollapse} onExpand={onItemExpand} showDisabledSelection={isDisabledSelectionVisible(value)} checkboxTooltip={getCheckboxTooltip(value)} className={classNames(getItemClassName(value), { [style.draggingRow]: isDragged })} metaColumnClassName={getMetaColumnClassName(value)} draggable={draggable} alwaysShowDragHandle={alwaysShowDragHandle} dragHandleTitle={dragHandleTitle} columns={columns} data-test={getItemDataTest(value)} cellClassName={this.props.cellClassName} {...restProps} key={restProps.key ?? getItemKey(value)}/>);
-            return isDragged ? (<table style={{ ...props.style }} className={style.draggingTable}>
-          <tbody>{row}</tbody>
-        </table>) : (row);
-        };
-        return (<div className={wrapperClasses} data-test='ring-table-wrapper' ref={this.props.innerRef}>
-        {focused && <Shortcuts map={this.props.shortcutsMap} scope={this.state.shortcutsScope}/>}
-
-        {/* Handler detects that user holds Shift key */}
-        <div role='presentation' onMouseDown={this.onMouseDown}>
-          {draggable ? (<List values={data} renderList={renderList} renderItem={renderItem} onChange={this.onSortEnd}/>) : (renderList({ children: data.map((value, index) => renderItem({ value, index })) }))}
-        </div>
-
-        {loading && (<div className={style.loadingOverlay}>
-            {renderLoader ? renderLoader(loaderClassName) : <Loader className={loaderClassName}/>}
-          </div>)}
-      </div>);
-    }
-}
-const getContainer = () => disableHoverHOC(selectionShortcutsHOC(focusSensorHOC(Table)));
-// eslint-disable-next-line react/no-multi-comp
-export default class TableContainer extends Component {
-    // https://stackoverflow.com/a/53882322/6304152
-    Table = getContainer();
-    render() {
-        return <this.Table {...this.props}/>;
-    }
-}
+import Table from './table-component';
+export default Table;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jetbrains/ring-ui",
-  "version": "7.0.115",
+  "version": "8.0.0-beta.1",
   "description": "JetBrains UI library",
   "author": {
     "name": "JetBrains"