Add Image component (#174)

Adds support for embedding images in Mafs views.


![](https://github.com/user-attachments/assets/f2d19d91-fdcc-4672-9493-b8a62c53f7b9)

.api-report/mafs.api.md

@@ -4,8 +4,6 @@
 
 ```ts
 
-/// <reference types="react" />
-
 import { JSX as JSX_2 } from 'react/jsx-runtime';
 import { KatexOptions } from 'katex';
 import * as React_2 from 'react';
@@ -82,6 +80,29 @@ export interface Filled {
     weight?: number;
 }
 
+// @public (undocumented)
+function Image_2({ href, x, y, width, height, anchor, preserveAspectRatio, svgImageProps, }: ImageProps): JSX_2.Element;
+export { Image_2 as Image }
+
+// @public (undocumented)
+export interface ImageProps {
+    // Warning: (ae-forgotten-export) The symbol "Anchor" needs to be exported by the entry point index.d.ts
+    anchor?: Anchor;
+    // (undocumented)
+    height: number;
+    // (undocumented)
+    href: string;
+    preserveAspectRatio?: string;
+    // (undocumented)
+    svgImageProps?: React.SVGProps<SVGImageElement>;
+    // (undocumented)
+    width: number;
+    // (undocumented)
+    x: number;
+    // (undocumented)
+    y: number;
+}
+
 // @public (undocumented)
 export type Interval = [min: number, max: number];
 

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

@@ -0,0 +1,56 @@
+import { PropTable } from "components/PropTable"
+
+import CodeAndExample from "components/CodeAndExample"
+import ImageExample from "guide-examples/display/images/ImageExample"
+import ImageAnchorExample from "guide-examples/display/images/ImageAnchorExample"
+import type { Metadata } from "next"
+
+export const metadata: Metadata = {
+  title: "Images",
+}
+
+function Images() {
+  return (
+    <>
+      <p>
+        Images in Mafs are just wrappers around the SVG <code>image</code> element, with some
+        quality of life improvements tacked on (see below).
+      </p>
+
+      <CodeAndExample example={ImageExample} />
+
+      <PropTable of={"Image"} />
+
+      <h2>
+        Comparison with SVG <code>&lt;image&gt;</code>
+      </h2>
+
+      <p>
+        The SVG <code>image</code> element is a low-level way to include external images in an SVG.
+        It has a few downsides:
+      </p>
+
+      <ul>
+        <li>Negative widths and heights lead to undefined behavior.</li>
+        <li>
+          The x and y attributes correspond to the top left of the image and is not configurable.
+        </li>
+      </ul>
+
+      <p>
+        Mafs handles negative heights and widths the way you'd expect; by making the image grow in
+        the <code>-x</code> and <code>-y</code> directions.
+      </p>
+
+      <p>
+        Additionally, the <code>anchor</code> attribute of <code>Image</code> allows you to declare
+        whether the image's x and y coordinates refer to the corners, center of edges, or center of
+        the image.
+      </p>
+
+      <CodeAndExample example={ImageAnchorExample} />
+    </>
+  )
+}
+
+export default Images

docs/app/guides/guides.tsx

@@ -10,6 +10,7 @@ import {
   TextIcon,
   CursorArrowIcon,
   PlayIcon,
+  ImageIcon,
 } from "@radix-ui/react-icons"
 
 import {
@@ -62,6 +63,7 @@ export const Guides: Section[] = [
       { title: "Plots", icon: FunctionIcon, slug: "plots" },
       { title: "Text", icon: TextIcon, slug: "text" },
       { title: "Vectors", icon: ArrowTopRightIcon, slug: "vectors" },
+      { title: "Images", icon: ImageIcon, slug: "images" },
       { separator: true },
       { title: "Transform", icon: RotateCounterClockwiseIcon, slug: "transform" },
       { title: "Debug", icon: DebugIcon, slug: "debug" },

docs/components/PropTable.tsx

@@ -149,9 +149,9 @@ function PropType({ prop }: { prop: DocgenProp }) {
   return (
     <div className="flex flex-col gap-1">
       {prop.description && (
-        <p className="text-gray-800 dark:text-slate-200 markdown">
+        <div className="text-gray-800 dark:text-slate-200 markdown">
           <ReactMarkdown>{prop.description}</ReactMarkdown>
-        </p>
+        </div>
       )}
       <div className="text-gray-600 dark:text-slate-400">{typeNode}</div>
     </div>

docs/components/guide-examples/display/images/ImageAnchorExample.tsx

@@ -0,0 +1,52 @@
+"use client"
+
+import {
+  Coordinates,
+  Image,
+  Mafs,
+  useMovablePoint,
+} from "mafs"
+
+import image from "./mafs.png"
+
+export default function VectorExample() {
+  const center = useMovablePoint([2, 2])
+  return (
+    <Mafs viewBox={{ x: [-1, 7], y: [-1, 5] }}>
+      <Coordinates.Cartesian />
+      <Image
+        href={image.src ?? image}
+        anchor="tl"
+        x={center.x + 0.1}
+        y={center.y - 0.1}
+        width={1}
+        height={1}
+      />
+      <Image
+        href={image.src ?? image}
+        anchor="tr"
+        x={center.x - 0.1}
+        y={center.y - 0.1}
+        width={1}
+        height={1}
+      />
+      <Image
+        href={image.src ?? image}
+        anchor="bl"
+        x={center.x + 0.1}
+        y={center.y + 0.1}
+        width={1}
+        height={1}
+      />
+      <Image
+        href={image.src ?? image}
+        anchor="br"
+        x={center.x - 0.1}
+        y={center.y + 0.1}
+        width={1}
+        height={1}
+      />
+      {center.element}
+    </Mafs>
+  )
+}

docs/components/guide-examples/display/images/ImageExample.tsx

@@ -0,0 +1,29 @@
+"use client"
+
+import {
+  Mafs,
+  Image,
+  Coordinates,
+  useMovablePoint,
+} from "mafs"
+
+import image from "./mafs.png"
+
+export default function ImageExample() {
+  const origin = useMovablePoint([1, 1])
+
+  return (
+    <Mafs viewBox={{ x: [-1, 7], y: [-1, 5] }}>
+      <Coordinates.Cartesian />
+      <Image
+        href={image.src ?? image}
+        anchor="bl"
+        x={origin.x}
+        y={origin.y}
+        width={2}
+        height={2}
+      />
+      {origin.element}
+    </Mafs>
+  )
+}

e2e/generated-vrt.spec.tsx

@@ -41,6 +41,8 @@ import SimpleTransform from "../docs/components/guide-examples/utility/SimpleTra
 import CartesianCoordinatesConfigExample from "../docs/components/guide-examples/display/coordinates/CartesianCoordinatesConfigExample"
 import CartesianCoordinatesExample from "../docs/components/guide-examples/display/coordinates/CartesianCoordinatesExample"
 import PolarCoordinatesExample from "../docs/components/guide-examples/display/coordinates/PolarCoordinatesExample"
+import ImageAnchorExample from "../docs/components/guide-examples/display/images/ImageAnchorExample"
+import ImageExample from "../docs/components/guide-examples/display/images/ImageExample"
 import VectorExample from "../docs/components/guide-examples/display/vectors/VectorExample"
 import ContainViewbox from "../docs/components/guide-examples/display/viewbox/ContainViewbox"
 import StretchViewbox from "../docs/components/guide-examples/display/viewbox/StretchViewbox"
@@ -381,6 +383,24 @@ test("guide-examples/display/coordinates/PolarCoordinatesExample", async ({ moun
     </TestContextProvider>,
   ))
 
+test("guide-examples/display/images/ImageAnchorExample", async ({ mount, page }) =>
+  await visualTest(
+    mount,
+    page,
+    <TestContextProvider value={{ overrideHeight: 500 }}>
+      <ImageAnchorExample />
+    </TestContextProvider>,
+  ))
+
+test("guide-examples/display/images/ImageExample", async ({ mount, page }) =>
+  await visualTest(
+    mount,
+    page,
+    <TestContextProvider value={{ overrideHeight: 500 }}>
+      <ImageExample />
+    </TestContextProvider>,
+  ))
+
 test("guide-examples/display/vectors/VectorExample", async ({ mount, page }) =>
   await visualTest(
     mount,

src/display/Image.tsx

@@ -0,0 +1,61 @@
+import { Anchor, computeAnchor } from "../math"
+
+export interface ImageProps {
+  href: string
+  x: number
+  y: number
+  /**
+   * Indicate where, in the image (top, bottom, left, right, center), the x and
+   * y coordinate refers to.
+   */
+  anchor?: Anchor
+  width: number
+  height: number
+  /**
+   * Whether to preserve the aspect ratio of the image. By default, the image
+   * will be centered and scaled to fit the width and height. If you want to
+   * squish the image to be the same shape as the box, set this to "none".
+   *
+   * This is passed directly to the `preserveAspectRatio` attribute of the SVG
+   * `<image>` element.
+   *
+   * See [preserveAspectRatio](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/preserveAspectRatio) on MDN.
+   */
+  preserveAspectRatio?: string
+
+  svgImageProps?: React.SVGProps<SVGImageElement>
+}
+
+export function Image({
+  href,
+  x,
+  y,
+  width,
+  height,
+  anchor = "bl",
+  preserveAspectRatio,
+  svgImageProps,
+}: ImageProps) {
+  const [anchorX, anchorY] = computeAnchor(anchor, x, y, width, height)
+
+  const transform = [
+    "var(--mafs-view-transform)",
+    "var(--mafs-user-transform)",
+    // Ensure the image is not upside down (since Mafs has the y-axis pointing
+    // up, while SVG has it pointing down).
+    "scaleY(-1)",
+  ].join(" ")
+
+  return (
+    <image
+      href={href}
+      x={anchorX}
+      y={-anchorY}
+      width={width}
+      height={height}
+      preserveAspectRatio={preserveAspectRatio}
+      {...svgImageProps}
+      style={{ transform }}
+    />
+  )
+}

src/index.tsx

@@ -35,6 +35,9 @@ export type { PointProps } from "./display/Point"
 export { Vector } from "./display/Vector"
 export type { VectorProps } from "./display/Vector"
 
+export { Image } from "./display/Image"
+export type { ImageProps } from "./display/Image"
+
 export { Text } from "./display/Text"
 export type { TextProps, CardinalDirection } from "./display/Text"
 

src/math.ts

@@ -1,4 +1,5 @@
 export type Interval = [min: number, max: number]
+export type Anchor = "tl" | "tc" | "tr" | "cl" | "cc" | "cr" | "bl" | "bc" | "br"
 
 export function round(value: number, precision = 0): number {
   const multiplier = Math.pow(10, precision || 0)
@@ -24,3 +25,59 @@ export function range(min: number, max: number, step = 1): number[] {
 export function clamp(number: number, min: number, max: number): number {
   return Math.min(Math.max(number, min), max)
 }
+
+/**
+ * Given an anchor and a bounding box (x, y, width, height), compute the x and y coordinates of the
+ * anchor such that rendering an element at those coordinates will align the element with the anchor.
+ */
+export function computeAnchor(
+  anchor: Anchor,
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+): [number, number] {
+  let actualX = x
+  let actualY = y
+
+  switch (anchor) {
+    case "tl":
+      actualX = x
+      actualY = y
+      break
+    case "tc":
+      actualX = x - width / 2
+      actualY = y
+      break
+    case "tr":
+      actualX = x - width
+      actualY = y
+      break
+    case "cl":
+      actualX = x
+      actualY = y + height / 2
+      break
+    case "cc":
+      actualX = x - width / 2
+      actualY = y + height / 2
+      break
+    case "cr":
+      actualX = x - width
+      actualY = y + height / 2
+      break
+    case "bl":
+      actualX = x
+      actualY = y + height
+      break
+    case "bc":
+      actualX = x - width / 2
+      actualY = y + height
+      break
+    case "br":
+      actualX = x - width
+      actualY = y + height
+      break
+  }
+
+  return [actualX, actualY]
+}

src/typings/env.d.ts

@@ -0,0 +1,10 @@
+declare module "*.css" {
+  const content: { [className: string]: string }
+  export default content
+}
+
+declare module "*.png" {
+  /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
+  const content: any
+  export default content
+}