@12-apps/ui 6.38.0 → 6.39.1

package/src/components/form/Calendar/CalendarMonth.tsx

@@ -6,12 +6,15 @@ import Typography from '@mui/material/Typography/index.js';
 import type { FC } from 'react';
 import React from 'react';
 
+import { sxRem } from '../../../tokens/relative';
+
 import { getMonthName } from './Calendar.dates';
 import type { CalendarProps, MonthMatrix } from './Calendar.types';
 import type { DayCellContext } from './CalendarDayCell';
 import { CalendarDayCell } from './CalendarDayCell';
 
-const SPACER_WIDTH = 32;
+/** The nav spacer's width and the weekday row's height, 32 design px through the type scale. */
+const SPACER_WIDTH = sxRem(32);
 
 const GRID_SX = { display: 'grid', gridTemplateColumns: 'repeat(7, 1fr)', gap: 0.5 } as const;
 
@@ -66,7 +69,7 @@ const WeekdayHeader: FC<{ weekdayNames: string[] }> = ({ weekdayNames }) => (
           alignItems: 'center',
           justifyContent: 'center',
           height: SPACER_WIDTH,
-          fontSize: '0.875rem',
+          fontSize: sxRem(14),
           fontWeight: 'bold',
           color: 'text.secondary',
         }}
@@ -109,7 +112,7 @@ export const CalendarMonth: FC<CalendarMonthProps> = ({
        January's 5th and February's. Without a per-month hook a test can only
        reach a day positionally, which is exactly what the flakiness gate
        refuses. Additive: `calendar-grid` below is unchanged. */
-    <Box sx={{ minWidth: 280 }} data-testid={`calendar-month-${monthIndex}`}>
+    <Box sx={{ minWidth: sxRem(280) }} data-testid={`calendar-month-${monthIndex}`}>
       <MonthNavHeader
         title={title}
         showPrevious={monthIndex === 0}

package/src/components/form/Switch/Switch.metrics.ts

@@ -87,12 +87,26 @@ export const MUI_SHADOWS: Record<number, string> = {
   3: ELEVATION_SHADOWS[3],
 };
 
-/** The iOS thumb's own three-layer shadow, which the web writes out literally. */
-export const IOS_THUMB_SHADOW = `0 3px 1px 0 ${alpha(SWITCH_BLACK, 0.04)}, 0 3px 8px 0 ${alpha(SWITCH_BLACK, 0.12)}, 0 1px 0 0 ${alpha(SWITCH_BLACK, 0.08)}`;
+/**
+ * How a shadow builder writes one of its lengths. Native takes the px as they
+ * stand ({@link AS_PX}); the web hands in its type scale (`rem`), so the iOS
+ * shadows scale with the theme like every other length it draws.
+ */
+export type ShadowLength = (px: number) => string;
+
+/** A length written as the px it was drawn at — what native reads. */
+export const AS_PX: ShadowLength = (value) => `${value}px`;
+
+/** The iOS thumb's own three-layer shadow. */
+export const iosThumbShadow = (length: ShadowLength = AS_PX): string =>
+  `0 ${length(3)} ${length(1)} 0 ${alpha(SWITCH_BLACK, 0.04)}, 0 ${length(3)} ${length(8)} 0 ${alpha(SWITCH_BLACK, 0.12)}, 0 ${length(1)} 0 0 ${alpha(SWITCH_BLACK, 0.08)}`;
+
+/** {@link iosThumbShadow} in px, as native draws it. */
+export const IOS_THUMB_SHADOW = iosThumbShadow();
 
-/** The iOS track's inset hairline. */
-export const iosTrackShadow = (): string =>
-  `inset 0 0 0 0.5px ${alpha(SWITCH_BLACK, 0.1)}, inset 0 2px 3px ${alpha(SWITCH_BLACK, 0.12)}`;
+/** The iOS track's inset hairline and inner shade. */
+export const iosTrackShadow = (length: ShadowLength = AS_PX): string =>
+  `inset 0 0 0 ${length(0.5)} ${alpha(SWITCH_BLACK, 0.1)}, inset 0 ${length(2)} ${length(3)} ${alpha(SWITCH_BLACK, 0.12)}`;
 
 /** The resting track: a black wash on iOS, the disabled ink elsewhere. */
 export const TRACK_ALPHA = { ios: 0.1, android: 0.2, other: 0.3 } as const;

package/src/components/form/Switch/Switch.styles.ts

@@ -12,7 +12,6 @@ import {
 import {
   DISABLED,
   IOS_BASE_OFFSET,
-  IOS_THUMB_SHADOW,
   IOS_TRAVEL_INSET,
   SWITCH_GLASS,
   SWITCH_GLOW,
@@ -30,6 +29,7 @@ import {
   TRACK_LABEL,
   TRACK_RADIUS,
   geometryOf,
+  iosThumbShadow,
   iosTrackShadow,
   lookOf,
   seconds,
@@ -108,7 +108,9 @@ const lengthOrPercent = (theme: Theme, value: number | string): string =>
   typeof value === 'number' ? rem(theme, value) : value;
 
 const thumbShadow = (theme: Theme, look: SwitchLook): string =>
-  look === 'ios' ? IOS_THUMB_SHADOW : (theme.shadows[THUMB_ELEVATION[look]] ?? 'none');
+  look === 'ios'
+    ? iosThumbShadow((px) => rem(theme, px))
+    : (theme.shadows[THUMB_ELEVATION[look]] ?? 'none');
 
 /** The ripple that expands from the thumb on hover. */
 const rippleOverlay = (palette: ColorPalette): CSSObject => ({
@@ -356,7 +358,7 @@ const trackSx = (
     opacity: 1,
     transition: `all ${seconds(SWITCH_TRANSITION.ms)} ${SWITCH_TRANSITION.easing}`,
     position: 'relative',
-    boxShadow: look === 'ios' ? iosTrackShadow() : 'none',
+    boxShadow: look === 'ios' ? iosTrackShadow((px) => rem(theme, px)) : 'none',
     ...(glass && {
       backgroundColor: alpha(theme.palette.background.paper, SWITCH_GLASS.trackAlpha),
       backdropFilter: `blur(${rem(theme, SWITCH_GLASS.trackBlur)})`,

package/src/components/layout/CardGrid/CardGrid.tsx

@@ -1,11 +1,13 @@
+import { useTheme, type Theme } from "@mui/material/styles/index.js";
 import { Children, type CSSProperties, type ReactNode, type Ref } from "react";
 
+import { rem } from "../../../tokens/relative";
 import { cn } from "../../../utils/cn";
 
 /**
  * How the grid turns surplus row space into layout:
  *
- * - `"fixed"` — every column is exactly `cardWidth` px; leftover row space is
+ * - `"fixed"` — every column is exactly `cardWidth` design px; leftover row space is
  *   spread as even gutters (`justify-content: space-around`). Cards never resize;
  *   the column count changes with the viewport. This is the original tabwoah
  *   card-grid behavior.
@@ -14,7 +16,7 @@ import { cn } from "../../../utils/cn";
  *   left-aligned at a single track's width rather than stretching edge to edge.
  * - `"scroll"` — a single row that scrolls horizontally, with fluid-width cards
  *   sized from the container so that exactly {@link SCROLL_VISIBLE_CARDS} cards
- *   plus a {@link SCROLL_PEEK_WIDTH}px sliver of the next one fit on screen (up
+ *   plus a `GRID.peekPx` sliver of the next one fit on screen (up
  *   to `maxCardWidth`, past which more cards simply fit). The sliver is the
  *   point: it makes the rail visibly continue past the fold, so the row reads as
  *   swipeable instead of as a finished pair of cards. Wrapping is off; the row
@@ -23,19 +25,27 @@ import { cn } from "../../../utils/cn";
  */
 export type CardGridVariant = "fixed" | "fluid" | "scroll";
 
-/** The grid gap, in px — mirrors the `gap: 1rem` below, for the scroll math. */
-const GRID_GAP = 16;
+/**
+ * The grid's own lengths, in design px — every one drawn through `rem`, so the
+ * `gap` the grid lays out with and the gap the scroll track math reserves are
+ * the same length at any type scale.
+ */
+const GRID = {
+  /** Between cards: the grid's `gap`, and what the scroll math reserves per gap. */
+  gapPx: 16,
+  /**
+   * `scroll`: the next card left visible past the last whole one — the
+   * "there's more, swipe" hint. Wide enough to read as a clipped card (rounded
+   * edge + a slice of its photo) rather than as a rendering glitch.
+   */
+  peekPx: 28,
+  /** Under the row — the tabwoah original's Tailwind `pb-0.5`. */
+  paddingBottomPx: 2,
+} as const;
 
 /** `scroll`: how many WHOLE cards the rail commits to showing at once. */
 const SCROLL_VISIBLE_CARDS = 2;
 
-/**
- * `scroll`: px of the next card left visible past the last whole one — the
- * "there's more, swipe" hint. Wide enough to read as a clipped card (rounded
- * edge + a slice of its photo) rather than as a rendering glitch.
- */
-const SCROLL_PEEK_WIDTH = 28;
-
 /**
  * The `scroll` track width: the widest a card can be while the container still
  * shows `SCROLL_VISIBLE_CARDS` of them plus the peek — or, when there is nothing
@@ -46,25 +56,27 @@ const SCROLL_PEEK_WIDTH = 28;
  * that follow them (one between each pair, one before the peeked card), and the
  * peek. With no overflow there are only N-1 gaps and no peek.
  */
-function scrollTrackWidth(count: number, max: number): string {
+function scrollTrackWidth(theme: Theme, count: number, max: number): string {
   const tracks = Math.max(1, Math.min(count, SCROLL_VISIBLE_CARDS));
   const overflows = count > tracks;
   const gaps = overflows ? tracks : tracks - 1;
-  const reserved = gaps * GRID_GAP + (overflows ? SCROLL_PEEK_WIDTH : 0);
-  return `min(${max}px, calc((100% - ${reserved}px) / ${tracks}))`;
+  const reserved = gaps * GRID.gapPx + (overflows ? GRID.peekPx : 0);
+  return `min(${rem(theme, max)}, calc((100% - ${rem(theme, reserved)}) / ${tracks}))`;
 }
 
 interface CardGridProps {
   /**
-   * `"fixed"`: the exact column width in px. `"fluid"`: the minimum column width
+   * `"fixed"`: the exact column width. `"fluid"`: the minimum column width
    * (columns grow from here). `"scroll"`: only seeds the default `maxCardWidth`
    * — a scroll track has no minimum, because a minimum is exactly what would
    * break the "two cards plus a peek" promise on a narrow phone.
+   *
+   * Design px, scaled with the theme's type scale.
    */
   cardWidth: number;
   /**
-   * `"scroll"` only: the maximum fluid card width in px. Defaults to
-   * `1.6 × cardWidth`.
+   * `"scroll"` only: the maximum fluid card width. Defaults to
+   * `1.6 × cardWidth`. Design px, scaled with the theme's type scale.
    */
   maxCardWidth?: number;
   /** Layout behavior — see {@link CardGridVariant}. Defaults to `"fixed"`. */
@@ -84,8 +96,8 @@ interface CardGridProps {
  *
  * Ported from the tabwoah card grid (the `"fixed"` variant is verbatim). The one
  * adaptation: that app is Tailwind (`className="grid gap-4 pb-0.5"`); this one
- * has no Tailwind, so those three utilities (display:grid, gap 1rem,
- * padding-bottom 2px) live in `style`.
+ * has no Tailwind, so those three utilities (display:grid, gap 16 design px,
+ * padding-bottom 2 design px) live in `style`, drawn through `rem`.
  */
 export function CardGrid({
   cardWidth,
@@ -96,10 +108,11 @@ export function CardGrid({
   containerRef,
   children,
 }: CardGridProps) {
+  const theme = useTheme();
   const style: CSSProperties = {
     display: "grid",
-    gap: "1rem",
-    paddingBottom: "2px",
+    gap: rem(theme, GRID.gapPx),
+    paddingBottom: rem(theme, GRID.paddingBottomPx),
   };
 
   if (variant === "scroll") {
@@ -109,14 +122,14 @@ export function CardGrid({
     // always fit (see `scrollTrackWidth`). Scroll-snap makes a swipe settle on a
     // card boundary instead of drifting mid-card.
     style.gridAutoFlow = "column";
-    style.gridAutoColumns = scrollTrackWidth(Children.count(children), max);
+    style.gridAutoColumns = scrollTrackWidth(theme, Children.count(children), max);
     style.overflowX = "auto";
     style.overflowY = "hidden";
     style.scrollSnapType = "x mandatory";
   } else if (variant === "fluid") {
-    style.gridTemplateColumns = `repeat(auto-fill, minmax(${cardWidth}px, 1fr))`;
+    style.gridTemplateColumns = `repeat(auto-fill, minmax(${rem(theme, cardWidth)}, 1fr))`;
   } else {
-    style.gridTemplateColumns = `repeat(auto-fill, ${cardWidth}px)`;
+    style.gridTemplateColumns = `repeat(auto-fill, ${rem(theme, cardWidth)})`;
     // `space-around` only distributes leftover width in the fixed variant; the
     // fluid variant consumes it via `1fr` and scroll overflows instead.
     style.justifyContent = "space-around";

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 };
 };