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

package/components/table/table-primitives.js

@@ -1,66 +1,13 @@
-import { use, useCallback } from 'react';
 import classNames from 'classnames';
-import unsortedIcon from '@jetbrains/icons/unsorted-12px';
-import arrowDownIcon from '@jetbrains/icons/arrow-12px-down';
-import arrowUpIcon from '@jetbrains/icons/arrow-12px-up';
-import trashIcon from '@jetbrains/icons/trash-12px';
-import Icon from '../icon/icon';
-import { ColumnIndexContext, TablePropsContext } from './table-const';
-import { keyboardFocusableAttrName } from './table-row-focus';
+import { ReorderHandle } from './internal/reorder-handle';
 import styles from './table.css';
 /**
- * Include it in a column header to make the column sortable.
- * Handle clicks with {@link TableProps.onSort}.
+ * @internal
  */
-export function SortButton({ className, children, onClick, ...restProps }) {
-    const tableProps = use(TablePropsContext);
-    const columnIndex = use(ColumnIndexContext);
-    const column = tableProps?.columns[columnIndex];
-    const sortOrder = column?.sortOrder ?? 'none';
-    // eslint-disable-next-line no-nested-ternary, prettier/prettier
-    const glyph = sortOrder === 'none' ? unsortedIcon
-        : sortOrder === 'ascending' ? arrowUpIcon
-            : arrowDownIcon;
-    const handleClick = useCallback((e) => {
-        onClick?.(e);
-        if (!e.defaultPrevented) {
-            const sequence = ['none', 'ascending', 'descending'];
-            const nextOrder = sequence[(sequence.indexOf(sortOrder) + 1) % sequence.length];
-            tableProps.onSort?.(columnIndex, nextOrder, tableProps.columns);
-        }
-    }, [columnIndex, onClick, sortOrder, tableProps]);
-    if (!tableProps || !column) {
-        return null;
-    }
-    return (<button type='button' className={classNames(styles.headerButton, className)} onClick={handleClick} {...restProps}>
-      {children} <Icon glyph={glyph} aria-hidden/>
-    </button>);
-}
-/**
- * Include it in a column header to make the column deletable.
- * Beware that `column.name ?? String(column.key)` is used in the aria-label.
- * Handle clicks with {@link TableProps.onColumnDelete}.
- */
-export function DeleteColumnButton({ className, onClick, ...restProps }) {
-    const tableProps = use(TablePropsContext);
-    const columnIndex = use(ColumnIndexContext);
-    const column = tableProps?.columns[columnIndex];
-    const handleClick = useCallback((e) => {
-        onClick?.(e);
-        if (!e.defaultPrevented) {
-            tableProps.onColumnDelete?.(columnIndex, tableProps.columns);
-        }
-    }, [columnIndex, onClick, tableProps]);
-    if (!tableProps || !column) {
-        return null;
-    }
-    return (<button type='button' className={classNames(styles.headerButton, styles.deleteColumnButton, className)} onClick={handleClick} aria-label={`Delete column ${column.name ?? String(column.key)}`} {...restProps}>
-      <Icon glyph={trashIcon}/>
-    </button>);
-}
+export const keyboardFocusableAttrName = 'data-keyboard-focusable';
 /**
- * A helper `<tr>` component for a custom {@link TableProps.renderItem} implementations.
- * Applies the standard row classnames.
+ * A helper `<tr>` component for custom {@link TableProps.renderItem} implementations.
+ * Applies the standard row class names.
  */
 export function TableRow(props) {
     const { keyboardFocusable, className, ...restProps } = props;
@@ -69,11 +16,19 @@ export function TableRow(props) {
     return <tr className={classes} {...trRestProps}/>;
 }
 /**
- * A helper `<td>` component for a custom {@link TableProps.renderItem} implementations.
- * Applies the standard cell classnames, but not data-dependent `tdClassName`.
+ * A helper `<td>` component for custom {@link TableProps.renderItem} implementations.
+ * Applies the standard cell class names, but not data-dependent `tdClassName`.
  */
 export function TableCell(props) {
     const { className, ...restProps } = props;
     const classes = classNames(styles.cell, className);
     return <td className={classes} {...restProps}/>;
 }
+/**
+ * A drag handle that allows the user to reorder the row. Place it anywhere
+ * inside a row renderer.
+ * Use {@link TableProps.canReorderItem} and {@link TableProps.onItemReorder}.
+ */
+export function ItemReorderHandle({ index, ...restProps }) {
+    return <ReorderHandle direction='items' index={index} {...restProps}/>;
+}

package/components/table/table-props.d.ts

@@ -0,0 +1,304 @@
+import type { AriaAttributes, ReactNode, RefObject } from 'react';
+export interface TableProps<T> {
+    /**
+     * The data items to render. `null` and `undefined` items are not supported.
+     * Referentially identical items are not supported either.
+     */
+    data: readonly T[];
+    /**
+     * Column definitions.
+     */
+    columns: readonly Column<T>[];
+    /**
+     * Used as a key in the items list.
+     */
+    getKey: (item: T, index: number, items: readonly T[]) => React.Key;
+    /**
+     * If `true`, the table header will not be rendered.
+     *
+     * Note that this may impact accessibility. If necessary, provide additional
+     * information via `aria-label` or `aria-description` on the `Table` element.
+     */
+    noHeader?: boolean;
+    /**
+     * If true, renders a sticky header.
+     */
+    stickyHeader?: boolean;
+    /**
+     * Called when the user clicks the sort button in a column header.
+     * The client is expected to update the `columns` prop with the new
+     * sort order for the corresponding column, and update the data accordingly.
+     */
+    onSort?: (columnIndex: number, newOrder: SortOrder, columns: readonly Column<T>[]) => void;
+    /**
+     * Called when the user clicks on a column delete button in the header.
+     * The client is expected to update the `columns` prop with the column removed.
+     */
+    onColumnDelete?: (column: Column<T>, columnIndex: number, columns: readonly Column<T>[]) => void;
+    /**
+     * Called when the user reorders columns by dragging a column.
+     * The `insertionIndex` parameter represents an insertion position in the original,
+     * unchanged `columns` array before the column is removed.
+     *
+     * One possible implementation is:
+     *
+     * ```ts
+     * columns.splice(fromIndex, 1);
+     * columns.splice(fromIndex < insertionIndex ? insertionIndex - 1 : insertionIndex, 0, columnBeingReordered);
+     * ```
+     *
+     * The callback is not called when the reorder operation would not change the
+     * column order, i.e. when
+     * `insertionIndex === fromIndex || insertionIndex === fromIndex + 1`.
+     */
+    onColumnReorder?: (columnBeingReordered: Column<T>, fromIndex: number, insertionIndex: number, columns: readonly Column<T>[]) => void;
+    /**
+     * By default, when a column is reordered, the moved column is highlighted
+     * with a temporary background color. Set `true` to disable this animation.
+     */
+    noColumnReorderAnimation?: boolean;
+    /**
+     * If defined, determines whether an item may be reordered to a specific insertion position.
+     * If not defined, any item may be reordered to any position.
+     */
+    canReorderItem?: (itemBeingReordered: T, fromIndex: number, insertionIndex: number, items: readonly T[]) => boolean;
+    /**
+     * Called when the user reorders items by dragging a handle.
+     * The `insertionIndex` parameter represents an insertion position in the original,
+     * unchanged `data` array before the item is removed. See {@link TableProps.onColumnReorder}
+     * for an example implementation.
+     *
+     * To make reorder possible, render `ItemReorderHandle` (from `table-primitives`)
+     * anywhere in a row.
+     *
+     * The callback is not called when the reorder operation would not change the
+     * item order, i.e. when
+     * `insertionIndex === fromIndex || insertionIndex === fromIndex + 1`.
+     */
+    onItemReorder?: (itemBeingReordered: T, fromIndex: number, insertionIndex: number, items: readonly T[]) => void;
+    /**
+     * By default, when an item is reordered, the moved item is highlighted
+     * with a temporary background color. Set `true` to disable this animation.
+     */
+    noItemReorderAnimation?: boolean;
+    /**
+     * Customizes how an item is rendered.
+     *
+     * Return `DefaultItemRenderer` to configure row-specific behavior such as
+     * `clickable`, `keyboardFocusable`, event handlers, `className`, or `ref`.
+     *
+     * You can also return custom row(s) instead. See the `Table` documentation
+     * for details.
+     */
+    renderItem?: (item: T, index: number, items: readonly 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`.
+     *
+     * Toggling this prop should normally work as expected, but a seamless
+     * transition is not guaranteed: the scroll position may reset to the top.
+     * However, if row height estimates are accurate and the data has not
+     * changed, the browser may apply scroll anchoring, resulting in a smoother
+     * transition, possibly with brief flickering but without scroll jumps.
+     */
+    virtualizeRows?: boolean;
+    /**
+     * Used with `virtualizeRows` as the source of scroll events, the target of
+     * `ResizeObserver`, and the root of `IntersectionObserver`. Required when
+     * the scrollable container is not the whole document.
+     *
+     * If not set:
+     * - the scroll listener is attached to `window`
+     * - `ResizeObserver` observes `document.body`
+     * - `IntersectionObserver` has no root (i.e. the viewport is used)
+     *
+     * Note that if this scroller is nested inside another scrollable container,
+     * the outer container is not tracked. As a result, items may not materialize
+     * until the inner scroller is scrolled.
+     *
+     * Support for nested scroll containers may be added in the future.
+     */
+    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: readonly 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;
+    /**
+     * "Column editing mode" is a mode in which controls that are normally hidden
+     * become visible, such as column reorder and delete buttons.
+     *
+     * When this prop is `undefined`, the component manages the mode internally.
+     * Users can toggle it by tapping the table header on mobile or by clicking
+     * the column edit button, if enabled. Since tapping the table header is not
+     * discoverable by assistive technologies, it's recommended to enable
+     * `columnEditButton` when using the internal mode.
+     *
+     * Alternatively, pass `true` or `false` to control the mode externally.
+     */
+    columnEditing?: boolean;
+    /**
+     * Called when the user requests to enter or leave column editing mode.
+     *
+     * The `source` parameter indicates what triggered the request.
+     *
+     * When `columnEditing` is not controlled, the component automatically
+     * applies the requested change internally.
+     *
+     * When `columnEditing` is controlled externally and you still want to
+     * respond to user requests, use this callback to decide whether to
+     * update the mode.
+     */
+    onColumnEditingRequest?: (editing: boolean, source: 'header' | 'edit-button') => void;
+    /**
+     * Whether to show a small gear button in the top-right corner that
+     * toggles column editing mode.
+     *
+     * For accessibility, it's recommended to enable this button unless you
+     * provide an external control for toggling column editing mode.
+     */
+    columnEditButton?: boolean;
+    /**
+     * 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 = Extract<AriaAttributes['aria-sort'], 'none' | 'ascending' | 'descending'>;
+/**
+ * The column specification.
+ */
+export interface Column<T> {
+    /**
+     * Used as a key in the columns list.
+     */
+    key: React.Key;
+    /**
+     * Used in `aria-label`s of column controls which do not contain text,
+     * such as the delete column button. If not set, the `String(key)` is used.
+     */
+    name?: string;
+    /**
+     * Renders the content of the column header, excluding controls such as
+     * the sort and delete buttons. If not specified, the default behavior is
+     * `name ?? String(key)`.
+     */
+    renderHeader?: () => ReactNode;
+    /**
+     * Renders the value of a single cell. If not specified, the default
+     * behavior is:
+     *
+     * - If `item` is an `Array`, renders `String(item[columnIndex])`
+     * - If `item` is an `Object`, renders `String(item[String(columnKey)])`
+     * - Otherwise:
+     *   - The first column renders `String(item)`
+     *   - Other columns render an empty string
+     */
+    renderCell?: (item: T, index: number, items: readonly T[]) => ReactNode;
+    /**
+     * If the column gets an indent when `DefaultItemRendererProps.level` returns
+     * a positive number.
+     */
+    indent?: boolean;
+    /**
+     * If set, displays sort button and includes `aria-sort` in the column header.
+     * Handle clicks with {@link TableProps.onSort}.
+     */
+    sortOrder?: AriaAttributes['aria-sort'];
+    /**
+     * Whether to display a delete button in the column header.
+     * Handle delete requests with {@link TableProps.onColumnDelete}.
+     * Make sure {@link Column.name} or {@link Column.key} is meaningful,
+     * as it will be included in the `aria-label` of the delete button.
+     */
+    deletable?: boolean;
+    /**
+     * Displays a reorder handle in the column header.
+     * Handle reorder requests with {@link TableProps.onColumnReorder}.
+     * If a function is provided, it determines whether the column may be moved
+     * to the specified insertion position.
+     *
+     * Make sure {@link Column.name} or {@link Column.key} is meaningful,
+     * as it will be included in the `aria-label` of the reorder button.
+     */
+    canReorder?: boolean | ((columnBeingReordered: Column<T>, fromIndex: number, insertionIndex: number, columns: readonly Column<T>[]) => boolean);
+    /**
+     * The class name to apply to the `th` element inside `table > thead`.
+     */
+    thClassName?: string;
+    /**
+     * The class name 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 the `DefaultItemRenderer`.
+     */
+    tdClassName?: string | ((item: T, index: number, items: readonly T[]) => string | undefined);
+}

package/components/table/table-props.js

@@ -0,0 +1 @@
+export {};

package/components/table/table.css

@@ -1,91 +1,73 @@
 @import '../global/variables.css';
 
 .table {
+  --reorder-animation-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;
+  border-bottom: 1px solid var(--ring-line-color);
 
-  font-size: var(--ring-font-size-smaller);
-  font-weight: normal;
-
-  &: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(.reorderAnimationInitial, .reorderAnimationFadeOut) {
+      background-color: var(--ring-grey-container-light-color);
     }
   }
 }
 
-.spacerRow {
-  margin: 0;
-  padding: 0;
-
-  border: 0;
-}
+.headerCellInnerWrapper {
+  display: flex;
+  justify-content: start;
 
-.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 {
+.tableButton {
   margin: unset;
   padding: unset;
 
@@ -108,30 +90,160 @@
     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;
+}
+
+.itemReorderHandle {
+  cursor: grab;
+
+  color: var(--ring-secondary-color);
+
+  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);
+  }
+}
+
+.dragFrame {
+  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);
+}
+
+.insertionIndicator {
+  position: fixed;
+
+  z-index: var(--ring-overlay-z-index);
+
+  background-color: var(--ring-main-color);
+}
+
+.reorderAnimationInitial {
+  transition: none;
+
+  background-color: rgba(var(--ring-border-accent-components), 0.12);
+}
+
+.reorderAnimationFadeOut {
+  transition: background-color var(--reorder-animation-fade-out-duration) ease-out;
+
+  background-color: transparent;
+}
 
-  color: var(--ring-main-hover-color);
+.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);
 }