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

package/components/global/intersection-observer-context.d.ts

@@ -1,5 +1,21 @@
 import { type RefObject } from 'react';
 /**
+ * Provides access to a shared `IntersectionObserver` instance
+ * via the {@link IntersectionObserverContext} context.
+ *
+ * @see IntersectionObserverContext
+ */
+export interface IntersectionObserverHandle {
+    /**
+     * Starts observing an element.
+     *
+     * Returns a cleanup function that stops observing it.
+     */
+    observe(element: Element, isIntersecting: (isIntersecting: boolean) => void): () => void;
+}
+/**
+ * Multiple components can share a single `IntersectionObserver` instance through this context.
+ *
  * Usage:
  *
  * ```tsx
@@ -10,17 +26,21 @@ import { type RefObject } from 'react';
  * function YourComponent() {
  *   // Contains the current isIntersecting value
  *   const isIntersecting = useIsIntersecting(elementRef);
- *   // Or, to get updates instead:
- *   useIsIntersectingListener(elementRef, newIsIntersecting => {
- *     // ...
+ *
+ *   // Or, to manually work with the IntersectionObserverHandle:
+ *   const handle = use(IntersectionObserverContext);
+ *   useEffect(() => {
+ *     return handle.observe(elementRef.current, isIntersecting => { ... })
  *   })
  * }
  * ```
  */
-export declare const IntersectionObserverContext: import("react").Context<IntersectionObserverHandle | null>;
-export declare function useIntersectionObserverHandle(rootRef?: RefObject<HTMLElement | null>, rootMargin?: number, scrollMargin?: number): IntersectionObserverHandle | null;
-export interface IntersectionObserverHandle {
-    observe(element: Element, setIsIntersecting: (isIntersecting: boolean) => void): () => void;
-}
+export declare const IntersectionObserverContext: import("react").Context<IntersectionObserverHandle>;
+/**
+ * Creates an IntersectionObserverHandle suitable for {@link IntersectionObserverContext}.
+ */
+export declare function useIntersectionObserverHandle(rootRef?: RefObject<HTMLElement | null>, rootMargin?: number, scrollMargin?: number): IntersectionObserverHandle;
+/**
+ * Returns whether the referenced element is currently intersecting.
+ */
 export declare function useIsIntersecting(elementRef: RefObject<Element | null>): boolean;
-export declare function useIsIntersectingListener(elementRef: RefObject<Element | null>, onChange: (isIntersecting: boolean) => void): void;

package/components/global/intersection-observer-context.js

@@ -1,5 +1,13 @@
 import { createContext, use, useEffect, useState } from 'react';
 /**
+ * @internal
+ */
+const noopIntersectionObserverHandle = {
+    observe: () => () => { },
+};
+/**
+ * Multiple components can share a single `IntersectionObserver` instance through this context.
+ *
  * Usage:
  *
  * ```tsx
@@ -10,23 +18,28 @@ import { createContext, use, useEffect, useState } from 'react';
  * function YourComponent() {
  *   // Contains the current isIntersecting value
  *   const isIntersecting = useIsIntersecting(elementRef);
- *   // Or, to get updates instead:
- *   useIsIntersectingListener(elementRef, newIsIntersecting => {
- *     // ...
+ *
+ *   // Or, to manually work with the IntersectionObserverHandle:
+ *   const handle = use(IntersectionObserverContext);
+ *   useEffect(() => {
+ *     return handle.observe(elementRef.current, isIntersecting => { ... })
  *   })
  * }
  * ```
  */
-export const IntersectionObserverContext = createContext(null);
+export const IntersectionObserverContext = createContext(noopIntersectionObserverHandle);
+/**
+ * Creates an IntersectionObserverHandle suitable for {@link IntersectionObserverContext}.
+ */
 export function useIntersectionObserverHandle(rootRef, rootMargin, scrollMargin) {
-    const [handle, setHandle] = useState(null);
+    const [handle, setHandle] = useState(noopIntersectionObserverHandle);
     useEffect(() => {
         const root = rootRef?.current;
-        const elementToOnChange = new Map();
+        const callbacksByElement = new Map();
         const observer = new IntersectionObserver(entries => {
             for (const entry of entries) {
-                const onChange = elementToOnChange.get(entry.target);
-                onChange?.(entry.isIntersecting);
+                const callbacks = callbacksByElement.get(entry.target);
+                callbacks?.forEach(cb => cb(entry.isIntersecting));
             }
         }, {
             root,
@@ -35,38 +48,44 @@ export function useIntersectionObserverHandle(rootRef, rootMargin, scrollMargin)
         });
         setHandle({
             observe(element, onChange) {
-                elementToOnChange.set(element, onChange);
-                observer.observe(element);
+                if (!callbacksByElement.has(element)) {
+                    callbacksByElement.set(element, []);
+                    observer.observe(element);
+                }
+                callbacksByElement.get(element).push(onChange);
                 return () => {
-                    elementToOnChange.delete(element);
-                    observer.unobserve(element);
+                    const callbacks = callbacksByElement.get(element);
+                    if (!callbacks)
+                        return;
+                    const index = callbacks.indexOf(onChange);
+                    if (index !== -1) {
+                        callbacks.splice(index, 1);
+                    }
+                    if (!callbacks.length) {
+                        callbacksByElement.delete(element);
+                        observer.unobserve(element);
+                    }
                 };
             },
         });
         return () => {
             observer.disconnect();
-            setHandle(null);
+            setHandle(noopIntersectionObserverHandle);
         };
     }, [rootRef, rootMargin, scrollMargin]);
     return handle;
 }
+/**
+ * Returns whether the referenced element is currently intersecting.
+ */
 export function useIsIntersecting(elementRef) {
     const handle = use(IntersectionObserverContext);
     const [isIntersecting, setIsIntersecting] = useState(false);
     useEffect(() => {
         const element = elementRef.current;
-        if (!element || !handle)
+        if (!element)
             return;
         return handle.observe(element, setIsIntersecting);
-    }, [handle, elementRef, setIsIntersecting]);
+    }, [handle, elementRef]);
     return isIntersecting;
 }
-export function useIsIntersectingListener(elementRef, onChange) {
-    const handle = use(IntersectionObserverContext);
-    useEffect(() => {
-        const element = elementRef.current;
-        if (!element || !handle)
-            return;
-        return handle.observe(element, onChange);
-    }, [handle, elementRef, onChange]);
-}

package/components/global/is-within-interactive-element.d.ts

@@ -0,0 +1,6 @@
+/**
+ * If this function returns `false`, the event may be interpreted as a click
+ * or tap on a "empty space" rather than on an interactive element such as
+ * a button or a link.
+ */
+export declare function isWithinInteractiveElement(target: EventTarget | null): boolean;

package/components/global/is-within-interactive-element.js

@@ -0,0 +1,26 @@
+const interactiveSelector = [
+    'a',
+    'button',
+    'details',
+    'input',
+    'label',
+    'option',
+    'select',
+    'summary',
+    'textarea',
+    '[contenteditable]',
+    '[role="button"]',
+    '[role="checkbox"]',
+    '[role="link"]',
+    '[role="radio"]',
+    '[role="switch"]',
+    '[role="tab"]',
+].join();
+/**
+ * If this function returns `false`, the event may be interpreted as a click
+ * or tap on a "empty space" rather than on an interactive element such as
+ * a button or a link.
+ */
+export function isWithinInteractiveElement(target) {
+    return target instanceof Element && target.closest(interactiveSelector) != null;
+}

package/components/global/is-within-navigable-element.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns whether the event target is within an element that is expected to
+ * handle keyboard navigation itself, so container-level keyboard shortcuts
+ * should generally be ignored.
+ */
+export declare function isWithinNavigableElement(target: EventTarget | null): boolean;

package/components/global/is-within-navigable-element.js

@@ -0,0 +1,27 @@
+const navigableSelector = [
+    'input:not([type="button"]):not([type="checkbox"]):not([type="color"]):not([type="file"]):not([type="hidden"]):not([type="image"]):not([type="reset"]):not([type="submit"])',
+    'textarea',
+    'select',
+    '[contenteditable]',
+    '[role="combobox"]',
+    '[role="grid"]',
+    '[role="listbox"]',
+    '[role="menu"]',
+    '[role="menubar"]',
+    '[role="radiogroup"]',
+    '[role="searchbox"]',
+    '[role="slider"]',
+    '[role="spinbutton"]',
+    '[role="tablist"]',
+    '[role="textbox"]',
+    '[role="tree"]',
+    '[role="treegrid"]',
+].join();
+/**
+ * Returns whether the event target is within an element that is expected to
+ * handle keyboard navigation itself, so container-level keyboard shortcuts
+ * should generally be ignored.
+ */
+export function isWithinNavigableElement(target) {
+    return target instanceof Element && target.closest(navigableSelector) != null;
+}

package/components/global/parse-css-duration.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Parses a CSS duration string (e.g., "500ms", "2s") and returns the duration in milliseconds.
+ * Returns the `defaultVal` if the input string is not a valid CSS duration.
+ */
+export declare function parseCssDuration(duration: string, defaultVal?: number): number;

package/components/global/parse-css-duration.js

@@ -0,0 +1,13 @@
+/**
+ * Parses a CSS duration string (e.g., "500ms", "2s") and returns the duration in milliseconds.
+ * Returns the `defaultVal` if the input string is not a valid CSS duration.
+ */
+export function parseCssDuration(duration, defaultVal = 0) {
+    const match = duration.match(/(\d+(\.\d+)?)(s|ms)/);
+    if (!match)
+        return defaultVal;
+    const value = parseFloat(match[1]);
+    const unit = match[3];
+    // eslint-disable-next-line no-magic-numbers
+    return unit === 's' ? value * 1000 : value;
+}

package/components/global/schedule-with-cleanup.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Schedules a timeout and returns a function that cancels it.
+ *
+ * Useful from React effects.
+ */
+export declare function setTimeoutWithCleanup(callback: () => void, delay?: number): () => void;
+/**
+ * Schedules an animation frame and returns a function that cancels it.
+ *
+ * Useful from React effects.
+ */
+export declare function requestAnimationFrameWithCleanup(callback: () => void): () => void;

package/components/global/schedule-with-cleanup.js

@@ -0,0 +1,34 @@
+/**
+ * Schedules a timeout and returns a function that cancels it.
+ *
+ * Useful from React effects.
+ */
+export function setTimeoutWithCleanup(callback, delay = 0) {
+    let timerId = window.setTimeout(() => {
+        callback();
+        timerId = null;
+    }, delay);
+    return () => {
+        if (timerId != null) {
+            window.clearTimeout(timerId);
+            timerId = null;
+        }
+    };
+}
+/**
+ * Schedules an animation frame and returns a function that cancels it.
+ *
+ * Useful from React effects.
+ */
+export function requestAnimationFrameWithCleanup(callback) {
+    let rafId = requestAnimationFrame(() => {
+        callback();
+        rafId = null;
+    });
+    return () => {
+        if (rafId != null) {
+            cancelAnimationFrame(rafId);
+            rafId = null;
+        }
+    };
+}

package/components/global/table-selection.js

@@ -15,7 +15,7 @@ export default class TableSelection {
             return item.id;
         }
         // If there's no id provided on item and no getKey supplied, fail fast with a clear message
-        throw new Error('Selection: getKey is required when items have no "id" property');
+        throw new Error('TableSelection: getKey is required when items have no "id" property');
     }, getChildren = () => [], isItemSelectable = () => true, } = {}) {
         this._rawData = data;
         this._getChildren = getChildren;

package/components/input/input.d.ts

@@ -69,7 +69,7 @@ export declare class Input extends PureComponent<InputProps> {
     stretch(el: HTMLElement | null | undefined): void;
     adapt(): void;
     inputRef: (el: HTMLInputElement | HTMLTextAreaElement | null) => void;
-    composedInputRef: import("memoize-one").MemoizedFn<(...refs: (Ref<HTMLInputElement | HTMLTextAreaElement> | undefined)[]) => (value: T | null) => void>;
+    composedInputRef: import("memoize-one").MemoizedFn<(...refs: (Ref<HTMLInputElement | HTMLTextAreaElement> | undefined)[]) => (value: T | null) => () => void>;
     clear: (e: React.MouseEvent<HTMLButtonElement>) => void;
     handleInputChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
     handleTextareaChange: (e: React.ChangeEvent<HTMLTextAreaElement>) => void;

package/components/legacy-table/row.d.ts

@@ -55,7 +55,7 @@ export default class Row<T extends object> extends PureComponent<RowProps<T>> {
     onDoubleClick: () => void;
     row?: HTMLElement | null;
     rowRef: (el: HTMLElement | null) => void;
-    composedRowRef: import("memoize-one").MemoizedFn<(...refs: (React.Ref<HTMLElement> | undefined)[]) => (value: T_1 | null) => void>;
+    composedRowRef: import("memoize-one").MemoizedFn<(...refs: (React.Ref<HTMLElement> | undefined)[]) => (value: T_1 | null) => () => void>;
     render(): React.JSX.Element;
 }
 export type RowAttrs<T extends object> = React.JSX.LibraryManagedAttributes<typeof Row, RowProps<T>>;

package/components/popup/popup.d.ts

@@ -45,6 +45,8 @@ export interface BasePopupProps {
     onMouseUp?: ((e: React.MouseEvent<HTMLElement>) => void) | undefined;
     onMouseOver?: ((e: React.SyntheticEvent<HTMLElement>) => void) | undefined;
     onMouseOut?: ((e: React.SyntheticEvent<HTMLElement>) => void) | undefined;
+    onMouseEnter?: ((e: React.MouseEvent<HTMLElement>) => void) | undefined;
+    onMouseLeave?: ((e: React.MouseEvent<HTMLElement>) => void) | undefined;
     onContextMenu?: ((e: React.MouseEvent<HTMLElement>) => void) | undefined;
     onDirectionChange?: ((direction: Directions) => void) | null | undefined;
     onShow?: (() => void) | null | undefined;

package/components/popup/popup.js

@@ -282,7 +282,7 @@ export default class Popup extends PureComponent {
         esc: this._onEscPress,
     };
     render() {
-        const { className, style, hidden, attached, keepMounted, client, onMouseDown, onMouseUp, onMouseOver, onMouseOut, onContextMenu, 'data-test': dataTest, largeBorderRadius, } = this.props;
+        const { className, style, hidden, attached, keepMounted, client, onMouseDown, onMouseUp, onMouseOver, onMouseOut, onMouseEnter, onMouseLeave, onContextMenu, 'data-test': dataTest, largeBorderRadius, } = this.props;
         const showing = this.state.display === Display.SHOWING;
         const direction = (this.state.direction || '').toLowerCase().replace(/[_]/g, '-');
         return (<ThemeContext.Consumer>
@@ -305,7 +305,7 @@ export default class Popup extends PureComponent {
 
                       {client !== false &&
                                 (keepMounted || !hidden) &&
-                                createPortal(<PopupTarget id={this.uid} ref={this.containerRef} onMouseOver={onMouseOver} onFocus={onMouseOver} onMouseOut={onMouseOut} onBlur={onMouseOut} onContextMenu={onContextMenu}>
+                                createPortal(<PopupTarget id={this.uid} ref={this.containerRef} onMouseOver={onMouseOver} onFocus={onMouseOver} onMouseOut={onMouseOut} onBlur={onMouseOut} onMouseEnter={onMouseEnter} onMouseLeave={onMouseLeave} onContextMenu={onContextMenu}>
                             <div data-test={dataTests('ring-popup', dataTest)} data-test-shown={!hidden && !showing} data-test-direction={direction} ref={this.popupRef} className={classes} style={style} onMouseDown={onMouseDown} onMouseUp={onMouseUp} 
                                 // mouse handlers are used to track clicking on inner elements
                                 role='presentation'>

package/components/select/select-popup.d.ts

@@ -127,7 +127,7 @@ export default class SelectPopup<T = unknown> extends PureComponent<SelectPopupP
     list?: List<T> | null;
     listRef: (el: List<T> | null) => void;
     filterRef: (el: HTMLInputElement | null) => void;
-    composedFilterRef: import("memoize-one").MemoizedFn<(...refs: (Ref<HTMLInputElement> | undefined)[]) => (value: T_1 | null) => void>;
+    composedFilterRef: import("memoize-one").MemoizedFn<(...refs: (Ref<HTMLInputElement> | undefined)[]) => (value: T_1 | null) => () => void>;
     shortcutsScope: string;
     shortcutsMap: {
         tab: (event: Event) => void;

package/components/select/select.d.ts

@@ -264,7 +264,7 @@ export default class Select<T = unknown> extends Component<SelectProps<T>, Selec
     private _getAvatar;
     filter?: HTMLInputElement | null;
     filterRef: (el: HTMLInputElement | null) => void;
-    composedFilterRef: import("memoize-one").MemoizedFn<(...refs: (Ref<HTMLInputElement> | undefined)[]) => (value: T_1 | null) => void>;
+    composedFilterRef: import("memoize-one").MemoizedFn<(...refs: (Ref<HTMLInputElement> | undefined)[]) => (value: T_1 | null) => () => void>;
     getShortcutsMap(): {
         enter: () => true | undefined;
         esc: (event: KeyboardEvent) => boolean | undefined;

package/components/table/default-item-renderer.d.ts

@@ -5,13 +5,10 @@ export interface DefaultItemRendererProps {
      */
     index: number;
     /**
-     * If true, the row will be focusable with up/down arrow keys.
+     * If `true`, the row will be focusable with up/down arrow keys.
      * Focus is implemented using the
      * ["roving tabindex"](https://developer.mozilla.org/en-US/docs/Web/Accessibility/Guides/Keyboard-navigable_JavaScript_widgets#technique_1_roving_tabindex)
      * technique, that is, only the focused row has `tabIndex={0}`.
-     *
-     * To focus the row on click or other user interaction, add e.g. `onClick()`
-     * and invoke `focusRow(e.currentTarget)` imported from `table-row-focus.ts`.
      */
     keyboardFocusable?: boolean;
     /**
@@ -20,17 +17,33 @@ export interface DefaultItemRendererProps {
      */
     clickable?: boolean;
     /**
-     * If true, the row is highlighted as selected, that is, with the
-     * a different background color.
+     * If `true`, the row is highlighted as selected with a different background color.
      */
     selected?: boolean;
     /**
-     * A level of a nested item. Results in an indent for columns with `indent: true`.
-     * 0, negative values, and an unset value mean no indent.
+     * The nesting level of an item. Applies an indent for columns with
+     * `Column.indent` set to `true`. `0`, negative values, and an unset value
+     * mean no indent.
      */
     level?: number;
+    /**
+     * When set to `true`, does not control item virtualization.
+     * Useful when you include `DefaultItemRenderer` as a part of a custom row renderer,
+     * and track the visibility yourself.
+     */
+    noItemVirtualization?: boolean;
 }
 /**
- * @see TableProps.renderItem
+ * Standard component for rendering a table row.
+ *
+ * Renders an item using the table's column definitions and lets you
+ * configure item-scoped behavior such as selection, keyboard navigation,
+ * event handlers, `className`, and `ref`.
+ *
+ * Note that row-level click and keyboard handlers are not discoverable
+ * by assistive technologies. Make sure that any functionality relying on
+ * them (such as selection or expand/collapse) is also available through
+ * accessible controls, such as checkboxes or buttons with accessible
+ * labels.
  */
-export declare function DefaultItemRenderer<T>({ index, keyboardFocusable, clickable, selected, level, ref: userRef, className, ...restProps }: DefaultItemRendererProps & ComponentPropsWithRef<'tr'>): import("react").JSX.Element | null;
+export declare function DefaultItemRenderer<T>({ index, keyboardFocusable, clickable, selected, level, noItemVirtualization, ref: userRef, className, ...restProps }: DefaultItemRendererProps & ComponentPropsWithRef<'tr'>): import("react").JSX.Element | null;

package/components/table/default-item-renderer.js

@@ -1,40 +1,61 @@
-import { use, useRef } from 'react';
+import { use, useCallback, useRef } from 'react';
 import classNames from 'classnames';
-import { mergeRefs } from 'react-merge-refs';
-import { CollapseItemIntoSpacerContext, TablePropsContext } from './table-const';
-import { useIsIntersectingListener } from '../global/intersection-observer-context';
+import { ColumnAnimationContext, TablePropsContext } from './table-const';
+import { useComposedRef } from '../global/compose-refs';
+import { useItemVirtualization } from './item-virtualization';
 import { TableCell, TableRow } from './table-primitives';
 import styles from './table.css';
-const INDENT_SIZE = 24;
 /**
- * @see TableProps.renderItem
+ * Standard component for rendering a table row.
+ *
+ * Renders an item using the table's column definitions and lets you
+ * configure item-scoped behavior such as selection, keyboard navigation,
+ * event handlers, `className`, and `ref`.
+ *
+ * Note that row-level click and keyboard handlers are not discoverable
+ * by assistive technologies. Make sure that any functionality relying on
+ * them (such as selection or expand/collapse) is also available through
+ * accessible controls, such as checkboxes or buttons with accessible
+ * labels.
  */
-export function DefaultItemRenderer({ index, keyboardFocusable, clickable, selected, level, ref: userRef, className, ...restProps }) {
+export function DefaultItemRenderer({ index, keyboardFocusable, clickable, selected, level, noItemVirtualization, ref: userRef, className, ...restProps }) {
     const localRef = useRef(null);
-    const collapseItemIntoSpacer = use(CollapseItemIntoSpacerContext);
-    useIsIntersectingListener(localRef, isIntersecting => {
-        if (localRef.current && !isIntersecting) {
-            collapseItemIntoSpacer(localRef.current.getBoundingClientRect().height);
-        }
+    const composedRef = useComposedRef(userRef, localRef);
+    useItemVirtualization({
+        index,
+        refs: localRef,
+        onIntersectionChange: useCallback(([isIntersecting], _i, [element]) => isIntersecting === false &&
+            !noItemVirtualization &&
+            element?.isConnected &&
+            !element.contains(document.activeElement) &&
+            !element.previousElementSibling?.contains(document.activeElement) &&
+            !element.nextElementSibling?.contains(document.activeElement)
+            ? element.getBoundingClientRect().height
+            : undefined, [noItemVirtualization]),
     });
     const tableProps = use(TablePropsContext);
     if (!tableProps) {
         return null;
     }
+    const animatedColumn = use(ColumnAnimationContext);
     const { data, columns } = tableProps;
     const item = data[index];
-    return (<TableRow ref={mergeRefs([userRef, localRef])} keyboardFocusable={keyboardFocusable} className={classNames(className, clickable && styles.clickableRow, selected && styles.selectedRow)} {...restProps}>
-      {columns.map((column, columnIndex) => (<TableCell key={column.key} className={column.tdClassName?.(item, index, data)} style={column.indent && level != null && level > 0 ? { paddingInlineStart: `${level * INDENT_SIZE}px` } : undefined}>
-          {column.renderCell?.(item, index, data) ?? getDefaultCellValue(item, columnIndex)}
-        </TableCell>))}
+    const indentSize = 24;
+    return (<TableRow ref={composedRef} keyboardFocusable={keyboardFocusable} className={classNames(className, clickable && styles.clickableRow, selected && styles.selectedRow)} {...restProps}>
+      {columns.map((column, columnIndex) => {
+            const { key, tdClassName, indent } = column;
+            return (<TableCell key={key} className={classNames(columnIndex === animatedColumn?.columnIndex && animatedColumn.cellClassName, typeof tdClassName === 'function' ? tdClassName(item, index, data) : tdClassName)} style={indent && level != null && level > 0 ? { paddingInlineStart: `${level * indentSize}px` } : undefined}>
+            {column.renderCell?.(item, index, data) ?? getDefaultCellValue(item, columnIndex, key)}
+          </TableCell>);
+        })}
     </TableRow>);
 }
-function getDefaultCellValue(item, columnIndex) {
+function getDefaultCellValue(item, columnIndex, columnKey) {
     if (Array.isArray(item)) {
-        return String(item[columnIndex] ?? '');
+        return String(item[columnIndex]);
     }
     if (item !== null && typeof item === 'object') {
-        return String(Object.values(item)[columnIndex] ?? '');
+        return String(item[String(columnKey)]);
     }
     if (columnIndex === 0) {
         return String(item);

package/components/table/internal/column-animation.d.ts

@@ -0,0 +1,16 @@
+import { type RefObject } from 'react';
+import type { Column } from '../table-props';
+import type { ColumnAnimation } from '../table-const';
+export interface ReorderSpec {
+    fromIndex: number;
+    insertionIndex: number;
+}
+export type ExpectColumnReorder = (reorderSpec: ReorderSpec) => void;
+export declare function useColumnAnimation<T>({ disabled, tableRef, columns, }: {
+    disabled: boolean | undefined;
+    tableRef: RefObject<HTMLTableElement | null>;
+    columns: readonly Column<T>[];
+}): {
+    columnAnimation: ColumnAnimation | null;
+    expectColumnReorder: ExpectColumnReorder;
+};

package/components/table/internal/column-animation.js

@@ -0,0 +1,45 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { parseCssDuration } from '../../global/parse-css-duration';
+import { requestAnimationFrameWithCleanup, setTimeoutWithCleanup } from '../../global/schedule-with-cleanup';
+import styles from '../table.css';
+const reorderExpectationTimeout = 1000;
+export function useColumnAnimation({ disabled, tableRef, columns, }) {
+    const [columnAnimation, setColumnAnimation] = useState(null);
+    const pendingColumnReorder = useRef(null);
+    const expectColumnReorder = useCallback((reorderSpec) => {
+        if (disabled)
+            return;
+        const timerId = window.setTimeout(() => {
+            pendingColumnReorder.current = null;
+        }, reorderExpectationTimeout);
+        pendingColumnReorder.current = { ...reorderSpec, timerId, columns };
+    }, [disabled, columns]);
+    useEffect(() => {
+        return () => {
+            if (pendingColumnReorder.current) {
+                window.clearTimeout(pendingColumnReorder.current.timerId);
+                pendingColumnReorder.current = null;
+            }
+        };
+    }, []);
+    useEffect(() => {
+        const table = tableRef.current;
+        if (!table || !pendingColumnReorder.current || columns === pendingColumnReorder.current.columns)
+            return;
+        const { fromIndex, insertionIndex } = pendingColumnReorder.current;
+        pendingColumnReorder.current = null;
+        const columnIndex = fromIndex < insertionIndex ? insertionIndex - 1 : insertionIndex;
+        return requestAnimationFrameWithCleanup(() => setColumnAnimation(prev => prev == null ? { columnIndex, phase: 'initial', cellClassName: styles.animatedColumnInitial } : prev));
+    }, [columns, tableRef]);
+    useEffect(() => {
+        if (columnAnimation?.phase === 'initial') {
+            return requestAnimationFrameWithCleanup(() => setColumnAnimation(prev => prev === columnAnimation ? { ...prev, phase: 'fade-out', cellClassName: styles.animatedColumnFadeOut } : prev));
+        }
+        if (columnAnimation?.phase === 'fade-out') {
+            const fadeOutMs = parseCssDuration(window.getComputedStyle(tableRef.current).getPropertyValue('--animated-column-fade-out-duration'));
+            return setTimeoutWithCleanup(() => setColumnAnimation(prev => (prev === columnAnimation ? null : prev)), fadeOutMs);
+        }
+        return undefined;
+    }, [columnAnimation, tableRef]);
+    return { columnAnimation, expectColumnReorder };
+}

package/components/table/internal/table-header.d.ts

@@ -0,0 +1,4 @@
+import { type ExpectColumnReorder } from './column-animation';
+export declare function TableHeader<T>({ expectColumnReorder }: {
+    expectColumnReorder: ExpectColumnReorder;
+}): import("react").JSX.Element | null;