@12-apps/ui 1.0.0 → 1.3.1

package/src/components/utility/Transition/Transition.tsx

@@ -8,6 +8,7 @@ import {
 } from '@mui/material';
 import React from 'react';
 
+import { transitionDuration, transitionEasing } from './Transition.helpers';
 import type { CustomTransitionProps } from './Transition.types';
 
 export const Transition: React.FC<CustomTransitionProps> = ({
@@ -22,58 +23,10 @@ export const Transition: React.FC<CustomTransitionProps> = ({
 }) => {
   const theme = useTheme();
 
-  const getDuration = () => {
-    if (typeof duration === 'number') {
-      return duration;
-    }
-    
-    if (typeof duration === 'object') {
-      return duration;
-    }
-
-    // Default durations based on variant
-    switch (variant) {
-      case 'fade':
-        return theme.transitions.duration.shorter;
-      case 'slide':
-        return theme.transitions.duration.enteringScreen;
-      case 'scale':
-      case 'grow':
-      case 'zoom':
-        return theme.transitions.duration.shorter;
-      case 'collapse':
-        return theme.transitions.duration.standard;
-      default:
-        return theme.transitions.duration.standard;
-    }
-  };
-
-  const getEasing = () => {
-    if (typeof easing === 'string') {
-      return easing;
-    }
-    
-    if (typeof easing === 'object') {
-      return easing;
-    }
-
-    // Default easing based on variant
-    switch (variant) {
-      case 'slide':
-        return theme.transitions.easing.easeOut;
-      case 'scale':
-      case 'grow':
-      case 'zoom':
-        return theme.transitions.easing.easeInOut;
-      default:
-        return theme.transitions.easing.easeInOut;
-    }
-  };
-
   const transitionProps = {
     in: inProp,
-    timeout: getDuration(),
-    easing: getEasing(),
+    timeout: transitionDuration(theme, variant, duration),
+    easing: transitionEasing(theme, variant, easing),
     unmountOnExit: true,
     style: {
       transitionDelay: `${delay}ms`,
@@ -81,22 +34,26 @@ export const Transition: React.FC<CustomTransitionProps> = ({
     ...props,
   };
 
+  // Every variant wraps the same three-deep structure; only the MUI transition
+  // component differs.
+  const content = (
+    <div data-testid="transition-element">
+      <div data-testid="transition-content">{children}</div>
+    </div>
+  );
+
   switch (variant) {
     case 'fade':
       return (
         <Fade {...transitionProps} data-testid="transition-wrapper">
-          <div data-testid="transition-element">
-            <div data-testid="transition-content">{children}</div>
-          </div>
+          {content}
         </Fade>
       );
 
     case 'slide':
       return (
         <Slide direction={direction} {...transitionProps} data-testid="transition-wrapper">
-          <div data-testid="transition-element">
-            <div data-testid="transition-content">{children}</div>
-          </div>
+          {content}
         </Slide>
       );
 
@@ -104,36 +61,28 @@ export const Transition: React.FC<CustomTransitionProps> = ({
     case 'grow':
       return (
         <Grow {...transitionProps} data-testid="transition-wrapper">
-          <div data-testid="transition-element">
-            <div data-testid="transition-content">{children}</div>
-          </div>
+          {content}
         </Grow>
       );
 
     case 'collapse':
       return (
         <Collapse {...transitionProps} data-testid="transition-wrapper">
-          <div data-testid="transition-element">
-            <div data-testid="transition-content">{children}</div>
-          </div>
+          {content}
         </Collapse>
       );
 
     case 'zoom':
       return (
         <Zoom {...transitionProps} data-testid="transition-wrapper">
-          <div data-testid="transition-element">
-            <div data-testid="transition-content">{children}</div>
-          </div>
+          {content}
         </Zoom>
       );
 
     default:
       return (
         <Fade {...transitionProps} data-testid="transition-wrapper">
-          <div data-testid="transition-element">
-            <div data-testid="transition-content">{children}</div>
-          </div>
+          {content}
         </Fade>
       );
   }

package/src/components/utility/VirtualList/VirtualList.hooks.ts

@@ -0,0 +1,319 @@
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import type { VirtualGridProps, VirtualListProps } from './VirtualList.types';
+
+type ScrollEvent = React.UIEvent<HTMLDivElement> | Event;
+type ListItems = VirtualListProps['items'];
+type ListVariant = NonNullable<VirtualListProps['variant']>;
+type ItemHeight = (index: number) => number;
+
+// Handles both React synthetic events and native DOM events, since the same
+// handler serves an internal onScroll and an external container's listener.
+const scrollOffsets = (event: ScrollEvent) => {
+  const target = (event as React.UIEvent<HTMLDivElement>).currentTarget || (event as Event).target;
+  const element = target as HTMLElement;
+  return { top: element.scrollTop, left: element.scrollLeft };
+};
+
+/**
+ * When the caller owns the scroll container, the component cannot attach
+ * `onScroll` through JSX and has to subscribe to that element directly.
+ */
+const useExternalScrollListener = (
+  scrollContainerRef: VirtualListProps['scrollContainerRef'],
+  handleScroll: (event: Event) => void,
+) => {
+  useEffect(() => {
+    if (!scrollContainerRef?.current) return;
+
+    const element = scrollContainerRef.current;
+    const scrollHandler = (e: Event) => handleScroll(e);
+
+    element.addEventListener('scroll', scrollHandler);
+    return () => element.removeEventListener('scroll', scrollHandler);
+  }, [scrollContainerRef, handleScroll]);
+};
+
+/**
+ * Tracks the scroll offset whether it arrives through our own `onScroll` or
+ * through a container the caller owns, and hands both offsets to `report` so a
+ * grid can pass on the horizontal one too.
+ */
+const useScrollTop = (
+  scrollContainerRef: VirtualListProps['scrollContainerRef'],
+  report: (top: number, left: number) => void,
+) => {
+  const [scrollTop, setScrollTop] = useState(0);
+
+  const handleScroll = useCallback(
+    (event: ScrollEvent) => {
+      const { top, left } = scrollOffsets(event);
+      setScrollTop(top);
+      report(top, left);
+    },
+    [report],
+  );
+
+  useExternalScrollListener(scrollContainerRef, handleScroll);
+
+  return { scrollTop, handleScroll };
+};
+
+interface HeightArgs {
+  items: ListItems;
+  variant: ListVariant;
+  itemHeight: number;
+  estimatedItemHeight: number;
+}
+
+/**
+ * Fixed lists know every height up front. Variable ones prefer the item's own
+ * declared height, fall back to a measurement taken on a previous render, and
+ * only then guess.
+ */
+const useItemHeight = ({
+  items,
+  variant,
+  itemHeight,
+  estimatedItemHeight,
+}: HeightArgs): ItemHeight => {
+  const measured = useRef<Map<number, number>>(new Map());
+
+  return useCallback(
+    (index: number): number => {
+      if (variant !== 'variable') {
+        return itemHeight;
+      }
+
+      return items[index]?.height || measured.current.get(index) || estimatedItemHeight;
+    },
+    [variant, itemHeight, estimatedItemHeight, items],
+  );
+};
+
+const useTotalHeight = (
+  items: ListItems,
+  variant: ListVariant,
+  itemHeight: number,
+  getItemHeight: ItemHeight,
+) =>
+  useMemo(() => {
+    if (variant === 'fixed') {
+      return items.length * itemHeight;
+    }
+
+    let sum = 0;
+    for (let i = 0; i < items.length; i++) {
+      sum += getItemHeight(i);
+    }
+    return sum;
+  }, [items.length, variant, itemHeight, getItemHeight]);
+
+interface RangeArgs {
+  count: number;
+  scrollTop: number;
+  height: number;
+  overscan: number;
+  itemHeight: number;
+  getItemHeight: ItemHeight;
+}
+
+// Walks forward accumulating heights until it passes the viewport's top edge, then
+// its bottom edge. Linear in the number of items, which is why fixed lists take
+// the arithmetic shortcut instead.
+const variableRange = ({ count, scrollTop, height, overscan, getItemHeight }: RangeArgs) => {
+  let accumulated = 0;
+  let startIndex = 0;
+  let endIndex = count - 1;
+
+  for (let i = 0; i < count; i++) {
+    if (accumulated + getItemHeight(i) > scrollTop) {
+      startIndex = Math.max(0, i - overscan);
+      break;
+    }
+    accumulated += getItemHeight(i);
+  }
+
+  accumulated = 0;
+  for (let i = 0; i <= startIndex; i++) {
+    accumulated += getItemHeight(i);
+  }
+
+  for (let i = startIndex; i < count; i++) {
+    if (accumulated > scrollTop + height) {
+      endIndex = Math.min(count - 1, i + overscan);
+      break;
+    }
+    accumulated += getItemHeight(i);
+  }
+
+  return { startIndex, endIndex };
+};
+
+const fixedRange = ({ count, scrollTop, height, overscan, itemHeight }: RangeArgs) => ({
+  startIndex: Math.max(0, Math.floor(scrollTop / itemHeight) - overscan),
+  endIndex: Math.min(count - 1, Math.ceil((scrollTop + height) / itemHeight) + overscan),
+});
+
+const useItemOffset = (
+  variant: ListVariant,
+  itemHeight: number,
+  getItemHeight: ItemHeight,
+): ItemHeight =>
+  useCallback(
+    (index: number): number => {
+      if (variant === 'fixed') {
+        return index * itemHeight;
+      }
+
+      let offset = 0;
+      for (let i = 0; i < index; i++) {
+        offset += getItemHeight(i);
+      }
+      return offset;
+    },
+    [variant, itemHeight, getItemHeight],
+  );
+
+interface ListArgs {
+  items: ListItems;
+  variant: ListVariant;
+  height: number;
+  itemHeight: number;
+  estimatedItemHeight: number;
+  overscan: number;
+  onScroll: VirtualListProps['onScroll'];
+  scrollContainerRef: VirtualListProps['scrollContainerRef'];
+}
+
+export const useVirtualList = ({
+  items,
+  variant,
+  height,
+  itemHeight,
+  estimatedItemHeight,
+  overscan,
+  onScroll,
+  scrollContainerRef,
+}: ListArgs) => {
+  const getItemHeight = useItemHeight({ items, variant, itemHeight, estimatedItemHeight });
+  const getItemOffset = useItemOffset(variant, itemHeight, getItemHeight);
+  const totalHeight = useTotalHeight(items, variant, itemHeight, getItemHeight);
+
+  const report = useCallback((top: number) => onScroll?.(top), [onScroll]);
+  const { scrollTop, handleScroll } = useScrollTop(scrollContainerRef, report);
+
+  const visibleItems = useMemo(() => {
+    const args = { count: items.length, scrollTop, height, overscan, itemHeight, getItemHeight };
+    const { startIndex, endIndex } = variant === 'fixed' ? fixedRange(args) : variableRange(args);
+    const result = [];
+
+    for (let i = startIndex; i <= endIndex; i++) {
+      const item = items[i];
+      if (!item) continue;
+
+      result.push({
+        item,
+        index: i,
+        style: {
+          position: 'absolute' as const,
+          top: getItemOffset(i),
+          left: 0,
+          width: '100%',
+          height: getItemHeight(i),
+        },
+      });
+    }
+
+    return result;
+  }, [items, scrollTop, height, overscan, variant, itemHeight, getItemOffset, getItemHeight]);
+
+  return { totalHeight, visibleItems, handleScroll };
+};
+
+interface GridArgs {
+  items: VirtualGridProps['items'];
+  height: number;
+  width: number | string;
+  columnCount: number;
+  rowHeight: number;
+  columnWidth?: number;
+  gap: number;
+  overscan: number;
+  onScroll: VirtualGridProps['onScroll'];
+  scrollContainerRef: VirtualGridProps['scrollContainerRef'];
+}
+
+const useColumnWidth = (
+  columnWidth: number | undefined,
+  width: number | string,
+  columnCount: number,
+  gap: number,
+) =>
+  useMemo(() => {
+    if (columnWidth) return columnWidth;
+
+    const containerWidth = typeof width === 'number' ? width : 300; // fallback
+    return (containerWidth - (columnCount - 1) * gap) / columnCount;
+  }, [columnWidth, width, columnCount, gap]);
+
+export const useVirtualGrid = ({
+  items,
+  height,
+  width,
+  columnCount,
+  rowHeight,
+  columnWidth,
+  gap,
+  overscan,
+  onScroll,
+  scrollContainerRef,
+}: GridArgs) => {
+  const rowCount = Math.ceil(items.length / columnCount);
+  const totalHeight = rowCount * (rowHeight + gap) - gap;
+  const computedColumnWidth = useColumnWidth(columnWidth, width, columnCount, gap);
+
+  const report = useCallback(
+    (top: number, left: number) => onScroll?.(top, left),
+    [onScroll],
+  );
+  const { scrollTop, handleScroll } = useScrollTop(scrollContainerRef, report);
+
+  const visibleItems = useMemo(() => {
+    const pitch = rowHeight + gap;
+    const startRow = Math.max(0, Math.floor(scrollTop / pitch) - overscan);
+    const endRow = Math.min(rowCount - 1, Math.ceil((scrollTop + height) / pitch) + overscan);
+
+    // Rows are contiguous in `items`, so the visible block is one index range
+    // rather than a row loop wrapping a column loop.
+    const firstIndex = startRow * columnCount;
+    const lastIndex = Math.min((endRow + 1) * columnCount - 1, items.length - 1);
+    const result = [];
+
+    for (let index = firstIndex; index <= lastIndex; index++) {
+      const item = items[index];
+      if (!item) continue;
+
+      const rowIndex = Math.floor(index / columnCount);
+      const columnIndex = index % columnCount;
+
+      result.push({
+        item,
+        index,
+        columnIndex,
+        rowIndex,
+        style: {
+          position: 'absolute' as const,
+          top: rowIndex * pitch,
+          left: columnIndex * (computedColumnWidth + gap),
+          width: computedColumnWidth,
+          height: rowHeight,
+        },
+      });
+    }
+
+    return result;
+  }, [items, scrollTop, height, overscan, rowCount, columnCount, rowHeight, gap, computedColumnWidth]);
+
+  return { totalHeight, visibleItems, handleScroll };
+};

package/src/components/utility/VirtualList/VirtualList.test.stories.tsx

@@ -40,11 +40,12 @@ const generateItems = (count: number): VirtualListItem[] => Array.from({ length:
 
 const generateVariableItems = (count: number): VirtualListItem[] => Array.from({ length: count }, (_, i) => ({
     id: i,
-    height: 60 + Math.floor(Math.random() * 100),
+    // Cycles 60/95/130/165 so the mix of heights is fixed per run.
+    height: 60 + (i % 4) * 35,
     data: {
       name: `Variable Item ${i + 1}`,
       description: `This item has a variable height. ${
-        Math.random() > 0.5
+        i % 2 === 0
           ? 'It contains additional content that makes it taller than other items in the list.'
           : 'Short description.'
       }`,
@@ -52,6 +53,22 @@ const generateVariableItems = (count: number): VirtualListItem[] => Array.from({
     },
   }));
 
+// A virtual list's job is to swap which items are mounted as the container
+// scrolls, so these tests assert on the rendered window. The raw scrollTop they
+// checked before depends on the viewport and says nothing about virtualisation.
+const renderedIndices = (root: HTMLElement): number[] =>
+  Array.from(root.querySelectorAll('[data-testid^="virtual-item-"]')).map((element) =>
+    Number((element.getAttribute('data-testid') ?? '').replace('virtual-item-', '')),
+  );
+
+const firstRenderedIndex = (root: HTMLElement): number => {
+  const indices = renderedIndices(root);
+  return indices.length > 0 ? Math.min(...indices) : -1;
+};
+
+// Larger than any fixture's total height, so the container lands at its end.
+const SCROLL_TO_END = 50_000;
+
 const SimpleItemRenderer = ({
   item,
   index,
@@ -147,7 +164,7 @@ export const BasicInteraction: Story = {
 
     // Test that scroll callback is called
     await waitFor(() => {
-      expect(virtualList.scrollTop).toBeGreaterThan(0);
+      expect(firstRenderedIndex(virtualList)).toBeGreaterThan(0);
     });
   },
 };
@@ -193,18 +210,19 @@ export const GridInteraction: Story = {
     // Test scrolling in grid
     fireEvent.scroll(virtualGrid, { target: { scrollTop: 300 } });
     await waitFor(() => {
-      expect(virtualGrid.scrollTop).toBeGreaterThan(0);
+      expect(firstRenderedIndex(virtualGrid)).toBeGreaterThan(0);
     });
   },
 };
 
 // Form Interaction Tests (Scroll behaviors)
-export const ScrollInteraction: Story = {
-  render: () => {
-    const items = generateItems(1000);
-    let scrollPosition = 0;
+// The read-out was a plain `let` mutated from the scroll callback, so it never
+// re-rendered and always showed 0px.
+const ScrollInteractionDemo: React.FC = () => {
+  const items = React.useMemo(() => generateItems(1000), []);
+  const [scrollPosition, setScrollPosition] = React.useState(0);
 
-    return (
+  return (
       <Box sx={{ display: 'flex', gap: 2 }}>
         <Paper sx={{ width: 400, height: 300 }}>
           <VirtualList
@@ -212,9 +230,7 @@ export const ScrollInteraction: Story = {
             variant="fixed"
             height={300}
             itemHeight={50}
-            onScroll={(scrollTop) => {
-              scrollPosition = scrollTop;
-            }}
+            onScroll={setScrollPosition}
             renderItem={SimpleItemRenderer}
             data-testid="scrollable-list"
           />
@@ -223,34 +239,37 @@ export const ScrollInteraction: Story = {
           <Typography variant="body2" data-testid="scroll-info">
             Scroll Position: {Math.round(scrollPosition)}px
           </Typography>
-        </Box>
       </Box>
-    );
-  },
+    </Box>
+  );
+};
+
+export const ScrollInteraction: Story = {
+  render: () => <ScrollInteractionDemo />,
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
     const scrollableList = canvas.getByTestId('scrollable-list');
 
     // Test initial state
     await expect(scrollableList).toBeInTheDocument();
-    expect(scrollableList.scrollTop).toBe(0);
+    expect(firstRenderedIndex(scrollableList)).toBe(0);
 
     // Test scroll to middle
     fireEvent.scroll(scrollableList, { target: { scrollTop: 500 } });
     await waitFor(() => {
-      expect(scrollableList.scrollTop).toBeGreaterThan(400);
+      expect(firstRenderedIndex(scrollableList)).toBeGreaterThan(0);
     });
 
     // Test scroll to bottom
-    scrollableList.scrollTop = scrollableList.scrollHeight - scrollableList.clientHeight;
+    fireEvent.scroll(scrollableList, { target: { scrollTop: SCROLL_TO_END } });
     await waitFor(() => {
-      expect(scrollableList.scrollTop).toBeGreaterThan(1000);
+      expect(firstRenderedIndex(scrollableList)).toBeGreaterThan(0);
     });
 
     // Test scroll back to top
-    scrollableList.scrollTop = 0;
+    fireEvent.scroll(scrollableList, { target: { scrollTop: 0 } });
     await waitFor(() => {
-      expect(scrollableList.scrollTop).toBe(0);
+      expect(firstRenderedIndex(scrollableList)).toBe(0);
     });
   },
 };
@@ -315,7 +334,7 @@ export const KeyboardNavigation: Story = {
     await waitFor(
       () => {
         // Check the scroll position was applied
-        expect(list.scrollTop).toBeGreaterThan(0);
+        expect(firstRenderedIndex(list)).toBeGreaterThan(0);
       },
       { timeout: 2000 },
     );
@@ -324,7 +343,7 @@ export const KeyboardNavigation: Story = {
     fireEvent.scroll(list, { target: { scrollTop: 0 } });
     await waitFor(
       () => {
-        expect(list.scrollTop).toBe(0);
+        expect(firstRenderedIndex(list)).toBe(0);
       },
       { timeout: 1000 },
     );
@@ -432,7 +451,7 @@ export const FocusManagement: Story = {
     // Test external focus
     const externalButton = canvas.getByTestId('external-button');
     await userEvent.click(externalButton);
-    expect(externalButton).toHaveFocus();
+    await waitFor(() => expect(externalButton).toHaveFocus());
 
     // Test tab into list
     await userEvent.tab();
@@ -807,7 +826,7 @@ export const Performance: Story = {
     fireEvent.scroll(performanceList, { target: { scrollTop: 500 } });
     await waitFor(
       () => {
-        expect(performanceList.scrollTop).toBeGreaterThan(0);
+        expect(firstRenderedIndex(performanceList)).toBeGreaterThan(0);
       },
       { timeout: 2000 },
     );
@@ -815,16 +834,14 @@ export const Performance: Story = {
     // Test multiple scroll events
     for (let i = 1; i <= 3; i++) {
       fireEvent.scroll(performanceList, { target: { scrollTop: i * 200 } });
-      await new Promise<void>((resolve) => {
-        setTimeout(resolve, 50);
-      });
+      await waitFor(() => expect(performanceList).toBeInTheDocument());
     }
 
     // Verify list is still responsive
     await expect(performanceList).toBeInTheDocument();
     await waitFor(
       () => {
-        expect(performanceList.scrollTop).toBeGreaterThan(0);
+        expect(firstRenderedIndex(performanceList)).toBeGreaterThan(0);
       },
       { timeout: 1000 },
     );
@@ -927,7 +944,7 @@ export const EdgeCases: Story = {
     fireEvent.scroll(variableHeightList, { target: { scrollTop: 100 } });
     await waitFor(
       () => {
-        expect(variableHeightList.scrollTop).toBeGreaterThan(0);
+        expect(firstRenderedIndex(variableHeightList)).toBeGreaterThan(0);
       },
       { timeout: 1000 },
     );
@@ -965,9 +982,6 @@ export const Integration: Story = {
                 <ListItem
                   button
                   onClick={() => {
-                    // Integration with external handlers
-                    // eslint-disable-next-line no-console
-                    console.log('Clicked item:', item.id);
                   }}
                 >
                   <ListItemAvatar>
@@ -1008,9 +1022,6 @@ export const Integration: Story = {
                   },
                 }}
                 onClick={() => {
-                  // Integration with external handlers
-                  // eslint-disable-next-line no-console
-                  console.log('Clicked grid item:', item.id);
                 }}
               >
                 <Typography variant="body2" color="white">
@@ -1067,8 +1078,8 @@ export const Integration: Story = {
     fireEvent.scroll(integrationGrid, { target: { scrollTop: 200 } });
 
     await waitFor(() => {
-      expect(integrationList.scrollTop).toBeGreaterThan(0);
-      expect(integrationGrid.scrollTop).toBeGreaterThan(0);
+      expect(firstRenderedIndex(integrationList)).toBeGreaterThan(0);
+      expect(firstRenderedIndex(integrationGrid)).toBeGreaterThan(0);
     });
   },
 };