@gen-epix/ui 1.14.4 → 1.15.0

package/src/components/ui/SortableList/SortableList.tsx

@@ -0,0 +1,172 @@
+import {
+  type ReactNode,
+  useCallback,
+  useMemo,
+  useState,
+  type ChangeEvent as ReactChangeEvent,
+} from 'react';
+import {
+  DndContext,
+  KeyboardSensor,
+  PointerSensor,
+  useSensor,
+  useSensors,
+} from '@dnd-kit/core';
+import type {
+  Active,
+  DragEndEvent,
+  DragStartEvent,
+  UniqueIdentifier,
+} from '@dnd-kit/core';
+import {
+  SortableContext,
+  arrayMove,
+  sortableKeyboardCoordinates,
+} from '@dnd-kit/sortable';
+import {
+  Box,
+  Checkbox,
+  FormControlLabel,
+  FormGroup,
+  useTheme,
+} from '@mui/material';
+import { useTranslation } from 'react-i18next';
+
+import { TestIdUtil } from '../../../utils/TestIdUtil';
+
+import { SortableOverlay } from './SortableOverlay';
+import { SortableListItem } from './SortableListItem';
+import { SortableListItemDragHandle } from './SortableListItemDragHandle';
+
+
+interface BaseItem {
+  id: UniqueIdentifier;
+  label: string;
+  isSelected: boolean;
+}
+
+interface Props<T extends BaseItem> {
+  readonly items: T[];
+  onChange(items: T[]): void;
+  renderItemContent(item: T): ReactNode;
+}
+
+export const SortableList = <T extends BaseItem>({
+  items,
+  onChange,
+  renderItemContent,
+}: Props<T>) => {
+  const theme = useTheme();
+  const { t } = useTranslation();
+  const [active, setActive] = useState<Active>(null);
+  const activeItem = useMemo(
+    () => items.find((item) => item.id === active?.id),
+    [active, items],
+  );
+  const sensors = useSensors(
+    useSensor(PointerSensor),
+    useSensor(KeyboardSensor, {
+      coordinateGetter: sortableKeyboardCoordinates,
+    }),
+  );
+
+  const onDragCancel = useCallback(() => {
+    setActive(null);
+  }, []);
+
+  const onDragEnd = useCallback(({ active: item, over }: DragEndEvent) => {
+    if (over && item.id !== over?.id) {
+      const activeIndex = items.findIndex(({ id }) => id === item.id);
+      const overIndex = items.findIndex(({ id }) => id === over.id);
+
+      onChange(arrayMove(items, activeIndex, overIndex));
+    }
+    setActive(null);
+  }, [items, onChange]);
+
+  const onDragStart = useCallback(({ active: item }: DragStartEvent) => {
+    setActive(item);
+  }, []);
+
+  const onCheckBoxChange = useCallback((event: ReactChangeEvent<HTMLInputElement>) => {
+    const itemId = event.target.getAttribute('data-id') as UniqueIdentifier;
+    if (!itemId) {
+      return;
+    }
+    const isSelected = event.target.checked;
+    onChange(items.map((item) => {
+      if (item.id === itemId) {
+        return { ...item, isSelected };
+      }
+      return item;
+    }));
+  }, [onChange, items]);
+
+  const renderItem = useCallback((item: T) => {
+    return (
+      <SortableListItem
+        key={item.id}
+        id={item.id}
+        sx={{
+          backgroundColor: theme.palette.background.paper,
+          '&:hover': {
+            backgroundColor: theme.palette.action.hover,
+          },
+        }}
+      >
+        <FormControlLabel
+          label={renderItemContent(item)}
+          sx={{
+            flexGrow: 1,
+            paddingLeft: theme.spacing(1),
+          }}
+          control={(
+            <Checkbox
+              checked={item.isSelected}
+              size={'small'}
+              slotProps={{
+                input: {
+                  ...{ 'data-id': (item.id as string) },
+                },
+              }}
+              onChange={onCheckBoxChange}
+            />
+          )}
+        />
+        <SortableListItemDragHandle
+          name={t('Drag handle for {{label}}', { label: item.label })}
+        />
+      </SortableListItem>
+    );
+  }, [onCheckBoxChange, renderItemContent, t, theme]);
+
+  return (
+    <DndContext
+      sensors={sensors}
+      onDragCancel={onDragCancel}
+      onDragEnd={onDragEnd}
+      onDragStart={onDragStart}
+    >
+      <SortableContext items={items}>
+        <FormGroup>
+          <Box
+            {...TestIdUtil.createAttributes('SortableList')}
+            component={'ul'}
+            sx={{
+              display: 'flex',
+              flexDirection: 'column',
+              gap: theme.spacing(0.5),
+              padding: 0,
+              listStyle: 'none',
+            }}
+          >
+            {items.map((item) => renderItem(item))}
+          </Box>
+        </FormGroup>
+      </SortableContext>
+      <SortableOverlay>
+        {activeItem ? renderItem(activeItem) : null}
+      </SortableOverlay>
+    </DndContext>
+  );
+};

package/src/components/ui/SortableList/SortableListItem.tsx

@@ -0,0 +1,73 @@
+import { useSortable } from '@dnd-kit/sortable';
+import type {
+  CSSProperties,
+  PropsWithChildren,
+} from 'react';
+import { useMemo } from 'react';
+import { CSS } from '@dnd-kit/utilities';
+import type { UniqueIdentifier } from '@dnd-kit/core';
+import type { SxProps } from '@mui/material';
+import {
+  Box,
+  useTheme,
+} from '@mui/material';
+
+import { TestIdUtil } from '../../../utils/TestIdUtil';
+
+import { SortableListItemContextProvider } from './context/SortableListItemContextProvider';
+
+export type SortableListItemProps = PropsWithChildren<{
+  readonly id: UniqueIdentifier;
+  readonly sx?: SxProps;
+}>;
+
+export const SortableListItem = ({ children, id, sx }: SortableListItemProps) => {
+  const theme = useTheme();
+  const {
+    attributes,
+    isDragging,
+    listeners,
+    setNodeRef,
+    setActivatorNodeRef,
+    transform,
+    transition,
+  } = useSortable({ id });
+  const context = useMemo(
+    () => ({
+      attributes,
+      listeners,
+      ref: setActivatorNodeRef,
+    }),
+    [attributes, listeners, setActivatorNodeRef],
+  );
+  const style: CSSProperties = {
+    backgroundColor: isDragging ? theme.palette.secondary.main : theme.palette.background.paper,
+    transform: CSS.Translate.toString(transform),
+    transition,
+  };
+
+  return (
+    <SortableListItemContextProvider value={context}>
+      <Box
+        {...TestIdUtil.createAttributes('SortableListItem', { id })}
+        ref={setNodeRef}
+        component={'li'}
+        style={style}
+        sx={{
+          ...(sx ?? {}),
+          display: 'flex',
+          justifyContent: 'space-between',
+          backgroundColor: theme.palette.background.paper,
+          flexGrow: 1,
+          alignItems: 'center',
+          boxShadow: 1,
+          borderRadius: `${theme.shape.borderRadius}px`,
+          boxSizing: 'border-box',
+          listStyle: 'none',
+        }}
+      >
+        {children}
+      </Box>
+    </SortableListItemContextProvider>
+  );
+};

package/src/components/ui/SortableList/SortableListItemDragHandle.tsx

@@ -0,0 +1,53 @@
+import {
+  Box,
+  useTheme,
+} from '@mui/material';
+import { useContext } from 'react';
+import DragIndicatorIcon from '@mui/icons-material/DragIndicator';
+
+import { TestIdUtil } from '../../../utils/TestIdUtil';
+
+import { SortableListItemContext } from './context/SortableListItemContext';
+
+export type SortableListItemDragHandleProps = {
+  readonly name: string;
+};
+
+export const SortableListItemDragHandle = ({ name }: SortableListItemDragHandleProps) => {
+  const theme = useTheme();
+  const { attributes, listeners, ref } = useContext(SortableListItemContext);
+
+  return (
+    <Box
+      {...TestIdUtil.createAttributes('SortableListItemDragHandle')}
+      component={'button'}
+      {...attributes}
+      {...listeners}
+      ref={ref}
+      sx={{
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        flex: '0 0 auto',
+        touchAction: 'none',
+        cursor: 'pointer',
+        borderRadius: `${theme.shape.borderRadius}px`,
+        border: 'none',
+        outline: 'none',
+        appearance: 'none',
+        backgroundColor: 'transparent',
+
+        '&:hover': {
+          backgroundColor: theme.palette.action.hover,
+        },
+        '&:focus-visible': {
+          boxShadow: `0 0px 0px 2px ${theme.palette.primary.main}`,
+        },
+      }}
+      aria-label={name}
+      name={name}
+    >
+      <DragIndicatorIcon />
+    </Box>
+  );
+};

package/src/components/ui/SortableList/SortableOverlay.tsx

@@ -0,0 +1,35 @@
+import {
+  useMemo,
+  type PropsWithChildren,
+} from 'react';
+import {
+  DragOverlay,
+  defaultDropAnimationSideEffects,
+} from '@dnd-kit/core';
+import type { DropAnimation } from '@dnd-kit/core';
+
+import { TestIdUtil } from '../../../utils/TestIdUtil';
+
+
+export const SortableOverlay = ({ children }: PropsWithChildren<unknown>) => {
+  const dropAnimationConfig = useMemo<DropAnimation>(() => ({
+    sideEffects: defaultDropAnimationSideEffects({
+      styles: {
+        active: {
+          opacity: '0.6',
+        },
+      },
+    }),
+  }), []);
+
+
+  return (
+    <DragOverlay
+      {...TestIdUtil.createAttributes('SortableOverlay')}
+      dropAnimation={dropAnimationConfig}
+      zIndex={1000}
+    >
+      {children}
+    </DragOverlay>
+  );
+};

package/src/components/ui/SortableList/context/SortableListItemContext.tsx

@@ -0,0 +1,17 @@
+import type {
+  DraggableAttributes,
+  DraggableSyntheticListeners,
+} from '@dnd-kit/core';
+import { createContext } from 'react';
+
+export type SortableListItemContextValue = {
+  attributes: DraggableAttributes;
+  listeners: DraggableSyntheticListeners;
+  ref(node: HTMLElement | null): void;
+};
+
+export const SortableListItemContext = createContext<SortableListItemContextValue>({
+  attributes: undefined,
+  listeners: undefined,
+  ref: undefined,
+});

package/src/components/ui/SortableList/context/SortableListItemContextProvider.tsx

@@ -0,0 +1,19 @@
+import type { PropsWithChildren } from 'react';
+
+import type { SortableListItemContextValue } from './SortableListItemContext';
+import { SortableListItemContext } from './SortableListItemContext';
+
+export type SortableListItemContextProviderProps = PropsWithChildren<{
+  readonly value: SortableListItemContextValue;
+}>;
+
+export const SortableListItemContextProvider = (
+  props: SortableListItemContextProviderProps,
+) => {
+  const { children, value } = props;
+  return (
+    <SortableListItemContext.Provider value={value}>
+      {children}
+    </SortableListItemContext.Provider>
+  );
+};

package/src/components/ui/SortableList/context/useSortableListItemContext.tsx

@@ -0,0 +1,5 @@
+import { useContext } from 'react';
+
+import { SortableListItemContext } from './SortableListItemContext';
+
+export const useSortableListItemContext = () => useContext(SortableListItemContext);

package/src/components/ui/Spinner/Spinner.tsx

@@ -0,0 +1,84 @@
+import type { CircularProgressProps } from '@mui/material';
+import {
+  Box,
+  Typography,
+  CircularProgress,
+} from '@mui/material';
+import type { ReactElement } from 'react';
+import {
+  useState,
+  useEffect,
+} from 'react';
+import { useTranslation } from 'react-i18next';
+import { visuallyHidden } from '@mui/utils';
+
+import { ConfigManager } from '../../../classes/managers/ConfigManager';
+
+
+export type SpinnerProps = {
+  readonly label?: string;
+  readonly takingLongerLabel?: string;
+  readonly takingLongerTimeoutMs?: number;
+  readonly inline?: boolean;
+  readonly color?: 'secondary' | 'primary' | 'inherit';
+  readonly size?: CircularProgressProps['size'];
+};
+
+export const Spinner = ({ label, inline, color = 'primary', takingLongerLabel, takingLongerTimeoutMs, size }: SpinnerProps): ReactElement => {
+  const [isTakingLonger, setIsTakingLonger] = useState(false);
+  const { t } = useTranslation();
+
+  useEffect(() => {
+    const handle = setTimeout(() => {
+      setIsTakingLonger(true);
+    }, takingLongerTimeoutMs ?? ConfigManager.instance.config.spinner.DEFAULT_TAKING_LONGER_TIMEOUT_MS);
+    return () => {
+      clearTimeout(handle);
+    };
+  }, [takingLongerTimeoutMs]);
+
+  return (
+    <Box
+      sx={{
+        width: inline ? '100%' : 'auto',
+        top: inline ? 'auto' : 0,
+        bottom: inline ? 'auto' : 0,
+        left: inline ? 'auto' : 0,
+        right: inline ? 'auto' : 0,
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        flexDirection: 'column',
+        position: inline ? 'relative' : 'absolute',
+      }}
+      role={'status'}
+      aria-busy={'true'}
+    >
+      <Box margin={1}>
+        <CircularProgress
+          color={color}
+          size={size ?? ConfigManager.instance.config.spinner.DEFAULT_CIRCULAR_PROGRESS_SIZE}
+        />
+      </Box>
+      <Box
+        margin={1}
+        sx={!label ? visuallyHidden : undefined}
+      >
+        <Typography
+          aria-live={'polite'}
+        >
+          {label ?? t`Loading`}
+        </Typography>
+      </Box>
+      {isTakingLonger && (
+        <Box margin={1}>
+          <Typography
+            aria-live={'polite'}
+          >
+            {takingLongerLabel || t`This is taking longer than expected. We are still trying.`}
+          </Typography>
+        </Box>
+      )}
+    </Box>
+  );
+};

package/src/components/ui/Spinner/index.ts

@@ -0,0 +1 @@
+export * from './Spinner';

package/src/components/ui/Stepper/Stepper.tsx

@@ -0,0 +1,194 @@
+import type { BoxProps } from '@mui/material';
+import {
+  Box,
+  useTheme,
+  StepIcon,
+  Typography,
+} from '@mui/material';
+import type { ReactNode } from 'react';
+import { useCallback } from 'react';
+import omit from 'lodash/omit';
+import { useTranslation } from 'react-i18next';
+import { visuallyHidden } from '@mui/utils';
+
+import { TestIdUtil } from '../../../utils/TestIdUtil';
+
+import { STEPPER_DIRECTION } from './stepperModel';
+
+export type Step = {
+  key: string;
+  label: string;
+  optional?: boolean;
+  content?: ReactNode;
+  index?: string;
+};
+
+export type StepperProps = {
+  readonly steps: Step[];
+  readonly activeStep: string;
+  readonly direction?: STEPPER_DIRECTION;
+  readonly hideCompletedIndicator?: boolean;
+} & BoxProps;
+
+// NOTE: This Stepper component is an alternative for the MUI Stepper component, because it is more accessibility friendly
+
+export const Stepper = ({ steps, activeStep, direction = STEPPER_DIRECTION.HORIZONTAL, hideCompletedIndicator = false, ...boxProps }: StepperProps) => {
+  const theme = useTheme();
+  const { t } = useTranslation();
+
+  const isFirstStep = useCallback((key: string) => {
+    return steps.findIndex((step) => step.key === key) === 0;
+  }, [steps]);
+
+  const isLastStep = useCallback((key: string) => {
+    return steps.findIndex((step) => step.key === key) === steps.length - 1;
+  }, [steps]);
+
+  const isCompletedStep = useCallback((key: string) => {
+    const activeStepIndex = steps.findIndex((step) => step.key === activeStep);
+    const stepIndex = steps.findIndex((step) => step.key === key);
+    return stepIndex < activeStepIndex;
+  }, [activeStep, steps]);
+
+  const isActiveStep = useCallback((key: string) => {
+    return key === activeStep;
+  } , [activeStep]);
+
+  return (
+    <Box
+      {...TestIdUtil.createAttributes('Stepper', { 'active-step': activeStep })}
+      {...omit(boxProps, ['sx'])}
+      sx={{
+        position: 'relative',
+        ...boxProps.sx,
+      }}
+      role={'presentation'}
+    >
+      <Box
+        sx={direction === STEPPER_DIRECTION.HORIZONTAL ? {
+          display: 'flex',
+          flexDirection: 'row',
+          alignItems: 'center',
+          justifyContent: 'space-between',
+          gap: 1,
+          position: 'absolute',
+          top: 0,
+          left: 0,
+          right: 0,
+          bottom: 0,
+          margin: 0,
+          padding: 0,
+        } : {
+          display: 'flex',
+          flexDirection: 'column',
+          alignItems: 'flex-start',
+          justifyContent: 'space-between',
+          gap: 1,
+          position: 'relative',
+          padding: 0,
+          margin: 0,
+        }}
+        component={'ol'}
+      >
+        {steps.map((step, index) => (
+          <Box
+            key={step.key}
+            component={'li'}
+            sx={{
+              background: theme.palette.background.default,
+              paddingLeft: direction === STEPPER_DIRECTION.VERTICAL || isFirstStep(step.key) ? 0 : 2,
+              paddingRight: direction === STEPPER_DIRECTION.VERTICAL || isLastStep(step.key) ? 0 : 2,
+              display: 'flex',
+              flexDirection: 'row',
+              alignItems: direction === STEPPER_DIRECTION.HORIZONTAL ? 'center' : 'flex-start',
+              gap: 1,
+              zIndex: 2,
+              position: 'relative',
+            }}
+            aria-current={isActiveStep(step.key) ? 'step' : undefined}
+          >
+            <Box>
+              <StepIcon
+                completed={hideCompletedIndicator ? false : isCompletedStep(step.key)}
+                active={isActiveStep(step.key)}
+                icon={step.index ?? index + 1}
+                aria-hidden={'true'}
+              />
+            </Box>
+            {direction === STEPPER_DIRECTION.VERTICAL && (
+              <Box
+                role={'presentation'}
+                sx={{
+                  width: '1px',
+                  height: '100%',
+                  position: 'absolute',
+                  background: isLastStep(step.key) ? theme.palette.background.default : theme.palette.divider,
+                  marginLeft: theme.spacing(1.5),
+                  top: theme.spacing(1.5),
+                  zIndex: -1,
+                }}
+              />
+            )}
+            <Box>
+              {isActiveStep(step.key) && (
+                <Typography
+                  sx={visuallyHidden}
+                  component={'span'}
+                >
+                  {t`Current: `}
+                </Typography>
+              )}
+              {isCompletedStep(step.key) && (
+                <Typography
+                  sx={visuallyHidden}
+                  component={'span'}
+                >
+                  {t`Completed: `}
+                </Typography>
+              )}
+              <Typography
+                component={'span'}
+                sx={{
+                  fontWeight: isActiveStep(step.key) ? 'bold' : 'normal',
+                }}
+              >
+                {step.label}
+              </Typography>
+              {step.optional && (
+                <Typography
+                  variant={'caption'}
+                  color={'text.secondary'}
+                  component={'span'}
+                  sx={{
+                    display: 'block',
+                  }}
+                >
+                  {t`Optional`}
+                </Typography>
+              )}
+              {step.content && (
+                <Box
+                  sx={{
+                    marginTop: 1,
+                  }}
+                >
+                  {step.content}
+                </Box>
+              )}
+            </Box>
+          </Box>
+        ))}
+      </Box>
+      {direction === STEPPER_DIRECTION.HORIZONTAL && (
+        <Box
+          role={'presentation'}
+          sx={{
+            background: theme.palette.divider,
+            height: '1px',
+            width: '100%',
+          }}
+        />
+      )}
+    </Box>
+  );
+};

package/src/components/ui/Stepper/index.ts

@@ -0,0 +1,2 @@
+export * from './Stepper';
+export * from './stepperModel';

package/src/components/ui/Stepper/stepperModel.ts

@@ -0,0 +1,4 @@
+export enum STEPPER_DIRECTION {
+  HORIZONTAL = 'HORIZONTAL',
+  VERTICAL = 'VERTICAL',
+}