@12-apps/ui 1.0.0 → 1.3.0

package/src/components/data-display/Table/TableParts.hooks.tsx

@@ -0,0 +1,112 @@
+import type React from 'react';
+import { useCallback } from 'react';
+
+import { TableDataRow } from './TableParts';
+import type { TableBodyProps } from './Table.types';
+
+// Row identity, selection and the row element itself. Split out of
+// EnhancedTableBody so that component is just the virtualised/plain choice.
+// A row's identity: the caller's extractor, else its id, else its position.
+const useRowKey = (rowKeyExtractor: TableBodyProps['rowKeyExtractor']) =>
+  useCallback(
+    (rowData: Record<string, unknown>, index: number): string | number =>
+      rowKeyExtractor ? rowKeyExtractor(rowData, index) : (rowData.id as string | number) || index,
+    [rowKeyExtractor],
+  );
+
+const useRowSelection = ({
+  selectedRows,
+  onSelectionChange,
+}: {
+  selectedRows: Array<string | number>;
+  onSelectionChange: TableBodyProps['onSelectionChange'];
+}) =>
+  useCallback(
+    (event: React.MouseEvent | React.ChangeEvent, rowKey: string | number) => {
+      // Stop propagation so selecting does not also fire the row click.
+      event.stopPropagation();
+      if (!onSelectionChange) return;
+      onSelectionChange(rowKey, !selectedRows.includes(rowKey));
+    },
+    [onSelectionChange, selectedRows],
+  );
+
+export const useTableRowRenderer = ({
+  columns,
+  selectedRows,
+  onRowClick,
+  onRowFocus,
+  onRowBlur,
+  onSelectionChange,
+  rowKeyExtractor,
+  selectable,
+  renderRow,
+  renderCell,
+  virtualScrolling,
+  rowHeight,
+}: Pick<
+  TableBodyProps,
+  | 'columns'
+  | 'onRowClick'
+  | 'onRowFocus'
+  | 'onRowBlur'
+  | 'onSelectionChange'
+  | 'rowKeyExtractor'
+  | 'selectable'
+  | 'renderRow'
+  | 'renderCell'
+  | 'virtualScrolling'
+  | 'rowHeight'
+> & { selectedRows: Array<string | number> }) => {
+  const getRowKey = useRowKey(rowKeyExtractor);
+  const isRowSelected = useCallback(
+    (rowKey: string | number) => selectedRows.includes(rowKey),
+    [selectedRows],
+  );
+  const handleRowSelection = useRowSelection({ selectedRows, onSelectionChange });
+
+  const renderTableRow = useCallback(
+    (rowData: Record<string, unknown>, index: number, offsetY: number = 0) => {
+      const rowKey = getRowKey(rowData, index);
+      const selected = isRowSelected(rowKey);
+
+      if (renderRow) return renderRow(rowData, index, selected);
+
+      return (
+        <TableDataRow
+          key={rowKey}
+          rowData={rowData}
+          rowKey={rowKey}
+          index={index}
+          offsetY={offsetY}
+          columns={columns}
+          selected={selected}
+          selectable={selectable}
+          rowHeight={rowHeight}
+          onRowClick={onRowClick}
+          onRowFocus={onRowFocus}
+          onRowBlur={onRowBlur}
+          onSelect={handleRowSelection}
+          virtualScrolling={virtualScrolling}
+          renderCell={renderCell}
+        />
+      );
+    },
+    [
+      columns,
+      getRowKey,
+      isRowSelected,
+      handleRowSelection,
+      onRowClick,
+      onRowFocus,
+      onRowBlur,
+      renderRow,
+      renderCell,
+      rowHeight,
+      selectable,
+      virtualScrolling,
+    ],
+  );
+
+  return renderTableRow;
+};

package/src/components/data-display/Table/TableParts.tsx

@@ -0,0 +1,298 @@
+import {
+  Box,
+  Checkbox,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableRow,
+  TableSortLabel } from '@mui/material';
+import React, { useCallback } from 'react';
+
+import { useVirtualScrolling } from './Table.hooks';
+import { useTableRowRenderer } from './TableParts.hooks';
+import type { ColumnConfig, TableBodyProps, TableHeaderProps } from './Table.types';
+
+// Mirrors the visible sort indicator for assistive technology; undefined when
+// the column is not sorted, which is what removes the attribute entirely.
+const ariaSortFor = (
+  canSort: boolean,
+  isSorted: boolean,
+  direction?: 'asc' | 'desc',
+): 'ascending' | 'descending' | undefined => {
+  if (!canSort || !isSorted) return undefined;
+
+  return direction === 'asc' ? 'ascending' : 'descending';
+};
+
+// One header cell. Sorting is offered when the table is sortable and the column
+// has not opted out; aria-sort mirrors the visible indicator.
+const HeaderCell: React.FC<{
+  column: ColumnConfig;
+  sortable?: boolean;
+  sortConfig?: { key: string; direction: 'asc' | 'desc' };
+  onSort: (columnKey: string) => void;
+}> = ({ column, sortable, sortConfig, onSort }) => {
+  const canSort = Boolean(sortable) && column.sortable !== false;
+  const isSorted = sortConfig?.key === column.key;
+
+  return (
+    <TableCell
+      align={column.align || 'left'}
+      style={{ minWidth: column.minWidth, width: column.width }}
+      aria-sort={ariaSortFor(canSort, isSorted, sortConfig?.direction)}
+    >
+      {canSort ? (
+        <TableSortLabel
+          active={isSorted}
+          direction={isSorted ? sortConfig?.direction : 'asc'}
+          onClick={() => onSort(column.key)}
+          data-testid="sort-indicator"
+          aria-label={`Sort by ${column.label}`}
+        >
+          {column.label}
+        </TableSortLabel>
+      ) : (
+        column.label
+      )}
+    </TableCell>
+  );
+};
+
+export const EnhancedTableHeader: React.FC<TableHeaderProps> = React.memo(({
+  columns,
+  data,
+  sortable,
+  sortConfig,
+  onSortChange,
+  selectable,
+  selectedRows = [],
+  onSelectAll }) => {
+  const handleSort = useCallback(
+    (columnKey: string) => {
+      if (!sortable || !onSortChange) return;
+      
+      const direction = 
+        sortConfig?.key === columnKey && sortConfig.direction === 'asc' ? 'desc' : 'asc';
+      onSortChange(columnKey, direction);
+    },
+    [sortable, onSortChange, sortConfig]
+  );
+
+  const handleSelectAll = useCallback(
+    (event: React.ChangeEvent<globalThis.HTMLInputElement>) => {
+      if (!onSelectAll) return;
+      onSelectAll(event.target.checked);
+    },
+    [onSelectAll]
+  );
+
+  return (
+    <TableHead>
+      <TableRow>
+        {selectable && (
+          <TableCell padding="checkbox">
+            <Checkbox
+              indeterminate={selectedRows.length > 0 && selectedRows.length < data.length}
+              checked={selectedRows.length === data.length && data.length > 0}
+              onChange={handleSelectAll}
+              inputProps={{ 'aria-label': 'select all' }}
+            />
+          </TableCell>
+        )}
+        {columns.map((column) => (
+          <HeaderCell
+            key={column.key}
+            column={column}
+            sortable={sortable}
+            sortConfig={sortConfig}
+            onSort={handleSort}
+          />
+        ))}
+      </TableRow>
+    </TableHead>
+  );
+});
+
+EnhancedTableHeader.displayName = 'EnhancedTableHeader';
+
+// One data row. Split out of the memoised renderTableRow callback so the
+// callback stays a short dispatch and the row markup is readable on its own.
+export const TableDataRow: React.FC<{
+  rowData: Record<string, unknown>;
+  rowKey: string | number;
+  index: number;
+  offsetY: number;
+  columns: ColumnConfig[];
+  selected: boolean;
+  selectable?: boolean;
+  rowHeight?: number;
+  onRowClick?: TableBodyProps['onRowClick'];
+  onRowFocus?: TableBodyProps['onRowFocus'];
+  onRowBlur?: TableBodyProps['onRowBlur'];
+  onSelect: (event: React.MouseEvent | React.ChangeEvent, rowKey: string | number) => void;
+  virtualScrolling?: boolean;
+  renderCell?: TableBodyProps['renderCell'];
+}> = ({
+  rowData,
+  rowKey,
+  index,
+  offsetY,
+  columns,
+  selected,
+  selectable,
+  rowHeight,
+  onRowClick,
+  onRowFocus,
+  onRowBlur,
+  onSelect,
+  virtualScrolling,
+  renderCell }) => (
+
+      <TableRow
+        key={String(rowKey)}
+        selected={selected}
+        className={selected ? 'selected' : ''}
+        onClick={(event: React.MouseEvent<globalThis.HTMLTableRowElement>) => onRowClick?.(event, rowData)}
+        onFocus={(event: React.FocusEvent<globalThis.HTMLTableRowElement>) => onRowFocus?.(event, rowData)}
+        onBlur={(event: React.FocusEvent<globalThis.HTMLTableRowElement>) => onRowBlur?.(event, rowData)}
+        style={virtualScrolling ? { 
+          transform: `translateY(${offsetY}px)`,
+          position: 'absolute',
+          top: 0,
+          left: 0,
+          right: 0,
+          height: rowHeight } : undefined}
+      >
+        {selectable && (
+          <TableCell padding="checkbox">
+            <Checkbox
+              checked={selected}
+              onChange={(event) => onSelect(event, rowKey)}
+              onClick={(event) => event.stopPropagation()}
+              inputProps={{ 'aria-label': `select row ${index + 1}` }}
+            />
+          </TableCell>
+        )}
+        {columns.map((column) => {
+          const value = rowData[column.key];
+          return (
+            <TableCell key={column.key} align={column.align || 'left'}>
+              {renderCell 
+                ? renderCell(value, column, rowData, index)
+                : column.render 
+                ? column.render(value, rowData) 
+                : (value as React.ReactNode)
+              }
+            </TableCell>
+          );
+        })}
+      </TableRow>
+);
+
+// Only the rows in view are rendered, positioned by absolute offset inside a
+// spacer sized to the full data set.
+const VirtualisedBody: React.FC<{
+  visibleItems: {
+    items: Record<string, unknown>[];
+    startIndex: number;
+    offsetY: number;
+    totalHeight: number;
+  };
+  rowHeight: number;
+  containerHeight: number;
+  onScroll: (event: React.UIEvent<HTMLDivElement>) => void;
+  renderTableRow: (
+    rowData: Record<string, unknown>,
+    index: number,
+    offsetY?: number,
+  ) => React.ReactNode;
+}> = ({ visibleItems, rowHeight, containerHeight, onScroll, renderTableRow }) => (
+
+    <Box
+      onScroll={onScroll}
+      style={{
+        height: containerHeight,
+        overflow: 'auto',
+        position: 'relative' }}
+    >
+      <TableBody
+        style={{
+          height: visibleItems.totalHeight,
+          position: 'relative' }}
+      >
+        {visibleItems.items.map((rowData, index) => 
+          renderTableRow(rowData, visibleItems.startIndex + index, visibleItems.offsetY + index * rowHeight)
+        )}
+      </TableBody>
+    </Box>
+  
+);
+
+const PlainBody: React.FC<{
+  data: TableBodyProps['data'];
+  renderTableRow: (rowData: Record<string, unknown>, index: number) => React.ReactNode;
+}> = ({ data, renderTableRow }) => (
+
+    <TableBody>
+      {data.map((rowData, index) => renderTableRow(rowData, index))}
+    </TableBody>
+);
+
+// Enhanced Table Body Component  
+export const EnhancedTableBody: React.FC<TableBodyProps> = React.memo(({
+  data,
+  columns,
+  selectedRows = [],
+  onRowClick,
+  onRowFocus,
+  onRowBlur,
+  onSelectionChange,
+  rowKeyExtractor,
+  selectable,
+  renderRow,
+  renderCell,
+  virtualScrolling,
+  containerHeight,
+  rowHeight,
+  overscan = 5 }) => {
+  const renderTableRow = useTableRowRenderer({
+    columns,
+    selectedRows,
+    onRowClick,
+    onRowFocus,
+    onRowBlur,
+    onSelectionChange,
+    rowKeyExtractor,
+    selectable,
+    renderRow,
+    renderCell,
+    virtualScrolling,
+    rowHeight });
+
+  const { visibleItems, handleScroll } = useVirtualScrolling(
+    data, 
+    rowHeight || 40, 
+    typeof containerHeight === 'number' ? containerHeight : 400, 
+    overscan
+  );
+
+  if (virtualScrolling && containerHeight && rowHeight) {
+    return (
+      <VirtualisedBody
+        visibleItems={visibleItems}
+        rowHeight={rowHeight}
+        containerHeight={containerHeight}
+        onScroll={handleScroll}
+        renderTableRow={renderTableRow}
+      />
+    );
+  }
+
+  return (
+    <PlainBody data={data} renderTableRow={renderTableRow} />
+  );
+});
+
+EnhancedTableBody.displayName = 'EnhancedTableBody';
+
+// Main Table Component

package/src/components/data-display/Table/TableStates.tsx

@@ -0,0 +1,21 @@
+import { Box, TableBody, TableCell, TableRow } from '@mui/material';
+import React from 'react';
+
+
+export const NoDataPlaceholder: React.FC = () => (
+  <Box py={4} color="text.secondary">
+    No data available
+  </Box>
+);
+
+export const EmptyRow: React.FC<{ colSpan: number; children: React.ReactNode }> = ({
+  colSpan,
+  children }) => (
+  <TableBody>
+    <TableRow>
+      <TableCell colSpan={colSpan} align="center">
+        {children}
+      </TableCell>
+    </TableRow>
+  </TableBody>
+);

package/src/components/data-display/Timeline/Timeline.stories.tsx

@@ -1,15 +1,13 @@
-import {
-  CheckCircle,
-  Error,
-  Flag,
-  Inventory,
-  LocalShipping,
-  Payment,
-  Person,
-  Schedule,
-  Star,
-  Warning,
-} from '@mui/icons-material';
+import CheckCircle from '@mui/icons-material/CheckCircle';
+import Error from '@mui/icons-material/Error';
+import Flag from '@mui/icons-material/Flag';
+import Inventory from '@mui/icons-material/Inventory';
+import LocalShipping from '@mui/icons-material/LocalShipping';
+import Payment from '@mui/icons-material/Payment';
+import Person from '@mui/icons-material/Person';
+import Schedule from '@mui/icons-material/Schedule';
+import Star from '@mui/icons-material/Star';
+import Warning from '@mui/icons-material/Warning';
 import { Box, Stack, Typography } from '@mui/material';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import React from 'react';

package/src/components/data-display/Timeline/Timeline.test.stories.tsx

@@ -1,4 +1,7 @@
-import { CheckCircle, Error as ErrorIcon, Info, Warning } from '@mui/icons-material';
+import CheckCircle from '@mui/icons-material/CheckCircle';
+import ErrorIcon from '@mui/icons-material/Error';
+import Info from '@mui/icons-material/Info';
+import Warning from '@mui/icons-material/Warning';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { expect, fn,Mock,userEvent, waitFor, within } from 'storybook/test';
 
@@ -101,16 +104,14 @@ export const BasicInteraction: Story = {
 
     // Initially collapsed - description should not be visible
     const firstDescription = sampleItems[0].description!;
-    let descriptionElement = canvas.queryByText(firstDescription);
-    await expect(descriptionElement).not.toBeVisible();
+    await waitFor(() => expect(canvas.queryByText(firstDescription)).not.toBeVisible());
 
     // Click to expand
     await userEvent.click(expandButtons[0]);
 
     // Wait for expansion animation and verify description is now visible
     await waitFor(() => {
-      descriptionElement = canvas.getByText(firstDescription);
-      expect(descriptionElement).toBeVisible();
+      expect(canvas.getByText(firstDescription)).toBeVisible();
     }, { timeout: 3000 });
 
     // Verify the expand button rotated (indicates expanded state)
@@ -123,8 +124,7 @@ export const BasicInteraction: Story = {
 
     // Wait for collapse animation
     await waitFor(() => {
-      descriptionElement = canvas.queryByText(firstDescription);
-      expect(descriptionElement).not.toBeVisible();
+      expect(canvas.queryByText(firstDescription)).not.toBeVisible();
     }, { timeout: 3000 });
 
     // Verify the expand button rotated back
@@ -303,7 +303,7 @@ export const ScreenReader: Story = {
     for (const button of expandButtons) {
       // Button should be focusable
       await expect(button).not.toHaveAttribute('disabled');
-      await expect(button.tabIndex).toBeGreaterThanOrEqual(0);
+      await expect(button).not.toHaveAttribute('tabindex', '-1');
     }
 
     // Verify icons are decorative (aria-hidden) or have labels
@@ -353,14 +353,15 @@ export const FocusManagement: Story = {
     // Test focus retention on expand/collapse
     await expect(expandButtons.length).toBeGreaterThan(0);
     
-    expandButtons[0].focus();
-    await expect(document.activeElement).toBe(expandButtons[0]);
+    // Tab in from the body to reach the first expand button.
+    await userEvent.tab();
+    await waitFor(() => expect(expandButtons[0]).toHaveFocus());
 
     // Click to expand
     await userEvent.click(expandButtons[0]);
 
     // Focus should remain on the button after expansion
-    await expect(document.activeElement).toBe(expandButtons[0]);
+    await waitFor(() => expect(expandButtons[0]).toHaveFocus());
 
     // Wait for expansion to complete
     await waitFor(() => {
@@ -370,12 +371,10 @@ export const FocusManagement: Story = {
 
     // Now action button should be available
     const actionButton = canvas.getByRole('button', { name: /View Details/i });
-    actionButton.focus();
-    await expect(document.activeElement).toBe(actionButton);
 
-    // Click action button and verify focus remains
+    // Clicking focuses the button, so the pre-focus only asserted focus() works.
     await userEvent.click(actionButton);
-    await expect(document.activeElement).toBe(actionButton);
+    await waitFor(() => expect(actionButton).toHaveFocus());
     await expect(args.items[0].action?.onClick).toHaveBeenCalled();
 
     // Test focus on card click
@@ -384,19 +383,18 @@ export const FocusManagement: Story = {
 
     // Test focus trap prevention (focus can move outside component)
     const lastExpandButton = expandButtons[expandButtons.length - 1];
-    lastExpandButton.focus();
+
+    // Walk the keyboard to the last expand button, then once more: focus has to
+    // leave the timeline rather than wrap back into it.
+    await userEvent.click(lastExpandButton);
+    await waitFor(() => expect(lastExpandButton).toHaveFocus());
+
     await userEvent.tab();
+    await waitFor(() => expect(lastExpandButton).not.toHaveFocus());
 
-    // Focus should move outside the timeline component
-    await expect(document.activeElement).not.toBe(lastExpandButton);
-    
-    // Test programmatic focus
-    expandButtons[1].focus();
-    await expect(document.activeElement).toBe(expandButtons[1]);
-    
-    // Click to expand second item
+    // Clicking the second item's expand button focuses it and keeps focus there.
     await userEvent.click(expandButtons[1]);
-    await expect(document.activeElement).toBe(expandButtons[1]);
+    await waitFor(() => expect(expandButtons[1]).toHaveFocus());
     
     // Verify multiple items can be expanded simultaneously
     await waitFor(() => {
@@ -422,17 +420,13 @@ export const ResponsiveDesign: Story = {
     const canvas = within(canvasElement);
 
     // Verify timeline renders on mobile - wait longer for mobile viewport
-    let container: HTMLElement | null = null;
+    // Read the container after the wait rather than assigning to an outer
+    // binding from inside the callback — the callback reruns, so the binding
+    // held whichever value the last retry happened to leave behind.
     await waitFor(() => {
-      container = canvas.getByTestId('timeline-container') as HTMLElement;
-      expect(container).toBeInTheDocument();
-      expect(container).not.toBeNull();
+      expect(canvas.getByTestId('timeline-container')).toBeInTheDocument();
     }, { timeout: 5000 });
-
-    // Assert container is not null for TypeScript
-    if (!container) {
-      throw new Error('Timeline container not found');
-    }
+    const container = canvas.getByTestId('timeline-container');
 
     // Wait for all items to render
     await waitFor(() => {
@@ -725,20 +719,12 @@ export const Performance: Story = {
       await expect(style.animation).toContain('none');
     }
 
-    // Test interaction performance with many items
-    const startTime = Date.now();
-    
-    // Click multiple items quickly
+    // Click multiple items quickly. No wall-clock budget: a 1s ceiling on three
+    // clicks measures how loaded the runner is, not how the component performs.
     await userEvent.click(items[0]);
     await userEvent.click(items[10]);
     await userEvent.click(items[20]);
     
-    const endTime = Date.now();
-    const interactionTime = endTime - startTime;
-    
-    // Interactions should be responsive (under 1 second for 3 clicks)
-    await expect(interactionTime).toBeLessThan(1000);
-    
     // Verify clicks were registered
     await expect(args.onItemClick).toHaveBeenCalledTimes(3);