@12-apps/ui 1.4.0 → 1.5.0

package/src/components/data-display/HoverCard/HoverCard.animations.ts

@@ -0,0 +1,73 @@
+import { keyframes } from '@mui/material';
+
+export const pulseAnimation = keyframes`
+  0% {
+    box-shadow: 0 0 0 0 currentColor;
+    opacity: 1;
+  }
+  70% {
+    box-shadow: 0 0 0 10px currentColor;
+    opacity: 0;
+  }
+  100% {
+    box-shadow: 0 0 0 0 currentColor;
+    opacity: 0;
+  }
+`;
+
+export const slideInUp = keyframes`
+  from {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+`;
+
+export const slideInDown = keyframes`
+  from {
+    opacity: 0;
+    transform: translateY(-8px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+`;
+
+export const slideInLeft = keyframes`
+  from {
+    opacity: 0;
+    transform: translateX(8px);
+  }
+  to {
+    opacity: 1;
+    transform: translateX(0);
+  }
+`;
+
+export const slideInRight = keyframes`
+  from {
+    opacity: 0;
+    transform: translateX(-8px);
+  }
+  to {
+    opacity: 1;
+    transform: translateX(0);
+  }
+`;
+
+export const scaleIn = keyframes`
+  from {
+    opacity: 0;
+    transform: scale(0.8);
+  }
+  to {
+    opacity: 1;
+    transform: scale(1);
+  }
+`;
+
+// Arrow component

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

@@ -0,0 +1,143 @@
+import { Avatar, Box, CircularProgress, Typography } from '@mui/material';
+import { styled } from '@mui/material/styles';
+import React from 'react';
+
+import type { HoverCardProps } from './HoverCard.types';
+
+const LoadingContainer = styled(Box)(({ theme }) => ({
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'center',
+  minHeight: 80,
+  color: theme.palette.text.secondary,
+}));
+
+/** `${dataTestId}-${suffix}`, or the shared default when the caller gave no id. */
+const testId = (base: string | undefined, suffix: string, fallback: string) =>
+  base ? `${base}-${suffix}` : fallback;
+
+export interface HoverCardContentProps
+  extends Pick<
+    HoverCardProps,
+    'variant' | 'title' | 'description' | 'avatar' | 'loading' | 'loadingComponent' | 'children'
+  > {
+  dataTestId?: string;
+}
+
+/** A string avatar is a src; anything else is an element to re-size in place. */
+const CardAvatar: React.FC<{ avatar: HoverCardProps['avatar'] }> = ({ avatar }) => {
+  if (!avatar) return null;
+
+  if (typeof avatar === 'string') {
+    return <Avatar src={avatar} sx={{ width: 48, height: 48, mr: 2 }} />;
+  }
+
+  const element = avatar as React.ReactElement<{ sx?: object }>;
+  return React.cloneElement(element, {
+    sx: { width: 48, height: 48, mr: 2, ...element.props.sx },
+  });
+};
+
+const Title: React.FC<{
+  title: React.ReactNode;
+  variant?: string;
+  sx?: object;
+  dataTestId?: string;
+}> = ({ title, variant, sx, dataTestId }) => (
+  <Typography
+    variant={variant === 'minimal' ? 'body2' : 'subtitle1'}
+    sx={{ fontWeight: 600, ...sx }}
+    data-testid={testId(dataTestId, 'title', 'hover-card-title')}
+  >
+    {title}
+  </Typography>
+);
+
+const Description: React.FC<{
+  description: React.ReactNode;
+  sx?: object;
+  dataTestId?: string;
+}> = ({ description, sx, dataTestId }) => (
+  <Typography
+    variant="body2"
+    color="text.secondary"
+    sx={sx}
+    data-testid={testId(dataTestId, 'description', 'hover-card-description')}
+  >
+    {description}
+  </Typography>
+);
+
+/** The detailed variant leads with the avatar and sets the text beside it. */
+const DetailedContent: React.FC<HoverCardContentProps> = ({
+  title,
+  description,
+  avatar,
+  children,
+  dataTestId,
+}) => (
+  <>
+    {avatar && (
+      <Box sx={{ display: 'flex', alignItems: 'center', mb: 2 }}>
+        <CardAvatar avatar={avatar} />
+        <Box>
+          {title && (
+            <Typography
+              variant="h6"
+              sx={{ fontWeight: 600, mb: 0.5 }}
+              data-testid={testId(dataTestId, 'title', 'hover-card-title')}
+            >
+              {title}
+            </Typography>
+          )}
+          {description && <Description description={description} dataTestId={dataTestId} />}
+        </Box>
+      </Box>
+    )}
+    {!avatar && title && (
+      <Typography
+        variant="h6"
+        sx={{ fontWeight: 600, mb: 1 }}
+        data-testid={testId(dataTestId, 'title', 'hover-card-title')}
+      >
+        {title}
+      </Typography>
+    )}
+    {!avatar && description && (
+      <Description description={description} sx={{ mb: 1 }} dataTestId={dataTestId} />
+    )}
+    {children && <Box>{children}</Box>}
+  </>
+);
+
+export const HoverCardContent: React.FC<HoverCardContentProps> = (props) => {
+  const { variant, title, description, avatar, loading, loadingComponent, children, dataTestId } =
+    props;
+
+  if (loading) {
+    return (
+      <LoadingContainer>
+        {loadingComponent || (
+          <Box sx={{ display: 'flex', alignItems: 'center', gap: 1 }}>
+            <CircularProgress size={20} />
+            <Typography variant="body2">Loading...</Typography>
+          </Box>
+        )}
+      </LoadingContainer>
+    );
+  }
+
+  if (variant === 'detailed' && (avatar || title || description)) {
+    return <DetailedContent {...props} />;
+  }
+
+  return (
+    <>
+      {title && (
+        <Title title={title} variant={variant} sx={{ mb: 0.5 }} dataTestId={dataTestId} />
+      )}
+      {description && <Description description={description} dataTestId={dataTestId} />}
+      {children}
+    </>
+  );
+};

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

@@ -0,0 +1,180 @@
+import React from 'react';
+
+interface HandlerInput {
+  isTouchDevice: boolean;
+  touchEnabled: boolean;
+  enterDelay: number;
+  openCard: (event: React.MouseEvent<HTMLElement> | React.TouchEvent<HTMLElement>) => void;
+  closeCard: () => void;
+  exitTimeoutRef: React.MutableRefObject<number | undefined>;
+}
+
+/**
+ * The pointer and touch handlers, over the open/close pair. Touch gets a
+ * long-press because there is no hover to respond to; the card's own handlers
+ * keep it open while the pointer is travelling onto it.
+ */
+const useHoverHandlers = ({
+  isTouchDevice,
+  touchEnabled,
+  enterDelay,
+  openCard,
+  closeCard,
+  exitTimeoutRef,
+}: HandlerInput) => {
+  const [touchTimeout, setTouchTimeout] = React.useState<number>();
+
+  /** A touch device with touch disabled has no hover to respond to. */
+  const hoverIgnored = isTouchDevice && !touchEnabled;
+
+  const cancelTouch = React.useCallback(() => {
+    if (touchTimeout) {
+      window.clearTimeout(touchTimeout);
+      setTouchTimeout(undefined);
+    }
+  }, [touchTimeout]);
+
+  React.useEffect(
+    () => () => {
+      if (touchTimeout) window.clearTimeout(touchTimeout);
+    },
+    [touchTimeout],
+  );
+
+  const triggerHandlers = {
+    onMouseEnter: (event: React.MouseEvent<HTMLElement>) => {
+      if (hoverIgnored) return;
+      openCard(event);
+    },
+    onMouseLeave: () => {
+      if (hoverIgnored) return;
+      closeCard();
+    },
+    onTouchStart: (event: React.TouchEvent<HTMLElement>) => {
+      if (!touchEnabled) return;
+      if (touchTimeout) window.clearTimeout(touchTimeout);
+      setTouchTimeout(window.setTimeout(() => openCard(event), enterDelay));
+    },
+    // End and cancel do the same thing: the press did not become a long press.
+    onTouchEnd: cancelTouch,
+    onTouchCancel: cancelTouch,
+  };
+
+  /** Moving onto the card keeps it open; leaving it starts the exit delay. */
+  const cardHandlers = {
+    onMouseEnter: () => {
+      if (exitTimeoutRef.current) window.clearTimeout(exitTimeoutRef.current);
+    },
+    onMouseLeave: closeCard,
+  };
+
+  return { triggerHandlers, cardHandlers };
+};
+
+/** Escape dismisses the card while it is open. */
+const useEscapeKey = (active: boolean, onEscape: () => void) => {
+  React.useEffect(() => {
+    if (!active) return;
+
+    const handleEscape = (event: globalThis.KeyboardEvent) => {
+      if (event.key === 'Escape') onEscape();
+    };
+
+    document.addEventListener('keydown', handleEscape);
+    return () => document.removeEventListener('keydown', handleEscape);
+  }, [active, onEscape]);
+};
+
+interface HoverCardTimingInput {
+  disabled: boolean;
+  touchEnabled: boolean;
+  enterDelay: number;
+  exitDelay: number;
+  onOpen?: () => void;
+  onClose?: () => void;
+}
+
+/**
+ * When the card is open, and the delays that decide it.
+ *
+ * Three timers are in play: the enter delay before opening, the exit delay
+ * before closing (so the pointer can travel from the trigger onto the card
+ * without dismissing it), and the long-press timer on touch. Each cancels the
+ * others' pending work, which is why they live together.
+ */
+export const useHoverCard = ({
+  disabled,
+  touchEnabled,
+  enterDelay,
+  exitDelay,
+  onOpen,
+  onClose,
+}: HoverCardTimingInput) => {
+  const [anchorEl, setAnchorEl] = React.useState<HTMLElement | null>(null);
+  const [isOpen, setIsOpen] = React.useState(false);
+  const [isTouchDevice, setIsTouchDevice] = React.useState(false);
+  const enterTimeoutRef = React.useRef<number | undefined>(undefined);
+  const exitTimeoutRef = React.useRef<number | undefined>(undefined);
+
+  // Probed in an effect, not during render, so SSR and hydration stay intact.
+  React.useEffect(() => {
+    setIsTouchDevice('ontouchstart' in window);
+  }, []);
+
+  const openCard = React.useCallback(
+    (event: React.MouseEvent<HTMLElement> | React.TouchEvent<HTMLElement>) => {
+      if (disabled) return;
+
+      if (exitTimeoutRef.current) {
+        window.clearTimeout(exitTimeoutRef.current);
+      }
+
+      const target = event.currentTarget;
+      enterTimeoutRef.current = window.setTimeout(() => {
+        setAnchorEl(target);
+        setIsOpen(true);
+        onOpen?.();
+      }, enterDelay);
+    },
+    [disabled, enterDelay, onOpen],
+  );
+
+  const closeCard = React.useCallback(() => {
+    if (enterTimeoutRef.current) {
+      window.clearTimeout(enterTimeoutRef.current);
+    }
+
+    exitTimeoutRef.current = window.setTimeout(() => {
+      setIsOpen(false);
+      setAnchorEl(null);
+      onClose?.();
+    }, exitDelay);
+  }, [exitDelay, onClose]);
+
+  const handleClose = React.useCallback(() => {
+    setIsOpen(false);
+    setAnchorEl(null);
+    onClose?.();
+  }, [onClose]);
+
+  const { triggerHandlers, cardHandlers } = useHoverHandlers({
+    isTouchDevice,
+    touchEnabled,
+    enterDelay,
+    openCard,
+    closeCard,
+    exitTimeoutRef,
+  });
+
+  useEscapeKey(isOpen, handleClose);
+
+  React.useEffect(
+    () => () => {
+      if (enterTimeoutRef.current) window.clearTimeout(enterTimeoutRef.current);
+      if (exitTimeoutRef.current) window.clearTimeout(exitTimeoutRef.current);
+    },
+    [],
+  );
+
+  return { anchorEl, isOpen, handleClose, triggerHandlers, cardHandlers };
+};

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

@@ -0,0 +1,178 @@
+import { alpha } from '@mui/material';
+import type { CSSObject, Theme } from '@mui/material/styles';
+
+import {
+  pulseAnimation,
+  scaleIn,
+  slideInDown,
+  slideInLeft,
+  slideInRight,
+  slideInUp,
+} from './HoverCard.animations';
+import type { HoverCardAnimation, HoverCardPlacement } from './HoverCard.types';
+
+/** The edge the card sits on, ignoring the `-start`/`-end` alignment suffix. */
+type Side = 'top' | 'bottom' | 'left' | 'right';
+
+export const sideOf = (placement: HoverCardPlacement): Side => {
+  if (placement.startsWith('top')) return 'top';
+  if (placement.startsWith('left')) return 'left';
+  if (placement.startsWith('right')) return 'right';
+  return 'bottom';
+};
+
+const ARROW_SIZE = 8;
+
+/**
+ * The arrow is a CSS triangle: two transparent borders on the cross axis and one
+ * filled border pointing back at the anchor. Every placement is that same shape,
+ * so the table holds only which edge is filled and where the triangle sits.
+ */
+const ARROWS: Record<Side, (color: string) => CSSObject> = {
+  top: (color) => ({
+    bottom: -ARROW_SIZE,
+    left: '50%',
+    transform: 'translateX(-50%)',
+    borderLeft: `${ARROW_SIZE}px solid transparent`,
+    borderRight: `${ARROW_SIZE}px solid transparent`,
+    borderTop: `${ARROW_SIZE}px solid ${color}`,
+  }),
+  bottom: (color) => ({
+    top: -ARROW_SIZE,
+    left: '50%',
+    transform: 'translateX(-50%)',
+    borderLeft: `${ARROW_SIZE}px solid transparent`,
+    borderRight: `${ARROW_SIZE}px solid transparent`,
+    borderBottom: `${ARROW_SIZE}px solid ${color}`,
+  }),
+  left: (color) => ({
+    right: -ARROW_SIZE,
+    top: '50%',
+    transform: 'translateY(-50%)',
+    borderTop: `${ARROW_SIZE}px solid transparent`,
+    borderBottom: `${ARROW_SIZE}px solid transparent`,
+    borderLeft: `${ARROW_SIZE}px solid ${color}`,
+  }),
+  right: (color) => ({
+    left: -ARROW_SIZE,
+    top: '50%',
+    transform: 'translateY(-50%)',
+    borderTop: `${ARROW_SIZE}px solid transparent`,
+    borderBottom: `${ARROW_SIZE}px solid transparent`,
+    borderRight: `${ARROW_SIZE}px solid ${color}`,
+  }),
+};
+
+export const arrowSx = (theme: Theme, placement: HoverCardPlacement): CSSObject => ({
+  position: 'absolute',
+  width: 0,
+  height: 0,
+  zIndex: 1,
+  ...ARROWS[sideOf(placement)](theme.palette.background.paper),
+});
+
+type Origin = { vertical: 'top' | 'center' | 'bottom'; horizontal: 'left' | 'center' | 'right' };
+
+/** Where the popover attaches to the anchor, per side. */
+const ANCHOR_ORIGINS: Record<Side, Origin> = {
+  top: { vertical: 'top', horizontal: 'center' },
+  bottom: { vertical: 'bottom', horizontal: 'center' },
+  left: { vertical: 'center', horizontal: 'left' },
+  right: { vertical: 'center', horizontal: 'right' },
+};
+
+/** The card's own corner meets the anchor's, so its origin is the opposite one. */
+const flip = (origin: Origin): Origin => ({
+  vertical: origin.vertical === 'top' ? 'bottom' : origin.vertical === 'bottom' ? 'top' : 'center',
+  horizontal:
+    origin.horizontal === 'left' ? 'right' : origin.horizontal === 'right' ? 'left' : 'center',
+});
+
+export const getAnchorOrigin = (placement: HoverCardPlacement): Origin =>
+  ANCHOR_ORIGINS[sideOf(placement)];
+
+export const getTransformOrigin = (placement: HoverCardPlacement): Origin =>
+  flip(ANCHOR_ORIGINS[sideOf(placement)]);
+
+const ANIMATIONS: Record<string, CSSObject> = {
+  // `fade` shares slideInUp deliberately: the keyframes fade in while rising.
+  fade: { animation: `${slideInUp} 0.2s ease-out` },
+  scale: { transformOrigin: 'center', animation: `${scaleIn} 0.2s cubic-bezier(0.4, 0, 0.2, 1)` },
+  'slide-up': { animation: `${slideInUp} 0.3s cubic-bezier(0.4, 0, 0.2, 1)` },
+  'slide-down': { animation: `${slideInDown} 0.3s cubic-bezier(0.4, 0, 0.2, 1)` },
+  'slide-left': { animation: `${slideInLeft} 0.3s cubic-bezier(0.4, 0, 0.2, 1)` },
+  'slide-right': { animation: `${slideInRight} 0.3s cubic-bezier(0.4, 0, 0.2, 1)` },
+};
+
+const VARIANTS: Record<string, (theme: Theme) => CSSObject> = {
+  default: (theme) => ({
+    backgroundColor: theme.palette.background.paper,
+    border: `1px solid ${alpha(theme.palette.divider, 0.2)}`,
+    boxShadow: theme.shadows[8],
+  }),
+  glass: (theme) => ({
+    backgroundColor: alpha(theme.palette.background.paper, 0.85),
+    backdropFilter: 'blur(20px)',
+    WebkitBackdropFilter: 'blur(20px)',
+    border: `1px solid ${alpha(theme.palette.divider, 0.2)}`,
+    boxShadow: `0 8px 32px ${alpha(theme.palette.common.black, 0.12)}`,
+  }),
+  detailed: (theme) => ({
+    backgroundColor: theme.palette.background.paper,
+    border: `1px solid ${alpha(theme.palette.divider, 0.2)}`,
+    boxShadow: theme.shadows[12],
+  }),
+  minimal: (theme) => ({
+    backgroundColor: theme.palette.background.paper,
+    border: `1px solid ${alpha(theme.palette.divider, 0.1)}`,
+    boxShadow: theme.shadows[4],
+  }),
+};
+
+const glowStyles = (theme: Theme): CSSObject => ({
+  boxShadow: `0 0 20px 5px ${alpha(theme.palette.primary.main, 0.3)} !important`,
+  filter: 'brightness(1.05)',
+});
+
+const pulseStyles = (theme: Theme): CSSObject => ({
+  position: 'relative',
+  '&::after': {
+    content: '""',
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    borderRadius: 'inherit',
+    backgroundColor: theme.palette.primary.main,
+    opacity: 0.1,
+    animation: `${pulseAnimation} 2s infinite`,
+    pointerEvents: 'none',
+    zIndex: -1,
+  },
+});
+
+export interface CardStyleFlags {
+  customVariant?: string;
+  glow?: boolean;
+  pulse?: boolean;
+  animation?: HoverCardAnimation;
+}
+
+export const cardSx = (theme: Theme, flags: CardStyleFlags): CSSObject => {
+  const { customVariant, glow, pulse, animation } = flags;
+
+  return {
+    borderRadius: theme.spacing(1.5),
+    transition: 'all 0.3s cubic-bezier(0.4, 0, 0.2, 1)',
+    position: 'relative',
+    overflow: 'visible',
+    minWidth: 200,
+    maxWidth: 400,
+    ...(animation ? (ANIMATIONS[animation] ?? {}) : {}),
+    ...(customVariant ? (VARIANTS[customVariant]?.(theme) ?? {}) : {}),
+    // The old "both" arm was exactly these two spread together.
+    ...(glow && glowStyles(theme)),
+    ...(pulse && pulseStyles(theme)),
+  };
+};