@12-apps/ui 6.38.0 → 6.39.1

package/src/components/utility/InfiniteScroll/InfiniteScroll.parts.tsx

@@ -2,27 +2,33 @@ import Alert from '@mui/material/Alert/index.js';
 import Box from '@mui/material/Box/index.js';
 import CircularProgress from '@mui/material/CircularProgress/index.js';
 import Typography from '@mui/material/Typography/index.js';
+import { useTheme, type SxProps, type Theme } from '@mui/material/styles/index.js';
 import React from 'react';
 
+import { rem } from '../../../tokens/relative';
+
 import type { InfiniteScrollProps } from './InfiniteScroll.types';
 
 type Variant = NonNullable<InfiniteScrollProps['variant']>;
 
-const CENTERED = {
+const CENTERED: SxProps<Theme> = {
   display: 'flex',
   justifyContent: 'center',
   alignItems: 'center',
   p: 2,
-} as const;
+};
 
-export const DefaultLoader: React.FC<{ loadingText: string }> = ({ loadingText }) => (
-  <Box sx={CENTERED}>
-    <CircularProgress size={24} />
-    <Typography variant="body2" sx={{ ml: 1 }}>
-      {loadingText}
-    </Typography>
-  </Box>
-);
+export const DefaultLoader: React.FC<{ loadingText: string }> = ({ loadingText }) => {
+  const theme = useTheme();
+  return (
+    <Box sx={CENTERED}>
+      <CircularProgress size={rem(theme, 24)} />
+      <Typography variant="body2" sx={{ ml: 1 }}>
+        {loadingText}
+      </Typography>
+    </Box>
+  );
+};
 
 export const DefaultEndMessage: React.FC<{ endText: string }> = ({ endText }) => (
   <Box sx={CENTERED}>
@@ -38,14 +44,25 @@ export const DefaultError: React.FC<{ error: Error }> = ({ error }) => (
   </Alert>
 );
 
+/**
+ * The horizontal variant's `width` as CSS: a number of 1 or less stays the
+ * fraction `sx` reads it as, a larger one is design px, a string is as given;
+ * unset (or 0) fills the parent.
+ */
+const horizontalWidth = (theme: Theme, width: number | string | undefined): string => {
+  if (!width) return '100%';
+  if (typeof width !== 'number') return width;
+  return width <= 1 ? `${width * 100}%` : rem(theme, width);
+};
+
 /**
  * `horizontal` scrolls along a row; `reverse` stacks bottom-up, for a chat log
  * that loads older messages as you scroll away from the newest.
  */
-export const containerStyles = (variant: Variant, width?: number | string) => {
+export const containerStyles = (theme: Theme, variant: Variant, width?: number | string) => {
   const horizontal = variant === 'horizontal';
   const base = {
-    width: horizontal ? width || '100%' : '100%',
+    width: horizontal ? horizontalWidth(theme, width) : '100%',
     height: horizontal ? '100%' : 'auto',
     overflowX: horizontal ? 'auto' : 'hidden',
     overflowY: horizontal ? 'hidden' : 'visible',

package/src/components/utility/InfiniteScroll/InfiniteScroll.tsx

@@ -1,6 +1,9 @@
 import Box from '@mui/material/Box/index.js';
+import { useTheme } from '@mui/material/styles/index.js';
 import React from 'react';
 
+import { rem, remPx } from '../../../tokens/relative';
+
 import { useLoadMore, useSentinel } from './InfiniteScroll.hooks';
 import {
   containerStyles,
@@ -15,7 +18,7 @@ export const InfiniteScroll: React.FC<InfiniteScrollProps> = ({
   variant = 'default',
   hasMore,
   loading,
-  threshold = 150,
+  threshold,
   loadMore,
   loader,
   loadingText,
@@ -31,7 +34,10 @@ export const InfiniteScroll: React.FC<InfiniteScrollProps> = ({
   testMode = false,
   testTriggerRef,
 }) => {
-  const { sentinelRef, isIntersecting } = useSentinel({ testMode, threshold, scrollableTarget });
+  const theme = useTheme();
+  // 150 design px unless the caller says; `rootMargin` only takes px.
+  const rootMargin = `${remPx(theme, threshold ?? 150)}px`;
+  const { sentinelRef, isIntersecting } = useSentinel({ testMode, rootMargin, scrollableTarget });
 
   useLoadMore({
     hasMore,
@@ -56,8 +62,8 @@ export const InfiniteScroll: React.FC<InfiniteScrollProps> = ({
         ref={sentinelRef}
         data-testid="infinite-scroll-sentinel"
         style={{
-          height: variant === 'horizontal' ? '100%' : '1px',
-          width: variant === 'horizontal' ? '1px' : '100%',
+          height: variant === 'horizontal' ? '100%' : rem(theme, 1),
+          width: variant === 'horizontal' ? rem(theme, 1) : '100%',
         }}
       />
     );
@@ -67,7 +73,7 @@ export const InfiniteScroll: React.FC<InfiniteScrollProps> = ({
     <Box
       className={className}
       sx={{
-        ...containerStyles(variant, width),
+        ...containerStyles(theme, variant, width),
         ...style,
       }}
     >

package/src/components/utility/InfiniteScroll/InfiniteScroll.types.ts

@@ -13,7 +13,11 @@ export interface InfiniteScrollProps {
   variant?: InfiniteScrollVariant;
   hasMore: boolean;
   loading: boolean;
-  threshold?: number; // Distance from bottom/edge to trigger loading
+  /**
+   * How far before the end the next page is requested (default 150) — design
+   * px, scaled with the theme's type scale.
+   */
+  threshold?: number;
   loadMore: () => void | Promise<void>;
   loader?: ReactNode;
   endMessage?: ReactNode;
@@ -22,7 +26,11 @@ export interface InfiniteScrollProps {
   onError?: (error: Error) => void;
   className?: string;
   style?: React.CSSProperties;
-  // Horizontal specific
+  /**
+   * The `horizontal` variant's width. A number of 1 or less is a fraction of
+   * the parent (as in `sx`); a larger number is design px, scaled with the
+   * theme's type scale; a string is used as given.
+   */
   width?: number | string;
   scrollableTarget?: string | HTMLElement; // For custom scroll containers
   /**

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

@@ -1,18 +1,21 @@
-import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useTheme, type Theme } from '@mui/material/styles/index.js';
+import React, { useCallback, useEffect, useMemo, useState } from 'react';
+
+import { rem, remPx } from '../../../tokens/relative';
 
 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;
+type ItemSize = (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 };
+  return { scrollTop: element.scrollTop, scrollLeft: element.scrollLeft };
 };
 
 /**
@@ -47,7 +50,7 @@ const useScrollTop = (
 
   const handleScroll = useCallback(
     (event: ScrollEvent) => {
-      const { top, left } = scrollOffsets(event);
+      const { scrollTop: top, scrollLeft: left } = scrollOffsets(event);
       setScrollTop(top);
       report(top, left);
     },
@@ -59,63 +62,60 @@ const useScrollTop = (
   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.
+ * A `width` prop as CSS. `sx` reads a number of 1 or less as a fraction of the
+ * parent, and that stays so; a larger number is design px, through the type
+ * scale; a string is as given.
  */
-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],
-  );
+export const widthCss = (theme: Theme, width: number | string): string => {
+  if (typeof width !== 'number') return width;
+  return width <= 1 && width !== 0 ? `${width * 100}%` : rem(theme, width);
 };
 
-const useTotalHeight = (
+/** Every item's height, its offset from the top, and their sum — all in DESIGN px. */
+interface DesignHeights {
+  size: ItemSize;
+  offset: ItemSize;
+  total: number;
+}
+
+/**
+ * Fixed lists know every height up front; variable ones take the item's own
+ * declared height and otherwise the estimate.
+ *
+ * Kept in the caller's DESIGN px on purpose: the CSS draws a height with `rem`
+ * and the range maths reads it through `remPx`, so the two are one number at
+ * any type scale — never a row drawn at one pitch and positioned at another.
+ */
+const useDesignHeights = (
   items: ListItems,
   variant: ListVariant,
-  itemHeight: number,
-  getItemHeight: ItemHeight,
-) =>
+  fixed: number,
+  estimated: number,
+): DesignHeights =>
   useMemo(() => {
-    if (variant === 'fixed') {
-      return items.length * itemHeight;
+    if (variant !== 'variable') {
+      return { size: () => fixed, offset: (index) => index * fixed, total: items.length * fixed };
     }
 
-    let sum = 0;
+    const size = (index: number): number => items[index]?.height || estimated;
+    // Running sums, so an offset is a lookup rather than a walk from the top.
+    const starts = [0];
     for (let i = 0; i < items.length; i++) {
-      sum += getItemHeight(i);
+      starts.push((starts[i] ?? 0) + size(i));
     }
-    return sum;
-  }, [items.length, variant, itemHeight, getItemHeight]);
+    return { size, offset: (index) => starts[index] ?? 0, total: starts[items.length] ?? 0 };
+  }, [items, variant, fixed, estimated]);
 
+/** The range maths' inputs, in the px the scroll offset is measured in. */
 interface RangeArgs {
   count: number;
   scrollTop: number;
   height: number;
   overscan: number;
   itemHeight: number;
-  getItemHeight: ItemHeight;
+  getItemHeight: ItemSize;
 }
 
 // Walks forward accumulating heights until it passes the viewport's top edge, then
@@ -155,56 +155,38 @@ const fixedRange = ({ count, scrollTop, height, overscan, itemHeight }: RangeArg
   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'];
-}
-
+/**
+ * `height`, `itemHeight`, `estimatedItemHeight` and an item's own `height` are
+ * design px. The range is computed in the px `scrollTop` is measured in
+ * (`remPx`), the viewport and the scroll content are drawn in `rem`, and each
+ * item's `top`/`height` is the `remPx` of its design offset and height.
+ */
 export const useVirtualList = ({
   items,
-  variant,
+  variant = 'fixed',
   height,
   itemHeight,
   estimatedItemHeight,
-  overscan,
+  overscan = 5,
   onScroll,
   scrollContainerRef,
-}: ListArgs) => {
-  const getItemHeight = useItemHeight({ items, variant, itemHeight, estimatedItemHeight });
-  const getItemOffset = useItemOffset(variant, itemHeight, getItemHeight);
-  const totalHeight = useTotalHeight(items, variant, itemHeight, getItemHeight);
+}: VirtualListProps) => {
+  const theme = useTheme();
+  // 40 design px when the caller does not size a row.
+  const design = useDesignHeights(items, variant, itemHeight ?? 40, estimatedItemHeight ?? 40);
 
   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 args = {
+      count: items.length,
+      scrollTop,
+      height: remPx(theme, height),
+      overscan,
+      itemHeight: remPx(theme, design.size(0)),
+      getItemHeight: (index: number) => remPx(theme, design.size(index)),
+    };
     const { startIndex, endIndex } = variant === 'fixed' ? fixedRange(args) : variableRange(args);
     const result = [];
 
@@ -217,33 +199,26 @@ export const useVirtualList = ({
         index: i,
         style: {
           position: 'absolute' as const,
-          top: getItemOffset(i),
+          top: remPx(theme, design.offset(i)),
           left: 0,
           width: '100%',
-          height: getItemHeight(i),
+          height: remPx(theme, design.size(i)),
         },
       });
     }
 
     return result;
-  }, [items, scrollTop, height, overscan, variant, itemHeight, getItemOffset, getItemHeight]);
-
-  return { totalHeight, visibleItems, handleScroll };
+  }, [items, scrollTop, height, overscan, variant, design, theme]);
+
+  return {
+    totalHeight: rem(theme, design.total),
+    viewportHeight: rem(theme, height),
+    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'];
-}
-
+/** The column width in DESIGN px: the caller's, or an even share of a numeric width. */
 const useColumnWidth = (
   columnWidth: number | undefined,
   width: number | string,
@@ -257,21 +232,26 @@ const useColumnWidth = (
     return (containerWidth - (columnCount - 1) * gap) / columnCount;
   }, [columnWidth, width, columnCount, gap]);
 
+/**
+ * `height`, `rowHeight`, `columnWidth` and `gap` are design px: the range and
+ * every cell's box are computed through `remPx`, the viewport and the content
+ * are drawn through `rem`.
+ */
 export const useVirtualGrid = ({
   items,
   height,
-  width,
+  width = '100%',
   columnCount,
   rowHeight,
   columnWidth,
-  gap,
-  overscan,
+  gap = 0,
+  overscan = 5,
   onScroll,
   scrollContainerRef,
-}: GridArgs) => {
+}: VirtualGridProps) => {
+  const theme = useTheme();
   const rowCount = Math.ceil(items.length / columnCount);
-  const totalHeight = rowCount * (rowHeight + gap) - gap;
-  const computedColumnWidth = useColumnWidth(columnWidth, width, columnCount, gap);
+  const designColumn = useColumnWidth(columnWidth, width, columnCount, gap);
 
   const report = useCallback(
     (top: number, left: number) => onScroll?.(top, left),
@@ -280,9 +260,13 @@ export const useVirtualGrid = ({
   const { scrollTop, handleScroll } = useScrollTop(scrollContainerRef, report);
 
   const visibleItems = useMemo(() => {
-    const pitch = rowHeight + gap;
+    const pitch = remPx(theme, rowHeight + gap);
+    const stride = remPx(theme, designColumn + gap);
     const startRow = Math.max(0, Math.floor(scrollTop / pitch) - overscan);
-    const endRow = Math.min(rowCount - 1, Math.ceil((scrollTop + height) / pitch) + overscan);
+    const endRow = Math.min(
+      rowCount - 1,
+      Math.ceil((scrollTop + remPx(theme, 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.
@@ -305,15 +289,20 @@ export const useVirtualGrid = ({
         style: {
           position: 'absolute' as const,
           top: rowIndex * pitch,
-          left: columnIndex * (computedColumnWidth + gap),
-          width: computedColumnWidth,
-          height: rowHeight,
+          left: columnIndex * stride,
+          width: remPx(theme, designColumn),
+          height: remPx(theme, rowHeight),
         },
       });
     }
 
     return result;
-  }, [items, scrollTop, height, overscan, rowCount, columnCount, rowHeight, gap, computedColumnWidth]);
-
-  return { totalHeight, visibleItems, handleScroll };
+  }, [items, scrollTop, height, overscan, rowCount, columnCount, rowHeight, gap, designColumn, theme]);
+
+  return {
+    totalHeight: rem(theme, rowCount * (rowHeight + gap) - gap),
+    viewportHeight: rem(theme, height),
+    visibleItems,
+    handleScroll,
+  };
 };

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

@@ -1,15 +1,19 @@
 import Box from '@mui/material/Box/index.js';
+import { useTheme } from '@mui/material/styles/index.js';
 import React, { useRef } from 'react';
 
-import { useVirtualGrid, useVirtualList } from './VirtualList.hooks';
+import { useVirtualGrid, useVirtualList, widthCss } from './VirtualList.hooks';
 import type { VirtualGridProps, VirtualListProps } from './VirtualList.types';
 
 interface ContainerProps {
   children: React.ReactNode;
   role: 'list' | 'grid';
-  totalHeight: number;
-  height: number;
-  width: number | string;
+  /** The scroll content's height, as CSS. */
+  totalHeight: string;
+  /** The viewport's height, as CSS. */
+  height: string;
+  /** The viewport's width, as CSS. */
+  width: string;
   disableInternalScroll: boolean;
   onScroll: (event: React.UIEvent<HTMLDivElement>) => void;
   className?: string;
@@ -64,40 +68,25 @@ const VirtualContainer: React.FC<ContainerProps> = ({
   );
 };
 
-export const VirtualList: React.FC<VirtualListProps> = ({
-  items,
-  variant = 'fixed',
-  height,
-  width = '100%',
-  itemHeight = 40,
-  estimatedItemHeight = 40,
-  overscan = 5,
-  renderItem,
-  onScroll,
-  className,
-  style,
-  'data-testid': dataTestId,
-  'aria-label': ariaLabel,
-  scrollContainerRef,
-  disableInternalScroll = false,
-}) => {
-  const { totalHeight, visibleItems, handleScroll } = useVirtualList({
-    items,
-    variant,
-    height,
-    itemHeight,
-    estimatedItemHeight,
-    overscan,
-    onScroll,
-    scrollContainerRef,
-  });
+export const VirtualList: React.FC<VirtualListProps> = (props) => {
+  const {
+    width = '100%',
+    renderItem,
+    className,
+    style,
+    'data-testid': dataTestId,
+    'aria-label': ariaLabel,
+    disableInternalScroll = false,
+  } = props;
+  const theme = useTheme();
+  const { totalHeight, viewportHeight, visibleItems, handleScroll } = useVirtualList(props);
 
   return (
     <VirtualContainer
       role="list"
       totalHeight={totalHeight}
-      height={height}
-      width={width}
+      height={viewportHeight}
+      width={widthCss(theme, width)}
       disableInternalScroll={disableInternalScroll}
       onScroll={handleScroll}
       className={className}
@@ -112,43 +101,25 @@ export const VirtualList: React.FC<VirtualListProps> = ({
   );
 };
 
-export const VirtualGrid: React.FC<VirtualGridProps> = ({
-  items,
-  height,
-  width = '100%',
-  columnCount,
-  rowHeight,
-  columnWidth,
-  gap = 0,
-  overscan = 5,
-  renderItem,
-  onScroll,
-  className,
-  style,
-  'data-testid': dataTestId,
-  'aria-label': ariaLabel,
-  scrollContainerRef,
-  disableInternalScroll = false,
-}) => {
-  const { totalHeight, visibleItems, handleScroll } = useVirtualGrid({
-    items,
-    height,
-    width,
-    columnCount,
-    rowHeight,
-    columnWidth,
-    gap,
-    overscan,
-    onScroll,
-    scrollContainerRef,
-  });
+export const VirtualGrid: React.FC<VirtualGridProps> = (props) => {
+  const {
+    width = '100%',
+    renderItem,
+    className,
+    style,
+    'data-testid': dataTestId,
+    'aria-label': ariaLabel,
+    disableInternalScroll = false,
+  } = props;
+  const theme = useTheme();
+  const { totalHeight, viewportHeight, visibleItems, handleScroll } = useVirtualGrid(props);
 
   return (
     <VirtualContainer
       role="grid"
       totalHeight={totalHeight}
-      height={height}
-      width={width}
+      height={viewportHeight}
+      width={widthCss(theme, width)}
       disableInternalScroll={disableInternalScroll}
       onScroll={handleScroll}
       className={className}

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

@@ -4,17 +4,25 @@ export type VirtualListVariant = 'fixed' | 'variable' | 'grid';
 
 export interface VirtualListItem {
   id: string | number;
-  height?: number; // For variable height items
+  /** This item's own height, for a `variable` list — design px, scaled with the theme's type scale. */
+  height?: number;
   data?: unknown;
 }
 
 export interface VirtualListProps {
   items: VirtualListItem[];
   variant?: VirtualListVariant;
+  /** The viewport's height — design px, scaled with the theme's type scale. */
   height: number;
+  /**
+   * The viewport's width. A number of 1 or less is a fraction of the parent (as
+   * in `sx`); a larger number is design px, scaled with the theme's type scale; a string is used as given.
+   */
   width?: number | string;
-  itemHeight?: number; // For fixed height items
-  estimatedItemHeight?: number; // For variable height items
+  /** Every row's height in a `fixed` list (default 40) — design px, scaled with the theme's type scale. */
+  itemHeight?: number;
+  /** The height assumed for a `variable` item that declares none (default 40) — design px, scaled with the theme's type scale. */
+  estimatedItemHeight?: number;
   overscan?: number; // Number of items to render outside visible area
   renderItem: (params: { item: VirtualListItem; index: number; style: CSSProperties }) => ReactNode;
   onScroll?: (scrollTop: number) => void;
@@ -30,11 +38,20 @@ export interface VirtualListProps {
 
 export interface VirtualGridProps {
   items: VirtualListItem[];
+  /** The viewport's height — design px, scaled with the theme's type scale. */
   height: number;
+  /**
+   * The viewport's width. A number of 1 or less is a fraction of the parent (as
+   * in `sx`); a larger number is design px, scaled with the theme's type scale, and also what an unset
+   * `columnWidth` is shared out of; a string is used as given.
+   */
   width?: number | string;
   columnCount: number;
+  /** Every row's height — design px, scaled with the theme's type scale. */
   rowHeight: number;
+  /** Every column's width — design px, scaled with the theme's type scale. */
   columnWidth?: number;
+  /** The space between two rows and between two columns — design px, scaled with the theme's type scale. */
   gap?: number;
   overscan?: number;
   renderItem: (params: {