@12-apps/ui 1.0.0 → 1.3.1

package/src/components/data-display/HoverCard/HoverCard.stories.tsx

@@ -1,4 +1,6 @@
-import { Person, Star, Verified } from '@mui/icons-material';
+import Person from '@mui/icons-material/Person';
+import Star from '@mui/icons-material/Star';
+import Verified from '@mui/icons-material/Verified';
 import { Box,Button, Chip, Stack, Typography } from '@mui/material';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import React from 'react';

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

@@ -155,8 +155,8 @@ export const KeyboardNavigation: Story = {
 
     await step('Focus trigger with Tab key', async () => {
       const trigger = await canvas.findByTestId('keyboard-trigger');
-      trigger.focus();
-      expect(trigger).toHaveFocus();
+      await userEvent.click(trigger);
+      await waitFor(() => expect(trigger).toHaveFocus());
     });
 
     await step('HoverCard should appear on focus', async () => {
@@ -272,8 +272,8 @@ export const FocusManagement: Story = {
 
     await step('Focus should remain on trigger when hovering', async () => {
       const trigger = await canvas.findByTestId('focus-trigger');
-      trigger.focus();
-      expect(trigger).toHaveFocus();
+      await userEvent.click(trigger);
+      await waitFor(() => expect(trigger).toHaveFocus());
 
       await userEvent.hover(trigger);
 
@@ -603,7 +603,7 @@ export const VisualStates: Story = {
       await new Promise((resolve) => window.setTimeout(resolve, 200));
 
       const disabledCard = canvasElement.ownerDocument.body.querySelector('h6');
-      expect(disabledCard).not.toBeInTheDocument();
+      await waitFor(() => expect(disabledCard).not.toBeInTheDocument());
     });
   },
 };

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

@@ -0,0 +1,99 @@
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+
+import type { InteractiveTooltipProps } from './InteractiveTooltip.types';
+
+type TooltipDefaultedKeys = 'variant' | 'size' | 'glow' | 'pulse' | 'maxWidth' | 'clickable';
+
+type ResolvedTooltipProps = InteractiveTooltipProps &
+  Required<Pick<InteractiveTooltipProps, TooltipDefaultedKeys>>;
+
+const TOOLTIP_DEFAULTS: Pick<InteractiveTooltipProps, TooltipDefaultedKeys> = {
+  variant: 'default',
+  size: 'md',
+  glow: false,
+  pulse: false,
+  maxWidth: 300,
+  clickable: true,
+};
+
+// 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: InteractiveTooltipProps): Partial<InteractiveTooltipProps> =>
+  Object.fromEntries(
+    Object.entries(props).filter(([, value]) => value !== undefined),
+  ) as Partial<InteractiveTooltipProps>;
+
+export const resolveTooltipProps = (
+  props: InteractiveTooltipProps,
+): ResolvedTooltipProps =>
+  ({ ...TOOLTIP_DEFAULTS, ...definedProps(props) }) as ResolvedTooltipProps;
+
+interface PinOptions {
+  clickable: boolean;
+  onPin?: () => void;
+  onUnpin?: () => void;
+}
+
+/**
+ * Clicking the trigger pins the tooltip open; clicking anywhere that is neither
+ * the tooltip nor the trigger unpins it. The listener only exists while pinned,
+ * so an unpinned tooltip costs nothing on every document click.
+ */
+export const usePinnedTooltip = ({ clickable, onPin, onUnpin }: PinOptions) => {
+  const [isPinned, setIsPinned] = useState(false);
+  const [isControlledOpen, setIsControlledOpen] = useState(false);
+  const wrapperRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!isPinned || !clickable) {
+      return;
+    }
+
+    const handleClickOutside = (event: MouseEvent) => {
+      const targetElement = event.target as Element;
+
+      // Check if click was on tooltip or trigger
+      const isClickOnTooltip = targetElement.closest('[role="tooltip"]');
+      const isClickOnTrigger = wrapperRef.current?.contains(targetElement);
+
+      if (isClickOnTooltip || isClickOnTrigger) {
+        return;
+      }
+
+      // Click was outside - unpin
+      setIsPinned(false);
+      setIsControlledOpen(false);
+      onUnpin?.();
+    };
+
+    document.addEventListener('mousedown', handleClickOutside);
+    return () => {
+      document.removeEventListener('mousedown', handleClickOutside);
+    };
+  }, [isPinned, clickable, onUnpin]);
+
+  const handleClick = useCallback(
+    (e: React.MouseEvent) => {
+      if (!clickable) return;
+
+      e.preventDefault();
+      e.stopPropagation();
+
+      setIsPinned((current) => {
+        const newPinned = !current;
+        setIsControlledOpen(newPinned);
+
+        if (newPinned) {
+          onPin?.();
+        } else {
+          onUnpin?.();
+        }
+
+        return newPinned;
+      });
+    },
+    [clickable, onPin, onUnpin],
+  );
+
+  return { isPinned, isControlledOpen, wrapperRef, handleClick };
+};

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

@@ -0,0 +1,87 @@
+import { alpha, keyframes } from '@mui/material';
+import type { CSSObject, Theme } from '@mui/material';
+
+const pulseAnimation = keyframes`
+  0% {
+    transform: scale(1);
+    opacity: 1;
+  }
+  70% {
+    transform: scale(1.05);
+    opacity: 0.8;
+  }
+  100% {
+    transform: scale(1);
+    opacity: 1;
+  }
+`;
+
+const SIZE_MAP = {
+  sm: { fontSize: '0.75rem', padding: '4px 8px' },
+  md: { fontSize: '0.875rem', padding: '6px 12px' },
+  lg: { fontSize: '1rem', padding: '8px 16px' },
+} as const;
+
+export const getSizeStyles = (size?: string): { fontSize: string; padding: string } =>
+  SIZE_MAP[size as keyof typeof SIZE_MAP] || SIZE_MAP.md;
+
+export const variantStyles = (theme: Theme, variant?: string): CSSObject => {
+  switch (variant) {
+    case 'default':
+      return {
+        backgroundColor: alpha(theme.palette.grey[900], 0.92),
+        color: theme.palette.common.white,
+        boxShadow: `0 4px 12px ${alpha(theme.palette.common.black, 0.3)}`,
+      };
+    case 'dark':
+      return {
+        backgroundColor: '#000000',
+        color: theme.palette.common.white,
+        boxShadow: `0 6px 16px ${alpha(theme.palette.common.black, 0.5)}`,
+        border: `1px solid ${alpha(theme.palette.common.white, 0.1)}`,
+      };
+    case 'light':
+      return {
+        backgroundColor: theme.palette.common.white,
+        color: theme.palette.grey[900],
+        border: `1px solid ${alpha(theme.palette.grey[400], 0.4)}`,
+        boxShadow: `0 4px 16px ${alpha(theme.palette.common.black, 0.15)}`,
+      };
+    case 'glass':
+      return {
+        backgroundColor: alpha(theme.palette.background.paper, 0.75),
+        backdropFilter: 'blur(24px) saturate(180%)',
+        WebkitBackdropFilter: 'blur(24px) saturate(180%)',
+        border: `1px solid ${alpha(theme.palette.divider, 0.3)}`,
+        color: theme.palette.text.primary,
+        boxShadow: `0 8px 32px ${alpha(theme.palette.common.black, 0.12)}`,
+      };
+    default:
+      return {};
+  }
+};
+
+// glow and pulse are independent flags. The three combinations used to be spelled
+// out one by one, but each is just the union of whichever flags are set.
+export const emphasisStyles = (theme: Theme, glow?: boolean, pulse?: boolean): CSSObject => ({
+  ...(glow && {
+    boxShadow: `0 0 15px 3px ${alpha(theme.palette.primary.main, 0.4)} !important`,
+    filter: 'brightness(1.05)',
+  }),
+  ...(pulse && {
+    animation: `${pulseAnimation} 2s infinite`,
+  }),
+});
+
+export const arrowColor = (theme: Theme, variant?: string): string => {
+  switch (variant) {
+    case 'light':
+      return theme.palette.common.white;
+    case 'glass':
+      return alpha(theme.palette.background.paper, 0.75);
+    case 'dark':
+      return '#000000';
+    default:
+      return alpha(theme.palette.grey[900], 0.92);
+  }
+};

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

@@ -1,35 +1,16 @@
-import { alpha, keyframes, Tooltip as MuiTooltip } from '@mui/material';
+import { Tooltip as MuiTooltip } from '@mui/material';
 import { styled } from '@mui/material/styles';
-import React, { useCallback, useEffect, useId, useRef, useState } from 'react';
-
+import React from 'react';
+
+import { resolveTooltipProps, usePinnedTooltip } from './InteractiveTooltip.hooks';
+import {
+  arrowColor,
+  emphasisStyles,
+  getSizeStyles,
+  variantStyles,
+} from './InteractiveTooltip.styles';
 import type { InteractiveTooltipProps } from './InteractiveTooltip.types';
 
-// Define pulse animation
-const pulseAnimation = keyframes`
-  0% {
-    transform: scale(1);
-    opacity: 1;
-  }
-  70% {
-    transform: scale(1.05);
-    opacity: 0.8;
-  }
-  100% {
-    transform: scale(1);
-    opacity: 1;
-  }
-`;
-
-const getSizeStyles = (size: string): { fontSize: string; padding: string } => {
-  const sizeMap = {
-    sm: { fontSize: '0.75rem', padding: '4px 8px' },
-    md: { fontSize: '0.875rem', padding: '6px 12px' },
-    lg: { fontSize: '1rem', padding: '8px 16px' },
-  } as const;
-
-  return sizeMap[size as keyof typeof sizeMap] || sizeMap.md;
-};
-
 const StyledTooltip = styled(MuiTooltip, {
   shouldForwardProp: (prop) =>
     !['customVariant', 'customSize', 'glow', 'pulse'].includes(prop as string),
@@ -38,7 +19,7 @@ const StyledTooltip = styled(MuiTooltip, {
   customSize?: string;
   glow?: boolean;
   pulse?: boolean;
-}>(({ theme, customVariant, customSize = 'md', glow, pulse }) => {
+}>(({ theme, customVariant, customSize, glow, pulse }) => {
   const sizeStyles = getSizeStyles(customSize);
 
   return {
@@ -50,148 +31,40 @@ const StyledTooltip = styled(MuiTooltip, {
       transition: 'all 0.3s ease',
       position: 'relative',
       overflow: 'hidden',
-
-      // Variant styles - made more distinct
-      ...(customVariant === 'default' && {
-        backgroundColor: alpha(theme.palette.grey[900], 0.92),
-        color: theme.palette.common.white,
-        boxShadow: `0 4px 12px ${alpha(theme.palette.common.black, 0.3)}`,
-      }),
-
-      ...(customVariant === 'dark' && {
-        backgroundColor: '#000000',
-        color: theme.palette.common.white,
-        boxShadow: `0 6px 16px ${alpha(theme.palette.common.black, 0.5)}`,
-        border: `1px solid ${alpha(theme.palette.common.white, 0.1)}`,
-      }),
-
-      ...(customVariant === 'light' && {
-        backgroundColor: theme.palette.common.white,
-        color: theme.palette.grey[900],
-        border: `1px solid ${alpha(theme.palette.grey[400], 0.4)}`,
-        boxShadow: `0 4px 16px ${alpha(theme.palette.common.black, 0.15)}`,
-      }),
-
-      ...(customVariant === 'glass' && {
-        backgroundColor: alpha(theme.palette.background.paper, 0.75),
-        backdropFilter: 'blur(24px) saturate(180%)',
-        WebkitBackdropFilter: 'blur(24px) saturate(180%)',
-        border: `1px solid ${alpha(theme.palette.divider, 0.3)}`,
-        color: theme.palette.text.primary,
-        boxShadow: `0 8px 32px ${alpha(theme.palette.common.black, 0.12)}`,
-      }),
-
-      // Glow effect
-      ...(glow &&
-        !pulse && {
-          boxShadow: `0 0 15px 3px ${alpha(theme.palette.primary.main, 0.4)} !important`,
-          filter: 'brightness(1.05)',
-        }),
-
-      // Pulse animation
-      ...(pulse &&
-        !glow && {
-          animation: `${pulseAnimation} 2s infinite`,
-        }),
-
-      // Both glow and pulse
-      ...(glow &&
-        pulse && {
-          boxShadow: `0 0 15px 3px ${alpha(theme.palette.primary.main, 0.4)} !important`,
-          filter: 'brightness(1.05)',
-          animation: `${pulseAnimation} 2s infinite`,
-        }),
+      ...variantStyles(theme, customVariant),
+      ...emphasisStyles(theme, glow, pulse),
     },
 
     '& .MuiTooltip-arrow': {
-      color:
-        customVariant === 'light'
-          ? theme.palette.common.white
-          : customVariant === 'glass'
-            ? alpha(theme.palette.background.paper, 0.75)
-            : customVariant === 'dark'
-              ? '#000000'
-              : alpha(theme.palette.grey[900], 0.92),
+      color: arrowColor(theme, customVariant),
     },
   };
 });
 
 export const InteractiveTooltip = React.forwardRef<HTMLDivElement, InteractiveTooltipProps>(
-  (
-    {
-      variant = 'default',
-      size = 'md',
-      glow = false,
-      pulse = false,
-      maxWidth = 300,
+  (rawProps, ref) => {
+    const {
+      variant,
+      size,
+      glow,
+      pulse,
+      maxWidth,
       dataTestId,
       hoverContent,
       pinnedContent,
-      clickable = true,
+      clickable,
       onPin,
       onUnpin,
       className,
       children,
       ...props
-    },
-    ref,
-  ) => {
-    const [isPinned, setIsPinned] = useState(false);
-    const [isControlledOpen, setIsControlledOpen] = useState(false);
-    const wrapperRef = useRef<HTMLDivElement>(null);
-    const _tooltipId = useId();
-
-    // Handle outside clicks to unpin
-    useEffect(() => {
-      if (!isPinned || !clickable) {
-        return;
-      }
-
-      const handleClickOutside = (event: MouseEvent) => {
-        const targetElement = event.target as Element;
+    } = resolveTooltipProps(rawProps);
 
-        // Check if click was on tooltip or trigger
-        const isClickOnTooltip = targetElement.closest('[role="tooltip"]');
-        const isClickOnTrigger = wrapperRef.current?.contains(targetElement);
-
-        if (isClickOnTooltip || isClickOnTrigger) {
-          return;
-        }
-
-        // Click was outside - unpin
-        setIsPinned(false);
-        setIsControlledOpen(false);
-        onUnpin?.();
-      };
-
-      document.addEventListener('mousedown', handleClickOutside);
-      return () => {
-        document.removeEventListener('mousedown', handleClickOutside);
-      };
-    }, [isPinned, clickable, onUnpin]);
-
-    const handleClick = useCallback(
-      (e: React.MouseEvent) => {
-        if (!clickable) return;
-
-        e.preventDefault();
-        e.stopPropagation();
-
-        setIsPinned((current) => {
-          const newPinned = !current;
-          setIsControlledOpen(newPinned);
-
-          if (newPinned) {
-            onPin?.();
-          } else {
-            onUnpin?.();
-          }
-
-          return newPinned;
-        });
-      },
-      [clickable, onPin, onUnpin],
-    );
+    const { isPinned, isControlledOpen, wrapperRef, handleClick } = usePinnedTooltip({
+      clickable,
+      onPin,
+      onUnpin,
+    });
 
     // Determine which content to show
     const tooltipContent = isPinned ? pinnedContent : hoverContent;

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

@@ -0,0 +1,203 @@
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+
+import type { LazyImageProps, LazyImageState } from './LazyImage.types';
+
+type LazyImageDefaultedKeys =
+  | 'height'
+  | 'loadingState'
+  | 'objectFit'
+  | 'objectPosition'
+  | 'lazy'
+  | 'rootMargin'
+  | 'threshold'
+  | 'fadeIn'
+  | 'fadeInDuration'
+  | 'retryOnError'
+  | 'maxRetries'
+  | 'retryDelay'
+  | 'decoding'
+  | 'skeletonProps'
+  | 'spinnerProps'
+  | 'sx'
+  | 'role';
+
+export type ResolvedLazyImageProps = LazyImageProps &
+  Required<Pick<LazyImageProps, LazyImageDefaultedKeys>>;
+
+const LAZY_IMAGE_DEFAULTS: Pick<LazyImageProps, LazyImageDefaultedKeys> = {
+  height: 'auto',
+  loadingState: 'skeleton',
+  objectFit: 'cover',
+  objectPosition: 'center',
+  lazy: true,
+  rootMargin: '100px',
+  threshold: 0,
+  fadeIn: true,
+  fadeInDuration: 300,
+  retryOnError: false,
+  maxRetries: 3,
+  retryDelay: 1000,
+  decoding: 'async',
+  skeletonProps: {},
+  spinnerProps: {},
+  sx: {},
+  role: 'img',
+};
+
+// Strips explicitly-undefined props before the merge, so `lazy={undefined}` still
+// falls back to the default exactly as a destructuring default would.
+const definedProps = (props: LazyImageProps): Partial<LazyImageProps> =>
+  Object.fromEntries(
+    Object.entries(props).filter(([, value]) => value !== undefined),
+  ) as Partial<LazyImageProps>;
+
+export const resolveLazyImageProps = (props: LazyImageProps): ResolvedLazyImageProps =>
+  ({ ...LAZY_IMAGE_DEFAULTS, ...definedProps(props) }) as ResolvedLazyImageProps;
+
+// Props this component consumes itself. Anything else the caller passed is an
+// ordinary <img> attribute and is forwarded untouched.
+const OWN_PROPS = new Set([
+  'src', 'alt', 'width', 'height', 'placeholder', 'fallback', 'loadingState',
+  'showSpinner', 'objectFit', 'objectPosition', 'borderRadius', 'lazy', 'rootMargin',
+  'threshold', 'fadeIn', 'fadeInDuration', 'onLoad', 'onError', 'onLoadStart',
+  'retryOnError', 'maxRetries', 'retryDelay', 'decoding', 'loading', 'fetchPriority',
+  'skeletonProps', 'spinnerProps', 'sx', 'className', 'data-testid', 'aria-label',
+  'aria-describedby', 'role',
+]);
+
+export const imgPassThrough = (props: ResolvedLazyImageProps): Record<string, unknown> =>
+  Object.fromEntries(Object.entries(props).filter(([key]) => !OWN_PROPS.has(key)));
+
+/**
+ * Flips `isVisible` the first time the container nears the viewport, then stops
+ * observing. Does nothing when `lazy` is off — the caller wants the request now.
+ */
+const useVisibility = (
+  props: ResolvedLazyImageProps,
+  containerRef: React.RefObject<HTMLDivElement | null>,
+  isVisible: boolean,
+  onVisible: () => void,
+) => {
+  const { lazy, src, rootMargin, threshold, onLoadStart } = props;
+
+  useEffect(() => {
+    if (!lazy || isVisible) {
+      return;
+    }
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        entries.forEach((entry) => {
+          if (entry.isIntersecting) {
+            onVisible();
+            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, isVisible, onLoadStart, onVisible, containerRef]);
+};
+
+/** A pending retry has to be cancelled on unmount, or it sets state on a dead component. */
+const useRetryTimeout = () => {
+  const ref = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+
+  useEffect(
+    () => () => {
+      if (ref.current) {
+        clearTimeout(ref.current);
+      }
+    },
+    [],
+  );
+
+  return ref;
+};
+
+/**
+ * Owns whether the real image has been requested yet and how it went: the
+ * observer above, the load/error handlers, and the retry timer.
+ */
+export const useLazyImage = (props: ResolvedLazyImageProps) => {
+  const { src, placeholder, lazy, loadingState, showSpinner } = props;
+  const { onLoad, onError, retryOnError, maxRetries, retryDelay } = props;
+
+  const containerRef = useRef<HTMLDivElement>(null);
+  const retryTimeoutRef = useRetryTimeout();
+
+  // 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,
+  });
+
+  const markVisible = useCallback(
+    () => setState((prev) => ({ ...prev, isVisible: true, currentSrc: src })),
+    [src],
+  );
+  useVisibility(props, containerRef, state.isVisible, markVisible);
+
+  // 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 handleImageLoad = useCallback(
+    (event: React.SyntheticEvent<HTMLImageElement>) => {
+      setState((prev) => ({ ...prev, isLoading: false, hasError: false, retryCount: 0 }));
+      onLoad?.(event);
+    },
+    [onLoad],
+  );
+
+  const handleImageError = useCallback(
+    (event: React.SyntheticEvent<HTMLImageElement>) => {
+      if (!retryOnError || state.retryCount >= maxRetries) {
+        setState((prev) => ({ ...prev, isLoading: false, hasError: true }));
+        onError?.(event);
+        return;
+      }
+
+      retryTimeoutRef.current = setTimeout(() => {
+        setState((prev) => ({
+          ...prev,
+          retryCount: prev.retryCount + 1,
+          currentSrc: `${src}?retry=${prev.retryCount + 1}`, // Force reload with cache buster
+        }));
+      }, retryDelay);
+    },
+    [onError, retryOnError, state.retryCount, maxRetries, retryDelay, src],
+  );
+
+  return {
+    state,
+    containerRef,
+    effectiveLoadingState,
+    handleImageLoad,
+    handleImageError,
+    showImage: Boolean(state.currentSrc) && !state.hasError,
+    showLoading:
+      state.isLoading && (!state.currentSrc || effectiveLoadingState !== 'placeholder'),
+  };
+};

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

@@ -58,7 +58,7 @@ function App() {
 ### Custom Fallback Component
 
 ```tsx
-import { BrokenImageIcon } from '@mui/icons-material';
+import BrokenImageIcon from '@mui/icons-material/BrokenImageIcon';
 
 <LazyImage
   src="https://example.com/image.jpg"

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

@@ -312,15 +312,15 @@ export const WithEventCallbacks: Story = {
     width: 600,
     height: 400,
     onLoadStart: () => {
-      // eslint-disable-next-line no-console
+      // eslint-disable-next-line no-console -- demo output for the Storybook docs page
       console.info('🚀 Started loading image');
     },
     onLoad: (event) => {
-      // eslint-disable-next-line no-console
+      // eslint-disable-next-line no-console -- demo output for the Storybook docs page
       console.info('✅ Image loaded successfully', event);
     },
     onError: (event) => {
-      // eslint-disable-next-line no-console
+      // eslint-disable-next-line no-console -- demo output for the Storybook docs page
       console.error('❌ Image failed to load', event);
     },
   },