@wallarm-org/design-system 0.38.2 → 0.39.0

package/dist/components/Table/Table.js

@@ -1,27 +1,33 @@
-import { jsx } from "react/jsx-runtime";
+import { jsx, jsxs } from "react/jsx-runtime";
 import { TestIdProvider } from "../../utils/testId.js";
 import { TableProvider } from "./TableContext/index.js";
+import { TableImperativeBridge } from "./TableImperativeBridge.js";
 import { TableInner } from "./TableInner/index.js";
 const Table = (props)=>{
-    const { data, isLoading = false, children, className, 'aria-label': ariaLabel, 'data-testid': testId, ...providerProps } = props;
+    const { data, isLoading = false, children, className, 'aria-label': ariaLabel, 'data-testid': testId, ref, ...providerProps } = props;
     const isEmpty = 0 === data.length && !isLoading;
     const showSettings = !!props.onColumnVisibilityChange || !!props.onColumnOrderChange;
-    return /*#__PURE__*/ jsx(TableProvider, {
+    return /*#__PURE__*/ jsxs(TableProvider, {
         data: data,
         isLoading: isLoading,
         ...providerProps,
-        children: /*#__PURE__*/ jsx(TestIdProvider, {
-            value: testId,
-            children: /*#__PURE__*/ jsx(TableInner, {
-                isEmpty: isEmpty,
-                virtualized: props.virtualized,
-                showSettings: showSettings,
-                ariaLabel: ariaLabel,
-                className: className,
-                "data-testid": testId,
-                children: children
+        children: [
+            ref ? /*#__PURE__*/ jsx(TableImperativeBridge, {
+                handleRef: ref
+            }) : null,
+            /*#__PURE__*/ jsx(TestIdProvider, {
+                value: testId,
+                children: /*#__PURE__*/ jsx(TableInner, {
+                    isEmpty: isEmpty,
+                    virtualized: props.virtualized,
+                    showSettings: showSettings,
+                    ariaLabel: ariaLabel,
+                    className: className,
+                    "data-testid": testId,
+                    children: children
+                })
             })
-        })
+        ]
     });
 };
 Table.displayName = 'Table';

package/dist/components/Table/TableBody/TableBody.js

@@ -7,7 +7,7 @@ import { TableRow } from "../TableRow.js";
 import { TableBodyVirtualizedContainer } from "./TableBodyVirtualizedContainer.js";
 import { TableBodyVirtualizedWindow } from "./TableBodyVirtualizedWindow.js";
 const TableBody = ()=>{
-    const { table, isLoading, virtualized } = useTableContext();
+    const { table, isLoading, virtualized, tbodyRef, virtualizerRef } = useTableContext();
     const testId = useTestId('body');
     const rows = table.getRowModel().rows;
     const hasData = rows.length > 0;
@@ -15,7 +15,9 @@ const TableBody = ()=>{
         if ('window' === virtualized) return /*#__PURE__*/ jsx(TableBodyVirtualizedWindow, {});
         return /*#__PURE__*/ jsx(TableBodyVirtualizedContainer, {});
     }
+    virtualizerRef.current = null;
     return /*#__PURE__*/ jsxs(TBody, {
+        ref: tbodyRef,
         "data-testid": testId,
         children: [
             rows.map((row)=>/*#__PURE__*/ jsx(TableRow, {

package/dist/components/Table/TableBody/TableBodyVirtualizedContainer.js

@@ -1,5 +1,5 @@
 import { jsx } from "react/jsx-runtime";
-import { useCallback, useRef } from "react";
+import { useCallback, useEffect } from "react";
 import { useVirtualizer } from "@tanstack/react-virtual";
 import { TABLE_VIRTUALIZATION_OVERSCAN } from "../lib/index.js";
 import { useTableContext } from "../TableContext/index.js";
@@ -7,15 +7,22 @@ import { TableBodyVirtualizedCore } from "./TableBodyVirtualizedCore.js";
 import { useResetVirtualizerOnDataChange } from "./useResetVirtualizerOnDataChange.js";
 import { useSmoothScrollOnSort } from "./useSmoothScrollOnSort.js";
 const TableBodyVirtualizedContainer = ()=>{
-    const { table, estimateRowHeight, overscan } = useTableContext();
-    const tbodyRef = useRef(null);
-    const getScrollElement = useCallback(()=>tbodyRef.current?.closest('[data-table-scroll-container]') ?? null, []);
+    const { table, estimateRowHeight, overscan, tbodyRef, virtualizerRef } = useTableContext();
+    const getScrollElement = useCallback(()=>tbodyRef.current?.closest('[data-table-scroll-container]') ?? null, [
+        tbodyRef
+    ]);
     const virtualizer = useVirtualizer({
         count: table.getRowModel().rows.length,
         getScrollElement,
         estimateSize: estimateRowHeight ?? (()=>40),
         overscan: overscan ?? TABLE_VIRTUALIZATION_OVERSCAN
     });
+    virtualizerRef.current = virtualizer;
+    useEffect(()=>()=>{
+            virtualizerRef.current = null;
+        }, [
+        virtualizerRef
+    ]);
     useResetVirtualizerOnDataChange(table, virtualizer);
     useSmoothScrollOnSort(table, getScrollElement);
     return /*#__PURE__*/ jsx(TableBodyVirtualizedCore, {

package/dist/components/Table/TableBody/TableBodyVirtualizedWindow.js

@@ -1,5 +1,5 @@
 import { jsx } from "react/jsx-runtime";
-import { useCallback, useRef } from "react";
+import { useCallback, useEffect } from "react";
 import { useWindowVirtualizer } from "@tanstack/react-virtual";
 import { TABLE_VIRTUALIZATION_OVERSCAN } from "../lib/index.js";
 import { useTableContext } from "../TableContext/index.js";
@@ -8,14 +8,19 @@ import { TableBodyVirtualizedCore } from "./TableBodyVirtualizedCore.js";
 import { useResetVirtualizerOnDataChange } from "./useResetVirtualizerOnDataChange.js";
 import { useSmoothScrollOnSort } from "./useSmoothScrollOnSort.js";
 const TableBodyVirtualizedWindow = ()=>{
-    const { table, estimateRowHeight, overscan } = useTableContext();
-    const tbodyRef = useRef(null);
+    const { table, estimateRowHeight, overscan, tbodyRef, virtualizerRef } = useTableContext();
     const virtualizer = useWindowVirtualizer({
         count: table.getRowModel().rows.length,
         estimateSize: estimateRowHeight ?? (()=>40),
         overscan: overscan ?? TABLE_VIRTUALIZATION_OVERSCAN,
         scrollMargin: tbodyRef.current ? getDocumentOffsetTop(tbodyRef.current) : 0
     });
+    virtualizerRef.current = virtualizer;
+    useEffect(()=>()=>{
+            virtualizerRef.current = null;
+        }, [
+        virtualizerRef
+    ]);
     useResetVirtualizerOnDataChange(table, virtualizer);
     const getScrollTarget = useCallback(()=>window, []);
     useSmoothScrollOnSort(table, getScrollTarget);

package/dist/components/Table/TableContext/TableProvider.js

@@ -183,6 +183,8 @@ const TableProvider = (props)=>{
     const lastSelectedRowIndexRef = useRef(null);
     const theadRef = useRef(null);
     const containerRef = useRef(null);
+    const tbodyRef = useRef(null);
+    const virtualizerRef = useRef(null);
     const contextValue = useMemo(()=>({
             table,
             isLoading,
@@ -208,6 +210,8 @@ const TableProvider = (props)=>{
             lastSelectedRowIndexRef,
             theadRef,
             containerRef,
+            tbodyRef,
+            virtualizerRef,
             onEndReached,
             onEndReachedThreshold,
             onMasterCellClick,

package/dist/components/Table/TableContext/types.d.ts

@@ -1,6 +1,13 @@
 import type { ReactNode, RefObject } from 'react';
 import type { Column, Row, Table as TanStackTable, VisibilityState } from '@tanstack/react-table';
+import type { Virtualizer } from '@tanstack/react-virtual';
 import type { TableProps, TableVirtualized } from '../types';
+/**
+ * Union covers both virtualizer flavors used by the Table (`useVirtualizer`
+ * with HTMLElement scroll container and `useWindowVirtualizer` with Window).
+ * Lives behind `TableHandle` — consumers never touch this directly.
+ */
+export type TableVirtualizerInstance = Virtualizer<Window, Element> | Virtualizer<HTMLElement, Element> | Virtualizer<Element, Element>;
 export interface TableContextValue<T> {
     table: TanStackTable<T>;
     isLoading: boolean;
@@ -26,6 +33,8 @@ export interface TableContextValue<T> {
     masterColumnId: string | null;
     theadRef: RefObject<HTMLTableSectionElement | null>;
     containerRef: RefObject<HTMLDivElement | null>;
+    tbodyRef: RefObject<HTMLTableSectionElement | null>;
+    virtualizerRef: RefObject<TableVirtualizerInstance | null>;
     onEndReached?: () => void;
     onEndReachedThreshold?: number;
     onMasterCellClick?: (rowId: string) => void;

package/dist/components/Table/TableImperativeBridge.d.ts

@@ -0,0 +1,15 @@
+import { type Ref } from 'react';
+import type { TableHandle } from './types';
+interface TableImperativeBridgeProps {
+    handleRef: Ref<TableHandle>;
+}
+/**
+ * Bridges the imperative ref forwarded to `<Table>` to context-backed
+ * refs (`virtualizerRef`, `tbodyRef`). Mounted inside `TableProvider` so
+ * it has access to the context; renders nothing.
+ */
+export declare const TableImperativeBridge: {
+    ({ handleRef }: TableImperativeBridgeProps): null;
+    displayName: string;
+};
+export {};

package/dist/components/Table/TableImperativeBridge.js

@@ -0,0 +1,48 @@
+import { useImperativeHandle } from "react";
+import { useTableContext } from "./TableContext/index.js";
+const resolveScrollIntoViewBlock = (align)=>{
+    switch(align){
+        case 'start':
+            return 'start';
+        case 'center':
+            return 'center';
+        case 'end':
+            return 'end';
+        default:
+            return 'nearest';
+    }
+};
+const TableImperativeBridge = ({ handleRef })=>{
+    const { table, virtualizerRef, tbodyRef } = useTableContext();
+    useImperativeHandle(handleRef, ()=>({
+            scrollToRow (id, opts = {}) {
+                const rows = table.getRowModel().rows;
+                const index = rows.findIndex((r)=>r.id === id);
+                if (index < 0) return false;
+                const virtualizer = virtualizerRef.current;
+                if (virtualizer) {
+                    virtualizer.scrollToIndex(index, {
+                        align: opts.align ?? 'auto',
+                        behavior: opts.behavior
+                    });
+                    return true;
+                }
+                const tbody = tbodyRef.current;
+                if (!tbody) return false;
+                const el = tbody.querySelector(`[data-row-id="${CSS.escape(id)}"]`);
+                if (!(el instanceof HTMLElement)) return false;
+                el.scrollIntoView({
+                    block: resolveScrollIntoViewBlock(opts.align),
+                    behavior: opts.behavior
+                });
+                return true;
+            }
+        }), [
+        table,
+        virtualizerRef,
+        tbodyRef
+    ]);
+    return null;
+};
+TableImperativeBridge.displayName = 'TableImperativeBridge';
+export { TableImperativeBridge };

package/dist/components/Table/TableRow.js

@@ -27,6 +27,7 @@ const TableRowInner = ({ row, ref, 'data-index': dataIndex })=>{
                 /*#__PURE__*/ jsxs(Tr, {
                     ref: ref,
                     "data-index": dataIndex,
+                    "data-row-id": row.id,
                     "data-testid": testId,
                     className: "group/row",
                     "data-selected": isSelected || void 0,
@@ -62,6 +63,7 @@ const TableRowInner = ({ row, ref, 'data-index': dataIndex })=>{
             /*#__PURE__*/ jsx(Tr, {
                 ref: ref,
                 "data-index": dataIndex,
+                "data-row-id": row.id,
                 "data-testid": testId,
                 className: "group/row",
                 "data-selected": isSelected || void 0,

package/dist/components/Table/index.d.ts

@@ -4,4 +4,4 @@ export { Table } from './Table';
 export { TableActionBar } from './TableActionBar';
 export { TableEmptyState } from './TableEmptyState';
 export { TableSettingsMenu } from './TableSettingsMenu';
-export type { TableAccessorColumnDef, TableCellContext, TableColumnBase, TableColumnDef, TableColumnMeta, TableColumnPinningState, TableColumnSizingState, TableDisplayColumnDef, TableExpandedState, TableGroupingState, TableOnChangeFn, TableProps, TableRow, TableRowSelectionState, TableSortingState, TableUpdater, TableVirtualized, TableVisibilityState, } from './types';
+export type { TableAccessorColumnDef, TableCellContext, TableColumnBase, TableColumnDef, TableColumnMeta, TableColumnPinningState, TableColumnSizingState, TableDisplayColumnDef, TableExpandedState, TableGroupingState, TableHandle, TableOnChangeFn, TableProps, TableRow, TableRowSelectionState, TableScrollToRowOptions, TableSortingState, TableUpdater, TableVirtualized, TableVisibilityState, } from './types';

package/dist/components/Table/types.d.ts

@@ -1,4 +1,4 @@
-import type { ReactNode } from 'react';
+import type { ReactNode, Ref } from 'react';
 import type { Row, RowData } from '@tanstack/react-table';
 import type { TestableProps } from '../../utils/testId';
 declare module '@tanstack/react-table' {
@@ -44,6 +44,29 @@ export type TableGroupingState = string[];
 export type TableVisibilityState = Record<string, boolean>;
 /** State updater — value or functional update */
 export type TableUpdater<T> = T | ((prev: T) => T);
+/** Options for the imperative `scrollToRow` method */
+export interface TableScrollToRowOptions {
+    /** Alignment within the viewport. Default: 'auto'. */
+    align?: 'start' | 'center' | 'end' | 'auto';
+    /** Scroll behavior. Default: 'auto'. */
+    behavior?: 'auto' | 'smooth';
+}
+/**
+ * Imperative handle exposed via `ref` on `<Table>`. The only supported way
+ * to programmatically scroll the table to a row that may be outside the
+ * currently rendered virtual window.
+ */
+export interface TableHandle {
+    /**
+     * Scrolls to the row with the given id.
+     *
+     * Returns `true` if the row was found in the current row model and a
+     * scroll was initiated. Returns `false` if the id is not in the current
+     * rows or the virtualizer has not yet mounted — the caller decides
+     * whether to load more pages or retry on the next frame.
+     */
+    scrollToRow(id: string, opts?: TableScrollToRowOptions): boolean;
+}
 /** onChange callback */
 export type TableOnChangeFn<T> = (updaterOrValue: TableUpdater<T>) => void;
 /** Public row interface — structural subset of TanStack Row<T> */
@@ -164,4 +187,6 @@ export interface TableProps<T> extends TestableProps {
     onMasterCellClick?: (rowId: string) => void;
     /** ID of the currently active (highlighted) row, or null. Controls row highlighting via data-preview-active attribute. */
     activeRowId?: string | null;
+    /** Imperative handle — exposes `scrollToRow(id, opts)`. See {@link TableHandle}. */
+    ref?: Ref<TableHandle>;
 }

package/dist/index.d.ts

@@ -56,7 +56,7 @@ export { Skeleton, type SkeletonProps } from './components/Skeleton';
 export { SplitButton, type SplitButtonProps } from './components/SplitButton';
 export { HStack, type HStackProps, Stack, type StackProps, VStack, type VStackProps, } from './components/Stack';
 export { Switch, SwitchControl, SwitchDescription, type SwitchDescriptionProps, SwitchLabel, type SwitchLabelProps, type SwitchProps, } from './components/Switch';
-export { createTableColumnHelper, Table, type TableAccessorColumnDef, TableActionBar, type TableCellContext, type TableColumnBase, type TableColumnDef, type TableColumnHelper, type TableColumnMeta, type TableColumnPinningState, type TableColumnSizingState, type TableDisplayColumnDef, TableEmptyState, type TableExpandedState, type TableGroupingState, type TableOnChangeFn, type TableProps, type TableRow, type TableRowSelectionState, TableSettingsMenu, type TableSortingState, type TableUpdater, type TableVisibilityState, } from './components/Table';
+export { createTableColumnHelper, Table, type TableAccessorColumnDef, TableActionBar, type TableCellContext, type TableColumnBase, type TableColumnDef, type TableColumnHelper, type TableColumnMeta, type TableColumnPinningState, type TableColumnSizingState, type TableDisplayColumnDef, TableEmptyState, type TableExpandedState, type TableGroupingState, type TableHandle, type TableOnChangeFn, type TableProps, type TableRow, type TableRowSelectionState, type TableScrollToRowOptions, TableSettingsMenu, type TableSortingState, type TableUpdater, type TableVisibilityState, } from './components/Table';
 export { Tabs, TabsButton, TabsContent, TabsLineActions, TabsList, TabsSeparator, TabsTrigger, } from './components/Tabs';
 export { Tag, TagClose, type TagProps } from './components/Tag';
 export { Text, type TextProps } from './components/Text';

package/dist/metadata/components.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.38.1",
-  "generatedAt": "2026-05-18T12:15:53.965Z",
+  "version": "0.38.2",
+  "generatedAt": "2026-05-18T13:33:44.697Z",
   "components": [
     {
       "name": "Accordion",
@@ -42632,6 +42632,10 @@
           "name": "WindowVirtualization",
           "code": "() => {\n  const largeData = useMemo(() => createLargeSecurityEvents(1000), []);\n  const [columnOrder, setColumnOrder] = useState<string[]>([]);\n  const [columnSizing, setColumnSizing] = useState<TableColumnSizingState>({});\n\n  return (\n    <Table\n      data={largeData}\n      columns={securityColumns}\n      getRowId={row => row.id}\n      virtualized='window'\n      columnOrder={columnOrder}\n      onColumnOrderChange={setColumnOrder}\n      columnSizing={columnSizing}\n      onColumnSizingChange={setColumnSizing}\n    />\n  );\n}"
         },
+        {
+          "name": "ScrollToRow",
+          "code": "() => {\n  const largeData = useMemo(() => createLargeSecurityEvents(1000), []);\n  const tableRef = useRef<TableHandle>(null);\n  const [lastResult, setLastResult] = useState<string | null>(null);\n\n  const scroll = (index: number, align: 'start' | 'center' | 'end' | 'auto' = 'center') => {\n    const row = largeData[index];\n    if (!row) return;\n    const ok = tableRef.current?.scrollToRow(row.id, { align, behavior: 'smooth' }) ?? false;\n    setLastResult(`scrollToRow(\"${row.id}\", { align: \"${align}\" }) → ${ok}`);\n  };\n\n  return (\n    <VStack gap='md'>\n      <HStack gap='sm'>\n        <Button onClick={() => scroll(0, 'start')}>Top</Button>\n        <Button onClick={() => scroll(499, 'center')}>Middle</Button>\n        <Button onClick={() => scroll(999, 'end')}>Bottom</Button>\n        <Button\n          variant='ghost'\n          onClick={() => {\n            const ok = tableRef.current?.scrollToRow('does-not-exist') ?? false;\n            setLastResult(`scrollToRow(\"does-not-exist\") → ${ok}`);\n          }}\n        >\n          Missing id (returns false)\n        </Button>\n      </HStack>\n      {lastResult && (\n        <Text size='sm' color='secondary'>\n          {lastResult}\n        </Text>\n      )}\n      <Table\n        ref={tableRef}\n        className='h-500'\n        data={largeData}\n        columns={securityColumns}\n        getRowId={row => row.id}\n        virtualized='container'\n      />\n    </VStack>\n  );\n}"
+        },
         {
           "name": "InfiniteScroll",
           "code": "() => {\n  const { data, isFetching, hasMore, totalItems, fetchNextPage } = useInfiniteData();\n\n  return (\n    <VStack gap={8}>\n      <Text size='sm' color='secondary'>\n        Loaded {data.length} of {totalItems} rows {isFetching && '— loading...'}\n        {!hasMore && ' — all loaded'}\n      </Text>\n      <Table\n        className='h-500'\n        data={data}\n        columns={securityColumns}\n        getRowId={row => row.id}\n        virtualized='container'\n        isLoading={isFetching}\n        onEndReached={fetchNextPage}\n        onEndReachedThreshold={200}\n      />\n    </VStack>\n  );\n}"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wallarm-org/design-system",
-  "version": "0.38.2",
+  "version": "0.39.0",
   "description": "Core design system library with React components and Storybook documentation",
   "publishConfig": {
     "access": "public",