@12-apps/ui 1.4.0 → 1.5.0

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>
+  );
+};

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

@@ -0,0 +1,190 @@
+import { Box, Paper, Typography, useTheme } from '@mui/material';
+import React from 'react';
+
+import type { CarouselItem, CarouselProps } from './Carousel.types';
+
+export interface CarouselSlideProps {
+  item: CarouselItem;
+  index: number;
+  isActive: boolean;
+  variant: NonNullable<CarouselProps['variant']>;
+  clickable: boolean;
+  onSelect: (item: CarouselItem, index: number) => void;
+}
+
+/**
+ * A slide's caption. Over an image it is white with a shadow so it stays legible
+ * against whatever the photograph happens to be; on a bare surface it uses the
+ * ordinary text colours.
+ */
+const SlideCaption: React.FC<Pick<CarouselItem, 'title' | 'description' | 'content' | 'image'>> = ({
+  title,
+  description,
+  content,
+  image,
+}) => (
+  <Box sx={{ position: 'relative', zIndex: 1, textAlign: 'center', p: 3 }}>
+    {title && (
+      <Typography
+        variant="h5"
+        sx={{
+          color: image ? 'white' : 'text.primary',
+          textShadow: image ? '0 2px 4px rgba(0,0,0,0.5)' : 'none',
+          mb: 1,
+        }}
+      >
+        {title}
+      </Typography>
+    )}
+
+    {description && (
+      <Typography
+        variant="body1"
+        sx={{
+          color: image ? 'white' : 'text.secondary',
+          textShadow: image ? '0 1px 2px rgba(0,0,0,0.5)' : 'none',
+        }}
+      >
+        {description}
+      </Typography>
+    )}
+
+    {content}
+  </Box>
+);
+
+export const CarouselSlide: React.FC<CarouselSlideProps> = ({
+  item,
+  index,
+  isActive,
+  variant,
+  clickable,
+  onSelect,
+}) => {
+  const theme = useTheme();
+
+  const content = (
+    <Box
+      sx={{
+        width: '100%',
+        height: '100%',
+        display: 'flex',
+        flexDirection: 'column',
+        justifyContent: 'center',
+        alignItems: 'center',
+        cursor: clickable ? 'pointer' : 'default',
+        position: 'relative',
+      }}
+      onClick={() => onSelect(item, index)}
+    >
+      {item.image && (
+        <Box
+          component="img"
+          src={item.image}
+          alt={item.alt || item.title}
+          sx={{
+            width: '100%',
+            height: '100%',
+            objectFit: 'cover',
+            position: 'absolute',
+            top: 0,
+            left: 0,
+          }}
+        />
+      )}
+
+      <SlideCaption
+        title={item.title}
+        description={item.description}
+        content={item.content}
+        image={item.image}
+      />
+    </Box>
+  );
+
+  // The cards variant gives each slide its own raised surface, and lifts the
+  // active one further so the stack reads as a deck rather than a strip.
+  if (variant === 'cards') {
+    return (
+      <Paper
+        elevation={isActive ? 8 : 2}
+        sx={{
+          width: '100%',
+          height: '100%',
+          overflow: 'hidden',
+          transform: isActive ? 'scale(1)' : 'scale(0.9)',
+          transition: theme.transitions.create(['transform', 'box-shadow']),
+        }}
+      >
+        {content}
+      </Paper>
+    );
+  }
+
+  return content;
+};
+
+export interface CarouselTrackProps {
+  items: CarouselItem[];
+  activeIndex: number;
+  variant: NonNullable<CarouselProps['variant']>;
+  animation: NonNullable<CarouselProps['animation']>;
+  transition: React.ElementType;
+  clickable: boolean;
+  onSelect: (item: CarouselItem, index: number) => void;
+}
+
+/**
+ * The slides themselves. Every slide stays mounted and absolutely positioned so
+ * the transition has both the outgoing and incoming one to work with; `display`
+ * is what actually hides the rest.
+ */
+export const CarouselTrack: React.FC<CarouselTrackProps> = ({
+  items,
+  activeIndex,
+  variant,
+  animation,
+  transition: Transition,
+  clickable,
+  onSelect,
+}) => (
+  <Box
+    data-testid="carousel-track"
+    sx={{
+      width: '100%',
+      height: '100%',
+      position: 'relative',
+      display: 'flex',
+      alignItems: 'center',
+    }}
+  >
+    {items.map((item, index) => (
+      <Transition
+        key={item.id}
+        in={index === activeIndex}
+        timeout={600}
+        {...(animation === 'flip' && { direction: 'left' as const })}
+      >
+        <Box
+          data-testid={`carousel-slide-${index}`}
+          data-active={index === activeIndex}
+          sx={{
+            position: 'absolute',
+            width: '100%',
+            height: '100%',
+            display: index === activeIndex ? 'block' : 'none',
+          }}
+        >
+          <CarouselSlide
+            item={item}
+            index={index}
+            isActive={index === activeIndex}
+            variant={variant}
+            clickable={clickable}
+            onSelect={onSelect}
+          />
+        </Box>
+      </Transition>
+    ))}
+  </Box>
+);

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

@@ -0,0 +1,86 @@
+import { alpha } from '@mui/material';
+import type { CSSObject, Theme } from '@mui/material';
+
+import type { CarouselProps } from './Carousel.types';
+
+type Variant = NonNullable<CarouselProps['variant']>;
+type Size = NonNullable<CarouselProps['size']>;
+type Color = NonNullable<CarouselProps['color']>;
+
+const SIZES: Record<Size, { height: number; fontSize: string }> = {
+  xs: { height: 200, fontSize: '0.75rem' },
+  sm: { height: 300, fontSize: '0.875rem' },
+  md: { height: 400, fontSize: '1rem' },
+  lg: { height: 500, fontSize: '1.125rem' },
+  xl: { height: 600, fontSize: '1.25rem' },
+};
+
+const sizeStyles = (size: Size) => SIZES[size] ?? SIZES.md;
+
+interface ContainerStyleInput {
+  theme: Theme;
+  variant: Variant;
+  size: Size;
+  color: Color;
+  height: number | string;
+  width: number | string;
+  glow: boolean;
+  pulse: boolean;
+  glass: boolean;
+  gradient: boolean;
+}
+
+/**
+ * Each variant's own additions to the shared frame. The old switch re-spread the
+ * same base, glow and pulse objects in all six arms before adding these; only
+ * these differ, so the shared prefix is applied once by `containerStyles`.
+ */
+const SURFACES: Record<Variant, (input: ContainerStyleInput) => CSSObject> = {
+  glass: ({ theme, color, glass }) => ({
+    backgroundColor: alpha(theme.palette.background.paper, glass ? 0.1 : 0.9),
+    backdropFilter: 'blur(20px)',
+    border: `1px solid ${alpha(theme.palette[color].main, 0.2)}`,
+  }),
+
+  gradient: ({ theme, color, gradient }) => ({
+    background: gradient
+      ? `linear-gradient(135deg, ${alpha(theme.palette[color].light, 0.1)}, ${alpha(theme.palette[color].dark, 0.1)})`
+      : 'transparent',
+  }),
+
+  elevated: ({ theme }) => ({ boxShadow: theme.shadows[8] }),
+
+  minimal: () => ({ border: 'none', boxShadow: 'none' }),
+
+  cards: ({ theme }) => ({ padding: theme.spacing(2) }),
+
+  default: () => ({}),
+};
+
+export const containerStyles = (input: ContainerStyleInput): CSSObject => {
+  const { theme, variant, size, color, height, width, glow, pulse } = input;
+  const accent = theme.palette[color].main;
+
+  return {
+    position: 'relative' as const,
+    width,
+    // A numeric height is taken literally; anything else falls back to the size
+    // preset, since a percentage cannot resolve against an unsized parent here.
+    height: typeof height === 'number' ? height : sizeStyles(size).height,
+    overflow: 'hidden',
+    borderRadius: theme.spacing(1),
+    transition: theme.transitions.create(['all'], {
+      duration: theme.transitions.duration.standard,
+    }),
+    ...(glow && { boxShadow: `0 0 30px ${alpha(accent, 0.4)}` }),
+    ...(pulse && {
+      animation: 'pulse 2s infinite',
+      '@keyframes pulse': {
+        '0%': { boxShadow: `0 0 0 0 ${alpha(accent, 0.4)}` },
+        '70%': { boxShadow: `0 0 0 20px ${alpha(accent, 0)}` },
+        '100%': { boxShadow: `0 0 0 0 ${alpha(accent, 0)}` },
+      },
+    }),
+    ...(SURFACES[variant] ?? SURFACES.default)(input),
+  };
+};

package/src/components/data-display/Carousel/Carousel.test.stories.tsx

@@ -209,7 +209,11 @@ export const Autoplay: Story = {
     if (carousel) {
       await userEvent.hover(carousel);
 
-      // Wait a bit to ensure it doesn't advance
+      // This assertion is that nothing happens, which no query can await: a
+      // findBy would resolve on the slide already showing, and waitFor passes
+      // the instant its condition holds. Proving the timer is paused needs more
+      // than one autoplay interval to actually elapse.
+      // eslint-disable-next-line test-flakiness/no-hard-coded-timeout -- negative assertion over elapsed time
       await new Promise((resolve) => window.setTimeout(resolve, 1500));
 
       // Should still be on slide 2
@@ -252,7 +256,7 @@ export const KeyboardNavigation: Story = {
     // Focus on the carousel container
     const carousel = canvasElement.querySelector('[class*="MuiBox-root"]');
     if (carousel) {
-      carousel.focus();
+      await userEvent.click(carousel);
 
       // Press right arrow key
       await userEvent.keyboard('{ArrowRight}');
@@ -330,7 +334,7 @@ export const FocusManagement: Story = {
     // Focus on carousel container
     const carousel = canvasElement.querySelector('[class*="MuiBox-root"]');
     if (carousel instanceof HTMLElement) {
-      carousel.focus();
+      await userEvent.click(carousel);
 
       // Tab through interactive elements
       await userEvent.tab();
@@ -385,8 +389,14 @@ export const ResponsiveDesign: Story = {
       const styles = window.getComputedStyle(carousel);
       expect(styles.width).toBeTruthy();
 
-      // Verify responsive behavior
-      expect(carousel.clientWidth).toBeLessThanOrEqual(window.innerWidth);
+      // Responsive here means the carousel fills the box it is given, whatever
+      // that box is — comparing it to the viewport would hold on any screen and
+      // so would pass even if the carousel ignored its container entirely.
+      const parent = carousel.parentElement;
+      expect(carousel.clientWidth).toBeGreaterThan(0);
+      if (parent) {
+        expect(carousel.clientWidth).toBeLessThanOrEqual(parent.clientWidth);
+      }
     }
   },
 };