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

package/components/table/table.css

@@ -1,90 +1,72 @@
 @import '../global/variables.css';
 
 .table {
+  --animated-column-fade-out-duration: 600ms;
+
   width: 100%;
 
-  border-collapse: collapse;
+  border-spacing: 0;
+
   border-style: none;
 }
 
-.headerRow {
-  border-bottom: 1px solid var(--ring-line-color);
+.stickyHeader {
+  position: sticky;
+  z-index: var(--ring-overlay-z-index);
+
+  top: 0;
+
+  background-color: rgba(var(--ring-content-background-components), 0.85);
+  backdrop-filter: blur(8px);
+}
+
+@property --header-cell-shadow-color {
+  syntax: '<color>';
+  inherits: true;
+  initial-value: transparent;
 }
 
 .headerCell {
-  position: relative;
+  margin: 0;
 
   padding: calc(var(--ring-unit) * 0.75) var(--ring-unit);
 
-  transition: background-color var(--ring-fast-ease), border-color var(--ring-fast-ease);
-
-  text-align: left;
+  transition: background-color var(--ring-fast-ease), --header-cell-shadow-color var(--ring-fast-ease);
 
-  color: var(--ring-secondary-color);
-  border-left: 1px solid transparent;
-
-  font-size: var(--ring-font-size-smaller);
-  font-weight: normal;
+  border-bottom: 1px solid var(--ring-line-color);
 
-  &:last-child {
-    border-right: 1px solid transparent;
-  }
+  box-shadow: inset 1px 0 0 var(--header-cell-shadow-color), 1px 0 0 var(--header-cell-shadow-color);
 
   &:hover {
-    border-left-color: var(--ring-line-color);
-    background-color: var(--ring-grey-container-light-color);
-
-    &:last-child {
-      border-right-color: var(--ring-line-color);
-    }
+    --header-cell-shadow-color: var(--ring-line-color);
 
-    & + .headerCell {
-      border-left-color: var(--ring-line-color);
+    &:not(.animatedColumnInitial, .animatedColumnFadeOut) {
+      background-color: var(--ring-grey-container-light-color);
     }
   }
 }
 
-.spacerRow {
-  margin: 0;
-  padding: 0;
+.headerCellInnerWrapper {
+  display: flex;
+  justify-content: start;
 
-  border: 0;
-}
-
-.spacerCell {
-  margin: 0;
-  padding: 0;
+  color: var(--ring-secondary-color);
 
-  border: 0;
-}
+  font-size: var(--ring-font-size-smaller);
+  font-weight: normal;
 
-.row {
-  border-bottom: 1px solid var(--ring-line-color);
+  .sortAndHeader {
+    flex-grow: 1;
 
-  &:focus {
-    border-radius: var(--ring-border-radius);
-    outline: 2px solid var(--ring-button-focus-border-color);
+    text-align: left;
+    white-space: nowrap;
   }
-}
 
-.clickableRow {
-  cursor: pointer;
-
-  transition: background-color var(--ring-fast-ease);
-
-  &:not(.selectedRow):hover {
-    background-color: var(--ring-hover-background-color);
+  .rightButtons {
+    margin-left: 4px;
   }
 }
 
-.selectedRow {
-  background-color: var(--ring-selected-background-color);
-}
-
-.cell {
-  padding: var(--ring-unit);
-}
-
 .headerButton {
   margin: unset;
   padding: unset;
@@ -108,30 +90,153 @@
     border-radius: 2px;
     outline: 2px solid var(--ring-button-focus-border-color);
   }
+
+  &:focus-within {
+    color: var(--ring-main-hover-color);
+  }
 }
 
 .deleteColumnButton {
-  float: right;
-
   pointer-events: none;
 
   color: transparent;
 
-}
-
-.headerCell:hover .deleteColumnButton {
-  pointer-events: all;
+  .theadColumnEditing &,
+  .headerCell:hover &,
+  &:focus {
+    pointer-events: unset;
+  }
 
-  color: unset;
+  /* stylelint-disable-next-line selector-max-specificity */
+  .theadColumnEditing &:not(:focus),
+  /* stylelint-disable-next-line selector-max-specificity */
+  .headerCell:hover &:not(:focus) {
+    color: unset;
+  }
 
   /* stylelint-disable-next-line selector-max-specificity */
-  &:hover {
+  .headerCell:hover &:hover:not(:focus),
+  &:focus {
     color: var(--ring-main-hover-color);
   }
 }
 
-.deleteColumnButton:focus-within {
-  pointer-events: all;
+.columnReorderHandle {
+  overflow: hidden;
+
+  width: 0;
+
+  cursor: grab;
+
+  transition: color var(--ring-fast-ease), width var(--ring-fast-ease), margin-right var(--ring-fast-ease);
+
+  border-radius: var(--ring-border-radius);
+  touch-action: none;
+}
+
+.theadColumnEditing .columnReorderHandle,
+.headerCell:hover .columnReorderHandle,
+.columnReorderHandle:focus-visible {
+  width: 12px;
+  margin-right: 4px;
+}
+
+.columnReorderHandleMirror {
+  display: inline-block;
+
+  width: 12px;
+  margin-left: 4px;
+
+  transition: width var(--ring-fast-ease), margin-left var(--ring-fast-ease);
+}
+
+.theadColumnEditing .columnReorderHandleMirror,
+.headerCell:hover .columnReorderHandleMirror,
+.columnReorderHandle:focus-visible ~ .columnReorderHandleMirror {
+  width: 0;
+  margin-left: 0;
+}
+
+.editColumnsButton {
+  & svg {
+    transition: transform var(--ring-fast-ease);
+  }
+
+  .theadColumnEditing & svg {
+    transform: rotate(90deg);
+  }
+}
+
+.columnDragFrame {
+  position: fixed;
+
+  z-index: var(--ring-overlay-z-index);
+
+  pointer-events: none;
+
+  border: 2px solid var(--ring-border-accent-color);
+  border-radius: calc(2 * var(--ring-border-radius));
+
+  background-color: rgba(var(--ring-border-accent-components), 0.06);
+}
+
+.columnInsertionIndicator {
+  position: fixed;
+
+  z-index: var(--ring-overlay-z-index);
 
-  color: var(--ring-main-hover-color);
+  width: 2px;
+
+  background-color: var(--ring-main-color);
+}
+
+.animatedColumnInitial {
+  transition: none;
+
+  background-color: rgba(var(--ring-border-accent-components), 0.12);
+}
+
+.animatedColumnFadeOut {
+  transition: background-color var(--animated-column-fade-out-duration) ease-out;
+
+  background-color: transparent;
+}
+
+.spacerRow {
+  margin: 0;
+  padding: 0;
+
+  border: 0;
+}
+
+.spacerCell {
+  margin: 0;
+  padding: 0;
+
+  border: 0;
+}
+
+.row:focus {
+  border-radius: var(--ring-border-radius);
+  outline: 2px solid var(--ring-button-focus-border-color);
+}
+
+.clickableRow {
+  cursor: pointer;
+
+  transition: background-color var(--ring-fast-ease);
+
+  &:not(.selectedRow):hover {
+    background-color: var(--ring-hover-background-color);
+  }
+}
+
+.selectedRow {
+  background-color: var(--ring-selected-background-color);
+}
+
+.cell {
+  padding: var(--ring-unit);
+
+  border-bottom: 1px solid var(--ring-line-color);
 }

package/components/table/table.d.ts

@@ -1,211 +1,207 @@
-import Table from './table-component';
-import type { ReactNode, RefObject } from 'react';
-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, items: T[]) => React.Key;
-    /**
-     * If true, the table header will not be rendered.
-     */
-    noHeader?: boolean;
-    /**
-     * 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, columns: Column<T>[]) => void;
-    /**
-     * Called when the client clicks on a column delete button in the header.
-     */
-    onColumnDelete?: (columnIndex: number, columns: Column<T>[]) => void;
-    /**
-     * Called when the client moves a column.
-     */
-    onColumnMove?: (fromIndex: number, toIndex: number, columns: Column<T>[]) => 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?: 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?: (item: T, index: number, items: T[]) => 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';
-    /**
-     * 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, items)}...</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;