@multiplatform.one/forms 7.6.2 → 7.7.0

package/src/FloatingPanel/useFloatingPanel.spec.tsx

@@ -15,9 +15,10 @@
  */
 import { waitFor } from "@testing-library/react";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it } from "vitest";
 import {
   type PanelWidthMode,
+  measureDrawnRadius,
   panelAnchorOffset,
   resolvePanelWidthMode,
   useFloatingPanel,
@@ -166,3 +167,200 @@ describe("FloatingPanel width modes (MPO-38)", () => {
     expect(result.getByTestId("anchor-floating").style.minWidth).toBe("");
   });
 });
+
+/**
+ * Drawn-radius equality (MPO-129).
+ *
+ * The panel wears the arc the TRIGGER actually draws, and the box the panel
+ * anchors to is not always the box that paints. `FloatingPanelWeb` hands
+ * `setReferenceRef` to a layout-only `<View>` around the caller's `trigger`
+ * slot, so reading the anchor's own computed radius returned 0px and
+ * `min(0, h/2, w/2)` pinned every consumer's panel to a square corner at
+ * EVERY stop — measured on origin/main 3bb889f32: trigger 5/9/16/50px,
+ * panel 0px, in light and dark.
+ *
+ * These cases lock the three behaviours that fix depends on, so the zero
+ * cannot come back: the anchor's own paint wins when it has one (the
+ * Select/Combobox path, which was never broken), an unpainted anchor
+ * descends to the box sharing its corner, and an anchor with nothing painted
+ * anywhere returns null so the caller falls back to the CLAMPED TOKEN rather
+ * than to zero.
+ *
+ * FIXTURE FIDELITY, and it is load-bearing. jsdom reports an UNSET
+ * `borderTopLeftRadius` as the empty string; a browser reports "0px". The old
+ * implementation ran `parseFloat` on that value, so on an unstyled jsdom node
+ * it saw NaN and returned null — accidentally the right answer — while in a
+ * browser it saw 0 and returned a measured 0 that beat the token fallback.
+ * That is the bug. So every layout-only wrapper below sets
+ * `borderTopLeftRadius: "0px"` explicitly: without it these cases pass against
+ * the broken implementation and lock nothing.
+ */
+function boxed(
+  el: HTMLElement,
+  rect: { x: number; y: number; width: number; height: number },
+  style: Partial<CSSStyleDeclaration>,
+) {
+  mockRect(el, rect);
+  Object.assign(el.style, style);
+  return el;
+}
+
+/** jsdom resolves computed style only for ATTACHED nodes, and the fix reads
+ *  computed style — so the fixture has to live in the document. */
+function mounted(el: HTMLElement) {
+  document.body.appendChild(el);
+  return el;
+}
+
+describe("FloatingPanel drawn radius (MPO-129)", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("reads the anchor itself when the anchor is the painted control", () => {
+    // Select and Combobox spread the reference onto InputParts.Box. That path
+    // was correct before this fix and must stay byte-for-byte correct after.
+    const anchor = mounted(
+      boxed(
+        document.createElement("div"),
+        { x: 0, y: 0, width: 240, height: 44 },
+        {
+          borderTopLeftRadius: "9px",
+          backgroundColor: "rgb(255, 255, 255)",
+        },
+      ),
+    );
+    expect(measureDrawnRadius(anchor)).toBe(9);
+  });
+
+  it("descends to the painted trigger when the anchor is a layout-only wrapper", () => {
+    // The regression itself: wrapper draws nothing, Button draws 16px.
+    const wrapper = mounted(
+      boxed(
+        document.createElement("div"),
+        { x: 0, y: 0, width: 240, height: 44 },
+        {
+          // A browser reports "0px" here; jsdom leaves it "". Without this the
+          // fixture is not the box the bug happens on — see the note above.
+          borderTopLeftRadius: "0px",
+          cursor: "pointer",
+          opacity: "1",
+        },
+      ),
+    );
+    const button = boxed(
+      document.createElement("div"),
+      { x: 0, y: 0, width: 240, height: 44 },
+      {
+        borderTopLeftRadius: "16px",
+        backgroundColor: "rgb(240, 240, 240)",
+      },
+    );
+    wrapper.appendChild(button);
+    expect(measureDrawnRadius(wrapper)).toBe(16);
+  });
+
+  it("clamps the descended radius to the painted trigger's own half-height", () => {
+    // `full` asks for 50px on a 44px control; CSS draws 22px, so the panel
+    // must draw 22px too — matching a 50px arc would not coincide.
+    const wrapper = mounted(
+      boxed(
+        document.createElement("div"),
+        { x: 0, y: 0, width: 240, height: 44 },
+        {
+          // A browser reports "0px" here; jsdom leaves it "". Without this the
+          // fixture is not the box the bug happens on — see the note above.
+          borderTopLeftRadius: "0px",
+          cursor: "pointer",
+        },
+      ),
+    );
+    const button = boxed(
+      document.createElement("div"),
+      { x: 0, y: 0, width: 240, height: 44 },
+      {
+        borderTopLeftRadius: "50px",
+        backgroundColor: "rgb(240, 240, 240)",
+      },
+    );
+    wrapper.appendChild(button);
+    expect(measureDrawnRadius(wrapper)).toBe(22);
+  });
+
+  it("keeps a square corner square rather than inventing one", () => {
+    const wrapper = mounted(
+      boxed(
+        document.createElement("div"),
+        { x: 0, y: 0, width: 240, height: 44 },
+        {
+          // A browser reports "0px" here; jsdom leaves it "". Without this the
+          // fixture is not the box the bug happens on — see the note above.
+          borderTopLeftRadius: "0px",
+          cursor: "pointer",
+        },
+      ),
+    );
+    const button = boxed(
+      document.createElement("div"),
+      { x: 0, y: 0, width: 240, height: 44 },
+      {
+        borderTopLeftRadius: "0px",
+        backgroundColor: "rgb(240, 240, 240)",
+      },
+    );
+    wrapper.appendChild(button);
+    expect(measureDrawnRadius(wrapper)).toBe(0);
+  });
+
+  it("ignores a painted descendant that does not share the anchor's corner", () => {
+    // An inset swatch is not the corner the panel meets. Nothing else paints,
+    // so this resolves to the token fallback, not to the swatch's radius.
+    const wrapper = mounted(
+      boxed(
+        document.createElement("div"),
+        { x: 0, y: 0, width: 240, height: 44 },
+        {
+          // A browser reports "0px" here; jsdom leaves it "". Without this the
+          // fixture is not the box the bug happens on — see the note above.
+          borderTopLeftRadius: "0px",
+          cursor: "pointer",
+        },
+      ),
+    );
+    const swatch = boxed(
+      document.createElement("div"),
+      { x: 12, y: 12, width: 20, height: 20 },
+      {
+        borderTopLeftRadius: "10px",
+        backgroundColor: "rgb(255, 0, 0)",
+      },
+    );
+    wrapper.appendChild(swatch);
+    expect(measureDrawnRadius(wrapper)).toBeNull();
+  });
+
+  it("returns null — never 0 — when nothing under the anchor paints a corner", () => {
+    // This is the whole bug in one assertion. A measured 0 wins over the
+    // token fallback because `measuredRadius ?? clampDropdownRadius(token)`
+    // only falls back on null, so returning 0 here squares every panel.
+    const wrapper = mounted(
+      boxed(
+        document.createElement("div"),
+        { x: 0, y: 0, width: 240, height: 44 },
+        {
+          // A browser reports "0px" here; jsdom leaves it "". Without this the
+          // fixture is not the box the bug happens on — see the note above.
+          borderTopLeftRadius: "0px",
+          cursor: "pointer",
+        },
+      ),
+    );
+    wrapper.appendChild(
+      boxed(document.createElement("span"), { x: 0, y: 0, width: 60, height: 20 }, {}),
+    );
+    // Guard the premise: if this ever reads "" again the case below goes green
+    // against a broken implementation, exactly as it did before MPO-129.
+    expect(getComputedStyle(wrapper).borderTopLeftRadius).toBe("0px");
+    expect(measureDrawnRadius(wrapper)).toBeNull();
+  });
+});

package/src/FloatingPanel/useFloatingPanel.ts

@@ -141,6 +141,42 @@ export interface UseFloatingPanelReturn {
 
 // ── Hook ──────────────────────────────────────────────────────
 
+/** A box paints a corner if it draws a radius, a border or a background. */
+function paintsACorner(el: HTMLElement): boolean {
+  const cs = getComputedStyle(el);
+  if (Number.parseFloat(cs.borderTopLeftRadius) > 0) return true;
+  if (Number.parseFloat(cs.borderTopWidth) > 0 && cs.borderTopStyle !== "none") return true;
+  const bg = cs.backgroundColor;
+  return !!bg && bg !== "transparent" && bg !== "rgba(0, 0, 0, 0)";
+}
+
+/**
+ * The element the panel ANCHORS to is not always the element that PAINTS
+ * (MPO-129). `FloatingPanelWeb` hands `setReferenceRef` to a layout-only
+ * `<View>` wrapping the caller's `trigger` slot — it carries cursor and
+ * opacity and draws nothing — so reading its computed radius returns 0px and
+ * `min(0, h/2, w/2)` pins the panel to a square corner at EVERY stop, not
+ * just at `full`. Select and Combobox escape it only because they spread the
+ * reference onto `InputParts.Box`, which is the painted control itself.
+ *
+ * Positioning still measures the wrapper (that is the cover contract's box —
+ * a ColorPicker read from its swatch would measure the swatch's inset).
+ * Only the ARC descends: to the outermost box that shares the anchor's own
+ * top-left corner and actually paints one. Nothing painted → null, so the
+ * caller falls back to the clamped token rather than to zero.
+ */
+function paintedCornerBox(root: HTMLElement): HTMLElement | null {
+  if (paintsACorner(root)) return root;
+  const rootRect = root.getBoundingClientRect();
+  for (const el of Array.from(root.querySelectorAll<HTMLElement>("*"))) {
+    const rect = el.getBoundingClientRect();
+    if (rect.width <= 0 || rect.height <= 0) continue;
+    if (Math.abs(rect.left - rootRect.left) > 1 || Math.abs(rect.top - rootRect.top) > 1) continue;
+    if (paintsACorner(el)) return el;
+  }
+  return null;
+}
+
 /**
  * OVERLAY_ANCHOR_GAP rule — radius equality: a panel that aligns to (or
  * covers) its trigger must draw the SAME corner arc as the trigger at the
@@ -149,11 +185,17 @@ export interface UseFloatingPanelReturn {
  * ~22px arcs on a 44px-high field while a token-styled panel would draw its
  * own, different arc. Measure the trigger's effective (drawn) radius
  * instead and hand that px value to the panel.
+ *
+ * Exported for `useFloatingPanel.spec.tsx`: the arc is measured, not
+ * declared, so the only way to lock it is to feed it real boxes.
  */
-function measureDrawnRadius(el: HTMLElement): number | null {
-  const raw = parseFloat(getComputedStyle(el).borderTopLeftRadius);
+export function measureDrawnRadius(el: HTMLElement): number | null {
+  const box = paintedCornerBox(el);
+  if (!box) return null;
+  const raw = parseFloat(getComputedStyle(box).borderTopLeftRadius);
   if (!Number.isFinite(raw)) return null;
-  const rect = el.getBoundingClientRect();
+  const rect = box.getBoundingClientRect();
+  if (rect.width <= 0 || rect.height <= 0) return null;
   return Math.min(raw, rect.height / 2, rect.width / 2);
 }
 

package/src/InputParts/index.tsx

@@ -27,6 +27,8 @@ import {
 import {
   ensureCompositeFocusRing,
   ensureFocusVisibleRing,
+  FOCUS_RING_CLIPPED_OFFSET,
+  FOCUS_RING_HALO_OFFSET,
   isTouchSurface,
   recipeFamilies,
   resolveGlyphPaint,
@@ -219,7 +221,9 @@ export function boxRingMode(
 }
 
 export function boxRingOffset(mode: "inset" | "outset" | undefined): number {
-  return mode === "outset" ? 2 : -2;
+  // Both branches are LC-71 §4 sanctioned offsets: the clipping inset when the
+  // Box clips its adornments, the shape halo when it does not (MPO-92).
+  return mode === "outset" ? FOCUS_RING_HALO_OFFSET : FOCUS_RING_CLIPPED_OFFSET;
 }
 
 export const inputPartsRingCss = `/* LC-71: ring on Box (adornments inside); Area never outlines.
@@ -781,6 +785,13 @@ const InputAreaImpl = InputFrame.styleable<{
     focusVisibleStyle: focusVisibleStyleProp,
     className: classNameProp,
     inputMode: inputModeProp,
+    flex: flexProp,
+    width: widthProp,
+    minWidth: minWidthProp,
+    maxWidth: maxWidthProp,
+    height: heightProp,
+    minHeight: minHeightProp,
+    maxHeight: maxHeightProp,
     ...props
   } = areaProps as typeof areaProps & {
     focusStyle?: Record<string, unknown>;
@@ -788,6 +799,13 @@ const InputAreaImpl = InputFrame.styleable<{
     className?: string;
     inputMode?: InputModeValue;
     type?: string;
+    flex?: number | string;
+    width?: number | string;
+    minWidth?: number | string;
+    maxWidth?: number | string;
+    height?: number | string;
+    minHeight?: number | string;
+    maxHeight?: number | string;
   };
   const { knobProps } = useResolvedKnobs();
   const theme = useTheme();
@@ -799,6 +817,11 @@ const InputAreaImpl = InputFrame.styleable<{
   // number-pad↔numeric, decimal-pad↔decimal, email-address↔email.
   const resolvedInputMode = inputModeProp ?? mapKeyboardTypeToInputMode(keyboardType);
   const resolvedKeyboardType = keyboardType ?? mapInputModeToKeyboardType(resolvedInputMode);
+  // Duration (and any Area with a numeric width / flex 0) must not sit inside
+  // a flex:1 wrapper — that wrapper grows with the Box, then Section's
+  // justifyContent:center floats the cluster in the leftover space. OTP still
+  // pins width on Box, not Area, so it keeps the grow wrapper.
+  const hugWidth = flexProp === 0 || typeof widthProp === "number";
 
   return (
     // LC-06/LC-10 (UX-P12): in a table cell the flex wrapper and the raw
@@ -806,7 +829,20 @@ const InputAreaImpl = InputFrame.styleable<{
     // (min-width:auto floors flex items at it); width 100% makes the input
     // adopt the flexed width instead of its size-attribute default. Explicit
     // consumer widths (OTP digit boxes) still win via the later spread.
-    <View flex={1} {...(inTableCell ? { minWidth: 0 } : undefined)}>
+    <View
+      flex={hugWidth ? 0 : 1}
+      {...(hugWidth && typeof widthProp === "number"
+        ? {
+            width: widthProp,
+            minWidth: minWidthProp ?? widthProp,
+            maxWidth: maxWidthProp ?? widthProp,
+          }
+        : undefined)}
+      {...(heightProp != null
+        ? { height: heightProp, minHeight: minHeightProp ?? 0, maxHeight: maxHeightProp }
+        : undefined)}
+      {...(inTableCell ? { minWidth: 0 } : undefined)}
+    >
       <InputFrame
         aria-describedby={fieldDescribedBy}
         {...nativeA11yProps}
@@ -837,7 +873,25 @@ const InputAreaImpl = InputFrame.styleable<{
                   : undefined
         }
         {...props}
+        {...(flexProp != null ? { flex: flexProp } : undefined)}
+        {...(widthProp != null
+          ? { width: widthProp, minWidth: minWidthProp, maxWidth: maxWidthProp }
+          : undefined)}
+        {...(heightProp != null
+          ? { height: heightProp, minHeight: minHeightProp, maxHeight: maxHeightProp }
+          : undefined)}
         {...webAreaAttrs(classNameProp)}
+        {...(isWeb && typeof heightProp === "number"
+          ? {
+              // Beat the UA / `$true` 44px min on <input> when a recipe height is set
+              // (Duration size:$3 is 36; a 44 input overflows the box).
+              style: {
+                height: heightProp,
+                minHeight: typeof minHeightProp === "number" ? minHeightProp : 0,
+                maxHeight: typeof maxHeightProp === "number" ? maxHeightProp : heightProp,
+              },
+            }
+          : undefined)}
         {...AREA_NO_OUTLINE}
         focusStyle={{ ...focusStyleProp, ...AREA_NO_OUTLINE }}
         focusVisibleStyle={{ ...focusVisibleStyleProp, ...AREA_NO_OUTLINE }}

package/src/Spinner/SpinnerGlyph.spec.tsx

@@ -0,0 +1,132 @@
+/**
+ * SpinnerGlyph and useSpinnerStroke (MPO-143).
+ *
+ * Spinner.spec.tsx covers the status region, the size ladder and the animation
+ * knob; the glyph inside it — the two-circle arc that IS the spinner — had no
+ * coverage. Two contracts live here: the arc is exactly 270 degrees of the
+ * circumference on a faint full track, and `useSpinnerStroke` resolves a `$`
+ * token through the theme while passing a literal colour straight through.
+ */
+import { cleanup } from "@testing-library/react";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { afterEach, describe, expect, it } from "vitest";
+import { SpinnerGlyph, useSpinnerStroke } from "./SpinnerGlyph";
+
+afterEach(cleanup);
+
+const R = 9;
+const CIRCUMFERENCE = 2 * Math.PI * R;
+
+function svg(container: HTMLElement): SVGElement {
+  const node = container.querySelector("svg");
+  if (!node) throw new Error("SpinnerGlyph rendered no svg");
+  return node as unknown as SVGElement;
+}
+
+function circles(container: HTMLElement): SVGElement[] {
+  return Array.from(container.querySelectorAll("circle")) as unknown as SVGElement[];
+}
+
+function Probe({ color }: { color?: string }) {
+  const stroke = useSpinnerStroke(color);
+  return <span data-stroke={stroke} />;
+}
+
+function stroke(container: HTMLElement): string | null {
+  return container.querySelector("[data-stroke]")?.getAttribute("data-stroke") ?? null;
+}
+
+describe("SpinnerGlyph — the arc", () => {
+  it("draws a track and a head, never one circle", () => {
+    const { container } = renderWithProviders(<SpinnerGlyph color="#123456" size={24} />);
+    expect(circles(container)).toHaveLength(2);
+  });
+
+  it("keeps the viewBox fixed and scales through width/height, so it stays crisp", () => {
+    const { container } = renderWithProviders(<SpinnerGlyph color="#123456" size={48} />);
+    const node = svg(container);
+    expect(node.getAttribute("viewBox")).toBe("0 0 24 24");
+    expect(node.getAttribute("width")).toBe("48");
+    expect(node.getAttribute("height")).toBe("48");
+  });
+
+  it("takes the box size it is handed rather than a fixed one", () => {
+    const small = renderWithProviders(<SpinnerGlyph color="#123456" size={16} />);
+    expect(svg(small.container).getAttribute("width")).toBe("16");
+    cleanup();
+    const large = renderWithProviders(<SpinnerGlyph color="#123456" size={64} />);
+    expect(svg(large.container).getAttribute("width")).toBe("64");
+  });
+
+  it("makes the track faint and the head solid, both in the requested colour", () => {
+    const { container } = renderWithProviders(<SpinnerGlyph color="#abcdef" size={24} />);
+    const [track, head] = circles(container);
+    expect(track.getAttribute("stroke")).toBe("#abcdef");
+    expect(head.getAttribute("stroke")).toBe("#abcdef");
+    expect(Number(track.getAttribute("opacity"))).toBeCloseTo(0.2, 5);
+    expect(head.getAttribute("opacity")).toBeNull();
+  });
+
+  it("paints 270 degrees of arc and leaves the remaining quarter open", () => {
+    const { container } = renderWithProviders(<SpinnerGlyph color="#123456" size={24} />);
+    const [, head] = circles(container);
+    const [drawn, gap] = String(
+      head.getAttribute("stroke-dasharray") ?? head.getAttribute("strokeDasharray"),
+    )
+      .split(" ")
+      .map(Number);
+    expect(drawn).toBeCloseTo(CIRCUMFERENCE * 0.75, 5);
+    expect(gap).toBeCloseTo(CIRCUMFERENCE * 0.25, 5);
+    expect(drawn + gap).toBeCloseTo(CIRCUMFERENCE, 5);
+  });
+
+  it("starts the head at twelve o'clock, not at three", () => {
+    const { container } = renderWithProviders(<SpinnerGlyph color="#123456" size={24} />);
+    const [, head] = circles(container);
+    expect(head.getAttribute("transform")).toBe("rotate(-90 12 12)");
+  });
+
+  it("rounds the head's cap, which is what makes it read as Linear/Polaris rather than a pie slice", () => {
+    const { container } = renderWithProviders(<SpinnerGlyph color="#123456" size={24} />);
+    const [track, head] = circles(container);
+    expect(head.getAttribute("stroke-linecap") ?? head.getAttribute("strokeLinecap")).toBe("round");
+    expect(track.getAttribute("stroke-linecap") ?? track.getAttribute("strokeLinecap")).toBeNull();
+  });
+
+  it("fills neither circle, so the spinner is a ring and not a disc", () => {
+    const { container } = renderWithProviders(<SpinnerGlyph color="#123456" size={24} />);
+    for (const circle of circles(container)) {
+      expect(circle.getAttribute("fill")).toBe("none");
+    }
+  });
+});
+
+describe("useSpinnerStroke", () => {
+  it("passes a literal colour through untouched", () => {
+    const { container } = renderWithProviders(<Probe color="#ff0000" />);
+    expect(stroke(container)).toBe("#ff0000");
+    cleanup();
+    const named = renderWithProviders(<Probe color="rebeccapurple" />);
+    expect(stroke(named.container)).toBe("rebeccapurple");
+  });
+
+  it("resolves a $ token to a concrete colour instead of leaking the token", () => {
+    const { container } = renderWithProviders(<Probe color="$color" />);
+    const value = stroke(container);
+    expect(value).toBeTruthy();
+    expect(value?.startsWith("$")).toBe(false);
+  });
+
+  it("defaults to $color when no colour is given, and still resolves it", () => {
+    const explicit = renderWithProviders(<Probe color="$color" />);
+    const explicitValue = stroke(explicit.container);
+    cleanup();
+    const implicit = renderWithProviders(<Probe />);
+    expect(stroke(implicit.container)).toBe(explicitValue);
+  });
+
+  it("hands back the token itself when the theme has no such key, rather than throwing", () => {
+    const { container } = renderWithProviders(<Probe color="$definitelyNotAThemeKey" />);
+    expect(stroke(container)).toBe("$definitelyNotAThemeKey");
+  });
+});

package/src/Wheel/WheelEdgeFade.spec.tsx

@@ -0,0 +1,141 @@
+/**
+ * WheelEdgeFade — LC-25's two halves (MPO-143).
+ *
+ * The contract is a platform split with a contrast reason behind it. On web the
+ * wheel viewport carries a CSS mask, so this component must render NOTHING; on
+ * native it paints two absolutely-positioned gradient bands as an OVERLAY. The
+ * overlay is the whole point: fading the rows themselves would drop their
+ * opacity below 1 and take the inactive `$color11` numerals under the AA floor,
+ * which is the regression Wheel.spec.tsx guards from the other side.
+ *
+ * Both halves are exercised. A spec that covered only the file the web build
+ * resolves would be asserting `null` and calling it a test.
+ *
+ * `expo-linear-gradient` ships untranspiled JSX in its published build, which
+ * the web transform cannot parse, so it is mocked into a probe element. The
+ * mock is the gradient, not the component under test: colours, start and end
+ * come straight from WheelEdgeFade.
+ */
+import { cleanup } from "@testing-library/react";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { WheelEdgeFade } from "./WheelEdgeFade";
+import { WheelEdgeFade as NativeWheelEdgeFade } from "./WheelEdgeFade.native";
+
+vi.mock("expo-linear-gradient", () => ({
+  LinearGradient: (props: { colors?: string[]; start?: unknown; end?: unknown }) => (
+    <div
+      data-gradient="true"
+      data-colors={(props.colors ?? []).join("|")}
+      data-start={JSON.stringify(props.start)}
+      data-end={JSON.stringify(props.end)}
+    />
+  ),
+}));
+
+afterEach(cleanup);
+
+function bands(container: HTMLElement): HTMLElement[] {
+  return Array.from(container.querySelectorAll("[style*='height']")) as HTMLElement[];
+}
+
+function gradients(container: HTMLElement): HTMLElement[] {
+  return Array.from(container.querySelectorAll("[data-gradient]")) as HTMLElement[];
+}
+
+function colorsOf(node: HTMLElement): string[] {
+  return String(node.getAttribute("data-colors") ?? "").split("|");
+}
+
+describe("WheelEdgeFade — web", () => {
+  it("renders nothing, because the viewport's CSS mask already does the fade", () => {
+    const { container } = renderWithProviders(<WheelEdgeFade height={24} />);
+    expect(container.querySelector("[data-gradient]")).toBeNull();
+    expect(container.textContent).toBe("");
+  });
+
+  it("renders nothing at every height, so it can never dim a row", () => {
+    for (const height of [0, 1, 24, 400]) {
+      const { container } = renderWithProviders(<WheelEdgeFade height={height} />);
+      expect(container.querySelector("[data-gradient]"), String(height)).toBeNull();
+      cleanup();
+    }
+  });
+});
+
+describe("WheelEdgeFade — native", () => {
+  it("paints one band per edge, never a single one", () => {
+    const { container } = renderWithProviders(<NativeWheelEdgeFade height={24} />);
+    expect(gradients(container)).toHaveLength(2);
+  });
+
+  it("draws nothing at all when the band height is zero or negative", () => {
+    const zero = renderWithProviders(<NativeWheelEdgeFade height={0} />);
+    expect(gradients(zero.container)).toHaveLength(0);
+    cleanup();
+    const negative = renderWithProviders(<NativeWheelEdgeFade height={-8} />);
+    expect(gradients(negative.container)).toHaveLength(0);
+  });
+
+  it("pins one band to the top and one to the bottom", () => {
+    const { container } = renderWithProviders(<NativeWheelEdgeFade height={30} />);
+    const edges = bands(container).map((node) => node.getAttribute("style") ?? "");
+    expect(edges.some((style) => /top:\s*0px/.test(style))).toBe(true);
+    expect(edges.some((style) => /bottom:\s*0px/.test(style))).toBe(true);
+  });
+
+  it("gives each band the height it was handed, so the caller sets the fade depth", () => {
+    const { container } = renderWithProviders(<NativeWheelEdgeFade height={30} />);
+    const heights = bands(container).map(
+      (node) => /height:\s*(\d+)px/.exec(node.getAttribute("style") ?? "")?.[1],
+    );
+    expect(heights.filter(Boolean)).toEqual(["30", "30"]);
+    cleanup();
+    const taller = renderWithProviders(<NativeWheelEdgeFade height={64} />);
+    expect(
+      bands(taller.container).map(
+        (node) => /height:\s*(\d+)px/.exec(node.getAttribute("style") ?? "")?.[1],
+      ),
+    ).toEqual(["64", "64"]);
+  });
+
+  it("keeps the bands out of the way of a drag, so the wheel still scrolls", () => {
+    const { container } = renderWithProviders(<NativeWheelEdgeFade height={24} />);
+    for (const band of bands(container)) {
+      expect(band.className).toContain("r-pointerEvents");
+      expect(band.className).toContain("r-position");
+    }
+  });
+
+  it("runs the top band opaque-to-clear and the bottom band clear-to-opaque", () => {
+    const { container } = renderWithProviders(<NativeWheelEdgeFade height={24} />);
+    const [top, bottom] = gradients(container).map(colorsOf);
+    expect(top).toHaveLength(2);
+    expect(bottom).toHaveLength(2);
+    // The two bands are mirror images: the top starts on the page background
+    // and ends transparent, the bottom does the reverse.
+    expect(top[0]).toBe(bottom[1]);
+    expect(top[1]).toBe(bottom[0]);
+    expect(top[1]).toMatch(/,\s*0\)$/);
+    expect(top[0]).not.toMatch(/,\s*0\)$/);
+  });
+
+  it("derives the fade colour from the theme background rather than a hardcoded white", () => {
+    const { container } = renderWithProviders(<NativeWheelEdgeFade height={24} />);
+    const [opaque, clear] = colorsOf(gradients(container)[0]);
+    expect(opaque).toBeTruthy();
+    expect(opaque).not.toBe("transparent");
+    // The clear stop is the SAME colour at zero alpha, so the band never
+    // shifts hue across its length.
+    const channels = /rgba\(([^)]+),\s*0\)$/.exec(clear)?.[1];
+    expect(channels, `clear stop ${clear} must be the opaque stop at alpha 0`).toBeTruthy();
+  });
+
+  it("runs both gradients vertically down the centre line", () => {
+    const { container } = renderWithProviders(<NativeWheelEdgeFade height={24} />);
+    for (const gradient of gradients(container)) {
+      expect(gradient.getAttribute("data-start")).toBe(JSON.stringify({ x: 0.5, y: 0 }));
+      expect(gradient.getAttribute("data-end")).toBe(JSON.stringify({ x: 0.5, y: 1 }));
+    }
+  });
+});