Add debug prop to Mafs (#173)

This adds `<Mafs debug />` which shows a helpfully zoomed out view,
letting you peek beyond what the camera is limited to.



https://github.com/user-attachments/assets/5da478ba-7422-47e4-b436-9eda91ce0cee

Author: stevenpetryk

.api-report/mafs.api.md

@@ -102,7 +102,7 @@ export const Line: {
 };
 
 // @public (undocumented)
-export function Mafs({ width: propWidth, height: propHeight, pan, zoom, viewBox, preserveAspectRatio, children, ssr, onClick, }: MafsProps): JSX_2.Element;
+export function Mafs({ width: propWidth, height: propHeight, pan, zoom, viewBox, preserveAspectRatio, children, ssr, debug, onClick, }: MafsProps): JSX_2.Element;
 
 // @public (undocumented)
 export namespace Mafs {
@@ -127,6 +127,7 @@ export type MafsProps = React_2.PropsWithChildren<{
     preserveAspectRatio?: "contain" | false;
     onClick?: (point: vec.Vector2, event: MouseEvent) => void;
     ssr?: boolean;
+    debug?: boolean;
 }>;
 
 // @public (undocumented)

docs/app/guides/display/debug/page.tsx

@@ -5,6 +5,7 @@ import Link from "next/link"
 import CodeAndExample from "components/CodeAndExample"
 
 import PizzaSliceExample from "guide-examples/custom/pizza-slice"
+import DebugExample from "guide-examples/debug/DebugExample"
 import Example from "guide-examples/debug/PaneVisualizerExample"
 import type { Metadata } from "next"
 
@@ -16,8 +17,23 @@ export default function DebugPage() {
   return (
     <>
       <p>
-        Mafs provides a few utilities for debugging or experimentation, underneath the{" "}
-        <code>Debug</code> namespace.
+        Mafs provides several utilities for debugging your visualizations. Perhaps the most useful
+        utility the <code>debug</code> prop on <code>Mafs</code>. Adding this prop will force a
+        larger SVG viewBox and add a red border around the <em>actual</em> viewBox.
+      </p>
+
+      <CodeAndExample example={DebugExample} />
+
+      <p>
+        In the above example, you can gain an insight into how Mafs lazy-loads the coordinate grid
+        and the function being visualized. In the bottom left corner, there is also some debug
+        information pinned to the viewport. More on that below.
+      </p>
+
+      <h2>Other utilities</h2>
+
+      <p>
+        Mafs also provides some debug components under the <code>Debug</code> namespace.
       </p>
 
       <Code source={`import { Debug } from "mafs"`} language="tsx" />

docs/components/guide-examples/debug/DebugExample.tsx

@@ -0,0 +1,26 @@
+"use client"
+
+import * as React from "react"
+import { Mafs, Coordinates, Plot } from "mafs"
+
+export default function Example() {
+  const [debug, setDebug] = React.useState(true)
+
+  return (
+    <div>
+      {/* Set the `debug` prop on Mafs to get a bird's eye view. */}
+      <Mafs debug={debug} height={400}>
+        <Coordinates.Cartesian />
+        <Plot.OfX y={(x) => Math.sin(x * Math.PI)} />
+      </Mafs>
+      <label className="p-4 bg-black flex gap-2 pointer">
+        <input
+          type="checkbox"
+          checked={debug}
+          onChange={(e) => setDebug(e.target.checked)}
+        />
+        Debug
+      </label>
+    </div>
+  )
+}

e2e/generated-vrt.spec.tsx

@@ -20,6 +20,7 @@ import VectorFieldExample from "../docs/components/guide-examples/VectorFieldExa
 import PizzaMarch from "../docs/components/guide-examples/custom/pizza-march"
 import PizzaSlice from "../docs/components/guide-examples/custom/pizza-slice"
 import PointCloud from "../docs/components/guide-examples/custom/point-cloud"
+import DebugExample from "../docs/components/guide-examples/debug/DebugExample"
 import PaneVisualizerExample from "../docs/components/guide-examples/debug/PaneVisualizerExample"
 import DynamicMovablePoints from "../docs/components/guide-examples/display/DynamicMovablePoints"
 import PointsAlongFunction from "../docs/components/guide-examples/display/PointsAlongFunction"
@@ -188,6 +189,15 @@ test("guide-examples/custom/PointCloud", async ({ mount, page }) =>
     </TestContextProvider>,
   ))
 
+test("guide-examples/debug/DebugExample", async ({ mount, page }) =>
+  await visualTest(
+    mount,
+    page,
+    <TestContextProvider value={{ overrideHeight: 500 }}>
+      <DebugExample />
+    </TestContextProvider>,
+  ))
+
 test("guide-examples/debug/PaneVisualizerExample", async ({ mount, page }) =>
   await visualTest(
     mount,

e2e/generated-vrt.spec.tsx-snapshots/guide-examples-debug-DebugExample-1-Mobile-Chrome-darwin.png

@@ -12,6 +12,7 @@ import invariant from "tiny-invariant"
 import { useCamera } from "../gestures/useCamera"
 import { useWheelEnabler } from "../gestures/useWheelEnabler"
 import { TestContext } from "../context/TestContext"
+import { Debug } from "../debug"
 
 export type MafsProps = React.PropsWithChildren<{
   width?: number | "auto"
@@ -49,6 +50,9 @@ export type MafsProps = React.PropsWithChildren<{
    * this prop is now ignored.
    */
   ssr?: boolean
+
+  /** Take a peek outside the viewbox to make sure things are rendering properly. */
+  debug?: boolean
 }>
 
 export function Mafs({
@@ -60,6 +64,7 @@ export function Mafs({
   preserveAspectRatio = "contain",
   children,
   ssr = false,
+  debug = false,
   onClick = undefined,
 }: MafsProps) {
   const testContext = React.useContext(TestContext)
@@ -92,6 +97,7 @@ export function Mafs({
           preserveAspectRatio={preserveAspectRatio}
           ssr={ssr}
           onClick={onClick}
+          debug={debug}
         >
           {children}
         </MafsCanvas>
@@ -105,7 +111,9 @@ type MafsCanvasProps = {
   height: number
   desiredCssWidth: string
   rootRef: React.RefObject<HTMLDivElement>
-} & Required<Pick<MafsProps, "pan" | "zoom" | "viewBox" | "preserveAspectRatio" | "ssr">> &
+} & Required<
+  Pick<MafsProps, "pan" | "zoom" | "viewBox" | "preserveAspectRatio" | "ssr" | "debug">
+> &
   Pick<MafsProps, "children" | "onClick">
 
 function MafsCanvas({
@@ -119,6 +127,7 @@ function MafsCanvas({
   preserveAspectRatio,
   children,
   onClick,
+  debug,
 }: MafsCanvasProps) {
   let minZoom = 1
   let maxZoom = 1
@@ -306,7 +315,12 @@ function MafsCanvas({
             <svg
               width={width}
               height={height}
-              viewBox={`${viewBoxX} ${viewBoxY} ${width} ${height}`}
+              viewBox={[
+                viewBoxX - (debug ? 150 : 0),
+                viewBoxY - (debug ? 150 : 0),
+                width + (debug ? 300 : 0),
+                height + (debug ? 300 : 0),
+              ].join(" ")}
               preserveAspectRatio="xMidYMin"
               style={{
                 width: desiredCssWidth,
@@ -318,6 +332,18 @@ function MafsCanvas({
               }}
             >
               {children}
+              {debug && (
+                <rect
+                  x={viewBoxX}
+                  y={viewBoxY}
+                  width={width}
+                  height={height}
+                  fill="none"
+                  stroke="red"
+                  style={{ outline: "9999px solid #f002" }}
+                />
+              )}
+              {debug && <Debug.ViewportInfo />}
             </svg>
           </PaneManager>
         </TransformContext.Provider>

e2e/generated-vrt.spec.tsx-snapshots/guide-examples-debug-DebugExample-1-Mobile-Safari-darwin.png

@@ -15,7 +15,7 @@
     "react-dom": "^18.3.1"
   },
   "devDependencies": {
-    "@types/node": "^20.16.11",
+    "@types/node": "^20.16.13",
     "@types/react": "^18.3.11",
     "@types/react-dom": "^18.3.1",
     "typescript": "^5.6.3"