@titan-design/react-ui 0.12.0 → 0.13.0

package/src/components/custom/Table/Table.stories.tsx

@@ -1,4 +1,4 @@
-import React, { useState } from 'react'
+import { useState } from 'react'
 import type { Meta, StoryObj } from '@storybook/react-vite'
 import { View, Text } from 'react-native'
 import { cn } from '../../../utils/cn'
@@ -15,6 +15,7 @@ import {
   TableSelectCell,
   useTable,
 } from './Table'
+import { useColumnFit, type TableColumnFit } from './column-fit'
 import { Button, ButtonText } from '../../ui/button/Button'
 
 interface User {
@@ -44,7 +45,10 @@ const manyUsers: User[] = Array.from({ length: 50 }, (_, i) => ({
 const meta: Meta<typeof Table> = {
   title: 'Components/Organisms/Table',
   component: Table,
-  tags: ['autodocs'],
+  parameters: {
+    docs: { description: { component: 'Composes **Tooltip**.' } },
+  },
+  tags: ['autodocs', 'status:candidate', '!status:review'],
   argTypes: {
     isLoading: {
       control: 'boolean',
@@ -114,9 +118,7 @@ export const WithSorting: Story = {
 
     const handleSort = (column: string) => {
       if (sortColumn === column) {
-        setSortDirection((prev) =>
-          prev === 'asc' ? 'desc' : prev === 'desc' ? null : 'asc'
-        )
+        setSortDirection((prev) => (prev === 'asc' ? 'desc' : prev === 'desc' ? null : 'asc'))
       } else {
         setSortColumn(column)
         setSortDirection('asc')
@@ -313,11 +315,17 @@ export const WithColumnWidths: Story = {
     <Table>
       <TableHeader>
         <TableRow isHoverable={false}>
-          <TableHeaderCell width={60} align="center">#</TableHeaderCell>
+          <TableHeaderCell width={60} align="center">
+            #
+          </TableHeaderCell>
           <TableHeaderCell width={200}>Name</TableHeaderCell>
           <TableHeaderCell>Email</TableHeaderCell>
-          <TableHeaderCell width={120} align="center">Role</TableHeaderCell>
-          <TableHeaderCell width={100} align="right">Status</TableHeaderCell>
+          <TableHeaderCell width={120} align="center">
+            Role
+          </TableHeaderCell>
+          <TableHeaderCell width={100} align="right">
+            Status
+          </TableHeaderCell>
         </TableRow>
       </TableHeader>
       <TableBody>
@@ -330,8 +338,12 @@ export const WithColumnWidths: Story = {
               <Text className="text-sm text-text-primary font-medium">{user.name}</Text>
             </TableCell>
             <TableCell>{user.email}</TableCell>
-            <TableCell width={120} align="center">{user.role}</TableCell>
-            <TableCell width={100} align="right">{user.status}</TableCell>
+            <TableCell width={120} align="center">
+              {user.role}
+            </TableCell>
+            <TableCell width={100} align="right">
+              {user.status}
+            </TableCell>
           </TableRow>
         ))}
       </TableBody>
@@ -339,6 +351,79 @@ export const WithColumnWidths: Story = {
   ),
 }
 
+/**
+ * A column's terms for the fit: what it needs, and when it leaves. `name` has no
+ * `dropPriority`, so it never drops — which is what puts a floor under the
+ * dropping and hands the overflow to horizontal scroll instead.
+ */
+const FIT_COLUMNS: (TableColumnFit & { label: string })[] = [
+  { key: 'name', label: 'Name', minWidth: 200 },
+  { key: 'email', label: 'Email', minWidth: 220, dropPriority: 3 },
+  { key: 'role', label: 'Role', minWidth: 120, dropPriority: 2 },
+  { key: 'status', label: 'Status', minWidth: 100, dropPriority: 1 },
+]
+
+/** The hairline frame, which the outer width includes but the columns cannot use. */
+const FRAME_INSET = 2
+
+/** The same table at a pinned width, so one story shows every step of the order at once. */
+function FittedTable({ available }: { available: number }) {
+  const fit = useColumnFit(FIT_COLUMNS, available - FRAME_INSET)
+  const columns = FIT_COLUMNS.filter((column) => fit.isVisible(column.key))
+  const width = (key: string) =>
+    key === 'name' ? undefined : FIT_COLUMNS.find((c) => c.key === key)!.minWidth
+
+  return (
+    <View className="gap-1" style={{ width: available }}>
+      <Text className="text-xs text-text-secondary">
+        {`${available}px · ${columns.length} columns${fit.isScrolling ? ' · scrolls' : ''}`}
+      </Text>
+      <View className="overflow-hidden rounded-lg border border-hairline">
+        <Table contentMinWidth={fit.contentMinWidth}>
+          <TableHeader>
+            <TableRow isHoverable={false}>
+              {columns.map((column) => (
+                <TableHeaderCell key={column.key} width={width(column.key)}>
+                  {column.label}
+                </TableHeaderCell>
+              ))}
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {sampleUsers.slice(0, 3).map((user) => (
+              <TableRow key={user.id}>
+                {columns.map((column) => (
+                  <TableCell key={column.key} width={width(column.key)}>
+                    {user[column.key as keyof User]}
+                  </TableCell>
+                ))}
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      </View>
+    </View>
+  )
+}
+
+/**
+ * **Column drop order.** When the measured width cannot hold every column, they
+ * drop one at a time in the order the caller declared — `status`, then `role`,
+ * then `email`. `name` declares no `dropPriority`, so dropping stops there and
+ * the table scrolls horizontally instead: scroll is the floor, not the first
+ * resort. Measure with `useMeasuredWidth`, decide with `useColumnFit`, and hand
+ * `contentMinWidth` to `Table` so it knows what to scroll to.
+ */
+export const ColumnDropOrder: Story = {
+  render: () => (
+    <View className="gap-6">
+      {[660, 560, 440, 300, 150].map((available) => (
+        <FittedTable key={available} available={available} />
+      ))}
+    </View>
+  ),
+}
+
 export const UseTableHook: Story = {
   render: function Render() {
     const {
@@ -361,8 +446,8 @@ export const UseTableHook: Story = {
     return (
       <View style={{ gap: 8 }}>
         <Text className="text-sm text-text-secondary">
-          Showing {paginatedData.length} of {totalItems} users, sorted by{' '}
-          {sortColumn ?? 'none'} ({sortDirection ?? 'none'})
+          Showing {paginatedData.length} of {totalItems} users, sorted by {sortColumn ?? 'none'} (
+          {sortDirection ?? 'none'})
         </Text>
         <Table sortColumn={sortColumn} sortDirection={sortDirection} onSort={handleSort}>
           <TableHeader>
@@ -434,9 +519,7 @@ export const SortingAndSelection: Story = {
 
     return (
       <View style={{ gap: 8 }}>
-        <Text className="text-sm text-text-secondary">
-          Selected: {selectedRows.size} rows
-        </Text>
+        <Text className="text-sm text-text-secondary">Selected: {selectedRows.size} rows</Text>
         <Table
           sortColumn={sortColumn}
           sortDirection={sortDirection}

package/src/components/custom/Table/Table.test.tsx

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from 'vitest'
-import { render, screen, fireEvent } from '@testing-library/react'
+import { render, screen, fireEvent, renderHook, act } from '@testing-library/react'
 import { axe } from 'jest-axe'
 import {
   Table,
@@ -12,6 +12,7 @@ import {
   TableEmptyState,
   TableSelectAllCell,
   TableSelectCell,
+  useTable,
 } from './Table'
 
 function renderBasicTable() {
@@ -321,29 +322,142 @@ describe('Table', () => {
     })
   })
 
-  describe('TablePagination', () => {
-    it('renders pagination info', () => {
+  describe('sort cycle end state', () => {
+    // Regression: after asc -> desc -> unsorted the column is still the sort
+    // column, and the header kept showing the descending arrow.
+    it('shows the neutral glyph once the cycle returns to unsorted', () => {
       render(
-        <TablePagination
-          page={0}
-          pageSize={10}
-          totalItems={50}
-          onPageChange={vi.fn()}
-        />
+        <Table sortColumn="name" sortDirection={null} onSort={vi.fn()}>
+          <TableHeader>
+            <TableRow>
+              <TableHeaderCell sortKey="name">Name</TableHeaderCell>
+            </TableRow>
+          </TableHeader>
+        </Table>
+      )
+      expect(screen.getByText('↕')).toBeInTheDocument()
+      expect(screen.getByRole('columnheader')).toHaveAttribute('aria-sort', 'none')
+    })
+  })
+
+  describe('idle sort glyph', () => {
+    it('hides the neutral glyph until the header is hovered, and keeps an active arrow visible', () => {
+      render(
+        <Table sortColumn="name" sortDirection="asc" onSort={vi.fn()}>
+          <TableHeader>
+            <TableRow>
+              <TableHeaderCell sortKey="name">Name</TableHeaderCell>
+              <TableHeaderCell sortKey="email">Email</TableHeaderCell>
+            </TableRow>
+          </TableHeader>
+        </Table>
+      )
+      expect(screen.getByText('↑')).toHaveStyle({ opacity: '1' })
+      const idle = screen.getByText('↕')
+      expect(idle).toHaveStyle({ opacity: '0' })
+      fireEvent.mouseEnter(screen.getByRole('button', { name: 'Sort by Email' }))
+      expect(idle).toHaveStyle({ opacity: '1' })
+      fireEvent.mouseLeave(screen.getByRole('button', { name: 'Sort by Email' }))
+      expect(idle).toHaveStyle({ opacity: '0' })
+    })
+  })
+
+  describe('header tooltip', () => {
+    it('uses the full column name as the accessible sort name and shows it on hover', () => {
+      render(
+        <Table onSort={vi.fn()}>
+          <TableHeader>
+            <TableRow>
+              <TableHeaderCell sortKey="priority" tooltip="Priority">
+                Pri
+              </TableHeaderCell>
+            </TableRow>
+          </TableHeader>
+        </Table>
+      )
+      const sortButton = screen.getByRole('button', { name: 'Sort by Priority' })
+      fireEvent.mouseEnter(sortButton.parentElement!)
+      expect(screen.getByText('Priority')).toBeInTheDocument()
+    })
+
+    it('still sorts when the tooltip-wrapped header is pressed', () => {
+      const onSort = vi.fn()
+      render(
+        <Table onSort={onSort}>
+          <TableHeader>
+            <TableRow>
+              <TableHeaderCell sortKey="priority" tooltip="Priority">
+                Pri
+              </TableHeaderCell>
+            </TableRow>
+          </TableHeader>
+        </Table>
       )
+      fireEvent.click(screen.getByText('Pri'))
+      expect(onSort).toHaveBeenCalledWith('priority')
+    })
+  })
+
+  describe('flexible column layout', () => {
+    // Regression: a long nowrap title used to size the horizontal scroller to
+    // max-content, so the flexible column never shrank and the last fixed
+    // column was clipped inside the table's card (AW-22 T2 Gate 2 finding).
+    it('fills the scroll viewport instead of sizing to its longest cell', () => {
+      renderBasicTable()
+      const scrollContent = screen.getByRole('table').parentElement
+      expect(scrollContent).toHaveStyle({ width: '100%' })
+    })
+
+    it('lets a cell without a width shrink below its content', () => {
+      render(
+        <Table>
+          <TableBody>
+            <TableRow>
+              <TableCell width={80}>fixed</TableCell>
+              <TableCell>flexible</TableCell>
+            </TableRow>
+          </TableBody>
+        </Table>
+      )
+      expect(screen.getByText('fixed').closest('[role="cell"]')).toHaveStyle({ width: '80px' })
+      expect(screen.getByText('flexible').closest('[role="cell"]')).toHaveStyle({
+        flexGrow: '1',
+        minWidth: '0px',
+      })
+    })
+
+    it('floors the content at the width the columns need, so a too-narrow table scrolls', () => {
+      render(
+        <Table contentMinWidth={420}>
+          <TableBody>
+            <TableRow>
+              <TableCell>only</TableCell>
+            </TableRow>
+          </TableBody>
+        </Table>
+      )
+      // width 100% + the floor resolves to max(container, floor): fill, then scroll.
+      expect(screen.getByRole('table').parentElement).toHaveStyle({
+        width: '100%',
+        minWidth: '420px',
+      })
+    })
+
+    it('sets no floor when the caller has not measured one', () => {
+      renderBasicTable()
+      expect(screen.getByRole('table').parentElement).not.toHaveStyle({ minWidth: '420px' })
+    })
+  })
+
+  describe('TablePagination', () => {
+    it('renders pagination info', () => {
+      render(<TablePagination page={0} pageSize={10} totalItems={50} onPageChange={vi.fn()} />)
       expect(screen.getByText('1-10 of 50')).toBeInTheDocument()
     })
 
     it('calls onPageChange when next is clicked', () => {
       const onPageChange = vi.fn()
-      render(
-        <TablePagination
-          page={0}
-          pageSize={10}
-          totalItems={50}
-          onPageChange={onPageChange}
-        />
-      )
+      render(<TablePagination page={0} pageSize={10} totalItems={50} onPageChange={onPageChange} />)
 
       fireEvent.click(screen.getByLabelText('Next page'))
       expect(onPageChange).toHaveBeenCalledWith(1)
@@ -351,41 +465,20 @@ describe('Table', () => {
 
     it('calls onPageChange when previous is clicked', () => {
       const onPageChange = vi.fn()
-      render(
-        <TablePagination
-          page={2}
-          pageSize={10}
-          totalItems={50}
-          onPageChange={onPageChange}
-        />
-      )
+      render(<TablePagination page={2} pageSize={10} totalItems={50} onPageChange={onPageChange} />)
 
       fireEvent.click(screen.getByLabelText('Previous page'))
       expect(onPageChange).toHaveBeenCalledWith(1)
     })
 
     it('disables previous button on first page', () => {
-      render(
-        <TablePagination
-          page={0}
-          pageSize={10}
-          totalItems={50}
-          onPageChange={vi.fn()}
-        />
-      )
+      render(<TablePagination page={0} pageSize={10} totalItems={50} onPageChange={vi.fn()} />)
       const prevButton = screen.getByLabelText('Previous page')
       expect(prevButton).toHaveAttribute('aria-disabled', 'true')
     })
 
     it('disables next button on last page', () => {
-      render(
-        <TablePagination
-          page={4}
-          pageSize={10}
-          totalItems={50}
-          onPageChange={vi.fn()}
-        />
-      )
+      render(<TablePagination page={4} pageSize={10} totalItems={50} onPageChange={vi.fn()} />)
       const nextButton = screen.getByLabelText('Next page')
       expect(nextButton).toHaveAttribute('aria-disabled', 'true')
     })
@@ -422,26 +515,12 @@ describe('Table', () => {
     })
 
     it('shows correct range for middle pages', () => {
-      render(
-        <TablePagination
-          page={2}
-          pageSize={10}
-          totalItems={50}
-          onPageChange={vi.fn()}
-        />
-      )
+      render(<TablePagination page={2} pageSize={10} totalItems={50} onPageChange={vi.fn()} />)
       expect(screen.getByText('21-30 of 50')).toBeInTheDocument()
     })
 
     it('shows correct range for last partial page', () => {
-      render(
-        <TablePagination
-          page={2}
-          pageSize={10}
-          totalItems={25}
-          onPageChange={vi.fn()}
-        />
-      )
+      render(<TablePagination page={2} pageSize={10} totalItems={25} onPageChange={vi.fn()} />)
       expect(screen.getByText('21-25 of 25')).toBeInTheDocument()
     })
   })
@@ -454,30 +533,18 @@ describe('Table', () => {
     })
 
     it('renders with custom title and description', () => {
-      render(
-        <TableEmptyState title="No users" description="Add users to see them here." />
-      )
+      render(<TableEmptyState title="No users" description="Add users to see them here." />)
       expect(screen.getByText('No users')).toBeInTheDocument()
       expect(screen.getByText('Add users to see them here.')).toBeInTheDocument()
     })
 
     it('renders with action element', () => {
-      render(
-        <TableEmptyState
-          title="No data"
-          action={<button>Add Item</button>}
-        />
-      )
+      render(<TableEmptyState title="No data" action={<button>Add Item</button>} />)
       expect(screen.getByText('Add Item')).toBeInTheDocument()
     })
 
     it('renders with custom icon', () => {
-      render(
-        <TableEmptyState
-          title="No data"
-          icon={<span data-testid="empty-icon">E</span>}
-        />
-      )
+      render(<TableEmptyState title="No data" icon={<span data-testid="empty-icon">E</span>} />)
       expect(screen.getByTestId('empty-icon')).toBeInTheDocument()
     })
   })
@@ -491,12 +558,7 @@ describe('Table', () => {
 
     it('has no accessibility violations for pagination', async () => {
       const { container } = render(
-        <TablePagination
-          page={0}
-          pageSize={10}
-          totalItems={50}
-          onPageChange={vi.fn()}
-        />
+        <TablePagination page={0} pageSize={10} totalItems={50} onPageChange={vi.fn()} />
       )
       const results = await axe(container)
       expect(results).toHaveNoViolations()
@@ -543,16 +605,141 @@ describe('Table', () => {
     })
 
     it('pagination buttons have accessible labels', () => {
-      render(
-        <TablePagination
-          page={1}
-          pageSize={10}
-          totalItems={50}
-          onPageChange={vi.fn()}
-        />
-      )
+      render(<TablePagination page={1} pageSize={10} totalItems={50} onPageChange={vi.fn()} />)
       expect(screen.getByLabelText('Previous page')).toBeInTheDocument()
       expect(screen.getByLabelText('Next page')).toBeInTheDocument()
     })
   })
 })
+
+describe('Table density', () => {
+  it('defaults to comfortable and accepts dense without changing structure', () => {
+    const { rerender } = render(
+      <Table>
+        <TableBody>
+          <TableRow>
+            <TableCell>Alice</TableCell>
+          </TableRow>
+        </TableBody>
+      </Table>
+    )
+    expect(screen.getByRole('cell')).toBeInTheDocument()
+
+    rerender(
+      <Table density="dense">
+        <TableBody>
+          <TableRow>
+            <TableCell>Alice</TableCell>
+          </TableRow>
+        </TableBody>
+      </Table>
+    )
+    // nativewind compiles className to style, so density is asserted through
+    // structure + a11y surviving rather than through class names.
+    expect(screen.getByRole('cell')).toBeInTheDocument()
+    expect(screen.getByText('Alice')).toBeInTheDocument()
+  })
+
+  it('keeps header cells sortable at dense density', () => {
+    const onSort = vi.fn()
+    render(
+      <Table density="dense" sortColumn="name" sortDirection="asc" onSort={onSort}>
+        <TableHeader>
+          <TableRow>
+            <TableHeaderCell sortKey="name">Name</TableHeaderCell>
+          </TableRow>
+        </TableHeader>
+      </Table>
+    )
+    fireEvent.click(screen.getByRole('button', { name: 'Sort by Name' }))
+    expect(onSort).toHaveBeenCalledWith('name')
+    expect(screen.getByRole('columnheader')).toHaveAttribute('aria-sort', 'ascending')
+  })
+})
+
+describe('useTable', () => {
+  // A type alias, not an interface: `useTable` constrains T to an index-signature
+  // shape, and only aliases get the implicit index signature that satisfies it.
+  type Row = {
+    id: string
+    rank: number
+    size?: number
+  }
+  const rows: Row[] = [
+    { id: 'b', rank: 2, size: 5 },
+    { id: 'a', rank: 3 },
+    { id: 'c', rank: 1, size: 2 },
+  ]
+
+  const ids = (data: Row[]) => data.map((r) => r.id)
+
+  it('returns data untouched until a direction is set', () => {
+    const { result } = renderHook(() => useTable<Row>({ data: rows, defaultSortColumn: 'rank' }))
+    expect(ids(result.current.sortedData)).toEqual(['b', 'a', 'c'])
+  })
+
+  it('sorts by raw field value when no comparator is supplied', () => {
+    const { result } = renderHook(() =>
+      useTable<Row>({ data: rows, defaultSortColumn: 'rank', defaultSortDirection: 'asc' })
+    )
+    expect(ids(result.current.sortedData)).toEqual(['c', 'b', 'a'])
+  })
+
+  it('ranks blank values last in BOTH directions', () => {
+    const asc = renderHook(() =>
+      useTable<Row>({ data: rows, defaultSortColumn: 'size', defaultSortDirection: 'asc' })
+    )
+    const desc = renderHook(() =>
+      useTable<Row>({ data: rows, defaultSortColumn: 'size', defaultSortDirection: 'desc' })
+    )
+    // `a` has no size; flipping direction must not promote it to the top.
+    expect(ids(asc.result.current.sortedData).at(-1)).toBe('a')
+    expect(ids(desc.result.current.sortedData).at(-1)).toBe('a')
+  })
+
+  it('uses a per-column comparator when one is supplied', () => {
+    const { result } = renderHook(() =>
+      useTable<Row>({
+        data: rows,
+        defaultSortColumn: 'id',
+        defaultSortDirection: 'asc',
+        // Reverse-alphabetical, to prove the comparator beats the field compare.
+        comparators: { id: (x, y) => y.id.localeCompare(x.id) },
+      })
+    )
+    expect(ids(result.current.sortedData)).toEqual(['c', 'b', 'a'])
+  })
+
+  it('inverts a comparator for desc rather than reversing the array', () => {
+    const { result } = renderHook(() =>
+      useTable<Row>({
+        data: rows,
+        defaultSortColumn: 'id',
+        defaultSortDirection: 'desc',
+        comparators: { id: (x, y) => y.id.localeCompare(x.id) },
+      })
+    )
+    expect(ids(result.current.sortedData)).toEqual(['a', 'b', 'c'])
+  })
+
+  it('leaves columns without a comparator on the default compare', () => {
+    const { result } = renderHook(() =>
+      useTable<Row>({
+        data: rows,
+        defaultSortColumn: 'rank',
+        defaultSortDirection: 'asc',
+        comparators: { id: (x, y) => y.id.localeCompare(x.id) },
+      })
+    )
+    expect(ids(result.current.sortedData)).toEqual(['c', 'b', 'a'])
+  })
+
+  it('toggles direction through handleSort on the same column', () => {
+    const { result } = renderHook(() =>
+      useTable<Row>({ data: rows, defaultSortColumn: 'rank', defaultSortDirection: 'asc' })
+    )
+    act(() => result.current.handleSort('rank'))
+    expect(result.current.sortDirection).toBe('desc')
+    expect(ids(result.current.sortedData)).toEqual(['a', 'b', 'c'])
+  })
+})