@12-apps/ui 1.0.0 → 1.3.1

package/src/components/data-display/StatCard/index.ts

@@ -0,0 +1,7 @@
+export { StatCard } from './StatCard';
+export type {
+  StatCardDelta,
+  StatCardDeltaDirection,
+  StatCardDeltaTone,
+  StatCardProps,
+} from './StatCard.types';

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

@@ -1,7 +1,7 @@
 import { Box } from '@mui/material';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useState } from 'react';
-import { expect, fn,userEvent, waitFor, within } from 'storybook/test';
+import { expect, fn, userEvent, waitFor, within } from 'storybook/test';
 
 import { Stepper } from './Stepper';
 import type { Step } from './Stepper.types';
@@ -135,8 +135,8 @@ export const KeyboardNavigation: Story = {
     const firstStepButton = canvas.getByLabelText(/Step 1.*Personal Info/);
 
     // Focus the first step button
-    firstStepButton.focus();
-    await expect(firstStepButton).toHaveFocus();
+    await userEvent.click(firstStepButton);
+    await waitFor(() => expect(firstStepButton).toHaveFocus());
 
     // Press Enter to activate
     await userEvent.keyboard('{Enter}');
@@ -146,17 +146,17 @@ export const KeyboardNavigation: Story = {
 
     // Test Space key
     const thirdStepButton = canvas.getByLabelText(/Step 3.*Payment/);
-    thirdStepButton.focus();
+    await userEvent.click(thirdStepButton);
     await userEvent.keyboard(' ');
     await waitFor(() => {
       expect(args.onStepChange).toHaveBeenCalledWith('step3');
     });
 
     // Test Tab navigation
-    firstStepButton.focus();
+    await userEvent.click(firstStepButton);
     await userEvent.tab();
     const nextButton = canvas.getByLabelText(/Step 2.*Address/);
-    await expect(nextButton).toHaveFocus();
+    await waitFor(() => expect(nextButton).toHaveFocus());
   },
 };
 
@@ -233,23 +233,23 @@ export const FocusManagement: Story = {
     const firstStepButton = canvas.getByLabelText(/Step 1.*Personal Info/);
 
     // Focus external element first
-    externalButton.focus();
-    await expect(externalButton).toHaveFocus();
+    await userEvent.click(externalButton);
+    await waitFor(() => expect(externalButton).toHaveFocus());
 
     // Tab to first step
     await userEvent.tab();
-    await expect(firstStepButton).toHaveFocus();
+    await waitFor(() => expect(firstStepButton).toHaveFocus());
 
     // Click step and verify focus remains
     await userEvent.click(firstStepButton);
-    await expect(firstStepButton).toHaveFocus();
+    await waitFor(() => expect(firstStepButton).toHaveFocus());
 
     // Test that disabled steps don't receive focus
     const steps = canvas.getAllByRole('button');
     for (const step of steps) {
       if (!step.hasAttribute('disabled')) {
-        step.focus();
-        await expect(step).toHaveFocus();
+        await userEvent.click(step);
+        await waitFor(() => expect(step).toHaveFocus());
       }
     }
   },
@@ -390,7 +390,6 @@ export const Performance: Story = {
   },
   play: async ({ args, canvasElement }) => {
     const canvas = within(canvasElement);
-    const startTime = Date.now();
 
     // Verify all 10 steps render
     const stepButtons = canvas.getAllByRole('button');
@@ -405,12 +404,6 @@ export const Performance: Story = {
     await userEvent.click(step3Button);
     await userEvent.click(step7Button);
 
-    const endTime = Date.now();
-    const renderTime = endTime - startTime;
-
-    // Verify interactions completed quickly (less than 1000ms)
-    expect(renderTime).toBeLessThan(1000);
-
     // Verify callback was called for all clicks
     await waitFor(() => {
       expect(args.onStepChange).toHaveBeenCalledTimes(3);

package/src/components/data-display/Stepper/Stepper.tsx

@@ -1,4 +1,4 @@
-import { CheckCircle } from '@mui/icons-material';
+import CheckCircle from '@mui/icons-material/CheckCircle';
 import {
   Box,
   Button,

package/src/components/data-display/Table/Table.helpers.ts

@@ -0,0 +1,31 @@
+import type { TableProps } from './Table.types';
+
+export const TABLE_DEFAULTS: Partial<TableProps> = {
+  variant: 'default',
+  stripeColor: 'neutral',
+  glow: false,
+  pulse: false,
+  hoverable: false,
+  loading: false,
+  density: 'normal',
+  stickyHeader: false,
+  selectable: false,
+  selectedRows: [],
+  sortable: false,
+  virtualScrolling: false,
+  rowHeight: 52,
+  overscan: 5,
+  responsive: false,
+  showColumnToggle: true,
+};
+
+// Strips explicitly-undefined props before the merge, so `prop={undefined}` still
+// falls back to the default as a destructuring default would. Eighteen separate
+// destructuring defaults were most of this component's branch count.
+export const definedProps = (props: TableProps): Partial<TableProps> =>
+  Object.fromEntries(
+    Object.entries(props).filter(([, value]) => value !== undefined),
+  ) as Partial<TableProps>;
+
+// The container + styled table + optional header, shared by the loading, empty
+// and populated renders.

package/src/components/data-display/Table/Table.hooks.ts

@@ -0,0 +1,161 @@
+import { useMediaQuery, useTheme } from '@mui/material';
+import { useCallback, useEffect, useMemo, useState } from 'react';
+
+import type { ColumnConfig, TableProps } from './Table.types';
+
+export const useVirtualScrolling = (
+  data: Record<string, unknown>[],
+  rowHeight: number,
+  containerHeight: number,
+  overscan: number = 5
+) => {
+  const [scrollTop, setScrollTop] = useState(0);
+  
+  const visibleItems = useMemo(() => {
+    const visibleHeight = containerHeight;
+    const startIndex = Math.floor(scrollTop / rowHeight);
+    const endIndex = Math.min(
+      data.length,
+      Math.ceil((scrollTop + visibleHeight) / rowHeight)
+    );
+    
+    const start = Math.max(0, startIndex - overscan);
+    const end = Math.min(data.length, endIndex + overscan);
+    
+    return {
+      startIndex: start,
+      endIndex: end,
+      items: data.slice(start, end),
+      totalHeight: data.length * rowHeight,
+      offsetY: start * rowHeight,
+    };
+  }, [data, rowHeight, containerHeight, scrollTop, overscan]);
+
+  const handleScroll = useCallback((e: React.UIEvent<HTMLDivElement>) => {
+    setScrollTop(e.currentTarget.scrollTop);
+  }, []);
+
+  return { visibleItems, handleScroll };
+};
+
+// Responsive Hook
+
+const useResponsive = (
+  columns: ColumnConfig[],
+  columnPriorities?: number[]
+) => {
+  const theme = useTheme();
+  const isMobile = useMediaQuery(theme.breakpoints.down('md'));
+  const isTablet = useMediaQuery(theme.breakpoints.down('lg'));
+  
+  const [hiddenColumns, setHiddenColumns] = useState<number[]>([]);
+  const [columnMenuAnchor, setColumnMenuAnchor] = useState<null | HTMLElement>(null);
+
+  useEffect(() => {
+    if (!columnPriorities) return;
+    
+    let columnsToHide: number[] = [];
+    
+    if (isMobile) {
+      // Hide lowest priority columns on mobile
+      columnsToHide = columnPriorities
+        .map((priority, index) => ({ priority, index }))
+        .sort((a, b) => b.priority - a.priority)
+        .slice(0, Math.floor(columns.length / 2))
+        .map(item => item.index);
+    } else if (isTablet) {
+      // Hide some columns on tablet
+      columnsToHide = columnPriorities
+        .map((priority, index) => ({ priority, index }))
+        .sort((a, b) => b.priority - a.priority)
+        .slice(0, Math.floor(columns.length / 3))
+        .map(item => item.index);
+    }
+    
+    setHiddenColumns(columnsToHide);
+  }, [isMobile, isTablet, columnPriorities, columns.length]);
+
+  const visibleColumns = columns.filter((_, index) => !hiddenColumns.includes(index));
+
+  return {
+    visibleColumns,
+    hiddenColumns,
+    isMobile,
+    columnMenuAnchor,
+    setColumnMenuAnchor,
+    setHiddenColumns,
+  };
+};
+
+// Enhanced Table Header Component
+// Visible/hidden column split for responsive mode, plus row selection.
+export const useTableSelection = ({
+  columns,
+  data,
+  responsive,
+  columnPriorities,
+  selectedRows,
+  rowKeyExtractor,
+  onSelectionChange,
+}: {
+  columns?: ColumnConfig[];
+  data: TableProps['data'];
+  responsive?: boolean;
+  columnPriorities?: number[];
+  selectedRows: (string | number)[];
+  rowKeyExtractor?: (row: Record<string, unknown>, index: number) => string | number;
+  onSelectionChange?: TableProps['onSelectionChange'];
+}) => {
+    
+  // Use responsive hook if responsive mode is enabled
+  const {
+    visibleColumns,
+    hiddenColumns,
+    isMobile,
+    columnMenuAnchor,
+    setColumnMenuAnchor,
+    setHiddenColumns,
+  } = useResponsive(
+    columns || [],
+    responsive ? columnPriorities : undefined
+  );
+
+  // Handle selection changes
+  const handleSelectionChange = useCallback((rowKey: string | number, selected: boolean) => {
+    if (!onSelectionChange) return;
+    
+    let newSelection: (string | number)[];
+    if (selected) {
+      newSelection = [...selectedRows, rowKey];
+    } else {
+      newSelection = selectedRows.filter(key => key !== rowKey);
+    }
+    onSelectionChange(newSelection);
+  }, [selectedRows, onSelectionChange]);
+
+  const handleSelectAll = useCallback((selected: boolean) => {
+    if (!onSelectionChange || !data) return;
+    
+    if (selected) {
+      const allKeys = data.map((rowData, index) => 
+        rowKeyExtractor ? rowKeyExtractor(rowData, index) : (rowData.id as string | number) || index
+      );
+      onSelectionChange(allKeys);
+    } else {
+      onSelectionChange([]);
+    }
+  }, [data, onSelectionChange, rowKeyExtractor]);
+
+  // Loading state
+
+  return {
+    visibleColumns,
+    hiddenColumns,
+    isMobile,
+    columnMenuAnchor,
+    setColumnMenuAnchor,
+    setHiddenColumns,
+    handleSelectionChange,
+    handleSelectAll,
+  };
+};

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

@@ -1,4 +1,6 @@
-import { Delete as DeleteIcon, Edit as EditIcon, Star as StarIcon } from '@mui/icons-material';
+import DeleteIcon from '@mui/icons-material/Delete';
+import EditIcon from '@mui/icons-material/Edit';
+import StarIcon from '@mui/icons-material/Star';
 import {
   Avatar,
   Box,

package/src/components/data-display/Table/Table.styles.ts

@@ -0,0 +1,223 @@
+import { alpha, keyframes } from '@mui/material';
+import type { CSSObject, Theme } from '@mui/material/styles';
+
+import type { TableDensity, TableStripeColor } from './Table.types';
+
+const pulseAnimation = keyframes`
+  0% {
+    box-shadow: 0 0 0 0 currentColor;
+    opacity: 1;
+  }
+  70% {
+    box-shadow: 0 0 0 10px currentColor;
+    opacity: 0;
+  }
+  100% {
+    box-shadow: 0 0 0 0 currentColor;
+    opacity: 0;
+  }
+`;
+
+// Density configurations
+const getDensityConfig = (density: TableDensity = 'normal') => {
+  const configs = {
+    compact: {
+      rowHeight: 36,
+      cellPadding: '6px 12px',
+      fontSize: '0.8125rem',
+      headerPadding: '8px 12px' },
+    normal: {
+      rowHeight: 52,
+      cellPadding: '12px 16px',
+      fontSize: '0.875rem',
+      headerPadding: '16px 16px' },
+    comfortable: {
+      rowHeight: 68,
+      cellPadding: '18px 24px',
+      fontSize: '0.875rem',
+      headerPadding: '20px 24px' } };
+  return configs[density];
+};
+
+const getStripeColorFromTheme = (theme: { palette: { primary: { main: string }; secondary: { main: string }; info: { main: string }; success: { main: string }; warning: { main: string }; error: { main: string }; action: { hover: string } } }, stripeColor: TableStripeColor = 'neutral') => {
+  const colorMap: Record<TableStripeColor, string> = {
+    primary: theme.palette.primary.main,
+    secondary: theme.palette.secondary.main,
+    info: theme.palette.info.main,
+    success: theme.palette.success.main,
+    warning: theme.palette.warning.main,
+    error: theme.palette.error.main,
+    neutral: theme.palette.action.hover };
+  return colorMap[stripeColor];
+};
+
+// One variant applies at a time, so a lookup replaces the mutually exclusive
+// spreads.
+const TABLE_VARIANTS: Record<string, (args: VariantArgs) => CSSObject> = {
+  default: ({ theme }) => ({
+      backgroundColor: theme.palette.background.paper,
+      '& .MuiTableHead-root': {
+        backgroundColor: alpha(theme.palette.primary.main, 0.1) } }),
+  striped: ({ theme, stripeColor }) => ({
+      backgroundColor: theme.palette.background.paper,
+      '& .MuiTableBody-root .MuiTableRow-root:nth-of-type(even)': {
+        backgroundColor: alpha(getStripeColorFromTheme(theme, stripeColor), stripeColor === 'neutral' ? 0.5 : 0.15) } }),
+  glass: ({ theme }) => ({
+      backgroundColor: alpha(theme.palette.background.paper, 0.1),
+      backdropFilter: 'blur(20px)',
+      border: `1px solid ${alpha(theme.palette.divider, 0.2)}` }),
+  minimal: ({ theme }) => ({
+      backgroundColor: 'transparent',
+      '& .MuiTableCell-root': {
+        borderBottom: `1px solid ${alpha(theme.palette.divider, 0.1)}` } }),
+  gradient: ({ theme }) => ({
+      background: `linear-gradient(135deg, ${alpha(theme.palette.primary.main, 0.05)}, ${alpha(theme.palette.secondary.main, 0.05)})`,
+      border: `1px solid ${alpha(theme.palette.divider, 0.2)}`,
+      '& .MuiTableHead-root': {
+        background: `linear-gradient(135deg, ${alpha(theme.palette.primary.main, 0.15)}, ${alpha(theme.palette.secondary.main, 0.15)})` },
+      '& .MuiTableCell-root': {
+        borderBottom: `1px solid ${alpha(theme.palette.divider, 0.15)}` } }) };
+
+type VariantArgs = {
+  theme: Theme;
+  densityConfig: ReturnType<typeof getDensityConfig>;
+  stripeColor?: TableStripeColor;
+};
+
+const tableVariantStyles = (args: VariantArgs, customVariant?: string): CSSObject =>
+  customVariant ? (TABLE_VARIANTS[customVariant]?.(args) ?? {}) : {};
+
+// Sticky headers and row hover are independent of the variant.
+const stickyHeaderStyles = (
+  theme: Theme,
+  densityConfig: ReturnType<typeof getDensityConfig>,
+): CSSObject => ({
+      '& .MuiTableHead-root': {
+        position: 'sticky',
+        top: 0,
+        zIndex: 100,
+        backgroundColor: theme.palette.background.paper,
+        '& .MuiTableCell-root': {
+          borderBottom: `2px solid ${theme.palette.divider}`,
+          fontWeight: 600,
+          padding: densityConfig.headerPadding } } });
+
+const hoverableRowStyles = (theme: Theme): CSSObject => ({
+      '& .MuiTableBody-root .MuiTableRow-root:hover': {
+        backgroundColor: alpha(theme.palette.primary.main, 0.08),
+        cursor: 'pointer',
+        transition: 'background-color 0.15s ease-in-out' } });
+
+// glow and pulse combine into three distinct looks, spelled out rather than
+// layered — the glow-only shadow differs from the one used when both are on.
+const emphasisStyles = (theme: Theme, glow?: boolean, pulse?: boolean): CSSObject => {
+  if (glow && pulse) return ({
+      position: 'relative',
+      boxShadow: `0 0 20px 5px ${alpha(theme.palette.primary.main, 0.3)} !important`,
+      filter: 'brightness(1.05)',
+      '&::after': {
+        content: '""',
+        position: 'absolute',
+        top: 0,
+        left: 0,
+        right: 0,
+        bottom: 0,
+        borderRadius: 'inherit',
+        backgroundColor: theme.palette.primary.main,
+        opacity: 0.1,
+        animation: `${pulseAnimation} 2s infinite`,
+        pointerEvents: 'none',
+        zIndex: -1 } });
+  if (glow) return ({
+      boxShadow: `0 0 20px 5px ${alpha(theme.palette.primary.main, 0.3)} !important`,
+      filter: 'brightness(1.05)' });
+  if (pulse) return ({
+      position: 'relative',
+      '&::after': {
+        content: '""',
+        position: 'absolute',
+        top: 0,
+        left: 0,
+        right: 0,
+        bottom: 0,
+        borderRadius: 'inherit',
+        backgroundColor: theme.palette.primary.main,
+        opacity: 0.1,
+        animation: `${pulseAnimation} 2s infinite`,
+        pointerEvents: 'none',
+        zIndex: -1 } });
+
+  return {};
+};
+
+// The table's own styling, lifted out so the styled() callback just forwards
+// its props.
+export const tableStyles = ({
+  theme,
+  customVariant,
+  glow,
+  pulse,
+  hoverable,
+  density,
+  stickyHeader,
+  stripeColor = 'neutral' }: {
+  theme: Theme;
+  customVariant?: string;
+  glow?: boolean;
+  pulse?: boolean;
+  hoverable?: boolean;
+  density?: TableDensity;
+  stickyHeader?: boolean;
+  stripeColor?: TableStripeColor;
+}): CSSObject => {
+  const densityConfig = getDensityConfig(density);
+  
+  return {
+    borderRadius: theme.spacing(1),
+    overflow: 'hidden',
+    transition: 'all 0.3s ease',
+    position: 'relative',
+
+    // Density styles
+    '& .MuiTableCell-root': {
+      padding: densityConfig.cellPadding,
+      fontSize: densityConfig.fontSize,
+      height: densityConfig.rowHeight },
+
+    // Sticky header
+    ...tableVariantStyles({ theme, densityConfig, stripeColor }, customVariant),
+    ...(stickyHeader ? stickyHeaderStyles(theme, densityConfig) : {}),
+    ...(hoverable ? hoverableRowStyles(theme) : {}),
+    ...emphasisStyles(theme, glow, pulse),
+
+
+    // Variant styles
+
+
+
+
+
+
+
+
+
+
+    // Hoverable rows
+
+
+    // Selection styles
+    '& .MuiTableRow-root.selected': {
+      backgroundColor: alpha(theme.palette.primary.main, 0.12),
+      '&:hover': {
+        backgroundColor: alpha(theme.palette.primary.main, 0.16) } },
+
+    // Glow effect
+
+
+    // Pulse animation
+
+
+    // Both glow and pulse
+
+  };
+}

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

@@ -1,7 +1,7 @@
 import { Box, Typography } from '@mui/material';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useState } from 'react';
-import { expect, userEvent, waitFor,within } from 'storybook/test';
+import { expect, userEvent, waitFor, within } from 'storybook/test';
 
 import { Table } from './Table';
 import type { ColumnConfig } from './Table.types';
@@ -149,7 +149,7 @@ export const KeyboardNavigation: Story = {
     // Test Tab navigation
     await userEvent.tab();
     const firstCheckbox = canvas.getAllByRole('checkbox')[0];
-    await expect(firstCheckbox).toHaveFocus();
+    await waitFor(() => expect(firstCheckbox).toHaveFocus());
   },
 };
 
@@ -201,11 +201,11 @@ export const FocusManagement: Story = {
     const canvas = within(canvasElement);
 
     const beforeButton = canvas.getByTestId('before');
-    beforeButton.focus();
+    await userEvent.click(beforeButton);
 
     await userEvent.tab();
     const firstCheckbox = canvas.getAllByRole('checkbox')[0];
-    await expect(firstCheckbox).toHaveFocus();
+    await waitFor(() => expect(firstCheckbox).toHaveFocus());
   },
 };