@12-apps/ui 1.0.0

package/src/components/utility/WorkflowStep/WorkflowStep.tsx

@@ -0,0 +1,506 @@
+import { Box } from '@mui/material';
+import { styled } from '@mui/material/styles';
+import React, { forwardRef, useCallback, useMemo } from 'react';
+
+import type {
+  StepConnectorProps,
+  StepContentProps,
+  StepIndicatorProps,
+  WorkflowStepItem,
+  WorkflowStepProps,
+} from './WorkflowStep.types';
+
+// Styled Components
+const StepContainer = styled(Box, {
+  shouldForwardProp: (prop) => !['orientation', 'variant'].includes(prop as string),
+})<{
+  orientation: WorkflowStepProps['orientation'];
+  variant: WorkflowStepProps['variant'];
+}>(({ theme, orientation, variant }) => ({
+  display: 'flex',
+  flexDirection: orientation === 'vertical' ? 'column' : 'row',
+  alignItems: orientation === 'vertical' ? 'flex-start' : 'center',
+  gap: orientation === 'vertical' ? theme.spacing(2) : theme.spacing(1),
+  width: '100%',
+  position: 'relative',
+  
+  // Variant-specific styles
+  ...(variant === 'minimal' && {
+    gap: orientation === 'vertical' ? theme.spacing(1) : theme.spacing(0.5),
+  }),
+}));
+
+const StepItem = styled(Box, {
+  shouldForwardProp: (prop) => !['orientation', 'isLast'].includes(prop as string),
+})<{
+  orientation: WorkflowStepProps['orientation'];
+  isLast: boolean;
+}>(({ orientation, isLast }) => ({
+  display: 'flex',
+  flexDirection: orientation === 'vertical' ? 'column' : 'row',
+  alignItems: orientation === 'vertical' ? 'flex-start' : 'center',
+  flex: orientation === 'horizontal' && !isLast ? 1 : 'none',
+  position: 'relative',
+  minWidth: 0, // Allow content to shrink
+}));
+
+const StepIndicator = styled(Box, {
+  shouldForwardProp: (prop) => !['size', 'variant', 'color', 'isActive', 'isCompleted', 'isError', 'interactive', 'disabled'].includes(prop as string),
+})<{
+  size: WorkflowStepProps['size'];
+  variant: WorkflowStepProps['variant'];
+  color: WorkflowStepProps['color'];
+  isActive: boolean;
+  isCompleted: boolean;
+  isError: boolean;
+  interactive: boolean;
+  animated: boolean;
+  disabled: boolean;
+}>(({ theme, size, variant, color, isActive, isCompleted, isError, interactive, animated, disabled }) => {
+  const sizeMap = {
+    xs: 20,
+    sm: 24,
+    md: 32,
+    lg: 40,
+    xl: 48,
+  };
+
+  const indicatorSize = sizeMap[size || 'md'];
+  const colorKey = color || 'primary';
+  const colorValue = colorKey === 'neutral' 
+    ? { main: theme.palette.grey[600], contrastText: theme.palette.getContrastText(theme.palette.grey[600]) }
+    : theme.palette[colorKey as 'primary' | 'secondary' | 'success' | 'warning' | 'error'];
+
+  let backgroundColor = theme.palette.grey[300];
+  let borderColor = theme.palette.grey[300];
+  let textColor = theme.palette.text.secondary;
+
+  if (isError) {
+    backgroundColor = theme.palette.error.main;
+    borderColor = theme.palette.error.main;
+    textColor = theme.palette.error.contrastText;
+  } else if (isCompleted) {
+    backgroundColor = colorValue.main;
+    borderColor = colorValue.main;
+    textColor = colorValue.contrastText;
+  } else if (isActive) {
+    backgroundColor = variant === 'filled' ? colorValue.main : theme.palette.background.paper;
+    borderColor = colorValue.main;
+    textColor = variant === 'filled' ? colorValue.contrastText : colorValue.main;
+  }
+
+  return {
+    width: indicatorSize,
+    height: indicatorSize,
+    borderRadius: '50%',
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    fontSize: theme.typography.caption.fontSize,
+    fontWeight: theme.typography.fontWeightMedium,
+    cursor: interactive && !disabled ? 'pointer' : 'default',
+    transition: animated ? theme.transitions.create(['background-color', 'border-color', 'transform'], {
+      duration: theme.transitions.duration.short,
+    }) : 'none',
+    flexShrink: 0,
+    
+    // Variant-specific styles
+    ...(variant === 'outlined' && {
+      border: `2px solid ${borderColor}`,
+      backgroundColor: theme.palette.background.paper,
+    }),
+    ...(variant === 'filled' && {
+      backgroundColor,
+      color: textColor,
+    }),
+    ...(variant === 'minimal' && {
+      backgroundColor,
+      color: textColor,
+      border: 'none',
+    }),
+    ...(variant === 'default' && {
+      backgroundColor,
+      color: textColor,
+      border: `1px solid ${borderColor}`,
+    }),
+
+    // Interactive states
+    ...(interactive && !disabled && {
+      '&:hover': {
+        transform: 'scale(1.1)',
+        boxShadow: theme.shadows[2],
+      },
+      '&:focus-visible': {
+        outline: `2px solid ${colorValue.main}`,
+        outlineOffset: '2px',
+      },
+    }),
+
+    // Disabled state
+    ...(disabled && {
+      opacity: 0.5,
+      cursor: 'not-allowed',
+    }),
+  };
+});
+
+const StepContent = styled(Box, {
+  shouldForwardProp: (prop) => !['orientation', 'interactive', 'disabled'].includes(prop as string),
+})<{
+  orientation: WorkflowStepProps['orientation'];
+  interactive: boolean;
+  disabled: boolean;
+}>(({ theme, orientation, interactive, disabled }) => ({
+  display: 'flex',
+  flexDirection: 'column',
+  alignItems: orientation === 'vertical' ? 'flex-start' : 'center',
+  textAlign: orientation === 'vertical' ? 'left' : 'center',
+  marginTop: orientation === 'vertical' ? theme.spacing(1) : theme.spacing(0.5),
+  marginLeft: orientation === 'horizontal' ? theme.spacing(1) : 0,
+  cursor: interactive && !disabled ? 'pointer' : 'default',
+  minWidth: 0,
+  flex: 1,
+
+  '& .step-title': {
+    fontSize: theme.typography.body2.fontSize,
+    fontWeight: theme.typography.fontWeightMedium,
+    color: theme.palette.text.primary,
+    marginBottom: theme.spacing(0.5),
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+    whiteSpace: 'nowrap',
+    maxWidth: '100%',
+  },
+
+  '& .step-description': {
+    fontSize: theme.typography.caption.fontSize,
+    color: theme.palette.text.secondary,
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+    whiteSpace: 'nowrap',
+    maxWidth: '100%',
+  },
+
+  ...(disabled && {
+    opacity: 0.5,
+  }),
+}));
+
+const StepConnector = styled(Box, {
+  shouldForwardProp: (prop) => !['orientation', 'isCompleted', 'color', 'variant'].includes(prop as string),
+})<{
+  orientation: WorkflowStepProps['orientation'];
+  isCompleted: boolean;
+  color: WorkflowStepProps['color'];
+  variant: WorkflowStepProps['variant'];
+}>(({ theme, orientation, isCompleted, color, variant }) => {
+  const colorKey = color || 'primary';
+  const colorValue = colorKey === 'neutral' 
+    ? { main: theme.palette.grey[600] }
+    : theme.palette[colorKey as 'primary' | 'secondary' | 'success' | 'warning' | 'error'];
+  const connectorColor = isCompleted ? colorValue.main : theme.palette.grey[300];
+
+  return {
+    flex: 1,
+    position: 'relative',
+    
+    ...(orientation === 'horizontal' && {
+      height: '2px',
+      backgroundColor: connectorColor,
+      margin: `0 ${theme.spacing(1)}`,
+      minWidth: theme.spacing(2),
+    }),
+    
+    ...(orientation === 'vertical' && {
+      width: '2px',
+      backgroundColor: connectorColor,
+      minHeight: theme.spacing(3),
+      marginLeft: theme.spacing(2),
+      position: 'absolute',
+      left: '50%',
+      transform: 'translateX(-50%)',
+      top: '100%',
+    }),
+
+    transition: theme.transitions.create('background-color', {
+      duration: theme.transitions.duration.short,
+    }),
+
+    ...(variant === 'minimal' && {
+      opacity: 0.6,
+    }),
+  };
+});
+
+/**
+ * Individual step indicator component
+ */
+const StepIndicatorComponent = forwardRef<HTMLDivElement, StepIndicatorProps>(({
+  step,
+  index,
+  isActive,
+  isCompleted,
+  isError,
+  variant,
+  color,
+  size,
+  showNumbers,
+  showIcons,
+  completedIcon,
+  errorIcon,
+  interactive,
+  animated,
+  disabled,
+  onClick,
+  'data-testid': dataTestId,
+}, ref) => {
+  const handleClick = useCallback(() => {
+    if (interactive && !disabled && onClick) {
+      onClick(index, step);
+    }
+  }, [interactive, disabled, onClick, index, step]);
+
+  const handleKeyDown = useCallback((event: React.KeyboardEvent) => {
+    if (interactive && !disabled && (event.key === 'Enter' || event.key === ' ')) {
+      event.preventDefault();
+      if (onClick) {
+        onClick(index, step);
+      }
+    }
+  }, [interactive, disabled, onClick, index, step]);
+
+  const renderIndicatorContent = () => {
+    if (isError && errorIcon) {
+      return errorIcon;
+    }
+    if (isCompleted && completedIcon) {
+      return completedIcon;
+    }
+    if (showIcons && step.icon) {
+      return step.icon;
+    }
+    if (showNumbers) {
+      return index + 1;
+    }
+    return null;
+  };
+
+  return (
+    <StepIndicator
+      ref={ref}
+      size={size}
+      variant={variant}
+      color={color}
+      isActive={isActive}
+      isCompleted={isCompleted}
+      isError={isError}
+      interactive={interactive}
+      animated={animated}
+      disabled={Boolean(disabled || step.disabled)}
+      onClick={handleClick}
+      onKeyDown={handleKeyDown}
+      role={interactive ? 'button' : undefined}
+      tabIndex={interactive && !disabled && !step.disabled ? 0 : -1}
+      aria-label={`Step ${index + 1}: ${step.title}`}
+      aria-current={isActive ? 'step' : undefined}
+      data-testid={dataTestId}
+    >
+      {renderIndicatorContent()}
+    </StepIndicator>
+  );
+});
+
+StepIndicatorComponent.displayName = 'StepIndicator';
+
+/**
+ * Step connector component
+ */
+const StepConnectorComponent = forwardRef<HTMLDivElement, StepConnectorProps>(({
+  isCompleted,
+  orientation,
+  variant,
+  color,
+  'data-testid': dataTestId,
+}, ref) => (
+  <StepConnector
+    ref={ref}
+    orientation={orientation}
+    isCompleted={isCompleted}
+    color={color}
+    variant={variant}
+    data-testid={dataTestId}
+  />
+));
+
+StepConnectorComponent.displayName = 'StepConnector';
+
+/**
+ * Step content component
+ */
+const StepContentComponent = forwardRef<HTMLDivElement, StepContentProps>(({
+  step,
+  index,
+  orientation,
+  interactive,
+  disabled,
+  onClick,
+  'data-testid': dataTestId,
+}, ref) => {
+  const handleClick = useCallback(() => {
+    if (interactive && !disabled && onClick) {
+      onClick(index, step);
+    }
+  }, [interactive, disabled, onClick, index, step]);
+
+  const handleKeyDown = useCallback((event: React.KeyboardEvent) => {
+    if (interactive && !disabled && (event.key === 'Enter' || event.key === ' ')) {
+      event.preventDefault();
+      if (onClick) {
+        onClick(index, step);
+      }
+    }
+  }, [interactive, disabled, onClick, index, step]);
+
+  return (
+    <StepContent
+      ref={ref}
+      orientation={orientation}
+      interactive={interactive}
+      disabled={Boolean(disabled || step.disabled)}
+      onClick={handleClick}
+      onKeyDown={handleKeyDown}
+      role={interactive ? 'button' : undefined}
+      tabIndex={interactive && !disabled && !step.disabled ? 0 : -1}
+      data-testid={dataTestId}
+    >
+      <div className="step-title">{step.title}</div>
+      {step.description && (
+        <div className="step-description">{step.description}</div>
+      )}
+    </StepContent>
+  );
+});
+
+StepContentComponent.displayName = 'StepContent';
+
+/**
+ * WorkflowStep component for displaying multi-step workflows with visual progression
+ */
+export const WorkflowStep = forwardRef<HTMLDivElement, WorkflowStepProps>(({
+  steps,
+  currentStep = 0,
+  variant = 'default',
+  orientation = 'horizontal',
+  color = 'primary',
+  size = 'md',
+  showProgress = true,
+  animated = true,
+  interactive = false,
+  showNumbers = true,
+  showIcons = false,
+  completedIcon,
+  errorIcon,
+  onStepClick,
+  disabled = false,
+  className,
+  style,
+  'data-testid': dataTestId,
+  ...other
+}, ref) => {
+  const handleStepClick = useCallback((stepIndex: number, step: WorkflowStepItem) => {
+    if (onStepClick && !disabled && !step.disabled) {
+      onStepClick(stepIndex, step);
+    }
+  }, [onStepClick, disabled]);
+
+  const stepsWithStatus = useMemo(() => steps.map((step, index) => {
+      let status = step.status;
+      
+      // Auto-calculate status based on currentStep if not explicitly set
+      if (status === 'pending' || status === 'current' || status === 'completed') {
+        if (index < currentStep) {
+          status = 'completed';
+        } else if (index === currentStep) {
+          status = 'current';
+        } else {
+          status = 'pending';
+        }
+      }
+      
+      return { ...step, status };
+    }), [steps, currentStep]);
+
+  return (
+    <StepContainer
+      ref={ref}
+      orientation={orientation}
+      variant={variant}
+      className={className}
+      style={style}
+      role="progressbar"
+      aria-valuemin={0}
+      aria-valuemax={steps.length - 1}
+      aria-valuenow={currentStep}
+      aria-valuetext={`Step ${currentStep + 1} of ${steps.length}: ${steps[currentStep]?.title}`}
+      data-testid={dataTestId}
+      {...other}
+    >
+      {stepsWithStatus.map((step, index) => {
+        const isActive = step.status === 'current';
+        const isCompleted = step.status === 'completed';
+        const isError = step.status === 'error';
+        const isLast = index === steps.length - 1;
+
+        return (
+          <React.Fragment key={index}>
+            <StepItem orientation={orientation} isLast={isLast}>
+              <StepIndicatorComponent
+                step={step}
+                index={index}
+                isActive={isActive}
+                isCompleted={isCompleted}
+                isError={isError}
+                variant={variant}
+                color={color}
+                size={size}
+                showNumbers={showNumbers}
+                showIcons={showIcons}
+                completedIcon={completedIcon}
+                errorIcon={errorIcon}
+                interactive={interactive}
+                animated={animated}
+                disabled={disabled}
+                onClick={handleStepClick}
+                data-testid={`${dataTestId}-indicator-${index}`}
+              />
+              
+              <StepContentComponent
+                step={step}
+                index={index}
+                orientation={orientation}
+                interactive={interactive}
+                disabled={disabled}
+                onClick={handleStepClick}
+                data-testid={`${dataTestId}-content-${index}`}
+              />
+              
+              {showProgress && !isLast && (
+                <StepConnectorComponent
+                  isCompleted={isCompleted}
+                  orientation={orientation}
+                  variant={variant}
+                  color={color}
+                    data-testid={`${dataTestId}-connector-${index}`}
+                />
+              )}
+            </StepItem>
+          </React.Fragment>
+        );
+      })}
+    </StepContainer>
+  );
+});
+
+WorkflowStep.displayName = 'WorkflowStep';
+
+export default WorkflowStep;

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

@@ -0,0 +1,133 @@
+import type { ComponentProps } from 'react';
+
+/**
+ * Status of an individual workflow step
+ */
+export type WorkflowStepStatus = 'pending' | 'current' | 'completed' | 'error';
+
+/**
+ * Visual variant of the workflow step component
+ */
+export type WorkflowStepVariant = 'default' | 'minimal' | 'outlined' | 'filled';
+
+/**
+ * Layout orientation of the workflow steps
+ */
+export type WorkflowStepOrientation = 'horizontal' | 'vertical';
+
+/**
+ * Color theme for the workflow step component
+ */
+export type WorkflowStepColor = 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'neutral';
+
+/**
+ * Size variant for step indicators
+ */
+export type WorkflowStepSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+/**
+ * Individual step item configuration
+ */
+export interface WorkflowStepItem {
+  /** The title of the step */
+  title: string;
+  /** Optional description text for the step */
+  description?: string;
+  /** Current status of the step */
+  status: WorkflowStepStatus;
+  /** Optional custom icon for the step */
+  icon?: React.ReactNode;
+  /** Whether this step is disabled */
+  disabled?: boolean;
+  /** Optional data attribute for testing */
+  'data-testid'?: string;
+}
+
+/**
+ * Props for the WorkflowStep component
+ */
+export interface WorkflowStepProps extends Omit<ComponentProps<'div'>, 'onError'> {
+  /** Array of step objects defining the workflow */
+  steps: WorkflowStepItem[];
+  /** Index of the currently active step (0-based) */
+  currentStep?: number;
+  /** Visual style variant */
+  variant?: WorkflowStepVariant;
+  /** Layout orientation */
+  orientation?: WorkflowStepOrientation;
+  /** Theme color */
+  color?: WorkflowStepColor;
+  /** Size of step indicators */
+  size?: WorkflowStepSize;
+  /** Whether to show progress bar between steps */
+  showProgress?: boolean;
+  /** Enable transition animations */
+  animated?: boolean;
+  /** Allow clicking on steps to navigate */
+  interactive?: boolean;
+  /** Show step numbers in indicators */
+  showNumbers?: boolean;
+  /** Show custom icons for each step */
+  showIcons?: boolean;
+  /** Custom icon for completed steps (overrides step-specific icons) */
+  completedIcon?: React.ReactNode;
+  /** Custom icon for error steps (overrides step-specific icons) */
+  errorIcon?: React.ReactNode;
+  /** Callback when a step is clicked (only called if interactive=true) */
+  onStepClick?: (stepIndex: number, step: WorkflowStepItem) => void;
+  /** Disable all interactions */
+  disabled?: boolean;
+  /** Additional CSS class names */
+  className?: string;
+  /** Inline styles */
+  style?: React.CSSProperties;
+  /** Data attribute for testing */
+  'data-testid'?: string;
+}
+
+/**
+ * Props for individual step indicator
+ */
+export interface StepIndicatorProps {
+  step: WorkflowStepItem;
+  index: number;
+  isActive: boolean;
+  isCompleted: boolean;
+  isError: boolean;
+  variant: WorkflowStepVariant;
+  color: WorkflowStepColor;
+  size: WorkflowStepSize;
+  showNumbers: boolean;
+  showIcons: boolean;
+  completedIcon?: React.ReactNode;
+  errorIcon?: React.ReactNode;
+  interactive: boolean;
+  animated: boolean;
+  disabled: boolean;
+  onClick?: (index: number, step: WorkflowStepItem) => void;
+  'data-testid'?: string;
+}
+
+/**
+ * Props for step connector/progress line
+ */
+export interface StepConnectorProps {
+  isCompleted: boolean;
+  orientation: WorkflowStepOrientation;
+  variant: WorkflowStepVariant;
+  color: WorkflowStepColor;
+  'data-testid'?: string;
+}
+
+/**
+ * Props for step content (title and description)
+ */
+export interface StepContentProps {
+  step: WorkflowStepItem;
+  index: number;
+  orientation: WorkflowStepOrientation;
+  interactive: boolean;
+  disabled: boolean;
+  onClick?: (index: number, step: WorkflowStepItem) => void;
+  'data-testid'?: string;
+}

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

@@ -0,0 +1,13 @@
+export { WorkflowStep as default, WorkflowStep } from './WorkflowStep';
+export type {
+  StepConnectorProps,
+  StepContentProps,
+  StepIndicatorProps,
+  WorkflowStepColor,
+  WorkflowStepItem,
+  WorkflowStepOrientation,
+  WorkflowStepProps,
+  WorkflowStepSize,
+  WorkflowStepStatus,
+  WorkflowStepVariant,
+} from './WorkflowStep.types';

package/src/components/utility/index.ts

@@ -0,0 +1,7 @@
+export * from './AnimatedIcon';
+export * from './AspectRatio';
+export * from './InfiniteScroll';
+export * from './Portal';
+export * from './Transition';
+export * from './VirtualList';
+export * from './WorkflowStep';

package/src/index.ts

@@ -0,0 +1,17 @@
+// This file is intentionally empty.
+// Please use direct imports instead of barrel exports:
+//
+// ❌ Don't: import { Button } from '@12-apps/ui';
+// ✅ Do:    import { Button } from '@12-apps/ui/form/Button';
+//
+// Available import paths:
+// - @12-apps/ui/data-display/*
+// - @12-apps/ui/feedback/*
+// - @12-apps/ui/form/*
+// - @12-apps/ui/layout/*
+// - @12-apps/ui/navigation/*
+// - @12-apps/ui/typography/*
+// - @12-apps/ui/utility/*
+// - @12-apps/ui/utils
+//
+// See packages/ui/components-catalog.md for a full list of components.

package/src/mui/AppBar.ts

@@ -0,0 +1,2 @@
+export type { AppBarProps } from '@mui/material/AppBar';
+export { default as AppBar, default } from '@mui/material/AppBar';

package/src/mui/Box.ts

@@ -0,0 +1,2 @@
+export type { BoxProps } from '@mui/material/Box';
+export { default as Box, default } from '@mui/material/Box';

package/src/mui/CssBaseline.ts

@@ -0,0 +1,2 @@
+export type { CssBaselineProps } from '@mui/material/CssBaseline';
+export { default as CssBaseline, default } from '@mui/material/CssBaseline';

package/src/mui/FormControl.ts

@@ -0,0 +1,2 @@
+export type { FormControlProps } from '@mui/material/FormControl';
+export { default as FormControl, default } from '@mui/material/FormControl';

package/src/mui/FormControlLabel.ts

@@ -0,0 +1,2 @@
+export type { FormControlLabelProps } from '@mui/material/FormControlLabel';
+export { default as FormControlLabel, default } from '@mui/material/FormControlLabel';

package/src/mui/Grid2.ts

@@ -0,0 +1,2 @@
+export type { Grid2Props } from '@mui/material/Grid2';
+export { default as Grid2, default } from '@mui/material/Grid2';