@12-apps/ui 1.0.0

package/src/components/utility/VirtualList/VirtualList.tsx

@@ -0,0 +1,369 @@
+import { Box } from '@mui/material';
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import type { VirtualGridProps, VirtualListProps } from './VirtualList.types';
+
+export const VirtualList: React.FC<VirtualListProps> = ({
+  items,
+  variant = 'fixed',
+  height,
+  width = '100%',
+  itemHeight = 40,
+  estimatedItemHeight = 40,
+  overscan = 5,
+  renderItem,
+  onScroll,
+  className,
+  style,
+  'data-testid': dataTestId,
+  'aria-label': ariaLabel,
+  scrollContainerRef,
+  disableInternalScroll = false,
+}) => {
+  const [scrollTop, setScrollTop] = useState(0);
+  const internalContainerRef = useRef<HTMLDivElement>(null);
+  const _containerRef = scrollContainerRef || internalContainerRef;
+  const itemHeights = useRef<Map<number, number>>(new Map());
+
+  const getItemHeight = useCallback(
+    (index: number): number => {
+      if (variant === 'fixed') {
+        return itemHeight;
+      }
+
+      if (variant === 'variable') {
+        const item = items[index];
+        if (item?.height) {
+          return item.height;
+        }
+
+        const measuredHeight = itemHeights.current.get(index);
+        if (measuredHeight) {
+          return measuredHeight;
+        }
+
+        return estimatedItemHeight;
+      }
+
+      return itemHeight;
+    },
+    [variant, itemHeight, estimatedItemHeight, items],
+  );
+
+  const getTotalHeight = useMemo(() => {
+    if (variant === 'fixed') {
+      return items.length * itemHeight;
+    }
+
+    let totalHeight = 0;
+    for (let i = 0; i < items.length; i++) {
+      totalHeight += getItemHeight(i);
+    }
+    return totalHeight;
+  }, [items.length, variant, itemHeight, getItemHeight]);
+
+  const getVisibleRange = useMemo(() => {
+    if (variant === 'fixed') {
+      const startIndex = Math.max(0, Math.floor(scrollTop / itemHeight) - overscan);
+      const endIndex = Math.min(
+        items.length - 1,
+        Math.ceil((scrollTop + height) / itemHeight) + overscan,
+      );
+      return { startIndex, endIndex };
+    }
+
+    // For variable height items
+    let accumulatedHeight = 0;
+    let startIndex = 0;
+    let endIndex = items.length - 1;
+
+    // Find start index
+    for (let i = 0; i < items.length; i++) {
+      if (accumulatedHeight + getItemHeight(i) > scrollTop) {
+        startIndex = Math.max(0, i - overscan);
+        break;
+      }
+      accumulatedHeight += getItemHeight(i);
+    }
+
+    // Find end index
+    accumulatedHeight = 0;
+    for (let i = 0; i <= startIndex; i++) {
+      accumulatedHeight += getItemHeight(i);
+    }
+
+    for (let i = startIndex; i < items.length; i++) {
+      if (accumulatedHeight > scrollTop + height) {
+        endIndex = Math.min(items.length - 1, i + overscan);
+        break;
+      }
+      accumulatedHeight += getItemHeight(i);
+    }
+
+    return { startIndex, endIndex };
+  }, [scrollTop, height, variant, itemHeight, overscan, items.length, getItemHeight]);
+
+  const getItemOffset = useCallback(
+    (index: number): number => {
+      if (variant === 'fixed') {
+        return index * itemHeight;
+      }
+
+      let offset = 0;
+      for (let i = 0; i < index; i++) {
+        offset += getItemHeight(i);
+      }
+      return offset;
+    },
+    [variant, itemHeight, getItemHeight],
+  );
+
+  const handleScroll = useCallback(
+    (event: React.UIEvent<HTMLDivElement> | Event) => {
+      // Handle both React synthetic events and native DOM events
+      const target =
+        (event as React.UIEvent<HTMLDivElement>).currentTarget ||
+        (event as Event).target;
+      const newScrollTop = (target as HTMLElement).scrollTop;
+      setScrollTop(newScrollTop);
+      onScroll?.(newScrollTop);
+    },
+    [onScroll],
+  );
+
+  // Listen to external scroll container if provided
+  useEffect(() => {
+    if (!scrollContainerRef?.current) return;
+
+    const element = scrollContainerRef.current;
+    const scrollHandler = (e: Event) => handleScroll(e);
+
+    element.addEventListener('scroll', scrollHandler);
+    return () => element.removeEventListener('scroll', scrollHandler);
+  }, [scrollContainerRef, handleScroll]);
+
+  const visibleItems = useMemo(() => {
+    const { startIndex, endIndex } = getVisibleRange;
+    const result = [];
+
+    for (let i = startIndex; i <= endIndex; i++) {
+      const item = items[i];
+      if (!item) continue;
+
+      const offset = getItemOffset(i);
+      const itemStyle = {
+        position: 'absolute' as const,
+        top: offset,
+        left: 0,
+        width: '100%',
+        height: getItemHeight(i),
+      };
+
+      result.push({
+        item,
+        index: i,
+        style: itemStyle,
+      });
+    }
+
+    return result;
+  }, [getVisibleRange, items, getItemOffset, getItemHeight]);
+
+  // When using external scroll container, render just the content
+  if (disableInternalScroll) {
+    return (
+      <Box
+        className={className}
+        data-testid={dataTestId}
+        role="list"
+        aria-label={ariaLabel}
+        sx={{
+          height: getTotalHeight,
+          width,
+          position: 'relative',
+          ...style,
+        }}
+      >
+        {visibleItems.map(({ item, index, style }) => renderItem({ item, index, style }))}
+      </Box>
+    );
+  }
+
+  return (
+    <Box
+      ref={internalContainerRef}
+      className={className}
+      data-testid={dataTestId}
+      role="list"
+      aria-label={ariaLabel}
+      sx={{
+        height,
+        width,
+        overflow: 'auto',
+        position: 'relative',
+        ...style,
+      }}
+      onScroll={handleScroll}
+    >
+      <Box
+        sx={{
+          height: getTotalHeight,
+          position: 'relative',
+        }}
+      >
+        {visibleItems.map(({ item, index, style }) => renderItem({ item, index, style }))}
+      </Box>
+    </Box>
+  );
+};
+
+export const VirtualGrid: React.FC<VirtualGridProps> = ({
+  items,
+  height,
+  width = '100%',
+  columnCount,
+  rowHeight,
+  columnWidth,
+  gap = 0,
+  overscan = 5,
+  renderItem,
+  onScroll,
+  className,
+  style,
+  'data-testid': dataTestId,
+  'aria-label': ariaLabel,
+  scrollContainerRef,
+  disableInternalScroll = false,
+}) => {
+  const [scrollTop, setScrollTop] = useState(0);
+  const internalContainerRef = useRef<HTMLDivElement>(null);
+
+  const rowCount = Math.ceil(items.length / columnCount);
+  const totalHeight = rowCount * (rowHeight + gap) - gap;
+
+  const computedColumnWidth = useMemo(() => {
+    if (columnWidth) return columnWidth;
+
+    const containerWidth = typeof width === 'number' ? width : 300; // fallback
+    return (containerWidth - (columnCount - 1) * gap) / columnCount;
+  }, [columnWidth, width, columnCount, gap]);
+
+  const getVisibleRange = useMemo(() => {
+    const startRow = Math.max(0, Math.floor(scrollTop / (rowHeight + gap)) - overscan);
+    const endRow = Math.min(
+      rowCount - 1,
+      Math.ceil((scrollTop + height) / (rowHeight + gap)) + overscan,
+    );
+
+    return { startRow, endRow };
+  }, [scrollTop, height, rowHeight, gap, overscan, rowCount]);
+
+  const handleScroll = useCallback(
+    (event: React.UIEvent<HTMLDivElement> | Event) => {
+      // Handle both React synthetic events and native DOM events
+      const target =
+        (event as React.UIEvent<HTMLDivElement>).currentTarget ||
+        (event as Event).target;
+      const newScrollTop = (target as HTMLElement).scrollTop;
+      const newScrollLeft = (target as HTMLElement).scrollLeft;
+
+      setScrollTop(newScrollTop);
+      onScroll?.(newScrollTop, newScrollLeft);
+    },
+    [onScroll],
+  );
+
+  // Listen to external scroll container if provided
+  useEffect(() => {
+    if (!scrollContainerRef?.current) return;
+
+    const element = scrollContainerRef.current;
+    const scrollHandler = (e: Event) => handleScroll(e);
+
+    element.addEventListener('scroll', scrollHandler);
+    return () => element.removeEventListener('scroll', scrollHandler);
+  }, [scrollContainerRef, handleScroll]);
+
+  const visibleItems = useMemo(() => {
+    const { startRow, endRow } = getVisibleRange;
+    const result = [];
+
+    for (let rowIndex = startRow; rowIndex <= endRow; rowIndex++) {
+      for (let columnIndex = 0; columnIndex < columnCount; columnIndex++) {
+        const index = rowIndex * columnCount + columnIndex;
+        const item = items[index];
+
+        if (!item) continue;
+
+        const itemStyle = {
+          position: 'absolute' as const,
+          top: rowIndex * (rowHeight + gap),
+          left: columnIndex * (computedColumnWidth + gap),
+          width: computedColumnWidth,
+          height: rowHeight,
+        };
+
+        result.push({
+          item,
+          index,
+          columnIndex,
+          rowIndex,
+          style: itemStyle,
+        });
+      }
+    }
+
+    return result;
+  }, [getVisibleRange, items, columnCount, rowHeight, gap, computedColumnWidth]);
+
+  // When using external scroll container, render just the content
+  if (disableInternalScroll) {
+    return (
+      <Box
+        className={className}
+        data-testid={dataTestId}
+        role="grid"
+        aria-label={ariaLabel}
+        sx={{
+          height: totalHeight,
+          width,
+          position: 'relative',
+          ...style,
+        }}
+      >
+        {visibleItems.map(({ item, index, columnIndex, rowIndex, style }) =>
+          renderItem({ item, index, columnIndex, rowIndex, style }),
+        )}
+      </Box>
+    );
+  }
+
+  return (
+    <Box
+      ref={internalContainerRef}
+      className={className}
+      data-testid={dataTestId}
+      role="grid"
+      aria-label={ariaLabel}
+      sx={{
+        height,
+        width,
+        overflow: 'auto',
+        position: 'relative',
+        ...style,
+      }}
+      onScroll={handleScroll}
+    >
+      <Box
+        sx={{
+          height: totalHeight,
+          position: 'relative',
+        }}
+      >
+        {visibleItems.map(({ item, index, columnIndex, rowIndex, style }) =>
+          renderItem({ item, index, columnIndex, rowIndex, style }),
+        )}
+      </Box>
+    </Box>
+  );
+};

package/src/components/utility/VirtualList/VirtualList.types.ts

@@ -0,0 +1,56 @@
+import type { CSSProperties, ReactNode, RefObject } from 'react';
+
+export type VirtualListVariant = 'fixed' | 'variable' | 'grid';
+
+export interface VirtualListItem {
+  id: string | number;
+  height?: number; // For variable height items
+  data?: unknown;
+}
+
+export interface VirtualListProps {
+  items: VirtualListItem[];
+  variant?: VirtualListVariant;
+  height: number;
+  width?: number | string;
+  itemHeight?: number; // For fixed height items
+  estimatedItemHeight?: number; // For variable height items
+  overscan?: number; // Number of items to render outside visible area
+  renderItem: (params: { item: VirtualListItem; index: number; style: CSSProperties }) => ReactNode;
+  onScroll?: (scrollTop: number) => void;
+  className?: string;
+  style?: CSSProperties;
+  'data-testid'?: string;
+  'aria-label'?: string;
+  /** External scroll container ref - when provided, uses this element for scroll events */
+  scrollContainerRef?: RefObject<HTMLElement | null>;
+  /** Disable internal scroll container - use when composing with external ScrollArea */
+  disableInternalScroll?: boolean;
+}
+
+export interface VirtualGridProps {
+  items: VirtualListItem[];
+  height: number;
+  width?: number | string;
+  columnCount: number;
+  rowHeight: number;
+  columnWidth?: number;
+  gap?: number;
+  overscan?: number;
+  renderItem: (params: {
+    item: VirtualListItem;
+    index: number;
+    columnIndex: number;
+    rowIndex: number;
+    style: CSSProperties;
+  }) => ReactNode;
+  onScroll?: (scrollTop: number, scrollLeft: number) => void;
+  className?: string;
+  style?: CSSProperties;
+  'data-testid'?: string;
+  'aria-label'?: string;
+  /** External scroll container ref - when provided, uses this element for scroll events */
+  scrollContainerRef?: RefObject<HTMLElement | null>;
+  /** Disable internal scroll container - use when composing with external ScrollArea */
+  disableInternalScroll?: boolean;
+}

package/src/components/utility/VirtualList/index.ts

@@ -0,0 +1,7 @@
+export { VirtualGrid,VirtualList } from './VirtualList';
+export type {
+  VirtualGridProps,
+  VirtualListItem,
+  VirtualListProps,
+  VirtualListVariant,
+} from './VirtualList.types';

package/src/components/utility/WorkflowStep/WorkflowStep.md

@@ -0,0 +1,187 @@
+# WorkflowStep Component
+
+## Overview
+
+The WorkflowStep component is an advanced workflow visualization component that displays multi-step processes with clear visual progression indicators. It provides flexible styling, interactive navigation, and comprehensive accessibility features for complex workflow management interfaces.
+
+## Features
+
+- **Multi-step Visualization**: Display workflow progression with clear step indicators
+- **Interactive Navigation**: Allow users to click on steps to navigate (when enabled)
+- **Multiple Orientations**: Support both horizontal and vertical layouts
+- **Visual Variants**: Multiple styling options (default, minimal, outlined, filled)
+- **Progress Indication**: Visual progress bar between steps
+- **Accessibility**: Full keyboard navigation and screen reader support
+- **Animation Support**: Smooth transitions between step states
+- **Theming**: Comprehensive theme integration with multiple color options
+- **Responsive Design**: Adapts to different screen sizes
+
+## Props
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `steps` | `WorkflowStepItem[]` | - | **Required.** Array of step objects with title, description, status, and optional icons |
+| `currentStep` | `number` | `0` | Index of the currently active step |
+| `variant` | `'default' \| 'minimal' \| 'outlined' \| 'filled'` | `'default'` | Visual style variant |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction |
+| `color` | `'primary' \| 'secondary' \| 'success' \| 'warning' \| 'error' \| 'neutral'` | `'primary'` | Theme color |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Step indicator size |
+| `showProgress` | `boolean` | `true` | Whether to show progress bar between steps |
+| `animated` | `boolean` | `true` | Enable transition animations |
+| `interactive` | `boolean` | `false` | Allow clicking on steps to navigate |
+| `showNumbers` | `boolean` | `true` | Show step numbers in indicators |
+| `showIcons` | `boolean` | `false` | Show custom icons for each step |
+| `completedIcon` | `React.ReactNode` | - | Custom icon for completed steps |
+| `errorIcon` | `React.ReactNode` | - | Custom icon for error steps |
+| `onStepClick` | `(stepIndex: number) => void` | - | Callback when a step is clicked |
+| `disabled` | `boolean` | `false` | Disable all interactions |
+| `className` | `string` | - | Additional CSS classes |
+| `style` | `React.CSSProperties` | - | Inline styles |
+
+## Step Item Interface
+
+```typescript
+interface WorkflowStepItem {
+  title: string;
+  description?: string;
+  status: 'pending' | 'current' | 'completed' | 'error';
+  icon?: React.ReactNode;
+  disabled?: boolean;
+}
+```
+
+## Usage Examples
+
+### Basic Usage
+
+```tsx
+import { WorkflowStep } from '@procurement/ui';
+
+const steps = [
+  { title: 'Order Placed', description: 'Your order has been placed', status: 'completed' },
+  { title: 'Processing', description: 'Order is being processed', status: 'current' },
+  { title: 'Shipped', description: 'Order has been shipped', status: 'pending' },
+  { title: 'Delivered', description: 'Order delivered', status: 'pending' }
+];
+
+function OrderTracking() {
+  return (
+    <WorkflowStep
+      steps={steps}
+      currentStep={1}
+      showProgress
+    />
+  );
+}
+```
+
+### Interactive Navigation
+
+```tsx
+import { WorkflowStep } from '@procurement/ui';
+
+function InteractiveWorkflow() {
+  const [currentStep, setCurrentStep] = useState(0);
+  
+  const steps = [
+    { title: 'Personal Info', status: currentStep > 0 ? 'completed' : 'current' },
+    { title: 'Address', status: currentStep > 1 ? 'completed' : currentStep === 1 ? 'current' : 'pending' },
+    { title: 'Payment', status: currentStep > 2 ? 'completed' : currentStep === 2 ? 'current' : 'pending' },
+    { title: 'Confirmation', status: currentStep === 3 ? 'current' : 'pending' }
+  ];
+
+  return (
+    <WorkflowStep
+      steps={steps}
+      currentStep={currentStep}
+      interactive
+      onStepClick={setCurrentStep}
+      variant="outlined"
+      color="primary"
+    />
+  );
+}
+```
+
+### Vertical Layout with Icons
+
+```tsx
+import { WorkflowStep } from '@procurement/ui';
+import { PersonIcon, LocationIcon, CreditCardIcon, CheckIcon } from '@your/icons';
+
+function VerticalWorkflow() {
+  const steps = [
+    { 
+      title: 'Profile Setup', 
+      description: 'Complete your profile information',
+      status: 'completed',
+      icon: <PersonIcon />
+    },
+    { 
+      title: 'Location', 
+      description: 'Set your delivery address',
+      status: 'current',
+      icon: <LocationIcon />
+    },
+    { 
+      title: 'Payment', 
+      description: 'Add payment method',
+      status: 'pending',
+      icon: <CreditCardIcon />
+    },
+    { 
+      title: 'Complete', 
+      description: 'Finish setup',
+      status: 'pending',
+      icon: <CheckIcon />
+    }
+  ];
+
+  return (
+    <WorkflowStep
+      steps={steps}
+      currentStep={1}
+      orientation="vertical"
+      variant="filled"
+      showIcons
+      animated
+    />
+  );
+}
+```
+
+## Accessibility
+
+The WorkflowStep component includes comprehensive accessibility features:
+
+- **Keyboard Navigation**: Navigate between steps using Tab, Enter, Space, and Arrow keys
+- **Screen Reader Support**: Proper ARIA attributes and announcements
+- **Focus Management**: Clear focus indicators and logical focus order
+- **High Contrast**: Supports high contrast mode
+- **Reduced Motion**: Respects user's motion preferences
+
+## Theming
+
+The component integrates with the MUI theme system and supports:
+
+- **Color Variants**: Primary, secondary, success, warning, error, neutral
+- **Size Variants**: xs, sm, md, lg, xl
+- **Visual Variants**: default, minimal, outlined, filled
+- **Dark/Light Mode**: Full theme support
+- **Custom Styling**: Override styles through theme or className/style props
+
+## Best Practices
+
+1. **Step Status**: Ensure step status accurately reflects the workflow state
+2. **Descriptions**: Provide clear, concise step descriptions
+3. **Interactive Mode**: Only enable interactive mode when navigation is meaningful
+4. **Error Handling**: Use error status for steps that have validation issues
+5. **Loading States**: Consider showing loading states for steps being processed
+6. **Responsive**: Test on different screen sizes, especially for horizontal layouts
+
+## Related Components
+
+- `Stepper` - Alternative stepper component with different styling
+- `ProgressBar` - For simple progress indication
+- `Timeline` - For time-based step visualization
+- `Breadcrumbs` - For navigation breadcrumbs