@astryxdesign/core 0.1.4-canary.39ffd21 → 0.1.4-canary.3d64ef2

package/src/SelectableCard/SelectableCard.doc.mjs

@@ -34,7 +34,7 @@ export const docs = {
   ],
   theming: {
     container: true,
-    targets: [{className: 'astryx-selectable-card', visualProps: ['selected']}],
+    targets: [{className: 'astryx-selectable-card', visualProps: ['selected', 'variant']}],
   },
   playground: {
     defaults: {

package/src/SideNav/SideNav.doc.mjs

@@ -21,7 +21,7 @@ export const docs = {
     targets: [
       {className: 'astryx-side-nav', visualProps: ['mode']},
       {className: 'astryx-side-nav-heading'},
-      {className: 'astryx-side-nav-item'},
+      {className: 'astryx-side-nav-item', visualProps: ['size'], states: ['selected']},
       {className: 'astryx-side-nav-section'},
     ],
   },
@@ -102,6 +102,12 @@ export const docs = {
       description: 'Enables collapse behavior. true for uncontrolled with default toggle button, or an object for controlled mode and advanced config (defaultIsCollapsed, isCollapsed + onCollapsedChange, hasButton, buttonLabel).',
       default: 'false',
     },
+    {
+      name: 'resizable',
+      type: 'boolean | { defaultWidth?: number; minWidth?: number; maxWidth?: number; autoSaveId?: string; onWidthChange?: (width: number) => void }',
+      description: 'Enables a resize handle at the inline-end edge. true for defaults (260px initial, 180-480px range), or a ResizableConfig object (defaultWidth, minWidth, maxWidth, autoSaveId for localStorage persistence, onWidthChange). The handle is hidden while collapsed.',
+      default: 'false',
+    },
     {
       name: 'handleRef',
       type: 'Ref<SideNavImperativeCollapseHandle>',

package/src/SideNav/SideNav.test.tsx

@@ -162,6 +162,26 @@ describe('SideNav', () => {
       screen.getByRole('button', {name: 'Expand sidebar'}),
     ).toBeInTheDocument();
   });
+
+  it('does not render an empty footer container when collapsible.hasButton is false', () => {
+    render(
+      <SideNav data-testid="nav" collapsible={{hasButton: false}}>
+        Content
+      </SideNav>,
+    );
+
+    // The built-in collapse button is opted out (consumers render their own
+    // SideNavCollapseButton in the header), so it must not appear...
+    expect(
+      screen.queryByRole('button', {name: 'Collapse sidebar'}),
+    ).not.toBeInTheDocument();
+
+    // ...and no empty sticky-bottom container should be left behind. With no
+    // footer/footerIcons and no built-in button, the scrollable content region
+    // is the nav's only child.
+    const nav = screen.getByTestId('nav');
+    expect(nav.children).toHaveLength(1);
+  });
 });
 
 // =============================================================================

package/src/SideNav/SideNav.tsx

@@ -490,6 +490,10 @@ export function SideNav({
   // =========================================================================
   const hasStickyTop = !!(header || topContent);
   const hasStickyBottom = !!(footer || footerIcons);
+  // The built-in collapse button only renders when collapse is enabled and it
+  // hasn't been opted out via `collapsible.hasButton: false` (e.g. when the
+  // consumer places a SideNavCollapseButton in the header instead).
+  const showCollapseButton = isCollapsible && hasCollapseButton;
 
   // When resizable, override the nav width via inline style
   const resizableNavStyle: React.CSSProperties | undefined = isResizable
@@ -532,7 +536,7 @@ export function SideNav({
         )}>
         {children}
       </div>
-      {(hasStickyBottom || isCollapsible) && (
+      {(hasStickyBottom || showCollapseButton) && (
         <div
           {...stylex.props(
             styles.stickyBottom,
@@ -544,7 +548,7 @@ export function SideNav({
               styles.footerRow,
               collapsed && styles.footerRowCollapsed,
             )}>
-            {isCollapsible && hasCollapseButton && <SideNavCollapseButton />}
+            {showCollapseButton && <SideNavCollapseButton />}
             {footerIcons}
           </div>
         </div>

package/src/TabList/TabList.test.tsx

@@ -10,7 +10,7 @@
  */
 
 import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {render, screen, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {TabList} from './TabList';
 import {Tab} from './Tab';
@@ -702,3 +702,187 @@ describe('TabMenu', () => {
     expect(reportsItem).not.toHaveAttribute('aria-current');
   });
 });
+
+describe('TabMenu keyboard navigation (roving tabindex)', () => {
+  const menuOptions = [
+    {value: 'analytics', label: 'Analytics'},
+    {value: 'reports', label: 'Reports'},
+  ];
+
+  it('exposes the overflow menu as a single Tab stop (one item tabbable, rest -1)', async () => {
+    const user = userEvent.setup();
+    render(
+      <TabList value="home" onChange={() => {}}>
+        <Tab value="home" label="Home" />
+        <TabMenu label="More" options={menuOptions} />
+      </TabList>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /More/}));
+
+    const analytics = screen.getByRole('menuitem', {
+      name: 'Analytics',
+      hidden: true,
+    });
+    const reports = screen.getByRole('menuitem', {
+      name: 'Reports',
+      hidden: true,
+    });
+
+    // Exactly one menu item is in the Tab sequence; arrow keys reach the rest.
+    expect(analytics).toHaveAttribute('tabindex', '0');
+    expect(reports).toHaveAttribute('tabindex', '-1');
+
+    const tabbable = [analytics, reports].filter(
+      el => el.getAttribute('tabindex') === '0',
+    );
+    expect(tabbable).toHaveLength(1);
+  });
+
+  it('moves focus between items with ArrowDown and ArrowUp', async () => {
+    const user = userEvent.setup();
+    render(
+      <TabList value="home" onChange={() => {}}>
+        <Tab value="home" label="Home" />
+        <TabMenu label="More" options={menuOptions} />
+      </TabList>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /More/}));
+    const menu = screen.getByRole('menu', {hidden: true});
+    const analytics = screen.getByRole('menuitem', {
+      name: 'Analytics',
+      hidden: true,
+    });
+    const reports = screen.getByRole('menuitem', {
+      name: 'Reports',
+      hidden: true,
+    });
+
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    expect(analytics).toHaveFocus();
+
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    expect(reports).toHaveFocus();
+
+    fireEvent.keyDown(menu, {key: 'ArrowUp'});
+    expect(analytics).toHaveFocus();
+  });
+
+  it('moves the roving tab stop with arrow navigation', async () => {
+    const user = userEvent.setup();
+    render(
+      <TabList value="home" onChange={() => {}}>
+        <Tab value="home" label="Home" />
+        <TabMenu label="More" options={menuOptions} />
+      </TabList>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /More/}));
+    const menu = screen.getByRole('menu', {hidden: true});
+    const analytics = screen.getByRole('menuitem', {
+      name: 'Analytics',
+      hidden: true,
+    });
+    const reports = screen.getByRole('menuitem', {
+      name: 'Reports',
+      hidden: true,
+    });
+
+    fireEvent.keyDown(menu, {key: 'ArrowDown'}); // focus analytics
+    fireEvent.keyDown(menu, {key: 'ArrowDown'}); // focus reports
+
+    // The tab stop follows focus, so it is still a single stop after moving.
+    expect(reports).toHaveAttribute('tabindex', '0');
+    expect(analytics).toHaveAttribute('tabindex', '-1');
+  });
+
+  it('jumps to first and last item with Home and End', async () => {
+    const user = userEvent.setup();
+    const options = [
+      {value: 'analytics', label: 'Analytics'},
+      {value: 'reports', label: 'Reports'},
+      {value: 'exports', label: 'Exports'},
+    ];
+    render(
+      <TabList value="home" onChange={() => {}}>
+        <Tab value="home" label="Home" />
+        <TabMenu label="More" options={options} />
+      </TabList>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /More/}));
+    const menu = screen.getByRole('menu', {hidden: true});
+    const analytics = screen.getByRole('menuitem', {
+      name: 'Analytics',
+      hidden: true,
+    });
+    const exports = screen.getByRole('menuitem', {
+      name: 'Exports',
+      hidden: true,
+    });
+
+    fireEvent.keyDown(menu, {key: 'End'});
+    expect(exports).toHaveFocus();
+
+    fireEvent.keyDown(menu, {key: 'Home'});
+    expect(analytics).toHaveFocus();
+  });
+
+  it('selects an item with Enter and calls onChange', async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+    render(
+      <TabList value="home" onChange={handleChange}>
+        <Tab value="home" label="Home" />
+        <TabMenu label="More" options={menuOptions} />
+      </TabList>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /More/}));
+    const analytics = screen.getByRole('menuitem', {
+      name: 'Analytics',
+      hidden: true,
+    });
+    analytics.focus();
+    fireEvent.keyDown(analytics, {key: 'Enter'});
+
+    expect(handleChange).toHaveBeenCalledWith('analytics');
+  });
+
+  it('closes the menu when Tab is pressed inside it (APG menu-button)', async () => {
+    const user = userEvent.setup();
+    render(
+      <TabList value="home" onChange={() => {}}>
+        <Tab value="home" label="Home" />
+        <TabMenu label="More" options={menuOptions} />
+      </TabList>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /More/}));
+    const menu = screen.getByRole('menu', {hidden: true});
+
+    const hidePopover = vi.mocked(HTMLElement.prototype.hidePopover);
+    hidePopover.mockClear();
+    fireEvent.keyDown(menu, {key: 'Tab'});
+    expect(hidePopover).toHaveBeenCalled();
+  });
+
+  it('closes the menu when Escape is pressed', async () => {
+    const user = userEvent.setup();
+    render(
+      <TabList value="home" onChange={() => {}}>
+        <Tab value="home" label="Home" />
+        <TabMenu label="More" options={menuOptions} />
+      </TabList>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /More/}));
+    const menu = screen.getByRole('menu', {hidden: true});
+
+    const hidePopover = vi.mocked(HTMLElement.prototype.hidePopover);
+    hidePopover.mockClear();
+    fireEvent.keyDown(menu, {key: 'Escape'});
+    expect(hidePopover).toHaveBeenCalled();
+  });
+});

package/src/TabList/TabMenu.tsx

@@ -16,7 +16,7 @@
  * - /packages/cli/templates/blocks/components/TabList/ (showcase blocks)
  */
 
-import React, {useCallback, useId, type ReactNode} from 'react';
+import React, {useCallback, useId, useRef, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {Icon} from '../Icon';
 import {renderIconSlot, type IconType} from '../Icon';
@@ -262,6 +262,7 @@ export function TabMenu({
 }: TabMenuProps) {
   const tabListCtx = useTabListContext();
   const menuId = useId();
+  const buttonRef = useRef<HTMLButtonElement>(null);
 
   const popover = usePopover({
     hasLightDismiss: true,
@@ -270,20 +271,50 @@ export function TabMenu({
     // The popup's own role="menu" is the exposed semantics; a modal dialog
     // wrapper would announce an unnamed dialog around the menu.
     role: 'none',
+    // Return focus to the trigger when the menu closes (Escape, Tab, select,
+    // or light dismiss) so keyboard focus is never dropped to <body>.
+    onHide: useCallback(() => {
+      buttonRef.current?.focus();
+    }, []),
   });
 
-  const {listRef, handleKeyDown: handleListKeyDown} =
-    useListFocus<HTMLDivElement>({
-      onEscape: () => popover.hide(),
-    });
+  // The overflow menu is a composite widget: a single roving tab stop with
+  // arrow-key navigation between items, per the APG menu pattern. The hook owns
+  // item tabindex — items render tabIndex={-1} and exactly one is promoted to 0.
+  const {
+    listRef,
+    handleKeyDown: handleListKeyDown,
+    handleFocus,
+    focusFirst,
+  } = useListFocus<HTMLDivElement>({
+    hasRovingTabIndex: true,
+    onEscape: () => popover.hide(),
+  });
 
   const handleToggle = useCallback(() => {
     if (popover.isOpen) {
       popover.hide();
     } else {
       popover.show();
+      // Move focus into the menu on open so arrow navigation works and the
+      // roving tab stop lands on a real item (APG menu-button focus-on-open).
+      requestAnimationFrame(() => focusFirst());
     }
-  }, [popover]);
+  }, [popover, focusFirst]);
+
+  const handleMenuKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      // APG menu-button: Tab leaves the menu rather than walking its items.
+      // Close and let onHide return focus to the trigger, from which the
+      // browser's default Tab continues to the next element.
+      if (e.key === 'Tab') {
+        popover.hide();
+        return;
+      }
+      handleListKeyDown(e);
+    },
+    [handleListKeyDown, popover],
+  );
 
   const selectedOption = options.find(o => o.value === tabListCtx.value);
   const triggerLabel = selectedOption?.label ?? label;
@@ -299,7 +330,11 @@ export function TabMenu({
     [tabListCtx, popover],
   );
 
-  const setButtonRef = mergeRefs<HTMLButtonElement>(popover.triggerRef, ref);
+  const setButtonRef = mergeRefs<HTMLButtonElement>(
+    popover.triggerRef,
+    buttonRef,
+    ref,
+  );
 
   return (
     <>
@@ -357,7 +392,8 @@ export function TabMenu({
           id={menuId}
           role="menu"
           aria-label={label}
-          onKeyDown={handleListKeyDown}
+          onKeyDown={handleMenuKeyDown}
+          onFocus={handleFocus}
           {...mergeProps(
             themeProps('tab-menu-dropdown'),
             stylex.props(styles.dropdown),
@@ -371,7 +407,7 @@ export function TabMenu({
               <div
                 key={option.value}
                 role="menuitem"
-                tabIndex={0}
+                tabIndex={-1}
                 aria-current={isSelected ? 'true' : undefined}
                 onClick={() => handleSelect(option.value)}
                 onKeyDown={e => {

package/src/Table/BaseTable.tsx

@@ -279,11 +279,18 @@ function areRowPropsEqual<T extends Record<string, unknown>>(
     return true;
   }
 
-  // Different object reference - compare values
+  // Different object reference - compare values. This is intentionally a
+  // one-level shallow compare: nested fields rely on reference identity.
   const prevItem = prevProps.item;
   const nextItem = nextProps.item;
   const keys = Object.keys(nextItem);
 
+  // A key deleted from nextItem would never be visited by the loop below,
+  // and the row would keep rendering the removed field's stale value.
+  if (Object.keys(prevItem).length !== keys.length) {
+    return false;
+  }
+
   for (const key of keys) {
     if (prevItem[key] !== nextItem[key]) {
       return false;
@@ -365,9 +372,13 @@ function BaseTableInner<T extends Record<string, unknown>>({
   const headerCells = resolvedColumns.map((col, columnIndex) => {
     const headerContent = col.header ?? col.key;
 
-    // Build initial htmlProps with column alignment if specified
+    // Build initial htmlProps with column alignment if specified.
+    // `scope: 'col'` is the default so every column header associates its
+    // data cells with the correct column for screen readers; a plugin's
+    // transformHeaderCell can override it via htmlProps.scope.
     const initialHeaderHtmlProps: Record<string, unknown> = {
       'data-column-key': col.key,
+      scope: 'col',
     };
     if (col.align) {
       initialHeaderHtmlProps.style = {textAlign: col.align};

package/src/Table/Table.test.tsx

@@ -229,6 +229,34 @@ describe('BaseTable', () => {
     expect(headers[2]).toHaveTextContent('Email');
   });
 
+  it('renders every column header with scope="col"', () => {
+    render(<BaseTable data={users} columns={columns} />);
+    const headers = screen.getAllByRole('columnheader');
+    expect(headers).toHaveLength(3);
+    for (const header of headers) {
+      expect(header).toHaveAttribute('scope', 'col');
+    }
+  });
+
+  it('lets a consumer override scope via header html props', () => {
+    // A `<th scope="row">` maps to the `rowheader` role, so query the DOM
+    // directly to assert the attribute regardless of the resolved ARIA role.
+    const plugin: TablePlugin<User> = {
+      transformHeaderCell: (props, column) =>
+        column.key === 'name'
+          ? {...props, htmlProps: {...props.htmlProps, scope: 'row'}}
+          : props,
+    };
+    const {container} = render(
+      <BaseTable data={users} columns={columns} plugins={[plugin]} />,
+    );
+    const headerCells = container.querySelectorAll('thead th');
+    // columns fixture order: name, age, email — plugin overrides name → 'row'
+    expect(headerCells[0]).toHaveAttribute('scope', 'row');
+    expect(headerCells[1]).toHaveAttribute('scope', 'col');
+    expect(headerCells[2]).toHaveAttribute('scope', 'col');
+  });
+
   it('renders data cells', () => {
     render(<BaseTable data={users} columns={columns} />);
     const cells = screen.getAllByRole('cell');
@@ -617,6 +645,29 @@ describe('BaseTable', () => {
 // =============================================================================
 
 describe('Table', () => {
+  it('clears a cell when the field is removed from the row object (#3595)', () => {
+    const cols: TableColumn<Record<string, unknown>>[] = [
+      {key: 'name', header: 'Name'},
+      {key: 'status', header: 'Status'},
+    ];
+    const {rerender} = render(
+      <Table
+        data={[{id: '1', name: 'Alice', status: 'active'}]}
+        columns={cols}
+        idKey="id"
+      />,
+    );
+    expect(screen.getByText('active')).toBeInTheDocument();
+
+    // Clearing a field by omitting it (optimistic update / server response)
+    // must re-render the row — the memo previously only compared the keys of
+    // the NEW item, so the deleted field's stale value kept rendering.
+    rerender(
+      <Table data={[{id: '1', name: 'Alice'}]} columns={cols} idKey="id" />,
+    );
+    expect(screen.queryByText('active')).not.toBeInTheDocument();
+  });
+
   it('renders a table with correct structure', () => {
     render(<Table data={users} columns={columns} />);
     expect(screen.getByRole('table')).toBeInTheDocument();

package/src/Table/plugins/columnResize/useTableColumnResize.test.tsx

@@ -551,6 +551,19 @@ describe('useTableColumnResize', () => {
       expect(handle).toHaveAttribute('aria-valuenow', '200');
     });
 
+    it('handle has a numeric aria-valuenow on initial render (before any width is measured)', () => {
+      // A focusable role="separator" requires aria-valuenow per the ARIA spec.
+      // Before the column width has been measured there is no override width, so
+      // the handle must fall back to a defined numeric value (the column
+      // minWidth) rather than omitting the attribute.
+      render(<ResizeTable minWidth={80} />);
+      const handle = getResizeHandles()[0];
+      const valueNow = handle.getAttribute('aria-valuenow');
+      expect(valueNow).not.toBeNull();
+      expect(Number.isNaN(Number(valueNow))).toBe(false);
+      expect(valueNow).toBe('80');
+    });
+
     it('handle has aria-label with column header text', () => {
       render(<ResizeTable />);
       const handle = getResizeHandles()[0];

package/src/Table/plugins/columnResize/useTableColumnResize.tsx

@@ -676,7 +676,9 @@ function ResizeHandle({
     <div
       role="separator"
       aria-orientation="vertical"
-      aria-valuenow={currentWidth ?? undefined}
+      // A focusable role="separator" requires a numeric aria-valuenow, so fall
+      // back to the column's minWidth before the width has been measured.
+      aria-valuenow={currentWidth ?? minWidth}
       aria-valuemin={minWidth}
       aria-valuemax={maxWidth === Infinity ? undefined : maxWidth}
       aria-label={ariaLabel}

package/src/Table/plugins/pagination/paginateData.ts

@@ -38,6 +38,10 @@ export function paginateData<T>(
   const size = Number.isFinite(pageSize)
     ? Math.max(1, Math.floor(pageSize))
     : 10;
-  const start = (page - 1) * size;
+  // page needs the same coercion: a negative start index makes Array.slice
+  // count from the END of the data (page -1 returns the tail dressed up as a
+  // page), and a fractional page returns a slice straddling two pages.
+  const p = Number.isFinite(page) ? Math.max(1, Math.floor(page)) : 1;
+  const start = (p - 1) * size;
   return data.slice(start, start + size);
 }

package/src/Table/plugins/pagination/useTablePagination.test.tsx

@@ -132,6 +132,19 @@ describe('paginateData', () => {
     expect(paginateData([], 1, 10)).toEqual([]);
   });
 
+  it('clamps invalid page numbers to the first page (#3593)', () => {
+    const data = generateItems(30);
+    // Negative pages previously fed a negative index to Array.slice, which
+    // counts from the END of the data — the tail dressed up as a page.
+    expect(paginateData(data, -1, 10)[0].id).toBe('1');
+    expect(paginateData(data, 0, 10)[0].id).toBe('1');
+    expect(paginateData(data, NaN, 10)[0].id).toBe('1');
+    // Fractional pages floor to the containing page instead of straddling two.
+    expect(paginateData(data, 1.5, 10).map(i => i.id)).toEqual(
+      paginateData(data, 1, 10).map(i => i.id),
+    );
+  });
+
   it('returns empty array when page exceeds data', () => {
     const data = generateItems(10);
     expect(paginateData(data, 5, 10)).toEqual([]);

package/src/Table/plugins/selection/useTableSelectionState.test.tsx

@@ -302,6 +302,29 @@ describe('useTableSelectionState with filtered data', () => {
     expect(screen.getByTestId('selected-keys')).toHaveTextContent('1,3');
   });
 
+  it('select-all is unchecked when the filter matches nothing (#3591)', async () => {
+    const user = userEvent.setup();
+    render(<FilteredSelectionTable />);
+
+    // Select Bob, then filter to an empty result set.
+    const checkboxes = screen.getAllByLabelText('Select row');
+    await user.click(checkboxes[1]);
+    expect(screen.getByTestId('selected-keys')).toHaveTextContent('2');
+
+    const input = screen.getByTestId('filter-input');
+    await user.clear(input);
+    await user.type(input, 'zzz');
+
+    // Zero visible rows must not read as "all selected" — previously the
+    // header checkbox rendered checked here and deselect-all was a no-op.
+    const selectAll = screen.getByLabelText('Select all rows');
+    expect(selectAll).not.toBeChecked();
+
+    // The hidden selection itself is preserved (frozen), as designed.
+    await user.clear(input);
+    expect(screen.getByTestId('selected-keys')).toHaveTextContent('2');
+  });
+
   it('selections persist when filter changes', async () => {
     const user = userEvent.setup();
     render(<FilteredSelectionTable />);

package/src/Table/plugins/selection/useTableSelectionState.tsx

@@ -125,12 +125,17 @@ export function useTableSelectionState<T extends Record<string, unknown>>(
     [selectedKeys, selectableIDs],
   );
 
-  const getAllSelected = useCallback(
-    () =>
-      allSelectableIDs.size === selectedKeys.size &&
-      allSelectableIDs.size !== 0,
-    [allSelectableIDs, selectedKeys],
-  );
+  const getAllSelected = useCallback(() => {
+    // Require at least one actionable row: with zero visible selectable
+    // rows (e.g. a filter with no matches while a selection exists), the
+    // union-based size comparison would read any non-empty selection as
+    // "all selected" — a checked header checkbox over an empty table that
+    // deselect-all can't clear, since the invisible keys count as frozen.
+    if (selectableIDs.size === 0) {
+      return false;
+    }
+    return allSelectableIDs.size === selectedKeys.size;
+  }, [allSelectableIDs, selectableIDs, selectedKeys]);
 
   // Use refs to keep onSelectAll stable
   const frozenSelectedIDsRef = useRef(frozenSelectedIDs);

package/src/Table/plugins/sortable/useTableSortableState.test.tsx

@@ -8,7 +8,7 @@
  */
 
 import {describe, it, expect, vi} from 'vitest';
-import {render, screen, within} from '@testing-library/react';
+import {render, renderHook, screen, within} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {useState} from 'react';
 import {Table} from '../../Table';
@@ -421,6 +421,40 @@ describe('useTableSortableState', () => {
     });
   });
 
+  describe('NaN handling', () => {
+    it('keeps valid numbers sorted when a NaN cell is present', () => {
+      const data: Employee[] = [
+        {id: '1', name: 'A', age: 5, department: 'X', salary: 1},
+        {id: '2', name: 'B', age: NaN, department: 'X', salary: 1},
+        {id: '3', name: 'C', age: 1, department: 'X', salary: 1},
+        {id: '4', name: 'D', age: 3, department: 'X', salary: 1},
+      ];
+      const {result} = renderHook(() =>
+        useTableSortableState({
+          data,
+          defaultSort: [{sortKey: 'age', direction: 'ascending'}],
+        }),
+      );
+      // NaN groups at the end like null; the valid numbers stay ordered.
+      expect(result.current.sortedData.map(e => e.age)).toEqual([1, 3, 5, NaN]);
+    });
+
+    it('sorts NaN to the start in descending order, like null', () => {
+      const data: Employee[] = [
+        {id: '1', name: 'A', age: 5, department: 'X', salary: 1},
+        {id: '2', name: 'B', age: NaN, department: 'X', salary: 1},
+        {id: '3', name: 'C', age: 1, department: 'X', salary: 1},
+      ];
+      const {result} = renderHook(() =>
+        useTableSortableState({
+          data,
+          defaultSort: [{sortKey: 'age', direction: 'descending'}],
+        }),
+      );
+      expect(result.current.sortedData.map(e => e.age)).toEqual([NaN, 5, 1]);
+    });
+  });
+
   describe('null/undefined handling', () => {
     it('sorts null values to the end', () => {
       const data: Employee[] = [