@12-apps/ui 1.4.0 → 1.5.0

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

@@ -0,0 +1,44 @@
+import { keyframes } from '@mui/material';
+
+/** Spring physics used by the draggable variant's snap-point animation. */
+export const SPRING_CONFIG = {
+  tension: 200,
+  friction: 25,
+  velocity: 0,
+};
+
+/** Velocity threshold for snap detection (pixels per millisecond). */
+export const DEFAULT_VELOCITY_THRESHOLD = 0.5;
+
+/** Drag resistance factor applied past the first and last snap points. */
+export const DEFAULT_DRAG_RESISTANCE = 0.3;
+
+export const pulseAnimation = keyframes`
+  0% {
+    box-shadow: 0 0 0 0 rgba(var(--pulse-color), 0.4);
+  }
+  70% {
+    box-shadow: 0 0 0 20px rgba(var(--pulse-color), 0);
+  }
+  100% {
+    box-shadow: 0 0 0 0 rgba(var(--pulse-color), 0);
+  }
+`;
+
+export const shimmerAnimation = keyframes`
+  0% {
+    background-position: -1000px 0;
+  }
+  100% {
+    background-position: 1000px 0;
+  }
+`;
+
+export const glowAnimation = keyframes`
+  0%, 100% {
+    box-shadow: 0 0 20px 5px rgba(var(--glow-color), 0.3);
+  }
+  50% {
+    box-shadow: 0 0 35px 10px rgba(var(--glow-color), 0.5);
+  }
+`;

package/src/components/data-display/Sheet/Sheet.body.tsx

@@ -0,0 +1,124 @@
+import { Box, CircularProgress } from '@mui/material';
+import React from 'react';
+
+import { SheetContent, SheetFooter, SheetHeader } from './Sheet.parts';
+import type { SheetProps } from './Sheet.types';
+
+export interface SheetBodyProps extends Pick<
+  SheetProps,
+  | 'title'
+  | 'description'
+  | 'showCloseButton'
+  | 'showHandle'
+  | 'header'
+  | 'footer'
+  | 'loading'
+  | 'color'
+  | 'children'
+  | 'onClick'
+  | 'onFocus'
+  | 'onBlur'
+> {
+  testId: string;
+  isDragging: boolean;
+  isVerticalSheet: boolean;
+  isDraggableVariant: boolean;
+  onClose: () => void;
+  onDragStart: (e: React.MouseEvent | React.TouchEvent) => void;
+}
+
+/**
+ * The header earns its place if it would show anything at all — a grab handle,
+ * either piece of text, the close button, or caller-supplied content.
+ */
+const needsHeader = (props: SheetBodyProps) =>
+  Boolean(
+    props.showHandle ||
+    props.title ||
+    props.description ||
+    props.showCloseButton ||
+    props.header,
+  );
+
+/** The centred spinner shown in place of the children while `loading`. */
+const SheetLoading: React.FC<Pick<SheetBodyProps, 'color'>> = ({ color }) => (
+  <Box
+    sx={{
+      display: 'flex',
+      justifyContent: 'center',
+      alignItems: 'center',
+      minHeight: 200,
+    }}
+  >
+    <CircularProgress color={color} />
+  </Box>
+);
+
+/**
+ * What the sheet contains, independent of which drawer is carrying it. The
+ * swipeable and plain branches render exactly this — they differ only in the
+ * MUI component and its swipe props, so the contents are built once.
+ */
+export const SheetBody: React.FC<SheetBodyProps> = (props) => {
+  const {
+    title,
+    description,
+    showCloseButton,
+    showHandle,
+    header,
+    footer,
+    loading,
+    color,
+    children,
+    onClick,
+    onFocus,
+    onBlur,
+    testId,
+    isDragging,
+    isVerticalSheet,
+    isDraggableVariant,
+    onClose,
+    onDragStart,
+  } = props;
+
+  return (
+    <Box
+      onClick={onClick}
+      onFocus={onFocus}
+      onBlur={onBlur}
+      data-testid={testId}
+      sx={{
+        height: '100%',
+        display: 'flex',
+        flexDirection: 'column',
+        position: 'relative',
+        userSelect: isDragging ? 'none' : 'auto',
+      }}
+    >
+      {needsHeader(props) && (
+        <SheetHeader
+          title={title}
+          description={description}
+          showCloseButton={showCloseButton}
+          onClose={onClose}
+          showHandle={showHandle && isVerticalSheet}
+          isDraggable={isDraggableVariant && isVerticalSheet}
+          onDragStart={onDragStart}
+          dataTestId={`${testId}-header`}
+        >
+          {header}
+        </SheetHeader>
+      )}
+
+      <SheetContent padded dataTestId={`${testId}-content`}>
+        {loading ? <SheetLoading color={color} /> : children}
+      </SheetContent>
+
+      {footer && (
+        <SheetFooter sticky divider dataTestId={`${testId}-footer`}>
+          {footer}
+        </SheetFooter>
+      )}
+    </Box>
+  );
+};

package/src/components/data-display/Sheet/Sheet.drag.ts

@@ -0,0 +1,203 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import type { SheetDragInput, SnapGeometry } from './Sheet.hooks';
+
+type AnyPointerEvent =
+  | React.MouseEvent
+  | React.TouchEvent
+  | globalThis.MouseEvent
+  | globalThis.TouchEvent;
+
+/** Reads the pointer's y from either a mouse or a touch event. */
+const clientYOf = (e: AnyPointerEvent) =>
+  'touches' in e ? (e.touches[0]?.clientY ?? 0) : e.clientY;
+
+/**
+ * A drag continues wherever the pointer goes, so the move and end listeners
+ * belong on the document rather than the panel.
+ */
+const useDragListeners = (
+  isDragging: boolean,
+  onMove: (e: globalThis.MouseEvent | globalThis.TouchEvent) => void,
+  onEnd: (e: globalThis.MouseEvent | globalThis.TouchEvent) => void,
+) => {
+  useEffect(() => {
+    if (!isDragging) return;
+
+    document.addEventListener('mousemove', onMove);
+    document.addEventListener('mouseup', onEnd);
+    document.addEventListener('touchmove', onMove, { passive: false });
+    document.addEventListener('touchend', onEnd);
+
+    return () => {
+      document.removeEventListener('mousemove', onMove);
+      document.removeEventListener('mouseup', onEnd);
+      document.removeEventListener('touchmove', onMove);
+      document.removeEventListener('touchend', onEnd);
+    };
+  }, [isDragging, onMove, onEnd]);
+};
+
+/**
+ * Pointer velocity across a drag, in snap-point units per millisecond. Kept in
+ * refs rather than state: it is read once at drag end and must not re-render
+ * the panel on every pointer move.
+ */
+const useVelocityTracker = () => {
+  const velocityRef = useRef(0);
+  const lastYRef = useRef(0);
+  const lastTimeRef = useRef(0);
+
+  const begin = useCallback((clientY: number) => {
+    lastYRef.current = clientY;
+    lastTimeRef.current = globalThis.performance.now();
+    velocityRef.current = 0;
+  }, []);
+
+  const track = useCallback((clientY: number) => {
+    const now = globalThis.performance.now();
+    const deltaTime = now - lastTimeRef.current;
+    if (deltaTime > 0) {
+      velocityRef.current = (clientY - lastYRef.current) / deltaTime;
+    }
+    lastYRef.current = clientY;
+    lastTimeRef.current = now;
+  }, []);
+
+  const read = useCallback(() => velocityRef.current || 0, []);
+
+  return { begin, track, read };
+};
+
+/**
+ * The two conversions between pointer travel and snap points: how far a pointer
+ * at `clientY` has moved the sheet, and what happens past the end stops.
+ */
+const useDragMath = (input: SheetDragInput, dragStartY: number) => {
+  const { isBottomSheet, minSnapPoint, maxSnapPoint, dragResistance } = input;
+
+  /** Snap-point delta for a pointer at `clientY`, sign-corrected for the anchor. */
+  const snapDeltaFor = useCallback(
+    (clientY: number) =>
+      (isBottomSheet ? dragStartY - clientY : clientY - dragStartY) / window.innerHeight,
+    [isBottomSheet, dragStartY],
+  );
+
+  /**
+   * Past either end the sheet still moves, but only by a fraction of the drag,
+   * so the boundary is felt rather than hit.
+   */
+  const withResistance = useCallback(
+    (snapPoint: number) => {
+      if (snapPoint < minSnapPoint) {
+        return minSnapPoint - (minSnapPoint - snapPoint) * dragResistance;
+      }
+      if (snapPoint > maxSnapPoint) {
+        return maxSnapPoint + (snapPoint - maxSnapPoint) * dragResistance;
+      }
+      return snapPoint;
+    },
+    [minSnapPoint, maxSnapPoint, dragResistance],
+  );
+
+  return { snapDeltaFor, withResistance };
+};
+
+interface InFlightInput {
+  isDragging: boolean;
+  dragStartY: number;
+  stopDragging: () => void;
+  velocity: ReturnType<typeof useVelocityTracker>;
+}
+
+/**
+ * The two handlers that run while a drag is live: one per pointer move, and one
+ * at release that hands the resting position to the geometry.
+ */
+const useDragInFlight = (
+  input: SheetDragInput,
+  geometry: SnapGeometry,
+  { isDragging, dragStartY, stopDragging, velocity }: InFlightInput,
+) => {
+  const { isVerticalSheet, isBottomSheet, onDragEnd } = input;
+  const { sheetRef, currentSnapPoint, updateSheetHeight, settleAt } = geometry;
+  const { snapDeltaFor, withResistance } = useDragMath(input, dragStartY);
+
+  const handleDragMove = useCallback(
+    (e: globalThis.MouseEvent | globalThis.TouchEvent) => {
+      if (!isDragging || !sheetRef.current || !isVerticalSheet) return;
+
+      e.preventDefault();
+      const clientY = clientYOf(e);
+      velocity.track(clientY);
+      updateSheetHeight(withResistance(currentSnapPoint + snapDeltaFor(clientY)));
+    },
+    [isDragging, sheetRef, isVerticalSheet, currentSnapPoint, snapDeltaFor, withResistance, updateSheetHeight, velocity],
+  );
+
+  const handleDragEnd = useCallback(
+    (e: globalThis.MouseEvent | globalThis.TouchEvent) => {
+      if (!isDragging || !isVerticalSheet) return;
+
+      e.preventDefault();
+      stopDragging();
+
+      const position = currentSnapPoint + snapDeltaFor(clientYOf(e));
+      // A bottom sheet grows as the pointer moves up, so its velocity reads
+      // negative for the direction the panel is actually travelling.
+      const finalVelocity = isBottomSheet ? -velocity.read() : velocity.read();
+
+      const target = settleAt(position, finalVelocity);
+      if (target !== undefined) {
+        onDragEnd?.(target);
+      }
+    },
+    [isDragging, isVerticalSheet, isBottomSheet, currentSnapPoint, snapDeltaFor, settleAt, stopDragging, velocity, onDragEnd],
+  );
+
+  return { handleDragMove, handleDragEnd };
+};
+
+/**
+ * The pointer half of the draggable variant: tracks one drag from press to
+ * release, converts its travel into a snap-point delta, and hands the result to
+ * the geometry to settle.
+ */
+export const useDragGestures = (input: SheetDragInput, geometry: SnapGeometry) => {
+  const { isDraggableVariant, isVerticalSheet, onDragStart } = input;
+  const { isAnimating, cancelAnimation } = geometry;
+
+  const [isDragging, setIsDragging] = useState(false);
+  const [dragStartY, setDragStartY] = useState(0);
+  const velocity = useVelocityTracker();
+
+  const handleDragStart = useCallback(
+    (e: React.MouseEvent | React.TouchEvent) => {
+      if (!isDraggableVariant || !isVerticalSheet || isAnimating) return;
+
+      e.preventDefault();
+      e.stopPropagation();
+
+      const clientY = clientYOf(e);
+      setIsDragging(true);
+      setDragStartY(clientY);
+      velocity.begin(clientY);
+
+      cancelAnimation();
+      onDragStart?.();
+    },
+    [isDraggableVariant, isVerticalSheet, isAnimating, velocity, cancelAnimation, onDragStart],
+  );
+
+  const stopDragging = useCallback(() => setIsDragging(false), []);
+  const { handleDragMove, handleDragEnd } = useDragInFlight(input, geometry, {
+    isDragging,
+    dragStartY,
+    stopDragging,
+    velocity,
+  });
+
+  useDragListeners(isDragging, handleDragMove, handleDragEnd);
+
+  return { isDragging, handleDragStart };
+};

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

@@ -0,0 +1,318 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import { SPRING_CONFIG } from './Sheet.animations';
+import { useDragGestures } from './Sheet.drag';
+import type { SheetProps } from './Sheet.types';
+
+export interface SheetDragInput {
+  isDraggableVariant: boolean;
+  isVerticalSheet: boolean;
+  isBottomSheet: boolean;
+  isTopSheet: boolean;
+  snapPoints: number[];
+  defaultSnapPoint: number;
+  minSnapPoint: number;
+  maxSnapPoint: number;
+  velocityThreshold: number;
+  dragResistance: number;
+  animationConfig: NonNullable<SheetProps['animationConfig']>;
+  onSnapPointChange?: (snapPoint: number) => void;
+  onDragStart?: () => void;
+  onDragEnd?: (snapPoint: number) => void;
+}
+
+/**
+ * Which snap point a drag ending at `position` should land on.
+ *
+ * A flick past the velocity threshold advances one point in the direction of
+ * travel rather than landing on whichever is nearest — that is what makes a
+ * short fast drag feel like a throw. Anything slower simply snaps to the
+ * closest point.
+ */
+const closestSnapPoint = (
+  points: number[],
+  position: number,
+  from: number,
+  velocity: number,
+  velocityThreshold: number,
+) => {
+  if (Math.abs(velocity) > velocityThreshold) {
+    const index = points.findIndex((point) => Math.abs(point - from) < 0.01);
+
+    if (velocity > 0 && index < points.length - 1) return points[index + 1];
+    if (velocity < 0 && index > 0) return points[index - 1];
+  }
+
+  return points.reduce(
+    (closest, point) =>
+      Math.abs(position - point) < Math.abs(position - closest) ? point : closest,
+    points[0] ?? from,
+  );
+};
+
+/** Owns the panel element and the height writes that realise a snap point. */
+const useSheetHeight = (input: Pick<SheetDragInput, 'isVerticalSheet' | 'isBottomSheet' | 'isTopSheet'>) => {
+  const { isVerticalSheet, isBottomSheet, isTopSheet } = input;
+  const [currentHeight, setCurrentHeight] = useState<number | null>(null);
+  const sheetRef = useRef<HTMLDivElement>(null);
+
+  const updateSheetHeight = useCallback(
+    (snapPoint: number) => {
+      if (!sheetRef.current || !isVerticalSheet) return;
+
+      const height = Math.round(window.innerHeight * snapPoint);
+
+      if (isBottomSheet) {
+        sheetRef.current.style.height = `${height}px`;
+        sheetRef.current.style.transform = 'translateY(0)';
+      } else if (isTopSheet) {
+        sheetRef.current.style.height = `${height}px`;
+      }
+
+      setCurrentHeight(height);
+    },
+    [isBottomSheet, isTopSheet, isVerticalSheet],
+  );
+
+  return { sheetRef, currentHeight, updateSheetHeight };
+};
+
+interface SnapAnimationInput {
+  isVerticalSheet: boolean;
+  animationConfig: NonNullable<SheetProps['animationConfig']>;
+  updateSheetHeight: (snapPoint: number) => void;
+  onSettled: (snapPoint: number) => void;
+  enabled: () => boolean;
+}
+
+/** The spring that carries the panel from one snap point to another. */
+const useSnapAnimation = ({
+  isVerticalSheet,
+  animationConfig,
+  updateSheetHeight,
+  onSettled,
+  enabled,
+}: SnapAnimationInput) => {
+  const [isAnimating, setIsAnimating] = useState(false);
+  const animationFrameRef = useRef<number | undefined>(undefined);
+
+  const animateToSnapPoint = useCallback(
+    (from: number, to: number, velocity = 0) => {
+      if (!enabled() || !isVerticalSheet) return;
+
+      setIsAnimating(true);
+      const distance = to - from;
+      const startTime = globalThis.performance.now();
+
+      const { tension, friction } = { ...SPRING_CONFIG, ...animationConfig };
+      let currentVelocity = velocity * 1000; // px per second
+
+      const animate = () => {
+        const elapsed = (globalThis.performance.now() - startTime) / 1000;
+
+        const springForce = -tension * (from - to);
+        const dampingForce = -friction * currentVelocity;
+        currentVelocity += (springForce + dampingForce) * 0.016; // 60fps timestep
+
+        const progress = Math.min(1, elapsed * 4);
+        updateSheetHeight(from + distance * progress);
+
+        if (progress < 1) {
+          animationFrameRef.current = window.requestAnimationFrame(animate);
+          return;
+        }
+
+        setIsAnimating(false);
+        onSettled(to);
+        updateSheetHeight(to);
+      };
+
+      animate();
+    },
+    [isVerticalSheet, animationConfig, updateSheetHeight, onSettled, enabled],
+  );
+
+  const cancelAnimation = useCallback(() => {
+    if (animationFrameRef.current) {
+      window.cancelAnimationFrame(animationFrameRef.current);
+    }
+  }, []);
+
+  return { isAnimating, animateToSnapPoint, cancelAnimation };
+};
+
+/**
+ * Where the sheet rests and how it gets there. Knows nothing about pointers —
+ * `useDragGestures` supplies the positions.
+ */
+const useSnapGeometry = (input: SheetDragInput) => {
+  const {
+    isVerticalSheet,
+    snapPoints,
+    defaultSnapPoint,
+    minSnapPoint,
+    maxSnapPoint,
+    velocityThreshold,
+    animationConfig,
+    onSnapPointChange,
+  } = input;
+
+  const [currentSnapPoint, setCurrentSnapPoint] = useState(defaultSnapPoint);
+  const { sheetRef, currentHeight, updateSheetHeight } = useSheetHeight(input);
+
+  const sortedSnapPoints = useMemo(
+    () =>
+      [...snapPoints]
+        .sort((a, b) => a - b)
+        .filter((point) => point >= minSnapPoint && point <= maxSnapPoint),
+    [snapPoints, minSnapPoint, maxSnapPoint],
+  );
+
+  const onSettled = useCallback(
+    (snapPoint: number) => {
+      setCurrentSnapPoint(snapPoint);
+      onSnapPointChange?.(snapPoint);
+    },
+    [onSnapPointChange],
+  );
+
+  const hasPanel = useCallback(() => Boolean(sheetRef.current), [sheetRef]);
+
+  const { isAnimating, animateToSnapPoint, cancelAnimation } = useSnapAnimation({
+    isVerticalSheet,
+    animationConfig,
+    updateSheetHeight,
+    onSettled,
+    enabled: hasPanel,
+  });
+
+  const settleAt = useCallback(
+    (position: number, velocity: number) => {
+      const target = closestSnapPoint(
+        sortedSnapPoints,
+        position,
+        currentSnapPoint,
+        velocity,
+        velocityThreshold,
+      );
+      if (target === undefined) return undefined;
+
+      animateToSnapPoint(currentSnapPoint, target, velocity);
+      return target;
+    },
+    [sortedSnapPoints, currentSnapPoint, velocityThreshold, animateToSnapPoint],
+  );
+
+  /** Re-seat the panel at its default snap point each time it opens. */
+  const resetToDefaultSnapPoint = useCallback(() => {
+    setCurrentSnapPoint(defaultSnapPoint);
+    updateSheetHeight(defaultSnapPoint);
+  }, [defaultSnapPoint, updateSheetHeight]);
+
+  return {
+    sheetRef,
+    currentSnapPoint,
+    currentHeight,
+    isAnimating,
+    updateSheetHeight,
+    settleAt,
+    resetToDefaultSnapPoint,
+    cancelAnimation,
+  };
+};
+
+export type SnapGeometry = ReturnType<typeof useSnapGeometry>;
+
+/**
+ * The draggable variant's whole state machine. It lives apart from the component
+ * because none of it is about what the sheet renders — the component only needs
+ * the ref to attach, the current height to size with, and the two flags that
+ * suppress the CSS transition mid-drag.
+ */
+export const useSheetDrag = (input: SheetDragInput) => {
+  const geometry = useSnapGeometry(input);
+  const { isDragging, handleDragStart } = useDragGestures(input, geometry);
+
+  return {
+    sheetRef: geometry.sheetRef,
+    currentHeight: geometry.currentHeight,
+    isAnimating: geometry.isAnimating,
+    resetToDefaultSnapPoint: geometry.resetToDefaultSnapPoint,
+    isDragging,
+    handleDragStart,
+  };
+};
+
+interface SheetOpenInput {
+  open: boolean;
+  persistent: boolean;
+  disabled: boolean;
+  closeOnEscape: boolean;
+  closeOnOverlayClick: boolean;
+  isDraggableVariant: boolean;
+  isVerticalSheet: boolean;
+  resetToDefaultSnapPoint: () => void;
+  onOpenChange?: (open: boolean) => void;
+  onClose?: () => void;
+  onOpen?: () => void;
+}
+
+/**
+ * Open/closed state and the three ways it changes: the `open` prop, the Escape
+ * key, and a click on the overlay. `persistent` and `disabled` block every
+ * close path, so they are checked once here rather than at each caller.
+ */
+export const useSheetOpen = (input: SheetOpenInput) => {
+  const {
+    open, persistent, disabled, closeOnEscape, closeOnOverlayClick,
+    isDraggableVariant, isVerticalSheet, resetToDefaultSnapPoint,
+    onOpenChange, onClose, onOpen,
+  } = input;
+
+  const [isOpen, setIsOpen] = useState(open);
+
+  const handleClose = useCallback(() => {
+    if (!persistent && !disabled) {
+      setIsOpen(false);
+      onOpenChange?.(false);
+      onClose?.();
+    }
+  }, [persistent, disabled, onOpenChange, onClose]);
+
+  const handleOverlayClick = useCallback(() => {
+    if (closeOnOverlayClick && !persistent) {
+      handleClose();
+    }
+  }, [closeOnOverlayClick, persistent, handleClose]);
+
+  const handleSwipeOpen = useCallback(() => {
+    setIsOpen(true);
+    onOpenChange?.(true);
+    onOpen?.();
+  }, [onOpenChange, onOpen]);
+
+  useEffect(() => {
+    setIsOpen(open);
+    if (open) {
+      onOpen?.();
+      if (isDraggableVariant && isVerticalSheet) {
+        resetToDefaultSnapPoint();
+      }
+    }
+  }, [open, onOpen, isDraggableVariant, isVerticalSheet, resetToDefaultSnapPoint]);
+
+  useEffect(() => {
+    if (!isOpen) return;
+
+    const handleEscape = (e: globalThis.KeyboardEvent) => {
+      if (closeOnEscape && e.key === 'Escape') {
+        handleClose();
+      }
+    };
+
+    document.addEventListener('keydown', handleEscape);
+    return () => document.removeEventListener('keydown', handleEscape);
+  }, [isOpen, closeOnEscape, handleClose]);
+
+  return { isOpen, handleClose, handleOverlayClick, handleSwipeOpen };
+};