@12-apps/ui 6.38.0 → 6.39.0

package/src/components/layout/Resizable/Resizable.helpers.ts

@@ -1,7 +1,10 @@
 import type { Theme } from '@mui/material/styles/index.js';
 
+import { rem, remPx } from '../../../tokens/relative';
+
 import type { ResizableProps, ResizableVariant, ResizeHandle } from './Resizable.types';
 
+/** One axis's clamp, in the px a drag runs in. */
 export interface Axis {
   min: number;
   max: number;
@@ -80,16 +83,30 @@ export const handleStyle = (theme: Theme, handle: ResizeHandle, active: boolean)
 
   switch (handle) {
     case 'right':
-      return { ...baseStyle, top: 0, right: -2, width: 4, height: '100%', cursor: 'ew-resize' };
+      return {
+        ...baseStyle,
+        top: 0,
+        right: rem(theme, -2),
+        width: rem(theme, 4),
+        height: '100%',
+        cursor: 'ew-resize',
+      };
     case 'bottom':
-      return { ...baseStyle, bottom: -2, left: 0, width: '100%', height: 4, cursor: 'ns-resize' };
+      return {
+        ...baseStyle,
+        bottom: rem(theme, -2),
+        left: 0,
+        width: '100%',
+        height: rem(theme, 4),
+        cursor: 'ns-resize',
+      };
     case 'bottomRight':
       return {
         ...baseStyle,
-        bottom: -2,
-        right: -2,
-        width: 8,
-        height: 8,
+        bottom: rem(theme, -2),
+        right: rem(theme, -2),
+        width: rem(theme, 8),
+        height: rem(theme, 8),
         cursor: 'nw-resize',
         borderRadius: '50%',
       };
@@ -98,30 +115,35 @@ export const handleStyle = (theme: Theme, handle: ResizeHandle, active: boolean)
   }
 };
 
-type ResizableDefaultedKeys =
-  | 'variant'
-  | 'width'
-  | 'height'
-  | 'minWidth'
-  | 'maxWidth'
-  | 'minHeight'
-  | 'maxHeight'
-  | 'disabled';
+type ResizableDefaultedKeys = 'variant' | 'disabled';
 
 type ResolvedResizableProps = ResizableProps &
   Required<Pick<ResizableProps, ResizableDefaultedKeys>>;
 
 const RESIZABLE_DEFAULTS: Pick<ResizableProps, ResizableDefaultedKeys> = {
   variant: 'both',
-  width: 200,
-  height: 200,
-  minWidth: 50,
-  maxWidth: 1000,
-  minHeight: 50,
-  maxHeight: 1000,
   disabled: false,
 };
 
+/** The box's own defaults, in design px: where it starts, and its clamp. */
+const DEFAULT_BOX_PX = { start: 200, min: 50, max: 1000 } as const;
+
+/**
+ * Where the box starts, in the px a drag runs in. The consumer's sizes are
+ * design px, like every other size in the package; a drag is pointer pixels,
+ * so the live size is px from here on.
+ */
+export const startSizePx = (theme: Theme, width?: number, height?: number) => ({
+  width: remPx(theme, width ?? DEFAULT_BOX_PX.start),
+  height: remPx(theme, height ?? DEFAULT_BOX_PX.start),
+});
+
+/** One axis's clamp, from the consumer's design px to the px a drag runs in. */
+export const axisPx = (theme: Theme, min?: number, max?: number): Axis => ({
+  min: remPx(theme, min ?? DEFAULT_BOX_PX.min),
+  max: remPx(theme, max ?? DEFAULT_BOX_PX.max),
+});
+
 // Strips explicitly-undefined props before the merge, so `minWidth={undefined}`
 // still falls back to the default exactly as a destructuring default would.
 const definedProps = (props: ResizableProps): Partial<ResizableProps> =>

package/src/components/layout/Resizable/Resizable.hooks.ts

@@ -5,9 +5,12 @@ import { resizedTo } from './Resizable.helpers';
 import type { ResizeHandle } from './Resizable.types';
 
 interface ResizeArgs {
-  width: number;
-  height: number;
+  /** Where the box starts, in px (`startSizePx`); a new object re-seats the box. */
+  start: { width: number; height: number };
+  /** The clamp, in px (`axisPx` per axis). */
   bounds: Bounds;
+  /** Rendered px per design px (`remPx(theme, 1)`) — `onResize` reports design px. */
+  pxPerDesignPx: number;
   disabled: boolean;
   onResize?: (width: number, height: number) => void;
 }
@@ -16,17 +19,21 @@ interface ResizeArgs {
  * Tracks the box's size across a drag. The listeners live on the document rather
  * than the handle, so the pointer can leave the handle — or the component — mid
  * drag without the resize sticking.
+ *
+ * The live size is px, because a drag is pointer pixels. What `onResize`
+ * reports is design px — the unit the consumer's `width`/`height` are in — so a
+ * controlled box (`onResize` feeding `width`) stays put at any type scale.
  */
-export const useResize = ({ width, height, bounds, disabled, onResize }: ResizeArgs) => {
-  const [size, setSize] = useState({ width, height });
+export const useResize = ({ start, bounds, pxPerDesignPx, disabled, onResize }: ResizeArgs) => {
+  const [size, setSize] = useState(start);
   const [isResizing, setIsResizing] = useState(false);
   const startPos = useRef({ x: 0, y: 0 });
   const startSize = useRef({ width: 0, height: 0 });
   const activeHandle = useRef<ResizeHandle | null>(null);
 
   React.useEffect(() => {
-    setSize({ width, height });
-  }, [width, height]);
+    setSize(start);
+  }, [start]);
 
   const handleMouseDown = useCallback(
     (e: React.MouseEvent, handle: ResizeHandle) => {
@@ -38,7 +45,8 @@ export const useResize = ({ width, height, bounds, disabled, onResize }: ResizeA
       setIsResizing(true);
       activeHandle.current = handle;
       startPos.current = { x: e.clientX, y: e.clientY };
-      startSize.current = { width: size.width, height: size.height };
+      // State is replaced on every change, never mutated, so holding it is a snapshot.
+      startSize.current = size;
 
       const handleMouseMove = (move: globalThis.MouseEvent) => {
         const delta = {
@@ -48,7 +56,7 @@ export const useResize = ({ width, height, bounds, disabled, onResize }: ResizeA
         const next = resizedTo(handle, delta, startSize.current, bounds);
 
         setSize(next);
-        onResize?.(next.width, next.height);
+        onResize?.(next.width / pxPerDesignPx, next.height / pxPerDesignPx);
       };
 
       const handleMouseUp = () => {
@@ -61,7 +69,7 @@ export const useResize = ({ width, height, bounds, disabled, onResize }: ResizeA
       document.addEventListener('mousemove', handleMouseMove);
       document.addEventListener('mouseup', handleMouseUp);
     },
-    [disabled, size, bounds, onResize],
+    [disabled, size, bounds, pxPerDesignPx, onResize],
   );
 
   return { size, isResizing, activeHandle, handleMouseDown };

package/src/components/layout/Resizable/Resizable.md

@@ -51,18 +51,22 @@ import { Resizable } from '@procurement/ui';
 | -------------- | ---------------------------------------- | ------------------------------------ | ------------------------------------------------ |
 | `children`     | `ReactNode`                              | -                                    | Content to render inside the resizable container |
 | `variant`      | `'horizontal' \| 'vertical' \| 'both'`   | `'both'`                             | Resize direction constraint                      |
-| `width`        | `number`                                 | `300`                                | Initial width in pixels                          |
-| `height`       | `number`                                 | `200`                                | Initial height in pixels                         |
+| `width`        | `number`                                 | `200`                                | Initial width, design px (scales with the theme's type scale) |
+| `height`       | `number`                                 | `200`                                | Initial height, design px (scales with the theme's type scale) |
 | `minWidth`     | `number`                                 | `50`                                 | Minimum width constraint                         |
-| `maxWidth`     | `number`                                 | -                                    | Maximum width constraint                         |
+| `maxWidth`     | `number`                                 | `1000`                               | Maximum width constraint                         |
 | `minHeight`    | `number`                                 | `50`                                 | Minimum height constraint                        |
-| `maxHeight`    | `number`                                 | -                                    | Maximum height constraint                        |
-| `onResize`     | `(dimensions: ResizeDimensions) => void` | -                                    | Callback fired during resize with new dimensions |
+| `maxHeight`    | `number`                                 | `1000`                               | Maximum height constraint                        |
+| `onResize`     | `(width: number, height: number) => void` | -                                   | Fired during resize with the new size, in design px |
 | `disabled`     | `boolean`                                | `false`                              | Disables resize functionality                    |
 | `handles`      | `HandlePosition[]`                       | `['right', 'bottom', 'bottomRight']` | Array of handle positions                        |
 | `className`    | `string`                                 | -                                    | Additional CSS class name                        |
 | `data-testid`  | `string`                                 | -                                    | Test ID for automated testing                    |
 
+Every size prop — and what `onResize` reports — is in design px, the unit the
+whole package draws in, scaled with the theme's type scale (`remPx`). A drag
+follows the pointer in real pixels.
+
 ## Handle Positions
 
 The `handles` prop accepts an array of the following positions:

package/src/components/layout/Resizable/Resizable.tsx

@@ -2,7 +2,15 @@ import Box from '@mui/material/Box/index.js';
 import { useTheme } from '@mui/material/styles/index.js';
 import React, { useMemo } from 'react';
 
-import { defaultHandles, handleStyle, resolveResizableProps } from './Resizable.helpers';
+import { remPx } from '../../../tokens/relative';
+
+import {
+  axisPx,
+  defaultHandles,
+  handleStyle,
+  resolveResizableProps,
+  startSizePx,
+} from './Resizable.helpers';
 import { useResize } from './Resizable.hooks';
 import type { ResizableProps } from './Resizable.types';
 
@@ -10,8 +18,8 @@ export const Resizable: React.FC<ResizableProps> = (rawProps) => {
   const {
     children,
     variant,
-    width: initialWidth,
-    height: initialHeight,
+    width,
+    height,
     minWidth,
     maxWidth,
     minHeight,
@@ -24,18 +32,20 @@ export const Resizable: React.FC<ResizableProps> = (rawProps) => {
     ...rest
   } = resolveResizableProps(rawProps);
   const theme = useTheme();
+  // Keyed apart: a new `start` re-seats the box, which a changed clamp must not do.
+  const start = useMemo(() => startSizePx(theme, width, height), [theme, width, height]);
   const bounds = useMemo(
     () => ({
-      width: { min: minWidth, max: maxWidth },
-      height: { min: minHeight, max: maxHeight },
+      width: axisPx(theme, minWidth, maxWidth),
+      height: axisPx(theme, minHeight, maxHeight),
     }),
-    [minWidth, maxWidth, minHeight, maxHeight],
+    [theme, minWidth, maxWidth, minHeight, maxHeight],
   );
 
   const { size, isResizing, activeHandle, handleMouseDown } = useResize({
-    width: initialWidth,
-    height: initialHeight,
+    start,
     bounds,
+    pxPerDesignPx: remPx(theme, 1),
     disabled,
     onResize,
   });
@@ -49,6 +59,8 @@ export const Resizable: React.FC<ResizableProps> = (rawProps) => {
       data-testid={dataTestId}
       sx={{
         position: 'relative',
+        // The live size: the start and the clamp came through `remPx`, the rest
+        // is pointer pixels dragged, so it is px as it stands.
         width: size.width,
         height: size.height,
         border: `1px solid ${theme.palette.divider}`,

package/src/components/layout/Resizable/Resizable.types.ts

@@ -14,12 +14,22 @@ export type ResizeHandle =
 export interface ResizableProps {
   children: ReactNode;
   variant?: ResizableVariant;
+  /** Starting width (default 200). Design px, scaled with the theme's type scale. */
   width?: number;
+  /** Starting height (default 200). Design px, scaled with the theme's type scale. */
   height?: number;
+  /** Narrowest a drag can make it (default 50). Design px, scaled with the theme's type scale. */
   minWidth?: number;
+  /** Widest a drag can make it (default 1000). Design px, scaled with the theme's type scale. */
   maxWidth?: number;
+  /** Shortest a drag can make it (default 50). Design px, scaled with the theme's type scale. */
   minHeight?: number;
+  /** Tallest a drag can make it (default 1000). Design px, scaled with the theme's type scale. */
   maxHeight?: number;
+  /**
+   * Fired on every drag step with the new size, in design px — the unit `width`
+   * and `height` take, so feeding it back keeps a controlled box where it is.
+   */
   onResize?: (width: number, height: number) => void;
   disabled?: boolean;
   handles?: ResizeHandle[];

package/src/components/layout/ScrollArea/ScrollArea.helpers.ts

@@ -10,7 +10,6 @@ type ScrollAreaDefaultedKeys =
   | 'smoothScroll'
   | 'variant'
   | 'scrollToTopButton'
-  | 'scrollToTopThreshold'
   | 'contentPadding'
   | 'alwaysShowScrollbar'
   | 'disabled'
@@ -30,7 +29,6 @@ const SCROLL_AREA_DEFAULTS: Pick<ScrollAreaProps, ScrollAreaDefaultedKeys> = {
   smoothScroll: true,
   variant: 'default',
   scrollToTopButton: false,
-  scrollToTopThreshold: 100,
   contentPadding: 0,
   alwaysShowScrollbar: false,
   disabled: false,

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

@@ -8,7 +8,7 @@ import type { SxProps, Theme } from '@mui/material/styles/index.js';
 import type { FC } from 'react';
 import React, { useCallback, useEffect, useRef, useState } from 'react';
 
-import { rem, sxRem } from '../../../tokens/relative';
+import { rem, remPx, sxRem } from '../../../tokens/relative';
 
 import type { ResolvedScrollAreaProps } from './ScrollArea.helpers';
 import { resolveScrollAreaProps } from './ScrollArea.helpers';
@@ -105,6 +105,7 @@ const useScrollArea = (
     scrollToTopThreshold,
     smoothScroll } = props;
 
+  const theme = useTheme();
   const { scrollRef, setScrollRef, containerDimensions } = useObservedScrollRef({
     externalScrollRef,
     onResize });
@@ -121,12 +122,13 @@ const useScrollArea = (
       noteScroll();
 
       if (scrollToTopButton && scrollRef.current) {
-        setShowScrollToTop(scrollRef.current.scrollTop > scrollToTopThreshold);
+        // 100 design px unless the caller says, in the px `scrollTop` is measured in.
+        setShowScrollToTop(scrollRef.current.scrollTop > remPx(theme, scrollToTopThreshold ?? 100));
       }
 
       onScroll?.(event);
     },
-    [disabled, noteScroll, scrollToTopButton, scrollToTopThreshold, onScroll, scrollRef],
+    [disabled, noteScroll, scrollToTopButton, scrollToTopThreshold, onScroll, scrollRef, theme],
   );
 
   const scrollToTop = useCallback(() => {

package/src/components/layout/ScrollArea/ScrollArea.types.ts

@@ -63,7 +63,10 @@ export interface ScrollAreaBase extends Omit<BoxProps, 'ref'> {
   /** Scroll event handler */
   onScroll?: (event: React.UIEvent<HTMLDivElement>) => void;
 
-  /** Threshold for showing scroll-to-top button (in pixels) */
+  /**
+   * How far down the scroll-to-top button appears (default 100) — design px,
+   * scaled with the theme's type scale.
+   */
   scrollToTopThreshold?: number;
 
   /** Custom scrollbar color */

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

@@ -19,7 +19,8 @@ const resolveScrollable = (scrollableTarget: ScrollableTarget): Element | null =
 
 interface ObserverArgs {
   testMode: boolean;
-  threshold: number;
+  /** The observer's `rootMargin` — px, which is all `IntersectionObserver` takes. */
+  rootMargin: string;
   scrollableTarget: ScrollableTarget;
 }
 
@@ -28,7 +29,7 @@ interface ObserverArgs {
  * it fire before the sentinel is actually on screen, so the next page is already
  * loading by the time the user reaches the bottom.
  */
-export const useSentinel = ({ testMode, threshold, scrollableTarget }: ObserverArgs) => {
+export const useSentinel = ({ testMode, rootMargin, scrollableTarget }: ObserverArgs) => {
   const sentinelRef = useRef<HTMLDivElement>(null);
   const [isIntersecting, setIsIntersecting] = useState(false);
 
@@ -43,7 +44,7 @@ export const useSentinel = ({ testMode, threshold, scrollableTarget }: ObserverA
       },
       {
         root: resolveScrollable(scrollableTarget) || undefined,
-        rootMargin: `${threshold}px`,
+        rootMargin,
         threshold: 0,
       },
     );
@@ -51,7 +52,7 @@ export const useSentinel = ({ testMode, threshold, scrollableTarget }: ObserverA
     observer.observe(sentinelRef.current);
 
     return () => observer.disconnect();
-  }, [testMode, threshold, scrollableTarget]);
+  }, [testMode, rootMargin, scrollableTarget]);
 
   return { sentinelRef, isIntersecting };
 };

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
   /**