@12-apps/ui 1.0.0 → 1.3.1

package/src/components/data-display/LazyImage/LazyImage.tsx

@@ -1,7 +1,9 @@
 import { Box, CircularProgress, styled, useTheme } from '@mui/material';
-import React, { useCallback, useEffect, useRef, useState } from 'react';
+import React from 'react';
 import { Skeleton } from '../../layout/Skeleton';
-import type { LazyImageProps, LazyImageState } from './LazyImage.types';
+import type { ResolvedLazyImageProps } from './LazyImage.hooks';
+import { imgPassThrough, resolveLazyImageProps, useLazyImage } from './LazyImage.hooks';
+import type { LazyImageProps } from './LazyImage.types';
 
 const ImageContainer = styled(Box)(() => ({
   position: 'relative',
@@ -47,277 +49,176 @@ const FallbackContainer = styled(Box)(({ theme }) => ({
   left: 0,
 }));
 
-/**
- * LazyImage component with enhanced features for optimized image loading
- * Supports lazy loading, placeholders, error handling, and various loading states
- */
-export const LazyImage = React.memo<LazyImageProps>(function LazyImage({
-  src,
-  alt,
-  width,
-  height = 'auto',
-  placeholder,
-  fallback,
-  loadingState = 'skeleton',
-  showSpinner,
-  objectFit = 'cover',
-  objectPosition = 'center',
-  borderRadius,
-  lazy = true,
-  rootMargin = '100px',
-  threshold = 0,
-  fadeIn = true,
-  fadeInDuration = 300,
-  onLoad,
-  onError,
-  onLoadStart,
-  retryOnError = false,
-  maxRetries = 3,
-  retryDelay = 1000,
-  decoding = 'async',
-  loading: nativeLoading,
-  fetchPriority: _fetchPriority,
-  skeletonProps = {},
-  spinnerProps = {},
-  sx = {},
-  className,
-  'data-testid': dataTestId,
-  'aria-label': ariaLabel,
-  'aria-describedby': ariaDescribedBy,
-  role = 'img',
-  ...imgProps
-}) {
+/** The box the image occupies, shared by the real image and every stand-in for it. */
+interface BoxMetrics {
+  width?: number | string;
+  height?: number | string;
+  objectFit: NonNullable<LazyImageProps['objectFit']>;
+  objectPosition: string;
+  borderRadius?: number | string;
+}
+
+interface IndicatorProps {
+  props: ResolvedLazyImageProps;
+  metrics: BoxMetrics;
+}
+
+const SkeletonIndicator: React.FC<IndicatorProps> = ({ props, metrics }) => (
+  <Skeleton
+    variant="rectangular"
+    width={metrics.width || '100%'}
+    height={metrics.height || 200}
+    animation={props.skeletonProps.animation || 'pulse'}
+    intensity={props.skeletonProps.intensity}
+    borderRadius={props.borderRadius}
+    data-testid={`${props['data-testid']}-skeleton`}
+  />
+);
+
+const SpinnerIndicator: React.FC<IndicatorProps> = ({ props }) => {
   const theme = useTheme();
-  const imgRef = useRef<HTMLImageElement>(null);
-  const containerRef = useRef<HTMLDivElement>(null);
-  const retryTimeoutRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
-
-  // Handle deprecated showSpinner prop
-  const effectiveLoadingState = showSpinner ? 'spinner' : loadingState;
-
-  const [state, setState] = useState<LazyImageState>({
-    isLoading: true,
-    hasError: false,
-    isVisible: !lazy, // If not lazy, load immediately
-    retryCount: 0,
-    currentSrc: lazy ? (placeholder || null) : src,
-  });
-
-  // Clean up retry timeout on unmount
-  useEffect(() => {
-    return () => {
-      if (retryTimeoutRef.current) {
-        clearTimeout(retryTimeoutRef.current);
-      }
-    };
-  }, []);
-
-  // Intersection Observer for lazy loading
-  useEffect(() => {
-    if (!lazy || state.isVisible) {
-      return;
-    }
-
-    const observer = new IntersectionObserver(
-      (entries) => {
-        entries.forEach((entry) => {
-          if (entry.isIntersecting) {
-            setState((prev) => ({ ...prev, isVisible: true, currentSrc: src }));
-            onLoadStart?.();
-            observer.unobserve(entry.target);
-          }
-        });
-      },
-      {
-        rootMargin,
-        threshold,
-      }
-    );
-
-    if (containerRef.current) {
-      observer.observe(containerRef.current);
-    }
-
-    return () => {
-      if (containerRef.current) {
-        observer.unobserve(containerRef.current);
-      }
-    };
-  }, [lazy, src, rootMargin, threshold, state.isVisible, onLoadStart]);
-
-  // Load image when it becomes visible
-  useEffect(() => {
-    if (!state.isVisible || !src || state.currentSrc === src) {
-      return;
-    }
-
-    setState((prev) => ({ ...prev, currentSrc: src, isLoading: true, hasError: false }));
-  }, [state.isVisible, src, state.currentSrc]);
+  const { spinnerProps } = props;
 
-  const handleImageLoad = useCallback(
-    (event: React.SyntheticEvent<HTMLImageElement>) => {
-      setState((prev) => ({ ...prev, isLoading: false, hasError: false, retryCount: 0 }));
-      onLoad?.(event);
-    },
-    [onLoad]
+  return (
+    <SpinnerOverlay>
+      <CircularProgress
+        size={spinnerProps.size || 40}
+        thickness={spinnerProps.thickness || 4}
+        sx={{ color: spinnerProps.color || theme.palette.primary.main }}
+        data-testid={`${props['data-testid']}-spinner`}
+      />
+    </SpinnerOverlay>
   );
+};
 
-  const handleImageError = useCallback(
-    (event: React.SyntheticEvent<HTMLImageElement>) => {
-      const shouldRetry = retryOnError && state.retryCount < maxRetries;
+const PlaceholderIndicator: React.FC<IndicatorProps & { hasSrc: boolean }> = ({
+  props,
+  metrics,
+  hasSrc,
+}) => {
+  // Once a src has been chosen the real <img> is on screen, so the placeholder
+  // would only stack behind it.
+  if (!props.placeholder || hasSrc) return null;
 
-      if (shouldRetry) {
-        retryTimeoutRef.current = setTimeout(() => {
-          setState((prev) => ({
-            ...prev,
-            retryCount: prev.retryCount + 1,
-            currentSrc: `${src}?retry=${prev.retryCount + 1}`, // Force reload with cache buster
-          }));
-        }, retryDelay);
-      } else {
-        setState((prev) => ({ ...prev, isLoading: false, hasError: true }));
-        onError?.(event);
-      }
-    },
-    [onError, retryOnError, state.retryCount, maxRetries, retryDelay, src]
+  return (
+    <StyledImage
+      src={props.placeholder}
+      alt={`${props.alt} (loading)`}
+      style={metrics}
+      data-testid={`${props['data-testid']}-placeholder`}
+    />
   );
-
-  // Determine what to show for loading state
-  const renderLoadingState = () => {
-    if (!state.isLoading) return null;
-
-    switch (effectiveLoadingState) {
-      case 'skeleton':
-        return (
-          <Skeleton
-            variant="rectangular"
-            width={width || '100%'}
-            height={height || 200}
-            animation={skeletonProps.animation || 'pulse'}
-            intensity={skeletonProps.intensity}
-            borderRadius={borderRadius}
-            data-testid={`${dataTestId}-skeleton`}
-          />
-        );
-      case 'spinner':
-        return (
-          <SpinnerOverlay>
-            <CircularProgress
-              size={spinnerProps.size || 40}
-              thickness={spinnerProps.thickness || 4}
-              sx={{ color: spinnerProps.color || theme.palette.primary.main }}
-              data-testid={`${dataTestId}-spinner`}
-            />
-          </SpinnerOverlay>
-        );
-      case 'placeholder':
-        if (placeholder && !state.currentSrc) {
-          return (
-            <StyledImage
-              src={placeholder}
-              alt={`${alt} (loading)`}
-              style={{
-                width,
-                height,
-                objectFit,
-                objectPosition,
-              }}
-              data-testid={`${dataTestId}-placeholder`}
-            />
-          );
-        }
-        return null;
-      case 'none':
-      default:
-        return null;
-    }
-  };
-
-  // Render error fallback
-  const renderErrorFallback = () => {
-    if (!state.hasError || !fallback) return null;
-
-    if (typeof fallback === 'string') {
-      return (
-        <StyledImage
-          src={fallback}
-          alt={`${alt} (fallback)`}
-          style={{
-            width,
-            height,
-            objectFit,
-            objectPosition,
-          }}
-          fadeIn={false}
-          isLoaded={true}
-          data-testid={`${dataTestId}-fallback`}
-        />
-      );
-    }
-
+};
+
+const LoadingIndicator: React.FC<
+  IndicatorProps & { kind: NonNullable<LazyImageProps['loadingState']>; hasSrc: boolean }
+> = ({ kind, hasSrc, ...rest }) => {
+  switch (kind) {
+    case 'skeleton':
+      return <SkeletonIndicator {...rest} />;
+    case 'spinner':
+      return <SpinnerIndicator {...rest} />;
+    case 'placeholder':
+      return <PlaceholderIndicator {...rest} hasSrc={hasSrc} />;
+    default:
+      return null;
+  }
+};
+
+const ErrorFallback: React.FC<IndicatorProps> = ({ props, metrics }) => {
+  const { alt, fallback, borderRadius } = props;
+  const testId = props['data-testid'];
+
+  if (!fallback) return null;
+
+  if (typeof fallback === 'string') {
     return (
-      <FallbackContainer
-        sx={{
-          width,
-          height,
-          borderRadius,
-        }}
-        data-testid={`${dataTestId}-fallback`}
-      >
-        {fallback}
-      </FallbackContainer>
+      <StyledImage
+        src={fallback}
+        alt={`${alt} (fallback)`}
+        style={metrics}
+        fadeIn={false}
+        isLoaded={true}
+        data-testid={`${testId}-fallback`}
+      />
     );
-  };
+  }
+
+  return (
+    <FallbackContainer
+      sx={{ width: metrics.width, height: metrics.height, borderRadius }}
+      data-testid={`${testId}-fallback`}
+    >
+      {fallback}
+    </FallbackContainer>
+  );
+};
 
-  const imageStyles: React.CSSProperties = {
+/**
+ * LazyImage component with enhanced features for optimized image loading
+ * Supports lazy loading, placeholders, error handling, and various loading states
+ */
+export const LazyImage = React.memo<LazyImageProps>(function LazyImage(rawProps) {
+  const props = resolveLazyImageProps(rawProps);
+  const {
+    state,
+    containerRef,
+    effectiveLoadingState,
+    handleImageLoad,
+    handleImageError,
+    showImage,
+    showLoading,
+  } = useLazyImage(props);
+
+  const { width, height, borderRadius, alt } = props;
+  const testId = props['data-testid'];
+  const metrics: BoxMetrics = {
     width,
     height,
-    objectFit,
-    objectPosition,
+    objectFit: props.objectFit,
+    objectPosition: props.objectPosition,
     borderRadius,
-    ...sx,
   };
 
-  const showImage = state.currentSrc && !state.hasError;
-  const showLoading = state.isLoading && (!state.currentSrc || effectiveLoadingState !== 'placeholder');
-
   return (
     <ImageContainer
       ref={containerRef}
-      className={className}
-      sx={{
-        width: width || 'auto',
-        height: height || 'auto',
-        borderRadius,
-      }}
-      data-testid={dataTestId}
+      className={props.className}
+      sx={{ width: width || 'auto', height: height || 'auto', borderRadius }}
+      data-testid={testId}
     >
-      {showLoading && renderLoadingState()}
+      {showLoading && (
+        <LoadingIndicator
+          kind={effectiveLoadingState}
+          props={props}
+          metrics={metrics}
+          hasSrc={Boolean(state.currentSrc)}
+        />
+      )}
 
       {showImage && (
         <StyledImage
-          ref={imgRef}
           src={state.currentSrc || undefined}
           alt={alt}
           onLoad={handleImageLoad}
           onError={handleImageError}
-          fadeIn={fadeIn}
-          fadeInDuration={fadeInDuration}
+          fadeIn={props.fadeIn}
+          fadeInDuration={props.fadeInDuration}
           isLoaded={!state.isLoading}
-          decoding={decoding}
-          loading={lazy ? 'lazy' : nativeLoading}
-          style={imageStyles}
-          aria-label={ariaLabel || alt}
-          aria-describedby={ariaDescribedBy}
-          role={role}
-          data-testid={`${dataTestId}-img`}
-          {...imgProps}
+          decoding={props.decoding}
+          loading={props.lazy ? 'lazy' : props.loading}
+          style={{ ...metrics, ...props.sx }}
+          aria-label={props['aria-label'] || alt}
+          aria-describedby={props['aria-describedby']}
+          role={props.role}
+          data-testid={`${testId}-img`}
+          {...imgPassThrough(props)}
         />
       )}
 
-      {state.hasError && renderErrorFallback()}
+      {state.hasError && <ErrorFallback props={props} metrics={metrics} />}
     </ImageContainer>
   );
 });
 
-LazyImage.displayName = 'LazyImage';
+LazyImage.displayName = 'LazyImage';

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

@@ -0,0 +1,53 @@
+export const MIN_ZOOM = 0.5;
+export const MAX_ZOOM = 5;
+export const ZOOM_STEP = 1.2;
+// Each wheel notch is ~100 deltaY, so this makes one notch a 1x zoom change.
+export const WHEEL_ZOOM_FACTOR = 0.01;
+
+export const DEFAULT_AUTOPLAY_INTERVAL_MS = 4000;
+export const MIN_SWIPE_DISTANCE = 50;
+export const OVERLAY_Z_INDEX = 1000;
+
+const SCRIM = 'rgba(0, 0, 0, 0.5)';
+const SCRIM_HOVER = 'rgba(0, 0, 0, 0.7)';
+
+export const overlayButtonSx = {
+  color: 'white',
+  backgroundColor: SCRIM,
+  '&:hover': { backgroundColor: SCRIM_HOVER },
+} as const;
+
+// The arrows drop their hover treatment at the ends of a non-looping gallery and
+// dim instead, so a disabled arrow does not look pressable.
+export const navButtonSx = {
+  color: 'white',
+  backgroundColor: SCRIM,
+  '&:hover:not(:disabled)': { backgroundColor: SCRIM_HOVER },
+  '&:disabled': { color: 'rgba(255, 255, 255, 0.3)' },
+} as const;
+
+export const captionSx = {
+  color: 'white',
+  textAlign: 'center',
+  backgroundColor: SCRIM_HOVER,
+  borderRadius: 1,
+} as const;
+
+export const counterSx = {
+  color: 'white',
+  fontSize: '0.875rem',
+  backgroundColor: SCRIM,
+  borderRadius: 1,
+} as const;
+
+export const thumbnailStripSx = {
+  background: SCRIM,
+  borderRadius: 1,
+} as const;
+
+// Every element gets `${dataTestId}-suffix` when the caller supplied an id, and
+// `lightbox-suffix` otherwise.
+export const makeTestId =
+  (dataTestId?: string) =>
+  (suffix: string): string =>
+    dataTestId ? `${dataTestId}-${suffix}` : `lightbox-${suffix}`;

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

@@ -0,0 +1,39 @@
+import type { LightboxProps } from './Lightbox.types';
+
+type LightboxDefaultedKeys =
+  | 'isOpen'
+  | 'items'
+  | 'startIndex'
+  | 'showControls'
+  | 'showCaptions'
+  | 'loop'
+  | 'autoplay'
+  | 'thumbnails'
+  | 'zoomable';
+
+export type ResolvedLightboxProps = LightboxProps &
+  Required<Pick<LightboxProps, LightboxDefaultedKeys>>;
+
+const LIGHTBOX_DEFAULTS: Pick<LightboxProps, LightboxDefaultedKeys> = {
+  isOpen: false,
+  items: [],
+  startIndex: 0,
+  showControls: true,
+  showCaptions: true,
+  loop: false,
+  autoplay: false,
+  thumbnails: false,
+  zoomable: true,
+};
+
+// Strips explicitly-undefined props before the merge, so `prop={undefined}` still
+// falls back to the default exactly as a destructuring default would.
+const definedProps = (props: LightboxProps): Partial<LightboxProps> =>
+  Object.fromEntries(
+    Object.entries(props).filter(([, value]) => value !== undefined),
+  ) as Partial<LightboxProps>;
+
+// Applied as a merge rather than destructuring defaults, which would otherwise
+// put nine branches into the component's own complexity budget.
+export const resolveLightboxProps = (props: LightboxProps): ResolvedLightboxProps =>
+  ({ ...LIGHTBOX_DEFAULTS, ...definedProps(props) }) as ResolvedLightboxProps;