@12-apps/ui 1.0.0 → 1.3.1

package/src/components/data-display/Lightbox/LightboxControls.tsx

@@ -0,0 +1,152 @@
+import PrevIcon from '@mui/icons-material/ChevronLeft';
+import NextIcon from '@mui/icons-material/ChevronRight';
+import CloseIcon from '@mui/icons-material/Close';
+import PauseIcon from '@mui/icons-material/Pause';
+import PlayIcon from '@mui/icons-material/PlayArrow';
+import ResetZoomIcon from '@mui/icons-material/RestartAlt';
+import ZoomInIcon from '@mui/icons-material/ZoomIn';
+import ZoomOutIcon from '@mui/icons-material/ZoomOut';
+import { Box, IconButton } from '@mui/material';
+import type { FC } from 'react';
+import React from 'react';
+
+import { navButtonSx, OVERLAY_Z_INDEX, overlayButtonSx } from './Lightbox.constants';
+
+type TestId = (suffix: string) => string;
+
+export const LightboxCloseButton: FC<{ testId: TestId; onClose: () => void }> = ({
+  testId,
+  onClose,
+}) => (
+  <IconButton
+    onClick={onClose}
+    sx={{ ...overlayButtonSx, position: 'absolute', top: 16, right: 16, zIndex: OVERLAY_Z_INDEX }}
+    aria-label="Close lightbox"
+    data-testid={testId('close')}
+  >
+    <CloseIcon />
+  </IconButton>
+);
+
+const arrowSx = (side: 'left' | 'right') =>
+  ({
+    ...navButtonSx,
+    position: 'absolute',
+    [side]: 16,
+    top: '50%',
+    transform: 'translateY(-50%)',
+    zIndex: OVERLAY_Z_INDEX,
+  }) as const;
+
+export interface LightboxNavButtonsProps {
+  testId: TestId;
+  atStart: boolean;
+  atEnd: boolean;
+  onPrev: () => void;
+  onNext: () => void;
+}
+
+export const LightboxNavButtons: FC<LightboxNavButtonsProps> = ({
+  testId,
+  atStart,
+  atEnd,
+  onPrev,
+  onNext,
+}) => (
+  <>
+    <IconButton
+      onClick={onPrev}
+      disabled={atStart}
+      sx={arrowSx('left')}
+      aria-label="Previous item"
+      data-testid={testId('prev')}
+    >
+      <PrevIcon />
+    </IconButton>
+
+    <IconButton
+      onClick={onNext}
+      disabled={atEnd}
+      sx={arrowSx('right')}
+      aria-label="Next item"
+      data-testid={testId('next')}
+    >
+      <NextIcon />
+    </IconButton>
+  </>
+);
+
+export interface LightboxZoomControlsProps {
+  testId: TestId;
+  onZoomIn: () => void;
+  onZoomOut: () => void;
+  onResetZoom: () => void;
+}
+
+export const LightboxZoomControls: FC<LightboxZoomControlsProps> = ({
+  testId,
+  onZoomIn,
+  onZoomOut,
+  onResetZoom,
+}) => (
+  <Box
+    sx={{
+      position: 'absolute',
+      top: 16,
+      left: 16,
+      display: 'flex',
+      flexDirection: 'column',
+      gap: 1,
+      zIndex: OVERLAY_Z_INDEX,
+    }}
+    data-testid={testId('zoom-controls')}
+  >
+    <IconButton onClick={onZoomIn} sx={overlayButtonSx} aria-label="Zoom in" data-testid={testId('zoom-in')}>
+      <ZoomInIcon />
+    </IconButton>
+    <IconButton
+      onClick={onZoomOut}
+      sx={overlayButtonSx}
+      aria-label="Zoom out"
+      data-testid={testId('zoom-out')}
+    >
+      <ZoomOutIcon />
+    </IconButton>
+    <IconButton
+      onClick={onResetZoom}
+      sx={overlayButtonSx}
+      aria-label="Reset zoom"
+      data-testid={testId('zoom-reset')}
+    >
+      <ResetZoomIcon />
+    </IconButton>
+  </Box>
+);
+
+export interface LightboxAutoplayButtonProps {
+  testId: TestId;
+  isAutoPlaying: boolean;
+  onToggle: () => void;
+}
+
+export const LightboxAutoplayButton: FC<LightboxAutoplayButtonProps> = ({
+  testId,
+  isAutoPlaying,
+  onToggle,
+}) => (
+  <IconButton
+    onClick={onToggle}
+    sx={{
+      ...overlayButtonSx,
+      position: 'absolute',
+      top: 16,
+      left: '50%',
+      transform: 'translateX(-50%)',
+      zIndex: OVERLAY_Z_INDEX,
+    }}
+    aria-label={isAutoPlaying ? 'Pause slideshow' : 'Start slideshow'}
+    data-testid={testId('autoplay')}
+  >
+    {isAutoPlaying ? <PauseIcon /> : <PlayIcon />}
+  </IconButton>
+);

package/src/components/data-display/Lightbox/LightboxCurrentMedia.tsx

@@ -0,0 +1,50 @@
+import type { FC } from 'react';
+import React from 'react';
+
+import type { ZoomState } from './Lightbox.hooks';
+import type { LightboxItem } from './Lightbox.types';
+import { LightboxMedia } from './LightboxMedia';
+
+export interface LightboxCurrentMediaProps {
+  item?: LightboxItem;
+  index: number;
+  total: number;
+  zoomable: boolean;
+  zoom: ZoomState;
+  testId: (suffix: string) => string;
+  onLoadingChange: (loading: boolean) => void;
+  onWheel: (event: React.WheelEvent) => void;
+}
+
+// Wires the active item to the zoom state. Double-clicking zooms in, or snaps
+// back to 1x if already zoomed.
+export const LightboxCurrentMedia: FC<LightboxCurrentMediaProps> = ({
+  item,
+  index,
+  total,
+  zoomable,
+  zoom,
+  testId,
+  onLoadingChange,
+  onWheel,
+}) => {
+  if (!item) return null;
+
+  return (
+    <LightboxMedia
+      item={item}
+      index={index}
+      total={total}
+      zoomLevel={zoom.zoomLevel}
+      panOffset={zoom.panOffset}
+      zoomable={zoomable}
+      // Drag-panning is not wired up, so the transform transition is always on.
+      isDragging={false}
+      testId={testId}
+      onLoadStart={() => onLoadingChange(true)}
+      onLoaded={() => onLoadingChange(false)}
+      onWheel={onWheel}
+      onDoubleClick={zoom.zoomLevel > 1 ? zoom.resetZoom : zoom.zoomIn}
+    />
+  );
+};

package/src/components/data-display/Lightbox/LightboxMedia.tsx

@@ -0,0 +1,76 @@
+import type { FC } from 'react';
+import React from 'react';
+
+import type { LightboxItem } from './Lightbox.types';
+
+export interface LightboxMediaProps {
+  item: LightboxItem;
+  index: number;
+  total: number;
+  zoomLevel: number;
+  panOffset: { x: number; y: number };
+  zoomable: boolean;
+  isDragging: boolean;
+  testId: (suffix: string) => string;
+  onLoadStart: () => void;
+  onLoaded: () => void;
+  onWheel: (event: React.WheelEvent) => void;
+  onDoubleClick: () => void;
+}
+
+const cursorFor = (zoomLevel: number, zoomable: boolean): string => {
+  if (zoomLevel > 1) return 'move';
+  return zoomable ? 'zoom-in' : 'default';
+};
+
+export const LightboxMedia: FC<LightboxMediaProps> = ({
+  item,
+  index,
+  total,
+  zoomLevel,
+  panOffset,
+  zoomable,
+  isDragging,
+  testId,
+  onLoadStart,
+  onLoaded,
+  onWheel,
+  onDoubleClick,
+}) => {
+  if (item.type === 'video') {
+    return (
+      <video
+        src={item.src}
+        controls
+        style={{ maxWidth: '90vw', maxHeight: '80vh', objectFit: 'contain' }}
+        onLoadStart={onLoadStart}
+        onLoadedData={onLoaded}
+        aria-label={item.alt || `Video ${index + 1} of ${total}`}
+        data-testid={testId('video')}
+      />
+    );
+  }
+
+  return (
+    <img
+      src={item.src}
+      alt={item.alt || `Image ${index + 1} of ${total}`}
+      style={{
+        // At 1x the image is bounded by the viewport; once zoomed it is allowed
+        // to overflow so there is something to pan around.
+        maxWidth: zoomLevel === 1 ? '90vw' : 'none',
+        maxHeight: zoomLevel === 1 ? '80vh' : 'none',
+        transform: `scale(${zoomLevel}) translate(${panOffset.x}px, ${panOffset.y}px)`,
+        transformOrigin: 'center',
+        cursor: cursorFor(zoomLevel, zoomable),
+        transition: isDragging ? 'none' : 'transform 0.2s ease',
+        objectFit: 'contain',
+      }}
+      onLoad={onLoaded}
+      onWheel={onWheel}
+      onDoubleClick={onDoubleClick}
+      draggable={false}
+      data-testid={testId('image')}
+    />
+  );
+};

package/src/components/data-display/Lightbox/LightboxOverlay.tsx

@@ -0,0 +1,83 @@
+import type { FC } from 'react';
+import React from 'react';
+
+import type { LightboxProps } from './Lightbox.types';
+import {
+  LightboxAutoplayButton,
+  LightboxCloseButton,
+  LightboxNavButtons,
+  LightboxZoomControls,
+} from './LightboxControls';
+
+export interface LightboxOverlayProps {
+  testId: (suffix: string) => string;
+  itemCount: number;
+  currentIndex: number;
+  showControls: boolean;
+  loop: boolean;
+  autoplay: LightboxProps['autoplay'];
+  canZoom: boolean;
+  isAutoPlaying: boolean;
+  onClose: () => void;
+  onPrev: () => void;
+  onNext: () => void;
+  onZoomIn: () => void;
+  onZoomOut: () => void;
+  onResetZoom: () => void;
+  onToggleAutoplay: () => void;
+}
+
+// Everything that floats above the media: dismiss, step, zoom and slideshow.
+export const LightboxOverlay: FC<LightboxOverlayProps> = ({
+  testId,
+  itemCount,
+  currentIndex,
+  showControls,
+  loop,
+  autoplay,
+  canZoom,
+  isAutoPlaying,
+  onClose,
+  onPrev,
+  onNext,
+  onZoomIn,
+  onZoomOut,
+  onResetZoom,
+  onToggleAutoplay,
+}) => {
+  const hasMultiple = itemCount > 1;
+
+  return (
+    <>
+      <LightboxCloseButton testId={testId} onClose={onClose} />
+
+      {showControls && hasMultiple && (
+        <LightboxNavButtons
+          testId={testId}
+          // A non-looping gallery runs out of moves at either end.
+          atStart={!loop && currentIndex === 0}
+          atEnd={!loop && currentIndex === itemCount - 1}
+          onPrev={onPrev}
+          onNext={onNext}
+        />
+      )}
+
+      {canZoom && (
+        <LightboxZoomControls
+          testId={testId}
+          onZoomIn={onZoomIn}
+          onZoomOut={onZoomOut}
+          onResetZoom={onResetZoom}
+        />
+      )}
+
+      {autoplay && hasMultiple && (
+        <LightboxAutoplayButton
+          testId={testId}
+          isAutoPlaying={isAutoPlaying}
+          onToggle={onToggleAutoplay}
+        />
+      )}
+    </>
+  );
+};

package/src/components/data-display/Lightbox/LightboxStage.tsx

@@ -0,0 +1,97 @@
+import { Box, CircularProgress, DialogContent, Typography } from '@mui/material';
+import type { FC, ReactNode } from 'react';
+import React from 'react';
+
+import { captionSx, counterSx } from './Lightbox.constants';
+import type { LightboxItem } from './Lightbox.types';
+
+type TestId = (suffix: string) => string;
+
+export interface LightboxStageProps {
+  items: LightboxItem[];
+  currentItem?: LightboxItem;
+  currentIndex: number;
+  isLoading: boolean;
+  showCaptions: boolean;
+  thumbnails: boolean;
+  testId: TestId;
+  media: ReactNode;
+  thumbnailStrip: ReactNode;
+}
+
+// The viewport itself: the media, whatever floats over it, and the filmstrip.
+export const LightboxStage: FC<LightboxStageProps> = ({
+  items,
+  currentItem,
+  currentIndex,
+  isLoading,
+  showCaptions,
+  thumbnails,
+  testId,
+  media,
+  thumbnailStrip,
+}) => (
+  <DialogContent
+    sx={{
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      padding: 0,
+      position: 'relative',
+      height: '100vh',
+      overflow: 'hidden',
+    }}
+    data-testid={testId('content')}
+  >
+    {isLoading && (
+      <CircularProgress
+        sx={{ position: 'absolute', color: 'white', zIndex: 999 }}
+        data-testid={testId('loading')}
+      />
+    )}
+
+    <Box
+      sx={{
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        width: '100%',
+        height: '100%',
+      }}
+      data-testid={testId('image-container')}
+    >
+      {media}
+    </Box>
+
+    {showCaptions && currentItem?.caption && (
+      <Typography
+        id="lightbox-description"
+        sx={{
+          ...captionSx,
+          position: 'absolute',
+          // Sit above the filmstrip when there is one.
+          bottom: thumbnails ? 120 : 16,
+          left: '50%',
+          transform: 'translateX(-50%)',
+          maxWidth: '80vw',
+          padding: 2,
+        }}
+        data-testid={testId('caption')}
+      >
+        {currentItem.caption}
+      </Typography>
+    )}
+
+    {items.length > 1 && (
+      <Typography
+        sx={{ ...counterSx, position: 'absolute', top: 70, right: 16, padding: '4px 8px' }}
+        aria-live="polite"
+        data-testid={testId('counter')}
+      >
+        {currentIndex + 1} / {items.length}
+      </Typography>
+    )}
+
+    {thumbnailStrip}
+  </DialogContent>
+);

package/src/components/data-display/Lightbox/LightboxThumbnails.tsx

@@ -0,0 +1,83 @@
+import PlayIcon from '@mui/icons-material/PlayArrow';
+import { Box } from '@mui/material';
+import type { FC } from 'react';
+import React from 'react';
+
+import { thumbnailStripSx } from './Lightbox.constants';
+import type { LightboxItem } from './Lightbox.types';
+
+const THUMB_WIDTH = 60;
+const THUMB_HEIGHT = 40;
+
+const VideoThumbnail: FC = () => (
+  <Box
+    sx={{
+      width: '100%',
+      height: '100%',
+      background: 'rgba(255, 255, 255, 0.1)',
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+    }}
+  >
+    <PlayIcon sx={{ color: 'white', fontSize: 16 }} />
+  </Box>
+);
+
+export interface LightboxThumbnailsProps {
+  items: LightboxItem[];
+  currentIndex: number;
+  testId: (suffix: string) => string;
+  onSelect: (index: number) => void;
+}
+
+export const LightboxThumbnails: FC<LightboxThumbnailsProps> = ({
+  items,
+  currentIndex,
+  testId,
+  onSelect,
+}) => (
+  <Box
+    sx={{
+      ...thumbnailStripSx,
+      position: 'absolute',
+      bottom: 16,
+      left: '50%',
+      transform: 'translateX(-50%)',
+      display: 'flex',
+      gap: 1,
+      maxWidth: '90vw',
+      overflowX: 'auto',
+      padding: 1,
+    }}
+    data-testid={testId('thumbnails')}
+  >
+    {items.map((item, index) => (
+      <Box
+        key={`${item.src}-${index}`}
+        onClick={() => onSelect(index)}
+        sx={{
+          width: THUMB_WIDTH,
+          height: THUMB_HEIGHT,
+          cursor: 'pointer',
+          border: currentIndex === index ? '2px solid white' : '2px solid transparent',
+          borderRadius: 0.5,
+          overflow: 'hidden',
+          flexShrink: 0,
+          '&:hover': { border: '2px solid rgba(255, 255, 255, 0.7)' },
+        }}
+        data-testid={testId(`thumbnail-${index}`)}
+      >
+        {item.type === 'video' ? (
+          <VideoThumbnail />
+        ) : (
+          <img
+            src={item.src}
+            alt={item.alt || `Thumbnail ${index + 1}`}
+            style={{ width: '100%', height: '100%', objectFit: 'cover' }}
+          />
+        )}
+      </Box>
+    ))}
+  </Box>
+);

package/src/components/data-display/Lightbox/useLightbox.ts

@@ -0,0 +1,80 @@
+import { useCallback, useImperativeHandle, useState } from 'react';
+import type React from 'react';
+
+import {
+  useAutoplay,
+  useLightboxKeyboard,
+  useNavigation,
+  usePreloader,
+  useSwipe,
+  useWheelZoom,
+  useZoomState,
+} from './Lightbox.hooks';
+import type { ResolvedLightboxProps } from './Lightbox.helpers';
+import type { LightboxRef } from './Lightbox.types';
+
+// Wires the independent concerns together in dependency order: zoom, then
+// navigation (which resets zoom), then autoplay (which advances), then the
+// input handlers that close.
+export const useLightbox = (
+  { isOpen, onClose, items, startIndex, showControls, loop, autoplay, zoomable }: ResolvedLightboxProps,
+  ref: React.ForwardedRef<LightboxRef>,
+) => {
+  const [isLoading, setIsLoading] = useState(false);
+
+  const preloadImage = usePreloader();
+  const zoom = useZoomState();
+
+  const { currentIndex, goToIndex, next, prev } = useNavigation({
+    items,
+    loop,
+    startIndex,
+    resetZoom: zoom.resetZoom,
+    preloadImage,
+  });
+
+  const currentItem = items[currentIndex];
+  const canZoom = Boolean(zoomable && currentItem && currentItem.type !== 'video');
+
+  const handleWheel = useWheelZoom({ enabled: canZoom, setZoomLevel: zoom.setZoomLevel });
+
+  const { isAutoPlaying, setIsAutoPlaying, stopAutoplay } = useAutoplay({
+    isOpen,
+    autoplay,
+    itemCount: items.length,
+    currentIndex,
+    next,
+  });
+
+  const close = useCallback(() => {
+    stopAutoplay();
+    onClose();
+  }, [stopAutoplay, onClose]);
+
+  // open() with no argument starts at the first item.
+  const open = useCallback((index = 0) => goToIndex(index), [goToIndex]);
+
+  useImperativeHandle(ref, () => ({ open, close, next, prev, goTo: goToIndex }));
+
+  useLightboxKeyboard({ isOpen, showControls, autoplay, close, prev, next, setIsAutoPlaying });
+
+  const { handleTouchStart, handleTouchEnd } = useSwipe({ prev, next, close });
+
+  return {
+    currentIndex,
+    currentItem,
+    canZoom,
+    isLoading,
+    setIsLoading,
+    isAutoPlaying,
+    setIsAutoPlaying,
+    zoom,
+    handleWheel,
+    goToIndex,
+    next,
+    prev,
+    close,
+    handleTouchStart,
+    handleTouchEnd,
+  };
+};

package/src/components/data-display/LoadingState/LoadingState.helpers.ts

@@ -0,0 +1,52 @@
+import type { LoadingStateProps, LoadingStateSize } from './LoadingState.types';
+
+export const SIZE_MAP: Record<
+  LoadingStateSize,
+  { spinner: number; text: 'body2' | 'body1' | 'h6' }
+> = {
+  sm: { spinner: 24, text: 'body2' },
+  md: { spinner: 40, text: 'body1' },
+  lg: { spinner: 56, text: 'h6' },
+};
+
+export const SKELETON_ROW_HEIGHT: Record<LoadingStateSize, number> = {
+  sm: 20,
+  md: 28,
+  lg: 36,
+};
+
+type LoadingStateDefaultedKeys = 'variant' | 'size' | 'skeletonRows';
+
+type ResolvedLoadingStateProps = LoadingStateProps &
+  Required<Pick<LoadingStateProps, LoadingStateDefaultedKeys>>;
+
+const LOADING_STATE_DEFAULTS: Pick<LoadingStateProps, LoadingStateDefaultedKeys> = {
+  variant: 'spinner',
+  size: 'md',
+  skeletonRows: 3,
+};
+
+// 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: LoadingStateProps): Partial<LoadingStateProps> =>
+  Object.fromEntries(
+    Object.entries(props).filter(([, value]) => value !== undefined),
+  ) as Partial<LoadingStateProps>;
+
+export const resolveLoadingStateProps = (
+  props: LoadingStateProps,
+): ResolvedLoadingStateProps =>
+  ({ ...LOADING_STATE_DEFAULTS, ...definedProps(props) }) as ResolvedLoadingStateProps;
+
+/**
+ * Test ids come in three flavours here: the container falls back to a bare
+ * `loading-state`, the labelled parts to `loading-state-<part>`, and the
+ * skeleton rows to nothing at all when the caller supplied no base id.
+ */
+export const makeTestIds = (dataTestId?: string) => ({
+  base: dataTestId || 'loading-state',
+  optional: (suffix: string): string | undefined =>
+    dataTestId ? `${dataTestId}-${suffix}` : undefined,
+  named: (suffix: string): string =>
+    dataTestId ? `${dataTestId}-${suffix}` : `loading-state-${suffix}`,
+});