@12-apps/ui 1.0.0 → 1.3.1

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

@@ -1,8 +1,69 @@
 import { Box } from '@mui/material';
-import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import React, { useRef } from 'react';
 
+import { useVirtualGrid, useVirtualList } from './VirtualList.hooks';
 import type { VirtualGridProps, VirtualListProps } from './VirtualList.types';
 
+interface ContainerProps {
+  children: React.ReactNode;
+  role: 'list' | 'grid';
+  totalHeight: number;
+  height: number;
+  width: number | string;
+  disableInternalScroll: boolean;
+  onScroll: (event: React.UIEvent<HTMLDivElement>) => void;
+  className?: string;
+  style?: React.CSSProperties;
+  dataTestId?: string;
+  ariaLabel?: string;
+}
+
+/**
+ * Two shapes, shared by the list and the grid: when the caller owns the scroll
+ * container we render only the full-height content, so their element does the
+ * scrolling; otherwise we render our own viewport around it.
+ */
+const VirtualContainer: React.FC<ContainerProps> = ({
+  children,
+  role,
+  totalHeight,
+  height,
+  width,
+  disableInternalScroll,
+  onScroll,
+  className,
+  style,
+  dataTestId,
+  ariaLabel,
+}) => {
+  const internalContainerRef = useRef<HTMLDivElement>(null);
+  const identity = {
+    className,
+    'data-testid': dataTestId,
+    role,
+    'aria-label': ariaLabel,
+  };
+
+  if (disableInternalScroll) {
+    return (
+      <Box {...identity} sx={{ height: totalHeight, width, position: 'relative', ...style }}>
+        {children}
+      </Box>
+    );
+  }
+
+  return (
+    <Box
+      ref={internalContainerRef}
+      {...identity}
+      sx={{ height, width, overflow: 'auto', position: 'relative', ...style }}
+      onScroll={onScroll}
+    >
+      <Box sx={{ height: totalHeight, position: 'relative' }}>{children}</Box>
+    </Box>
+  );
+};
+
 export const VirtualList: React.FC<VirtualListProps> = ({
   items,
   variant = 'fixed',
@@ -20,200 +81,34 @@ export const VirtualList: React.FC<VirtualListProps> = ({
   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>
-    );
-  }
+  const { totalHeight, visibleItems, handleScroll } = useVirtualList({
+    items,
+    variant,
+    height,
+    itemHeight,
+    estimatedItemHeight,
+    overscan,
+    onScroll,
+    scrollContainerRef,
+  });
 
   return (
-    <Box
-      ref={internalContainerRef}
-      className={className}
-      data-testid={dataTestId}
+    <VirtualContainer
       role="list"
-      aria-label={ariaLabel}
-      sx={{
-        height,
-        width,
-        overflow: 'auto',
-        position: 'relative',
-        ...style,
-      }}
+      totalHeight={totalHeight}
+      height={height}
+      width={width}
+      disableInternalScroll={disableInternalScroll}
       onScroll={handleScroll}
+      className={className}
+      style={style}
+      dataTestId={dataTestId}
+      ariaLabel={ariaLabel}
     >
-      <Box
-        sx={{
-          height: getTotalHeight,
-          position: 'relative',
-        }}
-      >
-        {visibleItems.map(({ item, index, style }) => renderItem({ item, index, style }))}
-      </Box>
-    </Box>
+      {visibleItems.map(({ item, index, style: itemStyle }) =>
+        renderItem({ item, index, style: itemStyle }),
+      )}
+    </VirtualContainer>
   );
 };
 
@@ -235,135 +130,35 @@ export const VirtualGrid: React.FC<VirtualGridProps> = ({
   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>
-    );
-  }
+  const { totalHeight, visibleItems, handleScroll } = useVirtualGrid({
+    items,
+    height,
+    width,
+    columnCount,
+    rowHeight,
+    columnWidth,
+    gap,
+    overscan,
+    onScroll,
+    scrollContainerRef,
+  });
 
   return (
-    <Box
-      ref={internalContainerRef}
-      className={className}
-      data-testid={dataTestId}
+    <VirtualContainer
       role="grid"
-      aria-label={ariaLabel}
-      sx={{
-        height,
-        width,
-        overflow: 'auto',
-        position: 'relative',
-        ...style,
-      }}
+      totalHeight={totalHeight}
+      height={height}
+      width={width}
+      disableInternalScroll={disableInternalScroll}
       onScroll={handleScroll}
+      className={className}
+      style={style}
+      dataTestId={dataTestId}
+      ariaLabel={ariaLabel}
     >
-      <Box
-        sx={{
-          height: totalHeight,
-          position: 'relative',
-        }}
-      >
-        {visibleItems.map(({ item, index, columnIndex, rowIndex, style }) =>
-          renderItem({ item, index, columnIndex, rowIndex, style }),
-        )}
-      </Box>
-    </Box>
+      {visibleItems.map(({ item, index, columnIndex, rowIndex, style: itemStyle }) =>
+        renderItem({ item, index, columnIndex, rowIndex, style: itemStyle }),
+      )}
+    </VirtualContainer>
   );
 };

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

@@ -0,0 +1,151 @@
+import type { Theme } from '@mui/material';
+
+import type { WorkflowStepItem, WorkflowStepProps } from './WorkflowStep.types';
+
+type StepColor = NonNullable<WorkflowStepProps['color']>;
+type StepSize = NonNullable<WorkflowStepProps['size']>;
+
+const INDICATOR_SIZE: Record<StepSize, number> = {
+  xs: 20,
+  sm: 24,
+  md: 32,
+  lg: 40,
+  xl: 48,
+};
+
+export const indicatorSizeFor = (size?: StepSize): number =>
+  INDICATOR_SIZE[size as StepSize] ?? INDICATOR_SIZE.md;
+
+interface StepPalette {
+  main: string;
+  contrastText: string;
+}
+
+/** `neutral` has no MUI palette entry, so its pair is derived from grey. */
+export const stepPalette = (theme: Theme, color?: StepColor): StepPalette => {
+  if (color === 'neutral') {
+    return {
+      main: theme.palette.grey[600],
+      contrastText: theme.palette.getContrastText(theme.palette.grey[600]),
+    };
+  }
+
+  const key = (color || 'primary') as 'primary' | 'secondary' | 'success' | 'warning' | 'error';
+  return theme.palette[key];
+};
+
+export interface StepColors {
+  backgroundColor: string;
+  borderColor: string;
+  textColor: string;
+}
+
+interface StepState {
+  isActive: boolean;
+  isCompleted: boolean;
+  isError: boolean;
+  variant?: WorkflowStepProps['variant'];
+}
+
+/**
+ * An indicator is one of four things, in priority order: failed, done, the step
+ * you are on, or still ahead. Only the active one respects `variant` — an active
+ * outlined step stays hollow with a coloured rim.
+ */
+export const stepColors = (
+  theme: Theme,
+  palette: StepPalette,
+  { isActive, isCompleted, isError, variant }: StepState,
+): StepColors => {
+  if (isError) {
+    return {
+      backgroundColor: theme.palette.error.main,
+      borderColor: theme.palette.error.main,
+      textColor: theme.palette.error.contrastText,
+    };
+  }
+
+  if (isCompleted) {
+    return {
+      backgroundColor: palette.main,
+      borderColor: palette.main,
+      textColor: palette.contrastText,
+    };
+  }
+
+  if (isActive) {
+    const filled = variant === 'filled';
+    return {
+      backgroundColor: filled ? palette.main : theme.palette.background.paper,
+      borderColor: palette.main,
+      textColor: filled ? palette.contrastText : palette.main,
+    };
+  }
+
+  return {
+    backgroundColor: theme.palette.grey[300],
+    borderColor: theme.palette.grey[300],
+    textColor: theme.palette.text.secondary,
+  };
+};
+
+/**
+ * A step that declares `error` keeps it; the rest are positioned against
+ * `currentStep`, so a caller only has to move one number to advance the workflow.
+ */
+export const withDerivedStatus = (
+  steps: WorkflowStepItem[],
+  currentStep: number,
+): WorkflowStepItem[] =>
+  steps.map((step, index) => {
+    const derivable =
+      step.status === 'pending' || step.status === 'current' || step.status === 'completed';
+
+    if (!derivable) return { ...step, status: step.status };
+
+    if (index < currentStep) return { ...step, status: 'completed' as const };
+    if (index === currentStep) return { ...step, status: 'current' as const };
+    return { ...step, status: 'pending' as const };
+  });
+
+type WorkflowDefaultedKeys =
+  | 'currentStep'
+  | 'variant'
+  | 'orientation'
+  | 'color'
+  | 'size'
+  | 'showProgress'
+  | 'animated'
+  | 'interactive'
+  | 'showNumbers'
+  | 'showIcons'
+  | 'disabled';
+
+type ResolvedWorkflowStepProps = WorkflowStepProps &
+  Required<Pick<WorkflowStepProps, WorkflowDefaultedKeys>>;
+
+const WORKFLOW_DEFAULTS: Pick<WorkflowStepProps, WorkflowDefaultedKeys> = {
+  currentStep: 0,
+  variant: 'default',
+  orientation: 'horizontal',
+  color: 'primary',
+  size: 'md',
+  showProgress: true,
+  animated: true,
+  interactive: false,
+  showNumbers: true,
+  showIcons: false,
+  disabled: false,
+};
+
+// Strips explicitly-undefined props before the merge, so `size={undefined}` still
+// falls back to the default exactly as a destructuring default would.
+const definedProps = (props: WorkflowStepProps): Partial<WorkflowStepProps> =>
+  Object.fromEntries(
+    Object.entries(props).filter(([, value]) => value !== undefined),
+  ) as Partial<WorkflowStepProps>;
+
+export const resolveWorkflowStepProps = (
+  props: WorkflowStepProps,
+): ResolvedWorkflowStepProps =>
+  ({ ...WORKFLOW_DEFAULTS, ...definedProps(props) }) as ResolvedWorkflowStepProps;