@12-apps/ui 1.3.1 → 1.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/ui",
-  "version": "1.3.1",
+  "version": "1.4.1",
   "license": "MIT",
   "packageManager": "pnpm@9.0.0",
   "type": "module",
@@ -194,7 +194,7 @@
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@12-apps/forms-core": "^1.2.1",
+    "@12-apps/forms-core": "^1.3.1",
     "@emotion/react": "^11.14.0",
     "@emotion/styled": "^11.14.0",
     "@monaco-editor/react": "^4.7.0",
@@ -209,8 +209,8 @@
     "recharts": "^3.5.1"
   },
   "devDependencies": {
-    "@12-apps/eslint-config": "^1.3.1",
-    "@12-apps/typescript-config": "^1.3.1",
+    "@12-apps/eslint-config": "^1.4.1",
+    "@12-apps/typescript-config": "^1.4.1",
     "@playwright/test": "^1.55.0",
     "@storybook/addon-docs": "^9.1.10",
     "@storybook/addon-links": "^9.1.10",

package/src/components/data-display/Carousel/Carousel.chrome.tsx

@@ -0,0 +1,83 @@
+import React from 'react';
+
+import { CarouselArrows, CarouselIndicators, CarouselThumbnails } from './Carousel.parts';
+import type {
+  CarouselArrowsProps,
+  CarouselIndicatorsProps,
+  CarouselItem,
+  CarouselThumbnailsProps,
+} from './Carousel.types';
+
+type IndicatorPosition = NonNullable<CarouselIndicatorsProps['position']>;
+type Color = NonNullable<CarouselIndicatorsProps['color']>;
+
+export interface CarouselChromeProps {
+  items: CarouselItem[];
+  activeIndex: number;
+  loop: boolean;
+  disabled: boolean;
+  showArrows: boolean;
+  showIndicators: boolean;
+  showThumbnails: boolean;
+  arrowPosition: NonNullable<CarouselArrowsProps['position']>;
+  indicatorPosition: IndicatorPosition;
+  color: Color;
+  size: NonNullable<CarouselThumbnailsProps['size']>;
+  onPrev: () => void;
+  onNext: () => void;
+  onSelect: (index: number) => void;
+}
+
+/**
+ * Everything drawn over the slides: the arrows, the indicators and the thumbnail
+ * strip. Each is independently switchable, so they travel together rather than
+ * as three conditional blocks inside the carousel's own render.
+ */
+export const CarouselChrome: React.FC<CarouselChromeProps> = ({
+  items,
+  activeIndex,
+  loop,
+  disabled,
+  showArrows,
+  showIndicators,
+  showThumbnails,
+  arrowPosition,
+  indicatorPosition,
+  color,
+  size,
+  onPrev,
+  onNext,
+  onSelect,
+}) => (
+  <>
+    {showArrows && !disabled && (
+      <CarouselArrows
+        onPrev={onPrev}
+        onNext={onNext}
+        position={arrowPosition}
+        color={color}
+        disablePrev={!loop && activeIndex === 0}
+        disableNext={!loop && activeIndex === items.length - 1}
+      />
+    )}
+
+    {showIndicators && (
+      <CarouselIndicators
+        count={items.length}
+        activeIndex={activeIndex}
+        onSelect={onSelect}
+        position={indicatorPosition}
+        color={color}
+      />
+    )}
+
+    {showThumbnails && (
+      <CarouselThumbnails
+        items={items}
+        activeIndex={activeIndex}
+        onSelect={onSelect}
+        size={size}
+      />
+    )}
+  </>
+);

package/src/components/data-display/Carousel/Carousel.hooks.ts

@@ -0,0 +1,88 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+interface CarouselNavigationInput {
+  count: number;
+  loop: boolean;
+  autoPlay: boolean;
+  autoPlayInterval: number;
+  pauseOnHover: boolean;
+  disabled: boolean;
+  onChange?: (index: number) => void;
+}
+
+/**
+ * Steps `current` by `step`, wrapping when `loop` allows it and stopping at the
+ * end when it does not. Returns the same index it was given when there is
+ * nowhere to go, which is what lets the caller skip a no-op `onChange`.
+ */
+const stepIndex = (current: number, step: number, count: number, loop: boolean) => {
+  const next = current + step;
+
+  if (next >= count) return loop ? 0 : current;
+  if (next < 0) return loop ? count - 1 : 0;
+  return next;
+};
+
+/**
+ * Which slide is showing and everything that changes it: the arrows, an
+ * indicator click, and the autoplay timer.
+ *
+ * Hover is tracked here rather than in the component because its only job is to
+ * pause that timer.
+ */
+export const useCarouselNavigation = ({
+  count,
+  loop,
+  autoPlay,
+  autoPlayInterval,
+  pauseOnHover,
+  disabled,
+  onChange,
+}: CarouselNavigationInput) => {
+  const [activeIndex, setActiveIndex] = useState(0);
+  const [isHovered, setIsHovered] = useState(false);
+  const intervalRef = useRef<number | null>(null);
+
+  const goBy = useCallback(
+    (step: number) => {
+      setActiveIndex((prev) => {
+        const next = stepIndex(prev, step, count, loop);
+        if (next !== prev) {
+          onChange?.(next);
+        }
+        return next;
+      });
+    },
+    [count, loop, onChange],
+  );
+
+  const handleNext = useCallback(() => goBy(1), [goBy]);
+  const handlePrev = useCallback(() => goBy(-1), [goBy]);
+
+  const handleSelect = useCallback(
+    (index: number) => {
+      setActiveIndex(index);
+      onChange?.(index);
+    },
+    [onChange],
+  );
+
+  useEffect(() => {
+    if (!autoPlay || isHovered || disabled) return;
+
+    intervalRef.current = window.setInterval(handleNext, autoPlayInterval);
+
+    return () => {
+      if (intervalRef.current) {
+        window.clearInterval(intervalRef.current);
+      }
+    };
+  }, [autoPlay, autoPlayInterval, isHovered, disabled, handleNext]);
+
+  const hoverProps = {
+    onMouseEnter: () => pauseOnHover && setIsHovered(true),
+    onMouseLeave: () => pauseOnHover && setIsHovered(false),
+  };
+
+  return { activeIndex, handleNext, handlePrev, handleSelect, hoverProps };
+};

package/src/components/data-display/Carousel/Carousel.parts.tsx

@@ -0,0 +1,346 @@
+import ArrowBackIosIcon from '@mui/icons-material/ArrowBackIos';
+import ArrowForwardIosIcon from '@mui/icons-material/ArrowForwardIos';
+import FiberManualRecordIcon from '@mui/icons-material/FiberManualRecord';
+import { alpha, Box, IconButton, Typography, useTheme } from '@mui/material';
+import type { CSSObject, Theme } from '@mui/material';
+import React from 'react';
+
+import { withDefaults } from '../../../utils/withDefaults';
+
+import type {
+  CarouselArrowsProps,
+  CarouselIndicatorsProps,
+  CarouselItem,
+  CarouselThumbnailsProps,
+} from './Carousel.types';
+
+type IndicatorPosition = NonNullable<CarouselIndicatorsProps['position']>;
+type IndicatorVariant = NonNullable<CarouselIndicatorsProps['variant']>;
+type Color = NonNullable<CarouselIndicatorsProps['color']>;
+
+/** Fires `onSelect` for the keys a native button would treat as activation. */
+const activateOnKey = (onSelect: () => void) => (e: React.KeyboardEvent) => {
+  if (e.key === 'Enter' || e.key === ' ') {
+    e.preventDefault();
+    onSelect();
+  }
+};
+
+const INDICATOR_POSITIONS = (theme: Theme): Record<IndicatorPosition, CSSObject> => ({
+  top: { top: theme.spacing(2), left: '50%', transform: 'translateX(-50%)' },
+  bottom: { bottom: theme.spacing(2), left: '50%', transform: 'translateX(-50%)' },
+  left: {
+    left: theme.spacing(2),
+    top: '50%',
+    transform: 'translateY(-50%)',
+    flexDirection: 'column',
+  },
+  right: {
+    right: theme.spacing(2),
+    top: '50%',
+    transform: 'translateY(-50%)',
+    flexDirection: 'column',
+  },
+});
+
+interface IndicatorProps {
+  index: number;
+  isActive: boolean;
+  color: Color;
+  onSelect: () => void;
+}
+
+/** Attributes every indicator variant carries, whatever it draws. */
+const indicatorAttrs = (index: number, isActive: boolean) => ({
+  'aria-label': `Go to slide ${index + 1}`,
+  'data-testid': `carousel-indicator-${index}`,
+  'data-active': isActive,
+});
+
+const LineIndicator: React.FC<IndicatorProps> = ({ index, isActive, color, onSelect }) => {
+  const theme = useTheme();
+
+  return (
+    <Box
+      role="button"
+      tabIndex={0}
+      {...indicatorAttrs(index, isActive)}
+      sx={{
+        width: isActive ? 30 : 20,
+        height: 3,
+        backgroundColor: isActive
+          ? theme.palette[color].main
+          : alpha(theme.palette[color].main, 0.3),
+        borderRadius: 1.5,
+        transition: theme.transitions.create(['width', 'background-color']),
+        cursor: 'pointer',
+      }}
+      onClick={onSelect}
+      onKeyDown={activateOnKey(onSelect)}
+    />
+  );
+};
+
+const NumberIndicator: React.FC<IndicatorProps> = ({ index, isActive, color, onSelect }) => {
+  const theme = useTheme();
+
+  return (
+    <Box
+      role="button"
+      tabIndex={0}
+      {...indicatorAttrs(index, isActive)}
+      sx={{
+        width: 24,
+        height: 24,
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        borderRadius: '50%',
+        backgroundColor: isActive ? theme.palette[color].main : 'transparent',
+        color: isActive ? theme.palette[color].contrastText : theme.palette[color].main,
+        border: `1px solid ${theme.palette[color].main}`,
+        fontSize: '0.75rem',
+        fontWeight: isActive ? 'bold' : 'normal',
+        cursor: 'pointer',
+        transition: theme.transitions.create(['all']),
+      }}
+      onClick={onSelect}
+      onKeyDown={activateOnKey(onSelect)}
+    >
+      {index + 1}
+    </Box>
+  );
+};
+
+const DotIndicator: React.FC<IndicatorProps> = ({ index, isActive, color, onSelect }) => {
+  const theme = useTheme();
+
+  return (
+    <IconButton
+      size="small"
+      {...indicatorAttrs(index, isActive)}
+      onClick={onSelect}
+      sx={{
+        p: 0.5,
+        color: isActive ? theme.palette[color].main : alpha(theme.palette[color].main, 0.3),
+        transform: isActive ? 'scale(1.2)' : 'scale(1)',
+        transition: theme.transitions.create(['transform', 'color']),
+      }}
+    >
+      <FiberManualRecordIcon fontSize="small" />
+    </IconButton>
+  );
+};
+
+const INDICATORS: Record<IndicatorVariant, React.FC<IndicatorProps>> = {
+  lines: LineIndicator,
+  numbers: NumberIndicator,
+  dots: DotIndicator,
+};
+
+const INDICATORS_DEFAULTS = {
+  position: 'bottom',
+  color: 'primary',
+  variant: 'dots',
+} satisfies Partial<CarouselIndicatorsProps>;
+
+export const CarouselIndicators: React.FC<CarouselIndicatorsProps> = (props) => {
+  const { count, activeIndex, onSelect, position, color, variant, className, style } = withDefaults(
+    props,
+    INDICATORS_DEFAULTS,
+  ) as CarouselIndicatorsProps & Required<Pick<CarouselIndicatorsProps, keyof typeof INDICATORS_DEFAULTS>>;
+
+  const theme = useTheme();
+  const Indicator = INDICATORS[variant] ?? DotIndicator;
+
+  return (
+    <Box
+      className={className}
+      data-testid="carousel-indicators"
+      sx={{
+        position: 'absolute',
+        display: 'flex',
+        gap: 1,
+        zIndex: 2,
+        ...(INDICATOR_POSITIONS(theme)[position] ?? INDICATOR_POSITIONS(theme).bottom),
+        ...style,
+      }}
+    >
+      {Array.from({ length: count }).map((_, index) => (
+        <Indicator
+          key={index}
+          index={index}
+          isActive={index === activeIndex}
+          color={color}
+          onSelect={() => onSelect(index)}
+        />
+      ))}
+    </Box>
+  );
+};
+
+const ARROWS_DEFAULTS = {
+  position: 'overlay',
+  disabled: false,
+  disablePrev: false,
+  disableNext: false,
+  color: 'primary',
+  size: 'medium',
+} satisfies Partial<CarouselArrowsProps>;
+
+/**
+ * All three positions place the arrow the same way; only `overlay` fades it back
+ * until hovered, and only `outside` sits it clear of the frame.
+ */
+const arrowSx = (theme: Theme, color: Color, isOverlay: boolean): CSSObject => ({
+  position: 'absolute',
+  top: '50%',
+  transform: 'translateY(-50%)',
+  zIndex: 3,
+  backgroundColor: alpha(theme.palette.background.paper, 0.8),
+  color: theme.palette[color].main,
+  '&:disabled': { opacity: 0.3 },
+  ...(isOverlay
+    ? {
+        opacity: 0.7,
+        '&:hover': { backgroundColor: theme.palette.background.paper, opacity: 1 },
+      }
+    : { '&:hover': { backgroundColor: theme.palette.background.paper } }),
+});
+
+export const CarouselArrows: React.FC<CarouselArrowsProps> = (props) => {
+  const {
+    onPrev, onNext, position, disabled, disablePrev, disableNext, color, size, className, style,
+  } = withDefaults(props, ARROWS_DEFAULTS) as CarouselArrowsProps &
+    Required<Pick<CarouselArrowsProps, keyof typeof ARROWS_DEFAULTS>>;
+
+  const theme = useTheme();
+  const sx = arrowSx(theme, color, position === 'overlay');
+  const offset = position === 'outside' ? -40 : 8;
+
+  return (
+    <Box data-testid="carousel-navigation">
+      <IconButton
+        onClick={onPrev}
+        disabled={disabled || disablePrev}
+        size={size}
+        className={className}
+        aria-label="Previous slide"
+        data-testid="carousel-prev-button"
+        sx={{ ...sx, left: offset, ...style }}
+      >
+        <ArrowBackIosIcon />
+      </IconButton>
+
+      <IconButton
+        onClick={onNext}
+        disabled={disabled || disableNext}
+        aria-label="Next slide"
+        size={size}
+        className={className}
+        data-testid="carousel-next-button"
+        sx={{ ...sx, right: offset, ...style }}
+      >
+        <ArrowForwardIosIcon />
+      </IconButton>
+    </Box>
+  );
+};
+
+const THUMBNAIL_SIZES = { xs: 40, sm: 60, md: 80, lg: 100, xl: 120 } as const;
+const DEFAULT_THUMBNAIL_SIZE = 60;
+
+const Thumbnail: React.FC<{
+  item: CarouselItem;
+  index: number;
+  isActive: boolean;
+  side: number;
+  onSelect: () => void;
+}> = ({ item, index, isActive, side, onSelect }) => {
+  const theme = useTheme();
+
+  return (
+    <Box
+      onClick={onSelect}
+      data-testid={`carousel-thumbnail-${index}`}
+      data-active={isActive}
+      sx={{
+        width: side,
+        height: side,
+        border: `2px solid ${isActive ? theme.palette.primary.main : 'transparent'}`,
+        borderRadius: 1,
+        overflow: 'hidden',
+        cursor: 'pointer',
+        opacity: isActive ? 1 : 0.6,
+        transition: theme.transitions.create(['opacity', 'border-color']),
+        '&:hover': { opacity: 1 },
+      }}
+    >
+      {item.image ? (
+        <Box
+          component="img"
+          src={item.image}
+          alt={item.alt || item.title}
+          sx={{ width: '100%', height: '100%', objectFit: 'cover' }}
+        />
+      ) : (
+        // No image to show, so the slide's number stands in for it.
+        <Box
+          sx={{
+            width: '100%',
+            height: '100%',
+            backgroundColor: theme.palette.grey[300],
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+          }}
+        >
+          <Typography variant="caption">{index + 1}</Typography>
+        </Box>
+      )}
+    </Box>
+  );
+};
+
+export const CarouselThumbnails: React.FC<CarouselThumbnailsProps> = ({
+  items,
+  activeIndex,
+  onSelect,
+  size = 'sm',
+  className,
+  style,
+}) => {
+  const theme = useTheme();
+  const side = THUMBNAIL_SIZES[size as keyof typeof THUMBNAIL_SIZES] ?? DEFAULT_THUMBNAIL_SIZE;
+
+  return (
+    <Box
+      className={className}
+      data-testid="carousel-thumbnails"
+      sx={{
+        position: 'absolute',
+        // Hung below the frame, clear of its own height plus a gap.
+        bottom: -side - 16,
+        left: '50%',
+        transform: 'translateX(-50%)',
+        display: 'flex',
+        gap: 1,
+        p: 1,
+        backgroundColor: alpha(theme.palette.background.paper, 0.9),
+        borderRadius: 1,
+        ...style,
+      }}
+    >
+      {items.map((item, index) => (
+        <Thumbnail
+          key={item.id}
+          item={item}
+          index={index}
+          isActive={index === activeIndex}
+          side={side}
+          onSelect={() => onSelect(index)}
+        />
+      ))}
+    </Box>
+  );
+};