@12-apps/ui 1.0.0

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

@@ -0,0 +1,328 @@
+import { CheckCircle } from '@mui/icons-material';
+import {
+  Box,
+  Button,
+  styled,
+  Typography,
+} from '@mui/material';
+import React from 'react';
+
+import type { Step, StepItemProps, StepperProps } from './Stepper.types';
+
+const StepperRoot = styled(Box, {
+  shouldForwardProp: (prop) => prop !== 'orientation',
+})<{ orientation: 'horizontal' | 'vertical'; component?: React.ElementType }>(({ orientation }) => ({
+  display: 'flex',
+  flexDirection: orientation === 'horizontal' ? 'row' : 'column',
+  // Use flex-start to align all step circles at the same vertical position
+  alignItems: 'flex-start',
+}));
+
+const StepItem = styled(Box, {
+  shouldForwardProp: (prop) => !['orientation', 'isLast'].includes(prop as string),
+})<{ orientation: 'horizontal' | 'vertical'; isLast: boolean }>(({ orientation, isLast }) => ({
+  display: 'flex',
+  // For horizontal: row layout so connector appears beside step content
+  // For vertical: column layout so connector appears below step content
+  flexDirection: orientation === 'horizontal' ? 'row' : 'column',
+  // For horizontal: flex-start to keep circles aligned at top
+  // For vertical: center to align connector with centered circle
+  alignItems: orientation === 'horizontal' ? 'flex-start' : 'center',
+  flex: orientation === 'horizontal' && !isLast ? 1 : 'none',
+  position: 'relative',
+  // For vertical: ensure consistent width for proper centering
+  ...(orientation === 'vertical' && {
+    width: '100%',
+  }),
+}));
+
+/** Circle diameter per size. */
+const CIRCLE_SIZE = { sm: 32, md: 48 } as const;
+
+const StepButton = styled(Button, {
+  shouldForwardProp: (prop) =>
+    !['isActive', 'isCompleted', 'clickable', 'stepSize'].includes(prop as string),
+})<{ isActive: boolean; isCompleted: boolean; clickable: boolean; stepSize: 'sm' | 'md' }>(
+  ({ theme, isActive, isCompleted, clickable, stepSize }) => ({
+    minWidth: CIRCLE_SIZE[stepSize],
+    width: CIRCLE_SIZE[stepSize],
+    height: CIRCLE_SIZE[stepSize],
+    borderRadius: '50%',
+    padding: 0,
+    backgroundColor: isCompleted
+      ? theme.palette.primary.main
+      : isActive
+      ? theme.palette.primary.main
+      : theme.palette.grey[300],
+    color: isCompleted || isActive ? theme.palette.primary.contrastText : theme.palette.text.primary,
+    cursor: clickable ? 'pointer' : 'default',
+    pointerEvents: clickable ? 'auto' : 'none',
+    transition: theme.transitions.create(['background-color', 'transform'], {
+      duration: theme.transitions.duration.short,
+    }),
+    '&:hover': clickable
+      ? {
+          backgroundColor: isCompleted
+            ? theme.palette.primary.dark
+            : isActive
+            ? theme.palette.primary.dark
+            : theme.palette.grey[400],
+          transform: 'scale(1.05)',
+        }
+      : {},
+    '&:disabled': {
+      backgroundColor: theme.palette.grey[300],
+      color: theme.palette.text.disabled,
+    },
+  }),
+);
+
+const StepConnector = styled(Box, {
+  shouldForwardProp: (prop) =>
+    !['orientation', 'isCompleted', 'size'].includes(prop as string),
+})<{ orientation: 'horizontal' | 'vertical'; isCompleted: boolean; size: 'sm' | 'md' }>(
+  ({ theme, orientation, isCompleted, size }) => ({
+    backgroundColor: isCompleted ? theme.palette.primary.main : theme.palette.grey[300],
+    transition: theme.transitions.create('background-color', {
+      duration: theme.transitions.duration.short,
+    }),
+    ...(orientation === 'horizontal'
+      ? {
+          flex: 1,
+          height: 2,
+          // Vertically centered on the circle (circle/2 - 1 for the 2px line).
+          marginTop: CIRCLE_SIZE[size] / 2 - 1,
+          marginLeft: 8,
+          marginRight: 8,
+          minWidth: 24,
+        }
+      : {
+          width: 2,
+          height: 32,
+          marginTop: 8,
+          marginBottom: 8,
+          // Use margin auto to center horizontally
+          marginLeft: 'auto',
+          marginRight: 'auto',
+        }),
+  }),
+);
+
+const StepLabel = styled(Box, {
+  shouldForwardProp: (prop) => prop !== 'orientation',
+})<{ orientation: 'horizontal' | 'vertical' }>(({ orientation }) => ({
+  textAlign: 'center',
+  marginTop: orientation === 'horizontal' ? 8 : 0,
+}));
+
+type StepSize = 'sm' | 'md';
+type LabelVariant = 'caption' | 'body2';
+
+/** Space-joined state classes for a step (active / completed / optional). */
+function stepClasses(isActive: boolean, isCompleted: boolean, optional?: boolean): string {
+  return [
+    isActive && 'stepper-step-active',
+    isCompleted && 'stepper-step-completed',
+    optional && 'stepper-step-optional',
+  ]
+    .filter(Boolean)
+    .join(' ');
+}
+
+/** The circle content-column width per orientation/size. */
+function contentSx(orientation: 'horizontal' | 'vertical', size: StepSize) {
+  return orientation === 'horizontal'
+    ? { minWidth: size === 'sm' ? 56 : 80, maxWidth: 150, flex: '0 1 auto' }
+    : { flexShrink: 0 };
+}
+
+interface StepPartProps {
+  step: Step;
+  index: number;
+  isActive: boolean;
+  size: StepSize;
+  labelVariant: LabelVariant;
+}
+
+/** The step circle: a check when completed, otherwise the 1-based index. */
+const StepCircle: React.FC<
+  StepPartProps & { isCompleted: boolean; isClickable: boolean; onClick: () => void }
+> = ({ step, index, isActive, isCompleted, isClickable, size, labelVariant, onClick }) => {
+  const state = isCompleted ? ' (completed)' : isActive ? ' (current)' : '';
+  return (
+    <StepButton
+      isActive={isActive}
+      isCompleted={isCompleted}
+      clickable={isClickable}
+      stepSize={size}
+      onClick={onClick}
+      disabled={step.disabled}
+      aria-current={isActive ? 'step' : undefined}
+      aria-label={`Step ${index + 1}: ${step.label}${step.optional ? ' (optional)' : ''}${state}`}
+      data-testid={`stepper-step-icon-${index}`}
+    >
+      {isCompleted ? (
+        <CheckCircle sx={{ fontSize: size === 'sm' ? 18 : 24 }} />
+      ) : (
+        <Typography variant={labelVariant} fontWeight="bold">
+          {index + 1}
+        </Typography>
+      )}
+    </StepButton>
+  );
+};
+
+/** The step label block: title, optional marker, and description. */
+const StepLabelBlock: React.FC<StepPartProps & { orientation: 'horizontal' | 'vertical' }> = ({
+  step,
+  index,
+  isActive,
+  orientation,
+  size,
+  labelVariant,
+}) => (
+  <StepLabel
+    orientation={orientation}
+    data-testid={`stepper-step-label-${index}`}
+    sx={size === 'sm' && orientation === 'horizontal' ? { mt: '2px' } : undefined}
+  >
+    <Typography
+      variant={labelVariant}
+      fontWeight={isActive ? 'bold' : 'normal'}
+      color={isActive ? 'primary' : 'textPrimary'}
+    >
+      {step.label}
+      {step.optional && (
+        <Typography component="span" variant="caption" color="textSecondary" sx={{ ml: 1 }}>
+          (optional)
+        </Typography>
+      )}
+    </Typography>
+    {step.description && (
+      <Typography variant="caption" color="textSecondary" display="block">
+        {step.description}
+      </Typography>
+    )}
+  </StepLabel>
+);
+
+const StepperItem: React.FC<StepItemProps> = ({
+  step,
+  index,
+  isActive,
+  isCompleted,
+  isLast,
+  orientation,
+  size,
+  variant,
+  clickable,
+  onStepClick,
+  renderConnector,
+  nextStep,
+}) => {
+  const labelVariant: LabelVariant = size === 'sm' ? 'caption' : 'body2';
+  const isClickable = Boolean(clickable) && !step.disabled && (variant === 'non-linear' || !isActive);
+  const handleStepClick = () => {
+    if (isClickable && onStepClick) onStepClick(step.id);
+  };
+  const connector =
+    renderConnector && nextStep ? (
+      renderConnector(step, nextStep, { completed: isCompleted, active: isActive })
+    ) : (
+      <StepConnector orientation={orientation} isCompleted={isCompleted} size={size} data-testid={`stepper-connector-${index}`} />
+    );
+
+  return (
+    <StepItem
+      orientation={orientation}
+      isLast={isLast}
+      role="listitem"
+      data-testid={`stepper-step-${index}`}
+      className={stepClasses(isActive, isCompleted, step.optional)}
+    >
+      <Box
+        display="flex"
+        flexDirection="column"
+        alignItems="center"
+        data-testid={`stepper-step-content-${index}`}
+        sx={contentSx(orientation, size)}
+      >
+        <StepCircle
+          step={step}
+          index={index}
+          isActive={isActive}
+          isCompleted={isCompleted}
+          isClickable={isClickable}
+          size={size}
+          labelVariant={labelVariant}
+          onClick={handleStepClick}
+        />
+        <StepLabelBlock
+          step={step}
+          index={index}
+          isActive={isActive}
+          orientation={orientation}
+          size={size}
+          labelVariant={labelVariant}
+        />
+      </Box>
+      {!isLast && connector}
+    </StepItem>
+  );
+};
+
+export const Stepper: React.FC<StepperProps> = ({
+  steps,
+  activeId,
+  completed = new Set(),
+  orientation = 'horizontal',
+  size = 'md',
+  variant = 'linear',
+  onStepChange,
+  clickable,
+  renderConnector,
+  className,
+  'data-testid': dataTestId,
+}) => {
+  // Determine clickable behavior
+  const isClickable = clickable ?? variant === 'non-linear';
+
+  return (
+    <StepperRoot
+      component="ol"
+      orientation={orientation}
+      className={className}
+      data-testid={dataTestId || 'stepper-container'}
+      sx={{
+        listStyle: 'none',
+        padding: 0,
+        margin: 0,
+      }}
+    >
+      {steps.map((step, index) => {
+        const isActive = step.id === activeId;
+        const isCompleted = completed.has(step.id);
+        const isLast = index === steps.length - 1;
+        const nextStep = !isLast ? steps[index + 1] : undefined;
+
+        return (
+          <StepperItem
+            key={step.id}
+            step={step}
+            index={index}
+            isActive={isActive}
+            isCompleted={isCompleted}
+            isLast={isLast}
+            orientation={orientation}
+            size={size}
+            variant={variant}
+            clickable={isClickable}
+            onStepClick={onStepChange}
+            renderConnector={renderConnector}
+            nextStep={nextStep}
+          />
+        );
+      })}
+    </StepperRoot>
+  );
+};

package/src/components/data-display/Stepper/Stepper.types.ts

@@ -0,0 +1,97 @@
+import type { ReactNode } from 'react';
+
+export interface Step {
+  id: string;
+  label: string;
+  description?: string;
+  optional?: boolean;
+  disabled?: boolean;
+}
+
+export interface ConnectorState {
+  completed: boolean;
+  active: boolean;
+}
+
+export interface StepperProps {
+  /**
+   * Array of step configurations defining the stepper flow
+   */
+  steps: Step[];
+  
+  /**
+   * ID of the currently active step
+   */
+  activeId: string;
+  
+  /**
+   * Set of step IDs that have been completed
+   */
+  completed?: Set<string>;
+  
+  /**
+   * Display orientation of the stepper
+   * @default 'horizontal'
+   */
+  orientation?: 'horizontal' | 'vertical';
+
+  /**
+   * Visual size of the step circles + labels. `'sm'` is a compact variant that
+   * takes far less vertical space — useful above the fold on mobile checkouts.
+   * @default 'md'
+   */
+  size?: 'sm' | 'md';
+  
+  /**
+   * Navigation variant controlling step access
+   * - 'linear': Users can only progress to next step after completing current
+   * - 'non-linear': Users can jump to any enabled step
+   * @default 'linear'
+   */
+  variant?: 'linear' | 'non-linear';
+  
+  /**
+   * Callback fired when a step is clicked or navigated to
+   */
+  onStepChange?: (id: string) => void;
+  
+  /**
+   * Whether steps are clickable for navigation
+   * @default false for linear, true for non-linear
+   */
+  clickable?: boolean;
+  
+  /**
+   * Custom connector renderer between steps
+   */
+  renderConnector?: (
+    from: Step,
+    to: Step,
+    state: ConnectorState,
+  ) => ReactNode;
+  
+  /**
+   * Additional CSS class name
+   */
+  className?: string;
+  
+  /**
+   * Test identifier
+   */
+  'data-testid'?: string;
+}
+
+export interface StepItemProps {
+  step: Step;
+  index: number;
+  isActive: boolean;
+  isCompleted: boolean;
+  isLast: boolean;
+  orientation: 'horizontal' | 'vertical';
+  size: 'sm' | 'md';
+  variant: 'linear' | 'non-linear';
+  clickable: boolean;
+  onStepClick?: (id: string) => void;
+  renderConnector?: StepperProps['renderConnector'];
+  nextStep?: Step;
+}

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

@@ -0,0 +1,2 @@
+export { Stepper } from './Stepper';
+export type { ConnectorState, Step, StepItemProps,StepperProps } from './Stepper.types';

package/src/components/data-display/Table/Table.md

@@ -0,0 +1,243 @@
+# Table Component
+
+A comprehensive data table component with advanced features including sorting, filtering, pagination, row selection, virtual scrolling, and responsive design.
+
+## Usage
+
+```tsx
+import { Table } from '@procurement/ui';
+
+// Basic usage with columns and data
+<Table
+  columns={columns}
+  data={data}
+  sortable
+  selectable
+/>
+
+// With MUI TableContainer (backward compatible)
+<TableContainer component={Paper}>
+  <Table>
+    <TableHead>
+      <TableRow>
+        <TableCell>Name</TableCell>
+        <TableCell>Email</TableCell>
+      </TableRow>
+    </TableHead>
+    <TableBody>
+      {data.map(row => (
+        <TableRow key={row.id}>
+          <TableCell>{row.name}</TableCell>
+          <TableCell>{row.email}</TableCell>
+        </TableRow>
+      ))}
+    </TableBody>
+  </Table>
+</TableContainer>
+```
+
+## Props
+
+### Core Props
+
+- **columns** `ColumnConfig[]` - Column definitions for the table
+- **data** `any[]` - Array of data objects to display
+- **variant** `'default' | 'striped' | 'glass' | 'minimal' | 'gradient'` - Visual style variant
+- **density** `'compact' | 'normal' | 'comfortable'` - Row height/padding density
+
+### Features
+
+- **sortable** `boolean` - Enable column sorting functionality
+- **sortConfig** `SortConfig` - Current sort configuration
+- **onSortChange** `(key: string, direction: 'asc' | 'desc') => void` - Sort change handler
+- **selectable** `boolean` - Enable row selection
+- **selectedRows** `(string | number)[]` - Currently selected row IDs
+- **onSelectionChange** `(rows: (string | number)[]) => void` - Selection change handler
+- **stickyHeader** `boolean` - Keep header fixed when scrolling
+- **responsive** `boolean` - Enable responsive column hiding
+- **virtualScrolling** `boolean` - Enable virtual scrolling for large datasets
+- **loading** `boolean` - Show loading state
+- **hoverable** `boolean` - Enable row hover effects
+
+### Visual Effects
+
+- **glow** `boolean` - Add glow effect to the table
+- **pulse** `boolean` - Add pulse animation effect
+- **glass** `boolean` - Apply glassmorphism effect
+
+### Container Props
+
+- **containerHeight** `number` - Fixed height for scrollable container
+- **rowHeight** `number` - Height per row (for virtual scrolling)
+- **overscan** `number` - Number of rows to render outside viewport
+
+### Column Configuration
+
+```tsx
+interface ColumnConfig {
+  key: string;
+  label: string;
+  sortable?: boolean;
+  width?: number | string;
+  align?: 'left' | 'center' | 'right';
+  priority?: number; // For responsive hiding
+  render?: (value: any, rowData: any) => React.ReactNode;
+}
+```
+
+## Features
+
+### Sorting
+Enable sortable columns with click-to-sort functionality:
+
+```tsx
+<Table
+  columns={columns}
+  data={data}
+  sortable
+  sortConfig={sortConfig}
+  onSortChange={(key, direction) => handleSort(key, direction)}
+/>
+```
+
+### Row Selection
+Support single or multiple row selection:
+
+```tsx
+<Table
+  columns={columns}
+  data={data}
+  selectable
+  selectedRows={selectedRows}
+  onSelectionChange={setSelectedRows}
+/>
+```
+
+### Virtual Scrolling
+Handle large datasets efficiently:
+
+```tsx
+<Table
+  columns={columns}
+  data={largeDataset} // 10,000+ rows
+  virtualScrolling
+  rowHeight={52}
+  containerHeight={400}
+  overscan={10}
+/>
+```
+
+### Responsive Design
+Automatically hide/show columns based on viewport:
+
+```tsx
+<Table
+  columns={columns}
+  data={data}
+  responsive
+  columnPriorities={[1, 2, 3, 4, 5]}
+  showColumnToggle
+/>
+```
+
+### Custom Cell Rendering
+Customize how cells are rendered:
+
+```tsx
+const columns = [
+  {
+    key: 'status',
+    label: 'Status',
+    render: (value) => (
+      <Chip 
+        label={value} 
+        color={value === 'Active' ? 'success' : 'default'}
+      />
+    )
+  }
+];
+```
+
+## Variants
+
+- **default** - Standard table appearance
+- **striped** - Alternating row backgrounds
+- **glass** - Glassmorphism effect with transparency
+- **minimal** - Clean, minimal borders
+- **gradient** - Gradient background effect
+
+## Density Options
+
+- **compact** - Reduced padding for more data density
+- **normal** - Standard padding (default)
+- **comfortable** - Extra padding for improved readability
+
+## Accessibility
+
+- Proper `role="table"` attributes
+- `aria-sort` for sortable columns
+- `aria-selected` for selectable rows
+- Keyboard navigation support (Tab, Arrow keys)
+- Screen reader announcements for interactions
+- Focus management for interactive elements
+
+## Best Practices
+
+1. **Large Datasets**: Use virtual scrolling for datasets over 100 rows
+2. **Responsive Tables**: Set column priorities based on importance
+3. **Custom Rendering**: Use render functions for complex cell content
+4. **Performance**: Enable `virtualScrolling` for large datasets
+5. **Accessibility**: Always provide column labels and proper ARIA attributes
+6. **Loading States**: Show loading indicator during data fetching
+7. **Empty States**: Provide meaningful empty state messages
+
+## Examples
+
+### Complete Feature Set
+```tsx
+<Table
+  columns={columns}
+  data={data}
+  
+  // Features
+  sortable
+  selectable
+  stickyHeader
+  responsive
+  virtualScrolling
+  
+  // Visual
+  variant="gradient"
+  density="comfortable"
+  glow
+  hoverable
+  
+  // Handlers
+  onSortChange={handleSort}
+  onSelectionChange={handleSelection}
+  onRowClick={handleRowClick}
+  
+  // Container
+  containerHeight={400}
+/>
+```
+
+### Backward Compatible Usage
+```tsx
+<TableContainer>
+  <Table variant="striped" hoverable>
+    <TableHead>
+      <TableRow>
+        <TableCell>Header 1</TableCell>
+        <TableCell>Header 2</TableCell>
+      </TableRow>
+    </TableHead>
+    <TableBody>
+      <TableRow>
+        <TableCell>Data 1</TableCell>
+        <TableCell>Data 2</TableCell>
+      </TableRow>
+    </TableBody>
+  </Table>
+</TableContainer>
+```