@12-apps/ui 1.0.0 → 1.3.0

package/src/components/layout/ScrollArea/ScrollArea.tsx

@@ -1,40 +1,23 @@
-import { KeyboardArrowUp } from '@mui/icons-material';
+import KeyboardArrowUp from '@mui/icons-material/KeyboardArrowUp';
 import { alpha, Box, CircularProgress,Fab, useTheme, Zoom } from '@mui/material';
-import React, { useCallback,useEffect, useRef, useState } from 'react';
+import type { FC } from 'react';
+import React, { useCallback, useEffect, useRef, useState } from 'react';
 
+import type { ResolvedScrollAreaProps } from './ScrollArea.helpers';
+import { resolveScrollAreaProps } from './ScrollArea.helpers';
 import type { ScrollAreaProps } from './ScrollArea.types';
-
-export const ScrollArea: React.FC<ScrollAreaProps> = ({
-  children,
-  width = '100%',
-  height = '100%',
-  maxHeight,
-  maxWidth,
-  orientation = 'vertical',
-  scrollbarSize = 'medium',
-  autoHide = true,
-  autoHideDelay = 1000,
-  smoothScroll = true,
-  variant = 'default',
-  onScroll,
-  scrollToTopButton = false,
-  scrollToTopThreshold = 100,
-  scrollbarColor,
-  scrollbarTrackColor,
-  contentPadding = 0,
-  alwaysShowScrollbar = false,
-  disabled = false,
-  loading = false,
-  emptyContent,
-  testId = 'scroll-area',
-  scrollRef: externalScrollRef,
-  onResize,
-  sx,
-  ...props
+import { ScrollAreaContent } from './ScrollAreaContent';
+import { ScrollViewport } from './ScrollViewport';
+
+// Owns the scroll container ref (merging in any ref the caller passed) and
+// reports size changes through a ResizeObserver.
+const useObservedScrollRef = ({
+  externalScrollRef,
+  onResize }: {
+  externalScrollRef?: React.Ref<HTMLDivElement>;
+  onResize?: ScrollAreaProps['onResize'];
 }) => {
-  const theme = useTheme();
   const internalScrollRef = useRef<HTMLDivElement>(null);
-  const [showScrollToTop, setShowScrollToTop] = useState(false);
   const [containerDimensions, setContainerDimensions] = useState({ width: 0, height: 0 });
 
   // Track container dimensions with ResizeObserver
@@ -68,381 +51,207 @@ export const ScrollArea: React.FC<ScrollAreaProps> = ({
   );
 
   // Use internal ref for accessing the element
-  const scrollRef = internalScrollRef;
-  const [isScrolling, setIsScrolling] = useState(false);
-  const scrollTimeoutRef = useRef<number | undefined>(undefined);
 
-  // Get scrollbar size in pixels
-  const getScrollbarSize = () => {
-    switch (scrollbarSize) {
-      case 'thin':
-        return 8;
-      case 'thick':
-        return 16;
-      default:
-        return 12;
-    }
-  };
+  return { scrollRef: internalScrollRef, setScrollRef, containerDimensions };
+};
+
+// Scroll position, the transient "is scrolling" flag that drives auto-hide, the
+// observed container size, and the scroll-to-top affordance.
+// The scrollbar shows while scrolling and hides once movement stops.
+const useAutoHide = ({
+  autoHide,
+  alwaysShowScrollbar,
+  autoHideDelay }: {
+  autoHide: boolean;
+  alwaysShowScrollbar: boolean;
+  autoHideDelay: number;
+}) => {
+  const [isScrolling, setIsScrolling] = useState(false);
+  const timeoutRef = useRef<number | undefined>(undefined);
 
-  // Get scrollbar colors
-  const getScrollbarColors = () => {
-    const defaultScrollbarColor =
-      variant === 'glass'
-        ? alpha(theme.palette.primary.main, 0.5)
-        : theme.palette.mode === 'dark'
-          ? theme.palette.grey[600]
-          : theme.palette.grey[400];
+  const noteScroll = useCallback(() => {
+    if (!autoHide || alwaysShowScrollbar) return;
 
-    const defaultTrackColor =
-      variant === 'glass'
-        ? alpha(theme.palette.background.paper, 0.1)
-        : theme.palette.mode === 'dark'
-          ? theme.palette.grey[900]
-          : theme.palette.grey[200];
+    setIsScrolling(true);
+    window.clearTimeout(timeoutRef.current);
+    timeoutRef.current = window.setTimeout(() => setIsScrolling(false), autoHideDelay);
+  }, [autoHide, alwaysShowScrollbar, autoHideDelay]);
 
-    return {
-      scrollbar: scrollbarColor || defaultScrollbarColor,
-      track: scrollbarTrackColor || defaultTrackColor,
-    };
-  };
+  useEffect(() => () => window.clearTimeout(timeoutRef.current), []);
 
-  // Get overflow style based on orientation
-  const getOverflowStyle = () => {
-    if (disabled) return { overflow: 'hidden' as const };
+  return { isScrolling, noteScroll };
+};
 
-    switch (orientation) {
-      case 'horizontal':
-        return {
-          overflow: 'hidden' as const,
-          overflowX: 'auto' as const,
-          overflowY: 'hidden' as const,
-        };
-      case 'both':
-        return { overflow: 'auto' as const };
-      default:
-        return {
-          overflow: 'hidden' as const,
-          overflowY: 'auto' as const,
-          overflowX: 'hidden' as const,
-        };
-    }
-  };
+const useScrollArea = (
+  props: ResolvedScrollAreaProps & { externalScrollRef?: React.Ref<HTMLDivElement> },
+) => {
+  const {
+    disabled,
+    onScroll,
+    onResize,
+    externalScrollRef,
+    autoHide,
+    autoHideDelay,
+    alwaysShowScrollbar,
+    scrollToTopButton,
+    scrollToTopThreshold,
+    smoothScroll } = props;
+
+  const { scrollRef, setScrollRef, containerDimensions } = useObservedScrollRef({
+    externalScrollRef,
+    onResize });
+  const [showScrollToTop, setShowScrollToTop] = useState(false);
+  const { isScrolling, noteScroll } = useAutoHide({
+    autoHide,
+    alwaysShowScrollbar,
+    autoHideDelay });
 
-  // Handle scroll event
   const handleScroll = useCallback(
     (event: React.UIEvent<HTMLDivElement>) => {
       if (disabled) return;
 
-      // Handle auto-hide behavior
-      if (autoHide && !alwaysShowScrollbar) {
-        setIsScrolling(true);
-        if (scrollTimeoutRef.current) {
-          window.clearTimeout(scrollTimeoutRef.current);
-        }
-        scrollTimeoutRef.current = window.setTimeout(() => {
-          setIsScrolling(false);
-        }, autoHideDelay);
-      }
+      noteScroll();
 
-      // Check if should show scroll to top button
       if (scrollToTopButton && scrollRef.current) {
-        const scrollTop = scrollRef.current.scrollTop;
-        setShowScrollToTop(scrollTop > scrollToTopThreshold);
+        setShowScrollToTop(scrollRef.current.scrollTop > scrollToTopThreshold);
       }
 
-      // Call user's onScroll handler
-      if (onScroll) {
-        onScroll(event);
-      }
+      onScroll?.(event);
     },
-    [
-      disabled,
-      autoHide,
-      alwaysShowScrollbar,
-      autoHideDelay,
-      scrollToTopButton,
-      scrollToTopThreshold,
-      onScroll,
-    ],
+    [disabled, noteScroll, scrollToTopButton, scrollToTopThreshold, onScroll, scrollRef],
   );
 
-  // Scroll to top function
   const scrollToTop = useCallback(() => {
-    if (scrollRef.current) {
-      scrollRef.current.scrollTo({
-        top: 0,
-        behavior: smoothScroll ? 'smooth' : 'auto',
-      });
-    }
-  }, [smoothScroll]);
-
-  // Clean up timeout on unmount
-  useEffect(() => () => {
-      if (scrollTimeoutRef.current) {
-        window.clearTimeout(scrollTimeoutRef.current);
-      }
-    }, []);
-
-  // Determine if scrollbar should be visible
-  const shouldShowScrollbar = alwaysShowScrollbar || !autoHide || isScrolling;
-
-  // Get variant-specific styles
-  const getVariantStyles = () => {
-    const colors = getScrollbarColors();
-    const size = getScrollbarSize();
-
-    // Common scrollbar styles with auto-hide support
-    const getAutoHideStyles = (thumbColor: string, trackColor: string) => ({
-      '&::-webkit-scrollbar': {
-        width: orientation !== 'horizontal' ? size : '100%',
-        height: orientation !== 'vertical' ? size : '100%',
-      },
-      '&::-webkit-scrollbar-track': {
-        background: shouldShowScrollbar ? trackColor : 'transparent',
-        borderRadius: size / 2,
-        transition: 'background 0.3s ease',
-      },
-      '&::-webkit-scrollbar-thumb': {
-        background: shouldShowScrollbar ? thumbColor : 'transparent',
-        borderRadius: size / 2,
-        transition: 'background 0.3s ease',
-        '&:hover': {
-          background: shouldShowScrollbar ? theme.palette.primary.main : 'transparent',
-        },
-      },
-      '&::-webkit-scrollbar-corner': {
-        background: shouldShowScrollbar ? trackColor : 'transparent',
-      },
-      // Firefox scrollbar styling
-      scrollbarWidth: shouldShowScrollbar
-        ? scrollbarSize === 'thin'
-          ? ('thin' as const)
-          : ('auto' as const)
-        : ('none' as const),
-      scrollbarColor: shouldShowScrollbar
-        ? `${thumbColor} ${trackColor}`
-        : 'transparent transparent',
-    });
-
-    switch (variant) {
-      case 'overlay':
-        return {
-          '&::-webkit-scrollbar': {
-            width: orientation !== 'horizontal' ? size : '100%',
-            height: orientation !== 'vertical' ? size : '100%',
-            position: 'absolute',
-            right: 0,
-            top: 0,
-          },
-          '&::-webkit-scrollbar-track': {
-            background: 'transparent',
-            borderRadius: size / 2,
-          },
-          '&::-webkit-scrollbar-thumb': {
-            background: shouldShowScrollbar
-              ? alpha(colors.scrollbar, 0.5)
-              : 'transparent',
-            borderRadius: size / 2,
-            transition: 'background 0.3s ease',
-            border: '2px solid transparent',
-            backgroundClip: 'padding-box',
-            '&:hover': {
-              background: shouldShowScrollbar ? theme.palette.primary.main : 'transparent',
-            },
-          },
-          '&::-webkit-scrollbar-corner': {
-            background: 'transparent',
-          },
-          scrollbarWidth: shouldShowScrollbar
-            ? scrollbarSize === 'thin'
-              ? ('thin' as const)
-              : ('auto' as const)
-            : ('none' as const),
-          scrollbarColor: shouldShowScrollbar
-            ? `${alpha(colors.scrollbar, 0.5)} transparent`
-            : 'transparent transparent',
-        };
-
-      case 'glass': {
-        const glassThumbColor = `linear-gradient(180deg, ${alpha(theme.palette.primary.main, 0.3)}, ${alpha(theme.palette.secondary.main, 0.3)})`;
-        const glassTrackColor = alpha(theme.palette.background.paper, 0.1);
-        return {
-          '&::-webkit-scrollbar': {
-            width: orientation !== 'horizontal' ? size : '100%',
-            height: orientation !== 'vertical' ? size : '100%',
-          },
-          '&::-webkit-scrollbar-track': {
-            background: shouldShowScrollbar ? glassTrackColor : 'transparent',
-            borderRadius: size / 2,
-            backdropFilter: shouldShowScrollbar ? 'blur(5px)' : 'none',
-            transition: 'background 0.3s ease',
-          },
-          '&::-webkit-scrollbar-thumb': {
-            background: shouldShowScrollbar ? glassThumbColor : 'transparent',
-            borderRadius: size / 2,
-            transition: 'background 0.3s ease',
-            boxShadow: shouldShowScrollbar
-              ? `inset 0 0 6px ${alpha(theme.palette.common.white, 0.3)}`
-              : 'none',
-            '&:hover': {
-              background: shouldShowScrollbar ? theme.palette.primary.main : 'transparent',
-            },
-          },
-          '&::-webkit-scrollbar-corner': {
-            background: shouldShowScrollbar ? glassTrackColor : 'transparent',
-          },
-          scrollbarWidth: shouldShowScrollbar
-            ? scrollbarSize === 'thin'
-              ? ('thin' as const)
-              : ('auto' as const)
-            : ('none' as const),
-          scrollbarColor: shouldShowScrollbar
-            ? `${colors.scrollbar} ${glassTrackColor}`
-            : 'transparent transparent',
-          backdropFilter: 'blur(10px)',
-        };
-      }
-
-      default:
-        return getAutoHideStyles(colors.scrollbar, colors.track);
-    }
-  };
-
-  // Render empty content if no children and emptyContent is provided
-  const renderContent = () => {
-    if (!children && emptyContent) {
-      return (
-        <Box
-          sx={{
-            display: 'flex',
-            alignItems: 'center',
-            justifyContent: 'center',
-            height: '100%',
-            minHeight: 200,
-            color: theme.palette.text.secondary,
-          }}
-        >
-          {emptyContent}
-        </Box>
-      );
-    }
-
-    // Auto-enhance children that accept scrollContainerRef (like VirtualList/VirtualGrid)
-    return React.Children.map(children, (child) => {
-      if (React.isValidElement(child)) {
-        // Check if the child component accepts scrollContainerRef prop
-        // by looking at its props type or if it's a known virtualization component
-        const childProps = child.props as Record<string, unknown>;
+    scrollRef.current?.scrollTo({ top: 0, behavior: smoothScroll ? 'smooth' : 'auto' });
+  }, [smoothScroll, scrollRef]);
+
+  return {
+    scrollRef,
+    setScrollRef,
+    isScrolling,
+    showScrollToTop,
+    containerDimensions,
+    handleScroll,
+    scrollToTop };
+};
 
-        // If child has disableInternalScroll prop, it's likely a VirtualList/VirtualGrid
-        // Auto-inject scrollContainerRef, disableInternalScroll, and container width
-        if ('disableInternalScroll' in childProps || childProps.scrollContainerRef !== undefined) {
-          const enhancedProps: Record<string, unknown> = {
-            scrollContainerRef: internalScrollRef,
-            disableInternalScroll: true,
-          };
+const LoadingOverlay: FC = () => (
+  <Box
+    sx={{
+      position: 'absolute',
+      top: '50%',
+      left: '50%',
+      transform: 'translate(-50%, -50%)',
+      zIndex: 10 }}
+  >
+    <CircularProgress />
+  </Box>
+);
+
+const ScrollToTopFab: FC<{ visible: boolean; glass: boolean; onClick: () => void }> = ({
+  visible,
+  glass,
+  onClick }) => {
+  const theme = useTheme();
 
-          // If child accepts width and doesn't have one set, provide container width
-          if (containerDimensions.width > 0 && childProps.width === '100%') {
-            enhancedProps.width = containerDimensions.width;
-          }
+  return (
+    <Zoom in={visible}>
+      <Fab
+        size="small"
+        aria-label="Scroll to top"
+        onClick={onClick}
+        sx={{
+          position: 'absolute',
+          bottom: 16,
+          right: 16,
+          zIndex: 1,
+          backgroundColor: glass
+            ? alpha(theme.palette.primary.main, 0.2)
+            : theme.palette.primary.main,
+          backdropFilter: glass ? 'blur(10px)' : 'none',
+          '&:hover': {
+            backgroundColor: glass
+              ? alpha(theme.palette.primary.main, 0.3)
+              : theme.palette.primary.dark } }}
+      >
+        <KeyboardArrowUp />
+      </Fab>
+    </Zoom>
+  );
+};
 
-          return React.cloneElement(child, enhancedProps);
-        }
-      }
-      return child;
-    });
-  };
+export const ScrollArea: React.FC<ScrollAreaProps> = (componentProps) => {
+  const resolved = resolveScrollAreaProps(componentProps);
+  const {
+    children,
+    width,
+    height,
+    maxHeight,
+    maxWidth,
+    orientation: _orientation,
+    scrollbarSize: _scrollbarSize,
+    autoHide,
+    autoHideDelay: _autoHideDelay,
+    smoothScroll: _smoothScroll,
+    variant,
+    onScroll: _onScroll,
+    scrollToTopButton,
+    scrollToTopThreshold: _scrollToTopThreshold,
+    scrollbarColor: _scrollbarColor,
+    scrollbarTrackColor: _scrollbarTrackColor,
+    contentPadding: _contentPadding,
+    alwaysShowScrollbar,
+    disabled,
+    loading,
+    emptyContent,
+    testId,
+    scrollRef: externalScrollRef,
+    onResize: _onResize,
+    sx,
+    ...props
+  } = resolved;
+
+  const {
+    scrollRef,
+    setScrollRef,
+    isScrolling,
+    showScrollToTop,
+    containerDimensions,
+    handleScroll,
+    scrollToTop } = useScrollArea({ ...resolved, externalScrollRef });
+
+  // Auto-hide keeps the scrollbar out of the way until the user is scrolling.
+  const shouldShowScrollbar = alwaysShowScrollbar || !autoHide || isScrolling;
 
   return (
     <Box
       data-testid={testId}
-      sx={{
-        position: 'relative',
-        width,
-        height,
-        maxHeight,
-        maxWidth,
-        ...sx,
-      }}
+      sx={{ position: 'relative', width, height, maxHeight, maxWidth, ...sx }}
       {...props}
     >
-      <Box
-        ref={setScrollRef}
+      <ScrollViewport
+        {...resolved}
+        shouldShowScrollbar={shouldShowScrollbar}
+        setScrollRef={setScrollRef}
         onScroll={handleScroll}
-        role="region"
-        aria-label="Scrollable content"
-        aria-busy={loading}
-        tabIndex={disabled ? -1 : 0}
-        sx={{
-          width: '100%',
-          height: '100%',
-          // Use explicit maxHeight when height is 'auto', otherwise inherit from parent
-          maxHeight: height === 'auto' && maxHeight ? maxHeight : '100%',
-          padding: contentPadding,
-          opacity: loading ? 0.5 : 1,
-          pointerEvents: disabled || loading ? 'none' : 'auto',
-          transition: 'opacity 0.3s ease',
-          '&:focus': {
-            outline: 'none',
-            '&:focus-visible': {
-              outline: `2px solid ${theme.palette.primary.main}`,
-              outlineOffset: -2,
-            },
-          },
-          ...getOverflowStyle(),
-          ...getVariantStyles(),
-        }}
-        style={{
-          scrollBehavior: smoothScroll ? 'smooth' : 'auto',
-        }}
       >
-        {renderContent()}
-      </Box>
-
-      {/* Loading overlay */}
-      {loading && (
-        <Box
-          sx={{
-            position: 'absolute',
-            top: '50%',
-            left: '50%',
-            transform: 'translate(-50%, -50%)',
-            zIndex: 10,
-          }}
+        <ScrollAreaContent
+          emptyContent={emptyContent}
+          scrollRef={scrollRef}
+          containerWidth={containerDimensions.width}
         >
-          <CircularProgress />
-        </Box>
-      )}
+          {children}
+        </ScrollAreaContent>
+      </ScrollViewport>
+
+      {loading && <LoadingOverlay />}
 
-      {/* Scroll to top button */}
       {scrollToTopButton && !disabled && !loading && (
-        <Zoom in={showScrollToTop}>
-          <Fab
-            size="small"
-            aria-label="Scroll to top"
-            onClick={scrollToTop}
-            sx={{
-              position: 'absolute',
-              bottom: 16,
-              right: 16,
-              zIndex: 1,
-              backgroundColor:
-                variant === 'glass'
-                  ? alpha(theme.palette.primary.main, 0.2)
-                  : theme.palette.primary.main,
-              backdropFilter: variant === 'glass' ? 'blur(10px)' : 'none',
-              '&:hover': {
-                backgroundColor:
-                  variant === 'glass'
-                    ? alpha(theme.palette.primary.main, 0.3)
-                    : theme.palette.primary.dark,
-              },
-            }}
-          >
-            <KeyboardArrowUp />
-          </Fab>
-        </Zoom>
+        <ScrollToTopFab
+          visible={showScrollToTop}
+          glass={variant === 'glass'}
+          onClick={scrollToTop}
+        />
       )}
     </Box>
   );

package/src/components/layout/ScrollArea/ScrollAreaContent.tsx

@@ -0,0 +1,70 @@
+import { Box, useTheme } from '@mui/material';
+import type { FC, ReactNode } from 'react';
+import React from 'react';
+
+const EMPTY_MIN_HEIGHT = 200;
+
+const EmptyState: FC<{ children: ReactNode }> = ({ children }) => {
+  const theme = useTheme();
+
+  return (
+    <Box
+      sx={{
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        height: '100%',
+        minHeight: EMPTY_MIN_HEIGHT,
+        color: theme.palette.text.secondary,
+      }}
+    >
+      {children}
+    </Box>
+  );
+};
+
+// VirtualList and VirtualGrid scroll themselves by default. When one is nested
+// here that would mean two scrollers, so they are handed this container instead
+// and told to stop scrolling internally. They are recognised by the props they
+// accept rather than by identity, so a wrapper around one still works.
+const wantsScrollContainer = (props: Record<string, unknown>): boolean =>
+  'disableInternalScroll' in props || props.scrollContainerRef !== undefined;
+
+export interface ScrollAreaContentProps {
+  children: ReactNode;
+  emptyContent?: ReactNode;
+  scrollRef: React.RefObject<HTMLDivElement | null> | ((node: HTMLDivElement | null) => void);
+  containerWidth: number;
+}
+
+export const ScrollAreaContent: FC<ScrollAreaContentProps> = ({
+  children,
+  emptyContent,
+  scrollRef,
+  containerWidth,
+}) => {
+  if (!children && emptyContent) return <EmptyState>{emptyContent}</EmptyState>;
+
+  return (
+    <>
+      {React.Children.map(children, (child) => {
+        if (!React.isValidElement(child)) return child;
+
+        const childProps = child.props as Record<string, unknown>;
+        if (!wantsScrollContainer(childProps)) return child;
+
+        const enhanced: Record<string, unknown> = {
+          scrollContainerRef: scrollRef,
+          disableInternalScroll: true,
+        };
+
+        // Only fill in a measured width where the child is still at its default.
+        if (containerWidth > 0 && childProps.width === '100%') {
+          enhanced.width = containerWidth;
+        }
+
+        return React.cloneElement(child, enhanced);
+      })}
+    </>
+  );
+};